Basic Usage¶

Sequence of Use¶

Sample Structure Creation

Sample structures for generating force field are created by users using Advance/NanoLabo or other software. Multiple sample structures are simultaneously available to generate a single force field.

Random Structure Generation

Based on the sample structures, a number of structures with randomly displaced atomic coordinates are automatically generated. It also outputs a script that performs a batch of first-principles calculations for all generated structures.

First-principles calculations with Quantum ESPRESSO

The generated scripts are executed to perform first-principles calculations. The calculation uses our modified Quantum ESPRESSO to output each atomic energy.

Neural Network Learning (Optimization)

The neural network is optimized using each atomic energy calculated by Quantum ESPRESSO as the training data. The optimization calculations are performed with tools provided by us. After the calculation is completed, the information of the neural network is output as a force field file available in LAMMPS.

Molecular dynamics calculation with LAMMPS

Molecular dynamics calculations are performed using the generated force field file. The calculations are performed using LAMMPS, to which Neural Network Potential functionality are added by us.

Explanation¶

Step 1. Creating Sample Structures¶

Prepare the atomic structure of the sample that would like to be used as training data, and create an input file for SCF calculations of Quantum ESPRESSO based on it. Our product Advance/NanoLabo can easily generate an input file from atomic structure files such as cif.

The path to the pseudopotential in the file must be the one used for the actual calculation in step 3. For example, when running the calculation on a calculation server, the path must point to the pseudopotential directory in the calculation server.

Once the input file is prepared, add the following settings to have the necessary information output.

&CONTROL
   tprnfor = .true.
   tsannp = .true.
/
&SYSTEM
   nosym = .true.
/

Step 2. Generating Random Structures¶

Run Advance/NeuralMD to generate a number of random structures based on the input file created. The executable file is sannp in the bin folder in the installation location. If the file is named espresso.scf.in, execute as follows.

sannp --dft espresso.scf.in

In an interactive format, enter the required information such as the number of structures to be generated and the magnitude of the displacement. Pressing Enter without inputting any information, the default values will be used.

After the input is complete, the shell script for running the Quantum ESPRESSO calculation dft_run.sh (or the batch file dft_run.bat for Windows) and the input files for each structure are generated.

├ dft_run.sh (.bat)

└ dft_inp

├ inp.1
├ inp.2
├ …

Step 3. First-principles Calculations with Quantum ESPRESSO¶

When using Quantum ESPRESSO bundled with NanoLabo Tool, setup of the library search path and others are required. Please refer to the following for the settings.

Calculation Engines included in Nanolabo Tool

Without a job management system, run dft_run.sh directly.

./dft_run.sh

Run dft_run.bat for Windows.

dft_run.bat

When using a job management system, edit dft_run.sh as necessary. For example, add the #PBS directive for PBS and the #SBATCH directive for SLURM (FOCUS supercomputer). Then submit dft_run.sh as a job script.

Example of PBS¶

qsub dft_run.sh

As calculations are performed, the training data (atomic structures and corresponding energy, force, and charge for each atom) are stored in sannp.train file.

Hint

Repeat steps 1 through 3 as necessary to prepare multiple sannp.train files so that the geometry of the atoms in the system for which molecular dynamics calculations are performed is sampled in an exhaustive and uniform manner. Multiple sannp.train files can be combined for use.

Step 4. Training of Neural Network (Optimization)¶

Prepare the settings for the neural network in the file sannp.prop and the settings for the Behler symmetry function in the file sannp.behler. No file is required with default settings.

In case without calculations of the charge (set withCharge 0 in sannp.prop), execute the following command to train a neural network.

sannp --train

For Linux, MPI parallel execution is available. Use the MPI executable included with the NeuralMD installer or the MPI executable included with the NanoLabo Tool installer. Please refer to the setup instructions to configure and run the program.

Example of MPI parallel execution (Linux)¶

mpirun -n 4 sannp --train

Note

Windows version does not support MPI parallel execution while OpenMP parallel execution is available.

The residual RMS, elapsed time, etc. are output during execution. After the execution is completed successfully, files sannp.data and sannp.data_e containing information on the neural network are output.

To stop learning, run sannp --stop.

If the maximum number of times has been reached without convergence, or if the process is interrupted with above command, you can set restart 1 in sannp.prop and execute it again to resume training after reading the information of the neural network that has already been trained.

In the case of calculating the charge (set withCharge 1 in sannp.prop), a neural network for the charge is trained in addition to the above.

sannp --train-charge

If successfully executed, the file sannp.data_q containing information on the neural network of the charge is output.

After the neural network has been trained, execute

sannp --export

to output the force field definition file ffield.sannp to be used in LAMMPS.

Step 5. Molecular Dynamics Calculations with LAMMPS¶

When using LAMMPS bundled with NanoLabo Tool, setup of the library search path and others are required. Please refer to the following and set up.

Calculation Engines included in Nanolabo Tool

The following pair_style is available in the input file of LAMMPS.

pair_style nnp

Neural network force field

Syntax¶

pair_style nnp
pair_coeff * * <ffield.sannp> <eatom zero|finite> <elementname1 elementname2 ...>

pair_style nnp/coul/cut

Neural network force field + Coulomb interaction (real-space)

Syntax¶

pair_style nnp/coul/cut <rcut>
pair_coeff * * <ffield.sannp> <eatom zero|finite> <elementname1 elementname2 ...>

pair_style nnp/coul/long

Neural network force field + Coulomb interaction (real-space + k-space)

Syntax¶

pair_style nnp/coul/long <rcut>
pair_coeff * * <ffield.sannp> <eatom zero|finite> <elementname1 elementname2 ...>
kspace_modify gewald <rinv>

Parameters

ffield.sannp

File name output in Step 4.

elementname

List of the corresponding element name in the training data (= element name in Quantum ESPRESSO calculation) for each atom type in LAMMPS.

eatom

Function to set the bias term in the final layer of the neural network (constant corresponds to internal energy of atom) to zero (leveling of atomic energy)

Enabled by eatom zero, disabled by eatom finite or omitted (specify element name followed by force field file name)

rcut

Cutoff radius for real-space (short-range) Coulomb interaction

(must be specified for nnp/coul/cut, can be omitted for nnp/coul/long) (→coul/cut)

rinv

Parameters for calculating the Ewald sum of charges (in units of 1/distance)

(must be specified for nnp/coul/long) (→kspace_modify)

When running LAMMPS with setting either pair_style, molecular dynamics calculations are performed using the neural network force field.

Execution Option List¶

--dft <file>, --qe <file>, --quantum-espresso <file>¶

Generates a number of randomly structured input files *.inp and a execution script dft_run.sh from a single Quantum ESPRESSO input file to generate training data.

If no file is specified, input must be interactive.

--train, --train-energy¶: Trains a neural network to calculate energy and force based on the training data sannp.train. After the execution terminates successfully, files sannp.data and sannp.data_e containing information on the neural network are output.

--train-charge¶: Trains a neural network to calculate electric charge based on the training data sannp.train. After the execution terminates successfully, a file sannp.data_q containing information on the neural network is output.

--stop, --stop-training¶: Stop training during execution and output the information of the neural network in the process of training to sannp.data, sannp.data_e or sannp.data_q.

--test, --test-without-bias¶

Calculate data for test using the learned neural network. The test data file sannp.test can be created by executing sannp --dft and selecting “test”. The resultant file contains the total energy sannp.etot, the energy sannp.eatom per atom, the force sannp.force acting on the atom, and the electric charge sannp.charge.

MPI parallel calculation is not supported.

Atomic energies in the output are leveled by setting the bias term of the last layer (constant corresponds to internal energy of atom) to 0.

$E_\mathrm{tot}(\mathrm{DFT/NNP}) = \left(E(\mathrm{DFT/NNP}) - \sum_i b_i N_i \right) / \sum_i N_i$ , ( $i$ :element)

In case multiple neural network models are used (models > 1), leveling is performed so the average value of the bias term of the last layer of each model becomes 0.

--test-with-bias¶: Similar to --test , but without leveling of atomic energies in the output.

$E_\mathrm{tot}(\mathrm{DFT/NNP}) = E(\mathrm{DFT/NNP}) / \sum_i N_i$ , ( $i$ :element)

--temp, --template¶: Outputs the template for the configuration file sannp.prop while existing files will be overwritten.

--behler, --behler-temp¶: Outputs the template for the Behler symmetric function configuration file sannp.behler while existing files will be overwritten.

--force, --force-test¶

Calculate the test data using the trained neural network and display the resultant force acting on the atoms. The test data file sannp.test can be created by executing sannp --dft and selecting “test”.

MPI parallel calculation is not supported.

--export, --force-field, --lammps¶: Outputs the force field file field.sannp available in LAMMPS from the trained neural network.

--split <r>, --split-train <r>¶: Extracts data from the training data sannp.train with specifying the fraction $r (0 \le r \le 1)$ , and creates the test data sannp.test. At the same time, the remaining $(1 - r)$ data is output as new training data sannp.train.

--metro, --monte-carlo, --mc¶: Executing after training, it generates a structure by Monte Carlo calculation using the Metropolis method, which is replica-parallel in MPI parallel execution. After execution, the generated structures are saved in the dft_geom folder, and the Monte Carlo simulation movie for each replica is saved in the movie folder. Following that, run sannp --dft to generate the execution script dft_run.sh to create training data from the generated structures.

--metro-temp, --monte-carlo-temp, --mc-temp¶: Outputs the template for the metropolis method configuration file sannp.metro while existing files are overwritten. GEOMETRY uses the first structure in training data sannp.train.

--classical¶: Optimizes the parameters of the classical force field used in Δ-NNP based on the training data sannp.train. After a successful execution, a file sannp.class containing the parameters is output.

Option to use with other options¶

--omp <n>, --cpu <n>¶: Specify the number of parallels of OpenMP parallel (thread parallel).

--que¶

In case of a license error (maximum number of concurrent executions), wait until it becomes possible to execute.

Without specifying this option, the program exits immediately in case of a license error.

Single-precision and Double-precision Versions¶

The bin folder in the installation location contains sannp_d (double-precision version) in addition to the normal sannp (single-precision version). When using the double-precision version, replace sannp with sannp_d in the description.

GPU version¶

If your machine has a graphic card (GPU), you can accelerate the calculations by using the GPU for processing. sannp_gpu (single-precision version), sannp_gpu_d (double-precision version) in the bin folder in the installation location are GPU version executables. Use them by replacing sannp with these files in the description.

Although the property file sannp.prop has some GPU version-specific items, the input files for non-GPU version can readily be used without any modification.

Note

GPU driver is necessary to be installed beforehand. As CUDA 11.4.4 is used, driver version 470.82.01 or later is required.
In case 5 or more elements are in the system, weighted symmetry function must be used (set elemWeight 1 in sannp.prop).

Combination use with MPI parallel¶

By executing GPU version with MPI parallel, the GPU is used more efficiently. The trick is that each process communicates with GPU independently, and while one process is calculating with GPU, another process transfers data to GPU memory, for example, to execute multiple tasks in parallel.

In case your machine has multiple GPUs, you can specify which one(s) to be used. Make a file named sannp.mpi2gpu and specify to which GPU the process is allocated by the device ID in each line. For example, on a machine with 2 graphic cards, to execute with 8 MPI parallel processes, with allocating 4 processes to device ID0 GPU and 4 to device ID1 GPU, you can set it as follows.

sannp.mpi2gpu¶

Be sure to match the number of lines in the file with the number of MPI parallel (processes). By default (without sannp.mpi2gpu), all processes are allocated to device ID0 GPU.

For your information, you can check the device ID assigned to each GPU by executing following:

nvidia-smi -L

Hint

The calculation is effectively executed if you assign 2-4 processes per 1 GPU device.

Hint

For the calculation engines included in NanoLabo Tool, Quantum ESPRESSO does not support GPU and LAMMPS support GPU. Please refer to GPU version of LAMMPS for the detail.

ffield.sannp	File name output in Step 4.
elementname	List of the corresponding element name in the training data (= element name in Quantum ESPRESSO calculation) for each atom type in LAMMPS.
eatom	Function to set the bias term in the final layer of the neural network (constant corresponds to internal energy of atom) to zero (leveling of atomic energy) Enabled by eatom zero, disabled by eatom finite or omitted (specify element name followed by force field file name)
rcut	Cutoff radius for real-space (short-range) Coulomb interaction (must be specified for `nnp/coul/cut`, can be omitted for `nnp/coul/long`) (→coul/cut)
rinv	Parameters for calculating the Ewald sum of charges (in units of 1/distance) (must be specified for `nnp/coul/long`) (→kspace_modify)