VASPml library - Revision history

Singraber at 07:51, 20 February 2025

2025-02-20T07:51:31Z

← Older revision		Revision as of 07:51, 20 February 2025
Line 1:		Line 1:
	VASPml is a C++ library accompanying {{VASP}}, providing functionality related to [[:Category:Machine-learned force fields\|machine-learned force fields]]. It is supposed to extend, and eventually replace, the original Fortran machine learning code inside {{VASP}}. Currently, it does not yet offer any training capabilities but rather focuses on inference. At this point VASPml is in a beta-testing stage and provides its first application, an interface to the popular molecular dynamics (MD) software [https://www.lammps.org LAMMPS]. This allows users to combine {{VASP}}-generated machine-learned force fields with the large amount of MD-related features provided by LAMMPS, some of which may not be offered in {{VASP}} directly.		VASPml is a C++ library accompanying {{VASP}} 6.5.0 and above, providing functionality related to [[:Category:Machine-learned force fields\|machine-learned force fields]]. It is supposed to extend, and eventually replace, the original Fortran machine learning code inside {{VASP}}. Currently, it does not yet offer any training capabilities but rather focuses on inference. At this point VASPml is in a beta-testing stage and provides its first application, an interface to the popular molecular dynamics (MD) software [https://www.lammps.org LAMMPS]. This allows users to combine {{VASP}}-generated machine-learned force fields with the large amount of MD-related features provided by LAMMPS, some of which may not be offered in {{VASP}} directly.
	{{NB\|warning\|As of {{VASP}} 6.5.0 the VASPml library is experimental and results should be carefully checked against the standard Fortran code (compile without <code>-Dlibvaspml</code> or set {{TAGO\|ML_LIB\|.FALSE.}}).}}		{{NB\|warning\|As of {{VASP}} 6.5.0 the VASPml library is experimental and results should be carefully checked against the standard Fortran code (compile without <code>-Dlibvaspml</code> or set {{TAGO\|ML_LIB\|.FALSE.}}).}}

Singraber: /* Restrictions */

2025-02-19T09:18:45Z

Restrictions

← Older revision		Revision as of 09:18, 19 February 2025
Line 19:		Line 19:
	{{CB\| const SemanticVersion versionMax {{=}} SemanticVersion(0, 2, 4);\|:\|0.5em}}		{{CB\| const SemanticVersion versionMax {{=}} SemanticVersion(0, 2, 4);\|:\|0.5em}}
	:After complete recompilation of {{VASP}} the newer force fields should also be accepted. This bug and workaround also apply to the LAMMPS interface. In case the workaround is applied please also recompile LAMMPS.		:After complete recompilation of {{VASP}} the newer force fields should also be accepted. This bug and workaround also apply to the LAMMPS interface. In case the workaround is applied please also recompile LAMMPS.
			* If {{VASP}} 6.5.0 is compiled with the VASPml library the [[Validation tests\|validation tests]] for prediction-only runs, i.e., all tests labelled <code>ML_..._ISTART2</code>, fail because the provided {{FILE\|ML_FF}} files are too old. This issue is fixed in {{VASP}} 6.5.1. Updated tests for {{TAGO\|ML_MODE\|run}} are work in progress.

	= Dependencies =		= Dependencies =

Singraber at 08:58, 19 February 2025

2025-02-19T08:58:53Z

← Older revision		Revision as of 08:58, 19 February 2025
Line 27:		Line 27:
	* BLAS and the corresponding C interface CBLAS		* BLAS and the corresponding C interface CBLAS
	* LAPACK and the corresponding C interface LAPACKE		* LAPACK and the corresponding C interface LAPACKE
	These requirements are usually already covered by the [[Installing_VASP.6.X.X#Requirements\|{{VASP}} requirements]].		These requirements are usually already covered by the [[Installing_VASP.6.X.X#Requirements\|{{VASP}} requirements]]. Additionally, for compiling the optional [[#Internal validation tests\|internal validation tests]] the following external library is required:
			* [http://boost.org/libs/test Boost.test]

	= Build instructions =		= Build instructions =
Line 112:		Line 113:
	= Internal validation tests =		= Internal validation tests =

	VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. {{NB\|mind\|Currently, the VASPml internal tests are not executed as part of the [[Validation tests\|{{VASP}} validation tests]]. They can only be built and executed with a standalone build of VASPml.}} In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <code>makefile.include</code> file (see [[#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:		VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. {{NB\|mind\|Currently, the VASPml internal tests are not executed as part of the [[Validation tests\|{{VASP}} validation tests]]. They can only be built and executed with a [[#Standalone build instructions\|standalone build of VASPml]].}} In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <code>makefile.include</code> file (see [[#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:

	cd test		cd test

Singraber at 08:52, 19 February 2025

2025-02-19T08:52:51Z

← Older revision		Revision as of 08:52, 19 February 2025
Line 112:		Line 112:
	= Internal validation tests =		= Internal validation tests =

	VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. {{NB\|mind\|Currently, the VASPml internal tests are not executed as part of the [[Validation tests\|{{VASP}} validation tests]]. They can only be built and executed with a standalone build of VASPml.}} In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <code>makefile.include</code> file (see [[~~#Standalone build instructions~~#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:		VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. {{NB\|mind\|Currently, the VASPml internal tests are not executed as part of the [[Validation tests\|{{VASP}} validation tests]]. They can only be built and executed with a standalone build of VASPml.}} In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <code>makefile.include</code> file (see [[#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:

	cd test		cd test

Singraber: /* Internal validation tests */

2025-02-19T08:51:01Z

Internal validation tests

← Older revision		Revision as of 08:51, 19 February 2025
Line 112:		Line 112:
	= Internal validation tests =		= Internal validation tests =

	VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <code>makefile.include</code> file (see [[#Standalone build instructions#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:		VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. {{NB\|mind\|Currently, the VASPml internal tests are not executed as part of the [[Validation tests\|{{VASP}} validation tests]]. They can only be built and executed with a standalone build of VASPml.}} In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <code>makefile.include</code> file (see [[#Standalone build instructions#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:

	cd test		cd test

Singraber: /* Step 2: Modify makefile.include */

2025-02-19T08:47:24Z

Step 2: Modify makefile.include

← Older revision		Revision as of 08:47, 19 February 2025
Line 100:		Line 100:
	** <code>--no-logo</code>: Disables the VASPml logo output.		** <code>--no-logo</code>: Disables the VASPml logo output.
	:For example, to disable both the color output and the logo use: <code>MAKE_OPTIONS = --no-color --no-logo</code>.		:For example, to disable both the color output and the logo use: <code>MAKE_OPTIONS = --no-color --no-logo</code>.
	* <code>VERBOSE</code>: Setting this to any value, e.g. <code>VERBOSE=1</code> will echo all executed commands to the screen.		* <code>VERBOSE</code>: Setting this to any value, e.g. <code>VERBOSE=1</code>, will echo all executed commands to the screen.

	=== Step 3: Build ===		=== Step 3: Build ===

Singraber: /* Step 1: Separate VASPml directory */

2025-02-19T08:44:34Z

Step 1: Separate VASPml directory

← Older revision		Revision as of 08:44, 19 February 2025
Line 65:		Line 65:
	cd /some/other/location/vaspml		cd /some/other/location/vaspml

	Inside you will find a similar folder structure as in {{VASP}}. For example, the source code is located in <code>src</code> and will be copied and compiled in the <code>build</code> directory. Moreover, ~~similar to {{VASP}}~~ also VASPml requires to enter compiler details and library paths into a file named <code>makefile.include</code> before the standalone build process can be started. The <code>arch</code> folder contains template files for typical compiler toolchains. {{NB\|mind\|The <code>makefile.include</code> files inside VASPml's <code>arch</code> directory are only required for the standalone build described here. For a regular {{VASP}} build they must not be used because then compilers and flags are taken from {{VASP}}'s <code>makefile.include</code> (for this purpose, the special file <code>makefile.include.vasp</code> is used '''automatically''').}}		Inside you will find a similar folder structure as in {{VASP}}. For example, the source code is located in <code>src</code> and will be copied and compiled in the <code>build</code> directory. Moreover, also VASPml requires to enter compiler details and library paths into a file named <code>makefile.include</code> before the standalone build process can be started. The <code>arch</code> folder contains template files for typical compiler toolchains. {{NB\|mind\|The <code>makefile.include</code> files inside VASPml's <code>arch</code> directory are only required for the standalone build described here. For a regular {{VASP}} build they must not be used because then compilers and flags are taken from {{VASP}}'s <code>makefile.include</code> (for this purpose, the special file <code>makefile.include.vasp</code> is used '''automatically''').}}

	=== Step 2: Modify <code>makefile.include</code> ===		=== Step 2: Modify <code>makefile.include</code> ===

Singraber: /* Standalone build instructions */

2025-02-19T08:23:58Z

Standalone build instructions

← Older revision		Revision as of 08:23, 19 February 2025
Line 55:		Line 55:

	= Standalone build instructions =		= Standalone build instructions =

	~~{{NB\|warning\|This part of the documentation is incomplete... work in progress!}}~~

	Although VASPml is typically part of the {{VASP}} build process as described above it is also possible to compile it independently. This can be useful, for example, if {{VASP}} is deliberately compiled without VASPml but the <code>libvaspml</code> library is still necessary to build [[Running machine-learned force fields in LAMMPS#Building LAMMPS with VASPml patch\|LAMMPS with VASPml patch]]. For a standalone build of VASPml follow these steps:		Although VASPml is typically part of the {{VASP}} build process as described above it is also possible to compile it independently. This can be useful, for example, if {{VASP}} is deliberately compiled without VASPml but the <code>libvaspml</code> library is still necessary to build [[Running machine-learned force fields in LAMMPS#Building LAMMPS with VASPml patch\|LAMMPS with VASPml patch]]. For a standalone build of VASPml follow these steps:

Singraber: /* Internal validation tests */

2025-02-19T08:23:39Z

Internal validation tests

← Older revision		Revision as of 08:23, 19 February 2025
Line 114:		Line 114:
	= Internal validation tests =		= Internal validation tests =

	VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <~~core~~>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <~~core~~>makefile.include</~~core~~> file (see [[#Standalone build instructions#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:		VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <code>makefile.include</code> file (see [[#Standalone build instructions#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:

	cd test		cd test

Singraber at 08:20, 19 February 2025

2025-02-19T08:20:29Z

← Older revision		Revision as of 08:20, 19 February 2025
Line 110:		Line 110:
	make libvaspml		make libvaspml

	In order to parallelize the build process it is possible to add the <code>-j</code> flag. The library will be located in <code>lib/libvaspml.a</code>.		In order to parallelize the build process it is possible to add the <code>-j</code> flag. The library will be located in <code>lib/libvaspml.a</code>. To completely remove all compiled files and build folders you may use <code>make clean</code>.

	= Internal validation tests =		= Internal validation tests =

	VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. In addition to the regular dependencies of VASPml the tests require the external library [http://boost.org/libs/test Boost.test] to be present. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:		VASPml comes with its own set of tests (unit tests, integration tests, regression tests) to validate the correctness of the build. They are located in the <code>test</code> subfolder relative to the base directory. In addition to the regular dependencies of VASPml (CBLAS, LAPACKE) the tests require the external library [http://boost.org/libs/test Boost.test] to be present on your system. The corresponding include and linking flags must be added to the <core>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> variables in the <core>makefile.include</core> file (see [[#Standalone build instructions#Step 2: Modify makefile.include\|step 2]] above). Before continuing please make sure the VASPml library was correctly built. To build and execute the tests change to the <code>test</code> directory and run <code>make</code>:

	cd test		cd test
	make		make

	Optionally, use the <code>-j</code> flag to parallelize the build process.		Optionally, use the <code>-j</code> flag to parallelize the build process. The <code>make</code> command will first build multiple test binaries which will then be executed sequentially. Each binary may execute multiple tests which is summarized on the screen like this:

			<span style="color:#808080">Running test executable ====> </span><span style="color:#A82C35">test_TypeMap.x</span>
			Running 2 test cases...
			<span style="color:#6699CC"><b>Entering test module "TypeMap"</b></span>
			<span style="color:#6699CC"><b>test_TypeMap.cpp(16): Entering test suite "UnitTests"</b></span>
			<span style="color:#6699CC"><b>test_TypeMap.cpp(18): Entering test case "RandomOrderMapping_CorrectMapping"</b></span>
			<span style="color:#6699CC"><b>test_TypeMap.cpp(18): Leaving test case "RandomOrderMapping_CorrectMapping"; testing time: 169us</b></span>
			<span style="color:#6699CC"><b>test_TypeMap.cpp(65): Entering test case "IllegalTypeCombination_ThrowError"</b></span>
			<span style="color:#6699CC"><b>test_TypeMap.cpp(65): Leaving test case "IllegalTypeCombination_ThrowError"; testing time: 145us</b></span>
			<span style="color:#6699CC"><b>test_TypeMap.cpp(16): Leaving test suite "UnitTests"; testing time: 340us</b></span>
			<span style="color:#6699CC"><b>Leaving test module "TypeMap"; testing time: 353us</b></span>

			<span style="color:#99CC99"><b>*** No errors detected</b></span>

			The message <code><span style="color:#99CC99"><b>*** No errors detected</b></span></code> should be present for all test binaries. If this is not the case, please file a bug report with the error message, your <code>makefile.include</code> and a description of your toolchain to the [https://www.vasp.at/forum/ {{VASP}} forum], thank you! The <code>test</code> directory can be cleaned up from binaries and build folders with the <code>make clean</code> command.

	[[Category:Machine-learned force fields]]		[[Category:Machine-learned force fields]]