# Main Page

## Versions

• This website documents the developing version of GPUMD.
• Because both the code and the documentation are developing, they can be inconsistent before a new release.
• We suggest use the latest released version, which is GPUMD-v2.4.1 now.
• For each released version, there is a corresponding user manual in a PDF file.
• We expect to release GPUMD-v2.5 in the summer of 2020.
• For a full description of the various versions of GPUMD, see Versions of GPUMD.

## What is GPUMD?

• GPUMD stands for Graphics Processing Units Molecular Dynamics. It is a general-purpose molecular dynamics (MD) code fully implemented on graphics processing units (GPU). It is written in CUDA C++ and requires to run on a CUDA-enabled Nvidia GPU of compute capability no less than 3.5.
• It is super fast. It is highly efficient for doing MD simulations with many-body potentials such as the Tersoff potential. Using a single powerful GPU such as Tesla P100, it can run 100 MD steps for a one-million-atom system within one second. See the tutorials for details.
• Good for MD simulations with many-body potentials. We have implemented quite a few many-body potentials as well as a few two-body potentials. One can also define multiple potentials for a complicated system.

## Install and run GPUMD

• All the releases of GPUMD can be downloaded from GitHub.
• The latest stable release is GPUMD-v2.4.1.
• The documentation on this site is targeted at the developing version. For each released version, there is a corresponding user manual in the PDF format.

### Installation

#### Prerequisites

• 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, which can be downloaded here: http://www.equation.com/servlet/equation.cmd?fa=make.

#### Compile the source codes

• Go to the src directory and type make. When the compilation finishes, two executables, gpumd and phonon, 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 either 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/gpumd or src/phonon) 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.

#### Prepared examples

• Go to the directory where you can see src.
• Type src/gpumd < examples/input_gpumd.txt to run the examples in examples/gpumd.
• Type  src/phonon < examples/input_phonon.txt to run the examples in examples/phonon.

## Inputs and outputs

### Inputs for src/gpumd

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

• Here is the complete list of the keywords:
 Keyword Brief description Take action immediately? velocity Set up the initial velocities with a given temperature Yes potential Set up a single potential Yes minimize Perform an energy minimization Yes ensemble Specify an integrator for a run No time_step Specify the time step for integration No neighbor Require neighbor list updating No fix Fix (freeze) some atoms No deform Deform the simulation box No dump_thermo Dump some thermodynamic quantities No dump_position Dump the atom positions No dump_netcdf Dump the atom positions in the netCDF format No dump_restart Dump a restart file No compute Compute some time- and space-averaged quantities No compute_shc Calculate spectral heat current No compute_dos Calculate the phonon density of states (PDOS) No compute_sdc Calculate the self diffusion coefficient (SDC) No compute_hac Calculate thermal conductivity using the EMD method No compute_hnemd Calculate thermal conductivity using the HNEMD method No run Run a number of steps Yes
• The overall structure of a run.in file is as follows:
• First, set up the initial velocities using the velocity keyword and set up the potential model using the potential keyword.
• Then, if needed, use minimize keyword to minimize the energy of the whole system.
• 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.

### Outputs for src/gpumd

 Output filename Generated by 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 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 dos.out compute_dos Phonon density of states data Append sdc.out compute_sdc Self diffusion coefficient data Append

### Inputs for src/phonon

• To run one simulation using the src/phonon executable, one has to prepare at least four input files:
 Input filename Brief description xyz.in Define the simulation model basis.in Define the mapping from the atom label to the basis label kpoints.in Specify the k-points phonon.in Define the simulation protocol

• The phonon.in file is used to define the simulation protocol for sr/phonon. 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 ...

• Here is the complete list of the keywords:
 Keyword Brief description Take action immediately? potential Set up a single potential Yes minimize Perform an energy minimization Yes cutoff The cutoff distance used for calculating the force constants No delta The finite displacement used in calculating the force constants No
• The overall structure of a phonon.in file is as follows:
• First, set up the potential model using the potential keyword.
• Then, if needed, use minimize keyword to minimize the energy of the whole system.
• Then use the other keywords to set up some parameters.

### Outputs for src/phonon

 Output filename Brief description Output mode D.out Dynamical matrices $D(\vec{k})$ for the input k points Overwrite omega2.out Phonon frequency square $\omega^2(\vec{k})$ for the input k points Overwrite

## Tutorials

### Tutorials for gpumd

 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 and HNEMD Calculate the spectral conductance and conductivity of graphene using the NEMD, HNEMD, and spectral decomposition methods

### Tutorials for phonon

 Tutorial name Brief description Tutorial: Phonon dispersion Calculate the phonon dispersion of silicon crystal

## Python interface

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

## Theoretical formulations

• I am also writing a book on MD. This book is in Chinese.

## Mailing list and discussion group

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

## Want to contribute?

• The GPUMD code was first developed by Zheyong Fan (Postdoc at Aalto University; brucenju(at)gmail.com) and his colleagues Ville Vierimaa (Previously at Aalto University), Mikko Ervasti (Previously at Aalto University), and Ari Harju (Previously at Aalto University) 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.
• If you want to become a developer of GPUMD, please note the following:
• 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.
• Make sure that the code is correct for any Nvidia GPU from compute capability 3.5 to 7.5 and in both Linux and Windows systems.
• Use the .clang-format file within src/ to format any CUDA C++ source code.