Build instructions

Code structure

This package contains multiple components with varying interdependencies and dependencies on third-party libraries. You may not need to build all components, this depends on the intended use. The following table lists all components and their respective requirements (follow the links for more information).

Component

Requirements

Function

libnnp

C++11 compiler (icpc, g++)

NNP core library (NN, SF, Structure, …)

libnnpif

libnnp, MPI

Interfaces to other software (LAMMPS, …)

libnnptrain

libnnp, MPI, GSL, Eigen 3.3+

Dataset and training routines (Kalman, …).

nnp-convert

libnnp

Convert between structure file formats.

nnp-cutoff

libnnp

Test speed of different cutoff functions.

nnp-dist

libnnp

Calculate radial and angular distribution functions.

nnp-predict

libnnp

Predict energy and forces for one structure.

nnp-prune

libnnp

Prune symmetry functions.

nnp-select

libnnp

Select subset from data set.

nnp-symfunc

libnnp

Symmetry function shape from settings file.

nnp-atomenv

libnnptrain

Write atomic environment data to files.

nnp-checkf

libnnptrain

Check analytic vs. numeric forces.

nnp-comp2

libnnptrain

Compare prediction of 2 NNPs for data set.

nnp-dataset

libnnptrain

Calculate energies and forces for a whole data set.

nnp-norm

libnnptrain

Calculate normalization factors for data set.

nnp-scaling

libnnptrain

Calculate symmetry function values for data set.

nnp-train

libnnptrain

Train a neural network potential.

lammps-nnp

libnnpif

Pair style nnp for LAMMPS

pynnp

libnnp, python, cython

Python interface to NNP library.

doc

Sphinx, Doxygen, Breathe

Documentation.

The master makefile

A master makefile is provided in the src directory which provides targets for all individual components. For instance, compiling the interface library libnnpif requires only to type

make libnnpif

in the src directory. Similarly, to build the application nnp-predict run

make nnp-predict

If an application depends on libraries, these will be built in advance automatically. Compiled binaries will be copied to the bin path (relative to the root directory), whereas libraries can be found in the lib folder. To clean up individual components use

make clean-<component>

or to clean everything (except documentation) use

make clean

By default, all libraries and applications will be built for static linking, i.e .a versions of libraries and statically built versions of executables are created. If dynamic linking is preferred use the MODE=shared switch as additional argument of the make command:

make MODE=shared nnp-predict

This will build .so versions of libraries and executables which require dynamic linking at runtime. Do not forget to point your linker to the lib directory, e.g. correctly set the environment variable LD_LIBRARY_PATH.

There are three different choices for the MODE switch:

  • static (default): This is the default which is used when no mode is explicitly set at the command line. Static build of libraries and applications.

  • shared: Use for dynamic linking, creates .so versions of libraries.

  • test: Special builds for CI tests and coverage reports.

Currently the build process has been tested with two different compilers, the GNU compiler g++ 5.4 (gnu) and the Intel compiler 17 (intel). It is possible to switch between them via the COMP variable, e.g.

make libnnp COMP=intel

If you need to change compiler variables and paths have a look at the corresponding makefiles containing global build parameters:

src/makefile.gnu
src/makefile.intel

You can also create new parameter makefiles based on the above and change the file name suffix according to your target:

src/makefile.<target>
make libnnp COMP=<target>

Note

In contrast to earlier versions it is now safe to use the -j switch to enable parallel compilation. By default only a single processor is used. For instance, in order to use 4 processors to build all components type:

make -j 4

Individual component makefiles

It is also possible to invoke individual makefiles for each component manually. Just switch to the corresponding folder and use make MODE=<mode> COMP=<target>. The global build parameters will be used from the src/makefile.<target> file.

Project-wide compilation options

Each of the build parameter makefiles src/makefile.<target> contains a section at the end which allows to enable/disable certain options at compile time:

Symmetry function groups

Flag: -DN2P2_NO_SF_GROUPS (default: disabled)

If this flag is set the symmetry function group feature will be disabled everywhere. This will result in a much worse performance but may be useful for debugging and development purposes. Note that disabling symmetry function groups will not change results, please see details in this publication 1.

Improved symmetry function derivative memory

Flag: -DN2P2_FULL_SFD_MEMORY (default: disabled)

By default n2p2 reduces the memory usage when multiple elements are present by eliminating storage for symmetry function derivatives which are zero by definition. This happens whenever a symmetry function is only sensitive to neighbors of certain (and not all) elements. Then, there is no space required for derivatives with respect to neighbors of all other elements and hence a significant amount of memory allocation can be avoided. The actual benefit depends on the symmetry function setup, as a rough estimate expect about 30 to 50% reduction. This feature is particularly useful for training of large data sets when symmetry function derivatives are stored in memory (keyword memorize_symfunc_results).

However, for debugging and development purposes (see e.g. this discussion) it can be helpful to keep the naive, full symmetry function derivative memory allocation. This can be achieved by enabling the flag -DN2P2_FULL_SFD_MEMORY. Only in this case there is a one-to-one correspondance between the list of symmetry functions in the libnnp output and the symmetry function derivative vectors in nnp::Atom::Neighbor::dGdr.

Normally, i.e. when -DN2P2_FULL_SFD_MEMORY is disabled, an additional section in the libnnp output will displayed after the SETUP: SYMMETRY FUNCTIONS section, which indicates the amount of still required memory for symmetry function derivatives. Here is how the output looks like for the RPBE-D3 water example (examples/nnp-predict/H2O_RPBE-D3):

*** SETUP: SYMMETRY FUNCTION MEMORY *******************************************

Symmetry function derivatives memory table for element  H :
-------------------------------------------------------------------------------
Relevant symmetry functions for neighbors with element:
-  H:   15 of   27 ( 55.6 %)
-  O:   19 of   27 ( 70.4 %)
-------------------------------------------------------------------------------
Symmetry function derivatives memory table for element  O :
-------------------------------------------------------------------------------
Relevant symmetry functions for neighbors with element:
-  H:   18 of   30 ( 60.0 %)
-  O:   16 of   30 ( 53.3 %)
-------------------------------------------------------------------------------
*******************************************************************************

Benchmarking the training program and the LAMMPS interface with the same system gives the following results:

-DN2P2_FULL_SFD_MEMORY

enabled

disabled

difference

Training (memory)

55.2 GB

37.8 GB

-31.5 %

MD with LAMMPS (memory)

725.6 MB

500.0 MB

-31.1 %

MD with LAMMPS (speed)

33.82 s

34.14 s

+0.9 %

Given the significant reduction in memory and the negligible impact on speed the improved memory layout is used by default (-DN2P2_FULL_SFD_MEMORY disabled).

1

Singraber, A.; Behler, J.; Dellago, C. Library-Based LAMMPS Implementation of High-Dimensional Neural Network Potentials. J. Chem. Theory Comput. 2019, 15 (3), 1827–1840. https://doi.org/10.1021/acs.jctc.8b00770