# Main Page

Jump to navigation Jump to search

## What is GPUMD?

• GPUMD stands for Graphics Processing Units Molecular Dynamics. It is a general-purpose molecular dynamics (MD) package fully implemented on graphics processing units (GPU). It is written in CUDA C++ and requires a CUDA-enabled Nvidia GPU of compute capability no less than 3.5.
• It is highly efficient for doing MD simulations with many-body potentials such as the Tersoff potential.
• It has native support for the NEP machine learning potential. That is, it can be used to train a NEP potential and then run MD simulations with the trained potential.
• Installation of GPUMD is easy. If you have a working CUDA development environment, it just requires a single make to install GPUMD in either Linux or Windows.

## Versions of GPUMD

• This website documents GPUMD-master.
• We suggest use the latest released version or GPUMD-master.
• For a full description of the various versions of GPUMD, see the following table.
 Version Date of release Major changes relative to the previous version GPUMD-v1.0 Aug 13, 2017 The first version of GPUMD. GPUMD-v1.1 Aug 30, 2017 Added a potential describing single-layer black phosphorene (but the implementation is incorrect and was corrected in GPUMD-v1.5). GPUMD-v1.2 Sep 25, 2017 Zero the angular momentum when initializing the velocities. GPUMD-v1.3 Oct 12, 2017 Added a REBO (without LJ) potential for Mo-S systems. GPUMD-v1.4 Dec 24, 2017 Added the Vashishta potential. GPUMD-v1.5 Jan 24, 2018 Added the general two-element SW potential. GPUMD-v1.6 Mar 4, 2018 Improved the performance of some potentials. GPUMD-v1.7 Jun 30, 2018 Added the HNEMD method for the Tersoff and SW potentials. GPUMD-v1.8 Jul 26, 2018 1) Added the HNEMD method for all the potentials. 2) Added support for hybrid potentials. GPUMD-v1.9 Oct 9, 2018 Corrected a couple of memory bugs. GPUMD-v2.0 Nov 23, 2018 Added the Langevin thermostat and the BDP thermostat. GPUMD-v2.1 Dec 14, 2018 Implemented a more general version of the SHC method. GPUMD-v2.2 Jan 19, 2019 1) Fixed a few memory bugs introduced in GPUMD-v2.0 and GPUMD-v2.1. 2) Changed the data format in the xyz.in file and removed the layer.in file. 3) Changed the output of the dump_position command from xyz.out to movie.xyz. 4) Added a dump_restart command which can produce a restart.out file. 5) The compute_temp command has been replaced by the more general compute command. 6) Added the deform command, which can be used to compute the stress-strain relation. GPUMD-v2.3 Feb 20, 2019 1) Added the general Tersoff potential, which is applicable to systems with an arbitrary number of atom types. The added version is as general as the Tersoff potential in LAMMPS. 2) Added the support of triclinic box (but it currently cannot be used together with the NPT ensemble). GPUMD-v2.4 Apr 20, 2019 1) Added a main program for phonon calculations based on harmonic lattice dynamics. 2) Improved the calculation of the vibrational density of states from the velocity autocorrelation function. GPUMD-v2.4.1 Apr 20, 2019 Corrected makefile.phonon, which is incorrect as in GPUMD-v2.4. GPUMD-v2.5 Aug 31, 2020 1) Added the Tersoff-mini potential. 2) Added the FCP potential. 3) Added a modal analysis method. 4) Changed the data format in the xyz.in file by removing the has_layer item in the first line. 5) Changed the grammar of the  potential keyword and removed the  potentials keyword. 6) Added the minimize keyword. 7) Changed the grammar of the compute_shc keyword. 8) Enriched the features of the compute_dos keyword by allowing for calculating the DOS for all the groups. 9) Added support for dumping the NETCDF file. 10) Added support for Windows with MSVC. GPUMD-v2.5.1 Sep 19, 2020 1) Created Jupyter notebooks (with Python 3) as the new tutorials. 2) Fixed a bug related to the ensemble npt_ber command (the bug will affect simulations where the $z$ direction is periodic and not deformed and at the same time the target pressures for the $z$ and $x$ directions are different. GPUMD-v2.6 Sep 13, 2021 1) Added the Neuroevolution machine learning potentials (NEP) [1]. 2) Fixed a bug about the simulation cell. The volume of some simulation cells were calculated to be negative, which can give rise to a "negative thermal conductivity". Otherwise, the dynamics is not affected. GPUMD-v2.7 Sep 21, 2021 1) Improved the accuracy of the NEP potential for multi-component systems. The formats of the input files related to the NEP potential have been slightly changed. To use the original NEP potential as described in [2], please use GPUMD-v2.6. GPUMD-v2.8 Nov 13, 2021 1) Enabled using a batchsize in NEP training (Therefore, one more line is added to nep.in). 2) Now NEP needs both train.in and test.in and will output energy_train.out, force_train.out, virial_train.out, energy_test.out, force_test.out, and virial_test.out instead of energy.out, force.out, and virial.out only. 3) Now for the NEP potential, the atom types in train.in, test.in, and xyz.in are not represented as integers but as atom symbols (such as H, He, and Li). 4) The NEP training efficiency has been significantly improved when there are a lot of small-cell structures. 5) Fixed a bug related to thermo.out (the triclinic box matrix was different from the manual by a transpose). 6) Fixed a bug for the dump_position, dump_velocity, and dump_force keywords (These keywords may output incorrect data when the group option is used and the group indices in the relevant grouping method are not continuous). GPUMD-v2.8.1 Nov 20, 2021 1) In GPUMD-v2.8, the regression accuracy of the NEP potential for single-component system has been decreased (by 10%-20%) compared to the previous versions, due a change related to using mini-batch for training. In this release, we bring back the original accuracy. GPUMD-v2.9 Dec 11, 2021 1) Removed the phonon executable, and added the compute_phonon keyword in run.in to do phonon dispersion calculation. 2) Enabled isotropic pressure controlling in NPT. 3) Added the compute_cohesive keyword in run.in to compute the cohesive energy curve. 4) Added the compute_elastic keyword in run.in to compute the elastic constants (only for cubic systems now). 5) Reduced the weighting factor of the virial loss in NEP training from 1 to 0.1 (virial is usually not as important as force and energy and should have a smaller weighting factor). 6) Fixed a hidden memory bug for the nep executable. GPUMD-v2.9.1 Dec 25, 2021 1) The convergence speed of NEP training has been significantly improved in most cases. 2) Changed movie.xyz from the simplest XYZ format to an extended XYZ format. 3) Used atom symbols in restart.out for NEP potentials. 4) Reported an error message if NPT is used with triclinic box. 5) Fixed a hidden bug related to variable initialization. To be released as GPUMD-v3.0 To be released in 2022 1) Enabled O(N) neighbor list algorithm for triclinic box. 2) Enabled triclinic box NPT. 3) Added the stochastic cell rescaling (SCR) barostat. 4) Changed the syntax for NPT. 5) Extended the EAM potential to support alloys. 6) Changed nep.in from fixed format to free-style format. 7) Added a type_weight keyword in nep.in to enable type-wise force weight. 8) Added a force_delta keyword in nep.in to possibly emphasize the accuracy of smaller forces. 9) Enabled configuration-wise weight in trian.in. 10) Allowed for adding the universal ZBL potential for NEP training.

## Install and run GPUMD

### Download GPUMD

• Go to GitHub and download the version(s) you need.

### Prerequisites for using GPUMD

• Hardware: You need to have an Nvidia GPU card with compute capability no less than 3.5.
• Software:
• A CUDA toolkit 9.0 or newer.
• In Linux system, you also need a g++ compiler supporting at least c++11.
• In Windows system, you also need the cl.exe compiler from Microsoft Visual Studio and a 64-bit version of make.exe.

### Compile GPUMD

• Go to the src directory and type make. When the compilation finishes, two executables, nep and gpumd, will be generated in the src directory.
• Please check the comments in the beginning of the makefile for some compiling options.

### Run GPUMD

#### The driver input file

• To run each executable, one has to prepare some input files and a driver input file, which is used to do one or more simulations using a single launch of an executable. The driver input file should have the following format:
   number_of_simulations
path_1
path_2
...


Here number_of_simulations is the number of individual simulations you want to run within a single launch (by the operating system) of the executable (src/nep or src/gpumd) and path_n is the path of the directory containing the actual input files for the n-th simulation. Output files will be created in the directories containing the corresponding input files.

## Inputs and outputs for GPUMD

### Inputs for the src/gpumd executable

• To run one simulation using the src/gpumd executable, one has to prepare at least two input files:
 Input filename Brief description xyz.in Define the simulation model run.in Define the simulation protocol
• The run.in file is used to define the simulation protocol for gpumd. The code will execute the commands in this file one by one. If the code encounters an invalid command in this file, it will report an error message and exit. In this input file, blank lines and lines starting with # are ignored. One can thus write comments after #. All the other lines should be of the following form:
keyword parameter_1 parameter_2 ...

• The overall structure of a run.in file is as follows:
• First, set up the potential model using the potential keyword.
• Then, if needed, use the minimize keyword to minimize the energy of the whole system.
• Then one can use the following keywords to do some static calculations (that is, non-MD simulations):
• Then, if you want to do MD simulaitons, set up the initial velocities using the velocity keyword and do a number of MD runs in the following way:
• Specify an integrator using the ensemble keyword and optionally add keywords to further control the evolution and measurement processes.
• Use the keyword run to run a number of steps according to the above settings.
• One can repeat the above two steps.
• Here is the complete list of the keywords:
 Keyword Brief description Take action immediately? Propagating from one run to the next? velocity Set up the initial velocities with a given temperature Yes N/A potential Set up a single potential Yes N/A minimize Perform an energy minimization Yes N/A compute_cohesive Compute the cohesive energy curve Yes N/A compute_elastic Compute the elastic constants Yes N/A compute_phonon Compute the phonon dispersion Yes N/A ensemble Specify an integrator for a run No No time_step Specify the time step for integration No Yes neighbor Require neighbor list updating No No fix Fix (freeze) some atoms No No deform Deform the simulation box No No dump_thermo Dump some thermodynamic quantities No No dump_position Dump the atom positions No No dump_netcdf Dump the atom positions in the netCDF format No No dump_restart Dump a restart file No No dump_velocity Dump the atom velocities No No dump_force Dump the atom forces No No compute Compute some time- and space-averaged quantities No No compute_shc Calculate spectral heat current No No compute_dos Calculate the phonon density of states (PDOS) No No compute_sdc Calculate the self diffusion coefficient (SDC) No No compute_hac Calculate thermal conductivity using the EMD method No No compute_hnemd Calculate thermal conductivity using the HNEMD method No No compute_gkma Calculate modal heat current using the GKMA method No No compute_hnema Calculate modal thermal conductivity using the HNEMA method No No run Run a number of steps Yes No

### Output files for the src/gpumd executable

 Output filename Generated by which keyword? Brief description Output mode thermo.out dump_thermo Some global thermodynamic quantities Append movie.xyz dump_position Trajectory (atom positions) Append restart.out dump_restart The restart file Overwrite velocity.out dump_velocity The velocity file Append force.out dump_force The force file Append compute.out compute Time and space (group) averaged quantities Append hac.out compute_hac Thermal conductivity data from the EMD method Append kappa.out compute_hnemd Thermal conductivity data from the HNEMD method Append shc.out compute_shc Spectral heat current data Append heatmode.out compute_gkma Modal heat current data from GKMA method Append kappamode.out compute_hnema Modal thermal conductivity data from HNEMA method Append dos.out compute_dos Phonon density of states data Append sdc.out compute_sdc Self diffusion coefficient data Append D.out compute_phonon Dynamical matrices $D(\vec{k})$ for the input k points Overwrite omega2.out compute_phonon Phonon frequency square $\omega^2(\vec{k})$ for the input k points Overwrite

### Inputs for the src/nep executable

• To run one simulation using the src/nep executable, one has to prepare at least three input files:
 Input filename Brief description nep.in Define the NEP potential train.in and test.in Provide the training and testing data

### Outputs for the src/nep executable

• The output files for the src/nep executable are described here.

## Empirical potentials implemented in GPUMD

• The individual potentials available in GPUMD are listed in the following table:
• Hybrid potentials can be constructed from these individual ones. See the potential keyword for details.

## Tutorials for using GPUMD

### Tutorials for using the src/gpumd executable

 Tutorial name Brief description Tutorial: Thermal expansion Study thermal expansion of silicon crystal from 100 K to 1000 K Tutorial: Density of states Calculate the vibrational density of states of graphene at 300 K Tutorial: Thermal conductivity from EMD Calculate the lattice thermal conductivity of graphene at 300 K using the EMD method Tutorial: Thermal transport from NEMD Calculate the spectral ballistic conductance of graphene using the NEMD and spectral decomposition Tutorial: Thermal transport from HNEMD Calculate the spectral conductivity of graphene using the HNEMD method and spectral decomposition Tutorial: Phonon dispersion Calculate the phonon dispersion of silicon crystal

### Tutorials for using the src/nep executable

 Tutorial name Brief description Tutorial: NEP tutorial Train a NEP machine-learning potential for PbTe crystal

## Python interface of GPUMD

• The thermo Python package developed by Alex Gabourie can be used to pre-process and post-process GPUMD.

## Mailing list and discussion group of GPUMD

• Discussion group
• There is a Chinese discussion group based on the following QQ 群:
• 887975816

## Want to develop GPUMD?

### Developers of GPUMD

• GPUMD was first developed by Zheyong Fan (Previously Aalto University; brucenju(at)gmail.com), with help from his colleagues Ville Vierimaa, Mikko Ervasti, and Ari Harju during 2012-2017.
• In 2018, Alexander J. Gabourie (PhD candidate at Stanford University; gabourie(at)stanford.edu) joined in and he is now an active developer.

### Important coding conventions of GPUMD

• We want to keep GPUMD as a standalone code. So we only use standard C++ (currently only up to c++11) and CUDA (currently only up to CUDA 9.0) libraries.
• We will make sure that the code is correct for any Nvidia GPU with compute capability no less than 3.5 and in both Linux and Windows systems.
• We use the .clang-format file in the package to format any CUDA C++ source code.

### Units system adopted within GPUMD

• We use the following basic units
• Energy: eV (electron volt)
• Length: A (angstrom)
• Mass: amu (atomic mass unit)
• Temperature: K (kelvin)
• Charge: e (elementary charge)
• The units for all the quantities are thus fixed.
• One only needs to make units conversions when dealing with inputs and outputs; all the quantities should be defined in the above units system elsewhere.