Main Page

Notice

This manual is only for versions up to GPUMD-v3.5. Starting from GPUMD-v3.6, please use the new manual: https://gpumd.org/

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.

• Particularly good for heat transport applications. See the theoretical formulations.

• 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.

Publications

See the publications that developed or used GPUMD.

Versions of GPUMD

• This website documents up to GPUMD-v3.5.
• We have been recently focusing on developing the NEP machine-learned potential and the best version for empirical potentials should be GPUMD-v3.3.1.
• For a full description of the various versions of GPUMD, see the Github page https://github.com/brucefan1983/GPUMD/releases

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

Up to GPUMD-3.3.1

• 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.

Starting from GPUMD-v3.4

There will be no driver input file any more. To run one example, one just need to go to the directory of that example and type one of the following commands:

 path/to/gpumd
 path/to/nep

Prepared examples

• Please check this link: https://github.com/brucefan1983/GPUMD/tree/master/examples

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:

Mandatory input files for the src/gpumd executable

Input filename	Brief description
xyz.in	Define the simulation model (before GPUMD-v3.4)
model.xyz	Define the simulation model (starting from GPUMD-v3.4)
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):
    • Use the compute_cohesive keyword to compute the cohesive energy curve.
    • Use the compute_elastic keyword to compute the elastic constants.
    • Use the compute_phonon keyword to compute the phonon dispersions.
  • Then, if you want to do MD simulations, 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:

Keywords for the run.in input file

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 (before GPUMD-v3.4)	Set up a single potential	Yes	N/A
potential (starting from GPUMD-v3.4)	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
change_box	Change the box	Yes	N/A
ensemble	Specify an integrator for a run	No	No
time_step	Specify the time step for integration	No	Yes
neighbor	Control the 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
dump_exyz	Dump an extended XYZ file with some data	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 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 (Before GPUMD-v3.4) or restart.xyz (Starting from GPUMD-v3.4)	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 mvac.out	compute_dos	Phonon density of states data	Append
sdc.out	compute_sdc	Self diffusion coefficient data	Append
D.out	compute_phonon	Dynamical matrices [math]D(\vec{k})[/math] for the input k points	Overwrite
omega2.out	compute_phonon	Phonon frequency square [math]\omega^2(\vec{k})[/math] 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 files for the src/nep executable

Input filename	Brief description
nep.in	Define the NEP potential
train.in and test.in	Provide the training and testing data (before GPUMD-v3.4)
train.xyz and test.xyz	Provide the training and testing data (starting from GPUMD-v3.4)

Outputs for the src/nep executable

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

Tutorials for using GPUMD

Tutorials for using the src/gpumd executable

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
Tutorial: Phonon vibration visualization	Visualize phonon vibrations
Tutorial: Phonon participation ratio	Calculating the phonon participation ratio in the frequency domain for prsitine and defect graphene
Tutorial: Elastic constant	Elastic constant calculations from strain fluctuations

Tutorials for using the src/nep executable

Tutorials for using the src/nep executable

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

Python interfaces of GPUMD

Name	Brief description
gpyumd	Pre- and post-process GPUMD simulations with Python
pyNEP	Python interface for the NEP machine learning potential
calorine	Python library to manage GPUMD simulations

Theoretical formulations of GPUMD

• Here are the Theoretical formulations of GPUMD.

Mailing list and discussion group of GPUMD

• Mailing list
  • You can use the following link to subscribe and unsubscribe to the mailing list: https://www.freelists.org/list/gpumd
  • To post a question, you can send an email to gpumd(at)freelists.org
  • Here is the archive (public): https://www.freelists.org/archive/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.

Acknowledgements

• NSFC with project numbers 11404033 and 11974059.
• Aalto Science-IT project
• Finland's IT Center for Science (CSC)