.. n2p2 - A neural network potential package documentation master file, created by sphinx-quickstart on Tue Jan 29 14:37:49 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to the documentation of n2p2! ===================================== This repository (obtain source code `here `__) provides ready-to-use software for high-dimensional neural network potentials in computational physics and chemistry. The methodology behind the Behler-Parinello neural network potentials was first described here: `J. Behler and M. Parrinello, Phys. Rev. Lett. 98, 146401 (2007) `__ This package contains software that will allow you to use existing neural network potential parameterizations to predict energies and forces (with standalone tools but also in conjunction with the MD software `LAMMPS `__). In addition it is possible to train new neural network potentials with the provided training tools. Documentation ============= .. warning:: Unfortunately many parts of the documentation are still unfinished and will be completed little by little. If you have specific questions, consider to ask on GitHub (file an issue) and I will update the corresponding docs as quickly as possible. This package uses automatic documentation generation via `Doxygen `__, `Sphinx `__ and `Breathe `__. An online version of the documentation which is automatically updated with the main repository can be found `here `__. .. note:: The online documentation describes the ``master`` branch of the *n2p2* repository and not the release versions. .. This package uses automatic documentation generation via `Doxygen .. `__, `Sphinx `__ .. and `Exhale `__. An online version of the .. documentation which is automatically updated with the main repository can be .. found `here `__. API documentation ----------------- Most parts of the C++ code are documented in the header files via Doxygen annotations. The information written in the source files is automatically extracted by `Doxygen` and presented in a separate API documentation page available `here `__. .. Most parts of the C++ code are documented in the header files via Doxygen .. annotations. The information written in the source files is automatically .. extracted by `Exhale` (which uses `Doxygen`) and integrated into this .. documentation (see `API` section on the left). However, because .. this documentation and also `Exhale` is still under development some things may .. not work as expected. As a fallback option the unaltered Doxygen API .. documentation is also available `here `__. Purpose ======= This repository provides applications for multiple purposes. Depending on your task at hand you may only need individual parts and do not need to compile all components (see components table below). As a new user you may find yourself in one of these three possible scenarios: Prediction with existing neural network potential ------------------------------------------------- If you have a working neural network potential setup (i.e. a settings file with network and symmetry function parameters, weight files and a scaling file) ready and want to predict energies and forces for a single structure you only need these components: * :ref:`libnnp ` * :ref:`nnp-predict` Molecular dynamics simulation ----------------------------- Similarly, if you have a working neural network potential setup and would like to run an MD simulation with an external MD software (LAMMPS or CabanaMD), these components are required: * :ref:`libnnp ` * `libnnpif` * :ref:`lammps-nnp ` (for LAMMPS) Training a new neural network potential --------------------------------------- To train a completely new neural network potential the following parts are required: * :ref:`libnnp ` * `libnnptrain` * :ref:`nnp-scaling` * :ref:`nnp-train` Additional, though not strictly required tools, are also quite useful: * `nnp-comp2` * :ref:`nnp-convert` * `nnp-dataset` * `nnp-dist` * :ref:`nnp-norm` * :ref:`nnp-prune` * :ref:`nnp-select` * `nnp-symfunc` Rough guidelines for NNP training are provided :ref:`here `. Examples ======== Applications ------------ Minimal working examples for each application can be found in the corresponding subdirectory in ``examples``, e.g. ``examples/nnp-train``. Training data sets and single configurations (for testing) ---------------------------------------------------------- Small data sets for testing purposes can be found in ``examples/configuration-sets`` and single configurations are provided in ``configuration-single``. Training data sets (full size) ------------------------------ Actual full size data sets may be rather large and are therefore hosted elsewhere: +-------------+--------------+ | System | Link | +=============+==============+ | |H2O| [1]_ | |h2o_data|_ | +-------------+--------------+ | |Cu2S| [2]_ | |cu2s_data|_ | +-------------+--------------+ NNP potentials ready for use ---------------------------- Working pre-trained NNP potentials are located in ``examples/potentials``. Keywords ======== The setup of a neural network potential (network topology, symmetry function parameters,...) is stored in a simple text file with keyword-argument pairs. A list of keywords is provided :ref:`here `. .. toctree:: :hidden: Overview .. toctree:: :hidden: :caption: Topics topics/build topics/descriptors topics/keywords topics/cfg_file topics/training topics/units .. toctree:: :hidden: :caption: Interfaces interfaces/if_lammps interfaces/pair_nnp interfaces/if_cabanamd .. toctree:: :hidden: :caption: Tools tools/libnnp tools/nnp-atomenv tools/nnp-checkf tools/nnp-convert tools/nnp-norm tools/nnp-predict tools/nnp-prune tools/nnp-select tools/nnp-scaling tools/nnp-train .. toctree:: :hidden: :caption: Miscellaneous misc/cabanamd_build_example misc/cg_descriptor_analysis .. toctree:: :hidden: :caption: API api/neural_network api/cutoff_functions api/symmetry_function_types api/symmetry_function_scaling api/memory_layout .. doc-exhale/root .. toctree:: :hidden: :caption: About about/authors about/how_to_cite about/license about/changelog .. |H2O| replace:: H\ :sub:`2`\ O .. |Cu2S| replace:: Cu\ :sub:`2`\ S .. |h2o_data| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.2634098.svg .. _h2o_data: https://doi.org/10.5281/zenodo.2634098 .. |cu2s_data| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.2603918.svg .. _cu2s_data: https://doi.org/10.5281/zenodo.2603918 .. [1] Morawietz, T.; Singraber, A.; Dellago, C.; Behler, J. How van Der Waals Interactions Determine the Unique Properties of Water. Proc. Natl. Acad. Sci. U. S. A. 2016, 113 (30), 8368–8373. https://doi.org/10.1073/pnas.1602375113 .. [2] Singraber, A.; Morawietz, T.; Behler, J.; Dellago, C. Parallel Multistream Training of High-Dimensional Neural Network Potentials. J. Chem. Theory Comput. 2019, 15 (5), 3075–3092. https://doi.org/10.1021/acs.jctc.8b01092