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.0.0cuda11.3_gpuLinuxx86_64.sh.0 deepmdkit2.0.0cuda11.3_gpuLinuxx86_64.sh.1 > deepmdkit2.0.0cuda11.3_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 lammpsdp c https://conda.deepmodeling.org
Or one may want to create a GPU environment containing CUDA Toolkit:
conda create n deepmd deepmdkit=*=*gpu libdeepmd=*=*gpu lammpsdp cudatoolkit=11.3 horovod c https://conda.deepmodeling.org
One could change the CUDA Toolkit version from 10.1
or 11.3
.
One may speficy the DeePMDkit version such as 2.0.0
using
conda create n deepmd deepmdkit=2.0.0=*cpu libdeepmd=2.0.0=*cpu lammpsdp=2.0.0 horovod c https://conda.deepmodeling.org
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.0.0_cpu
To pull the GPU version:
docker pull ghcr.io/deepmodeling/deepmdkit:2.0.0_cuda10.1_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.
Training 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.0.0cuda11.3_gpuLinuxx86_64.sh.0 deepmdkit2.0.0cuda11.3_gpuLinuxx86_64.sh.1 > deepmdkit2.0.0cuda11.3_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 lammpsdp c https://conda.deepmodeling.org
Or one may want to create a GPU environment containing CUDA Toolkit:
conda create n deepmd deepmdkit=*=*gpu libdeepmd=*=*gpu lammpsdp cudatoolkit=11.3 horovod c https://conda.deepmodeling.org
One could change the CUDA Toolkit version from 10.1
or 11.3
.
One may speficy the DeePMDkit version such as 2.0.0
using
conda create n deepmd deepmdkit=2.0.0=*cpu libdeepmd=2.0.0=*cpu lammpsdp=2.0.0 horovod c https://conda.deepmodeling.org
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.0.0_cpu
To pull the GPU version:
docker pull ghcr.io/deepmodeling/deepmdkit:2.0.0_cuda10.1_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. 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.
Install the DeePMDkit’s python interface
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. 
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
Check the compiler version on your machine
gcc version
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.
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 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. 
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). 
DLAMMPS_SOURCE_ROOT=<value> 
Path 
 
Only neccessary for LAMMPS plugin mode. The path to the LAMMPS source code (later than 8Apr2021). 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)
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 (29Oct2020
or later), and uncompress it:
cd /some/workspace
wget https://github.com/lammps/lammps/archive/stable_29Sep2021_update3.tar.gz
tar xf stable_29Sep2021_update3.tar.gz
The source code of LAMMPS is stored in directory lammpsstable_29Sep2021_update3
. Now go into the LAMMPS code and copy the DeePMDkit module like this
cd lammpsstable_29Sep2021_update3/src/
cp r $deepmd_source_dir/source/build/USERDEEPMD .
Now build LAMMPS
make yeskspace
make yesuserdeepmd
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_29Sep2021_update3.tar.gz
tar xf stable_29Sep2021_update3.tar.gz
The source code of LAMMPS is stored in directory lammpsstable_29Sep2021_update3
. Now go into the LAMMPS directory and create a directory called build
mkdir p lammpsstable_29Sep2021_update3/build/
cd lammpsstable_29Sep2021_update3/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
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 lammpsdpfeedstock
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 lammpsdp c file:///path/to/build_artifacts c https://conda.deepmodeling.org 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 short 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.
Data conversion
One needs to provide the following information to train a model: the atom type, the simulation box, the atom coordinate, the atom force, system energy and virial. A snapshot of a system that contains these information is called a frame. We use the following convention of units:
Property 
Unit 

Time 
ps 
Length 
Å 
Energy 
eV 
Force 
eV/Å 
Virial 
eV 
Pressure 
Bar 
The frames of the system are stored in two formats. A raw file is a plain text file with each information item written in one file and one frame written on one line. The default files that provide box, coordinate, force, energy and virial are box.raw
, coord.raw
, force.raw
, energy.raw
and virial.raw
, respectively. We recommend you use these file names. 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. The coordinate file coord.raw
is organized similarly. In box.raw
, the 9 components of the box vectors should be provided on each line in the order XX XY XZ YX YY YZ ZX ZY ZZ
. In virial.raw
, the 9 components of the virial tensor should be provided on each line in the order XX XY XZ YX YY YZ ZX ZY ZZ
. The number of lines of all raw files should be identical.
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"
.
The second format is the data sets of numpy
binary data that are directly used by the training program. User can use the script $deepmd_source_dir/data/raw/raw_to_set.sh
to convert the prepared raw files to data sets. 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. One do not need to take care of the binary data files in each of the set.*
directories. The path containing set.*
and type.raw
is called a system.
If one needs to train a nonperiodic system, an empty nopbc
file should be put under the system directory. box.raw
is not necessary in a nonperiodic system.
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" : {
"...": "..."
}
}
Assume that we are looking for a model for water, we will have two types of atoms. The atom types are recorded as integers. In this example, we denote 0
for oxygen and 1
for hydrogen. A mapping from the atom type to their names is provided by type_map
.
The model has two subsections descritpor
and fitting_net
, which defines the descriptor and the fitting net, respectively. The type_map
is optional, which provides the element names (but not necessarily to be the element name) of the corresponding atom types.
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 thercut_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, andsel[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 totrue
, 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 paperIf the option
resnet_dt
is settrue
, 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
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 D_1, D_2, …, D_N, the hybrid descriptor this the concatenation of the list, i.e. D = (D_1, D_2, …, 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.
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 settrue
, 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 for training energy is given by
loss = pref_e * loss_e + pref_f * loss_f + pref_v * loss_v
where loss_e
, loss_f
and loss_v
denote the loss in energy, force and virial, respectively. pref_e
, pref_f
and pref_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
pref_f(t) = start_pref_f * ( lr(t) / start_lr ) + limit_pref_f * ( 1  lr(t) / start_lr )
where lr(t)
denotes the learning rate at step t
. start_pref_f
and limit_pref_f
specifies the pref_f
at the start of the training and at the limit of t > inf
.
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 API to allow 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
.
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 astensor
as a distinction fromener
mode.pref
andpref_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 theneuron
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 settrue
, 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 A^{1}) gives the spread parameter controls the spread of Gaussian charges, and "ewald_h"
(unit A) 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.
Training
Training 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
tostop_lr
following the formula.lr(t) = start_lr * decay_rate ^ ( t / decay_steps )
where
t
is the training step.
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_step": 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 alist
or astr
.list
:systems
gives the training data systems.str
:systems
should be a valid path. DeePMDkit will recursively search all data systems in this path.
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 keyauto_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_prob"
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_prob": [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 tolist
: the length of which is the same as thesystems
. 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 thebatch_size
times the number of atoms in the system is no less thanN
.
The key
numb_batch
invalidate_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, onlyfloat32
is supported currently.compute_prec
precision used in the computing tensors, onlyfloat16
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_step
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 stepssave_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”.
 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:float64
argument path:model/type_embedding/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 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:
str
list
, 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”.
 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:float64
argument path:model/descriptor[se_e2_a]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 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:
str
list
, 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”.
 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:float64
argument path:model/descriptor[se_e3]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 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:
str
list
, 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”.
 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:float64
argument path:model/descriptor[se_a_tpe]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 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:
str
list
, 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”.
 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:float64
argument path:model/descriptor[se_e2_r]/precision
The precision of the embedding net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 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”.
 precision:
 type:
str
, optional, default:float64
argument path:model/fitting_net[ener]/precision
The precision of the fitting net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 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:
bool
list
, 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”.
 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:float64
argument path:model/fitting_net[dipole]/precision
The precision of the fitting net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 sel_type:
 type:
int
list
NoneType
, 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”.
 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:float64
argument path:model/fitting_net[polar]/precision
The precision of the fitting net parameters, supported options are “default”, “float16”, “float32”, “float64”.
 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:
float
list
, 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:
int
list
NoneType
, 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.
 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:

The type of the loss. When the fitting type is ener, the loss type should be set to ener or left unset. When the fitting type is dipole or polar, the loss type should be set to tensor. .
When type is set to
ener
: start_pref_e:
 type:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
int
, 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:
float
NoneType
, 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.
When type is set to
tensor
: pref:
 type:
float
int
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:
float
int
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.
 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.
 training:
 type:
dict
argument path:training
The training options.
 training_data:
 type:
dict
argument path:training/training_data
Configurations of training data.
 systems:
 type:
str
list
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:
int
str
list
, 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:
dict
NoneType
, 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:
str
list
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:
int
str
list
, 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.
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” 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 I $tensorflow_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
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
Df_i
Ef_i = 
f_i + level
where Df_i
is the absolute model deviation of the force on atom i
, f_i
is the norm of the the force and level
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 is the atomic position of nth atom, velocity of atom and 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.
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 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 M1 dimension by a embedding net
, so the environment matrix R
can be embed into matrix G
. We can thus extract a descriptor vector (of M1*M2 dim) of the centric atom from the 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.
Symbol 
Meaning 

i 
Type of centric atom 
j 
Type of neighbor atom 
s_ij 
Distance between centric atom and neighbor atom 
G_ij(·) 
Origin embedding net, take s_ij as input and output embedding vector of M1 dim 
G(·) 
Shared embedding net 
Multi(·) 
Matrix multiplication and flattening, output the descriptor vector of M1*M2 dim 
F_i(·) 
Origin fitting net, take the descriptor vector as input and output energy 
F(·) 
Shared fitting net 
A(·) 
Atom type embedding net, input is atom type, output is type embedding vector of dim 
So, we can formulate the training process as follows. Vanilla deepmdkit algorithm:
Energy = F_i( Multi( G_ij( s_ij ) ) )
Deepmdkit applying atom type embedding:
Energy = F( [ Multi( G( [s_ij, A(i), A(j)] ) ), A(j)] )
or
Energy = F( [ Multi( G( [s_ij, A(j)] ) ), A(j)] )
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 [ntypes * nchanl] dimension). 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 R
as input and output matrix 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 (G^T·R
), do further multiplication involved in Multi(·), and finally output the result of descriptor vector of M1*M2 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 inputR
(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 oftype_one_side
(if set True, then we only use the vector of the neighbor atom). The modified input will be put into thefitting net
to getG
for further matrix multiplication stage.
fitting net (fit/ener.py)
In fitting net
, it take the descriptor vector as input, whose dimension is [natoms, (M1*M2)]. 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 {0}
 precision
The precision of the embedding net parameters. Supported options are {1}
 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 {0}
 precision
The precision of the embedding net parameters. Supported options are {1}
 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 {0}
 precision
The precision of the embedding net parameters. Supported options are {1}
 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 {0}
 precision
The precision of the embedding net parameters. Supported options are {1}
 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, **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
 deepmd.entrypoints.transfer(*, old_model: str, raw_model: str, output: str, **kwargs)[source]
Transfer operation from old fron graph to new prepared raw graph.
Submodules
deepmd.entrypoints.compress module
Compress a model, which including tabulating the embeddingnet.
 deepmd.entrypoints.compress.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 module
Quickly create a configuration file for smooth model.
 deepmd.entrypoints.config.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.convert module
deepmd.entrypoints.doc module
Module that prints train input arguments docstrings.
deepmd.entrypoints.freeze module
Script for freezing TF trained graph so it can be used with LAMMPS and iPI.
deepmd.entrypoints.main module
DeePMDKit entry point module.
 deepmd.entrypoints.main.get_ll(log_level: str) int [source]
Convert string to python logging level.
 deepmd.entrypoints.main.main()[source]
DeePMDKit entry point.
 Raises
RuntimeError
if no command was input
deepmd.entrypoints.neighbor_stat module
 deepmd.entrypoints.neighbor_stat.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 module
Test trained DeePMD model.
 deepmd.entrypoints.test.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 module
DeePMD training entrypoint script.
Can handle local or distributed training.
 deepmd.entrypoints.train.train(*, 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)[source]
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
deepmd.entrypoints.transfer module
Module used for transfering parameters between models.
deepmd.fit package
Submodules
deepmd.fit.dipole module
 class deepmd.fit.dipole.DipoleFittingSeA[source]
Bases:
deepmd.fit.fitting.Fitting
Fit the atomic dipole with descriptor se_a
 Parameters
 descrpt
tf.Tensor
The descrptor
 neuron
List
[int
] Number of neurons in each hidden layer of the fitting net
 resnet_dtbool
Timestep dt in the resnet construction: y = x + dt * phi (Wx + b)
 sel_type
List
[int
] The atom types selected to have an atomic dipole prediction. If is None, all atoms are selected.
 seed
int
Random seed for initializing the network parameters.
 activation_function
str
The activation function in the embedding net. Supported options are {0}
 precision
str
The precision of the embedding net parameters. Supported options are {1}
 uniform_seed
Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed
 descrpt
 Attributes
precision
Precision of fitting network.
Methods
build
(input_d, rot_mat, natoms[, reuse, suffix])Build the computational graph for fitting net
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Get the output size.
Get selected type
init_variables
(graph, graph_def[, suffix])Init the fitting net variables with the given dict
 build(input_d: tensorflow.python.framework.ops.Tensor, rot_mat: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, reuse: bool = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for fitting net
 Parameters
 input_d
The input descriptor
 rot_mat
The rotation matrix from the descriptor.
 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
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
dipole
The atomic dipole.
 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
deepmd.fit.ener module
 class deepmd.fit.ener.EnerFitting[source]
Bases:
deepmd.fit.fitting.Fitting
Fitting the energy of the system. The force and the virial can also be trained.
The potential energy \(E\) is a fitting network function of the descriptor \(\mathcal{D}\):
\[E(\mathcal{D}) = \mathcal{L}^{(n)} \circ \mathcal{L}^{(n1)} \circ \cdots \circ \mathcal{L}^{(1)} \circ \mathcal{L}^{(0)}\]The first \(n\) hidden layers \(\mathcal{L}^{(0)}, \cdots, \mathcal{L}^{(n1)}\) are given by
\[\mathbf{y}=\mathcal{L}(\mathbf{x};\mathbf{w},\mathbf{b})= \boldsymbol{\phi}(\mathbf{x}^T\mathbf{w}+\mathbf{b})\]where \(\mathbf{x} \in \mathbb{R}^{N_1}\) is the input vector and \(\mathbf{y} \in \mathbb{R}^{N_2}\) is the output vector. \(\mathbf{w} \in \mathbb{R}^{N_1 \times N_2}\) and \(\mathbf{b} \in \mathbb{R}^{N_2}\) are weights and biases, respectively, both of which are trainable if trainable[i] is True. \(\boldsymbol{\phi}\) is the activation function.
The output layer \(\mathcal{L}^{(n)}\) is given by
\[\mathbf{y}=\mathcal{L}^{(n)}(\mathbf{x};\mathbf{w},\mathbf{b})= \mathbf{x}^T\mathbf{w}+\mathbf{b}\]where \(\mathbf{x} \in \mathbb{R}^{N_{n1}}\) is the input vector and \(\mathbf{y} \in \mathbb{R}\) is the output scalar. \(\mathbf{w} \in \mathbb{R}^{N_{n1}}\) and \(\mathbf{b} \in \mathbb{R}\) are weights and bias, respectively, both of which are trainable if trainable[n] is True.
 Parameters
 descrpt
The descrptor \(\mathcal{D}\)
 neuron
Number of neurons \(N\) in each hidden layer of the fitting net
 resnet_dt
Timestep dt in the resnet construction: \(y = x + dt * \phi (Wx + b)\)
 numb_fparam
Number of frame parameter
 numb_aparam
Number of atomic parameter
 rcond
The condition number for the regression of atomic energy.
 tot_ener_zero
Force the total energy to zero. Useful for the charge fitting.
 trainable
If the weights of fitting net are trainable. Suppose that we have \(N_l\) hidden layers in the fitting net, this list is of length \(N_l + 1\), specifying if the hidden layers and the output layer are trainable.
 seed
Random seed for initializing the network parameters.
 atom_ener
Specifying atomic energy contribution in vacuum. The set_davg_zero key in the descrptor should be set.
 activation_function
The activation function \(\boldsymbol{\phi}\) in the embedding net. Supported options are {0}
 precision
The precision of the embedding net parameters. Supported options are {1}
 uniform_seed
Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed
 Attributes
precision
Precision of fitting network.
Methods
build
(inputs, natoms[, input_dict, reuse, ...])Build the computational graph for fitting net
compute_input_stats
(all_stat[, protection])Compute the input statistics
compute_output_stats
(all_stat)Compute the ouput statistics
enable_compression
(model_file[, suffix])Set the fitting net attributes from the frozen model_file when fparam or aparam is not zero
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Get the number of atomic parameters
Get the number of frame parameters
init_variables
(graph, graph_def[, suffix])Init the fitting net variables with the given dict
 build(inputs: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, input_dict: dict = None, reuse: bool = None, suffix: str = '') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for fitting net
 Parameters
 inputs
The input descriptor
 input_dict
Additional dict for inputs. if numb_fparam > 0, should have input_dict[‘fparam’] if numb_aparam > 0, should have input_dict[‘aparam’]
 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
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
ener
The system energy
 compute_input_stats(all_stat: dict, protection: float = 0.01) None [source]
Compute the input statistics
 Parameters
 all_stat
if numb_fparam > 0 must have all_stat[‘fparam’] if numb_aparam > 0 must have all_stat[‘aparam’] can be prepared by model.make_stat_input
 protection
Dividedbyzero protection
 compute_output_stats(all_stat: dict) None [source]
Compute the ouput statistics
 Parameters
 all_stat
must have the following components: all_stat[‘energy’] of shape n_sys x n_batch x n_frame can be prepared by model.make_stat_input
 enable_compression(model_file: str, suffix: str = '') None [source]
Set the fitting net attributes from the frozen model_file when fparam or aparam is not zero
 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
deepmd.fit.fitting module
 class deepmd.fit.fitting.Fitting[source]
Bases:
object
 Attributes
precision
Precision of fitting network.
Methods
init_variables
(graph, graph_def[, suffix])Init the fitting net variables with the given dict
 init_variables(graph: tensorflow.python.framework.ops.Graph, graph_def: tensorflow.core.framework.graph_pb2.GraphDef, suffix: str = '') None [source]
Init the fitting net variables with the given dict
 Parameters
Notes
This method is called by others when the fitting supported initialization from the given variables.
 property precision: tensorflow.python.framework.dtypes.DType
Precision of fitting network.
deepmd.fit.polar module
 class deepmd.fit.polar.GlobalPolarFittingSeA[source]
Bases:
object
Fit the system polarizability with descriptor se_a
 Parameters
 descrpt
tf.Tensor
The descrptor
 neuron
List
[int
] Number of neurons in each hidden layer of the fitting net
 resnet_dtbool
Timestep dt in the resnet construction: y = x + dt * phi (Wx + b)
 sel_type
List
[int
] The atom types selected to have an atomic polarizability prediction
 fit_diagbool
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
List
[float
] The output of the fitting net (polarizability matrix) for type i atom will be scaled by scale[i]
 diag_shift
List
[float
] The diagonal part of the polarizability matrix of type i will be shifted by diag_shift[i]. The shift operation is carried out after scale.
 seed
int
Random seed for initializing the network parameters.
 activation_function
str
The activation function in the embedding net. Supported options are {0}
 precision
str
The precision of the embedding net parameters. Supported options are {1}
 descrpt
Methods
build
(input_d, rot_mat, natoms[, reuse, suffix])Build the computational graph for fitting net
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Get the output size.
Get selected atom types
init_variables
(graph, graph_def[, suffix])Init the fitting net variables with the given dict
 build(input_d, rot_mat, natoms, reuse=None, suffix='') tensorflow.python.framework.ops.Tensor [source]
Build the computational graph for fitting net
 Parameters
 input_d
The input descriptor
 rot_mat
The rotation matrix from the descriptor.
 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
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
polar
The system polarizability
 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
 class deepmd.fit.polar.PolarFittingLocFrame(jdata, descrpt)[source]
Bases:
object
Fitting polarizability with local frame descriptor.
Deprecated since version 2.0.0: This class is not supported any more.
Methods
build
get_out_size
get_sel_type
 class deepmd.fit.polar.PolarFittingSeA[source]
Bases:
deepmd.fit.fitting.Fitting
Fit the atomic polarizability with descriptor se_a
 Attributes
precision
Precision of fitting network.
Methods
build
(input_d, rot_mat, natoms[, reuse, suffix])Build the computational graph for fitting net
compute_input_stats
(all_stat[, protection])Compute the input statistics
enable_mixed_precision
([mixed_prec])Reveive the mixed precision setting.
Get the output size.
Get selected atom types
init_variables
(graph, graph_def[, suffix])Init the fitting net variables with the given dict
 build(input_d: tensorflow.python.framework.ops.Tensor, rot_mat: tensorflow.python.framework.ops.Tensor, natoms: tensorflow.python.framework.ops.Tensor, reuse: bool = None, suffix: str = '')[source]
Build the computational graph for fitting net
 Parameters
 input_d
The input descriptor
 rot_mat
The rotation matrix from the descriptor.
 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
 reuse
The weights in the networks should be reused when get the variable.
 suffix
Name suffix to identify this descriptor
 Returns
atomic_polar
The atomic polarizability
 compute_input_stats(all_stat, protection=0.01)[source]
Compute the input statistics
 Parameters
 all_stat
Dictionary of inputs. can be prepared by model.make_stat_input
 protection
Dividedbyzero protection
 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
deepmd.fit.wfc module
deepmd.infer package
Submodule containing all the implemented potentials.
 class deepmd.infer.DeepDipole(model_file: Path, load_prefix: str = 'load', default_tf_graph: bool = False)[source]
Bases:
deepmd.infer.deep_tensor.DeepTensor
Constructor.
 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
 model_file
Warning
For developers: DeepTensor initializer must be called at the end after self.tensors are modified because it uses the data in self.tensors dict. Do not chanage the order!
 Attributes
model_type
Get type of model.
model_version
Get version of model.
Methods
eval
(coords, cells, atom_types[, atomic, ...])Evaluate the model.
eval_full
(coords, cells, atom_types[, ...])Evaluate the model with interface similar to the energy model.
Unsupported in this model.
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.
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.
 class deepmd.infer.DeepEval(