DeePMDkit’s documentation
DeePMDkit is a package written in Python/C++, designed to minimize the effort required to build deep learning based model of interatomic potential energy and force field and to perform molecular dynamics (MD). This brings new hopes to addressing the accuracyversusefficiency dilemma in molecular simulations. Applications of DeePMDkit span from finite molecules to extended systems and from metallic systems to chemically bonded systems.
Important
The project DeePMDkit is licensed under GNU LGPLv3.0. If you use this code in any future publications, please cite this using Han Wang, Linfeng Zhang, Jiequn Han, and Weinan E. “DeePMDkit: A deep learning package for manybody potential energy representation and molecular dynamics.” Computer Physics Communications 228 (2018): 178184.
Getting Started
In this text, we will call the deep neural network that is used to represent the interatomic interactions (Deep Potential) the model. The typical procedure of using DeePMDkit is
Easy install
There are various easy methods to install DeePMDkit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections.
After your easy installation, DeePMDkit (dp
) and LAMMPS (lmp
) will be available to execute. You can try dp h
and lmp h
to see the help. mpirun
is also available considering you may want to train models or run LAMMPS in parallel.
Note: The offline packages and conda packages require the GNU C Library 2.17 or above. The GPU version requires compatible NVIDIA driver to be installed in advance. It is possible to force conda to override detection when installation, but these requirements are still necessary during runtime.
Install offline packages
Both CPU and GPU version offline packages are available in the Releases page.
Some packages are splited into two files due to size limit of GitHub. One may merge them into one after downloading:
cat deepmdkit2.1.1cuda11.6_gpuLinuxx86_64.sh.0 deepmdkit2.1.1cuda11.6_gpuLinuxx86_64.sh.1 > deepmdkit2.1.1cuda11.6_gpuLinuxx86_64.sh
Install with conda
DeePMDkit is avaiable with conda. Install Anaconda or Miniconda first.
One may create an environment that contains the CPU version of DeePMDkit and LAMMPS:
conda create n deepmd deepmdkit=*=*cpu libdeepmd=*=*cpu lammps c https://conda.deepmodeling.com
Or one may want to create a GPU environment containing CUDA Toolkit:
conda create n deepmd deepmdkit=*=*gpu libdeepmd=*=*gpu lammps cudatoolkit=11.6 horovod c https://conda.deepmodeling.com
One could change the CUDA Toolkit version from 10.2
or 11.6
.
One may speficy the DeePMDkit version such as 2.1.1
using
conda create n deepmd deepmdkit=2.1.1=*cpu libdeepmd=2.1.1=*cpu lammps horovod c https://conda.deepmodeling.com
One may enable the environment using
conda activate deepmd
Install with docker
A docker for installing the DeePMDkit is available here.
To pull the CPU version:
docker pull ghcr.io/deepmodeling/deepmdkit:2.1.1_cpu
To pull the GPU version:
docker pull ghcr.io/deepmodeling/deepmdkit:2.1.1_cuda11.6_gpu
To pull the ROCm version:
docker pull deepmodeling/dpmdkitrocm:dp2.0.3rocm4.5.2tf2.6lmp29Sep2021
Prepare data with dpdata
One can use the a convenient tool dpdata
to convert data directly from the output of first principle packages to the DeePMDkit format.
To install one can execute
pip install dpdata
An example of converting data VASP data in OUTCAR
format to DeePMDkit data can be found at
$deepmd_source_dir/examples/data_conv
Switch to that directory, then one can convert data by using the following python script
import dpdata
dsys = dpdata.LabeledSystem('OUTCAR')
dsys.to('deepmd/npy', 'deepmd_data', set_size = dsys.get_nframes())
get_nframes()
method gets the number of frames in the OUTCAR
, and the argument set_size
enforces that the set size is equal to the number of frames in the system, viz. only one set
is created in the system
.
The data in DeePMDkit format is stored in the folder deepmd_data
.
A list of all supported data format and more nice features of dpdata
can be found at the official website.
Train a model
Several examples of training can be found at the examples
directory:
$ cd $deepmd_source_dir/examples/water/se_e2_a/
After switching to that directory, the training can be invoked by
$ dp train input.json
where input.json
is the name of the input script.
By default, the verbosity level of the DeePMDkit is INFO
, one may see a lot of important information on the code and environment showing on the screen. Among them two pieces of information regarding data systems worth special notice.
DEEPMD INFO Summary of DataSystem: training 
DEEPMD INFO found 3 system(s):
DEEPMD INFO system natoms bch_sz n_bch prob pbc
DEEPMD INFO ../data_water/data_0/ 192 1 80 0.250 T
DEEPMD INFO ../data_water/data_1/ 192 1 160 0.500 T
DEEPMD INFO ../data_water/data_2/ 192 1 80 0.250 T
DEEPMD INFO 
DEEPMD INFO Summary of DataSystem: validation 
DEEPMD INFO found 1 system(s):
DEEPMD INFO system natoms bch_sz n_bch prob pbc
DEEPMD INFO ../data_water/data_3 192 1 80 1.000 T
DEEPMD INFO 
The DeePMDkit prints detailed information on the training and validation data sets. The data sets are defined by training_data and validation_data defined in the training section of the input script. The training data set is composed by three data systems, while the validation data set is composed by one data system. The number of atoms, batch size, number of batches in the system and the probability of using the system are all shown on the screen. The last column presents if the periodic boundary condition is assumed for the system.
During the training, the error of the model is tested every disp_freq training steps with the batch used to train the model and with numb_btch batches from the validating data. The training error and validation error are printed correspondingly in the file disp_file (default is lcurve.out
). The batch size can be set in the input script by the key batch_size in the corresponding sections for training and validation data set. An example of the output
# step rmse_val rmse_trn rmse_e_val rmse_e_trn rmse_f_val rmse_f_trn lr
0 3.33e+01 3.41e+01 1.03e+01 1.03e+01 8.39e01 8.72e01 1.0e03
100 2.57e+01 2.56e+01 1.87e+00 1.88e+00 8.03e01 8.02e01 1.0e03
200 2.45e+01 2.56e+01 2.26e01 2.21e01 7.73e01 8.10e01 1.0e03
300 1.62e+01 1.66e+01 5.01e02 4.46e02 5.11e01 5.26e01 1.0e03
400 1.36e+01 1.32e+01 1.07e02 2.07e03 4.29e01 4.19e01 1.0e03
500 1.07e+01 1.05e+01 2.45e03 4.11e03 3.38e01 3.31e01 1.0e03
The file contains 8 columns, form left to right, are the training step, the validation loss, training loss, root mean square (RMS) validation error of energy, RMS training error of energy, RMS validation error of force, RMS training error of force and the learning rate. The RMS error (RMSE) of the energy is normalized by number of atoms in the system. One can visualize this file by a simple Python script:
import numpy as np
import matplotlib.pyplot as plt
data = np.genfromtxt("lcurve.out", names=True)
for name in data.dtype.names[1:1]:
plt.plot(data['step'], data[name], label=name)
plt.legend()
plt.xlabel('Step')
plt.ylabel('Loss')
plt.xscale('symlog')
plt.yscale('log')
plt.grid()
plt.show()
Checkpoints will be written to files with prefix save_ckpt every save_freq training steps.
Warning
It is warned that the example water data (in folder examples/water/data
) is of very limited amount, is provided only for testing purpose, and should not be used to train a production model.
Freeze a model
The trained neural network is extracted from a checkpoint and dumped into a database. This process is called “freezing” a model. The idea and part of our code are from Morgan. To freeze a model, typically one does
$ dp freeze o graph.pb
in the folder where the model is trained. The output database is called graph.pb
.
Test a model
The frozen model can be used in many ways. The most straightforward test can be performed using dp test
. A typical usage of dp test
is
dp test m graph.pb s /path/to/system n 30
where m
gives the tested model, s
the path to the tested system and n
the number of tested frames. Several other command line options can be passed to dp test
, which can be checked with
$ dp test help
An explanation will be provided
usage: dp test [h] [m MODEL] [s SYSTEM] [S SET_PREFIX] [n NUMB_TEST]
[r RAND_SEED] [shuffletest] [d DETAIL_FILE]
optional arguments:
h, help show this help message and exit
m MODEL, model MODEL
Frozen model file to import
s SYSTEM, system SYSTEM
The system dir
S SET_PREFIX, setprefix SET_PREFIX
The set prefix
n NUMB_TEST, numbtest NUMB_TEST
The number of data for test
r RAND_SEED, randseed RAND_SEED
The random seed
shuffletest Shuffle test data
d DETAIL_FILE, detailfile DETAIL_FILE
The file containing details of energy force and virial
accuracy
Run MD with LAMMPS
Running an MD simulation with LAMMPS is simpler. In the LAMMPS input file, one needs to specify the pair style as follows
pair_style deepmd graph.pb
pair_coeff * *
where graph.pb
is the file name of the frozen model. It should be noted that LAMMPS counts atom types starting from 1, therefore, all LAMMPS atom type will be firstly subtracted by 1, and then passed into the DeePMDkit engine to compute the interactions.
Installation
Easy install
There are various easy methods to install DeePMDkit. Choose one that you prefer. If you want to build by yourself, jump to the next two sections.
After your easy installation, DeePMDkit (dp
) and LAMMPS (lmp
) will be available to execute. You can try dp h
and lmp h
to see the help. mpirun
is also available considering you may want to train models or run LAMMPS in parallel.
Note: The offline packages and conda packages require the GNU C Library 2.17 or above. The GPU version requires compatible NVIDIA driver to be installed in advance. It is possible to force conda to override detection when installation, but these requirements are still necessary during runtime.
Install offline packages
Both CPU and GPU version offline packages are available in the Releases page.
Some packages are splited into two files due to size limit of GitHub. One may merge them into one after downloading:
cat deepmdkit2.1.1cuda11.6_gpuLinuxx86_64.sh.0 deepmdkit2.1.1cuda11.6_gpuLinuxx86_64.sh.1 > deepmdkit2.1.1cuda11.6_gpuLinuxx86_64.sh
Install with conda
DeePMDkit is avaiable with conda. Install Anaconda or Miniconda first.
One may create an environment that contains the CPU version of DeePMDkit and LAMMPS:
conda create n deepmd deepmdkit=*=*cpu libdeepmd=*=*cpu lammps c https://conda.deepmodeling.com
Or one may want to create a GPU environment containing CUDA Toolkit:
conda create n deepmd deepmdkit=*=*gpu libdeepmd=*=*gpu lammps cudatoolkit=11.6 horovod c https://conda.deepmodeling.com
One could change the CUDA Toolkit version from 10.2
or 11.6
.
One may speficy the DeePMDkit version such as 2.1.1
using
conda create n deepmd deepmdkit=2.1.1=*cpu libdeepmd=2.1.1=*cpu lammps horovod c https://conda.deepmodeling.com
One may enable the environment using
conda activate deepmd
Install with docker
A docker for installing the DeePMDkit is available here.
To pull the CPU version:
docker pull ghcr.io/deepmodeling/deepmdkit:2.1.1_cpu
To pull the GPU version:
docker pull ghcr.io/deepmodeling/deepmdkit:2.1.1_cuda11.6_gpu
To pull the ROCm version:
docker pull deepmodeling/dpmdkitrocm:dp2.0.3rocm4.5.2tf2.6lmp29Sep2021
Install from source code
Please follow our github webpage to download the latest released version and development version.
Or get the DeePMDkit source code by git clone
cd /some/workspace
git clone recursive https://github.com/deepmodeling/deepmdkit.git deepmdkit
The recursive
option clones all submodules needed by DeePMDkit.
For convenience, you may want to record the location of source to a variable, saying deepmd_source_dir
by
cd deepmdkit
deepmd_source_dir=`pwd`
Install the python interface
Install the Tensorflow’s python interface
First, check the python version on your machine
python version
We follow the virtual environment approach to install TensorFlow’s Python interface. The full instruction can be found on the official TensorFlow website. TensorFlow 1.8 or later is supported. Now we assume that the Python interface will be installed to virtual environment directory $tensorflow_venv
virtualenv p python3 $tensorflow_venv
source $tensorflow_venv/bin/activate
pip install upgrade pip
pip install upgrade tensorflow
It is important that everytime a new shell is started and one wants to use DeePMDkit
, the virtual environment should be activated by
source $tensorflow_venv/bin/activate
if one wants to skip out of the virtual environment, he/she can do
deactivate
If one has multiple python interpreters named like python3.x, it can be specified by, for example
virtualenv p python3.7 $tensorflow_venv
If one does not need the GPU support of deepmdkit and is concerned about package size, the CPUonly version of TensorFlow should be installed by
pip install upgrade tensorflowcpu
To verify the installation, run
python c "import tensorflow as tf;print(tf.reduce_sum(tf.random.normal([1000, 1000])))"
One should remember to activate the virtual environment every time he/she uses deepmdkit.
One can also build TensorFlow Python interface from source for custom hardward optimization, such as CUDA, ROCM, or OneDNN support.
Install the DeePMDkit’s python interface
Check the compiler version on your machine
gcc version
The compiler gcc 4.8 or later is supported in the DeePMDkit. Note that TensorFlow may have specific requirement of the compiler version. It is recommended to use the same compiler version as TensorFlow, which can be printed by python c "import tensorflow;print(tensorflow.version.COMPILER_VERSION)"
.
Execute
cd $deepmd_source_dir
pip install .
One may set the following environment variables before executing pip
:
Environment variables  Allowed value  Default value  Usage 

DP_VARIANT 

 Build CPU variant or GPU variant with CUDA or ROCM support. 
CUDA_TOOLKIT_ROOT_DIR  Path  Detected automatically  The path to the CUDA toolkit directory. CUDA 7.0 or later is supported. NVCC is required. 
ROCM_ROOT  Path  Detected automatically  The path to the ROCM toolkit directory. 
To test the installation, one should firstly jump out of the source directory
cd /some/other/workspace
then execute
dp h
It will print the help information like
usage: dp [h] {train,freeze,test} ...
DeePMDkit: A deep learning package for manybody potential energy
representation and molecular dynamics
optional arguments:
h, help show this help message and exit
Valid subcommands:
{train,freeze,test}
train train a model
freeze freeze the model
test test the model
Install horovod and mpi4py
Horovod and mpi4py is used for parallel training. For better performance on GPU, please follow tuning steps in Horovod on GPU.
# With GPU, prefer NCCL as a communicator.
HOROVOD_WITHOUT_GLOO=1 HOROVOD_WITH_TENSORFLOW=1 HOROVOD_GPU_OPERATIONS=NCCL HOROVOD_NCCL_HOME=/path/to/nccl pip install horovod mpi4py
If your work in CPU environment, please prepare runtime as below:
# By default, MPI is used as communicator.
HOROVOD_WITHOUT_GLOO=1 HOROVOD_WITH_TENSORFLOW=1 pip install horovod mpi4py
To ensure Horovod has been built with proper framework support enabled, one can invoke the horovodrun checkbuild
command, e.g.,
$ horovodrun checkbuild
Horovod v0.22.1:
Available Frameworks:
[X] TensorFlow
[X] PyTorch
[ ] MXNet
Available Controllers:
[X] MPI
[X] Gloo
Available Tensor Operations:
[X] NCCL
[ ] DDL
[ ] CCL
[X] MPI
[X] Gloo
From version 2.0.1, Horovod and mpi4py with MPICH support is shipped with the installer.
If you don’t install horovod, DeePMDkit will fall back to serial mode.
Install the C++ interface
If one does not need to use DeePMDkit with Lammps or IPi, then the python interface installed in the previous section does everything and he/she can safely skip this section.
Install the Tensorflow’s C++ interface
The C++ interface of DeePMDkit was tested with compiler gcc >= 4.8. It is noticed that the IPi support is only compiled with gcc >= 4.8. Note that TensorFlow may have specific requirement of the compiler version.
First the C++ interface of Tensorflow should be installed. It is noted that the version of Tensorflow should be consistent with the python interface. You may follow the instruction or run the script $deepmd_source_dir/source/install/build_tf.py
to install the corresponding C++ interface.
Install the DeePMDkit’s C++ interface
Now go to the source code directory of DeePMDkit and make a build place.
cd $deepmd_source_dir/source
mkdir build
cd build
I assume you want to install DeePMDkit into path $deepmd_root
, then execute cmake
cmake DTENSORFLOW_ROOT=$tensorflow_root DCMAKE_INSTALL_PREFIX=$deepmd_root ..
where the variable tensorflow_root
stores the location where the TensorFlow’s C++ interface is installed.
One may add the following arguments to cmake
:
CMake Aurgements  Allowed value  Default value  Usage 

DTENSORFLOW_ROOT=<value>  Path    The Path to TensorFlow’s C++ interface. 
DCMAKE_INSTALL_PREFIX=<value>  Path    The Path where DeePMDkit will be installed. 
DUSE_CUDA_TOOLKIT=<value> 

 If 
DCUDA_TOOLKIT_ROOT_DIR=<value>  Path  Detected automatically  The path to the CUDA toolkit directory. CUDA 7.0 or later is supported. NVCC is required. 
DUSE_ROCM_TOOLKIT=<value> 

 If 
DROCM_ROOT=<value>  Path  Detected automatically  The path to the ROCM toolkit directory. 
DLAMMPS_VERSION_NUMBER=<value>  Number 
 Only neccessary for LAMMPS builtin mode. The version number of LAMMPS (yyyymmdd). LAMMPS 29Oct2020 (20201029) or later is supported. 
DLAMMPS_SOURCE_ROOT=<value>  Path    Only neccessary for LAMMPS plugin mode. The path to the LAMMPS source code. LAMMPS 8Apr2021 or later is supported. If not assigned, the plugin mode will not be enabled. 
If the cmake has been executed successfully, then run the following make commands to build the package:
make j4
make install
The option j4
means using 4 processes in parallel. You may want to use a different number according to your hardware.
If everything works fine, you will have the following executable and libraries installed in $deepmd_root/bin
and $deepmd_root/lib
$ ls $deepmd_root/bin
dp_ipi dp_ipi_low
$ ls $deepmd_root/lib
libdeepmd_cc_low.so libdeepmd_ipi_low.so libdeepmd_lmp_low.so libdeepmd_low.so libdeepmd_op_cuda.so libdeepmd_op.so
libdeepmd_cc.so libdeepmd_ipi.so libdeepmd_lmp.so libdeepmd_op_cuda_low.so libdeepmd_op_low.so libdeepmd.so
Install LAMMPS
There are two ways to install LAMMPS: the builtin mode and the plugin mode. The builtin mode builds LAMMPS along with the DeePMDkit and DeePMDkit will be loaded automatically when running LAMMPS. The plugin mode builds LAMMPS and a plugin separately, so one needs to use plugin load
command to load the DeePMDkit’s LAMMPS plugin library.
Install LAMMPS’s DeePMDkit module (builtin mode)
Before following this section, DeePMDkit C++ interface should have be installed.
DeePMDkit provides a module for running MD simulation with LAMMPS. Now make the DeePMDkit module for LAMMPS.
cd $deepmd_source_dir/source/build
make lammps
DeePMDkit will generate a module called USERDEEPMD
in the build
directory. If you need the low precision version, move env_low.sh
to env.sh
in the directory. Now download the LAMMPS code, and uncompress it. The LAMMPS version should be the same as what is specified as the CMAKE argument LAMMPS_VERSION_NUMBER
.
cd /some/workspace
wget https://github.com/lammps/lammps/archive/stable_23Jun2022.tar.gz
tar xf stable_23Jun2022.tar.gz
The source code of LAMMPS is stored in directory lammpsstable_23Jun2022
. Now go into the LAMMPS code and copy the DeePMDkit module like this
cd lammpsstable_23Jun2022/src/
cp r $deepmd_source_dir/source/build/USERDEEPMD .
make yeskspace
make yesuserdeepmd
You can enable any other package you want. Now build LAMMPS
make mpi j4
If everything works fine, you will end up with an executable lmp_mpi
.
./lmp_mpi h
The DeePMDkit module can be removed from LAMMPS source code by
make nouserdeepmd
Install LAMMPS (plugin mode)
Starting from 8Apr2021
, LAMMPS also provides a plugin mode, allowing one to build LAMMPS and a plugin separately.
Now download the LAMMPS code (8Apr2021
or later), and uncompress it:
cd /some/workspace
wget https://github.com/lammps/lammps/archive/stable_23Jun2022.tar.gz
tar xf stable_23Jun2022.tar.gz
The source code of LAMMPS is stored in directory lammpsstable_23Jun2022
. The directory of the source code should be specified as the CMAKE argument LAMMPS_SOURCE_ROOT
during installation of the DeePMDkit C++ interface. Now go into the LAMMPS directory and create a directory called build
mkdir p lammpsstable_23Jun2022/build/
cd lammpsstable_23Jun2022/build/
Now build LAMMPS. Note that PLUGIN
and KSPACE
package must be enabled, and BUILD_SHARED_LIBS
must be set to yes
. You can install any other package you want.
cmake D PKG_PLUGIN=ON D PKG_KSPACE=ON D LAMMPS_INSTALL_RPATH=ON D BUILD_SHARED_LIBS=yes D CMAKE_INSTALL_PREFIX=${deepmd_root} D CMAKE_INSTALL_LIBDIR=lib D CMAKE_INSTALL_FULL_LIBDIR=${deepmd_root}/lib ../cmake
make j4
make install
If everything works fine, you will end up with an executable ${deepmd_root}/bin/lmp
.
${deepmd_root}/bin/lmp h
Install iPI
The iPI works in a clientserver model. The iPI provides the server for integrating the replica positions of atoms, while the DeePMDkit provides a client named dp_ipi
that computes the interactions (including energy, force and virial). The server and client communicate via the Unix domain socket or the Internet socket. Full documentation for iPI can be found here. The source code and a complete installation guide for iPI can be found here. To use iPI with already existing drivers, install and update using Pip:
pip install U iPI
Test with Pytest:
pip install pytest
pytest pyargs ipi.tests
Install GROMACS with DeepMD
Before following this section, DeePMDkit C++ interface should have be installed.
Patch source code of GROMACS
Download source code of a supported gromacs version (2020.2) from https://manual.gromacs.org/2020.2/download.html. Run the following command:
export PATH=$PATH:$deepmd_kit_root/bin
dp_gmx_patch d $gromacs_root v $version p
where deepmd_kit_root
is the directory where the latest version of deepmdkit is installed, and gromacs_root
refers to the source code directory of gromacs. And version
represents the version of gromacs, only support 2020.2 now. If attempting to patch another version of gromacs you will still need to set version
to 2020.2
as this is the only supported version, we cannot guarantee that patching other versions of gromacs will work.
Compile GROMACS with deepmdkit
The C++ interface of deepmdkit 2.x
and tensorflow 2.x
are required. And be aware that only deepmdkit with high precision is supported now, since we cannot ensure single precision is enough for a GROMACS simulation. Here is a sample compile script:
#!/bin/bash
export CC=/usr/bin/gcc
export CXX=/usr/bin/g++
export CMAKE_PREFIX_PATH="/path/to/fftw3.3.9" # fftw libraries
mkdir build
cd build
cmake3 .. DCMAKE_CXX_STANDARD=14 \ # not required, but c++14 seems to be more compatible with higher version of tensorflow
DGMX_MPI=ON \
DGMX_GPU=CUDA \ # Gromacs on ROCm has not been fully developed yet
DCUDA_TOOLKIT_ROOT_DIR=/path/to/cuda \
DCMAKE_INSTALL_PREFIX=/path/to/gromacs2020.2deepmd
make j
make install
Building conda packages
One may want to keep both convenience and personalization of the DeePMDkit. To achieve this goal, one can consider building conda packages. We provide building scripts in deepmdkitrecipes organization. These building tools are driven by condabuild and condasmithy.
For example, if one wants to turn on MPIIO
package in LAMMPS, go to lammpsfeedstock
repository and modify recipe/build.sh
. D PKG_MPIIO=OFF
should be changed to D PKG_MPIIO=ON
. Then go to the main directory and executing
./buildlocally.py
This requires that Docker has been installed. After the building, the packages will be generated in build_artifacts/linux64
and build_artifacts/noarch
, and then one can install then executing
conda create n deepmd lammps c file:///path/to/build_artifacts c https://conda.deepmodeling.com c nvidia
One may also upload packages to one’s Anaconda channel, so they can be installed on other machines:
anaconda upload /path/to/build_artifacts/linux64/*.tar.bz2 /path/to/build_artifacts/noarch/*.tar.bz2
Data
In this section, we will introduce how to convert the DFT labeled data into the data format used by DeePMDkit.
The DeePMDkit organize data in systems
. Each system
is composed by a number of frames
. One may roughly view a frame
as a snap shot on an MD trajectory, but it does not necessary come from an MD simulation. A frame
records the coordinates and types of atoms, cell vectors if the periodic boundary condition is assumed, energy, atomic forces and virial. It is noted that the frames
in one system
share the same number of atoms with the same type.
System
DeePMDkit takes a system as data structure. A snapshot of a system is called a frame. A system may contain multiple frames with the same atom types and numbers, i.e. the same formula (like H2O
). To contains data with different formula, one need to divide data into multiple systems.
A system should contain system properties, input frame properties, and labeled frame properties. The system property contains the following property:
ID  Property  Raw file  Required/Optional  Shape  Description 

type  Atom type indexes  type.raw  Required  Natoms  Integers that start with 0 
type_map  Atom type names  type_map.raw  Optional  Ntypes  Atom names that map to atom type, which is unnecessart to be contained in the periodic table 
nopbc  Nonperiodic system  nopbc  Optional  1  If True, this system is nonperiodic; otherwise it’s periodic 
The input frame properties contains the following property, the first axis of which is the number of frames:
ID  Property  Raw file  Unit  Required/Optional  Shape  Description 

coord  Atomic coordinates  coord.raw  Å  Required  Nframes * Natoms * 3  
box  Boxes  box.raw  Å  Required if periodic  Nframes * 3 * 3  in the order 
fparam  Extra frame parameters  fparam.raw  Any  Optional  Nframes * Any  
aparam  Extra atomic parameters  aparam.raw  Any  Optional  Nframes * aparam * Any 
The labeled frame properties is listed as follows, all of which will be used for training if and only if the loss function contains such property:
ID  Property  Raw file  Unit  Shape  Description 

energy  Frame energies  energy.raw  eV  Nframes  
force  Atomic forces  force.raw  eV/Å  Nframes * Natoms * 3  
virial  Frame virial  virial.raw  eV  Nframes * 3  in the order 
atom_ener  Atomic energies  atom_ener.raw  eV  Nframes * Natoms  
atom_pref  Weights of atomic forces  atom_pref.raw  1  Nframes * Natoms  
dipole  Frame dipole  dipole.raw  Any  Nframes * 3  
atomic_dipole  Atomic dipole  atomic_dipole.raw  Any  Nframes * Natoms * 3  
polarizability  Frame polarizability  polarizability.raw  Any  Nframes * 9  in the order 
atomic_polarizability  Atomic polarizability  atomic_polarizability.raw  Any  Nframes * Natoms * 9  in the order 
In general, we always use the following convention of units:
Property  Unit 

Time  ps 
Length  Å 
Energy  eV 
Force  eV/Å 
Virial  eV 
Pressure  Bar 
Formats of a system
Two binaray formats, NumPy and HDF5, are supported for training. The raw format is not directly supported, but a tool is provided to convert data from the raw format to the NumPy format.
NumPy format
In a system with the Numpy format, the system properties are stored as text files ending with .raw
, such as type.raw
amd type_map.raw
, under the system directory. If one needs to train a nonperiodic system, an empty nopbc
file should be put under the system directory. Both input and labeled frame properties are saved as the NumPy binary data (NPY) files ending with .npy
in each of the set.*
directories. Take an example, a system may contain the following files:
type.raw
type_map.raw
nopbc
set.000/coord.npy
set.000/energy.npy
set.000/force.npy
set.001/coord.npy
set.001/energy.npy
set.001/force.npy
We assume that the atom types do not change in all frames. It is provided by type.raw
, which has one line with the types of atoms written one by one. The atom types should be integers. For example the type.raw
of a system that has 2 atoms with 0 and 1:
$ cat type.raw
0 1
Sometimes one needs to map the integer types to atom name. The mapping can be given by the file type_map.raw
. For example
$ cat type_map.raw
O H
The type 0
is named by "O"
and the type 1
is named by "H"
.
HDF5 format
A system with the HDF5 format has the same strucutre as the Numpy format, but in a HDF5 file, a system is organized as an HDF5 group. The file name of a Numpy file is the key in a HDF5 file, and the data is the value to the key. One need to use #
in a DP path to divide the path to the HDF5 file and the HDF5 key:
/path/to/data.hdf5#H2O
Here, /path/to/data.hdf5
is the path and H2O
is the key. There should be some data in the H2O
group, such as H2O/type.raw
and H2O/set.000/force.npy
.
A HDF5 files with a large number of systems has better performance than multiple NumPy files in a large cluster.
Raw format and data conversion
A raw file is a plain text file with each information item written in one file and one frame written on one line. It’s not directly supported, but we provide a tool to convert them.
In the raw format, the property of one frame are provided per line, ending with .raw
. Take an example, the default files that provide box, coordinate, force, energy and virial are box.raw
, coord.raw
, force.raw
, energy.raw
and virial.raw
, respectively. Here is an example of force.raw
:
$ cat force.raw
0.724 2.039 0.951 0.841 0.464 0.363
6.737 1.554 5.587 2.803 0.062 2.222
1.968 0.163 1.020 0.225 0.789 0.343
This force.raw
contains 3 frames with each frame having the forces of 2 atoms, thus it has 3 lines and 6 columns. Each line provides all the 3 force components of 2 atoms in 1 frame. The first three numbers are the 3 force components of the first atom, while the second three numbers are the 3 force components of the second atom. Other files are organized similarly. The number of lines of all raw files should be identical.
One can use the script $deepmd_source_dir/data/raw/raw_to_set.sh
to convert the prepared raw files to the NumPy format. For example, if we have a raw file that contains 6000 frames,
$ ls
box.raw coord.raw energy.raw force.raw type.raw virial.raw
$ $deepmd_source_dir/data/raw/raw_to_set.sh 2000
nframe is 6000
nline per set is 2000
will make 3 sets
making set 0 ...
making set 1 ...
making set 2 ...
$ ls
box.raw coord.raw energy.raw force.raw set.000 set.001 set.002 type.raw virial.raw
It generates three sets set.000
, set.001
and set.002
, with each set contains 2000 frames with the Numpy format.
Prepare data with dpdata
One can use the a convenient tool dpdata
to convert data directly from the output of first principle packages to the DeePMDkit format.
To install one can execute
pip install dpdata
An example of converting data VASP data in OUTCAR
format to DeePMDkit data can be found at
$deepmd_source_dir/examples/data_conv
Switch to that directory, then one can convert data by using the following python script
import dpdata
dsys = dpdata.LabeledSystem('OUTCAR')
dsys.to('deepmd/npy', 'deepmd_data', set_size = dsys.get_nframes())
get_nframes()
method gets the number of frames in the OUTCAR
, and the argument set_size
enforces that the set size is equal to the number of frames in the system, viz. only one set
is created in the system
.
The data in DeePMDkit format is stored in the folder deepmd_data
.
A list of all supported data format and more nice features of dpdata
can be found at the official website.
Model
Overall
A model has two parts, a descriptor that maps atomic configuration to a set of symmetry invariant features, and a fitting net that takes descriptor as input and predicts the atomic contribution to the target physical property. It’s defined in the model section of the input.json
, for example,
"model": {
"type_map": ["O", "H"],
"descriptor" :{
"...": "..."
},
"fitting_net" : {
"...": "..."
}
}
The two subsections, descriptor and fitting_net, define the descriptor and the fitting net, respectively.
The type_map is optional, which provides the element names (but not necessarily same with the actual name of the element) of the corresponding atom types. A model for water, as in this example, has two kinds of atoms. The atom types are internally recorded as integers, e.g., 0
for oxygen and 1
for hydrogen here. A mapping from the atom type to their names is provided by type_map.
DeePMDkit implements the following descriptors:
se_e2_a
: DeepPotSE constructed from all information (both angular and radial) of atomic configurations. The embedding takes the distance between atoms as input.se_e2_r
: DeepPotSE constructed from radial information of atomic configurations. The embedding takes the distance between atoms as input.se_e3
: DeepPotSE constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input.loc_frame
: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame.hybrid
: Concate a list of descriptors to form a new descriptor.
The fitting of the following physical properties are supported
Descriptor "se_e2_a"
The notation of se_e2_a
is short for the Deep Potential Smooth Edition (DeepPotSE) constructed from all information (both angular and radial) of atomic configurations. The e2
stands for the embedding with twoatoms information. This descriptor was described in detail in the DeepPotSE paper.
In this example we will train a DeepPotSE model for a water system. A complete training input script of this example can be find in the directory.
$deepmd_source_dir/examples/water/se_e2_a/input.json
With the training input script, data are also provided in the example directory. One may train the model with the DeePMDkit from the directory.
The construction of the descriptor is given by section descriptor. An example of the descriptor is provided as follows
"descriptor" :{
"type": "se_e2_a",
"rcut_smth": 0.50,
"rcut": 6.00,
"sel": [46, 92],
"neuron": [25, 50, 100],
"type_one_side": true,
"axis_neuron": 16,
"resnet_dt": false,
"seed": 1
}
The type of the descriptor is set to
"se_e2_a"
.rcut is the cutoff radius for neighbor searching, and the rcut_smth gives where the smoothing starts.
sel gives the maximum possible number of neighbors in the cutoff radius. It is a list, the length of which is the same as the number of atom types in the system, and
sel[i]
denote the maximum possible number of neighbors with typei
.The neuron specifies the size of the embedding net. From left to right the members denote the sizes of each hidden layer from input end to the output end, respectively. If the outer layer is of twice size as the inner layer, then the inner layer is copied and concatenated, then a ResNet architecture is built between them.
If the option type_one_side is set to
true
, then descriptor will consider the types of neighbor atoms. Otherwise, both the types of centric and neighbor atoms are considered.The axis_neuron specifies the size of submatrix of the embedding matrix, the axis matrix as explained in the DeepPotSE paper
If the option resnet_dt is set to
true
, then a timestep is used in the ResNet.seed gives the random seed that is used to generate random numbers when initializing the model parameters.
Descriptor "se_e2_r"
The notation of se_e2_r
is short for the Deep Potential Smooth Edition (DeepPotSE) constructed from the radial information of atomic configurations. The e2
stands for the embedding with twoatom information.
A complete training input script of this example can be found in the directory
$deepmd_source_dir/examples/water/se_e2_r/input.json
The training input script is very similar to that of se_e2_a
. The only difference lies in the descriptor section
"descriptor": {
"type": "se_e2_r",
"sel": [46, 92],
"rcut_smth": 0.50,
"rcut": 6.00,
"neuron": [5, 10, 20],
"resnet_dt": false,
"seed": 1,
"_comment": " that's all"
},
The type of the descriptor is set by the key type.
Descriptor "se_e3"
The notation of se_e3
is short for the Deep Potential Smooth Edition (DeepPotSE) constructed from all information (both angular and radial) of atomic configurations. The embedding takes angles between two neighboring atoms as input (denoted by e3
).
A complete training input script of this example can be found in the directory
$deepmd_source_dir/examples/water/se_e3/input.json
The training input script is very similar to that of se_e2_a
. The only difference lies in the descriptor <model/descriptor>
section
"descriptor": {
"type": "se_e3",
"sel": [40, 80],
"rcut_smth": 0.50,
"rcut": 6.00,
"neuron": [2, 4, 8],
"resnet_dt": false,
"seed": 1,
"_comment": " that's all"
},
The type of the descriptor is set by the key type.
Descriptor "hybrid"
This descriptor hybridize multiple descriptors to form a new descriptor. For example we have a list of descriptor denoted by \(\mathcal D_1\), \(\mathcal D_2\), …, \(\mathcal D_N\), the hybrid descriptor this the concatenation of the list, i.e. \(\mathcal D = (\mathcal D_1, \mathcal D_2, \cdots, \mathcal D_N)\).
To use the descriptor in DeePMDkit, one firstly set the type to hybrid, then provide the definitions of the descriptors by the items in the list
,
"descriptor" :{
"type": "hybrid",
"list" : [
{
"type" : "se_e2_a",
...
},
{
"type" : "se_e2_r",
...
}
]
},
A complete training input script of this example can be found in the directory
$deepmd_source_dir/examples/water/hybrid/input.json
Determine sel
All descriptors require to set sel
, which means the expected maximum number of typei neighbors of an atom. DeePMDkit will allocate memory according to sel
.
sel
should not be too large or too small. If sel
is too large, the computing will become much slower and cost more memory. If sel
is not enough, the energy will be not conserved, making the accuracy of the model worse.
To determine a proper sel
, one can calculate the neighbor stat of the training data before training:
dp neighborstat s data r 6.0 t O H
where data
is the directory of data, 6.0
is the cutoff radius, and O
and H
is the type map. The program will give the max_nbor_size
. For example, max_nbor_size
of the water example is [38, 72]
, meaning an atom may have 38 O neighbors and 72 H neighbors in the training data.
The sel
should be set to a higher value than that of the training data, considering there may be some extreme geometries during MD simulations. As a result, we set to [46, 92]
in the water example.
Fit energy
In this section, we will take $deepmd_source_dir/examples/water/se_e2_a/input.json
as an example of the input file.
The fitting network
The construction of the fitting net is give by section fitting_net
"fitting_net" : {
"neuron": [240, 240, 240],
"resnet_dt": true,
"seed": 1
},
neuron specifies the size of the fitting net. If two neighboring layers are of the same size, then a ResNet architecture is built between them.
If the option resnet_dt is set to
true
, then a timestep is used in the ResNet.seed gives the random seed that is used to generate random numbers when initializing the model parameters.
Loss
The loss function \(L\) for training energy is given by
where \(L_e\), \(L_f\), and \(L_v\) denote the loss in energy, force and virial, respectively. \(p_e\), \(p_f\), and \(p_v\) give the prefactors of the energy, force and virial losses. The prefectors may not be a constant, rather it changes linearly with the learning rate. Taking the force prefactor for example, at training step \(t\), it is given by
where \(\alpha(t)\) denotes the learning rate at step \(t\). \(p_f^0\) and \(p_f^\infty\) specifies the \(p_f\) at the start of the training and at the limit of \(t \to \infty\) (set by start_pref_f and limit_pref_f, respectively), i.e.
pref_f(t) = start_pref_f * ( lr(t) / start_lr ) + limit_pref_f * ( 1  lr(t) / start_lr )
The loss section in the input.json
is
"loss" : {
"start_pref_e": 0.02,
"limit_pref_e": 1,
"start_pref_f": 1000,
"limit_pref_f": 1,
"start_pref_v": 0,
"limit_pref_v": 0
}
The options start_pref_e, limit_pref_e, start_pref_f, limit_pref_f, start_pref_v and limit_pref_v determine the start and limit prefactors of energy, force and virial, respectively.
If one does not want to train with virial, then he/she may set the virial prefactors start_pref_v and limit_pref_v to 0.
Fit tensor
like Dipole
and Polarizability
Unlike energy
, which is a scalar, one may want to fit some high dimensional physical quantity, like dipole
(vector) and polarizability
(matrix, shorted as polar
). Deep Potential has provided different APIs to do this. In this example, we will show you how to train a model to fit them for a water system. A complete training input script of the examples can be found in
$deepmd_source_dir/examples/water_tensor/dipole/dipole_input.json
$deepmd_source_dir/examples/water_tensor/polar/polar_input.json
The training and validation data are also provided our examples. But note that the data provided along with the examples are of limited amount, and should not be used to train a production model.
Similar to the input.json
used in ener
mode, training json is also divided into model, learning_rate, loss and training. Most keywords remains the same as ener
mode, and their meaning can be found here. To fit a tensor, one need to modify model/fitting_net and loss.
The fitting Network
The fitting_net section tells DP which fitting net to use.
The json of dipole
type should be provided like
"fitting_net" : {
"type": "dipole",
"sel_type": [0],
"neuron": [100,100,100],
"resnet_dt": true,
"seed": 1,
},
The json of polar
type should be provided like
"fitting_net" : {
"type": "polar",
"sel_type": [0],
"neuron": [100,100,100],
"resnet_dt": true,
"seed": 1,
},
type
specifies which type of fitting net should be used. It should be eitherdipole
orpolar
. Note thatglobal_polar
mode in version 1.x is already deprecated and is merged intopolar
. To specify whether a system is global or atomic, please see here.sel_type
is a list specifying which type of atoms have the quantity you want to fit. For example, in water system,sel_type
is[0]
since0
represents for atomO
. If left unset, all type of atoms will be fitted.The rest
args
has the same meaning as they do inener
mode.
Loss
DP supports a combinational training of global system (only a global tensor
label, i.e. dipole or polar, is provided in a frame) and atomic system (labels for each atom included in sel_type
are provided). In a global system, each frame has just one tensor
label. For example, when fitting polar
, each frame will just provide a 1 x 9
vector which gives the elements of the polarizability tensor of that frame in order XX, XY, XZ, YX, YY, YZ, XZ, ZY, ZZ. By contrast, in a atomic system, each atom in sel_type
has a tensor
label. For example, when fitting dipole, each frame will provide a #sel_atom x 3
matrix, where #sel_atom
is the number of atoms whose type are in sel_type
.
The loss section tells DP the weight of this two kind of loss, i.e.
loss = pref * global_loss + pref_atomic * atomic_loss
The loss section should be provided like
"loss" : {
"type": "tensor",
"pref": 1.0,
"pref_atomic": 1.0
},
type should be written as
tensor
as a distinction fromener
mode.pref and pref_atomic respectively specify the weight of global loss and atomic loss. It can not be left unset. If set to 0, system with corresponding label will NOT be included in the training process.
Training Data Preparation
In tensor mode, the identification of label’s type (global or atomic) is derived from the file name. The global label should be named as dipole.npy/raw
or polarizability.npy/raw
, while the atomic label should be named as atomic_dipole.npy/raw
or atomic_polarizability.npy/raw
. If wrongly named, DP will report an error
ValueError: cannot reshape array of size xxx into shape (xx,xx). This error may occur when your label mismatch it's name, i.e. you might store global tensor in `atomic_tensor.npy` or atomic tensor in `tensor.npy`.
In this case, please check the file name of label.
Train the Model
The training command is the same as ener
mode, i.e.
dp train input.json
The detailed loss can be found in lcurve.out
:
# step rmse_val rmse_trn rmse_lc_val rmse_lc_trn rmse_gl_val rmse_gl_trn lr
0 8.34e+00 8.26e+00 8.34e+00 8.26e+00 0.00e+00 0.00e+00 1.0e02
100 3.51e02 8.55e02 0.00e+00 8.55e02 4.38e03 0.00e+00 5.0e03
200 4.77e02 5.61e02 0.00e+00 5.61e02 5.96e03 0.00e+00 2.5e03
300 5.68e02 1.47e02 0.00e+00 0.00e+00 7.10e03 1.84e03 1.3e03
400 3.73e02 3.48e02 1.99e02 0.00e+00 2.18e03 4.35e03 6.3e04
500 2.77e02 5.82e02 1.08e02 5.82e02 2.11e03 0.00e+00 3.2e04
600 2.81e02 5.43e02 2.01e02 0.00e+00 1.01e03 6.79e03 1.6e04
700 2.97e02 3.28e02 2.03e02 0.00e+00 1.17e03 4.10e03 7.9e05
800 2.25e02 6.19e02 9.05e03 0.00e+00 1.68e03 7.74e03 4.0e05
900 3.18e02 5.54e02 9.93e03 5.54e02 2.74e03 0.00e+00 2.0e05
1000 2.63e02 5.02e02 1.02e02 5.02e02 2.01e03 0.00e+00 1.0e05
1100 3.27e02 5.89e02 2.13e02 5.89e02 1.43e03 0.00e+00 5.0e06
1200 2.85e02 2.42e02 2.85e02 0.00e+00 0.00e+00 3.02e03 2.5e06
1300 3.47e02 5.71e02 1.07e02 5.71e02 3.00e03 0.00e+00 1.3e06
1400 3.13e02 5.76e02 3.13e02 5.76e02 0.00e+00 0.00e+00 6.3e07
1500 3.34e02 1.11e02 2.09e02 0.00e+00 1.57e03 1.39e03 3.2e07
1600 3.11e02 5.64e02 3.11e02 5.64e02 0.00e+00 0.00e+00 1.6e07
1700 2.97e02 5.05e02 2.97e02 5.05e02 0.00e+00 0.00e+00 7.9e08
1800 2.64e02 7.70e02 1.09e02 0.00e+00 1.94e03 9.62e03 4.0e08
1900 3.28e02 2.56e02 3.28e02 0.00e+00 0.00e+00 3.20e03 2.0e08
2000 2.59e02 5.71e02 1.03e02 5.71e02 1.94e03 0.00e+00 1.0e08
One may notice that in each step, some of local loss and global loss will be 0.0
. This is because our training data and validation data consist of global system and atomic system, i.e.
training_data
>atomic_system
>global_system
validation_data
>atomic_system
>global_system
During training, at each step when the lcurve.out is printed, the system used for evaluating the training (validation) error may be either with only global or only atomic labels, thus the corresponding atomic or global errors are missing and are printed as zeros.
Type embedding approach
We generate specific type embedding vector for each atom type, so that we can share one descriptor embedding net and one fitting net in total, which decline training complexity largely.
The training input script is similar to that of se_e2_a
, but different by adding the type_embedding section.
Type embedding net
The model defines how the model is constructed, adding a section of type embedding net:
"model": {
"type_map": ["O", "H"],
"type_embedding":{
...
},
"descriptor" :{
...
},
"fitting_net" : {
...
}
}
Model will automatically apply type embedding approach and generate type embedding vectors. If type embedding vector is detected, descriptor and fitting net would take it as a part of input.
The construction of type embedding net is given by type_embedding. An example of type_embedding is provided as follows
"type_embedding":{
"neuron": [2, 4, 8],
"resnet_dt": false,
"seed": 1
}
The neuron specifies the size of the type embedding net. From left to right the members denote the sizes of each hidden layer from input end to the output end, respectively. It takes onehot vector as input and output dimension equals to the last dimension of the neuron list. If the outer layer is of twice size as the inner layer, then the inner layer is copied and concatenated, then a ResNet architecture is built between them.
If the option resnet_dt is set to
true
, then a timestep is used in the ResNet.seed gives the random seed that is used to generate random numbers when initializing the model parameters.
A complete training input script of this example can be find in the directory.
$deepmd_source_dir/examples/water/se_e2_a_tebd/input.json
See here for further explanation of type embedding
.
P.S.: You can’t apply compression method while using atom type embedding
Deep potential longrange (DPLR)
Notice: The interfaces of DPLR are not stable and subject to change
The method of DPLR is described in this paper. One is recommended to read the paper before using the DPLR.
In the following, we take the DPLR model for example to introduce the training and LAMMPS simulation with the DPLR model. The DPLR model is training in two steps.
Train a deep Wannier model for Wannier centroids
We use the deep Wannier model (DW) to represent the relative position of the Wannier centroid (WC) with the atom to which it is associated. One may consult the introduction of the dipole model for a detailed introduction. An example input wc.json
and a small dataset data
for tutorial purposes can be found in
$deepmd_source_dir/examples/water/dplr/train/
It is noted that the tutorial dataset is not enough for training a productive model. Two settings make the training input script different from an energy training input:
"fitting_net": {
"type": "dipole",
"dipole_type": [0],
"neuron": [128, 128, 128],
"seed": 1
},
The type of fitting is set to dipole. The dipole is associate to type 0 atoms (oxygens), by the setting "dipole_type": [0]
. What we trained is the displacement of the WC from the corresponding oxygen atom. It shares the same training input as atomic dipole because both are 3dimensional vectors defined on atoms. The loss section is provided as follows
"loss": {
"type": "tensor",
"pref": 0.0,
"pref_atomic": 1.0
},
so that the atomic dipole is trained as labels. Note that the numpy compressed file atomic_dipole.npy
should be provided in each dataset.
The training and freezing can be started from the example directory by
dp train dw.json && dp freeze o dw.pb
Train the DPLR model
The training of the DPLR model is very similar to the standard shortrange DP models. An example input script can be found in the example directory. The following section is introduced to compute the longrange energy contribution of the DPLR model, and modify the shortrange DP model by this part.
"modifier": {
"type": "dipole_charge",
"model_name": "dw.pb",
"model_charge_map": [8],
"sys_charge_map": [6, 1],
"ewald_h": 1.00,
"ewald_beta": 0.40
},
The model_name specifies which DW model is used to predict the position of WCs. model_charge_map gives the amount of charge assigned to WCs. sys_charge_map provides the nuclear charge of oxygen (type 0) and hydrogen (type 1) atoms. ewald_beta (unit \(\text{Å}^{1}\)) gives the spread parameter controls the spread of Gaussian charges, and ewald_h (unit Å) assigns the grid size of Fourier transform. The DPLR model can be trained and frozen by (from the example directory)
dp train ener.json && dp freeze o ener.pb
Molecular dynamics simulation with DPLR
In MD simulations, the longrange part of the DPLR is calculated by the LAMMPS kspace
support. Then the longrange interaction is backpropagated to atoms by DeePMDkit. This setup is commonly used in classical molecular dynamics simulations as the “virtual site”. Unfortunately, LAMMPS does not natively support virtual sites, so we have to hack the LAMMPS code, which makes the input configuration and script a little wired.
An example of input configuration file and script can be found in
$deepmd_source_dir/examples/water/dplr/lmp/
We use atom_style full
for DPLR simulations. the coordinates of the WCs are explicitly written to the configuration file. Moreover, a virtual bond is established between the oxygens and the WCs to indicate they are associated together. The configuration file containing 128 H2O molecules is thus written as
512 atoms
3 atom types
128 bonds
1 bond types
0 16.421037674 xlo xhi
0 16.421037674 ylo yhi
0 16.421037674 zlo zhi
0 0 0 xy xz yz
Masses
1 16
2 2
3 16
Atoms
1 1 1 6 8.4960699081e+00 7.5073699951e+00 9.6371297836e+00
2 2 1 6 4.0597701073e+00 6.8156299591e+00 1.2051420212e+01
...
385 1 3 8 8.4960699081e+00 7.5073699951e+00 9.6371297836e+00
386 2 3 8 4.0597701073e+00 6.8156299591e+00 1.2051420212e+01
...
Bonds
1 1 1 385
2 1 2 386
...
The oxygens and hydrogens are assigned with atom types 1 and 2 (corresponding to training atom types 0 and 1), respectively. The WCs are assigned with atom type 3. We want to simulate heavy water so the mass of hydrogens is set to 2.
An example input script is provided in
$deepmd_source_dir/examples/water/dplr/lmp/in.lammps
Here are some explanations
# groups of real and virtual atoms
group real_atom type 1 2
group virtual_atom type 3
# bond between real and its corresponding virtual site should be given
# to setup a map between real and virtual atoms. However, no real
# bonded interaction is applied, thus bond_sytle "zero" is used.
pair_style deepmd ener.pb
pair_coeff * *
bond_style zero
bond_coeff *
special_bonds lj/coul 1 1 1 angle no
Type 1 and 2 (O and H) are real_atom
s, while type 3 (WCs) are virtual_atom
s. The model file ener.pb
stores both the DW and DPLR models, so the position of WCs and the energy can be inferred from it. A virtual bond type is specified by bond_style zero
. The special_bonds
command switches off the exclusion of intramolecular interactions.
# kspace_style "pppm/dplr" should be used. in addition the
# gewald(1/distance) should be set the same as that used in
# training. Currently only ik differentiation is supported.
kspace_style pppm/dplr 1e5
kspace_modify gewald ${BETA} diff ik mesh ${KMESH} ${KMESH} ${KMESH}
The longrange part is calculated by the kspace
support of LAMMPS. The kspace_style
pppm/dplr
is required. The spread parameter set by variable BETA
should be set the same as that used in training. The KMESH
should be set dense enough so the longrange calculation is converged.
# "fix dplr" set the position of the virtual atom, and spread the
# electrostatic interaction asserting on the virtual atom to the real
# atoms. "type_associate" associates the real atom type its
# corresponding virtual atom type. "bond_type" gives the type of the
# bond between the real and virtual atoms.
fix 0 all dplr model ener.pb type_associate 1 3 bond_type 1
fix_modify 0 virial yes
The fix command dplr
calculates the position of WCs by the DW model and backpropagates the longrange interaction on virtual atoms to real toms.
# compute the temperature of real atoms, excluding virtual atom contribution
compute real_temp real_atom temp
compute real_press all pressure real_temp
fix 1 real_atom nvt temp ${TEMP} ${TEMP} ${TAU_T}
fix_modify 1 temp real_temp
The temperature of the system should be computed from the real atoms. The kinetic contribution in the pressure tensor is also computed from the real atoms. The thermostat is applied to only real atoms. The computed temperature and pressure of real atoms can be accessed by, e.g.
fix thermo_print all print ${THERMO_FREQ} "$(step) $(pe) $(ke) $(etotal) $(enthalpy) $(c_real_temp) $(c_real_press) $(vol) $(c_real_press[1]) $(c_real_press[2]) $(c_real_press[3])" append thermo.out screen no title "# step pe ke etotal enthalpy temp press vol pxx pyy pzz"
The LAMMPS simulation can be started from the example directory by
lmp i in.lammps
If LAMMPS complains that no model file ener.pb
exists, it can be copied from the training example directory.
The MD simulation lasts for only 20 steps. If one runs a longer simulation, it will blow up, because the model is trained with a very limited dataset for a very short training steps, thus is of poor quality.
Another restriction should be noted is that the energies printed at the zero step is not correct. This is because at the zero step the position of the WC has not been updated with the DW model. The energies printed in later steps are correct.
Deep Potential  Range Correction (DPRc)
Deep Potential  Range Correction (DPRc) is designed to combine with QM/MM method, and corrects energies from a lowlevel QM/MM method to a highlevel QM/MM method:
See the JCTC paper for details.
Training data
Instead the normal ab initio data, one needs to provide the correction from a lowlevel QM/MM method to a highlevel QM/MM method:
Two levels of data use the same MM method, so \(E_\text{MM}\) is eliminated.
Training the DPRc model
In a DPRc model, QM atoms and MM atoms have different atom types. Assuming we have 4 QM atom types (C, H, O, P) and 2 MM atom types (HW, OW):
"type_map": ["C", "H", "HW", "O", "OW", "P"]
As described in the paper, the DPRc model only corrects \(E_\text{QM}\) and \(E_\text{QM/MM}\) within the cutoff, so we use a hybrid descriptor to describe them separatedly:
"descriptor" :{
"type": "hybrid",
"list" : [
{
"type": "se_e2_a",
"sel": [6, 11, 0, 6, 0, 1],
"rcut_smth": 1.00,
"rcut": 9.00,
"neuron": [12, 25, 50],
"exclude_types": [[2, 2], [2, 4], [4, 4], [0, 2], [0, 4], [1, 2], [1, 4], [3, 2], [3, 4], [5, 2], [5, 4]],
"axis_neuron": 12,
"set_davg_zero": true,
"_comment": " QM/QM interaction"
},
{
"type": "se_e2_a",
"sel": [6, 11, 100, 6, 50, 1],
"rcut_smth": 0.50,
"rcut": 6.00,
"neuron": [12, 25, 50],
"exclude_types": [[0, 0], [0, 1], [0, 3], [0, 5], [1, 1], [1, 3], [1, 5], [3, 3], [3, 5], [5, 5], [2, 2], [2, 4], [4, 4]],
"axis_neuron": 12,
"set_davg_zero": true,
"_comment": " QM/MM interaction"
}
]
}
exclude_types can be generated by the following Python script:
from itertools import combinations_with_replacement, product
qm = (0, 1, 3, 5)
mm = (2, 4)
print("QM/QM:", list(map(list, list(combinations_with_replacement(mm, 2)) + list(product(qm, mm)))))
print("QM/MM:", list(map(list, list(combinations_with_replacement(qm, 2)) + list(combinations_with_replacement(mm, 2)))))
Also, DPRc assumes MM atom energies (atom_ener) are zero:
"fitting_net": {
"neuron": [240, 240, 240],
"resnet_dt": true,
"atom_ener": [null, null, 0.0, null, 0.0, null]
}
Note that atom_ener only works when descriptor/set_davg_zero is true
.
Run MD simulations
The DPRc model has the best practices with the AMBER QM/MM module. An example is given by GitLab RutgersLBSR/AmberDPRc. In theory, DPRc is able to be used with any QM/MM package, as long as the DeePMDkit package accepts QM atoms and MM atoms within the cutoff range and returns energies and forces.
Training
Train a model
Several examples of training can be found at the examples
directory:
$ cd $deepmd_source_dir/examples/water/se_e2_a/
After switching to that directory, the training can be invoked by
$ dp train input.json
where input.json
is the name of the input script.
By default, the verbosity level of the DeePMDkit is INFO
, one may see a lot of important information on the code and environment showing on the screen. Among them two pieces of information regarding data systems worth special notice.
DEEPMD INFO Summary of DataSystem: training 
DEEPMD INFO found 3 system(s):
DEEPMD INFO system natoms bch_sz n_bch prob pbc
DEEPMD INFO ../data_water/data_0/ 192 1 80 0.250 T
DEEPMD INFO ../data_water/data_1/ 192 1 160 0.500 T
DEEPMD INFO ../data_water/data_2/ 192 1 80 0.250 T
DEEPMD INFO 
DEEPMD INFO Summary of DataSystem: validation 
DEEPMD INFO found 1 system(s):
DEEPMD INFO system natoms bch_sz n_bch prob pbc
DEEPMD INFO ../data_water/data_3 192 1 80 1.000 T
DEEPMD INFO 
The DeePMDkit prints detailed information on the training and validation data sets. The data sets are defined by training_data and validation_data defined in the training section of the input script. The training data set is composed by three data systems, while the validation data set is composed by one data system. The number of atoms, batch size, number of batches in the system and the probability of using the system are all shown on the screen. The last column presents if the periodic boundary condition is assumed for the system.
During the training, the error of the model is tested every disp_freq training steps with the batch used to train the model and with numb_btch batches from the validating data. The training error and validation error are printed correspondingly in the file disp_file (default is lcurve.out
). The batch size can be set in the input script by the key batch_size in the corresponding sections for training and validation data set. An example of the output
# step rmse_val rmse_trn rmse_e_val rmse_e_trn rmse_f_val rmse_f_trn lr
0 3.33e+01 3.41e+01 1.03e+01 1.03e+01 8.39e01 8.72e01 1.0e03
100 2.57e+01 2.56e+01 1.87e+00 1.88e+00 8.03e01 8.02e01 1.0e03
200 2.45e+01 2.56e+01 2.26e01 2.21e01 7.73e01 8.10e01 1.0e03
300 1.62e+01 1.66e+01 5.01e02 4.46e02 5.11e01 5.26e01 1.0e03
400 1.36e+01 1.32e+01 1.07e02 2.07e03 4.29e01 4.19e01 1.0e03
500 1.07e+01 1.05e+01 2.45e03 4.11e03 3.38e01 3.31e01 1.0e03
The file contains 8 columns, form left to right, are the training step, the validation loss, training loss, root mean square (RMS) validation error of energy, RMS training error of energy, RMS validation error of force, RMS training error of force and the learning rate. The RMS error (RMSE) of the energy is normalized by number of atoms in the system. One can visualize this file by a simple Python script:
import numpy as np
import matplotlib.pyplot as plt
data = np.genfromtxt("lcurve.out", names=True)
for name in data.dtype.names[1:1]:
plt.plot(data['step'], data[name], label=name)
plt.legend()
plt.xlabel('Step')
plt.ylabel('Loss')
plt.xscale('symlog')
plt.yscale('log')
plt.grid()
plt.show()
Checkpoints will be written to files with prefix save_ckpt every save_freq training steps.
Warning
It is warned that the example water data (in folder examples/water/data
) is of very limited amount, is provided only for testing purpose, and should not be used to train a production model.
Advanced options
In this section, we will take $deepmd_source_dir/examples/water/se_e2_a/input.json
as an example of the input file.
Learning rate
The learning_rate section in input.json
is given as follows
"learning_rate" :{
"type": "exp",
"start_lr": 0.001,
"stop_lr": 3.51e8,
"decay_steps": 5000,
"_comment": "that's all"
}
start_lr gives the learning rate at the beginning of the training.
stop_lr gives the learning rate at the end of the training. It should be small enough to ensure that the network parameters satisfactorily converge.
During the training, the learning rate decays exponentially from start_lr to stop_lr following the formula:
where \(t\) is the training step, \(\alpha\) is the learning rate, \(\alpha_0\) is the starting learning rate (set by start_lr), \(\lambda\) is the decay rate, and \(\tau\) is the decay steps, i.e.
```
lr(t) = start_lr * decay_rate ^ ( t / decay_steps )
```
Training parameters
Other training parameters are given in the training section.
"training": {
"training_data": {
"systems": ["../data_water/data_0/", "../data_water/data_1/", "../data_water/data_2/"],
"batch_size": "auto"
},
"validation_data":{
"systems": ["../data_water/data_3"],
"batch_size": 1,
"numb_btch": 3
},
"mixed_precision": {
"output_prec": "float32",
"compute_prec": "float16"
},
"numb_steps": 1000000,
"seed": 1,
"disp_file": "lcurve.out",
"disp_freq": 100,
"save_freq": 1000
}
The sections training_data and validation_data give the training dataset and validation dataset, respectively. Taking the training dataset for example, the keys are explained below:
systems provide paths of the training data systems. DeePMDkit allows you to provide multiple systems with different numbers of atoms. This key can be a
list
or astr
.At each training step, DeePMDkit randomly pick batch_size frame(s) from one of the systems. The probability of using a system is by default in proportion to the number of batches in the system. More optional are available for automatically determining the probability of using systems. One can set the key auto_prob to
"prob_uniform"
all systems are used with the same probability."prob_sys_size"
the probability of using a system is in proportional to its size (number of frames)."prob_sys_size; sidx_0:eidx_0:w_0; sidx_1:eidx_1:w_1;..."
thelist
of systems are divided into blocks. The blocki
has systems ranging fromsidx_i
toeidx_i
. The probability of using a system from blocki
is in proportional tow_i
. Within one block, the probability of using a system is in proportional to its size.
An example of using
"auto_prob"
is given as below. The probability of usingsystems[2]
is 0.4, and the sum of the probabilities of usingsystems[0]
andsystems[1]
is 0.6. If the number of frames insystems[1]
is twice assystem[0]
, then the probability of usingsystem[1]
is 0.4 and that ofsystem[0]
is 0.2.
"training_data": {
"systems": ["../data_water/data_0/", "../data_water/data_1/", "../data_water/data_2/"],
"auto_prob": "prob_sys_size; 0:2:0.6; 2:3:0.4",
"batch_size": "auto"
}
The probability of using systems can also be specified explicitly with key sys_probs that is a list having the length of the number of systems. For example
"training_data": {
"systems": ["../data_water/data_0/", "../data_water/data_1/", "../data_water/data_2/"],
"sys_probs": [0.5, 0.3, 0.2],
"batch_size": "auto:32"
}
The key batch_size specifies the number of frames used to train or validate the model in a training step. It can be set to
list
: the length of which is the same as the systems. The batch size of each system is given by the elements of the list.int
: all systems use the same batch size."auto"
: the same as"auto:32"
, see"auto:N"
"auto:N"
: automatically determines the batch size so that the batch_size times the number of atoms in the system is no less thanN
.
The key numb_batch in validate_data gives the number of batches of model validation. Note that the batches may not be from the same system
The section mixed_precision specifies the mixed precision settings, which will enable the mixed precision training workflow for deepmdkit. The keys are explained below:
output_prec precision used in the output tensors, only
float32
is supported currently.compute_prec precision used in the computing tensors, only
float16
is supported currently. Note there are severial limitations about the mixed precision training:Only se_e2_a type descriptor is supported by the mixed precision training workflow.
The precision of embedding net and fitting net are forced to be set to
float32
.
Other keys in the training section are explained below:
numb_steps The number of training steps.
seed The random seed for getting frames from the training data set.
disp_file The file for printing learning curve.
disp_freq The frequency of printing learning curve. Set in the unit of training steps
save_freq The frequency of saving check point.
Options and environment variables
Several command line options can be passed to dp train
, which can be checked with
$ dp train help
An explanation will be provided
positional arguments:
INPUT the input json database
optional arguments:
h, help show this help message and exit
initmodel INIT_MODEL
Initialize a model by the provided checkpoint
restart RESTART Restart the training from the provided checkpoint
initfrzmodel INIT_FRZ_MODEL
Initialize the training from the frozen model.
skipneighborstat Skip calculating neighbor statistics. Sel checking, automatic sel, and model compression will be disabled. (default: False)
initmodel model.ckpt
, initializes the model training with an existing model that is stored in the checkpoint model.ckpt
, the network architectures should match.
restart model.ckpt
, continues the training from the checkpoint model.ckpt
.
initfrzmodel frozen_model.pb
, initializes the training with an existing model that is stored in frozen_model.pb
.
skipneighborstat
will skip calculating neighbor statistics if one is concerned about performance. Some features will be disabled.
To get the best performance, one should control the number of threads used by DeePMDkit. This is achieved by three environmental variables: OMP_NUM_THREADS
, TF_INTRA_OP_PARALLELISM_THREADS
and TF_INTER_OP_PARALLELISM_THREADS
. OMP_NUM_THREADS
controls the multithreading of DeePMDkit implemented operations. TF_INTRA_OP_PARALLELISM_THREADS
and TF_INTER_OP_PARALLELISM_THREADS
controls intra_op_parallelism_threads
and inter_op_parallelism_threads
, which are Tensorflow configurations for multithreading. An explanation is found here.
For example if you wish to use 3 cores of 2 CPUs on one node, you may set the environmental variables and run DeePMDkit as follows:
export OMP_NUM_THREADS=3
export TF_INTRA_OP_PARALLELISM_THREADS=3
export TF_INTER_OP_PARALLELISM_THREADS=2
dp train input.json
For a node with 128 cores, it is recommended to start with the following variables:
export OMP_NUM_THREADS=16
export TF_INTRA_OP_PARALLELISM_THREADS=16
export TF_INTER_OP_PARALLELISM_THREADS=8
It is encouraged to adjust the configurations after empirical testing.
One can set other environmental variables:
Environment variables  Allowed value  Default value  Usage 

DP_INTERFACE_PREC 

 Control high (double) or low (float) precision of training. 
DP_AUTO_PARALLELIZATION  0, 1  0  Enable auto parallelization for CPU operators. 
Adjust sel
of a frozen model
One can use initfrzmodel
features to adjust (increase or decrease) sel
of a existing model. Firstly, one need to adjust sel
in input.json
. For example, adjust from [46, 92]
to [23, 46]
.
"model": {
"descriptor": {
"sel": [23, 46]
}
}
To obtain the new model at once, numb_steps
should be set to zero:
"training": {
"numb_steps": 0
}
Then, one can initialize the training from the frozen model and freeze the new model at once:
dp train input.json initfrzmodel frozen_model.pb
dp freeze o frozen_model_adjusted_sel.pb
Two models should give the same result when the input satisfies both constraints.
Note: At this time, this feature is only supported by se_e2_a
descriptor with set_davg_true
enable, or hybrid
composed of above descriptors.
Training Parameters
Note
One can load, modify, and export the input file by using our effective webbased tool DPGUI. All training parameters below can be set in DPGUI. By clicking “SAVE JSON”, one can download the input file for furthur training.
 model:
 type:
dict
argument path:model
 type_map:
 type:
list
, optionalargument path:model/type_map
A list of strings. Give the name to each type of atoms. It is noted that the number of atom type of training system must be less than 128 in a GPU environment.
 data_stat_nbatch:
 type:
int
, optional, default:10
argument path:model/data_stat_nbatch
The model determines the normalization from the statistics of the data. This key specifies the number of frames in each system used for statistics.
 data_stat_protect:
 type:
float
, optional, default:0.01
argument path:model/data_stat_protect
Protect parameter for atomic energy regression.
 use_srtab:
 type:
str
, optionalargument path:model/use_srtab
The table for the shortrange pairwise interaction added on top of DP. The table is a text data file with (N_t + 1) * N_t / 2 + 1 columes. The first colume is the distance between atoms. The second to the last columes are energies for pairs of certain types. For example we have two atom types, 0 and 1. The columes from 2nd to 4th are for 00, 01 and 11 correspondingly.
 smin_alpha:
 type:
float
, optionalargument path:model/smin_alpha
The shortrange tabulated interaction will be swithed according to the distance of the nearest neighbor. This distance is calculated by softmin. This parameter is the decaying parameter in the softmin. It is only required when use_srtab is provided.
 sw_rmin:
 type:
float
, optionalargument path:model/sw_rmin
The lower boundary of the interpolation between shortrange tabulated interaction and DP. It is only required when use_srtab is provided.
 sw_rmax:
 type:
float
, optionalargument path:model/sw_rmax
The upper boundary of the interpolation between shortrange tabulated interaction and DP. It is only required when use_srtab is provided.
 type_embedding:
 type:
dict
, optionalargument path:model/type_embedding
The type embedding.
 neuron:
 type:
list
, optional, default:[2, 4, 8]
argument path:model/type_embedding/neuron
Number of neurons in each hidden layers of the embedding net. When two layers are of the same size or one layer is twice as large as the previous layer, a skip connection is built.
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/type_embedding/activation_function
The activation function in the embedding net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 resnet_dt:
 type:
bool
, optional, default:False
argument path:model/type_embedding/resnet_dt
Whether to use a “Timestep” in the skip connection
 precision:
 type:
str
, optional, default:default
argument path:model/type_embedding/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 trainable:
 type:
bool
, optional, default:True
argument path:model/type_embedding/trainable
If the parameters in the embedding net are trainable
 seed:
 type:
int
NoneType
, optionalargument path:model/type_embedding/seed
Random seed for parameter initialization
 descriptor:
 type:
dict
argument path:model/descriptor
The descriptor of atomic environment.
Depending on the value of type, different sub args are accepted.
 type:
 type:
str
(flag key)argument path:model/descriptor/type
The type of the descritpor. See explanation below.
loc_frame: Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame.
se_e2_a: Used by the smooth edition of Deep Potential. The full relative coordinates are used to construct the descriptor.
se_e2_r: Used by the smooth edition of Deep Potential. Only the distance between atoms is used to construct the descriptor.
se_e3: Used by the smooth edition of Deep Potential. The full relative coordinates are used to construct the descriptor. Threebody embedding will be used by this descriptor.
se_a_tpe: Used by the smooth edition of Deep Potential. The full relative coordinates are used to construct the descriptor. Type embedding will be used by this descriptor.
hybrid: Concatenate of a list of descriptors as a new descriptor.
When type is set to
loc_frame
: sel_a:
 type:
list
argument path:model/descriptor[loc_frame]/sel_a
A list of integers. The length of the list should be the same as the number of atom types in the system. sel_a[i] gives the selected number of typei neighbors. The full relative coordinates of the neighbors are used by the descriptor.
 sel_r:
 type:
list
argument path:model/descriptor[loc_frame]/sel_r
A list of integers. The length of the list should be the same as the number of atom types in the system. sel_r[i] gives the selected number of typei neighbors. Only relative distance of the neighbors are used by the descriptor. sel_a[i] + sel_r[i] is recommended to be larger than the maximally possible number of typei neighbors in the cutoff radius.
 rcut:
 type:
float
, optional, default:6.0
argument path:model/descriptor[loc_frame]/rcut
The cutoff radius. The default value is 6.0
 axis_rule:
 type:
list
argument path:model/descriptor[loc_frame]/axis_rule
A list of integers. The length should be 6 times of the number of types.
axis_rule[i*6+0]: class of the atom defining the first axis of typei atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.
axis_rule[i*6+1]: type of the atom defining the first axis of typei atom.
axis_rule[i*6+2]: index of the axis atom defining the first axis. Note that the neighbors with the same class and type are sorted according to their relative distance.
axis_rule[i*6+3]: class of the atom defining the first axis of typei atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.
axis_rule[i*6+4]: type of the atom defining the second axis of typei atom.
axis_rule[i*6+5]: class of the atom defining the second axis of typei atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.
When type is set to
se_e2_a
(or its aliasse_a
): sel:
 type:
list
str
, optional, default:auto
argument path:model/descriptor[se_e2_a]/sel
This parameter set the number of selected neighbors for each type of atom. It can be:
List[int]. The length of the list should be the same as the number of atom types in the system. sel[i] gives the selected number of typei neighbors. sel[i] is recommended to be larger than the maximally possible number of typei neighbors in the cutoff radius. It is noted that the total sel value must be less than 4096 in a GPU environment.
str. Can be “auto:factor” or “auto”. “factor” is a float number larger than 1. This option will automatically determine the sel. In detail it counts the maximal number of neighbors with in the cutoff radius for each type of neighbor, then multiply the maximum by the “factor”. Finally the number is wraped up to 4 divisible. The option “auto” is equivalent to “auto:1.1”.
 rcut:
 type:
float
, optional, default:6.0
argument path:model/descriptor[se_e2_a]/rcut
The cutoff radius.
 rcut_smth:
 type:
float
, optional, default:0.5
argument path:model/descriptor[se_e2_a]/rcut_smth
Where to start smoothing. For example the 1/r term is smoothed from rcut to rcut_smth
 neuron:
 type:
list
, optional, default:[10, 20, 40]
argument path:model/descriptor[se_e2_a]/neuron
Number of neurons in each hidden layers of the embedding net. When two layers are of the same size or one layer is twice as large as the previous layer, a skip connection is built.
 axis_neuron:
 type:
int
, optional, default:4
, alias: n_axis_neuronargument path:model/descriptor[se_e2_a]/axis_neuron
Size of the submatrix of G (embedding matrix).
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/descriptor[se_e2_a]/activation_function
The activation function in the embedding net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 resnet_dt:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e2_a]/resnet_dt
Whether to use a “Timestep” in the skip connection
 type_one_side:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e2_a]/type_one_side
Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets
 precision:
 type:
str
, optional, default:default
argument path:model/descriptor[se_e2_a]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 trainable:
 type:
bool
, optional, default:True
argument path:model/descriptor[se_e2_a]/trainable
If the parameters in the embedding net is trainable
 seed:
 type:
int
NoneType
, optionalargument path:model/descriptor[se_e2_a]/seed
Random seed for parameter initialization
 exclude_types:
 type:
list
, optional, default:[]
argument path:model/descriptor[se_e2_a]/exclude_types
The excluded pairs of types which have no interaction with each other. For example, [[0, 1]] means no interaction between type 0 and type 1.
 set_davg_zero:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e2_a]/set_davg_zero
Set the normalization average to zero. This option should be set when atom_ener in the energy fitting is used
When type is set to
se_e3
(or its aliasesse_at
,se_a_3be
,se_t
): sel:
 type:
list
str
, optional, default:auto
argument path:model/descriptor[se_e3]/sel
This parameter set the number of selected neighbors for each type of atom. It can be:
List[int]. The length of the list should be the same as the number of atom types in the system. sel[i] gives the selected number of typei neighbors. sel[i] is recommended to be larger than the maximally possible number of typei neighbors in the cutoff radius. It is noted that the total sel value must be less than 4096 in a GPU environment.
str. Can be “auto:factor” or “auto”. “factor” is a float number larger than 1. This option will automatically determine the sel. In detail it counts the maximal number of neighbors with in the cutoff radius for each type of neighbor, then multiply the maximum by the “factor”. Finally the number is wraped up to 4 divisible. The option “auto” is equivalent to “auto:1.1”.
 rcut:
 type:
float
, optional, default:6.0
argument path:model/descriptor[se_e3]/rcut
The cutoff radius.
 rcut_smth:
 type:
float
, optional, default:0.5
argument path:model/descriptor[se_e3]/rcut_smth
Where to start smoothing. For example the 1/r term is smoothed from rcut to rcut_smth
 neuron:
 type:
list
, optional, default:[10, 20, 40]
argument path:model/descriptor[se_e3]/neuron
Number of neurons in each hidden layers of the embedding net. When two layers are of the same size or one layer is twice as large as the previous layer, a skip connection is built.
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/descriptor[se_e3]/activation_function
The activation function in the embedding net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 resnet_dt:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e3]/resnet_dt
Whether to use a “Timestep” in the skip connection
 precision:
 type:
str
, optional, default:default
argument path:model/descriptor[se_e3]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 trainable:
 type:
bool
, optional, default:True
argument path:model/descriptor[se_e3]/trainable
If the parameters in the embedding net are trainable
 seed:
 type:
int
NoneType
, optionalargument path:model/descriptor[se_e3]/seed
Random seed for parameter initialization
 set_davg_zero:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e3]/set_davg_zero
Set the normalization average to zero. This option should be set when atom_ener in the energy fitting is used
When type is set to
se_a_tpe
(or its aliasse_a_ebd
): sel:
 type:
list
str
, optional, default:auto
argument path:model/descriptor[se_a_tpe]/sel
This parameter set the number of selected neighbors for each type of atom. It can be:
List[int]. The length of the list should be the same as the number of atom types in the system. sel[i] gives the selected number of typei neighbors. sel[i] is recommended to be larger than the maximally possible number of typei neighbors in the cutoff radius. It is noted that the total sel value must be less than 4096 in a GPU environment.
str. Can be “auto:factor” or “auto”. “factor” is a float number larger than 1. This option will automatically determine the sel. In detail it counts the maximal number of neighbors with in the cutoff radius for each type of neighbor, then multiply the maximum by the “factor”. Finally the number is wraped up to 4 divisible. The option “auto” is equivalent to “auto:1.1”.
 rcut:
 type:
float
, optional, default:6.0
argument path:model/descriptor[se_a_tpe]/rcut
The cutoff radius.
 rcut_smth:
 type:
float
, optional, default:0.5
argument path:model/descriptor[se_a_tpe]/rcut_smth
Where to start smoothing. For example the 1/r term is smoothed from rcut to rcut_smth
 neuron:
 type:
list
, optional, default:[10, 20, 40]
argument path:model/descriptor[se_a_tpe]/neuron
Number of neurons in each hidden layers of the embedding net. When two layers are of the same size or one layer is twice as large as the previous layer, a skip connection is built.
 axis_neuron:
 type:
int
, optional, default:4
, alias: n_axis_neuronargument path:model/descriptor[se_a_tpe]/axis_neuron
Size of the submatrix of G (embedding matrix).
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/descriptor[se_a_tpe]/activation_function
The activation function in the embedding net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 resnet_dt:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_a_tpe]/resnet_dt
Whether to use a “Timestep” in the skip connection
 type_one_side:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_a_tpe]/type_one_side
Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets
 precision:
 type:
str
, optional, default:default
argument path:model/descriptor[se_a_tpe]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 trainable:
 type:
bool
, optional, default:True
argument path:model/descriptor[se_a_tpe]/trainable
If the parameters in the embedding net is trainable
 seed:
 type:
int
NoneType
, optionalargument path:model/descriptor[se_a_tpe]/seed
Random seed for parameter initialization
 exclude_types:
 type:
list
, optional, default:[]
argument path:model/descriptor[se_a_tpe]/exclude_types
The excluded pairs of types which have no interaction with each other. For example, [[0, 1]] means no interaction between type 0 and type 1.
 set_davg_zero:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_a_tpe]/set_davg_zero
Set the normalization average to zero. This option should be set when atom_ener in the energy fitting is used
 type_nchanl:
 type:
int
, optional, default:4
argument path:model/descriptor[se_a_tpe]/type_nchanl
number of channels for type embedding
 type_nlayer:
 type:
int
, optional, default:2
argument path:model/descriptor[se_a_tpe]/type_nlayer
number of hidden layers of type embedding net
 numb_aparam:
 type:
int
, optional, default:0
argument path:model/descriptor[se_a_tpe]/numb_aparam
dimension of atomic parameter. if set to a value > 0, the atomic parameters are embedded.
When type is set to
se_e2_r
(or its aliasse_r
): sel:
 type:
list
str
, optional, default:auto
argument path:model/descriptor[se_e2_r]/sel
This parameter set the number of selected neighbors for each type of atom. It can be:
List[int]. The length of the list should be the same as the number of atom types in the system. sel[i] gives the selected number of typei neighbors. sel[i] is recommended to be larger than the maximally possible number of typei neighbors in the cutoff radius. It is noted that the total sel value must be less than 4096 in a GPU environment.
str. Can be “auto:factor” or “auto”. “factor” is a float number larger than 1. This option will automatically determine the sel. In detail it counts the maximal number of neighbors with in the cutoff radius for each type of neighbor, then multiply the maximum by the “factor”. Finally the number is wraped up to 4 divisible. The option “auto” is equivalent to “auto:1.1”.
 rcut:
 type:
float
, optional, default:6.0
argument path:model/descriptor[se_e2_r]/rcut
The cutoff radius.
 rcut_smth:
 type:
float
, optional, default:0.5
argument path:model/descriptor[se_e2_r]/rcut_smth
Where to start smoothing. For example the 1/r term is smoothed from rcut to rcut_smth
 neuron:
 type:
list
, optional, default:[10, 20, 40]
argument path:model/descriptor[se_e2_r]/neuron
Number of neurons in each hidden layers of the embedding net. When two layers are of the same size or one layer is twice as large as the previous layer, a skip connection is built.
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/descriptor[se_e2_r]/activation_function
The activation function in the embedding net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 resnet_dt:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e2_r]/resnet_dt
Whether to use a “Timestep” in the skip connection
 type_one_side:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e2_r]/type_one_side
Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets
 precision:
 type:
str
, optional, default:default
argument path:model/descriptor[se_e2_r]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 trainable:
 type:
bool
, optional, default:True
argument path:model/descriptor[se_e2_r]/trainable
If the parameters in the embedding net are trainable
 seed:
 type:
int
NoneType
, optionalargument path:model/descriptor[se_e2_r]/seed
Random seed for parameter initialization
 exclude_types:
 type:
list
, optional, default:[]
argument path:model/descriptor[se_e2_r]/exclude_types
The excluded pairs of types which have no interaction with each other. For example, [[0, 1]] means no interaction between type 0 and type 1.
 set_davg_zero:
 type:
bool
, optional, default:False
argument path:model/descriptor[se_e2_r]/set_davg_zero
Set the normalization average to zero. This option should be set when atom_ener in the energy fitting is used
When type is set to
hybrid
: list:
 type:
list
argument path:model/descriptor[hybrid]/list
A list of descriptor definitions
 fitting_net:
 type:
dict
argument path:model/fitting_net
The fitting of physical properties.
Depending on the value of type, different sub args are accepted.
 type:
 type:
str
(flag key), default:ener
argument path:model/fitting_net/type
The type of the fitting. See explanation below.
ener: Fit an energy model (potential energy surface).
dipole: Fit an atomic dipole model. Global dipole labels or atomic dipole labels for all the selected atoms (see sel_type) should be provided by dipole.npy in each data system. The file either has number of frames lines and 3 times of number of selected atoms columns, or has number of frames lines and 3 columns. See loss parameter.
polar: Fit an atomic polarizability model. Global polarizazbility labels or atomic polarizability labels for all the selected atoms (see sel_type) should be provided by polarizability.npy in each data system. The file eith has number of frames lines and 9 times of number of selected atoms columns, or has number of frames lines and 9 columns. See loss parameter.
When type is set to
ener
: numb_fparam:
 type:
int
, optional, default:0
argument path:model/fitting_net[ener]/numb_fparam
The dimension of the frame parameter. If set to >0, file fparam.npy should be included to provided the input fparams.
 numb_aparam:
 type:
int
, optional, default:0
argument path:model/fitting_net[ener]/numb_aparam
The dimension of the atomic parameter. If set to >0, file aparam.npy should be included to provided the input aparams.
 neuron:
 type:
list
, optional, default:[120, 120, 120]
, alias: n_neuronargument path:model/fitting_net[ener]/neuron
The number of neurons in each hidden layers of the fitting net. When two hidden layers are of the same size, a skip connection is built.
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/fitting_net[ener]/activation_function
The activation function in the fitting net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 precision:
 type:
str
, optional, default:default
argument path:model/fitting_net[ener]/precision
The precision of the fitting net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 resnet_dt:
 type:
bool
, optional, default:True
argument path:model/fitting_net[ener]/resnet_dt
Whether to use a “Timestep” in the skip connection
 trainable:
 type:
list
bool
, optional, default:True
argument path:model/fitting_net[ener]/trainable
Whether the parameters in the fitting net are trainable. This option can be
bool: True if all parameters of the fitting net are trainable, False otherwise.
list of bool: Specifies if each layer is trainable. Since the fitting net is composed by hidden layers followed by a output layer, the length of tihs list should be equal to len(neuron)+1.
 rcond:
 type:
float
, optional, default:0.001
argument path:model/fitting_net[ener]/rcond
The condition number used to determine the inital energy shift for each type of atoms.
 seed:
 type:
int
NoneType
, optionalargument path:model/fitting_net[ener]/seed
Random seed for parameter initialization of the fitting net
 atom_ener:
 type:
list
, optional, default:[]
argument path:model/fitting_net[ener]/atom_ener
Specify the atomic energy in vacuum for each type
When type is set to
dipole
: neuron:
 type:
list
, optional, default:[120, 120, 120]
, alias: n_neuronargument path:model/fitting_net[dipole]/neuron
The number of neurons in each hidden layers of the fitting net. When two hidden layers are of the same size, a skip connection is built.
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/fitting_net[dipole]/activation_function
The activation function in the fitting net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 resnet_dt:
 type:
bool
, optional, default:True
argument path:model/fitting_net[dipole]/resnet_dt
Whether to use a “Timestep” in the skip connection
 precision:
 type:
str
, optional, default:default
argument path:model/fitting_net[dipole]/precision
The precision of the fitting net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 sel_type:
 type:
list
NoneType
int
, optional, alias: dipole_typeargument path:model/fitting_net[dipole]/sel_type
The atom types for which the atomic dipole will be provided. If not set, all types will be selected.
 seed:
 type:
int
NoneType
, optionalargument path:model/fitting_net[dipole]/seed
Random seed for parameter initialization of the fitting net
When type is set to
polar
: neuron:
 type:
list
, optional, default:[120, 120, 120]
, alias: n_neuronargument path:model/fitting_net[polar]/neuron
The number of neurons in each hidden layers of the fitting net. When two hidden layers are of the same size, a skip connection is built.
 activation_function:
 type:
str
, optional, default:tanh
argument path:model/fitting_net[polar]/activation_function
The activation function in the fitting net. Supported activation functions are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.. Note that “gelu” denotes the custom operator version, and “gelu_tf” denotes the TF standard version.
 resnet_dt:
 type:
bool
, optional, default:True
argument path:model/fitting_net[polar]/resnet_dt
Whether to use a “Timestep” in the skip connection
 precision:
 type:
str
, optional, default:default
argument path:model/fitting_net[polar]/precision
The precision of the fitting net parameters, supported options are “default”, “float16”, “float32”, “float64”. Default follows the interface precision.
 fit_diag:
 type:
bool
, optional, default:True
argument path:model/fitting_net[polar]/fit_diag
Fit the diagonal part of the rotational invariant polarizability matrix, which will be converted to normal polarizability matrix by contracting with the rotation matrix.
 scale:
 type:
list
float
, optional, default:1.0
argument path:model/fitting_net[polar]/scale
The output of the fitting net (polarizability matrix) will be scaled by
scale
 shift_diag:
 type:
bool
, optional, default:True
argument path:model/fitting_net[polar]/shift_diag
Whether to shift the diagonal of polar, which is beneficial to training. Default is true.
 sel_type:
 type:
list
NoneType
int
, optional, alias: pol_typeargument path:model/fitting_net[polar]/sel_type
The atom types for which the atomic polarizability will be provided. If not set, all types will be selected.
 seed:
 type:
int
NoneType
, optionalargument path:model/fitting_net[polar]/seed
Random seed for parameter initialization of the fitting net
 modifier:
 type:
dict
, optionalargument path:model/modifier
The modifier of model output.
Depending on the value of type, different sub args are accepted.
 type:
The type of modifier. See explanation below.
dipole_charge: Use WFCC to model the electronic structure of the system. Correct the longrange interaction
When type is set to
dipole_charge
: model_name:
 type:
str
argument path:model/modifier[dipole_charge]/model_name
The name of the frozen dipole model file.
 model_charge_map:
 type:
list
argument path:model/modifier[dipole_charge]/model_charge_map
The charge of the WFCC. The list length should be the same as the sel_type.
 sys_charge_map:
 type:
list
argument path:model/modifier[dipole_charge]/sys_charge_map
The charge of real atoms. The list length should be the same as the type_map
 ewald_beta:
 type:
float
, optional, default:0.4
argument path:model/modifier[dipole_charge]/ewald_beta
The splitting parameter of Ewald sum. Unit is A^1
 ewald_h:
 type:
float
, optional, default:1.0
argument path:model/modifier[dipole_charge]/ewald_h
The grid spacing of the FFT grid. Unit is A
 compress:
 type:
dict
, optionalargument path:model/compress
Model compression configurations
Depending on the value of type, different sub args are accepted.
 type:
The type of model compression, which should be consistent with the descriptor type.
When type is set to
se_e2_a
(or its aliasse_a
): model_file:
 type:
str
argument path:model/compress[se_e2_a]/model_file
The input model file, which will be compressed by the DeePMDkit.
 table_config:
 type:
list
argument path:model/compress[se_e2_a]/table_config
The arguments of model compression, including extrapolate(scale of model extrapolation), stride(uniform stride of tabulation’s first and second table), and frequency(frequency of tabulation overflow check).
 min_nbor_dist:
 type:
float
argument path:model/compress[se_e2_a]/min_nbor_dist
The nearest distance between neighbor atoms saved in the frozen model.
 learning_rate:
 type:
dict
argument path:learning_rate
The definitio of learning rate
 scale_by_worker:
 type:
str
, optional, default:linear
argument path:learning_rate/scale_by_worker
When parallel training or batch size scaled, how to alter learning rate. Valid values are linear`(default), `sqrt or none.
Depending on the value of type, different sub args are accepted.
 type:
The type of the learning rate.
When type is set to
exp
: start_lr:
 type:
float
, optional, default:0.001
argument path:learning_rate[exp]/start_lr
The learning rate the start of the training.
 stop_lr:
 type:
float
, optional, default:1e08
argument path:learning_rate[exp]/stop_lr
The desired learning rate at the end of the training.
 decay_steps:
 type:
int
, optional, default:5000
argument path:learning_rate[exp]/decay_steps
The learning rate is decaying every this number of training steps.
 loss:
 type:
dict
, optionalargument path:loss
The definition of loss function. The loss type should be set to tensor, ener or left unset. .
Depending on the value of type, different sub args are accepted.
 type:
When type is set to
ener
: start_pref_e:
 type:
int
float
, optional, default:0.02
argument path:loss[ener]/start_pref_e
The prefactor of energy loss at the start of the training. Should be larger than or equal to 0. If set to nonezero value, the energy label should be provided by file energy.npy in each data system. If both start_pref_energy and limit_pref_energy are set to 0, then the energy will be ignored.
 limit_pref_e:
 type:
int
float
, optional, default:1.0
argument path:loss[ener]/limit_pref_e
The prefactor of energy loss at the limit of the training, Should be larger than or equal to 0. i.e. the training step goes to infinity.
 start_pref_f:
 type:
int
float
, optional, default:1000
argument path:loss[ener]/start_pref_f
The prefactor of force loss at the start of the training. Should be larger than or equal to 0. If set to nonezero value, the force label should be provided by file force.npy in each data system. If both start_pref_force and limit_pref_force are set to 0, then the force will be ignored.
 limit_pref_f:
 type:
int
float
, optional, default:1.0
argument path:loss[ener]/limit_pref_f
The prefactor of force loss at the limit of the training, Should be larger than or equal to 0. i.e. the training step goes to infinity.
 start_pref_v:
 type:
int
float
, optional, default:0.0
argument path:loss[ener]/start_pref_v
The prefactor of virial loss at the start of the training. Should be larger than or equal to 0. If set to nonezero value, the virial label should be provided by file virial.npy in each data system. If both start_pref_virial and limit_pref_virial are set to 0, then the virial will be ignored.
 limit_pref_v:
 type:
int
float
, optional, default:0.0
argument path:loss[ener]/limit_pref_v
The prefactor of virial loss at the limit of the training, Should be larger than or equal to 0. i.e. the training step goes to infinity.
 start_pref_ae:
 type:
int
float
, optional, default:0.0
argument path:loss[ener]/start_pref_ae
The prefactor of atom_ener loss at the start of the training. Should be larger than or equal to 0. If set to nonezero value, the atom_ener label should be provided by file atom_ener.npy in each data system. If both start_pref_atom_ener and limit_pref_atom_ener are set to 0, then the atom_ener will be ignored.
 limit_pref_ae:
 type:
int
float
, optional, default:0.0
argument path:loss[ener]/limit_pref_ae
The prefactor of atom_ener loss at the limit of the training, Should be larger than or equal to 0. i.e. the training step goes to infinity.
 start_pref_pf:
 type:
int
float
, optional, default:0.0
argument path:loss[ener]/start_pref_pf
The prefactor of atom_pref loss at the start of the training. Should be larger than or equal to 0. If set to nonezero value, the atom_pref label should be provided by file atom_pref.npy in each data system. If both start_pref_atom_pref and limit_pref_atom_pref are set to 0, then the atom_pref will be ignored.
 limit_pref_pf:
 type:
int
float
, optional, default:0.0
argument path:loss[ener]/limit_pref_pf
The prefactor of atom_pref loss at the limit of the training, Should be larger than or equal to 0. i.e. the training step goes to infinity.
 relative_f:
 type:
NoneType
float
, optionalargument path:loss[ener]/relative_f
If provided, relative force error will be used in the loss. The difference of force will be normalized by the magnitude of the force in the label with a shift given by relative_f, i.e. DF_i / (  F  + relative_f ) with DF denoting the difference between prediction and label and  F  denoting the L2 norm of the label.
 enable_atom_ener_coeff:
 type:
bool
, optional, default:False
argument path:loss[ener]/enable_atom_ener_coeff
If true, the energy will be computed as sum_i c_i E_i. c_i should be provided by file atom_ener_coeff.npy in each data system, otherwise it’s 1.
When type is set to
tensor
: pref:
 type:
int
float
argument path:loss[tensor]/pref
The prefactor of the weight of global loss. It should be larger than or equal to 0. If controls the weight of loss corresponding to global label, i.e. ‘polarizability.npy` or dipole.npy, whose shape should be #frames x [9 or 3]. If it’s larger than 0.0, this npy should be included.
 pref_atomic:
 type:
int
float
argument path:loss[tensor]/pref_atomic
The prefactor of the weight of atomic loss. It should be larger than or equal to 0. If controls the weight of loss corresponding to atomic label, i.e. atomic_polarizability.npy or atomic_dipole.npy, whose shape should be #frames x ([9 or 3] x #selected atoms). If it’s larger than 0.0, this npy should be included. Both pref and pref_atomic should be provided, and either can be set to 0.0.
 training:
 type:
dict
argument path:training
The training options.
 training_data:
 type:
dict
argument path:training/training_data
Configurations of training data.
 systems:
 type:
list
str
argument path:training/training_data/systems
The data systems for training. This key can be provided with a list that specifies the systems, or be provided with a string by which the prefix of all systems are given and the list of the systems is automatically generated.
 set_prefix:
 type:
str
, optional, default:set
argument path:training/training_data/set_prefix
The prefix of the sets in the systems.
 batch_size:
 type:
list
int
str
, optional, default:auto
argument path:training/training_data/batch_size
This key can be
list: the length of which is the same as the systems. The batch size of each system is given by the elements of the list.
int: all systems use the same batch size.
string “auto”: automatically determines the batch size so that the batch_size times the number of atoms in the system is no less than 32.
string “auto:N”: automatically determines the batch size so that the batch_size times the number of atoms in the system is no less than N.
 auto_prob:
 type:
str
, optional, default:prob_sys_size
, alias: auto_prob_styleargument path:training/training_data/auto_prob
Determine the probability of systems automatically. The method is assigned by this key and can be
“prob_uniform” : the probability all the systems are equal, namely 1.0/self.get_nsystems()
“prob_sys_size” : the probability of a system is proportional to the number of batches in the system
“prob_sys_size;stt_idx:end_idx:weight;stt_idx:end_idx:weight;…” : the list of systems is devided into blocks. A block is specified by stt_idx:end_idx:weight, where stt_idx is the starting index of the system, end_idx is then ending (not including) index of the system, the probabilities of the systems in this block sums up to weight, and the relatively probabilities within this block is proportional to the number of batches in the system.
 sys_probs:
 type:
list
NoneType
, optional, default:None
, alias: sys_weightsargument path:training/training_data/sys_probs
A list of float if specified. Should be of the same length as systems, specifying the probability of each system.
 validation_data:
 type:
NoneType
dict
, optional, default:None
argument path:training/validation_data
Configurations of validation data. Similar to that of training data, except that a numb_btch argument may be configured
 systems:
 type:
list
str
argument path:training/validation_data/systems
The data systems for validation. This key can be provided with a list that specifies the systems, or be provided with a string by which the prefix of all systems are given and the list of the systems is automatically generated.
 set_prefix:
 type:
str
, optional, default:set
argument path:training/validation_data/set_prefix
The prefix of the sets in the systems.
 batch_size:
 type:
list
int
str
, optional, default:auto
argument path:training/validation_data/batch_size
This key can be
list: the length of which is the same as the systems. The batch size of each system is given by the elements of the list.
int: all systems use the same batch size.
string “auto”: automatically determines the batch size so that the batch_size times the number of atoms in the system is no less than 32.
string “auto:N”: automatically determines the batch size so that the batch_size times the number of atoms in the system is no less than N.
 auto_prob:
 type:
str
, optional, default:prob_sys_size
, alias: auto_prob_styleargument path:training/validation_data/auto_prob
Determine the probability of systems automatically. The method is assigned by this key and can be
“prob_uniform” : the probability all the systems are equal, namely 1.0/self.get_nsystems()
“prob_sys_size” : the probability of a system is proportional to the number of batches in the system
“prob_sys_size;stt_idx:end_idx:weight;stt_idx:end_idx:weight;…” : the list of systems is devided into blocks. A block is specified by stt_idx:end_idx:weight, where stt_idx is the starting index of the system, end_idx is then ending (not including) index of the system, the probabilities of the systems in this block sums up to weight, and the relatively probabilities within this block is proportional to the number of batches in the system.
 sys_probs:
 type:
list
NoneType
, optional, default:None
, alias: sys_weightsargument path:training/validation_data/sys_probs
A list of float if specified. Should be of the same length as systems, specifying the probability of each system.
 numb_btch:
 type:
int
, optional, default:1
, alias: numb_batchargument path:training/validation_data/numb_btch
An integer that specifies the number of systems to be sampled for each validation period.
 mixed_precision:
 type:
dict
, optionalargument path:training/mixed_precision
Configurations of mixed precision.
 output_prec:
 type:
str
, optional, default:float32
argument path:training/mixed_precision/output_prec
The precision for mixed precision params. ” “The trainable variables precision during the mixed precision training process, ” “supported options are float32 only currently.
 compute_prec:
 type:
str
argument path:training/mixed_precision/compute_prec
The precision for mixed precision compute. ” “The compute precision during the mixed precision training process, “” “supported options are float16 only currently.
 numb_steps:
 type:
int
, alias: stop_batchargument path:training/numb_steps
Number of training batch. Each training uses one batch of data.
 seed:
 type:
int
NoneType
, optionalargument path:training/seed
The random seed for getting frames from the training data set.
 disp_file:
 type:
str
, optional, default:lcurve.out
argument path:training/disp_file
The file for printing learning curve.
 disp_freq:
 type:
int
, optional, default:1000
argument path:training/disp_freq
The frequency of printing learning curve.
 save_freq:
 type:
int
, optional, default:1000
argument path:training/save_freq
The frequency of saving check point.
 save_ckpt:
 type:
str
, optional, default:model.ckpt
argument path:training/save_ckpt
The file name of saving check point.
 disp_training:
 type:
bool
, optional, default:True
argument path:training/disp_training
Displaying verbose information during training.
 time_training:
 type:
bool
, optional, default:True
argument path:training/time_training
Timing durining training.
 profiling:
 type:
bool
, optional, default:False
argument path:training/profiling
Profiling during training.
 profiling_file:
 type:
str
, optional, default:timeline.json
argument path:training/profiling_file
Output file for profiling.
 enable_profiler:
 type:
bool
, optional, default:False
argument path:training/enable_profiler
Enable TensorFlow Profiler (available in TensorFlow 2.3) to analyze performance. The log will be saved to tensorboard_log_dir.
 tensorboard:
 type:
bool
, optional, default:False
argument path:training/tensorboard
Enable tensorboard
 tensorboard_log_dir:
 type:
str
, optional, default:log
argument path:training/tensorboard_log_dir
The log directory of tensorboard outputs
 tensorboard_freq:
 type:
int
, optional, default:1
argument path:training/tensorboard_freq
The frequency of writing tensorboard events.
 nvnmd:
 type:
dict
, optionalargument path:nvnmd
The nvnmd options.
 net_size:
 type:
int
argument path:nvnmd/net_size
configuration the number of nodes of fitting_net, just can be set as 128
 map_file:
 type:
str
argument path:nvnmd/map_file
A file containing the mapping tables to replace the calculation of embedding nets
 config_file:
 type:
str
argument path:nvnmd/config_file
A file containing the parameters about how to implement the model in certain hardware
 weight_file:
 type:
str
argument path:nvnmd/weight_file
a *.npy file containing the weights of the model
 enable:
 type:
bool
argument path:nvnmd/enable
enable the nvnmd training
 restore_descriptor:
 type:
bool
argument path:nvnmd/restore_descriptor
enable to restore the parameter of embedding_net from weight.npy
 restore_fitting_net:
 type:
bool
argument path:nvnmd/restore_fitting_net
enable to restore the parameter of fitting_net from weight.npy
 quantize_descriptor:
 type:
bool
argument path:nvnmd/quantize_descriptor
enable the quantizatioin of descriptor
 quantize_fitting_net:
 type:
bool
argument path:nvnmd/quantize_fitting_net
enable the quantizatioin of fitting_net
Parallel training
Currently, parallel training is enabled in a sychoronized way with help of Horovod. Depend on the number of training processes (according to MPI context) and number of GPU cards avaliable, DeePMDkit will decide whether to launch the training in parallel (distributed) mode or in serial mode. Therefore, no additional options is specified in your JSON/YAML input file.
Tuning learning rate
Horovod works in the dataparallel mode, resulting in a larger global batch size. For example, the real batch size is 8 when batch_size is set to 2 in the input file and you launch 4 workers. Thus, learning_rate is automatically scaled by the number of workers for better convergence. Technical details of such heuristic rule are discussed at Accurate, Large Minibatch SGD: Training ImageNet in 1 Hour.
The number of decay steps required to achieve same accuracy can decrease by the number of cards (e.g., 1/2 of steps in the above case), but needs to be scaled manually in the input file.
In some cases, it won’t work well when scale learning rate by worker count in a linear
way. Then you can try sqrt
or none
by setting argument scale_by_worker like below.
"learning_rate" :{
"scale_by_worker": "none",
"type": "exp"
}
Scaling test
Testing examples/water/se_e2_a
on a 8GPU host, linear acceleration can be observed with increasing number of cards.
Num of GPU cards  Seconds every 100 samples  Samples per second  Speed up 

1  1.4515  68.89  1.00 
2  1.5962  62.65*2  1.82 
4  1.7635  56.71*4  3.29 
8  1.7267  57.91*8  6.72 
How to use
Training workers can be launched with horovodrun
. The following command launches 4 processes on the same host:
CUDA_VISIBLE_DEVICES=4,5,6,7 horovodrun np 4 \
dp train mpilog=workers input.json
Need to mention, environment variable CUDA_VISIBLE_DEVICES
must be set to control parallelism on the occupied host where one process is bound to one GPU card.
Note that OMP_NUM_THREADS
, TF_INTRA_OP_PARALLELISM_THREADS
, and TF_INTER_OP_PARALLELISM_THREADS
should be carefully adjusted to achieve the best performance.
When using MPI with Horovod, horovodrun
is a simple wrapper around mpirun
. In the case where finegrained control over options passed to mpirun
, mpirun
can be invoked directly, and it will be detected automatically by Horovod, e.g.,
CUDA_VISIBLE_DEVICES=4,5,6,7 mpirun l launcher=fork hosts=localhost np 4 \
dp train mpilog=workers input.json
this is sometimes neccessary on HPC environment.
Whether distributed workers are initiated can be observed at the “Summary of the training” section in the log (world size
> 1, and distributed
).
[0] DEEPMD INFO Summary of the training
[0] DEEPMD INFO distributed
[0] DEEPMD INFO world size: 4
[0] DEEPMD INFO my rank: 0
[0] DEEPMD INFO node list: ['exp1357']
[0] DEEPMD INFO running on: exp1357
[0] DEEPMD INFO computing device: gpu:0
[0] DEEPMD INFO CUDA_VISIBLE_DEVICES: 0,1,2,3
[0] DEEPMD INFO Count of visible GPU: 4
[0] DEEPMD INFO num_intra_threads: 0
[0] DEEPMD INFO num_inter_threads: 0
[0] DEEPMD INFO 
Logging
What’s more, 2 commandline arguments are defined to control the logging behvaior when performing parallel training with MPI.
optional arguments:
l LOG_PATH, logpath LOG_PATH
set log file to log messages to disk, if not
specified, the logs will only be output to console
(default: None)
m {master,collect,workers}, mpilog {master,collect,workers}
Set the manner of logging when running with MPI.
'master' logs only on main process, 'collect'
broadcasts logs from workers to master and 'workers'
means each process will output its own log (default:
master)
TensorBoard Usage
TensorBoard provides the visualization and tooling needed for machine learning experimentation. A full instruction of tensorboard can be found here.
Highlighted features
DeePMDkit can now use most of the interesting features enabled by tensorboard!
Tracking and visualizing metrics, such as l2_loss, l2_energy_loss and l2_force_loss
Visualizing the model graph (ops and layers)
Viewing histograms of weights, biases, or other tensors as they change over time.
Viewing summaries of trainable viriables
How to use Tensorboard with DeePMDkit
Before running TensorBoard, make sure you have generated summary data in a log directory by modifying the the input script, set tensorboard to true in training subsection will enable the tensorboard data analysis. eg. water_se_a.json.
"training" : {
"systems": ["../data/"],
"set_prefix": "set",
"stop_batch": 1000000,
"batch_size": 1,
"seed": 1,
"_comment": " display and restart",
"_comment": " frequencies counted in batch",
"disp_file": "lcurve.out",
"disp_freq": 100,
"numb_test": 10,
"save_freq": 1000,
"save_ckpt": "model.ckpt",
"disp_training":true,
"time_training":true,
"tensorboard": true,
"tensorboard_log_dir":"log",
"tensorboard_freq": 1000,
"profiling": false,
"profiling_file":"timeline.json",
"_comment": "that's all"
}
Once you have event files, run TensorBoard and provide the log directory. This should print that TensorBoard has started. Next, connect to http://tensorboard_server_ip:6006.
TensorBoard requires a logdir to read logs from. For info on configuring TensorBoard, run tensorboard –help. One can easily change the log name with “tensorboard_log_dir” and the sampling frequency with “tensorboard_freq”.
tensorboard logdir path/to/logs
Examples
Tracking and visualizing loss metrics(red:train, blue:test)
Visualizing deepmdkit model graph
Viewing histograms of weights, biases, or other tensors as they change over time
Viewing summaries of trainable variables
Attention
Allowing the tensorboard analysis will takes extra execution time.(eg, 15% increasing @Nvidia GTX 1080Ti double precision with default water sample)
TensorBoard can be used in Google Chrome or Firefox. Other browsers might work, but there may be bugs or performance issues.
Known limitations of using GPUs
If you use deepmdkit in a GPU environment, the acceptable value range of some variables are additionally restricted compared to the CPU environment due to the software’s GPU implementations:
The number of atom type of a given system must be less than 128.
The maximum distance between an atom and it’s neighbors must be less than 128. It can be controlled by setting the rcut value of training parameters.
Theoretically, the maximum number of atoms that a single GPU can accept is about 10,000,000. However, this value is actually limited by the GPU memory size currently, usually within 1000,000 atoms even at the model compression mode.
The total sel value of training parameters(in model/descriptor section) must be less than 4096.
The size of the last layer of embedding net must be less than 1024 during the model compression process.
Freeze and Compress
Freeze a model
The trained neural network is extracted from a checkpoint and dumped into a database. This process is called “freezing” a model. The idea and part of our code are from Morgan. To freeze a model, typically one does
$ dp freeze o graph.pb
in the folder where the model is trained. The output database is called graph.pb
.
Compress a model
Once the frozen model is obtained from deepmdkit, we can get the neural network structure and its parameters (weights, biases, etc.) from the trained model, and compress it in the following way:
dp compress i graph.pb o graphcompress.pb
where i
gives the original frozen model, o
gives the compressed model. Several other command line options can be passed to dp compress
, which can be checked with
$ dp compress help
An explanation will be provided
usage: dp compress [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[m {master,collect,workers}] [i INPUT] [o OUTPUT]
[s STEP] [e EXTRAPOLATE] [f FREQUENCY]
[c CHECKPOINT_FOLDER]
optional arguments:
h, help show this help message and exit
v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}, loglevel {DEBUG,3,INFO,2,WARNING,1,ERROR,0}
set verbosity level by string or number, 0=ERROR,
1=WARNING, 2=INFO and 3=DEBUG (default: INFO)
l LOG_PATH, logpath LOG_PATH
set log file to log messages to disk, if not
specified, the logs will only be output to console
(default: None)
m {master,collect,workers}, mpilog {master,collect,workers}
Set the manner of logging when running with MPI.
'master' logs only on main process, 'collect'
broadcasts logs from workers to master and 'workers'
means each process will output its own log (default:
master)
i INPUT, input INPUT
The original frozen model, which will be compressed by
the code (default: frozen_model.pb)
o OUTPUT, output OUTPUT
The compressed model (default:
frozen_model_compressed.pb)
s STEP, step STEP Model compression uses fifthorder polynomials to
interpolate the embeddingnet. It introduces two
tables with different step size to store the
parameters of the polynomials. The first table covers
the range of the training data, while the second table
is an extrapolation of the training data. The domain
of each table is uniformly divided by a given step
size. And the step(parameter) denotes the step size of
the first table and the second table will use 10 *
step as it's step size to save the memory. Usually the
value ranges from 0.1 to 0.001. Smaller step means
higher accuracy and bigger model size (default: 0.01)
e EXTRAPOLATE, extrapolate EXTRAPOLATE
The domain range of the first table is automatically
detected by the code: [d_low, d_up]. While the second
table ranges from the first table's upper
boundary(d_up) to the extrapolate(parameter) * d_up:
[d_up, extrapolate * d_up] (default: 5)
f FREQUENCY, frequency FREQUENCY
The frequency of tabulation overflow check(Whether the
input environment matrix overflow the first or second
table range). By default do not check the overflow
(default: 1)
c CHECKPOINT_FOLDER, checkpointfolder CHECKPOINT_FOLDER
path to checkpoint folder (default: .)
t TRAINING_SCRIPT, trainingscript TRAINING_SCRIPT
The training script of the input frozen model
(default: None)
Parameter explanation
Model compression, which including tabulating the embeddingnet. The table is composed of fifthorder polynomial coefficients and is assembled from two subtables. For model descriptor with se_e2_a
type, the first subtable takes the stride(parameter) as it’s uniform stride, while the second subtable takes 10 * stride as it’s uniform stride; For model descriptor with se_e3
type, the first subtable takes 10 * stride as it’s uniform stride, while the second subtable takes 100 * stride as it’s uniform stride. The range of the first table is automatically detected by deepmdkit, while the second table ranges from the first table’s upper boundary(upper) to the extrapolate(parameter) * upper. Finally, we added a check frequency parameter. It indicates how often the program checks for overflow(if the input environment matrix overflow the first or second table range) during the MD inference.
Justification of model compression
Model compression, with little loss of accuracy, can greatly speed up MD inference time. According to different simulation systems and training parameters, the speedup can reach more than 10 times at both CPU and GPU devices. At the same time, model compression can greatly change the memory usage, reducing as much as 20 times under the same hardware conditions.
Acceptable original model version
The model compression interface requires the version of deepmdkit used in original model generation should be 2.0.0alpha.0
or above. If one has a frozen 1.2 or 1.3 model, one can upgrade it through the dp convertfrom
interface.(eg: dp convertfrom 1.2/1.3 i old_frozen_model.pb o new_frozen_model.pb
)
Acceptable descriptor type
Descriptors with se_e2_a
,se_e3
, se_e2_r
type are supported by the model compression feature. Hybrid mixed with above descriptors is also supported.
Available activation functions for descriptor:
tanh
gelu
relu
relu6
softplus
sigmoid
Test
Test a model
The frozen model can be used in many ways. The most straightforward test can be performed using dp test
. A typical usage of dp test
is
dp test m graph.pb s /path/to/system n 30
where m
gives the tested model, s
the path to the tested system and n
the number of tested frames. Several other command line options can be passed to dp test
, which can be checked with
$ dp test help
An explanation will be provided
usage: dp test [h] [m MODEL] [s SYSTEM] [S SET_PREFIX] [n NUMB_TEST]
[r RAND_SEED] [shuffletest] [d DETAIL_FILE]
optional arguments:
h, help show this help message and exit
m MODEL, model MODEL
Frozen model file to import
s SYSTEM, system SYSTEM
The system dir
S SET_PREFIX, setprefix SET_PREFIX
The set prefix
n NUMB_TEST, numbtest NUMB_TEST
The number of data for test
r RAND_SEED, randseed RAND_SEED
The random seed
shuffletest Shuffle test data
d DETAIL_FILE, detailfile DETAIL_FILE
The file containing details of energy force and virial
accuracy
Calculate Model Deviation
One can also use a subcommand to calculate deviation of prediced forces or virials for a bunch of models in the following way:
dp modeldevi m graph.000.pb graph.001.pb graph.002.pb graph.003.pb s ./data o model_devi.out
where m
specifies graph files to be calculated, s
gives the data to be evaluated, o
the file to which model deviation results is dumped. Here is more information on this subcommand:
usage: dp modeldevi [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}]
[l LOG_PATH] [m MODELS [MODELS ...]] [s SYSTEM]
[S SET_PREFIX] [o OUTPUT] [f FREQUENCY] [i ITEMS]
optional arguments:
h, help show this help message and exit
v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}, loglevel {DEBUG,3,INFO,2,WARNING,1,ERROR,0}
set verbosity level by string or number, 0=ERROR,
1=WARNING, 2=INFO and 3=DEBUG (default: INFO)
l LOG_PATH, logpath LOG_PATH
set log file to log messages to disk, if not
specified, the logs will only be output to console
(default: None)
m MODELS [MODELS ...], models MODELS [MODELS ...]
Frozen models file to import (default:
['graph.000.pb', 'graph.001.pb', 'graph.002.pb',
'graph.003.pb'])
s SYSTEM, system SYSTEM
The system directory, not support recursive detection.
(default: .)
S SET_PREFIX, setprefix SET_PREFIX
The set prefix (default: set)
o OUTPUT, output OUTPUT
The output file for results of model deviation
(default: model_devi.out)
f FREQUENCY, frequency FREQUENCY
The trajectory frequency of the system (default: 1)
For more details with respect to definition of model deviation and its application, please refer to Yuzhi Zhang, Haidi Wang, Weijie Chen, Jinzhe Zeng, Linfeng Zhang, Han Wang, and Weinan E, DPGEN: A concurrent learning platform for the generation of reliable deep learning based potential energy models, Computer Physics Communications, 2020, 253, 107206.
Inference
Note that the model for inference is required to be compatible with the DeePMDkit package. See Model compatibility for details.
Python interface
One may use the python interface of DeePMDkit for model inference, an example is given as follows
from deepmd.infer import DeepPot
import numpy as np
dp = DeepPot('graph.pb')
coord = np.array([[1,0,0], [0,0,1.5], [1,0,3]]).reshape([1, 1])
cell = np.diag(10 * np.ones(3)).reshape([1, 1])
atype = [1,0,1]
e, f, v = dp.eval(coord, cell, atype)
where e
, f
and v
are predicted energy, force and virial of the system, respectively.
Furthermore, one can use the python interface to calulate model deviation.
from deepmd.infer import calc_model_devi
from deepmd.infer import DeepPot as DP
import numpy as np
coord = np.array([[1,0,0], [0,0,1.5], [1,0,3]]).reshape([1, 1])
cell = np.diag(10 * np.ones(3)).reshape([1, 1])
atype = [1,0,1]
graphs = [DP("graph.000.pb"), DP("graph.001.pb")]
model_devi = calc_model_devi(coord, cell, atype, graphs)
C++ interface
The C++ interface of DeePMDkit is also avaiable for model interface, which is considered faster than Python interface. An example infer_water.cpp
is given below:
#include "deepmd/DeepPot.h"
int main(){
deepmd::DeepPot dp ("graph.pb");
std::vector<double > coord = {1., 0., 0., 0., 0., 1.5, 1. ,0. ,3.};
std::vector<double > cell = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
std::vector<int > atype = {1, 0, 1};
double e;
std::vector<double > f, v;
dp.compute (e, f, v, coord, atype, cell);
}
where e
, f
and v
are predicted energy, force and virial of the system, respectively.
You can compile infer_water.cpp
using gcc
:
gcc infer_water.cpp D HIGH_PREC L $deepmd_root/lib L $tensorflow_root/lib I $deepmd_root/include Wl,noasneeded ldeepmd_cc lstdc++ ltensorflow_cc Wl,rpath=$deepmd_root/lib Wl,rpath=$tensorflow_root/lib o infer_water
and then run the program:
./infer_water
Command line interface
DeePMDkit: A deep learning package for manybody potential energy representation and molecular dynamics
usage: dp [h] [version]
{config,transfer,train,freeze,test,compress,doctraininput,modeldevi,convertfrom,neighborstat,trainnvnmd}
...
Named Arguments
 version
show program’s version number and exit
Valid subcommands
 command
Possible choices: config, transfer, train, freeze, test, compress, doctraininput, modeldevi, convertfrom, neighborstat, trainnvnmd
Subcommands:
config
fast configuration of parameter file for smooth model
dp config [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[o OUTPUT]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 o, output
the output json file
Default: “input.json”
transfer
pass parameters to another model
dp transfer [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[r RAW_MODEL] [O OLD_MODEL] [o OUTPUT]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 r, rawmodel
the model receiving parameters
Default: “raw_frozen_model.pb”
 O, oldmodel
the model providing parameters
Default: “old_frozen_model.pb”
 o, output
the model after passing parameters
Default: “frozen_model.pb”
train
train a model
dp train [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[m {master,collect,workers}] [i INIT_MODEL] [r RESTART]
[o OUTPUT] [f INIT_FRZ_MODEL] [skipneighborstat]
INPUT
Positional Arguments
 INPUT
the input parameter file in json or yaml format
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 m, mpilog
Possible choices: master, collect, workers
Set the manner of logging when running with MPI. ‘master’ logs only on main process, ‘collect’ broadcasts logs from workers to master and ‘workers’ means each process will output its own log
Default: “master”
 i, initmodel
Initialize the model by the provided checkpoint.
 r, restart
Restart the training from the provided checkpoint.
 o, output
The output file of the parameters used in training.
Default: “out.json”
 f, initfrzmodel
Initialize the training from the frozen model.
 skipneighborstat
Skip calculating neighbor statistics. Sel checking, automatic sel, and model compression will be disabled.
Default: False
freeze
freeze the model
dp freeze [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[c CHECKPOINT_FOLDER] [o OUTPUT] [n NODE_NAMES] [w NVNMD_WEIGHT]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 c, checkpointfolder
path to checkpoint folder
Default: “.”
 o, output
name of graph, will output to the checkpoint folder
Default: “frozen_model.pb”
 n, nodenames
the frozen nodes, if not set, determined from the model type
 w, nvnmdweight
the name of weight file (.npy), if set, save the model’s weight into the file
test
test the model
dp test [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH] [m MODEL]
[s SYSTEM] [S SET_PREFIX] [n NUMB_TEST] [r RAND_SEED]
[shuffletest] [d DETAIL_FILE] [a]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 m, model
Frozen model file to import
Default: “frozen_model.pb”
 s, system
The system dir. Recursively detect systems in this directory
Default: “.”
 S, setprefix
The set prefix
Default: “set”
 n, numbtest
The number of data for test
Default: 100
 r, randseed
The random seed
 shuffletest
Shuffle test data
Default: False
 d, detailfile
File where details of energy force and virial accuracy will be written
 a, atomic
Test the accuracy of atomic label, i.e. energy / tensor (dipole, polar)
Default: False
compress
compress a model
dp compress [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[m {master,collect,workers}] [i INPUT] [o OUTPUT] [s STEP]
[e EXTRAPOLATE] [f FREQUENCY] [c CHECKPOINT_FOLDER]
[t TRAINING_SCRIPT]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 m, mpilog
Possible choices: master, collect, workers
Set the manner of logging when running with MPI. ‘master’ logs only on main process, ‘collect’ broadcasts logs from workers to master and ‘workers’ means each process will output its own log
Default: “master”
 i, input
The original frozen model, which will be compressed by the code
Default: “frozen_model.pb”
 o, output
The compressed model
Default: “frozen_model_compressed.pb”
 s, step
Model compression uses fifthorder polynomials to interpolate the embeddingnet. It introduces two tables with different step size to store the parameters of the polynomials. The first table covers the range of the training data, while the second table is an extrapolation of the training data. The domain of each table is uniformly divided by a given step size. And the step(parameter) denotes the step size of the first table and the second table will use 10 * step as it’s step size to save the memory. Usually the value ranges from 0.1 to 0.001. Smaller step means higher accuracy and bigger model size
Default: 0.01
 e, extrapolate
The domain range of the first table is automatically detected by the code: [d_low, d_up]. While the second table ranges from the first table’s upper boundary(d_up) to the extrapolate(parameter) * d_up: [d_up, extrapolate * d_up]
Default: 5
 f, frequency
The frequency of tabulation overflow check(Whether the input environment matrix overflow the first or second table range). By default do not check the overflow
Default: 1
 c, checkpointfolder
path to checkpoint folder
Default: “modelcompression”
 t, trainingscript
The training script of the input frozen model
doctraininput
print the documentation (in rst format) of input training parameters.
dp doctraininput [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[outtype OUT_TYPE]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 outtype
The output type
Default: “rst”
modeldevi
calculate model deviation
dp modeldevi [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[m MODELS [MODELS ...]] [s SYSTEM] [S SET_PREFIX] [o OUTPUT]
[f FREQUENCY]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 m, models
Frozen models file to import
Default: [‘graph.000.pb’, ‘graph.001.pb’, ‘graph.002.pb’, ‘graph.003.pb’]
 s, system
The system directory. Recursively detect systems in this directory.
Default: “.”
 S, setprefix
The set prefix
Default: “set”
 o, output
The output file for results of model deviation
Default: “model_devi.out”
 f, frequency
The trajectory frequency of the system
Default: 1
convertfrom
convert lower model version to supported version
dp convertfrom [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[i INPUT_MODEL] [o OUTPUT_MODEL]
{0.12,1.0,1.1,1.2,1.3,2.0}
Positional Arguments
 FROM
Possible choices: 0.12, 1.0, 1.1, 1.2, 1.3, 2.0
The original model compatibility
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 i, inputmodel
the input model
Default: “frozen_model.pb”
 o, outputmodel
the output model
Default: “convert_out.pb”
neighborstat
Calculate neighbor statistics
dp neighborstat [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[s SYSTEM] r RCUT t TYPE_MAP [TYPE_MAP ...]
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 s, system
The system dir. Recursively detect systems in this directory
Default: “.”
 r, rcut
cutoff radius
 t, typemap
type map
trainnvnmd
train nvnmd model
dp trainnvnmd [h] [v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [l LOG_PATH]
[s {s1,s2}]
INPUT
Positional Arguments
 INPUT
the input parameter file in json format
Named Arguments
 v, loglevel
Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0
set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG
Default: “INFO”
 l, logpath
set log file to log messages to disk, if not specified, the logs will only be output to console
 s, step
Possible choices: s1, s2
steps to train model of NVNMD: s1 (train CNN), s2 (train QNN)
Default: “s1”
Integrate with thirdparty packages
Note that the model for inference is required to be compatible with the DeePMDkit package. See Model compatibility for details.
Use deep potential with ASE
Deep potential can be set up as a calculator with ASE to obtain potential energies and forces.
from ase import Atoms
from deepmd.calculator import DP
water = Atoms('H2O',
positions=[(0.7601, 1.9270, 1),
(1.9575, 1, 1),
(1., 1., 1.)],
cell=[100, 100, 100],
calculator=DP(model="frozen_model.pb"))
print(water.get_potential_energy())
print(water.get_forces())
Optimization is also available:
from ase.optimize import BFGS
dyn = BFGS(water)
dyn.run(fmax=1e6)
print(water.get_positions())
Run MD with LAMMPS
Running an MD simulation with LAMMPS is simpler. In the LAMMPS input file, one needs to specify the pair style as follows
pair_style deepmd graph.pb
pair_coeff * *
where graph.pb
is the file name of the frozen model. It should be noted that LAMMPS counts atom types starting from 1, therefore, all LAMMPS atom type will be firstly subtracted by 1, and then passed into the DeePMDkit engine to compute the interactions.
LAMMPS commands
Enable DeePMDkit plugin (plugin mode)
If you are using the plugin mode, enable DeePMDkit package in LAMMPS with plugin
command:
plugin load libdeepmd_lmp.so
After LAMMPS version patch_24Mar2022
, another way to load plugins is to set the environmental variable LAMMPS_PLUGIN_PATH
:
LAMMPS_PLUGIN_PATH=$deepmd_root/lib/deepmd_lmp
where $deepmd_root
is the directory to install C++ interface.
The builtin mode doesn’t need this step.
pair_style deepmd
The DeePMDkit package provides the pair_style deepmd
pair_style deepmd models ... keyword value ...
deepmd = style of this pair_style
models = frozen model(s) to compute the interaction. If multiple models are provided, then only the first model serves to provide energy and force prediction for each timestep of molecular dynamics, and the model deviation will be computed among all models every
out_freq
timesteps.keyword = out_file or out_freq or fparam or atomic or relative
out_file value = filename filename = The file name for the model deviation output. Default is model_devi.out out_freq value = freq freq = Frequency for the model deviation output. Default is 100. fparam value = parameters parameters = one or more frame parameters required for model evaluation. atomic = no value is required. If this keyword is set, the model deviation of each atom will be output. relative value = level level = The level parameter for computing the relative model deviation
Examples
pair_style deepmd graph.pb
pair_style deepmd graph.pb fparam 1.2
pair_style deepmd graph_0.pb graph_1.pb graph_2.pb out_file md.out out_freq 10 atomic relative 1.0
Description
Evaluate the interaction of the system by using Deep Potential or Deep Potential Smooth Edition. It is noticed that deep potential is not a “pairwise” interaction, but a multibody interaction.
This pair style takes the deep potential defined in a model file that usually has the .pb extension. The model can be trained and frozen by package DeePMDkit.
The model deviation evalulate the consistency of the force predictions from multiple models. By default, only the maximal, minimal and averge model deviations are output. If the key atomic
is set, then the model deviation of force prediction of each atom will be output.
By default, the model deviation is output in absolute value. If the keyword relative
is set, then the relative model deviation will be output. The relative model deviation of the force on atom \(i\) is defined by
where \(D_{f_i}\) is the absolute model deviation of the force on atom \(i\), \(f_i\) is the norm of the the force and \(l\) is provided as the parameter of the keyword relative
.
Restrictions
The
deepmd
pair style is provided in the USERDEEPMD package, which is compiled from the DeePMDkit, visit the DeePMDkit website for more information.
Compute tensorial properties
The DeePMDkit package provide the compute deeptensor/atom
for computing atomic tensorial properties.
compute ID groupID deeptensor/atom model_file
ID: userassigned name of the computation
groupID: ID of the group of atoms to compute
deeptensor/atom: the style of this compute
model_file: the name of the binary model file.
Examples
compute dipole all deeptensor/atom dipole.pb
The result of the compute can be dump to trajctory file by
dump 1 all custom 100 water.dump id type c_dipole[1] c_dipole[2] c_dipole[3]
Restrictions
The
deeptensor/atom
compute is provided in the USERDEEPMD package, which is compiled from the DeePMDkit, visit the DeePMDkit website for more information.
Longrange interaction
The reciprocal space part of the longrange interaction can be calculated by LAMMPS command kspace_style
. To use it with DeePMDkit, one writes
pair_style deepmd graph.pb
pair_coeff
kspace_style pppm 1.0e5
kspace_modify gewald 0.45
Please notice that the DeePMD does nothing to the direct space part of the electrostatic interaction, because this part is assumed to be fitted in the DeePMD model (the direct space cutoff is thus the cutoff of the DeePMD model). The splitting parameter gewald
is modified by the kspace_modify
command.
Use of the centroid/stress/atom to get the full 3x3 “atomicvirial”
The DeePMDkit allows also the computation of peratom stress tensor defined as:
Where \(\mathbf{r}_n\) is the atomic position of nth atom, \(\mathbf{v}_n\) velocity of atom and \(\frac{de_m}{d\mathbf{r}_n}\) the derivative of the atomic energy.
In LAMMPS one can get the peratom stress using the command centroid/stress/atom
:
compute ID groupID centroid/stress/atom NULL virial
see LAMMPS doc page for more detailes on the meaning of the keywords.
Examples
In order of computing the 9component peratom stress
compute stress all centroid/stress/atom NULL virial
Thus c_stress
is an array with 9 component in the order xx,yy,zz,xy,xz,yz,yx,zx,zy
.
If you use this feature please cite D. Tisi, L. Zhang, R. Bertossa, H. Wang, R. Car, S. Baroni  arXiv preprint arXiv:2108.10850, 2021
Computation of heat flux
Using peratom stress tensor one can, for example, compute the heat flux defined as:
to compute the heat flux with LAMMPS:
compute ke_ID all ke/atom
compute pe_ID all pe/atom
compute stress_ID groupID centroid/stress/atom NULL virial
compute flux_ID all heat/flux ke_ID pe_ID stress_ID
Examples
compute ke all ke/atom
compute pe all pe/atom
compute stress all centroid/stress/atom NULL virial
compute flux all heat/flux ke pe stress
c_flux
is a global vector of length 6. The first three components are the \(x\), \(y\) and \(z\) components of the full heat flux vector. The others are the components of the socalled convective portion, see LAMMPS doc page for more detailes.
If you use these features please cite D. Tisi, L. Zhang, R. Bertossa, H. Wang, R. Car, S. Baroni  arXiv preprint arXiv:2108.10850, 2021
Run pathintegral MD with iPI
The iPI works in a clientserver model. The iPI provides the server for integrating the replica positions of atoms, while the DeePMDkit provides a client named dp_ipi
(or dp_ipi_low
for low precision) that computes the interactions (including energy, force and virial). The server and client communicates via the Unix domain socket or the Internet socket. Installation instructions of iPI can be found here. The client can be started by
ipi input.xml &
dp_ipi water.json
It is noted that multiple instances of the client is allow for computing, in parallel, the interactions of multiple replica of the pathintegral MD.
water.json
is the parameter file for the client dp_ipi
, and an example is provided:
{
"verbose": false,
"use_unix": true,
"port": 31415,
"host": "localhost",
"graph_file": "graph.pb",
"coord_file": "conf.xyz",
"atom_type" : {
"OW": 0,
"HW1": 1,
"HW2": 1
}
}
The option use_unix
is set to true
to activate the Unix domain socket, otherwise, the Internet socket is used.
The option port
should be the same as that in input.xml:
<port>31415</port>
The option graph_file
provides the file name of the frozen model.
The dp_ipi
gets the atom names from an XYZ file provided by coord_file
(meanwhile ignores all coordinates in it), and translates the names to atom types by rules provided by atom_type
.
Running MD with GROMACS
DP/MM Simulation
This part gives a simple tutorial on how to run a DP/MM simulation for methane in water, which means using DP for methane and TIP3P for water. All relevant files can be found in examples/methane
.
Topology Preparation
Similar to QM/MM simulation, the internal interactions (including bond, angle, dihedrals, LJ, Columb) of the region descibed by a neural network potential (NNP) have to be turned off. In GROMACS, bonded interactions can be turned off by modifying [ bonds ]
, [ angles ]
, [ dihedrals ]
and [ pairs ]
sections. And LJ and Columb interactions must be turned off by [ exclusions ]
section.
For example, if one wants to simulate ethane in water, using DeepPotential for methane and TIP3P for water, the topology of methane should be like the following (as presented in examples/methane/methane.itp
):
[ atomtypes ]
;name btype mass charge ptype sigma epsilon
c3 c3 0.0 0.0 A 0.339771 0.451035
hc hc 0.0 0.0 A 0.260018 0.087027
[ moleculetype ]
;name nrexcl
methane 3
[ atoms ]
; nr type resnr residue atom cgnr charge mass
1 c3 1 MOL C1 1 0.1068 12.010
2 hc 1 MOL H1 2 0.0267 1.008
3 hc 1 MOL H2 3 0.0267 1.008
4 hc 1 MOL H3 4 0.0267 1.008
5 hc 1 MOL H4 5 0.0267 1.008
[ bonds ]
; i j func b0 kb
1 2 5
1 3 5
1 4 5
1 5 5
[ exclusions ]
; ai aj1 aj2 aj3 aj4
1 2 3 4 5
2 1 3 4 5
3 1 2 4 5
4 1 2 3 5
5 1 2 3 4
For comparsion, the original topology file genearted by acpype
will be:
; methane_GMX.itp created by acpype (v: 20210205T22:15:50CET) on Wed Sep 8 01:21:53 2021
[ atomtypes ]
;name bond_type mass charge ptype sigma epsilon Amb
c3 c3 0.00000 0.00000 A 3.39771e01 4.51035e01 ; 1.91 0.1078
hc hc 0.00000 0.00000 A 2.60018e01 8.70272e02 ; 1.46 0.0208
[ moleculetype ]
;name nrexcl
methane 3
[ atoms ]
; nr type resi res atom cgnr charge mass ; qtot bond_type
1 c3 1 MOL C1 1 0.106800 12.01000 ; qtot 0.107
2 hc 1 MOL H1 2 0.026700 1.00800 ; qtot 0.080
3 hc 1 MOL H2 3 0.026700 1.00800 ; qtot 0.053
4 hc 1 MOL H3 4 0.026700 1.00800 ; qtot 0.027
5 hc 1 MOL H4 5 0.026700 1.00800 ; qtot 0.000
[ bonds ]
; ai aj funct r k
1 2 1 1.0970e01 3.1455e+05 ; C1  H1
1 3 1 1.0970e01 3.1455e+05 ; C1  H2
1 4 1 1.0970e01 3.1455e+05 ; C1  H3
1 5 1 1.0970e01 3.1455e+05 ; C1  H4
[ angles ]
; ai aj ak funct theta cth
2 1 3 1 1.0758e+02 3.2635e+02 ; H1  C1  H2
2 1 4 1 1.0758e+02 3.2635e+02 ; H1  C1  H3
2 1 5 1 1.0758e+02 3.2635e+02 ; H1  C1  H4
3 1 4 1 1.0758e+02 3.2635e+02 ; H2  C1  H3
3 1 5 1 1.0758e+02 3.2635e+02 ; H2  C1  H4
4 1 5 1 1.0758e+02 3.2635e+02 ; H3  C1  H4
DeepMD Settings
Before running simulation, we need to tell GROMACS to use DeepPotential by setting environment variable GMX_DEEPMD_INPUT_JSON
:
export GMX_DEEPMD_INPUT_JSON=input.json
Then, in your working directories, we have to write input.json
file:
{
"graph_file": "/path/to/graph.pb",
"type_file": "type.raw",
"index_file": "index.raw",
"lambda": 1.0,
"pbc": false
}
Here is an explanation for these settings:
graph_file
: The graph file (with suffix .pb) generated bydp freeze
commandtype_file
: File to specify DP atom types (in spacesepreated format). Here,type.raw
looks like
1 0 0 0 0
index_file
: File containing indices of DP atoms (in spaceseperated format), which should be in consistent with indices’ order in .gro file but starting from zero. Here,index.raw
looks like
0 1 2 3 4
lambda
: Optional, default 1.0. Used in alchemical calculations.pbc
: Optional, default true. If true, the GROMACS peroidic condition is passed to DeepMD.
Run Simulation
Finally, you can run GROMACS using gmx mdrun
as usual.
Allatom DP Simulation
This part gives an example on how to run a simulation with all atoms described by a DeepPotential with Gromacs, taking water as an example. Instead of using [ exclusions ]
to turn off the nonbonded energies, we can simply do this by setting LJ parameters (i.e. epsilon and sigma) and partial charges to 0, as shown in examples/water/gmx/water.top
:
[ atomtypes ]
; name at.num mass charge ptype sigma epsilon
HW 1 1.008 0.0000 A 0.00000e+00 0.00000e+00
OW 8 16.00 0.0000 A 0.00000e+00 0.00000e+00
As mentioned in the above section, input.json
and relevant files (index.raw
, type.raw
) should also be created. Then, we can start the simulation under NVT ensemble and plot the radial distribution function (RDF) by gmx rdf
command. We can see that the RDF given by Gromacs+DP matches perfectly with Lammps+DP, which further provides an evidence on the validity of our simulation.
However, we still recommend you run allatom DP simulation using LAMMPS since it is more stable and efficient.
Interfaces out of DeePMDkit
The codes of the following interfaces are not a part of the DeePMDkit package and maintained by other repositories. We list these interfaces here for user convenience.
dpdata
dpdata provides the predict
method for System
class:
import dpdata
dsys = dpdata.LabeledSystem('OUTCAR')
dp_sys = dsys.predict("frozen_model_compressed.pb")
By inferring with the DP model frozen_model_compressed.pb
, dpdata will generate a new labeled system dp_sys
with inferred energies, forces, and virials.
OpenMM plugin for DeePMDkit
An OpenMM plugin is provided from JingHuangLab/openmm_deepmd_plugin, written by the Huang Lab at the Westlake University.
AMBER interface to DeePMDkit
An AMBER interface to DeePMDkit is written by the York Lab from the Rutgers University. It is opensource at GitLab RutgersLBSR/AmberDPRc. Details can be found in this paper.
DPGEN
DPGEN provides a workflow to generate accurate DP models by calling DeePMDkit’s command line interface (CLI) in the local or the remote server. Details can be found in this paper.
MLatom
Mlatom provides an interface to the DeePMDkit within MLatom’s workflow by calling DeePMDkit’s CLI. Details can be found in this paper.
Use NVNMD
Introduction
NVNMD stands for nonvon Neumann molecular dynamics.
This is the training code we used to generate the results in our paper entitled “Accurate and Efficient Molecular Dynamics based on Machine Learning and Non Von Neumann Architecture”, which has been accepted by npj Computational Materials (DOI: 10.1038/s4152402200773z).
Any user can follow two consecutive steps to run molecular dynamics (MD) on the proposed NVNMD computer, which has been released online: (i) to train a machine learning (ML) model that can decently reproduce the potential energy surface (PES); and (ii) to deploy the trained ML model on the proposed NVNMD computer, then run MD there to obtain the atomistic trajectories.
Training
Our training procedure consists of not only the continuous neural network (CNN) training, but also the quantized neural network (QNN) training which uses the results of CNN as inputs. It is performed on CPU or GPU by using the training codes we opensourced online.
To train a ML model that can decently reproduce the PES, training and testing data set should be prepared first. This can be done by using either the stateoftheart active learning tools, or the outdated (i.e., less efficient) bruteforce density functional theory (DFT)based abinitio molecular dynamics (AIMD) sampling.
If you just want to simply test the training function, you can use the example in the $deepmd_source_dir/examples/nvnmd
directory. If you want to fully experience training and running MD functions, you can download the complete example from the website.
Then, copy the data set to working directory
mkdir p $workspace
cd $workspace
mkdir p data
cp r $dataset data
where $dataset
is the path to the data set and $workspace
is the path to working directory.
Input script
Create and go to the training directory.
mkdir train
cd train
Then copy the input script train_cnn.json
and train_qnn.json
to the directory train
cp r $deepmd_source_dir/examples/nvnmd/train/train_cnn.json train_cnn.json
cp r $deepmd_source_dir/examples/nvnmd/train/train_qnn.json train_qnn.json
The structure of the input script is as follows
{
"nvnmd" : {},
"learning_rate" : {},
"loss" : {},
"training": {}
}
nvnmd
The “nvnmd” section is defined as
{
"net_size":128,
"sel":[60, 60],
"rcut":6.0,
"rcut_smth":0.5
}
where items are defined as:
Item  Mean  Optional Value 

net_size  the size of nueral network  128 
sel  the number of neighbors  integer list of lengths 1 to 4 are acceptable 
rcut  the cutoff radial  (0, 8.0] 
rcut_smth  the smooth cutoff parameter  (0, 8.0] 
learning_rate
The “learning_rate” section is defined as
{
"type":"exp",
"start_lr": 1e3,
"stop_lr": 3e8,
"decay_steps": 5000
}
where items are defined as:
Item  Mean  Optional Value 

type  learning rate variant type  exp 
start_lr  the learning rate at the beginning of the training  a positive real number 
stop_lr  the desired learning rate at the end of the training  a positive real number 
decay_stops  the learning rate is decaying every {decay_stops} training steps  a positive integer 
loss
The “loss” section is defined as
{
"start_pref_e": 0.02,
"limit_pref_e": 2,
"start_pref_f": 1000,
"limit_pref_f": 1,
"start_pref_v": 0,
"limit_pref_v": 0
}
where items are defined as:
Item  Mean  Optional Value 

start_pref_e  the loss factor of energy at the beginning of the training  zero or positive real number 
limit_pref_e  the loss factor of energy at the end of the training  zero or positive real number 
start_pref_f  the loss factor of force at the beginning of the training  zero or positive real number 
limit_pref_f  the loss factor of force at the end of the training  zero or positive real number 
start_pref_v  the loss factor of virial at the beginning of the training  zero or positive real number 
limit_pref_v  the loss factor of virial at the end of the training  zero or positive real number 
training
The “training” section is defined as
{
"seed": 1,
"stop_batch": 1000000,
"numb_test": 1,
"disp_file": "lcurve.out",
"disp_freq": 1000,
"save_ckpt": "model.ckpt",
"save_freq": 10000,
"training_data":{
"systems":["system1_path", "system2_path", "..."],
"set_prefix": "set",
"batch_size": ["batch_size_of_system1", "batch_size_of_system2", "..."]
}
}
where items are defined as:
Item  Mean  Optional Value 

seed  the randome seed  a integer 
stop_batch  the total training steps  a positive integer 
numb_test  the accuracy is test by using {numb_test} sample  a positive integer 
disp_file  the log file where the training message display  a string 
disp_freq  display frequency  a positive integer 
save_ckpt  check point file  a string 
save_freq  save frequency  a positive integer 
systems  a list of data directory which contains the dataset  string list 
set_prefix  the prefix of dataset  a string 
batch_size  a list of batch size of corresponding dataset  a integer list 
Training
Training can be invoked by
# step1: train CNN
dp trainnvnmd train_cnn.json s s1
# step2: train QNN
dp trainnvnmd train_qnn.json s s2
After training process, you will get two folders: nvnmd_cnn
and nvnmd_qnn
. The nvnmd_cnn
contains the model after continuous neural network (CNN) training. The nvnmd_qnn
contains the model after quantized neural network (QNN) training. The binary file nvnmd_qnn/model.pb
is the model file which is used to performs NVNMD in server [http://nvnmd.picp.vip]
Testing
The frozen model can be used in many ways. The most straightforward testing can be invoked by
mkdir test
dp test m ./nvnmd_qnn/frozen_model.pb s path/to/system d ./test/detail n 99999 l test/output.log
where the frozen model file to import is given via the m
command line flag, the path to the testing data set is given via the s
command line flag, the file containing details of energy, force and virial accuracy is given via the d
command line flag, the amount of data for testing is given via the n
command line flag.
Running MD
After CNN and QNN training, you can upload the ML model to our online NVNMD system and run MD there.
Account application
The server website of NVNMD is available at http://nvnmd.picp.vip. You can visit the URL and enter the login interface (Figure.1).
To obtain an account, please send your application to the email (jie_liu@hnu.edu.cn, liujie@uw.edu). The username and password will be sent to you by email.
Adding task
After successfully obtaining the account, enter the username and password in the login interface, and click “Login” to enter the homepage (Figure.2).
The homepage displays the remaining calculation time and all calculation records not deleted. Click Add a new task
to enter the interface for adding a new task (Figure.3).
Task name: name of the task
Upload mode: two modes of uploading results to online data storage, including
Manual upload
andAutomatic upload
. Results need to be uploaded manually to online data storage withManual upload
mode, and will be uploaded automatically withAutomatic upload
mode.Input script: input file of the MD simulation.
In the input script, one needs to specify the pair style as follows
pair_style nvnmd model.pb
pair_coeff * *
Model file: the ML model named
model.pb
obtained by QNN training.Data files: data files containing information required for running an MD simulation (e.g.,
coord.lmp
containing initial atom coordinates).
Next, you can click Submit
to submit the task and then automatically return to the homepage (Figure.4).
Then, click Refresh
to view the latest status of all calculation tasks.
Cancelling calculation
For the task whose calculation status is Pending
and Running
, you can click the corresponding Cancel
on the homepage to stop the calculation (Figure.5).
Downloading results
For the task whose calculation status is Completed
, Failed
and Cancelled
, you can click the corresponding Package
or Separate files
in the Download results
bar on the homepage to download results.
Click Package
to download a zipped package of all files including input files and output results (Figure.6).
Click Separate files
to download the required separate files (Figure.7).
If Manual upload
mode is selected or the file has expired, click Upload
on the download interface to upload manually.
Deleting record
For the task no longer needed, you can click the corresponding Delete
on the homepage to delete the record.
Records cannot be retrieved after deletion.
Clearing records
Click Clear calculation records
on the homepage to clear all records.
Records cannot be retrieved after clearing.
FAQs
In consequence of various differences of computers or systems, problems may occur. Some common circumstances are listed as follows. In addition, some frequently asked questions about parameters setting are listed as follows. If other unexpected problems occur, you’re welcome to contact us for help.
How to tune Fitting/embeddingnet size ?
Here are some test forms on fittingnet size tuning or embeddingnet size tuning performed on several different systems.
Al2O3
Fitting net size tuning form on Al2O3: (embeddingnet size: [25,50,100])
Fittingnet size  Energy L2err(eV)  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[240,240,240]  1.742252e02  7.259383e05  4.014115e02 
[80,80,80]  1.799349e02  7.497287e05  4.042977e02 
[40,40,40]  1.799036e02  7.495984e05  4.068806e02 
[20,20,20]  1.834032e02  7.641801e05  4.094784e02 
[10,10,10]  1.913058e02  7.971073e05  4.154775e02 
[5,5,5]  1.932914e02  8.053808e05  4.188052e02 
[4,4,4]  1.944832e02  8.103467e05  4.217826e02 
[3,3,3]  2.068631e02  8.619296e05  4.300497e02 
[2,2,2]  2.267962e02  9.449840e05  4.413609e02 
[1,1,1]  2.813596e02  1.172332e04  4.781115e02 
[]  3.135002e02  1.306251e04  5.373120e02 
[] means no hidden layer, but there is still a linear output layer. This situation is equal to the linear regression.
Embedding net size tuning form on Al2O3: (Fittingnet size: [240,240,240])
Embeddingnet size  Energy L2err(eV)  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[25,50,100]  1.742252e02  7.259383e05  4.014115e02 
[10,20,40]  2.909990e02  1.212496e04  4.734667e02 
[5,10,20]  3.357767e02  1.399070e04  5.706385e02 
[4,8,16]  6.060367e02  2.525153e04  7.333304e02 
[3,6,12]  5.656043e02  2.356685e04  7.793539e02 
[2,4,8]  5.277023e02  2.198759e04  7.459995e02 
[1,2,4]  1.302282e01  5.426174e04  9.672238e02 
Cu
Fitting net size tuning form on Cu: (embeddingnet size: [25,50,100])
Fittingnet size  Energy L2err(eV)  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[240,240,240]  4.135548e02  1.615449e04  8.940946e02 
[20,20,20]  4.323858e02  1.689007e04  8.955762e02 
[10,10,10]  4.399364e02  1.718502e04  8.962891e02 
[5,5,5]  4.468404e02  1.745470e04  8.970111e02 
[4,4,4]  4.463580e02  1.743586e04  8.972011e02 
[3,3,3]  4.493758e02  1.755374e04  8.971303e02 
[2,2,2]  4.500736e02  1.758100e04  8.973878e02 
[1,1,1]  4.542073e02  1.774247e04  8.964761e02 
[]  4.545168e02  1.775456e04  8.983201e02 
Embedding net size tuning form on Cu: (Fittingnet size: [240,240,240])
Embeddingnet size  Energy L2err(eV)  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[25,50,100]  4.135548e02  1.615449e04  8.940946e02 
[20,40,80]  4.203562e02  1.642016e04  8.925881e02 
[15,30,60]  4.146672e02  1.619794e04  8.936911e02 
[10,20,40]  4.263060e02  1.665258e04  8.955818e02 
[5,10,20]  4.994913e02  1.951138e04  9.007786e02 
[4,8,16]  1.022157e01  3.992802e04  9.532119e02 
[3,6,12]  1.362098e01  5.320695e04  1.073860e01 
[2,4,8]  7.061800e02  2.758515e04  9.126418e02 
[1,2,4] && seed = 1  9.843161e02  3.844985e04  9.348505e02 
[1,2,4] && seed = 2  9.404335e02  3.673568e04  9.304089e02 
[1,2,4] && seed = 3  1.508016e01  5.890688e04  1.382356e01 
[1,2,4] && seed = 4  9.686949e02  3.783965e04  9.294820e02 
Water
Fitting net size tuning form on water: (embeddingnet size: [25,50,100])
Fittingnet size  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[240,240,240]  9.1589E04  5.1540E02 
[200,200,200]  9.3221E04  5.2366E02 
[160,160,160]  9.4274E04  5.3403E02 
[120,120,120]  9.5407E04  5.3093E02 
[80,80,80]  9.4605E04  5.3402E02 
[40,40,40]  9.8533E04  5.5790E02 
[20,20,20]  1.0057E03  5.8232E02 
[10,10,10]  1.0466E03  6.2279E02 
[5,5,5]  1.1154E03  6.7994E02 
[4,4,4]  1.1289E03  6.9613E02 
[3,3,3]  1.2368E03  7.9786E02 
[2,2,2]  1.3558E03  9.7042E02 
[1,1,1]  1.4633E03  1.1265E01 
[]  1.5193E03  1.2136E01 
Embedding net size tuning form on water: (Fittingnet size: [240,240,240])
Embeddingnet size  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[25,50,100]  9.1589E04  5.1540E02 
[20,40,80]  9.5080E04  5.3593E02 
[15,30,60]  9.7996E04  5.6338E02 
[10,20,40]  1.0353E03  6.2776E02 
[5,10,20]  1.1254E03  7.3195E02 
[4,8,16]  1.2495E03  8.0371E02 
[3,6,12]  1.3604E03  9.9883E02 
[2,4,8]  1.4358E03  9.7389E02 
[1,2,4]  2.1765E03  1.7276E01 
MgAl
Fitting net size tuning form on MgAl: (embeddingnet size: [25,50,100])
Fittingnet size  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[240,240,240]  3.9606e03  1.6289e02 
[200,200,200]  3.9449e03  1.6471e02 
[160,160,160]  4.0947e03  1.6413e02 
[120,120,120]  3.9234e03  1.6283e02 
[80,80,80]  3.9758e03  1.6506e02 
[40,40,40]  3.9142e03  1.6348e02 
[20,20,20]  4.1302e03  1.7006e02 
[10,10,10]  4.3433e03  1.7524e02 
[5,5,5]  5.3154e03  1.9716e02 
[4,4,4]  5.4210e03  1.9710e02 
[2,2,2]  6.2667e03  2.2568e02 
[1,1,1]  7.3676e03  2.6375e02 
[]  7.3999e03  2.6097e02 
Embedding net size tuning form on MgAl: (Fittingnet size: [240,240,240])
Embeddingnet size  Energy L2err/Natoms(eV)  Force L2err(eV/Angstrom) 

[25,50,100]  3.9606e03  1.6289e02 
[20,40,80]  4.0292e03  1.6555e02 
[15,30,60]  4.1743e03  1.7026e02 
[10,20,40]  4.8138e03  1.8516e02 
[5,10,20]  5.6052e03  2.0709e02 
[4,8,16]  6.1335e03  2.1450e02 
[3,6,12]  6.6469e03  2.3003e02 
[2,4,8]  6.8222e03  2.6318e02 
[1,2,4]  1.0678e02  3.9559e02 
How to control the number of nodes used by a job ?
Set the number of CPU nodes used by DP algorithms with:
mpirun np $num_nodes dp
Set the number of threads used by DP algorithms with:
export OMP_NUM_THREADS=$num_threads
Set the number of CPU nodes used by TF kernels with:
export TF_INTRA_OP_PARALLELISM_THREADS=$num_nodes
export TF_INTER_OP_PARALLELISM_THREADS=$num_nodes
Do we need to set rcut < half boxsize ?
When seeking the neighbors of atom i under periodic boundary condition, deepmdkit considers all j atoms within cutoff rcut from atom i in all mirror cells.
So, so there is no limitation on the setting of rcut.
PS: The reason why some softwares require rcut < half boxsize is that they only consider the nearest mirrors from the center cell. Deepmdkit is totally different from them.
How to set sel ?
sel
is short for “selected number of atoms in rcut
”.
sel_a[i]
is a list of integers. The length of the list should be the same as the number of atom types in the system.
sel_a[i]
gives the number of selected number of type i
neighbors within rcut
. To ensure that the results are strictly accurate, sel_a[i]
should be larger than the largest number of type i
neighbors in the rcut
.
However, the computation overhead increases with sel_a[i]
, therefore, sel_a[i]
should be as small as possible.
The setting of sel_a[i]
should balance the above two considerations.
Installation
Inadequate versions of gcc/g++
Sometimes you may use a gcc/g++ of version < 4.8. In this way, you can still compile all the parts of TensorFlow and most of the parts of DeePMDkit, but iPi and GROMACS plugin will be disabled automatically. Or if you have a gcc/g++ of version > 4.8, say, 7.2.0, you may choose to use it by doing
export CC=/path/to/gcc7.2.0/bin/gcc
export CXX=/path/to/gcc7.2.0/bin/g++
Build files left in DeePMDkit
When you try to build a second time when installing DeePMDkit, files produced before may contribute to failure. Thus, you may clear them by
cd build
rm r *
and redo the cmake
process.
The temperature undulates violently during early stages of MD
This is probably because your structure is too far from the equlibrium configuration.
Although, to make sure the potential model is truly accurate, we recommend to check model deviation.
MD: cannot run LAMMPS after installing a new version of DeePMDkit
This typically happens when you install a new version of DeePMDkit and copy directly the generated USERDEEPMD
to a LAMMPS source code folder and reinstall LAMMPS.
To solve this problem, it suffices to first remove USERDEEPMD
from LAMMPS source code by
make nouserdeepmd
and then install the new USERDEEPMD
.
If this does not solve your problem, try to decompress the LAMMPS source tarball and install LAMMPS from scratch again, which typically should be very fast.
Model compatibility
When the version of DeePMDkit used to training model is different from the that of DeePMDkit running MDs, one has the problem of model compatibility.
DeePMDkit guarantees that the codes with the same major and minor revisions are compatible. That is to say v0.12.5 is compatible to v0.12.0, but is not compatible to v0.11.0 nor v1.0.0.
One can execute dp convertfrom
to convert an old model to a new one.
Model version  v0.12  v1.0  v1.1  v1.2  v1.3  v2.0  v2.1 

Compatibility  😊  😊  😊  😊  😊  😄  😄 
Legend:
😄: The model is compatible with the DeePMDkit package.
😊: The model is incompatible with the DeePMDkit package, but one can execute
dp convertfrom
to convert an old model to v2.1.😢: The model is incompatible with the DeePMDkit package, and there is no way to convert models.
Coding Conventions
Preface
The aim of these coding standards is to help create a codebase with defined and consistent coding style that every contributor can get easily familiar with. This will in enhance code readability as there will be no different coding styles from different contributors and everything will be documented. Also PR diffs will be smaller because of unified coding style. Finally static typing will help in hunting down potential bugs before the code is even run.
Contributed code will not be refused merely because it does not strictly adhere to these conditions; as long as it’s internally consistent, clean, and correct, it probably will be accepted. But don’t be surprised if the “offending” code gets fiddled over time to conform to these conventions.
There are also github actions CI checks for python code style which will annotate the PR diff for you to see the areas where your code is lacking compared to the set standard.
Rules
The code must be compatible with the oldest supported version of python which is 3.6
The project follows the generic coding conventions as specified in the Style Guide for Python Code, Docstring Conventions and Typing Conventions PEPs, clarified and extended as follows:
Do not use “
*
” imports such asfrom module import *
. Instead, list imports explicitly.Use 4 spaces per indentation level. No tabs.
No oneliner compound statements (i.e., no
if x: return
: use two lines).Maximum line length is 88 characters as recomended by black wich is less strict than Docstring Conventions suggests.
Use “StudlyCaps” for class names.
Use “lowercase” or “lowercase_with_underscores” for function, method, variable names and module names. For short names, joined lowercase may be used (e.g. “tagname”). Choose what is most readable.
No singlecharacter variable names, except indices in loops that encompass a very small number of lines (
for i in range(5): ...
).Avoid lambda expressions. Use named functions instead.
Avoid functional constructs (filter, map, etc.). Use list comprehensions instead.
Use
"double quotes"
for string literals, and"""triple double quotes"""
for docstring’s. Single quotes are OK for something likef"something {'this' if x else 'that'}"
Use fstrings
s = f"{x:.2f}"
instead of old style formating with"%f" % x
. string format method"{x:.2f}".format()
may be used sparsely where it is more convenient than fstrings.
Whitespace
Python is not C/C++ so whitespace should be used sparingly to maintain code readability
Read the Whitespace in Expressions and Statements section of PEP8.
Avoid trailing whitespaces.
Do not use excessive whitespace in your expressions and statements.
You should have blank spaces after commas, colons, and semicolons if it isn’t trailing next to the end of a bracket, brace, or parentheses.
With any operators you should use a space in on both sides of the operator.
Colons for slicing are considered a binary operator, and should not have any spaces between them.
You should have parentheses with no space, directly next to the function when calling functions
function()
.When indexing or slicing the brackets should be directly next to the collection with no space
collection["index"]
.Whitespace used to line up variable values is not recommended.
Make sure you are consistent with the formats you choose when optional choices are available.
General advice
Get rid of as many
break
andcontinue
statements as possible.Write short functions. All functions should fit within a standard screen.
Use descriptive variable names.
Writing documentation in the code
Here is an example of how to write good docstrings:
The numpy doctring documentation can be found here
It is a good practice to run pydocstyle check on your code or use a text editor that does it automatically):
$ pydocstyle filename.py
Run pycodestyle on your code
It’s a good idea to run pycodestyle on your code (or use a text editor that does it automatically):
$ pycodestyle filename.py
Run mypy on your code
It’s a good idea to run mypy on your code (or use a text editor that does it automatically):
$ mypy filename.py
Run pydocstyle on your code
It’s a good idea to run pycodestyle on your code (or use a text editor that does it automatically):
$ pycodestyle filename.py maxlinelength=88
Run black on your code
Another method of enforcing PEP8 is using a tool such as black. These tools tend to be very effective at cleaning up code, but should be used carefully and code should be retested after cleaning it. Try:
$ black help
Create a model
If you’d like to create a new model that isn’t covered by the existing DeePMDkit library, but reuse DeePMDkit’s other efficient module such as data processing, trainner, etc, you may want to read this section.
To incorporate your custom model you’ll need to:
Register and implement new components (e.g. descriptor) in a Python file. You may also want to regiester new TensorFlow OPs if necessary.
Register new arguments for user inputs.
Package new codes into a Python package.
Test new models.
Design a new component
When creating a new component, take descriptor as the example, you should inherit deepmd.descriptor.descriptor.Descriptor
class and override several methods. Abstract methods such as deepmd.descriptor.descriptor.Descriptor.build
must be implemented and others are not. You should keep arguments of these methods unchanged.
After implementation, you need to register the component with a key:
from deepmd.descriptor import Descriptor
@Descriptor.register("some_descrpt")
class SomeDescript(Descriptor):
def __init__(self, arg1: bool, arg2: float) > None:
pass
Register new arguments
To let some one uses your new component in their input file, you need to create a new methods that returns some Argument
of your new component, and then register new arguments. For example, the code below
from typing import List
from dargs import Argument
from deepmd.utils.argcheck import descrpt_args_plugin
@descrpt_args_plugin.register("some_descrpt")
def descrpt_some_args() > List[Argument]:
return [
Argument("arg1", bool, optional=False, doc="balabala"),
Argument("arg2", float, optional=True, default=6.0, doc="haha"),
]
allows one to use your new descriptor as below:
"descriptor" :{
"type": "some_descrpt",
"arg1": true,
"arg2": 6.0
}
The arguments here should be consistent with the class arguments of your new componenet.
Package new codes
You may use setuptools
to package new codes into a new Python package. It’s crirical to add your new component to entry_points['deepmd']
in setup.py
:
entry_points={
'deepmd': [
'some_descrpt=deepmd_some_descrtpt:SomeDescript',
],
},
where deepmd_some_descrtpt
is the module of your codes. It is equivalent to from deepmd_some_descrtpt import SomeDescript
.
If you place SomeDescript
and descrpt_some_args
into different modules, you are also expected to add descrpt_some_args
to entry_points
.
After you install your new package, you can now use dp train
to run your new model.
Atom Type Embedding
Overview
Here is an overview of the deepmdkit algorithm. Given a specific centric atom, we can obtain the matrix describing its local environment, named as \(\mathcal R\). It is consist of the distance between centric atom and its neighbors, as well as a direction vector. We can embed each distance into a vector of \(M_1\) dimension by an embedding net
, so the environment matrix \(\mathcal R\) can be embed into matrix \(\mathcal G\). We can thus extract a descriptor vector (of \(M_1 \times M_2\) dim) of the centric atom from the \(\mathcal G\) by some matrix multiplication, and put the descriptor into fitting net
to get predicted energy \(E\). The vanilla version of deepmdkit build embedding net
and fitting net
relying on the atom type, resulting in \(O(N)\) memory usage. After applying atom type embedding, in deepmdkit v2.0, we can share one embedding net
and one fitting net
in total, which decline training complexity largely.
Preliminary
In the following chart, you can find the meaning of symbols used to clarify the atom type embedding algorithm.
\(i\): Type of centric atom
\(j\): Type of neighbor atom
\(s_{ij}\): Distance between centric atom and neighbor atom
\(\mathcal G_{ij}(\cdot)\): Origin embedding net, take \(s_{ij}\) as input and output embedding vector of \(M_1\) dim
\(\mathcal G(\cdot)\): Shared embedding net
\(\text{Multi}(\cdot)\): Matrix multiplication and flattening, output the descriptor vector of \(M_1\times M_2\) dim
\(F_i(\cdot)\): Origin fitting net, take the descriptor vector as input and output energy
\(F(\cdot)\): Shared fitting net
\(A(\cdot)\): Atom type embedding net, input is atom type, output is type embedding vector of dim nchanl
So, we can formulate the training process as follows. Vanilla deepmdkit algorithm:
Deepmdkit applying atom type embedding:
or
The difference between two variants above is whether using the information of centric atom when generating the descriptor. Users can choose by modifying the type_one_side
hyperparameter in the input json file.
How to use
A detailed introduction can be found at se_e2_a_tebd
. Looking for a fast start up, you can simply add a type_embedding
section in the input json file as displayed in the following, and the algorithm will adopt atom type embedding algorithm automatically. An example of type_embedding
is like
"type_embedding":{
"neuron": [2, 4, 8],
"resnet_dt": false,
"seed": 1
}
Code Modification
Atom type embedding can be applied to varied embedding net
and fitting net
, as a result we build a class TypeEmbedNet
to support this free combination. In the following, we will go through the execution process of the code to explain our code modification.
trainer (train/trainer.py)
In trainer.py, it will parse the parameter from the input json file. If a type_embedding
section is detected, it will build a TypeEmbedNet
, which will be later input in the model
. model
will be built in the function _build_network
.
model (model/ener.py)
When building the operation graph of the model
in model.build
. If a TypeEmbedNet
is detected, it will build the operation graph of type embed net
, embedding net
and fitting net
by order. The building process of type embed net
can be found in TypeEmbedNet.build
, which output the type embedding vector of each atom type (of [\(\text{ntypes} \times \text{nchanl}\)] dimensions). We then save the type embedding vector into input_dict
, so that they can be fetched later in embedding net
and fitting net
.
embedding net (descriptor/se*.py)
In embedding net
, we shall take local environment \(\mathcal R\) as input and output matrix \(\mathcal G\). Functions called in this process by order is
build > _pass_filter > _filter > _filter_lower
_pass_filter
: It will first detect whether an atom type embedding exists, if so, it will apply atom type embedding algorithm and doesn’t divide the input by type.
_filter
: It will call _filter_lower
function to obtain the result of matrix multiplication (\(\mathcal G^T\cdot \mathcal R\)), do further multiplication involved in \(\text{Multi}(\cdot)\), and finally output the result of descriptor vector of \(M_1 \times M_2\) dim.
_filter_lower
: The main function handling input modification. If type embedding exists, it will call _concat_type_embedding
function to concat the first column of input \(\mathcal R\) (the column of \(s_{ij}\)) with the atom type embedding information. It will decide whether using the atom type embedding vector of centric atom according to the value of type_one_side
(if set True, then we only use the vector of the neighbor atom). The modified input will be put into the fitting net
to get \(\mathcal G\) for further matrix multiplication stage.
fitting net (fit/ener.py)
In fitting net
, it take the descriptor vector as input, whose dimension is [natoms, \(M_1\times M_2\)]. Because we need to involve information of centric atom in this step, we need to generate a matrix named as atype_embed
(of dim [natoms, nchanl]), in which each row is the type embedding vector of the specific centric atom. The input is sorted by type of centric atom, we also know the number of a particular atom type (stored in natoms[2+i]
), thus we get the type vector of centric atom. In the build phrase of fitting net, it will check whether type embedding exist in input_dict
and fetch them. After that calling embed_atom_type
function to lookup embedding vector for type vector of centric atom to obtain atype_embed
, and concat input with it ([input, atype_embed]). The modified input go through fitting net
to get predicted energy.
P.S.: You can’t apply compression method while using atom type embedding
Python API
deepmd package
Root of the deepmd package, exposes all public classes and submodules.
 class deepmd.DeepEval(model_file: Path, load_prefix: str = 'load', default_tf_graph: bool = False, auto_batch_size: Union[bool, int, deepmd.utils.batch_size.AutoBatchSize] = False)[source]
Bases:
object
Common methods for DeepPot, DeepWFC, DeepPolar, …
 Parameters
 model_file
Path
The name of the frozen model file.
 load_prefix: str
The prefix in the load computational graph
 default_tf_graphbool
If uses the default tf graph, otherwise build a new tf graph for evaluation
 auto_batch_sizebool or
int
orAutomaticBatchSize
, default:False
If True, automatic batch size will be used. If int, it will be used as the initial batch size.
 model_file
 Attributes
model_type
Get type of model.
model_version
Get version of model.
Methods
make_natoms_vec
(atom_types)Make the natom vector used by deepmdkit.
reverse_map
(vec, imap)Reverse mapping of a vector according to the index map
sort_input
(coord, atom_type[, sel_atoms])Sort atoms in the system according their types.
 make_natoms_vec(atom_types: numpy.ndarray) numpy.ndarray [source]
Make the natom vector used by deepmdkit.
 Parameters
 atom_types
The type of atoms
 Returns
natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 static reverse_map(vec: numpy.ndarray, imap: List[int]) numpy.ndarray [source]
Reverse mapping of a vector according to the index map
 Parameters
 vec
Input vector. Be of shape [nframes, natoms, 1]
 imap
Index map. Be of shape [natoms]
 Returns
vec_out
Reverse mapped vector.
 static sort_input(coord: numpy.ndarray, atom_type: numpy.ndarray, sel_atoms: Optional[List[int]] = None)[source]
Sort atoms in the system according their types.
 Parameters
 coord
The coordinates of atoms. Should be of shape [nframes, natoms, 3]
 atom_type
The type of atoms Should be of shape [natoms]
 sel_atom
The selected atoms by type
 Returns
coord_out
The coordinates after sorting
atom_type_out
The atom types after sorting
idx_map
The index mapping from the input to the output. For example coord_out = coord[:,idx_map,:]
sel_atom_type
Only output if sel_atoms is not None The sorted selected atom types
sel_idx_map
Only output if sel_atoms is not None The index mapping from the selected atoms to sorted selected atoms.
 deepmd.DeepPotential(model_file: Union[str, pathlib.Path], load_prefix: str = 'load', default_tf_graph: bool = False) Union[deepmd.infer.deep_dipole.DeepDipole, deepmd.infer.deep_polar.DeepGlobalPolar, deepmd.infer.deep_polar.DeepPolar, deepmd.infer.deep_pot.DeepPot, deepmd.infer.deep_wfc.DeepWFC] [source]
Factory function that will inialize appropriate potential read from model_file.
 Parameters
 model_file: str
The name of the frozen model file.
 load_prefix: str
The prefix in the load computational graph
 default_tf_graphbool
If uses the default tf graph, otherwise build a new tf graph for evaluation
 Returns
Union
[DeepDipole
,DeepGlobalPolar
,DeepPolar
,DeepPot
,DeepWFC
]one of the available potentials
 Raises
RuntimeError
if model file does not correspond to any implementd potential
 class deepmd.DipoleChargeModifier(model_name: str, model_charge_map: List[float], sys_charge_map: List[float], ewald_h: float = 1, ewald_beta: float = 1)[source]
Bases:
deepmd.infer.deep_dipole.DeepDipole
 Parameters
 model_name
The model file for the DeepDipole model
 model_charge_map
Gives the amount of charge for the wfcc
 sys_charge_map
Gives the amount of charge for the real atoms
 ewald_h
Grid spacing of the reciprocal part of Ewald sum. Unit: A
 ewald_beta
Splitting parameter of the Ewald sum. Unit: A^{1}
 Attributes
model_type
Get type of model.
model_version
Get version of model.
Methods
Build the computational graph for the force and virial inference.
eval
(coord, box, atype[, eval_fv])Evaluate the modification
eval_full
(coords, cells, atom_types[, ...])Evaluate the model with interface similar to the energy model.
get_dim_aparam
()Unsupported in this model.
get_dim_fparam
()Unsupported in this model.
get_ntypes
()Get the number of atom types of this model.
get_rcut
()Get the cutoff radius of this model.
get_sel_type
()Get the selected atom types of this model.
get_type_map
()Get the type map (element name of the atom types) of this model.
make_natoms_vec
(atom_types)Make the natom vector used by deepmdkit.
modify_data
(data)Modify data.
reverse_map
(vec, imap)Reverse mapping of a vector according to the index map
sort_input
(coord, atom_type[, sel_atoms])Sort atoms in the system according their types.
 build_fv_graph() tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the force and virial inference.
 eval(coord: numpy.ndarray, box: numpy.ndarray, atype: numpy.ndarray, eval_fv: bool = True) Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray] [source]
Evaluate the modification
 Parameters
 coord
The coordinates of atoms
 box
The simulation region. PBC is assumed
 atype
The atom types
 eval_fv
Evaluate force and virial
 Returns
tot_e
The energy modification
tot_f
The force modification
tot_v
The virial modification
 modify_data(data: dict) None [source]
Modify data.
 Parameters
 data
Internal data of DeepmdData. Be a dict, has the following keys  coord coordinates  box simulation box  type atom types  find_energy tells if data has energy  find_force tells if data has force  find_virial tells if data has virial  energy energy  force force  virial virial
Subpackages
deepmd.cluster package
Module that reads node resources, auto detects if running local or on SLURM.
 deepmd.cluster.get_resource() Tuple[str, List[str], Optional[List[int]]] [source]
Get local or slurm resources: nodename, nodelist, and gpus.
Submodules
deepmd.cluster.local module
Get local GPU resources.
deepmd.cluster.slurm module
MOdule to get resources on SLURM cluster.
https://github.com/deepsenseai/tensorflow_on_slurm ####
 deepmd.cluster.slurm.get_resource() Tuple[str, List[str], Optional[List[int]]] [source]
Get SLURM resources: nodename, nodelist, and gpus.
 Returns
 Raises
RuntimeError
if number of nodes could not be retrieved
ValueError
list of nodes is not of the same length sa number of nodes
ValueError
if current nodename is not found in node list
deepmd.descriptor package
Submodules
deepmd.descriptor.descriptor module
 class deepmd.descriptor.descriptor.Descriptor(*args, **kwargs)[source]
Bases:
deepmd.utils.plugin.PluginVariant
The abstract class for descriptors. All specific descriptors should be based on this class.
The descriptor \(\mathcal{D}\) describes the environment of an atom, which should be a function of coordinates and types of its neighbour atoms.
Notes
Only methods and attributes defined in this class are generally public, that can be called by other classes.
Examples
>>> descript = Descriptor(type="se_e2_a", rcut=6., rcut_smth=0.5, sel=[50]) >>> type(descript) <class 'deepmd.descriptor.se_a.DescrptSeA'>
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor.
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Returns the output dimension of this descriptor.
Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
Returns neighbor information.
Returns the number of atom types.
get_rcut
()Returns the cutoff radius.
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(*tensors)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial.
register
(key)Regiester a descriptor plugin.
 abstract build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: Dict[str, Any], reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor.
 Parameters
 coord_
tf.Tensor
The coordinate of atoms
 atype_
tf.Tensor
The type of atoms
 natoms
tf.Tensor
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 box
tf.Tensor
The box of frames
 mesh
tf.Tensor
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
dict
[str
,Any
] Dictionary for additional inputs
 reusebool,
optional
The weights in the networks should be reused when get the variable.
 suffix
str
,optional
Name suffix to identify this descriptor
 coord_
 Returns
 descriptor:
tf.Tensor
The output descriptor
 descriptor:
Notes
This method must be implemented, as it’s called by other classes.
 abstract compute_input_stats(data_coord: List[numpy.ndarray], data_box: List[numpy.ndarray], data_atype: List[numpy.ndarray], natoms_vec: List[numpy.ndarray], mesh: List[numpy.ndarray], input_dict: Dict[str, List[numpy.ndarray]]) None [source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
list
[np.ndarray
] The coordinates. Can be generated by
deepmd.model.model_stat.make_stat_input()
 data_box
list
[np.ndarray
] The box. Can be generated by
deepmd.model.model_stat.make_stat_input()
 data_atype
list
[np.ndarray
] The atom types. Can be generated by
deepmd.model.model_stat.make_stat_input()
 natoms_vec
list
[np.ndarray
] The vector for the number of atoms of the system and different types of atoms. Can be generated by
deepmd.model.model_stat.make_stat_input()
 mesh
list
[np.ndarray
] The mesh for neighbor searching. Can be generated by
deepmd.model.model_stat.make_stat_input()
 input_dict
dict
[str
,list
[np.ndarray
]] Dictionary for additional input
 data_coord
Notes
This method must be implemented, as it’s called by other classes.
 enable_compression(min_nbor_dist: float, model_file: str = 'frozon_model.pb', table_extrapolate: float = 5.0, table_stride_1: float = 0.01, table_stride_2: float = 0.1, check_frequency: int =  1, suffix: str = '') None [source]
Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
 Parameters
 min_nbor_dist
float
The nearest distance between atoms
 model_file
str
, default: ‘frozon_model.pb’ The original frozen model, which will be compressed by the program
 table_extrapolate
float
, default: 5. The scale of model extrapolation
 table_stride_1
float
, default: 0.01 The uniform stride of the first table
 table_stride_2
float
, default: 0.1 The uniform stride of the second table
 check_frequency
int
, default: 1 The overflow check frequency
 suffix
str
,optional
The suffix of the scope
 min_nbor_dist
Notes
This method is called by others when the descriptor supported compression.
 enable_mixed_precision(mixed_prec: Optional[dict] = None) None [source]
Reveive the mixed precision setting.
 Parameters
 mixed_prec
The mixed precision setting used in the embedding net
Notes
This method is called by others when the descriptor supported compression.
 abstract get_dim_out() int [source]
Returns the output dimension of this descriptor.
 Returns
int
the output dimension of this descriptor
Notes
This method must be implemented, as it’s called by other classes.
 get_dim_rot_mat_1() int [source]
Returns the first dimension of the rotation matrix. The rotation is of shape dim_1 x 3
 Returns
int
the first dimension of the rotation matrix
 get_feed_dict(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor) Dict[str, tensorflow.python.framework.ops.Tensor] [source]
Generate the feed_dict for current descriptor
 Parameters
 coord_
tf.Tensor
The coordinate of atoms
 atype_
tf.Tensor
The type of atoms
 natoms
tf.Tensor
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 box
tf.Tensor
The box. Can be generated by deepmd.model.make_stat_input
 mesh
tf.Tensor
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 coord_
 Returns
 get_nlist() Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, List[int], List[int]] [source]
Returns neighbor information.
 abstract get_ntypes() int [source]
Returns the number of atom types.
 Returns
int
the number of atom types
Notes
This method must be implemented, as it’s called by other classes.
 abstract get_rcut() float [source]
Returns the cutoff radius.
 Returns
float
the cutoff radius
Notes
This method must be implemented, as it’s called by other classes.
 init_variables(graph: tensorflow.python.framework.ops.Graph, graph_def: tensorflow.core.framework.graph_pb2.GraphDef, suffix: str = '') None [source]
Init the embedding net variables with the given dict
 Parameters
Notes
This method is called by others when the descriptor supported initialization from the given variables.
 pass_tensors_from_frz_model(*tensors: tensorflow.python.framework.ops.Tensor) None [source]
Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
 Parameters
 *tensors
tf.Tensor
passed tensors
 *tensors
Notes
The number of parameters in the method must be equal to the numbers of returns in
get_tensor_names()
.
 abstract prod_force_virial(atom_ener: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor] [source]
Compute force and virial.
 Parameters
 Returns
 static register(key: str) deepmd.descriptor.descriptor.Descriptor [source]
Regiester a descriptor plugin.
 Parameters
 key
str
the key of a descriptor
 key
 Returns
Descriptor
the regiestered descriptor
Examples
>>> @Descriptor.register("some_descrpt") class SomeDescript(Descriptor): pass
deepmd.descriptor.hybrid module
 class deepmd.descriptor.hybrid.DescrptHybrid(*args, **kwargs)[source]
Bases:
deepmd.descriptor.descriptor.Descriptor
Concate a list of descriptors to form a new descriptor.
 Parameters
 list
list
Build a descriptor from the concatenation of the list of descriptors.
 list
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Returns the output dimension of this descriptor
get_dim_rot_mat_1
()Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
get_nlist
()Returns neighbor information.
get_nlist_i
(ii)Get the neighbor information of the iith descriptor
Returns the number of atom types
get_rcut
()Returns the cutoff radius
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(*tensors)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: dict, reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
 compute_input_stats(data_coord: list, data_box: list, data_atype: list, natoms_vec: list, mesh: list, input_dict: dict) None [source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
The coordinates. Can be generated by deepmd.model.make_stat_input
 data_box
The box. Can be generated by deepmd.model.make_stat_input
 data_atype
The atom types. Can be generated by deepmd.model.make_stat_input
 natoms_vec
The vector for the number of atoms of the system and different types of atoms. Can be generated by deepmd.model.make_stat_input
 mesh
The mesh for neighbor searching. Can be generated by deepmd.model.make_stat_input
 input_dict
Dictionary for additional input
 enable_compression(min_nbor_dist: float, model_file: str = 'frozon_model.pb', table_extrapolate: float = 5.0, table_stride_1: float = 0.01, table_stride_2: float = 0.1, check_frequency: int =  1, suffix: str = '') None [source]
Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
 Parameters
 min_nbor_dist
float
The nearest distance between atoms
 model_file
str
, default: ‘frozon_model.pb’ The original frozen model, which will be compressed by the program
 table_extrapolate
float
, default: 5. The scale of model extrapolation
 table_stride_1
float
, default: 0.01 The uniform stride of the first table
 table_stride_2
float
, default: 0.1 The uniform stride of the second table
 check_frequency
int
, default: 1 The overflow check frequency
 suffix
str
,optional
The suffix of the scope
 min_nbor_dist
 enable_mixed_precision(mixed_prec: Optional[dict] = None) None [source]
Reveive the mixed precision setting.
 Parameters
 mixed_prec
The mixed precision setting used in the embedding net
 get_nlist_i(ii: int) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, List[int], List[int]] [source]
Get the neighbor information of the iith descriptor
 Parameters
 ii
int
The index of the descriptor
 ii
 Returns
nlist
Neighbor list
rij
The relative distance between the neighbor and the center atom.
sel_a
The number of neighbors with full information
sel_r
The number of neighbors with only radial information
 init_variables(graph: tensorflow.python.framework.ops.Graph, graph_def: tensorflow.core.framework.graph_pb2.GraphDef, suffix: str = '') None [source]
Init the embedding net variables with the given dict
 pass_tensors_from_frz_model(*tensors: tensorflow.python.framework.ops.Tensor) None [source]
Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
 Parameters
 *tensors
tf.Tensor
passed tensors
 *tensors
 prod_force_virial(atom_ener: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor] [source]
Compute force and virial
 Parameters
 atom_ener
The atomic energy
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 Returns
force
The force on atoms
virial
The total virial
atom_virial
The atomic virial
deepmd.descriptor.loc_frame module
 class deepmd.descriptor.loc_frame.DescrptLocFrame(*args, **kwargs)[source]
Bases:
deepmd.descriptor.descriptor.Descriptor
Defines a local frame at each atom, and the compute the descriptor as local coordinates under this frame.
 Parameters
 rcut
The cutoff radius
 sel_a
list
[str
] The length of the list should be the same as the number of atom types in the system. sel_a[i] gives the selected number of typei neighbors. The full relative coordinates of the neighbors are used by the descriptor.
 sel_r
list
[str
] The length of the list should be the same as the number of atom types in the system. sel_r[i] gives the selected number of typei neighbors. Only relative distance of the neighbors are used by the descriptor. sel_a[i] + sel_r[i] is recommended to be larger than the maximally possible number of typei neighbors in the cutoff radius.
 axis_rule: list[int]
The length should be 6 times of the number of types.  axis_rule[i*6+0]: class of the atom defining the first axis of typei atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.
axis_rule[i*6+1]: type of the atom defining the first axis of typei atom.
axis_rule[i*6+2]: index of the axis atom defining the first axis. Note that the neighbors with the same class and type are sorted according to their relative distance.
axis_rule[i*6+3]: class of the atom defining the first axis of typei atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.
axis_rule[i*6+4]: type of the atom defining the second axis of typei atom.
axis_rule[i*6+5]: class of the atom defining the second axis of typei atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Returns the output dimension of this descriptor
get_dim_rot_mat_1
()Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
 Returns
Returns the number of atom types
get_rcut
()Returns the cutoff radisu
Get rotational matrix
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(*tensors)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: dict, reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
 compute_input_stats(data_coord: list, data_box: list, data_atype: list, natoms_vec: list, mesh: list, input_dict: dict) None [source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
The coordinates. Can be generated by deepmd.model.make_stat_input
 data_box
The box. Can be generated by deepmd.model.make_stat_input
 data_atype
The atom types. Can be generated by deepmd.model.make_stat_input
 natoms_vec
The vector for the number of atoms of the system and different types of atoms. Can be generated by deepmd.model.make_stat_input
 mesh
The mesh for neighbor searching. Can be generated by deepmd.model.make_stat_input
 input_dict
Dictionary for additional input
 get_nlist() Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, List[int], List[int]] [source]
 Returns
nlist
Neighbor list
rij
The relative distance between the neighbor and the center atom.
sel_a
The number of neighbors with full information
sel_r
The number of neighbors with only radial information
 init_variables(graph: tensorflow.python.framework.ops.Graph, graph_def: tensorflow.core.framework.graph_pb2.GraphDef, suffix: str = '') None [source]
Init the embedding net variables with the given dict
 prod_force_virial(atom_ener: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor] [source]
Compute force and virial
 Parameters
 atom_ener
The atomic energy
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 Returns
force
The force on atoms
virial
The total virial
atom_virial
The atomic virial
deepmd.descriptor.se module
 class deepmd.descriptor.se.DescrptSe(*args, **kwargs)[source]
Bases:
deepmd.descriptor.descriptor.Descriptor
A base class for smooth version of descriptors.
Notes
All of these descriptors have an environmental matrix and an embedding network (
deepmd.utils.network.embedding_net()
), so they can share some similiar methods without defining them twice. Attributes
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor.
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
get_dim_out
()Returns the output dimension of this descriptor.
get_dim_rot_mat_1
()Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
get_nlist
()Returns neighbor information.
get_ntypes
()Returns the number of atom types.
get_rcut
()Returns the cutoff radius.
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(descrpt_reshape, ...)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial.
register
(key)Regiester a descriptor plugin.
 init_variables(graph: tensorflow.python.framework.ops.Graph, graph_def: tensorflow.core.framework.graph_pb2.GraphDef, suffix: str = '') None [source]
Init the embedding net variables with the given dict
 pass_tensors_from_frz_model(descrpt_reshape: tensorflow.python.framework.ops.Tensor, descrpt_deriv: tensorflow.python.framework.ops.Tensor, rij: tensorflow.python.framework.ops.Tensor, nlist: tensorflow.python.framework.ops.Tensor)[source]
Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
 Parameters
 descrpt_reshape
The passed descrpt_reshape tensor
 descrpt_deriv
The passed descrpt_deriv tensor
 rij
The passed rij tensor
 nlist
The passed nlist tensor
 property precision: tensorflow.python.framework.dtypes.DType
Precision of filter network.
deepmd.descriptor.se_a module
 class deepmd.descriptor.se_a.DescrptSeA(*args, **kwargs)[source]
Bases:
deepmd.descriptor.se.DescrptSe
DeepPotSE constructed from all information (both angular and radial) of atomic configurations. The embedding takes the distance between atoms as input.
The descriptor \(\mathcal{D}^i \in \mathcal{R}^{M_1 \times M_2}\) is given by [1]
\[\mathcal{D}^i = (\mathcal{G}^i)^T \mathcal{R}^i (\mathcal{R}^i)^T \mathcal{G}^i_<\]where \(\mathcal{R}^i \in \mathbb{R}^{N \times 4}\) is the coordinate matrix, and each row of \(\mathcal{R}^i\) can be constructed as follows
\[(\mathcal{R}^i)_j = [ \begin{array}{c} s(r_{ji}) & \frac{s(r_{ji})x_{ji}}{r_{ji}} & \frac{s(r_{ji})y_{ji}}{r_{ji}} & \frac{s(r_{ji})z_{ji}}{r_{ji}} \end{array} ]\]where \(\mathbf{R}_{ji}=\mathbf{R}_j\mathbf{R}_i = (x_{ji}, y_{ji}, z_{ji})\) is the relative coordinate and \(r_{ji}=\lVert \mathbf{R}_{ji} \lVert\) is its norm. The switching function \(s(r)\) is defined as:
\[\begin{split}s(r)= \begin{cases} \frac{1}{r}, & r<r_s \\ \frac{1}{r} \{ {(\frac{r  r_s}{ r_c  r_s})}^3 (6 {(\frac{r  r_s}{ r_c  r_s})}^2 +15 \frac{r  r_s}{ r_c  r_s} 10) +1 \}, & r_s \leq r<r_c \\ 0, & r \geq r_c \end{cases}\end{split}\]Each row of the embedding matrix \(\mathcal{G}^i \in \mathbb{R}^{N \times M_1}\) consists of outputs of a embedding network \(\mathcal{N}\) of \(s(r_{ji})\):
\[(\mathcal{G}^i)_j = \mathcal{N}(s(r_{ji}))\]\(\mathcal{G}^i_< \in \mathbb{R}^{N \times M_2}\) takes first \(M_2\) columns of \(\mathcal{G}^i\). The equation of embedding network \(\mathcal{N}\) can be found at
deepmd.utils.network.embedding_net()
. Parameters
 rcut
The cutoff radius \(r_c\)
 rcut_smth
From where the environment matrix should be smoothed \(r_s\)
 sel
list
[str
] sel[i] specifies the maxmum number of type i atoms in the cutoff radius
 neuron
list
[int
] Number of neurons in each hidden layers of the embedding net \(\mathcal{N}\)
 axis_neuron
Number of the axis neuron \(M_2\) (number of columns of the submatrix of the embedding matrix)
 resnet_dt
Timestep dt in the resnet construction: y = x + dt * phi (Wx + b)
 trainable
If the weights of embedding net are trainable.
 seed
Random seed for initializing the network parameters.
 type_one_side
Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets
 exclude_types
List
[List
[int
]] The excluded pairs of types which have no interaction with each other. For example, [[0, 1]] means no interaction between type 0 and type 1.
 set_davg_zero
Set the shift of embedding net input to zero.
 activation_function
The activation function in the embedding net. Supported options are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.
 precision
The precision of the embedding net parameters. Supported options are “default”, “float16”, “float32”, “float64”.
 uniform_seed
Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed
References
 1(1,2)
Linfeng Zhang, Jiequn Han, Han Wang, Wissam A. Saidi, Roberto Car, and E. Weinan. 2018. Endtoend symmetry preserving interatomic potential energy model for finite and extended systems. In Proceedings of the 32nd International Conference on Neural Information Processing Systems (NIPS’18). Curran Associates Inc., Red Hook, NY, USA, 4441–4451.
 Attributes
precision
Precision of filter network.
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Returns the output dimension of this descriptor
Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
 Returns
Returns the number of atom types
get_rcut
()Returns the cutoff radius
Get rotational matrix
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(descrpt_reshape, ...)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: dict, reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
 compute_input_stats(data_coord: list, data_box: list, data_atype: list, natoms_vec: list, mesh: list, input_dict: dict) None [source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
The coordinates. Can be generated by deepmd.model.make_stat_input
 data_box
The box. Can be generated by deepmd.model.make_stat_input
 data_atype
The atom types. Can be generated by deepmd.model.make_stat_input
 natoms_vec
The vector for the number of atoms of the system and different types of atoms. Can be generated by deepmd.model.make_stat_input
 mesh
The mesh for neighbor searching. Can be generated by deepmd.model.make_stat_input
 input_dict
Dictionary for additional input
 enable_compression(min_nbor_dist: float, model_file: str = 'frozon_model.pb', table_extrapolate: float = 5, table_stride_1: float = 0.01, table_stride_2: float = 0.1, check_frequency: int =  1, suffix: str = '') None [source]
Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
 Parameters
 min_nbor_dist
The nearest distance between atoms
 model_file
The original frozen model, which will be compressed by the program
 table_extrapolate
The scale of model extrapolation
 table_stride_1
The uniform stride of the first table
 table_stride_2
The uniform stride of the second table
 check_frequency
The overflow check frequency
 suffix
str
,optional
The suffix of the scope
 enable_mixed_precision(mixed_prec: Optional[dict] = None) None [source]
Reveive the mixed precision setting.
 Parameters
 mixed_prec
The mixed precision setting used in the embedding net
 get_dim_rot_mat_1() int [source]
Returns the first dimension of the rotation matrix. The rotation is of shape dim_1 x 3
 get_nlist() Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, List[int], List[int]] [source]
 Returns
nlist
Neighbor list
rij
The relative distance between the neighbor and the center atom.
sel_a
The number of neighbors with full information
sel_r
The number of neighbors with only radial information
 init_variables(graph: tensorflow.python.framework.ops.Graph, graph_def: tensorflow.core.framework.graph_pb2.GraphDef, suffix: str = '') None [source]
Init the embedding net variables with the given dict
 prod_force_virial(atom_ener: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor] [source]
Compute force and virial
 Parameters
 atom_ener
The atomic energy
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 Returns
force
The force on atoms
virial
The total virial
atom_virial
The atomic virial
deepmd.descriptor.se_a_ebd module
 class deepmd.descriptor.se_a_ebd.DescrptSeAEbd(*args, **kwargs)[source]
Bases:
deepmd.descriptor.se_a.DescrptSeA
DeepPotSE descriptor with type embedding approach.
 Parameters
 rcut
The cutoff radius
 rcut_smth
From where the environment matrix should be smoothed
 sel
list
[str
] sel[i] specifies the maxmum number of type i atoms in the cutoff radius
 neuron
list
[int
] Number of neurons in each hidden layers of the embedding net
 axis_neuron
Number of the axis neuron (number of columns of the submatrix of the embedding matrix)
 resnet_dt
Timestep dt in the resnet construction: y = x + dt * phi (Wx + b)
 trainable
If the weights of embedding net are trainable.
 seed
Random seed for initializing the network parameters.
 type_one_side
Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets
 type_nchanl
Number of channels for type representation
 type_nlayer
Number of hidden layers for the type embedding net (skip connected).
 numb_aparam
Number of atomic parameters. If >0 it will be embedded with atom types.
 set_davg_zero
Set the shift of embedding net input to zero.
 activation_function
The activation function in the embedding net. Supported options are {0}
 precision
The precision of the embedding net parameters. Supported options are {1}
 exclude_types
List
[List
[int
]] The excluded pairs of types which have no interaction with each other. For example, [[0, 1]] means no interaction between type 0 and type 1.
 Attributes
precision
Precision of filter network.
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
get_dim_out
()Returns the output dimension of this descriptor
get_dim_rot_mat_1
()Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
get_nlist
() Returns
get_ntypes
()Returns the number of atom types
get_rcut
()Returns the cutoff radius
get_rot_mat
()Get rotational matrix
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(descrpt_reshape, ...)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: dict, reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
deepmd.descriptor.se_a_ef module
 class deepmd.descriptor.se_a_ef.DescrptSeAEf(*args, **kwargs)[source]
Bases:
deepmd.descriptor.descriptor.Descriptor
 Parameters
 rcut
The cutoff radius
 rcut_smth
From where the environment matrix should be smoothed
 sel
list
[str
] sel[i] specifies the maxmum number of type i atoms in the cutoff radius
 neuron
list
[int
] Number of neurons in each hidden layers of the embedding net
 axis_neuron
Number of the axis neuron (number of columns of the submatrix of the embedding matrix)
 resnet_dt
Timestep dt in the resnet construction: y = x + dt * phi (Wx + b)
 trainable
If the weights of embedding net are trainable.
 seed
Random seed for initializing the network parameters.
 type_one_side
Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets
 exclude_types
List
[List
[int
]] The excluded pairs of types which have no interaction with each other. For example, [[0, 1]] means no interaction between type 0 and type 1.
 set_davg_zero
Set the shift of embedding net input to zero.
 activation_function
The activation function in the embedding net. Supported options are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.
 precision
The precision of the embedding net parameters. Supported options are “default”, “float16”, “float32”, “float64”.
 uniform_seed
Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Returns the output dimension of this descriptor
Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
 Returns
Returns the number of atom types
get_rcut
()Returns the cutoff radisu
Get rotational matrix
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(*tensors)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: dict, reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs. Should have ‘efield’.
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
 compute_input_stats(data_coord: list, data_box: list, data_atype: list, natoms_vec: list, mesh: list, input_dict: dict) None [source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
The coordinates. Can be generated by deepmd.model.make_stat_input
 data_box
The box. Can be generated by deepmd.model.make_stat_input
 data_atype
The atom types. Can be generated by deepmd.model.make_stat_input
 natoms_vec
The vector for the number of atoms of the system and different types of atoms. Can be generated by deepmd.model.make_stat_input
 mesh
The mesh for neighbor searching. Can be generated by deepmd.model.make_stat_input
 input_dict
Dictionary for additional input
 get_dim_rot_mat_1() int [source]
Returns the first dimension of the rotation matrix. The rotation is of shape dim_1 x 3
 get_nlist() Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, List[int], List[int]] [source]
 Returns
nlist
Neighbor list
rij
The relative distance between the neighbor and the center atom.
sel_a
The number of neighbors with full information
sel_r
The number of neighbors with only radial information
 prod_force_virial(atom_ener: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor] [source]
Compute force and virial
 Parameters
 atom_ener
The atomic energy
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 Returns
force
The force on atoms
virial
The total virial
atom_virial
The atomic virial
 class deepmd.descriptor.se_a_ef.DescrptSeAEfLower(*args, **kwargs)[source]
Bases:
deepmd.descriptor.se_a.DescrptSeA
Helper class for implementing DescrptSeAEf
 Attributes
precision
Precision of filter network.
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
get_dim_out
()Returns the output dimension of this descriptor
get_dim_rot_mat_1
()Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
get_nlist
() Returns
get_ntypes
()Returns the number of atom types
get_rcut
()Returns the cutoff radius
get_rot_mat
()Get rotational matrix
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(descrpt_reshape, ...)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_, atype_, natoms, box_, mesh, input_dict, suffix='', reuse=None)[source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
 compute_input_stats(data_coord, data_box, data_atype, natoms_vec, mesh, input_dict)[source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
The coordinates. Can be generated by deepmd.model.make_stat_input
 data_box
The box. Can be generated by deepmd.model.make_stat_input
 data_atype
The atom types. Can be generated by deepmd.model.make_stat_input
 natoms_vec
The vector for the number of atoms of the system and different types of atoms. Can be generated by deepmd.model.make_stat_input
 mesh
The mesh for neighbor searching. Can be generated by deepmd.model.make_stat_input
 input_dict
Dictionary for additional input
deepmd.descriptor.se_r module
 class deepmd.descriptor.se_r.DescrptSeR(*args, **kwargs)[source]
Bases:
deepmd.descriptor.se.DescrptSe
DeepPotSE constructed from radial information of atomic configurations.
The embedding takes the distance between atoms as input.
 Parameters
 rcut
The cutoff radius
 rcut_smth
From where the environment matrix should be smoothed
 sel
list
[str
] sel[i] specifies the maxmum number of type i atoms in the cutoff radius
 neuron
list
[int
] Number of neurons in each hidden layers of the embedding net
 resnet_dt
Timestep dt in the resnet construction: y = x + dt * phi (Wx + b)
 trainable
If the weights of embedding net are trainable.
 seed
Random seed for initializing the network parameters.
 type_one_side
Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets
 exclude_types
List
[List
[int
]] The excluded pairs of types which have no interaction with each other. For example, [[0, 1]] means no interaction between type 0 and type 1.
 activation_function
The activation function in the embedding net. Supported options are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.
 precision
The precision of the embedding net parameters. Supported options are “default”, “float16”, “float32”, “float64”.
 uniform_seed
Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed
 Attributes
precision
Precision of filter network.
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Returns the output dimension of this descriptor
get_dim_rot_mat_1
()Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
 Returns
Returns the number of atom types
get_rcut
()Returns the cutoff radisu
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(descrpt_reshape, ...)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: dict, reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
 compute_input_stats(data_coord, data_box, data_atype, natoms_vec, mesh, input_dict)[source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
The coordinates. Can be generated by deepmd.model.make_stat_input
 data_box
The box. Can be generated by deepmd.model.make_stat_input
 data_atype
The atom types. Can be generated by deepmd.model.make_stat_input
 natoms_vec
The vector for the number of atoms of the system and different types of atoms. Can be generated by deepmd.model.make_stat_input
 mesh
The mesh for neighbor searching. Can be generated by deepmd.model.make_stat_input
 input_dict
Dictionary for additional input
 enable_compression(min_nbor_dist: float, model_file: str = 'frozon_model.pb', table_extrapolate: float = 5, table_stride_1: float = 0.01, table_stride_2: float = 0.1, check_frequency: int =  1, suffix: str = '') None [source]
Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
 Parameters
 min_nbor_dist
The nearest distance between atoms
 model_file
The original frozen model, which will be compressed by the program
 table_extrapolate
The scale of model extrapolation
 table_stride_1
The uniform stride of the first table
 table_stride_2
The uniform stride of the second table
 check_frequency
The overflow check frequency
 suffix
str
,optional
The suffix of the scope
 get_nlist()[source]
 Returns
nlist
Neighbor list
rij
The relative distance between the neighbor and the center atom.
sel_a
The number of neighbors with full information
sel_r
The number of neighbors with only radial information
 prod_force_virial(atom_ener: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor] [source]
Compute force and virial
 Parameters
 atom_ener
The atomic energy
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 Returns
force
The force on atoms
virial
The total virial
atom_virial
The atomic virial
deepmd.descriptor.se_t module
 class deepmd.descriptor.se_t.DescrptSeT(*args, **kwargs)[source]
Bases:
deepmd.descriptor.se.DescrptSe
DeepPotSE constructed from all information (both angular and radial) of atomic configurations.
The embedding takes angles between two neighboring atoms as input.
 Parameters
 rcut
The cutoff radius
 rcut_smth
From where the environment matrix should be smoothed
 sel
list
[str
] sel[i] specifies the maxmum number of type i atoms in the cutoff radius
 neuron
list
[int
] Number of neurons in each hidden layers of the embedding net
 resnet_dt
Timestep dt in the resnet construction: y = x + dt * phi (Wx + b)
 trainable
If the weights of embedding net are trainable.
 seed
Random seed for initializing the network parameters.
 set_davg_zero
Set the shift of embedding net input to zero.
 activation_function
The activation function in the embedding net. Supported options are “relu”, “relu6”, “softplus”, “sigmoid”, “tanh”, “gelu”, “gelu_tf”.
 precision
The precision of the embedding net parameters. Supported options are “default”, “float16”, “float32”, “float64”.
 uniform_seed
Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed
 Attributes
precision
Precision of filter network.
Methods
build
(coord_, atype_, natoms, box_, mesh, ...)Build the computational graph for the descriptor
compute_input_stats
(data_coord, data_box, ...)Compute the statisitcs (avg and std) of the training data.
enable_compression
(min_nbor_dist[, ...])Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Returns the output dimension of this descriptor
get_dim_rot_mat_1
()Returns the first dimension of the rotation matrix.
get_feed_dict
(coord_, atype_, natoms, box, mesh)Generate the feed_dict for current descriptor
 Returns
Returns the number of atom types
get_rcut
()Returns the cutoff radisu
get_tensor_names
([suffix])Get names of tensors.
init_variables
(graph, graph_def[, suffix])Init the embedding net variables with the given dict
pass_tensors_from_frz_model
(descrpt_reshape, ...)Pass the descrpt_reshape tensor as well as descrpt_deriv tensor from the frz graph_def
prod_force_virial
(atom_ener, natoms)Compute force and virial
register
(key)Regiester a descriptor plugin.
 build(coord_: tensorflow.python.framework.ops.Tensor, atype_: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, box_: tensorflow.python.framework.ops.Tensor, mesh: tensorflow.python.framework.ops.Tensor, input_dict: dict, reuse: Optional[bool] = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for the descriptor
 Parameters
 coord_
The coordinate of atoms
 atype_
The type of atoms
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 mesh
For historical reasons, only the length of the Tensor matters. if size of mesh == 6, pbc is assumed. if size of mesh == 0, nopbc is assumed.
 input_dict
Dictionary for additional inputs
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
descriptor
The output descriptor
 compute_input_stats(data_coord: list, data_box: list, data_atype: list, natoms_vec: list, mesh: list, input_dict: dict) None [source]
Compute the statisitcs (avg and std) of the training data. The input will be normalized by the statistics.
 Parameters
 data_coord
The coordinates. Can be generated by deepmd.model.make_stat_input
 data_box
The box. Can be generated by deepmd.model.make_stat_input
 data_atype
The atom types. Can be generated by deepmd.model.make_stat_input
 natoms_vec
The vector for the number of atoms of the system and different types of atoms. Can be generated by deepmd.model.make_stat_input
 mesh
The mesh for neighbor searching. Can be generated by deepmd.model.make_stat_input
 input_dict
Dictionary for additional input
 enable_compression(min_nbor_dist: float, model_file: str = 'frozon_model.pb', table_extrapolate: float = 5, table_stride_1: float = 0.01, table_stride_2: float = 0.1, check_frequency: int =  1, suffix: str = '') None [source]
Reveive the statisitcs (distance, max_nbor_size and env_mat_range) of the training data.
 Parameters
 min_nbor_dist
The nearest distance between atoms
 model_file
The original frozen model, which will be compressed by the program
 table_extrapolate
The scale of model extrapolation
 table_stride_1
The uniform stride of the first table
 table_stride_2
The uniform stride of the second table
 check_frequency
The overflow check frequency
 suffix
str
,optional
The suffix of the scope
 get_nlist() Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, List[int], List[int]] [source]
 Returns
nlist
Neighbor list
rij
The relative distance between the neighbor and the center atom.
sel_a
The number of neighbors with full information
sel_r
The number of neighbors with only radial information
 prod_force_virial(atom_ener: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor) Tuple[tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor, tensorflow.python.framework.ops.Tensor] [source]
Compute force and virial
 Parameters
 atom_ener
The atomic energy
 natoms
The number of atoms. This tensor has the length of Ntypes + 2 natoms[0]: number of local atoms natoms[1]: total number of atoms held by this processor natoms[i]: 2 <= i < Ntypes+2, number of type i atoms
 Returns
force
The force on atoms
virial
The total virial
atom_virial
The atomic virial
deepmd.entrypoints package
Submodule that contains all the DeePMDKit entry point scripts.
 deepmd.entrypoints.compress(*, input: str, output: str, extrapolate: int, step: float, frequency: str, checkpoint_folder: str, training_script: str, mpi_log: str, log_path: Optional[str], log_level: int, **kwargs)[source]
Compress model.
The table is composed of fifthorder polynomial coefficients and is assembled from two subtables. The first table takes the step parameter as the domain’s uniform step size, while the second table takes 10 * step as it’s uniform step size. The range of the first table is automatically detected by the code, while the second table ranges from the first table’s upper boundary(upper) to the extrapolate(parameter) * upper.
 Parameters
 input
str
frozen model file to compress
 output
str
compressed model filename
 extrapolate
int
scale of model extrapolation
 step
float
uniform step size of the tabulation’s first table
 frequency
str
frequency of tabulation overflow check
 checkpoint_folder
str
trining checkpoint folder for freezing
 training_script
str
training script of the input frozen model
 mpi_log
str
mpi logging mode for training
 log_path
Optional
[str
] if speccified log will be written to this file
 log_level
int
logging level
 input
 deepmd.entrypoints.config(*, output: str, **kwargs)[source]
Auto config file generator.
 Parameters
 output: str
file to write config file
 Raises
RuntimeError
if user does not input any systems
ValueError
if output file is of wrong type
 deepmd.entrypoints.doc_train_input(*, out_type: str = 'rst', **kwargs)[source]
Print out trining input arguments to console.
 deepmd.entrypoints.freeze(*, checkpoint_folder: str, output: str, node_names: Optional[str] = None, nvnmd_weight: Optional[str] = None, **kwargs)[source]
Freeze the graph in supplied folder.
 deepmd.entrypoints.make_model_devi(*, models: list, system: str, set_prefix: str, output: str, frequency: int, **kwargs)[source]
Make model deviation calculation
 Parameters
 models: list
A list of paths of models to use for making model deviation
 system: str
The path of system to make model deviation calculation
 set_prefix: str
The set prefix of the system
 output: str
The output file for model deviation results
 frequency: int
The number of steps that elapse between writing coordinates in a trajectory by a MD engine (such as Gromacs / Lammps). This paramter is used to determine the index in the output file.
 deepmd.entrypoints.neighbor_stat(*, system: str, rcut: float, type_map: List[str], **kwargs)[source]
Calculate neighbor statistics.
Examples
>>> neighbor_stat(system='.', rcut=6., type_map=["C", "H", "O", "N", "P", "S", "Mg", "Na", "HW", "OW", "mNa", "mCl", "mC", "mH", "mMg", "mN", "mO", "mP"]) min_nbor_dist: 0.6599510670195264 max_nbor_size: [23, 26, 19, 16, 2, 2, 1, 1, 72, 37, 5, 0, 31, 29, 1, 21, 20, 5]
 deepmd.entrypoints.test(*, model: str, system: str, set_prefix: str, numb_test: int, rand_seed: Optional[int], shuffle_test: bool, detail_file: str, atomic: bool, **kwargs)[source]
Test model predictions.
 Parameters
 model
str
path where model is stored
 system
str
system directory
 set_prefix
str
string prefix of set
 numb_test
int
munber of tests to do
 rand_seed
Optional
[int
] seed for random generator
 shuffle_testbool
whether to shuffle tests
 detail_file
Optional
[str
] file where test details will be output
 atomicbool
whether per atom quantities should be computed
 model
 Raises
RuntimeError
if no valid system was found
 deepmd.entrypoints.train_dp(*, INPUT: str, init_model: Optional[str], restart: Optional[str], output: str, init_frz_model: str, mpi_log: str, log_level: int, log_path: Optional[str], is_compress: bool = False, skip_neighbor_stat: bool = False, **kwargs)
Run DeePMD model training.
 Parameters
 INPUT
str
json/yaml control file
 init_model
Optional
[str
] path to checkpoint folder or None
 restart
Optional
[str
] path to checkpoint folder or None
 output
str
path for dump file with arguments
 init_frz_model
str
path to frozen model or None
 mpi_log
str
mpi logging mode
 log_level
int
logging level defined by int 03
 log_path
Optional
[str
] logging file path or None if logs are to be output only to stdout
 is_compress: bool
indicates whether in the model compress mode
 skip_neighbor_statbool, default=False
skip checking neighbor statistics
 INPUT
 Raises
RuntimeError
if distributed training job nem is wrong