Symmetry Function Parameter Generator for n2p2¶
This module implements schemes from the literature ([GaSc2018], [ImAn2018]) for automatically generating parameter sets for Behler-Parrinello-type symmetry functions ([BePa2007], [Beh2011]), and variations thereof, in neural network potential applications. It is designed to work in conjunction with the n2p2 package, but can be used as a standalone, too.
Purpose of Module¶
To represent potential energy surfaces via an artificial neural network, in a first step, the n2p2 software package uses Behler-Parrinello-type symmetry functions ([BePa2007], [Beh2011]), and variations thereof. These serve as descriptors of an atom’s local chemical environment, that make manifest, already at the input level, the output’s invariance w.r.t. translations, rotations, and particle number permutations. They are obtained via a transformation from the cartesian coordinates of the atom and its neighbor atoms.
The choice of these symmetry functions is an important step in the application of a neural network potential. Both the number of symmetry functions to be used, and the parameters of those symmetry functions (symmetry functions with different parameters being sensitive to different regions in an atom’s surroundings), need to be decided on. In principle, using more symmetry functions yields a more complete description of an atom’s chemical environment and thus improves accuracy. On the other hand, the numerical computation of those symmetry functions in fact tends to be the most computationally expensive step in the application of a neural network potential, so it is undesirable to use too many symmetry functions.
Now, what this module does is implement algorithms from the literature ([GaSc2018], [ImAn2018]) for automatically generating sets of these symmetry function parameters. The aim of these algorithms is to create symmetry function parameter sets that capture all the possible spatial correlations of atoms with their neighbors as completely as possible, while still being economical (i.e., as few symmetry functions as possible), and to do so in a more systematic fashion than when parameters are chosen by hand.
Note that the implemented procedures for generating symmetry function parameter sets are agnostic to the actual dataset of atom configurations that the neural network potential is applied to, and the correlations of atoms therein. They are merely a way of covering all regions in an atom’s environment as completely, yet at the same time as parsimoniously, as possible, without any knowledge of where neighbor atoms in a given system are actually most likely to be located. The symmetry functions generated this way are what is referred to as the ‘pool of candidate SFs’ in [ImAn2018]. This is alluding to the fact that this ‘pool of candidate SFs’ could then be further sparsified, keeping only those symmetry functions that have the greatest descriptive power for a given dataset. Functionality for this is, however, not currently implemented in this module.
The main module file is sfparamgen.py, in tools/python/symfunc_paramgen/src. It implements the class
SymFuncParamGenerator, which provides methods for the parameter generation described above, as well as for
outputting the parameter sets in the format that is required for the parameter file input.nn used by n2p2.
| [GaSc2018] | (1, 2) https://doi.org/10.1063/1.5019667 |
| [ImAn2018] | (1, 2, 3) https://doi.org/10.1063/1.5024611 |
| [BePa2007] | (1, 2) https://doi.org/10.1103/PhysRevLett.98.146401 |
| [Beh2011] | (1, 2) https://doi.org/10.1063/1.3553717 |
Background Information¶
This module is designed to be used in conjunction with n2p2, a software package for high-dimensional neural network potentials in computational physics and chemistry. For more information on n2p2 itself, see:
- n2p2 documentation: https://compphysvienna.github.io/n2p2/index.html
- n2p2 source code: https://github.com/CompPhysVienna/n2p2
That being said, this module does not directly interface the core of n2p2 or call any of its functionality. The
communication of this module with the core of n2p2 is limited to outputting symmetry function parameter sets in a
format that n2p2 can read (the format in which symmetry functions are specified in the parameter file input.nn of
n2p2). Therefore, the module’s functionality for generating symmetry function parameter sets can in principle be used
independently of n2p2.
Building and Testing¶
Seeing as this module itself is just a lightweight Python tool and does not directly interface the core of n2p2, it does not require building. Realistically, however, you will want to use it in conjunction with n2p2’s functionality for neural network potentials, for which you need to build n2p2. This is described here.
Follow these steps to test the module:
- Install the pytest package.
- Navigate to the
tools/python/symfunc_paramgen/testsdirectory. - Run
pytestin your terminal. - For an additional code coverage report install the pytest-cov package.
- Go to the
tools/python/symfunc_paramgen/testsdirectory. - Execute
pytest --cov=sfparamgen --cov-report=html ..
Examples¶
See the example.ipynb IPython notebook in the tools/python/symfunc_paramgen/examples
directory (here is a direct link:
https://github.com/flobuch/n2p2/tree/symfunc_paramgen/tools/python/symfunc_paramgen/examples).
Inside the examples folder, run the example by typing jupyter notebook example.ipynb in your terminal.
Source Code¶
The source code for this module can be found here.
Ultimately, this module is intended to be merged into the official n2p2 code. For the status of the corresponding pull request, see here.