LAMMPS Documentation

Release stable 29Sep2021

The LAMMPS Developers

Sep 29, 2021

 LAMMPS DOCUMENTATION

I User Guide 3
1 Introduction 5
1.1 Overview of LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 What does a LAMMPS version mean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 LAMMPS features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3.1 General features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.2 Particle and model types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.3 Interatomic potentials (force fields) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.4 Atom creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.5 Ensembles, constraints, and boundary conditions . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.6 Integrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.7 Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.8 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.9 Multi-replica models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.10 Pre- and post-processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.11 Specialized features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4 LAMMPS non-features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5 LAMMPS open-source license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5.1 GPL version of LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5.2 LGPL version of LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.6 Authors of LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.7 Citing LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.7.1 Core Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.7.2 DOI for the LAMMPS code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.7.3 Home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.7.4 Citing contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.8 Additional website links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2 Install LAMMPS 17
2.1 Download an executable for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1.1 Pre-built Ubuntu Linux executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1.2 Pre-built Fedora Linux executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.3 Pre-built EPEL Linux executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.4 Pre-built OpenSuse Linux executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.5 Gentoo Linux executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.1.6 Archlinux build-script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2 Download an executable for Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.3 Download an executable for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.4 Download an executable for Linux or Mac via Conda . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.5 Download source and documentation as a tarball . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

i
 2.6 Download the LAMMPS source with git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3 Build LAMMPS 27
3.1 Build LAMMPS with CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.1 Advantages of using CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.1.3 Configuration and build options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.1.4 Installing CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.2 Build LAMMPS with make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.2.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.2.3 Customized builds and alternate makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.3 Link LAMMPS as a library to another code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.3.1 Link with LAMMPS as a static library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.3.2 Link with LAMMPS as a shared library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.4 Basic build options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.4.1 Serial vs parallel build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.4.2 Choice of compiler and compile/link options . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.4.3 Build the LAMMPS executable and library . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.4.4 Including or removing debug support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4.5 Build LAMMPS tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4.6 Install LAMMPS after a build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3.5 Optional build settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3.5.1 C++11 standard compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.5.2 FFT library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.5.3 Size of LAMMPS integer types and size limits . . . . . . . . . . . . . . . . . . . . . . . . 45
3.5.4 Output of JPG, PNG, and movie files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.5.5 Read or write compressed files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.5.6 Memory allocation alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.5.7 Workaround for long long integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.5.8 Exception handling when using LAMMPS as a library . . . . . . . . . . . . . . . . . . . . 49
3.5.9 Trigger selected floating-point exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.6 Include packages in build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.6.1 Information for both build systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3.6.2 Make shortcuts for installing many packages . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.7 Packages with extra build options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.7.1 COMPRESS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.7.2 GPU package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.7.3 KIM package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.7.4 KOKKOS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
3.7.5 LATTE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
3.7.6 MESSAGE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3.7.7 ML-IAP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.7.8 MSCG package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.7.9 OPT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.7.10 POEMS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.7.11 PYTHON package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.7.12 VORONOI package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.7.13 ADIOS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.7.14 ATC package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.7.15 AWPMD package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
3.7.16 COLVARS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.7.17 ML-PACE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
3.7.18 PLUMED package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

ii
 3.7.19 H5MD package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
3.7.20 ML-HDNNP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
3.7.21 INTEL package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.7.22 MDI package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
3.7.23 MESONT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.7.24 MOLFILE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.7.25 NETCDF package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.7.26 OPENMP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.7.27 QMMM package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.7.28 ML-QUIP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.7.29 SCAFACOS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.7.30 MACHDYN package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
3.7.31 VTK package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.8 Build the LAMMPS documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.8.1 Build using GNU make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.8.2 Build using CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.8.3 Prerequisites for HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.8.4 Prerequisites for PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
3.8.5 Prerequisites for ePUB and MOBI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
3.8.6 Instructions for Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
3.9 Notes for building LAMMPS on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.9.1 General remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.9.2 Running Linux on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.9.3 Using a GNU GCC ported to Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
3.9.4 Using a cross-compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.9.5 Native Visual C++ support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
3.10 Notes for saving disk space when building LAMMPS from source . . . . . . . . . . . . . . . . . . . 86
3.11 Development build options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
3.11.1 Monitor compilation flags (CMake only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
3.11.2 Enable static code analysis with clang-tidy (CMake only) . . . . . . . . . . . . . . . . . . . 87
3.11.3 Report missing and unneeded ‘#include’ statements (CMake only) . . . . . . . . . . . . . . 87
3.11.4 Address, Undefined Behavior, and Thread Sanitizer Support (CMake only) . . . . . . . . . . 88
3.11.5 Code Coverage and Unit Testing (CMake only) . . . . . . . . . . . . . . . . . . . . . . . . 88
3.11.6 Coding style utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
3.11.7 Clang-format support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

4 Run LAMMPS 95
4.1 Basics of running LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.2 Command-line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
4.3 Screen and logfile output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.4 Running LAMMPS on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

5 Commands 109
5.1 LAMMPS input scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
5.2 Parsing rules for input scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
5.3 Input script structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
5.3.1 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.3.2 System definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.3.3 Simulation settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.3.4 Run a simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.4 Commands by category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.4.1 Initialization: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.4.2 Setup simulation box: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.4.3 Setup atoms: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

iii
 5.4.4 Force fields: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.4.5 Settings: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
5.4.6 Operations within timestepping (fixes) and diagnostics (computes): . . . . . . . . . . . . . . 114
5.4.7 Output: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.4.8 Actions: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.4.9 Input script control: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.5 General commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
5.6 Fix commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.7 Compute commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.8 Pair_style potentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.9 Bond_style potentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.10 Angle_style potentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.11 Dihedral_style potentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.12 Improper_style potentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.13 KSpace solvers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.14 Removed commands and packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.14.1 Fix ave/spatial and fix ave/spatial/sphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.14.2 Reset_ids command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.14.3 MEAM package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.14.4 REAX package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.14.5 USER-CUDA package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.14.6 restart2data tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

6 Optional packages 125

6.1 Available Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
6.2 Package details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6.2.1 ADIOS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
6.2.2 ASPHERE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.2.3 ATC package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.2.4 AWPMD package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.2.5 BOCS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.2.6 BODY package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.2.7 BROWNIAN package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.2.8 CG-DNA package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.2.9 CG-SDK package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.2.10 CLASS2 package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.2.11 COLLOID package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.2.12 COLVARS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2.13 COMPRESS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2.14 CORESHELL package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.2.15 DIELECTRIC package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.2.16 DIFFRACTION package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.2.17 DIPOLE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.2.18 DPD-BASIC package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.2.19 DPD-MESO package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.2.20 DPD-REACT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.2.21 DPD-SMOOTH package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.2.22 DRUDE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.2.23 EFF package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.2.24 EXTRA-COMPUTE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.2.25 EXTRA-DUMP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.2.26 EXTRA-FIX package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.2.27 EXTRA-MOLECULE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.2.28 EXTRA-PAIR package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

iv
6.2.29 FEP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.2.30 GPU package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.2.31 GRANULAR package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6.2.32 H5MD package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.2.33 INTEL package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.2.34 INTERLAYER package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.2.35 KIM package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.2.36 KOKKOS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.2.37 KSPACE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
6.2.38 LATBOLTZ package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
6.2.39 LATTE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.2.40 MACHDYN package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.2.41 MANIFOLD package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
6.2.42 MANYBODY package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
6.2.43 MC package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.2.44 MDI package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.2.45 MEAM package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
6.2.46 MESONT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
6.2.47 MESSAGE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.2.48 MGPT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
6.2.49 MISC package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6.2.50 ML-HDNNP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6.2.51 ML-IAP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.2.52 ML-PACE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.2.53 ML-QUIP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.2.54 ML-RANN package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6.2.55 ML-SNAP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
6.2.56 MOFFF package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
6.2.57 MOLECULE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.2.58 MOLFILE package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.2.59 MPIIO package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.2.60 MSCG package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.2.61 NETCDF package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.2.62 OPENMP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
6.2.63 OPT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.2.64 ORIENT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.2.65 PERI package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.2.66 PHONON package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6.2.67 PLUGIN package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.2.68 PLUMED package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.2.69 POEMS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.2.70 PTM package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.2.71 PYTHON package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.2.72 QEQ package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.2.73 QMMM package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.2.74 QTB package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.2.75 REACTION package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.2.76 REAXFF package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
6.2.77 REPLICA package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
6.2.78 RIGID package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
6.2.79 SCAFACOS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
6.2.80 SHOCK package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
6.2.81 SMTBQ package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
6.2.82 SPH package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

v
 6.2.83 SPIN package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.2.84 SRD package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
6.2.85 TALLY package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
6.2.86 UEF package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
6.2.87 VORONOI package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
6.2.88 VTK package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
6.2.89 YAFF package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

7 Accelerate performance 171

7.1 Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
7.2 Measuring performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
7.3 General tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.4 Accelerator packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
7.4.1 GPU package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
7.4.2 INTEL package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
7.4.3 KOKKOS package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.4.4 OPENMP package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
7.4.5 OPT package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
7.5 Comparison of various accelerator packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

8 Howto discussions 201

8.1 General howto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.1.1 Restart a simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.1.2 Visualize LAMMPS snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
8.1.3 Run multiple simulations from one input script . . . . . . . . . . . . . . . . . . . . . . . . 203
8.1.4 Multi-replica simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.1.5 Library interface to LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.1.6 Coupling LAMMPS to other codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.1.7 Using LAMMPS in client/server mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
8.1.8 Using LAMMPS with the MDI library for code coupling . . . . . . . . . . . . . . . . . . . 208
8.2 Settings howto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.2.1 2d simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.2.2 Triclinic (non-orthogonal) simulation boxes . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.2.3 Thermostats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.2.4 Barostats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
8.2.5 Walls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.2.6 NEMD simulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.2.7 Long-range dispersion settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.3 Analysis howto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.3.1 Output from LAMMPS (thermo, dumps, computes, fixes, variables) . . . . . . . . . . . . . 218
8.3.2 Use chunks to calculate system properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
8.3.3 Calculate temperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
8.3.4 Calculate elastic constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.3.5 Calculate thermal conductivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.3.6 Calculate viscosity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
8.3.7 Calculate diffusion coefficients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.3.8 Output structured data from LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.4 Force fields howto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
8.4.1 CHARMM, AMBER, COMPASS, and DREIDING force fields . . . . . . . . . . . . . . . . 234
8.4.2 TIP3P water model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
8.4.3 TIP4P water model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.4.4 SPC water model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
8.5 Packages howto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
8.5.1 Finite-size spherical and aspherical particles . . . . . . . . . . . . . . . . . . . . . . . . . . 240

vi
 8.5.2 Granular models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
8.5.3 Body particles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
8.5.4 Polarizable models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
8.5.5 Adiabatic core/shell model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
8.5.6 Drude induced dipoles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
8.5.7 Tutorial for Thermalized Drude oscillators in LAMMPS . . . . . . . . . . . . . . . . . . . 255
8.5.8 Manifolds (surfaces) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
8.5.9 Magnetic spins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
8.6 Tutorials howto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
8.6.1 Using CMake with LAMMPS tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
8.6.2 LAMMPS GitHub tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
8.6.3 PyLammps Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
8.6.4 Using LAMMPS on Windows 10 with WSL . . . . . . . . . . . . . . . . . . . . . . . . . . 296

9 Example scripts 307

9.1 Lowercase directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
9.2 Uppercase directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

10 Auxiliary tools 311

10.1 Pre-processing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
10.2 Post-processing tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
10.3 Miscellaneous tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
10.4 Tool descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
10.4.1 amber2lmp tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
10.4.2 binary2txt tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
10.4.3 ch2lmp tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
10.4.4 chain tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
10.4.5 CMake tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
10.4.6 colvars tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
10.4.7 createatoms tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
10.4.8 drude tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
10.4.9 eam database tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
10.4.10 eam generate tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
10.4.11 eff tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
10.4.12 emacs tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
10.4.13 fep tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
10.4.14 i-pi tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
10.4.15 ipp tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
10.4.16 kate tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
10.4.17 LAMMPS shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
10.4.18 lmp2arc tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
10.4.19 lmp2cfg tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
10.4.20 Magic patterns for the “file” command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
10.4.21 matlab tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
10.4.22 micelle2d tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
10.4.23 moltemplate tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
10.4.24 msi2lmp tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
10.4.25 Scripts for building LAMMPS when offline . . . . . . . . . . . . . . . . . . . . . . . . . . 320
10.4.26 phonon tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
10.4.27 polybond tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
10.4.28 pymol_asphere tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
10.4.29 python tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
10.4.30 replica tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
10.4.31 smd tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

vii
 10.4.32 spin tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
10.4.33 singularity tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
10.4.34 SWIG interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
10.4.35 vim tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
10.4.36 xmgrace tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

11 Errors 327
11.1 Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
11.2 Reporting bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
11.3 Debugging crashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
11.3.1 Using the GDB debugger to get a stack trace . . . . . . . . . . . . . . . . . . . . . . . . . . 330
11.3.2 Using valgrind to get a stack trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
11.4 Error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
11.5 Warning messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

II Programmer Guide 427

12 LAMMPS Library Interfaces 429
12.1 LAMMPS C Library API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
12.1.1 Creating or deleting a LAMMPS object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
12.1.2 Executing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
12.1.3 System properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
12.1.4 Per-atom properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
12.1.5 Compute, fixes, variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
12.1.6 Scatter/gather operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
12.1.7 Neighbor list access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
12.1.8 Configuration information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
12.1.9 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
12.1.10 Extending the C API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
12.2 LAMMPS Python APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
12.3 LAMMPS Fortran API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
12.3.1 The LIBLAMMPS Fortran Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
12.3.2 Creating or deleting a LAMMPS object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
12.3.3 The LIBLAMMPS module API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
12.4 LAMMPS C++ API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
12.4.1 Using the C++ API directly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
12.4.2 Creating or deleting a LAMMPS object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
12.4.3 Executing LAMMPS commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475

13 Use Python with LAMMPS 477

13.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
13.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
13.2.1 Installing the LAMMPS Python Module and Shared Library . . . . . . . . . . . . . . . . . 479
13.2.2 Extending Python to run in parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
13.3 Run LAMMPS from Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
13.3.1 Running LAMMPS and Python in serial . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
13.3.2 Running LAMMPS and Python in parallel with MPI . . . . . . . . . . . . . . . . . . . . . 487
13.3.3 Running Python scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
13.3.4 Creating or deleting a LAMMPS object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
13.3.5 Executing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
13.3.6 System properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
13.3.7 Per-atom properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
13.3.8 Compute, fixes, variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496

viii
 13.3.9 Scatter/gather operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
13.3.10 Neighbor list access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
13.3.11 Configuration information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
13.4 The lammps Python module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
13.4.1 The lammps class API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
13.4.2 The PyLammps class API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
13.4.3 The IPyLammps class API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
13.4.4 Additional components of the lammps module . . . . . . . . . . . . . . . . . . . . . . . . . 521
13.5 Extending the Python interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
13.6 Calling Python from LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
13.7 Output Readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
13.8 Example Python scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
13.9 Handling LAMMPS errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
13.10 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
13.10.1 Testing if Python can launch LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

14 Modifying & extending LAMMPS 529

14.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
14.2 Submitting new features for inclusion in LAMMPS . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
14.2.1 Communication with the LAMMPS developers . . . . . . . . . . . . . . . . . . . . . . . . 531
14.2.2 Packages versus individual files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
14.2.3 Time and effort required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
14.2.4 Submission procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
14.2.5 Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
14.2.6 External contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
14.3 LAMMPS programming style and requirements for contributions . . . . . . . . . . . . . . . . . . . 532
14.3.1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
14.3.2 Licensing requirements (strict) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
14.3.3 Using Pull Requests on GitHub (preferred) . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
14.3.4 Integration Testing (strict) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
14.3.5 Documentation (strict) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
14.3.6 Examples (preferred) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
14.3.7 Howto document (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
14.3.8 Programming Style Requirements (varied) . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
14.3.9 Contributing a package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
14.3.10 Build system (strongly preferred) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
14.3.11 Citation reminder (suggested) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
14.3.12 Testing (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
14.4 Atom styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
14.5 Pair styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
14.6 Bond, angle, dihedral, improper styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
14.7 Compute styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
14.8 Fix styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
14.9 Input script command style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
14.10 Dump styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
14.11 Kspace styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
14.12 Minimization styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
14.13 Region styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
14.14 Body styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
14.15 Thermodynamic output options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
14.16 Variable options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546

15 Information for Developers 549

15.1 Source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

ix
 15.2 Class topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
15.3 Parallel algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
15.3.1 Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553
15.3.2 Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
15.3.3 Neighbor lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
15.3.4 Long-range interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
15.3.5 OpenMP Parallelism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
15.4 How a timestep works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
15.5 Writing new styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
15.5.1 Writing a new fix style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
15.6 Notes for developers and code maintainers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
15.6.1 Fix contributions to instantaneous energy, virial, and cumulative energy . . . . . . . . . . . 569
15.6.2 KSpace PPPM FFT grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
15.7 Writing plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
15.7.1 Members of lammpsplugin_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
15.7.2 Pair style example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
15.7.3 Fix style example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
15.7.4 Command style example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574
15.7.5 Additional Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
15.8 Adding tests for unit testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
15.8.1 Tests for utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
15.8.2 Tests for individual LAMMPS commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
15.8.3 Tests for the C-style library interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
15.8.4 Tests for the Python module and package . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
15.8.5 Tests for the Fortran interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
15.8.6 Tests for the C++-style library interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
15.8.7 Tests for reading and writing file formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
15.8.8 Tests for styles computing or modifying forces . . . . . . . . . . . . . . . . . . . . . . . . . 580
15.8.9 Tests for programs in the tools folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
15.9 C++ base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
15.9.1 LAMMPS Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
15.9.2 LAMMPS Atom and AtomVec Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . 585
15.9.3 LAMMPS Input Base Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
15.10 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
15.10.1 I/O with status check and similar functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
15.10.2 String to number conversions with validity check . . . . . . . . . . . . . . . . . . . . . . . 591
15.10.3 String processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592
15.10.4 File and path functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
15.10.5 Potential file functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596
15.10.6 Argument processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
15.10.7 Convenience functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598
15.10.8 Customized standard functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
15.11 Tokenizer classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
15.12 Argument parsing classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604
15.13 File reader classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606
15.14 Memory pool classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
15.15 Eigensolver functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614
15.16 Communication buffer coding with ubuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614

III Command Reference 617

16 Commands 619
16.1 angle_coeff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

x
 16.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
16.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
16.1.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
16.1.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
16.1.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
16.1.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
16.2 angle_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
16.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
16.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
16.2.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
16.2.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
16.2.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
16.2.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
16.3 atom_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
16.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
16.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
16.3.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
16.3.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
16.3.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
16.3.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
16.4 atom_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
16.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
16.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
16.4.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
16.4.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
16.4.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
16.4.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
16.5 balance command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
16.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
16.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630
16.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631
16.5.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
16.5.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
16.5.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
16.6 bond_coeff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
16.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
16.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
16.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
16.6.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
16.6.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
16.6.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
16.7 bond_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
16.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
16.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
16.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
16.7.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
16.7.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
16.7.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
16.8 bond_write command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
16.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
16.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
16.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
16.8.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
16.8.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641

xi
 16.8.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
16.9 boundary command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
16.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
16.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
16.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
16.9.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
16.9.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
16.9.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
16.10 box command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
16.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
16.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
16.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
16.10.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
16.10.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
16.10.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
16.11 change_box command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
16.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
16.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
16.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
16.11.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
16.11.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
16.11.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.12 clear command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.12.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.12.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.12.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
16.13 comm_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
16.13.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
16.13.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
16.13.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
16.13.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
16.13.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
16.13.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
16.14 comm_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
16.14.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
16.14.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
16.14.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
16.14.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
16.14.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
16.14.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
16.15 compute command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
16.15.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
16.15.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
16.15.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
16.15.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
16.15.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
16.15.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
16.16 compute_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
16.16.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
16.16.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
16.16.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

xii
 16.16.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
16.16.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
16.16.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
16.17 create_atoms command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
16.17.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
16.17.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
16.17.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
16.17.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
16.17.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
16.17.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
16.18 create_bonds command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
16.18.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
16.18.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
16.18.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
16.18.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
16.18.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
16.18.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
16.19 create_box command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
16.19.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
16.19.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
16.19.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
16.19.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
16.19.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
16.19.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
16.20 delete_atoms command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
16.20.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
16.20.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
16.20.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
16.20.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
16.20.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
16.20.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
16.21 delete_bonds command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
16.21.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
16.21.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
16.21.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
16.21.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
16.21.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
16.21.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
16.22 dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.22.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.22.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.22.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.22.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.22.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.22.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.23 dihedral_coeff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.23.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
16.23.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
16.23.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
16.23.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
16.23.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
16.23.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
16.24 dihedral_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
16.24.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678

xiii
 16.24.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
16.24.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
16.24.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.24.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.24.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.25 dimension command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.25.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.25.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.25.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
16.25.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
16.25.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
16.25.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
16.26 displace_atoms command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
16.26.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
16.26.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
16.26.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
16.26.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.26.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.26.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.27 dump command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.28 dump vtk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.29 dump h5md command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.30 dump molfile command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.31 dump netcdf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.32 dump image command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.33 dump movie command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.34 dump atom/adios command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.35 dump custom/adios command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.35.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
16.35.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
16.35.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
16.35.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
16.35.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
16.35.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
16.36 dump atom/adios command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
16.37 dump custom/adios command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
16.37.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
16.37.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
16.37.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
16.37.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
16.37.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
16.38 dump cfg/uef command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
16.38.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
16.38.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
16.38.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
16.38.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
16.38.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
16.38.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
16.39 dump h5md command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
16.39.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
16.39.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
16.39.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
16.39.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
16.39.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696

xiv
16.40 dump image command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
16.41 dump movie command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
16.41.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
16.41.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
16.41.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
16.41.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
16.41.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
16.41.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
16.42 dump_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
16.42.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
16.42.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
16.42.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
16.42.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
16.42.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
16.42.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
16.43 dump molfile command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
16.43.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
16.43.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
16.43.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
16.43.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
16.43.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
16.43.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
16.44 dump netcdf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
16.45 dump netcdf/mpiio command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
16.45.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
16.45.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
16.45.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
16.45.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
16.45.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
16.46 dump vtk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
16.46.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
16.46.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
16.46.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
16.46.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
16.46.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
16.46.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
16.47 dynamical_matrix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
16.47.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
16.47.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
16.47.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
16.47.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
16.47.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
16.47.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
16.48 echo command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.48.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.48.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.48.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.48.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.48.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.48.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.49 fix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.49.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
16.49.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
16.49.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730

xv
 16.49.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
16.49.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
16.49.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
16.50 fix_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
16.50.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
16.50.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
16.50.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739
16.50.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
16.50.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
16.50.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
16.51 group command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
16.51.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
16.51.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
16.51.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742
16.51.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
16.51.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
16.51.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
16.52 group2ndx command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
16.53 ndx2group command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
16.53.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
16.53.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745
16.53.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
16.53.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
16.53.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
16.53.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
16.54 hyper command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
16.54.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746
16.54.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
16.54.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
16.54.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
16.54.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
16.54.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
16.55 if command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
16.55.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
16.55.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
16.55.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
16.55.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
16.55.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
16.55.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
16.56 improper_coeff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
16.56.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
16.56.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
16.56.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
16.56.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
16.56.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
16.56.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
16.57 improper_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
16.57.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
16.57.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
16.57.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
16.57.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
16.57.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
16.57.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
16.58 include command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755

xvi
 16.58.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
16.58.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
16.58.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
16.58.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
16.58.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
16.58.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
16.59 info command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
16.59.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
16.59.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
16.59.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
16.59.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
16.59.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
16.59.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
16.60 jump command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
16.60.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
16.60.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
16.60.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
16.60.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
16.60.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
16.60.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
16.61 kim command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
16.61.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
16.61.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
16.61.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
16.61.4 Using OpenKIM IMs with LAMMPS (kim init, kim interactions) . . . . . . . . . . . . . . . 762
16.61.5 Using OpenKIM Web Queries in LAMMPS (kim query) . . . . . . . . . . . . . . . . . . . 766
16.61.6 Accessing KIM Model Parameters from LAMMPS (kim param) . . . . . . . . . . . . . . . 769
16.61.7 Writing material properties in standard KIM Property Instance format (kim property) . . . . 773
16.61.8 Citation of OpenKIM IMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
16.61.9 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778
16.61.10Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
16.62 kspace_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
16.62.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779
16.62.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
16.62.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
16.62.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784
16.62.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
16.62.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
16.63 kspace_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
16.63.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785
16.63.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
16.63.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
16.63.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
16.63.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
16.63.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791
16.64 label command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
16.64.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
16.64.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
16.64.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
16.64.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
16.64.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
16.64.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
16.65 lattice command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
16.65.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793

xvii
 16.65.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
16.65.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793
16.65.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
16.65.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796
16.65.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.66 log command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.66.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.66.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.66.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.66.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.66.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
16.66.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
16.67 mass command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
16.67.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
16.67.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
16.67.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798
16.67.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
16.67.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
16.67.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
16.68 mdi_engine command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
16.68.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
16.68.2 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799
16.68.3 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.68.4 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.68.5 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.69 message command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.69.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800
16.69.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
16.69.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801
16.69.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.69.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.69.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.70 min_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.70.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803
16.70.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804
16.70.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804
16.70.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
16.70.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
16.70.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
16.71 min_style spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
16.72 min_style spin/cg command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
16.73 min_style spin/lbfgs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
16.73.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
16.73.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
16.73.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
16.73.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
16.73.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
16.73.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
16.74 min_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
16.74.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
16.74.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
16.74.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
16.74.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
16.74.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809

xviii
 16.74.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
16.75 minimize command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
16.76 minimize/kk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
16.76.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809
16.76.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
16.76.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810
16.76.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813
16.76.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
16.76.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
16.77 molecule command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
16.77.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
16.77.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814
16.77.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815
16.77.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
16.77.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
16.77.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
16.78 neb command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
16.78.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821
16.78.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
16.78.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 822
16.78.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
16.78.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
16.78.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826
16.79 neb/spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
16.79.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
16.79.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
16.79.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 827
16.79.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
16.79.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
16.79.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
16.80 neigh_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
16.80.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
16.80.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832
16.80.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833
16.80.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
16.80.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
16.80.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
16.81 neighbor command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
16.81.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
16.81.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
16.81.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
16.81.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
16.81.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
16.81.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836
16.82 newton command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
16.82.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
16.82.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
16.82.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
16.82.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
16.82.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
16.82.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
16.83 next command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
16.83.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
16.83.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838

xix
 16.83.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838
16.83.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
16.83.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
16.83.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
16.84 package command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
16.84.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840
16.84.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
16.84.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
16.84.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
16.84.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
16.84.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
16.85 pair_coeff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
16.85.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
16.85.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
16.85.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
16.85.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
16.85.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
16.85.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
16.86 pair_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
16.86.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
16.86.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
16.86.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
16.86.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
16.86.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
16.86.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
16.87 pair_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
16.87.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
16.87.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
16.87.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
16.87.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
16.87.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
16.87.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
16.88 pair_write command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
16.88.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
16.88.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
16.88.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864
16.88.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
16.88.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
16.88.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
16.89 partition command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
16.89.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
16.89.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865
16.89.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
16.89.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
16.89.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
16.89.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
16.90 plugin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
16.90.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866
16.90.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
16.90.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
16.90.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
16.90.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
16.90.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
16.91 prd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868

xx
 16.91.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 868
16.91.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
16.91.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869
16.91.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
16.91.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
16.91.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
16.92 print command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
16.92.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
16.92.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872
16.92.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
16.92.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
16.92.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
16.92.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873
16.93 processors command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
16.93.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
16.93.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874
16.93.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875
16.93.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
16.93.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
16.93.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
16.94 python command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
16.94.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878
16.94.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879
16.94.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880
16.94.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
16.94.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
16.94.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
16.95 quit command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
16.95.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
16.95.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
16.95.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885
16.95.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
16.95.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
16.95.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
16.96 read_data command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
16.96.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 886
16.96.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
16.96.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
16.96.4 Reading multiple data files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887
16.96.5 Format of a data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
16.96.6 Format of the header of a data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889
16.96.7 Format of the body of a data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 892
16.96.8 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
16.96.9 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
16.96.10Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
16.97 read_dump command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
16.97.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904
16.97.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905
16.97.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905
16.97.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908
16.97.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
16.97.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
16.98 read_restart command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
16.98.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909

xxi
 16.98.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
16.98.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909
16.98.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
16.98.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
16.98.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
16.99 region command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
16.99.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912
16.99.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
16.99.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 914
16.99.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917
16.99.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
16.99.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
16.100replicate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
16.100.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
16.100.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
16.100.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918
16.100.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
16.100.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
16.100.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
16.101rerun command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
16.101.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919
16.101.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
16.101.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920
16.101.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
16.101.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
16.101.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
16.102reset_atom_ids command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
16.102.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
16.102.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922
16.102.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
16.102.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
16.102.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
16.102.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923
16.103reset_mol_ids command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
16.103.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
16.103.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
16.103.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924
16.103.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
16.103.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
16.103.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
16.104reset_timestep command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
16.104.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
16.104.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
16.104.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925
16.104.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
16.104.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
16.104.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
16.105restart command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
16.105.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926
16.105.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
16.105.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927
16.105.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
16.105.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
16.105.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929

xxii
16.106run command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
16.106.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
16.106.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
16.106.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929
16.106.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931
16.106.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
16.106.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
16.107run_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
16.107.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932
16.107.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
16.107.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933
16.107.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
16.107.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
16.107.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
16.108server command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
16.108.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
16.108.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936
16.108.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
16.108.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
16.108.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
16.108.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
16.109server mc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
16.109.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937
16.109.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
16.109.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938
16.109.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
16.109.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
16.109.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
16.110server md command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
16.110.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
16.110.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939
16.110.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940
16.110.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
16.110.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
16.110.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
16.111set command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
16.111.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942
16.111.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
16.111.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944
16.111.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
16.111.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948
16.111.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
16.112shell command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
16.112.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
16.112.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
16.112.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949
16.112.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
16.112.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
16.112.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
16.113special_bonds command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
16.113.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950
16.113.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951
16.113.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951
16.113.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953

xxiii
 16.113.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953
16.113.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
16.114suffix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
16.114.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
16.114.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
16.114.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954
16.114.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
16.114.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
16.114.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955
16.115tad command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
16.115.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
16.115.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
16.115.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957
16.115.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
16.115.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
16.115.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959
16.116temper command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
16.116.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
16.116.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
16.116.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960
16.116.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
16.116.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
16.116.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
16.117temper/grem command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
16.117.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
16.117.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
16.117.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962
16.117.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
16.117.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963
16.117.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
16.118temper/npt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
16.118.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
16.118.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
16.118.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964
16.118.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
16.118.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
16.118.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
16.119thermo command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
16.119.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
16.119.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
16.119.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965
16.119.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
16.119.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
16.119.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
16.120thermo_modify command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
16.120.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
16.120.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966
16.120.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967
16.120.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
16.120.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
16.120.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
16.121thermo_style command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
16.121.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969
16.121.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971

xxiv
 16.121.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 971
16.121.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974
16.121.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
16.121.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
16.122third_order command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
16.122.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
16.122.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
16.122.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975
16.122.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
16.122.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
16.122.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
16.123timer command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
16.123.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
16.123.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
16.123.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
16.123.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.123.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.123.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.124timestep command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.124.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.124.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.124.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.124.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978
16.124.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
16.124.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
16.125uncompute command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
16.125.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
16.125.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
16.125.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
16.125.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979
16.125.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.125.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.126undump command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.126.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.126.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.126.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.126.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.126.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.126.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980
16.127unfix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.127.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.127.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.127.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.127.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.127.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.127.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.128units command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.128.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981
16.128.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
16.128.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982
16.128.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
16.128.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
16.128.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
16.129variable command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986

xxv
 16.129.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986
16.129.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
16.129.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
16.129.4Immediate Evaluation of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
16.129.5Variable Accuracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
16.129.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
16.129.7Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
16.129.8Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
16.130velocity command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
16.130.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
16.130.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
16.130.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006
16.130.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
16.130.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
16.130.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
16.131write_coeff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
16.131.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
16.131.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
16.131.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
16.131.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
16.131.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
16.132write_data command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
16.132.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
16.132.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
16.132.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
16.132.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010
16.132.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
16.132.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
16.133write_dump command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
16.133.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
16.133.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011
16.133.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
16.133.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
16.133.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
16.133.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
16.134write_restart command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
16.134.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
16.134.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
16.134.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013
16.134.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
16.134.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
16.134.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014

17 Fixes 1015
17.1 fix accelerate/cos command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
17.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
17.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
17.1.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015
17.1.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1016
17.1.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
17.1.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
17.1.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
17.2 fix adapt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
17.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016

xxvi
 17.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
17.2.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
17.2.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1021
17.2.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
17.2.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
17.2.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021
17.3 fix adapt/fep command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
17.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
17.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
17.3.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
17.3.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1026
17.3.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
17.3.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
17.3.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
17.4 fix addforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
17.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
17.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
17.4.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
17.4.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1028
17.4.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
17.4.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028
17.4.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
17.5 fix addtorque command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
17.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
17.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
17.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
17.5.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1029
17.5.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
17.5.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
17.5.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
17.6 fix append/atoms command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
17.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
17.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
17.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
17.6.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1032
17.6.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
17.6.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
17.6.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
17.7 fix atc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
17.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032
17.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
17.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
17.7.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1035
17.7.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
17.7.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035
17.7.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037
17.8 fix atom/swap command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
17.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1038
17.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
17.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039
17.8.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1040
17.8.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040
17.8.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
17.8.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041

xxvii
 17.9 fix ave/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
17.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
17.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041
17.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042
17.9.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1043
17.9.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
17.9.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
17.9.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
17.10 fix ave/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
17.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043
17.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
17.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045
17.10.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1049
17.10.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
17.10.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
17.10.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
17.11 fix ave/correlate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
17.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050
17.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051
17.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051
17.11.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1054
17.11.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1054
17.11.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
17.11.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
17.12 fix ave/correlate/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
17.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055
17.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056
17.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056
17.12.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1057
17.12.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
17.12.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
17.12.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
17.13 fix ave/histo command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
17.14 fix ave/histo/weight command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
17.14.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057
17.14.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058
17.14.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1059
17.14.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1062
17.14.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
17.14.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
17.14.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
17.15 fix ave/time command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
17.15.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1062
17.15.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063
17.15.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
17.15.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1066
17.15.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
17.15.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
17.15.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
17.16 fix aveforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
17.16.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
17.16.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
17.16.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068
17.16.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1068

xxviii
 17.16.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
17.16.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
17.16.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
17.17 fix balance command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
17.17.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069
17.17.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070
17.17.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070
17.17.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1074
17.17.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
17.17.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
17.17.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
17.18 fix bocs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
17.18.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074
17.18.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
17.18.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
17.18.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1076
17.18.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
17.18.6 Further information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076
17.19 fix bond/break command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
17.19.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
17.19.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
17.19.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
17.19.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1078
17.19.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078
17.19.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
17.19.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
17.20 fix bond/create command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
17.21 fix bond/create/angle command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
17.21.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079
17.21.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
17.21.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080
17.21.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1082
17.21.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
17.21.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
17.21.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
17.22 fix bond/react command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
17.22.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1082
17.22.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
17.22.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084
17.22.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1090
17.22.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
17.22.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
17.22.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
17.23 fix bond/swap command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
17.23.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
17.23.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091
17.23.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092
17.23.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1094
17.23.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
17.23.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
17.23.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
17.24 fix box/relax command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
17.24.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
17.24.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095

xxix
 17.24.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095
17.24.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1098
17.24.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
17.24.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
17.24.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
17.25 fix brownian command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
17.26 fix brownian/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
17.27 fix brownian/asphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
17.27.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099
17.27.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100
17.27.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100
17.27.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1101
17.27.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
17.27.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
17.27.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
17.28 fix charge/regulation command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
17.28.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102
17.28.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
17.28.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103
17.28.4 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105
17.28.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105
17.28.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105
17.28.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
17.29 fix client/md command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
17.29.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
17.29.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
17.29.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106
17.29.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1107
17.29.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
17.29.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
17.29.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107
17.30 fix cmap command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
17.30.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
17.30.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
17.30.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108
17.30.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1109
17.30.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1109
17.30.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
17.30.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
17.31 fix colvars command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
17.31.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
17.31.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
17.31.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110
17.31.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1111
17.31.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111
17.31.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
17.31.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
17.32 fix controller command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
17.32.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
17.32.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112
17.32.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113
17.32.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1114
17.32.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
17.32.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115

xxx
 17.32.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
17.33 fix deform command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
17.33.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115
17.33.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116
17.33.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116
17.33.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1122
17.33.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
17.33.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
17.33.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
17.34 fix deposit command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
17.34.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
17.34.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
17.34.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
17.34.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1126
17.34.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
17.34.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126
17.34.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
17.35 fix dpd/energy command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
17.35.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
17.35.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
17.35.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1127
17.35.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
17.35.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
17.35.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
17.36 fix edpd/source command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
17.37 fix tdpd/source command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
17.37.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128
17.37.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
17.37.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
17.37.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1129
17.37.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
17.37.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129
17.37.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
17.38 fix drag command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
17.38.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
17.38.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
17.38.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1130
17.38.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1130
17.38.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
17.38.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
17.38.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
17.39 fix drude command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
17.39.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
17.39.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
17.39.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131
17.39.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.39.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.39.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.40 fix drude/transform/direct command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.41 fix drude/transform/inverse command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.41.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.41.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.41.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1132
17.41.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1134

xxxi
 17.41.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134
17.41.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
17.41.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
17.42 fix dt/reset command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
17.42.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
17.42.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135
17.42.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
17.42.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1136
17.42.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136
17.42.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
17.42.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
17.43 fix efield command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
17.43.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
17.43.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
17.43.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137
17.43.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1138
17.43.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
17.43.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
17.43.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
17.44 fix ehex command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
17.44.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139
17.44.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1140
17.44.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1140
17.44.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1141
17.44.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
17.44.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
17.44.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
17.45 fix electron/stopping command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
17.46 fix electron/stopping/fit command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
17.46.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1142
17.46.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
17.46.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143
17.46.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1144
17.46.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144
17.46.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
17.47 fix enforce2d command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
17.47.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
17.47.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
17.47.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145
17.47.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1146
17.47.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
17.47.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
17.47.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
17.48 fix eos/cv command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
17.48.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
17.48.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1146
17.48.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
17.48.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
17.48.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
17.48.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
17.49 fix eos/table command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
17.49.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147
17.49.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148
17.49.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148

xxxii
 17.49.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
17.49.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
17.49.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
17.50 fix eos/table/rx command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
17.50.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149
17.50.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1150
17.50.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1150
17.50.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152
17.50.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152
17.50.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152
17.51 fix evaporate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152
17.51.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152
17.51.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
17.51.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
17.51.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1153
17.51.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153
17.51.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
17.51.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
17.52 fix external command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
17.52.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
17.52.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
17.52.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1154
17.52.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1156
17.52.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
17.52.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
17.52.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
17.53 fix ffl command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
17.53.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156
17.53.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157
17.53.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157
17.53.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1157
17.53.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
17.53.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
17.54 fix filter/corotate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
17.54.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
17.54.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1158
17.54.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
17.54.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1159
17.54.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
17.54.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
17.54.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
17.55 fix flow/gauss command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
17.55.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
17.55.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1160
17.55.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1160
17.55.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1161
17.55.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161
17.55.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161
17.55.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
17.56 fix freeze command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
17.56.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
17.56.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
17.56.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1162
17.56.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1163

xxxiii
 17.56.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163
17.56.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163
17.56.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163
17.57 fix gcmc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163
17.57.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163
17.57.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1164
17.57.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1164
17.57.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1168
17.57.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169
17.57.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169
17.57.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169
17.58 fix gld command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169
17.58.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169
17.58.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1170
17.58.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1170
17.58.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1171
17.58.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1171
17.58.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
17.58.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
17.59 fix gle command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
17.59.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
17.59.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172
17.59.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173
17.59.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1173
17.59.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
17.59.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
17.60 fix gravity command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
17.60.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174
17.60.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175
17.60.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175
17.60.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1176
17.60.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
17.60.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
17.60.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
17.61 fix grem command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
17.61.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176
17.61.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1177
17.61.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1177
17.61.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1177
17.61.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
17.61.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
17.61.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
17.62 fix halt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
17.62.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1178
17.62.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1179
17.62.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1179
17.62.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1180
17.62.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1180
17.62.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1180
17.62.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1180
17.63 fix heat command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
17.63.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
17.63.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181
17.63.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181

xxxiv
 17.63.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1182
17.63.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1182
17.63.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1182
17.63.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
17.64 fix hyper/global command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
17.64.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
17.64.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
17.64.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1183
17.64.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1185
17.64.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
17.64.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
17.64.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
17.65 fix hyper/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
17.65.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186
17.65.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1187
17.65.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1187
17.65.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1191
17.65.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
17.65.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
17.65.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
17.66 fix imd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
17.66.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193
17.66.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194
17.66.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1194
17.66.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1195
17.66.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
17.66.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
17.66.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
17.67 fix indent command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
17.67.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195
17.67.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196
17.67.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196
17.67.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1198
17.67.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198
17.67.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198
17.67.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198
17.68 fix ipi command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198
17.68.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198
17.68.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1199
17.68.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1199
17.68.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1199
17.68.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1199
17.68.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1200
17.69 fix langevin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1200
17.69.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1200
17.69.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
17.69.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201
17.69.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1203
17.69.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
17.69.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
17.69.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
17.70 fix langevin/drude command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
17.70.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
17.70.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205

xxxv
 17.70.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205
17.70.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1208
17.70.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
17.70.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
17.70.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
17.71 fix langevin/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
17.71.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208
17.71.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1209
17.71.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1209
17.71.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1209
17.71.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
17.71.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
17.71.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
17.72 fix langevin/spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
17.72.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
17.72.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
17.72.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210
17.72.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1211
17.72.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
17.72.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
17.72.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
17.73 fix latte command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
17.73.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
17.73.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
17.73.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212
17.73.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1213
17.73.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1213
17.73.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
17.73.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
17.74 fix lb/fluid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
17.74.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214
17.74.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1216
17.74.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1216
17.74.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1219
17.74.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
17.74.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
17.74.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219
17.75 fix lb/momentum command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
17.75.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
17.75.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
17.75.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220
17.75.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1221
17.75.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
17.75.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
17.75.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
17.76 fix lb/pc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
17.76.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
17.76.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
17.76.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1221
17.76.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1222
17.76.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222
17.76.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222
17.76.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222
17.77 fix lb/rigid/pc/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222

xxxvi
 17.77.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222
17.77.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
17.77.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223
17.77.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1223
17.77.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224
17.77.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224
17.77.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224
17.78 fix lb/viscous command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224
17.78.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224
17.78.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225
17.78.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225
17.78.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1225
17.78.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225
17.78.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
17.78.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
17.79 fix lineforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
17.79.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
17.79.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
17.79.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
17.79.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1226
17.79.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
17.79.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
17.79.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
17.80 fix manifoldforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
17.80.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
17.80.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
17.80.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227
17.80.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1227
17.80.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
17.80.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
17.81 fix mdi/engine command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
17.81.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
17.81.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
17.81.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228
17.81.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
17.81.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
17.81.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
17.82 fix meso/move command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
17.82.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
17.82.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1230
17.82.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1230
17.82.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1232
17.82.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
17.82.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
17.82.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
17.83 fix_modify AtC commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
17.83.1 fix_modify AtC add_molecule command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232
17.83.2 fix_modify AtC add_species command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1233
17.83.3 fix_modify AtC atom_element_map command . . . . . . . . . . . . . . . . . . . . . . . . 1234
17.83.4 fix_modify AtC atom_weight command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235
17.83.5 fix_modify AtC atomic_charge command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236
17.83.6 fix_modify AtC boundary_dynamics command . . . . . . . . . . . . . . . . . . . . . . . . 1237
17.83.7 fix_modify AtC boundary_faceset command . . . . . . . . . . . . . . . . . . . . . . . . . . 1238
17.83.8 fix_modify AtC boundary type command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239

xxxvii
 17.83.9 fix_modify AtC consistent_fe_initialization command . . . . . . . . . . . . . . . . . . . . . 1239
17.83.10fix_modify AtC control localized_lambda command . . . . . . . . . . . . . . . . . . . . . 1240
17.83.11fix_modify AtC control momentum command . . . . . . . . . . . . . . . . . . . . . . . . . 1241
17.83.12fix_modify AtC control thermal command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1242
17.83.13fix_modify AtC decomposition command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1244
17.83.14fix_modify AtC extrinsic electron_integration command . . . . . . . . . . . . . . . . . . . 1245
17.83.15fix_modify AtC equilibrium_start command . . . . . . . . . . . . . . . . . . . . . . . . . . 1246
17.83.16fix_modify AtC extrinsic exchange command . . . . . . . . . . . . . . . . . . . . . . . . . 1246
17.83.17fix_modify AtC fe_md_boundary command . . . . . . . . . . . . . . . . . . . . . . . . . . 1247
17.83.18fix_modify AtC filter scale command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1248
17.83.19fix_modify AtC filter type command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1249
17.83.20fix_modify AtC fix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1250
17.83.21fix_modify AtC fix_flux command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1251
17.83.22fix_modify AtC computes command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1251
17.83.23fix_modify AtC fields command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1252
17.83.24fix_modify AtC gradients command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1254
17.83.25fix_modify AtC kernel command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256
17.83.26fix_modify AtC on_the_fly command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257
17.83.27fix_modify AtC rates command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258
17.83.28fix_modify AtC initial command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259
17.83.29fix_modify AtC internal_element_set command . . . . . . . . . . . . . . . . . . . . . . . . 1260
17.83.30fix_modify AtC internal_quadrature command . . . . . . . . . . . . . . . . . . . . . . . . . 1261
17.83.31fix_modify AtC kernel_bandwidth command . . . . . . . . . . . . . . . . . . . . . . . . . 1262
17.83.32fix_modify AtC control lumped_lambda_solve command . . . . . . . . . . . . . . . . . . . 1263
17.83.33fix_modify AtC control mask_direction command . . . . . . . . . . . . . . . . . . . . . . . 1263
17.83.34fix_modify AtC mass_matrix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264
17.83.35fix_modify AtC material command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265
17.83.36fix_modify AtC mesh add_to_nodeset command . . . . . . . . . . . . . . . . . . . . . . . 1266
17.83.37fix_modify AtC mesh create command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266
17.83.38fix_modify AtC mesh create_elementset command . . . . . . . . . . . . . . . . . . . . . . 1267
17.83.39fix_modify AtC mesh create_faceset box command . . . . . . . . . . . . . . . . . . . . . . 1268
17.83.40fix_modify AtC mesh create_faceset plane command . . . . . . . . . . . . . . . . . . . . . 1269
17.83.41fix_modify AtC mesh create_nodeset command . . . . . . . . . . . . . . . . . . . . . . . . 1270
17.83.42fix_modify AtC mesh delete_elements command . . . . . . . . . . . . . . . . . . . . . . . 1271
17.83.43fix_modify AtC mesh nodeset_to_elementset command . . . . . . . . . . . . . . . . . . . . 1272
17.83.44fix_modify AtC mesh output command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273
17.83.45fix_modify AtC mesh quadrature command . . . . . . . . . . . . . . . . . . . . . . . . . . 1273
17.83.46fix_modify AtC mesh read command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274
17.83.47fix_modify AtC mesh write command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275
17.83.48fix_modify AtC output command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276
17.83.49fix_modify AtC output boundary_integral command . . . . . . . . . . . . . . . . . . . . . 1277
17.83.50fix_modify AtC output contour_integral command . . . . . . . . . . . . . . . . . . . . . . 1278
17.83.51fix_modify AtC output nodeset command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279
17.83.52fix_modify AtC output volume_integral command . . . . . . . . . . . . . . . . . . . . . . . 1280
17.83.53fix_modify AtC pair_interactions command . . . . . . . . . . . . . . . . . . . . . . . . . . 1280
17.83.54fix_modify AtC bond_interactions command . . . . . . . . . . . . . . . . . . . . . . . . . 1280
17.83.55fix_modify AtC poisson_solver command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1281
17.83.56fix_modify AtC read_restart command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1282
17.83.57fix_modify AtC remove_molecule command . . . . . . . . . . . . . . . . . . . . . . . . . . 1283
17.83.58fix_modify AtC remove_source command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1284
17.83.59fix_modify AtC remove_species command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1284
17.83.60fix_modify AtC reset_atomic_reference_positions command . . . . . . . . . . . . . . . . . 1285
17.83.61fix_modify AtC reset_time command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286
17.83.62fix_modify AtC sample_frequency command . . . . . . . . . . . . . . . . . . . . . . . . . 1287

xxxviii
 17.83.63fix_modify AtC set reference_potential_energy command . . . . . . . . . . . . . . . . . . . 1288
17.83.64fix_modify AtC source command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1288
17.83.65fix_modify AtC source_integration command . . . . . . . . . . . . . . . . . . . . . . . . . 1289
17.83.66fix_modify AtC temperature_definition command . . . . . . . . . . . . . . . . . . . . . . . 1290
17.83.67fix_modify AtC filter command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291
17.83.68fix_modify AtC time_integration command . . . . . . . . . . . . . . . . . . . . . . . . . . 1292
17.83.69fix_modify AtC track_displacement command . . . . . . . . . . . . . . . . . . . . . . . . . 1293
17.83.70fix_modify AtC unfix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1294
17.83.71fix_modify AtC unfix_flux command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1294
17.83.72fix_modify AtC write_atom_weights command . . . . . . . . . . . . . . . . . . . . . . . . 1295
17.83.73fix_modify AtC write_restart command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296
17.84 fix momentum command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297
17.85 fix momentum/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297
17.85.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297
17.85.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1298
17.85.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1298
17.85.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1298
17.85.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299
17.85.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299
17.85.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299
17.86 fix move command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299
17.86.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299
17.86.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1300
17.86.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1300
17.86.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1302
17.86.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
17.86.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
17.86.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
17.87 fix mscg command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
17.87.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302
17.87.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
17.87.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303
17.87.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304
17.87.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304
17.87.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304
17.88 fix msst command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304
17.88.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304
17.88.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305
17.88.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305
17.88.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1306
17.88.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
17.88.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
17.88.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
17.89 fix mvv/dpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
17.90 fix mvv/edpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
17.91 fix mvv/tdpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
17.91.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1307
17.91.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308
17.91.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308
17.91.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1308
17.91.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309
17.91.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309
17.91.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309
17.92 fix neb command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309

xxxix
 17.92.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309
17.92.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1310
17.92.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1310
17.92.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1312
17.92.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
17.92.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
17.92.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
17.93 fix neb/spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
17.93.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312
17.93.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
17.93.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
17.93.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1313
17.93.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
17.93.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
17.93.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
17.94 fix nvt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314
17.95 fix npt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314
17.96 fix nph command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314
17.96.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314
17.96.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315
17.96.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315
17.96.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1321
17.96.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322
17.96.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322
17.96.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322
17.97 fix nvt/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
17.98 fix npt/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
17.99 fix nph/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
17.99.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
17.99.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323
17.99.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324
17.99.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1324
17.99.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324
17.99.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
17.99.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
17.100fix nvt/uef command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
17.101fix npt/uef command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
17.101.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325
17.101.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326
17.101.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326
17.101.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1328
17.101.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328
17.101.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328
17.101.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328
17.102fix nph/asphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329
17.102.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329
17.102.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329
17.102.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329
17.102.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1330
17.102.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330
17.102.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331
17.102.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331
17.103fix nph/body command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331
17.103.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331

xl
 17.103.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331
17.103.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1331
17.103.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1332
17.103.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
17.103.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
17.103.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
17.104fix nph/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
17.104.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
17.104.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333
17.104.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334
17.104.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1335
17.104.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335
17.104.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335
17.104.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335
17.105fix nphug command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335
17.105.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335
17.105.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336
17.105.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336
17.105.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1338
17.105.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1338
17.105.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1338
17.105.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1338
17.106fix npt/asphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339
17.106.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339
17.106.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339
17.106.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339
17.106.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1340
17.106.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
17.106.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
17.106.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
17.107fix npt/body command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
17.107.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
17.107.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
17.107.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341
17.107.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1343
17.107.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
17.107.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
17.107.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
17.108fix npt/cauchy command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
17.108.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343
17.108.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344
17.108.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344
17.108.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1349
17.108.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1350
17.108.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351
17.108.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351
17.109fix npt/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351
17.109.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351
17.109.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351
17.109.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352
17.109.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1353
17.109.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353
17.109.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353
17.109.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353

xli
 17.110fix numdiff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354
17.110.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354
17.110.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354
17.110.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354
17.110.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1355
17.110.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
17.110.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
17.110.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
17.111fix nve command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
17.111.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355
17.111.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356
17.111.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356
17.111.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1356
17.111.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356
17.111.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356
17.111.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356
17.112fix nve/asphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357
17.112.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357
17.112.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357
17.112.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1357
17.112.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1357
17.112.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
17.112.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
17.112.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
17.113fix nve/asphere/noforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
17.113.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
17.113.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
17.113.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1358
17.113.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1359
17.113.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
17.113.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
17.113.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
17.114fix nve/awpmd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
17.114.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
17.114.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359
17.114.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
17.114.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1360
17.114.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
17.114.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
17.114.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
17.115fix nve/body command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
17.115.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1360
17.115.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
17.115.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
17.115.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1361
17.115.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
17.115.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
17.115.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
17.116fix nve/dot command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
17.116.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361
17.116.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
17.116.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
17.116.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
17.116.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362

xlii
 17.116.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
17.117fix nve/dotc/langevin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
17.117.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1362
17.117.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363
17.117.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363
17.117.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1364
17.117.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1364
17.117.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1364
17.118fix nve/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
17.118.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
17.118.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
17.118.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
17.118.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1365
17.118.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
17.118.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
17.118.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
17.119fix nve/limit command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
17.119.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
17.119.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
17.119.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
17.119.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1366
17.119.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
17.119.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
17.119.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
17.120fix nve/line command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
17.120.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
17.120.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
17.120.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
17.120.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1367
17.120.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
17.120.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
17.120.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
17.121fix nve/manifold/rattle command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
17.121.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
17.121.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1368
17.121.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
17.121.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1369
17.121.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
17.121.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
17.121.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
17.122fix nve/noforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
17.122.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
17.122.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
17.122.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
17.122.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1370
17.122.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
17.122.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1370
17.122.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
17.123fix nve/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
17.123.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
17.123.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
17.123.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371
17.123.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1372
17.123.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372

xliii
 17.123.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
17.123.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
17.124fix nve/spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
17.124.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372
17.124.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373
17.124.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373
17.124.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
17.124.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
17.124.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
17.125fix nve/tri command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
17.125.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
17.125.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
17.125.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374
17.125.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1375
17.125.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
17.125.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
17.125.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
17.126fix nvk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
17.126.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
17.126.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
17.126.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375
17.126.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1376
17.126.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376
17.126.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376
17.126.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376
17.127fix nvt/asphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376
17.127.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376
17.127.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
17.127.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1377
17.127.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1378
17.127.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
17.127.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
17.127.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
17.128fix nvt/body command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
17.128.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378
17.128.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379
17.128.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379
17.128.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1380
17.128.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
17.128.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
17.128.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
17.129fix nvt/manifold/rattle command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
17.129.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380
17.129.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381
17.129.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381
17.129.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1381
17.129.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381
17.129.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381
17.130fix nvt/sllod command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
17.130.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
17.130.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
17.130.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382
17.130.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1383
17.130.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384

xliv
 17.130.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
17.130.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
17.131fix nvt/sllod/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
17.131.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
17.131.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
17.131.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384
17.131.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1385
17.131.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
17.131.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
17.131.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
17.132fix nvt/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
17.132.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1385
17.132.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386
17.132.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386
17.132.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1387
17.132.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387
17.132.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387
17.132.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387
17.133fix oneway command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1388
17.133.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1388
17.133.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1388
17.133.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1388
17.133.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1388
17.133.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1388
17.133.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
17.133.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
17.134fix orient/fcc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
17.135fix orient/bcc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
17.135.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
17.135.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
17.135.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389
17.135.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1391
17.135.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391
17.135.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391
17.135.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391
17.136fix orient/eco command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
17.136.1Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
17.136.2Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392
17.136.3Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1393
17.136.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394
17.136.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394
17.136.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394
17.137fix pafi command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394
17.137.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394
17.137.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395
17.137.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395
17.137.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1396
17.137.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
17.137.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
17.138fix pair/tracker command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
17.138.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1396
17.138.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
17.138.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
17.138.4Restart, fix_modify, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . . . . . 1397

xlv
 17.138.5Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397
17.138.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
17.138.7Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
17.138.8Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
17.139fix phonon command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
17.139.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398
17.139.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399
17.139.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399
17.139.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1400
17.139.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400
17.139.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400
17.139.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400
17.140fix pimd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
17.140.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
17.140.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
17.140.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401
17.140.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
17.140.5Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
17.141fix planeforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
17.141.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
17.141.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404
17.141.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
17.141.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1405
17.141.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
17.141.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
17.141.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
17.142fix plumed command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
17.142.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1405
17.142.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1406
17.142.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1406
17.142.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1406
17.142.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
17.142.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
17.142.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
17.143fix poems command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
17.143.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
17.143.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407
17.143.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1408
17.143.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1409
17.143.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
17.143.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
17.143.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
17.144fix polarize/bem/gmres command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
17.145fix polarize/bem/icc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
17.146fix polarize/functional command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
17.146.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409
17.146.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410
17.146.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410
17.146.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1410
17.146.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
17.146.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
17.146.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
17.147fix pour command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411
17.147.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411

xlvi
 17.147.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412
17.147.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412
17.147.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1414
17.147.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1414
17.147.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
17.147.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
17.148fix precession/spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
17.148.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
17.148.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415
17.148.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416
17.148.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1417
17.148.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418
17.148.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418
17.148.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418
17.149fix press/berendsen command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418
17.149.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418
17.149.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419
17.149.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419
17.149.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1421
17.149.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
17.149.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
17.149.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
17.150fix print command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
17.150.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421
17.150.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1422
17.150.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1422
17.150.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1422
17.150.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
17.150.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
17.150.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
17.151fix propel/self command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
17.151.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
17.151.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
17.151.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1423
17.151.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1424
17.151.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
17.151.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
17.151.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
17.152fix property/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
17.152.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425
17.152.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426
17.152.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426
17.152.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1429
17.152.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
17.152.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
17.152.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
17.153fix python/invoke command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
17.153.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429
17.153.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430
17.153.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430
17.153.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430
17.153.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431
17.154fix python/move command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431
17.154.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431

xlvii
 17.154.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431
17.154.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1431
17.154.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1432
17.154.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
17.154.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
17.154.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
17.155fix qbmsst command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
17.155.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432
17.155.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433
17.155.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1434
17.155.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1435
17.155.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.155.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.155.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.156fix qeq/point command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.157fix qeq/shielded command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.158fix qeq/slater command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.159fix qeq/dynamic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.160fix qeq/fire command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.160.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436
17.160.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1437
17.160.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1437
17.160.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1439
17.160.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1439
17.160.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1439
17.160.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
17.161fix qeq/comb command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
17.161.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
17.161.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
17.161.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440
17.161.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1441
17.161.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441
17.161.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441
17.161.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
17.162fix qeq/reaxff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
17.162.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
17.162.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442
17.162.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443
17.162.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1443
17.162.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
17.162.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
17.162.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
17.163fix qmmm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
17.163.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
17.163.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
17.163.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444
17.163.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1445
17.163.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445
17.163.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445
17.163.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445
17.164fix qtb command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445
17.164.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445
17.164.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446
17.164.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446

xlviii
 17.164.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1447
17.164.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447
17.164.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447
17.164.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447
17.165fix reaxff/bonds command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448
17.165.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448
17.165.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448
17.165.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448
17.165.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1449
17.165.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449
17.165.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449
17.165.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449
17.166fix reaxff/species command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449
17.166.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449
17.166.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1450
17.166.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1450
17.166.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1451
17.166.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1451
17.166.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
17.166.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
17.167fix recenter command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
17.167.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
17.167.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
17.167.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452
17.167.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1453
17.167.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453
17.167.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453
17.167.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
17.168fix restrain command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
17.168.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
17.168.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454
17.168.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455
17.168.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1457
17.168.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1457
17.168.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1457
17.168.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1457
17.169fix rhok command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458
17.169.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458
17.169.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458
17.169.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458
17.169.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1458
17.169.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.169.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.169.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.170fix rigid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.171fix rigid/nve command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.172fix rigid/nvt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.173fix rigid/npt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.174fix rigid/nph command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459
17.175fix rigid/small command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
17.176fix rigid/nve/small command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
17.177fix rigid/nvt/small command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
17.178fix rigid/npt/small command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
17.179fix rigid/nph/small command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460

xlix
 17.179.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460
17.179.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461
17.179.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462
17.179.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1469
17.179.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1470
17.179.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1470
17.179.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1470
17.180fix rigid/meso command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471
17.180.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471
17.180.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471
17.180.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471
17.180.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1474
17.180.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1475
17.180.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1475
17.180.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1475
17.181fix rx command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1475
17.181.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1475
17.181.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1476
17.181.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1476
17.181.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478
17.181.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478
17.181.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478
17.182fix saed/vtk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478
17.182.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478
17.182.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479
17.182.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479
17.182.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1481
17.182.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481
17.182.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481
17.182.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481
17.183fix setforce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481
17.184fix setforce/spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481
17.184.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1481
17.184.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1482
17.184.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1482
17.184.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1483
17.184.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1483
17.184.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1483
17.184.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1483
17.185fix shake command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1483
17.186fix rattle command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1483
17.186.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1483
17.186.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484
17.186.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484
17.186.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1486
17.186.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486
17.186.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486
17.186.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486
17.187fix shardlow command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1487
17.187.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1487
17.187.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1487
17.187.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1487
17.187.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1488
17.187.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1488

l
 17.187.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1488
17.188fix smd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1488
17.188.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1488
17.188.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1489
17.188.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1489
17.188.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1490
17.188.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1490
17.188.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1490
17.188.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1490
17.189fix smd/adjust_dt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491
17.189.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491
17.189.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491
17.189.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491
17.189.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1491
17.189.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491
17.189.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491
17.189.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492
17.190fix smd/integrate_tlsph command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492
17.190.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492
17.190.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492
17.190.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492
17.190.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1492
17.190.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492
17.190.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493
17.190.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493
17.191fix smd/integrate_ulsph command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493
17.191.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493
17.191.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493
17.191.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493
17.191.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1494
17.191.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494
17.191.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494
17.191.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494
17.192fix smd/move_tri_surf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494
17.192.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494
17.192.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495
17.192.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495
17.192.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1495
17.192.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495
17.192.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495
17.192.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1495
17.193fix smd/setvel command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496
17.193.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496
17.193.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496
17.193.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496
17.193.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1497
17.193.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
17.193.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
17.193.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
17.194fix smd/wall_surface command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
17.194.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
17.194.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497
17.194.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
17.194.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1498

li
 17.194.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
17.194.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
17.194.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
17.195fix sph command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
17.195.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1498
17.195.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
17.195.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
17.195.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1499
17.195.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
17.195.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
17.195.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
17.196fix sph/stationary command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
17.196.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499
17.196.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500
17.196.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500
17.196.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1500
17.196.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500
17.196.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500
17.196.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500
17.197fix spring command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500
17.197.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500
17.197.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1501
17.197.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1501
17.197.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1502
17.197.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1502
17.197.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1502
17.197.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1502
17.198fix spring/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1502
17.198.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1502
17.198.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1503
17.198.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1503
17.198.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1503
17.198.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504
17.198.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504
17.198.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504
17.199fix spring/rg command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504
17.199.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504
17.199.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504
17.199.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504
17.199.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1505
17.199.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505
17.199.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505
17.199.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505
17.200fix spring/self command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505
17.200.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505
17.200.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1506
17.200.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1506
17.200.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1506
17.200.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1506
17.200.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1507
17.200.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1507
17.201fix srd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1507
17.201.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1507
17.201.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1508

lii
 17.201.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1508
17.201.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1511
17.201.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
17.201.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
17.201.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
17.202fix store/force command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
17.202.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
17.202.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
17.202.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512
17.202.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1513
17.202.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1513
17.202.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1513
17.202.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1513
17.203fix store/state command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1513
17.203.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1513
17.203.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514
17.203.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514
17.203.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1515
17.203.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515
17.203.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515
17.203.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515
17.204fix temp/berendsen command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515
17.204.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1515
17.204.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1516
17.204.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1516
17.204.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1517
17.204.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517
17.204.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1517
17.204.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518
17.205fix temp/csvr command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518
17.206fix temp/csld command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518
17.206.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518
17.206.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518
17.206.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518
17.206.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1520
17.206.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1520
17.206.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1520
17.206.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1520
17.207fix temp/rescale command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521
17.207.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521
17.207.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521
17.207.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1521
17.207.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1522
17.207.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523
17.207.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523
17.207.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523
17.208fix temp/rescale/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523
17.208.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523
17.208.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523
17.208.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523
17.208.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1524
17.208.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524
17.208.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524
17.208.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524

liii
 17.209fix tfmc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524
17.209.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1524
17.209.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1525
17.209.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1525
17.209.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1526
17.209.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526
17.209.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526
17.209.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526
17.210fix tgnvt/drude command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526
17.211fix tgnpt/drude command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526
17.211.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526
17.211.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1527
17.211.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1528
17.211.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1529
17.211.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1530
17.211.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1530
17.211.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1530
17.212fix thermal/conductivity command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1531
17.212.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1531
17.212.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1531
17.212.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1531
17.212.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1532
17.212.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1532
17.212.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533
17.212.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533
17.213fix ti/spring command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533
17.213.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533
17.213.2Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533
17.213.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533
17.213.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1534
17.213.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535
17.213.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535
17.213.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535
17.214fix tmd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535
17.214.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535
17.214.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536
17.214.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536
17.214.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1537
17.214.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
17.214.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
17.214.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
17.215fix ttm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
17.216fix ttm/grid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
17.217fix ttm/mod command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
17.217.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537
17.217.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1538
17.217.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1538
17.217.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1542
17.217.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1542
17.217.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1542
17.217.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1542
17.218fix tune/kspace command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1543
17.218.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1543
17.218.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1543

liv
 17.218.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1543
17.218.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
17.218.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
17.218.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
17.219fix vector command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
17.219.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
17.219.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1544
17.219.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1545
17.219.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1546
17.219.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1546
17.219.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1546
17.219.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1546
17.220fix viscosity command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1546
17.220.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1546
17.220.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1547
17.220.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1547
17.220.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1548
17.220.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1548
17.220.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1548
17.220.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1548
17.221fix viscous command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1549
17.221.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1549
17.221.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1549
17.221.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1549
17.221.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1550
17.221.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1550
17.221.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1550
17.221.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1550
17.222fix wall/lj93 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1550
17.223fix wall/lj126 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1551
17.224fix wall/lj1043 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1551
17.225fix wall/colloid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1551
17.226fix wall/harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1551
17.227fix wall/morse command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1551
17.227.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1551
17.227.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1552
17.227.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1552
17.227.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1555
17.227.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1555
17.227.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556
17.227.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556
17.228fix wall/body/polygon command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556
17.228.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556
17.228.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556
17.228.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1557
17.228.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1557
17.228.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1557
17.228.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1557
17.228.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1558
17.229fix wall/body/polyhedron command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1558
17.229.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1558
17.229.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1558
17.229.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1558
17.229.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1559

lv
 17.229.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559
17.229.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559
17.229.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559
17.230fix wall/ees command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559
17.231fix wall/region/ees command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559
17.231.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1559
17.231.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1560
17.231.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1560
17.231.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1561
17.231.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562
17.231.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562
17.231.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562
17.232fix wall/gran command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562
17.232.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1562
17.232.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1563
17.232.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1564
17.232.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1565
17.232.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565
17.232.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565
17.232.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1565
17.233fix wall/gran/region command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566
17.233.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566
17.233.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566
17.233.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1567
17.233.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1569
17.233.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1569
17.233.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1569
17.233.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1570
17.234fix wall/piston command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1570
17.234.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1570
17.234.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1570
17.234.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1570
17.234.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1571
17.234.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1571
17.234.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1571
17.234.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1571
17.235fix wall/reflect command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1572
17.235.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1572
17.235.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1572
17.235.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1572
17.235.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1574
17.235.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1574
17.235.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1574
17.235.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1574
17.236fix wall/reflect/stochastic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1574
17.236.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1574
17.236.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575
17.236.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1575
17.236.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576
17.236.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576
17.236.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576
17.237fix wall/region command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576
17.237.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576
17.237.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577

lvi
 17.237.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1577
17.237.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1578
17.237.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579
17.237.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579
17.237.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579
17.238fix wall/srd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579
17.238.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1579
17.238.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1580
17.238.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1580
17.238.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1582
17.238.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1582
17.238.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1582
17.238.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1582
17.239fix widom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1582
17.239.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1582
17.239.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1583
17.239.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1583
17.239.4Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 1584
17.239.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585
17.239.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585
17.239.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1585

18 Computes 1587
18.1 compute ackland/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1587
18.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1587
18.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1587
18.1.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1587
18.1.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1588
18.1.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1588
18.1.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1588
18.1.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1588
18.2 compute adf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1588
18.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1588
18.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1589
18.2.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1589
18.2.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
18.2.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
18.2.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
18.2.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
18.3 compute angle command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
18.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1591
18.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.3.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.3.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.3.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.3.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.3.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.4 compute angle/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1592
18.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1593
18.4.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1593
18.4.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1594
18.4.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1594
18.4.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1594

lvii
 18.4.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1594
18.5 compute angmom/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595
18.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595
18.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595
18.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1595
18.5.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.5.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.5.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.5.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.6 compute basal/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1596
18.6.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1597
18.6.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1597
18.6.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1597
18.6.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1597
18.7 compute body/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1597
18.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1597
18.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1598
18.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1598
18.7.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1598
18.7.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.7.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.7.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.8 compute bond command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.8.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1599
18.8.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1600
18.8.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1600
18.8.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1600
18.9 compute bond/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1600
18.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1600
18.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1601
18.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1601
18.9.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1602
18.9.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603
18.9.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603
18.9.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603
18.10 compute centro/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603
18.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603
18.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603
18.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603
18.10.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1604
18.10.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605
18.10.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605
18.10.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605
18.11 compute chunk/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605
18.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1605
18.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1607
18.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1607
18.11.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613

lviii
 18.11.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613
18.11.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613
18.11.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613
18.12 compute chunk/spread/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614
18.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614
18.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614
18.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1614
18.12.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616
18.12.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1616
18.12.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.12.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.13 compute cluster/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.14 compute fragment/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.15 compute aggregate/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.15.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.15.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.15.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1617
18.15.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1618
18.15.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1618
18.15.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1618
18.15.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619
18.16 compute cna/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619
18.16.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619
18.16.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619
18.16.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1619
18.16.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620
18.16.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620
18.16.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620
18.16.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620
18.17 compute cnp/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620
18.17.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1620
18.17.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1621
18.17.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1621
18.17.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
18.17.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
18.17.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
18.17.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
18.18 compute com command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
18.18.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1622
18.18.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.18.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.18.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.18.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.18.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.18.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.19 compute com/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.19.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1623
18.19.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
18.19.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
18.19.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1624
18.19.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
18.19.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
18.19.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
18.20 compute contact/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625

lix
 18.20.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
18.20.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
18.20.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
18.20.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1625
18.20.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
18.20.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
18.20.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
18.21 compute coord/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
18.21.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
18.21.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1626
18.21.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1627
18.21.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1628
18.21.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1628
18.21.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1628
18.21.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1628
18.22 compute damage/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1628
18.22.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1628
18.22.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.22.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.22.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.22.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.22.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.22.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.23 compute dihedral command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.23.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1629
18.23.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.23.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.23.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.23.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.23.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.23.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.24 compute dihedral/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.24.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1630
18.24.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631
18.24.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1631
18.24.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632
18.24.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632
18.24.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632
18.24.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632
18.25 compute dilatation/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632
18.25.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1632
18.25.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.25.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.25.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.25.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.25.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.25.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.26 compute dipole command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.26.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1633
18.26.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
18.26.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
18.26.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
18.26.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
18.26.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634

lx
 18.26.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1634
18.27 compute dipole/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635
18.27.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635
18.27.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635
18.27.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1635
18.27.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
18.27.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
18.27.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
18.27.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
18.28 compute displace/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
18.28.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
18.28.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1636
18.28.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1637
18.28.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
18.28.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
18.28.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
18.28.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
18.29 compute dpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
18.29.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1638
18.29.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639
18.29.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639
18.29.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639
18.29.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1639
18.29.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
18.29.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
18.30 compute dpd/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
18.30.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
18.30.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
18.30.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
18.30.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1640
18.30.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
18.30.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
18.30.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
18.31 compute edpd/temp/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
18.31.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
18.31.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
18.31.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1641
18.31.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
18.31.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
18.31.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
18.31.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
18.32 compute efield/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
18.32.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
18.32.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1642
18.32.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
18.32.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
18.32.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
18.32.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
18.32.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
18.33 compute entropy/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
18.33.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1643
18.33.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1644
18.33.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1644
18.33.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645

lxi
 18.33.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645
18.33.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645
18.33.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645
18.34 compute erotate/asphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645
18.34.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1645
18.34.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646
18.34.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646
18.34.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646
18.34.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646
18.34.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1646
18.34.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647
18.35 compute erotate/rigid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647
18.35.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647
18.35.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647
18.35.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647
18.35.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1647
18.35.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648
18.35.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648
18.35.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648
18.36 compute erotate/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648
18.36.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648
18.36.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648
18.36.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1648
18.36.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.36.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.36.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.36.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.37 compute erotate/sphere/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.37.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.37.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.37.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1649
18.37.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.37.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.37.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.37.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.38 compute event/displace command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.38.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.38.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.38.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1650
18.38.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651
18.38.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651
18.38.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651
18.38.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651
18.39 compute fabric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651
18.39.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1651
18.39.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1652
18.39.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1652
18.39.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1653
18.39.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1653
18.39.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1653
18.39.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1653
18.40 compute fep command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654
18.40.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654
18.40.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654

lxii
 18.40.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1654
18.40.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657
18.40.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657
18.40.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657
18.40.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1657
18.41 compute global/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658
18.41.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658
18.41.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658
18.41.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1658
18.41.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1660
18.41.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1660
18.41.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661
18.41.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661
18.42 compute group/group command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661
18.42.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661
18.42.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661
18.42.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1661
18.42.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
18.42.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
18.42.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
18.42.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
18.43 compute gyration command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
18.43.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
18.43.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1663
18.43.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664
18.43.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664
18.43.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664
18.43.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664
18.43.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1664
18.44 compute gyration/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665
18.44.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665
18.44.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665
18.44.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1665
18.44.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666
18.44.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666
18.44.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666
18.44.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666
18.45 compute gyration/shape command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666
18.45.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666
18.45.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1667
18.45.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1667
18.45.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1667
18.45.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
18.45.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
18.45.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
18.46 compute gyration/shape/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
18.46.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
18.46.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
18.46.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1668
18.46.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669
18.46.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669
18.46.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669
18.46.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1669
18.47 compute heat/flux command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1670

lxiii
 18.47.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1670
18.47.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1670
18.47.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1670
18.47.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1671
18.47.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672
18.47.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672
18.47.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1672
18.48 compute hexorder/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673
18.48.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1673
18.48.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1674
18.48.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1674
18.48.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675
18.48.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675
18.48.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675
18.48.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675
18.49 compute hma command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675
18.49.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1675
18.49.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676
18.49.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1676
18.49.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678
18.49.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678
18.49.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678
18.49.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678
18.50 compute improper command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678
18.50.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678
18.50.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1678
18.50.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679
18.50.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679
18.50.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679
18.50.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679
18.50.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679
18.51 compute improper/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679
18.51.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1679
18.51.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680
18.51.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680
18.51.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680
18.51.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680
18.51.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1680
18.51.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1681
18.52 compute inertia/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1681
18.52.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1681
18.52.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1681
18.52.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1681
18.52.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.52.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.52.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.52.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.53 compute ke command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.53.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.53.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.53.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1682
18.53.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683
18.53.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683
18.53.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683

lxiv
 18.53.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683
18.54 compute ke/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683
18.54.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683
18.54.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683
18.54.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1683
18.54.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.54.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.54.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.54.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.55 compute ke/atom/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.55.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.55.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.55.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1684
18.55.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685
18.55.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685
18.55.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685
18.55.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685
18.56 compute ke/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685
18.56.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1685
18.56.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686
18.56.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686
18.56.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686
18.56.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1686
18.56.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687
18.56.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687
18.57 compute ke/rigid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687
18.57.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687
18.57.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687
18.57.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687
18.57.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1687
18.57.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.57.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.57.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.58 compute mesont command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.58.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.58.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.58.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.58.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1688
18.58.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689
18.58.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689
18.58.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689
18.59 compute mliap command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689
18.59.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689
18.59.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689
18.59.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1689
18.59.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691
18.59.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691
18.59.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691
18.59.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691
18.60 compute momentum command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691
18.60.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1691
18.60.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
18.60.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
18.60.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692

lxv
 18.60.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
18.60.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
18.60.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
18.61 compute msd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
18.61.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1692
18.61.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1693
18.61.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1693
18.61.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.61.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.61.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.61.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.62 compute msd/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.62.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.62.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.62.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1694
18.62.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1695
18.62.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696
18.62.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696
18.62.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696
18.63 compute msd/nongauss command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696
18.63.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696
18.63.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696
18.63.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1696
18.63.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697
18.63.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697
18.63.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697
18.63.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697
18.64 compute omega/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697
18.64.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697
18.64.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697
18.64.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698
18.64.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698
18.64.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1698
18.64.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699
18.64.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699
18.65 compute orientorder/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699
18.65.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699
18.65.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699
18.65.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1699
18.65.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1701
18.65.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1701
18.65.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1701
18.65.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1701
18.66 compute pair command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1702
18.66.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1702
18.66.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1702
18.66.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1702
18.66.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703
18.66.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703
18.66.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703
18.66.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703
18.67 compute pair/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703
18.67.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1703
18.67.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1704

lxvi
 18.67.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1704
18.67.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705
18.67.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705
18.67.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705
18.67.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705
18.68 compute pe command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705
18.68.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1705
18.68.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1706
18.68.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1706
18.68.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1706
18.68.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707
18.68.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707
18.68.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707
18.69 compute pe/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707
18.69.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707
18.69.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707
18.69.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707
18.69.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708
18.69.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708
18.69.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708
18.69.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1708
18.70 compute plasticity/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709
18.70.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709
18.70.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709
18.70.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709
18.70.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709
18.70.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709
18.70.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1709
18.70.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710
18.71 compute pressure command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710
18.71.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710
18.71.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710
18.71.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1710
18.71.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
18.71.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
18.71.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
18.71.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
18.72 compute pressure/cylinder command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
18.72.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1712
18.72.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713
18.72.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713
18.72.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713
18.72.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713
18.72.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713
18.72.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1713
18.73 compute pressure/uef command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
18.73.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
18.73.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
18.73.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
18.73.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
18.73.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1714
18.73.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715
18.74 compute property/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715
18.74.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1715

lxvii
 18.74.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1716
18.74.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1716
18.74.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1717
18.74.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1717
18.74.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718
18.74.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718
18.75 compute property/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718
18.75.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718
18.75.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718
18.75.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1718
18.75.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1719
18.75.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1719
18.75.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1719
18.75.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1719
18.76 compute property/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720
18.76.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1720
18.76.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721
18.76.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1721
18.76.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
18.76.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
18.76.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
18.76.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
18.77 compute ptm/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
18.77.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
18.77.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1722
18.77.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1723
18.77.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
18.77.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
18.77.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
18.77.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
18.78 compute rdf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
18.78.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1724
18.78.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725
18.78.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1725
18.78.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1726
18.78.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
18.78.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
18.78.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
18.79 compute reduce command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
18.80 compute reduce/region command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
18.80.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1727
18.80.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1728
18.80.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1728
18.80.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730
18.80.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730
18.80.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730
18.80.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730
18.81 compute reduce/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730
18.81.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1730
18.81.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1731
18.81.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1731
18.81.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1732
18.81.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733
18.81.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733

lxviii
 18.81.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733
18.82 compute rigid/local command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733
18.82.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1733
18.82.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1734
18.82.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1734
18.82.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1735
18.82.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1735
18.82.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1736
18.82.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1736
18.83 compute saed command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1736
18.83.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1736
18.83.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1736
18.83.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737
18.83.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739
18.83.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739
18.83.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739
18.83.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739
18.84 compute slice command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739
18.84.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1739
18.84.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740
18.84.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1740
18.84.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
18.84.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
18.84.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
18.84.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
18.85 compute smd/contact/radius command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
18.85.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
18.85.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1741
18.85.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
18.85.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
18.85.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
18.85.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
18.85.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
18.86 compute smd/damage command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
18.86.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1742
18.86.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
18.86.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
18.86.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
18.86.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
18.86.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
18.87 compute smd/hourglass/error command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
18.87.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1743
18.87.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744
18.87.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744
18.87.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744
18.87.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744
18.87.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744
18.88 compute smd/internal/energy command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744
18.88.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1744
18.88.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
18.88.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
18.88.4 Output Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
18.88.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
18.88.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745

lxix
 18.88.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
18.89 compute smd/plastic/strain command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
18.89.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1745
18.89.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
18.89.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
18.89.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
18.89.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
18.89.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
18.90 compute smd/plastic/strain/rate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
18.90.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1746
18.90.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
18.90.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
18.90.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
18.90.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
18.90.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
18.91 compute smd/rho command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
18.91.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1747
18.91.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.91.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.91.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.91.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.91.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.91.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.92 compute smd/tlsph/defgrad command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.92.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1748
18.92.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.92.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.92.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.92.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.92.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.92.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.93 compute smd/tlsph/dt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.93.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1749
18.93.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.93.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.93.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.93.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.93.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.93.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.94 compute smd/tlsph/num/neighs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.94.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1750
18.94.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.94.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.94.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.94.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.94.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.94.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.95 compute smd/tlsph/shape command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.95.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1751
18.95.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
18.95.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
18.95.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
18.95.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
18.95.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752

lxx
 18.95.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
18.96 compute smd/tlsph/strain command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
18.96.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1752
18.96.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.96.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.96.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.96.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.96.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.96.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.97 compute smd/tlsph/strain/rate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.97.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1753
18.97.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.97.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.97.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.97.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.97.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.97.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.98 compute smd/tlsph/stress command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.98.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1754
18.98.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.98.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.98.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.98.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.98.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.98.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.99 compute smd/triangle/vertices command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.99.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1755
18.99.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.99.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.99.4 Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.99.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.99.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.99.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.100compute smd/ulsph/effm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.100.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1756
18.100.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.100.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.100.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.100.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.100.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.100.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.101compute smd/ulsph/num/neighs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.101.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1757
18.101.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.101.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.101.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.101.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.101.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.101.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.102compute smd/ulsph/strain command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.102.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1758
18.102.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759
18.102.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759
18.102.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759

lxxi
 18.102.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759
18.102.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759
18.102.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759
18.103compute smd/ulsph/strain/rate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759
18.103.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1759
18.103.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.103.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.103.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.103.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.103.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.103.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.104compute smd/ulsph/stress command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.104.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1760
18.104.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.104.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.104.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.104.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.104.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.104.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.105compute smd/vol command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.105.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1761
18.105.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.105.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.105.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.105.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.105.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.105.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.106compute sna/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.107compute snad/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.108compute snav/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.109compute snap command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.109.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1762
18.109.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1763
18.109.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1764
18.109.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1766
18.109.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1768
18.109.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1768
18.109.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1768
18.110compute sph/e/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1768
18.110.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1768
18.110.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1768
18.110.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
18.110.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
18.110.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
18.110.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
18.110.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
18.111compute sph/rho/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
18.111.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1769
18.111.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
18.111.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
18.111.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
18.111.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
18.111.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
18.111.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770

lxxii
18.112compute sph/t/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
18.112.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1770
18.112.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.112.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.112.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.112.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.112.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.112.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.113compute spin command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.113.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1771
18.113.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772
18.113.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772
18.113.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772
18.113.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1772
18.113.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773
18.114compute stress/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773
18.115compute centroid/stress/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773
18.115.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773
18.115.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773
18.115.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1773
18.115.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1775
18.115.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776
18.115.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776
18.115.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776
18.116compute stress/mop command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776
18.117compute stress/mop/profile command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776
18.117.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1776
18.117.2Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1777
18.117.3Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1777
18.117.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.117.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.117.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.118compute force/tally command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.119compute heat/flux/tally command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.120compute heat/flux/virial/tally command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.121compute pe/tally command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.122compute pe/mol/tally command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.123compute stress/tally command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.123.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1778
18.123.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1779
18.123.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1779
18.123.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1780
18.123.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
18.123.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
18.123.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
18.124compute tdpd/cc/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
18.124.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
18.124.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
18.124.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1781
18.124.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
18.124.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
18.124.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
18.124.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
18.125compute temp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782

lxxiii
 18.125.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
18.125.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1782
18.125.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1783
18.125.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1783
18.125.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
18.125.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
18.125.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
18.126compute temp/asphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
18.126.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
18.126.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
18.126.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1784
18.126.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
18.126.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
18.126.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
18.126.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
18.127compute temp/body command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
18.127.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786
18.127.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787
18.127.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1787
18.127.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1788
18.127.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1788
18.127.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1788
18.127.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1788
18.128compute temp/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1788
18.128.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1788
18.128.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1789
18.128.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1789
18.128.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
18.128.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
18.128.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
18.128.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
18.129compute temp/com command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
18.129.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
18.129.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1791
18.129.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1792
18.129.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1792
18.129.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1792
18.129.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1792
18.129.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793
18.130compute temp/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793
18.130.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793
18.130.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793
18.130.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1793
18.130.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794
18.130.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794
18.130.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794
18.130.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794
18.131compute temp/deform command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1794
18.131.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795
18.131.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795
18.131.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1795
18.131.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796
18.131.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796
18.131.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796

lxxiv
 18.131.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796
18.132compute temp/deform/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796
18.132.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1796
18.132.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
18.132.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
18.132.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
18.132.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
18.132.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
18.132.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1797
18.133compute temp/drude command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798
18.133.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798
18.133.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798
18.133.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798
18.133.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1798
18.133.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
18.133.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
18.133.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
18.134compute temp/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
18.134.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
18.134.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
18.134.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1799
18.134.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800
18.134.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800
18.134.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800
18.134.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800
18.135compute temp/partial command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800
18.135.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1800
18.135.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1801
18.135.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1801
18.135.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1802
18.135.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1802
18.135.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1802
18.135.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1802
18.136compute temp/profile command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1802
18.136.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1802
18.136.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1803
18.136.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1803
18.136.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1804
18.136.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1804
18.136.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1804
18.136.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1804
18.137compute temp/ramp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1805
18.137.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1805
18.137.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1805
18.137.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1805
18.137.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806
18.137.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806
18.137.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806
18.137.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806
18.138compute temp/region command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806
18.138.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1806
18.138.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1807
18.138.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1807
18.138.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1807

lxxv
 18.138.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.138.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.138.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.139compute temp/region/eff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.139.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.139.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.139.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.139.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1808
18.139.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
18.139.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
18.139.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
18.140compute temp/rotate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
18.140.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
18.140.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
18.140.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1809
18.140.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810
18.140.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810
18.140.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810
18.140.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810
18.141compute temp/sphere command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810
18.141.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1810
18.141.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1811
18.141.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1811
18.141.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
18.141.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
18.141.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
18.141.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
18.142compute temp/uef command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
18.142.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
18.142.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1812
18.142.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
18.142.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
18.142.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
18.142.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
18.143compute ti command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
18.143.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1813
18.143.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1814
18.143.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1814
18.143.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
18.143.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
18.143.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
18.143.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
18.144compute torque/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
18.144.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
18.144.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1815
18.144.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816
18.144.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816
18.144.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1816
18.144.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817
18.144.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817
18.145compute vacf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817
18.145.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817
18.145.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817
18.145.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1817

lxxvi
 18.145.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.145.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.145.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.145.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.146compute vcm/chunk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.146.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.146.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.146.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1818
18.146.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
18.146.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
18.146.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
18.146.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
18.147compute viscosity/cos command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
18.147.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1819
18.147.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1820
18.147.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1820
18.147.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821
18.147.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821
18.147.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821
18.147.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821
18.148compute voronoi/atom command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821
18.148.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1821
18.148.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822
18.148.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1822
18.148.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824
18.148.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824
18.148.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1824
18.148.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825
18.149compute xrd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825
18.149.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825
18.149.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1825
18.149.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1826
18.149.4Output info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828
18.149.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828
18.149.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828
18.149.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1828

19 Pair Styles 1829

19.1 pair_style adp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829
19.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829
19.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829
19.1.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1829
19.1.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1831
19.1.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1831
19.1.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1831
19.1.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1831
19.2 pair_style agni command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1832
19.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1832
19.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1832
19.2.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1832
19.2.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1833
19.2.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1833
19.2.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1833
19.2.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1833

lxxvii
 19.3 pair_style airebo command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834
19.4 pair_style airebo/morse command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834
19.5 pair_style rebo command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834
19.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834
19.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834
19.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1834
19.5.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1836
19.5.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
19.5.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
19.5.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
19.6 pair_style atm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
19.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
19.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1837
19.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1838
19.6.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1839
19.6.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1839
19.6.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1840
19.6.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1840
19.7 pair_style awpmd/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1840
19.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1840
19.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1840
19.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1841
19.7.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1841
19.7.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
19.7.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
19.7.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
19.8 pair_style beck command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
19.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
19.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
19.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1842
19.8.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1843
19.8.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1843
19.8.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1843
19.8.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1843
19.9 pair_style body/nparticle command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1844
19.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1844
19.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1844
19.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1844
19.9.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1845
19.9.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
19.9.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
19.9.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
19.10 pair_style body/rounded/polygon command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
19.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1845
19.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846
19.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1846
19.10.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1848
19.10.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
19.10.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
19.10.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
19.11 pair_style body/rounded/polyhedron command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
19.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1848
19.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1849
19.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1849

lxxviii
 19.11.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1851
19.11.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851
19.11.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851
19.11.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851
19.12 pair_style bop command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851
19.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851
19.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1851
19.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1852
19.12.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1856
19.12.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856
19.12.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856
19.12.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
19.13 pair_style born command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
19.14 pair_style born/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
19.15 pair_style born/coul/msm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
19.16 pair_style born/coul/wolf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
19.17 pair_style born/coul/dsf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
19.17.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1857
19.17.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1858
19.17.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1859
19.17.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1860
19.17.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1860
19.17.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1860
19.17.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1860
19.18 pair_style brownian command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1860
19.19 pair_style brownian/poly command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1860
19.19.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861
19.19.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861
19.19.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1861
19.19.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1862
19.19.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1862
19.19.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1862
19.19.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1862
19.20 pair_style buck command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1863
19.21 pair_style buck/coul/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1863
19.22 pair_style buck/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1863
19.23 pair_style buck/coul/msm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1863
19.23.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1863
19.23.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1863
19.23.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1864
19.23.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1865
19.23.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1865
19.23.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1865
19.23.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866
19.24 pair_style buck6d/coul/gauss/dsf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866
19.25 pair_style buck6d/coul/gauss/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866
19.25.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866
19.25.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866
19.25.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1866
19.25.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1867
19.25.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868
19.25.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868
19.25.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868
19.26 pair_style buck/long/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868

lxxix
 19.26.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868
19.26.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1868
19.26.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1869
19.26.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1870
19.26.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870
19.26.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870
19.26.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870
19.27 pair_style lj/charmm/coul/charmm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1870
19.28 pair_style lj/charmm/coul/charmm/implicit command . . . . . . . . . . . . . . . . . . . . . . . . . 1871
19.29 pair_style lj/charmm/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871
19.30 pair_style lj/charmm/coul/msm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871
19.31 pair_style lj/charmmfsw/coul/charmmfsh command . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871
19.32 pair_style lj/charmmfsw/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871
19.32.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1871
19.32.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872
19.32.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1872
19.32.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1874
19.32.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
19.32.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
19.32.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
19.33 pair_style lj/class2 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
19.34 pair_style lj/class2/coul/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
19.35 pair_style lj/class2/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
19.35.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1875
19.35.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876
19.35.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1876
19.35.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1877
19.35.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1877
19.35.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
19.35.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
19.36 pair_style colloid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
19.36.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
19.36.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
19.36.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1878
19.36.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1880
19.36.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
19.36.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
19.36.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
19.37 pair_style comb command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
19.38 pair_style comb3 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
19.38.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1881
19.38.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1882
19.38.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1882
19.38.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1883
19.38.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
19.38.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
19.38.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
19.39 pair_style cosine/squared command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
19.39.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1884
19.39.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885
19.39.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1885
19.39.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1886
19.39.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886
19.39.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886

lxxx
 19.39.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886
19.40 pair_style coul/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886
19.41 pair_style coul/debye command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1886
19.42 pair_style coul/dsf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.43 pair_style coul/exclude command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.44 pair_style coul/cut/global command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.45 pair_style coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.46 pair_style coul/msm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.47 pair_style coul/streitz command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.48 pair_style coul/wolf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.49 pair_style tip4p/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.50 pair_style tip4p/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1887
19.50.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888
19.50.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888
19.50.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1889
19.50.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1891
19.50.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1891
19.50.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892
19.50.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892
19.51 pair_style coul/diel command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892
19.51.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892
19.51.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892
19.51.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1892
19.51.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1893
19.51.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1893
19.51.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1893
19.51.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1893
19.52 pair_style coul/shield command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894
19.52.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894
19.52.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894
19.52.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1894
19.52.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1895
19.52.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
19.52.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
19.52.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
19.53 pair_style coul/slater command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
19.54 pair_style coul/slater/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
19.55 pair_style coul/slater/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
19.55.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1895
19.55.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896
19.55.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1896
19.55.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1896
19.55.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897
19.55.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897
19.55.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897
19.56 pair_style coul/tt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897
19.56.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897
19.56.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1897
19.56.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1898
19.56.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1898
19.56.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1898
19.56.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.56.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.57 pair_style born/coul/dsf/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899

lxxxi
 19.58 pair_style born/coul/long/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.59 pair_style born/coul/wolf/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.60 pair_style buck/coul/long/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.61 pair_style coul/long/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.62 pair_style coul/wolf/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.63 pair_style lj/cut/coul/long/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.64 pair_style lj/class2/coul/long/cs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.64.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1899
19.64.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1900
19.64.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1901
19.64.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1902
19.64.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.64.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.64.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.65 pair_style coul/cut/dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.66 pair_style coul/long/dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.67 pair_style lj/cut/coul/cut/dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.68 pair_style lj/cut/coul/debye/dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.69 pair_style lj/cut/coul/long/dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1902
19.70 pair_style lj/cut/coul/msm/dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903
19.71 pair_style lj/long/coul/long/dielectric command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903
19.71.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903
19.71.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903
19.71.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1903
19.71.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1904
19.71.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1904
19.71.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1904
19.71.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1904
19.72 pair_style lj/cut/dipole/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1904
19.73 pair_style lj/sf/dipole/sf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1904
19.74 pair_style lj/cut/dipole/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1905
19.75 pair_style lj/long/dipole/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1905
19.75.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1905
19.75.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1905
19.75.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1906
19.75.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1909
19.75.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1909
19.75.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1909
19.75.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1909
19.76 pair_style dpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.77 pair_style dpd/tstat command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.77.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.77.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.77.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1910
19.77.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1912
19.77.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912
19.77.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912
19.77.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1912
19.78 pair_style dpd/ext command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
19.79 pair_style dpd/ext/tstat command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
19.79.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
19.79.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
19.79.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1913
19.79.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915

lxxxii
 19.79.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915
19.80 pair_style dpd/fdt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915
19.81 pair_style dpd/fdt/energy command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915
19.81.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1915
19.81.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916
19.81.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1916
19.81.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1917
19.81.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
19.81.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
19.82 pair_style drip command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
19.82.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
19.82.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
19.82.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1918
19.82.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1919
19.82.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920
19.82.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920
19.83 pair_style dsmc command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920
19.83.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920
19.83.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1920
19.83.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1921
19.83.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1922
19.83.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
19.83.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
19.83.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
19.84 pair_style e3b command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
19.84.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1922
19.84.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923
19.84.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1923
19.84.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1924
19.84.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1924
19.84.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.84.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.85 pair_style eam command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.86 pair_style eam/alloy command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.87 pair_style eam/cd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.88 pair_style eam/cd/old command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.89 pair_style eam/fs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.90 pair_style eam/he command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.90.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1925
19.90.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926
19.90.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1926
19.90.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1931
19.90.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1931
19.90.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1931
19.90.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1931
19.91 pair_style edip command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932
19.92 pair_style edip/multi command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932
19.92.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932
19.92.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932
19.92.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1932
19.92.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1934
19.92.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1934
19.92.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1934
19.92.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1934

lxxxiii
 19.93 pair_style eff/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
19.93.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
19.93.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
19.93.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1935
19.93.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1938
19.93.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938
19.93.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1938
19.93.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
19.94 pair_style eim command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
19.94.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
19.94.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
19.94.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1939
19.94.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
19.94.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
19.94.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1941
19.95 pair_style exp6/rx command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942
19.95.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942
19.95.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942
19.95.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1942
19.95.4 Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1944
19.95.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1944
19.95.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1944
19.95.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1944
19.96 pair_style extep command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.96.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.96.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.96.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.96.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.96.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.96.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.97 pair_style lj/cut/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1945
19.98 pair_style lj/cut/coul/cut/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.99 pair_style lj/cut/coul/long/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.100pair_style lj/cut/tip4p/long/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.101pair_style lj/charmm/coul/long/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.102pair_style lj/class2/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.103pair_style lj/class2/coul/cut/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.104pair_style lj/class2/coul/long/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.105pair_style coul/cut/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.106pair_style coul/long/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.107pair_style tip4p/long/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1946
19.108pair_style morse/soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1947
19.108.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1947
19.108.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1948
19.108.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1949
19.108.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1952
19.108.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1952
19.108.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1952
19.108.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953
19.109pair_style gauss command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953
19.110pair_style gauss/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953
19.110.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953
19.110.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953
19.110.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1953

lxxxiv
 19.110.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1954
19.110.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1955
19.110.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1955
19.110.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1955
19.111pair_style gayberne command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
19.111.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
19.111.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
19.111.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1956
19.111.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1958
19.111.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958
19.111.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958
19.111.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958
19.112pair_style gran/hooke command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1959
19.113pair_style gran/hooke/history command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1959
19.114pair_style gran/hertz/history command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1959
19.114.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1959
19.114.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1960
19.114.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1960
19.114.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1962
19.114.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1962
19.114.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963
19.114.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963
19.115pair_style granular command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963
19.115.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963
19.115.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1963
19.115.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1964
19.115.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1971
19.115.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1972
19.115.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1972
19.115.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1972
19.115.8References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1972
19.116pair_style lj/gromacs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973
19.117pair_style lj/gromacs/coul/gromacs command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973
19.117.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1973
19.117.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974
19.117.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1974
19.117.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1975
19.117.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975
19.117.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1975
19.117.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
19.118pair_style gw command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
19.119pair_style gw/zbl command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
19.119.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
19.119.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
19.119.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1976
19.119.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1977
19.119.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977
19.119.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977
19.119.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1977
19.120pair_style hbond/dreiding/lj command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
19.121pair_style hbond/dreiding/morse command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
19.121.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
19.121.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978
19.121.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1978

lxxxv
 19.121.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1981
19.121.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1981
19.121.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
19.121.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
19.122pair_style hdnnp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
19.122.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
19.122.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1982
19.122.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1983
19.122.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1984
19.122.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
19.123pair_style hybrid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
19.124pair_style hybrid/overlay command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
19.125pair_style hybrid/scaled command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
19.125.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1985
19.125.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1986
19.125.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1986
19.125.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1990
19.125.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1991
19.125.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1991
19.125.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1991
19.126pair_style ilp/graphene/hbn command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1991
19.126.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1991
19.126.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1991
19.126.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1992
19.126.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1993
19.126.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1993
19.126.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1993
19.126.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1993
19.127pair_style kim command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1994
19.127.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1994
19.127.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1994
19.127.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1994
19.127.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1995
19.127.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
19.127.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
19.127.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
19.128pair_style kolmogorov/crespi/full command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
19.128.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
19.128.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1995
19.128.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1996
19.128.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 1997
19.128.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997
19.128.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997
19.128.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997
19.129pair_style kolmogorov/crespi/z command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997
19.129.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997
19.129.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998
19.129.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998
19.129.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1998
19.129.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999
19.129.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999
19.130pair_style lcbop command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999
19.130.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999
19.130.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999

lxxxvi
 19.130.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1999
19.130.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2000
19.130.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000
19.130.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000
19.130.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000
19.131pair_style lebedeva/z command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000
19.131.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2000
19.131.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001
19.131.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001
19.131.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001
19.131.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2001
19.131.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002
19.132pair_style line/lj command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002
19.132.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002
19.132.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002
19.132.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2002
19.132.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2003
19.132.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2003
19.132.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004
19.132.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004
19.133pair_style list command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004
19.133.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004
19.133.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004
19.133.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2004
19.133.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2006
19.133.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006
19.133.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006
19.133.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006
19.134pair_style lj/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006
19.134.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2006
19.134.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2007
19.134.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2007
19.134.4Coefficients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2007
19.134.5Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2008
19.134.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2008
19.134.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2008
19.135pair_style lj96/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2008
19.135.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2009
19.135.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2009
19.135.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2009
19.135.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2010
19.135.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010
19.135.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010
19.135.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010
19.136pair_style lj/cubic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010
19.136.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2010
19.136.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011
19.136.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2011
19.136.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2012
19.136.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012
19.136.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012
19.136.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012
19.137pair_style lj/cut/coul/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012
19.138pair_style lj/cut/coul/debye command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2012

lxxxvii
 19.139pair_style lj/cut/coul/dsf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013
19.140pair_style lj/cut/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013
19.141pair_style lj/cut/coul/msm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013
19.142pair_style lj/cut/coul/wolf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013
19.142.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2013
19.142.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2014
19.142.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2014
19.142.4Coefficients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2015
19.142.5Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2016
19.142.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2016
19.142.7Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017
19.142.8Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017
19.143pair_style lj/cut/tip4p/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017
19.144pair_style lj/cut/tip4p/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017
19.144.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2017
19.144.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018
19.144.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2018
19.144.4Coefficients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019
19.144.5Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2020
19.144.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2020
19.144.7Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2020
19.144.8Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2020
19.145pair_style lj/expand command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2020
19.146pair_style lj/expand/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021
19.146.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021
19.146.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021
19.146.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2021
19.146.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2022
19.146.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022
19.146.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022
19.146.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022
19.147pair_style lj/long/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2022
19.148pair_style lj/long/tip4p/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2023
19.148.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2023
19.148.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2023
19.148.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2024
19.148.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2025
19.148.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
19.148.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
19.148.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
19.149pair_style lj/relres command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
19.149.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
19.149.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
19.149.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2026
19.149.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2029
19.149.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
19.149.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
19.149.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
19.150pair_style lj/smooth command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
19.150.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
19.150.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
19.150.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2030
19.150.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2031
19.150.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032

lxxxviii
 19.150.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032
19.150.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032
19.151pair_style lj/smooth/linear command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032
19.151.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032
19.151.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032
19.151.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2032
19.151.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2033
19.151.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2033
19.151.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2033
19.151.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2034
19.152pair_style lj/switch3/coulgauss/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2034
19.153pair_style mm3/switch3/coulgauss/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . 2034
19.153.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2034
19.153.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2034
19.153.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2035
19.153.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2035
19.153.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036
19.153.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036
19.153.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036
19.154pair_style local/density command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036
19.154.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036
19.154.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036
19.154.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2036
19.154.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2039
19.154.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2039
19.154.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2039
19.154.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2039
19.155pair_style lubricate command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2040
19.156pair_style lubricate/poly command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2040
19.156.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2040
19.156.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2040
19.156.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2040
19.156.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2042
19.156.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2042
19.156.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043
19.156.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043
19.157pair_style lubricateU command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043
19.158pair_style lubricateU/poly command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043
19.158.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043
19.158.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043
19.158.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2044
19.158.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2045
19.158.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2045
19.158.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
19.158.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
19.159pair_style lj/mdf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
19.160pair_style buck/mdf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
19.161pair_style lennard/mdf command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
19.161.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2046
19.161.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047
19.161.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047
19.161.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2048
19.161.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2048
19.161.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049

lxxxix
 19.161.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
19.162pair_style meam command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
19.162.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
19.162.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
19.162.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2049
19.162.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2054
19.162.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054
19.162.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054
19.162.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2054
19.163pair_style meam/spline command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055
19.163.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055
19.163.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055
19.163.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2055
19.163.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2056
19.163.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
19.163.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
19.163.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
19.164pair_style meam/sw/spline command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
19.164.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
19.164.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
19.164.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2057
19.164.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2058
19.164.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
19.164.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
19.164.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
19.165pair_style mesocnt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
19.165.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
19.165.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
19.165.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2059
19.165.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2060
19.165.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.165.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.165.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.166pair_style edpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.167pair_style mdpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.168pair_style mdpd/rhosum command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.169pair_style tdpd command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.169.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2061
19.169.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2062
19.169.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2062
19.169.4Example scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2065
19.169.5Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2066
19.169.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067
19.169.7Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067
19.169.8Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067
19.170pair_style mesont/tpm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067
19.170.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2067
19.170.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2068
19.170.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2068
19.170.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2069
19.170.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2069
19.171pair_style mgpt command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2070
19.171.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2070
19.171.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2070

xc
 19.171.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2070
19.171.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2072
19.171.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2072
19.171.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2072
19.171.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2072
19.172pair_style mie/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2073
19.172.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2073
19.172.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2073
19.172.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2073
19.172.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2074
19.172.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2074
19.172.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2074
19.172.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2074
19.173pair_style mliap command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2074
19.173.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2074
19.173.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2075
19.173.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2075
19.173.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2077
19.173.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077
19.173.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077
19.173.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077
19.174pair_style momb command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077
19.174.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2077
19.174.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2078
19.174.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2078
19.174.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2078
19.174.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2078
19.174.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2078
19.175pair_style morse command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
19.176pair_style morse/smooth/linear command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
19.176.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
19.176.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
19.176.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2079
19.176.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2080
19.176.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
19.176.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
19.176.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
19.177pair_style multi/lucy command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
19.177.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
19.177.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
19.177.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2081
19.177.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2083
19.177.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2083
19.177.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2083
19.177.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2084
19.178pair_style multi/lucy/rx command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2084
19.178.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2084
19.178.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2084
19.178.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2084
19.178.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2086
19.178.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087
19.178.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087
19.178.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087
19.179pair_style nb3b/harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087

xci
 19.179.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087
19.179.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2087
19.179.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2088
19.179.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089
19.179.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089
19.179.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089
19.180pair_style nm/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089
19.181pair_style nm/cut/coul/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089
19.182pair_style nm/cut/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089
19.182.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2089
19.182.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2090
19.182.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2090
19.182.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2091
19.182.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2091
19.182.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2091
19.182.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2091
19.183pair_style none command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2092
19.183.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2092
19.183.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2092
19.183.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2092
19.183.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2092
19.183.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2092
19.183.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2092
19.184pair_style oxdna/excv command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
19.185pair_style oxdna/stk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
19.186pair_style oxdna/hbond command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
19.187pair_style oxdna/xstk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
19.188pair_style oxdna/coaxstk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
19.188.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
19.188.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2093
19.188.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2094
19.188.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.188.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.188.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.189pair_style oxdna2/excv command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.190pair_style oxdna2/stk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.191pair_style oxdna2/hbond command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.192pair_style oxdna2/xstk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.193pair_style oxdna2/coaxstk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.194pair_style oxdna2/dh command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.194.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2095
19.194.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2096
19.194.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2096
19.194.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097
19.194.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097
19.194.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2097
19.195pair_style oxrna2/excv command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2098
19.196pair_style oxrna2/stk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2098
19.197pair_style oxrna2/hbond command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2098
19.198pair_style oxrna2/xstk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2098
19.199pair_style oxrna2/coaxstk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2098
19.200pair_style oxrna2/dh command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2098
19.200.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2098
19.200.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2099

xcii
 19.200.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2099
19.200.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2100
19.200.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2100
19.200.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2100
19.201pair_style pace command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2100
19.201.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2100
19.201.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2101
19.201.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2101
19.201.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2101
19.201.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.201.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.201.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.202pair_style peri/pmb command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.203pair_style peri/lps command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.204pair_style peri/ves command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.205pair_style peri/eps command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.205.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.205.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2102
19.205.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2103
19.205.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2104
19.205.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
19.205.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
19.205.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
19.206pair_style polymorphic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
19.206.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
19.206.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2105
19.206.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2106
19.206.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2110
19.206.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2110
19.206.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2110
19.207pair_style python command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2110
19.207.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2110
19.207.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111
19.207.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2111
19.207.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2113
19.207.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2113
19.207.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
19.207.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
19.208pair_style quip command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
19.208.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
19.208.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
19.208.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2114
19.208.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2115
19.208.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
19.208.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
19.209pair_style rann command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
19.209.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
19.209.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2115
19.209.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2116
19.209.4Potential file syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2116
19.209.5Formulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2119
19.209.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2121
19.209.7Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2121
19.210pair_style reaxff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2121

xciii
 19.210.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2121
19.210.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2122
19.210.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2122
19.210.4Control file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2124
19.210.5Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2125
19.210.6Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126
19.210.7Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126
19.210.8Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126
19.211pair_style resquared command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126
19.211.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2126
19.211.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2127
19.211.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2127
19.211.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2128
19.211.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129
19.211.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129
19.211.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129
19.212pair_style lj/sdk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129
19.213pair_style lj/sdk/coul/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2130
19.214pair_style lj/sdk/coul/msm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2130
19.214.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2130
19.214.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2130
19.214.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2130
19.214.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2131
19.214.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132
19.214.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132
19.214.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132
19.215pair_style sdpd/taitwater/isothermal command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132
19.215.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132
19.215.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132
19.215.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2132
19.215.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2133
19.215.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2133
19.215.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2134
19.215.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2134
19.216pair_style smd/hertz command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2134
19.216.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2134
19.216.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2134
19.216.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2134
19.216.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2134
19.216.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
19.216.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
19.216.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
19.217pair_style smd/tlsph command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
19.217.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
19.217.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
19.217.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2135
19.217.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2136
19.217.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2136
19.217.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2136
19.217.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2136
19.218pair_style smd/tri_surface command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2136
19.218.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2136
19.218.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2136
19.218.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2136

xciv
 19.218.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2137
19.218.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137
19.218.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137
19.218.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137
19.219pair_style smd/ulsph command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137
19.219.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137
19.219.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137
19.219.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2137
19.219.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2138
19.219.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138
19.219.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138
19.219.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138
19.220pair_style smtbq command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138
19.220.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2138
19.220.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2139
19.220.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2139
19.220.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2142
19.220.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2142
19.220.6Citing this work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2142
19.221pair_style snap command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2143
19.221.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2143
19.221.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2143
19.221.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2143
19.221.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2146
19.221.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2146
19.221.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2146
19.221.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2146
19.222pair_style soft command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2147
19.222.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2147
19.222.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2147
19.222.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2147
19.222.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2148
19.222.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2148
19.222.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2148
19.222.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149
19.223pair_style sph/heatconduction command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149
19.223.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149
19.223.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149
19.223.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149
19.223.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2149
19.223.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150
19.223.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150
19.223.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150
19.224pair_style sph/idealgas command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150
19.224.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150
19.224.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150
19.224.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2150
19.224.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2151
19.224.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2151
19.224.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2151
19.224.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2151
19.225pair_style sph/lj command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2151
19.225.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2151
19.225.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2151

xcv
 19.225.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2152
19.225.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2152
19.225.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2152
19.225.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2152
19.225.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2152
19.226pair_style sph/rhosum command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2153
19.226.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2153
19.226.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2153
19.226.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2153
19.226.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2153
19.226.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2153
19.226.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2154
19.226.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2154
19.227pair_style sph/taitwater command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2154
19.227.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2154
19.227.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2154
19.227.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2154
19.227.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2155
19.227.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155
19.227.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155
19.227.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155
19.228pair_style sph/taitwater/morris command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155
19.228.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155
19.228.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2155
19.228.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2156
19.228.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2156
19.228.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2156
19.228.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2156
19.228.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2156
19.229pair_style spin/dipole/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2157
19.230pair_style spin/dipole/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2157
19.230.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2157
19.230.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2157
19.230.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2157
19.230.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158
19.230.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158
19.230.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158
19.231pair_style spin/dmi command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158
19.231.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158
19.231.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158
19.231.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2158
19.231.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
19.231.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
19.231.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
19.232pair_style spin/exchange command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
19.233pair_style spin/exchange/biquadratic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
19.233.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2159
19.233.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2160
19.233.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2160
19.233.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162
19.233.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162
19.233.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162
19.234pair_style spin/magelec command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162
19.234.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162

xcvi
 19.234.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162
19.234.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2162
19.234.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2163
19.234.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2163
19.234.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2163
19.235pair_style spin/neel command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2163
19.235.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2163
19.235.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2164
19.235.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2164
19.235.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2164
19.235.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2165
19.235.6Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2165
19.236pair_style srp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2165
19.236.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2165
19.236.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2165
19.236.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2166
19.236.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2167
19.236.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2167
19.236.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2167
19.236.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2167
19.237pair_style sw command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2167
19.237.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2168
19.237.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2168
19.237.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2168
19.237.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2170
19.237.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2170
19.237.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2170
19.237.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2170
19.238pair_style table command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171
19.238.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171
19.238.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171
19.238.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2171
19.238.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2174
19.238.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2174
19.238.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2174
19.238.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2174
19.239pair_style table/rx command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2174
19.239.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2174
19.239.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2175
19.239.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2175
19.239.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2177
19.239.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
19.239.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
19.239.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
19.240pair_style tersoff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
19.241pair_style tersoff/table command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
19.241.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
19.241.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2178
19.241.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2179
19.241.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2182
19.241.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182
19.241.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182
19.241.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2182
19.242pair_style tersoff/mod command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2183

xcvii
 19.243pair_style tersoff/mod/c command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2183
19.243.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2183
19.243.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2183
19.243.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2184
19.243.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2186
19.243.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186
19.243.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186
19.243.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2186
19.244pair_style tersoff/zbl command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2187
19.244.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2187
19.244.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2187
19.244.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2187
19.244.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2191
19.244.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2191
19.244.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2191
19.244.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2191
19.245pair_style thole command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2192
19.246pair_style lj/cut/thole/long command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2192
19.246.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2192
19.246.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2192
19.246.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2192
19.246.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2194
19.246.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2194
19.246.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2194
19.246.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2194
19.247pair_style tracker command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2194
19.247.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2194
19.247.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2195
19.247.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2195
19.247.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2195
19.247.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2195
19.247.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196
19.247.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196
19.248pair_style tri/lj command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196
19.248.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196
19.248.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196
19.248.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2196
19.248.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2197
19.248.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2197
19.248.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2197
19.248.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2197
19.249pair_style ufm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2197
19.249.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2198
19.249.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2198
19.249.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2198
19.249.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2199
19.249.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2199
19.249.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2199
19.249.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2199
19.250pair_style vashishta command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2200
19.251pair_style vashishta/table command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2200
19.251.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2200
19.251.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2200
19.251.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2200

xcviii
 19.251.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2202
19.251.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203
19.251.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203
19.251.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203
19.252pair_style wf/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203
19.252.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203
19.252.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203
19.252.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2204
19.252.4Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2205
19.252.5Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2205
19.253pair_style yukawa command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2205
19.253.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2205
19.253.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2205
19.253.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2206
19.253.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2206
19.253.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207
19.253.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207
19.253.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207
19.254pair_style yukawa/colloid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207
19.254.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207
19.254.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207
19.254.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2207
19.254.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2208
19.254.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
19.254.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
19.254.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
19.255pair_style zbl command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
19.255.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
19.255.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2209
19.255.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2210
19.255.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2211
19.255.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
19.255.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
19.255.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
19.256pair_style zero command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
19.256.1Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2211
19.256.2Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212
19.256.3Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2212
19.256.4Mixing, shift, table, tail correction, restart, rRESPA info . . . . . . . . . . . . . . . . . . . 2212
19.256.5Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2213
19.256.6Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2213
19.256.7Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2213

20 Bond Styles 2215

20.1 bond_style class2 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2215
20.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2215
20.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2215
20.1.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2215
20.1.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216
20.1.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216
20.1.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216
20.2 bond_style fene command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216
20.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216
20.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2216

xcix
 20.2.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217
20.2.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217
20.2.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2217
20.2.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
20.3 bond_style fene/expand command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
20.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
20.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
20.3.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2218
20.3.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219
20.3.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219
20.3.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219
20.4 bond_style gaussian command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219
20.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219
20.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2219
20.4.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2220
20.4.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2220
20.4.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2220
20.4.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2220
20.5 bond_style gromos command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2220
20.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221
20.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221
20.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221
20.5.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2221
20.5.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222
20.5.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222
20.6 bond_style harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222
20.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222
20.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222
20.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2222
20.6.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
20.6.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
20.6.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
20.7 bond_style harmonic/shift command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
20.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
20.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
20.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2223
20.7.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2224
20.7.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2224
20.7.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2224
20.8 bond_style harmonic/shift/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2224
20.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2224
20.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2224
20.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2225
20.8.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2225
20.8.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2225
20.8.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2225
20.9 bond_style hybrid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226
20.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226
20.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226
20.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226
20.9.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2226
20.9.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
20.9.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
20.10 bond_style mm3 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227

c
 20.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
20.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
20.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
20.10.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227
20.10.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2228
20.10.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2228
20.11 bond_style morse command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2228
20.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2228
20.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2228
20.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2228
20.11.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.11.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.11.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.12 bond_style none command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.12.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2229
20.12.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2230
20.12.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2230
20.13 bond_style nonlinear command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2230
20.13.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2230
20.13.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2230
20.13.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2230
20.13.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.13.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.13.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.14 bond_style oxdna/fene command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.15 bond_style oxdna2/fene command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.16 bond_style oxrna2/fene command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.16.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.16.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2231
20.16.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2232
20.16.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2233
20.16.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2233
20.16.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2233
20.17 bond_style quartic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2233
20.17.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2233
20.17.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2233
20.17.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2234
20.17.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2235
20.17.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2235
20.17.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2235
20.18 bond_style special command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2235
20.18.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2235
20.18.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2235
20.18.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2235
20.18.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236
20.18.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236
20.18.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2236
20.19 bond_style table command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2237
20.19.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2237
20.19.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2237
20.19.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2237

ci
 20.19.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 2238
20.19.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
20.19.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
20.19.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
20.20 bond_style zero command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
20.20.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
20.20.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
20.20.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239
20.20.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240
20.20.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240
20.20.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2240

21 Angle Styles 2241

21.1 angle_style charmm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241
21.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241
21.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241
21.1.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2241
21.1.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
21.1.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
21.1.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
21.2 angle_style class2 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
21.3 angle_style class2/p6 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
21.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2242
21.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2243
21.3.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2243
21.3.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2244
21.3.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2244
21.3.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2245
21.4 angle_style cosine command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2245
21.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2245
21.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2245
21.4.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2245
21.4.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
21.4.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
21.4.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
21.5 angle_style cosine/buck6d command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
21.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
21.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
21.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2246
21.5.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247
21.5.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247
21.5.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247
21.6 angle_style cosine/delta command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247
21.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247
21.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247
21.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2247
21.6.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248
21.6.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248
21.6.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248
21.7 angle_style cosine/periodic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248
21.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248
21.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2248
21.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2249
21.7.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2249

cii
 21.7.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2249
21.7.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2249
21.8 angle_style cosine/shift command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2250
21.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2250
21.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2250
21.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2250
21.8.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
21.8.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
21.8.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
21.9 angle_style cosine/shift/exp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
21.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
21.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
21.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2251
21.9.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2252
21.9.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2252
21.9.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2252
21.10 angle_style cosine/squared command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2252
21.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2252
21.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2252
21.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2253
21.10.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2253
21.10.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2253
21.10.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2253
21.11 angle_style cross command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2254
21.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2254
21.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2254
21.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2254
21.11.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2254
21.11.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2255
21.11.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2255
21.12 angle_style dipole command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2255
21.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2255
21.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2255
21.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2255
21.12.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2256
21.12.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257
21.12.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257
21.13 angle_style fourier command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257
21.13.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257
21.13.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257
21.13.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257
21.13.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
21.13.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
21.13.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
21.14 angle_style fourier/simple command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
21.14.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
21.14.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
21.14.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2258
21.14.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259
21.14.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259
21.14.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259
21.15 angle_style gaussian command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259
21.15.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259
21.15.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2259

ciii
 21.15.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2260
21.15.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2260
21.15.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2260
21.15.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2260
21.16 angle_style harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2260
21.16.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2261
21.16.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2261
21.16.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2261
21.16.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2261
21.16.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2262
21.16.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2262
21.17 angle_style hybrid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2262
21.17.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2262
21.17.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2262
21.17.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2262
21.17.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2263
21.17.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2263
21.17.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2263
21.18 angle_style mm3 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2263
21.18.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2263
21.18.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2263
21.18.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
21.18.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
21.18.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
21.18.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
21.19 angle_style none command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
21.19.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
21.19.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2264
21.19.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.19.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.19.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.19.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.20 angle_style quartic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.20.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.20.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.20.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2265
21.20.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2266
21.20.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2266
21.20.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2266
21.21 angle_style sdk command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2266
21.21.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2266
21.21.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2267
21.21.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2267
21.21.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2267
21.21.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2267
21.21.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2268
21.22 angle_style table command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2268
21.22.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2268
21.22.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2268
21.22.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2268
21.22.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 2270
21.22.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270
21.22.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270
21.22.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270

civ
 21.23 angle_style zero command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270
21.23.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270
21.23.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270
21.23.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2270
21.23.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2271
21.23.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2271
21.23.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2271

22 Dihedral Styles 2273

22.1 dihedral_style charmm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2273
22.2 dihedral_style charmmfsw command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2273
22.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2273
22.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2273
22.2.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2273
22.2.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2275
22.2.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2275
22.2.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2275
22.3 dihedral_style class2 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2275
22.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2275
22.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2275
22.3.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2276
22.3.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2278
22.3.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2278
22.3.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2278
22.4 dihedral_style cosine/shift/exp command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2278
22.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2278
22.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2278
22.4.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2279
22.4.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2279
22.4.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2279
22.4.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2280
22.5 dihedral_style fourier command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2280
22.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2280
22.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2280
22.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2280
22.5.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281
22.5.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281
22.5.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281
22.6 dihedral_style harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281
22.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281
22.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281
22.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2281
22.6.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2282
22.6.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2282
22.6.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2282
22.7 dihedral_style helix command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2282
22.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2282
22.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2283
22.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2283
22.7.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2283
22.7.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2283
22.7.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2284
22.8 dihedral_style hybrid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2284
22.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2284

cv
 22.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2284
22.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2284
22.8.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285
22.8.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285
22.8.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285
22.9 dihedral_style multi/harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285
22.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285
22.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2285
22.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286
22.9.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286
22.9.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286
22.9.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2286
22.10 dihedral_style nharmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287
22.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287
22.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287
22.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2287
22.10.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.10.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.10.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.11 dihedral_style none command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.11.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.11.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2288
22.11.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2289
22.12 dihedral_style opls command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2289
22.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2289
22.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2289
22.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2289
22.12.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
22.12.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
22.12.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
22.13 dihedral_style quadratic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
22.13.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
22.13.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
22.13.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2290
22.13.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291
22.13.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291
22.13.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291
22.14 dihedral_style spherical command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291
22.14.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291
22.14.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2291
22.14.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2292
22.14.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293
22.14.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293
22.14.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293
22.15 dihedral_style table command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293
22.16 dihedral_style table/cut command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293
22.16.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2293
22.16.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2294
22.16.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2294
22.16.4 Restart, fix_modify, output, run start/stop, minimize info . . . . . . . . . . . . . . . . . . . 2296
22.16.5 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297

cvi
 22.16.6 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297
22.16.7 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297
22.17 dihedral_style zero command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297
22.17.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297
22.17.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297
22.17.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2297
22.17.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2298
22.17.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2298
22.17.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2298

23 Improper Styles 2299

23.1 improper_style class2 command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299
23.1.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299
23.1.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299
23.1.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2299
23.1.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2300
23.1.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301
23.1.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301
23.2 improper_style cossq command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301
23.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301
23.2.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301
23.2.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2301
23.2.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2302
23.2.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2302
23.2.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2302
23.3 improper_style cvff command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2302
23.3.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2302
23.3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2302
23.3.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2303
23.3.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2303
23.3.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2303
23.3.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2304
23.4 improper_style distance command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2304
23.4.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2304
23.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2304
23.4.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2304
23.4.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305
23.4.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305
23.4.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305
23.5 improper_style distharm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305
23.5.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305
23.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305
23.5.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2305
23.5.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
23.5.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
23.5.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
23.6 improper_style fourier command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
23.6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
23.6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
23.6.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2306
23.6.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308
23.6.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308
23.6.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308
23.7 improper_style harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308

cvii
 23.7.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308
23.7.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308
23.7.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2308
23.7.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2309
23.7.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2309
23.7.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2309
23.8 improper_style hybrid command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2309
23.8.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2309
23.8.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2309
23.8.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2310
23.8.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2310
23.8.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311
23.8.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311
23.9 improper_style inversion/harmonic command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311
23.9.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311
23.9.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311
23.9.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2311
23.9.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.9.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.9.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.10 improper_style none command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.10.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.10.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.10.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2312
23.10.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.10.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.10.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.11 improper_style ring command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.11.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.11.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.11.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2313
23.11.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314
23.11.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314
23.12 improper_style sqdistharm command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314
23.12.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314
23.12.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2314
23.12.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.12.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.12.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.12.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.13 improper_style umbrella command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.13.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2315
23.13.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316
23.13.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2316
23.13.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317
23.13.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317
23.13.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317
23.14 improper_style zero command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317
23.14.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317
23.14.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317
23.14.3 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2317
23.14.4 Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318
23.14.5 Related commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318
23.14.6 Default . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2318

cviii
24 Bibliography 2319

IV Indices and tables 2335

Bibliography 2339

Python Module Index 2341

Index 2343

cix
cx
 LAMMPS Documentation, Release stable 29Sep2021

LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel Simulator.

LAMMPS is a classical molecular dynamics simulation code with a focus on materials modeling. It was designed to
run efficiently on parallel computers. It was developed originally at Sandia National Laboratories, a US Department of
Energy facility. The majority of funding for LAMMPS has come from the US Department of Energy (DOE). LAMMPS
is an open-source code, distributed freely under the terms of the GNU Public License Version 2 (GPLv2).
The LAMMPS website has a variety of information about the code. It includes links to an on-line version of this manual,
a mailing list and online forum where users can post questions, and a GitHub site where all LAMMPS development is
coordinated.

The content for this manual is part of the LAMMPS distribution. The online version always corresponds to the latest
development version. If needed, you can download or build a local copy of the manual as HTML pages or a PDF file
by following the steps on the Build the LAMMPS documentation page. If you have difficulties viewing the pages please
see this note.

The manual is organized in three parts: 1) the User Guide for how to install and use LAMMPS, 2) the Programmer
Guide for how to write programs using the LAMMPS library from different programming languages and how to modify
and extend LAMMPS, and 3) the Command Reference which includes detailed descriptions of all commands included
in the LAMMPS code.

LAMMPS DOCUMENTATION 1
LAMMPS Documentation, Release stable 29Sep2021

2 LAMMPS DOCUMENTATION
 Part I

User Guide

3
 CHAPTER

ONE

INTRODUCTION

These pages provide a brief introduction to LAMMPS.

1.1 Overview of LAMMPS

LAMMPS is a classical molecular dynamics (MD) code that models ensembles of particles in a liquid, solid, or gaseous
state. It can model atomic, polymeric, biological, solid-state (metals, ceramics, oxides), granular, coarse-grained, or
macroscopic systems using a variety of interatomic potentials (force fields) and boundary conditions. It can model 2d
or 3d systems with only a few particles up to millions or billions.
LAMMPS can be built and run on a laptop or desktop machine, but is designed for parallel computers. It will run
in serial and on any parallel machine that supports the MPI message-passing library. This includes shared-memory
boxes and distributed-memory clusters and supercomputers. Parts of LAMMPS also support OpenMP multi-threading,
vectorization and GPU acceleration.
LAMMPS is written in C++ and requires a compiler that is at least compatible with the C++-11 standard. Earlier
versions were written in F77, F90, and C++-98. See the History page of the website for details. All versions can be
downloaded as source code from the LAMMPS website.
LAMMPS is designed to be easy to modify or extend with new capabilities, such as new force fields, atom types,
boundary conditions, or diagnostics. See the Modify page for more details.
In the most general sense, LAMMPS integrates Newton’s equations of motion for a collection of interacting parti-
cles. A single particle can be an atom or molecule or electron, a coarse-grained cluster of atoms, or a mesoscopic or
macroscopic clump of material. The interaction models that LAMMPS includes are mostly short-range in nature; some
long-range models are included as well.
LAMMPS uses neighbor lists to keep track of nearby particles. The lists are optimized for systems with particles that
are repulsive at short distances, so that the local density of particles never becomes too large. This is in contrast to
methods used for modeling plasma or gravitational bodies (e.g. galaxy formation).
On parallel machines, LAMMPS uses spatial-decomposition techniques with MPI parallelization to partition the sim-
ulation domain into small sub-domains of equal computational cost, one of which is assigned to each processor. Pro-
cessors communicate and store “ghost” atom information for atoms that border their sub-domain. Multi-threading
parallelization and GPU acceleration with with particle-decomposition can be used in addition.

5
LAMMPS Documentation, Release stable 29Sep2021

1.2 What does a LAMMPS version mean

The LAMMPS “version” is the date when it was released, such as 1 May 2014. LAMMPS is updated continuously and
we aim to keep it working correctly and reliably at all times. You can follow its development in a public git repository
on GitHub.
Whenever we fix a bug or update or add a feature, it will be merged into the master branch of the git repository. When
a sufficient number of changes have accumulated and the software passes a set of automated tests, we release it in the
next patch release, which are made every few weeks. Info on patch releases are on this website page.
Once or twice a year, only bug fixes and small, non-intrusive changes are included for a period of time, and the code is
subjected to more detailed and thorough testing than the default automated testing. The latest patch release after such
a period is then labeled as a stable version.
Each version of LAMMPS contains all the features and bug-fixes up to and including its version date.
The version date is printed to the screen and logfile every time you run LAMMPS. It is also in the file src/version.h and
in the LAMMPS directory name created when you unpack a tarball. And it is on the first page of the manual.
• If you browse the HTML pages on the LAMMPS WWW site, they always describe the most current patch release
of LAMMPS.
• If you browse the HTML pages included in your tarball, they describe the version you have, which may be older.

1.3 LAMMPS features

LAMMPS is a classical molecular dynamics (MD) code with these general classes of functionality:
1. General features
2. Particle and model types
3. Interatomic potentials (force fields)
4. Atom creation
5. Ensembles, constraints, and boundary conditions
6. Integrators
7. Diagnostics
8. Output
9. Multi-replica models
10. Pre- and post-processing
11. Specialized features (beyond MD itself)

6 Chapter 1. Introduction
 LAMMPS Documentation, Release stable 29Sep2021

1.3.1 General features

• runs on a single processor or in parallel

• distributed memory message-passing parallelism (MPI)
• shared memory multi-threading parallelism (OpenMP)
• spatial decomposition of simulation domain for MPI parallelism
• particle decomposition inside of spatial decomposition for OpenMP and GPU parallelism
• GPLv2 licensed open-source distribution
• highly portable C++-11
• modular code with most functionality in optional packages
• only depends on MPI library for basic parallel functionality, MPI stub for serial compilation
• other libraries are optional and only required for specific packages
• GPU (CUDA, OpenCL, HIP, SYCL), Intel Xeon Phi, and OpenMP support for many code features
• easy to extend with new features and functionality
• runs from an input script
• syntax for defining and using variables and formulas
• syntax for looping over runs and breaking out of loops
• run one or multiple simulations simultaneously (in parallel) from one script
• build as library, invoke LAMMPS through library interface or provided Python wrapper or SWIG based wrappers
• couple with other codes: LAMMPS calls other code, other code calls LAMMPS, umbrella code calls both

1.3.2 Particle and model types

(See atom style command)

• atoms
• coarse-grained particles (e.g. bead-spring polymers)
• united-atom polymers or organic molecules
• all-atom polymers, organic molecules, proteins, DNA
• metals
• granular materials
• coarse-grained mesoscale models
• finite-size spherical and ellipsoidal particles
• finite-size line segment (2d) and triangle (3d) particles
• finite-size rounded polygons (2d) and polyhedra (3d) particles
• point dipole particles
• particles with magnetic spin
• rigid collections of n particles

1.3. LAMMPS features 7

LAMMPS Documentation, Release stable 29Sep2021

• hybrid combinations of these

1.3.3 Interatomic potentials (force fields)

(See pair style, bond style, angle style, dihedral style, improper style, kspace style commands)
• pairwise potentials: Lennard-Jones, Buckingham, Morse, Born-Mayer-Huggins, Yukawa, soft, class 2 (COM-
PASS), hydrogen bond, tabulated
• charged pairwise potentials: Coulombic, point-dipole
• many-body potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM), embedded ion method (EIM),
EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, Streitz-Mintmire, 3-body polymor-
phic, BOP, Vashishta
• machine learning potentials: SNAP, GAP, ACE, N2P2, RANN, AGNI
• long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-
mesh Ewald), MSM
• polarization models: QEq, core/shell model, Drude dipole model
• charge equilibration (QEq via dynamic, point, shielded, Slater methods)
• coarse-grained potentials: DPD, GayBerne, REsquared, colloidal, DLVO
• mesoscopic potentials: granular, Peridynamics, SPH, mesoscopic tubular potential (MESONT)
• semi-empirical potentials: multi-ion generalized pseudopotential theory (MGPT), second moment tight binding
+ QEq (SMTB-Q), density functional tight-binding (LATTE)
• electron force field (eFF, AWPMD)
• bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable), tabulated
• angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, class 2 (COMPASS), tabulated
• dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2 (COMPASS), OPLS, tabulated
• improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS), tabulated
• polymer potentials: all-atom, united-atom, bead-spring, breakable
• water potentials: TIP3P, TIP4P, SPC, SPC/E and variants
• interlayer potentials for graphene and analogues
• metal-organic framework potentials (QuickFF, MO-FF)
• implicit solvent potentials: hydrodynamic lubrication, Debye
• force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS op-
tions
• access to the OpenKIM Repository of potentials via kim command
• hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
• overlaid potentials: superposition of multiple pair potentials (including many-body) with optional scale factor

8 Chapter 1. Introduction
 LAMMPS Documentation, Release stable 29Sep2021

1.3.4 Atom creation

(See read_data, lattice, create_atoms, delete_atoms, displace_atoms, replicate commands)

• read in atom coords from files
• create atoms on one or more lattices (e.g. grain boundaries)
• delete geometric or logical groups of atoms (e.g. voids)
• replicate existing atoms multiple times
• displace atoms

1.3.5 Ensembles, constraints, and boundary conditions

(See fix command)

• 2d or 3d systems
• orthogonal or non-orthogonal (triclinic symmetry) simulation domains
• constant NVE, NVT, NPT, NPH, Parrinello/Rahman integrators
• thermostatting options for groups and geometric regions of atoms
• pressure control via Nose/Hoover or Berendsen barostatting in 1 to 3 dimensions
• simulation box deformation (tensile and shear)
• harmonic (umbrella) constraint forces
• rigid body constraints
• SHAKE bond and angle constraints
• motion constraints to manifold surfaces
• Monte Carlo bond breaking, formation, swapping, template based reaction modeling
• atom/molecule insertion and deletion
• walls of various kinds, static and moving
• non-equilibrium molecular dynamics (NEMD)
• variety of additional boundary conditions and constraints

1.3.6 Integrators

(See run, run_style, minimize commands)

• velocity-Verlet integrator
• Brownian dynamics
• rigid body integration
• energy minimization via conjugate gradient or steepest descent relaxation
• rRESPA hierarchical timestepping
• rerun command for post-processing of dump files

1.3. LAMMPS features 9

LAMMPS Documentation, Release stable 29Sep2021

1.3.7 Diagnostics

• see various flavors of the fix and compute commands

• introspection command for system, simulation, and compile time settings and configurations

1.3.8 Output

(dump, restart commands)

• log file of thermodynamic info
• text dump files of atom coords, velocities, other per-atom quantities
• binary restart files
• parallel I/O of dump and restart files
• per-atom quantities (energy, stress, centro-symmetry parameter, CNA, etc)
• user-defined system-wide (log file) or per-atom (dump file) calculations
• custom partitioning (chunks) for binning, and static or dynamic grouping of atoms for analysis
• spatial, time, and per-chunk averaging of per-atom quantities
• time averaging and histogramming of system-wide quantities
• atom snapshots in native, XYZ, XTC, DCD, CFG formats

1.3.9 Multi-replica models

• nudged elastic band

• hyperdynamics
• parallel replica dynamics
• temperature accelerated dynamics
• parallel tempering
• path-integral MD: first variant <fix_pimd>, second variant <fix_ipi>
• multi-walker collective variables with Colvars and Plumed

1.3.10 Pre- and post-processing

• A handful of pre- and post-processing tools are packaged with LAMMPS, some of which can convert input and
output files to/from formats used by other codes; see the Tools page.
• Our group has also written and released a separate toolkit called Pizza.py which provides tools for doing setup,
analysis, plotting, and visualization for LAMMPS simulations. Pizza.py is written in Python and is available for
download from the Pizza.py WWW site.

10 Chapter 1. Introduction
 LAMMPS Documentation, Release stable 29Sep2021

1.3.11 Specialized features

LAMMPS can be built with optional packages which implement a variety of additional capabilities. See the Optional
Packages page for details.
These are LAMMPS capabilities which you may not think of as typical classical MD options:
• static and dynamic load-balancing, optional with recursive bisectioning decomposition
• generalized aspherical particles
• stochastic rotation dynamics (SRD)
• real-time visualization and interactive MD, built-in renderer for images and movies
• calculate virtual diffraction patterns
• calculate finite temperature phonon dispersion and the dynamical matrix of minimized structures
• atom-to-continuum coupling with finite elements
• coupled rigid body integration via the POEMS library
• QM/MM coupling
• Monte Carlo via GCMC and tfMC and atom swapping
• path-integral molecular dynamics (PIMD) and this as well
• Direct Simulation Monte Carlo for low-density fluids
• Peridynamics modeling
• Lattice Boltzmann fluid
• targeted and steered molecular dynamics
• two-temperature electron model

1.4 LAMMPS non-features

LAMMPS is designed to be a fast, parallel engine for molecular dynamics (MD) simulations. It provides only a modest
amount of functionality for setting up simulations and analyzing their output.
Specifically, LAMMPS was not conceived and designed for:
• being run through a GUI
• building molecular systems, or building molecular topologies
• assign force-field coefficients automagically
• perform sophisticated analysis of your MD simulation
• visualize your MD simulation interactively
• plot your output data
Over the years some of these limitations have been reduced or removed, through features added to LAMMPS or external
tools that either closely interface with LAMMPS or extend LAMMPS.
Here are suggestions on how to perform these tasks:

1.4. LAMMPS non-features 11

LAMMPS Documentation, Release stable 29Sep2021

• GUI: LAMMPS can be built as a library and a Python wrapper that wraps the library interface is provided.
Thus, GUI interfaces can be written in Python (or C or C++ if desired) that run LAMMPS and visualize or plot
its output. Examples of this are provided in the python directory and described on the Python doc page. Also,
there are several external wrappers or GUI front ends.
• Builder: Several pre-processing tools are packaged with LAMMPS. Some of them convert input files in formats
produced by other MD codes such as CHARMM, AMBER, or Insight into LAMMPS input formats. Some of
them are simple programs that will build simple molecular systems, such as linear bead-spring polymer chains.
The moltemplate program is a true molecular builder that will generate complex molecular models. See the
Tools page for details on tools packaged with LAMMPS. The Pre/post processing page of the LAMMPS website
describes a variety of third party tools for this task. Furthermore, some LAMMPS internal commands allow to
reconstruct, or selectively add topology information, as well as provide the option to insert molecule templates
instead of atoms for building bulk molecular systems.
• Force-field assignment: The conversion tools described in the previous bullet for CHARMM, AMBER, and
Insight will also assign force field coefficients in the LAMMPS format, assuming you provide CHARMM, AM-
BER, or BIOVIA (formerly Accelrys) force field files. The tools ParmEd and InterMol are particularly powerful
and flexible in converting force field and topology data between various MD simulation programs.
• Simulation analysis: If you want to perform analysis on-the-fly as your simulation runs, see the compute and fix
doc pages, which list commands that can be used in a LAMMPS input script. Also see the Modify page for info
on how to add your own analysis code or algorithms to LAMMPS. For post-processing, LAMMPS output such as
dump file snapshots can be converted into formats used by other MD or post-processing codes. To some degree,
that conversion can be done directly inside of LAMMPS by interfacing to the VMD molfile plugins. The rerun
command also allows to do some post-processing of existing trajectories, and through being able to read a variety
of file formats, this can also be used for analyzing trajectories from other MD codes. Some post-processing tools
packaged with LAMMPS will do these conversions. Scripts provided in the tools/python directory can extract
and massage data in dump files to make it easier to import into other programs. See the Tools page for details on
these various options.
• Visualization: LAMMPS can produce NETPBM, JPG or PNG snapshot images on-the-fly via its dump image
command and pass them to an external program, FFmpeg to generate movies from them. For high-quality,
interactive visualization there are many excellent and free tools available. See the Visualization Tools page of
the LAMMPS website for visualization packages that can process LAMMPS output data.
• Plotting: See the next bullet about Pizza.py as well as the Python page for examples of plotting LAMMPS output.
Scripts provided with the python tool in the tools directory will extract and massage data in log and dump files
to make it easier to analyze and plot. See the Tools doc page for more discussion of the various tools.
• Pizza.py: Our group has also written a separate toolkit called Pizza.py which can do certain kinds of setup,
analysis, plotting, and visualization (via OpenGL) for LAMMPS simulations. It thus provides some functionality
for several of the above bullets. Pizza.py is written in Python and is available for download from this page.

1.5 LAMMPS open-source license

1.5.1 GPL version of LAMMPS

LAMMPS is an open-source code, available free-of-charge, and distributed under the terms of the GNU Public License
Version 2 (GPLv2), which means you can use or modify the code however you wish for your own purposes, but have
to adhere to certain rules when redistributing it - specifically in binary form - or are distributing software derived from
it or that includes parts of it.
LAMMPS comes with no warranty of any kind.
As each source file states in its header, it is a copyrighted code, and thus not in the public domain. For more information
about open-source software and open-source distribution, see www.gnu.org or www.opensource.org. The legal text of

12 Chapter 1. Introduction
 LAMMPS Documentation, Release stable 29Sep2021

the GPL as it applies to LAMMPS is in the LICENSE file included in the LAMMPS distribution.
Here is a more specific summary of what the GPL means for LAMMPS users:
(1) Anyone is free to use, copy, modify, or extend LAMMPS in any way they choose, including for commercial purposes.
(2) If you distribute a modified version of LAMMPS, it must remain open-source, meaning you are required to dis-
tribute all of it under the terms of the GPL. You should clearly annotate such a modified code as a derivative version
of LAMMPS.
(3) If you release any code that includes or uses LAMMPS source code, then it must also be open-sourced, meaning
you distribute it under the terms of the GPL. You may write code that interfaces LAMMPS to a differently licensed
library. In that case the code that provides the interface must be licensed GPL, but not necessarily that library unless
you are distributing binaries that require the library to run.
(4) If you give LAMMPS files to someone else, the GPL LICENSE file and source file headers (including the copyright
and GPL notices) should remain part of the code.

1.5.2 LGPL version of LAMMPS

We occasionally make stable LAMMPS releases available under the GNU Lesser Public License v2.1. This is on request
only and with non-LGPL compliant files removed. This allows uses linking non-GPL compatible software with the
(otherwise unmodified) LAMMPS library or loading it dynamically at runtime. Any modifications to the LAMMPS
code however, even with the LGPL licensed version, must still be made available under the same open source terms as
LAMMPS itself.

1.6 Authors of LAMMPS

The primary LAMMPS developers are at Sandia National Labs and Temple University:
• Steve Plimpton, sjplimp at sandia.gov
• Aidan Thompson, athomps at sandia.gov
• Stan Moore, stamoor at sandia.gov
• Axel Kohlmeyer, akohlmey at gmail.com
• Richard Berger, richard.berger at temple.edu
Past developers include Paul Crozier and Mark Stevens, both at Sandia, and Ray Shan, now at Materials Design.

The Authors page of the LAMMPS website has a comprehensive list of all the individuals who have contributed code
for a new feature or command or tool to LAMMPS.

The following folks deserve special recognition. Many of the packages they have written are unique for an MD code
and LAMMPS would not be as general-purpose as it is without their expertise and efforts.
• Metin Aktulga (MSU), REAXFF package for C/C++ version of ReaxFF
• Mike Brown (Intel), GPU and INTEL packages
• Colin Denniston (U Western Ontario), LATBOLTZ package
• Georg Ganzenmuller (EMI), MACHDYN and SPH packages
• Andres Jaramillo-Botero (Caltech), EFF package for electron force field

1.6. Authors of LAMMPS 13

LAMMPS Documentation, Release stable 29Sep2021

• Reese Jones (Sandia) and colleagues, ATC package for atom/continuum coupling
• Christoph Kloss (DCS Computing), LIGGGHTS code for granular materials, built on top of LAMMPS
• Rudra Mukherjee (JPL), POEMS package for articulated rigid body motion
• Trung Ngyuen (Northwestern U), GPU, RIGID, BODY, and DIELECTRIC packages
• Mike Parks (Sandia), PERI package for Peridynamics
• Roy Pollock (LLNL), Ewald and PPPM solvers
• Julien Tranchida (Sandia), SPIN package
• Christian Trott (Sandia), CUDA and KOKKOS packages
• Ilya Valuev (JIHT), AWPMD package for wave packet MD
• Greg Wagner (Northwestern U), MEAM package for MEAM potential

As discussed on the History page of the website, LAMMPS originated as a cooperative project between DOE labs and
industrial partners. Folks involved in the design and testing of the original version of LAMMPS were the following:
• John Carpenter (Mayo Clinic, formerly at Cray Research)
• Terry Stouch (Lexicon Pharmaceuticals, formerly at Bristol Myers Squibb)
• Steve Lustig (Dupont)
• Jim Belak and Roy Pollock (LLNL)

1.7 Citing LAMMPS

1.7.1 Core Algorithms

The paper mentioned below is the best overview of LAMMPS, but there are also publications describing particular
models or algorithms implemented in LAMMPS or complementary software that is has interfaces to. Please see below
for how to cite contributions to LAMMPS.
The latest canonical publication that describes the basic features, the source code design, the program structure, the
spatial decomposition approach, the neighbor finding, basic communications algorithms, and how users and developers
have contributed to LAMMPS is:
LAMMPS - A flexible simulation tool for particle-based materials modeling at the atomic, meso, and
continuum scales, Comp. Phys. Comm. (accepted 09/2021), DOI:10.1016/j.cpc.2021.108171
So a project using LAMMPS or a derivative application that uses LAMMPS as a simulation engine should cite this
paper. The paper is expected to be published in its final form under the same DOI in the first half of 2022. Please also
give the URL of the LAMMPS website in your paper, namely https://www.lammps.org.
The original publication describing the parallel algorithms used in the initial versions of LAMMPS is:
S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19
(1995).

14 Chapter 1. Introduction
 LAMMPS Documentation, Release stable 29Sep2021

1.7.2 DOI for the LAMMPS code

LAMMPS developers use the Zenodo service at CERN to create digital object identifies (DOI) for stable releases of
the LAMMPS source code. There are two types of DOIs for the LAMMPS source code.
The canonical DOI for all versions of LAMMPS, which will always point to the latest stable release version is:
• DOI: 10.5281/zenodo.3726416
In addition there are DOIs for individual stable releases. Currently there are:
• 3 March 2020 version: DOI:10.5281/zenodo.3726417
• 29 October 2020 version: DOI:10.5281/zenodo.4157471

1.7.3 Home page

The LAMMPS website at https://www.lammps.org/ is the canonical location for information about LAMMPS and its
features.

1.7.4 Citing contributions

LAMMPS has many features that use either previously published methods and algorithms or novel features. It also
includes potential parameter files for specific models. Where available, a reminder about references for optional features
used in a specific run is printed to the screen and log file. Style and output location can be selected with the -cite
command-line switch. Additional references are given in the documentation of the corresponding commands or in the
Howto tutorials. So please make certain, that you provide the proper acknowledgments and citations in any published
works using LAMMPS.

1.8 Additional website links

The LAMMPS website has a variety of additional info about LAMMPS, beyond what is in this manual. Some other
useful resources available online are listed below.
• Brief intro and recently added significant features
• List of features
• List of non-features
• Recent bug fixes and new features
• Download info
• GitHub site
• SourceForge site
• LAMMPS open-source license
• Glossary of terms relevant to LAMMPS
• LAMMPS highlights with images
• LAMMPS highlights with movies
• Mailing list
• LAMMPS forum

1.8. Additional website links 15

LAMMPS Documentation, Release stable 29Sep2021

• Workshops
• Tutorials
• Pre- and post-processing tools for LAMMPS
• Other software usable with LAMMPS
• Viz tools usable with LAMMPS
• Benchmark performance
• Publications that have cited LAMMPS
• Authors of LAMMPS
• History of LAMMPS development
• Funding for LAMMPS

16 Chapter 1. Introduction
 CHAPTER

TWO

INSTALL LAMMPS

You can download LAMMPS as an executable or as source code.

With source code, you also have to build LAMMPS. But you have more flexibility as to what features to include or
exclude in the build. If you plan to modify or extend LAMMPS, then you need the source code.

2.1 Download an executable for Linux

Binaries are available for different versions of Linux:

Pre-built Ubuntu Linux executables

Pre-built Fedora Linux executables
Pre-built EPEL Linux executables (RHEL, CentOS)
Pre-built OpenSuse Linux executables
Gentoo Linux executable
Arch Linux build-script

2.1.1 Pre-built Ubuntu Linux executables

A pre-built LAMMPS executable suitable for running on the latest Ubuntu Linux versions, can be downloaded as a
Debian package. This allows you to install LAMMPS with a single command, and stay up-to-date with the current
stable version of LAMMPS by simply updating your operating system. Please note, that the repository below offers
two LAMMPS packages, lammps-daily and lammps-stable. The LAMMPS developers recommend to use the
lammps-stable package for any production simulations. The lammps-daily package is built from the LAMMPS
development sources, and those versions may have known issues and bugs when new features are added and the software
has not undergone full release testing.
To install the appropriate personal-package archives (PPAs), do the following once:

$ sudo add-apt-repository ppa:gladky-anton/lammps

$ sudo add-apt-repository ppa:openkim/latest
$ sudo apt-get update

To install LAMMPS do the following once:

17
LAMMPS Documentation, Release stable 29Sep2021

$ sudo apt-get install lammps-stable

This downloads an executable named lmp_stable to your box, which can then be used in the usual way to run input
scripts:

$ lmp_stable -in in.lj

To update LAMMPS to the most current stable version, do the following:

$ sudo apt-get update

which will also update other packages on your system.

To get a copy of the current documentation and examples:

$ sudo apt-get install lammps-stable-doc

which will download the doc files in /usr/share/doc/lammps-stable-doc/doc and example problems in /usr/
share/doc/lammps-doc/examples.
To get a copy of the current potentials files:

$ sudo apt-get install lammps-stable-data

which will download the potentials files to /usr/share/lammps-stable/potentials. The lmp_stable binary is
hard-coded to look for potential files in this directory (it does not use the LAMMPS_POTENTIALS environment variable,
as described in pair_coeff command).
The lmp_stable binary is built with the KIM package which results in the above command also installing the kim-api
binaries when LAMMPS is installed. In order to use potentials from openkim.org, you can install the openkim-models
package

$ sudo apt-get install openkim-models

To un-install LAMMPS, do the following:

$ sudo apt-get remove lammps-stable

Please use lmp_stable -help to see which compilation options, packages, and styles are included in the binary.
Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this Ubuntu package capability.

2.1.2 Pre-built Fedora Linux executables

Pre-built LAMMPS packages for stable releases are available in the Fedora Linux distribution as of version 28. The
packages can be installed via the dnf package manager. There are 3 basic varieties (lammps = no MPI, lammps-mpich
= MPICH MPI library, lammps-openmpi = OpenMPI MPI library) and for each support for linking to the C library
interface (lammps-devel, lammps-mpich-devel, lammps-openmpi-devel), the header for compiling programs using the
C library interface (lammps-headers), and the LAMMPS python module for Python 3. All packages can be installed
at the same time and the name of the LAMMPS executable is lmp and lmp_openmpi or lmp_mpich respectively.
By default, lmp will refer to the serial executable, unless one of the MPI environment modules is loaded (module
load mpi/mpich-x86_64 or module load mpi/openmpi-x86_64). Then the corresponding parallel LAMMPS
executable can be used. The same mechanism applies when loading the LAMMPS python module.
To install LAMMPS with OpenMPI and run an input in.lj with 2 CPUs do:

18 Chapter 2. Install LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

$ dnf install lammps-openmpi

$ module load mpi/openmpi-x86_64
$ mpirun -np 2 lmp -in in.lj

The dnf install command is needed only once. In case of a new LAMMPS stable release, dnf update will auto-
matically update to the newer version as soon at the RPM files are built and uploaded to the download mirrors. The
module load command is needed once per (shell) session or shell terminal instance, unless it is automatically loaded
from the shell profile.
The LAMMPS binary is built with the KIM package which results in the above command also installing the kim-api
binaries when LAMMPS is installed. In order to use potentials from openkim.org, you can install the openkim-models
package

$ dnf install openkim-models

Please use lmp -help to see which compilation options, packages, and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in Fedora.

2.1.3 Pre-built EPEL Linux executable

Pre-built LAMMPS (and KIM) packages for stable releases are available in the Extra Packages for Enterprise Linux
(EPEL) repository for use with Red Hat Enterprise Linux (RHEL) or CentOS version 7.x and compatible Linux
distributions. Names of packages, executable, and content are the same as described above for Fedora Linux. But
RHEL/CentOS 7.x uses the yum package manager instead of dnf in Fedora 28.
Please use lmp -help to see which compilation options, packages, and styles are included in the binary.
Thanks to Christoph Junghans (LANL) for making LAMMPS available in EPEL.

2.1.4 Pre-built OpenSuse Linux executable

A pre-built LAMMPS package for stable releases is available in OpenSuse as of Leap 15.0. You can install the package
with:

$ zypper install lammps

This includes support for OpenMPI. The name of the LAMMPS executable is lmp. Thus to run an input in parallel on
2 CPUs you would do:

$ mpirun -np 2 lmp -in in.lj

Please use lmp -help to see which compilation options, packages, and styles are included in the binary.
The LAMMPS binary is built with the KIM package which results in the above command also installing the kim-api
binaries when LAMMPS is installed. In order to use potentials from openkim.org, you can install the openkim-models
package

$ zypper install openkim-models

Thanks to Christoph Junghans (LANL) for making LAMMPS available in OpenSuse.

2.1. Download an executable for Linux 19

LAMMPS Documentation, Release stable 29Sep2021

2.1.5 Gentoo Linux executable

LAMMPS is part of Gentoo’s main package tree and can be installed by typing:

% emerge --ask lammps

Note that in Gentoo the LAMMPS source is downloaded and the package is built on the your machine.
Certain LAMMPS packages can be enable via USE flags, type

% equery uses lammps

for details.
Thanks to Nicolas Bock and Christoph Junghans (LANL) for setting up this Gentoo capability.

2.1.6 Archlinux build-script

LAMMPS is available via Arch’s unofficial Arch User repository (AUR). There are three scripts available, named
lammps, lammps-beta and lammps-git. They respectively package the stable, patch and git releases.
To install, you will need to have the git package installed. You may use any of the above names in-place of lammps.

$ git clone https://aur.archlinux.org/lammps.git

$ cd lammps
$ makepkg -s
$ makepkg -i

To update, you may repeat the above, or change into the cloned directory, and execute the following, after which, if
there are any changes, you may use makepkg as above.

$ git pull

Alternatively, you may use an AUR helper to install these packages.

Note that the AUR provides build-scripts that download the source and the build the package on your machine.

2.2 Download an executable for Mac

LAMMPS can be downloaded, built, and configured for OS X on a Mac with Homebrew. (Alternatively, see the install
instructions for Download an executable via Conda.) The following LAMMPS packages are unavailable at this time
because of additional needs not yet met: GPU, KOKKOS, LATTE, MSCG, MESSAGE, MPIIO POEMS VORONOI.
After installing Homebrew, you can install LAMMPS on your system with the following commands:

% brew install lammps

This will install the executables “lammps_serial” and “lammps_mpi”, as well as the LAMMPS “doc”, “potentials”,
“tools”, “bench”, and “examples” directories.
Once LAMMPS is installed, you can test the installation with the Lennard-Jones benchmark file:

% brew test lammps -v

20 Chapter 2. Install LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

The LAMMPS binary is built with the KIM package which results in Homebrew also installing the kim-api binaries
when LAMMPS is installed. In order to use potentials from openkim.org, you can install the openkim-models package

% brew install openkim-models

If you have problems with the installation you can post issues to this link.
Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting up the Homebrew capability.

2.3 Download an executable for Windows

Pre-compiled Windows installers which install LAMMPS executables on a Windows system can be downloaded from
this site:
http://packages.lammps.org/windows.html
Note that each installer package has a date in its name, which corresponds to the LAMMPS version of the same date.
Installers for current and older versions of LAMMPS are available. 32-bit and 64-bit installers are available, and each
installer contains both a serial and parallel executable. The installer website also explains how to install the Windows
MPI package (MPICH2 from Argonne National Labs), needed to run in parallel with MPI.
The LAMMPS binaries contain all optional packages included in the source distribution except: KIM, KOKKOS,
MSCG, PYTHON, ADIOS, H5MD, NETCDF, QMMM, ML-QUIP, and VTK. The serial version also does not include
the MPIIO and LATBOLTZ packages. The GPU package is compiled for OpenCL with mixed precision kernels.
The LAMMPS library is compiled as a shared library and the LAMMPS Python module is installed, so that it is possible
to load LAMMPS into a Python interpreter.
The installer site also has instructions on how to run LAMMPS under Windows, once it is installed, in both serial and
parallel.
When you download the installer package, you run it on your Windows machine. It will then prompt you with a dialog,
where you can choose the installation directory, unpack and copy several executables, potential files, documentation
pdfs, selected example files, etc. It will then update a few system settings (e.g. PATH, LAMMPS_POTENTIALS) and
add an entry into the Start Menu (with references to the documentation, LAMMPS homepage and more). From that
menu, there is also a link to an uninstaller that removes the files and undoes the environment manipulations.
Note that to update to a newer version of LAMMPS, you should typically uninstall the version you currently have,
download a new installer, and go through the install procedure described above. I.e. the same procedure for in-
stalling/updating most Windows programs. You can install multiple versions of LAMMPS (in different directories), but
only the executable for the last-installed package will be found automatically, so this should only be done for debugging
purposes.

2.4 Download an executable for Linux or Mac via Conda

Binaries are available for MacOS or Linux via Conda.

First, one must setup the Conda package manager on your system. Follow the instructions to install Miniconda, then
create a conda environment (named my-lammps-env or whatever you prefer) for your lammps install:

% conda config --add channels conda-forge

% conda create -n my-lammps-env

Then, you can install lammps on your system with the following command:

2.3. Download an executable for Windows 21

LAMMPS Documentation, Release stable 29Sep2021

% conda activate my-lammps-env

% conda install lammps

The LAMMPS binary is built with the KIM package which results in Conda also installing the kim-api binaries when
LAMMPS is installed. In order to use potentials from openkim.org, you can install the openkim-models package

% conda install openkim-models

If you have problems with the installation you can post issues to this link. Thanks to Jan Janssen (Max-Planck-Institut
fuer Eisenforschung) for setting up the Conda capability.

2.5 Download source and documentation as a tarball

You can download a current LAMMPS tarball from the download page of the LAMMPS website.
You have two choices of tarballs, either the most recent stable release or the most current patch release. Stable releases
occur a few times per year, and undergo more testing before release. Patch releases occur a couple times per month.
The new contents in all releases are listed on the bug and feature page of the website.
Both tarballs include LAMMPS documentation (HTML and PDF files) corresponding to that version. The download
page also has an option to download the current-version LAMMPS documentation by itself.
Older versions of LAMMPS can also be downloaded from this page.
Once you have a tarball, unzip and untar it with the following command:

$ tar -xzvf lammps*.tar.gz

This will create a LAMMPS directory with the version date in its name, e.g. lammps-23Jun18.

You can also download a compressed tar or zip archives from the “Assets” sections of the LAMMPS GitHub releases
site. The file name will be lammps-<version>.zip which can be unzipped with the following command, to create a
lammps-<version> dir:

$ unzip lammps*.zip

This version corresponds to the selected LAMMPS patch or stable release.

2.6 Download the LAMMPS source with git

All LAMMPS development is coordinated through the “LAMMPS GitHub site”. If you clone the LAMMPS repository
onto your local machine, it has several advantages:
• You can stay current with changes to LAMMPS with a single git command.
• You can create your own development branches to add code to LAMMPS.
• You can submit your new features back to GitHub for inclusion in LAMMPS.
You must have git installed on your system to use the commands explained below to communicate with the git servers
on GitHub. For people still using subversion (svn), GitHub also provides limited support for subversion clients.

22 Chapter 2. Install LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Note: As of October 2016, the official home of public LAMMPS development is on GitHub. The previously advertised
LAMMPS git repositories on git.lammps.org and bitbucket.org are now deprecated or offline.

You can follow LAMMPS development on 3 different git branches:

• stable : this branch is updated with every stable release
• unstable : this branch is updated with every patch release
• master : this branch continuously follows ongoing development
To access the git repositories on your box, use the clone command to create a local copy of the LAMMPS repository
with a command like:

$ git clone -b unstable https://github.com/lammps/lammps.git mylammps

where “mylammps” is the name of the directory you wish to create on your machine and “unstable” is one of the 3
branches listed above. (Note that you actually download all 3 branches; you can switch between them at any time using
“git checkout <branch name>”.)
Once the command completes, your directory will contain the same files as if you unpacked a current LAMMPS tarball,
with the exception, that the HTML documentation files are not included. They can be fetched from the LAMMPS
website by typing make fetch in the doc directory. Or they can be generated from the content provided in doc/src by
typing make html from the doc directory.
After initial cloning, as bug fixes and new features are added to LAMMPS you can stay up-to-date by typing the
following git commands from within the “mylammps” directory:

$ git checkout unstable # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout master # to choose the branch to follow
$ git pull

Doing a “pull” will not change any files you have added to the LAMMPS directory structure. It will also not change
any existing LAMMPS files you have edited, unless those files have changed in the repository. In that case, git will
attempt to merge the new repository file with your version of the file and tell you if there are any conflicts. See the git
documentation for details.
If you want to access a particular previous release version of LAMMPS, you can instead “check out” any version with
a published tag. See the output of git tag -l for the list of tags. The git command to do this is as follows.

$ git checkout tagID

Stable versions and what tagID to use for a particular stable version are discussed on this page. Note that this command
will print some warnings, because in order to get back to the latest revision and to be able to update with git pull
again, you will need to do git checkout unstable (or check out any other desired branch) first.
Once you have updated your local files with a git pull (or git checkout), you still need to re-build LAMMPS if
any source files have changed. How to do this depends on the build system you are using.

CMake build
Change to your build folder and type:

cmake . --build

2.6. Download the LAMMPS source with git 23

LAMMPS Documentation, Release stable 29Sep2021

CMake should auto-detect whether it needs to re-run the CMake configuration step and otherwise redo the
build for all files that have been changed or files that depend on changed files. In case some build options
have been changed or renamed, you may have to update those by running:

cmake .

and then rebuild.

Traditional make
Switch to the src directory and type:

$ make purge # remove any deprecated src files

$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)

to enforce consistency of the source between the src folder and package directories. This is OK to do even
if you don’t use any packages. The “make purge” command removes any deprecated src files if they were
removed by the patch from a package sub-directory.

Warning: If you wish to edit/change a src file that is from a package, you should edit the version of
the file inside the package sub-directory with src, then re-install the package. The version in the source
directory is merely a copy and will be wiped out if you type “make package-update”.

Git protocols
The servers at github.com support the “git://” and “https://” access protocols for anonymous, read-only ac-
cess. If you have a suitably configured GitHub account, you may also use SSH protocol with the URL
“[email protected]:lammps/lammps.git”.

The LAMMPS GitHub project is currently managed by Axel Kohlmeyer (Temple U, akohlmey at gmail.com) and
Richard Berger (Temple U, richard.berger at temple.edu).
These are the files and sub-directories in the LAMMPS distribution:

README Short description of the LAMMPS package

LICENSE GNU General Public License (GPL)
SECURITY.md Security Policy for the LAMMPS package
bench benchmark problems
cmake CMake build files
doc documentation
examples simple test problems
fortran Fortran wrapper for LAMMPS
lib additional provided or external libraries
potentials interatomic potential files
python Python wrappers for LAMMPS
src source files
tools pre- and post-processing tools
unittest sources and inputs for testing LAMMPS

24 Chapter 2. Install LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

You will have all of these if you download source. You will only have some of them if you download executables, as
explained on the pages listed above.

2.6. Download the LAMMPS source with git 25

LAMMPS Documentation, Release stable 29Sep2021

26 Chapter 2. Install LAMMPS

 CHAPTER

THREE

BUILD LAMMPS

LAMMPS is built as a library and an executable from source code using either traditional makefiles for use with GNU
make (which may require manual editing), or using a build environment generated by CMake (Unix Makefiles, Ninja,
Xcode, Visual Studio, KDevelop, CodeBlocks and more).
As an alternative you can download a package with pre-built executables or automated build trees as described on the
Install page.

3.1 Build LAMMPS with CMake

This page describes how to use CMake in general to build LAMMPS. Details for specific compile time settings and
options to enable and configure add-on packages are discussed with those packages. Links to those pages on the Build
overview page.
The following text assumes some familiarity with CMake and focuses on using the command line tool cmake and what
settings are supported for building LAMMPS. A more detailed tutorial on how to use cmake itself, the text mode or
graphical user interface, change the generated output files for different build tools and development environments is on
a separate page.

Note: LAMMPS currently requires that CMake version 3.10 or later is available; version 3.12 or later is preferred.

Warning: You must not mix the traditional make based LAMMPS build procedure with using CMake. Thus no
packages may be installed or a build been previously attempted in the LAMMPS source directory by using make
<machine>. CMake will detect if this is the case and generate an error. To remove conflicting files from the src
you can use the command make no-all purge which will un-install all packages and delete all auto-generated
files.

3.1.1 Advantages of using CMake

CMake is an alternative to compiling LAMMPS in the traditional way through (manually customized) makefiles and
a recent addition to LAMMPS thanks to the efforts of Christoph Junghans (LANL) and Richard Berger (Temple U).
Using CMake has multiple advantages that are specifically helpful for people with limited experience in compiling
software or for people that want to modify or extend LAMMPS.
• CMake can detect available hardware, tools, features, and libraries and adapt the LAMMPS default build con-
figuration accordingly.
• CMake can generate files for different build tools and integrated development environments (IDE).

27
LAMMPS Documentation, Release stable 29Sep2021

• CMake supports customization of settings with a text mode or graphical user interface. No knowledge of file
formats or and complex command line syntax required.
• All enabled components are compiled in a single build operation.
• Automated dependency tracking for all files and configuration options.
• Support for true out-of-source compilation. Multiple configurations and settings with different choices of
LAMMPS packages, settings, or compilers can be configured and built concurrently from the same source tree.
• Simplified packaging of LAMMPS for Linux distributions, environment modules, or automated build tools like
Homebrew.
• Integration of automated regression testing (the LAMMPS side for that is still under development).

3.1.2 Getting started

Building LAMMPS with CMake is a two-step process. First you use CMake to generate a build environment in a new
directory. For that purpose you can use either the command-line utility cmake (or cmake3), the text-mode UI utility
ccmake (or ccmake3) or the graphical utility cmake-gui, or use them interchangeably. The second step is then the
compilation and linking of all objects, libraries, and executables. Here is a minimal example using the command line
version of CMake to build LAMMPS with no add-on packages enabled and no customization:

cd lammps # change to the LAMMPS distribution directory

mkdir build; cd build # create and use a build directory
cmake ../cmake # configuration reading CMake scripts from ../cmake
cmake --build . # compilation (or type "make")

This will create and change into a folder called build, then run the configuration step to generate build files for the
default build command and then launch that build command to compile LAMMPS. During the configuration step
CMake will try to detect whether support for MPI, OpenMP, FFTW, gzip, JPEG, PNG, and ffmpeg are available and
enable the corresponding configuration settings. The progress of this configuration can be followed on the screen and
a summary of selected options and settings will be printed at the end. The cmake --build . command will launch
the compilation, which, if successful, will ultimately produce a library liblammps.a and the LAMMPS executable
lmp inside the build folder.
Compilation can take a long time, since LAMMPS is a large project with many features. If your machine has multiple
CPU cores (most do these days), you can speed this up by compiling sources in parallel with make -j N (with N being
the maximum number of concurrently executed tasks). Also installation of the ccache (= Compiler Cache) software
may speed up repeated compilation even more, e.g. during code development.
After the initial build, whenever you edit LAMMPS source files, enable or disable packages, change compiler flags
or build options, you must re-compile and relink the LAMMPS executable with cmake --build . (or make). If the
compilation fails for some reason, try running cmake . and then compile again. The included dependency tracking
should make certain that only the necessary subset of files are re-compiled. You can also delete compiled objects,
libraries and executables with cmake --build . --target clean (or make clean).
After compilation, you may optionally install the LAMMPS executable into your system with:

make install # optional, copy compiled files into installation location

This will install the LAMMPS executable and library, some tools (if configured) and additional files like LAMMPS API
headers, manpages, potential and force field files. The location of the installation tree defaults to ${HOME}/.local.

28 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.1.3 Configuration and build options

The CMake commands have one mandatory argument: a folder containing a file called CMakeLists.txt (for
LAMMPS it is located in the cmake folder) or a build folder containing a file called CMakeCache.txt, which is
generated at the end of the CMake configuration step. The cache file contains all current CMake settings.
To modify settings, enable or disable features, you need to set variables with either the -D command line flag (-D
VARIABLE1_NAME=value) or change them in the text mode of graphical user interface. The -D flag can be used
several times in one command.
For your convenience we provide CMake presets that combine multiple settings to enable optional LAMMPS packages
or use a different compiler tool chain. Those are loaded with the -C flag (-C ../cmake/presets/basic.cmake).
This step would only be needed once, as the settings from the preset files are stored in the CMakeCache.txt file. It is
also possible to customize the build by adding one or more -D flags to the CMake command line.
Generating files for alternate build tools (e.g. Ninja) and project files for IDEs like Eclipse, CodeBlocks, or Kate can
be selected using the -G command line flag. A list of available generator settings for your specific CMake version is
given when running cmake --help.

3.1.4 Installing CMake

Check if your machine already has CMake installed:

which cmake # do you have it?

which cmake3 # version 3 may have this name
cmake --version # what specific version you have

On clusters or supercomputers which use environment modules to manage software packages, do this:

module list # is a module for cmake already loaded?

module avail # is a module for cmake available?
module load cmake # load cmake module with appropriate name

Most Linux distributions offer pre-compiled cmake packages through their package management system. If you do
not have CMake or a recent enough version (Note: for CentOS 7.x you need to enable the EPEL repository), you can
download the latest version from https://cmake.org/download/. Instructions on how to install it on various platforms
can be found on this page.

3.2 Build LAMMPS with make

Building LAMMPS with traditional makefiles requires that you have a Makefile.<machine> file appropriate for
your system in either the src/MAKE, src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see
below). It can include various options for customizing your LAMMPS build with a number of global compilation
options and features.

3.2. Build LAMMPS with make 29

LAMMPS Documentation, Release stable 29Sep2021

3.2.1 Requirements

Those makefiles are written for and tested with GNU make and may not be compatible with other make programs. In
most cases, if the “make” program is not GNU make, then there will be a GNU make program available under the name
“gmake”. If GNU make or a compatible make is not available, you may have to first install it or switch to building
with CMake. The makefiles of the traditional make based build process and the scripts they are calling expect a few
additional tools to be available and functioning.
• a working C/C++ compiler toolchain supporting the C++11 standard; on Linux these are often the GNU com-
pilers. Some older compilers require adding flags like -std=c++11 to enable the C++11 mode.
• a Bourne shell compatible “Unix” shell program (often this is bash)
• a few shell utilities: ls, mv, ln, rm, grep, sed, tr, cat, touch, diff, dirname
• python (optional, required for make lib-<pkg> in the src folder). python scripts are currently tested with python
2.7 and 3.6. The procedure for building the documentation requires python 3.5 or later.

3.2.2 Getting started

To include LAMMPS packages (i.e. optional commands and styles) you must enable (or “install”) them first, as
discussed on the Build package page. If a packages requires (provided or external) libraries, you must configure
and build those libraries before building LAMMPS itself and especially before enabling such a package with make
yes-<package>. Building LAMMPS with CMake can automate much of this for many types of machines, especially
workstations, desktops, and laptops, so we suggest you try it first when building LAMMPS in those cases.
The commands below perform a default LAMMPS build, producing the LAMMPS executable lmp_serial and
lmp_mpi in lammps/src:

cd lammps/src # change to main LAMMPS source folder

make serial # build a serial LAMMPS executable using GNU g++
make mpi # build a parallel LAMMPS executable with MPI
make # see a variety of make options

Compilation can take a long time, since LAMMPS is a large project with many features. If your machine has multiple
CPU cores (most do these days), you can speed this up by compiling sources in parallel with make -j N (with N being
the maximum number of concurrently executed tasks). Also installation of the ccache (= Compiler Cache) software
may speed up repeated compilation even more, e.g. during code development.
After the initial build, whenever you edit LAMMPS source files, or add or remove new files to the source directory
(e.g. by installing or uninstalling packages), you must re-compile and relink the LAMMPS executable with the same
make <machine> command. The makefile’s dependency tracking should insure that only the necessary subset of files
are re-compiled. If you change settings in the makefile, you have to recompile everything. To delete all objects you can
use make clean-<machine>.

Note: Before the actual compilation starts, LAMMPS will perform several steps to collect information from the
configuration and setup that is then embedded into the executable. When you build LAMMPS for the first time, it will
also compile a tool to quickly assemble a list of dependencies, that are required for the make program to correctly detect
which parts need to be recompiled after changes were made to the sources.

30 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.2.3 Customized builds and alternate makefiles

The src/MAKE directory tree contains the Makefile.<machine> files included in the LAMMPS distribution. Typing
make example uses Makefile.example from one of those folders, if available. Thus the make serial and make
mpi lines above use src/MAKE/Makefile.serial and src/MAKE/Makefile.mpi, respectively. Other makefiles are
in these directories:

OPTIONS # Makefiles which enable specific options

MACHINES # Makefiles for specific machines
MINE # customized Makefiles you create (you may need to create this folder)

Simply typing make lists all the available Makefile.<machine> files with a single line description toward the end
of the output. A file with the same name can appear in multiple folders (not a good idea). The order the directories
are searched is as follows: src/MAKE/MINE, src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives pref-
erence to a customized file you put in src/MAKE/MINE. If you create your own custom makefile under a new name,
please edit the first line with the description and machine name, so you will not confuse yourself, when looking at the
machine summary.
Makefiles you may wish to try include these (some require a package first be installed). Many of these include specific
compiler flags for optimized performance. Please note, however, that some of these customized machine Makefile are
contributed by users. Since both compilers, OS configurations, and LAMMPS itself keep changing, their settings may
become outdated:

make mac # build serial LAMMPS on a Mac

make mac_mpi # build parallel LAMMPS on a Mac
make intel_cpu # build with the INTEL package optimized for CPUs
make knl # build with the INTEL package optimized for KNLs
make opt # build with the OPT package optimized for CPUs
make omp # build with the OPENMP package optimized for OpenMP
make kokkos_omp # build with the KOKKOS package for OpenMP
make kokkos_cuda_mpi # build with the KOKKOS package for GPUs
make kokkos_phi # build with the KOKKOS package for KNLs

3.3 Link LAMMPS as a library to another code

LAMMPS is designed as a library of C++ objects that can be integrated into other applications including Python
scripts. The files src/library.cpp and src/library.h define a C-style API for using LAMMPS as a library. See
the Library interface to LAMMPS page for a description of the interface and how to use it for your needs.
The Basic build options page explains how to build LAMMPS as either a shared or static library. This results in a file
in the compilation folder called liblammps.a or liblammps_<name>.a in case of building a static library. In case
of a shared library the name is the same only that the suffix is going to be either .so or .dylib or .dll instead of .a
depending on the OS. In some cases the .so file may be a symbolic link to a file with the suffix .so.0 (or some other
number).

Note: Care should be taken to use the same MPI library for the calling code and the LAMMPS library unless LAMMPS
is to be compiled without (real) MPI support using the include STUBS MPI library.

3.3. Link LAMMPS as a library to another code 31

LAMMPS Documentation, Release stable 29Sep2021

3.3.1 Link with LAMMPS as a static library

The calling application can link to LAMMPS as a static library with compilation and link commands as in the examples
shown below. These are examples for a code written in C in the file caller.c. The benefit of linking to a static library
is, that the resulting executable is independent of that library since all required executable code from the library is
copied into the calling executable.

CMake build
This assumes that LAMMPS has been configured without setting a LAMMPS_MACHINE name, installed
with “make install”, and the PKG_CONFIG_PATH environment variable has been updated to include the
liblammps.pc file installed into the configured destination folder. The commands to compile and link a
coupled executable are then:

mpicc -c -O $(pkgconf liblammps --cflags) caller.c

mpicxx -o caller caller.o -$(pkgconf liblammps --libs)

Traditional make
This assumes that LAMMPS has been compiled in the folder ${HOME}/lammps/src with “make mpi”.
The commands to compile and link a coupled executable are then:

mpicc -c -O -I${HOME}/lammps/src caller.c

mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi

The -I argument is the path to the location of the library.h header file containing the interface to the
LAMMPS C-style library interface. The -L argument is the path to where the liblammps_mpi.a file is
located. The -llammps_mpi argument is shorthand for telling the compiler to link the file liblammps_mpi.
a. If LAMMPS has been built as a shared library, then the linker will use liblammps_mpi.so instead.
If both files are available, the linker will usually prefer the shared library. In case of a shared library, you
may need to update the LD_LIBRARY_PATH environment variable or running the caller executable will
fail since it cannot find the shared library at runtime.

However, it is only as simple as shown above for the case of a plain LAMMPS library without any optional packages
that depend on libraries (bundled or external) or when using a shared library. Otherwise, you need to include all flags,
libraries, and paths for the coupled executable, that are also required to link the LAMMPS executable.

CMake build
When using CMake, additional libraries with sources in the lib folder are built, but not included in
liblammps.a and (currently) not installed with make install and not included in the pkgconfig con-
figuration file. They can be found in the top level build folder, but you have to determine the necessary
link flags manually. It is therefore recommended to either use the traditional make procedure to build and
link with a static library or build and link with a shared library instead.

Traditional make
After you have compiled a static LAMMPS library using the conventional build system for example with
“make mode=static serial”. And you also have installed the POEMS package after building its bundled
library in lib/poems. Then the commands to build and link the coupled executable change to:

32 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

gcc -c -O -I${HOME}/lammps/src -caller.c

g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
-L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \
-llammps_serial -lpoems -lmpi_stubs

Note, that you need to link with g++ instead of gcc even if you have written your code in C, since LAMMPS
itself is C++ code. You can display the currently applied settings for building LAMMPS for the “serial”
machine target by using the command:

make mode=print serial

Which should output something like:

# Compiler:
CXX=g++
# Linker:
LD=g++
# Compilation:
CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/
,→lib/poems -I${HOME}/compile/lammps/src/STUBS

# Linking:
LDFLAGS=-g -O
# Libraries:
LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/
,→lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs

From this you can gather the necessary paths and flags. With makefiles for other machine configurations
you need to do the equivalent and replace “serial” with the corresponding “machine” name of the makefile.

3.3.2 Link with LAMMPS as a shared library

When linking to LAMMPS built as a shared library, the situation becomes much simpler, as all dependent libraries and
objects are either included in the shared library or registered as a dependent library in the shared library file. Thus those
libraries need not to be specified when linking the calling executable. Only the -I flags are needed. So the example
case from above of the serial version static LAMMPS library with the POEMS package installed becomes:

CMake build
The commands with a shared LAMMPS library compiled with the CMake build process are the same as
for the static library.

mpicc -c -O $(pkgconf liblammps --cflags) caller.c

mpicxx -o caller caller.o -$(pkgconf --libs)

Traditional make
The commands with a shared LAMMPS library compiled with the traditional make build using make
mode=shared serial becomes:

3.3. Link LAMMPS as a library to another code 33

LAMMPS Documentation, Release stable 29Sep2021

gcc -c -O -I${HOME}/lammps/src -caller.c

g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial

Locating liblammps.so at runtime

Unlike with a static link, now the liblammps.so file is required at runtime and needs to be in a folder, where the
shared linker program of the operating system can find it. This would be either a folder like /usr/local/lib64 or
${HOME}/.local/lib64 or a folder pointed to by the LD_LIBRARY_PATH environment variable. You can type

printenv LD_LIBRARY_PATH

to see what directories are in that list.

Or you can add the LAMMPS src directory or the directory you performed a CMake style build in to your
LD_LIBRARY_PATH environment variable, so that the current version of the shared library is always available to pro-
grams that use it.
For the Bourne or Korn shells (/bin/sh, /bin/ksh, /bin/bash etc.), you would add something like this to your ${HOME}/
.profile file:

LD_LIBRARY_PATH ${LD_LIBRARY_PATH-/usr/lib64}:${HOME}/lammps/src
export LD_LIBRARY_PATH

For the csh or tcsh shells, you would equivalently add something like this to your ${HOME}/.cshrc file:

setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src

You can verify whether all required shared libraries are found with the ldd tool. Example:

$ LD_LIBRARY_PATH=/home/user/lammps/src ldd caller

linux-vdso.so.1 (0x00007ffe729e0000)
liblammps.so => /home/user/lammps/src/liblammps.so (0x00007fc91bb9e000)
libstdc++.so.6 => /lib64/libstdc++.so.6 (0x00007fc91b984000)
libm.so.6 => /lib64/libm.so.6 (0x00007fc91b83e000)
libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00007fc91b824000)
libc.so.6 => /lib64/libc.so.6 (0x00007fc91b65b000)
/lib64/ld-linux-x86-64.so.2 (0x00007fc91c094000)

If a required library is missing, you would get a ‘not found’ entry:

$ ldd caller
linux-vdso.so.1 (0x00007ffd672fe000)
liblammps.so => not found
libstdc++.so.6 => /usr/lib64/libstdc++.so.6 (0x00007fb7c7e86000)
libm.so.6 => /usr/lib64/libm.so.6 (0x00007fb7c7d40000)
libgcc_s.so.1 => /usr/lib64/libgcc_s.so.1 (0x00007fb7c7d26000)
libc.so.6 => /usr/lib64/libc.so.6 (0x00007fb7c7b5d000)
/lib64/ld-linux-x86-64.so.2 (0x00007fb7c80a2000)

34 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.4 Basic build options

The following topics are covered on this page, for building with both CMake and make:
• Serial vs parallel build
• Choice of compiler and compile/link options
• Build the LAMMPS executable and library
• Including and removing debug support
• Install LAMMPS after a build

3.4.1 Serial vs parallel build

LAMMPS is written to use the ubiquitous MPI (Message Passing Interface) library API for distributed memory parallel
computation. You need to have such a library installed for building and running LAMMPS in parallel using a domain
decomposition parallelization. It is compatible with the MPI standard version 2.x and later. LAMMPS can also be
built into a “serial” executable for use with a single processor using the bundled MPI STUBS library.
Independent of the distributed memory MPI parallelization, parts of LAMMPS are also written with support for shared
memory parallelization using the OpenMP threading standard. A more detailed discussion of that is below.

CMake build

-D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else␣

,→no

-D BUILD_OMP=value # yes or no, default is yes if a compatible compiler␣

,→is detected

-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc

# no default value

The executable created by CMake (after running make) is named lmp unless the LAMMPS_MACHINE
option is set. When setting LAMMPS_MACHINE=name the executable will be called lmp_name. Using
BUILD_MPI=no will enforce building a serial executable using the MPI STUBS library.

Traditional make
The build with traditional makefiles has to be done inside the source folder src.

make mpi # parallel build, produces lmp_mpi using Makefile.mpi

make serial # serial build, produces lmp_serial using Makefile/
,→serial

make mybox # uses Makefile.mybox to produce lmp_mybox

Any make machine command will look up the make settings from a file Makefile.machine in the
folder src/MAKE or one of its sub-directories MINE, MACHINES, or OPTIONS, create a folder Obj_machine
with all objects and generated files and an executable called lmp_machine. The standard parallel build
with make mpi assumes a standard MPI installation with MPI compiler wrappers where all necessary
compiler and linker flags to get access and link with the suitable MPI headers and libraries are set by the
wrapper programs. For other cases or the serial build, you have to adjust the make file variables MPI_INC,
MPI_PATH, MPI_LIB as well as CC and LINK. To enable OpenMP threading usually a compiler specific flag

3.4. Basic build options 35

LAMMPS Documentation, Release stable 29Sep2021

needs to be added to the compile and link commands. For the GNU compilers, this is -fopenmp, which
can be added to the CC and LINK makefile variables.
For the serial build the following make variables are set (see src/MAKE/Makefile.serial):

CC = g++
LINK = g++
MPI_INC = -I../STUBS
MPI_PATH = -L../STUBS
MPI_LIB = -lmpi_stubs

You also need to build the STUBS library for your platform before making LAMMPS itself. A make
serial build does this for you automatically, otherwise, type make mpi-stubs from the src directory,
or make from the src/STUBS dir. If the build fails, you may need to edit the STUBS/Makefile for your
platform. The stubs library does not provide MPI/IO functions required by some LAMMPS packages, e.g.
MPIIO or LATBOLTZ, and thus is not compatible with those packages.

Note: The file src/STUBS/mpi.cpp provides a CPU timer function called MPI_Wtime() that calls
gettimeofday(). If your operating system does not support gettimeofday(), you will need to insert
code to call another timer. Note that the ANSI-standard function clock() rolls over after an hour or so,
and is therefore insufficient for timing long LAMMPS simulations.

MPI and OpenMP support in LAMMPS

If you are installing MPI yourself to build a parallel LAMMPS executable, we recommend either MPICH or OpenMPI
which are regularly used and tested with LAMMPS by the LAMMPS developers. MPICH can be downloaded from
the MPICH home page and OpenMPI can be downloaded correspondingly from the OpenMPI home page. Other MPI
packages should also work. No specific vendor provided and standard compliant MPI library is currently known to be
incompatible with LAMMPS. If you are running on a large parallel machine, your system admins or the vendor should
have already installed a version of MPI, which is likely to be faster than a self-installed MPICH or OpenMPI, so you
should study the provided documentation to find out how to build and link with it.
The majority of OpenMP (threading) support in LAMMPS is provided by the OPENMP package; see the OPENMP
package page for details. The INTEL package also includes OpenMP threading (it is compatible with OPENMP and will
usually fall back on styles from that package, if a INTEL does not exist) and adds vectorization support when compiled
with compatible compilers, in particular the Intel compilers on top of OpenMP. Also, the KOKKOS package can be
compiled to include OpenMP threading.
In addition, there are a few commands in LAMMPS that have native OpenMP support included as well. These are
commands in the MPIIO, ML-SNAP, DIFFRACTION, and DPD-REACT packages. In addition some packages support
OpenMP threading indirectly through the libraries they interface to: e.g. LATTE, KSPACE, and COLVARS. See the
Packages details page for more info on these packages and the pages for their respective commands for OpenMP
threading info.
For CMake, if you use BUILD_OMP=yes, you can use these packages and turn on their native OpenMP support and
turn on their native OpenMP support at run time, by setting the OMP_NUM_THREADS environment variable before you
launch LAMMPS.
For building via conventional make, the CCFLAGS and LINKFLAGS variables in Makefile.machine need to include the
compiler flag that enables OpenMP. For GNU compilers it is -fopenmp. For (recent) Intel compilers it is -qopenmp.
If you are using a different compiler, please refer to its documentation.

36 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

OpenMP Compiler compatibility

Some compilers do not fully support the default(none) directive and others (e.g. GCC version 9 and beyond, Clang
version 10 and later) may implement strict OpenMP 4.0 and later semantics, which are incompatible with the OpenMP
3.1 semantics used in LAMMPS for maximal compatibility with compiler versions in use. If compilation with OpenMP
enabled fails because of your compiler requiring strict OpenMP 4.0 semantics, you can change the behavior by adding
-D LAMMPS_OMP_COMPAT=4 to the LMP_INC variable in your makefile, or add it to the command line while configuring
with CMake. LAMMPS will auto-detect a suitable setting for most GNU, Clang, and Intel compilers.

3.4.2 Choice of compiler and compile/link options

The choice of compiler and compiler flags can be important for maximum performance. Vendor provided compilers for
a specific hardware can produce faster code than open-source compilers like the GNU compilers. On the most common
x86 hardware most popular C++ compilers are quite similar in performance of C/C++ code at high optimization levels.
When using the INTEL package, there is a distinct advantage in using the Intel C++ compiler due to much improved
vectorization through SSE and AVX instructions on compatible hardware as the source code includes changes and
Intel compiler specific directives to enable high degrees of vectorization. This may change over time as equivalent
vectorization directives are included into OpenMP standard revisions and other compilers adopt them.
On parallel clusters or supercomputers which use “environment modules” for their compile/link environments, you can
often access different compilers by simply loading the appropriate module before building LAMMPS.

CMake build
By default CMake will use the compiler it finds according to internal preferences and it will add opti-
mization flags appropriate to that compiler and any accelerator packages you have included in the build.
CMake will check if the detected or selected compiler is compatible with the C++ support requirements
of LAMMPS and stop with an error, if this is not the case.
You can tell CMake to look for a specific compiler with setting CMake variables (listed below) during
configuration. For a few common choices, there are also presets in the cmake/presets folder. For con-
venience, there is a CMAKE_TUNE_FLAGS variable that can be set to apply global compiler options (applied
to compilation only), to be used for adding compiler or host specific optimization flags in addition to the
“flags” variables listed below. You may also specify the corresponding CMAKE_*_FLAGS variables indi-
vidually, if you want to experiment with alternate optimization flags. You should specify all 3 compilers,
so that the (few) LAMMPS source files written in C or Fortran are built with a compiler consistent with
the one used for the C++ files:

-D CMAKE_CXX_COMPILER=name # name of C++ compiler

-D CMAKE_C_COMPILER=name # name of C compiler
-D CMAKE_Fortran_COMPILER=name # name of Fortran compiler

-D CMAKE_CXX_FLAGS=string # flags to use with C++ compiler

-D CMAKE_C_FLAGS=string # flags to use with C compiler
-D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler

A few example command lines are:

# Building with GNU Compilers:

cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_
,→COMPILER=gfortran

# Building with Intel Compilers:

(continues on next page)

3.4. Basic build options 37

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_
,→Fortran_COMPILER=ifort

# Building with Intel oneAPI Compilers:

cmake ../cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx -DCMAKE_
,→Fortran_COMPILER=ifx

# Building with LLVM/Clang Compilers:

cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_
,→Fortran_COMPILER=flang

# Building with PGI/Nvidia Compilers:

cmake ../cmake -DCMAKE_C_COMPILER=pgcc -DCMAKE_CXX_COMPILER=pgc++ -DCMAKE_
,→Fortran_COMPILER=pgfortran

For compiling with the Clang/LLVM compilers a CMake preset is provided that can be loaded with -
C ../cmake/presets/clang.cmake. Similarly, -C ../cmake/presets/intel.cmake should switch the compiler
toolchain to the legacy Intel compilers, -C ../cmake/presets/oneapi.cmake will switch to the LLVM based
oneAPI Intel compilers, and -C ../cmake/presets/pgi.cmake will switch the compiler to the PGI compilers.
In addition you can set CMAKE_TUNE_FLAGS to specifically add compiler flags to tune for optimal perfor-
mance on given hosts. By default this variable is empty.

Note: When the cmake command completes, it prints a summary to the screen which compilers it is
using and what flags and settings will be used for the compilation. Note that if the top-level compiler is
mpicxx, it is simply a wrapper on a real compiler. The underlying compiler info is what CMake will try
to determine and report. You should check to confirm you are using the compiler and optimization flags
you want.

Makefile.machine settings for traditional make

The “compiler/linker settings” section of a Makefile.machine lists compiler and linker settings for your C++
compiler, including optimization flags. For a parallel build it is recommended to use mpicxx or mpiCC,
since these compiler wrappers will include a variety of settings appropriate for your MPI installation and
thus avoiding the guesswork of finding the right flags.
Parallel build (see src/MAKE/Makefile.mpi):

CC = mpicxx
CCFLAGS = -g -O3
LINK = mpicxx
LINKFLAGS = -g -O

Serial build with GNU gcc (see src/MAKE/Makefile.serial):

CC = g++
CCFLAGS = -g -O3
LINK = g++
LINKFLAGS = -g -O

Note: If compilation stops with a message like the following:

38 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp

In file included from ../pointers.h:24:0,
from ../input.h:17,
from ../main.cpp:16:
../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant␣
,→compiler. Enable C++11 compatibility or upgrade the compiler.

then you have either an unsupported (old) compiler or you have to turn on C++11 mode. The latter applies
to GCC 4.8.x shipped with RHEL 7.x and CentOS 7.x or GCC 5.4.x shipped with Ubuntu16.04. For
those compilers, you need to add the -std=c++11 flag. If there is no compiler that supports this flag (or
equivalent), you would have to install a newer compiler that supports C++11; either as a binary package
or through compiling from source.
If you build LAMMPS with any Accelerator packages included, there may be specific compiler or linker
flags that are either required or recommended to enable required features and to achieve optimal perfor-
mance. You need to include these in the CCFLAGS and LINKFLAGS settings above. For details, see the
documentation for the individual packages listed on the Accelerator packages page. Or examine these files
in the src/MAKE/OPTIONS directory. They correspond to each of the 5 accelerator packages and their
hardware variants:

Makefile.opt # OPT package

Makefile.omp # OPENMP package
Makefile.intel_cpu # INTEL package for CPUs
Makefile.intel_coprocessor # INTEL package for KNLs
Makefile.gpu # GPU package
Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs
Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP)
Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP)

3.4.3 Build the LAMMPS executable and library

LAMMPS is always built as a library of C++ classes plus an executable. The executable is a simple main() function that
sets up MPI and then creates a LAMMPS class instance from the LAMMPS library, which will then process commands
provided via a file or from the console input. The LAMMPS library can also be called from another application or a
scripting language. See the Howto couple doc page for more info on coupling LAMMPS to other codes. See the Python
page for more info on wrapping and running LAMMPS from Python via its library interface.

CMake build
For CMake builds, you can select through setting CMake variables between building a shared or a static
LAMMPS library and what kind of suffix is added to them (in case you want to concurrently install multiple
variants of binaries with different settings). If none are set, defaults are applied.

-D BUILD_SHARED_LIBS=value # yes or no (default)

-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value

The compilation will always produce a LAMMPS library and an executable linked to it. By default this will
be a static library named liblammps.a and an executable named lmp Setting BUILD_SHARED_LIBS=yes

3.4. Basic build options 39

LAMMPS Documentation, Release stable 29Sep2021

will instead produce a shared library called liblammps.so (or liblammps.dylib or liblammps.dll
depending on the platform) If LAMMPS_MACHINE=name is set in addition, the name of the generated li-
braries will be changed to either liblammps_name.a or liblammps_name.so, respectively and the ex-
ecutable will be called lmp_name.

Traditional make
With the traditional makefile based build process, the choice of the generated executable or library depends
on the “mode” setting. Several options are available and mode=static is the default.

make machine # build LAMMPS executable lmp_machine

make mode=static machine # same as "make machine"
make mode=shared machine # build LAMMPS shared lib liblammps_machine.so␣
,→instead

The “static” build will generate a static library called liblammps_machine.a and an executable named
lmp_machine, while the “shared” build will generate a shared library liblammps_machine.so in-
stead and lmp_machine will be linked to it. The build step will also create generic soft links, named
liblammps.a and liblammps.so, which point to the specific liblammps_machine.a/so files.

Additional information

Note that for creating a shared library, all the libraries it depends on must be compiled to be compatible with shared
libraries. This should be the case for libraries included with LAMMPS, such as the dummy MPI library in src/STUBS
or any package libraries in the lib directory, since they are always built in a shared library compatible way using the
-fPIC compiler switch. However, if an auxiliary library (like MPI or FFTW) does not exist as a compatible format,
the shared library linking step may generate an error. This means you will need to install a compatible version of the
auxiliary library. The build instructions for that library should tell you how to do this.
As an example, here is how to build and install the MPICH library, a popular open-source version of MPI, as a shared
library in the default /usr/local/lib location:

./configure --enable-shared
make
make install

You may need to use sudo make install in place of the last line if you do not have write privileges for /usr/local/
lib or use the --prefix configuration option to select an installation folder, where you do have write access. The end
result should be the file /usr/local/lib/libmpich.so. On many Linux installations the folder ${HOME}/.local
is an alternative to using /usr/local and does not require superuser or sudo access. In that case the configuration
step becomes:

./configure --enable-shared --prefix=${HOME}/.local

Avoiding to use “sudo” for custom software installation (i.e. from source and not through a package manager tool
provided by the OS) is generally recommended to ensure the integrity of the system software installation.

40 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.4.4 Including or removing debug support

By default the compilation settings will include the -g flag which instructs the compiler to include debug information
(e.g. which line of source code a particular instruction correspond to). This can be extremely useful in case LAMMPS
crashes and can help to provide crucial information in tracking down the origin of a crash and help the LAMMPS
developers fix bugs in the source code. However, this increases the storage requirements for object files, libraries, and
the executable 3-5 fold.
If this is a concern, you can change the compilation settings or remove the debug information from the LAMMPS
executable:
• Traditional make: edit your Makefile.<machine> to remove the -g flag from the CCFLAGS and LINKFLAGS
definitions
• CMake: use -D CMAKE_BUILD_TYPE=Release or explicitly reset the applicable compiler flags (best done using
the text mode or graphical user interface).
• Remove debug info: If you are only concerned about the executable being too large, you can use the strip tool
(e.g. strip lmp_serial) to remove the debug information from the executable file. Do not strip libraries or
object files, as that will render them unusable.

3.4.5 Build LAMMPS tools

Some tools described in Auxiliary tools can be built directly using CMake or Make.

CMake build

-D BUILD_TOOLS=value # yes or no (default)

-D BUILD_LAMMPS_SHELL=value # yes or no (default)

The generated binaries will also become part of the LAMMPS installation (see below).

Traditional make

cd lammps/tools
make all # build all binaries of tools
make binary2txt # build only binary2txt tool
make chain # build only chain tool
make micelle2d # build only micelle2d tool
make thermo_extract # build only thermo_extract tool

cd lammps/tools/lammps-shell
make # build LAMMPS shell

3.4. Basic build options 41

LAMMPS Documentation, Release stable 29Sep2021

3.4.6 Install LAMMPS after a build

After building LAMMPS, you may wish to copy the LAMMPS executable of library, along with other LAMMPS files
(library header, doc files) to a globally visible place on your system, for others to access. Note that you may need
super-user privileges (e.g. sudo) if the directory you want to copy files to is protected.

CMake build

cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake

make # perform make after CMake command
make install # perform the installation into prefix

During the installation process CMake will by default remove any runtime path settings for loading shared
libraries. Because of this you may have to set or modify the LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH)
environment variable, if you are installing LAMMPS into a non-system location and/or are linking to li-
braries in a non-system location that depend on such runtime path settings. As an alternative you may
set the CMake variable LAMMPS_INSTALL_RPATH to on and then the runtime paths for any linked shared
libraries and the library installation folder for the LAMMPS library will be embedded and thus the require-
ment to set environment variables is avoided. The off setting is usually preferred for packaged binaries
or when setting up environment modules, the on setting is more convenient for installing software into a
non-system or personal folder.

Traditional make
There is no “install” option in the src/Makefile for LAMMPS. If you wish to do this you will need to
first build LAMMPS, then manually copy the desired LAMMPS files to the appropriate system directories.

3.5 Optional build settings

LAMMPS can be built with several optional settings. Each sub-section explain how to do this for building both with
CMake and make.
• C++11 standard compliance when building all of LAMMPS
• FFT library for use with the kspace_style pppm command
• Size of LAMMPS integer types
• Read or write compressed files
• Output of JPG and PNG files via the dump image command
• Output of movie files via the dump_movie command
• Memory allocation alignment
• Workaround for long long integers
• Error handling exceptions when using LAMMPS as a library

42 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.5.1 C++11 standard compliance

A C++11 standard compatible compiler is a requirement for compiling LAMMPS. LAMMPS version 3 March 2020 is
the last version compatible with the previous C++98 standard for the core code and most packages. Most currently used
C++ compilers are compatible with C++11, but some older ones may need extra flags to enable C++11 compliance.
Example for GNU c++ 4.8.x:

CCFLAGS = -g -O3 -std=c++11

3.5.2 FFT library

When the KSPACE package is included in a LAMMPS build, the kspace_style pppm command performs 3d FFTs
which require use of an FFT library to compute 1d FFTs. The KISS FFT library is included with LAMMPS but other
libraries can be faster. LAMMPS can use them if they are available on your system.

CMake build

-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found,␣

,→else KISS

-D FFT_SINGLE=value # yes or no (default), no = double precision

-D FFT_PACK=value # array (default) or pointer or memcpy

Note: The values for the FFT variable must be in upper-case. This is an exception to the rule that all
CMake variables can be specified with lower-case values.

Usually these settings are all that is needed. If FFTW3 is selected, then CMake will try to detect, if threaded
FFTW libraries are available and enable them by default. This setting is independent of whether OpenMP
threads are enabled and a packages like KOKKOS or OPENMP is used. If CMake cannot detect the FFT
library, you can set these variables to assist:

-D FFTW3_INCLUDE_DIR=path # path to FFTW3 include files

-D FFTW3_LIBRARY=path # path to FFTW3 libraries
-D FFTW3_OMP_LIBRARY=path # path to FFTW3 OpenMP wrapper libraries
-D FFT_FFTW_THREADS=on # enable using OpenMP threaded FFTW3 libraries
-D MKL_INCLUDE_DIR=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARY=path # path to MKL libraries

Traditional make
To change the FFT library to be used and its options, you have to edit your machine Makefile. Below are
examples how the makefile variables could be changed.

FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3),␣

,→-DFFT_MKL, or -DFFT_KISS

# default is KISS if not specified

FFT_INC = -DFFT_SINGLE # do not specify for double precision
(continues on next page)

3.5. Optional build settings 43

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries
FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
# default is FFT_PACK_ARRAY if not specified

FFT_INC = -I/usr/local/include
FFT_PATH = -L/usr/local/lib
FFT_LIB = -lfftw3 # FFTW3 double precision
FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads␣
,→(needs -DFFT_FFTW_THREADS)

FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision

FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with␣
,→Intel compiler, serial interface

FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU␣

,→compiler, serial interface

FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with␣

,→Intel compiler, threaded interface

FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU␣

,→compiler, threaded interface

FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of␣

,→interface libs

As with CMake, you do not need to set paths in FFT_INC or FFT_PATH, if the compiler can find the FFT
header and library files in its default search path. You must specify FFT_LIB with the appropriate FFT
libraries to include in the link.

The KISS FFT library is included in the LAMMPS distribution. It is portable across all platforms. Depending on the
size of the FFTs and the number of processors used, the other libraries listed here can be faster.
However, note that long-range Coulombics are only a portion of the per-timestep CPU cost, FFTs are only a portion
of long-range Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel communication can be costly). A
breakdown of these timings is printed to the screen at the end of a run when using the kspace_style pppm command.
The Screen and logfile output page gives more details. A more detailed (and time consuming) report of the FFT
performance is generated with the kspace_modify fftbench yes command.
FFTW is a fast, portable FFT library that should also work on any platform and can be faster than the KISS FFT
library. You can download it from www.fftw.org. LAMMPS requires version 3.X; the legacy version 2.1.X is no longer
supported.
Building FFTW for your box should be as simple as ./configure; make; make install. The install command
typically requires root privileges (e.g. invoke it via sudo), unless you specify a local directory with the “–prefix” option
of configure. Type ./configure --help to see various options.
The Intel MKL math library is part of the Intel compiler suite. It can be used with the Intel or GNU compiler (see the
FFT_LIB setting above).
Performing 3d FFTs in parallel can be time consuming due to data access and required communication. This cost
can be reduced by performing single-precision FFTs instead of double precision. Single precision means the real and
imaginary parts of a complex datum are 4-byte floats. Double precision means they are 8-byte doubles. Note that
Fourier transform and related PPPM operations are somewhat less sensitive to floating point truncation errors and thus
the resulting error is less than the difference in precision. Using the -DFFT_SINGLE setting trades off a little accuracy
for reduced memory use and parallel communication costs for transposing 3d FFT data.
When using -DFFT_SINGLE with FFTW3 you may need to build the FFTW library a second time with support for
single-precision.

44 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

For FFTW3, do the following, which should produce the additional library libfftw3f.a or libfftw3f.so.

make clean
./configure --enable-single; make; make install

Performing 3d FFTs requires communication to transpose the 3d FFT grid. The data packing/unpacking for this can
be done in one of 3 modes (ARRAY, POINTER, MEMCPY) as set by the FFT_PACK syntax above. Depending on
the machine, the size of the FFT grid, the number of processors used, one option may be slightly faster. The default is
ARRAY mode.

3.5.3 Size of LAMMPS integer types and size limits

LAMMPS has a few integer data types which can be defined as either 4-byte (= 32-bit) or 8-byte (= 64-bit) integers
at compile time. This has an impact on the size of a system that can be simulated or how large counters can become
before “rolling over”. The default setting of “smallbig” is almost always adequate.

CMake build
With CMake the choice of integer types is made via setting a variable during configuration.

-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall

If the variable is not set explicitly, “smallbig” is used.

Traditional build
If you want a setting different from the default, you need to edit the LMP_INC variable setting your machine
Makefile.

LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL

The default setting is -DLAMMPS_SMALLBIG if nothing is specified

LAMMPS system size restrictions

smallbig bigbig smallsmall

Total atom count 263 atoms (= 9.223 · 1018 ) 263 atoms (= 9.223 · 1018 ) 231 atoms (= 2.147 · 109 )
Total timesteps 263 steps (= 9.223 · 1018 ) 263 steps (= 9.223 · 1018 ) 231 steps (= 2.147 · 109 )
Atom ID values 1 ≤ i ≤ 231 (= 2.147 · 109 ) 1 ≤ i ≤ 263 (= 9.223 · 1018 ) 1 ≤ i ≤ 231 (= 2.147 · 109 )
Image flag values −512 ≤ i ≤ 511 −1 048 576 ≤ i ≤ 1 048 575 −512 ≤ i ≤ 511

The “bigbig” setting increases the size of image flags and atom IDs over “smallbig” and the “smallsmall” setting is
only needed if your machine does not support 64-bit integers or incurs performance penalties when using them.
These are limits for the core of the LAMMPS code, specific features or some styles may impose additional limits. The
ATC package cannot be compiled with the “bigbig” setting. Also, there are limitations when using the library interface
where some functions with known issues have been replaced by dummy calls printing a corresponding error message
rather than crashing randomly or corrupting data.

3.5. Optional build settings 45

LAMMPS Documentation, Release stable 29Sep2021

Atom IDs are not required for atomic systems which do not store bond topology information, though IDs are enabled
by default. The atom_modify id no command will turn them off. Atom IDs are required for molecular systems with
bond topology (bonds, angles, dihedrals, etc). Similarly, some force or compute or fix styles require atom IDs. Thus if
you model a molecular system or use one of those styles with more than 2 billion atoms, you need the “bigbig” setting.
Regardless of the total system size limits, the maximum number of atoms per MPI rank (local + ghost atoms) is limited
to 2 billion for atomic systems and 500 million for systems with bonds (the additional restriction is due to using the 2
upper bits of the local atom index in neighbor lists for storing special bonds info).
Image flags store 3 values per atom in a single integer which count the number of times an atom has moved through the
periodic box in each dimension. See the dump manual page for a discussion. If an atom moves through the periodic box
more than this limit, the value will “roll over”, e.g. from 511 to -512, which can cause diagnostics like the mean-squared
displacement, as calculated by the compute msd command, to be faulty.
Also note that the GPU package requires its lib/gpu library to be compiled with the same size setting, or the link will
fail. A CMake build does this automatically. When building with make, the setting in whichever lib/gpu/Makefile
is used must be the same as above.

3.5.4 Output of JPG, PNG, and movie files

The dump image command has options to output JPEG or PNG image files. Likewise the dump movie command outputs
movie files in MPEG format. Using these options requires the following settings:

CMake build

-D WITH_JPEG=value # yes or no
# default = yes if CMake finds JPEG files, else no
-D WITH_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB files,␣
,→else no

-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no

Usually these settings are all that is needed. If CMake cannot find the graphics header, library, executable
files, you can set these variables:

-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file

-D JPEG_LIBRARY=path # path to libjpeg.a (.so) file
-D PNG_INCLUDE_DIR=path # path to png.h header file
-D PNG_LIBRARY=path # path to libpng.a (.so) file
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARY=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable

Traditional make

LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG

(continues on next page)

46 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header␣
,→files if make cannot find them

JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so)␣

,→files if make cannot find them

JPG_LIB = -ljpeg -lpng -lz # library names

As with CMake, you do not need to set JPG_INC or JPG_PATH, if make can find the graphics header and
library files. You must specify JPG_LIB with a list of graphics libraries to include in the link. You must
insure ffmpeg is in a directory where LAMMPS can find it at runtime, that is a directory in your PATH
environment variable.

Using ffmpeg to output movie files requires that your machine supports the “popen” function in the standard runtime
library.

Note: On some clusters with high-speed networks, using the fork() library call (required by popen()) can interfere
with the fast communication library and lead to simulations using ffmpeg to hang or crash.

3.5.5 Read or write compressed files

If this option is enabled, large files can be read or written with gzip compression by several LAMMPS commands,
including read_data, rerun, and dump.

CMake build

-D WITH_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it

Traditional make

LMP_INC = -DLAMMPS_GZIP

This option requires that your operating system fully supports the “popen()” function in the standard runtime library
and that a gzip executable can be found by LAMMPS during a run.

Note: On some clusters with high-speed networks, using the “fork()” library call (required by “popen()”) can inter-
fere with the fast communication library and lead to simulations using compressed output or input to hang or crash.
For selected operations, compressed file I/O is also available using a compression library instead, which is what the
COMPRESS package enables.

3.5. Optional build settings 47

LAMMPS Documentation, Release stable 29Sep2021

3.5.6 Memory allocation alignment

This setting enables the use of the “posix_memalign()” call instead of “malloc()” when LAMMPS allocates large
chunks or memory. Vector instructions on CPUs may become more efficient, if dynamically allocated memory is
aligned on larger-than-default byte boundaries. On most current operating systems, the “malloc()” implementation
returns pointers that are aligned to 16-byte boundaries. Using SSE vector instructions efficiently, however, requires
memory blocks being aligned on 64-byte boundaries.

CMake build

-D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default)

Use a LAMMPS_MEMALIGN value of 0 to disable using “posix_memalign()” and revert to using the “mal-
loc()” C-library function instead. When compiling LAMMPS for Windows systems, “malloc()” will al-
ways be used and this setting is ignored.

Traditional make

LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64

Do not set -DLAMMPS_MEMALIGN, if you want to have memory allocated with the “malloc()” function call
instead. -DLAMMPS_MEMALIGN cannot be used on Windows, as Windows different function calls with
different semantics for allocating aligned memory, that are not compatible with how LAMMPS manages
its dynamical memory.

3.5.7 Workaround for long long integers

If your system or MPI version does not recognize “long long” data types, the following setting will be needed. It
converts “long long” to a “long” data type, which should be the desired 8-byte integer on those systems:

CMake build

-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default)

Traditional make

LMP_INC = -DLAMMPS_LONGLONG_TO_LONG

48 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.5.8 Exception handling when using LAMMPS as a library

This setting is useful when external codes drive LAMMPS as a library. With this option enabled, LAMMPS errors do
not kill the calling code. Instead, the call stack is unwound and control returns to the caller, e.g. to Python. Of course,
the calling code has to be set up to catch exceptions thrown from within LAMMPS.

CMake build

-D LAMMPS_EXCEPTIONS=value # yes or no (default)

Traditional make

LMP_INC = -DLAMMPS_EXCEPTIONS

Note: When LAMMPS is running in parallel, it is not always possible to cleanly recover from an exception since not
all parallel ranks may throw an exception and thus other MPI ranks may get stuck waiting for messages from the ones
with errors.

3.5.9 Trigger selected floating-point exceptions

Many kinds of CPUs have the capability to detect when a calculation results in an invalid math operation like a division
by zero or calling the square root with a negative argument. The default behavior on most operating systems is to
continue and have values for NaN (= not a number) or Inf (= infinity). This allows software to detect and recover from
such conditions. This behavior can be changed, however, often through use of compiler flags. On Linux systems (or
more general on systems using the GNU C library), these so-called floating-point traps can also be selectively enabled
through library calls. LAMMPS supports that by setting the -DLAMMPS_TRAP_FPE pre-processor define. As it is done
in the main() function, this applies only to the standalone executable, not the library.

CMake build

-D CMAKE_TUNE_FLAGS=-DLAMMPS_TRAP_FPE

Traditional make

LMP_INC = -DLAMMPS_TRAP_FPE

After compilation with this flag set, the LAMMPS executable will stop and produce a core dump when a division by
zero, overflow, illegal math function argument or other invalid floating point operation is encountered.

3.5. Optional build settings 49

LAMMPS Documentation, Release stable 29Sep2021

3.6 Include packages in build

In LAMMPS, a package is a group of files that enable a specific set of features. For example, force fields for molecular
systems or rigid-body constraints are in packages. In the src directory, each package is a sub-directory with the package
name in capital letters.
An overview of packages is given on the Packages doc page. Brief overviews of each package are on the Packages
details page.
When building LAMMPS, you can choose to include or exclude each package. In general there is no need to include
a package if you never plan to use its features.
If you get a run-time error that a LAMMPS command or style is “unknown”, it is often because the command is
contained in a package, and your build did not include that package. If the command or style is available in a package
included in the LAMMPS distribution, the error message will indicate which package would be needed. Running
LAMMPS with the -h command-line switch will print all optional commands and packages that were enabled when
building that executable.
For the majority of packages, if you follow the single step below to include it, you can then build LAMMPS exactly the
same as you would without any packages installed. A few packages may require additional steps, as explained on the
Build extras page.
These links take you to the extra instructions for those select packages:

ADIOS ATC AWPMD COLVARS COMPRESS GPU

H5MD INTEL KIM KOKKOS LATTE MACHDYN
MESSAGE ML-HDNNP ML-PACE ML-QUIP MOLFILE MSCG
NETCDF OPENMP OPT PLUMED POEMS PYTHON
QMMM SCAFACOS VORONOI VTK

The mechanism for including packages is simple but different for CMake versus make.

CMake build

-D PKG_NAME=value # yes or no (default)

Examples:

-D PKG_MANYBODY=yes
-D PKG_INTEL=yes

All packages are included the same way. See the shortcut section below for how to install many packages
at once with CMake.

Note: If you switch between building with CMake and make builds, no packages in the src directory can
be installed when you invoke cmake. CMake will give an error if that is not the case, indicating how you
can un-install all packages in the src dir.

Traditional make

50 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

cd lammps/src
make ps # check which packages are currently installed
make yes-name # install a package with name
make no-name # un-install a package with name
make mpi # build LAMMPS with whatever packages are now␣
,→installed

Examples:

make no-rigid
make yes-intel

All packages are included the same way. See the shortcut section below for how to install many packages
at once with make.

Note: You must always re-build LAMMPS (via make) after installing or un-installing a package, for the
action to take effect. The included dependency tracking will make certain only files that are required to be
rebuilt are recompiled.

Note: You cannot install or un-install packages and build LAMMPS in a single make command with
multiple targets, e.g. make yes-colloid mpi. This is because the make procedure creates a list of
source files that will be out-of-date for the build if the package configuration changes within the same com-
mand. You can include or exclude multiple packages in a single make command, e.g. make yes-colloid
no-manybody.

3.6.1 Information for both build systems

Almost all packages can be included or excluded in a LAMMPS build, independent of the other packages. However,
some packages include files derived from files in other packages. LAMMPS checks for this and does the right thing.
Individual files are only included if their dependencies are already included. Likewise, if a package is excluded, other
files dependent on that package are also excluded.

Note: By default no packages are installed. Prior to August 2018, however, if you downloaded a tarball, 3 packages
(KSPACE, MANYBODY, MOLECULE) were pre-installed via the traditional make procedure in the src directory.
That is no longer the case, so that CMake will build as-is without needing to un-install those packages.

3.6. Include packages in build 51

LAMMPS Documentation, Release stable 29Sep2021

CMake presets for installing many packages

Instead of specifying all the CMake options via the command-line, CMake allows initializing its settings cache using
script files. These are regular CMake files which can manipulate and set CMake variables (which represent selected
options), and can also contain control flow constructs for more complex operations.
LAMMPS includes several of these files to define configuration “presets”, similar to the options that exist for the Make
based system. Using these files you can enable/disable portions of the available packages in LAMMPS. If you need a
custom preset you can take one of them as a starting point and customize it to your needs.

cmake -C ../cmake/presets/basic.cmake [OPTIONS] ../cmake # enable just a few core␣

,→packages

cmake -C ../cmake/presets/most.cmake [OPTIONS] ../cmake # enable most packages

cmake -C ../cmake/presets/download.cmake [OPTIONS] ../cmake # enable packages which␣
,→download sources or potential files

cmake -C ../cmake/presets/nolib.cmake [OPTIONS] ../cmake # disable packages that do␣

,→require extra libraries or tools

cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake # change settings to use␣

,→the Clang compilers by default

cmake -C ../cmake/presets/gcc.cmake [OPTIONS] ../cmake # change settings to use␣

,→the GNU compilers by default

cmake -C ../cmake/presets/intel.cmake [OPTIONS] ../cmake # change settings to use␣

,→the Intel compilers by default

cmake -C ../cmake/presets/pgi.cmake [OPTIONS] ../cmake # change settings to use␣

,→the PGI compilers by default

cmake -C ../cmake/presets/all_on.cmake [OPTIONS] ../cmake # enable all packages

cmake -C ../cmake/presets/all_off.cmake [OPTIONS] ../cmake # disable all packages
mingw64-cmake -C ../cmake/presets/mingw-cross.cmake [OPTIONS] ../cmake # compile with␣
,→MinGW cross compilers

Note: Running cmake this way manipulates the CMake settings cache in your current build directory. You can combine
multiple presets and options in a single cmake run, or change settings incrementally by running cmake with new flags.
If you use a present for selecting a set of compilers, it will reset all settings from previous CMake runs.

Example

# build LAMMPS with most commonly used packages, but then remove
# those requiring additional library or tools, but still enable
# GPU package and configure it for using CUDA. You can run.
mkdir build
cd build
cmake -C ../cmake/presets/most.cmake -C ../cmake/presets/nolib.cmake -D PKG_GPU=on -D␣
,→GPU_API=cuda ../cmake

# to add another package, say BODY to the previous configuration you can run:
cmake -D PKG_BODY=on .

# to reset the package selection from above to the default of no packages

# but leaving all other settings untouched. You can run:
cmake -C ../cmake/presets/all_off.cmake .

52 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.6.2 Make shortcuts for installing many packages

The following commands are useful for managing package source files and their installation when building LAMMPS
via traditional make. Just type make in lammps/src to see a one-line summary.
These commands install/un-install sets of packages:

make yes-all # install all packages

make no-all # uninstall all packages
make yes-basic # install a few commonly used packages'
make no-basic # remove a few commonly used packages'
make yes-most # install most packages w/o libs'
make no-most # remove most packages w/o libs'
make yes-lib # install packages that require extra libraries
make no-lib # uninstall packages that require extra libraries
make yes-ext # install packages that require external libraries
make no-ext # uninstall packages that require external libraries

which install/un-install various sets of packages. Typing make package will list all the these commands.

Note: Installing or un-installing a package for the make based build process works by simply copying files back
and forth between the main source directory src and the sub-directories with the package name (e.g. src/KSPACE,
src/ATC), so that the files are included or excluded when LAMMPS is built. Only source files in the src folder will be
compiled.

The following make commands help manage files that exist in both the src directory and in package sub-directories.
You do not normally need to use these commands unless you are editing LAMMPS files or are updating LAMMPS via
git.
Type make package-status or make ps to show which packages are currently installed. For those that are installed,
it will list any files that are different in the src directory and package sub-directory.
Type make package-installed or make pi to show which packages are currently installed, without listing the status
of packages that are not installed.
Type make package-update or make pu to overwrite src files with files from the package sub-directories if the
package is installed. It should be used after the checkout has been updated or changed withy git, this will only update
the files in the package sub-directories, but not the copies in the src folder.
Type make package-overwrite to overwrite files in the package sub-directories with src files.
Type make package-diff to list all differences between pairs of files in both the source directory and the package
directory.

3.7 Packages with extra build options

When building with some packages, additional steps may be required, in addition to

CMake build Traditional make

$ cmake -D PKG_NAME=yes $ make yes-name

as described on the Build_package page.

3.7. Packages with extra build options 53

LAMMPS Documentation, Release stable 29Sep2021

For a CMake build there may be additional optional or required variables to set. For a build with make, a provided
library under the lammps/lib directory may need to be built first. Or an external library may need to exist on your
system or be downloaded and built. You may need to tell LAMMPS where it is found on your system.
This is the list of packages that may require additional steps.

ADIOS ATC AWPMD COLVARS COMPRESS GPU

H5MD INTEL KIM KOKKOS LATTE MACHDYN
MDI MESONT MESSAGE ML-HDNNP ML-IAP ML-PACE
ML-QUIP MOLFILE MSCG NETCDF OPENMP OPT
PLUMED POEMS PYTHON QMMM SCAFACOS VORONOI
VTK

3.7.1 COMPRESS package

To build with this package you must have the zlib compression library available on your system to build dump styles
with a ‘/gz’ suffix. There are also styles using the Zstandard library which have a ‘/zstd’ suffix. The zstd library version
must be at least 1.4. Older versions use an incompatible API and thus LAMMPS will fail to compile.

CMake build
If CMake cannot find the zlib library or include files, you can set these variables:

-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file

-D ZLIB_LIBRARY=path # path to libz.a (.so) file

Support for Zstandard compression is auto-detected and for that CMake depends on the pkg-config tool
to identify the necessary flags to compile with this library, so the corresponding libzstandard.pc file
must be in a folder where pkg-config can find it, which may require adding it to the PKG_CONFIG_PATH
environment variable.

Traditional make
To include support for Zstandard compression, -DLAMMPS_ZSTD must be added to the compiler flags. If
make cannot find the libraries, you can edit the file lib/compress/Makefile.lammps to specify the
paths and library names. This must be done before the package is installed.

3.7.2 GPU package

To build with this package, you must choose options for precision and which GPU hardware to build for. The GPU
package currently supports three different types of backends: OpenCL, CUDA and HIP.

54 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

CMake build

-D GPU_API=value # value = opencl (default) or cuda or hip

-D GPU_PREC=value # precision setting
# value = double or mixed (default) or single
-D GPU_ARCH=value # primary GPU hardware choice for GPU_API=cuda
# value = sm_XX, see below
# default is sm_50
-D HIP_ARCH=value # primary GPU hardware choice for GPU_API=hip
# value depends on selected HIP_PLATFORM
# default is 'gfx906' for HIP_PLATFORM=amd and 'sm_50' for HIP_
,→PLATFORM=nvcc

-D HIP_USE_DEVICE_SORT=value # enables GPU sorting

# value = yes (default) or no
-D CUDPP_OPT=value # use GPU binning on with CUDA (should be off for modern␣
,→GPUs)

# enables CUDA Performance Primitives, must be "no" for␣

,→CUDA_MPS_SUPPORT=yes

# value = yes or no (default)

-D CUDA_MPS_SUPPORT=value # enables some tweaks required to run with active nvidia-
,→cuda-mps daemon

# value = yes or no (default)

-D USE_STATIC_OPENCL_LOADER=value # downloads/includes OpenCL ICD loader library, no␣
,→local OpenCL headers/libs needed

# value = yes (default) or no

GPU_ARCH settings for different GPU hardware is as follows:

• sm_12 or sm_13 for GT200 (supported by CUDA 3.2 until CUDA 6.5)
• sm_20 or sm_21 for Fermi (supported by CUDA 3.2 until CUDA 7.5)
• sm_30 for Kepler (supported since CUDA 5 and until CUDA 10.x)
• sm_35 or sm_37 for Kepler (supported since CUDA 5 and until CUDA 11.x)
• sm_50 or sm_52 for Maxwell (supported since CUDA 6)
• sm_60 or sm_61 for Pascal (supported since CUDA 8)
• sm_70 for Volta (supported since CUDA 9)
• sm_75 for Turing (supported since CUDA 10)
• sm_80 for Ampere (supported since CUDA 11)
A more detailed list can be found, for example, at Wikipedia’s CUDA article
CMake can detect which version of the CUDA toolkit is used and thus will try to include support for all major GPU
architectures supported by this toolkit. Thus the GPU_ARCH setting is merely an optimization, to have code for the
preferred GPU architecture directly included rather than having to wait for the JIT compiler of the CUDA driver to
translate it.
When building with CMake, you must NOT build the GPU library in lib/gpu using the traditional build procedure.
CMake will detect files generated by that process and will terminate with an error and a suggestion for how to remove
them.
If you are compiling for OpenCL, the default setting is to download, build, and link with a static OpenCL ICD
loader library and standard OpenCL headers. This way no local OpenCL development headers or library needs to

3.7. Packages with extra build options 55

LAMMPS Documentation, Release stable 29Sep2021

be present and only OpenCL compatible drivers need to be installed to use OpenCL. If this is not desired, you can set
USE_STATIC_OPENCL_LOADER to no.
If you are compiling with HIP, note that before running CMake you will have to set appropriate environment variables.
Some variables such as HCC_AMDGPU_TARGET (for ROCm <= 4.0) or CUDA_PATH are necessary for hipcc and the
linker to work correctly.

# AMDGPU target (ROCm <= 4.0)

export HIP_PLATFORM=hcc
export HCC_AMDGPU_TARGET=gfx906
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4

# AMDGPU target (ROCm >= 4.1)

export HIP_PLATFORM=amd
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4

# CUDA target (not recommended, use GPU_ARCH=cuda)

# !!! DO NOT set CMAKE_CXX_COMPILER !!!
export HIP_PLATFORM=nvcc
export CUDA_PATH=/usr/local/cuda
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=sm_70 ..
make -j 4

Traditional make

Before building LAMMPS, you must build the GPU library in lib/gpu. You can do this manually if you prefer;
follow the instructions in lib/gpu/README. Note that the GPU library uses MPI calls, so you must use the same
MPI library (or the STUBS library) settings as the main LAMMPS code. This also applies to the -DLAMMPS_BIGBIG,
-DLAMMPS_SMALLBIG, or -DLAMMPS_SMALLSMALL settings in whichever Makefile you use.
You can also build the library in one step from the lammps/src dir, using a command like these, which simply invoke
the lib/gpu/Install.py script with the specified args:

$ make lib-gpu # print help message

$ make lib-gpu args="-b" # build GPU library with default Makefile.linux
$ make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single,␣
,→altered for single-precision

$ make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed␣
,→precision and P100 using other settings in Makefile.mpi

Note that this procedure starts with a Makefile.machine in lib/gpu, as specified by the “-m” switch. For your conve-
nience, machine makefiles for “mpi” and “serial” are provided, which have the same settings as the corresponding
machine makefiles in the main LAMMPS source folder. In addition you can alter 4 important settings in the Make-
file.machine you start from via the corresponding -c, -a, -p, -e switches (as in the examples above), and also save a copy
of the new Makefile if desired:
• CUDA_HOME = where NVIDIA CUDA software is installed on your system
• CUDA_ARCH = sm_XX, what GPU hardware you have, same as CMake GPU_ARCH above
• CUDA_PRECISION = precision (double, mixed, single)
• EXTRAMAKE = which Makefile.lammps.* file to copy to Makefile.lammps

56 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

The file Makefile.cuda is set up to include support for multiple GPU architectures as supported by the CUDA toolkit
in use. This is done through using the “–gencode ” flag, which can be used multiple times and thus support all GPU
architectures supported by your CUDA compiler.
To enable GPU binning via CUDA performance primitives set the Makefile variable CUDPP_OPT = -DUSE_CUDPP
-Icudpp_mini. This should not be used with most modern GPUs.
To support the CUDA multiprocessor server you can set the define -DCUDA_PROXY. Please note that in this case you
must not use the CUDA performance primitives and thus set the variable CUDPP_OPT to empty.
If the library build is successful, 3 files should be created: lib/gpu/libgpu.a, lib/gpu/nvc_get_devices, and
lib/gpu/Makefile.lammps. The latter has settings that enable LAMMPS to link with CUDA libraries. If the set-
tings in Makefile.lammps for your machine are not correct, the LAMMPS build will fail, and lib/gpu/Makefile.
lammps may need to be edited.

Note: If you re-build the GPU library in lib/gpu, you should always un-install the GPU package in lammps/src,
then re-install it and re-build LAMMPS. This is because the compilation of files in the GPU package uses the library
settings from the lib/gpu/Makefile.machine used to build the GPU library.

3.7.3 KIM package

To build with this package, the KIM library with API v2 must be downloaded and built on your system. It must include
the KIM models that you want to use with LAMMPS.
If you would like to use the kim query command, you also need to have libcurl installed with the matching development
headers and the curl-config tool.
If you would like to use the kim property command, you need to build LAMMPS with the PYTHON package installed
and linked to Python 3.6 or later. See the PYTHON package build info for more details on this. After successfully
building LAMMPS with Python, you also need to install the kim-property Python package, which can be easily done
using pip as pip install kim-property, or from the conda-forge channel as conda install kim-property if
LAMMPS is built in Conda. More detailed information is available at: kim-property installation.
In addition to installing the KIM API, it is also necessary to install the library of KIM models (interatomic potentials).
See Obtaining KIM Models to learn how to install a pre-build binary of the OpenKIM Repository of Models. See the
list of all KIM models here: https://openkim.org/browse/models
(Also note that when downloading and installing from source the KIM API library with all its models, may take a long
time (tens of minutes to hours) to build. Of course you only need to do that once.)

CMake build

-D DOWNLOAD_KIM=value # download OpenKIM API v2 for build, value =␣

,→no (default) or yes

-D LMP_DEBUG_CURL=value # set libcurl verbose mode on/off, value = off␣

,→(default) or on

-D LMP_NO_SSL_CHECK=value # tell libcurl to not verify the peer, value =␣

,→no (default) or yes

-D KIM_EXTRA_UNITTESTS=value # enables extra unit tests, value = no␣

,→(default) or yes

If DOWNLOAD_KIM is set to yes (or on), the KIM API library will be downloaded and built inside the CMake
build directory. If the KIM library is already installed on your system (in a location where CMake cannot

3.7. Packages with extra build options 57

LAMMPS Documentation, Release stable 29Sep2021

find it), you may need to set the PKG_CONFIG_PATH environment variable so that libkim-api can be found,
or run the command source kim-api-activate.
Extra unit tests can only be available if they are explicitly requested (KIM_EXTRA_UNITTESTS is set to yes
(or on)) and the prerequisites are met. See KIM Extra unit tests for more details on this.

Traditional make
You can download and build the KIM library manually if you prefer; follow the instructions in lib/kim/
README. You can also do this in one step from the lammps/src directory, using a command like these,
which simply invoke the lib/kim/Install.py script with the specified args.

$ make lib-kim # print help message

$ make lib-kim args="-b " # (re-)install KIM API lib with only example models
$ make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" #␣
,→ditto plus one model

$ make lib-kim args="-b -a everything" # install KIM API lib with all␣
,→models

$ make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" #␣

,→add one model or model driver

$ make lib-kim args="-p /usr/local" # use an existing KIM API installation at␣
,→the provided location

$ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002

,→" # ditto but add one model or driver

Settings for debugging OpenKIM web queries discussed below need to be applied by adding them to the
LMP_INC variable through editing the Makefile.machine you are using. For example:

LMP_INC = -DLMP_NO_SSL_CHECK

Debugging OpenKIM web queries in LAMMPS

If LMP_DEBUG_CURL is set, the libcurl verbose mode will be turned on, and any libcurl calls within the KIM web query
display a lot of information about libcurl operations. You hardly ever want this set in production use, you will almost
always want this when you debug or report problems.
The libcurl library performs peer SSL certificate verification by default. This verification is done using a CA cer-
tificate store that the SSL library can use to make sure the peer’s server certificate is valid. If SSL reports an error
(“certificate verify failed”) during the handshake and thus refuses further communicate with that server, you can set
LMP_NO_SSL_CHECK to override that behavior. When LAMMPS is compiled with LMP_NO_SSL_CHECK set, libcurl does
not verify the peer and connection attempts will succeed regardless of the names in the certificate. This option is inse-
cure. As an alternative, you can specify your own CA cert path by setting the environment variable CURL_CA_BUNDLE
to the path of your choice. A call to the KIM web query would get this value from the environment variable.

58 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

KIM Extra unit tests (CMake only)

During development, testing, or debugging, if unit testing is enabled in LAMMPS, one can also enable extra tests on
KIM commands by setting the KIM_EXTRA_UNITTESTS to yes (or on).
Enabling the extra unit tests have some requirements,
• It requires to have internet access.
• It requires to have libcurl installed with the matching development headers and the curl-config tool.
• It requires to build LAMMPS with the PYTHON package installed and linked to Python 3.6 or later. See the
PYTHON package build info for more details on this.
• It requires to have kim-property Python package installed, which can be easily done using pip as pip install
kim-property, or from the conda-forge channel as conda install kim-property if LAMMPS is built in
Conda. More detailed information is available at: kim-property installation.
• It is also necessary to install EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000,
EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005, and LennardJones612_UniversalShifted__MO_9592
KIM models. See Obtaining KIM Models to learn how to install a pre-built binary of the OpenKIM Repository
of Models or see Installing KIM Models to learn how to install the specific KIM models.

3.7.4 KOKKOS package

Using the KOKKOS package requires choosing several settings. You have to select whether you want to compile with
parallelization on the host and whether you want to include offloading of calculations to a device (e.g. a GPU). The
default setting is to have no host parallelization and no device offloading. In addition, you can select the hardware
architecture to select the instruction set. Since most hardware is backward compatible, you may choose settings for an
older architecture to have an executable that will run on this and newer architectures.

Note: If you run Kokkos on a different GPU architecture than what LAMMPS was compiled with, there will be a
delay during device initialization while the just-in-time compiler is recompiling all GPU kernels for the new hardware.
This is, however, only supported for GPUs of the same major hardware version and different minor hardware versions,
e.g. 5.0 and 5.2 but not 5.2 and 6.0. LAMMPS will abort with an error message indicating a mismatch, if that happens.

The settings discussed below have been tested with LAMMPS and are confirmed to work. Kokkos is an active project
with ongoing improvements and projects working on including support for additional architectures. More information
on Kokkos can be found on the Kokkos GitHub project.

Available Architecture settings

These are the possible choices for the Kokkos architecture ID. They must be specified in uppercase.

Arch-ID HOST or GPU Description

AMDAVX HOST AMD 64-bit x86 CPU (AVX 1)
ZEN HOST AMD Zen class CPU (AVX 2)
ZEN2 HOST AMD Zen2 class CPU (AVX 2)
ZEN3 HOST AMD Zen3 class CPU (AVX 2)
ARMV80 HOST ARMv8.0 Compatible CPU
ARMV81 HOST ARMv8.1 Compatible CPU
continues on next page

3.7. Packages with extra build options 59

LAMMPS Documentation, Release stable 29Sep2021

Table 1 – continued from previous page

ARMV8_THUNDERX HOST ARMv8 Cavium ThunderX CPU
ARMV8_THUNDERX2 HOST ARMv8 Cavium ThunderX2 CPU
A64FX HOST ARMv8.2 with SVE Support
WSM HOST Intel Westmere CPU (SSE 4.2)
SNB HOST Intel Sandy/Ivy Bridge CPU (AVX 1)
HSW HOST Intel Haswell CPU (AVX 2)
BDW HOST Intel Broadwell Xeon E-class CPU (AVX 2 + transactional mem)
SKX HOST Intel Sky Lake Xeon E-class HPC CPU (AVX512 + transactional mem)
KNC HOST Intel Knights Corner Xeon Phi
KNL HOST Intel Knights Landing Xeon Phi
BGQ HOST IBM Blue Gene/Q CPU
POWER7 HOST IBM POWER7 CPU
POWER8 HOST IBM POWER8 CPU
POWER9 HOST IBM POWER9 CPU
KEPLER30 GPU NVIDIA Kepler generation CC 3.0 GPU
KEPLER32 GPU NVIDIA Kepler generation CC 3.2 GPU
KEPLER35 GPU NVIDIA Kepler generation CC 3.5 GPU
KEPLER37 GPU NVIDIA Kepler generation CC 3.7 GPU
MAXWELL50 GPU NVIDIA Maxwell generation CC 5.0 GPU
MAXWELL52 GPU NVIDIA Maxwell generation CC 5.2 GPU
MAXWELL53 GPU NVIDIA Maxwell generation CC 5.3 GPU
PASCAL60 GPU NVIDIA Pascal generation CC 6.0 GPU
PASCAL61 GPU NVIDIA Pascal generation CC 6.1 GPU
VOLTA70 GPU NVIDIA Volta generation CC 7.0 GPU
VOLTA72 GPU NVIDIA Volta generation CC 7.2 GPU
TURING75 GPU NVIDIA Turing generation CC 7.5 GPU
AMPERE80 GPU NVIDIA Ampere generation CC 8.0 GPU
AMPERE86 GPU NVIDIA Ampere generation CC 8.6 GPU
VEGA900 GPU AMD GPU MI25 GFX900
VEGA906 GPU AMD GPU MI50/MI60 GFX906
VEGA908 GPU AMD GPU MI100 GFX908
INTEL_GEN GPU Intel GPUs Gen9+

This list was last updated for version 3.4.1 of the Kokkos library.

Basic CMake build settings:

For multicore CPUs using OpenMP, set these 2 variables.

-D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above

-D Kokkos_ENABLE_OPENMP=yes
-D BUILD_OMP=yes

Please note that enabling OpenMP for KOKKOS requires that OpenMP is also enabled for the rest of
LAMMPS.
For Intel KNLs using OpenMP, set these variables:

-D Kokkos_ARCH_KNL=yes
-D Kokkos_ENABLE_OPENMP=yes

For NVIDIA GPUs using CUDA, set these variables:

60 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

-D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above

-D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above
-D Kokkos_ENABLE_CUDA=yes
-D Kokkos_ENABLE_OPENMP=yes
-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper

This will also enable executing FFTs on the GPU, either via the internal KISSFFT library, or - by preference
- with the cuFFT library bundled with the CUDA toolkit, depending on whether CMake can identify its
location. The wrapper value for CMAKE_CXX_COMPILER variable is the path to the CUDA nvcc compiler
wrapper provided in the Kokkos library: lib/kokkos/bin/nvcc_wrapper. The setting should include
the full path name to the wrapper, e.g.

-D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper

To simplify compilation, three preset files are included in the cmake/presets folder, kokkos-serial.
cmake, kokkos-openmp.cmake, and kokkos-cuda.cmake. They will enable the KOKKOS package and
enable some hardware choice. So to compile with OpenMP host parallelization, CUDA device paralleliza-
tion (for GPUs with CC 5.0 and up) with some common packages enabled, you can do the following:

mkdir build-kokkos-cuda
cd build-kokkos-cuda
cmake -C ../cmake/presets/basic.cmake -C ../cmake/presets/kokkos-cuda.cmake ../
,→cmake

cmake --build .

Basic traditional make settings:

Choose which hardware to support in Makefile.machine via KOKKOS_DEVICES and KOKKOS_ARCH set-
tings. See the src/MAKE/OPTIONS/Makefile.kokkos* files for examples.
For multicore CPUs using OpenMP:

KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = HOSTARCH # HOSTARCH = HOST from list above

For Intel KNLs using OpenMP:

KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNL

For NVIDIA GPUs using CUDA:

KOKKOS_DEVICES = Cuda
KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is␣
,→hosting the GPU

KOKKOS_CUDA_OPTIONS = "enable_lambda"
# GPUARCH = GPU from list above
FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional)
FFT_LIB = -lcufft # link to cuFFT library

For GPUs, you also need the following lines in your Makefile.machine before the CC line is defined.
They tell mpicxx to use an nvcc compiler wrapper, which will use nvcc for compiling CUDA files and a
C++ compiler for non-Kokkos, non-CUDA files.

3.7. Packages with extra build options 61

LAMMPS Documentation, Release stable 29Sep2021

# For OpenMPI
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
CC = mpicxx

# For MPICH and derivatives

KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
CC = mpicxx -cxx=$(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper

Advanced KOKKOS compilation settings

There are other allowed options when building with the KOKKOS package that can improve performance or assist in
debugging or profiling. Below are some examples that may be useful in combination with LAMMPS. For the full list
(which keeps changing as the Kokkos package itself evolves), please consult the Kokkos library documentation.
As alternative to using multi-threading via OpenMP (-DKokkos_ENABLE_OPENMP=on or KOKKOS_DEVICES=OpenMP)
it is also possible to use Posix threads directly (-DKokkos_ENABLE_PTHREAD=on or KOKKOS_DEVICES=Pthread).
While binding of threads to individual or groups of CPU cores is managed in OpenMP with environment variables,
you need assistance from either the “hwloc” or “libnuma” library for the Pthread thread parallelization option. To
enable use with CMake: -DKokkos_ENABLE_HWLOC=on or -DKokkos_ENABLE_LIBNUMA=on; and with conventional
make: KOKKOS_USE_TPLS=hwloc or KOKKOS_USE_TPLS=libnuma.
The CMake option -DKokkos_ENABLE_LIBRT=on or the makefile setting KOKKOS_USE_TPLS=librt enables the use
of a more accurate timer mechanism on many Unix-like platforms for internal profiling.
The CMake option -DKokkos_ENABLE_DEBUG=on or the makefile setting KOKKOS_DEBUG=yes enables printing of run-
time debugging information that can be useful. It also enables runtime bounds checking on Kokkos data structures.
As to be expected, enabling this option will negatively impact the performance and thus is only recommended when
developing a Kokkos-enabled style in LAMMPS.
The CMake option -DKokkos_ENABLE_CUDA_UVM=on or the makefile setting
KOKKOS_CUDA_OPTIONS=enable_lambda,force_uvm enables the use of CUDA “Unified Virtual Memory”
(UVM) in Kokkos. UVM allows to transparently use RAM on the host to supplement the memory used on the GPU
(with some performance penalty) and thus enables running larger problems that would otherwise not fit into the RAM
on the GPU.
Please note, that the LAMMPS KOKKOS package must always be compiled with the enable_lambda option when
using GPUs. The CMake configuration will thus always enable it.

3.7.5 LATTE package

To build with this package, you must download and build the LATTE library.

CMake build

-D DOWNLOAD_LATTE=value # download LATTE for build, value = no (default) or␣

,→yes

-D LATTE_LIBRARY=path # LATTE library file (only needed if a custom␣

,→location)

62 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

If DOWNLOAD_LATTE is set, the LATTE library will be downloaded and built inside the CMake build direc-
tory. If the LATTE library is already on your system (in a location CMake cannot find it), LATTE_LIBRARY
is the filename (plus path) of the LATTE library file, not the directory the library file is in.

Traditional make
You can download and build the LATTE library manually if you prefer; follow the instructions in lib/
latte/README. You can also do it in one step from the lammps/src dir, using a command like these,
which simply invokes the lib/latte/Install.py script with the specified args:

$ make lib-latte # print help message

$ make lib-latte args="-b" # download and build in lib/latte/
,→LATTE-master

$ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in

,→$HOME/latte

$ make lib-latte args="-b -m gfortran" # download and build in lib/latte and

# copy Makefile.lammps.gfortran to␣
,→Makefile.lammps

Note that 3 symbolic (soft) links, includelink and liblink and filelink.o, are created in lib/latte
to point to required folders and files in the LATTE home directory. When LAMMPS itself is built it will
use these links. You should also check that the Makefile.lammps file you create is appropriate for the
compiler you use on your system to build LATTE.

3.7.6 MESSAGE package

This package can optionally include support for messaging via sockets, using the open-source ZeroMQ library, which
must be installed on your system.

CMake build

-D MESSAGE_ZMQ=value # build with ZeroMQ support, value = no (default) or␣

,→yes

-D ZMQ_LIBRARY=path # ZMQ library file (only needed if a custom location)

-D ZMQ_INCLUDE_DIR=path # ZMQ include directory (only needed if a custom␣
,→location)

Traditional make
Before building LAMMPS, you must build the CSlib library in lib/message. You can build the CSlib
library manually if you prefer; follow the instructions in lib/message/README. You can also do it in
one step from the lammps/src dir, using a command like these, which simply invoke the lib/message/
Install.py script with the specified args:

$ make lib-message # print help message

$ make lib-message args="-m -z" # build with MPI and socket (ZMQ) support
$ make lib-message args="-s" # build as serial lib with no ZMQ support

3.7. Packages with extra build options 63

LAMMPS Documentation, Release stable 29Sep2021

The build should produce two files: lib/message/cslib/src/libmessage.a and lib/message/

Makefile.lammps. The latter is copied from an existing Makefile.lammps.* and has settings to link
with the ZeroMQ library if requested in the build.

3.7.7 ML-IAP package

Building the ML-IAP package requires including the ML-SNAP package. There will be an error message if this re-
quirement is not satisfied. Using the mliappy model also requires enabling Python support, which in turn requires to
include the PYTHON package and requires to have the cython software installed and with it a working cythonize
command. This feature requires compiling LAMMPS with Python version 3.6 or later.

CMake build
-D MLIAP_ENABLE_PYTHON=value # enable mliappy model (default is autodetect)

Without this setting, CMake will check whether it can find a suitable Python version and the cythonize
command and choose the default accordingly. During the build procedure the provided .pyx file(s) will
be automatically translated to C++ code and compiled. Please do not run cythonize manually in the
src/ML-IAP folder, as that can lead to compilation errors if Python support is not enabled. If you did it
by accident, please remove the generated .cpp and .h files.

Traditional make
The build uses the lib/python/Makefile.mliap_python file in the compile/link process to add a rule
to update the files generated by the cythonize command in case the corresponding .pyx file(s) were
modified. You may need to modify lib/python/Makefile.lammps if the LAMMPS build fails.
To enable building the ML-IAP package with Python support enabled, you need to add -DMLIAP_PYTHON
to the LMP_INC variable in your machine makefile. You may have to manually run the cythonize com-
mand on .pyx file(s) in the src folder, if this is not automatically done during installing the ML-IAP
package. Please do not run cythonize in the src/ML-IAP folder, as that can lead to compilation errors
if Python support is not enabled. If you did this by accident, please remove the generated .cpp and .h files.

3.7.8 MSCG package

To build with this package, you must download and build the MS-CG library. Building the MS-CG library requires that
the GSL (GNU Scientific Library) headers and libraries are installed on your machine. See the lib/mscg/README
and MSCG/Install files for more details.

CMake build
-D DOWNLOAD_MSCG=value # download MSCG for build, value = no (default) or␣
,→yes

-D MSCG_LIBRARY=path # MSCG library file (only needed if a custom␣

,→location)

-D MSCG_INCLUDE_DIR=path # MSCG include directory (only needed if a custom␣

,→location)
(continues on next page)

64 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

If DOWNLOAD_MSCG is set, the MSCG library will be downloaded and built inside the CMake build
directory. If the MSCG library is already on your system (in a location CMake cannot find it),
MSCG_LIBRARY is the filename (plus path) of the MSCG library file, not the directory the library file
is in. MSCG_INCLUDE_DIR is the directory the MSCG include file is in.

Traditional make
You can download and build the MS-CG library manually if you prefer; follow the instructions in lib/
mscg/README. You can also do it in one step from the lammps/src dir, using a command like these, which
simply invoke the lib/mscg/Install.py script with the specified args:

$ make lib-mscg # print help message

$ make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-
,→release-master

# with the settings compatible with

,→"make serial"

$ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-

,→release-master

# with the settings compatible with

,→"make mpi"

$ make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG␣

,→installation in /usr/local/mscg-release

Note that 2 symbolic (soft) links, includelink and liblink, will be created in lib/mscg to point to
the MS-CG src/installation dir. When LAMMPS is built in src it will use these links. You should
not need to edit the lib/mscg/Makefile.lammps file.

3.7.9 OPT package

CMake build
No additional settings are needed besides -D PKG_OPT=yes

Traditional make
The compiler flag -restrict must be used to build LAMMPS with the OPT package when using In-
tel compilers. It should be added to the CCFLAGS line of your Makefile.machine. See src/MAKE/
OPTIONS/Makefile.opt for an example.

3.7. Packages with extra build options 65

LAMMPS Documentation, Release stable 29Sep2021

3.7.10 POEMS package

CMake build
No additional settings are needed besides -D PKG_OPT=yes

Traditional make
Before building LAMMPS, you must build the POEMS library in lib/poems. You can do this manually if
you prefer; follow the instructions in lib/poems/README. You can also do it in one step from the lammps/
src dir, using a command like these, which simply invoke the lib/poems/Install.py script with the
specified args:

$ make lib-poems # print help message

$ make lib-poems args="-m serial" # build with GNU g++ compiler (settings as␣
,→with "make serial")

$ make lib-poems args="-m mpi" # build with default MPI C++ compiler␣
,→(settings as with "make mpi")
$ make lib-poems args="-m icc" # build with Intel icc compiler

The build should produce two files: lib/poems/libpoems.a and lib/poems/Makefile.lammps. The
latter is copied from an existing Makefile.lammps.* and has settings needed to build LAMMPS with the
POEMS library (though typically the settings are just blank). If necessary, you can edit/create a new lib/
poems/Makefile.machine file for your system, which should define an EXTRAMAKE variable to specify
a corresponding Makefile.lammps.machine file.

3.7.11 PYTHON package

Building with the PYTHON package requires you have a the Python development headers and library available on your
system, which needs to be a Python 2.7 version or a Python 3.x version. Since support for Python 2.x has ended, using
Python 3.x is strongly recommended. See lib/python/README for additional details.

CMake build

-D PYTHON_EXECUTABLE=path # path to Python executable to use

Without this setting, CMake will guess the default Python version on your system. To use a different
Python version, you can either create a virtualenv, activate it and then run cmake. Or you can set the
PYTHON_EXECUTABLE variable to specify which Python interpreter should be used. Note note that
you will also need to have the development headers installed for this version, e.g. python2-devel.

Traditional make
The build uses the lib/python/Makefile.lammps file in the compile/link process to find Python. You
should only need to create a new Makefile.lammps.* file (and copy it to Makefile.lammps) if the
LAMMPS build fails.

66 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.7.12 VORONOI package

To build with this package, you must download and build the Voro++ library or install a binary package provided by
your operating system.

CMake build

-D DOWNLOAD_VORO=value # download Voro++ for build, value = no (default) or␣

,→yes

-D VORO_LIBRARY=path # Voro++ library file (only needed if at custom␣

,→location)

-D VORO_INCLUDE_DIR=path # Voro++ include directory (only needed if at custom␣

,→location)

If DOWNLOAD_VORO is set, the Voro++ library will be downloaded and built inside the CMake build
directory. If the Voro++ library is already on your system (in a location CMake cannot find it),
VORO_LIBRARY is the filename (plus path) of the Voro++ library file, not the directory the library file
is in. VORO_INCLUDE_DIR is the directory the Voro++ include file is in.

Traditional make
You can download and build the Voro++ library manually if you prefer; follow the instructions in lib/
voronoi/README. You can also do it in one step from the lammps/src dir, using a command like these,
which simply invoke the lib/voronoi/Install.py script with the specified args:

$ make lib-voronoi # print help message

$ make lib-voronoi args="-b" # download and build the default␣
,→version in lib/voronoi/voro++-<version>

$ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation␣

,→in $HOME/voro++

$ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6␣

,→version in lib/voronoi/voro++-0.4.6

Note that 2 symbolic (soft) links, includelink and liblink, are created in lib/voronoi to point to the
Voro++ source dir. When LAMMPS builds in src it will use these links. You should not need to edit the
lib/voronoi/Makefile.lammps file.

3.7.13 ADIOS package

The ADIOS package requires the ADIOS I/O library, version 2.3.1 or newer. Make sure that you have ADIOS built
either with or without MPI to match if you build LAMMPS with or without MPI. ADIOS compilation settings for
LAMMPS are automatically detected, if the PATH and LD_LIBRARY_PATH environment variables have been up-
dated for the local ADIOS installation and the instructions below are followed for the respective build systems.

CMake build

-D ADIOS2_DIR=path # path is where ADIOS 2.x is installed

-D PKG_ADIOS=yes

3.7. Packages with extra build options 67

LAMMPS Documentation, Release stable 29Sep2021

Traditional make
Turn on the ADIOS package before building LAMMPS. If the ADIOS 2.x software is installed in PATH,
there is nothing else to do:

$ make yes-adios

otherwise, set ADIOS2_DIR environment variable when turning on the package:

$ ADIOS2_DIR=path make yes-adios # path is where ADIOS 2.x is installed

3.7.14 ATC package

The ATC package requires the MANYBODY package also be installed.

CMake build
No additional settings are needed besides -D PKG_ATC=yes and -D PKG_MANYBODY=yes.

Traditional make
Before building LAMMPS, you must build the ATC library in lib/atc. You can do this manually if you
prefer; follow the instructions in lib/atc/README. You can also do it in one step from the lammps/src
dir, using a command like these, which simply invoke the lib/atc/Install.py script with the specified
args:

$ make lib-atc # print help message

$ make lib-atc args="-m serial" # build with GNU g++ compiler and MPI␣
,→STUBS (settings as with "make serial")

$ make lib-atc args="-m mpi" # build with default MPI compiler␣

,→(settings as with "make mpi")

$ make lib-atc args="-m icc" # build with Intel icc compiler

The build should produce two files: lib/atc/libatc.a and lib/atc/Makefile.lammps. The latter is
copied from an existing Makefile.lammps.* and has settings needed to build LAMMPS with the ATC
library. If necessary, you can edit/create a new lib/atc/Makefile.machine file for your system, which
should define an EXTRAMAKE variable to specify a corresponding Makefile.lammps.<machine> file.
Note that the Makefile.lammps file has settings for the BLAS and LAPACK linear algebra libraries. As
explained in lib/atc/README these can either exist on your system, or you can use the files provided in
lib/linalg. In the latter case you also need to build the library in lib/linalg with a command like
these:

$ make lib-linalg # print help message

$ make lib-linalg args="-m serial" # build with GNU Fortran compiler␣
,→(settings as with "make serial")

(continues on next page)

68 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

$ make lib-linalg args="-m mpi" # build with default MPI Fortran␣
,→compiler (settings as with "make mpi")

$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler

3.7.15 AWPMD package

CMake build
No additional settings are needed besides -D PKG_AQPMD=yes.

Traditional make
Before building LAMMPS, you must build the AWPMD library in lib/awpmd. You can do this manually
if you prefer; follow the instructions in lib/awpmd/README. You can also do it in one step from the
lammps/src dir, using a command like these, which simply invoke the lib/awpmd/Install.py script
with the specified args:

$ make lib-awpmd # print help message

$ make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS␣
,→(settings as with "make serial")
$ make lib-awpmd args="-m mpi" # build with default MPI compiler (settings␣
,→as with "make mpi")

$ make lib-awpmd args="-m icc" # build with Intel icc compiler

The build should produce two files: lib/awpmd/libawpmd.a and lib/awpmd/Makefile.lammps. The
latter is copied from an existing Makefile.lammps.* and has settings needed to build LAMMPS with
the AWPMD library. If necessary, you can edit/create a new lib/awpmd/Makefile.machine file for
your system, which should define an EXTRAMAKE variable to specify a corresponding Makefile.lammps.
<machine> file.
Note that the Makefile.lammps file has settings for the BLAS and LAPACK linear algebra libraries. As
explained in lib/awpmd/README these can either exist on your system, or you can use the files provided
in lib/linalg. In the latter case you also need to build the library in lib/linalg with a command like
these:

$ make lib-linalg # print help message

$ make lib-linalg args="-m serial" # build with GNU Fortran compiler␣
,→(settings as with "make serial")

$ make lib-linalg args="-m mpi" # build with default MPI Fortran␣

,→compiler (settings as with "make mpi")

$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler

3.7. Packages with extra build options 69

LAMMPS Documentation, Release stable 29Sep2021

3.7.16 COLVARS package

This package includes the Colvars library into the LAMMPS distribution, which can be built for the most part with all
major versions of the C++ language.

CMake build
This is the recommended build procedure for using Colvars in LAMMPS. No additional settings are nor-
mally needed besides -D PKG_COLVARS=yes.

Traditional make
Before building LAMMPS, one must build the Colvars library in lib/colvars.
This can be done manually in the same folder by using or adapting one of the provided Makefiles: for
example, Makefile.g++ for the GNU C++ compiler. C++11 compatibility may need to be enabled for
some older compilers (as is done in the example makefile).
In general, it is safer to use build setting consistent with the rest of LAMMPS. This is best carried out
from the LAMMPS src directory using a command like these, which simply invoke the lib/colvars/
Install.py script with the specified args:

$ make lib-colvars # print help message

$ make lib-colvars args="-m serial" # build with GNU g++ compiler␣
,→(settings as with "make serial")

$ make lib-colvars args="-m mpi" # build with default MPI compiler␣

,→(settings as with "make mpi")

$ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and␣
,→colvars debugging enabled

The “machine” argument of the “-m” flag is used to find a Makefile.machine to use as build recipe. If it
does not already exist in lib/colvars, it will be auto-generated by using compiler flags consistent with
those parsed from the core LAMMPS makefiles.
Optional flags may be specified as environment variables:

$ COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug␣

,→code (much slower)

$ COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton␣

,→(included otherwise)

The build should produce two files: the library lib/colvars/libcolvars.a (which also includes Lep-
ton objects if enabled) and the specification file lib/colvars/Makefile.lammps. The latter is auto-
generated, and normally does not need to be edited.

70 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.7.17 ML-PACE package

This package requires a library that can be downloaded and built in lib/pace or somewhere else, which must be done
before building LAMMPS with this package. The code for the library can be found at: https://github.com/ICAMS/
lammps-user-pace/

CMake build
By default the library will be downloaded from the git repository and built automatically when the ML-
PACE package is enabled with -D PKG_ML-PACE=yes. The location for the sources may be customized by
setting the variable PACELIB_URL when configuring with CMake (e.g. to use a local archive on machines
without internet access). Since CMake checks the validity of the archive with md5sum you may also need
to set PACELIB_MD5 if you provide a different library version than what is downloaded automatically.

Traditional make
You can download and build the ML-PACE library in one step from the lammps/src dir, using these
commands, which invoke the lib/pace/Install.py script.

$ make lib-pace # print help message

$ make lib-pace args="-b" # download and build the default␣
,→version in lib/pace

You should not need to edit the lib/pace/Makefile.lammps file.

3.7.18 PLUMED package

Before building LAMMPS with this package, you must first build PLUMED. PLUMED can be built as part of the
LAMMPS build or installed separately from LAMMPS using the generic PLUMED installation instructions. The
PLUMED package has been tested to work with Plumed versions 2.4.x, 2.5.x, and 2.6.x and will error out, when trying
to run calculations with a different version of the Plumed kernel.
PLUMED can be linked into MD codes in three different modes: static, shared, and runtime. With the “static” mode,
all the code that PLUMED requires is linked statically into LAMMPS. LAMMPS is then fully independent from the
PLUMED installation, but you have to rebuild/relink it in order to update the PLUMED code inside it. With the
“shared” linkage mode, LAMMPS is linked to a shared library that contains the PLUMED code. This library should
preferably be installed in a globally accessible location. When PLUMED is linked in this way the same library can be
used by multiple MD packages. Furthermore, the PLUMED library LAMMPS uses can be updated without the need
for a recompile of LAMMPS for as long as the shared PLUMED library is ABI-compatible.
The third linkage mode is “runtime” which allows the user to specify which PLUMED kernel should be used at runtime
by using the PLUMED_KERNEL environment variable. This variable should point to the location of the libplumed-
Kernel.so dynamical shared object, which is then loaded at runtime. This mode of linking is particularly convenient for
doing PLUMED development and comparing multiple PLUMED versions as these sorts of comparisons can be done
without recompiling the hosting MD code. All three linkage modes are supported by LAMMPS on selected operating
systems (e.g. Linux) and using either CMake or traditional make build. The “static” mode should be the most portable,
while the “runtime” mode support in LAMMPS makes the most assumptions about operating system and compiler
environment. If one mode does not work, try a different one, switch to a different build system, consider a global
PLUMED installation or consider downloading PLUMED during the LAMMPS build.

3.7. Packages with extra build options 71

LAMMPS Documentation, Release stable 29Sep2021

CMake build
When the -D PKG_PLUMED=yes flag is included in the cmake command you must ensure that GSL is
installed in locations that are specified in your environment. There are then two additional variables that
control the manner in which PLUMED is obtained and linked into LAMMPS.

-D DOWNLOAD_PLUMED=value # download PLUMED for build, value = no (default)␣

,→or yes

-D PLUMED_MODE=value # Linkage mode for PLUMED, value = static (default),

,→ shared, or runtime

If DOWNLOAD_PLUMED is set to “yes”, the PLUMED library will be downloaded (the version of
PLUMED that will be downloaded is hard-coded to a vetted version of PLUMED, usually a recent stable re-
lease version) and built inside the CMake build directory. If DOWNLOAD_PLUMED is set to “no” (the default),
CMake will try to detect and link to an installed version of PLUMED. For this to work, the PLUMED li-
brary has to be installed into a location where the pkg-config tool can find it or the PKG_CONFIG_PATH
environment variable has to be set up accordingly. PLUMED should be installed in such a location if you
compile it using the default make; make install commands.
The PLUMED_MODE setting determines the linkage mode for the PLUMED library. The allowed values for
this flag are “static” (default), “shared”, or “runtime”. If you want to switch the linkage mode, just re-run
CMake with a different setting. For a discussion of PLUMED linkage modes, please see above. When
DOWNLOAD_PLUMED is enabled the static linkage mode is recommended.

Traditional make
PLUMED needs to be installed before the PLUMED package is installed so that LAMMPS can find the
right settings when compiling and linking the LAMMPS executable. You can either download and build
PLUMED inside the LAMMPS plumed library folder or use a previously installed PLUMED library and
point LAMMPS to its location. You also have to choose the linkage mode: “static” (default), “shared” or
“runtime”. For a discussion of PLUMED linkage modes, please see above.
Download/compilation/configuration of the plumed library can be done from the src folder through the
following make args:

$ make lib-plumed # print help message

$ make lib-plumed args="-b" # download and build PLUMED in lib/
,→plumed/plumed2

$ make lib-plumed args="-p $HOME/.local" # use existing PLUMED installation␣

,→in $HOME/.local

$ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED␣

,→installation in

# /usr/local and use shared␣

,→linkage mode

Note that 2 symbolic (soft) links, includelink and liblink are created in lib/plumed that point to the
location of the PLUMED build to use. A new file lib/plumed/Makefile.lammps is also created with
settings suitable for LAMMPS to compile and link PLUMED using the desired linkage mode. After this
step is completed, you can install the PLUMED package and compile LAMMPS in the usual manner:

$ make yes-plumed
$ make machine

Once this compilation completes you should be able to run LAMMPS in the usual way. For shared linkage

72 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

mode, libplumed.so must be found by the LAMMPS executable, which on many operating systems means,
you have to set the LD_LIBRARY_PATH environment variable accordingly.
Support for the different linkage modes in LAMMPS varies for different operating systems, using the static
linkage is expected to be the most portable, and thus set to be the default.
If you want to change the linkage mode, you have to re-run “make lib-plumed” with the desired settings and
do a re-install if the PLUMED package with “make yes-plumed” to update the required makefile settings
with the changes in the lib/plumed folder.

3.7.19 H5MD package

To build with this package you must have the HDF5 software package installed on your system, which should include
the h5cc compiler and the HDF5 library.

CMake build
No additional settings are needed besides -D PKG_H5MD=yes.
This should auto-detect the H5MD library on your system. Several advanced CMake H5MD options exist
if you need to specify where it is installed. Use the ccmake (terminal window) or cmake-gui (graphical)
tools to see these options and set them interactively from their user interfaces.

Traditional make
Before building LAMMPS, you must build the CH5MD library in lib/h5md. You can do this manually if
you prefer; follow the instructions in lib/h5md/README. You can also do it in one step from the lammps/
src dir, using a command like these, which simply invoke the lib/h5md/Install.py script with the
specified args:

$ make lib-h5md # print help message

$ make lib-h5md args="-m h5cc" # build with h5cc compiler

The build should produce two files: lib/h5md/libch5md.a and lib/h5md/Makefile.lammps. The
latter is copied from an existing Makefile.lammps.* and has settings needed to build LAMMPS with
the system HDF5 library. If necessary, you can edit/create a new lib/h5md/Makefile.machine file
for your system, which should define an EXTRAMAKE variable to specify a corresponding Makefile.
lammps.<machine> file.

3.7.20 ML-HDNNP package

To build with the ML-HDNNP package it is required to download and build the external n2p2 library v2.1.4 (or
higher). The LAMMPS build process offers an automatic download and compilation of n2p2 or allows you to choose
the installation directory of n2p2 manually. Please see the boxes below for the CMake and traditional build system for
detailed information.
In case of a manual installation of n2p2 you only need to build the n2p2 core library libnnp and interface library
libnnpif. When using GCC it should suffice to execute make libnnpif in the n2p2 src directory. For more details
please see lib/hdnnp/README and the n2p2 build documentation.

3.7. Packages with extra build options 73

LAMMPS Documentation, Release stable 29Sep2021

CMake build

-D DOWNLOAD_N2P2=value # download n2p2 for build, value = no (default) or␣

,→yes

-D N2P2_DIR=path # n2p2 base directory (only needed if a custom␣

,→location)

If DOWNLOAD_N2P2 is set, the n2p2 library will be downloaded and built inside the CMake build directory.
If the n2p2 library is already on your system (in a location CMake cannot find it), set the N2P2_DIR to
path where n2p2 is located. If n2p2 is located directly in lib/hdnnp/n2p2 it will be automatically found
by CMake.

Traditional make
You can download and build the n2p2 library manually if you prefer; follow the instructions in lib/
hdnnp/README. You can also do it in one step from the lammps/src dir, using a command like these,
which simply invoke the lib/hdnnp/Install.py script with the specified args:

$ make lib-hdnnp # print help message

$ make lib-hdnnp args="-b" # download and build in lib/hdnnp/n2p2-...
$ make lib-hdnnp args="-b -v 2.1.4" # download and build specific version
$ make lib-hdnnp args="-p /usr/local/n2p2" # use the existing n2p2␣
,→installation in /usr/local/n2p2

Note that 3 symbolic (soft) links, includelink, liblink and Makefile.lammps, will be created in lib/
hdnnp to point to n2p2/include, n2p2/lib and n2p2/lib/Makefile.lammps-extra, respectively.
When LAMMPS is built in src it will use these links.

3.7.21 INTEL package

To build with this package, you must choose which hardware you want to build for, either x86 CPUs or Intel KNLs in
offload mode. You should also typically install the OPENMP package, as it can be used in tandem with the INTEL
package to good effect, as explained on the INTEL package page.
When using Intel compilers version 16.0 or later is required. You can also use the GNU or Clang compilers and
they will provide performance improvements over regular styles and OPENMP styles, but less so than with the Intel
compilers. Please also note, that some compilers have been found to apply memory alignment constraints incompletely
or incorrectly and thus can cause segmentation faults in otherwise correct code when using features from the INTEL
package.

CMake build

-D INTEL_ARCH=value # value = cpu (default) or knl

-D INTEL_LRT_MODE=value # value = threads, none, or c++11

Traditional make

74 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Choose which hardware to compile for in Makefile.machine via the following settings. See src/MAKE/
OPTIONS/Makefile.intel_cpu* and Makefile.knl files for examples. and src/INTEL/README for
additional information.
For CPUs:

OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -

,→qopt-zmm-usage=high

CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-

,→alias -restrict $(OPTFLAGS)

LINKFLAGS = -g -qopenmp $(OPTFLAGS)

LIB = -ltbbmalloc

For KNLs:

OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-

,→limits

CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-

,→alias -restrict $(OPTFLAGS)

LINKFLAGS = -g -qopenmp $(OPTFLAGS)

LIB = -ltbbmalloc

In Long-range thread mode (LRT) a modified verlet style is used, that operates the Kspace calculation in a separate
thread concurrently to other calculations. This has to be enabled in the package intel command at runtime. With the
setting “threads” it used the pthreads library, while “c++11” will use the built-in thread support of C++11 compilers.
The option “none” skips compilation of this feature. The default is to use “threads” if pthreads is available and otherwise
“none”.
Best performance is achieved with Intel hardware, Intel compilers, as well as the Intel TBB and MKL libraries. How-
ever, the code also compiles, links, and runs with other compilers / hardware and without TBB and MKL.

3.7.22 MDI package

CMake build

-D DOWNLOAD_MDI=value # download MDI Library for build, value = no␣

,→(default) or yes

Traditional make
Before building LAMMPS, you must build the MDI Library in lib/mdi. You can do this by executing a
command like one of the following from the lib/mdi directory:

$ python Install.py -m gcc # build using gcc compiler

$ python Install.py -m icc # build using icc compiler

The build should produce two files: lib/mdi/includelink/mdi.h and lib/mdi/liblink/libmdi.

so.

3.7. Packages with extra build options 75

LAMMPS Documentation, Release stable 29Sep2021

3.7.23 MESONT package

This package includes a library written in Fortran 90 in the lib/mesont folder, so a working Fortran 90 compiler is
required to compile it. Also, the files with the force field data for running the bundled examples are not included in the
source distribution. Instead they will be downloaded the first time this package is installed.

CMake build
No additional settings are needed besides -D PKG_MESONT=yes

Traditional make
Before building LAMMPS, you must build the mesont library in lib/mesont. You can also do it in
one step from the lammps/src dir, using a command like these, which simply invoke the lib/mesont/
Install.py script with the specified args:

$ make lib-mesont # print help message

$ make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings␣
,→as with "make serial")

$ make lib-mesont args="-m ifort" # build with Intel icc compiler

The build should produce two files: lib/mesont/libmesont.a and lib/mesont/Makefile.lammps.

The latter is copied from an existing Makefile.lammps.\* and has settings needed to build LAMMPS
with the mesont library (though typically the settings contain only the Fortran runtime library). If nec-
essary, you can edit/create a new lib/mesont/Makefile.machine file for your system, which should
define an EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine file.

3.7.24 MOLFILE package

CMake build

-D MOLFILE_INCLUDE_DIR=path # (optional) path where VMD molfile plugin␣

,→headers are installed

-D PKG_MOLFILE=yes

Using -D PKG_MOLFILE=yes enables the package, and setting -D MOLFILE_INCLUDE_DIR allows to pro-
vide a custom location for the molfile plugin header files. These should match the ABI of the plugin files
used, and thus one typically sets them to include folder of the local VMD installation in use. LAMMPS
ships with a couple of default header files that correspond to a popular VMD version, usually the latest
release.

Traditional make
The lib/molfile/Makefile.lammps file has a setting for a dynamic loading library libdl.a that is typ-
ically present on all systems. It is required for LAMMPS to link with this package. If the setting is not
valid for your system, you will need to edit the Makefile.lammps file. See lib/molfile/README and
lib/molfile/Makefile.lammps for details. It is also possible to configure a different folder with the

76 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

VMD molfile plugin header files. LAMMPS ships with a couple of default headers, but these are not com-
patible with all VMD versions, so it is often best to change this setting to the location of the same include
files of the local VMD installation in use.

3.7.25 NETCDF package

To build with this package you must have the NetCDF library installed on your system.

CMake build
No additional settings are needed besides -D PKG_NETCDF=yes.
This should auto-detect the NETCDF library if it is installed on your system at standard locations. Several
advanced CMake NETCDF options exist if you need to specify where it was installed. Use the ccmake
(terminal window) or cmake-gui (graphical) tools to see these options and set them interactively from
their user interfaces.

Traditional make
The lib/netcdf/Makefile.lammps file has settings for NetCDF include and library files which
LAMMPS needs to build with this package. If the settings are not valid for your system, you will need to
edit the Makefile.lammps file. See lib/netcdf/README for details.

3.7.26 OPENMP package

CMake build
No additional settings are required besides -D PKG_OPENMP=yes. If CMake detects OpenMP compiler
support, the OPENMP code will be compiled with multi-threading support enabled, otherwise as opti-
mized serial code.

Traditional make
To enable multi-threading support in the OPENMP package (and other styles supporting OpenMP) the
following compile and link flags must be added to your Makefile.machine file. See src/MAKE/OPTIONS/
Makefile.omp for an example.

CCFLAGS: -fopenmp # for GNU and Clang Compilers

CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux
LINKFLAGS: -fopenmp # for GNU and Clang Compilers
LINKFLAGS: -qopenmp # for Intel compilers on Linux

For other platforms and compilers, please consult the documentation about OpenMP support for your
compiler.

3.7. Packages with extra build options 77

LAMMPS Documentation, Release stable 29Sep2021

3.7.27 QMMM package

For using LAMMPS to do QM/MM simulations via the QMMM package you need to build LAMMPS as a library.
A LAMMPS executable with fix qmmm included can be built, but will not be able to do a QM/MM simulation on as
such. You must also build a QM code - currently only Quantum ESPRESSO (QE) is supported - and create a new
executable which links LAMMPS and the QM code together. Details are given in the lib/qmmm/README file. It is
also recommended to read the instructions for linking with LAMMPS as a library for background information. This
requires compatible Quantum Espresso and LAMMPS versions. The current interface and makefiles have last been
verified to work in February 2020 with Quantum Espresso versions 6.3 to 6.5.

CMake build
When using CMake, building a LAMMPS library is required and it is recommended to build a shared
library, since any libraries built from the sources in the lib folder (including the essential libqmmm.a) are
not included in the static LAMMPS library and (currently) not installed, while their code is included in
the shared LAMMPS library. Thus a typical command line to configure building LAMMPS for QMMM
would be:

cmake -C ../cmake/presets/basic.cmake -D PKG_QMMM=yes \

-D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake

After completing the LAMMPS build and also configuring and compiling Quantum ESPRESSO with
external library support (via “make couple”), go back to the lib/qmmm folder and follow the instructions
on the README file to build the combined LAMMPS/QE QM/MM executable (pwqmmm.x) in the lib/
qmmm folder.

Traditional make
Before building LAMMPS, you must build the QMMM library in lib/qmmm. You can do this manually
if you prefer; follow the first two steps explained in lib/qmmm/README. You can also do it in one step
from the lammps/src dir, using a command like these, which simply invoke the lib/qmmm/Install.py
script with the specified args:

$ make lib-qmmm # print help message

$ make lib-qmmm args="-m serial" # build with GNU Fortran compiler␣
,→(settings as in "make serial")

$ make lib-qmmm args="-m mpi" # build with default MPI compiler␣

,→(settings as in "make mpi")

$ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler

The build should produce two files: lib/qmmm/libqmmm.a and lib/qmmm/Makefile.lammps. The
latter is copied from an existing Makefile.lammps.* and has settings needed to build LAMMPS with
the QMMM library (though typically the settings are just blank). If necessary, you can edit/create a new
lib/qmmm/Makefile.<machine> file for your system, which should define an EXTRAMAKE variable to
specify a corresponding Makefile.lammps.<machine> file.
You can then install QMMM package and build LAMMPS in the usual manner. After completing the
LAMMPS build and compiling Quantum ESPRESSO with external library support (via “make couple”),
go back to the lib/qmmm folder and follow the instructions in the README file to build the combined
LAMMPS/QE QM/MM executable (pwqmmm.x) in the lib/qmmm folder.

78 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.7.28 ML-QUIP package

To build with this package, you must download and build the QUIP library. It can be obtained from GitHub. For
support of GAP potentials, additional files with specific licensing conditions need to be downloaded and configured.
The automatic download will from within CMake will download the non-commercial use version.

CMake build

-D DOWNLOAD_QUIP=value # download OpenKIM API v2 for build, value = no␣

,→(default) or yes

-D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location)

CMake will try to download and build the QUIP library from GitHub, if it is not found on the local machine.
This requires to have git installed. It will use the same compilers and flags as used for compiling LAMMPS.
Currently this is only supported for the GNU and the Intel compilers. Set the QUIP_LIBRARY variable if
you want to use a previously compiled and installed QUIP library and CMake cannot find it.

Traditional make
The download/build procedure for the QUIP library, described in lib/quip/README file requires set-
ting two environment variables, QUIP_ROOT and QUIP_ARCH. These are accessed by the lib/quip/
Makefile.lammps file which is used when you compile and link LAMMPS with this package. You
should only need to edit Makefile.lammps if the LAMMPS build can not use its settings to successfully
build on your system.

3.7.29 SCAFACOS package

To build with this package, you must download and build the ScaFaCoS Coulomb solver library

CMake build

-D DOWNLOAD_SCAFACOS=value # download ScaFaCoS for build, value = no␣

,→(default) or yes

-D SCAFACOS_LIBRARY=path # ScaFaCos library file (only needed if at␣

,→custom location)

-D SCAFACOS_INCLUDE_DIR=path # ScaFaCoS include directory (only needed if at␣

,→custom location)

If DOWNLOAD_SCAFACOS is set, the ScaFaCoS library will be downloaded and built inside the CMake
build directory. If the ScaFaCoS library is already on your system (in a location CMake cannot find it),
SCAFACOS_LIBRARY is the filename (plus path) of the ScaFaCoS library file, not the directory the library
file is in. SCAFACOS_INCLUDE_DIR is the directory the ScaFaCoS include file is in.

Traditional make
You can download and build the ScaFaCoS library manually if you prefer; follow the instructions in lib/
scafacos/README. You can also do it in one step from the lammps/src dir, using a command like these,
which simply invoke the lib/scafacos/Install.py script with the specified args:

3.7. Packages with extra build options 79

LAMMPS Documentation, Release stable 29Sep2021

make lib-scafacos # print help message

make lib-scafacos args="-b" # download and build in lib/scafacos/
,→scafacos-<version>

make lib-scafacos args="-p $HOME/scafacos # use existing ScaFaCoS␣

,→installation in $HOME/scafacos

Note that 2 symbolic (soft) links, includelink and liblink, are created in lib/scafacos to point to
the ScaFaCoS src dir. When LAMMPS builds in src it will use these links. You should not need to edit
the lib/scafacos/Makefile.lammps file.

3.7.30 MACHDYN package

To build with this package, you must download the Eigen3 library. Eigen3 is a template library, so you do not need to
build it.

CMake build

-D DOWNLOAD_EIGEN3 # download Eigen3, value = no (default) or yes

-D EIGEN3_INCLUDE_DIR=path # path to Eigen library (only needed if a custom␣
,→location)

If DOWNLOAD_EIGEN3 is set, the Eigen3 library will be downloaded and inside the CMake build direc-
tory. If the Eigen3 library is already on your system (in a location where CMake cannot find it), set
EIGEN3_INCLUDE_DIR to the directory the Eigen3 include file is in.

Traditional make
You can download the Eigen3 library manually if you prefer; follow the instructions in lib/smd/README.
You can also do it in one step from the lammps/src dir, using a command like these, which simply invoke
the lib/smd/Install.py script with the specified args:

$ make lib-smd # print help message

$ make lib-smd args="-b" # download to lib/smd/eigen3
$ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen␣
,→installation in /usr/include/eigen3

Note that a symbolic (soft) link named includelink is created in lib/smd to point to the Eigen dir. When
LAMMPS builds it will use this link. You should not need to edit the lib/smd/Makefile.lammps file.

80 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.7.31 VTK package

To build with this package you must have the VTK library installed on your system.

CMake build
No additional settings are needed besides -D PKG_VTK=yes.
This should auto-detect the VTK library if it is installed on your system at standard locations. Several
advanced VTK options exist if you need to specify where it was installed. Use the ccmake (terminal
window) or cmake-gui (graphical) tools to see these options and set them interactively from their user
interfaces.

Traditional make
The lib/vtk/Makefile.lammps file has settings for accessing VTK files and its library, which
LAMMPS needs to build with this package. If the settings are not valid for your system, check if one
of the other lib/vtk/Makefile.lammps.* files is compatible and copy it to Makefile.lammps. If none
of the provided files work, you will need to edit the Makefile.lammps file. See lib/vtk/README for
details.

3.8 Build the LAMMPS documentation

Depending on how you obtained LAMMPS and whether you have built the manual yourself, this directory has a number
of sub-directories and files. Here is a list with descriptions:

README # brief info about the documentation

src # content files for LAMMPS documentation
html # HTML version of the LAMMPS manual (see html/Manual.html)
utils # tools and settings for building the documentation
lammps.1 # man page for the lammps command
msi2lmp.1 # man page for the msi2lmp command
Manual.pdf # large PDF version of entire manual
LAMMPS.epub # Manual in ePUB e-book format
LAMMPS.mobi # Manual in MOBI e-book format
docenv # virtualenv folder for processing the manual sources
doctrees # temporary data from processing the manual
doxygen # doxygen configuration and output
.gitignore # list of files and folders to be ignored by git
doxygen-warn.log # logfile with warnings from running doxygen
github-development-workflow.md # notes on the LAMMPS development workflow

If you downloaded LAMMPS as a tarball from the LAMMPS website, the html folder and the PDF files should be
included.
If you downloaded LAMMPS from the public git repository, then the HTML and PDF files are not included. You can
build the HTML or PDF files yourself, by typing make html or make pdf in the doc folder. This requires various
tools and files. Some of them have to be installed (see below). For the rest the build process will attempt to download
and install them into a python virtual environment and local folders.
A current version of the manual (latest patch release, aka unstable branch) is is available online at: https://docs.lammps.
org/Manual.html. A version of the manual corresponding to the ongoing development (aka master branch) is available

3.8. Build the LAMMPS documentation 81

LAMMPS Documentation, Release stable 29Sep2021

online at: https://docs.lammps.org/latest/

3.8.1 Build using GNU make

The LAMMPS manual is written in reStructuredText format which can be translated to different output format using
the Sphinx document generator tool. It also incorporates programmer documentation extracted from the LAMMPS
C++ sources through the Doxygen program. Currently the translation to HTML, PDF (via LaTeX), ePUB (for many
e-book readers) and MOBI (for Amazon Kindle readers) are supported. For that to work a Python 3 interpreter, the
doxygen tools and internet access to download additional files and tools are required. This download is usually only
required once or after the documentation folder is returned to a pristine state with make clean-all.
For the documentation build a python virtual environment is set up in the folder doc/docenv and various python
packages are installed into that virtual environment via the pip tool. For rendering embedded LaTeX code also the
MathJax JavaScript engine needs to be downloaded. If you need to pass additional options to the pip commands to work
(e.g. to use a web proxy or to point to additional SSL certificates) you can set them via the PIP_OPTIONS environment
variable or uncomment and edit the PIP_OPTIONS setting at beginning of the makefile.
The actual translation is then done via make commands in the doc folder. The following make commands are available:

make html # generate HTML in html dir using Sphinx

make pdf # generate PDF as Manual.pdf using Sphinx and PDFLaTeX
make fetch # fetch HTML pages and PDF files from LAMMPS website
# and unpack into the html_www folder and Manual_www.pdf
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert

make clean # remove intermediate RST files created by HTML build

make clean-all # remove entire build folder and any cached data

make anchor_check # check for duplicate anchor labels

make style_check # check for complete and consistent style lists
make package_check # check for complete and consistent package lists
make spelling # spell-check the manual

3.8.2 Build using CMake

It is also possible to create the HTML version (and only the HTML version) of the manual within the CMake build
directory. The reason for this option is to include the installation of the HTML manual pages into the “install” step when
installing LAMMPS after the CMake build via cmake --build . --target install. The documentation build is
included in the default build target, but can also be requested independently with cmake --build . --target doc.
If you need to pass additional options to the pip commands to work (e.g. to use a web proxy or to point to additional
SSL certificates) you can set them via the PIP_OPTIONS environment variable.

-D BUILD_DOC=value # yes or no (default)

82 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.8.3 Prerequisites for HTML

To run the HTML documentation build toolchain, python 3, git, doxygen, and virtualenv have to be installed locally.
Here are instructions for common setups:

Ubuntu

sudo apt-get install python-virtualenv git doxygen

RHEL or CentOS (Version 7.x)

sudo yum install python3-virtualenv git doxygen

Fedora or RHEL/CentOS (8.x or later)

sudo dnf install python3-virtualenv git doxygen

MacOS X
Python 3
Download the latest Python 3 MacOS X package from https://www.python.org and install it. This will
install both Python 3 and pip3.
virtualenv
Once Python 3 is installed, open a Terminal and type

pip3 install virtualenv

This will install virtualenv from the Python Package Index.

3.8.4 Prerequisites for PDF

In addition to the tools needed for building the HTML format manual, a working LaTeX installation with support for
PDFLaTeX and a selection of LaTeX styles/packages are required. To run the PDFLaTeX translation the latexmk
script needs to be installed as well.

3.8. Build the LAMMPS documentation 83

LAMMPS Documentation, Release stable 29Sep2021

3.8.5 Prerequisites for ePUB and MOBI

In addition to the tools needed for building the HTML format manual, a working LaTeX installation with a few add-
on LaTeX packages as well as the dvipng tool are required to convert embedded math expressions transparently into
embedded images.
For converting the generated ePUB file to a MOBI format file (for e-book readers, like Kindle, that cannot read ePUB),
you also need to have the ebook-convert tool from the “calibre” software installed. http://calibre-ebook.com/ Typing
make mobi will first create the ePUB file and then convert it. On the Kindle readers in particular, you also have support
for PDF files, so you could download and view the PDF version as an alternative.

3.8.6 Instructions for Developers

When adding new styles or options to the LAMMPS code, corresponding documentation is required and either existing
files in the src folder need to be updated or new files added. These files are written in reStructuredText markup for
translation with the Sphinx tool.
Before contributing any documentation, please check that both the HTML and the PDF format documentation can
translate without errors. Please also check the output to the console for any warnings or problems. There will be
multiple tests run automatically:
• A test for correctness of all anchor labels and their references
• A test that all LAMMPS packages (= folders with sources in lammps/src) are documented and listed. A typical
warning shows the name of the folder with the suspected new package code and the documentation files where
they need to be listed:

Found 88 packages
Package NEWPACKAGE missing in Packages_list.rst
Package NEWPACKAGE missing in Packages_details.rst

• A test that only standard, printable ASCII text characters are used. This runs the command env LC_ALL=C
grep -n '[^ -~]' src/*.rst and thus prints all offending lines with filename and line number prepended
to the screen. Special characters like the Angstrom Å should be typeset with embedded math (like this :math:`\
mathrm{\mathring{A}}`).
• A test whether all styles are documented and listed in their respective overview pages. A typical output with
warnings looks like this:

Parsed style names w/o suffixes from C++ tree in ../src:

Angle styles: 21 Atom styles: 24
Body styles: 3 Bond styles: 17
Command styles: 41 Compute styles: 143
Dihedral styles: 16 Dump styles: 26
Fix styles: 223 Improper styles: 13
Integrate styles: 4 Kspace styles: 15
Minimize styles: 9 Pair styles: 234
Reader styles: 4 Region styles: 8
Compute style entry newcomp is missing or incomplete in Commands_compute.rst
Compute style entry newcomp is missing or incomplete in compute.rst
Fix style entry newfix is missing or incomplete in Commands_fix.rst
Fix style entry newfix is missing or incomplete in fix.rst
Pair style entry new is missing or incomplete in Commands_pair.rst
Pair style entry new is missing or incomplete in pair_style.rst
Found 6 issue(s) with style lists

84 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

In addition, there is the option to run a spellcheck on the entire manual with make spelling. This requires a library
called enchant. To avoid printing out false positives (e.g. keywords, names, abbreviations) those can be added to the
file lammps/doc/utils/sphinx-config/false_positives.txt.

3.9 Notes for building LAMMPS on Windows

• General remarks
• Running Linux on Windows
• Using GNU GCC ported to Windows
• Using a cross-compiler

3.9.1 General remarks

LAMMPS is developed and tested primarily on Linux machines. The vast majority of HPC clusters and supercomputers
today run on Linux as well. While portability to other platforms is desired, it is not always achieved. The LAMMPS
developers are dependent on LAMMPS users giving feedback and providing assistance in resolving portability issues.
This is particularly true for compiling LAMMPS on Windows, since this platform has significant differences in some
low-level functionality.

3.9.2 Running Linux on Windows

Before trying to build LAMMPS on Windows, please consider if the pre-compiled Windows binary packages are
sufficient for your needs. If it is necessary for you to compile LAMMPS on a Windows machine (e.g. because it is your
main desktop), please also consider using a virtual machine software and compile and run LAMMPS in a Linux virtual
machine, or - if you have a sufficiently up-to-date Windows 10 installation - consider using the Windows subsystem for
Linux. This optional Windows feature allows you to run the bash shell from Ubuntu from within Windows and from
there on, you can pretty much use that shell like you are running on an Ubuntu Linux machine (e.g. installing software
via apt-get and more). For more details on that, please see this tutorial.

3.9.3 Using a GNU GCC ported to Windows

One option for compiling LAMMPS on Windows natively that has been known to work in the past is to install a bash
shell, unix shell utilities, perl, GNU make, and a GNU compiler ported to Windows. The Cygwin package provides
a unix/linux interface to low-level Windows functions, so LAMMPS can be compiled on Windows. The necessary
(minor) modifications to LAMMPS are included, but may not always up-to-date for recently added functionality and
the corresponding new code. A machine makefile for using cygwin for the old build system is provided. Using CMake
for this mode of compilation is untested and not likely to work.
When compiling for Windows do not set the -DLAMMPS_MEMALIGN define in the LMP_INC makefile variable and add
-lwsock32 -lpsapi to the linker flags in LIB makefile variable. Try adding -static-libgcc or -static or both
to the linker flags when your resulting LAMMPS Windows executable complains about missing .dll files. The CMake
configuration should set this up automatically, but is untested.
In case of problems, you are recommended to contact somebody with experience in using Cygwin. If you do come
across portability problems requiring changes to the LAMMPS source code, or figure out corrections yourself, please
report them on the lammps-users mailing list, or file them as an issue or pull request on the LAMMPS GitHub project.

3.9. Notes for building LAMMPS on Windows 85

LAMMPS Documentation, Release stable 29Sep2021

3.9.4 Using a cross-compiler

If you need to provide custom LAMMPS binaries for Windows, but do not need to do the compilation on Windows,
please consider using a Linux to Windows cross-compiler. This is how currently the Windows binary packages are cre-
ated by the LAMMPS developers. Because of that, this is probably the currently best tested and supported way to build
LAMMPS executables for Windows. A CMake preset selecting all packages compatible with this cross-compilation
build is provided. The GPU package can only be compiled with OpenCL support. To compile with MPI support, a pre-
compiled library and the corresponding header files are required. When building with CMake the matching package
will be downloaded automatically, but MPI support has to be explicitly enabled with -DBUILD_MPI=on.
Please keep in mind, though, that this only applies to compiling LAMMPS. Whether the resulting binaries do work
correctly is rarely tested by the LAMMPS developers. We instead rely on the feedback of the users of these pre-compiled
LAMMPS packages for Windows. We will try to resolve issues to the best of our abilities if we become aware of them.
However this is subject to time constraints and focus on HPC platforms.

3.9.5 Native Visual C++ support

Support for the Visual C++ compilers is currently not available. The CMake build system is capable of creating suitable
a Visual Studio style build environment, but the LAMMPS source code itself is not ported to fully support Visual C++.
Volunteers to take on this task are welcome.

3.10 Notes for saving disk space when building LAMMPS from source

LAMMPS is a large software project with a large number of source files, extensive documentation, and a large collection
of example files. When downloading LAMMPS by cloning the git repository from GitHub this will by default also
download the entire commit history since September 2006. Compiling LAMMPS will add the storage requirements of
the compiled object files and libraries to the tally.
In a user account on an HPC cluster with filesystem quotas or in other environments with restricted disk space capacity
it may be needed to reduce the storage requirements. Here are some suggestions:
• Create a so-called shallow repository by cloning only the last commit instead of the full project history by using
git clone [email protected]:lammps/lammps --depth=1 --branch=master. This reduces the down-
loaded size to about half. With --depth=1 it is not possible to check out different versions/branches of
LAMMPS, using --depth=1000 will make multiple recent versions available at little extra storage needs (the
entire git history had nearly 30,000 commits in fall 2021).
• Download a tar archive from either the download section on the LAMMPS homepage or from the LAMMPS
releases page on GitHub these will not contain the git history at all.
• Build LAMMPS without the debug flag (remove -g from the machine makefile or use
-DCMAKE_BUILD_TYPE=Release) or use the strip command on the LAMMPS executable when no
more debugging would be needed. The strip command may also be applied to the LAMMPS shared library.
The static library may be deleted entirely.
• Delete compiled object files and libraries after copying the LAMMPS executable to a permanent location. When
using the traditional build process, one may use make clean-<machine> or make clean-all to delete object
files in the src folder. For CMake based builds, one may use make clean or just delete the entire build folder.
• The folders containing the documentation tree (doc), the examples (examples) are not needed to build and run
LAMMPS and can be safely deleted. Some files in the potentials folder are large and may be deleted, if not
needed. The largest of those files (occupying about 120 MBytes combined) will only be downloaded on demand,
when the corresponding package is installed.

86 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• When using the CMake build procedure, the compilation can be done on a (local) scratch storage that will not
count toward the quota. A local scratch file system may offer the additional benefit of speeding up creating
object files and linking with libraries compared to a networked file system. Also with CMake (and unlike with
the traditional make) it is possible to compile LAMMPS executables with different settings and packages included
from the same source tree since all the configuration information is stored in the build folder. So it is not necessary
to have multiple copies of LAMMPS.

3.11 Development build options

The build procedures in LAMMPS offers a few extra options which are useful during development, testing or debugging.

3.11.1 Monitor compilation flags (CMake only)

Sometimes it is necessary to verify the complete sequence of compilation flags generated by the CMake build. To
enable a more verbose output during compilation you can use the following option.

-D CMAKE_VERBOSE_MAKEFILE=value # value = no (default) or yes

Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:

make VERBOSE=1

3.11.2 Enable static code analysis with clang-tidy (CMake only)

The clang-tidy tool is a static code analysis tool to diagnose (and potentially fix) typical programming errors or coding
style violations. It has a modular framework of tests that can be adjusted to help identifying problems before they
become bugs and also assist in modernizing large code bases (like LAMMPS). It can be enabled for all C++ code with
the following CMake flag

-D ENABLE_CLANG_TIDY=value # value = no (default) or yes

With this flag enabled all source files will be processed twice, first to be compiled and then to be analyzed. Please note
that the analysis can be significantly more time consuming than the compilation itself.

3.11.3 Report missing and unneeded ‘#include’ statements (CMake only)

The conventions for how and when to use and order include statements in LAMMPS are documented in LAMMPS
programming style and requirements for contributions. To assist with following these conventions one can use the
Include What You Use tool. This tool is still under development and for large and complex projects like LAMMPS
there are some false positives, so suggested changes need to be verified manually. It is recommended to use at least
version 0.16, which has much fewer incorrect reports than earlier versions. To install the IWYU toolkit, you need to
have the clang compiler and its development package installed. Download the IWYU version that matches the version
of the clang compiler, configure, build, and install it.
The necessary steps to generate the report can be enabled via a CMake variable during CMake configuration.

3.11. Development build options 87

LAMMPS Documentation, Release stable 29Sep2021

-D ENABLE_IWYU=value # value = no (default) or yes

This will check if the required binary (include-what-you-use or iwyu) and python script script (iwyu-tool or iwyu_tool
or iwyu_tool.py) can be found in the path. The analysis can then be started with:

make iwyu

This may first run some compilation, as the analysis is dependent on recording all commands required to do the com-
pilation.

3.11.4 Address, Undefined Behavior, and Thread Sanitizer Support (CMake only)

Compilers such as GCC and Clang support generating instrumented binaries which use different sanitizer libraries to
detect problems in the code during run-time. They can detect issues like:
• memory leaks
• undefined behavior
• data races
Please note that this kind of instrumentation usually comes with a performance hit (but much less than using tools like
Valgrind with a more low level approach). To enable these features, additional compiler flags need to be added to the
compilation and linking stages. This is done through setting the ENABLE_SANITIZER variable during configuration.
Examples:

-D ENABLE_SANITIZER=none # no sanitizer active (default)

-D ENABLE_SANITIZER=address # enable address sanitizer / memory leak checker
-D ENABLE_SANITIZER=leak # enable memory leak checker (only)
-D ENABLE_SANITIZER=undefined # enable undefined behavior sanitizer
-D ENABLE_SANITIZER=thread # enable thread sanitizer

3.11.5 Code Coverage and Unit Testing (CMake only)

The LAMMPS code is subject to multiple levels of automated testing during development: integration testing (i.e.
whether the code compiles on various platforms and with a variety of settings), unit testing (i.e. whether certain
individual parts of the code produce the expected results for given inputs), run testing (whether selected complete input
decks run without crashing for multiple configurations), and regression testing (i.e. whether selected input examples
reproduce the same results over a given number of steps and operations within a given error margin). The status of this
automated testing can be viewed on https://ci.lammps.org.
The scripts and inputs for integration, run, and regression testing are maintained in a separate repository of the
LAMMPS project on GitHub.
The unit testing facility is integrated into the CMake build process of the LAMMPS source code distribution itself.
It can be enabled by setting -D ENABLE_TESTING=on during the CMake configuration step. It requires the YAML
library and development headers (if those are not found locally a recent version will be downloaded and compiled
along with LAMMPS and the test program) to compile and will download and compile a specific recent version of the
Googletest C++ test framework for implementing the tests.
After compilation is complete, the unit testing is started in the build folder using the ctest command, which is part of
the CMake software. The output of this command will be looking something like this:

88 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

[...]$ ctest
Test project /home/akohlmey/compile/lammps/build-testing
Start 1: MolPairStyle:hybrid-overlay
1/109 Test #1: MolPairStyle:hybrid-overlay ......... Passed 0.02 sec
Start 2: MolPairStyle:hybrid
2/109 Test #2: MolPairStyle:hybrid ................. Passed 0.01 sec
Start 3: MolPairStyle:lj_class2
[...]
Start 107: PotentialFileReader
107/109 Test #107: PotentialFileReader ................ Passed 0.04 sec
Start 108: EIMPotentialFileReader
108/109 Test #108: EIMPotentialFileReader ............. Passed 0.03 sec
Start 109: TestSimpleCommands
109/109 Test #109: TestSimpleCommands ................. Passed 0.02 sec

100% tests passed, 0 tests failed out of 26

Total Test time (real) = 25.57 sec

The ctest command has many options, the most important ones are:

Option Function
-V verbose output: display output of individual test runs
-j <num> parallel run: run <num> tests in parallel
-R <regex> run subset of tests matching the regular expression <regex>
-E <regex> exclude subset of tests matching the regular expression <regex>
-N dry-run: display list of tests without running them
-T memcheck run tests with valgrind memory checker (if available)

In its full implementation, the unit test framework will consist of multiple kinds of tests implemented in different
programming languages (C++, C, Python, Fortran) and testing different aspects of the LAMMPS software and its
features. The tests will adapt to the compilation settings of LAMMPS, so that tests will be skipped if prerequisite
features are not available in LAMMPS.

Note: The unit test framework was added in spring 2020 and is under active development. The coverage is not
complete and will be expanded over time.

Tests for styles of the same kind of style (e.g. pair styles or bond styles) are performed with the same test executable
using different input files in YAML format. So to add a test for another style of the same kind it may be sufficient to add
a suitable YAML file. Detailed instructions for adding tests are provided in the Programmer Guide part of the manual.

Unit tests for force styles

A large part of LAMMPS are different “styles” for computing non-bonded and bonded interactions selected through the
pair_style command, bond_style command, angle_style command, dihedral_style command, improper_style command,
and kspace_style command. Since these all share common interfaces, it is possible to write generic test programs that
will call those common interfaces for small test systems with less than 100 atoms and compare the results with pre-
recorded reference results. A test run is then a a collection multiple individual test runs each with many comparisons
to reference results based on template input files, individual command settings, relative error margins, and reference
data stored in a YAML format file with .yaml suffix. Currently the programs test_pair_style, test_bond_style,
and test_angle_style are implemented. They will compare forces, energies and (global) stress for all atoms after

3.11. Development build options 89

LAMMPS Documentation, Release stable 29Sep2021

a run 0 calculation and after a few steps of MD with fix nve, each in multiple variants with different settings and also
for multiple accelerated styles. If a prerequisite style or package is missing, the individual tests are skipped. All tests
will be executed on a single MPI process, so using the CMake option -D BUILD_MPI=off can significantly speed up
testing, since this will skip the MPI initialization for each test run. Below is an example command and output:

[tests]$ test_pair_style mol-pair-lj_cut.yaml

[==========] Running 6 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 6 tests from PairStyle
[ RUN ] PairStyle.plain
[ OK ] PairStyle.plain (24 ms)
[ RUN ] PairStyle.omp
[ OK ] PairStyle.omp (18 ms)
[ RUN ] PairStyle.intel
[ OK ] PairStyle.intel (6 ms)
[ RUN ] PairStyle.opt
[ SKIPPED ] PairStyle.opt (0 ms)
[ RUN ] PairStyle.single
[ OK ] PairStyle.single (7 ms)
[ RUN ] PairStyle.extract
[ OK ] PairStyle.extract (6 ms)
[----------] 6 tests from PairStyle (62 ms total)

[----------] Global test environment tear-down

[==========] 6 tests from 1 test suite ran. (63 ms total)
[ PASSED ] 5 tests.
[ SKIPPED ] 1 test, listed below:
[ SKIPPED ] PairStyle.opt

In this particular case, 5 out of 6 sets of tests were conducted, the tests for the lj/cut/opt pair style was skipped,
since the tests executable did not include it. To learn what individual tests are performed, you (currently) need to read
the source code. You can use code coverage recording (see next section) to confirm how well the tests cover the code
paths in the individual source files.
The force style test programs have a common set of options:

Option Function
-g <newfile> regenerate reference data in new YAML file
-u update reference data in the original YAML file
-s print error statistics for each group of comparisons
-v verbose output: also print the executed LAMMPS commands

The ctest tool has no mechanism to directly pass flags to the individual test programs, but a workaround has been
implemented where these flags can be set in an environment variable TEST_ARGS. Example:

env TEST_ARGS=-s ctest -V -R BondStyle

To add a test for a style that is not yet covered, it is usually best to copy a YAML file for a similar style to a new file,
edit the details of the style (how to call it, how to set its coefficients) and then run test command with either the -g and
the replace the initial test file with the regenerated one or the -u option. The -u option will destroy the original file, if
the generation run does not complete, so using -g is recommended unless the YAML file is fully tested and working.

Recommendations and notes for YAML files

90 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• The reference results should be recorded without any code optimization or related compiler flags enabled.
• The epsilon parameter defines the relative precision with which the reference results must be met. The test
geometries often have high and low energy parts and thus a significant impact from floating-point math truncation
errors is to be expected. Some functional forms and potentials are more noisy than others, so this parameter needs
to be adjusted. Typically a value around 1.0e-13 can be used, but it may need to be as large as 1.0e-8 in some
cases.
• The tests for pair styles from OPT, OPENMP and INTEL are performed with automatically rescaled epsilon to
account for additional loss of precision from code optimizations and different summation orders.
• When compiling with (aggressive) compiler optimization, some tests are likely to fail. It is recommended to
inspect the individual tests in detail to decide, whether the specific error for a specific property is acceptable
(it often is), or this may be an indication of mis-compiled code (or an undesired large loss of precision due to
significant reordering of operations and thus less error cancellation).

Unit tests for timestepping related fixes

A substantial subset of fix styles are invoked regularly during MD timestepping and manipulate per-atom properties
like positions, velocities, and forces. For those fix styles, testing can be done in a very similar fashion as for force fields
and thus there is a test program test_fix_timestep that shares a lot of code, properties, and command line flags with the
force field style testers described in the previous section.
This tester will set up a small molecular system run with verlet run style for 4 MD steps, then write a binary restart and
continue for another 4 MD steps. At this point coordinates and velocities are recorded and compared to reference data.
Then the system is cleared, restarted and running the second 4 MD steps again and the data is compared to the same
reference. That is followed by another restart after which per atom type masses are replaced with per-atom masses and
the second 4 MD steps are repeated again and compared to the same reference. Also global scalar and vector data of
the fix is recorded and compared. If the fix is a thermostat and thus the internal property t_target can be extracted,
then this is compared to the reference data. The tests are repeated with the respa run style.
If the fix has a multi-threaded version in the OPENMP package, then the entire set of tests is repeated for that version
as well.
For this to work, some additional conditions have to be met by the YAML format test inputs.
• The fix to be tested (and only this fix), should be listed in the prerequisites: section
• The fix to be tested must be specified in the post_commands: section with the fix-ID test. This section may
contain other commands and other fixes (e.g. an instance of fix nve for testing a thermostat or force manipulation
fix)
• For fixes that can tally contributions to the global virial, the line fix_modify test virial yes should be
included in the post_commands: section of the test input.
• For thermostat fixes the target temperature should be ramped from an arbitrary value (e.g. 50K) to a pre-defined
target temperature entered as ${t_target}.
• For fixes that have thermostatting support included, but do not have it enabled in the input (e.g. fix rigid with
default settings), the post_commands: section should contain the line variable t_target delete to disable
the target temperature ramp check to avoid false positives.

3.11. Development build options 91

LAMMPS Documentation, Release stable 29Sep2021

Use custom linker for faster link times when ENABLE_TESTING is active

When compiling LAMMPS with enabled tests, most test executables will need to be linked against the LAMMPS
library. Since this can be a very large library with many C++ objects when many packages are enabled, link times can
become very long on machines that use the GNU BFD linker (e.g. Linux systems). Alternatives like the lld linker
of the LLVM project or the gold linker available with GNU binutils can speed up this step substantially. CMake will
by default test if any of the two can be enabled and use it when ENABLE_TESTING is active. It can also be selected
manually through the CMAKE_CUSTOM_LINKER CMake variable. Allowed values are lld, gold, bfd, or default.
The default option will use the system default linker otherwise, the linker is chosen explicitly. This option is only
available for the GNU or Clang C++ compiler.

Tests for other components and utility functions

Additional tests that validate utility functions or specific components of LAMMPS are implemented as standalone
executable which may, or may not require creating a suitable LAMMPS instance. These tests are more specific and do
not require YAML format input files. To add a test, either an existing source file needs to be extended or a new file
added, which in turn requires additions to the CMakeLists.txt file in the source folder.

Collect and visualize code coverage metrics

You can also collect code coverage metrics while running LAMMPS or the tests by enabling code coverage support
during the CMake configuration:
-D ENABLE_COVERAGE=on # enable coverage measurements (off by default)

This will instrument all object files to write information about which lines of code were accessed during execution in
files next to the corresponding object files. These can be post-processed to visually show the degree of coverage and
which code paths are accessed and which are not taken. When working on unit tests (see above), this can be extremely
helpful to determine which parts of the code are not executed and thus what kind of tests are still missing. The coverage
data is cumulative, i.e. new data is added with each new run.
Enabling code coverage will also add the following build targets to generate coverage reports after running the
LAMMPS executable or the unit tests:
make gen_coverage_html # generate coverage report in HTML format
make gen_coverage_xml # generate coverage report in XML format
make clean_coverage_html # delete folder with HTML format coverage report
make reset_coverage # delete all collected coverage data and HTML output

These reports require GCOVR to be installed. The easiest way to do this to install it via pip:
pip install git+https://github.com/gcovr/gcovr.git

After post-processing with gen_coverage_html the results are in a folder coverage_html and can be viewed with
a web browser. The images below illustrate how the data is presented.

Top of the overview page Styles with good coverage Top of individual source Source page with branches
page

92 Chapter 3. Build LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

3.11.6 Coding style utilities

To aid with enforcing some of the coding style conventions in LAMMPS some additional build targets have been added.
These require Python 3.5 or later and will only work properly on Unix-like operating and file systems.
The following options are available.

make check-whitespace # search for files with whitespace issues

make fix-whitespace # correct whitespace issues in files
make check-homepage # search for files with old LAMMPS homepage URLs
make fix-homepage # correct LAMMPS homepage URLs in files
make check-permissions # search for files with permissions issues
make fix-permissions # correct permissions issues in files

These should help to replace all TAB characters with blanks and remove any trailing whitespace. Also all LAMMPS
homepage URL references can be updated to the location change from Sandia to the lammps.org domain. And the
permission check can remove executable permissions from non-executable files (like source code).

3.11.7 Clang-format support

For the code in the unittest and src trees we are transitioning to use the clang-format tool to assist with having
a consistent source code formatting style. The clang-format command bundled with Clang version 8.0 or later is
required. The configuration is in files called .clang-format in the respective folders. Since the modifications from
clang-format can be significant and - especially for “legacy style code” - they are not always improving readability, a
large number of files currently have a // clang-format off at the top, which will disable the processing. As of fall
2021 all files have been either “protected” this way or are enabled for full or partial clang-format processing. Over
time, the “protected” files will be refactored and updated so that clang-format may be applied to them as well.
It is recommended for all newly contributed files to use the clang-format processing while writing the code or do the
coding style processing (including the scripts mentioned in the previous paragraph)
If clang-format is available, files can be updated individually with commands like the following:

$ clang-format -i some_file.cpp

The following target are available for both, GNU make and CMake:

make format-src # apply clang-format to all files in src and the package folders
make format-tests # apply clang-format to all files in the unittest tree

3.11. Development build options 93

LAMMPS Documentation, Release stable 29Sep2021

94 Chapter 3. Build LAMMPS

 CHAPTER

FOUR

RUN LAMMPS

These pages explain how to run LAMMPS once you have installed an executable or downloaded the source code and
built an executable. The Commands doc page describes how input scripts are structured and the commands they can
contain.

4.1 Basics of running LAMMPS

LAMMPS is run from the command line, reading commands from a file via the -in command line flag, or from standard
input. Using the “-in in.file” variant is recommended (see note below). The name of the LAMMPS executable is either
lmp or lmp_<machine> with <machine> being the machine string used when compiling LAMMPS. This is required
when compiling LAMMPS with the traditional build system (e.g. with make mpi), but optional when using CMake
to configure and build LAMMPS:

$ lmp_serial -in in.file

$ lmp_serial < in.file
$ lmp -in in.file
$ lmp < in.file
$ /path/to/lammps/src/lmp_serial -i in.file
$ mpirun -np 4 lmp_mpi -in in.file
$ mpiexec -np 4 lmp -in in.file
$ mpirun -np 8 /path/to/lammps/src/lmp_mpi -in in.file
$ mpiexec -n 6 /usr/local/bin/lmp -in in.file

You normally run the LAMMPS command in the directory where your input script is located. That is also where output
files are produced by default, unless you provide specific other paths in your input script or on the command line. As
in some of the examples above, the LAMMPS executable itself can be placed elsewhere.

Note: The redirection operator “<” will not always work when running in parallel with mpirun or mpiexec; for those
systems the -in form is required.

As LAMMPS runs it prints info to the screen and a logfile named log.lammps. More info about output is given on the
screen and logfile output page.
If LAMMPS encounters errors in the input script or while running a simulation it will print an ERROR message and
stop or a WARNING message and continue. See the Common Problems page for a discussion of the various kinds of
errors LAMMPS can or can’t detect, a list of all ERROR and WARNING messages, and what to do about them.

LAMMPS can run the same problem on any number of processors, including a single processor. In theory you should
get identical answers on any number of processors and on any machine. In practice, numerical round-off due to using

95
LAMMPS Documentation, Release stable 29Sep2021

floating-point math can cause slight differences and an eventual divergence of molecular dynamics trajectories. See
the Errors common page for discussion of this.
LAMMPS can run as large a problem as will fit in the physical memory of one or more processors. If you run out of
memory, you must run on more processors or define a smaller problem. The amount of memory needed and how well
it can be distributed across processors may vary based on the models and settings and commands used.
If you run LAMMPS in parallel via mpirun, you should be aware of the processors command, which controls how MPI
tasks are mapped to the simulation box, as well as mpirun options that control how MPI tasks are assigned to physical
cores of the node(s) of the machine you are running on. These settings can improve performance, though the defaults
are often adequate.
For example, it is often important to bind MPI tasks (processes) to physical cores (processor affinity), so that the
operating system does not migrate them during a simulation. If this is not the default behavior on your machine, the
mpirun option “–bind-to core” (OpenMPI) or “-bind-to core” (MPICH) can be used.
If the LAMMPS command(s) you are using support multi-threading, you can set the number of threads per MPI task
via the environment variable OMP_NUM_THREADS, before you launch LAMMPS:

$ export OMP_NUM_THREADS=2 # bash

$ setenv OMP_NUM_THREADS 2 # csh or tcsh

This can also be done via the package command or via the -pk command-line switch which invokes the package com-
mand. See the package command or Speed doc pages for more details about which accelerator packages and which
commands support multi-threading.

You can experiment with running LAMMPS using any of the input scripts provided in the examples or bench directory.
Input scripts are named in.* and sample outputs are named log.*.P where P is the number of processors it was run on.
Some of the examples or benchmarks require LAMMPS to be built with optional packages.

4.2 Command-line options

At run time, LAMMPS recognizes several optional command-line switches which may be used in any order. Either the
full word or a one or two letter abbreviation can be used:
• -e or -echo
• -h or -help
• -i or -in
• -k or -kokkos
• -l or -log
• -mdi
• -m or -mpicolor
• -c or -cite
• -nc or -nocite
• -pk or -package
• -p or -partition
• -pl or -plog

96 Chapter 4. Run LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• -ps or -pscreen
• -ro or -reorder
• -r2data or -restart2data
• -r2dump or -restart2dump
• -sc or -screen
• -sr or skiprun
• -sf or -suffix
• -v or -var
For example, the lmp_mpi executable might be launched as follows:

$ mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy

$ mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy

-echo style
Set the style of command echoing. The style can be none or screen or log or both. Depending on the style, each
command read from the input script will be echoed to the screen and/or logfile. This can be useful to figure out which
line of your script is causing an input error. The default value is log. The echo style can also be set by using the echo
command in the input script itself.

-help
Print a brief help summary and a list of options compiled into this executable for each LAMMPS style (atom_style,
fix, compute, pair_style, bond_style, etc). This can tell you if the command you want to use was included via the
appropriate package at compile time. LAMMPS will print the info and immediately exit if this switch is used.

-in file
Specify a file to use as an input script. This is an optional but recommended switch when running LAMMPS in one-
partition mode. If it is not specified, LAMMPS reads its script from standard input, typically from a script via I/O
redirection; e.g. lmp_linux < in.run. With many MPI implementations I/O redirection also works in parallel, but using
the -in flag will always work.
Note that this is a required switch when running LAMMPS in multi-partition mode, since multiple processors cannot
all read from stdin concurrently. The file name may be “none” for starting multi-partition calculations without reading
an initial input file from the library interface.

-kokkos on/off keyword/value . . .

Explicitly enable or disable KOKKOS support, as provided by the KOKKOS package. Even if LAMMPS is built with
this package, as described in the the KOKKOS package page, this switch must be set to enable running with KOKKOS-
enabled styles the package provides. If the switch is not set (the default), LAMMPS will operate as if the KOKKOS
package were not installed; i.e. you can run standard LAMMPS or with the GPU or OPENMP packages, for testing or
benchmarking purposes.
Additional optional keyword/value pairs can be specified which determine how Kokkos will use the underlying hardware
on your platform. These settings apply to each MPI task you launch via the “mpirun” or “mpiexec” command. You

4.2. Command-line options 97

LAMMPS Documentation, Release stable 29Sep2021

may choose to run one or more MPI tasks per physical node. Note that if you are running on a desktop machine, you
typically have one physical node. On a cluster or supercomputer there may be dozens or 1000s of physical nodes.
Either the full word or an abbreviation can be used for the keywords. Note that the keywords do not use a leading minus
sign. I.e. the keyword is “t”, not “-t”. Also note that each of the keywords has a default setting. Examples of when to
use these options and what settings to use on different platforms is given on the KOKKOS package doc page.
• d or device
• g or gpus
• t or threads
• n or numa

device Nd

This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and if you
are running with only one MPI task per node. The Nd setting is the ID of the GPU on the node to run on. By default
Nd = 0. If you have multiple GPUs per node, they have consecutive IDs numbered as 0,1,2,etc. This setting allows you
to launch multiple independent jobs on the node, each with a single MPI task per node, and assign each job to run on
a different GPU.

gpus Ng Ns

This option is only relevant if you built LAMMPS with CUDA=yes, you have more than one GPU per node, and you
are running with multiple MPI tasks per node (up to one per GPU). The Ng setting is how many GPUs you will use.
The Ns setting is optional. If set, it is the ID of a GPU to skip when assigning MPI tasks to GPUs. This may be useful
if your desktop system reserves one GPU to drive the screen and the rest are intended for computational work like
running LAMMPS. By default Ng = 1 and Ns is not set.
Depending on which flavor of MPI you are running, LAMMPS will look for one of these 4 environment variables

SLURM_LOCALID (various MPI variants compiled with SLURM support)

MPT_LRANK (HPE MPI)
MV2_COMM_WORLD_LOCAL_RANK (Mvapich)
OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI)

which are initialized by the “srun”, “mpirun” or “mpiexec” commands. The environment variable setting for each MPI
rank is used to assign a unique GPU ID to the MPI task.

threads Nt

This option assigns Nt number of threads to each MPI task for performing work when Kokkos is executing in OpenMP
or pthreads mode. The default is Nt = 1, which essentially runs in MPI-only mode. If there are Np MPI tasks per
physical node, you generally want Np*Nt = the number of physical cores per node, to use your available hardware
optimally. This also sets the number of threads used by the host when LAMMPS is compiled with CUDA=yes.

numa Nm

This option is only relevant when using pthreads with hwloc support. In this case Nm defines the number of NUMA
regions (typically sockets) on a node which will be utilized by a single MPI rank. By default Nm = 1. If this option is
used the total number of worker-threads per MPI rank is threads*numa. Currently it is always almost better to assign
at least one MPI rank per NUMA region, and leave numa set to its default value of 1. This is because letting a single
process span multiple NUMA regions induces a significant amount of cross NUMA data traffic which is slow.

-log file

98 Chapter 4. Run LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Specify a log file for LAMMPS to write status information to. In one-partition mode, if the switch is not used, LAMMPS
writes to the file log.lammps. If this switch is used, LAMMPS writes to the specified file. In multi-partition mode, if
the switch is not used, a log.lammps file is created with high-level status information. Each partition also writes to a
log.lammps.N file where N is the partition ID. If the switch is specified in multi-partition mode, the high-level logfile
is named “file” and each partition also logs information to a file.N. For both one-partition and multi-partition mode,
if the specified file is “none”, then no log files are created. Using a log command in the input script will override this
setting. Option -plog will override the name of the partition log files file.N.

-mdi ‘multiple flags’

This flag is only recognized and used when LAMMPS has support for the MolSSI Driver Interface (MDI) included as
part of the MDI package. This flag is specific to the MDI library and controls how LAMMPS interacts with MDI. There
are usually multiple flags that have to follow it and those have to be placed in quotation marks. For more information
about how to launch LAMMPS in MDI client/server mode please refer to the MDI Howto.

-mpicolor color
If used, this must be the first command-line argument after the LAMMPS executable name. It is only used when
LAMMPS is launched by an mpirun command which also launches another executable(s) at the same time. (The
other executable could be LAMMPS as well.) The color is an integer value which should be different for each ex-
ecutable (another application may set this value in a different way). LAMMPS and the other executable(s) perform
an MPI_Comm_split() with their own colors to shrink the MPI_COMM_WORLD communication to be the subset of
processors they are actually running on.
Currently, this is only used in LAMMPS to perform client/server messaging with another application. LAMMPS can
act as either a client or server (or both). More details are given on the Howto client/server doc page.
Specifically, this refers to the “mpi/one” mode of messaging provided by the message command and the CSlib library
LAMMPS links with from the lib/message directory. See the message command for more details.

-cite style or file name

Select how and where to output a reminder about citing contributions to the LAMMPS code that were used during the
run. Available keywords for styles are “both”, “none”, “screen”, or “log”. Any other keyword will be considered a
file name to write the detailed citation info to instead of logfile or screen. Default is the “log” style where there is a
short summary in the screen output and detailed citations in BibTeX format in the logfile. The option “both” selects
the detailed output for both, “none”, the short output for both, and “screen” will write the detailed info to the screen
and the short version to the log file. If a dedicated citation info file is requested, the screen and log file output will be
in the short format (same as with “none”).
See the citation page for more details on how to correctly reference and cite LAMMPS.

-nocite
Disable generating a citation reminder (see above) at all.

-package style args . . . .

Invoke the package command with style and args. The syntax is the same as if the command appeared at the top of
the input script. For example “-package gpu 2” or “-pk gpu 2” is the same as package gpu 2 in the input script. The
possible styles and args are documented on the package doc page. This switch can be used multiple times, e.g. to set
options for the INTEL and OPENMP packages which can be used together.

4.2. Command-line options 99

LAMMPS Documentation, Release stable 29Sep2021

Along with the “-suffix” command-line switch, this is a convenient mechanism for invoking accelerator packages and
their options without having to edit an input script.

-partition 8x2 4 5 . . .
Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P processors and this switch is not used,
LAMMPS runs in one partition, i.e. all P processors run a single simulation. If this switch is used, the P proces-
sors are split into separate partitions and each partition runs its own simulation. The arguments to the switch specify
the number of processors in each partition. Arguments of the form MxN mean M partitions, each with N processors.
Arguments of the form N mean a single partition with N processors. The sum of processors in all partitions must equal
P. Thus the command “-partition 8x2 4 5” has 10 partitions and runs on a total of 25 processors.
Running with multiple partitions can be useful for running multi-replica simulations, where each replica runs on one
or a few processors. Note that with MPI installed on a machine (e.g. your desktop), you can run on more (virtual)
processors than you have physical processors.
To run multiple independent simulations from one input script, using multiple partitions, see the Howto multiple page.
World- and universe-style variables are useful in this context.

-plog file
Specify the base name for the partition log files, so partition N writes log information to file.N. If file is none, then no
partition log files are created. This overrides the filename specified in the -log command-line option. This option is
useful when working with large numbers of partitions, allowing the partition log files to be suppressed (-plog none)
or placed in a sub-directory (-plog replica_files/log.lammps) If this option is not used the log file for partition N is
log.lammps.N or whatever is specified by the -log command-line option.

-pscreen file
Specify the base name for the partition screen file, so partition N writes screen information to file.N. If file is “none”,
then no partition screen files are created. This overrides the filename specified in the -screen command-line option.
This option is useful when working with large numbers of partitions, allowing the partition screen files to be suppressed
(-pscreen none) or placed in a sub-directory (-pscreen replica_files/screen). If this option is not used the screen file for
partition N is screen.N or whatever is specified by the -screen command-line option.

-reorder
This option has 2 forms:

-reorder nth N
-reorder custom filename

Reorder the processors in the MPI communicator used to instantiate LAMMPS, in one of several ways. The original
MPI communicator ranks all P processors from 0 to P-1. The mapping of these ranks to physical processors is done by
MPI before LAMMPS begins. It may be useful in some cases to alter the rank order. E.g. to insure that cores within
each node are ranked in a desired order. Or when using the run_style verlet/split command with 2 partitions to insure
that a specific Kspace processor (in the second partition) is matched up with a specific set of processors in the first
partition. See the General tips page for more details.
If the keyword nth is used with a setting N, then it means every Nth processor will be moved to the end of the ranking.
This is useful when using the run_style verlet/split command with 2 partitions via the -partition command-line switch.
The first set of processors will be in the first partition, the second set in the second partition. The -reorder command-line
switch can alter this so that the first N procs in the first partition and one proc in the second partition will be ordered
consecutively, e.g. as the cores on one physical node. This can boost performance. For example, if you use “-reorder
nth 4” and “-partition 9 3” and you are running on 12 processors, the processors will be reordered from

100 Chapter 4. Run LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

0 1 2 3 4 5 6 7 8 9 10 11

to

0 1 2 4 5 6 8 9 10 3 7 11

so that the processors in each partition will be

0 1 2 4 5 6 8 9 10
3 7 11

See the “processors” command for how to insure processors from each partition could then be grouped optimally for
quad-core nodes.
If the keyword is custom, then a file that specifies a permutation of the processor ranks is also specified. The format
of the reorder file is as follows. Any number of initial blank or comment lines (starting with a “#” character) can be
present. These should be followed by P lines of the form:

I J

where P is the number of processors LAMMPS was launched with. Note that if running in multi-partition mode (see the
-partition switch above) P is the total number of processors in all partitions. The I and J values describe a permutation
of the P processors. Every I and J should be values from 0 to P-1 inclusive. In the set of P I values, every proc ID
should appear exactly once. Ditto for the set of P J values. A single I,J pairing means that the physical processor with
rank I in the original MPI communicator will have rank J in the reordered communicator.
Note that rank ordering can also be specified by many MPI implementations, either by environment variables that
specify how to order physical processors, or by config files that specify what physical processors to assign to each MPI
rank. The -reorder switch simply gives you a portable way to do this without relying on MPI itself. See the processors
file command for how to output info on the final assignment of physical processors to the LAMMPS simulation domain.

-restart2data restartfile [remap] datafile keyword value . . .

Convert the restart file into a data file and immediately exit. This is the same operation as if the following 2-line input
script were run:

read_restart restartfile [remap]

write_data datafile keyword value ...

The specified restartfile and/or datafile name may contain the wild-card character “*”. The restartfile name may also
contain the wild-card character “%”. The meaning of these characters is explained on the read_restart and write_data
doc pages. The use of “%” means that a parallel restart file can be read. Note that a filename such as file.* may need to
be enclosed in quotes or the “*” character prefixed with a backslash (“") to avoid shell expansion of the “*” character.
Following restartfile argument, the optional word “remap” may be used. This has the same effect like adding it to a
read_restart command, and operates as explained on its doc page. This is useful if reading the restart file triggers an
error that atoms have been lost. In that case, use of the remap flag should allow the data file to still be produced.
The syntax following restartfile (or remap), namely

datafile keyword value ...

is identical to the arguments of the write_data command. See its page for details. This includes its optional key-
word/value settings.

4.2. Command-line options 101

LAMMPS Documentation, Release stable 29Sep2021

-restart2dump restartfile [remap] group-ID dumpstyle dumpfile arg1 arg2 . . .

Convert the restart file into a dump file and immediately exit. This is the same operation as if the following 2-line input
script were run:

read_restart restartfile [remap]

write_dump group-ID dumpstyle dumpfile arg1 arg2 ...

Note that the specified restartfile and dumpfile names may contain wild-card characters (“*”,”%”) as explained on the
read_restart and write_dump doc pages. The use of “%” means that a parallel restart file and/or parallel dump file
can be read and/or written. Note that a filename such as file.* may need to be enclosed in quotes or the “*” character
prefixed with a backslash (“") to avoid shell expansion of the “*” character.
Note that following the restartfile argument, the optional word “remap” can be used. This has the effect as adding it to
the read_restart command, as explained on its doc page. This is useful if reading the restart file triggers an error that
atoms have been lost. In that case, use of the remap flag should allow the dump file to still be produced.
The syntax following restartfile (or remap), namely

group-ID dumpstyle dumpfile arg1 arg2 ...

is identical to the arguments of the write_dump command. See its page for details. This includes what per-atom fields
are written to the dump file and optional dump_modify settings, including ones that affect how parallel dump files are
written, e.g. the nfile and fileper keywords. See the dump_modify page for details.

-screen file
Specify a file for LAMMPS to write its screen information to. In one-partition mode, if the switch is not used, LAMMPS
writes to the screen. If this switch is used, LAMMPS writes to the specified file instead and you will see no screen
output. In multi-partition mode, if the switch is not used, high-level status information is written to the screen. Each
partition also writes to a screen.N file where N is the partition ID. If the switch is specified in multi-partition mode,
the high-level screen dump is named “file” and each partition also writes screen information to a file.N. For both one-
partition and multi-partition mode, if the specified file is “none”, then no screen output is performed. Option -pscreen
will override the name of the partition screen files file.N.

-skiprun
Insert the command timer timeout 0 every 1 at the beginning of an input file or after a clear command. This has the
effect that the entire LAMMPS input script is processed without executing actual run or minimize and similar commands
(their main loops are skipped). This can be helpful and convenient to test input scripts of long running calculations for
correctness to avoid having them crash after a long time due to a typo or syntax error in the middle or at the end.

-suffix style args

Use variants of various styles if they exist. The specified style can be gpu, intel, kk, omp, opt, or hybrid. These
refer to optional packages that LAMMPS can be built with, as described in Accelerate performance. The “gpu” style
corresponds to the GPU package, the “intel” style to the INTEL package, the “kk” style to the KOKKOS package, the
“opt” style to the OPT package, and the “omp” style to the OPENMP package. The hybrid style is the only style that
accepts arguments. It allows for two packages to be specified. The first package specified is the default and will be used
if it is available. If no style is available for the first package, the style for the second package will be used if available.
For example, “-suffix hybrid intel omp” will use styles from the INTEL package if they are installed and available, but
styles for the OPENMP package otherwise.
Along with the “-package” command-line switch, this is a convenient mechanism for invoking accelerator packages
and their options without having to edit an input script.

102 Chapter 4. Run LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

As an example, all of the packages provide a pair_style lj/cut variant, with style names lj/cut/gpu, lj/cut/intel, lj/cut/kk,
lj/cut/omp, and lj/cut/opt. A variant style can be specified explicitly in your input script, e.g. pair_style lj/cut/gpu. If
the -suffix switch is used the specified suffix (gpu,intel,kk,omp,opt) is automatically appended whenever your input
script command creates a new atom style, pair style, fix, compute, or run style. If the variant version does not exist, the
standard version is created.
For the GPU package, using this command-line switch also invokes the default GPU settings, as if the command
“package gpu 1” were used at the top of your input script. These settings can be changed by using the “-package gpu”
command-line switch or the package gpu command in your script.
For the INTEL package, using this command-line switch also invokes the default INTEL settings, as if the command
“package intel 1” were used at the top of your input script. These settings can be changed by using the “-package
intel” command-line switch or the package intel command in your script. If the OPENMP package is also installed, the
hybrid style with “intel omp” arguments can be used to make the omp suffix a second choice, if a requested style is not
available in the INTEL package. It will also invoke the default OPENMP settings, as if the command “package omp 0”
were used at the top of your input script. These settings can be changed by using the “-package omp” command-line
switch or the package omp command in your script.
For the KOKKOS package, using this command-line switch also invokes the default KOKKOS settings, as if the com-
mand “package kokkos” were used at the top of your input script. These settings can be changed by using the “-package
kokkos” command-line switch or the package kokkos command in your script.
For the OMP package, using this command-line switch also invokes the default OMP settings, as if the command
“package omp 0” were used at the top of your input script. These settings can be changed by using the “-package omp”
command-line switch or the package omp command in your script.
The suffix command can also be used within an input script to set a suffix, or to turn off or back on any suffix setting
made via the command line.

-var name value1 value2 . . .

Specify a variable that will be defined for substitution purposes when the input script is read. This switch can be used
multiple times to define multiple variables. “Name” is the variable name which can be a single character (referenced
as $x in the input script) or a full string (referenced as ${abc}). An index-style variable will be created and populated
with the subsequent values, e.g. a set of filenames. Using this command-line option is equivalent to putting the line
“variable name index value1 value2 . . . ” at the beginning of the input script. Defining an index variable as a command-
line argument overrides any setting for the same index variable in the input script, since index variables cannot be
re-defined.
See the variable command for more info on defining index and other kinds of variables and the Parsing rules page for
more info on using variables in input scripts.

Note: Currently, the command-line parser looks for arguments that start with “-” to indicate new switches. Thus you
cannot specify multiple variable values if any of them start with a “-“, e.g. a negative numeric value. It is OK if the
first value1 starts with a “-“, since it is automatically skipped.

4.2. Command-line options 103

LAMMPS Documentation, Release stable 29Sep2021

4.3 Screen and logfile output

As LAMMPS reads an input script, it prints information to both the screen and a log file about significant actions
it takes to setup a simulation. When the simulation is ready to begin, LAMMPS performs various initializations,
and prints info about the run it is about to perform, including the amount of memory (in MBytes per processor) that
the simulation requires. It also prints details of the initial thermodynamic state of the system. During the run itself,
thermodynamic information is printed periodically, every few timesteps. When the run concludes, LAMMPS prints
the final thermodynamic state and a total run time for the simulation. It also appends statistics about the CPU time and
storage requirements for the simulation. An example set of statistics is shown here:
Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms

Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s

97.0% CPU use with 4 MPI tasks x no OpenMP threads

MPI task timings breakdown:

Section | min time | avg time | max time |%varavg| %total
---------------------------------------------------------------
Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60
Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21
Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97
Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12
Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74
Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02
Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08
Other | | 0.007178 | | | 0.26

Nlocal: 501 ave 508 max 490 min

Histogram: 1 0 0 0 0 0 1 1 0 1
Nghost: 6586.25 ave 6628 max 6548 min
Histogram: 1 0 1 0 0 0 1 0 0 1
Neighs: 177007 ave 180562 max 170212 min
Histogram: 1 0 0 0 0 0 0 1 1 1

Total # of neighbors = 708028

Ave neighs/atom = 353.307
Ave special neighs/atom = 2.34032
Neighbor list builds = 26
Dangerous builds = 0

The first section provides a global loop timing summary. The loop time is the total wall-clock time for the simulation
to run. The Performance line is provided for convenience to help predict how long it will take to run a desired physical
simulation. The CPU use line provides the CPU utilization per MPI task; it should be close to 100% times the number
of OpenMP threads (or 1 of not using OpenMP). Lower numbers correspond to delays due to file I/O or insufficient
thread utilization.

The MPI task section gives the breakdown of the CPU run time (in seconds) into major categories:
• Pair = non-bonded force computations
• Bond = bonded interactions: bonds, angles, dihedrals, impropers
• Kspace = long-range interactions: Ewald, PPPM, MSM

104 Chapter 4. Run LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• Neigh = neighbor list construction

• Comm = inter-processor communication of atoms and their properties
• Output = output of thermodynamic info and dump files
• Modify = fixes and computes invoked by fixes
• Other = all the remaining time
For each category, there is a breakdown of the least, average and most amount of wall time any processor spent on this
category of computation. The “%varavg” is the percentage by which the max or min varies from the average. This is
an indication of load imbalance. A percentage close to 0 is perfect load balance. A large percentage is imbalance. The
final “%total” column is the percentage of the total loop time is spent in this category.
When using the timer full setting, an additional column is added that also prints the CPU utilization in percent. In
addition, when using timer full and the package omp command are active, a similar timing summary of time spent in
threaded regions to monitor thread utilization and load balance is provided. A new Thread timings section is also added,
which lists the time spent in reducing the per-thread data elements to the storage for non-threaded computation. These
thread timings are measured for the first MPI rank only and thus, because the breakdown for MPI tasks can change
from MPI rank to MPI rank, this breakdown can be very different for individual ranks. Here is an example output for
this section:
Thread timings breakdown (MPI rank 0):
Total threaded time 0.6846 / 90.6%
Section | min time | avg time | max time |%varavg| %total
---------------------------------------------------------------
Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18
Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68
Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89
Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70
Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55

The third section above lists the number of owned atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored
per processor. The max and min values give the spread of these values across processors with a 10-bin histogram
showing the distribution. The total number of histogram counts is equal to the number of processors.

The last section gives aggregate statistics (across all processors) for pair-wise neighbors and special neighbors that
LAMMPS keeps track of (see the special_bonds command). The number of times neighbor lists were rebuilt is tal-
lied, as is the number of potentially dangerous rebuilds. If atom movement triggered neighbor list rebuilding (see the
neigh_modify command), then dangerous reneighborings are those that were triggered on the first timestep atom move-
ment was checked for. If this count is non-zero you may wish to reduce the delay factor to insure no force interactions
are missed by atoms moving beyond the neighbor skin distance before a rebuild takes place.

If an energy minimization was performed via the minimize command, additional information is printed, e.g.

Minimization stats:
Stopping criterion = linesearch alpha is zero
Energy initial, next-to-last, final =
-6372.3765206 -8328.46998942 -8328.46998942
Force two-norm initial, final = 1059.36 5.36874
Force max component initial, final = 58.6026 1.46872
Final line search alpha, max atom move = 2.7842e-10 4.0892e-10
Iterations, force evaluations = 701 1516

4.3. Screen and logfile output 105

LAMMPS Documentation, Release stable 29Sep2021

The first line prints the criterion that determined minimization was converged. The next line lists the initial and final
energy, as well as the energy on the next-to-last iteration. The next 2 lines give a measure of the gradient of the energy
(force on all atoms). The 2-norm is the “length” of this 3N-component force vector; the largest component (x, y, or z)
of force (infinity-norm) is also given. Then information is provided about the line search and statistics on how many
iterations and force-evaluations the minimizer required. Multiple force evaluations are typically done at each iteration
to perform a 1d line minimization in the search direction. See the minimize page for more details.

If a kspace_style long-range Coulombics solver that performs FFTs was used during the run (PPPM, Ewald), then
additional information is printed, e.g.

FFT time (% of Kspce) = 0.200313 (8.34477)

FFT Gflps 3d 1d-only = 2.31074 9.19989

The first line is the time spent doing 3d FFTs (several per timestep) and the fraction it represents of the total KSpace
time (listed above). Each 3d FFT requires computation (3 sets of 1d FFTs) and communication (transposes). The total
flops performed is 5Nlog_2(N), where N is the number of points in the 3d grid. The FFTs are timed with and without
the communication and a Gflop rate is computed. The 3d rate is with communication; the 1d rate is without (just the
1d FFTs). Thus you can estimate what fraction of your FFT time was spent in communication, roughly 75% in the
example above.

4.4 Running LAMMPS on Windows

To run a serial (non-MPI) executable, follow these steps:

• Get a command prompt by going to Start->Run. . . , then typing “cmd”.
• Move to the directory where you have your input script, (e.g. by typing: cd “Documents”).
• At the command prompt, type “lmp -in in.file”, where in.file is the name of your LAMMPS input script.
Note that the serial executable includes support for multi-threading parallelization from the styles in the OPENMP
packages. To run with 4 threads, you can type this:

lmp -in in.lj -pk omp 4 -sf omp

For the MPI executable, which allows you to run LAMMPS under Windows in parallel, follow these steps.
Download and install a compatible MPI library binary package:
• for 32-bit Windows: mpich2-1.4.1p1-win-ia32.msi
• for 64-bit Windows: mpich2-1.4.1p1-win-x86-64.msi
The LAMMPS Windows installer packages will automatically adjust your path for the default location of this MPI
package. After the installation of the MPICH2 software, it needs to be integrated into the system. For this you need
to start a Command Prompt in Administrator Mode (right click on the icon and select it). Change into the MPICH2
installation directory, then into the sub-directory bin and execute smpd.exe -install. Exit the command window.
• Get a new, regular command prompt by going to Start->Run. . . , then typing “cmd”.
• Move to the directory where you have your input file (e.g. by typing: cd “Documents”).
Then you can run the executable in serial like in the example above or in parallel using MPI with one of the following
commands:

106 Chapter 4. Run LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

mpiexec -localonly 4 lmp -in in.file

mpiexec -np 4 lmp -in in.file

where in.file is the name of your LAMMPS input script. For the latter case, you may be prompted to enter the password
that you set during installation of the MPI library software.
In this mode, output may not immediately show up on the screen, so if your input script takes a long time to execute,
you may need to be patient before the output shows up.
The parallel executable can also run on a single processor by typing something like this:

lmp -in in.lj

Note that the parallel executable also includes OpenMP multi-threading, which can be combined with MPI using some-
thing like:

mpiexec -localonly 2 lmp -in in.lj -pk omp 2 -sf omp

4.4. Running LAMMPS on Windows 107

LAMMPS Documentation, Release stable 29Sep2021

108 Chapter 4. Run LAMMPS

 CHAPTER

FIVE

COMMANDS

These pages describe how a LAMMPS input script is formatted and the commands in it are used to define a LAMMPS
simulation.

5.1 LAMMPS input scripts

LAMMPS executes calculations by reading commands from a input script (text file), one line at a time. When the input
script ends, LAMMPS exits. This is different from programs that read and process the entire input before starting a
calculation.
Each command causes LAMMPS to take some immediate action without regard for any commands that may be pro-
cessed later. Commands may set an internal variable, read in a file, or run a simulation. These actions can be grouped
into three categories:
a) commands that change a global setting (examples: timestep, newton, echo, log, thermo, restart),
b) commands that add, modify, remove, or replace “styles” that are executed during a “run” (examples: pair_style,
fix, compute, dump, thermo_style, pair_modify), and
c) commands that execute a “run” or perform some other computation or operation (examples: print, run, minimize,
temper, write_dump, rerun, read_data, read_restart)
Commands in category a) have default settings, which means you only need to use the command if you wish to change
the defaults.
In many cases, the ordering of commands in an input script is not important, but can have consequences when the
global state is changed between commands in the c) category. The following rules apply:
(1) LAMMPS does not read your entire input script and then perform a simulation with all the settings. Rather,
the input script is read one line at a time and each command takes effect when it is read. Thus this sequence of
commands:

timestep 0.5
run 100
run 100

does something different than this sequence:

run 100
timestep 0.5
run 100

109
LAMMPS Documentation, Release stable 29Sep2021

In the first case, the specified timestep (0.5 fs) is used for two simulations of 100 timesteps each. In the second
case, the default timestep (1.0 fs) is used for the first 100 step simulation and a 0.5 fs timestep is used for the
second one.
(2) Some commands are only valid when they follow other commands. For example you cannot set the temperature
of a group of atoms until atoms have been defined and a group command is used to define which atoms belong
to the group.
(3) Sometimes command B will use values that can be set by command A. This means command A must precede
command B in the input script if it is to have the desired effect. For example, the read_data command initial-
izes the system by setting up the simulation box and assigning atoms to processors. If default values are not
desired, the processors and boundary commands need to be used before read_data to tell LAMMPS how to map
processors to the simulation box.
Many input script errors are detected by LAMMPS and an ERROR or WARNING message is printed. The Errors
page gives more information on what errors mean. The documentation for each command lists restrictions on how the
command can be used.
You can use the -skiprun command line flag to have LAMMPS skip the execution of any “run”, “minimize”, or similar
commands to check the entire input for correct syntax to avoid crashes on typos or syntax errors in long runs.

5.2 Parsing rules for input scripts

Each non-blank line in the input script is treated as a command. LAMMPS commands are case sensitive. Command
names are lower-case, as are specified command arguments. Upper case letters may be used in file names or user-chosen
ID strings.
Here are 6 rules for how each line in the input script is parsed by LAMMPS:
1. If the last printable character on the line is a “&” character, the command is assumed to continue on the next line.
The next line is concatenated to the previous line by removing the “&” character and line break. This allows long
commands to be continued across two or more lines. See the discussion of triple quotes in 6 for how to continue
a command across multiple line without using “&” characters.
2. All characters from the first “#” character onward are treated as comment and discarded. The exception to
this rule is described in 6. Note that a comment after a trailing “&” character will prevent the command from
continuing on the next line. Also note that for multi-line commands a single leading “#” will comment out the
entire command.

# this is a comment
timestep 1.0 # this is also a comment

3. The line is searched repeatedly for $ characters, which indicate variables that are replaced with a text string. The
exception to this rule is described in 6.
If the $ is followed by text in curly brackets ‘{}’, then the variable name is the text inside the curly brackets. If
no curly brackets follow the $, then the variable name is the single character immediately following the $. Thus
${myTemp} and $x refer to variables named “myTemp” and “x”, while “$xx” will be interpreted as a variable
named “x” followed by an “x” character.
How the variable is converted to a text string depends on what style of variable it is; see the variable page for
details. It can be a variable that stores multiple text strings, and return one of them. The returned text string
can be multiple “words” (space separated) which will then be interpreted as multiple arguments in the input
command. The variable can also store a numeric formula which will be evaluated and its numeric result returned
as a string.

110 Chapter 5. Commands

 LAMMPS Documentation, Release stable 29Sep2021

As a special case, if the $ is followed by parenthesis “()”, then the text inside the parenthesis is treated as an
“immediate” variable and evaluated as an equal-style variable. This is a way to use numeric formulas in an input
script without having to assign them to variable names. For example, these 3 input script lines:

variable X equal (xlo+xhi)/2+sqrt(v_area)

region 1 block $X 2 INF INF EDGE EDGE
variable X delete

can be replaced by:

region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE

so that you do not have to define (or discard) a temporary variable, “X” in this case.
Additionally, the “immediate” variable expression may be followed by a colon, followed by a C-style format
string, e.g. “:%f” or “:%.10g”. The format string must be appropriate for a double-precision floating-point
value. The format string is used to output the result of the variable expression evaluation. If a format string is
not specified a high-precision “%.20g” is used as the default.
This can be useful for formatting print output to a desired precision:

print "Final energy per atom: $(pe/atoms:%10.3f) eV/atom"

Note that neither the curly-bracket or immediate form of variables can contain nested $ characters for other
variables to substitute for. Thus you may NOT do this:

variable a equal 2
variable b2 equal 4
print "B2 = ${b$a}"

Nor can you specify an expression like “$($x-1.0)” for an immediate variable, but you could use $(v_x-1.0),
since the latter is valid syntax for an equal-style variable.
See the variable command for more details of how strings are assigned to variables and evaluated, and how they
can be used in input script commands.
4. The line is broken into “words” separated by white-space (tabs, spaces). Note that words can thus contain letters,
digits, underscores, or punctuation characters.
5. The first word is the command name. All successive words in the line are arguments.
6. If you want text with spaces to be treated as a single argument, it can be enclosed in either single or double or
triple quotes. A long single argument enclosed in single or double quotes can span multiple lines if the “&”
character is used, as described above. When the lines are concatenated together (and the “&” characters and line
breaks removed), the text will become a single line. If you want multiple lines of an argument to retain their line
breaks, the text can be enclosed in triple quotes, in which case “&” characters are not needed. For example:

print "Volume = $v"

print 'Volume = $v'
if "${steps} > 1000" then quit
variable a string "red green blue &
purple orange cyan"
print """
System volume = $v
System temperature = $t
"""

5.2. Parsing rules for input scripts 111

LAMMPS Documentation, Release stable 29Sep2021

In each case, the single, double, or triple quotes are removed when the single argument they enclose is stored
internally.
See the dump modify format, print, if , and python commands for examples.
A “#” or “$” character that is between quotes will not be treated as a comment indicator in 2 or substituted for
as a variable in 3.

Note: If the argument is itself a command that requires a quoted argument (e.g. using a print command as part of an
if or run every command), then single, double, or triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is allowed, but that should be sufficient for most use
cases.

ASCII versus UTF-8

LAMMPS expects and processes 7-bit ASCII format text internally. Many modern environments use UTF-8 encoding,
which is a superset of the 7-bit ASCII character table and thus mostly compatible. However, there are several non-
ASCII characters that can look very similar to their ASCII equivalents or are invisible (so they look like a blank), but
are encoded differently. Web browsers, PDF viewers, document editors are known to sometimes replace one with the
other for a better looking output. However, that can lead to problems, for instance, when using cut-n-paste of input file
examples from web pages, or when using a document editor (not a dedicated plain text editor) for writing LAMMPS
inputs. LAMMPS will try to detect this and substitute the non-ASCII characters with their ASCII equivalents where
known. There also is going to be a warning printed, if this occurs. It is recommended to avoid such characters altogether
in LAMMPS input, data and potential files. The replacement tables are likely incomplete and dependent on users
reporting problems processing correctly looking input containing UTF-8 encoded non-ASCII characters.

5.3 Input script structure

This page describes the structure of a typical LAMMPS input script. The examples directory in the LAMMPS distri-
bution contains many sample input scripts; it is discussed on the Examples doc page.
A LAMMPS input script typically has 4 parts:
1. Initialization
2. System definition
3. Simulation settings
4. Run a simulation
The last 2 parts can be repeated as many times as desired. I.e. run a simulation, change some settings, run some more,
etc. Each of the 4 parts is now described in more detail. Remember that almost all commands need only be used if a
non-default value is desired.

112 Chapter 5. Commands

 LAMMPS Documentation, Release stable 29Sep2021

5.3.1 Initialization

Set parameters that need to be defined before atoms are created or read-in from a file.
The relevant commands are units, dimension, newton, processors, boundary, atom_style, atom_modify.
If force-field parameters appear in the files that will be read, these commands tell LAMMPS what kinds of force fields
are being used: pair_style, bond_style, angle_style, dihedral_style, improper_style.

5.3.2 System definition

There are 3 ways to define the simulation cell and reserve space for force field info and fill it with atoms in LAMMPS.
Read them in from (1) a data file or (2) a restart file via the read_data or read_restart commands, respectively. These
files can also contain molecular topology information. Or (3) create a simulation cell and fill it with atoms on a lattice
(with no molecular topology), using these commands: lattice, region, create_box, create_atoms or read_dump.
The entire set of atoms can be duplicated to make a larger simulation using the replicate command.

5.3.3 Simulation settings

Once atoms and molecular topology are defined, a variety of settings can be specified: force field coefficients, simula-
tion parameters, output options, and more.
Force field coefficients are set by these commands (they can also be set in the read-in files): pair_coeff , bond_coeff ,
angle_coeff , dihedral_coeff , improper_coeff , kspace_style, dielectric, special_bonds.
Various simulation parameters are set by these commands: neighbor, neigh_modify, group, timestep, reset_timestep,
run_style, min_style, min_modify.
Fixes impose a variety of boundary conditions, time integration, and diagnostic options. The fix command comes in
many flavors.
Various computations can be specified for execution during a simulation using the compute, compute_modify, and
variable commands.
Output options are set by the thermo, dump, and restart commands.

5.3.4 Run a simulation

A molecular dynamics simulation is run using the run command. Energy minimization (molecular statics) is per-
formed using the minimize command. A parallel tempering (replica-exchange) simulation can be run using the temper
command.

5.4 Commands by category

This page lists most of the LAMMPS commands, grouped by category. The General commands page lists all general
commands alphabetically. Style options for entries like fix, compute, pair etc. have their own pages where they are
listed alphabetically.

5.4. Commands by category 113

LAMMPS Documentation, Release stable 29Sep2021

5.4.1 Initialization:

newton package processors suffix units

5.4.2 Setup simulation box:

boundary box change_box create_box

dimension lattice region

5.4.3 Setup atoms:

atom_modify atom_style balance create_atoms

create_bonds delete_atoms delete_bonds displace_atoms
group mass molecule read_data
read_dump read_restart replicate set
velocity

5.4.4 Force fields:

angle_coeff angle_style bond_coeff bond_style

bond_write dielectric dihedral_coeff dihedral_style
improper_coeff improper_style kspace_modify kspace_style
pair_coeff pair_modify pair_style pair_write
special_bonds

5.4.5 Settings:

comm_modify comm_style info min_modify

min_style neigh_modify neighbor partition
reset_timestep run_style timer timestep

5.4.6 Operations within timestepping (fixes) and diagnostics (computes):

compute compute_modify fix fix_modify

uncompute unfix

114 Chapter 5. Commands

 LAMMPS Documentation, Release stable 29Sep2021

5.4.7 Output:

dump image dump movie dump dump_modify

restart thermo thermo_modify thermo_style
undump write_coeff write_data write_dump
write_restart

5.4.8 Actions:

minimize neb neb_spin prd rerun run

tad temper

5.4.9 Input script control:

clear echo if include info jump label

log next print python quit shell variable

General commands Fix styles Compute styles

Pair styles Bond styles Angle styles
Dihedral styles Improper styles KSpace styles

5.5 General commands

An alphabetic list of all general LAMMPS commands.

5.5. General commands 115

LAMMPS Documentation, Release stable 29Sep2021

angle_coeff angle_style atom_modify atom_style balance

bond_coeff bond_style bond_write boundary box
change_box clear comm_modify comm_style compute
compute_modify create_atoms create_bonds create_box delete_atoms
delete_bonds dielectric dihedral_coeff dihedral_style dimension
displace_atoms dump dump_modify dynamical_matrix echo
fix fix_modify group group2ndx hyper
if improper_coeff improper_style include info
jump kim kspace_modify kspace_style label
lattice log mass mdi/engine message
minimize min_modify min_style min_style spin molecule
ndx2group neb neb/spin neigh_modify neighbor
newton next package pair_coeff pair_modify
pair_style pair_write partition plugin prd
print processors python quit read_data
read_dump read_restart region replicate rerun
reset_atom_ids reset_mol_ids reset_timestep restart run
run_style server set shell special_bonds
suffix tad temper temper/grem temper/npt
thermo thermo_modify thermo_style third_order timer
timestep uncompute undump unfix units
variable velocity write_coeff write_data write_dump
write_restart

General commands Fix styles Compute styles

Pair styles Bond styles Angle styles
Dihedral styles Improper styles KSpace styles

5.6 Fix commands

An alphabetic list of all LAMMPS fix commands. Some styles have accelerated versions. This is indicated by additional
letters in parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

accelerate/cos adapt adapt/fep addforce addtorque

append/atoms atc atom/swap ave/atom ave/chunk
ave/correlate ave/correlate/long ave/histo ave/histo/weight ave/time
aveforce balance brownian brownian/asphere brownian/sphere
bocs bond/break bond/create bond/create/angle bond/react
bond/swap box/relax charge/regulation client/md cmap
colvars controller deform (k) deposit dpd/energy (k)
drag drude drude/transform/direct drude/transform/inverse dt/reset
edpd/source efield ehex electron/stopping electron/stopping/fit
enforce2d (k) eos/cv eos/table eos/table/rx (k) evaporate
external ffl filter/corotate flow/gauss freeze (k)
gcmc gld gle gravity (ko) grem
halt heat hyper/global hyper/local imd
indent ipi langevin (k) langevin/drude langevin/eff
langevin/spin latte lb/fluid lb/momentum lb/pc
continues on next page

116 Chapter 5. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Table 1 – continued from previous page

lb/rigid/pc/sphere lb/viscous lineforce manifoldforce mdi/engine
meso/move momentum (k) momentum/chunk move mscg
msst mvv/dpd mvv/edpd mvv/tdpd neb
neb/spin nph (ko) nph/asphere (o) nph/body nph/eff
nph/sphere (o) nphug npt (giko) npt/asphere (o) npt/body
npt/cauchy npt/eff npt/sphere (o) npt/uef numdiff
nve (giko) nve/asphere (gi) nve/asphere/noforce nve/awpmd nve/body
nve/dot nve/dotc/langevin nve/eff nve/limit nve/line
nve/manifold/rattle nve/noforce nve/sphere (ko) nve/spin nve/tri
nvk nvt (giko) nvt/asphere (o) nvt/body nvt/eff
nvt/manifold/rattle nvt/sllod (iko) nvt/sllod/eff nvt/sphere (o) nvt/uef
oneway orient/bcc orient/fcc orient/eco pafi
pair/tracker phonon pimd planeforce plumed
poems polarize/bem/gmres polarize/bem/icc polarize/functional pour
precession/spin press/berendsen print propel/self property/atom (k)
python/invoke python/move qbmsst qeq/comb (o) qeq/dynamic
qeq/fire qeq/point qeq/reaxff (ko) qeq/shielded qeq/slater
qmmm qtb rattle reaxff/bonds (k) reaxff/species (k)
recenter restrain rhok rigid (o) rigid/meso
rigid/nph (o) rigid/nph/small rigid/npt (o) rigid/npt/small rigid/nve (o)
rigid/nve/small rigid/nvt (o) rigid/nvt/small rigid/small (o) rx (k)
saed/vtk setforce (k) setforce/spin shake (k) shardlow (k)
smd smd/adjust_dt smd/integrate_tlsph smd/integrate_ulsph smd/move_tri_surf
smd/setvel smd/wall_surface sph sph/stationary spring
spring/chunk spring/rg spring/self srd store/force
store/state tdpd/source temp/berendsen temp/csld temp/csvr
temp/rescale temp/rescale/eff tfmc tgnpt/drude tgnvt/drude
thermal/conductivity ti/spring tmd ttm ttm/grid
ttm/mod tune/kspace vector viscosity viscous
wall/body/polygon wall/body/polyhedron wall/colloid wall/ees wall/gran
wall/gran/region wall/harmonic wall/lj1043 wall/lj126 wall/lj93 (k)
wall/morse wall/piston wall/reflect (k) wall/reflect/stochastic wall/region
wall/region/ees wall/srd widom

General commands Fix styles Compute styles

Pair styles Bond styles Angle styles
Dihedral styles Improper styles KSpace styles

5.6. Fix commands 117

LAMMPS Documentation, Release stable 29Sep2021

5.7 Compute commands

An alphabetic list of all LAMMPS compute commands. Some styles have accelerated versions. This is indicated by
additional letters in parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

ackland/atom adf aggregate/atom angle angle/local

angmom/chunk basal/atom body/local bond bond/local
centro/atom centroid/stress/atom chunk/atom chunk/spread/atom cluster/atom
cna/atom cnp/atom com com/chunk contact/atom
coord/atom (k) damage/atom dihedral dihedral/local dilatation/atom
dipole dipole/chunk displace/atom dpd dpd/atom
edpd/temp/atom efield/atom entropy/atom erotate/asphere erotate/rigid
erotate/sphere erotate/sphere/atom event/displace fabric fep
force/tally fragment/atom global/atom group/group gyration
gyration/chunk gyration/shape gyra- heat/flux heat/flux/tally
tion/shape/chunk
heat/flux/virial/tally hexorder/atom hma improper improper/local
inertia/chunk ke ke/atom ke/atom/eff ke/eff
ke/rigid mesont mliap momentum msd
msd/chunk msd/nongauss omega/chunk orientorder/atom pair
(k)
pair/local pe pe/atom pe/mol/tally pe/tally
plasticity/atom pressure pressure/cylinder pressure/uef property/atom
property/chunk property/local ptm/atom rdf reduce
reduce/chunk reduce/region rigid/local saed slice
smd/contact/radius smd/damage smd/hourglass/error smd/internal/energy smd/plastic/strain
smd/plastic/strain/rate smd/rho smd/tlsph/defgrad smd/tlsph/dt smd/tlsph/num/neighs
smd/tlsph/shape smd/tlsph/strain smd/tlsph/strain/rate smd/tlsph/stress smd/triangle/vertices
smd/ulsph/effm smd/ulsph/num/neighs smd/ulsph/strain smd/ulsph/strain/rate smd/ulsph/stress
smd/vol snap sna/atom snad/atom snav/atom
sph/e/atom sph/rho/atom sph/t/atom spin stress/atom
stress/mop stress/mop/profile stress/tally tdpd/cc/atom temp (k)
temp/asphere temp/body temp/chunk temp/com temp/cs
temp/deform (k) temp/deform/eff temp/drude temp/eff temp/partial
temp/profile temp/ramp temp/region temp/region/eff temp/rotate
temp/sphere temp/uef ti torque/chunk vacf
vcm/chunk viscosity/cos voronoi/atom xrd

General commands Fix styles Compute styles

Pair styles Bond styles Angle styles
Dihedral styles Improper styles KSpace styles

118 Chapter 5. Commands

 LAMMPS Documentation, Release stable 29Sep2021

5.8 Pair_style potentials

All LAMMPS pair_style commands. Some styles have accelerated versions. This is indicated by additional letters in
parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

none zero hybrid (k) hybrid/overlay (k)

hybrid/scaled kim list tracker

adp (o) agni (o) airebo (io) airebo/morse (io)

atm awpmd/cut beck (go) body/nparticle
body/rounded/polygon body/rounded/polyhedron bop born (go)
born/coul/dsf born/coul/dsf/cs born/coul/long (go) born/coul/long/cs (g)
born/coul/msm (o) born/coul/wolf (go) born/coul/wolf/cs (g) brownian (o)
brownian/poly (o) buck (giko) buck/coul/cut (giko) buck/coul/long (giko)
buck/coul/long/cs buck/coul/msm (o) buck/long/coul/long (o) buck/mdf
buck6d/coul/gauss/dsf buck6d/coul/gauss/long colloid (go) comb (o)
comb3 cosine/squared coul/cut (gko) coul/cut/dielectric
coul/cut/global (o) coul/cut/soft (o) coul/debye (gko) coul/diel (o)
coul/dsf (gko) coul/exclude coul/long (gko) coul/long/cs (g)
coul/long/dielectric coul/long/soft (o) coul/msm (o) coul/slater/cut
coul/slater/long coul/shield coul/streitz coul/tt
coul/wolf (ko) coul/wolf/cs dpd (gio) dpd/fdt
dpd/ext dpd/ext/tstat dpd/fdt/energy (k) dpd/tstat (go)
dsmc e3b drip eam (gikot)
eam/alloy (gikot) eam/cd eam/cd/old eam/fs (gikot)
eam/he edip (o) edip/multi edpd
eff/cut eim (o) exp6/rx (k) extep
gauss (go) gauss/cut (o) gayberne (gio) gran/hertz/history (o)
gran/hooke (o) gran/hooke/history (ko) granular gw
gw/zbl hbond/dreiding/lj (o) hbond/dreiding/morse (o) hdnnp
ilp/graphene/hbn kolmogorov/crespi/full kolmogorov/crespi/z lcbop
lebedeva/z lennard/mdf line/lj lj/charmm/coul/charmm (giko)
lj/charmm/coul/charmm/implicit (ko) lj/charmm/coul/long (gikot) lj/charmm/coul/long/soft (o) lj/charmm/coul/msm (o)
lj/charmmfsw/coul/charmmfsh lj/charmmfsw/coul/long lj/class2 (gko) lj/class2/coul/cut (ko)
lj/class2/coul/cut/soft lj/class2/coul/long (gko) lj/class2/coul/long/cs lj/class2/coul/long/soft
lj/class2/soft lj/cubic (go) lj/cut (gikot) lj/cut/coul/cut (gko)
lj/cut/coul/cut/dielectric (o) lj/cut/coul/cut/soft (o) lj/cut/coul/debye (gko) lj/cut/coul/debye/dielectric
lj/cut/coul/dsf (gko) lj/cut/coul/long (gikot) lj/cut/coul/long/cs lj/cut/coul/long/dielectric (o)
lj/cut/coul/long/soft (o) lj/cut/coul/msm (go) lj/cut/coul/msm/dielectric lj/cut/coul/wolf (o)
lj/cut/dipole/cut (go) lj/cut/dipole/long (g) lj/cut/dipole/sf (go) lj/cut/soft (o)
lj/cut/thole/long (o) lj/cut/tip4p/cut (o) lj/cut/tip4p/long (got) lj/cut/tip4p/long/soft (o)
lj/expand (gko) lj/expand/coul/long (g) lj/gromacs (gko) lj/gromacs/coul/gromacs (ko)
lj/long/coul/long (iot) lj/long/coul/long/dielectric lj/long/dipole/long lj/long/tip4p/long (o)
lj/mdf lj/relres (o) lj/sdk (gko) lj/sdk/coul/long (go)
lj/sdk/coul/msm (o) lj/sf/dipole/sf (go) lj/smooth (go) lj/smooth/linear (o)
lj/switch3/coulgauss/long lj96/cut (go) local/density lubricate (o)
lubricate/poly (o) lubricateU lubricateU/poly mdpd
mdpd/rhosum meam meam/spline (o) meam/sw/spline
mesocnt mesont/tpm mgpt mie/cut (g)
mliap mm3/switch3/coulgauss/long momb morse (gkot)
continues on next page

5.8. Pair_style potentials 119

LAMMPS Documentation, Release stable 29Sep2021

Table 2 – continued from previous page

morse/smooth/linear (o) morse/soft multi/lucy multi/lucy/rx (k)
nb3b/harmonic nm/cut (o) nm/cut/coul/cut (o) nm/cut/coul/long (o)
oxdna/coaxstk oxdna/excv oxdna/hbond oxdna/stk
oxdna/xstk oxdna2/coaxstk oxdna2/dh oxdna2/excv
oxdna2/hbond oxdna2/stk oxdna2/xstk oxrna2/excv
oxrna2/hbond oxrna2/dh oxrna2/stk oxrna2/xstk
oxrna2/coaxstk pace peri/eps peri/lps (o)
peri/pmb (o) peri/ves polymorphic python
quip rann reaxff (ko) rebo (io)
resquared (go) sdpd/taitwater/isothermal smd/hertz smd/tlsph
smd/tri_surface smd/ulsph smtbq snap (k)
soft (go) sph/heatconduction sph/idealgas sph/lj
sph/rhosum sph/taitwater sph/taitwater/morris spin/dipole/cut
spin/dipole/long spin/dmi spin/exchange spin/exchange/biquadratic
spin/magelec spin/neel srp sw (giko)
table (gko) table/rx (k) tdpd tersoff (giko)
tersoff/mod (gko) tersoff/mod/c (o) tersoff/table (o) tersoff/zbl (gko)
thole tip4p/cut (o) tip4p/long (o) tip4p/long/soft (o)
tri/lj ufm (got) vashishta (gko) vashishta/table (o)
wf/cut yukawa (gko) yukawa/colloid (go) zbl (gko)

General commands Fix styles Compute styles

Pair styles Bond styles Angle styles
Dihedral styles Improper styles KSpace styles

5.9 Bond_style potentials

All LAMMPS bond_style commands. Some styles have accelerated versions. This is indicated by additional letters in
parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

none zero hybrid

class2 (ko) fene (iko) fene/expand (o) gaussian

gromos (o) harmonic (iko) harmonic/shift (o) harmonic/shift/cut (o)
mm3 morse (o) nonlinear (o) oxdna/fene
oxdna2/fene oxrna2/fene quartic (o) special
table (o)

5.10 Angle_style potentials

All LAMMPS angle_style commands. Some styles have accelerated versions. This is indicated by additional letters in
parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

120 Chapter 5. Commands

 LAMMPS Documentation, Release stable 29Sep2021

none zero hybrid

charmm (iko) class2 (ko) class2/p6 cosine (ko)

cosine/buck6d cosine/delta (o) cosine/periodic (o) cosine/shift
(o)
cosine/shift/exp cosine/squared cross dipole (o)
(o) (o)
fourier (o) fourier/simple (o) gaussian - multicentered Gaussian-based angle poten- harmonic
tial (iko)
mm3 quartic (o) sdk (o) table (o)

5.11 Dihedral_style potentials

All LAMMPS dihedral_style commands. Some styles have accelerated versions. This is indicated by additional letters
in parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

none zero hybrid

charmm (iko) charmmfsw class2 (ko) cosine/shift/exp (o)

fourier (io) harmonic (iko) helix (o) multi/harmonic (o)
nharmonic (o) opls (iko) quadratic (o) spherical
table (o) table/cut

5.12 Improper_style potentials

All LAMMPS improper_style commands. Some styles have accelerated versions. This is indicated by additional letters
in parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

none zero hybrid

class2 (ko) cossq (o) cvff (io) distance

distharm fourier (o) harmonic (iko) inversion/harmonic
ring (o) sqdistharm umbrella (o)

General commands Fix styles Compute styles

Pair styles Bond styles Angle styles
Dihedral styles Improper styles KSpace styles

5.11. Dihedral_style potentials 121

LAMMPS Documentation, Release stable 29Sep2021

5.13 KSpace solvers

All LAMMPS kspace_style solvers. Some styles have accelerated versions. This is indicated by additional letters in
parenthesis: g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT.

ewald (o) ewald/disp ewald/disp/dipole ewald/dipole

ewald/dipole/spin msm (o) msm/cg (o) msm/dielectric
pppm (giko) pppm/cg (o) pppm/dipole pppm/dipole/spin
pppm/dielectric pppm/disp (io) pppm/disp/tip4p (o) pppm/disp/dielectric
pppm/stagger pppm/tip4p (o) pppm/dielectric scafacos

5.14 Removed commands and packages

This page lists LAMMPS commands and packages that have been removed from the distribution and provides sugges-
tions for alternatives or replacements. LAMMPS has special dummy styles implemented, that will stop LAMMPS and
print a suitable error message in most cases, when a style/command is used that has been removed.

5.14.1 Fix ave/spatial and fix ave/spatial/sphere

The fixes ave/spatial and ave/spatial/sphere have been removed from LAMMPS since they were superseded by the more
general and extensible “chunk infrastructure”. Here the system is partitioned in one of many possible ways through
the compute chunk/atom command and then averaging is done using fix ave/chunk. Please refer to the chunk HOWTO
section for an overview.

5.14.2 Reset_ids command

The reset_ids command has been renamed to reset_atom_ids.

5.14.3 MEAM package

The MEAM package in Fortran has been replaced by a C++ implementation. The code in the MEAM package is a
translation of the Fortran code of MEAM into C++, which removes several restrictions (e.g. there can be multiple
instances in hybrid pair styles) and allows for some optimizations leading to better performance. The pair style meam
has the exact same syntax.

5.14.4 REAX package

The REAX package has been removed since it was superseded by the REAXFF package. The REAXFF package
has been tested to yield equivalent results to the REAX package, offers better performance, supports OpenMP multi-
threading via OPENMP, and GPU and threading parallelization through KOKKOS. The new pair styles are not syntax
compatible with the removed reax pair style, so input files will have to be adapted.

122 Chapter 5. Commands

 LAMMPS Documentation, Release stable 29Sep2021

5.14.5 USER-CUDA package

The USER-CUDA package had been removed, since it had been unmaintained for a long time and had known bugs
and problems. Significant parts of the design were transferred to the KOKKOS package, which has similar perfor-
mance characteristics on NVIDIA GPUs. Both, the KOKKOS and the GPU package are maintained and allow running
LAMMPS with GPU acceleration.

5.14.6 restart2data tool

The functionality of the restart2data tool has been folded into the LAMMPS executable directly instead of having a
separate tool. A combination of the commands read_restart and write_data can be used to the same effect. For added
convenience this conversion can also be triggered by command line flags

5.14. Removed commands and packages 123

LAMMPS Documentation, Release stable 29Sep2021

124 Chapter 5. Commands

 CHAPTER

SIX

OPTIONAL PACKAGES

This section gives an overview of the optional packages that extend LAMMPS functionality. Packages are groups of
files that enable a specific set of features. For example, force fields for molecular systems or rigid-body constraints are
in packages. You can see the list of all packages and “make” commands to manage them by typing “make package”
from within the src directory of the LAMMPS distribution. The Build package page gives general info on how to install
and un-install packages as part of the LAMMPS build process.

6.1 Available Packages

This is the list of packages included in LAMMPS. The link for each package name gives more details.
Packages are supported by either the LAMMPS developers or the contributing authors and written in a syntax and style
consistent with the rest of LAMMPS.
The “Example” column is a sub-directory in the examples directory of the distribution which has an input script
that uses the package. E.g. “peptide” refers to the examples/peptide directory; PACKAGES/atc refers to the exam-
ples/PACKAGES/atc directory. The “Library” column indicates whether an extra library is needed to build and use the
package:
• no = no library
• sys = system library: you likely have it on your machine
• int = internal library: provided with LAMMPS, but you may need to build it
• ext = external library: you will need to download and install it on your machine

Package Description Doc page Example

ADIOS dump output via ADIOS dump adios PACKAGES/
ASPHERE aspherical particle models Howto spherical ellipse
ATC Atom-to-Continuum coupling fix atc PACKAGES/
AWPMD wave packet MD pair_style awpmd/cut PACKAGES/
BOCS BOCS bottom up coarse graining fix bocs PACKAGES/
BODY body-style particles Howto body body
BROWNIAN Brownian dynamics, self-propelled particles fix brownian, fix propel/self PACKAGES/
CG-DNA coarse-grained DNA force fields src/CG-DNA/README PACKAGES/
CG-SDK SDK coarse-graining model pair_style lj/sdk PACKAGES/
CLASS2 class 2 force fields pair_style lj/class2 n/a
COLLOID colloidal particles atom_style colloid colloid
COLVARS collective variables library fix colvars PACKAGES/
COMPRESS I/O compression dump */gz n/a
CORESHELL adiabatic core/shell model Howto coreshell coreshell
co

125
LAMMPS Documentation, Release stable 29Sep2021

Table 1 – continued from previous page

Package Description Doc page Example
DIELECTRIC dielectric boundary solvers and force styles compute efield/atom PACKAGES/
DIFFRACTION virtual x-ray and electron diffraction compute xrd PACKAGES/
DIPOLE point dipole particles pair_style lj/. . . /dipole dipole
DPD-BASIC basic DPD models pair_styles dpd dpd/tstat dpd/ext dpd/ext/tstat PACKAGES/
DPD-MESO mesoscale DPD models pair_style edpd PACKAGES/
DPD-REACT reactive dissipative particle dynamics src/DPD-REACT/README PACKAGES/
DPD-SMOOTH smoothed dissipative particle dynamics src/DPD-SMOOTH/README PACKAGES/
DRUDE Drude oscillators Howto drude PACKAGES/
EFF electron force field pair_style eff/cut PACKAGES/
EXTRA-COMPUTE additional compute styles compute n/a
EXTRA-DUMP additional dump styles dump n/a
EXTRA-FIX additional fix styles fix n/a
EXTRA-MOLECULE additional molecular styles molecular styles n/a
EXTRA-PAIR additional pair styles pair_style n/a
FEP free energy perturbation compute fep PACKAGES/
GPU GPU-enabled styles Section gpu Benchmarks
GRANULAR granular systems Howto granular pour
H5MD dump output via HDF5 dump h5md n/a
INTEL optimized Intel CPU and KNL styles Speed intel Benchmarks
INTERLAYER Inter-layer pair potentials several pair styles PACKAGES/
KIM OpenKIM wrapper pair_style kim kim
KOKKOS Kokkos-enabled styles Speed kokkos Benchmarks
KSPACE long-range Coulombic solvers kspace_style peptide
LATBOLTZ Lattice Boltzmann fluid fix lb/fluid PACKAGES/
LATTE quantum DFTB forces via LATTE fix latte latte
MACHDYN smoothed Mach dynamics SMD User Guide PACKAGES/
MANIFOLD motion on 2d surfaces fix manifoldforce PACKAGES/
MANYBODY many-body potentials pair_style tersoff shear
MC Monte Carlo options fix gcmc n/a
MDI client-server coupling MDI Howto PACKAGES/
MEAM modified EAM potential (C++) pair_style meam meam
MESONT mesoscopic tubular potential model pair styles mesont/tpm, mesocnt PACKAGES/
MESSAGE client/server messaging message message
MGPT fast MGPT multi-ion potentials pair_style mgpt PACKAGES/
MISC miscellaneous single-file commands n/a no
ML-HDNNP High-dimensional neural network potentials pair_style hdnnp PACKAGES/
ML-IAP multiple machine learning potentials pair_style mliap mliap
ML-PACE Atomic Cluster Expansion potential pair pace PACKAGES/
ML-QUIP QUIP/libatoms interface pair_style quip PACKAGES/
ML-RANN Pair style for RANN potentials pair rann PACKAGES/
ML-SNAP quantum-fitted potential pair_style snap snap
MOFFF styles for MOF-FF force field pair_style buck6d/coul/gauss PACKAGES/
MOLECULE molecular system force fields Howto bioFF peptide
MOLFILE VMD molfile plug-ins dump molfile n/a
MPIIO MPI parallel I/O dump and restart dump n/a
MSCG multi-scale coarse-graining wrapper fix mscg mscg
NETCDF dump output via NetCDF dump netcdf n/a
OPENMP OpenMP-enabled styles Speed omp Benchmarks
OPT optimized pair styles Speed opt Benchmarks
co

126 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

Table 1 – continued from previous page

Package Description Doc page Example
ORIENT fixes for orientation depended forces fix orient/* PACKAGES/
PERI Peridynamics models pair_style peri peri
PHONON phonon dynamical matrix fix phonon PACKAGES/
PLUGIN Plugin loader command plugin plugins
PLUMED PLUMED free energy library fix plumed PACKAGES/
POEMS coupled rigid body motion fix poems rigid
PTM Polyhedral Template Matching compute ptm/atom n/a
PYTHON embed Python code in an input script python python
QEQ QEq charge equilibration fix qeq qeq
QMMM QM/MM coupling fix qmmm PACKAGES/
QTB quantum nuclear effects fix qtb fix qbmsst qtb
REACTION chemical reactions in classical MD fix bond/react PACKAGES/
REAXFF ReaxFF potential (C/C++) pair_style reaxff reax
REPLICA multi-replica methods Howto replica tad
RIGID rigid bodies and constraints fix rigid rigid
SCAFACOS wrapper for ScaFaCoS Kspace solver kspace_style scafacos PACKAGES/
SHOCK shock loading methods fix msst n/a
SMTBQ second moment tight binding potential pair_style smtbq PACKAGES/
SPH smoothed particle hydrodynamics SPH User Guide PACKAGES/
SPIN magnetic atomic spin dynamics Howto spins SPIN
SRD stochastic rotation dynamics fix srd srd
TALLY pairwise tally computes compute XXX/tally PACKAGES/
UEF extensional flow fix nvt/uef PACKAGES/
VORONOI Voronoi tesselation compute voronoi/atom n/a
VTK dump output via VTK compute vtk n/a
YAFF additional styles implemented in YAFF angle_style cross PACKAGES/

6.2 Package details

Here is a brief description of all packages in LAMMPS. It lists authors (if applicable) and summarizes the package
contents. It has specific instructions on how to install the package, including, if necessary, info on how to download
or build any extra library it requires. It also gives links to documentation, example scripts, and pictures/movies (if
available) that illustrate use of the package.
The majority of packages can be included in a LAMMPS build with a single setting (-D PGK_<NAME>=on for CMake)
or command (make yes-<name> for make). See the Build package page for more info. A few packages may require
additional steps; this is indicated in the descriptions below. The Build extras page gives those details.

Note: To see the complete list of commands a package adds to LAMMPS, you can examine the files in its src directory,
e.g. “ls src/GRANULAR”. Files with names that start with fix, compute, atom, pair, bond, angle, etc correspond to
commands with the same style name as contained in the file name.

6.2. Package details 127

LAMMPS Documentation, Release stable 29Sep2021

ADIOS ASPHERE ATC AWPMD BOCS BODY

BROWNIAN CG-DNA CG-SDK CLASS2 COLLOID COLVARS
COMPRESS CORE- DIELECTRIC DIFFRAC- DIPOLE DPD-BASIC
SHELL TION
DPD-MESO DPD- DPD-SMOOTH DRUDE EFF EXTRA-
REACT COMPUTE
EXTRA- EXTRA-FIX EXTRA- EXTRA-PAIR FEP GPU
DUMP MOLECULE
GRANULAR H5MD INTEL INTERLAYER KIM KOKKOS
KSPACE LATBOLTZ LATTE MACHDYN MANI- MANYBODY
FOLD
MC MDI MEAM MESONT MESSAGE MGPT
MISC ML-HDNNP ML-IAP ML-PACE ML-QUIP ML-RANN
ML-SNAP MOFFF MOLECULE MOLFILE MPIIO MSCG
NETCDF OPENMP OPT ORIENT PERI PHONON
PLUGIN PLUMED POEMS PTM PYTHON QEQ
QMMM QTB REACTION REAXFF REPLICA RIGID
SCAFACOS SHOCK SMTBQ SPH SPIN SRD
TALLY UEF VORONOI VTK YAFF

6.2.1 ADIOS package

Contents:
ADIOS is a high-performance I/O library. This package implements the dump atom/adios, dump custom/adios and
read_dump . . . format adios commands to write and read data using the ADIOS library.
Authors: Norbert Podhorszki (ORNL) from the ADIOS developer team.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/ADIOS: filenames -> commands
• src/ADIOS/README
• examples/PACKAGES/adios
• https://github.com/ornladios/ADIOS2
• dump atom/adios
• dump custom/adios
• read_dump

128 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.2 ASPHERE package

Contents:
Computes, time-integration fixes, and pair styles for aspherical particle models including ellipsoids, 2d lines, and 3d
triangles.
Supporting info:
• src/ASPHERE: filenames -> commands
• Howto spherical
• pair_style gayberne
• pair_style resquared
• doc/PDF/pair_gayberne_extra.pdf
• doc/PDF/pair_resquared_extra.pdf
• examples/ASPHERE
• examples/ellipse
• https://www.lammps.org/movies.html#line
• https://www.lammps.org/movies.html#tri

6.2.3 ATC package

Contents:
ATC stands for atoms-to-continuum. This package implements a fix atc command to either couple molecular dynamics
with continuum finite element equations or perform on-the-fly conversion of atomic information to continuum fields.
Authors: Reese Jones, Jeremy Templeton, Jon Zimmerman (Sandia).
Install:
This package has specific installation instructions on the Build extras page. The ATC package requires that also the
MANYBODY package is installed.
Supporting info:
• src/ATC: filenames -> commands
• src/ATC/README
• fix atc
• examples/PACKAGES/atc
• https://www.lammps.org/pictures.html#atc

6.2. Package details 129

LAMMPS Documentation, Release stable 29Sep2021

6.2.4 AWPMD package

Contents:
AWPMD stands for Antisymmetrized Wave Packet Molecular Dynamics. This package implements an atom, pair, and
fix style which allows electrons to be treated as explicit particles in a classical molecular dynamics model.
Author: Ilya Valuev (JIHT, Russia).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/AWPMD: filenames -> commands
• src/AWPMD/README
• pair_style awpmd/cut
• examples/PACKAGES/awpmd

6.2.5 BOCS package

Contents:
This package provides fix bocs, a modified version of fix npt which includes the pressure correction to the barostat as
outlined in:
N. J. H. Dunn and W. G. Noid, “Bottom-up coarse-grained models that accurately describe the structure, pressure, and
compressibility of molecular liquids,” J. Chem. Phys. 143, 243148 (2015).
Authors: Nicholas J. H. Dunn and Michael R. DeLyser (The Pennsylvania State University)
Supporting info:
The BOCS package for LAMMPS is part of the BOCS software package: https://github.com/noid-group/BOCS
See the following reference for information about the entire package:
Dunn, NJH; Lebold, KM; DeLyser, MR; Rudzinski, JF; Noid, WG. “BOCS: Bottom-Up Open-Source Coarse-Graining
Software.” J. Phys. Chem. B. 122, 13, 3363-3377 (2018).
Example inputs are in the examples/PACKAGES/bocs folder.

6.2.6 BODY package

Contents:
Body-style particles with internal structure. Computes, time-integration fixes, pair styles, as well as the body styles
themselves. See the Howto body page for an overview.
Supporting info:
• src/BODY filenames -> commands
• Howto_body
• atom_style body

130 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• fix nve/body
• pair_style body/nparticle
• examples/body

6.2.7 BROWNIAN package

Contents:
This package provides fix brownian, fix brownian/sphere, and fix brownian/asphere as well as fix propel/self which
allow to do Brownian Dynamics time integration of point, spherical and aspherical particles and also support self-
propelled particles.
Authors: Sam Cameron (University of Bristol), Stefan Paquay (while at Brandeis University) (initial version of fix
propel/self)
Example inputs are in the examples/PACKAGES/brownian folder.

6.2.8 CG-DNA package

Contents:
Several pair styles, bond styles, and integration fixes for coarse-grained modelling of single- and double-stranded DNA
and RNA based on the oxDNA and oxRNA model of Doye, Louis and Ouldridge. The package includes Langevin-type
rigid-body integrators with improved stability.
Author: Oliver Henrich (University of Strathclyde, Glasgow).
Install:
The CG-DNA package requires that also the MOLECULE and ASPHERE packages are installed.
Supporting info:
• src/CG-DNA: filenames -> commands
• /src/CG-DNA/README
• pair_style oxdna/*
• pair_style oxdna2/*
• pair_style oxrna2/*
• bond_style oxdna/*
• bond_style oxdna2/*
• bond_style oxrna2/*
• fix nve/dotc/langevin

6.2. Package details 131

LAMMPS Documentation, Release stable 29Sep2021

6.2.9 CG-SDK package

Contents:
Several pair styles and an angle style which implement the coarse-grained SDK model of Shinoda, DeVane, and Klein
which enables simulation of ionic liquids, electrolytes, lipids and charged amino acids.
Author: Axel Kohlmeyer (Temple U).
Supporting info:
• src/CG-SDK: filenames -> commands
• src/CG-SDK/README
• pair_style lj/sdk/*
• angle_style sdk
• examples/PACKAGES/cgsdk
• https://www.lammps.org/pictures.html#cg

6.2.10 CLASS2 package

Contents:
Bond, angle, dihedral, improper, and pair styles for the COMPASS CLASS2 molecular force field.
Supporting info:
• src/CLASS2: filenames -> commands
• bond_style class2
• angle_style class2
• dihedral_style class2
• improper_style class2
• pair_style lj/class2

6.2.11 COLLOID package

Contents:
Coarse-grained finite-size colloidal particles. Pair styles and fix wall styles for colloidal interactions. Includes the Fast
Lubrication Dynamics (FLD) method for hydrodynamic interactions, which is a simplified approximation to Stokesian
dynamics.
Authors: This package includes Fast Lubrication Dynamics pair styles which were created by Amit Kumar and Michael
Bybee from Jonathan Higdon’s group at UIUC.
Supporting info:
• src/COLLOID: filenames -> commands
• fix wall/colloid

132 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• pair_style colloid
• pair_style yukawa/colloid
• pair_style brownian
• pair_style lubricate
• pair_style lubricateU
• examples/colloid
• examples/srd

6.2.12 COLVARS package

Contents:
COLVARS stands for collective variables, which can be used to implement various enhanced sampling methods, includ-
ing Adaptive Biasing Force, Metadynamics, Steered MD, Umbrella Sampling and Restraints. A fix colvars command
is implemented which wraps a COLVARS library, which implements these methods. simulations.
Authors: The COLVARS library is written and maintained by Giacomo Fiorin (ICMS, Temple University, Philadel-
phia, PA, USA) and Jerome Henin (LISM, CNRS, Marseille, France), originally for the NAMD MD code, but with
portability in mind. Axel Kohlmeyer (Temple U) provided the interface to LAMMPS.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/COLVARS: filenames -> commands
• doc/PDF/colvars-refman-lammps.pdf
• src/COLVARS/README
• lib/colvars/README
• fix colvars
• examples/PACKAGES/colvars

6.2.13 COMPRESS package

Contents:
Compressed output of dump files via the zlib compression library, using dump styles with a “gz” in their style name.
To use this package you must have the zlib compression library available on your system.
Author: Axel Kohlmeyer (Temple U).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/COMPRESS: filenames -> commands

6.2. Package details 133

LAMMPS Documentation, Release stable 29Sep2021

• src/COMPRESS/README
• lib/compress/README
• dump atom/gz
• dump cfg/gz
• dump custom/gz
• dump xyz/gz

6.2.14 CORESHELL package

Contents:
Compute and pair styles that implement the adiabatic core/shell model for polarizability. The pair styles augment
Born, Buckingham, and Lennard-Jones styles with core/shell capabilities. The compute temp/cs command calculates
the temperature of a system with core/shell particles. See the Howto coreshell page for an overview of how to use this
package.
Author: Hendrik Heenen (Technical U of Munich).
Supporting info:
• src/CORESHELL: filenames -> commands
• Howto coreshell
• Howto polarizable
• compute temp/cs
• pair_style born/coul/long/cs
• pair_style buck/coul/long/cs
• pair_style lj/cut/coul/long/cs
• examples/coreshell

6.2.15 DIELECTRIC package

Contents:
An atom style, multiple pair styles, several fixes, Kspace styles and a compute for simulating systems using boundary
element solvers for computing the induced charges at the interface between two media with different dielectric constants.
Install:
To use this package, also the KSPACE and EXTRA-PAIR packages need to be installed.
Author: Trung Nguyen and Monica Olvera de la Cruz (Northwestern U)
Supporting info:
• src/DIELECTRIC: filenames -> commands
• compute efield/atom
• TODO: add all styles

134 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• examples/PACKAGES/dielectric

6.2.16 DIFFRACTION package

Contents:
Two computes and a fix for calculating x-ray and electron diffraction intensities based on kinematic diffraction theory.
Author: Shawn Coleman while at the U Arkansas.
Supporting info:
• src/DIFFRACTION: filenames -> commands
• compute saed
• compute xrd
• fix saed/vtk
• examples/PACKAGES/diffraction

6.2.17 DIPOLE package

Contents:
An atom style and several pair styles for point dipole models with short-range or long-range interactions.
Supporting info:
• src/DIPOLE: filenames -> commands
• atom_style dipole
• pair_style lj/cut/dipole/cut
• pair_style lj/cut/dipole/long
• pair_style lj/long/dipole/long
• doc angle_style dipole <angle_dipole>
• examples/dipole

6.2.18 DPD-BASIC package

Contents:
Pair styles for the basic dissipative particle dynamics (DPD) method and DPD thermostatting.
Author: Kurt Smith (U Pittsburgh), Martin Svoboda, Martin Lisal (ICPF and UJEP)
Supporting info:
• src/DPD-BASIC: filenames -> commands
• pair_style dpd

6.2. Package details 135

LAMMPS Documentation, Release stable 29Sep2021

• pair_style dpd/tstat
• pair_style dpd/ext
• pair_style dpd/ext/tstat
• examples/PACKAGES/dpd-basic

6.2.19 DPD-MESO package

Contents:
Several extensions of the dissipative particle dynamics (DPD) method. Specifically, energy-conserving DPD (eDPD)
that can model non-isothermal processes, many-body DPD (mDPD) for simulating vapor-liquid coexistence, and trans-
port DPD (tDPD) for modeling advection-diffusion-reaction systems. The equations of motion of these DPD extensions
are integrated through a modified velocity-Verlet (MVV) algorithm.
Author: Zhen Li (Division of Applied Mathematics, Brown University)
Supporting info:
• src/DPD-MESO: filenames -> commands
• src/DPD-MESO/README
• atom_style edpd
• pair_style edpd
• pair_style mdpd
• pair_style tdpd
• fix mvv/dpd
• examples/PACKAGES/mesodpd
• https://www.lammps.org/movies.html#mesodpd

6.2.20 DPD-REACT package

Contents:
DPD stands for dissipative particle dynamics. This package implements coarse-grained DPD-based models for en-
ergetic, reactive molecular crystalline materials. It includes many pair styles specific to these systems, including for
reactive DPD, where each particle has internal state for multiple species and a coupled set of chemical reaction ODEs
are integrated each timestep. Highly accurate time integrators for isothermal, isoenergetic, isobaric and isenthalpic
conditions are included. These enable long timesteps via the Shardlow splitting algorithm.
Authors: Jim Larentzos (ARL), Tim Mattox (Engility Corp), and John Brennan (ARL).
Supporting info:
• src/DPD-REACT: filenames -> commands
• /src/DPD-REACT/README
• compute dpd
• compute dpd/atom

136 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• fix eos/cv
• fix eos/table
• fix eos/table/rx
• fix shardlow
• fix rx
• pair_style table/rx
• pair_style dpd/fdt
• pair_style dpd/fdt/energy
• pair_style exp6/rx
• pair_style multi/lucy
• pair_style multi/lucy/rx
• examples/PACKAGES/dpd-react

6.2.21 DPD-SMOOTH package

Contents:
A pair style for smoothed dissipative particle dynamics (SDPD), which is an extension of smoothed particle hydrody-
namics (SPH) to mesoscale where thermal fluctuations are important (see the SPH package). Also two fixes for moving
and rigid body integration of SPH/SDPD particles (particles of atom_style meso).
Author: Morteza Jalalvand (Institute for Advanced Studies in Basic Sciences, Iran).
Supporting info:
• src/DPD-SMOOTH: filenames -> commands
• src/DPD-SMOOTH/README
• pair_style sdpd/taitwater/isothermal
• fix meso/move
• fix rigid/meso
• examples/PACKAGES/dpd-smooth

6.2.22 DRUDE package

Contents:
Fixes, pair styles, and a compute to simulate thermalized Drude oscillators as a model of polarization. See the Howto
drude and Howto drude2 pages for an overview of how to use the package. There are auxiliary tools for using this
package in tools/drude.
Authors: Alain Dequidt (U Clermont Auvergne), Julien Devemy (CNRS), and Agilio Padua (ENS de Lyon).
Supporting info:
• src/DRUDE: filenames -> commands

6.2. Package details 137

LAMMPS Documentation, Release stable 29Sep2021

• Howto drude
• Howto drude2
• Howto polarizable
• src/DRUDE/README
• fix drude
• fix drude/transform/*
• compute temp/drude
• pair_style thole
• pair_style lj/cut/thole/long
• examples/PACKAGES/drude
• tools/drude

6.2.23 EFF package

Contents:
EFF stands for electron force field which allows a classical MD code to model electrons as particles of variable radius.
This package contains atom, pair, fix and compute styles which implement the eFF as described in A. Jaramillo-Botero,
J. Su, Q. An, and W.A. Goddard III, JCC, 2010. The eFF potential was first introduced by Su and Goddard, in 2007.
There are auxiliary tools for using this package in tools/eff; see its README file.
Author: Andres Jaramillo-Botero (CalTech).
Supporting info:
• src/EFF: filenames -> commands
• src/EFF/README
• atom_style electron
• fix nve/eff
• fix nvt/eff
• fix npt/eff
• fix langevin/eff
• compute temp/eff
• pair_style eff/cut
• pair_style eff/inline
• examples/PACKAGES/eff
• tools/eff/README
• tools/eff
• https://www.lammps.org/movies.html#eff

138 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.24 EXTRA-COMPUTE package

Contents:
Additional compute styles that are less commonly used.
Supporting info:
• src/EXTRA-COMPUTE: filenames -> commands
• compute

6.2.25 EXTRA-DUMP package

Contents:
Additional dump styles that are less commonly used.
Supporting info:
• src/EXTRA-DUMP: filenames -> commands
• dump

6.2.26 EXTRA-FIX package

Contents:
Additional fix styles that are less commonly used.
Supporting info:
• src/EXTRA-FIX: filenames -> commands
• fix

6.2.27 EXTRA-MOLECULE package

Contents:
Additional bond, angle, dihedral, and improper styles that are less commonly used.
Supporting info:
• src/EXTRA-MOLECULE: filenames -> commands
• molecular styles

6.2. Package details 139

LAMMPS Documentation, Release stable 29Sep2021

6.2.28 EXTRA-PAIR package

Contents:
Additional pair styles that are less commonly used.
Supporting info:
• src/EXTRA-PAIR: filenames -> commands
• pair_style

6.2.29 FEP package

Contents:
FEP stands for free energy perturbation. This package provides methods for performing FEP simulations by using a
fix adapt/fep command with soft-core pair potentials, which have a “soft” in their style name. There are auxiliary tools
for using this package in tools/fep; see its README file.
Author: Agilio Padua (ENS de Lyon)
Supporting info:
• src/FEP: filenames -> commands
• src/FEP/README
• fix adapt/fep
• compute fep
• pair_style */soft
• examples/PACKAGES/fep
• tools/fep/README
• tools/fep

6.2.30 GPU package

Contents:
Dozens of pair styles and a version of the PPPM long-range Coulombic solver optimized for GPUs. All such styles
have a “gpu” as a suffix in their style name. The GPU code can be compiled with either CUDA or OpenCL, however
the OpenCL variants are no longer actively maintained and only the CUDA versions are regularly tested. The GPU
package page gives details of what hardware and GPU software is required on your system, and details on how to build
and use this package. Its styles can be invoked at run time via the “-sf gpu” or “-suffix gpu” command-line switches.
See also the KOKKOS package, which has GPU-enabled styles.
Authors: Mike Brown (Intel) while at Sandia and ORNL and Trung Nguyen (Northwestern U) while at ORNL and
later. AMD HIP support by Evgeny Kuznetsov, Vladimir Stegailov, and Vsevolod Nikolskiy (HSE University).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:

140 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• src/GPU: filenames -> commands

• src/GPU/README
• lib/gpu/README
• Accelerator packages
• GPU package
• Section 2.6 -sf gpu
• Section 2.6 -pk gpu
• package gpu
• Commands pages (pair, kspace) for styles followed by (g)
• Benchmarks page of website

6.2.31 GRANULAR package

Contents:
Pair styles and fixes for finite-size granular particles, which interact with each other and boundaries via frictional and
dissipative potentials.
Supporting info:
• src/GRANULAR: filenames -> commands
• Howto granular
• fix pour
• fix wall/gran
• pair_style gran/hooke
• pair_style gran/hertz/history
• examples/granregion
• examples/pour
• bench/in.chute
• https://www.lammps.org/pictures.html#jamming
• https://www.lammps.org/movies.html#hopper
• https://www.lammps.org/movies.html#dem
• https://www.lammps.org/movies.html#brazil
• https://www.lammps.org/movies.html#granregion

6.2. Package details 141

LAMMPS Documentation, Release stable 29Sep2021

6.2.32 H5MD package

Contents:
H5MD stands for HDF5 for MD. HDF5 is a portable, binary, self-describing file format, used by many scientific
simulations. H5MD is a format for molecular simulations, built on top of HDF5. This package implements a dump
h5md command to output LAMMPS snapshots in this format.
To use this package you must have the HDF5 library available on your system.
Author: Pierre de Buyl (KU Leuven) created both the package and the H5MD format.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/H5MD: filenames -> commands
• src/H5MD/README
• lib/h5md/README
• dump h5md

6.2.33 INTEL package

Contents:
Dozens of pair, fix, bond, angle, dihedral, improper, and kspace styles which are optimized for Intel CPUs and KNLs
(Knights Landing). All of them have an “intel” in their style name. The INTEL package page gives details of what
hardware and compilers are required on your system, and how to build and use this package. Its styles can be invoked
at run time via the “-sf intel” or “-suffix intel” command-line switches. Also see the KOKKOS, OPT , and OPENMP
packages, which have styles optimized for CPUs and KNLs.
You need to have an Intel compiler, version 14 or higher to take full advantage of this package. While compilation with
GNU compilers is supported, performance will be sub-optimal.

Note: the INTEL package contains styles that require using the -restrict flag, when compiling with Intel compilers.

Author: Mike Brown (Intel).

Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/INTEL: filenames -> commands
• src/INTEL/README
• Accelerator packages
• INTEL package
• Section 2.6 -sf intel
• Section 2.6 -pk intel

142 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• package intel
• Search the commands pages (fix, compute, pair, bond, angle, dihedral, improper, kspace) for styles followed by
(i)
• src/INTEL/TEST
• Benchmarks page of website

6.2.34 INTERLAYER package

Contents:
A collection of pair styles specifically to be used for modeling layered materials, most commonly graphene sheets (or
equivalents).
Supporting info:
• src/INTERLAYER: filenames -> commands
• Pair style page
• examples/PACKAGES/interlayer

6.2.35 KIM package

Contents:
This package contains a command with a set of sub-commands that serve as a wrapper on the Open Knowledgebase
of Interatomic Models (OpenKIM) repository of interatomic models (IMs) enabling compatible ones to be used in
LAMMPS simulations.
This includes kim init, and kim interactions commands to select, initialize and instantiate the IM, a kim query command
to perform web queries for material property predictions of OpenKIM IMs, a kim param command to access KIM
Model Parameters from LAMMPS, and a kim property command to write material properties computed in LAMMPS
to standard KIM property instance format.
Support for KIM IMs that conform to the KIM Application Programming Interface (API) is provided by the pair_style
kim command.

Note: The command pair_style kim is called by kim interactions and is not recommended to be directly used in input
scripts.

To use this package you must have the KIM API library available on your system. The KIM API is available for
download on the OpenKIM website. When installing LAMMPS from binary, the kim-api package is a dependency that
is automatically downloaded and installed.
Information about the KIM project can be found at its website: https://openkim.org. The KIM project is led by Ellad
Tadmor and Ryan Elliott (U Minnesota) and is funded by the National Science Foundation.
Authors: Ryan Elliott (U Minnesota) is the main developer for the KIM API and the pair_style kim command. Yaser
Afshar (U Minnesota), Axel Kohlmeyer (Temple U), Ellad Tadmor (U Minnesota), and Daniel Karls (U Minnesota)
contributed to the kim command interface in close collaboration with Ryan Elliott.
Install:

6.2. Package details 143

LAMMPS Documentation, Release stable 29Sep2021

This package has specific installation instructions on the Build extras page.
Supporting info:
• kim command
• pair_style kim
• src/KIM: filenames -> commands
• src/KIM/README
• lib/kim/README
• examples/kim

6.2.36 KOKKOS package

Contents:
Dozens of atom, pair, bond, angle, dihedral, improper, fix, compute styles adapted to compile using the Kokkos library
which can convert them to OpenMP or CUDA code so that they run efficiently on multicore CPUs, KNLs, or GPUs.
All the styles have a “kk” as a suffix in their style name. The KOKKOS package page gives details of what hardware
and software is required on your system, and how to build and use this package. Its styles can be invoked at run time via
the “-sf kk” or “-suffix kk” command-line switches. Also see the GPU, OPT , INTEL, and OPENMP packages, which
have styles optimized for CPUs, KNLs, and GPUs.
You must have a C++14 compatible compiler to use this package. KOKKOS makes extensive use of advanced C++
features, which can expose compiler bugs, especially when compiling for maximum performance at high optimization
levels. Please see the file lib/kokkos/README for a list of compilers and their respective platforms, that are known to
work.
Authors: The KOKKOS package was created primarily by Christian Trott and Stan Moore (Sandia), with contributions
from other folks as well. It uses the open-source Kokkos library which was developed by Carter Edwards, Christian
Trott, and others at Sandia, and which is included in the LAMMPS distribution in lib/kokkos.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/KOKKOS: filenames -> commands
• src/KOKKOS/README
• lib/kokkos/README
• Accelerator packages
• KOKKOS package
• Section 2.6 -k on . . .
• Section 2.6 -sf kk
• Section 2.6 -pk kokkos
• package kokkos
• Search the commands pages (fix, compute, pair, bond, angle, dihedral, improper, kspace) for styles followed by
(k)

144 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• Benchmarks page of website

6.2.37 KSPACE package

Contents:
A variety of long-range Coulombic solvers, as well as pair styles which compute the corresponding short-range pair-
wise Coulombic interactions. These include Ewald, particle-particle particle-mesh (PPPM), and multilevel summation
method (MSM) solvers.
Install:
Building with this package requires a 1d FFT library be present on your system for use by the PPPM solvers. This can
be the KISS FFT library provided with LAMMPS, third party libraries like FFTW, or a vendor-supplied FFT library.
See the Build settings page for details on how to select different FFT options for your LAMPMS build.
Supporting info:
• src/KSPACE: filenames -> commands
• kspace_style
• doc/PDF/kspace.pdf
• Howto tip3p
• Howto tip4p
• Howto spc
• pair_style coul
• Search the pair style page for styles with “long” or “msm” in name
• examples/peptide
• bench/in.rhodo

6.2.38 LATBOLTZ package

Contents:
Fixes which implement a background Lattice-Boltzmann (LB) fluid, which can be used to model MD particles influ-
enced by hydrodynamic forces.
Authors: Frances Mackay and Colin Denniston (University of Western Ontario).
Install:
The LATBOLTZ package requires that LAMMPS is build in MPI parallel mode.
Supporting info:
• src/LATBOLTZ: filenames -> commands
• src/LATBOLTZ/README
• fix lb/fluid
• fix lb/momentum

6.2. Package details 145

LAMMPS Documentation, Release stable 29Sep2021

• fix lb/viscous
• examples/PACKAGES/latboltz

6.2.39 LATTE package

Contents:
A fix command which wraps the LATTE DFTB code, so that molecular dynamics can be run with LAMMPS using
density-functional tight-binding quantum forces calculated by LATTE.
More information on LATTE can be found at this website: https://github.com/lanl/LATTE. A brief technical descrip-
tion is given with the fix latte command.
Authors: Christian Negre (LANL) and Steve Plimpton (Sandia). LATTE itself is developed at Los Alamos National
Laboratory by Marc Cawkwell, Anders Niklasson, and Christian Negre.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/LATTE: filenames -> commands
• src/LATTE/README
• lib/latte/README
• fix latte
• examples/latte
• LAMMPS-LATTE tutorial

6.2.40 MACHDYN package

Contents:
An atom style, fixes, computes, and several pair styles which implements smoothed Mach dynamics (SMD) for solids,
which is a model related to smoothed particle hydrodynamics (SPH) for liquids (see the SPH package).
This package solves solids mechanics problems via a state of the art stabilized meshless method with hourglass con-
trol. It can specify hydrostatic interactions independently from material strength models, i.e. pressure and deviatoric
stresses are separated. It provides many material models (Johnson-Cook, plasticity with hardening, Mie-Grueneisen,
Polynomial EOS) and allows new material models to be added. It implements rigid boundary conditions (walls) which
can be specified as surface geometries from *.STL files.
Author: Georg Ganzenmuller (Fraunhofer-Institute for High-Speed Dynamics, Ernst Mach Institute, Germany).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/MACHDYN: filenames -> commands
• src/MACHDYN/README

146 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• doc/PDF/MACHDYN_LAMMPS_userguide.pdf
• examples/PACKAGES/machdyn
• https://www.lammps.org/movies.html#smd

6.2.41 MANIFOLD package

Contents:
Several fixes and a “manifold” class which enable simulations of particles constrained to a manifold (a 2D surface
within the 3D simulation box). This is done by applying the RATTLE constraint algorithm to formulate single-particle
constraint functions g(xi,yi,zi) = 0 and their derivative (i.e. the normal of the manifold) n = grad(g).
Author: Stefan Paquay (until 2017: Eindhoven University of Technology (TU/e), The Netherlands; since 2017: Bran-
deis University, Waltham, MA, USA)
Supporting info:
• src/MANIFOLD: filenames -> commands
• src/MANIFOLD/README
• Howto manifold
• fix manifoldforce
• fix nve/manifold/rattle
• fix nvt/manifold/rattle
• examples/PACKAGES/manifold
• https://www.lammps.org/movies.html#manifold

6.2.42 MANYBODY package

Contents:
A variety of many-body and bond-order potentials. These include (AI)REBO, BOP, EAM, EIM, Stillinger-Weber, and
Tersoff potentials.
Supporting info:
• src/MANYBODY: filenames -> commands
• Pair style page
• examples/comb
• examples/eim
• examples/nb3d
• examples/shear
• examples/streitz
• examples/vashishta
• bench/in.eam

6.2. Package details 147

LAMMPS Documentation, Release stable 29Sep2021

6.2.43 MC package

Contents:
Several fixes and a pair style that have Monte Carlo (MC) or MC-like attributes. These include fixes for creating,
breaking, and swapping bonds, for performing atomic swaps, and performing grand-canonical MC (GCMC) or similar
processes in conjunction with dynamics.
Supporting info:
• src/MC: filenames -> commands
• fix atom/swap
• fix bond/break
• fix bond/create
• fix bond/create/angle
• fix bond/swap
• fix charge/regulation
• fix gcmc
• fix tfmc
• fix widom
• pair_style dsmc
• https://www.lammps.org/movies.html#gcmc

6.2.44 MDI package

Contents:
A LAMMPS command and fix to allow client-server coupling of LAMMPS to other atomic or molecular simulation
codes via the MolSSI Driver Interface (MDI) library.
Author: Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
Supporting info:
• src/MDI/README
• mdi/engine
• fix mdi/engine
• examples/PACKAGES/mdi

148 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.45 MEAM package

Contents:
A pair style for the modified embedded atom (MEAM) potential translated from the Fortran version in the (obso-
lete) MEAM package to plain C++. The MEAM fully replaces the MEAM package, which has been removed from
LAMMPS after the 12 December 2018 version.
Author: Sebastian Huetter, (Otto-von-Guericke University Magdeburg) based on the Fortran version of Greg Wagner
(Northwestern U) while at Sandia.
Supporting info:
• src/MEAM: filenames -> commands
• src/MEAM/README
• pair_style meam
• examples/meam

6.2.46 MESONT package

Contents:
MESONT is a LAMMPS package for simulation of nanomechanics of nanotubes (NTs). The model is based on a
coarse-grained representation of NTs as “flexible cylinders” consisting of a variable number of segments. Internal
interactions within a NT and the van der Waals interaction between the tubes are described by a mesoscopic force field
designed and parameterized based on the results of atomic-level molecular dynamics simulations. The description of
the force field is provided in the papers listed below. This package contains two independent implementations of this
model: pair_style mesocnt is a (minimal) C++ implementation, and pair_style mesont/tpm is a more general and feature
rich implementation based on a Fortran library in the lib/mesont folder.
Download of potential files:
The potential files for these pair styles are very large and thus are not included in the regular downloaded packages of
LAMMPS or the git repositories. Instead, they will be automatically downloaded from a web server when the package
is installed for the first time.
Authors of the *mesont* styles:
Maxim V. Shugaev (University of Virginia), Alexey N. Volkov (University of Alabama), Leonid V. Zhigilei (University
of Virginia)
Author of the *mesocnt* pair style: Philipp Kloza (U Cambridge)
Supporting info:
• src/MESONT: filenames -> commands
• src/MESONT/README
• atom_style mesont
• pair_style mesont/tpm
• compute mesont
• pair_style mesocnt
• examples/PACKAGES/mesont

6.2. Package details 149

LAMMPS Documentation, Release stable 29Sep2021

• tools/mesont

6.2.47 MESSAGE package

Contents:
Commands to use LAMMPS as either a client or server and couple it to another application.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/MESSAGE: filenames -> commands
• lib/message/README
• message
• fix client/md
• server md
• server mc
• examples/message

6.2.48 MGPT package

Contents:
A pair style which provides a fast implementation of the quantum-based MGPT multi-ion potentials. The MGPT or
model GPT method derives from first-principles DFT-based generalized pseudopotential theory (GPT) through a series
of systematic approximations valid for mid-period transition metals with nearly half-filled d bands. The MGPT method
was originally developed by John Moriarty at LLNL. The pair style in this package calculates forces and energies using
an optimized matrix-MGPT algorithm due to Tomas Oppelstrup at LLNL.
Authors: Tomas Oppelstrup and John Moriarty (LLNL).
Supporting info:
• src/MGPT: filenames -> commands
• src/MGPT/README
• pair_style mgpt
• examples/PACKAGES/mgpt

150 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.49 MISC package

Contents:
A variety of compute, fix, pair, bond styles with specialized capabilities that don’t align with other packages. Do a
directory listing, “ls src/MISC”, to see the list of commands.

Note: the MISC package contains styles that require using the -restrict flag, when compiling with Intel compilers.

Supporting info:
• src/MISC: filenames -> commands
• bond_style special
• compute viscosity/cos
• fix accelerate/cos
• fix imd
• fix ipi
• pair_style agni
• pair_style list
• pair_style srp
• pair_style tracker
• fix pair/tracker

6.2.50 ML-HDNNP package

Contents:
A pair_style hdnnp command which allows to use high-dimensional neural network potentials (HDNNPs), a form of
machine learning potentials. HDNNPs must be carefully trained prior to their application in a molecular dynamics
simulation.
To use this package you must have the n2p2 library installed and compiled on your system.
Author: Andreas Singraber
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/ML-HDNNP: filenames -> commands
• src/ML-HDNNP/README
• lib/hdnnp/README
• pair_style hdnnp
• examples/PACKAGES/hdnnp

6.2. Package details 151

LAMMPS Documentation, Release stable 29Sep2021

6.2.51 ML-IAP package

Contents:
A general interface for machine-learning interatomic potentials, including PyTorch.
Install:
To use this package, also the ML-SNAP package needs to be installed. To make the mliappy model available, also the
PYTHON package needs to be installed, the version of Python must be 3.6 or later, and the cython software must be
installed.
Author: Aidan Thompson (Sandia), Nicholas Lubbers (LANL).
Supporting info:
• src/ML-IAP: filenames -> commands
• src/ML-IAP/README.md
• pair_style mliap
• compute_style mliap
• examples/mliap (see README)
When built with the mliappy model this package includes an extension for coupling with Python models, including
PyTorch. In this case, the Python interpreter linked to LAMMPS will need the cython and numpy modules installed.
The provided examples build models with PyTorch, which would therefore also needs to be installed to run those
examples.

6.2.52 ML-PACE package

Contents:
A pair style for the Atomic Cluster Expansion potential (ACE). ACE is a methodology for deriving a highly accurate
classical potential fit to a large archive of quantum mechanical (DFT) data. The ML-PACE package provides an efficient
implementation for running simulations with ACE potentials.
Authors:
This package was written by Yury Lysogorskiy^1, Cas van der Oord^2, Anton Bochkarev^1, Sarath Menon^1, Matteo
Rinaldi^1, Thomas Hammerschmidt^1, Matous Mrovec^1, Aidan Thompson^3, Gabor Csanyi^2, Christoph Ortner^4,
Ralf Drautz^1.
^1: Ruhr-University Bochum, Bochum, Germany
^2: University of Cambridge, Cambridge, United Kingdom
^3: Sandia National Laboratories, Albuquerque, New Mexico, USA
^4: University of British Columbia, Vancouver, BC, Canada
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/ML-PACE: filenames -> commands
• pair_style pace

152 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• examples/PACKAGES/pace

6.2.53 ML-QUIP package

Contents:
A pair_style quip command which wraps the QUIP libAtoms library, which includes a variety of interatomic potentials,
including Gaussian Approximation Potential (GAP) models developed by the Cambridge University group.
To use this package you must have the QUIP libAtoms library available on your system.
Author: Albert Bartok (Cambridge University)
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/ML-QUIP: filenames -> commands
• src/ML-QUIP/README
• pair_style quip
• examples/PACKAGES/quip

6.2.54 ML-RANN package

Contents:
A pair style for using rapid atomistic neural network (RANN) potentials. These neural network potentials work by first
generating a series of symmetry functions from the neighbor list and then using these values as the input layer of a
neural network.
Authors:
This package was written by Christopher Barrett with contributions by Doyl Dickel, Mississippi State University.
Supporting info:
• src/ML-RANN: filenames -> commands
• pair_style rann
• examples/PACKAGES/rann

6.2. Package details 153

LAMMPS Documentation, Release stable 29Sep2021

6.2.55 ML-SNAP package

Contents:
A pair style for the spectral neighbor analysis potential (SNAP). SNAP is methodology for deriving a highly accurate
classical potential fit to a large archive of quantum mechanical (DFT) data. Also several computes which analyze
attributes of the potential.
Author: Aidan Thompson (Sandia).
Supporting info:
• src/ML-SNAP: filenames -> commands
• pair_style snap
• compute sna/atom
• compute snad/atom
• compute snav/atom
• examples/snap

6.2.56 MOFFF package

Contents:
Pair, angle and improper styles needed to employ the MOF-FF force field by Schmid and coworkers with LAMMPS.
MOF-FF is a first principles derived force field with the primary aim to simulate MOFs and related porous framework
materials, using spherical Gaussian charges. It is described in S. Bureekaew et al., Phys. Stat. Sol. B 2013, 250,
1128-1141. For the usage of MOF-FF see the example in the example directory as well as the MOF+ website.
Author: Hendrik Heenen (Technical U of Munich), Rochus Schmid (Ruhr-University Bochum).
Supporting info:
• src/MOFFF: filenames -> commands
• src/MOFFF/README
• pair_style buck6d/coul/gauss
• angle_style class2
• angle_style cosine/buck6d
• improper_style inversion/harmonic
• examples/PACKAGES/mofff

154 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.57 MOLECULE package

Contents:
A large number of atom, pair, bond, angle, dihedral, improper styles that are used to model molecular systems with
fixed covalent bonds. The pair styles include the Dreiding (hydrogen-bonding) and CHARMM force fields, and a TIP4P
water model.
Supporting info:
• src/MOLECULE: filenames -> commands
• atom_style
• bond_style
• angle_style
• dihedral_style
• improper_style
• pair_style hbond/dreiding/lj
• pair_style lj/charmm/coul/charmm
• Howto bioFF
• examples/cmap
• examples/dreiding
• examples/micelle,
• examples/peptide
• bench/in.chain
• bench/in.rhodo

6.2.58 MOLFILE package

Contents:
A dump molfile command which uses molfile plugins that are bundled with the VMD molecular visualization and
analysis program, to enable LAMMPS to dump snapshots in formats compatible with various molecular simulation
tools.
To use this package you must have the desired VMD plugins available on your system.
Note that this package only provides the interface code, not the plugins themselves, which will be accessed when
requesting a specific plugin via the dump molfile command. Plugins can be obtained from a VMD installation which
has to match the platform that you are using to compile LAMMPS for. By adding plugins to VMD, support for new
file formats can be added to LAMMPS (or VMD or other programs that use them) without having to re-compile the
application itself. More information about the VMD molfile plugins can be found at http://www.ks.uiuc.edu/Research/
vmd/plugins/molfile.
Author: Axel Kohlmeyer (Temple U).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:

6.2. Package details 155

LAMMPS Documentation, Release stable 29Sep2021

• src/MOLFILE: filenames -> commands

• src/MOLFILE/README
• lib/molfile/README
• dump molfile

6.2.59 MPIIO package

Contents:
Support for parallel output/input of dump and restart files via the MPIIO library. It adds dump styles with a “mpiio” in
their style name. Restart files with an “.mpiio” suffix are also written and read in parallel.
Install:
The MPIIO package requires that LAMMPS is build in MPI parallel mode.
Supporting info:
• src/MPIIO: filenames -> commands
• dump
• restart
• write_restart
• read_restart

6.2.60 MSCG package

Contents:
A fix mscg command which can parameterize a Multi-Scale Coarse-Graining (MSCG) model using the open-source
MS-CG library.
To use this package you must have the MS-CG library available on your system.
Authors: The fix was written by Lauren Abbott (Sandia). The MS-CG library was developed by Jacob Wagner in Greg
Voth’s group at the University of Chicago.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/MSCG: filenames -> commands
• src/MSCG/README
• lib/mscg/README
• examples/mscg

156 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.61 NETCDF package

Contents:
Dump styles for writing NetCDF formatted dump files. NetCDF is a portable, binary, self-describing file format de-
veloped on top of HDF5. The file contents follow the AMBER NetCDF trajectory conventions (http://ambermd.org/
netcdf/nctraj.xhtml), but include extensions.
To use this package you must have the NetCDF library available on your system.
Note that NetCDF files can be directly visualized with the following tools:
• Ovito (Ovito supports the AMBER convention and the extensions mentioned above)
• VMD
Author: Lars Pastewka (Karlsruhe Institute of Technology).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/NETCDF: filenames -> commands
• src/NETCDF/README
• lib/netcdf/README
• dump netcdf

6.2.62 OPENMP package

Contents:
Hundreds of pair, fix, compute, bond, angle, dihedral, improper, and kspace styles which are altered to enable threading
on many-core CPUs via OpenMP directives. All of them have an “omp” in their style name. The OPENMP package
page gives details of what hardware and compilers are required on your system, and how to build and use this package.
Its styles can be invoked at run time via the “-sf omp” or “-suffix omp” command-line switches. Also see the KOKKOS,
OPT , and INTEL packages, which have styles optimized for CPUs.
Author: Axel Kohlmeyer (Temple U).

Note: To enable multi-threading support the compile flag “-fopenmp” and the link flag “-fopenmp” (for GNU com-
pilers, you have to look up the equivalent flags for other compilers) must be used to build LAMMPS. When using Intel
compilers, also the “-restrict” flag is required. The OPENMP package can be compiled without enabling OpenMP;
then all code will be compiled as serial and the only improvement over the regular styles are some data access op-
timization. These flags should be added to the CCFLAGS and LINKFLAGS lines of your Makefile.machine. See
src/MAKE/OPTIONS/Makefile.omp for an example.

Once you have an appropriate Makefile.machine, you can install/un-install the package and build LAMMPS in the usual
manner:
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:

6.2. Package details 157

LAMMPS Documentation, Release stable 29Sep2021

• src/OPENMP: filenames -> commands

• src/OPENMP/README
• Accelerator packages
• OPENMP package
• Command line option -suffix/-sf omp
• Command line option -package/-pk omp
• package omp
• Search the commands pages (fix, compute, pair, bond, angle, dihedral, improper, kspace) for styles followed by
(o)
• Benchmarks page of website

6.2.63 OPT package

Contents:
A handful of pair styles which are optimized for improved CPU performance on single or multiple cores. These include
EAM, LJ, CHARMM, and Morse potentials. The styles have an “opt” suffix in their style name. The OPT package
page gives details of how to build and use this package. Its styles can be invoked at run time via the “-sf opt” or “-suffix
opt” command-line switches. See also the KOKKOS, INTEL, and OPENMP packages, which have styles optimized for
CPU performance.
Authors: James Fischer (High Performance Technologies), David Richie, and Vincent Natoli (Stone Ridge Technol-
ogy).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/OPT: filenames -> commands
• Accelerator packages
• OPT package
• Section 2.6 -sf opt
• Search the pair style page for styles followed by (t)
• Benchmarks page of website

6.2.64 ORIENT package

Contents:
A few fixes that apply orientation dependent forces for studying grain boundary migration.
Supporting info:
• src/ORIENT: filenames -> commands
• fix orient/bcc

158 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• fix orient/fcc
• fix orient/eco

6.2.65 PERI package

Contents:
An atom style, several pair styles which implement different Peridynamics materials models, and several computes
which calculate diagnostics. Peridynamics is a particle-based meshless continuum model.
Authors: The original package was created by Mike Parks (Sandia). Additional Peridynamics models were added by
Rezwanur Rahman and John Foster (UTSA).
Supporting info:
• src/PERI: filenames -> commands
• doc/PDF/PDLammps_overview.pdf
• doc/PDF/PDLammps_EPS.pdf
• doc/PDF/PDLammps_VES.pdf
• atom_style peri
• pair_style peri/*
• compute damage/atom
• compute plasticity/atom
• examples/peri
• https://www.lammps.org/movies.html#peri

6.2.66 PHONON package

Contents:
A fix phonon command that calculates dynamical matrices, which can then be used to compute phonon dispersion
relations, directly from molecular dynamics simulations. And a dynamical_matrix as well as a third_order command
to compute the dynamical matrix and third order tensor from finite differences.
Install:
The PHONON package requires that also the KSPACE package is installed.
Authors: Ling-Ti Kong (Shanghai Jiao Tong University) for “fix phonon” and Charlie Sievers (UC Davis) for “dy-
namical_matrix” and “third_order”
Supporting info:
• src/PHONON: filenames -> commands
• src/PHONON/README
• fix phonon
• dynamical_matrix

6.2. Package details 159

LAMMPS Documentation, Release stable 29Sep2021

• third_order
• examples/PACKAGES/phonon

6.2.67 PLUGIN package

Contents:
A plugin command that can load and unload several kind of styles in LAMMPS from shared object files at runtime
without having to recompile and relink LAMMPS.
Authors: Axel Kohlmeyer (Temple U)
Supporting info:
• src/PLUGIN: filenames -> commands
• plugin command
• Information on writing plugins
• examples/plugin

6.2.68 PLUMED package

Contents:
The fix plumed command allows you to use the PLUMED free energy plugin for molecular dynamics to analyze and
bias your LAMMPS trajectory on the fly. The PLUMED library is called from within the LAMMPS input script by
using the fix plumed command.
Authors: The PLUMED library is written and maintained by Massimilliano Bonomi, Giovanni Bussi, Carlo Camiloni,
and Gareth Tribello.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/PLUMED/README
• lib/plumed/README
• fix plumed
• examples/PACKAGES/plumed

160 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.69 POEMS package

Contents:
A fix that wraps the Parallelizable Open source Efficient Multibody Software (POEMS) library, which is able to simulate
the dynamics of articulated body systems. These are systems with multiple rigid bodies (collections of particles) whose
motion is coupled by connections at hinge points.
Author: Rudra Mukherjee (JPL) while at RPI.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/POEMS: filenames -> commands
• src/POEMS/README
• lib/poems/README
• fix poems
• examples/rigid

6.2.70 PTM package

Contents:
A compute ptm/atom command that calculates local structure characterization using the Polyhedral Template Matching
methodology.
Author: Peter Mahler Larsen (MIT).
Supporting info:
• src/PTM: filenames not starting with ptm_ -> commands
• src/PTM: filenames starting with ptm_ -> supporting code
• src/PTM/LICENSE
• compute ptm/atom

6.2.71 PYTHON package

Contents:
A python command which allow you to execute Python code from a LAMMPS input script. The code can be in a
separate file or embedded in the input script itself. See the Python call page for an overview of using Python from
LAMMPS in this manner and all the Python manual pages for other ways to use LAMMPS and Python together.

Note: Building with the PYTHON package assumes you have a Python development environment (headers and
libraries) available on your system, which needs to be either Python version 2.7 or Python 3.5 and later.

Install:

6.2. Package details 161

LAMMPS Documentation, Release stable 29Sep2021

This package has specific installation instructions on the Build extras page.
Supporting info:
• src/PYTHON: filenames -> commands
• Python call
• lib/python/README
• examples/python

6.2.72 QEQ package

Contents:
Several fixes for performing charge equilibration (QEq) via different algorithms. These can be used with pair styles
that perform QEq as part of their formulation.
Supporting info:
• src/QEQ: filenames -> commands
• fix qeq/*
• examples/qeq
• examples/streitz

6.2.73 QMMM package

Contents:
A fix qmmm command which allows LAMMPS to be used as the MM code in a QM/MM simulation. This is currently
only available in combination with the Quantum ESPRESSO package.
To use this package you must have Quantum ESPRESSO (QE) available on your system and include its coupling library
in the compilation and then compile LAMMPS as a library. For QM/MM calculations you then build a custom binary
with MPI support, that sets up 3 partitions with MPI sub-communicators (for inter- and intra-partition communication)
and then calls the corresponding library interfaces on each partition (2x LAMMPS and 1x QE).
The current implementation supports an ONIOM style mechanical coupling and a multi-pole based electrostatic cou-
pling to the Quantum ESPRESSO plane wave DFT package. The QM/MM interface has been written in a manner that
coupling to other QM codes should be possible without changes to LAMMPS itself.
Authors: Axel Kohlmeyer (Temple U). Mariella Ippolito and Carlo Cavazzoni (CINECA, Italy)
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/QMMM: filenames -> commands
• src/QMMM/README
• lib/qmmm/README
• fix phonon

162 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• lib/qmmm/example-ec/README
• lib/qmmm/example-mc/README

6.2.74 QTB package

Contents:
Two fixes which provide a self-consistent quantum treatment of vibrational modes in a classical molecular dynamics
simulation. By coupling the MD simulation to a colored thermostat, it introduces zero point energy into the system,
altering the energy power spectrum and the heat capacity to account for their quantum nature. This is useful when
modeling systems at temperatures lower than their classical limits or when temperatures ramp across the classical
limits in a simulation.
Author: Yuan Shen (Stanford U).
Supporting info:
• src/QTB: filenames -> commands
• src/QTB/README
• fix qtb
• fix qbmsst
• examples/PACKAGES/qtb

6.2.75 REACTION package

Contents:
This package allows for complex bond topology changes (reactions) during a running MD simulation, when using
classical force fields. Topology changes are defined in pre- and post-reaction molecule templates and can include
creation and deletion of bonds, angles, dihedrals, impropers, atom types, bond types, angle types, dihedral types,
improper types, and/or atomic charges. Other options currently available include reaction constraints (e.g. angle and
Arrhenius constraints), deletion of reaction byproducts or other small molecules, and chiral-sensitive reactions.
Author: Jacob R. Gissinger (CU Boulder) while at NASA Langley Research Center.
Supporting info:
• src/REACTION: filenames -> commands
• src/REACTION/README
• fix bond/react
• examples/PACKAGES/reaction
• 2017 LAMMPS Workshop
• 2019 LAMMPS Workshop
• reacter.org

6.2. Package details 163

LAMMPS Documentation, Release stable 29Sep2021

6.2.76 REAXFF package

Contents:
A pair style which implements the ReaxFF potential in C/C++. ReaxFF is a universal reactive force field. See the
src/REAXFF/README file for more info on differences between the two packages. Also two fixes for monitoring
molecules as bonds are created and destroyed.
Author: Hasan Metin Aktulga (MSU) while at Purdue University.
Supporting info:
• src/REAXFF: filenames -> commands
• src/REAXFF/README
• pair_style reaxff
• fix reaxff/bonds
• fix reaxff/species
• examples/reaxff

6.2.77 REPLICA package

Contents:
A collection of multi-replica methods which can be used when running multiple LAMMPS simulations (replicas). See
the Howto replica page for an overview of how to run multi-replica simulations in LAMMPS. Methods in the package
include nudged elastic band (NEB), parallel replica dynamics (PRD), temperature accelerated dynamics (TAD), par-
allel tempering, and a verlet/split algorithm for performing long-range Coulombics on one set of processors, and the
remainder of the force field calculation on another set.
Supporting info:
• src/REPLICA: filenames -> commands
• Howto replica
• neb
• prd
• tad
• temper,
• temper/npt,
• temper/grem,
• run_style verlet/split
• examples/neb
• examples/prd
• examples/tad
• examples/PACKAGES/grem

164 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.78 RIGID package

Contents:
Fixes which enforce rigid constraints on collections of atoms or particles. This includes SHAKE and RATTLE, as well
as various rigid-body integrators for a few large bodies or many small bodies. Also several computes which calculate
properties of rigid bodies.
Supporting info:
• src/RIGID: filenames -> commands
• compute erotate/rigid
• fix shake
• fix rattle
• fix rigid/*
• examples/ASPHERE
• examples/rigid
• bench/in.rhodo
• https://www.lammps.org/movies.html#box
• https://www.lammps.org/movies.html#star

6.2.79 SCAFACOS package

Contents:
A KSpace style which wraps the ScaFaCoS Coulomb solver library to compute long-range Coulombic interactions.
To use this package you must have the ScaFaCoS library available on your system.
Author: Rene Halver (JSC) wrote the scafacos LAMMPS command.
ScaFaCoS itself was developed by a consortium of German research facilities with a BMBF (German Ministry of
Science and Education) funded project in 2009-2012. Participants of the consortium were the Universities of Bonn,
Chemnitz, Stuttgart, and Wuppertal as well as the Forschungszentrum Juelich.
Install:
This package has specific installation instructions on the Build extras page. The SCAFACOS package requires that
LAMMPS is build in MPI parallel mode.
Supporting info:
• src/SCAFACOS: filenames -> commands
• src/SCAFACOS/README
• kspace_style scafacos
• kspace_modify
• examples/PACKAGES/scafacos

6.2. Package details 165

LAMMPS Documentation, Release stable 29Sep2021

6.2.80 SHOCK package

Contents:
Fixes for running impact simulations where a shock-wave passes through a material.
Supporting info:
• src/SHOCK: filenames -> commands
• fix append/atoms
• fix msst
• fix nphug
• fix wall/piston
• examples/hugoniostat
• examples/msst

6.2.81 SMTBQ package

Contents:
A pair style which implements a Second Moment Tight Binding model with QEq charge equilibration (SMTBQ) po-
tential for the description of ionocovalent bonds in oxides.
Authors: Nicolas Salles, Emile Maras, Olivier Politano, and Robert Tetot (LAAS-CNRS, France).
Supporting info:
• src/SMTBQ: filenames -> commands
• src/SMTBQ/README
• pair_style smtbq
• examples/PACKAGES/smtbq

6.2.82 SPH package

Contents:
An atom style, fixes, computes, and several pair styles which implements smoothed particle hydrodynamics (SPH) for
liquids. See the related MACHDYN package package for smooth Mach dynamics (SMD) for solids.
This package contains ideal gas, Lennard-Jones equation of states, Tait, and full support for complete (i.e. internal-
energy dependent) equations of state. It allows for plain or Monaghans XSPH integration of the equations of motion.
It has options for density continuity or density summation to propagate the density field. It has set command options
to set the internal energy and density of particles from the input script and allows the same quantities to be output with
thermodynamic output or to dump files via the compute property/atom command.
Author: Georg Ganzenmuller (Fraunhofer-Institute for High-Speed Dynamics, Ernst Mach Institute, Germany).
Supporting info:
• src/SPH: filenames -> commands

166 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

• src/SPH/README
• doc/PDF/SPH_LAMMPS_userguide.pdf
• examples/PACKAGES/sph
• https://www.lammps.org/movies.html#sph

6.2.83 SPIN package

Contents:
Model atomic magnetic spins classically, coupled to atoms moving in the usual manner via MD. Various pair, fix, and
compute styles.
Author: Julien Tranchida (Sandia).
Supporting info:
• src/SPIN: filenames -> commands
• Howto spins
• pair_style spin/dipole/cut
• pair_style spin/dipole/long
• pair_style spin/dmi
• pair_style spin/exchange
• pair_style spin/exchange/biquadratic
• pair_style spin/magelec
• pair_style spin/neel
• fix nve/spin
• fix langevin/spin
• fix precession/spin
• compute spin
• neb/spin
• examples/SPIN

6.2.84 SRD package

Contents:
A pair of fixes which implement the Stochastic Rotation Dynamics (SRD) method for coarse-graining of a solvent,
typically around large colloidal particles.
Supporting info:
• src/SRD: filenames -> commands
• fix srd

6.2. Package details 167

LAMMPS Documentation, Release stable 29Sep2021

• fix wall/srd
• examples/srd
• examples/ASPHERE
• https://www.lammps.org/movies.html#tri
• https://www.lammps.org/movies.html#line
• https://www.lammps.org/movies.html#poly

6.2.85 TALLY package

Contents:
Several compute styles that can be called when pairwise interactions are calculated to tally information (forces, heat
flux, energy, stress, etc) about individual interactions.
Author: Axel Kohlmeyer (Temple U).
Supporting info:
• src/TALLY: filenames -> commands
• src/TALLY/README
• compute */tally
• examples/PACKAGES/tally

6.2.86 UEF package

Contents:
A fix style for the integration of the equations of motion under extensional flow with proper boundary conditions, as
well as several supporting compute styles and an output option.
Author: David Nicholson (MIT).
Supporting info:
• src/UEF: filenames -> commands
• src/UEF/README
• fix nvt/uef
• fix npt/uef
• compute pressure/uef
• compute temp/uef
• dump cfg/uef
• examples/uef

168 Chapter 6. Optional packages

 LAMMPS Documentation, Release stable 29Sep2021

6.2.87 VORONOI package

Contents:
A compute command which calculates the Voronoi tesselation of a collection of atoms by wrapping the Voro++ library.
This can be used to calculate the local volume or each atoms or its near neighbors.
To use this package you must have the Voro++ library available on your system.
Author: Daniel Schwen (INL) while at LANL. The open-source Voro++ library was written by Chris Rycroft (Harvard
U) while at UC Berkeley and LBNL.
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/VORONOI: filenames -> commands
• src/VORONOI/README
• lib/voronoi/README
• compute voronoi/atom
• examples/voronoi

6.2.88 VTK package

Contents:
A dump vtk command which outputs snapshot info in the VTK format, enabling visualization by Paraview or other
visualization packages.
To use this package you must have VTK library available on your system.
Authors: Richard Berger (JKU) and Daniel Queteschiner (DCS Computing).
Install:
This package has specific installation instructions on the Build extras page.
Supporting info:
• src/VTK: filenames -> commands
• src/VTK/README
• lib/vtk/README
• dump vtk

6.2. Package details 169

LAMMPS Documentation, Release stable 29Sep2021

6.2.89 YAFF package

Contents:
Some potentials that are also implemented in the Yet Another Force Field (YAFF) code. The expressions and their use
are discussed in the following papers
• Vanduyfhuys et al., J. Comput. Chem., 36 (13), 1015-1027 (2015) link
• Vanduyfhuys et al., J. Comput. Chem., 39 (16), 999-1011 (2018) link
which discuss the QuickFF methodology.
Author: Steven Vandenbrande.
Supporting info:
• src/YAFF/README
• angle_style cross
• angle_style mm3
• bond_style mm3
• improper_style distharm
• improper_style sqdistharm
• pair_style mm3/switch3/coulgauss/long
• pair_style lj/switch3/coulgauss/long
• examples/PACKAGES/yaff

170 Chapter 6. Optional packages

 CHAPTER

SEVEN

ACCELERATE PERFORMANCE

This section describes various methods for improving LAMMPS performance for different classes of problems running
on different kinds of machines.
There are two thrusts to the discussion that follows. The first is using code options that implement alternate algorithms
that can speed-up a simulation. The second is to use one of the several accelerator packages provided with LAMMPS
that contain code optimized for certain kinds of hardware, including multi-core CPUs, GPUs, and Intel Xeon Phi
co-processors.
The Benchmark page of the LAMMPS website gives performance results for the various accelerator packages discussed
on the Speed packages doc page, for several of the standard LAMMPS benchmark problems, as a function of problem
size and number of compute nodes, on different hardware platforms.

7.1 Benchmarks

Current LAMMPS performance is discussed on the Benchmarks page of the LAMMPS website where timings and
parallel efficiency are listed. The page has several sections, which are briefly described below:
• CPU performance on 5 standard problems, strong and weak scaling
• GPU and Xeon Phi performance on same and related problems
• Comparison of cost of interatomic potentials
• Performance of huge, billion-atom problems
The 5 standard problems are as follow:
1. LJ = atomic fluid, Lennard-Jones potential with 2.5 sigma cutoff (55 neighbors per atom), NVE integration
2. Chain = bead-spring polymer melt of 100-mer chains, FENE bonds and LJ pairwise interactions with a 2^(1/6)
sigma cutoff (5 neighbors per atom), NVE integration
3. EAM = metallic solid, Cu EAM potential with 4.95 Angstrom cutoff (45 neighbors per atom), NVE integration
4. Chute = granular chute flow, frictional history potential with 1.1 sigma cutoff (7 neighbors per atom), NVE
integration
5. Rhodo = rhodopsin protein in solvated lipid bilayer, CHARMM force field with a 10 Angstrom LJ cutoff (440
neighbors per atom), particle-particle particle-mesh (PPPM) for long-range Coulombics, NPT integration
Input files for these 5 problems are provided in the bench directory of the LAMMPS distribution. Each has 32,000
atoms and runs for 100 timesteps. The size of the problem (number of atoms) can be varied using command-line
switches as described in the bench/README file. This is an easy way to test performance and either strong or weak
scalability on your machine.

171
LAMMPS Documentation, Release stable 29Sep2021

The bench directory includes a few log.* files that show performance of these 5 problems on 1 or 4 cores of Linux
desktop. The bench/FERMI and bench/KEPLER directories have input files and scripts and instructions for running
the same (or similar) problems using OpenMP or GPU or Xeon Phi acceleration options. See the README files in
those directories and the Accelerator packages pages for instructions on how to build LAMMPS and run on that kind
of hardware.
The bench/POTENTIALS directory has input files which correspond to the table of results on the Potentials section of
the Benchmarks web page. So you can also run those test problems on your machine.
The billion-atom section of the Benchmarks web page has performance data for very large benchmark runs of simple
Lennard-Jones (LJ) models, which use the bench/in.lj input script.

For all the benchmarks, a useful metric is the CPU cost per atom per timestep. Since performance scales roughly
linearly with problem size and timesteps for all LAMMPS models (i.e. interatomic or coarse-grained potentials), the
run time of any problem using the same model (atom style, force field, cutoff, etc) can then be estimated.
Performance on a parallel machine can also be predicted from one-core or one-node timings if the parallel efficiency
can be estimated. The communication bandwidth and latency of a particular parallel machine affects the efficiency.
On most machines LAMMPS will give a parallel efficiency on these benchmarks above 50% so long as the number of
atoms/core is a few 100 or greater, and closer to 100% for large numbers of atoms/core. This is for all-MPI mode with
one MPI task per core. For nodes with accelerator options or hardware (OpenMP, GPU, Phi), you should first measure
single node performance. Then you can estimate parallel performance for multi-node runs using the same logic as for
all-MPI mode, except that now you will typically need many more atoms/node to achieve good scalability.

7.2 Measuring performance

Before trying to make your simulation run faster, you should understand how it currently performs and where the
bottlenecks are.
The best way to do this is run the your system (actual number of atoms) for a modest number of timesteps (say 100
steps) on several different processor counts, including a single processor if possible. Do this for an equilibrium version
of your system, so that the 100-step timings are representative of a much longer run. There is typically no need to run
for 1000s of timesteps to get accurate timings; you can simply extrapolate from short runs.
For the set of runs, look at the timing data printed to the screen and log file at the end of each LAMMPS run. The
screen and logfile output page gives an overview.
Running on one (or a few processors) should give a good estimate of the serial performance and what portions of
the timestep are taking the most time. Running the same problem on a few different processor counts should give an
estimate of parallel scalability. I.e. if the simulation runs 16x faster on 16 processors, its 100% parallel efficient; if it
runs 8x faster on 16 processors, it’s 50% efficient.
The most important data to look at in the timing info is the timing breakdown and relative percentages. For example,
trying different options for speeding up the long-range solvers will have little impact if they only consume 10% of
the run time. If the pairwise time is dominating, you may want to look at GPU or OMP versions of the pair style,
as discussed below. Comparing how the percentages change as you increase the processor count gives you a sense of
how different operations within the timestep are scaling. Note that if you are running with a Kspace solver, there is
additional output on the breakdown of the Kspace time. For PPPM, this includes the fraction spent on FFTs, which can
be communication intensive.
Another important detail in the timing info are the histograms of atoms counts and neighbor counts. If these vary widely
across processors, you have a load-imbalance issue. This often results in inaccurate relative timing data, because
processors have to wait when communication occurs for other processors to catch up. Thus the reported times for
“Communication” or “Other” may be higher than they really are, due to load-imbalance. If this is an issue, you can
uncomment the MPI_Barrier() lines in src/timer.cpp, and re-compile LAMMPS, to obtain synchronized timings.

172 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

7.3 General tips

Note: this page is still a work in progress

Here is a list of general ideas for improving simulation performance. Most of them are only applicable to certain models
and certain bottlenecks in the current performance, so let the timing data you generate be your guide. It is hard, if not
impossible, to predict how much difference these options will make, since it is a function of problem size, number
of processors used, and your machine. There is no substitute for identifying performance bottlenecks, and trying out
various options.
• rRESPA
• Two-FFT PPPM
• Staggered PPPM
• single vs double PPPM
• partial charge PPPM
• verlet/split run style
• processor command for proc layout and numa layout
• load-balancing: balance and fix balance
Two-FFT PPPM, also called analytic differentiation or ad PPPM, uses 2 FFTs instead of the 4 FFTs used by the default
ik differentiation PPPM. However, 2-FFT PPPM also requires a slightly larger mesh size to achieve the same accuracy
as 4-FFT PPPM. For problems where the FFT cost is the performance bottleneck (typically large problems running on
many processors), 2-FFT PPPM may be faster than 4-FFT PPPM.
Staggered PPPM performs calculations using two different meshes, one shifted slightly with respect to the other. This
can reduce force aliasing errors and increase the accuracy of the method, but also doubles the amount of work required.
For high relative accuracy, using staggered PPPM allows one to half the mesh size in each dimension as compared to
regular PPPM, which can give around a 4x speedup in the kspace time. However, for low relative accuracy, using stag-
gered PPPM gives little benefit and can be up to 2x slower in the kspace time. For example, the rhodopsin benchmark
was run on a single processor, and results for kspace time vs. relative accuracy for the different methods are shown
in the figure below. For this system, staggered PPPM (using ik differentiation) becomes useful when using a relative
accuracy of slightly greater than 1e-5 and above.

7.3. General tips 173

LAMMPS Documentation, Release stable 29Sep2021

Note: Using staggered PPPM may not give the same increase in accuracy of energy and pressure as it does in forces,
so some caution must be used if energy and/or pressure are quantities of interest, such as when using a barostat.

7.4 Accelerator packages

Accelerated versions of various pair_style, fixes, computes, and other commands have been added to LAMMPS, which
will typically run faster than the standard non-accelerated versions. Some require appropriate hardware to be present
on your system, e.g. GPUs or Intel Xeon Phi co-processors.
All of these commands are in packages provided with LAMMPS. An overview of packages is give on the Packages doc
pages.
These are the accelerator packages currently in LAMMPS:

GPU Package for GPUs via CUDA, OpenCL, or ROCm HIP

INTEL Package for Intel CPUs and Intel Xeon Phi
KOKKOS Package for NVIDIA GPUs, Intel Xeon Phi, and OpenMP threading
OPENMP Package for OpenMP threading and generic CPU optimizations
OPT Package generic CPU optimizations

174 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

7.4.1 GPU package

The GPU package was developed by Mike Brown while at SNL and ORNL (now at Intel Corp.) and his collaborators,
particularly Trung Nguyen (now at Northwestern). Support for AMD GPUs via HIP was added by Vsevolod Nikolskiy
and coworkers at HSE University.
The GPU package provides GPU versions of many pair styles and for parts of the kspace_style pppm for long-range
Coulombics. It has the following general features:
• It is designed to exploit common GPU hardware configurations where one or more GPUs are coupled to many
cores of one or more multi-core CPUs, e.g. within a node of a parallel machine.
• Atom-based data (e.g. coordinates, forces) are moved back-and-forth between the CPU(s) and GPU every
timestep.
• Neighbor lists can be built on the CPU or on the GPU
• The charge assignment and force interpolation portions of PPPM can be run on the GPU. The FFT portion, which
requires MPI communication between processors, runs on the CPU.
• Force computations of different style (pair vs. bond/angle/dihedral/improper) can be performed concurrently on
the GPU and CPU(s), respectively.
• It allows for GPU computations to be performed in single or double precision, or in mixed-mode precision, where
pairwise forces are computed in single precision, but accumulated into double-precision force vectors.
• LAMMPS-specific code is in the GPU package. It makes calls to a generic GPU library in the lib/gpu directory.
This library provides either Nvidia support, AMD support, or more general OpenCL support (for Nvidia GPUs,
AMD GPUs, Intel GPUs, and multi-core CPUs). so that the same functionality is supported on a variety of
hardware.
Required hardware/software:
To compile and use this package in CUDA mode, you currently need to have an NVIDIA GPU and install the corre-
sponding NVIDIA CUDA toolkit software on your system (this is only tested on Linux and unsupported on Windows):
• Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/*/information
• Go to http://www.nvidia.com/object/cuda_get.html
• Install a driver and toolkit appropriate for your system (SDK is not necessary)
• Run lammps/lib/gpu/nvc_get_devices (after building the GPU library, see below) to list supported devices and
properties
To compile and use this package in OpenCL mode, you currently need to have the OpenCL headers and the (ven-
dor neutral) OpenCL library installed. In OpenCL mode, the acceleration depends on having an OpenCL Instal-
lable Client Driver (ICD) installed. There can be multiple of them for the same or different hardware (GPUs, CPUs,
Accelerators) installed at the same time. OpenCL refers to those as ‘platforms’. The GPU library will try to auto-
select the best suitable platform, but this can be overridden using the platform option of the package command. run
lammps/lib/gpu/ocl_get_devices to get a list of available platforms and devices with a suitable ICD available.
To compile and use this package for Intel GPUs, OpenCL or the Intel oneAPI HPC Toolkit can be installed using linux
package managers. The latter also provides optimized C++, MPI, and many other libraries and tools. See:
• https://software.intel.com/content/www/us/en/develop/tools/oneapi/hpc-toolkit/download.html
If you do not have a discrete GPU card installed, this package can still provide significant speedups on some CPUs that
include integrated GPUs. Additionally, for many macs, OpenCL is already included with the OS and Makefiles are
available in the lib/gpu directory.
To compile and use this package in HIP mode, you have to have the AMD ROCm software installed. Versions of ROCm
older than 3.5 are currently deprecated by AMD.

7.4. Accelerator packages 175

LAMMPS Documentation, Release stable 29Sep2021

Building LAMMPS with the GPU package:

See the Build extras page for instructions.
Run with the GPU package from the command line:
The mpirun or mpiexec command sets the total number of MPI tasks used by LAMMPS (one or multiple per compute
node) and the number of MPI tasks used per node. E.g. the mpirun command in MPICH does this via its -np and -ppn
switches. Ditto for OpenMPI via -np and -npernode.
When using the GPU package, you cannot assign more than one GPU to a single MPI task. However multiple MPI
tasks can share the same GPU, and in many cases it will be more efficient to run this way. Likewise it may be more
efficient to use less MPI tasks/node than the available # of CPU cores. Assignment of multiple MPI tasks to a GPU
will happen automatically if you create more MPI tasks/node than there are GPUs/mode. E.g. with 8 MPI tasks/node
and 2 GPUs, each GPU will be shared by 4 MPI tasks.
The GPU package also has limited support for OpenMP for both multi-threading and vectorization of routines that are
run on the CPUs. This requires that the GPU library and LAMMPS are built with flags to enable OpenMP support
(e.g. -fopenmp). Some styles for time integration are also available in the GPU package. These run completely on the
CPUs in full double precision, but exploit multi-threading and vectorization for faster performance.
Use the “-sf gpu” command-line switch, which will automatically append “gpu” to styles that support it. Use the “-pk
gpu Ng” command-line switch to set Ng = # of GPUs/node to use. If Ng is 0, the number is selected automatically as
the number of matching GPUs that have the highest number of compute cores.

lmp_machine -sf gpu -pk gpu 1 -in in.script # 1 MPI task uses 1␣
,→GPU

mpirun -np 12 lmp_machine -sf gpu -pk gpu 2 -in in.script # 12 MPI tasks share␣
,→2 GPUs on a single 16-core (or whatever) node

mpirun -np 48 -ppn 12 lmp_machine -sf gpu -pk gpu 2 -in in.script # ditto on 4 16-core␣
,→nodes

Note that if the “-sf gpu” switch is used, it also issues a default package gpu 0 command, which will result in automatic
selection of the number of GPUs to use.
Using the “-pk” switch explicitly allows for setting of the number of GPUs/node to use and additional options. Its
syntax is the same as the “package gpu” command. See the package command page for details, including the default
values used for all its options if it is not specified.
Note that the default for the package gpu command is to set the Newton flag to “off” pairwise interactions. It does
not affect the setting for bonded interactions (LAMMPS default is “on”). The “off” setting for pairwise interaction is
currently required for GPU package pair styles.
Or run with the GPU package by editing an input script:
The discussion above for the mpirun/mpiexec command, MPI tasks/node, and use of multiple MPI tasks/GPU is the
same.
Use the suffix gpu command, or you can explicitly add an “gpu” suffix to individual styles in your input script, e.g.

pair_style lj/cut/gpu 2.5

You must also use the package gpu command to enable the GPU package, unless the “-sf gpu” or “-pk gpu” command-
line switches were used. It specifies the number of GPUs/node to use, as well as other options.
Speed-ups to expect:
The performance of a GPU versus a multi-core CPU is a function of your hardware, which pair style is used, the number
of atoms/GPU, and the precision used on the GPU (double, single, mixed). Using the GPU package in OpenCL mode
on CPUs (which uses vectorization and multithreading) is usually resulting in inferior performance compared to using
LAMMPS’ native threading and vectorization support in the OPENMP and INTEL packages.

176 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

See the Benchmark page of the LAMMPS website for performance of the GPU package on various hardware, including
the Titan HPC platform at ORNL.
You should also experiment with how many MPI tasks per GPU to use to give the best performance for your problem
and machine. This is also a function of the problem size and the pair style being using. Likewise, you should experiment
with the precision setting for the GPU library to see if single or mixed precision will give accurate results, since they
will typically be faster.
MPI parallelism typically outperforms OpenMP parallelism, but in some cases using fewer MPI tasks and multiple
OpenMP threads with the GPU package can give better performance. 3-body potentials can often perform better with
multiple OMP threads because the inter-process communication is higher for these styles with the GPU package in
order to allow deterministic results.
Guidelines for best performance:
• Using multiple MPI tasks per GPU will often give the best performance, as allowed my most multi-core
CPU/GPU configurations.
• If the number of particles per MPI task is small (e.g. 100s of particles), it can be more efficient to run with fewer
MPI tasks per GPU, even if you do not use all the cores on the compute node.
• The package gpu command has several options for tuning performance. Neighbor lists can be built on the GPU
or CPU. Force calculations can be dynamically balanced across the CPU cores and GPUs. GPU-specific settings
can be made which can be optimized for different hardware. See the package command page for details.
• As described by the package gpu command, GPU accelerated pair styles can perform computations asyn-
chronously with CPU computations. The “Pair” time reported by LAMMPS will be the maximum of the time
required to complete the CPU pair style computations and the time required to complete the GPU pair style
computations. Any time spent for GPU-enabled pair styles for computations that run simultaneously with bond,
angle, dihedral, improper, and long-range calculations will not be included in the “Pair” time.
• Since only part of the pppm kspace style is GPU accelerated, it may be faster to only use GPU acceleration for
Pair styles with long-range electrostatics. See the “pair/only” keyword of the package command for a shortcut to
do that. The work between kspace on the CPU and non-bonded interactions on the GPU can be balanced through
adjusting the coulomb cutoff without loss of accuracy.
• When the mode setting for the package gpu command is force/neigh, the time for neighbor list calculations on
the GPU will be added into the “Pair” time, not the “Neigh” time. An additional breakdown of the times required
for various tasks on the GPU (data copy, neighbor calculations, force computations, etc) are output only with the
LAMMPS screen output (not in the log file) at the end of each run. These timings represent total time spent on
the GPU for each routine, regardless of asynchronous CPU calculations.
• The output section “GPU Time Info (average)” reports “Max Mem / Proc”. This is the maximum memory used
at one time on the GPU for data storage by a single MPI process.

7.4. Accelerator packages 177

LAMMPS Documentation, Release stable 29Sep2021

Restrictions

None.

7.4.2 INTEL package

The INTEL package is maintained by Mike Brown at Intel Corporation. It provides two methods for accelerating
simulations, depending on the hardware you have. The first is acceleration on Intel CPUs by running in single, mixed,
or double precision with vectorization. The second is acceleration on Intel Xeon Phi co-processors via offloading
neighbor list and non-bonded force calculations to the Phi. The same C++ code is used in both cases. When offloading
to a co-processor from a CPU, the same routine is run twice, once on the CPU and once with an offload flag. This
allows LAMMPS to run on the CPU cores and co-processor cores simultaneously.

Currently Available INTEL Styles

• Angle Styles: charmm, harmonic

• Bond Styles: fene, fourier, harmonic
• Dihedral Styles: charmm, fourier, harmonic, opls
• Fixes: nve, npt, nvt, nvt/sllod, nve/asphere
• Improper Styles: cvff, harmonic
• Pair Styles: airebo, airebo/morse, buck/coul/cut, buck/coul/long, buck, dpd, eam, eam/alloy, eam/fs, gayberne,
lj/charmm/coul/charmm, lj/charmm/coul/long, lj/cut, lj/cut/coul/long, lj/long/coul/long, rebo, sw, tersoff
• K-Space Styles: pppm, pppm/disp

Warning: None of the styles in the INTEL package currently support computing per-atom stress. If any compute
or fix in your input requires it, LAMMPS will abort with an error message.

Speed-up to expect

The speedup will depend on your simulation, the hardware, which styles are used, the number of atoms, and the floating-
point precision mode. Performance improvements are shown compared to LAMMPS without using other acceleration
packages as these are under active development (and subject to performance changes). The measurements were per-
formed using the input files available in the src/INTEL/TEST directory with the provided run script. These are scal-
able in size; the results given are with 512K particles (524K for Liquid Crystal). Most of the simulations are standard
LAMMPS benchmarks (indicated by the filename extension in parenthesis) with modifications to the run length and to
add a warm-up run (for use with offload benchmarks).

178 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Results are speedups obtained on Intel Xeon E5-2697v4 processors (code-named Broadwell), Intel Xeon Phi 7250
processors (code-named Knights Landing), and Intel Xeon Gold 6148 processors (code-named Skylake) with “June
2017” LAMMPS built with Intel Parallel Studio 2017 update 2. Results are with 1 MPI task per physical core. See
src/INTEL/TEST/README for the raw simulation rates and instructions to reproduce.

Accuracy and order of operations

In most molecular dynamics software, parallelization parameters (# of MPI, OpenMP, and vectorization) can change the
results due to changing the order of operations with finite-precision calculations. The INTEL package is deterministic.
This means that the results should be reproducible from run to run with the same parallel configurations and when using
deterministic libraries or library settings (MPI, OpenMP, FFT). However, there are differences in the INTEL package
that can change the order of operations compared to LAMMPS without acceleration:
• Neighbor lists can be created in a different order
• Bins used for sorting atoms can be oriented differently
• The default stencil order for PPPM is 7. By default, LAMMPS will calculate other PPPM parameters to fit the
desired accuracy with this order
• The newton setting applies to all atoms, not just atoms shared between MPI tasks
• Vectorization can change the order for adding pairwise forces
• When using the -DLMP_USE_MKL_RNG define (all included intel optimized makefiles do) at build time, the
random number generator for dissipative particle dynamics (pair style dpd/intel) uses the Mersenne Twister gen-
erator included in the Intel MKL library (that should be more robust than the default Masaglia random number
generator)
The precision mode (described below) used with the INTEL package can change the accuracy of the calculations. For
the default mixed precision option, calculations between pairs or triplets of atoms are performed in single precision,
intended to be within the inherent error of MD simulations. All accumulation is performed in double precision to
prevent the error from growing with the number of atoms in the simulation. Single precision mode should not be used
without appropriate validation.

7.4. Accelerator packages 179

LAMMPS Documentation, Release stable 29Sep2021

Quick Start for Experienced Users

LAMMPS should be built with the INTEL package installed. Simulations should be run with 1 MPI task per physical
core, not hardware thread.
• Edit src/MAKE/OPTIONS/Makefile.intel_cpu_intelmpi as necessary.
• Set the environment variable KMP_BLOCKTIME=0
• “-pk intel 0 omp $t -sf intel” added to LAMMPS command-line
• $t should be 2 for Intel Xeon CPUs and 2 or 4 for Intel Xeon Phi
• For some of the simple 2-body potentials without long-range electrostatics, performance and scalability can be
better with the “newton off” setting added to the input script
• For simulations on higher node counts, add “processors * * * grid numa” to the beginning of the input script for
better scalability
• If using kspace_style pppm in the input script, add “kspace_modify diff ad” for better performance
For Intel Xeon Phi CPUs:
• Runs should be performed using MCDRAM.
For simulations using kspace_style pppm on Intel CPUs supporting AVX-512:
• Add “kspace_modify diff ad” to the input script
• The command-line option should be changed to “-pk intel 0 omp $r lrt yes -sf intel” where $r is the number of
threads minus 1.
• Do not use thread affinity (set KMP_AFFINITY=none)
• The “newton off” setting may provide better scalability
For Intel Xeon Phi co-processors (Offload):
• Edit src/MAKE/OPTIONS/Makefile.intel_co-processor as necessary
• “-pk intel N omp 1” added to command-line where N is the number of co-processors per node.

Required hardware/software

When using Intel compilers version 16.0 or later is required.

In order to use offload to co-processors, an Intel Xeon Phi co-processor and an Intel compiler are required.
Although any compiler can be used with the INTEL package, currently, vectorization directives are disabled by de-
fault when not using Intel compilers due to lack of standard support and observations of decreased performance. The
OpenMP standard now supports directives for vectorization and we plan to transition the code to this standard once it
is available in most compilers. We expect this to allow improved performance and support with other compilers.
For Intel Xeon Phi x200 series processors (code-named Knights Landing), there are multiple configuration options
for the hardware. For best performance, we recommend that the MCDRAM is configured in “Flat” mode and with
the cluster mode set to “Quadrant” or “SNC4”. “Cache” mode can also be used, although the performance might be
slightly lower.

180 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Notes about Simultaneous Multithreading

Modern CPUs often support Simultaneous Multithreading (SMT). On Intel processors, this is called Hyper-Threading
(HT) technology. SMT is hardware support for running multiple threads efficiently on a single core. Hardware threads
or logical cores are often used to refer to the number of threads that are supported in hardware. For example, the
Intel Xeon E5-2697v4 processor is described as having 36 cores and 72 threads. This means that 36 MPI processes or
OpenMP threads can run simultaneously on separate cores, but that up to 72 MPI processes or OpenMP threads can be
running on the CPU without costly operating system context switches.
Molecular dynamics simulations will often run faster when making use of SMT. If a thread becomes stalled, for example
because it is waiting on data that has not yet arrived from memory, another thread can start running so that the CPU
pipeline is still being used efficiently. Although benefits can be seen by launching a MPI task for every hardware
thread, for multinode simulations, we recommend that OpenMP threads are used for SMT instead, either with the
INTEL package, OPENMP package, or KOKKOS package. In the example above, up to 36X speedups can be observed
by using all 36 physical cores with LAMMPS. By using all 72 hardware threads, an additional 10-30% performance
gain can be achieved.
The BIOS on many platforms allows SMT to be disabled, however, we do not recommend this on modern processors
as there is little to no benefit for any software package in most cases. The operating system will report every hardware
thread as a separate core allowing one to determine the number of hardware threads available. On Linux systems, this
information can normally be obtained with:

cat /proc/cpuinfo

Building LAMMPS with the INTEL package

See the Build extras page for instructions. Some additional details are covered here.
For building with make, several example Makefiles for building with the Intel compiler are included with LAMMPS
in the src/MAKE/OPTIONS/ directory:

Makefile.intel_cpu_intelmpi # Intel Compiler, Intel MPI, No Offload

Makefile.knl # Intel Compiler, Intel MPI, No Offload
Makefile.intel_cpu_mpich # Intel Compiler, MPICH, No Offload
Makefile.intel_cpu_openpmi # Intel Compiler, OpenMPI, No Offload
Makefile.intel_co-processor # Intel Compiler, Intel MPI, Offload

Makefile.knl is identical to Makefile.intel_cpu_intelmpi except that it explicitly specifies that vectorization should be
for Intel Xeon Phi x200 processors making it easier to cross-compile. For users with recent installations of Intel Parallel
Studio, the process can be as simple as:

make yes-intel
source /opt/intel/parallel_studio_xe_2016.3.067/psxevars.sh
# or psxevars.csh for C-shell
make intel_cpu_intelmpi

Note that if you build with support for a Phi co-processor, the same binary can be used on nodes with or without co-
processors installed. However, if you do not have co-processors on your system, building without offload support will
produce a smaller binary.
The general requirements for Makefiles with the INTEL package are as follows. When using Intel compilers, “-
restrict” is required and “-qopenmp” is highly recommended for CCFLAGS and LINKFLAGS. CCFLAGS should
include “-DLMP_INTEL_USELRT” (unless POSIX Threads are not supported in the build environment) and “-
DLMP_USE_MKL_RNG” (unless Intel Math Kernel Library (MKL) is not available in the build environment). For
Intel compilers, LIB should include “-ltbbmalloc” or if the library is not available, “-DLMP_INTEL_NO_TBB” can be

7.4. Accelerator packages 181

LAMMPS Documentation, Release stable 29Sep2021

added to CCFLAGS. For builds supporting offload, “-DLMP_INTEL_OFFLOAD” is required for CCFLAGS and “-
qoffload” is required for LINKFLAGS. Other recommended CCFLAG options for best performance are “-O2 -fno-alias
-ansi-alias -qoverride-limits fp-model fast=2 -no-prec-div”.

Note: See the src/INTEL/README file for additional flags that might be needed for best performance on Intel server
processors code-named “Skylake”.

Note: The vectorization and math capabilities can differ depending on the CPU. For Intel compilers, the “-x” flag
specifies the type of processor for which to optimize. “-xHost” specifies that the compiler should build for the processor
used for compiling. For Intel Xeon Phi x200 series processors, this option is “-xMIC-AVX512”. For fourth generation
Intel Xeon (v4/Broadwell) processors, “-xCORE-AVX2” should be used. For older Intel Xeon processors, “-xAVX”
will perform best in general for the different simulations in LAMMPS. The default in most of the example Makefiles
is to use “-xHost”, however this should not be used when cross-compiling.

Running LAMMPS with the INTEL package

Running LAMMPS with the INTEL package is similar to normal use with the exceptions that one should 1) specify
that LAMMPS should use the INTEL package, 2) specify the number of OpenMP threads, and 3) optionally specify the
specific LAMMPS styles that should use the INTEL package. 1) and 2) can be performed from the command-line or by
editing the input script. 3) requires editing the input script. Advanced performance tuning options are also described
below to get the best performance.
When running on a single node (including runs using offload to a co-processor), best performance is normally obtained
by using 1 MPI task per physical core and additional OpenMP threads with SMT. For Intel Xeon processors, 2 OpenMP
threads should be used for SMT. For Intel Xeon Phi CPUs, 2 or 4 OpenMP threads should be used (best choice depends
on the simulation). In cases where the user specifies that LRT mode is used (described below), 1 or 3 OpenMP threads
should be used. For multi-node runs, using 1 MPI task per physical core will often perform best, however, depending
on the machine and scale, users might get better performance by decreasing the number of MPI tasks and using more
OpenMP threads. For performance, the product of the number of MPI tasks and OpenMP threads should not exceed
the number of available hardware threads in almost all cases.

Note: Setting core affinity is often used to pin MPI tasks and OpenMP threads to a core or group of cores so that mem-
ory access can be uniform. Unless disabled at build time, affinity for MPI tasks and OpenMP threads on the host (CPU)
will be set by default on the host when using offload to a co-processor. In this case, it is unnecessary to use other methods
to control affinity (e.g. taskset, numactl, I_MPI_PIN_DOMAIN, etc.). This can be disabled with the no_affinity option
to the package intel command or by disabling the option at build time (by adding -DINTEL_OFFLOAD_NOAFFINITY
to the CCFLAGS line of your Makefile). Disabling this option is not recommended, especially when running on a ma-
chine with Intel Hyper-Threading technology disabled.

182 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Run with the INTEL package from the command line

To enable INTEL optimizations for all available styles used in the input script, the “-sf intel” command-line switch can
be used without any requirement for editing the input script. This switch will automatically append “intel” to styles
that support it. It also invokes a default command: package intel 1. This package command is used to set options
for the INTEL package. The default package command will specify that INTEL calculations are performed in mixed
precision, that the number of OpenMP threads is specified by the OMP_NUM_THREADS environment variable, and
that if co-processors are present and the binary was built with offload support, that 1 co-processor per node will be used
with automatic balancing of work between the CPU and the co-processor.
You can specify different options for the INTEL package by using the “-pk intel Nphi” command-line switch with
keyword/value pairs as specified in the documentation. Here, Nphi = # of Xeon Phi co-processors/node (ignored without
offload support). Common options to the INTEL package include omp to override any OMP_NUM_THREADS setting
and specify the number of OpenMP threads, mode to set the floating-point precision mode, and lrt to enable Long-
Range Thread mode as described below. See the package intel command for details, including the default values used
for all its options if not specified, and how to set the number of OpenMP threads via the OMP_NUM_THREADS
environment variable if desired.
Examples (see documentation for your MPI/Machine for differences in launching MPI applications):

mpirun -np 72 -ppn 36 lmp_machine -sf intel -in in.script ␣

,→ # 2 nodes, 36 MPI tasks/node, $OMP_NUM_THREADS OpenMP Threads

mpirun -np 72 -ppn 36 lmp_machine -sf intel -in in.script -pk intel 0 omp 2 mode double ␣
,→ # Don't use any co-processors that might be available, use 2 OpenMP threads for each␣

,→task, use double precision

Or run with the INTEL package by editing an input script

As an alternative to adding command-line arguments, the input script can be edited to enable the INTEL package. This
requires adding the package intel command to the top of the input script. For the second example above, this would be:

package intel 0 omp 2 mode double

To enable the INTEL package only for individual styles, you can add an “intel” suffix to the individual style, e.g.:

pair_style lj/cut/intel 2.5

Alternatively, the suffix intel command can be added to the input script to enable INTEL styles for the commands that
follow in the input script.

Tuning for Performance

Note: The INTEL package will perform better with modifications to the input script when PPPM is used:
kspace_modify diff ad should be added to the input script.

Long-Range Thread (LRT) mode is an option to the package intel command that can improve performance when using
PPPM for long-range electrostatics on processors with SMT. It generates an extra pthread for each MPI task. The
thread is dedicated to performing some of the PPPM calculations and MPI communications. This feature requires
setting the pre-processor flag -DLMP_INTEL_USELRT in the makefile when compiling LAMMPS. It is unset in the
default makefiles (Makefile.mpi and Makefile.serial) but it is set in all makefiles tuned for the INTEL package. On
Intel Xeon Phi x200 series CPUs, the LRT feature will likely improve performance, even on a single node. On Intel
Xeon processors, using this mode might result in better performance when using multiple nodes, depending on the

7.4. Accelerator packages 183

LAMMPS Documentation, Release stable 29Sep2021

specific machine configuration. To enable LRT mode, specify that the number of OpenMP threads is one less than
would normally be used for the run and add the “lrt yes” option to the “-pk” command-line suffix or “package intel”
command. For example, if a run would normally perform best with “-pk intel 0 omp 4”, instead use “-pk intel 0 omp
3 lrt yes”. When using LRT, you should set the environment variable “KMP_AFFINITY=none”. LRT mode is not
supported when using offload.

Note: Changing the newton setting to off can improve performance and/or scalability for simple 2-body potentials
such as lj/cut or when using LRT mode on processors supporting AVX-512.

Not all styles are supported in the INTEL package. You can mix the INTEL package with styles from the OPT package
or the OPENMP package. Of course, this requires that these packages were installed at build time. This can performed
automatically by using “-sf hybrid intel opt” or “-sf hybrid intel omp” command-line options. Alternatively, the “opt”
and “omp” suffixes can be appended manually in the input script. For the latter, the package omp command must be in
the input script or the “-pk omp Nt” command-line switch must be used where Nt is the number of OpenMP threads.
The number of OpenMP threads should not be set differently for the different packages. Note that the suffix hybrid intel
omp command can also be used within the input script to automatically append the “omp” suffix to styles when INTEL
styles are not available.

Note: For simulations on higher node counts, add processors * * * grid numa to the beginning of the input script for
better scalability.

When running on many nodes, performance might be better when using fewer OpenMP threads and more MPI tasks.
This will depend on the simulation and the machine. Using the verlet/split run style might also give better performance
for simulations with PPPM electrostatics. Note that this is an alternative to LRT mode and the two cannot be used
together.
Currently, when using Intel MPI with Intel Xeon Phi x200 series CPUs, better performance might be obtained by setting
the environment variable “I_MPI_SHM_LMT=shm” for Linux kernels that do not yet have full support for AVX-512.
Runs on Intel Xeon Phi x200 series processors will always perform better using MCDRAM. Please consult your system
documentation for the best approach to specify that MPI runs are performed in MCDRAM.

Tuning for Offload Performance

The default settings for offload should give good performance.

When using LAMMPS with offload to Intel co-processors, best performance will typically be achieved with concurrent
calculations performed on both the CPU and the co-processor. This is achieved by offloading only a fraction of the
neighbor and pair computations to the co-processor or using hybrid pair styles where only one style uses the “intel”
suffix. For simulations with long-range electrostatics or bond, angle, dihedral, improper calculations, computation
and data transfer to the co-processor will run concurrently with computations and MPI communications for these
calculations on the host CPU. This is illustrated in the figure below for the rhodopsin protein benchmark running on
E5-2697v2 processors with a Intel Xeon Phi 7120p co-processor. In this plot, the vertical access is time and routines
running at the same time are running concurrently on both the host and the co-processor.

184 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

The fraction of the offloaded work is controlled by the balance keyword in the package intel command. A balance of
0 runs all calculations on the CPU. A balance of 1 runs all supported calculations on the co-processor. A balance of
0.5 runs half of the calculations on the co-processor. Setting the balance to -1 (the default) will enable dynamic load
balancing that continuously adjusts the fraction of offloaded work throughout the simulation. Because data transfer
cannot be timed, this option typically produces results within 5 to 10 percent of the optimal fixed balance.
If running short benchmark runs with dynamic load balancing, adding a short warm-up run (10-20 steps) will allow
the load-balancer to find a near-optimal setting that will carry over to additional runs.
The default for the package intel command is to have all the MPI tasks on a given compute node use a single Xeon Phi
co-processor. In general, running with a large number of MPI tasks on each node will perform best with offload. Each
MPI task will automatically get affinity to a subset of the hardware threads available on the co-processor. For example,
if your card has 61 cores, with 60 cores available for offload and 4 hardware threads per core (240 total threads), running
with 24 MPI tasks per node will cause each MPI task to use a subset of 10 threads on the co-processor. Fine tuning of
the number of threads to use per MPI task or the number of threads to use per core can be accomplished with keyword
settings of the package intel command.
The INTEL package has two modes for deciding which atoms will be handled by the co-processor. This choice is
controlled with the ghost keyword of the package intel command. When set to 0, ghost atoms (atoms at the borders
between MPI tasks) are not offloaded to the card. This allows for overlap of MPI communication of forces with compu-
tation on the co-processor when the newton setting is “on”. The default is dependent on the style being used, however,
better performance may be achieved by setting this option explicitly.
When using offload with CPU Hyper-Threading disabled, it may help performance to use fewer MPI tasks and OpenMP
threads than available cores. This is due to the fact that additional threads are generated internally to handle the asyn-
chronous offload tasks.
If pair computations are being offloaded to an Intel Xeon Phi co-processor, a diagnostic line is printed to the screen (not
to the log file), during the setup phase of a run, indicating that offload mode is being used and indicating the number of
co-processor threads per MPI task. Additionally, an offload timing summary is printed at the end of each run. When
offloading, the frequency for atom sorting is changed to 1 so that the per-atom data is effectively sorted at every rebuild
of the neighbor lists. All the available co-processor threads on each Phi will be divided among MPI tasks, unless the
tptask option of the “-pk intel” command-line switch is used to limit the co-processor threads per MPI task.

7.4. Accelerator packages 185

LAMMPS Documentation, Release stable 29Sep2021

Restrictions

When offloading to a co-processor, hybrid styles that require skip lists for neighbor builds cannot be offloaded. Using
hybrid/overlay is allowed. Only one intel accelerated style may be used with hybrid styles when offloading. Spe-
cial_bonds exclusion lists are not currently supported with offload, however, the same effect can often be accomplished
by setting cutoffs for excluded atom types to 0. None of the pair styles in the INTEL package currently support the
“inner”, “middle”, “outer” options for rRESPA integration via the run_style respa command; only the “pair” option is
supported.

References

• Brown, W.M., Carrillo, J.-M.Y., Mishra, B., Gavhane, N., Thakkar, F.M., De Kraker, A.R., Yamada, M., Ang,
J.A., Plimpton, S.J., “Optimizing Classical Molecular Dynamics in LAMMPS,” in Intel Xeon Phi Processor
High Performance Programming: Knights Landing Edition, J. Jeffers, J. Reinders, A. Sodani, Eds. Morgan
Kaufmann.
• Brown, W. M., Semin, A., Hebenstreit, M., Khvostov, S., Raman, K., Plimpton, S.J. Increasing Molecular Dy-
namics Simulation Rates with an 8-Fold Increase in Electrical Power Efficiency. 2016 High Performance Com-
puting, Networking, Storage and Analysis, SC16: International Conference (pp. 82-95).
• Brown, W.M., Carrillo, J.-M.Y., Gavhane, N., Thakkar, F.M., Plimpton, S.J. Optimizing Legacy Molecular Dy-
namics Software with Directive-Based Offload. Computer Physics Communications. 2015. 195: p. 95-101.

7.4.3 KOKKOS package

Kokkos is a templated C++ library that provides abstractions to allow a single implementation of an application kernel
(e.g. a pair style) to run efficiently on different kinds of hardware, such as GPUs, Intel Xeon Phis, or many-core CPUs.
Kokkos maps the C++ kernel onto different back end languages such as CUDA, OpenMP, or Pthreads. The Kokkos
library also provides data abstractions to adjust (at compile time) the memory layout of data structures like 2d and 3d
arrays to optimize performance on different hardware. For more information on Kokkos, see the Kokkos GitHub page.
The LAMMPS KOKKOS package contains versions of pair, fix, and atom styles that use data structures and macros
provided by the Kokkos library, which is included with LAMMPS in /lib/kokkos. The KOKKOS package was developed
primarily by Christian Trott (Sandia) and Stan Moore (Sandia) with contributions of various styles by others, including
Sikandar Mashayak (UIUC), Ray Shan (Sandia), and Dan Ibanez (Sandia). For more information on developing using
Kokkos abstractions see the Kokkos Wiki.
Kokkos currently provides support for 4 modes of execution (per MPI task). These are Serial (MPI-only for CPUs and
Intel Phi), OpenMP (threading for many-core CPUs and Intel Phi), CUDA (for NVIDIA GPUs) and HIP (for AMD
GPUs). You choose the mode at build time to produce an executable compatible with a specific hardware.

C++14 support
Kokkos requires using a compiler that supports the c++14 standard. For some compilers, it may be necessary to add a
flag to enable c++14 support. For example, the GNU compiler uses the -std=c++14 flag. For a list of compilers that
have been tested with the Kokkos library, see the Kokkos README.

NVIDIA CUDA support

To build with Kokkos support for NVIDIA GPUs, the NVIDIA CUDA toolkit software version 9.0 or later must be
installed on your system. See the discussion for the GPU package for details of how to check and do this.

186 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

CUDA and MPI library compatibility

Kokkos with CUDA currently implicitly assumes that the MPI library is GPU-aware. This is not always the case,
especially when using pre-compiled MPI libraries provided by a Linux distribution. This is not a problem when using
only a single GPU with a single MPI rank. When running with multiple MPI ranks, you may see segmentation faults
without GPU-aware MPI support. These can be avoided by adding the flags -pk kokkos gpu/aware off to the LAMMPS
command line or by using the command package kokkos gpu/aware off in the input file.

AMD GPU support

To build with Kokkos the HIPCC compiler from the AMD ROCm software version 3.5 or later is required. Supporting
this Kokkos mode in LAMMPS is still work in progress. Please contact the LAMMPS developers if you run into
problems.

Building LAMMPS with the KOKKOS package

See the Build extras page for instructions.

Running LAMMPS with the KOKKOS package

All Kokkos operations occur within the context of an individual MPI task running on a single node of the machine.
The total number of MPI tasks used by LAMMPS (one or multiple per compute node) is set in the usual manner via
the mpirun or mpiexec commands, and is independent of Kokkos. E.g. the mpirun command in OpenMPI does this
via its -np and -npernode switches. Ditto for MPICH via -np and -ppn.

Running on a multi-core CPU

Here is a quick overview of how to use the KOKKOS package for CPU acceleration, assuming one or more 16-core
nodes.

mpirun -np 16 lmp_kokkos_mpi_only -k on -sf kk -in in.lj # 1 node, 16 MPI tasks/

,→node, no multi-threading

mpirun -np 2 -ppn 1 lmp_kokkos_omp -k on t 16 -sf kk -in in.lj # 2 nodes, 1 MPI task/
,→node, 16 threads/task

mpirun -np 2 lmp_kokkos_omp -k on t 8 -sf kk -in in.lj # 1 node, 2 MPI tasks/

,→node, 8 threads/task

mpirun -np 32 -ppn 4 lmp_kokkos_omp -k on t 4 -sf kk -in in.lj # 8 nodes, 4 MPI tasks/
,→node, 4 threads/task

To run using the KOKKOS package, use the “-k on”, “-sf kk” and “-pk kokkos” command-line switches in your mpirun
command. You must use the “-k on” command-line switch to enable the KOKKOS package. It takes additional argu-
ments for hardware settings appropriate to your system. For OpenMP use:

-k on t Nt

The “t Nt” option specifies how many OpenMP threads per MPI task to use with a node. The default is Nt = 1, which
is MPI-only mode. Note that the product of MPI tasks * OpenMP threads/task should not exceed the physical number
of cores (on a node), otherwise performance will suffer. If Hyper-Threading (HT) is enabled, then the product of
MPI tasks * OpenMP threads/task should not exceed the physical number of cores * hardware threads. The “-k on”

7.4. Accelerator packages 187

LAMMPS Documentation, Release stable 29Sep2021

switch also issues a “package kokkos” command (with no additional arguments) which sets various KOKKOS options
to default values, as discussed on the package command doc page.
The “-sf kk” command-line switch will automatically append the “/kk” suffix to styles that support it. In this manner no
modification to the input script is needed. Alternatively, one can run with the KOKKOS package by editing the input
script as described below.

Note: When using a single OpenMP thread, the Kokkos Serial back end (i.e. Makefile.kokkos_mpi_only) will give
better performance than the OpenMP back end (i.e. Makefile.kokkos_omp) because some of the overhead to make the
code thread-safe is removed.

Note: Use the “-pk kokkos” command-line switch to change the default package kokkos options. See its doc page
for details and default settings. Experimenting with its options can provide a speed-up for specific calculations. For
example:

mpirun -np 16 lmp_kokkos_mpi_only -k on -sf kk -pk kokkos newton on neigh half comm no -
,→in in.lj # Newton on, Half neighbor list, non-threaded comm

If the newton command is used in the input script, it can also override the Newton flag defaults.
For half neighbor lists and OpenMP, the KOKKOS package uses data duplication (i.e. thread-private arrays) by de-
fault to avoid thread-level write conflicts in the force arrays (and other data structures as necessary). Data duplication
is typically fastest for small numbers of threads (i.e. 8 or less) but does increase memory footprint and is not scal-
able to large numbers of threads. An alternative to data duplication is to use thread-level atomic operations which
do not require data duplication. The use of atomic operations can be enforced by compiling LAMMPS with the “-
DLMP_KOKKOS_USE_ATOMICS” pre-processor flag. Most but not all Kokkos-enabled pair_styles support data
duplication. Alternatively, full neighbor lists avoid the need for duplication or atomic operations but require more
compute operations per atom. When using the Kokkos Serial back end or the OpenMP back end with a single thread,
no duplication or atomic operations are used. For CUDA and half neighbor lists, the KOKKOS package always uses
atomic operations.

CPU Cores, Sockets and Thread Affinity

When using multi-threading, it is important for performance to bind both MPI tasks to physical cores, and threads to
physical cores, so they do not migrate during a simulation.
If you are not certain MPI tasks are being bound (check the defaults for your MPI installation), binding can be forced
with these flags:

OpenMPI 1.8: mpirun -np 2 --bind-to socket --map-by socket ./lmp_openmpi ...
Mvapich2 2.0: mpiexec -np 2 --bind-to socket --map-by socket ./lmp_mvapich ...

For binding threads with KOKKOS OpenMP, use thread affinity environment variables to force binding. With OpenMP
3.1 (gcc 4.7 or later, intel 12 or later) setting the environment variable OMP_PROC_BIND=true should be sufficient. In
general, for best performance with OpenMP 4.0 or later set OMP_PROC_BIND=spread and OMP_PLACES=threads. For
binding threads with the KOKKOS pthreads option, compile LAMMPS with the hwloc or libnuma support enabled as
described in the extra build options page.

188 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Running on Knight’s Landing (KNL) Intel Xeon Phi

Here is a quick overview of how to use the KOKKOS package for the Intel Knight’s Landing (KNL) Xeon Phi:
KNL Intel Phi chips have 68 physical cores. Typically 1 to 4 cores are reserved for the OS, and only 64 or 66 cores
are used. Each core has 4 Hyper-Threads,so there are effectively N = 256 (4*64) or N = 264 (4*66) cores to run on.
The product of MPI tasks * OpenMP threads/task should not exceed this limit, otherwise performance will suffer. Note
that with the KOKKOS package you do not need to specify how many KNLs there are per node; each KNL is simply
treated as running some number of MPI tasks.
Examples of mpirun commands that follow these rules are shown below.

# Running on an Intel KNL node with 68 cores (272 threads/node via 4x hardware␣
,→threading):

mpirun -np 64 lmp_kokkos_phi -k on t 4 -sf kk -in in.lj # 1 node, 64 MPI tasks/node,

,→ 4 threads/task

mpirun -np 66 lmp_kokkos_phi -k on t 4 -sf kk -in in.lj # 1 node, 66 MPI tasks/node,

,→ 4 threads/task

mpirun -np 32 lmp_kokkos_phi -k on t 8 -sf kk -in in.lj # 1 node, 32 MPI tasks/node,

,→ 8 threads/task

mpirun -np 512 -ppn 64 lmp_kokkos_phi -k on t 4 -sf kk -in in.lj # 8 nodes, 64 MPI␣
,→tasks/node, 4 threads/task

The -np setting of the mpirun command sets the number of MPI tasks/node. The “-k on t Nt” command-line switch
sets the number of threads/task as Nt. The product of these two values should be N, i.e. 256 or 264.

Note: The default for the package kokkos command when running on KNL is to use “half” neighbor lists and set the
Newton flag to “on” for both pairwise and bonded interactions. This will typically be best for many-body potentials.
For simpler pair-wise potentials, it may be faster to use a “full” neighbor list with Newton flag to “off”. Use the “-
pk kokkos” command-line switch to change the default package kokkos options. See its page for details and default
settings. Experimenting with its options can provide a speed-up for specific calculations. For example:

mpirun -np 64 lmp_kokkos_phi -k on t 4 -sf kk -pk kokkos comm host -in in.reax # ␣
,→Newton on, half neighbor list, threaded comm

mpirun -np 64 lmp_kokkos_phi -k on t 4 -sf kk -pk kokkos newton off neigh full comm no -
,→in in.lj # Newton off, full neighbor list, non-threaded comm

Note: MPI tasks and threads should be bound to cores as described above for CPUs.

Note: To build with Kokkos support for Intel Xeon Phi co-processors such as Knight’s Corner (KNC), your system
must be configured to use them in “native” mode, not “offload” mode like the INTEL package supports.

7.4. Accelerator packages 189

LAMMPS Documentation, Release stable 29Sep2021

Running on GPUs

Use the “-k” command-line switch to specify the number of GPUs per node. Typically the -np setting of the mpirun
command should set the number of MPI tasks/node to be equal to the number of physical GPUs on the node. You can
assign multiple MPI tasks to the same GPU with the KOKKOS package, but this is usually only faster if some portions
of the input script have not been ported to use Kokkos. In this case, also packing/unpacking communication buffers on
the host may give speedup (see the KOKKOS package command). Using CUDA MPS is recommended in this scenario.
Using a GPU-aware MPI library is highly recommended. GPU-aware MPI use can be avoided by using -pk kokkos
gpu/aware off . As above for multi-core CPUs (and no GPU), if N is the number of physical cores/node, then the
number of MPI tasks/node should not exceed N.

-k on g Ng

Here are examples of how to use the KOKKOS package for GPUs, assuming one or more nodes, each with two GPUs:

mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -in in.lj # 1 node, 2␣

,→MPI tasks/node, 2 GPUs/node

mpirun -np 32 -ppn 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -in in.lj # 16 nodes, 2␣

,→MPI tasks/node, 2 GPUs/node (32 GPUs total)

Note: The default for the package kokkos command when running on GPUs is to use “full” neighbor lists and set the
Newton flag to “off” for both pairwise and bonded interactions, along with threaded communication. When running
on Maxwell or Kepler GPUs, this will typically be best. For Pascal GPUs and beyond, using “half” neighbor lists and
setting the Newton flag to “on” may be faster. For many pair styles, setting the neighbor binsize equal to twice the CPU
default value will give speedup, which is the default when running on GPUs. Use the “-pk kokkos” command-line
switch to change the default package kokkos options. See its page for details and default settings. Experimenting with
its options can provide a speed-up for specific calculations. For example:

mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half␣

,→binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor␣
,→ghost cutoff

Note: When using a GPU, you will achieve the best performance if your input script does not use fix or compute styles
which are not yet Kokkos-enabled. This allows data to stay on the GPU for multiple timesteps, without being copied
back to the host CPU. Invoking a non-Kokkos fix or compute, or performing I/O for thermo or dump output will cause
data to be copied back to the CPU incurring a performance penalty.

Note: To get an accurate timing breakdown between time spend in pair, kspace, etc., you must set the environment
variable CUDA_LAUNCH_BLOCKING=1. However, this will reduce performance and is not recommended for pro-
duction runs.

190 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Run with the KOKKOS package by editing an input script

Alternatively the effect of the “-sf” or “-pk” switches can be duplicated by adding the package kokkos or suffix kk
commands to your input script.
The discussion above for building LAMMPS with the KOKKOS package, the mpirun/mpiexec command, and setting
appropriate thread are the same.
You must still use the “-k on” command-line switch to enable the KOKKOS package, and specify its additional argu-
ments for hardware options appropriate to your system, as documented above.
You can use the suffix kk command, or you can explicitly add a “kk” suffix to individual styles in your input script, e.g.

pair_style lj/cut/kk 2.5

You only need to use the package kokkos command if you wish to change any of its option defaults, as set by the “-k
on” command-line switch.
Using OpenMP threading and CUDA together:
With the KOKKOS package, both OpenMP multi-threading and GPUs can be compiled and used together in a few
special cases. In the makefile for the conventional build, the KOKKOS_DEVICES variable must include both, “Cuda”
and “OpenMP”, as is the case for /src/MAKE/OPTIONS/Makefile.kokkos_cuda_mpi.

KOKKOS_DEVICES=Cuda,OpenMP

When building with CMake you need to enable both features as it is done in the kokkos-cuda.cmake CMake preset
file.

cmake ../cmake -DKokkos_ENABLE_CUDA=yes -DKokkos_ENABLE_OPENMP=yes

The suffix “/kk” is equivalent to “/kk/device”, and for Kokkos CUDA, using the “-sf kk” in the command line gives
the default CUDA version everywhere. However, if the “/kk/host” suffix is added to a specific style in the input script,
the Kokkos OpenMP (CPU) version of that specific style will be used instead. Set the number of OpenMP threads as
“t Nt” and the number of GPUs as “g Ng”

-k on t Nt g Ng

For example, the command to run with 1 GPU and 8 OpenMP threads is then:

mpiexec -np 1 lmp_kokkos_cuda_openmpi -in in.lj -k on g 1 t 8 -sf kk

Conversely, if the “-sf kk/host” is used in the command line and then the “/kk” or “/kk/device” suffix is added to a
specific style in your input script, then only that specific style will run on the GPU while everything else will run on
the CPU in OpenMP mode. Note that the execution of the CPU and GPU styles will NOT overlap, except for a special
case:
A kspace style and/or molecular topology (bonds, angles, etc.) running on the host CPU can overlap with a pair
style running on the GPU. First compile with “–default-stream per-thread” added to CCFLAGS in the Kokkos CUDA
Makefile. Then explicitly use the “/kk/host” suffix for kspace and bonds, angles, etc. in the input file and the “kk” suffix
(equal to “kk/device”) on the command line. Also make sure the environment variable CUDA_LAUNCH_BLOCKING
is not set to “1” so CPU/GPU overlap can occur.

7.4. Accelerator packages 191

LAMMPS Documentation, Release stable 29Sep2021

Performance to expect

The performance of KOKKOS running in different modes is a function of your hardware, which KOKKOS-enable
styles are used, and the problem size.
Generally speaking, the following rules of thumb apply:
• When running on CPUs only, with a single thread per MPI task, performance of a KOKKOS style is somewhere
between the standard (un-accelerated) styles (MPI-only mode), and those provided by the OPENMP package.
However the difference between all 3 is small (less than 20%).
• When running on CPUs only, with multiple threads per MPI task, performance of a KOKKOS style is a bit slower
than the OPENMP package.
• When running large number of atoms per GPU, KOKKOS is typically faster than the GPU package when com-
piled for double precision. The benefit of using single or mixed precision with the GPU package depends signif-
icantly on the hardware in use and the simulated system and pair style.
• When running on Intel hardware, KOKKOS is not as fast as the INTEL package, which is optimized for x86
hardware (not just from Intel) and compilation with the Intel compilers. The INTEL package also can increase
the vector length of vector instructions by switching to single or mixed precision mode.
See the Benchmark page of the LAMMPS website for performance of the KOKKOS package on different hardware.

Advanced Kokkos options

There are other allowed options when building with the KOKKOS package that can improve performance or assist in
debugging or profiling. They are explained on the KOKKOS section of the build extras doc page,

Restrictions

Currently, there are no precision options with the KOKKOS package. All compilation and computation is performed
in double precision.

7.4.4 OPENMP package

The OPENMP package was developed by Axel Kohlmeyer at Temple University. It provides optimized and multi-
threaded versions of many pair styles, nearly all bonded styles (bond, angle, dihedral, improper), several Kspace styles,
and a few fix styles. It uses the OpenMP interface for multi-threading, but can also be compiled without OpenMP
support, providing optimized serial styles in that case.

Required hardware/software

To enable multi-threading, your compiler must support the OpenMP interface. You should have one or more multi-core
CPUs, as multiple threads can only be launched by each MPI task on the local node (using shared memory).

192 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Building LAMMPS with the OPENMP package

See the Build extras page for instructions.

Run with the OPENMP package from the command line

These examples assume one or more 16-core nodes.

env OMP_NUM_THREADS=16 lmp_omp -sf omp -in in.script # 1 MPI task, 16 threads␣
,→according to OMP_NUM_THREADS

lmp_mpi -sf omp -in in.script # 1 MPI task, no threads,␣

,→optimized kernels

mpirun -np 4 lmp_omp -sf omp -pk omp 4 -in in.script # 4 MPI tasks, 4 threads/
,→task

mpirun -np 32 -ppn 4 lmp_omp -sf omp -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/
,→node, 4 threads/task

The mpirun or mpiexec command sets the total number of MPI tasks used by LAMMPS (one or multiple per compute
node) and the number of MPI tasks used per node. E.g. the mpirun command in MPICH does this via its -np and -ppn
switches. Ditto for OpenMPI via -np and -npernode.
You need to choose how many OpenMP threads per MPI task will be used by the OPENMP package. Note that the
product of MPI tasks * threads/task should not exceed the physical number of cores (on a node), otherwise performance
will suffer.
As in the lines above, use the “-sf omp” command-line switch, which will automatically append “omp” to styles that
support it. The “-sf omp” switch also issues a default package omp 0 command, which will set the number of threads
per MPI task via the OMP_NUM_THREADS environment variable.
You can also use the “-pk omp Nt” command-line switch, to explicitly set Nt = # of OpenMP threads per MPI task
to use, as well as additional options. Its syntax is the same as the package omp command whose page gives details,
including the default values used if it is not specified. It also gives more details on how to set the number of threads
via the OMP_NUM_THREADS environment variable.

Or run with the OPENMP package by editing an input script

The discussion above for the mpirun/mpiexec command, MPI tasks/node, and threads/MPI task is the same.
Use the suffix omp command, or you can explicitly add an “omp” suffix to individual styles in your input script, e.g.

pair_style lj/cut/omp 2.5

You must also use the package omp command to enable the OPENMP package. When you do this you also specify how
many threads per MPI task to use. The command page explains other options and how to set the number of threads via
the OMP_NUM_THREADS environment variable.

7.4. Accelerator packages 193

LAMMPS Documentation, Release stable 29Sep2021

Speed-up to expect

Depending on which styles are accelerated, you should look for a reduction in the “Pair time”, “Bond time”, “KSpace
time”, and “Loop time” values printed at the end of a run.
You may see a small performance advantage (5 to 20%) when running a OPENMP style (in serial or parallel) with
a single thread per MPI task, versus running standard LAMMPS with its standard un-accelerated styles (in serial or
all-MPI parallelization with 1 task/core). This is because many of the OPENMP styles contain similar optimizations
to those used in the OPT package, described in the OPT package doc page.
With multiple threads/task, the optimal choice of number of MPI tasks/node and OpenMP threads/task can vary a
lot and should always be tested via benchmark runs for a specific simulation running on a specific machine, paying
attention to guidelines discussed in the next sub-section.
A description of the multi-threading strategy used in the OPENMP package and some performance examples are pre-
sented here.

Guidelines for best performance

For many problems on current generation CPUs, running the OPENMP package with a single thread/task is faster than
running with multiple threads/task. This is because the MPI parallelization in LAMMPS is often more efficient than
multi-threading as implemented in the OPENMP package. The parallel efficiency (in a threaded sense) also varies for
different OPENMP styles.
Using multiple threads/task can be more effective under the following circumstances:
• Individual compute nodes have a significant number of CPU cores but the CPU itself has limited memory band-
width, e.g. for Intel Xeon 53xx (Clovertown) and 54xx (Harpertown) quad-core processors. Running one MPI
task per CPU core will result in significant performance degradation, so that running with 4 or even only 2 MPI
tasks per node is faster. Running in hybrid MPI+OpenMP mode will reduce the inter-node communication band-
width contention in the same way, but offers an additional speedup by utilizing the otherwise idle CPU cores.
• The interconnect used for MPI communication does not provide sufficient bandwidth for a large number of
MPI tasks per node. For example, this applies to running over gigabit ethernet or on Cray XT4 or XT5 series
supercomputers. As in the aforementioned case, this effect worsens when using an increasing number of nodes.
• The system has a spatially inhomogeneous particle density which does not map well to the domain decomposition
scheme or load-balancing options that LAMMPS provides. This is because multi-threading achieves parallelism
over the number of particles, not via their distribution in space.
• A machine is being used in “capability mode”, i.e. near the point where MPI parallelism is maxed out. For
example, this can happen when using the PPPM solver for long-range electrostatics on large numbers of nodes.
The scaling of the KSpace calculation (see the kspace_style command) becomes the performance-limiting factor.
Using multi-threading allows less MPI tasks to be invoked and can speed-up the long-range solver, while increas-
ing overall performance by parallelizing the pairwise and bonded calculations via OpenMP. Likewise additional
speedup can be sometimes be achieved by increasing the length of the Coulombic cutoff and thus reducing the
work done by the long-range solver. Using the run_style verlet/split command, which is compatible with the
OPENMP package, is an alternative way to reduce the number of MPI tasks assigned to the KSpace calculation.
Additional performance tips are as follows:
• The best parallel efficiency from omp styles is typically achieved when there is at least one MPI task per physical
CPU chip, i.e. socket or die.
• It is usually most efficient to restrict threading to a single socket, i.e. use one or more MPI task per socket.
• NOTE: By default, several current MPI implementations use a processor affinity setting that restricts each MPI
task to a single CPU core. Using multi-threading in this mode will force all threads to share the one core and thus
is likely to be counterproductive. Instead, binding MPI tasks to a (multi-core) socket, should solve this issue.

194 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Restrictions

None.

7.4.5 OPT package

The OPT package was developed by James Fischer (High Performance Technologies), David Richie, and Vincent
Natoli (Stone Ridge Technologies). It contains a handful of pair styles whose compute() methods were rewritten in
C++ templated form to reduce the overhead due to if tests and other conditional code.

Required hardware/software

Any hardware. Any compiler.

Building LAMMPS with the OPT package

See the Build extras page for instructions.

Run with the OPT package from the command line

lmp_mpi -sf opt -in in.script # run in serial

mpirun -np 4 lmp_mpi -sf opt -in in.script # run in parallel

Use the “-sf opt” command-line switch, which will automatically append “opt” to styles that support it.

Or run with the OPT package by editing an input script

Use the suffix opt command, or you can explicitly add an “opt” suffix to individual styles in your input script, e.g.

pair_style lj/cut/opt 2.5

Speed-up to expect

You should see a reduction in the “Pair time” value printed at the end of a run. On most machines for reasonable
problem sizes, it will be a 5 to 20% savings.

Guidelines for best performance

Just try out an OPT pair style to see how it performs.

7.4. Accelerator packages 195

LAMMPS Documentation, Release stable 29Sep2021

Restrictions

None.
Inverting this list, LAMMPS currently has acceleration support for three kinds of hardware, via the listed packages:

Many-core CPUs INTEL, KOKKOS, OPENMP, OPT packages

GPUs GPU, KOKKOS packages
Intel Phi/AVX INTEL, KOKKOS packages

Which package is fastest for your hardware may depend on the size problem you are running and what commands (ac-
celerated and non-accelerated) are invoked by your input script. While these doc pages include performance guidelines,
there is no substitute for trying out the different packages appropriate to your hardware.
Any accelerated style has the same name as the corresponding standard style, except that a suffix is appended. Oth-
erwise, the syntax for the command that uses the style is identical, their functionality is the same, and the numerical
results it produces should also be the same, except for precision and round-off effects.
For example, all of these styles are accelerated variants of the Lennard-Jones pair_style lj/cut:
• pair_style lj/cut/gpu
• pair_style lj/cut/intel
• pair_style lj/cut/kk
• pair_style lj/cut/omp
• pair_style lj/cut/opt
To see what accelerate styles are currently available for a particular style, find the style name in the Commands style
pages (fix,compute,pair,etc) and see what suffixes are listed (g,i,k,o,t) with it. The doc pages for individual commands
(e.g. pair lj/cut or fix nve) also list any accelerated variants available for that style.
To use an accelerator package in LAMMPS, and one or more of the styles it provides, follow these general steps. Details
vary from package to package and are explained in the individual accelerator doc pages, listed above:

build the accelerator library only for GPU package

install the accelerator package make yes-opt, make yes-intel, etc
add compile/link flags to Makefile.machine in src/MAKE only for INTEL, KOKKOS, OPENMP, OPT
packages
re-build LAMMPS make machine
prepare and test a regular LAMMPS simulation lmp_machine -in in.script; mpirun -np 32
lmp_machine -in in.script
enable specific accelerator support via ‘-k on’ command-line only needed for KOKKOS package
switch,
set any needed options for the package via “-pk” command-line only if defaults need to be changed
switch or package command,
use accelerated styles in your input via “-sf” command-line switch lmp_machine -in in.script -sf gpu
or suffix command

Note that the first 4 steps can be done as a single command with suitable make command invocations. This is discussed
on the Packages doc pages, and its use is illustrated in the individual accelerator sections. Typically these steps only
need to be done once, to create an executable that uses one or more accelerator packages.
The last 4 steps can all be done from the command-line when LAMMPS is launched, without changing your input
script, as illustrated in the individual accelerator sections. Or you can add package and suffix commands to your input
script.

196 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

Note: With a few exceptions, you can build a single LAMMPS executable with all its accelerator packages installed.
Note however that the INTEL and KOKKOS packages require you to choose one of their hardware options when
building for a specific platform. I.e. CPU or Phi option for the INTEL package. Or the OpenMP, Cuda, or Phi option
for the KOKKOS package.

These are the exceptions. You cannot build a single executable with:
• both the INTEL Phi and KOKKOS Phi options
• the INTEL Phi or Kokkos Phi option, and the GPU package
See the examples/accelerate/README and make.list files for sample Make.py commands that build LAMMPS with
any or all of the accelerator packages. As an example, here is a command that builds with all the GPU related packages
installed (GPU, KOKKOS with Cuda), including settings to build the needed auxiliary GPU libraries for Kepler GPUs:

Make.py -j 16 -p omp gpu kokkos -cc nvcc wrap=mpi -gpu mode=double arch=35 -kokkos␣
,→cuda arch=35 lib-all file mpi

The examples/accelerate directory also has input scripts that can be used with all of the accelerator packages. See its
README file for details.
Likewise, the bench directory has FERMI and KEPLER and PHI sub-directories with Make.py commands and input
scripts for using all the accelerator packages on various machines. See the README files in those directories.
As mentioned above, the Benchmark page of the LAMMPS website gives performance results for the various acceler-
ator packages for several of the standard LAMMPS benchmark problems, as a function of problem size and number of
compute nodes, on different hardware platforms.
Here is a brief summary of what the various packages provide. Details are in the individual accelerator sections.
• Styles with a “gpu” suffix are part of the GPU package and can be run on Intel, NVIDIA, or AMD GPUs. The
speed-up on a GPU depends on a variety of factors, discussed in the accelerator sections.
• Styles with an “intel” suffix are part of the INTEL package. These styles support vectorized single and mixed
precision calculations, in addition to full double precision. In extreme cases, this can provide speedups over 3.5x
on CPUs. The package also supports acceleration in “offload” mode to Intel(R) Xeon Phi(TM) co-processors.
This can result in additional speedup over 2x depending on the hardware configuration.
• Styles with a “kk” suffix are part of the KOKKOS package, and can be run using OpenMP on multicore CPUs,
on an NVIDIA or AMD GPU, or on an Intel Xeon Phi in “native” mode. The speed-up depends on a variety of
factors, as discussed on the KOKKOS accelerator page.
• Styles with an “omp” suffix are part of the OPENMP package and allow a pair-style to be run in multi-threaded
mode using OpenMP. This can be useful on nodes with high-core counts when using less MPI processes than
cores is advantageous, e.g. when running with PPPM so that FFTs are run on fewer MPI processors or when the
many MPI tasks would overload the available bandwidth for communication.
• Styles with an “opt” suffix are part of the OPT package and typically speed-up the pairwise calculations of your
simulation by 5-25% on a CPU.
The individual accelerator package doc pages explain:
• what hardware and software the accelerated package requires
• how to build LAMMPS with the accelerated package
• how to run with the accelerated package either via command-line switches or modifying the input script
• speed-ups to expect
• guidelines for best performance

7.4. Accelerator packages 197

LAMMPS Documentation, Release stable 29Sep2021

• restrictions

7.5 Comparison of various accelerator packages

The next section compares and contrasts the various accelerator options, since there are multiple ways to perform
OpenMP threading, run on GPUs, optimize for vector units on CPUs and run on Intel Xeon Phi (co-)processors.
All of these packages can accelerate a LAMMPS calculation taking advantage of hardware features, but they do it in
different ways and acceleration is not always guaranteed.
As a consequence, for a particular simulation on specific hardware, one package may be faster than the other. We give
some guidelines below, but the best way to determine which package is faster for your input script is to try multiple
of them on your machine and experiment with available performance tuning settings. See the benchmarking section
below for examples where this has been done.
Guidelines for using each package optimally:
• Both, the GPU and the KOKKOS package allows you to assign multiple MPI ranks (= CPU cores) to the same
GPU. For the GPU package, this can lead to a speedup through better utilization of the GPU (by overlapping
computation and data transfer) and more efficient computation of the non-GPU accelerated parts of LAMMPS
through MPI parallelization, as all system data is maintained and updated on the host. For KOKKOS, there is
less to no benefit from this, due to its different memory management model, which tries to retain data on the
GPU.
• The GPU package moves per-atom data (coordinates, forces, and (optionally) neighbor list data, if not computed
on the GPU) between the CPU and GPU at every timestep. The KOKKOS/CUDA package only does this on
timesteps when a CPU calculation is required (e.g. to invoke a fix or compute that is non-GPU-ized). Hence,
if you can formulate your input script to only use GPU-ized fixes and computes, and avoid doing I/O too often
(thermo output, dump file snapshots, restart files), then the data transfer cost of the KOKKOS/CUDA package
can be very low, causing it to run faster than the GPU package.
• The GPU package is often faster than the KOKKOS/CUDA package, when the number of atoms per GPU is on
the smaller side. The crossover point, in terms of atoms/GPU at which the KOKKOS/CUDA package becomes
faster depends strongly on the pair style. For example, for a simple Lennard Jones system the crossover (in
single precision) is often about 50K-100K atoms per GPU. When performing double precision calculations the
crossover point can be significantly smaller.
• Both KOKKOS and GPU package compute bonded interactions (bonds, angles, etc) on the CPU. If the GPU pack-
age is running with several MPI processes assigned to one GPU, the cost of computing the bonded interactions
is spread across more CPUs and hence the GPU package can run faster in these cases.
• When using LAMMPS with multiple MPI ranks assigned to the same GPU, its performance depends to some
extent on the available bandwidth between the CPUs and the GPU. This can differ significantly based on the
available bus technology, capability of the host CPU and mainboard, the wiring of the buses and whether switches
are used to increase the number of available bus slots, or if GPUs are housed in an external enclosure. This can
become quite complex.
• To achieve significant acceleration through GPUs, both KOKKOS and GPU package require capable GPUs with
fast on-device memory and efficient data transfer rates. This requests capable upper mid-level to high-end (desk-
top) GPUs. Using lower performance GPUs (e.g. on laptops) may result in a slowdown instead.
• For the GPU package, specifically when running in parallel with MPI, if it often more efficient to exclude the
PPPM kspace style from GPU acceleration and instead run it - concurrently with a GPU accelerated pair style -
on the CPU. This can often be easily achieved with placing a suffix off command before and a suffix on command
after the kspace_style pppm command.
• The KOKKOS/OpenMP and OPENMP package have different thread management strategies, which should result
in OPENMP being more efficient for a small number of threads with increasing overhead as the number of threads

198 Chapter 7. Accelerate performance

 LAMMPS Documentation, Release stable 29Sep2021

per MPI rank grows. The KOKKOS/OpenMP kernels have less overhead in that case, but have lower performance
with few threads.
• The INTEL package contains many options and settings for achieving additional performance on Intel hardware
(CPU and accelerator cards), but to unlock this potential, an Intel compiler is required. The package code will
compile with GNU gcc, but it will not be as efficient.
Differences between the GPU and KOKKOS packages:
• The GPU package accelerates only pair force, neighbor list, and (parts of) PPPM calculations. The KOKKOS
package attempts to run most of the calculation on the GPU, but can transparently support non-accelerated code
(with a performance penalty due to having data transfers between host and GPU).
• The GPU package requires neighbor lists to be built on the CPU when using exclusion lists, or a triclinic simu-
lation box.
• The GPU package can be compiled for CUDA or OpenCL and thus supports both, NVIDIA and AMD GPUs
well. On NVIDIA hardware, using CUDA is typically resulting in equal or better performance over OpenCL.
• OpenCL in the GPU package does theoretically also support Intel CPUs or Intel Xeon Phi, but the native support
for those in KOKKOS (or INTEL) is superior.

7.5. Comparison of various accelerator packages 199

LAMMPS Documentation, Release stable 29Sep2021

200 Chapter 7. Accelerate performance

 CHAPTER

EIGHT

HOWTO DISCUSSIONS

These doc pages describe how to perform various tasks with LAMMPS, both for users and developers. The glossary
website page also lists MD terminology with links to corresponding LAMMPS manual pages. The example input
scripts included in the examples directory of the LAMMPS distribution and highlighted on the Examples doc page also
show how to setup and run various kinds of simulations.

8.1 General howto

8.1.1 Restart a simulation

There are 3 ways to continue a long LAMMPS simulation. Multiple run commands can be used in the same input
script. Each run will continue from where the previous run left off. Or binary restart files can be saved to disk using
the restart command. At a later time, these binary files can be read via a read_restart command in a new script. Or
they can be converted to text data files using the -r command-line switch and read by a read_data command in a new
script.
Here we give examples of 2 scripts that read either a binary restart file or a converted data file and then issue a new
run command to continue where the previous run left off. They illustrate what settings must be made in the new script.
Details are discussed in the documentation for the read_restart and read_data commands.
Look at the in.chain input script provided in the bench directory of the LAMMPS distribution to see the original script
that these 2 scripts are based on. If that script had the line

restart 50 tmp.restart

added to it, it would produce 2 binary restart files (tmp.restart.50 and tmp.restart.100) as it ran.
This script could be used to read the first restart file and re-run the last 50 timesteps:

read_restart tmp.restart.50

neighbor 0.4 bin

neigh_modify every 1 delay 1

fix 1 all nve

fix 2 all langevin 1.0 1.0 10.0 904297

timestep 0.012

run 50

201
LAMMPS Documentation, Release stable 29Sep2021

Note that the following commands do not need to be repeated because their settings are included in the restart file:
units, atom_style, special_bonds, pair_style, bond_style. However these commands do need to be used, since their
settings are not in the restart file: neighbor, fix, timestep.
If you actually use this script to perform a restarted run, you will notice that the thermodynamic data match at step 50
(if you also put a “thermo 50” command in the original script), but do not match at step 100. This is because the fix
langevin command uses random numbers in a way that does not allow for perfect restarts.
As an alternate approach, the restart file could be converted to a data file as follows:

lmp_g++ -r tmp.restart.50 tmp.restart.data

Then, this script could be used to re-run the last 50 steps:

units lj
atom_style bond
pair_style lj/cut 1.12
pair_modify shift yes
bond_style fene
special_bonds 0.0 1.0 1.0

read_data tmp.restart.data

neighbor 0.4 bin

neigh_modify every 1 delay 1

fix 1 all nve

fix 2 all langevin 1.0 1.0 10.0 904297

timestep 0.012

reset_timestep 50
run 50

Note that nearly all the settings specified in the original in.chain script must be repeated, except the pair_coeff and
bond_coeff commands since the new data file lists the force field coefficients. Also, the reset_timestep command is
used to tell LAMMPS the current timestep. This value is stored in restart files, but not in data files.

8.1.2 Visualize LAMMPS snapshots

LAMMPS itself does not do visualization, but snapshots from LAMMPS simulations can be visualized (and analyzed)
in a variety of ways.
Mention dump image and dump movie.
LAMMPS snapshots are created by the dump command which can create files in several formats. The native LAMMPS
dump format is a text file (see “dump atom” or “dump custom”) which can be visualized by several popular visualization
tools. The dump image and dump movie styles can output internally rendered images and convert a sequence of them
to a movie during the MD run. Several programs included with LAMMPS as auxiliary tools can convert between
LAMMPS format files and other formats. See the Tools page for details.
A Python-based toolkit distributed by our group can read native LAMMPS dump files, including custom dump files
with additional columns of user-specified atom information, and convert them to various formats or pipe them into
visualization software directly. See the Pizza.py WWW site for details. Specifically, Pizza.py can convert LAMMPS
dump files into PDB, XYZ, EnSight, and VTK formats. Pizza.py can pipe LAMMPS dump files directly into the

202 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Raster3d and RasMol visualization programs. Pizza.py has tools that do interactive 3d OpenGL visualization and one
that creates SVG images of dump file snapshots.

8.1.3 Run multiple simulations from one input script

This can be done in several ways. See the documentation for individual commands for more details on how these
examples work.
If “multiple simulations” means continue a previous simulation for more timesteps, then you simply use the run com-
mand multiple times. For example, this script
units lj
atom_style atomic
read_data data.lj
run 10000
run 10000
run 10000
run 10000
run 10000

would run 5 successive simulations of the same system for a total of 50,000 timesteps.
If you wish to run totally different simulations, one after the other, the clear command can be used in between them to
re-initialize LAMMPS. For example, this script
units lj
atom_style atomic
read_data data.lj
run 10000
clear
units lj
atom_style atomic
read_data data.lj.new
run 10000

would run 2 independent simulations, one after the other.

For large numbers of independent simulations, you can use variables and the next and jump commands to loop over
the same input script multiple times with different settings. For example, this script, named in.polymer
variable d index run1 run2 run3 run4 run5 run6 run7 run8
shell cd $d
read_data data.polymer
run 10000
shell cd ..
clear
next d
jump in.polymer

would run 8 simulations in different directories, using a data.polymer file in each directory. The same concept could be
used to run the same system at 8 different temperatures, using a temperature variable and storing the output in different
log and dump files, for example

variable a loop 8
variable t index 0.8 0.85 0.9 0.95 1.0 1.05 1.1 1.15
(continues on next page)

8.1. General howto 203

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

log log.$a
read data.polymer
velocity all create $t 352839
fix 1 all nvt $t $t 100.0
dump 1 all atom 1000 dump.$a
run 100000
clear
next t
next a
jump in.polymer

All of the above examples work whether you are running on 1 or multiple processors, but assumed you are running
LAMMPS on a single partition of processors. LAMMPS can be run on multiple partitions via the -partition command-
line switch.
In the last 2 examples, if LAMMPS were run on 3 partitions, the same scripts could be used if the “index” and “loop”
variables were replaced with universe-style variables, as described in the variable command. Also, the “next t” and
“next a” commands would need to be replaced with a single “next a t” command. With these modifications, the 8
simulations of each script would run on the 3 partitions one after the other until all were finished. Initially, 3 simulations
would be started simultaneously, one on each partition. When one finished, that partition would then start the fourth
simulation, and so forth, until all 8 were completed.

8.1.4 Multi-replica simulations

Several commands in LAMMPS run multi-replica simulations, meaning that multiple instances (replicas) of your sim-
ulation are run simultaneously, with small amounts of data exchanged between replicas periodically.
These are the relevant commands:
• hyper for bond boost hyperdynamics (HD)
• neb for nudged elastic band calculations (NEB)
• neb_spin for magnetic nudged elastic band calculations
• prd for parallel replica dynamics (PRD)
• tad for temperature accelerated dynamics (TAD)
• temper for parallel tempering with fixed volume
• temper/npt for parallel tempering extended for NPT
• temper/grem for parallel tempering with generalized replica exchange (gREM)
• fix pimd for path-integral molecular dynamics (PIMD)
NEB is a method for finding transition states and barrier potential energies. HD, PRD, and TAD are methods for
performing accelerated dynamics to find and perform infrequent events. Parallel tempering or replica exchange runs
different replicas at a series of temperature to facilitate rare-event sampling. PIMD runs different replicas whose in-
dividual particles in different replicas are coupled together by springs to model a system of ring-polymers which can
represent the quantum nature of atom cores.
These commands can only be used if LAMMPS was built with the REPLICA package. See the Build package page for
more info.
In all these cases, you must run with one or more processors per replica. The processors assigned to each replica are
determined at run-time by using the -partition command-line switch to launch LAMMPS on multiple partitions, which
in this context are the same as replicas. E.g. these commands:

204 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

mpirun -np 16 lmp_linux -partition 8x2 -in in.temper

mpirun -np 8 lmp_linux -partition 8x1 -in in.neb

would each run 8 replicas, on either 16 or 8 processors. Note the use of the -in command-line switch to specify the
input script which is required when running in multi-replica mode.
Also note that with MPI installed on a machine (e.g. your desktop), you can run on more (virtual) processors than you
have physical processors. Thus the above commands could be run on a single-processor (or few-processor) desktop
so that you can run a multi-replica simulation on more replicas than you have physical processors. This is useful for
testing and debugging, since with most modern processors and MPI libraries the efficiency of a calculation can severely
diminish when oversubscribing processors.

8.1.5 Library interface to LAMMPS

As described on the Build basics doc page, LAMMPS can be built as a static or shared library, so that it can be called
by another code, used in a coupled manner with other codes, or driven through a Python interface.
At the core of LAMMPS is the LAMMPS class which encapsulates the state of the simulation program through the state
of the various class instances that it is composed of. So a calculation using LAMMPS requires to create an instance of
the LAMMPS class and then send it (text) commands, either individually or from a file, or perform other operations that
modify the state stored inside that instance or drive simulations. This is essentially what the src/main.cpp file does
as well for the standalone LAMMPS executable with reading commands either from an input file or stdin.
Creating a LAMMPS instance can be done by using C++ code directly or through a C-style interface library to
LAMMPS that is provided in the files src/library.cpp and library.h. This C language API, can be used from
C and C++, and is also the basis for the Python and Fortran interfaces or wrappers included in the LAMMPS source
code.
The examples/COUPLE and python/examples directories contain some example programs written in C++, C, For-
tran, and Python, which show how a driver code can link to LAMMPS as a library, run LAMMPS on a subset of
processors (so the others are available to run some other code concurrently), grab data from LAMMPS, change it, and
send it back into LAMMPS.
A detailed documentation of the available APIs and examples of how to use them can be found in the Programmer
Guide section of this manual.

8.1.6 Coupling LAMMPS to other codes

LAMMPS is designed to allow it to be coupled to other codes. For example, a quantum mechanics code might compute
forces on a subset of atoms and pass those forces to LAMMPS. Or a continuum finite element (FE) simulation might
use atom positions as boundary conditions on FE nodal points, compute a FE solution, and return interpolated forces
on MD atoms.
LAMMPS can be coupled to other codes in at least 4 ways. Each has advantages and disadvantages, which you will
have to think about in the context of your application.
1. Define a new fix command that calls the other code. In this scenario, LAMMPS is the driver code. During
timestepping, the fix is invoked, and can make library calls to the other code, which has been linked to LAMMPS
as a library. This is the way how the LATTE package, which performs density-functional tight-binding calcula-
tions using the LATTE software to compute forces, is hooked to LAMMPS. See the fix latte command for more
details. Also see the Modify doc pages for info on how to add a new fix to LAMMPS.
2. Define a new LAMMPS command that calls the other code. This is conceptually similar to method (1), but in this
case LAMMPS and the other code are on a more equal footing. Note that now the other code is not called during
the timestepping of a LAMMPS run, but between runs. The LAMMPS input script can be used to alternate
LAMMPS runs with calls to the other code, invoked via the new command. The run command facilitates this

8.1. General howto 205

LAMMPS Documentation, Release stable 29Sep2021

with its every option, which makes it easy to run a few steps, invoke the command, run a few steps, invoke the
command, etc.
In this scenario, the other code can be called as a library, as in 1., or it could be a stand-alone code, invoked by a
system() call made by the command (assuming your parallel machine allows one or more processors to start up
another program). In the latter case the stand-alone code could communicate with LAMMPS through files that
the command writes and reads.
See the Modify command page for info on how to add a new command to LAMMPS.
3. Use LAMMPS as a library called by another code. In this case the other code is the driver and calls LAMMPS
as needed. Or a wrapper code could link and call both LAMMPS and another code as libraries. Again, the run
command has options that allow it to be invoked with minimal overhead (no setup or clean-up) if you wish to do
multiple short runs, driven by another program. Details about using the library interface are given in the library
API documentation.
4. Couple LAMMPS with another code in a client/server mode. This is described on the Howto client/server doc
page.

8.1.7 Using LAMMPS in client/server mode

Client/server coupling of two codes is where one code is the “client” and sends request messages to a “server” code.
The server responds to each request with a reply message. This enables the two codes to work in tandem to perform a
simulation. LAMMPS can act as either a client or server code.
Some advantages of client/server coupling are that the two codes run as stand-alone executables; they are not linked
together. Thus neither code needs to have a library interface. This often makes it easier to run the two codes on different
numbers of processors. If a message protocol (format and content) is defined for a particular kind of simulation, then
in principle any code that implements the client-side protocol can be used in tandem with any code that implements
the server-side protocol, without the two codes needing to know anything more specific about each other.
A simple example of client/server coupling is where LAMMPS is the client code performing MD timestepping. Each
timestep it sends a message to a server quantum code containing current coords of all the atoms. The quantum code
computes energy and forces based on the coords. It returns them as a message to LAMMPS, which completes the
timestep.
A more complex example is where LAMMPS is the client code and processes a series of data files, sending each
configuration to a quantum code to compute energy and forces. Or LAMMPS runs dynamics with an atomistic force
field, but pauses every N steps to ask the quantum code to compute energy and forces.
Alternate methods for code coupling with LAMMPS are described on the Howto couple doc page.
The protocol for using LAMMPS as a client is to use these 3 commands in this order (other commands may come in
between):
• message client # initiate client/server interaction
• fix client/md # any client fix which makes specific requests to the server
• message quit # terminate client/server interaction
In between the two message commands, a client fix command and unfix command can be used multiple times. Similarly,
this sequence of 3 commands can be repeated multiple times, assuming the server program operates in a similar fashion,
to initiate and terminate client/server communication.
The protocol for using LAMMPS as a server is to use these 2 commands in this order (other commands may come in
between):
• message server # initiate client/server interaction
• server md # any server command which responds to specific requests from the client

206 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

This sequence of 2 commands can be repeated multiple times, assuming the client program operates in a similar fashion,
to initiate and terminate client/server communication.
LAMMPS support for client/server coupling is in its MESSAGE package which implements several commands that
enable LAMMPS to act as a client or server, as discussed below. The MESSAGE package also wraps a client/server
library called CSlib which enables two codes to exchange messages in different ways, either via files, sockets, or MPI.
The CSlib is provided with LAMMPS in the lib/message dir. The CSlib has its own website with documentation and
test programs.

Note: For client/server coupling to work between LAMMPS and another code, the other code also has to use the CSlib.
This can sometimes be done without any modifications to the other code by simply wrapping it with a Python script
that exchanges CSlib messages with LAMMPS and prepares input for or processes output from the other code. The
other code also has to implement a matching protocol for the format and content of messages that LAMMPS exchanges
with it.

These are the commands currently in the MESSAGE package for two protocols, MD and MC (Monte Carlo). New
protocols can easily be defined and added to this directory, where LAMMPS acts as either the client or server.
• message
• fix client md = LAMMPS is a client for running MD
• server md = LAMMPS is a server for computing MD forces
• server mc = LAMMPS is a server for computing a Monte Carlo energy
The server doc files give details of the message protocols for data that is exchanged between the client and server.
These example directories illustrate how to use LAMMPS as either a client or server code:
• examples/message
• examples/COUPLE/README
• examples/COUPLE/lammps_mc
• examples/COUPLE/lammps_nwchem
• examples/COUPLE/lammps_vasp
The examples/message directory couples a client instance of LAMMPS to a server instance of LAMMPS.
The files in the lammps_mc folder show how to couple LAMMPS as a server to a simple Monte Carlo client code as
the driver.
The files in the lammps_nwchem folder show how to couple LAMMPS as a client code running MD timestepping to
NWChem acting as a server providing quantum DFT forces, through a Python wrapper script on NWChem.
The files in the lammps_vasp folder show how to couple LAMMPS as a client code running MD timestepping to VASP
acting as a server providing quantum DFT forces, through a Python wrapper script on VASP.
Here is how to launch a client and server code together for any of the 4 modes of message exchange that the message
command and the CSlib support. Here LAMMPS is used as both the client and server code. Another code could be
substituted for either.
The examples below show launching both codes from the same window (or batch script), using the “&” character to
launch the first code in the background. For all modes except mpi/one, you could also launch the codes in separate
windows on your desktop machine. It does not matter whether you launch the client or server first.
In these examples either code can be run on one or more processors. If running in a non-MPI mode (file or zmq) you
can launch a code on a single processor without using mpirun.

8.1. General howto 207

LAMMPS Documentation, Release stable 29Sep2021

IMPORTANT: If you run in mpi/two mode, you must launch both codes via mpirun, even if one or both of them runs
on a single processor. This is so that MPI can figure out how to connect both MPI processes together to exchange MPI
messages between them.
For message exchange in file, zmq, or mpi/two modes:

% mpirun -np 1 lmp_mpi -log log.client < in.client &

% mpirun -np 2 lmp_mpi -log log.server < in.server

% mpirun -np 4 lmp_mpi -log log.client < in.client &

% mpirun -np 1 lmp_mpi -log log.server < in.server

% mpirun -np 2 lmp_mpi -log log.client < in.client &

% mpirun -np 4 lmp_mpi -log log.server < in.server

For message exchange in mpi/one mode:

Launch both codes in a single mpirun command:

mpirun -np 2 lmp_mpi -mpicolor 0 -in in.message.client -log log.client : -np 4 lmp_mpi -
,→mpicolor 1 -in in.message.server -log log.server

The two -np values determine how many procs the client and the server run on.
A LAMMPS executable run in this manner must use the -mpicolor color command-line option as their its option, where
color is an integer label that will be used to distinguish one executable from another in the multiple executables that
the mpirun command launches. In this example the client was colored with a 0, and the server with a 1.

8.1.8 Using LAMMPS with the MDI library for code coupling

Note: This Howto page will eventually replace the Howto client/server doc page.

Client/server coupling of two codes is where one code is the “client” and sends request messages (data) to a “server”
code. The server responds to each request with a reply message. This enables the two codes to work in tandem to
perform a simulation. LAMMPS can act as either a client or server code; it does this by using the MolSSI Driver
Interface (MDI) library, developed by the Molecular Sciences Software Institute (MolSSI).
Alternate methods for code coupling with LAMMPS are described on the Howto couple doc page.
Some advantages of client/server coupling are that the two codes can run as stand-alone executables; they need not
be linked together. Thus neither code needs to have a library interface. This also makes it easy to run the two codes
on different numbers of processors. If a message protocol (format and content) is defined for a particular kind of
simulation, then in principle any code which implements the client-side protocol can be used in tandem with any code
which implements the server-side protocol. Neither code needs to know what specific other code it is working with.
In MDI nomenclature, a client code is the “driver”, and a server code is an “engine”. One driver code can communicate
with one or more instances of one or more engine codes. Driver and engine codes can be written in any language: C,
C++, Fortran, Python, etc.
In addition to allowing driver and engine(s) running to run as stand-alone executables, MDI also enables a server
code to be a “plugin” to the client code. In this scenario, server code(s) are compiled as shared libraries, and one
(or more) instances of the server are instantiated by the driver code. If the driver code runs in parallel, it can split its
MPI communicator into multiple sub-communicators, and launch each plugin engine instance on a sub-communicator.
Driver processors in that sub-communicator exchange messages with that engine instance, and can also send MPI
messages to other processors in the driver. The driver code can also destroy engine instances and re-instantiate them.

208 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

The way that a driver communicates with an engine is by making MDI_Send() and MDI_Recv() calls, which are
conceptually similar to MPI_Send() and MPI_Recv() calls. Each send or receive has a string which identifies the
command name, and optionally some data, which can be a single value or vector of values of any data type. Inside the
MDI library, data is exchanged between the driver and engine via MPI calls or sockets. This a run-time choice by the
user.

As an example, LAMMPS and the pw.x command from Quantum Espresso (a suite of quantum DFT codes), can work
together via the MDI library to perform an ab initio MD (AIMD) simulation, where LAMMPS runs an MD simulation
and sends a message each timestep to pw.x asking it to compute quantum forces on the current configuration of atoms.
Here is how the 2 codes are launched to communicate by MPI:

% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" \

-in in.aimd : -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method MPI"

In this case LAMMPS runs on 2 processors (MPI tasks), pw.x runs on 16 processors.
Here is how the 2 codes are launched to communicate by sockets:

% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" -in in.aimd
% mpirun -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method TCP -port 8021 -
,→hostname localhost"

These commands could be issued in different windows on a desktop machine. Or in the same window, if the first
command is ended with “&” so as to run in the background. If “localhost” is replaced by an IP address, pw.x could be
run on another machine on the same network, or even on another machine across the country.
After both codes initialize themselves to model the same system, this is what occurs each timestep:
• LAMMPS send a “>COORDS” message to pw.x with a 3*N vector of current atom coords
• pw.x receives the message/coords and computes quantum forces on all the atoms
• LAMMPS send a “<FORCES” message to pw.x and waits for the result
• pw.x receives the message (after its computation finishes) and sends a 3*N vector of forces
• LAMMPS receives the forces and time integrates to complete a single timestep

Examples scripts for using LAMMPS as an MDI engine are in the examples/mdi directory. See the README file in
that directory for instructions on how to run the examples.

Note: Work is underway to add commands that allow LAMMPS to be used as an MDI driver, e.g. for the AIMD
example discussed above. Example scripts for this usage mode will be added the same directory when available.

If LAMMPS is used as a stand-alone engine it should set up the system it will be modeling in its input script, then
invoke the mdi/engine command. This will put LAMMPS into “engine mode” where it waits for messages and data
from the driver. When the driver sends an “EXIT” command, LAMMPS will exit engine mode and the input script
will continue.
If LAMMPS is used as a plugin engine it operates the same way, except that the driver will pass LAMMPS an input
script to initialize itself. Upon receiving the “EXIT” command, LAMMPS will exit engine mode and the input script
will continue. After finishing execution of the input script, the instance of LAMMPS will be destroyed.
LAMMPS supports the full set of MD-appropriate engine commands defined by the MDI library. See the mdi/engine
page for a list of these.

8.1. General howto 209

LAMMPS Documentation, Release stable 29Sep2021

If those commands are not sufficient for a user-developed driver to use LAMMPS as an engine, then new commands
can be easily added. See these two files which implement the definition of MDI commands and the logic for responding
to them:
• src/MDI/mdi_engine.cpp
• src/MDI/fix_mdi_engine.cpp

8.2 Settings howto

8.2.1 2d simulations

Use the dimension command to specify a 2d simulation.

Make the simulation box periodic in z via the boundary command. This is the default.
If using the create_box command to define a simulation box, set the z dimensions narrow, but finite, so that the cre-
ate_atoms command will fill the 3d simulation box with a single z plane of atoms - e.g.

create box 1 -10 10 -10 10 -0.25 0.25

If using the read data command to read in a file of atom coordinates, set the “zlo zhi” values to be finite but narrow,
similar to the create_box command settings just described. For each atom in the file, assign a z coordinate so it falls
inside the z-boundaries of the box - e.g. 0.0.
Use the fix enforce2d command as the last defined fix to insure that the z-components of velocities and forces are zeroed
out every timestep. The reason to make it the last fix is so that any forces induced by other fixes will be zeroed out.
Many of the example input scripts included in the LAMMPS distribution are for 2d models.

Note: Some models in LAMMPS treat particles as finite-size spheres, as opposed to point particles. See the atom_style
sphere and fix nve/sphere commands for details. By default, for 2d simulations, such particles will still be modeled as
3d spheres, not 2d discs (circles), meaning their moment of inertia will be that of a sphere. If you wish to model them
as 2d discs, see the set density/disc command and the disc option for the fix nve/sphere, fix nvt/sphere, fix nph/sphere,
fix npt/sphere commands.

8.2.2 Triclinic (non-orthogonal) simulation boxes

By default, LAMMPS uses an orthogonal simulation box to encompass the particles. The boundary command sets the
boundary conditions of the box (periodic, non-periodic, etc). The orthogonal box has its “origin” at (xlo,ylo,zlo) and
is defined by 3 edge vectors starting from the origin given by a = (xhi-xlo,0,0); b = (0,yhi-ylo,0); c = (0,0,zhi-zlo). The
6 parameters (xlo,xhi,ylo,yhi,zlo,zhi) are defined at the time the simulation box is created, e.g. by the create_box or
read_data or read_restart commands. Additionally, LAMMPS defines box size parameters lx,ly,lz where lx = xhi-xlo,
and similarly in the y and z dimensions. The 6 parameters, as well as lx,ly,lz, can be output via the thermo_style custom
command.
LAMMPS also allows simulations to be performed in triclinic (non-orthogonal) simulation boxes shaped as a paral-
lelepiped with triclinic symmetry. The parallelepiped has its “origin” at (xlo,ylo,zlo) and is defined by 3 edge vectors
starting from the origin given by a = (xhi-xlo,0,0); b = (xy,yhi-ylo,0); c = (xz,yz,zhi-zlo). xy,xz,yz can be 0.0 or positive
or negative values and are called “tilt factors” because they are the amount of displacement applied to faces of an origi-
nally orthogonal box to transform it into the parallelepiped. In LAMMPS the triclinic simulation box edge vectors a, b,
and c cannot be arbitrary vectors. As indicated, a must lie on the positive x axis. b must lie in the xy plane, with strictly
positive y component. c may have any orientation with strictly positive z component. The requirement that a, b, and c

210 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

have strictly positive x, y, and z components, respectively, ensures that a, b, and c form a complete right-handed basis.
These restrictions impose no loss of generality, since it is possible to rotate/invert any set of 3 crystal basis vectors so
that they conform to the restrictions.
For example, assume that the 3 vectors A,B,C are the edge vectors of a general parallelepiped, where there is no
restriction on A,B,C other than they form a complete right-handed basis i.e. A x B . C > 0. The equivalent LAMMPS
a,b,c are a linear rotation of A, B, and C and can be computed as follows:
 

ax bx cx
a b c =  0 by cy 
0 0 cz
ax =A
^
bx =B · A = B cos γ
q
^ × B|
by =|A = B sin γ = B 2 − bx 2
^
cx =C · A = C cos β
^ B · C − bx cx
\
cy =C · (A × B) × A =
by
q
\
cz =|C · (A × B)| = C 2 − cx 2 − cy 2

where A = | A | indicates the scalar length of A. The hat symbol (^) indicates the corresponding unit vector. β and γ
are angles between the vectors described below. Note that by construction, a, b, and c have strictly positive x, y, and z
components, respectively. If it should happen that A, B, and C form a left-handed basis, then the above equations are
not valid for c. In this case, it is necessary to first apply an inversion. This can be achieved by interchanging two basis
vectors or by changing the sign of one of them.
For consistency, the same rotation/inversion applied to the basis vectors must also be applied to atom positions, veloc-
ities, and any other vector quantities. This can be conveniently achieved by first converting to fractional coordinates in
the old basis and then converting to distance coordinates in the new basis. The transformation is given by the following
equation:
 

1 B×C
x = a b c ·  C × A · X
V
A×B

where V is the volume of the box, X is the original vector quantity and x is the vector in the LAMMPS basis.
There is no requirement that a triclinic box be periodic in any dimension, though it typically should be in at least the
second dimension of the tilt (y in xy) if you want to enforce a shift in periodic boundary conditions across that boundary.
Some commands that work with triclinic boxes, e.g. the fix deform and fix npt commands, require periodicity or non-
shrink-wrap boundary conditions in specific dimensions. See the command doc pages for details.
The 9 parameters (xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) are defined at the time the simulation box is created. This happens
in one of 3 ways. If the create_box command is used with a region of style prism, then a triclinic box is setup. See the
region command for details. If the read_data command is used to define the simulation box, and the header of the data
file contains a line with the “xy xz yz” keyword, then a triclinic box is setup. See the read_data command for details.
Finally, if the read_restart command reads a restart file which was written from a simulation using a triclinic box, then
a triclinic box will be setup for the restarted simulation.
Note that you can define a triclinic box with all 3 tilt factors = 0.0, so that it is initially orthogonal. This is necessary
if the box will become non-orthogonal, e.g. due to the fix npt or fix deform commands. Alternatively, you can use the
change_box command to convert a simulation box from orthogonal to triclinic and vice versa.
As with orthogonal boxes, LAMMPS defines triclinic box size parameters lx,ly,lz where lx = xhi-xlo, and similarly in
the y and z dimensions. The 9 parameters, as well as lx,ly,lz, can be output via the thermo_style custom command.

8.2. Settings howto 211

LAMMPS Documentation, Release stable 29Sep2021

To avoid extremely tilted boxes (which would be computationally inefficient), LAMMPS normally requires that no
tilt factor can skew the box more than half the distance of the parallel box length, which is the first dimension in the
tilt factor (x for xz). This is required both when the simulation box is created, e.g. via the create_box or read_data
commands, as well as when the box shape changes dynamically during a simulation, e.g. via the fix deform or fix npt
commands.
For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5.
Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the
maximum tilt factor is 5 (as in this example), then configurations with tilt = . . . , -15, -5, 5, 15, 25, . . . are geometrically
all equivalent. If the box tilt exceeds this limit during a dynamics run (e.g. via the fix deform command), then the box
is “flipped” to an equivalent shape with a tilt factor within the bounds, so the run can continue. See the fix deform page
for further details.
One exception to this rule is if the first dimension in the tilt factor (x for xy) is non-periodic. In that case, the limits
on the tilt factor are not enforced, since flipping the box in that dimension does not change the atom positions due to
non-periodicity. In this mode, if you tilt the system to extreme angles, the simulation will simply become inefficient,
due to the highly skewed simulation box.
The limitation on not creating a simulation box with a tilt factor skewing the box more than half the distance of the
parallel box length can be overridden via the box command. Setting the tilt keyword to large allows any tilt factors to
be specified.
Box flips that may occur using the fix deform or fix npt commands can be turned off using the flip no option with either
of the commands.
Note that if a simulation box has a large tilt factor, LAMMPS will run less efficiently, due to the large volume of
communication needed to acquire ghost atoms around a processor’s irregular-shaped sub-domain. For extreme values
of tilt, LAMMPS may also lose atoms and generate an error.
Triclinic crystal structures are often defined using three lattice constants a, b, and c, and three angles α, β, and γ.
Note that in this nomenclature, the a, b, and c lattice constants are the scalar lengths of the edge vectors a, b, and c
defined above. The relationship between these 6 quantities (a, b, c, α, β, γ) and the LAMMPS box sizes (lx,ly,lz) =
(xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) is as follows:

a =lx
b2 =ly2 + xy2
c2 =lz2 + xz2 + yz2
xy ∗ xz + ly ∗ yz
cos α =
b∗c
xz
cos β =
c
xy
cos γ =
b
The inverse relationship can be written as follows:

lx =a
xy =b cos γ
xz =c cos β
ly2 =b2 − xy2
b ∗ c cos α − xy ∗ xz
yz =
ly
lz2 =c2 − xz2 − yz2

The values of a, b, c, α , β, and γ can be printed out or accessed by computes using the thermo_style custom keywords
cella, cellb, cellc, cellalpha, cellbeta, cellgamma, respectively.

212 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

As discussed on the dump command doc page, when the BOX BOUNDS for a snapshot is written to a dump file for
a triclinic box, an orthogonal bounding box which encloses the triclinic simulation box is output, along with the 3 tilt
factors (xy, xz, yz) of the triclinic box, formatted as follows:

ITEM: BOX BOUNDS xy xz yz

xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz

This bounding box is convenient for many visualization programs and is calculated from the 9 triclinic box parameters
(xlo,xhi,ylo,yhi,zlo,zhi,xy,xz,yz) as follows:

xlo_bound = xlo + MIN(0.0,xy,xz,xy+xz)

xhi_bound = xhi + MAX(0.0,xy,xz,xy+xz)
ylo_bound = ylo + MIN(0.0,yz)
yhi_bound = yhi + MAX(0.0,yz)
zlo_bound = zlo
zhi_bound = zhi

These formulas can be inverted if you need to convert the bounding box back into the triclinic box parameters, e.g. xlo
= xlo_bound - MIN(0.0,xy,xz,xy+xz).
One use of triclinic simulation boxes is to model solid-state crystals with triclinic symmetry. The lattice command can
be used with non-orthogonal basis vectors to define a lattice that will tile a triclinic simulation box via the create_atoms
command.
A second use is to run Parrinello-Rahman dynamics via the fix npt command, which will adjust the xy, xz, yz tilt
factors to compensate for off-diagonal components of the pressure tensor. The analog for an energy minimization is the
fix box/relax command.
A third use is to shear a bulk solid to study the response of the material. The fix deform command can be used for
this purpose. It allows dynamic control of the xy, xz, yz tilt factors as a simulation runs. This is discussed in the next
section on non-equilibrium MD (NEMD) simulations.

8.2.3 Thermostats

Thermostatting means controlling the temperature of particles in an MD simulation. Barostatting means controlling
the pressure. Since the pressure includes a kinetic component due to particle velocities, both these operations require
calculation of the temperature. Typically a target temperature (T) and/or pressure (P) is specified by the user, and the
thermostat or barostat attempts to equilibrate the system to the requested T and/or P.
Thermostatting in LAMMPS is performed by fixes, or in one case by a pair style. Several thermostatting fixes are
available: Nose-Hoover (nvt), Berendsen, CSVR, Langevin, and direct rescaling (temp/rescale). Dissipative particle
dynamics (DPD) thermostatting can be invoked via the dpd/tstat pair style:
• fix nvt
• fix nvt/sphere
• fix nvt/asphere
• fix nvt/sllod
• fix temp/berendsen
• fix temp/csvr
• fix langevin

8.2. Settings howto 213

LAMMPS Documentation, Release stable 29Sep2021

• fix temp/rescale
• pair_style dpd/tstat
Fix nvt only thermostats the translational velocity of particles. Fix nvt/sllod also does this, except that it subtracts out
a velocity bias due to a deforming box and integrates the SLLOD equations of motion. See the Howto nemd page for
further details. Fix nvt/sphere and fix nvt/asphere thermostat not only translation velocities but also rotational velocities
for spherical and aspherical particles.

Note: A recent (2017) book by (Daivis and Todd) discusses use of the SLLOD method and non-equilibrium MD
(NEMD) thermostatting generally, for both simple and complex fluids, e.g. molecular systems. The latter can be tricky
to do correctly.

DPD thermostatting alters pairwise interactions in a manner analogous to the per-particle thermostatting of fix langevin.
Any of the thermostatting fixes can be instructed to use custom temperature computes that remove bias which has two
effects: first, the current calculated temperature, which is compared to the requested target temperature, is calculated
with the velocity bias removed; second, the thermostat adjusts only the thermal temperature component of the particle’s
velocities, which are the velocities with the bias removed. The removed bias is then added back to the adjusted velocities.
See the doc pages for the individual fixes and for the fix_modify command for instructions on how to assign a temperature
compute to a thermostatting fix. For example, you can apply a thermostat to only the x and z components of velocity by
using it in conjunction with compute temp/partial. Of you could thermostat only the thermal temperature of a streaming
flow of particles without affecting the streaming velocity, by using compute temp/profile.
Below is a list of some custom temperature computes that can be used like that:
• compute temp/asphere command
• compute temp/body command
• compute temp/chunk command
• compute temp/com command
• compute temp/deform command
• compute temp/partial command
• compute temp/profile command
• compute temp/ramp command
• compute temp/region command
• compute temp/rotate command
• compute temp/sphere command

Note: Only the nvt fixes perform time integration, meaning they update the velocities and positions of particles due
to forces and velocities respectively. The other thermostat fixes only adjust velocities; they do NOT perform time
integration updates. Thus they should be used in conjunction with a constant NVE integration fix such as these:

• fix nve
• fix nve/sphere
• fix nve/asphere
Thermodynamic output, which can be setup via the thermo_style command, often includes temperature values. As
explained on the page for the thermo_style command, the default temperature is setup by the thermo command itself. It
is NOT the temperature associated with any thermostatting fix you have defined or with any compute you have defined

214 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

that calculates a temperature. The doc pages for the thermostatting fixes explain the ID of the temperature compute
they create. Thus if you want to view these temperatures, you need to specify them explicitly via the thermo_style
custom command. Or you can use the thermo_modify command to re-define what temperature compute is used for
default thermodynamic output.

(Daivis and Todd) Daivis and Todd, Nonequilibrium Molecular Dynamics (book), Cambridge University Press, https:
//doi.org/10.1017/9781139017848, (2017).

8.2.4 Barostats

Barostatting means controlling the pressure in an MD simulation. Thermostatting means controlling the temperature of
the particles. Since the pressure includes a kinetic component due to particle velocities, both these operations require
calculation of the temperature. Typically a target temperature (T) and/or pressure (P) is specified by the user, and the
thermostat or barostat attempts to equilibrate the system to the requested T and/or P.
Barostatting in LAMMPS is performed by fixes. Two barostatting methods are currently available: Nose-Hoover (npt
and nph) and Berendsen:
• fix npt
• fix npt/sphere
• fix npt/asphere
• fix nph
• fix press/berendsen
The fix npt commands include a Nose-Hoover thermostat and barostat. Fix nph is just a Nose/Hoover barostat; it does
no thermostatting. Both fix nph and fix press/berendsen can be used in conjunction with any of the thermostatting fixes.
As with the thermostats, fix npt and fix nph only use translational motion of the particles in computing T and P and
performing thermo/barostatting. Fix npt/sphere and fix npt/asphere thermo/barostat using not only translation velocities
but also rotational velocities for spherical and aspherical particles.
All of the barostatting fixes use the compute pressure compute to calculate a current pressure. By default, this compute
is created with a simple compute temp (see the last argument of the compute pressure command), which is used to
calculated the kinetic component of the pressure. The barostatting fixes can also use temperature computes that remove
bias for the purpose of computing the kinetic component which contributes to the current pressure. See the doc pages
for the individual fixes and for the fix_modify command for instructions on how to assign a temperature or pressure
compute to a barostatting fix.

Note: As with the thermostats, the Nose/Hoover methods (fix npt and fix nph) perform time integration. Fix
press/berendsen does NOT, so it should be used with one of the constant NVE fixes or with one of the NVT fixes.

Thermodynamic output, which can be setup via the thermo_style command, often includes pressure values. As ex-
plained on the page for the thermo_style command, the default pressure is setup by the thermo command itself. It is
NOT the pressure associated with any barostatting fix you have defined or with any compute you have defined that
calculates a pressure. The doc pages for the barostatting fixes explain the ID of the pressure compute they create. Thus
if you want to view these pressures, you need to specify them explicitly via the thermo_style custom command. Or you
can use the thermo_modify command to re-define what pressure compute is used for default thermodynamic output.

8.2. Settings howto 215

LAMMPS Documentation, Release stable 29Sep2021

8.2.5 Walls

Walls in an MD simulation are typically used to bound particle motion, i.e. to serve as a boundary condition.
Walls in LAMMPS can be of rough (made of particles) or idealized surfaces. Ideal walls can be smooth, generating
forces only in the normal direction, or frictional, generating forces also in the tangential direction.
Rough walls, built of particles, can be created in various ways. The particles themselves can be generated like any other
particle, via the lattice and create_atoms commands, or read in via the read_data command.
Their motion can be constrained by many different commands, so that they do not move at all, move together as a group
at constant velocity or in response to a net force acting on them, move in a prescribed fashion (e.g. rotate around a
point), etc. Note that if a time integration fix like fix nve or fix nvt is not used with the group that contains wall particles,
their positions and velocities will not be updated.
• fix aveforce - set force on particles to average value, so they move together
• fix setforce - set force on particles to a value, e.g. 0.0
• fix freeze - freeze particles for use as granular walls
• fix nve/noforce - advect particles by their velocity, but without force
• fix move - prescribe motion of particles by a linear velocity, oscillation, rotation, variable
The fix move command offers the most generality, since the motion of individual particles can be specified with variable
formula which depends on time and/or the particle position.
For rough walls, it may be useful to turn off pairwise interactions between wall particles via the neigh_modify exclude
command.
Rough walls can also be created by specifying frozen particles that do not move and do not interact with mobile particles,
and then tethering other particles to the fixed particles, via a bond. The bonded particles do interact with other mobile
particles.
Idealized walls can be specified via several fix commands. Fix wall/gran creates frictional walls for use with granular
particles; all the other commands create smooth walls.
• fix wall/reflect - reflective flat walls
• fix wall/lj93 - flat walls, with Lennard-Jones 9/3 potential
• fix wall/lj126 - flat walls, with Lennard-Jones 12/6 potential
• fix wall/colloid - flat walls, with pair_style colloid potential
• fix wall/harmonic - flat walls, with repulsive harmonic spring potential
• fix wall/morse - flat walls, with Morse potential
• fix wall/region - use region surface as wall
• fix wall/gran - flat or curved walls with pair_style granular potential
The lj93, lj126, colloid, harmonic, and morse styles all allow the flat walls to move with a constant velocity, or oscillate
in time. The fix wall/region command offers the most generality, since the region surface is treated as a wall, and the
geometry of the region can be a simple primitive volume (e.g. a sphere, or cube, or plane), or a complex volume made
from the union and intersection of primitive volumes. Regions can also specify a volume “interior” or “exterior” to the
specified primitive shape or union or intersection. Regions can also be “dynamic” meaning they move with constant
velocity, oscillate, or rotate.
The only frictional idealized walls currently in LAMMPS are flat or curved surfaces specified by the fix wall/gran
command. At some point we plan to allow region surfaces to be used as frictional walls, as well as triangulated
surfaces.

216 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

8.2.6 NEMD simulations

Non-equilibrium molecular dynamics or NEMD simulations are typically used to measure a fluid’s rheological proper-
ties such as viscosity. In LAMMPS, such simulations can be performed by first setting up a non-orthogonal simulation
box (see the preceding Howto section).
A shear strain can be applied to the simulation box at a desired strain rate by using the fix deform command. The fix
nvt/sllod command can be used to thermostat the sheared fluid and integrate the SLLOD equations of motion for the
system. Fix nvt/sllod uses compute temp/deform to compute a thermal temperature by subtracting out the streaming
velocity of the shearing atoms. The velocity profile or other properties of the fluid can be monitored via the fix ave/chunk
command.

Note: A recent (2017) book by (Daivis and Todd) discusses use of the SLLOD method and non-equilibrium MD
(NEMD) thermostatting generally, for both simple and complex fluids, e.g. molecular systems. The latter can be tricky
to do correctly.

As discussed in the previous section on non-orthogonal simulation boxes, the amount of tilt or skew that can be applied
is limited by LAMMPS for computational efficiency to be 1/2 of the parallel box length. However, fix deform can
continuously strain a box by an arbitrary amount. As discussed in the fix deform command, when the tilt value reaches
a limit, the box is flipped to the opposite limit which is an equivalent tiling of periodic space. The strain rate can then
continue to change as before. In a long NEMD simulation these box re-shaping events may occur many times.
In a NEMD simulation, the “remap” option of fix deform should be set to “remap v”, since that is what fix nvt/sllod
assumes to generate a velocity profile consistent with the applied shear strain rate.
An alternative method for calculating viscosities is provided via the fix viscosity command.
NEMD simulations can also be used to measure transport properties of a fluid through a pore or channel. Simulations
of steady-state flow can be performed using the fix flow/gauss command.

(Daivis and Todd) Daivis and Todd, Nonequilibrium Molecular Dynamics (book), Cambridge University Press, https:
//doi.org/10.1017/9781139017848, (2017).

8.2.7 Long-range dispersion settings

The PPPM method computes interactions by splitting the pair potential into two parts, one of which is computed in a
normal pairwise fashion, the so-called real-space part, and one of which is computed using the Fourier transform, the
so called reciprocal-space or kspace part. For both parts, the potential is not computed exactly but is approximated.
Thus, there is an error in both parts of the computation, the real-space and the kspace error. The just mentioned facts
are true both for the PPPM for Coulomb as well as dispersion interactions. The deciding difference - and also the reason
why the parameters for pppm/disp have to be selected with more care - is the impact of the errors on the results: The
kspace error of the PPPM for Coulomb and dispersion interaction and the real-space error of the PPPM for Coulomb
interaction have the character of noise. In contrast, the real-space error of the PPPM for dispersion has a clear physical
interpretation: the underprediction of cohesion. As a consequence, the real-space error has a much stronger effect than
the kspace error on simulation results for pppm/disp. Parameters must thus be chosen in a way that this error is much
smaller than the kspace error.
When using pppm/disp and not making any specifications on the PPPM parameters via the kspace modify command,
parameters will be tuned such that the real-space error and the kspace error are equal. This will result in simulations
that are either inaccurate or slow, both of which is not desirable. For selecting parameters for the pppm/disp that provide
fast and accurate simulations, there are two approaches, which both have their up- and downsides.
The first approach is to set desired real-space an kspace accuracies via the kspace_modify force/disp/real and
kspace_modify force/disp/kspace commands. Note that the accuracies have to be specified in force units and are thus

8.2. Settings howto 217

LAMMPS Documentation, Release stable 29Sep2021

dependent on the chosen unit settings. For real units, 0.0001 and 0.002 seem to provide reasonable accurate and effi-
cient computations for the real-space and kspace accuracies. 0.002 and 0.05 work well for most systems using lj units.
PPPM parameters will be generated based on the desired accuracies. The upside of this approach is that it usually
provides a good set of parameters and will work for both the kspace_modify diff ad and kspace_modify diff ik options.
The downside of the method is that setting the PPPM parameters will take some time during the initialization of the
simulation.
The second approach is to set the parameters for the pppm/disp explicitly using the kspace_modify mesh/disp,
kspace_modify order/disp, and kspace_modify gewald/disp commands. This approach requires a more experienced
user who understands well the impact of the choice of parameters on the simulation accuracy and performance. This
approach provides a fast initialization of the simulation. However, it is sensitive to errors: A combination of parameters
that will perform well for one system might result in far-from-optimal conditions for other simulations. For example,
parameters that provide accurate and fast computations for all-atomistic force fields can provide insufficient accuracy
or united-atomistic force fields (which is related to that the latter typically have larger dispersion coefficients).
To avoid inaccurate or inefficient simulations, the pppm/disp stops simulations with an error message if no action is
taken to control the PPPM parameters. If the automatic parameter generation is desired and real-space and kspace ac-
curacies are desired to be equal, this error message can be suppressed using the kspace_modify disp/auto yes command.
A reasonable approach that combines the upsides of both methods is to make the first run using the kspace_modify
force/disp/real and kspace_modify force/disp/kspace commands, write down the PPPM parameters from the output,
and specify these parameters using the second approach in subsequent runs (which have the same composition, force
field, and approximately the same volume).
Concerning the performance of the pppm/disp there are two more things to consider. The first is that when using
the pppm/disp, the cutoff parameter does no longer affect the accuracy of the simulation (subject to that gewald/disp is
adjusted when changing the cutoff). The performance can thus be increased by examining different values for the cutoff
parameter. A lower bound for the cutoff is only set by the truncation error of the repulsive term of pair potentials.
The second is that the mixing rule of the pair style has an impact on the computation time when using the pppm/disp.
Fastest computations are achieved when using the geometric mixing rule. Using the arithmetic mixing rule substan-
tially increases the computational cost. The computational overhead can be reduced using the kspace_modify mix/disp
geom and kspace_modify splittol commands. The first command simply enforces geometric mixing of the dispersion
coefficients in kspace computations. This introduces some error in the computations but will also significantly speed-up
the simulations. The second keyword sets the accuracy with which the dispersion coefficients are approximated using
a matrix factorization approach. This may result in better accuracy then using the first command, but will usually also
not provide an equally good increase of efficiency.
Finally, pppm/disp can also be used when no mixing rules apply. This can be achieved using the kspace_modify mix/disp
none command. Note that the code does not check automatically whether any mixing rule is fulfilled. If mixing rules
do not apply, the user will have to specify this command explicitly.

8.3 Analysis howto

8.3.1 Output from LAMMPS (thermo, dumps, computes, fixes, variables)

There are four basic kinds of LAMMPS output:

• Thermodynamic output, which is a list of quantities printed every few timesteps to the screen and logfile.
• Dump files, which contain snapshots of atoms and various per-atom values and are written at a specified fre-
quency.
• Certain fixes can output user-specified quantities to files: fix ave/time for time averaging, fix ave/chunk for spatial
or other averaging, and fix print for single-line output of variables. Fix print can also output to the screen.
• Restart files.

218 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

A simulation prints one set of thermodynamic output and (optionally) restart files. It can generate any number of dump
files and fix output files, depending on what dump and fix commands you specify.
As discussed below, LAMMPS gives you a variety of ways to determine what quantities are computed and printed
when the thermodynamics, dump, or fix commands listed above perform output. Throughout this discussion, note that
users can also add their own computes and fixes to LAMMPS which can then generate values that can then be output
with these commands.
The following sub-sections discuss different LAMMPS command related to output and the kind of data they operate
on and produce:
• Global/per-atom/local data
• Scalar/vector/array data
• Thermodynamic output
• Dump file output
• Fixes that write output files
• Computes that process output quantities
• Fixes that process output quantities
• Computes that generate values to output
• Fixes that generate values to output
• Variables that generate values to output
• Summary table of output options and data flow between commands

Global/per-atom/local data

Various output-related commands work with three different styles of data: global, per-atom, or local. A global datum
is one or more system-wide values, e.g. the temperature of the system. A per-atom datum is one or more values per
atom, e.g. the kinetic energy of each atom. Local datums are calculated by each processor based on the atoms it owns,
but there may be zero or more per atom, e.g. a list of bond distances.

Scalar/vector/array data

Global, per-atom, and local datums can each come in three kinds: a single scalar value, a vector of values, or a 2d array
of values. The doc page for a “compute” or “fix” or “variable” that generates data will specify both the style and kind
of data it produces, e.g. a per-atom vector.
When a quantity is accessed, as in many of the output commands discussed below, it can be referenced via the following
bracket notation, where ID in this case is the ID of a compute. The leading “c_” would be replaced by “f_” for a fix, or
“v_” for a variable:

c_ID entire scalar, vector, or array

c_ID[I] one element of vector, one column of array
c_ID[I][J] one element of array

In other words, using one bracket reduces the dimension of the data once (vector -> scalar, array -> vector). Using two
brackets reduces the dimension twice (array -> scalar). Thus a command that uses scalar values as input can typically
also process elements of a vector or array.

8.3. Analysis howto 219

LAMMPS Documentation, Release stable 29Sep2021

Disambiguation

Some computes and fixes produce data in multiple styles, e.g. a global scalar and a per-atom vector. Usually the context
in which the input script references the data determines which style is meant. Example: if a compute provides both
a global scalar and a per-atom vector, the former will be accessed by using c_ID in an equal-style variable, while the
latter will be accessed by using c_ID in an atom-style variable. Note that atom-style variable formulas can also access
global scalars, but in this case it is not possible to do directly because of the ambiguity. Instead, an equal-style variable
can be defined which accesses the global scalar, and that variable used in the atom-style variable formula in place of
c_ID.

Thermodynamic output

The frequency and format of thermodynamic output is set by the thermo, thermo_style, and thermo_modify commands.
The thermo_style command also specifies what values are calculated and written out. Pre-defined keywords can be
specified (e.g. press, etotal, etc). Three additional kinds of keywords can also be specified (c_ID, f_ID, v_name),
where a compute or fix or variable provides the value to be output. In each case, the compute, fix, or variable must
generate global values for input to the thermo_style custom command.
Note that thermodynamic output values can be “extensive” or “intensive”. The former scale with the number of atoms
in the system (e.g. total energy), the latter do not (e.g. temperature). The setting for thermo_modify norm determines
whether extensive quantities are normalized or not. Computes and fixes produce either extensive or intensive values; see
their individual doc pages for details. Equal-style variables produce only intensive values; you can include a division
by “natoms” in the formula if desired, to make an extensive calculation produce an intensive result.

Dump file output

Dump file output is specified by the dump and dump_modify commands. There are several pre-defined formats (dump
atom, dump xtc, etc).
There is also a dump custom format where the user specifies what values are output with each atom. Pre-defined
atom attributes can be specified (id, x, fx, etc). Three additional kinds of keywords can also be specified (c_ID, f_ID,
v_name), where a compute or fix or variable provides the values to be output. In each case, the compute, fix, or variable
must generate per-atom values for input to the dump custom command.
There is also a dump local format where the user specifies what local values to output. A pre-defined index keyword
can be specified to enumerate the local values. Two additional kinds of keywords can also be specified (c_ID, f_ID),
where a compute or fix or variable provides the values to be output. In each case, the compute or fix must generate
local values for input to the dump local command.

Fixes that write output files

Several fixes take various quantities as input and can write output files: fix ave/time, fix ave/chunk, fix ave/histo, fix
ave/correlate, and fix print.
The fix ave/time command enables direct output to a file and/or time-averaging of global scalars or vectors. The user
specifies one or more quantities as input. These can be global compute values, global fix values, or variables of any style
except the atom style which produces per-atom values. Since a variable can refer to keywords used by the thermo_style
custom command (like temp or press) and individual per-atom values, a wide variety of quantities can be time averaged
and/or output in this way. If the inputs are one or more scalar values, then the fix generate a global scalar or vector
of output. If the inputs are one or more vector values, then the fix generates a global vector or array of output. The
time-averaged output of this fix can also be used as input to other output commands.
The fix ave/chunk command enables direct output to a file of chunk-averaged per-atom quantities like those output in
dump files. Chunks can represent spatial bins or other collections of atoms, e.g. individual molecules. The per-atom

220 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

quantities can be atom density (mass or number) or atom attributes such as position, velocity, force. They can also be
per-atom quantities calculated by a compute, by a fix, or by an atom-style variable. The chunk-averaged output of this
fix can also be used as input to other output commands.
The fix ave/histo command enables direct output to a file of histogrammed quantities, which can be global or per-atom
or local quantities. The histogram output of this fix can also be used as input to other output commands.
The fix ave/correlate command enables direct output to a file of time-correlated quantities, which can be global values.
The correlation matrix output of this fix can also be used as input to other output commands.
The fix print command can generate a line of output written to the screen and log file or to a separate file, periodically
during a running simulation. The line can contain one or more variable values for any style variable except the vector
or atom styles). As explained above, variables themselves can contain references to global values generated by ther-
modynamic keywords, computes, fixes, or other variables, or to per-atom values for a specific atom. Thus the fix print
command is a means to output a wide variety of quantities separate from normal thermodynamic or dump file output.

Computes that process output quantities

The compute reduce and compute reduce/region commands take one or more per-atom or local vector quantities as
inputs and “reduce” them (sum, min, max, ave) to scalar quantities. These are produced as output values which can be
used as input to other output commands.
The compute slice command take one or more global vector or array quantities as inputs and extracts a subset of their
values to create a new vector or array. These are produced as output values which can be used as input to other output
commands.
The compute property/atom command takes a list of one or more pre-defined atom attributes (id, x, fx, etc) and stores
the values in a per-atom vector or array. These are produced as output values which can be used as input to other output
commands. The list of atom attributes is the same as for the dump custom command.
The compute property/local command takes a list of one or more pre-defined local attributes (bond info, angle info,
etc) and stores the values in a local vector or array. These are produced as output values which can be used as input to
other output commands.

Fixes that process output quantities

The fix vector command can create global vectors as output from global scalars as input, accumulating them one element
at a time.
The fix ave/atom command performs time-averaging of per-atom vectors. The per-atom quantities can be atom attributes
such as position, velocity, force. They can also be per-atom quantities calculated by a compute, by a fix, or by an atom-
style variable. The time-averaged per-atom output of this fix can be used as input to other output commands.
The fix store/state command can archive one or more per-atom attributes at a particular time, so that the old values can
be used in a future calculation or output. The list of atom attributes is the same as for the dump custom command,
including per-atom quantities calculated by a compute, by a fix, or by an atom-style variable. The output of this fix can
be used as input to other output commands.

8.3. Analysis howto 221

LAMMPS Documentation, Release stable 29Sep2021

Computes that generate values to output

Every compute in LAMMPS produces either global or per-atom or local values. The values can be scalars or vectors
or arrays of data. These values can be output using the other commands described in this section. The page for each
compute command describes what it produces. Computes that produce per-atom or local values have the word “atom”
or “local” in their style name. Computes without the word “atom” or “local” produce global values.

Fixes that generate values to output

Some fixes in LAMMPS produces either global or per-atom or local values which can be accessed by other commands.
The values can be scalars or vectors or arrays of data. These values can be output using the other commands described
in this section. The page for each fix command tells whether it produces any output quantities and describes them.

Variables that generate values to output

Variables defined in an input script can store one or more strings. But equal-style, vector-style, and atom-style or
atomfile-style variables generate a global scalar value, global vector or values, or a per-atom vector, respectively, when
accessed. The formulas used to define these variables can contain references to the thermodynamic keywords and to
global and per-atom data generated by computes, fixes, and other variables. The values generated by variables can be
used as input to and thus output by the other commands described in this section.

Summary table of output options and data flow between commands

This table summarizes the various commands that can be used for generating output from LAMMPS. Each command
produces output data of some kind and/or writes data to a file. Most of the commands can take data from other com-
mands as input. Thus you can link many of these commands together in pipeline form, where data produced by one
command is used as input to another command and eventually written to the screen or to a file. Note that to hook two
commands together the output and input data types must match, e.g. global/per-atom/local data and scalar/vector/array
data.
Also note that, as described above, when a command takes a scalar as input, that could be an element of a vector or
array. Likewise a vector input could be a column of an array.

222 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Command Input Output

thermo_style custom global scalars screen, log file
dump custom per-atom vectors dump file
dump local local vectors dump file
fix print global scalar from variable screen, file
print global scalar from variable screen
computes N/A global/per-atom/local scalar/vector/array
fixes N/A global/per-atom/local scalar/vector/array
variables global scalars and vectors, per-atom vectors global scalar and vector, per-atom vector
compute reduce per-atom/local vectors global scalar/vector
compute slice global vectors/arrays global vector/array
compute property/atom per-atom vectors per-atom vector/array
compute property/local local vectors local vector/array
fix vector global scalars global vector
fix ave/atom per-atom vectors per-atom vector/array
fix ave/time global scalars/vectors global scalar/vector/array, file
fix ave/chunk per-atom vectors global array, file
fix ave/histo global/per-atom/local scalars and vectors global array, file
fix ave/correlate global scalars global array, file
fix store/state per-atom vectors per-atom vector/array

8.3.2 Use chunks to calculate system properties

In LAMMS, “chunks” are collections of atoms, as defined by the compute chunk/atom command, which assigns each
atom to a chunk ID (or to no chunk at all). The number of chunks and the assignment of chunk IDs to atoms can
be static or change over time. Examples of “chunks” are molecules or spatial bins or atoms with similar values (e.g.
coordination number or potential energy).
The per-atom chunk IDs can be used as input to two other kinds of commands, to calculate various properties of a
system:
• fix ave/chunk
• any of the compute */chunk commands
Here a brief overview for each of the 4 kinds of chunk-related commands is provided. Then some examples are given
of how to compute different properties with chunk commands.

8.3. Analysis howto 223

LAMMPS Documentation, Release stable 29Sep2021

Compute chunk/atom command:

This compute can assign atoms to chunks of various styles. Only atoms in the specified group and optional specified
region are assigned to a chunk. Here are some possible chunk definitions:

atoms in same molecule chunk ID = molecule ID

atoms of same atom type chunk ID = atom type
all atoms with same atom property (charge, ra- chunk ID = output of compute property/atom
dius, etc)
atoms in same cluster chunk ID = output of compute cluster/atom command
atoms in same spatial bin chunk ID = bin ID
atoms in same rigid body chunk ID = molecule ID used to define rigid bodies
atoms with similar potential energy chunk ID = output of compute pe/atom
atoms with same local defect structure chunk ID = output of compute centro/atom or compute coord/atom
command

Note that chunk IDs are integer values, so for atom properties or computes that produce a floating point value, they will
be truncated to an integer. You could also use the compute in a variable that scales the floating point value to spread it
across multiple integers.
Spatial bins can be of various kinds, e.g. 1d bins = slabs, 2d bins = pencils, 3d bins = boxes, spherical bins, cylindrical
bins.
This compute also calculates the number of chunks Nchunk, which is used by other commands to tally per-chunk data.
Nchunk can be a static value or change over time (e.g. the number of clusters). The chunk ID for an individual atom
can also be static (e.g. a molecule ID), or dynamic (e.g. what spatial bin an atom is in as it moves).
Note that this compute allows the per-atom output of other computes, fixes, and variables to be used to define chunk
IDs for each atom. This means you can write your own compute or fix to output a per-atom quantity to use as chunk
ID. See the Modify doc pages for info on how to do this. You can also define a per-atom variable in the input script that
uses a formula to generate a chunk ID for each atom.

Fix ave/chunk command:

This fix takes the ID of a compute chunk/atom command as input. For each chunk, it then sums one or more specified
per-atom values over the atoms in each chunk. The per-atom values can be any atom property, such as velocity, force,
charge, potential energy, kinetic energy, stress, etc. Additional keywords are defined for per-chunk properties like
density and temperature. More generally any per-atom value generated by other computes, fixes, and per-atom variables,
can be summed over atoms in each chunk.
Similar to other averaging fixes, this fix allows the summed per-chunk values to be time-averaged in various ways, and
output to a file. The fix produces a global array as output with one row of values per chunk.

Compute */chunk commands:

The following computes operate on chunks of atoms to produce per-chunk values. Any compute whose style name
ends in “/chunk” is in this category:
• compute com/chunk
• compute gyration/chunk
• compute inertia/chunk
• compute msd/chunk

224 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

• compute property/chunk
• compute temp/chunk
• compute torque/chunk
• compute vcm/chunk
They each take the ID of a compute chunk/atom command as input. As their names indicate, they calculate the center-
of-mass, radius of gyration, moments of inertia, mean-squared displacement, temperature, torque, and velocity of
center-of-mass for each chunk of atoms. The compute property/chunk command can tally the count of atoms in each
chunk and extract other per-chunk properties.
The reason these various calculations are not part of the fix ave/chunk command, is that each requires a more complicated
operation than simply summing and averaging over per-atom values in each chunk. For example, many of them require
calculation of a center of mass, which requires summing mass*position over the atoms and then dividing by summed
mass.
All of these computes produce a global vector or global array as output, with one or more values per chunk. The output
can be used in various ways:
• As input to the fix ave/time command, which can write the values to a file and optionally time average them.
• As input to the fix ave/histo command to histogram values across chunks. E.g. a histogram of cluster sizes or
molecule diffusion rates.
• As input to special functions of equal-style variables, like sum() and max() and ave(). E.g. to find the largest
cluster or fastest diffusing molecule or average radius-of-gyration of a set of molecules (chunks).

Other chunk commands:

• compute chunk/spread/atom
• compute reduce/chunk
The compute chunk/spread/atom command spreads per-chunk values to each atom in the chunk, producing per-atom
values as its output. This can be useful for outputting per-chunk values to a per-atom dump file. Or for using an
atom’s associated chunk value in an atom-style variable. Or as input to the fix ave/chunk command to spatially average
per-chunk values calculated by a per-chunk compute.
The compute reduce/chunk command reduces a peratom value across the atoms in each chunk to produce a value per
chunk. When used with the compute chunk/spread/atom command it can create peratom values that induce a new set
of chunks with a second compute chunk/atom command.

Example calculations with chunks

Here are examples using chunk commands to calculate various properties:

(1) Average velocity in each of 1000 2d spatial bins:

compute cc1 all chunk/atom bin/2d x 0.0 0.1 y lower 0.01 units reduced
fix 1 all ave/chunk 100 10 1000 cc1 vx vy file tmp.out

(2) Temperature in each spatial bin, after subtracting a flow velocity:

compute cc1 all chunk/atom bin/2d x 0.0 0.1 y lower 0.1 units reduced
compute vbias all temp/profile 1 0 0 y 10
fix 1 all ave/chunk 100 10 1000 cc1 temp bias vbias file tmp.out

8.3. Analysis howto 225

LAMMPS Documentation, Release stable 29Sep2021

(3) Center of mass of each molecule:

compute cc1 all chunk/atom molecule

compute myChunk all com/chunk cc1
fix 1 all ave/time 100 1 100 c_myChunk[*] file tmp.out mode vector

(4) Total force on each molecule and ave/max across all molecules:

compute cc1 all chunk/atom molecule

fix 1 all ave/chunk 1000 1 1000 cc1 fx fy fz file tmp.out
variable xave equal ave(f_1[2])
variable xmax equal max(f_1[2])
thermo 1000
thermo_style custom step temp v_xave v_xmax

(5) Histogram of cluster sizes:

compute cluster all cluster/atom 1.0

compute cc1 all chunk/atom c_cluster compress yes
compute size all property/chunk cc1 count
fix 1 all ave/histo 100 1 100 0 20 20 c_size mode vector ave running beyond ignore file␣
,→tmp.histo

(6) An example for using a per-chunk value to apply per-atom forces to compress individual polymer chains (molecules)
in a mixture, is explained on the compute chunk/spread/atom command doc page.
(7) An example for using one set of per-chunk values for molecule chunks, to create a second set of micelle-scale chunks
(clustered molecules, due to hydrophobicity), is explained on the compute reduce/chunk command doc page.
(8) An example for using one set of per-chunk values (dipole moment vectors) for molecule chunks, spreading the values
to each atom in each chunk, then defining a second set of chunks as spatial bins, and using the fix ave/chunk command to
calculate an average dipole moment vector for each bin. This example is explained on the compute chunk/spread/atom
command doc page.

8.3.3 Calculate temperature

Temperature is computed as kinetic energy divided by some number of degrees of freedom (and the Boltzmann con-
stant). Since kinetic energy is a function of particle velocity, there is often a need to distinguish between a particle’s
advection velocity (due to some aggregate motion of particles) and its thermal velocity. The sum of the two is the
particle’s total velocity, but the latter is often what is wanted to compute a temperature.
LAMMPS has several options for computing temperatures, any of which can be used in thermostatting and barostatting.
These compute commands calculate temperature:
• compute temp
• compute temp/sphere
• compute temp/asphere
• compute temp/com
• compute temp/deform
• compute temp/partial
• compute temp/profile
• compute temp/ramp

226 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

• compute temp/region
All but the first 3 calculate velocity biases directly (e.g. advection velocities) that are removed when computing the
thermal temperature. Compute temp/sphere and compute temp/asphere compute kinetic energy for finite-size particles
that includes rotational degrees of freedom. They both allow for velocity biases indirectly, via an optional extra ar-
gument which is another temperature compute that subtracts a velocity bias. This allows the translational velocity of
spherical or aspherical particles to be adjusted in prescribed ways.

8.3.4 Calculate elastic constants

Elastic constants characterize the stiffness of a material. The formal definition is provided by the linear relation that
holds between the stress and strain tensors in the limit of infinitesimal deformation. In tensor notation, this is expressed
as s_ij = C_ijkl * e_kl, where the repeated indices imply summation. s_ij are the elements of the symmetric stress
tensor. e_kl are the elements of the symmetric strain tensor. C_ijkl are the elements of the fourth rank tensor of elastic
constants. In three dimensions, this tensor has 3^4=81 elements. Using Voigt notation, the tensor can be written as a
6x6 matrix, where C_ij is now the derivative of s_i w.r.t. e_j. Because s_i is itself a derivative w.r.t. e_i, it follows that
C_ij is also symmetric, with at most 7*6/2 = 21 distinct elements.
At zero temperature, it is easy to estimate these derivatives by deforming the simulation box in one of the six directions
using the change_box command and measuring the change in the stress tensor. A general-purpose script that does this
is given in the examples/elastic directory described on the Examples doc page.
Calculating elastic constants at finite temperature is more challenging, because it is necessary to run a simulation that
performs time averages of differential properties. One way to do this is to measure the change in average stress tensor
in an NVT simulations when the cell volume undergoes a finite deformation. In order to balance the systematic and
statistical errors in this method, the magnitude of the deformation must be chosen judiciously, and care must be taken
to fully equilibrate the deformed cell before sampling the stress tensor. Another approach is to sample the triclinic
cell fluctuations that occur in an NPT simulation. This method can also be slow to converge and requires careful
post-processing (Shinoda)

(Shinoda) Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).

8.3.5 Calculate thermal conductivity

The thermal conductivity kappa of a material can be measured in at least 4 ways using various options in LAMMPS.
See the examples/KAPPA directory for scripts that implement the 4 methods discussed here for a simple Lennard-Jones
fluid model. Also, see the Howto viscosity page for an analogous discussion for viscosity.
The thermal conductivity tensor kappa is a measure of the propensity of a material to transmit heat energy in a diffusive
manner as given by Fourier’s law
J = -kappa grad(T)
where J is the heat flux in units of energy per area per time and grad(T) is the spatial gradient of temperature. The
thermal conductivity thus has units of energy per distance per time per degree K and is often approximated as an
isotropic quantity, i.e. as a scalar.
The first method is to setup two thermostatted regions at opposite ends of a simulation box, or one in the middle and
one at the end of a periodic box. By holding the two regions at different temperatures with a thermostatting fix, the
energy added to the hot region should equal the energy subtracted from the cold region and be proportional to the heat
flux moving between the regions. See the papers by Ikeshoji and Hafskjold and Wirnsberger et al for details of this
idea. Note that thermostatting fixes such as fix nvt, fix langevin, and fix temp/rescale store the cumulative energy they
add/subtract.

8.3. Analysis howto 227

LAMMPS Documentation, Release stable 29Sep2021

Alternatively, as a second method, the fix heat or fix ehex commands can be used in place of thermostats on each of two
regions to add/subtract specified amounts of energy to both regions. In both cases, the resulting temperatures of the two
regions can be monitored with the “compute temp/region” command and the temperature profile of the intermediate
region can be monitored with the fix ave/chunk and compute ke/atom commands.
The third method is to perform a reverse non-equilibrium MD simulation using the fix thermal/conductivity command
which implements the rNEMD algorithm of Muller-Plathe. Kinetic energy is swapped between atoms in two different
layers of the simulation box. This induces a temperature gradient between the two layers which can be monitored with
the fix ave/chunk and compute ke/atom commands. The fix tallies the cumulative energy transfer that it performs. See
the fix thermal/conductivity command for details.
The fourth method is based on the Green-Kubo (GK) formula which relates the ensemble average of the auto-correlation
of the heat flux to kappa. The heat flux can be calculated from the fluctuations of per-atom potential and kinetic
energies and per-atom stress tensor in a steady-state equilibrated simulation. This is in contrast to the two preceding
non-equilibrium methods, where energy flows continuously between hot and cold regions of the simulation box.
The compute heat/flux command can calculate the needed heat flux and describes how to implement the Green_Kubo
formalism using additional LAMMPS commands, such as the fix ave/correlate command to calculate the needed auto-
correlation. See the page for the compute heat/flux command for an example input script that calculates the thermal
conductivity of solid Ar via the GK formalism.

(Ikeshoji) Ikeshoji and Hafskjold, Molecular Physics, 81, 251-261 (1994).

(Wirnsberger) Wirnsberger, Frenkel, and Dellago, J Chem Phys, 143, 124104 (2015).

8.3.6 Calculate viscosity

The shear viscosity eta of a fluid can be measured in at least 6 ways using various options in LAMMPS. See the
examples/VISCOSITY directory for scripts that implement the 5 methods discussed here for a simple Lennard-Jones
fluid model and 1 method for SPC/E water model. Also, see the page on calculating thermal conductivity for an
analogous discussion for thermal conductivity.
Eta is a measure of the propensity of a fluid to transmit momentum in a direction perpendicular to the direction of
velocity or momentum flow. Alternatively it is the resistance the fluid has to being sheared. It is given by
J = -eta grad(Vstream)
where J is the momentum flux in units of momentum per area per time. and grad(Vstream) is the spatial gradient of
the velocity of the fluid moving in another direction, normal to the area through which the momentum flows. Viscosity
thus has units of pressure-time.
The first method is to perform a non-equilibrium MD (NEMD) simulation by shearing the simulation box via the fix
deform command, and using the fix nvt/sllod command to thermostat the fluid via the SLLOD equations of motion.
Alternatively, as a second method, one or more moving walls can be used to shear the fluid in between them, again
with some kind of thermostat that modifies only the thermal (non-shearing) components of velocity to prevent the fluid
from heating up.

Note: A recent (2017) book by (Daivis and Todd) discusses use of the SLLOD method and non-equilibrium MD
(NEMD) thermostatting generally, for both simple and complex fluids, e.g. molecular systems. The latter can be tricky
to do correctly.

In both cases, the velocity profile setup in the fluid by this procedure can be monitored by the fix ave/chunk command,
which determines grad(Vstream) in the equation above. E.g. the derivative in the y-direction of the Vx component of
fluid motion or grad(Vstream) = dVx/dy. The Pxy off-diagonal component of the pressure or stress tensor, as calculated

228 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

by the compute pressure command, can also be monitored, which is the J term in the equation above. See the Howto
nemd page for details on NEMD simulations.
The third method is to perform a reverse non-equilibrium MD simulation using the fix viscosity command which im-
plements the rNEMD algorithm of Muller-Plathe. Momentum in one dimension is swapped between atoms in two
different layers of the simulation box in a different dimension. This induces a velocity gradient which can be moni-
tored with the fix ave/chunk command. The fix tallies the cumulative momentum transfer that it performs. See the fix
viscosity command for details.
The fourth method is based on the Green-Kubo (GK) formula which relates the ensemble average of the auto-correlation
of the stress/pressure tensor to eta. This can be done in a fully equilibrated simulation which is in contrast to the two
preceding non-equilibrium methods, where momentum flows continuously through the simulation box.
Here is an example input script that calculates the viscosity of liquid Ar via the GK formalism:

# Sample LAMMPS input script for viscosity of liquid Ar

units real
variable T equal 86.4956
variable V equal vol
variable dt equal 4.0
variable p equal 400 # correlation length
variable s equal 5 # sample interval
variable d equal $p*$s # dump interval

# convert from LAMMPS real units to SI

variable kB equal 1.3806504e-23 # [J/K] Boltzmann

variable atm2Pa equal 101325.0
variable A2m equal 1.0e-10
variable fs2s equal 1.0e-15
variable convert equal ${atm2Pa}*${atm2Pa}*${fs2s}*${A2m}*${A2m}*${A2m}

# setup problem

dimension 3
boundary p p p
lattice fcc 5.376 orient x 1 0 0 orient y 0 1 0 orient z 0 0 1
region box block 0 4 0 4 0 4
create_box 1 box
create_atoms 1 box
mass 1 39.948
pair_style lj/cut 13.0
pair_coeff * * 0.2381 3.405
timestep ${dt}
thermo $d

# equilibration and thermalization

velocity all create $T 102486 mom yes rot yes dist gaussian
fix NVT all nvt temp $T $T 10 drag 0.2
run 8000

# viscosity calculation, switch to NVE if desired

(continues on next page)

8.3. Analysis howto 229

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

#unfix NVT
#fix NVE all nve

reset_timestep 0
variable pxy equal pxy
variable pxz equal pxz
variable pyz equal pyz
fix SS all ave/correlate $s $p $d &
v_pxy v_pxz v_pyz type auto file S0St.dat ave running
variable scale equal ${convert}/(${kB}*$T)*$V*$s*${dt}
variable v11 equal trap(f_SS[3])*${scale}
variable v22 equal trap(f_SS[4])*${scale}
variable v33 equal trap(f_SS[5])*${scale}
thermo_style custom step temp press v_pxy v_pxz v_pyz v_v11 v_v22 v_v33
run 100000
variable v equal (v_v11+v_v22+v_v33)/3.0
variable ndens equal count(all)/vol
print "average viscosity: $v [Pa.s] @ $T K, ${ndens} /A^3"

The fifth method is related to the above Green-Kubo method, but uses the Einstein formulation, analogous to the
Einstein mean-square-displacement formulation for self-diffusivity. The time-integrated momentum fluxes play the
role of Cartesian coordinates, whose mean-square displacement increases linearly with time at sufficiently long times.
The sixth is periodic perturbation method. It is also a non-equilibrium MD method. However, instead of measure
the momentum flux in response of applied velocity gradient, it measures the velocity profile in response of applied
stress. A cosine-shaped periodic acceleration is added to the system via the fix accelerate/cos command, and the
compute viscosity/cos command is used to monitor the generated velocity profile and remove the velocity bias before
thermostatting.

Note: An article by (Hess) discussed the accuracy and efficiency of these methods.

(Daivis and Todd) Daivis and Todd, Nonequilibrium Molecular Dynamics (book), Cambridge University Press, https:
//doi.org/10.1017/9781139017848, (2017).
(Hess) Hess, B. The Journal of Chemical Physics 2002, 116 (1), 209-217.

8.3.7 Calculate diffusion coefficients

The diffusion coefficient D of a material can be measured in at least 2 ways using various options in LAMMPS. See
the examples/DIFFUSE directory for scripts that implement the 2 methods discussed here for a simple Lennard-Jones
fluid model.
The first method is to measure the mean-squared displacement (MSD) of the system, via the compute msd command.
The slope of the MSD versus time is proportional to the diffusion coefficient. The instantaneous MSD values can be
accumulated in a vector via the fix vector command, and a line fit to the vector to compute its slope via the variable
slope function, and thus extract D.
The second method is to measure the velocity auto-correlation function (VACF) of the system, via the compute vacf
command. The time-integral of the VACF is proportional to the diffusion coefficient. The instantaneous VACF values
can be accumulated in a vector via the fix vector command, and time integrated via the variable trap function, and thus
extract D.

230 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

8.3.8 Output structured data from LAMMPS

LAMMPS can output structured data with the print and fix print command. This gives you flexibility since you can
build custom data formats that contain system properties, thermo data, and variables values. This output can be directed
to the screen and/or to a file for post processing.

Writing the current system state, thermo data, variable values

Use the print command to output the current system state, which can include system properties, thermo data and
variable values.

YAML

print """---
timestep: $(step)
pe: $(pe)
ke: $(ke)""" file current_state.yaml screen no

Listing 1: current_state.yaml
---
timestep: 250
pe: -4.7774327356321810711
ke: 2.4962152903997174569

JSON

print """{
"timestep": $(step),
"pe": $(pe),
"ke": $(ke)
}""" file current_state.json screen no

8.3. Analysis howto 231

LAMMPS Documentation, Release stable 29Sep2021

Listing 2: current_state.json
{
"timestep": 250,
"pe": -4.7774327356321810711,
"ke": 2.4962152903997174569
}

Writing continuous data during a simulation

The fix print command allows you to output an arbitrary string at defined times during a simulation run.

YAML

fix extra all print 50 """

- timestep: $(step)
pe: $(pe)
ke: $(ke)""" file output.yaml screen no

Listing 3: output.yaml
# Fix print output for fix extra
- timestep: 0
pe: -6.77336805325924729
ke: 4.4988750000000026219

- timestep: 50
pe: -4.8082494418323200591
ke: 2.5257981827119797558

- timestep: 100
pe: -4.7875608875581505686
ke: 2.5062598821985102582

- timestep: 150
pe: -4.7471033686005483787
ke: 2.466095925545450207

- timestep: 200
pe: -4.7509052858544134068
ke: 2.4701136792591693592

- timestep: 250
pe: -4.7774327356321810711
ke: 2.4962152903997174569

Post-processing of YAML files can be easily be done with Python and other scripting languages. In case of Python the
yaml package allows you to load the data files and obtain a list of dictionaries.

232 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

import yaml

with open("output.yaml") as f:
data = yaml.load(f, Loader=yaml.FullLoader)

print(data)

[{'timestep': 0, 'pe': -6.773368053259247, 'ke': 4.498875000000003}, {'timestep': 50, 'pe

,→': -4.80824944183232, 'ke': 2.5257981827119798}, {'timestep': 100, 'pe': -4.

,→787560887558151, 'ke': 2.5062598821985103}, {'timestep': 150, 'pe': -4.747103368600548,

,→ 'ke': 2.46609592554545}, {'timestep': 200, 'pe': -4.750905285854413, 'ke': 2.

,→4701136792591694}, {'timestep': 250, 'pe': -4.777432735632181, 'ke': 2.

,→4962152903997175}]

Line Delimited JSON (LD-JSON)

The JSON format itself is very strict when it comes to delimiters. For continuous output/streaming data it is beneficial
use the line delimited JSON format. Each line represents one JSON object.

fix extra all print 50 """{"timestep": $(step), "pe": $(pe), "ke": $(ke)}""" title ""␣
,→file output.json screen no

Listing 4: output.json
{"timestep": 0, "pe": -6.77336805325924729, "ke": 4.4988750000000026219}
{"timestep": 50, "pe": -4.8082494418323200591, "ke": 2.5257981827119797558}
{"timestep": 100, "pe": -4.7875608875581505686, "ke": 2.5062598821985102582}
{"timestep": 150, "pe": -4.7471033686005483787, "ke": 2.466095925545450207}
{"timestep": 200, "pe": -4.7509052858544134068, "ke": 2.4701136792591693592}
{"timestep": 250, "pe": -4.7774327356321810711, "ke": 2.4962152903997174569}

One simple way to load this data into a Python script is to use the pandas package. It can directly load these files into
a data frame:

import pandas as pd

data = pd.read_json('output.json', lines=True)

print(data)

timestep pe ke
0 0 -6.773368 4.498875
1 50 -4.808249 2.525798
2 100 -4.787561 2.506260
3 150 -4.747103 2.466096
4 200 -4.750905 2.470114
5 250 -4.777433 2.496215

8.3. Analysis howto 233

LAMMPS Documentation, Release stable 29Sep2021

8.4 Force fields howto

8.4.1 CHARMM, AMBER, COMPASS, and DREIDING force fields

A force field has 2 parts: the formulas that define it and the coefficients used for a particular system. Here we only
discuss formulas implemented in LAMMPS that correspond to formulas commonly used in the CHARMM, AMBER,
COMPASS, and DREIDING force fields. Setting coefficients is done either from special sections in an input data file
via the read_data command or in the input script with commands like pair_coeff or bond_coeff and so on. See the
Tools doc page for additional tools that can use CHARMM, AMBER, or Materials Studio generated files to assign force
field coefficients and convert their output into LAMMPS input.
See (MacKerell) for a description of the CHARMM force field. See (Cornell) for a description of the AMBER force
field. See (Sun) for a description of the COMPASS force field.
The interaction styles listed below compute force field formulas that are consistent with common options in CHARMM
or AMBER. See each command’s documentation for the formula it computes.
• bond_style harmonic
• angle_style charmm
• dihedral_style charmmfsh
• dihedral_style charmm
• pair_style lj/charmmfsw/coul/charmmfsh
• pair_style lj/charmmfsw/coul/long
• pair_style lj/charmm/coul/charmm
• pair_style lj/charmm/coul/charmm/implicit
• pair_style lj/charmm/coul/long
• special_bonds charmm
• special_bonds amber

Note: For CHARMM, newer charmmfsw or charmmfsh styles were released in March 2017. We recommend they be
used instead of the older charmm styles. See discussion of the differences on the pair charmm and dihedral charmm
doc pages.

COMPASS is a general force field for atomistic simulation of common organic molecules, inorganic small molecules,
and polymers which was developed using ab initio and empirical parameterization techniques. See the Tools page for
the msi2lmp tool for creating LAMMPS template input and data files from BIOVIA’s Materials Studio files. Please
note that the msi2lmp tool is very old and largely unmaintained, so it does not support all features of Materials Studio
provided force field files, especially additions during the last decade. You should watch the output carefully and compare
results, where possible. See (Sun) for a description of the COMPASS force field.
These interaction styles listed below compute force field formulas that are consistent with the COMPASS force field.
See each command’s documentation for the formula it computes.
• bond_style class2
• angle_style class2
• dihedral_style class2
• improper_style class2

234 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

• pair_style lj/class2
• pair_style lj/class2/coul/cut
• pair_style lj/class2/coul/long
• special_bonds lj/coul 0 0 1
DREIDING is a generic force field developed by the Goddard group at Caltech and is useful for predicting structures
and dynamics of organic, biological and main-group inorganic molecules. The philosophy in DREIDING is to use
general force constants and geometry parameters based on simple hybridization considerations, rather than individual
force constants and geometric parameters that depend on the particular combinations of atoms involved in the bond,
angle, or torsion terms. DREIDING has an explicit hydrogen bond term to describe interactions involving a hydrogen
atom on very electronegative atoms (N, O, F).
See (Mayo) for a description of the DREIDING force field
The interaction styles listed below compute force field formulas that are consistent with the DREIDING force field.
See each command’s documentation for the formula it computes.
• bond_style harmonic
• bond_style morse
• angle_style cosine/squared
• angle_style harmonic
• angle_style cosine
• angle_style cosine/periodic
• dihedral_style charmm
• improper_style umbrella
• pair_style buck
• pair_style buck/coul/cut
• pair_style buck/coul/long
• pair_style lj/cut
• pair_style lj/cut/coul/cut
• pair_style lj/cut/coul/long
• pair_style hbond/dreiding/lj
• pair_style hbond/dreiding/morse
• special_bonds dreiding

(MacKerell) MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al, J Phys Chem,
102, 3586 (1998).
(Cornell) Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197
(1995).
(Sun) Sun, J. Phys. Chem. B, 102, 7338-7364 (1998).
(Mayo) Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909 (1990).

8.4. Force fields howto 235

LAMMPS Documentation, Release stable 29Sep2021

8.4.2 TIP3P water model

The TIP3P water model as implemented in CHARMM (MacKerell) specifies a 3-site rigid water molecule with charges
and Lennard-Jones parameters assigned to each of the 3 atoms. In LAMMPS the fix shake command can be used to
hold the two O-H bonds and the H-O-H angle rigid. A bond style of harmonic and an angle style of harmonic or
charmm should also be used.
These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid TIP3P-
CHARMM model with a cutoff. The K values can be used if a flexible TIP3P model (without fix shake) is desired. If
the LJ epsilon and sigma for HH and OH are set to 0.0, it corresponds to the original 1983 TIP3P model (Jorgensen).

O mass = 15.9994
H mass = 1.008
O charge = -0.834
H charge = 0.417
LJ  of OO = 0.1521
LJ σ of OO = 3.1507
LJ  of HH = 0.0460
LJ σ of HH = 0.4000
LJ  of OH = 0.0836
LJ σ of OH = 1.7753
K of OH bond = 450
r0 of OH bond = 0.9572
K of HOH angle = 55
θ of HOH angle = 104.52◦

These are the parameters to use for TIP3P with a long-range Coulomb solver (e.g. Ewald or PPPM in LAMMPS), see
(Price) for details:

O mass = 15.9994
H mass = 1.008
O charge = -0.830
H charge = 0.415
LJ  of OO = 0.102
LJ σ of OO = 3.188
LJ , σ of OH, HH = 0.0
K of OH bond = 450
r0 of OH bond = 0.9572
K of HOH angle = 55
θ of HOH angle = 104.52◦

Wikipedia also has a nice article on water models.

236 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

(MacKerell) MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al, J Phys Chem,
102, 3586 (1998).
(Jorgensen) Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem Phys, 79, 926 (1983).
(Price) Price and Brooks, J Chem Phys, 121, 10096 (2004).

8.4.3 TIP4P water model

The four-point TIP4P rigid water model extends the traditional three-point TIP3P model by adding an additional site,
usually massless, where the charge associated with the oxygen atom is placed. This site M is located at a fixed distance
away from the oxygen along the bisector of the HOH bond angle. A bond style of harmonic and an angle style of
harmonic or charmm should also be used.
A TIP4P model is run with LAMMPS using either this command for a cutoff model:
• pair_style lj/cut/tip4p/cut
or these two commands for a long-range model:
• pair_style lj/cut/tip4p/long
• kspace_style pppm/tip4p
For both models, the bond lengths and bond angles should be held fixed using the fix shake command.
These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid TIP4P
model with a cutoff (Jorgensen). Note that the OM distance is specified in the pair_style command, not as part of the
pair coefficients.

O mass = 15.9994
H mass = 1.008
O charge = -1.040
H charge = 0.520
r0 of OH bond = 0.9572
θ of HOH angle = 104.52◦
OM distance = 0.15
LJ  of O-O = 0.1550
LJ σ of O-O = 3.1536
LJ , σ of OH, HH = 0.0
Coulomb cutoff = 8.5

For the TIP4/Ice model (J Chem Phys, 122, 234511 (2005); https://doi.org/10.1063/1.1931662) these values can be
used:

O mass = 15.9994
H mass = 1.008
O charge = -1.1794
H charge = 0.5897
r0 of OH bond = 0.9572
θ of HOH angle = 104.52◦

8.4. Force fields howto 237

LAMMPS Documentation, Release stable 29Sep2021

OM distance = 0.1577
LJ  of O-O = 0.21084
LJ σ of O-O = 3.1668
LJ , σ of OH, HH = 0.0
Coulomb cutoff = 8.5

For the TIP4P/2005 model (J Chem Phys, 123, 234505 (2005); https://doi.org/10.1063/1.2121687), these values can
be used:

O mass = 15.9994
H mass = 1.008
O charge = -1.1128
H charge = 0.5564
r0 of OH bond = 0.9572
θ of HOH angle = 104.52◦
OM distance = 0.1546
LJ  of O-O = 0.1852
LJ σ of O-O = 3.1589
LJ , σ of OH, HH = 0.0
Coulomb cutoff = 8.5

These are the parameters to use for TIP4P with a long-range Coulombic solver (e.g. Ewald or PPPM in LAMMPS):

O mass = 15.9994
H mass = 1.008
O charge = -1.0484
H charge = 0.5242
r0 of OH bond = 0.9572
θ of HOH angle = 104.52◦
OM distance = 0.1250
LJ  of O-O = 0.16275
LJ σ of O-O = 3.16435
LJ , σ of OH, HH = 0.0

Note that the when using the TIP4P pair style, the neighbor list cutoff for Coulomb interactions is effectively extended by
a distance 2 * (OM distance), to account for the offset distance of the fictitious charges on O atoms in water molecules.
Thus it is typically best in an efficiency sense to use a LJ cutoff >= Coulomb cutoff + 2*(OM distance), to shrink the
size of the neighbor list. This leads to slightly larger cost for the long-range calculation, so you can test the trade-off for
your model. The OM distance and the LJ and Coulombic cutoffs are set in the pair_style lj/cut/tip4p/long command.
Wikipedia also has a nice article on water models.

238 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

(Jorgensen) Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem Phys, 79, 926 (1983).

8.4.4 SPC water model

The SPC water model specifies a 3-site rigid water molecule with charges and Lennard-Jones parameters assigned to
each of the 3 atoms. In LAMMPS the fix shake command can be used to hold the two O-H bonds and the H-O-H angle
rigid. A bond style of harmonic and an angle style of harmonic or charmm should also be used.
These are the additional parameters (in real units) to set for O and H atoms and the water molecule to run a rigid SPC
model.

O mass = 15.9994
H mass = 1.008
O charge = -0.820
H charge = 0.410
LJ  of OO = 0.1553
LJ σ of OO = 3.166
LJ , σ of OH, HH = 0.0
r0 of OH bond = 1.0
θ of HOH angle = 109.47◦

Note that as originally proposed, the SPC model was run with a 9 Angstrom cutoff for both LJ and Coulomb terms. It
can also be used with long-range electrostatic solvers (e.g. Ewald or PPPM in LAMMPS) without changing any of the
parameters above, although it becomes a different model in that mode of usage.
The SPC/E (extended) water model is the same, except the partial charge assignments change:

O charge = -0.8476
H charge = 0.4238

See the (Berendsen) reference for more details on both the SPC and SPC/E models.
Wikipedia also has a nice article on water models.

(Berendsen) Berendsen, Grigera, Straatsma, J Phys Chem, 91, 6269-6271 (1987).

8.4. Force fields howto 239

LAMMPS Documentation, Release stable 29Sep2021

8.5 Packages howto

8.5.1 Finite-size spherical and aspherical particles

Typical MD models treat atoms or particles as point masses. Sometimes it is desirable to have a model with finite-size
particles such as spheroids or ellipsoids or generalized aspherical bodies. The difference is that such particles have a
moment of inertia, rotational energy, and angular momentum. Rotation is induced by torque coming from interactions
with other particles.
LAMMPS has several options for running simulations with these kinds of particles. The following aspects are discussed
in turn:
• atom styles
• pair potentials
• time integration
• computes, thermodynamics, and dump output
• rigid bodies composed of finite-size particles
Example input scripts for these kinds of models are in the body, colloid, dipole, ellipse, line, peri, pour, and tri direc-
tories of the examples directory in the LAMMPS distribution.

Atom styles

There are several atom styles that allow for definition of finite-size particles: sphere, dipole, ellipsoid, line, tri, peri,
and body.
The sphere style defines particles that are spheroids and each particle can have a unique diameter and mass (or density).
These particles store an angular velocity (omega) and can be acted upon by torque. The “set” command can be used to
modify the diameter and mass of individual particles, after then are created.
The dipole style does not actually define finite-size particles, but is often used in conjunction with spherical particles,
via a command like

atom_style hybrid sphere dipole

This is because when dipoles interact with each other, they induce torques, and a particle must be finite-size (i.e. have a
moment of inertia) in order to respond and rotate. See the atom_style dipole command for details. The “set” command
can be used to modify the orientation and length of the dipole moment of individual particles, after then are created.
The ellipsoid style defines particles that are ellipsoids and thus can be aspherical. Each particle has a shape, specified
by 3 diameters, and mass (or density). These particles store an angular momentum and their orientation (quaternion),
and can be acted upon by torque. They do not store an angular velocity (omega), which can be in a different direction
than angular momentum, rather they compute it as needed. The “set” command can be used to modify the diameter,
orientation, and mass of individual particles, after then are created. It also has a brief explanation of what quaternions
are.
The line style defines line segment particles with two end points and a mass (or density). They can be used in 2d
simulations, and they can be joined together to form rigid bodies which represent arbitrary polygons.
The tri style defines triangular particles with three corner points and a mass (or density). They can be used in 3d
simulations, and they can be joined together to form rigid bodies which represent arbitrary particles with a triangulated
surface.
The peri style is used with Peridynamic models and defines particles as having a volume, that is used internally in the
pair_style peri potentials.

240 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

The body style allows for definition of particles which can represent complex entities, such as surface meshes of discrete
points, collections of sub-particles, deformable objects, etc. The body style is discussed in more detail on the Howto
body doc page.
Note that if one of these atom styles is used (or multiple styles via the atom_style hybrid command), not all particles
in the system are required to be finite-size or aspherical.
For example, in the ellipsoid style, if the 3 shape parameters are set to the same value, the particle will be a sphere
rather than an ellipsoid. If the 3 shape parameters are all set to 0.0 or if the diameter is set to 0.0, it will be a point
particle. In the line or tri style, if the lineflag or triflag is specified as 0, then it will be a point particle.
Some of the pair styles used to compute pairwise interactions between finite-size particles also compute the correct
interaction with point particles as well, e.g. the interaction between a point particle and a finite-size particle or between
two point particles. If necessary, pair_style hybrid can be used to insure the correct interactions are computed for
the appropriate style of interactions. Likewise, using groups to partition particles (ellipsoids versus spheres versus
point particles) will allow you to use the appropriate time integrators and temperature computations for each class of
particles. See the doc pages for various commands for details.
Also note that for 2d simulations, atom styles sphere and ellipsoid still use 3d particles, rather than as circular disks
or ellipses. This means they have the same moment of inertia as the 3d object. When temperature is computed, the
correct degrees of freedom are used for rotation in a 2d versus 3d system.

Pair potentials

When a system with finite-size particles is defined, the particles will only rotate and experience torque if the force field
computes such interactions. These are the various pair styles that generate torque:
• pair_style gran/history
• pair_style gran/hertz
• pair_style gran/no_history
• pair_style dipole/cut
• pair_style gayberne
• pair_style resquared
• pair_style brownian
• pair_style lubricate
• pair_style line/lj
• pair_style tri/lj
• pair_style body/nparticle
The granular pair styles are used with spherical particles. The dipole pair style is used with the dipole atom style,
which could be applied to spherical or ellipsoidal particles. The GayBerne and REsquared potentials require ellipsoidal
particles, though they will also work if the 3 shape parameters are the same (a sphere). The Brownian and lubrication
potentials are used with spherical particles. The line, tri, and body potentials are used with line segment, triangular,
and body particles respectively.

8.5. Packages howto 241

LAMMPS Documentation, Release stable 29Sep2021

Time integration

There are several fixes that perform time integration on finite-size spherical particles, meaning the integrators update
the rotational orientation and angular velocity or angular momentum of the particles:
• fix nve/sphere
• fix nvt/sphere
• fix npt/sphere
Likewise, there are 3 fixes that perform time integration on ellipsoidal particles:
• fix nve/asphere
• fix nvt/asphere
• fix npt/asphere
The advantage of these fixes is that those which thermostat the particles include the rotational degrees of freedom in
the temperature calculation and thermostatting. The fix langevin command can also be used with its omgea or angmom
options to thermostat the rotational degrees of freedom for spherical or ellipsoidal particles. Other thermostatting fixes
only operate on the translational kinetic energy of finite-size particles.
These fixes perform constant NVE time integration on line segment, triangular, and body particles:
• fix nve/line
• fix nve/tri
• fix nve/body
Note that for mixtures of point and finite-size particles, these integration fixes can only be used with groups which
contain finite-size particles.

Computes, thermodynamics, and dump output

There are several computes that calculate the temperature or rotational energy of spherical or ellipsoidal particles:
• compute temp/sphere
• compute temp/asphere
• compute erotate/sphere
• compute erotate/asphere
These include rotational degrees of freedom in their computation. If you wish the thermodynamic output of temperature
or pressure to use one of these computes (e.g. for a system entirely composed of finite-size particles), then the compute
can be defined and the thermo_modify command used. Note that by default thermodynamic quantities will be calculated
with a temperature that only includes translational degrees of freedom. See the thermo_style command for details.
These commands can be used to output various attributes of finite-size particles:
• dump custom
• compute property/atom
• dump local
• compute body/local
Attributes include the dipole moment, the angular velocity, the angular momentum, the quaternion, the torque, the
end-point and corner-point coordinates (for line and tri particles), and sub-particle attributes of body particles.

242 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Rigid bodies composed of finite-size particles

The fix rigid command treats a collection of particles as a rigid body, computes its inertia tensor, sums the total force
and torque on the rigid body each timestep due to forces on its constituent particles, and integrates the motion of the
rigid body.
If any of the constituent particles of a rigid body are finite-size particles (spheres or ellipsoids or line segments or
triangles), then their contribution to the inertia tensor of the body is different than if they were point particles. This
means the rotational dynamics of the rigid body will be different. Thus a model of a dimer is different if the dimer
consists of two point masses versus two spheroids, even if the two particles have the same mass. Finite-size particles
that experience torque due to their interaction with other particles will also impart that torque to a rigid body they are
part of.
See the “fix rigid” command for example of complex rigid-body models it is possible to define in LAMMPS.
Note that the fix shake command can also be used to treat 2, 3, or 4 particles as a rigid body, but it always assumes the
particles are point masses.
Also note that body particles cannot be modeled with the fix rigid command. Body particles are treated by LAMMPS
as single particles, though they can store internal state, such as a list of sub-particles. Individual body particles are
typically treated as rigid bodies, and their motion integrated with a command like fix nve/body. Interactions between
pairs of body particles are computed via a command like pair_style body/nparticle.

8.5.2 Granular models

Granular system are composed of spherical particles with a diameter, as opposed to point particles. This means they
have an angular velocity and torque can be imparted to them to cause them to rotate.
To run a simulation of a granular model, you will want to use the following commands:
• atom_style sphere
• fix nve/sphere
• fix gravity
This compute
• compute erotate/sphere
calculates rotational kinetic energy which can be output with thermodynamic info. The compute
• compute fabric
calculates various versions of the fabric tensor for granular and non-granular pair styles.
Use one of these 4 pair potentials, which compute forces and torques between interacting pairs of particles:
• pair_style gran/history
• pair_style gran/no_history
• pair_style gran/hertzian
• pair_style granular
These commands implement fix options specific to granular systems:
• fix freeze
• fix pour
• fix viscous

8.5. Packages howto 243

LAMMPS Documentation, Release stable 29Sep2021

• fix wall/gran
• fix wall/gran/region
The fix style freeze zeroes both the force and torque of frozen atoms, and should be used for granular system instead of
the fix style setforce.
For computational efficiency, you can eliminate needless pairwise computations between frozen atoms by using this
command:
• neigh_modify exclude

Note: By default, for 2d systems, granular particles are still modeled as 3d spheres, not 2d discs (circles), meaning
their moment of inertia will be the same as in 3d. If you wish to model granular particles in 2d as 2d discs, see the note
on this topic on the Howto 2d doc page, where 2d simulations are discussed.

8.5.3 Body particles

Overview:
In LAMMPS, body particles are generalized finite-size particles. Individual body particles can represent complex
entities, such as surface meshes of discrete points, collections of sub-particles, deformable objects, etc. Note that other
kinds of finite-size spherical and aspherical particles are also supported by LAMMPS, such as spheres, ellipsoids, line
segments, and triangles, but they are simpler entities than body particles. See the Howto spherical page for a general
overview of all these particle types.
Body particles are used via the atom_style body command. It takes a body style as an argument. The current body styles
supported by LAMMPS are as follows. The name in the first column is used as the bstyle argument for the atom_style
body command.

nparticle rigid body with N sub-particles

rounded/polygon 2d polygons with N vertices
rounded/polyhedron 3d polyhedra with N vertices, E edges and F faces

The body style determines what attributes are stored for each body and thus how they can be used to compute pairwise
body/body or bond/non-body (point particle) interactions. More details of each style are described below.
More styles may be added in the future. See the page on creating new body styles for details on how to add a new body
style to the code.

When to use body particles:

You should not use body particles to model a rigid body made of simpler particles (e.g. point, sphere, ellipsoid,
line segment, triangular particles), if the interaction between pairs of rigid bodies is just the summation of pairwise
interactions between the simpler particles. LAMMPS already supports this kind of model via the fix rigid command.
Any of the numerous pair styles that compute interactions between simpler particles can be used. The fix rigid command
time integrates the motion of the rigid bodies. All of the standard LAMMPS commands for thermostatting, adding
constraints, performing output, etc will operate as expected on the simple particles.
By contrast, when body particles are used, LAMMPS treats an entire body as a single particle for purposes of computing
pairwise interactions, building neighbor lists, migrating particles between processors, output of particles to a dump file,
etc. This means that interactions between pairs of bodies or between a body and non-body (point) particle need to be
encoded in an appropriate pair style. If such a pair style were to mimic the fix rigid model, it would need to loop over the
entire collection of interactions between pairs of simple particles within the two bodies, each time a single body/body
interaction was computed.

244 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Thus it only makes sense to use body particles and develop such a pair style, when particle/particle interactions are
more complex than what the fix rigid command can already calculate. For example, consider particles with one or more
of the following attributes:
• represented by a surface mesh
• represented by a collection of geometric entities (e.g. planes + spheres)
• deformable
• internal stress that induces fragmentation
For these models, the interaction between pairs of particles is likely to be more complex than the summation of simple
pairwise interactions. An example is contact or frictional forces between particles with planar surfaces that inter-
penetrate. Likewise, the body particle may store internal state, such as a stress tensor used to compute a fracture
criterion.
These are additional LAMMPS commands that can be used with body particles of different styles

fix nve/body integrate motion of a body particle in NVE ensemble

fix nvt/body ditto for NVT ensemble
fix npt/body ditto for NPT ensemble
fix nph/body ditto for NPH ensemble
compute body/local store sub-particle attributes of a body particle
compute temp/body compute temperature of body particles
dump local output sub-particle attributes of a body particle
dump image output body particle attributes as an image

The pair styles defined for use with specific body styles are listed in the sections below.

Specifics of body style nparticle:

The nparticle body style represents body particles as a rigid body with a variable number N of sub-particles. It is
provided as a vanilla, prototypical example of a body particle, although as mentioned above, the fix rigid command
already duplicates its functionality.
The atom_style body command for this body style takes two additional arguments:

atom_style body nparticle Nmin Nmax

Nmin = minimum # of sub-particles in any body in the system
Nmax = maximum # of sub-particles in any body in the system

The Nmin and Nmax arguments are used to bound the size of data structures used internally by each particle.
When the read_data command reads a data file for this body style, the following information must be provided for each
entry in the Bodies section of the data file:

atom-ID 1 M
N
ixx iyy izz ixy ixz iyz
x1 y1 z1
...
xN yN zN

where M = 6 + 3*N, and N is the number of sub-particles in the body particle.

8.5. Packages howto 245

LAMMPS Documentation, Release stable 29Sep2021

The integer line has a single value N. The floating point line(s) list 6 moments of inertia followed by the coordinates of
the N sub-particles (x1 to zN) as 3N values. These values can be listed on as many lines as you wish; see the read_data
command for more details.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the values consistent with the current orientation of the
rigid body around its center of mass. The values are with respect to the simulation box XYZ axes, not with respect to
the principal axes of the rigid body itself. LAMMPS performs the latter calculation internally. The coordinates of each
sub-particle are specified as its x,y,z displacement from the center-of-mass of the body particle. The center-of-mass
position of the particle is specified by the x,y,z values in the Atoms section of the data file, as is the total mass of the
body particle.
The pair_style body/nparticle command can be used with this body style to compute body/body and body/non-body
interactions.

Specifics of body style rounded/polygon:

The rounded/polygon body style represents body particles as a 2d polygon with a variable number of N vertices. This
style can only be used for 2d models; see the boundary command. See the “pair_style body/rounded/polygon” page
for a diagram of two squares with rounded circles at the vertices. Special cases for N = 1 (circle) and N = 2 (rod with
rounded ends) can also be specified.
One use of this body style is for 2d discrete element models, as described in Fraige.
Similar to body style nparticle, the atom_style body command for this body style takes two additional arguments:

atom_style body rounded/polygon Nmin Nmax

Nmin = minimum # of vertices in any body in the system
Nmax = maximum # of vertices in any body in the system

The Nmin and Nmax arguments are used to bound the size of data structures used internally by each particle.
When the read_data command reads a data file for this body style, the following information must be provided for each
body in the Bodies section of the data file:

atom-ID 1 M
N
ixx iyy izz ixy ixz iyz
x1 y1 z1
...
xN yN zN
diameter

where M = 6 + 3*N + 1, and N is the number of vertices in the body particle.

The integer line has a single value N. The floating point line(s) list 6 moments of inertia, followed by the coordinates of
the N vertices (x1 to zN) as 3N values (with z = 0.0 for each), followed by a diameter value = the rounded diameter of
the circle that surrounds each vertex. The diameter value can be different for each body particle. These floating-point
values can be listed on as many lines as you wish; see the read_data command for more details.

Note: It is important that the vertices for each polygonal body particle be listed in order around its perimeter, so that
edges can be inferred. LAMMPS does not check that this is the case.

The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the values consistent with the current orientation of the
rigid body around its center of mass. The values are with respect to the simulation box XYZ axes, not with respect to
the principal axes of the rigid body itself. LAMMPS performs the latter calculation internally. The coordinates of each

246 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

vertex are specified as its x,y,z displacement from the center-of-mass of the body particle. The center-of-mass position
of the particle is specified by the x,y,z values in the Atoms section of the data file.
For example, the following information would specify a square particle whose edge length is sqrt(2) and rounded
diameter is 1.0. The orientation of the square is aligned with the xy coordinate axes which is consistent with the 6
moments of inertia: ixx iyy izz ixy ixz iyz = 1 1 4 0 0 0. Note that only Izz matters in 2D simulations.

3 1 27
4
1 1 4 0 0 0
-0.7071 -0.7071 0
-0.7071 0.7071 0
0.7071 0.7071 0
0.7071 -0.7071 0
1.0

A rod in 2D, whose length is 4.0, mass 1.0, rounded at two ends by circles of diameter 0.5, is specified as follows:

1 1 13
2
1 1 1.33333 0 0 0
-2 0 0
2 0 0
0.5

A disk, whose diameter is 3.0, mass 1.0, is specified as follows:

1 1 10
1
1 1 4.5 0 0 0
0 0 0
3.0

The pair_style body/rounded/polygon command can be used with this body style to compute body/body interactions.
The fix wall/body/polygon command can be used with this body style to compute the interaction of body particles with
a wall.

Specifics of body style rounded/polyhedron:

The rounded/polyhedron body style represents body particles as a 3d polyhedron with a variable number of N vertices,
E edges and F faces. This style can only be used for 3d models; see the boundary command. See the “pair_style
body/rounded/polygon” page for a diagram of a two 2d squares with rounded circles at the vertices. A 3d cube with
rounded spheres at the 8 vertices and 12 rounded edges would be similar. Special cases for N = 1 (sphere) and N = 2
(rod with rounded ends) can also be specified.
This body style is for 3d discrete element models, as described in Wang.
Similar to body style rounded/polygon, the atom_style body command for this body style takes two additional argu-
ments:

atom_style body rounded/polyhedron Nmin Nmax

Nmin = minimum # of vertices in any body in the system
Nmax = maximum # of vertices in any body in the system

The Nmin and Nmax arguments are used to bound the size of data structures used internally by each particle.

8.5. Packages howto 247

LAMMPS Documentation, Release stable 29Sep2021

When the read_data command reads a data file for this body style, the following information must be provided for each
entry in the Bodies section of the data file:

atom-ID 3 M
N E F
ixx iyy izz ixy ixz iyz
x1 y1 z1
...
xN yN zN
0 1
1 2
2 3
...
0 1 2 -1
0 2 3 -1
...
1 2 3 4
diameter

where M = 6 + 3*N + 2*E + 4*F + 1, and N is the number of vertices in the body particle, E = number of edges, F =
number of faces. For N = 1 or 2, the format is simpler. E and F are ignored and no edges or faces are listed, so that M
= 6 + 3*N + 1.
The integer line has three values: number of vertices (N), number of edges (E) and number of faces (F). The floating
point line(s) list 6 moments of inertia followed by the coordinates of the N vertices (x1 to zN) as 3N values, followed
by 2N vertex indices corresponding to the end points of the E edges, then 4*F vertex indices defining F faces. The
last value is the diameter value = the rounded diameter of the sphere that surrounds each vertex. The diameter value
can be different for each body particle. These floating-point values can be listed on as many lines as you wish; see the
read_data command for more details.
Note that vertices are numbered from 0 to N-1 inclusive. The order of the 2 vertices in each edge does not matter. Faces
can be triangles or quadrilaterals. In both cases 4 vertices must be specified. For a triangle the 4th vertex is -1. The
4 vertices within each triangle or quadrilateral face should be ordered by the right-hand rule so that the normal vector
of the face points outwards from the center of mass. For polyhedron with faces with more than 4 vertices, you should
split the complex face into multiple simple faces, each of which is a triangle or quadrilateral.

Note: If a face is a quadrilateral then its 4 vertices must be co-planar. LAMMPS does not check that this is the case.
If you have a quad-face of a polyhedron that is not planar (e.g. a cube whose vertices have been randomly displaced),
then you should represent the single quad face as two triangle faces instead.

The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the values consistent with the current orientation of the
rigid body around its center of mass. The values are with respect to the simulation box XYZ axes, not with respect to
the principal axes of the rigid body itself. LAMMPS performs the latter calculation internally. The coordinates of each
vertex are specified as its x,y,z displacement from the center-of-mass of the body particle. The center-of-mass position
of the particle is specified by the x,y,z values in the Atoms section of the data file.
For example, the following information would specify a cubic particle whose edge length is 2.0 and rounded diameter
is 0.5. The orientation of the cube is aligned with the xyz coordinate axes which is consistent with the 6 moments of
inertia: ixx iyy izz ixy ixz iyz = 0.667 0.667 0.667 0 0 0.

1 3 79
8 12 6
0.667 0.667 0.667 0 0 0
1 1 1
(continues on next page)

248 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

1 -1 1
-1 -1 1
-1 1 1
1 1 -1
1 -1 -1
-1 -1 -1
-1 1 -1
0 1
1 2
2 3
3 0
4 5
5 6
6 7
7 4
0 4
1 5
2 6
3 7
0 1 2 3
4 5 6 7
0 1 5 4
1 2 6 5
2 3 7 6
3 0 4 7
0.5

A rod in 3D, whose length is 4.0, mass 1.0 and rounded at two ends by circles of diameter 0.5, is specified as follows:

1 3 13
2 1 1
0 1.33333 1.33333 0 0 0
-2 0 0
2 0 0
0.5

A sphere whose diameter is 3.0 and mass 1.0, is specified as follows:

1 3 10
1 1 1
0.9 0.9 0.9 0 0 0
0 0 0
3.0

The number of edges and faces for a rod or sphere must be listed, but is ignored.
The pair_style body/rounded/polhedron command can be used with this body style to compute body/body interactions.
The fix wall/body/polyhedron command can be used with this body style to compute the interaction of body particles
with a wall.

Output specifics for all body styles:

For the compute body/local and dump local commands, all 3 of the body styles described on his page produces one
datum for each of the N vertices (of sub-particles) in a body particle. The datum has 3 values:

8.5. Packages howto 249

LAMMPS Documentation, Release stable 29Sep2021

1 = x position of vertex (or sub-particle)

2 = y position of vertex
3 = z position of vertex

These values are the current position of the vertex within the simulation domain, not a displacement from the center-
of-mass (COM) of the body particle itself. These values are calculated using the current COM and orientation of the
body particle.
The dump image command and its body keyword can be used to render body particles.
For the nparticle body style, each body is drawn as a collection of spheres, one for each sub-particle. The size of each
sphere is determined by the bflag1 parameter for the body keyword. The bflag2 argument is ignored.
For the rounded/polygon body style, each body is drawn as a polygon with N line segments. For the rounded/polyhedron
body style, each face of each body is drawn as a polygon with N line segments. The drawn diameter of each line segment
is determined by the bflag1 parameter for the body keyword. The bflag2 argument is ignored.
Note that for both the rounded/polygon and rounded/polyhedron styles, line segments are drawn between the pairs of
vertices. Depending on the diameters of the line segments this may be slightly different than the physical extent of the
body as calculated by the pair_style rounded/polygon or pair_style rounded/polyhedron commands. Conceptually, the
pair styles define the surface of a 2d or 3d body by lines or planes that are tangent to the finite-size spheres of specified
diameter which are placed on each vertex position.

(Fraige) F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds, Particuology, 6, 455 (2008).

(Wang) J. Wang, H. S. Yu, P. A. Langston, F. Y. Fraige, Granular Matter, 13, 1 (2011).

8.5.4 Polarizable models

In polarizable force fields the charge distributions in molecules and materials respond to their electrostatic environ-
ments. Polarizable systems can be simulated in LAMMPS using three methods:
• the fluctuating charge method, implemented in the QEQ package,
• the adiabatic core-shell method, implemented in the CORESHELL package,
• the thermalized Drude dipole method, implemented in the DRUDE package.
The fluctuating charge method calculates instantaneous charges on interacting atoms based on the electronegativity
equalization principle. It is implemented in the fix qeq which is available in several variants. It is a relatively efficient
technique since no additional particles are introduced. This method allows for charge transfer between molecules or
atom groups. However, because the charges are located at the interaction sites, off-plane components of polarization
cannot be represented in planar molecules or atom groups.
The two other methods share the same basic idea: polarizable atoms are split into one core atom and one satellite
particle (called shell or Drude particle) attached to it by a harmonic spring. Both atoms bear a charge and they represent
collectively an induced electric dipole. These techniques are computationally more expensive than the QEq method
because of additional particles and bonds. These two charge-on-spring methods differ in certain features, with the
core-shell model being normally used for ionic/crystalline materials, whereas the so-called Drude model is normally
used for molecular systems and fluid states.
The core-shell model is applicable to crystalline materials where the high symmetry around each site leads to stable
trajectories of the core-shell pairs. However, bonded atoms in molecules can be so close that a core would interact too
strongly or even capture the Drude particle of a neighbor. The Drude dipole model is relatively more complex in order
to remedy this and other issues. Specifically, the Drude model includes specific thermostatting of the core-Drude pairs
and short-range damping of the induced dipoles.

250 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

The three polarization methods can be implemented through a self-consistent calculation of charges or induced dipoles
at each timestep. In the fluctuating charge scheme this is done by the matrix inversion method in fix qeq/point, but
for core-shell or Drude-dipoles the relaxed-dipoles technique would require an slow iterative procedure. These self-
consistent solutions yield accurate trajectories since the additional degrees of freedom representing polarization are
massless. An alternative is to attribute a mass to the additional degrees of freedom and perform time integration using
an extended Lagrangian technique. For the fluctuating charge scheme this is done by fix qeq/dynamic, and for the
charge-on-spring models by the methods outlined in the next two sections. The assignment of masses to the additional
degrees of freedom can lead to unphysical trajectories if care is not exerted in choosing the parameters of the polarizable
models and the simulation conditions.
In the core-shell model the vibration of the shells is kept faster than the ionic vibrations to mimic the fast response of
the polarizable electrons. But in molecular systems thermalizing the core-Drude pairs at temperatures comparable to
the rest of the simulation leads to several problems (kinetic energy transfer, too short a timestep, etc.) In order to avoid
these problems the relative motion of the Drude particles with respect to their cores is kept “cold” so the vibration of
the core-Drude pairs is very slow, approaching the self-consistent regime. In both models the temperature is regulated
using the velocities of the center of mass of core+shell (or Drude) pairs, but in the Drude model the actual relative
core-Drude particle motion is thermostatted separately as well.

8.5.5 Adiabatic core/shell model

The adiabatic core-shell model by Mitchell and Fincham is a simple method for adding polarizability to a system. In
order to mimic the electron shell of an ion, a satellite particle is attached to it. This way the ions are split into a core
and a shell where the latter is meant to react to the electrostatic environment inducing polarizability. See the Howto
polarizable page for a discussion of all the polarizable models available in LAMMPS.
Technically, shells are attached to the cores by a spring force f = k*r where k is a parameterized spring constant and r is
the distance between the core and the shell. The charges of the core and the shell add up to the ion charge, thus q(ion)
= q(core) + q(shell). This setup introduces the ion polarizability (alpha) given by alpha = q(shell)^2 / k. In a similar
fashion the mass of the ion is distributed on the core and the shell with the core having the larger mass.
To run this model in LAMMPS, atom_style full can be used since atom charge and bonds are needed. Each kind of
core/shell pair requires two atom types and a bond type. The core and shell of a core/shell pair should be bonded
to each other with a harmonic bond that provides the spring force. For example, a data file for NaCl, as found in
examples/coreshell, has this format:

432 atoms # core and shell atoms

216 bonds # number of core/shell springs

4 atom types # 2 cores and 2 shells for Na and Cl

2 bond types

0.0 24.09597 xlo xhi

0.0 24.09597 ylo yhi
0.0 24.09597 zlo zhi

Masses # core/shell mass ratio = 0.1

1 20.690784 # Na core
2 31.90500 # Cl core
3 2.298976 # Na shell
4 3.54500 # Cl shell

Atoms

(continues on next page)

8.5. Packages howto 251

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

1 1 2 1.5005 0.00000000 0.00000000 0.00000000 # core of core/shell pair 1
2 1 4 -2.5005 0.00000000 0.00000000 0.00000000 # shell of core/shell pair 1
3 2 1 1.5056 4.01599500 4.01599500 4.01599500 # core of core/shell pair 2
4 2 3 -0.5056 4.01599500 4.01599500 4.01599500 # shell of core/shell pair 2
(...)

Bonds # Bond topology for spring forces

1 2 1 2 # spring for core/shell pair 1

2 2 3 4 # spring for core/shell pair 2
(...)

Non-Coulombic (e.g. Lennard-Jones) pairwise interactions are only defined between the shells. Coulombic interactions
are defined between all cores and shells. If desired, additional bonds can be specified between cores.
The special_bonds command should be used to turn-off the Coulombic interaction within core/shell pairs, since that
interaction is set by the bond spring. This is done using the special_bonds command with a 1-2 weight = 0.0, which
is the default value. It needs to be considered whether one has to adjust the special_bonds weighting according to the
molecular topology since the interactions of the shells are bypassed over an extra bond.
Note that this core/shell implementation does not require all ions to be polarized. One can mix core/shell pairs and
ions without a satellite particle if desired.
Since the core/shell model permits distances of r = 0.0 between the core and shell, a pair style with a “cs” suffix
needs to be used to implement a valid long-range Coulombic correction. Several such pair styles are provided in the
CORESHELL package. See this page for details. All of the core/shell enabled pair styles require the use of a long-range
Coulombic solver, as specified by the kspace_style command. Either the PPPM or Ewald solvers can be used.
For the NaCL example problem, these pair style and bond style settings are used:

pair_style born/coul/long/cs 20.0 20.0

pair_coeff * * 0.0 1.000 0.00 0.00 0.00
pair_coeff 3 3 487.0 0.23768 0.00 1.05 0.50 #Na-Na
pair_coeff 3 4 145134.0 0.23768 0.00 6.99 8.70 #Na-Cl
pair_coeff 4 4 405774.0 0.23768 0.00 72.40 145.40 #Cl-Cl

bond_style harmonic
bond_coeff 1 63.014 0.0
bond_coeff 2 25.724 0.0

When running dynamics with the adiabatic core/shell model, the following issues should be considered. The relative
motion of the core and shell particles corresponds to the polarization, hereby an instantaneous relaxation of the shells
is approximated and a fast core/shell spring frequency ensures a nearly constant internal kinetic energy during the
simulation. Thermostats can alter this polarization behavior, by scaling the internal kinetic energy, meaning the shell
will not react freely to its electrostatic environment. Therefore it is typically desirable to decouple the relative motion
of the core/shell pair, which is an imaginary degree of freedom, from the real physical system. To do that, the compute
temp/cs command can be used, in conjunction with any of the thermostat fixes, such as fix nvt or fix langevin. This
compute uses the center-of-mass velocity of the core/shell pairs to calculate a temperature, and insures that velocity
is what is rescaled for thermostatting purposes. This compute also works for a system with both core/shell pairs and
non-polarized ions (ions without an attached satellite particle). The compute temp/cs command requires input of two
groups, one for the core atoms, another for the shell atoms. Non-polarized ions which might also be included in
the treated system should not be included into either of these groups, they are taken into account by the group-ID
(second argument) of the compute. The groups can be defined using the group *type* command. Note that to perform
thermostatting using this definition of temperature, the fix modify temp command should be used to assign the compute
to the thermostat fix. Likewise the thermo_modify temp command can be used to make this temperature be output for

252 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

the overall system.

For the NaCl example, this can be done as follows:

group cores type 1 2

group shells type 3 4
compute CSequ all temp/cs cores shells
fix thermoberendsen all temp/berendsen 1427 1427 0.4 # thermostat for the true␣
,→physical system

fix thermostatequ all nve # integrator as needed for the␣

,→berendsen thermostat

fix_modify thermoberendsen temp CSequ

thermo_modify temp CSequ # output of center-of-mass␣
,→derived temperature

The pressure for the core/shell system is computed via the regular LAMMPS convention by treating the cores and shells
as individual particles. For the thermo output of the pressure as well as for the application of a barostat, it is necessary
to use an additional pressure compute based on the default temperature and specifying it as a second argument in fix
modify and thermo_modify resulting in:

(...)
compute CSequ all temp/cs cores shells
compute thermo_press_lmp all pressure thermo_temp # pressure for individual␣
,→particles

thermo_modify temp CSequ press thermo_press_lmp # modify thermo to regular␣

,→pressure

fix press_bar all npt temp 300 300 0.04 iso 0 0 0.4
fix_modify press_bar temp CSequ press thermo_press_lmp # pressure modification for␣
,→correct kinetic scalar

If compute temp/cs is used, the decoupled relative motion of the core and the shell should in theory be stable. However
numerical fluctuation can introduce a small momentum to the system, which is noticeable over long trajectories. There-
fore it is recommendable to use the fix momentum command in combination with compute temp/cs when equilibrating
the system to prevent any drift.
When initializing the velocities of a system with core/shell pairs, it is also desirable to not introduce energy into the
relative motion of the core/shell particles, but only assign a center-of-mass velocity to the pairs. This can be done
by using the bias keyword of the velocity create command and assigning the compute temp/cs command to the temp
keyword of the velocity command, e.g.

velocity all create 1427 134 bias yes temp CSequ

velocity all scale 1427 temp CSequ

To maintain the correct polarizability of the core/shell pairs, the kinetic energy of the internal motion shall remain
nearly constant. Therefore the choice of spring force and mass ratio need to ensure much faster relative motion of
the 2 atoms within the core/shell pair than their center-of-mass velocity. This allows the shells to effectively react
instantaneously to the electrostatic environment and limits energy transfer to or from the core/shell oscillators. This
fast movement also dictates the timestep that can be used.
The primary literature of the adiabatic core/shell model suggests that the fast relative motion of the core/shell pairs
only allows negligible energy transfer to the environment. The mentioned energy transfer will typically lead to a small
drift in total energy over time. This internal energy can be monitored using the compute chunk/atom and compute
temp/chunk commands. The internal kinetic energies of each core/shell pair can then be summed using the sum()
special function of the variable command. Or they can be time/averaged and output using the fix ave/time command.
To use these commands, each core/shell pair must be defined as a “chunk”. If each core/shell pair is defined as its own
molecule, the molecule ID can be used to define the chunks. If cores are bonded to each other to form larger molecules,

8.5. Packages howto 253

LAMMPS Documentation, Release stable 29Sep2021

the chunks can be identified by the fix property/atom via assigning a core/shell ID to each atom using a special field in
the data file read by the read_data command. This field can then be accessed by the compute property/atom command,
to use as input to the compute chunk/atom command to define the core/shell pairs as chunks.
For example if core/shell pairs are the only molecules:

read_data NaCl_CS_x0.1_prop.data
compute prop all property/atom molecule
compute cs_chunk all chunk/atom c_prop
compute cstherm all temp/chunk cs_chunk temp internal com yes cdof 3.0 # note the␣
,→chosen degrees of freedom for the core/shell pairs

fix ave_chunk all ave/time 10 1 10 c_cstherm file chunk.dump mode vector

For example if core/shell pairs and other molecules are present:

fix csinfo all property/atom i_CSID # property/atom command

read_data NaCl_CS_x0.1_prop.data fix csinfo NULL CS-Info # atom property added in the␣
,→data-file

compute prop all property/atom i_CSID

(...)

The additional section in the date file would be formatted like this:

CS-Info # header of additional section

1 1 # column 1 = atom ID, column 2 = core/shell ID

2 1
3 2
4 2
5 3
6 3
7 4
8 4
(...)

(Mitchell and Fincham) Mitchell, Fincham, J Phys Condensed Matter, 5, 1031-1038 (1993).
(Fincham) Fincham, Mackrodt and Mitchell, J Phys Condensed Matter, 6, 393-404 (1994).

8.5.6 Drude induced dipoles

The thermalized Drude model represents induced dipoles by a pair of charges (the core atom and the Drude particle)
connected by a harmonic spring. See the Howto polarizable doc page for a discussion of all the polarizable models
available in LAMMPS.
The Drude model has a number of features aimed at its use in molecular systems (Lamoureux and Roux):
• Thermostatting of the additional degrees of freedom associated with the induced dipoles at very low temperature,
in terms of the reduced coordinates of the Drude particles with respect to their cores. This makes the trajectory
close to that of relaxed induced dipoles.
• Consistent definition of 1-2 to 1-4 neighbors. A core-Drude particle pair represents a single (polarizable) atom,
so the special screening factors in a covalent structure should be the same for the core and the Drude particle.
Drude particles have to inherit the 1-2, 1-3, 1-4 special neighbor relations from their respective cores.

254 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

• Stabilization of the interactions between induced dipoles. Drude dipoles on covalently bonded atoms interact
too strongly due to the short distances, so an atom may capture the Drude particle of a neighbor, or the induced
dipoles within the same molecule may align too much. To avoid this, damping at short range can be done by Thole
functions (for which there are physical grounds). This Thole damping is applied to the point charges composing
the induced dipole (the charge of the Drude particle and the opposite charge on the core, not to the total charge
of the core atom).
A detailed tutorial covering the usage of Drude induced dipoles in LAMMPS is on the here.
As with the core-shell model, the cores and Drude particles should appear in the data file as standard atoms. The same
holds for the springs between them, which are described by standard harmonic bonds. The nature of the atoms (core,
Drude particle or non-polarizable) is specified via the fix drude command. The special list of neighbors is automatically
refactored to account for the equivalence of core and Drude particles as regards special 1-2 to 1-4 screening. It may
be necessary to use the extra/special/per/atom keyword of the read_data command. If using fix shake, make sure no
Drude particle is in this fix group.
There are three ways to thermostat the Drude particles at a low temperature: use either fix langevin/drude for a Langevin
thermostat, or fix drude/transform/* for a Nose-Hoover thermostat, or fix tgnvt/drude for a temperature-grouped Nose-
Hoover thermostat. The first and third require use of the command comm_modify vel yes. The second requires two
separate integration fixes like nvt or npt. The correct temperatures of the reduced degrees of freedom can be calculated
using the compute temp/drude. This requires also to use the command comm_modify vel yes.
Short-range damping of the induced dipole interactions can be achieved using Thole functions through the pair style
thole in pair_style hybrid/overlay with a Coulomb pair style. It may be useful to use coul/long/cs or similar from the
CORESHELL package if the core and Drude particle come too close, which can cause numerical issues.

(Lamoureux and Roux) G. Lamoureux, B. Roux, J. Chem. Phys 119, 3025 (2003)

8.5.7 Tutorial for Thermalized Drude oscillators in LAMMPS

This tutorial explains how to use Drude oscillators in LAMMPS to simulate polarizable systems using the DRUDE
package. As an illustration, the input files for a simulation of 250 phenol molecules are documented. First of all,
LAMMPS has to be compiled with the DRUDE package activated. Then, the data file and input scripts have to be
modified to include the Drude dipoles and how to handle them.
Example input scripts available: examples/PACKAGES/drude

Overview of Drude induced dipoles

Polarizable atoms acquire an induced electric dipole moment under the action of an external electric field, for example
the electric field created by the surrounding particles. Drude oscillators represent these dipoles by two fixed charges:
the core (DC) and the Drude particle (DP) bound by a harmonic potential. The Drude particle can be thought of as the
electron cloud whose center can be displaced from the position of the corresponding nucleus.
The sum of the masses of a core-Drude pair should be the mass of the initial (unsplit) atom, mC + mD = m. The sum
of their charges should be the charge of the initial (unsplit) atom, qC + qD = q. A harmonic potential between the core
and Drude partners should be present, with force constant kD and an equilibrium distance of zero. The (half-)stiffness
of the harmonic bond KD = kD /2 and the Drude charge qD are related to the atom polarizability α by
2
1 qD
KD =
2 α
Ideally, the mass of the Drude particle should be small, and the stiffness of the harmonic bond should be large, so that
the Drude particle remains close to the core. The values of Drude mass, Drude charge, and force constant can be chosen
following different strategies, as in the following examples of polarizable force fields:

8.5. Packages howto 255

LAMMPS Documentation, Release stable 29Sep2021

• Lamoureux and Roux suggest adopting a global half-stiffness, KD = 500 kcal/(mol Ang 2 ) - which corresponds
to a force constant kD = 4184 kJ/(mol Ang 2 ) - for all types of core-Drude bond, a global mass mD = 0.4 g/mol
(or u) for all types of Drude particles, and to calculate the Drude charges for individual atom types from the atom
polarizabilities using equation (1). This choice is followed in the polarizable CHARMM force field.
• Alternately Schroeder and Steinhauser suggest adopting a global charge qD = -1.0e and a global mass mD = 0.1
g/mol (or u) for all Drude particles, and to calculate the force constant for each type of core-Drude bond from
equation (1). The timesteps used by these authors are between 0.5 and 2 fs, with the degrees of freedom of the
Drude oscillators kept cold at 1 K.
• In both these force fields hydrogen atoms are treated as non-polarizable.
The motion of of the Drude particles can be calculated by minimizing the energy of the induced dipoles at each timestep,
by an iterative, self-consistent procedure. The Drude particles can be massless and therefore do not contribute to the
kinetic energy. However, the relaxed method is computational slow. An extended-lagrangian method can be used to
calculate the positions of the Drude particles, but this requires them to have mass. It is important in this case to decouple
the degrees of freedom associated with the Drude oscillators from those of the normal atoms. Thermalizing the Drude
dipoles at temperatures comparable to the rest of the simulation leads to several problems (kinetic energy transfer, very
short timestep, etc.), which can be remedied by the “cold Drude” technique (Lamoureux and Roux).
Two closely related models are used to represent polarization through “charges on a spring”: the core-shell model
and the Drude model. Although the basic idea is the same, the core-shell model is normally used for ionic/crystalline
materials, whereas the Drude model is normally used for molecular systems and fluid states. In ionic crystals the
symmetry around each ion and the distance between them are such that the core-shell model is sufficiently stable. But
to be applicable to molecular/covalent systems the Drude model includes two important features:
1. The possibility to thermostat the additional degrees of freedom associated with the induced dipoles at very low
temperature, in terms of the reduced coordinates of the Drude particles with respect to their cores. This makes
the trajectory close to that of relaxed induced dipoles.
2. The Drude dipoles on covalently bonded atoms interact too strongly due to the short distances, so an atom may
capture the Drude particle (shell) of a neighbor, or the induced dipoles within the same molecule may align
too much. To avoid this, damping at short of the interactions between the point charges composing the induced
dipole can be done by Thole functions.

Preparation of the data file

The data file is similar to a standard LAMMPS data file for atom_style full. The DPs and the harmonic bonds connecting
them to their DC should appear in the data file as normal atoms and bonds.
You can use the polarizer tool (Python script distributed with the DRUDE package) to convert a non-polarizable data
file (here data.102494.lmp) to a polarizable data file (data-p.lmp)
polarizer -q -f phenol.dff data.102494.lmp data-p.lmp

This will automatically insert the new atoms and bonds. The masses and charges of DCs and DPs are computed from
phenol.dff, as well as the DC-DP bond constants. The file phenol.dff contains the polarizabilities of the atom types and
the mass of the Drude particles, for instance:
# units: kJ/mol, A, deg
# kforce is in the form k/2 r_D^2
# type m_D/u q_D/e k_D alpha/A3 thole
OH 0.4 -1.0 4184.0 0.63 0.67
CA 0.4 -1.0 4184.0 1.36 2.51
CAI 0.4 -1.0 4184.0 1.09 2.51
The hydrogen atoms are absent from this file, so they will be treated as non-polarizable atoms. In the non-polarizable
data file data.102494.lmp, atom names corresponding to the atom type numbers have to be specified as comments at
the end of lines of the Masses section. You probably need to edit it to add these names. It should look like

256 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Masses

1 12.011 # CAI
2 12.011 # CA
3 15.999 # OH
4 1.008 # HA
5 1.008 # HO

Basic input file

The atom style should be set to (or derive from) full, so that you can define atomic charges and molecular bonds, angles,
dihedrals. . .
The polarizer tool also outputs certain lines related to the input script (the use of these lines will be explained below).
In order for LAMMPS to recognize that you are using Drude oscillators, you should use the fix drude. The command
is

fix DRUDE all drude C C C N N D D D

The N, C, D following the drude keyword have the following meaning: There is one tag for each atom type. This tag
is C for DCs, D for DPs and N for non-polarizable atoms. Here the atom types 1 to 3 (C and O atoms) are DC, atom
types 4 and 5 (H atoms) are non-polarizable and the atom types 6 to 8 are the newly created DPs.
By recognizing the fix drude, LAMMPS will find and store matching DC-DP pairs and will treat DP as equivalent to
their DC in the special bonds relations. It may be necessary to extend the space for storing such special relations. In this
case extra space should be reserved by using the extra/special/per/atom keyword of either the read_data or create_box
command. With our phenol, there is 1 more special neighbor for which space is required. Otherwise LAMMPS crashes
and gives the required value.

read_data data-p.lmp extra/special/per/atom 1

Let us assume we want to run a simple NVT simulation at 300 K. Note that Drude oscillators need to be thermalized at
a low temperature in order to approximate a self-consistent field (SCF), therefore it is not possible to simulate an NVE
ensemble with this package. Since dipoles are approximated by a charged DC-DP pair, the pair_style must include
Coulomb interactions, for instance lj/cut/coul/long with kspace_style pppm. For example, with a cutoff of 10. and a
precision 1.e-4:

pair_style lj/cut/coul/long 10.0

kspace_style pppm 1.0e-4

As compared to the non-polarizable input file, pair_coeff lines need to be added for the DPs. Since the DPs have no
Lennard-Jones interactions, their  is 0. so the only pair_coeff line that needs to be added is

pair_coeff * 6* 0.0 0.0 # All-DPs

Now for the thermalization, the simplest choice is to use the fix langevin/drude.

fix LANG all langevin/drude 300. 100 12435 1. 20 13977

This applies a Langevin thermostat at temperature 300. to the centers of mass of the DC-DP pairs, with relaxation time
100 and with random seed 12345. This fix applies also a Langevin thermostat at temperature 1. to the relative motion
of the DPs around their DCs, with relaxation time 20 and random seed 13977. Only the DCs and non-polarizable atoms
need to be in this fix’s group. LAMMPS will thermostat the DPs together with their DC. For this, ghost atoms need to
know their velocities. Thus you need to add the following command:

8.5. Packages howto 257

LAMMPS Documentation, Release stable 29Sep2021

comm_modify vel yes

In order to avoid that the center of mass of the whole system drifts due to the random forces of the Langevin thermostat
on DCs, you can add the zero yes option at the end of the fix line.
If the fix shake is used to constrain the C-H bonds, it should be invoked after the fix langevin/drude for more accuracy.

fix SHAKE ATOMS shake 0.0001 20 0 t 4 5

Note: The group of the fix shake must not include the DPs. If the group ATOMS is defined by non-DPs atom types,
you could use

Since the fix langevin/drude does not perform time integration (just modification of forces but no position/velocity
updates), the fix nve should be used in conjunction.

fix NVE all nve

To avoid the flying ice cube artifact, where the atoms progressively freeze and the center of mass of the whole system
drifts faster and faster, the fix momentum can be used. For instance:

fix MOMENTUM all momentum 100 linear 1 1 1

Finally, do not forget to update the atom type elements if you use them in a dump_modify . . . element . . . command,
by adding the element type of the DPs. Here for instance

dump DUMP all custom 10 dump.lammpstrj id mol type element x y z ix iy iz

dump_modify DUMP element C C O H H D D D

The input file should now be ready for use!

You will notice that the global temperature thermo_temp computed by LAMMPS is not 300. K as wanted. This is
because LAMMPS treats DPs as standard atoms in his default compute. If you want to output the temperatures of the
DC-DP pair centers of mass and of the DPs relative to their DCs, you should use the compute temp_drude

compute TDRUDE all temp/drude

And then output the correct temperatures of the Drude oscillators using thermo_style custom with respectively
c_TDRUDE[1] and c_TDRUDE[2]. These should be close to 300.0 and 1.0 on average.

thermo_style custom step temp c_TDRUDE[1] c_TDRUDE[2]

Thole screening
Dipolar interactions represented by point charges on springs may not be stable, for example if the atomic polarizability
is too high for instance, a DP can escape from its DC and be captured by another DC, which makes the force and energy
diverge and the simulation crash. Even without reaching this extreme case, the correlation between nearby dipoles on
the same molecule may be exaggerated. Often, special bond relations prevent bonded neighboring atoms to see the
charge of each other’s DP, so that the problem does not always appear. It is possible to use screened dipole-dipole
interactions by using the *pair_style thole*. This is implemented as a correction to the Coulomb pair_styles, which
dampens at short distance the interactions between the charges representing the induced dipoles. It is to be used as
hybrid/overlay with any standard coul pair style. In our example, we would use

258 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

pair_style hybrid/overlay lj/cut/coul/long 10.0 thole 2.6 10.0

This tells LAMMPS that we are using two pair_styles. The first one is as above (lj/cut/coul/long 10.0). The second one
is a thole pair_style with default screening factor 2.6 (Noskov) and cutoff 10.0.
Since hybrid/overlay does not support mixing rules, the interaction coefficients of all the pairs of atom types with i <
j should be explicitly defined. The output of the polarizer script can be used to complete the pair_coeff section of the
input file. In our example, this will look like:

pair_coeff 1 1 lj/cut/coul/long 0.0700 3.550

pair_coeff 1 2 lj/cut/coul/long 0.0700 3.550
pair_coeff 1 3 lj/cut/coul/long 0.1091 3.310
pair_coeff 1 4 lj/cut/coul/long 0.0458 2.985
pair_coeff 2 2 lj/cut/coul/long 0.0700 3.550
pair_coeff 2 3 lj/cut/coul/long 0.1091 3.310
pair_coeff 2 4 lj/cut/coul/long 0.0458 2.985
pair_coeff 3 3 lj/cut/coul/long 0.1700 3.070
pair_coeff 3 4 lj/cut/coul/long 0.0714 2.745
pair_coeff 4 4 lj/cut/coul/long 0.0300 2.420
pair_coeff * 5 lj/cut/coul/long 0.0000 0.000
pair_coeff * 6* lj/cut/coul/long 0.0000 0.000
pair_coeff 1 1 thole 1.090 2.510
pair_coeff 1 2 thole 1.218 2.510
pair_coeff 1 3 thole 0.829 1.590
pair_coeff 1 6 thole 1.090 2.510
pair_coeff 1 7 thole 1.218 2.510
pair_coeff 1 8 thole 0.829 1.590
pair_coeff 2 2 thole 1.360 2.510
pair_coeff 2 3 thole 0.926 1.590
pair_coeff 2 6 thole 1.218 2.510
pair_coeff 2 7 thole 1.360 2.510
pair_coeff 2 8 thole 0.926 1.590
pair_coeff 3 3 thole 0.630 0.670
pair_coeff 3 6 thole 0.829 1.590
pair_coeff 3 7 thole 0.926 1.590
pair_coeff 3 8 thole 0.630 0.670
pair_coeff 6 6 thole 1.090 2.510
pair_coeff 6 7 thole 1.218 2.510
pair_coeff 6 8 thole 0.829 1.590
pair_coeff 7 7 thole 1.360 2.510
pair_coeff 7 8 thole 0.926 1.590
pair_coeff 8 8 thole 0.630 0.670

For the thole pair style the coefficients are

1. the atom polarizability in units of cubic length
2. the screening factor of the Thole function (optional, default value specified by the pair_style command)
3. the cutoff (optional, default value defined by the pair_style command)
The special neighbors have charge-charge and charge-dipole interactions screened by the coul factors of the spe-
cial_bonds command (0.0, 0.0, and 0.5 in the example above). Without using the pair_style thole, dipole-dipole in-
teractions are screened by the same factor. By using the pair_style thole, dipole-dipole interactions are screened by
Thole’s function, whatever their special relationship (except within each DC-DP pair of course). Consider for example
1-2 neighbors: using the pair_style thole, their dipoles will see each other (despite the coul factor being 0.) and the

8.5. Packages howto 259

LAMMPS Documentation, Release stable 29Sep2021

interactions between these dipoles will be damped by Thole’s function.

Thermostats and barostats

Using a Nose-Hoover barostat with the langevin/drude thermostat is straightforward using fix nph instead of nve. For
example:

fix NPH all nph iso 1. 1. 500

It is also possible to use a Nose-Hoover instead of a Langevin thermostat. This requires to use *fix drude/transform*
just before and after the time integration fixes. The fix drude/transform/direct converts the atomic masses, positions,
velocities and forces into a reduced representation, where the DCs transform into the centers of mass of the DC-DP pairs
and the DPs transform into their relative position with respect to their DC. The fix drude/transform/inverse performs
the reverse transformation. For a NVT simulation, with the DCs and atoms at 300 K and the DPs at 1 K relative to their
DC one would use

fix DIRECT all drude/transform/direct

fix NVT1 ATOMS nvt temp 300. 300. 100
fix NVT2 DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse

For our phenol example, the groups would be defined as

group ATOMS type 1 2 3 4 5 # DCs and non-polarizable atoms

group CORES type 1 2 3 # DCs
group DRUDES type 6 7 8 # DPs

Note that with the fixes drude/transform, it is not required to specify comm_modify vel yes because the fixes do it
anyway (several times and for the forces also).
It is a bit more tricky to run a NPT simulation with Nose-Hoover barostat and thermostat. First, the volume should be
integrated only once. So the fix for DCs and atoms should be npt while the fix for DPs should be nvt (or vice versa).
Second, the fix npt computes a global pressure and thus a global temperature whatever the fix group. We do want the
pressure to correspond to the whole system, but we want the temperature to correspond to the fix group only. We must
then use the fix_modify command for this. In the end, the block of instructions for thermostatting and barostatting will
look like

compute TATOMS ATOMS temp

fix DIRECT all drude/transform/direct
fix NPT ATOMS npt temp 300. 300. 100 iso 1. 1. 500
fix_modify NPT temp TATOMS press thermo_press
fix NVT DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse

Another option for thermalizing the Drude model is to use the temperature-grouped Nose-Hoover (TGNH) thermostat
proposed by (Son). This is implemented as fix tgnvt/drude and fix tgnpt/drude. It separates the kinetic energy into
three contributions: the molecular center of mass (COM) motion, the motion of atoms or atom-Drude pairs relative to
molecular COMs, and the relative motion of atom-Drude pairs. An independent Nose-Hoover chain is applied to each
type of motion. When TGNH is used, the temperatures of molecular, atomic and Drude motion can be printed out with
thermo_style command command.
NVT simulation with TGNH thermostat

260 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

comm_modify vel yes

fix TGNVT all tgnvt/drude temp 300. 300. 100 1. 20
thermo_style custom f_TGNVT[1] f_TGNVT[2] f_TGNVT[3]

NPT simulation with TGNH thermostat

comm_modify vel yes

fix TGNPT all tgnpt/drude temp 300. 300. 100 1. 20 iso 1. 1. 500
thermo_style custom f_TGNPT[1] f_TGNPT[2] f_TGNPT[3]

Rigid bodies
You may want to simulate molecules as rigid bodies (but polarizable). Common cases are water models such as SWM4-
NDP, which is a kind of polarizable TIP4P water. The rigid bodies and the DPs should be integrated separately, even
with the Langevin thermostat. Let us review the different thermostats and ensemble combinations.
NVT ensemble using Langevin thermostat:

comm_modify vel yes

fix LANG all langevin/drude 300. 100 12435 1. 20 13977
fix RIGID ATOMS rigid/nve/small molecule
fix NVE DRUDES nve

NVT ensemble using Nose-Hoover thermostat:

fix DIRECT all drude/transform/direct

fix RIGID ATOMS rigid/nvt/small molecule temp 300. 300. 100
fix NVT DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse

NPT ensemble with Langevin thermostat:

comm_modify vel yes

fix LANG all langevin/drude 300. 100 12435 1. 20 13977
fix RIGID ATOMS rigid/nph/small molecule iso 1. 1. 500
fix NVE DRUDES nve

NPT ensemble using Nose-Hoover thermostat:

compute TATOM ATOMS temp

fix DIRECT all drude/transform/direct
fix RIGID ATOMS rigid/npt/small molecule temp 300. 300. 100 iso 1. 1. 500
fix_modify RIGID temp TATOM press thermo_press
fix NVT DRUDES nvt temp 1. 1. 20
fix INVERSE all drude/transform/inverse

(Lamoureux and Roux) Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003)
(Schroeder) Schroeder and Steinhauser, J Chem Phys, 133, 154511 (2010).
(Jiang) Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux, J Phys Chem Lett, 2, 87-92 (2011).

8.5. Packages howto 261

LAMMPS Documentation, Release stable 29Sep2021

(Thole) Chem Phys, 59, 341 (1981).

(Noskov) Noskov, Lamoureux and Roux, J Phys Chem B, 109, 6705 (2005).
(SWM4-NDP) Lamoureux, Harder, Vorobyov, Roux, MacKerell, Chem Phys Let, 418, 245-249 (2006)
(Son) Son, McDaniel, Cui and Yethiraj, J Phys Chem Lett, 10, 7523 (2019).

8.5.8 Manifolds (surfaces)

Overview:
This page is not about a LAMMPS input script command, but about manifolds, which are generalized sur-
faces, as defined and used by the MANIFOLD package, to track particle motion on the manifolds. See the
src/MANIFOLD/README file for more details about the package and its commands.
Below is a list of currently supported manifolds by the MANIFOLD package, their parameters and a short description
of them. The parameters listed here are in the same order as they should be passed to the relevant fixes.

262 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

man- pa- equation description

ifold ram-
eters
cylin- R x^2 + y^2 - R^2 = 0 Cylinder along z-axis, axis going through (0,0,0)
der
cylin- R l a x^2 + y^2 - r(z)^2 = 0, r(x) = R if | z | > l, r(z) A cylinder with a dent around z = 0
der_dent = R - a*(1 + cos(z/l))/2 otherwise
dumb- a A -( x^2 + y^2 ) + (a^2 - z^2/c^2) * ( 1 + A dumbbell
bell Bc (A*sin(B*z^2))^4) = 0
ellip- a b c (x/a)^2 + (y/b)^2 + (z/c)^2 = 0 An ellipsoid
soid
gaus- A l if( x < rc1) -z + A * exp( -x^2 / (2 l^2) ); else A Gaussian bump at x = y = 0, smoothly tapered
sian_bumprc1 if( x < rc2 ) -z + a + b*x + c*x^2 + d*x^3; to a flat plane z = 0.
rc2 else z
plane a b a*(x-x0) + b*(y-y0) + c*(z-z0) = 0 A plane with normal (a,b,c) going through point
c x0 (x0,y0,z0)
y0
z0
plane_wiggle
aw z - a*sin(w*x) = 0 A plane with a sinusoidal modulation on z along
x.
sphere R x^2 + y^2 + z^2 - R^2 = 0 A sphere of radius R
su- Rq | x |^q + | y |^q + | z |^q - R^q = 0 A supersphere of hyperradius R
per-
sphere
spine a, A, -(x^2 + y^2) + (a^2 - z^2/f(z)^2)*(1 + An approximation to a dendritic spine
B, (A*sin(g(z)*z^2))^4), f(z) = c if z > 0, 1 oth-
B2, erwise; g(z) = B if z > 0, B2 otherwise
c
spine_two
a, A, -(x^2 + y^2) + (a^2 - z^2/f(z)^2)*(1 + Another approximation to a dendritic spine
B, (A*sin(g(z)*z^2))^2), f(z) = c if z > 0, 1 oth-
B2, erwise; g(z) = B if z > 0, B2 otherwise
c
thy- wB Various, see (Paquay) A model grana thylakoid consisting of two block-
lakoid LB like compartments connected by a bridge of width
lB wB, length LB and taper length lB
torus Rr (R - sqrt( x^2 + y^2 ) )^2 + z^2 - r^2 A torus with large radius R and small radius r, cen-
tered on (0,0,0)

(Paquay) Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at arXiv:1411.3019.

8.5.9 Magnetic spins

The magnetic spin simulations are enabled by the SPIN package, whose implementation is detailed in Tranchida.
The model represents the simulation of atomic magnetic spins coupled to lattice vibrations. The dynamics of those
magnetic spins can be used to simulate a broad range a phenomena related to magneto-elasticity, or or to study the
influence of defects on the magnetic properties of materials.
The magnetic spins are interacting with each others and with the lattice via pair interactions. Typically, the magnetic
exchange interaction can be defined using the pair/spin/exchange command. This exchange applies a magnetic torque
to a given spin, considering the orientation of its neighboring spins and their relative distances. It also applies a force
on the atoms as a function of the spin orientations and their associated inter-atomic distances.

8.5. Packages howto 263

LAMMPS Documentation, Release stable 29Sep2021

The command fix precession/spin allows to apply a constant magnetic torque on all the spins in the system. This torque
can be an external magnetic field (Zeeman interaction), and an uniaxial or cubic magnetic anisotropy.
A Langevin thermostat can be applied to those magnetic spins using fix langevin/spin. Typically, this thermostat can
be coupled to another Langevin thermostat applied to the atoms using fix langevin in order to simulate thermostatted
spin-lattice systems.
The magnetic Gilbert damping can also be applied using fix langevin/spin. It allows to either dissipate the thermal
energy of the Langevin thermostat, or to perform a relaxation of the magnetic configuration toward an equilibrium
state.
The command fix setforce/spin allows to set the components of the magnetic precession vectors (while erasing and
replacing the previously computed magnetic precession vectors on the atom). This command can be used to freeze the
magnetic moment of certain atoms in the simulation by zeroing their precession vector.
The command fix nve/spin can be used to perform a symplectic integration of the combined dynamics of spins and
atomic motions.
The minimization style min/spin can be applied to the spins to perform a minimization of the spin configuration.
All the computed magnetic properties can be output by two main commands. The first one is compute spin, that
enables to evaluate magnetic averaged quantities, such as the total magnetization of the system along x, y, or z, the spin
temperature, or the magnetic energy. The second command is compute property/atom. It enables to output all the per
atom magnetic quantities. Typically, the orientation of a given magnetic spin, or the magnetic force acting on this spin.

(Tranchida) Tranchida, Plimpton, Thibaudeau and Thompson, Journal of Computational Physics, 372, 406-425,
(2018).

8.6 Tutorials howto

8.6.1 Using CMake with LAMMPS tutorial

The support for building LAMMPS with CMake is a recent addition to LAMMPS thanks to the efforts of Christoph
Junghans (LANL) and Richard Berger (Temple U). One of the key strengths of CMake is that it is not tied to a specific
platform or build system and thus generate the files necessary to build and develop for different build systems and on
different platforms. Note, that this applies to the build system itself not the LAMMPS code. In other words, without
additional porting effort, it is not possible - for example - to compile LAMMPS with Visual C++ on Windows. The build
system output can also include support files necessary to program LAMMPS as a project in integrated development
environments (IDE) like Eclipse, Visual Studio, QtCreator, Xcode, CodeBlocks, Kate and others.
A second important feature of CMake is, that it can detect and validate available libraries, optimal settings, available
support tools and so on, so that by default LAMMPS will take advantage of available tools without requiring to provide
the details about how to enable/integrate them.
The downside of this approach is, that there is some complexity associated with running CMake itself and how to
customize the building of LAMMPS. This tutorial will show how to manage this through some selected examples.
Please see the chapter about building LAMMPS for descriptions of specific flags and options for LAMMPS in general
and for specific packages.
CMake can be used through either the command-line interface (CLI) program cmake (or cmake3), a text mode inter-
active user interface (TUI) program ccmake (or ccmake3), or a graphical user interface (GUI) program cmake-gui.
All of them are portable software available on all supported platforms and can be used interchangeably. The minimum
supported CMake version is 3.10 (3.12 or later is recommended).
All details about features and settings for CMake are in the CMake online documentation. We focus below on the most
important aspects with respect to compiling LAMMPS.

264 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Prerequisites

This tutorial assumes that you are operating in a command-line environment using a shell like Bash.
• Linux: any Terminal window will work
• MacOS X: launch the Terminal application.
• Windows 10: install and run the Windows Subsystem for Linux
We also assume that you have downloaded and unpacked a recent LAMMPS source code package or used Git to create
a clone of the LAMMPS sources on your compilation machine.
You should change into the top level directory of the LAMMPS source tree all paths mentioned in the tutorial are
relative to that. Immediately after downloading it should look like this:

$ ls
bench doc lib potentials README tools
cmake examples LICENSE python src

Build versus source directory

When using CMake the build procedure is separated into multiple distinct phases:
1. Configuration: detect or define which features and settings should be enable and used and how LAMMPS
should be compiled
2. Compilation: generate and compile all necessary source files and build libraries and executables.
3. Installation: copy selected files from the compilation into your file system, so they can be used without having
to keep the source and build tree around.
The configuration and compilation of LAMMPS has to happen in a dedicated build directory which must be different
from the source directory. Also the source directory (src) must remain pristine, so it is not allowed to “install” packages
using the traditional make process and after an compilation attempt all created source files must be removed. This can
be achieved with make no-all purge.
You can pick any folder outside the source tree. We recommend to create a folder build in the top-level directory,
or multiple folders in case you want to have separate builds of LAMMPS with different options (build-parallel,
build-serial) or with different compilers (build-gnu, build-clang, build-intel) and so on. All the auxiliary
files created by one build process (executable, object files, log files, etc) are stored in this directory or sub-directories
within it that CMake creates.

Running CMake

CLI version

In the (empty) build directory, we now run the command cmake ../cmake, which will start the configuration phase
and you will see the progress of the configuration printed to the screen followed by a summary of the enabled features,
options and compiler settings. A typical summary screen will look like this:

$ cmake ../cmake/
-- The CXX compiler identification is GNU 8.2.0
-- Check for working CXX compiler: /opt/tools/gcc-8.2.0/bin/c++
-- Check for working CXX compiler: /opt/tools/gcc-8.2.0/bin/c++ - works
-- Detecting CXX compiler ABI info
(continues on next page)

8.6. Tutorials howto 265

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Found Git: /usr/bin/git (found version "2.25.2")
-- Running check for auto-generated files from make-based build system
-- Found MPI_CXX: /usr/lib64/mpich/lib/libmpicxx.so (found version "3.1")
-- Found MPI: TRUE (found version "3.1")
-- Looking for C++ include omp.h
-- Looking for C++ include omp.h - found
-- Found OpenMP_CXX: -fopenmp (found version "4.5")
-- Found OpenMP: TRUE (found version "4.5")
-- Found JPEG: /usr/lib64/libjpeg.so (found version "62")
-- Found PNG: /usr/lib64/libpng.so (found version "1.6.37")
-- Found ZLIB: /usr/lib64/libz.so (found version "1.2.11")
-- Found GZIP: /usr/bin/gzip
-- Found FFMPEG: /usr/bin/ffmpeg
-- Performing Test COMPILER_SUPPORTS-ffast-math
-- Performing Test COMPILER_SUPPORTS-ffast-math - Success
-- Performing Test COMPILER_SUPPORTS-march=native
-- Performing Test COMPILER_SUPPORTS-march=native - Success
-- Looking for C++ include cmath
-- Looking for C++ include cmath - found
-- Generating style_angle.h...
[...]
-- Generating lmpinstalledpkgs.h...
-- The following tools and libraries have been found and configured:
* Git
* MPI
* OpenMP
* JPEG
* PNG
* ZLIB

-- <<< Build configuration >>>

Build type: RelWithDebInfo
Install path: /home/akohlmey/.local
Generator: Unix Makefiles using /usr/bin/gmake
-- <<< Compilers and Flags: >>>
-- C++ Compiler: /opt/tools/gcc-8.2.0/bin/c++
Type: GNU
Version: 8.2.0
C++ Flags: -O2 -g -DNDEBUG
Defines: LAMMPS_SMALLBIG;LAMMPS_MEMALIGN=64;LAMMPS_JPEG;LAMMPS_PNG;LAMMPS_
,→GZIP;LAMMPS_FFMPEG

Options: -ffast-math;-march=native
-- <<< Linker flags: >>>
-- Executable name: lmp
-- Static library flags:
-- <<< MPI flags >>>
-- MPI includes: /usr/include/mpich-x86_64
-- MPI libraries: /usr/lib64/mpich/lib/libmpicxx.so;/usr/lib64/mpich/lib/libmpi.so;
-- Configuring done
(continues on next page)

266 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

-- Generating done
-- Build files have been written to: /home/akohlmey/compile/lammps/build

The cmake command has one mandatory argument, and that is a folder with either the file CMakeLists.txt or
CMakeCache.txt. The CMakeCache.txt file is created during the CMake configuration run and contains all ac-
tive settings, thus after a first run of CMake all future runs in the build folder can use the folder . and CMake will know
where to find the CMake scripts and reload the settings from the previous step. This means, that one can modify an
existing configuration by re-running CMake, but only needs to provide flags indicating the desired change, everything
else will be retained. One can also mix compilation and configuration, i.e. start with a minimal configuration and then,
if needed, enable additional features and recompile.
The steps above will NOT compile the code. The compilation can be started in a portable fashion with cmake --build
., or you use the selected built tool, e.g. make.

TUI version

For the text mode UI CMake program the basic principle is the same. You start the command ccmake ../cmake in
the build folder.

Fig. 1: Initial ccmake screen Fig. 2: Configure output of ccmake Fig. 3: Options screen of ccmake

This will show you the initial screen (left image) with the empty configuration cache. Now you type the ‘c’ key to
run the configuration step. That will do a first configuration run and show the summary (center image). You exit the
summary screen with ‘e’ and see now the main screen with detected options and settings. You can now make changes
by moving and down with the arrow keys of the keyboard and modify entries. For on/off settings, the enter key will
toggle the state. For others, hitting enter will allow you to modify the value and you commit the change by hitting the
enter key again or cancel using the escape key. All “new” settings will be marked with a star ‘*’ and for as long as one
setting is marked like this, you have to re-run the configuration by hitting the ‘c’ key again, sometimes multiple times
unless the TUI shows the word “generate” next to the letter ‘g’ and by hitting the ‘g’ key the build files will be written
to the folder and the TUI exits. You can quit without generating build files by hitting ‘q’.

GUI version

For the graphical CMake program the steps are similar to the TUI version. You can type the command cmake-gui
../cmake in the build folder. In this case the path to the CMake script folder is not required, it can also be entered
from the GUI.

8.6. Tutorials howto 267

LAMMPS Documentation, Release stable 29Sep2021

Fig. 5: Generator selection in Fig. 6: Options screen of

Fig. 4: Initial cmake-gui screen
cmake-gui cmake-gui

Again, you start with an empty configuration cache (left image) and need to start the configuration step. For the very
first configuration in a folder, you will have a pop-up dialog (center image) asking to select the desired build tool and
some configuration settings (stick with the default) and then you get the option screen with all new settings highlighted
in red. You can modify them (or not) and click on the “configure” button again until satisfied and click on the “generate”
button to write out the build files. You can exit the GUI from the “File” menu or hit “ctrl-q”.

Setting options

Options that enable, disable or modify settings are modified by setting the value of CMake variables. This is done on
the command line with the -D flag in the format -D VARIABLE=value, e.g. -D CMAKE_BUILD_TYPE=Release or -D
BUILD_MPI=on. There is one quirk: when used before the CMake directory, there may be a space between the -D flag
and the variable, after it must not be. Such CMake variables can have boolean values (on/off, yes/no, or 1/0 are all
valid) or are strings representing a choice, or a path, or are free format. If the string would contain whitespace, it must
be put in quotes, for example -D CMAKE_TUNE_FLAGS="-ftree-vectorize -ffast-math".
CMake variables fall into two categories: 1) common CMake variables that are used by default for any CMake configu-
ration setup and 2) project specific variables, i.e. settings that are specific for LAMMPS. Also CMake variables can be
flagged as advanced, which means they are not shown in the text mode or graphical CMake program in the overview of
all settings by default, but only when explicitly requested (by hitting the ‘t’ key or clicking on the ‘Advanced’ check-box).

Some common CMake variables

Variable Description
CMAKE_INSTALL_PREFIX root directory of install location for make install (default: $HOME/.local)
LAMMPS_INSTALL_RPATH set or remove runtime path setting from binaries for make install (default: off)
CMAKE_BUILD_TYPE controls compilation options: one of RelWithDebInfo (default), Release, Debug,
MinSizeRel
BUILD_SHARED_LIBS if set to on build the LAMMPS library as shared library (default: off)
CMAKE_MAKE_PROGRAM name/path of the compilation command (default depends on -G option, usually make)
CMAKE_VERBOSE_MAKEFILEif set to on echo commands while executing during build (default: off)
CMAKE_C_COMPILER C compiler to be used for compilation (default: system specific, gcc on Linux)
CMAKE_CXX_COMPILER C++ compiler to be used for compilation (default: system specific, g++ on Linux)
CMAKE_Fortran_COMPILERFortran compiler to be used for compilation (default: system specific, gfortran on
Linux)
CXX_COMPILER_LAUNCHER tool to launch the C++ compiler, e.g. ccache or distcc for faster compilation (default:
empty)

268 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Some common LAMMPS specific variables

Variable Description
BUILD_MPI build LAMMPS with MPI support (default: on if a working MPI available, else off)
BUILD_OMP build LAMMPS with OpenMP support (default: on if compiler supports OpenMP fully, else
off)
BUILD_TOOLS compile some additional executables from the tools folder (default: off)
BUILD_LAMMPS_SHELLcompile the LAMMPS shell from the tools/lammps-shell folder (default: off)
BUILD_DOC include building the HTML format documentation for packaging/installing (default: off)
CMAKE_TUNE_FLAGS common compiler flags, for optimization or instrumentation (default:)
LAMMPS_MACHINE when set to name the LAMMPS executable and library will be called lmp_name and
liblammps_name.a
LAMMPS_EXCEPTIONS when set to on errors will throw a C++ exception instead of aborting (default: off)
FFT select which FFT library to use: FFTW3, MKL, KISS (default, unless FFTW3 is found)
FFT_SINGLE select whether to use single precision FFTs (default: off)
WITH_JPEG whether to support JPEG format in dump image (default: on if found)
WITH_PNG whether to support PNG format in dump image (default: on if found)
WITH_GZIP whether to support reading and writing compressed files (default: on if found)
WITH_FFMPEG whether to support generating movies with dump movie (default: on if found)

Enabling or disabling LAMMPS packages

The LAMMPS software is organized into a common core that is always included and a large number of add-on packages
that have to be enabled to be included into a LAMMPS executable. Packages are enabled through setting variables of
the kind PKG_<NAME> to on and disabled by setting them to off (or using yes, no, 1, 0 correspondingly). <NAME> has
to be replaced by the name of the package, e.g. MOLECULE or EXTRA-PAIR.

Using presets

Since LAMMPS has a lot of optional features and packages, specifying them all on the command line can be tedious.
Or when selecting a different compiler toolchain, multiple options have to be changed consistently and that is rather
error prone. Or when enabling certain packages, they require consistent settings to be operated in a particular mode.
For this purpose, we are providing a selection of “preset files” for CMake in the folder cmake/presets. They represent
a way to pre-load or override the CMake configuration cache by setting or changing CMake variables. Preset files are
loaded using the -C command line flag. You can combine loading multiple preset files or change some variables later
with additional -D flags. A few examples:

cmake -C ../cmake/presets/basic.cmake -D PKG_MISC=on ../cmake

cmake -C ../cmake/presets/clang.cmake -C ../cmake/presets/most.cmake ../cmake
cmake -C ../cmake/presets/basic.cmake -D BUILD_MPI=off ../cmake

The first command will install the packages KSPACE, MANYBODY, MOLECULE, RIGID and MISC; the first four from the pre-
set file and the fifth from the explicit variable definition. The second command will first switch the compiler toolchain
to use the Clang compilers and install a large number of packages that are not depending on any special external li-
braries or tools and are not very unusual. The third command will enable the first four packages like above and then
enforce compiling LAMMPS as a serial program (using the MPI STUBS library).
It is also possible to do this incrementally.

cmake -C ../cmake/presets/basic.cmake ../cmake

cmake -D PKG_MISC=on .

8.6. Tutorials howto 269

LAMMPS Documentation, Release stable 29Sep2021

will achieve the same final configuration as in the first example above. In this scenario it is particularly convenient to
do the second configuration step using either the text mode or graphical user interface (ccmake or cmake-gui).

Note: Using a preset to select a compiler package (clang.cmake, gcc.cmake, intel.cmake, oneapi.cmake, or
pgi.cmake) are an exception to the mechanism of updating the configuration incrementally, as they will trigger a reset
of cached internal CMake settings and thus reset settings to their default values.

Compilation and build targets

The actual compilation will be started by running the selected build command (on Linux this is by default make, see
below how to select alternatives). You can also use the portable command cmake --build . which will adapt to
whatever the selected build command is. This is particularly convenient, if you have set a custom build command via
the CMAKE_MAKE_PROGRAM variable.
When calling the build program, you can also select which “target” is to be build through appending the --target
flag and the name of the target to the build command. When using make as build tool, you can just append the target
name to the command. Example: cmake --build . --target all or make all. The following abstract targets
are available:

Target Description
all build “everything” (default)
lammps build the LAMMPS library and executable
doc build the HTML documentation (if configured)
install install all target files into folders in CMAKE_INSTALL_PREFIX
test run some tests (if configured with -D ENABLE_TESTING=on)
clean remove all generated files

Choosing generators

While CMake usually defaults to creating makefiles to compile software with the make program, it supports multiple
alternate build tools (e.g. ninja-build which tends to be faster and more efficient in parallelizing builds than make)
and can generate project files for integrated development environments (IDEs) like VisualStudio, Eclipse or Code-
Blocks. This is specific to how the local CMake version was configured and compiled. The list of available options
can be seen at the end of the output of cmake --help. Example on Fedora 31 this is:

Generators

The following generators are available on this platform (* marks default):

* Unix Makefiles = Generates standard UNIX makefiles.
Green Hills MULTI = Generates Green Hills MULTI files
(experimental, work-in-progress).
Ninja = Generates build.ninja files.
Ninja Multi-Config = Generates build-<Config>.ninja files.
Watcom WMake = Generates Watcom WMake makefiles.
CodeBlocks - Ninja = Generates CodeBlocks project files.
CodeBlocks - Unix Makefiles = Generates CodeBlocks project files.
CodeLite - Ninja = Generates CodeLite project files.
CodeLite - Unix Makefiles = Generates CodeLite project files.
Sublime Text 2 - Ninja = Generates Sublime Text 2 project files.
Sublime Text 2 - Unix Makefiles
(continues on next page)

270 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

= Generates Sublime Text 2 project files.
Kate - Ninja = Generates Kate project files.
Kate - Unix Makefiles = Generates Kate project files.
Eclipse CDT4 - Ninja = Generates Eclipse CDT 4.0 project files.
Eclipse CDT4 - Unix Makefiles= Generates Eclipse CDT 4.0 project files.

Below is a screenshot of using the CodeBlocks IDE with the ninja build tool after running CMake as follows:

cmake -G 'CodeBlocks - Ninja' ../cmake/presets/most.cmake ../cmake/

8.6.2 LAMMPS GitHub tutorial

written by Stefan Paquay

This document describes the process of how to use GitHub to integrate changes or additions you have made to LAMMPS
into the official LAMMPS distribution. It uses the process of updating this very tutorial as an example to describe the
individual steps and options. You need to be familiar with git and you may want to have a look at the git book to
reacquaint yourself with some of the more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests on GitHub is the preferred option for integrating
contributed features or improvements to LAMMPS, as it significantly reduces the amount of work required by the

8.6. Tutorials howto 271

LAMMPS Documentation, Release stable 29Sep2021

LAMMPS developers. Consequently, creating a pull request will increase your chances to have your contribution
included and will reduce the time until the integration is complete. For more information on the requirements to have
your code included into LAMMPS please see this page.

Making an account
First of all, you need a GitHub account. This is fairly simple, just go to GitHub and create an account by clicking the
“Sign up for GitHub” button. Once your account is created, you can sign in by clicking the button in the top left and
filling in your username or e-mail address and password.

Forking the repository

To get changes into LAMMPS, you need to first fork the lammps/lammps repository on GitHub. At the time of writing,
master is the preferred target branch. Thus go to LAMMPS on GitHub and make sure branch is set to “master”, as
shown in the figure below.

If it is not, use the button to change it to master. Once it is, use the fork button to create a fork.

This will create a fork (which is essentially a copy, but uses less resources) of the LAMMPS repository under your own
GitHub account. You can make changes in this fork and later file pull requests to allow the upstream repository to merge
changes from your own fork into the one we just forked from (or others that were forked from the same repository). At
the same time, you can set things up, so you can include changes from upstream into your repository and thus keep it
in sync with the ongoing LAMMPS development.

Adding changes to your own fork

Additions to the upstream version of LAMMPS are handled using feature branches. For every new feature, a so-called
feature branch is created, which contains only those modification relevant to one specific feature. For example, adding
a single fix would consist of creating a branch with only the fix header and source file and nothing else. It is explained
in more detail here: feature branch workflow.
Feature branches
First of all, create a clone of your version on GitHub on your local machine via HTTPS:

272 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

$ git clone https://github.com/<your user name>/lammps.git <some name>

or, if you have set up your GitHub account for using SSH keys, via SSH:

$ git clone [email protected]:<your user name>/lammps.git

You can find the proper URL by clicking the “Clone or download”-button:

The above command copies (“clones”) the git repository to your local machine to a directory with the name you chose.
If none is given, it will default to “lammps”. Typical names are “mylammps” or something similar.
You can use this local clone to make changes and test them without interfering with the repository on GitHub.
To pull changes from upstream into this copy, you can go to the directory and use git pull:

$ cd mylammps
$ git checkout master
$ git pull https://github.com/lammps/lammps

You can also add this URL as a remote:

$ git remote add lammps_upstream https://www.github.com/lammps/lammps

At this point, you typically make a feature branch from the updated master branch for the feature you want to work on.
This tutorial contains the workflow that updated this tutorial, and hence we will call the branch “github-tutorial-update”:

$ git checkout -b github-tutorial-update master

Now that we have changed branches, we can make our changes to our local repository. Just remember that if you want
to start working on another, unrelated feature, you should switch branches!
After changes are made
After everything is done, add the files to the branch and commit them:

$ git add doc/src/Howto_github.txt

$ git add doc/src/JPG/tutorial*.png

8.6. Tutorials howto 273

LAMMPS Documentation, Release stable 29Sep2021

Warning: Do not use git commit -a (or git add -A). The -a flag (or -A flag) will automatically include all modified
and new files and that is rarely the behavior you want. It can easily lead to accidentally adding unrelated and
unwanted changes into the repository. Instead it is preferable to explicitly use git add, git rm, git mv for adding,
removing, renaming individual files, respectively, and then git commit to finalize the commit. Carefully check all
pending changes with git status before committing them. If you find doing this on the command line too tedious,
consider using a GUI, for example the one included in git distributions written in Tk, i.e. use git gui (on some Linux
distributions it may be required to install an additional package to use it).

After adding all files, the change set can be committed with some useful message that explains the change.

$ git commit -m 'Finally updated the GitHub tutorial'

After the commit, the changes can be pushed to the same branch on GitHub:

$ git push

Git will ask you for your user name and password on GitHub if you have not configured anything. If your local branch
is not present on GitHub yet, it will ask you to add it by running

$ git push --set-upstream origin github-tutorial-update

If you correctly type your user name and password, the feature branch should be added to your fork on GitHub.
If you want to make really sure you push to the right repository (which is good practice), you can provide it explicitly:

$ git push origin

or using an explicit URL:

$ git push [email protected]:Pakketeretet2/lammps.git

Filing a pull request

Up to this point in the tutorial, all changes were to your clones of LAMMPS. Eventually, however, you want this feature
to be included into the official LAMMPS version. To do this, you will want to file a pull request by clicking on the
“New pull request” button:

Make sure that the current branch is set to the correct one, which, in this case, is “github-tutorial-update”. If done
correctly, the only changes you will see are those that were made on this branch.

274 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

This will open up a new window that lists changes made to the repository. If you are just adding new files, there is not
much to do, but I suppose merge conflicts are to be resolved here if there are changes in existing files. If all changes
can automatically be merged, green text at the top will say so and you can click the “Create pull request” button, see
image.

Before creating the pull request, make sure the short title is accurate and add a comment with details about your pull
request. Here you write what your modifications do and why they should be incorporated upstream.
Note the checkbox that says “Allow edits from maintainers”. This is checked by default checkbox (although in my
version of Firefox, only the checkmark is visible):

If it is checked, maintainers can immediately add their own edits to the pull request. This helps the inclusion of your
branch significantly, as simple/trivial changes can be added directly to your pull request branch by the LAMMPS
maintainers. The alternative would be that they make changes on their own version of the branch and file a reverse pull
request to you. Just leave this box checked unless you have a very good reason not to.
Now just write some nice comments and click on “Create pull request”.

8.6. Tutorials howto 275

LAMMPS Documentation, Release stable 29Sep2021

After filing a pull request

Note: When you submit a pull request (or ask for a pull request) for the first time, you will receive an invitation
to become a LAMMPS project collaborator. Please accept this invite as being a collaborator will simplify certain
administrative tasks and will probably speed up the merging of your feature, too.

You will notice that after filing the pull request, some checks are performed automatically:

276 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

If all is fine, you will see this:

8.6. Tutorials howto 277

LAMMPS Documentation, Release stable 29Sep2021

If any of the checks are failing, your pull request will not be processed, as your changes may break compilation for
certain configurations or may not merge cleanly. It is your responsibility to remove the reason(s) for the failed test(s).
If you need help with this, please contact the LAMMPS developers by adding a comment explaining your problems
with resolving the failed tests.
A few further interesting things (can) happen to pull requests before they are included.
Additional changes
First of all, any additional changes you push into your branch in your repository will automatically become part of the
pull request:

This means you can add changes that should be part of the feature after filing the pull request, which is useful in case
you have forgotten them, or if a developer has requested that something needs to be changed before the feature can be
accepted into the official LAMMPS version. After each push, the automated checks are run again.
Labels
LAMMPS developers may add labels to your pull request to assign it to categories (mostly for bookkeeping purposes),
but a few of them are important: needs_work, work_in_progress, test-for-regression, and full-regression-test. The first
two indicate, that your pull request is not considered to be complete. With “needs_work” the burden is on exclusively
on you; while “work_in_progress” can also mean, that a LAMMPS developer may want to add changes. Please watch
the comments to the pull requests. The two “test” labels are used to trigger extended tests before the code is merged.
This is sometimes done by LAMMPS developers, if they suspect that there may be some subtle side effects from your
changes. It is not done by default, because those tests are very time consuming.
Reviews
As of Summer 2018, a pull request needs at least 1 approving review from a LAMMPS developer with write access to
the repository. In case your changes touch code that certain developers are associated with, they are auto-requested by
the GitHub software. Those associations are set in the file .github/CODEOWNERS Thus if you want to be automatically
notified to review when anybody changes files or packages, that you have contributed to LAMMPS, you can add suitable
patterns to that file, or a LAMMPS developer may add you.

278 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Otherwise, you can also manually request reviews from specific developers, or LAMMPS developers - in their as-
sessment of your pull request - may determine who else should be reviewing your contribution and add that person.
Through reviews, LAMMPS developers also may request specific changes from you. If those are not addressed, your
pull requests cannot be merged.
Assignees
There is an assignee property for pull requests. If the request has not been reviewed by any developer yet, it is not
assigned to anyone. After revision, a developer can choose to assign it to either a) you, b) a LAMMPS developer
(including him/herself) or c) Axel Kohlmeyer (akohlmey).
• Case a) happens if changes are required on your part
• Case b) means that at the moment, it is being tested and reviewed by a LAMMPS developer with the expectation
that some changes would be required. After the review, the developer can choose to implement changes directly
or suggest them to you.
• Case c) means that the pull request has been assigned to the developer overseeing the merging of pull requests
into the master branch.
In this case, Axel assigned the tutorial to Steve:

Edits from LAMMPS maintainers

If you allowed edits from maintainers (the default), any LAMMPS maintainer can add changes to your pull request. In
this case, both Axel and Richard made changes to the tutorial:

Reverse pull requests

Sometimes, however, you might not feel comfortable having other people push changes into your own branch, or maybe
the maintainers are not sure their idea was the right one. In such a case, they can make changes, reassign you as the
assignee, and file a “reverse pull request”, i.e. file a pull request in your GitHub repository to include changes in the
branch, that you have submitted as a pull request yourself. In that case, you can choose to merge their changes back
into your branch, possibly make additional changes or corrections and proceed from there. It looks something like this:

8.6. Tutorials howto 279

LAMMPS Documentation, Release stable 29Sep2021

For some reason, the highlighted button did not work in my case, but I can go to my own repository and merge the pull
request from there:

Be sure to check the changes to see if you agree with them by clicking on the tab button:

280 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

In this case, most of it is changes in the markup and a short rewrite of Axel’s explanation of the “git gui” and “git add”
commands.

Because the changes are OK with us, we are going to merge by clicking on “Merge pull request”. After a merge it looks
like this:

8.6. Tutorials howto 281

LAMMPS Documentation, Release stable 29Sep2021

Now, since in the meantime our local text for the tutorial also changed, we need to pull Axel’s change back into our
branch, and merge them:
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request*.png
$ git commit -m "Updated text and images on reverse pull requests"
$ git pull

In this case, the merge was painless because git could auto-merge:

With Axel’s changes merged in and some final text updates, our feature branch is now perfect as far as we are concerned,
so we are going to commit and push again:
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request6.png
$ git commit -m "Merged Axel's suggestions and updated text"
$ git push [email protected]:Pakketeretet2/lammps

This merge also shows up on the lammps GitHub page:

After a merge

282 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

When everything is fine, the feature branch is merged into the master branch:

Now one question remains: What to do with the feature branch that got merged into upstream?
It is in principle safe to delete them from your own fork. This helps keep it a bit more tidy. Note that you first have to
switch to another branch!

$ git checkout master

$ git pull master
$ git branch -d github-tutorial-update

If you do not pull first, it is not really a problem but git will warn you at the next statement that you are deleting a local
branch that was not yet fully merged into HEAD. This is because git does not yet know your branch just got merged
into LAMMPS upstream. If you first delete and then pull, everything should still be fine.
Finally, if you delete the branch locally, you might want to push this to your remote(s) as well:

$ git push origin :github-tutorial-update

Recent changes in the workflow

Some changes to the workflow are not captured in this tutorial. For example, in addition to the master branch, to
which all new features should be submitted, there is now also an “unstable” and a “stable” branch; these have the same
content as “master”, but are only updated after a patch release or stable release was made. Furthermore, the naming of
the patches now follow the pattern “patch_<Day><Month><Year>” to simplify comparisons between releases. Finally,
all patches and submissions are subject to automatic testing and code checks to make sure they at the very least compile.
A discussion of the LAMMPS developer GitHub workflow can be found in the file doc/github-development-
workflow.md

8.6.3 PyLammps Tutorial

Contents

• PyLammps Tutorial
– Overview
∗ Comparison of lammps and PyLammps interfaces
· lammps.lammps
· lammps.PyLammps
– Quick Start

8.6. Tutorials howto 283

LAMMPS Documentation, Release stable 29Sep2021

∗ System-wide Installation
· Step 1: Building LAMMPS as a shared library
· Step 2: Installing the LAMMPS Python package
∗ Installation inside of a virtualenv
· Benefits of using a virtualenv
· Creating a virtualenv with lammps installed
– Creating a new instance of PyLammps
– Commands
– System state
– Working with LAMMPS variables
– Retrieving the value of an arbitrary LAMMPS expressions
– Accessing atom data
– Evaluating thermo data
– Error handling with PyLammps
– Using PyLammps in IPython notebooks and Jupyter
– IPyLammps Examples
∗ Validating a dihedral potential
∗ Running a Monte Carlo relaxation
– Using PyLammps and mpi4py (Experimental)
– Feedback and Contributing

Overview

PyLammps is a Python wrapper class for LAMMPS which can be created on its own or use an existing lammps Python
object. It creates a simpler, more “pythonic” interface to common LAMMPS functionality, in contrast to the lammps
wrapper for the C-style LAMMPS library interface which is written using Python ctypes. The lammps wrapper is
discussed on the Use Python with LAMMPS doc page.
Unlike the flat ctypes interface, PyLammps exposes a discoverable API. It no longer requires knowledge of the under-
lying C++ code implementation. Finally, the IPyLammps wrapper builds on top of PyLammps and adds some additional
features for IPython integration into Jupyter notebooks, e.g. for embedded visualization output from dump style image.

Comparison of lammps and PyLammps interfaces

lammps.lammps

• uses ctypes
• direct memory access to native C++ data
• provides functions to send and receive data to LAMMPS
• requires knowledge of how LAMMPS internally works (C pointers, etc)

284 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

lammps.PyLammps

• higher-level abstraction built on top of original ctypes interface

• manipulation of Python objects
• communication with LAMMPS is hidden from API user
• shorter, more concise Python
• better IPython integration, designed for quick prototyping

Quick Start

System-wide Installation

Step 1: Building LAMMPS as a shared library

To use LAMMPS inside of Python it has to be compiled as shared library. This library is then loaded by the Python
interface. In this example we enable the MOLECULE package and compile LAMMPS with C++ exceptions, PNG,
JPEG and FFMPEG output support enabled.
Step 1a: For the CMake based build system, the steps are:

mkdir $LAMMPS_DIR/build-shared
cd $LAMMPS_DIR/build-shared

# MPI, PNG, Jpeg, FFMPEG are auto-detected

cmake ../cmake -DPKG_MOLECULE=yes -DLAMMPS_EXCEPTIONS=yes -DBUILD_LIB=yes -DBUILD_SHARED_
,→LIBS=yes

make

Step 1b: For the legacy, make based build system, the steps are:

cd $LAMMPS_DIR/src

# add packages if necessary

make yes-MOLECULE

# compile shared library using Makefile

make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG -DLAMMPS_
,→EXCEPTIONS" JPG_LIB="-lpng -ljpeg"

Step 2: Installing the LAMMPS Python package

PyLammps is part of the lammps Python package. To install it simply install that package into your current Python
installation with:

make install-python

Note: Recompiling the shared library requires re-installing the Python package

8.6. Tutorials howto 285

LAMMPS Documentation, Release stable 29Sep2021

Installation inside of a virtualenv

You can use virtualenv to create a custom Python environment specifically tuned for your workflow.

Benefits of using a virtualenv

• isolation of your system Python installation from your development installation

• installation can happen in your user directory without root access (useful for HPC clusters)
• installing packages through pip allows you to get newer versions of packages than e.g., through apt-get or yum
package managers (and without root access)
• you can even install specific old versions of a package if necessary
Prerequisite (e.g. on Ubuntu)

apt-get install python-virtualenv

Creating a virtualenv with lammps installed

# create virtualenv named 'testing'

virtualenv $HOME/python/testing

# activate 'testing' environment

source $HOME/python/testing/bin/activate

Now configure and compile the LAMMPS shared library as outlined above. When using CMake and the shared library
has already been build, you need to re-run CMake to update the location of the python executable to the location in the
virtual environment with:

cmake . -DPYTHON_EXECUTABLE=$(which python)

# install LAMMPS package in virtualenv

(testing) make install-python

# install other useful packages

(testing) pip install matplotlib jupyter mpi4py

...

# return to original shell

(testing) deactivate

286 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Creating a new instance of PyLammps

To create a PyLammps object you need to first import the class from the lammps module. By using the default con-
structor, a new lammps instance is created.

from lammps import PyLammps

L = PyLammps()

You can also initialize PyLammps on top of this existing lammps object:

from lammps import lammps, PyLammps

lmp = lammps()
L = PyLammps(ptr=lmp)

Commands

Sending a LAMMPS command with the existing library interfaces is done using the command method of the lammps
object instance.
For instance, let’s take the following LAMMPS command:

region box block 0 10 0 5 -0.5 0.5

In the original interface this command can be executed with the following Python code if L was a lammps instance:

L.command("region box block 0 10 0 5 -0.5 0.5")

With the PyLammps interface, any command can be split up into arbitrary parts separated by white-space, passed as
individual arguments to a region method.

L.region("box block", 0, 10, 0, 5, -0.5, 0.5)

Note that each parameter is set as Python literal floating-point number. In the PyLammps interface, each command takes
an arbitrary parameter list and transparently merges it to a single command string, separating individual parameters by
white-space.
The benefit of this approach is avoiding redundant command calls and easier parameterization. In the original interface
parameterization needed to be done manually by creating formatted strings.

L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))

In contrast, methods of PyLammps accept parameters directly and will convert them automatically to a final command
string.

L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)

8.6. Tutorials howto 287

LAMMPS Documentation, Release stable 29Sep2021

System state

In addition to dispatching commands directly through the PyLammps object, it also provides several properties which
allow you to query the system state.
L.system Is a dictionary describing the system such as the bounding box or number of atoms
L.system.xlo, L.system.xhi bounding box limits along x-axis
L.system.ylo, L.system.yhi bounding box limits along y-axis
L.system.zlo, L.system.zhi bounding box limits along z-axis
L.communication configuration of communication subsystem, such as the number of threads or processors
L.communication.nthreads number of threads used by each LAMMPS process
L.communication.nprocs number of MPI processes used by LAMMPS
L.fixes List of fixes in the current system
L.computes List of active computes in the current system
L.dump List of active dumps in the current system
L.groups List of groups present in the current system

Working with LAMMPS variables

LAMMPS variables can be both defined and accessed via the PyLammps interface.
To define a variable you can use the variable command:

L.variable("a index 2")

A dictionary of all variables is returned by L.variables

you can access an individual variable by retrieving a variable object from the L.variables dictionary by name

a = L.variables['a']

The variable value can then be easily read and written by accessing the value property of this object.

print(a.value)
a.value = 4

Retrieving the value of an arbitrary LAMMPS expressions

LAMMPS expressions can be immediately evaluated by using the eval method. The passed string parameter can be
any expression containing global thermo values, variables, compute or fix data.

result = L.eval("ke") # kinetic energy

result = L.eval("pe") # potential energy

result = L.eval("v_t/2.0")

288 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Accessing atom data

All atoms in the current simulation can be accessed by using the L.atoms list. Each element of this list is an object
which exposes its properties (id, type, position, velocity, force, etc.).

# access first atom

L.atoms[0].id
L.atoms[0].type

# access second atom

L.atoms[1].position
L.atoms[1].velocity
L.atoms[1].force

Some properties can also be used to set:

# set position in 2D simulation

L.atoms[0].position = (1.0, 0.0)

# set position in 3D simulation

L.atoms[0].position = (1.0, 0.0, 1.)

Evaluating thermo data

Each simulation run usually produces thermo output based on system state, computes, fixes or variables. The trajecto-
ries of these values can be queried after a run via the L.runs list. This list contains a growing list of run data. The first
element is the output of the first run, the second element that of the second run.

L.run(1000)
L.runs[0] # data of first 1000 time steps

L.run(1000)
L.runs[1] # data of second 1000 time steps

Each run contains a dictionary of all trajectories. Each trajectory is accessible through its thermo name:

L.runs[0].thermo.Step # list of time steps in first run

L.runs[0].thermo.Ke # list of kinetic energy values in first run

Together with matplotlib plotting data out of LAMMPS becomes simple:

import matplotlib.plot as plt

steps = L.runs[0].thermo.Step
ke = L.runs[0].thermo.Ke
plt.plot(steps, ke)

8.6. Tutorials howto 289

LAMMPS Documentation, Release stable 29Sep2021

Error handling with PyLammps

Compiling the shared library with C++ exception support provides a better error handling experience. Without ex-
ceptions the LAMMPS code will terminate the current Python process with an error message. C++ exceptions allow
capturing them on the C++ side and rethrowing them on the Python side. This way you can handle LAMMPS errors
through the Python exception handling mechanism.

Warning: Capturing a LAMMPS exception in Python can still mean that the current LAMMPS process is in an
illegal state and must be terminated. It is advised to save your data and terminate the Python instance as quickly as
possible.

Using PyLammps in IPython notebooks and Jupyter

If the LAMMPS Python package is installed for the same Python interpreter as IPython, you can use PyLammps directly
inside of an IPython notebook inside of Jupyter. Jupyter is a powerful integrated development environment (IDE)
for many dynamic languages like Python, Julia and others, which operates inside of any web browser. Besides auto-
completion and syntax highlighting it allows you to create formatted documents using Markup, mathematical formulas,
graphics and animations intermixed with executable Python code. It is a great format for tutorials and showcasing your
latest research.
To launch an instance of Jupyter simply run the following command inside your Python environment (this assumes you
followed the Quick Start instructions):

jupyter notebook

IPyLammps Examples

Examples of IPython notebooks can be found in the python/examples/pylammps sub-directory. To open these notebooks
launch jupyter notebook inside this directory and navigate to one of them. If you compiled and installed a LAMMPS
shared library with exceptions, PNG, JPEG and FFMPEG support you should be able to rerun all of these notebooks.

Validating a dihedral potential

This example showcases how an IPython Notebook can be used to compare a simple LAMMPS simulation of a har-
monic dihedral potential to its analytical solution. Four atoms are placed in the simulation and the dihedral potential
is applied on them using a datafile. Then one of the atoms is rotated along the central axis by setting its position from
Python, which changes the dihedral angle.

phi = [d \* math.pi / 180 for d in range(360)]

pos = [(1.0, math.cos(p), math.sin(p)) for p in phi]

pe = []
for p in pos:
L.atoms[3].position = p
L.run(0)
pe.append(L.eval("pe"))

By evaluating the potential energy for each position we can verify that trajectory with the analytical formula. To
compare both solutions, we plot both trajectories over each other using matplotlib, which embeds the generated plot
inside the IPython notebook.

290 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Running a Monte Carlo relaxation

This second example shows how to use PyLammps to create a 2D Monte Carlo Relaxation simulation, computing and
plotting energy terms and even embedding video output.
Initially, a 2D system is created in a state with minimal energy.

8.6. Tutorials howto 291

LAMMPS Documentation, Release stable 29Sep2021

It is then disordered by moving each atom by a random delta.

random.seed(27848)
deltaperturb = 0.2

for i in range(L.system.natoms):
x, y = L.atoms[i].position
dx = deltaperturb \* random.uniform(-1, 1)
dy = deltaperturb \* random.uniform(-1, 1)
L.atoms[i].position = (x+dx, y+dy)

L.run(0)

292 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Finally, the Monte Carlo algorithm is implemented in Python. It continuously moves random atoms by a random delta
and only accepts certain moves.

estart = L.eval("pe")
elast = estart

naccept = 0
energies = [estart]

niterations = 3000
deltamove = 0.1
kT = 0.05

natoms = L.system.natoms

for i in range(niterations):
iatom = random.randrange(0, natoms)
current_atom = L.atoms[iatom]
(continues on next page)

8.6. Tutorials howto 293

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

x0, y0 = current_atom.position

dx = deltamove \* random.uniform(-1, 1)
dy = deltamove \* random.uniform(-1, 1)

current_atom.position = (x0+dx, y0+dy)

L.run(1, "pre no post no")

e = L.eval("pe")
energies.append(e)

if e <= elast:
naccept += 1
elast = e
elif random.random() <= math.exp(natoms\*(elast-e)/kT):
naccept += 1
elast = e
else:
current_atom.position = (x0, y0)

The energies of each iteration are collected in a Python list and finally plotted using matplotlib.

294 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

The IPython notebook also shows how to use dump commands and embed video files inside of the IPython notebook.

Using PyLammps and mpi4py (Experimental)

PyLammps can be run in parallel using mpi4py. This python package can be installed using

pip install mpi4py

The following is a short example which reads in an existing LAMMPS input file and executes it in parallel. You can
find in.melt in the examples/melt folder.

from mpi4py import MPI

from lammps import PyLammps

L = PyLammps()
L.file("in.melt")

if MPI.COMM_WORLD.rank == 0:
print("Potential energy: ", L.eval("pe"))
(continues on next page)

8.6. Tutorials howto 295

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

MPI.Finalize()

To run this script (melt.py) in parallel using 4 MPI processes we invoke the following mpirun command:

mpirun -np 4 python melt.py

Warning: Any command must be executed by all MPI processes. However, evaluations and querying the system
state is only available on rank 0.

Feedback and Contributing

If you find this Python interface useful, please feel free to provide feedback and ideas on how to improve it to Richard
Berger ([email protected]). We also want to encourage people to write tutorial style IPython notebooks
showcasing LAMMPS usage and maybe their latest research results.

8.6.4 Using LAMMPS on Windows 10 with WSL

written by Richard Berger

It’s always been tricky for us to have LAMMPS users and developers work on Windows. We primarily develop
LAMMPS to run on Linux clusters. To teach LAMMPS in workshop settings, we had to redirect Windows users
to Linux Virtual Machines such as VirtualBox or Unix-like compilation with Cygwin.
With the latest updates in Windows 10 (Version 2004, Build 19041 or higher), Microsoft has added a new way to work
on Linux-based code. The Windows Subsystem for Linux (WSL). With WSL Version 2, you now get a Linux Virtual
Machine that transparently integrates into Windows. All you need is to ensure you have the latest Windows updates
installed and enable this new feature. Linux VMs are then easily installed using the Microsoft Store.
In this tutorial, I’ll show you how to set up and compile LAMMPS for both serial and MPI usage in WSL2.

Installation

Upgrade to the latest Windows 10

Type “Updates” in Windows Start and select “Check for Updates”.

296 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Install all pending updates and reboot your system as many times as necessary. Continue until your Windows installation
is updated.

Verify your system has at least version 2004 and build 19041 or later. You can find this information by clicking on

8.6. Tutorials howto 297

LAMMPS Documentation, Release stable 29Sep2021

“OS build info”.

Enable WSL

Next, we must install two additional Windows features to enable WSL support. Open a PowerShell window as an
administrator. Type “PowerShell” in Windows Start and select “Run as Administrator”.

298 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Windows will ask you for administrator access. After you accept a new command line window will appear. Type in the
following command to install WSL:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /

,→norestart

Next, enable the VirtualMachinePlatform feature using the following command:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

8.6. Tutorials howto 299

LAMMPS Documentation, Release stable 29Sep2021

Finally, reboot your system.

Update WSL kernel component

Download and install the WSL Kernel Component Update. Afterwards, reboot your system.

Set WSL2 as default

Again, open PowerShell as administrator and run the following command:

wsl --set-default-version 2

This command ensures that all future Linux installations will use WSL version 2.

Install a Linux Distribution

Next, we need to install a Linux distribution via the Microsoft Store. Install Ubuntu 20.04 LTS. Once installed, you
can launch it like any other application from the Start Menu.

300 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Initial Setup

The first time you launch the Ubuntu Linux console, it will prompt you for a UNIX username and password. You will
need this password to perform sudo commands later. Once completed, your Linux shell is ready for use. All your
actions and commands will run as the Linux user you specified.

8.6. Tutorials howto 301

LAMMPS Documentation, Release stable 29Sep2021

Windows Explorer / WSL integration

Your Linux installation will have its own Linux filesystem, which contains the Ubuntu files. Your Linux user will have
a regular Linux home directory in /home/<USERNAME>. This directory is different from your Windows User directory.
Windows and Linux filesystems are connected through WSL.
All hard drives in Windows are accessible in the /mnt directory in Linux. E.g., WSL maps the C hard drive to the /mnt/
c directory. That means you can access your Windows User directory in /mnt/c/Users/<WINDOWS_USERNAME>.
The Windows Explorer can also access the Linux filesystem. To illustrate this integration, open an Ubuntu console and
navigate to a directory of your choice. To view this location in Windows Explorer, use the explorer.exe . command
(do not forget the final dot!).

Compiling LAMMPS

You now have a fully functioning Ubuntu installation and can follow most guides to install LAMMPS on a Linux
system. Here are some of the essential steps to follow:

Install prerequisite packages

Before we can begin, we need to download the necessary compiler toolchain and libraries to compile LAMMPS. In
our Ubuntu-based Linux installation, we will use the apt package manager to install additional packages.
First, upgrade all existing packages using apt update and apt upgrade.

sudo apt update

sudo apt upgrade -y

Next, install the following packages with apt install:

sudo apt install -y cmake build-essential ccache gfortran openmpi-bin libopenmpi-dev \

libfftw3-dev libjpeg-dev libpng-dev python3-dev python3-pip \
python3-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev \
hdf5-tools

302 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

Download LAMMPS

Obtain a copy of the LAMMPS source code and go into it using the cd command.

Option 1: Download a LAMMPS tarball using wget

wget https://github.com/lammps/lammps/archive/stable_3Mar2020.tar.gz
tar xvzf stable_3Mar2020.tar.gz
cd lammps

Option 2: Download a LAMMPS development version from GitHub

git clone --depth=1 https://github.com/lammps/lammps.git

cd lammps

Configure and Compile LAMMPS with CMake

A beginner-friendly way to compile LAMMPS is to use CMake. Create a build directory to compile LAMMPS and
move into it. This directory will store the build configuration and any binaries generated during compilation.

mkdir build
cd build

There are countless ways to compile LAMMPS. It is beyond the scope of this tutorial. If you want to find out more
about what can be enabled, please consult the extensive documentation.
To compile a minimal version of LAMMPS, we’re going to use a preset. Presets are a way to specify a collection of
CMake options using a file.

cmake ../cmake/presets/basic.cmake ../cmake

This command configures the build and generates the necessary Makefiles. To compile the binary, run the make
command.

make -j 4

The -j option specifies how many parallel processes will perform the compilation. This option can significantly speed
up compilation times. Use a number that corresponds to the number of processors in your system.
After the compilation completes successfully, you will have an executable called lmp in the build directory.

8.6. Tutorials howto 303

LAMMPS Documentation, Release stable 29Sep2021

Please take note of the absolute path of your build directory. You will need to know the location to execute the
LAMMPS binary later.
One way of getting the absolute path of the current directory is through the $PWD variable:

# prints out the current value of the PWD variable

echo $PWD

Let us save this value in a temporary variable LAMMPS_BUILD_DIR for future use:

LAMMPS_BUILD_DIR=$PWD

The full path of the LAMMPS binary then is $LAMMPS_BUILD_DIR/lmp.

Running an example script

Now that we have a LAMMPS binary, we will run a script from the examples folder.
Switch into the examples/melt folder:

cd ../examples/melt

To run this example in serial, use the following command line:

$LAMMPS_BUILD_DIR/lmp -in in.melt

To run the same script in parallel using MPI with 4 processes, do the following:

mpirun -np 4 $LAMMPS_BUILD_DIR/lmp -in in.melt

If you run LAMMPS for the first time, the Windows Firewall might prompt you to confirm access. LAMMPS is
accessing the network stack to enable parallel computation. Allow the access.

In either serial or MPI case, LAMMPS executes and will output something similar to this:

LAMMPS (30 Jun 2020)

...
...
...
(continues on next page)

304 Chapter 8. Howto discussions

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

Total # of neighbors = 151513
Ave neighs/atom = 37.878250
Neighbor list builds = 12
Dangerous builds not checked
Total wall time: 0:00:00

Congratulations! You’ve successfully compiled and executed LAMMPS on WSL!

Final steps

It is cumbersome to always specify the path of your LAMMPS binary. You can avoid this by adding the absolute path
of your build directory to your PATH environment variable.

export PATH=$LAMMPS_BUILD_DIR:$PATH

You can then run LAMMPS input scripts like this:

lmp -in in.melt

or

mpirun -np 4 lmp -in in.melt

Note: The value of this PATH variable will disappear once you close your console window. To persist this setting edit
the $HOME/.bashrc file using your favorite text editor and add this line:

export PATH=/full/path/to/your/lammps/build:$PATH

Example: If the LAMMPS executable lmp has the following absolute path:

/home/<USERNAME>/lammps/build/lmp

the PATH variable should be:

export PATH=/home/<USERNAME>/lammps/build:$PATH

Once set up, all your Ubuntu consoles will always have access to your lmp binary without having to specify its location.

Conclusion

I hope this gives you good overview on how to start compiling and running LAMMPS on Windows. WSL makes
preparing and running scripts on Windows a much better experience.
If you are completely new to Linux, I highly recommend investing some time in studying Linux online tutorials. E.g.,
tutorials about Bash Shell and Basic Unix commands (e.g., Linux Journey). Acquiring these skills will make you much
more productive in this environment.
See also:
• Windows Subsystem for Linux Documentation

8.6. Tutorials howto 305

LAMMPS Documentation, Release stable 29Sep2021

306 Chapter 8. Howto discussions

 CHAPTER

NINE

EXAMPLE SCRIPTS

The LAMMPS distribution includes an examples sub-directory with many sample problems. Many are 2d models that
run quickly and are straightforward to visualize, requiring at most a couple of minutes to run on a desktop machine.
Each problem has an input script (in.*) and produces a log file (log.*) when it runs. Some use a data file (data.*)
of initial coordinates as additional input. A few sample log file run on different machines and different numbers of
processors are included in the directories to compare your answers to. E.g. a log file like log.date.crack.foo.P means
the “crack” example was run on P processors of machine “foo” on that date (i.e. with that version of LAMMPS).
Many of the input files have commented-out lines for creating dump files and image files.
If you uncomment the dump command in the input script, a text dump file will be produced, which can be animated by
various visualization programs.
If you uncomment the dump image command in the input script, and assuming you have built LAMMPS with a JPG
library, JPG snapshot images will be produced when the simulation runs. They can be quickly post-processed into a
movie using commands described on the dump image doc page.
Animations of many of the examples can be viewed on the Movies section of the LAMMPS website.
There are two kinds of sub-directories in the examples folder. Lower case named directories contain one or a few simple,
quick-to-run problems. Upper case named directories contain up to several complex scripts that illustrate a particular
kind of simulation method or model. Some of these run for longer times, e.g. to measure a particular quantity.
Lists of both kinds of directories are given below.

9.1 Lowercase directories

accelerate run with various acceleration options (OpenMP, GPU, Phi)

airebo polyethylene with AIREBO potential
atm Axilrod-Teller-Muto potential example
balance dynamic load balancing, 2d system
body body particles, 2d system
cmap CMAP 5-body contributions to CHARMM force field
colloid big colloid particles in a small particle solvent, 2d system
comb models using the COMB potential
controller use of fix controller as a thermostat
coreshell core/shell model using CORESHELL package
crack crack propagation in a 2d solid
deposit deposit atoms and molecules on a surface
dipole point dipolar particles, 2d system
continues on next page

307
LAMMPS Documentation, Release stable 29Sep2021

Table 1 – continued from previous page

dreiding methanol via Dreiding FF
eim NaCl using the EIM potential
ellipse ellipsoidal particles in spherical solvent, 2d system
flow Couette and Poiseuille flow in a 2d channel
friction frictional contact of spherical asperities between 2d surfaces
gcmc Grand Canonical Monte Carlo (GCMC) via the fix gcmc command
granregion use of fix wall/region/gran as boundary on granular particles
hugoniostat Hugoniostat shock dynamics
hyper global and local hyperdynamics of diffusion on Pt surface
indent spherical indenter into a 2d solid
kim use of potentials from the OpenKIM Repository
latte examples for using fix latte for DFTB via the LATTE library
meam MEAM test for SiC and shear (same as shear examples)
melt rapid melt of 3d LJ system
message demos for LAMMPS client/server coupling with the MESSAGE package
micelle self-assembly of small lipid-like molecules into 2d bilayers
min energy minimization of 2d LJ melt
mscg parameterize a multi-scale coarse-graining (MSCG) model
msst MSST shock dynamics
multi multi neighboring for systems with large interaction disparities
nb3b use of non-bonded 3-body harmonic pair style
neb nudged elastic band (NEB) calculation for barrier finding
nemd non-equilibrium MD of 2d sheared system
obstacle flow around two voids in a 2d channel
peptide dynamics of a small solvated peptide chain (5-mer)
peri Peridynamic model of cylinder impacted by indenter
pour pouring of granular particles into a 3d box, then chute flow
prd parallel replica dynamics of vacancy diffusion in bulk Si
python using embedded Python in a LAMMPS input script
qeq use of the QEQ package for charge equilibration
rdf-adf computing radial and angle distribution functions for water
reax RDX and TATB models using the ReaxFF
rerun use of rerun and read_dump commands
rigid rigid bodies modeled as independent or coupled
shear sideways shear applied to 2d solid, with and without a void
snap NVE dynamics for BCC tantalum crystal using SNAP potential
srd stochastic rotation dynamics (SRD) particles as solvent
streitz use of Streitz/Mintmire potential with charge equilibration
tad temperature-accelerated dynamics of vacancy diffusion in bulk Si
threebody regression test input for a variety of manybody potentials
tracker track interactions in LJ melt
vashishta use of the Vashishta potential
voronoi Voronoi tesselation via compute voronoi/atom command

Here is how you can run and visualize one of the sample problems:

cd indent
cp ../../src/lmp_linux . # copy LAMMPS executable to this dir
lmp_linux -in in.indent # run the problem

Running the simulation produces the files dump.indent and log.lammps. You can visualize the dump file of snapshots
with a variety of third-party tools highlighted on the Visualization page of the LAMMPS website.

308 Chapter 9. Example scripts

 LAMMPS Documentation, Release stable 29Sep2021

If you uncomment the dump image line(s) in the input script a series of JPG images will be produced by the run (assum-
ing you built LAMMPS with JPG support; see the Build_settings page for details). These can be viewed individually
or turned into a movie or animated by tools like ImageMagick or QuickTime or various Windows-based tools. See the
dump image page for more details. E.g. this Imagemagick command would create a GIF file suitable for viewing in a
browser.

% convert -loop 1 *.jpg foo.gif

9.2 Uppercase directories

ASPHERE various aspherical particle models, using ellipsoids, rigid bodies, line/triangle particles, etc
COUPLE examples of how to use LAMMPS as a library
DIFFUSE compute diffusion coefficients via several methods
ELASTIC compute elastic constants at zero temperature
ELASTIC_T compute elastic constants at finite temperature
HEAT compute thermal conductivity for LJ and water via fix ehex
KAPPA compute thermal conductivity via several methods
MC using LAMMPS in a Monte Carlo mode to relax the energy of a system
PACKAGES examples for specific packages and contributed commands
SPIN examples for features of the SPIN package
UNITS examples that run the same simulation in lj, real, metal units
VISCOSITY compute viscosity via several methods

Nearly all of these directories have README files which give more details on how to understand and use their contents.
The PACKAGES directory has a large number of sub-directories which correspond by name to specific packages. They
contain scripts that illustrate how to use the command(s) provided in those packages. Many of the sub-directories have
their own README files which give further instructions. See the Packages_details doc page for more info on specific
packages.

9.2. Uppercase directories 309

LAMMPS Documentation, Release stable 29Sep2021

310 Chapter 9. Example scripts

 CHAPTER

TEN

AUXILIARY TOOLS

LAMMPS is designed to be a computational kernel for performing molecular dynamics computations. Additional pre-
and post-processing steps are often necessary to setup and analyze a simulation. A list of such tools can be found on
the LAMMPS webpage at these links:
• Pre/Post processing
• External LAMMPS packages & tools
• Pizza.py toolkit
The last link for Pizza.py is a Python-based tool developed at Sandia which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations.
Additional tools included in the LAMMPS distribution are described on this page.
Note that many users write their own setup or analysis tools or use other existing codes and convert their output to a
LAMMPS input format or vice versa. The tools listed here are included in the LAMMPS distribution as examples of
auxiliary tools. Some of them are not actively supported by the LAMMPS developers, as they were contributed by
LAMMPS users. If you have problems using them, we can direct you to the authors.
The source code for each of these codes is in the tools sub-directory of the LAMMPS distribution. There is a Makefile
(which you may need to edit for your platform) which will build several of the tools which reside in that directory. Most
of them are larger packages in their own sub-directories with their own Makefiles and/or README files.

10.1 Pre-processing tools

amber2lmp ch2lmp chain createatoms drude eam database

eam generate eff ipp micelle2d moltemplate msi2lmp
polybond

10.2 Post-processing tools

amber2lmp binary2txt ch2lmp colvars eff fep

lmp2arc lmp2cfg matlab phonon pymol_asphere python
replica smd spin xmgrace

311
LAMMPS Documentation, Release stable 29Sep2021

10.3 Miscellaneous tools

CMake emacs i-pi kate LAMMPS shell LAMMPS magic patterns for file(1)
Offline build tool singularity SWIG interface vim

10.4 Tool descriptions

10.4.1 amber2lmp tool

The amber2lmp sub-directory contains two Python scripts for converting files back-and-forth between the AMBER
MD code and LAMMPS. See the README file in amber2lmp for more information.
These tools were written by Keir Novik while he was at Queen Mary University of London. Keir is no longer there
and cannot support these tools which are out-of-date with respect to the current LAMMPS version (and maybe with
respect to AMBER as well). Since we don’t use these tools at Sandia, you will need to experiment with them and make
necessary modifications yourself.

10.4.2 binary2txt tool

The file binary2txt.cpp converts one or more binary LAMMPS dump file into ASCII text files. The syntax for running
the tool is

binary2txt file1 file2 ...

which creates file1.txt, file2.txt, etc. This tool must be compiled on a platform that can read the binary file created by
a LAMMPS run, since binary files are not compatible across all platforms.

10.4.3 ch2lmp tool

The ch2lmp sub-directory contains tools for converting files back-and-forth between the CHARMM MD code and
LAMMPS.
They are intended to make it easy to use CHARMM as a builder and as a post-processor for LAMMPS. Using
charmm2lammps.pl, you can convert a PDB file with associated CHARMM info, including CHARMM force field
data, into its LAMMPS equivalent. Support for the CMAP correction of CHARMM22 and later is available as an
option. This tool can also add solvent water molecules and Na+ or Cl- ions to the system. Using lammps2pdb.pl you
can convert LAMMPS atom dumps into PDB files.
See the README file in the ch2lmp sub-directory for more information.
These tools were created by Pieter in’t Veld (pjintve at sandia.gov) and Paul Crozier (pscrozi at sandia.gov) at Sandia.
CMAP support added and tested by Xiaohu Hu (hux2 at ornl.gov) and Robert A. Latour (latourr at clemson.edu), David
Hyde-Volpe, and Tigran Abramyan, (Clemson University) and Chris Lorenz (chris.lorenz at kcl.ac.uk), King’s College
London.

312 Chapter 10. Auxiliary tools

 LAMMPS Documentation, Release stable 29Sep2021

10.4.4 chain tool

The file chain.f90 creates a LAMMPS data file containing bead-spring polymer chains and/or monomer solvent atoms.
It uses a text file containing chain definition parameters as an input. The created chains and solvent atoms can strongly
overlap, so LAMMPS needs to run the system initially with a “soft” pair potential to un-overlap it. The syntax for
running the tool is

chain < def.chain > data.file

See the def.chain or def.chain.ab files in the tools directory for examples of definition files. This tool was used to create
the system for the chain benchmark.

10.4.5 CMake tools

The cmbuild script is a wrapper around using cmake --build <dir> --target and allows compiling LAMMPS
in a CMake build folder with a make-like syntax regardless of the actual build tool and the specific name of the program
used (e.g. ninja-v1.10 or gmake) when using -D CMAKE_MAKE_PROGRAM=<name>.

Usage: cmbuild [-v] [-h] [-C <dir>] [-j <num>] [<target>]

Options:
-h print this message
-j <NUM> allow processing of NUM concurrent tasks
-C DIRECTORY execute build in folder DIRECTORY
-v produce verbose output

10.4.6 colvars tools

The colvars directory contains a collection of tools for post-processing data produced by the colvars collective variable
library. To compile the tools, edit the makefile for your system and run “make”.
Please report problems and issues the colvars library and its tools at: https://github.com/colvars/colvars/issues
abf_integrate:
MC-based integration of multidimensional free energy gradient Version 20110511
./abf_integrate < filename > [-n < nsteps >] [-t < temp >] [-m [0|1] (metadynamics)] [-h
,→< hill_height >] [-f < variable_hill_factor >]

The LAMMPS interface to the colvars collective variable library, as well as these tools, were created by Axel Kohlmeyer
(akohlmey at gmail.com) while at ICTP, Italy.

10.4. Tool descriptions 313

LAMMPS Documentation, Release stable 29Sep2021

10.4.7 createatoms tool

The tools/createatoms directory contains a Fortran program called createAtoms.f which can generate a variety of inter-
esting crystal structures and geometries and output the resulting list of atom coordinates in LAMMPS or other formats.
See the included Manual.pdf for details.
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov.

10.4.8 drude tool

The tools/drude directory contains a Python script called polarizer.py which can add Drude oscillators to a LAMMPS
data file in the required format.
See the header of the polarizer.py file for details.
The tool is authored by Agilio Padua and Alain Dequidt: agilio.padua at ens-lyon.fr, alain.dequidt at uca.fr

10.4.9 eam database tool

The tools/eam_database directory contains a Fortran program that will generate EAM alloy setfl potential files for any
combination of 16 elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti, Zr. The files can then be used
with the pair_style eam/alloy command.
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov, and is based on his paper:
X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69, 144113 (2004).

10.4.10 eam generate tool

The tools/eam_generate directory contains several one-file C programs that convert an analytic formula into a tabulated
embedded atom method (EAM) setfl potential file. The potentials they produce are in the potentials directory, and can
be used with the pair_style eam/alloy command.
The source files and potentials were provided by Gerolf Ziegenhain (gerolf at ziegenhain.com).

10.4.11 eff tool

The tools/eff directory contains various scripts for generating structures and post-processing output for simulations
using the electron force field (eFF).
These tools were provided by Andres Jaramillo-Botero at CalTech (ajaramil at wag.caltech.edu).

314 Chapter 10. Auxiliary tools

 LAMMPS Documentation, Release stable 29Sep2021

10.4.12 emacs tool

The tools/emacs directory contains an Emacs Lisp add-on file for GNU Emacs that enables a lammps-mode for editing
input scripts when using GNU Emacs, with various highlighting options set up.
These tools were provided by Aidan Thompson at Sandia (athomps at sandia.gov).

10.4.13 fep tool

The tools/fep directory contains Python scripts useful for post-processing results from performing free-energy pertur-
bation simulations using the FEP package.
The scripts were contributed by Agilio Padua (ENS de Lyon), agilio.padua at ens-lyon.fr.
See README file in the tools/fep directory.

10.4.14 i-pi tool

The tools/i-pi directory contains a version of the i-PI package, with all the LAMMPS-unrelated files removed. It is
provided so that it can be used with the fix ipi command to perform path-integral molecular dynamics (PIMD).
The i-PI package was created and is maintained by Michele Ceriotti, michele.ceriotti at gmail.com, to interface to a
variety of molecular dynamics codes.
See the tools/i-pi/manual.pdf file for an overview of i-PI, and the fix ipi page for further details on running PIMD
calculations with LAMMPS.

10.4.15 ipp tool

The tools/ipp directory contains a Perl script ipp which can be used to facilitate the creation of a complicated file (say,
a lammps input script or tools/createatoms input file) using a template file.
ipp was created and is maintained by Reese Jones (Sandia), rjones at sandia.gov.
See two examples in the tools/ipp directory. One of them is for the tools/createatoms tool’s input file.

10.4.16 kate tool

The file in the tools/kate directory is an add-on to the Kate editor in the KDE suite that allow syntax highlighting of
LAMMPS input scripts. See the README.txt file for details.
The file was provided by Alessandro Luigi Sellerio (alessandro.sellerio at ieni.cnr.it).

10.4. Tool descriptions 315

LAMMPS Documentation, Release stable 29Sep2021

10.4.17 LAMMPS shell

New in version 9Oct2020.

Overview

The LAMMPS Shell, lammps-shell is a program that functions very similar to the regular LAMMPS executable
but has several modifications and additions that make it more powerful for interactive sessions, i.e. where you type
LAMMPS commands from the prompt instead of reading them from a file.
• It uses the readline and history libraries to provide command line editing and context aware TAB-expansion
(details on that below).
• When processing an input file with the ‘-in’ or ‘-i’ flag from the command line, it does not exit at the end of that
input file but stops at a prompt, so that additional commands can be issued
• Errors will not abort the shell but return to the prompt.
• It has additional commands aimed at interactive use (details below).
• Interrupting a calculation with CTRL-C will not terminate the session but rather enforce a timeout to cleanly
stop an ongoing run (more info on timeouts is in the timer command documentation).
These enhancements make the LAMMPS shell an attractive choice for interactive LAMMPS sessions in graphical
desktop environments (e.g. Gnome, KDE, Cinnamon, XFCE, Windows).

TAB-expansion

When writing commands interactively at the shell prompt, you can hit the TAB key at any time to try and complete the
text. This completion is context aware and will expand any first word only to commands available in that executable.
• For style commands it will expand to available styles of the corresponding category (e.g. pair styles after a
pair_style command).
• For compute, fix, or dump it will also expand only to already defined groups for the group-ID keyword.
• For commands like compute_modify, fix_modify, or dump_modify it will expand to known compute/fix/dump
IDs only.
• When typing references to computes, fixes, or variables with a “c_”, “f_”, or “v_” prefix, respectively, then the
expansion will be to known compute/fix IDs and variable names. Variable name expansion is also available for
the ${name} variable syntax.
• In all other cases TAB expansion will complete to names of files and directories.

Command line editing and history

When typing commands, command line editing similar to what BASH provides is available. Thus it is possible to move
around the currently line and perform various cut and insert and edit operations. Previous commands can be retrieved
by scrolling up (and down) or searching (e.g. with CTRL-r).
Also history expansion through using the exclamation mark ‘!’ can be performed. Examples: ‘!!’ will be replaced
with the previous command, ‘!-2’ will repeat the command before that, ‘!30’ will be replaced with event number 30
in the command history list, and ‘!run’ with the last command line that started with “run”. Adding a “:p” to such a
history expansion will result that the expansion is printed and added to the history list, but NOT executed. On exit the
LAMMPS shell will write the history list to a file “.lammps_history” in the current working directory. If such a file
exists when the LAMMPS shell is launched it will be read to populate the history list.

316 Chapter 10. Auxiliary tools

 LAMMPS Documentation, Release stable 29Sep2021

This is realized via the readline library and can thus be customized with an .inputrc file in the home directory. For
application specific customization, the LAMMPS shell uses the name “lammps-shell”. For more information about
using and customizing an application using readline, please see the available documentation at: http://www.gnu.org/s/
readline/#Documentation

Additional commands

The following commands are added to the LAMMPS shell on top of the regular LAMMPS commands:
help (or ?) print a brief help message
history display the current command history list
clear_history wipe out the current command history list
save_history <range> <file>
write commands from the history to file.
The range is given as <from>-<to>, where <from> and <to>
may be empty. Example: save_history 100- in.recent
source <file> read commands from file (same as "include")
pwd print current working directory
cd <directory> change current working directory (same as pwd if no directory)
mem print current and maximum memory usage
|<command> execute <command> as a shell command and return to the command prompt
exit exit the LAMMPS shell cleanly (unlike the "quit" command)
Please note that some known shell operations are implemented in the LAMMPS shell command in a platform neutral
fashion, while using the ‘|’ character will always pass the following text to the operating system’s shell command.

Compilation

Compilation of the LAMMPS shell can be enabled by setting the CMake variable BUILD_LAMMPS_SHELL to “on”
or using the makefile in the tools/lammps-shell folder to compile after building LAMMPS using the conventional
make procedure. The makefile will likely need customization depending on the features and settings used for compiling
LAMMPS.

Limitations

The LAMMPS shell was not designed for use with MPI parallelization via mpirun or mpiexec or srun.

Readline customization

The behavior of the readline functionality can be customized in the ${HOME}/.inputrc file. This can be used to alter
the default settings or change the key-bindings. The LAMMPS Shell sets the application name lammps-shell, so
settings can be either applied globally or only for the LAMMPS shell by bracketing them between $if lammps-shell
and $endif like in the following example:

$if lammps-shell
# disable "beep" or "screen flash"
set bell-style none
# bind the "Insert" key to toggle overwrite mode
"\e[2~": overwrite-mode
$endif

More details about this are in the readline documentation.

10.4. Tool descriptions 317

LAMMPS Documentation, Release stable 29Sep2021

LAMMPS Shell tips and tricks

Below are some suggestions for how to use and customize the LAMMPS shell.

Enable tilde expansion

Adding set expand-tilde on to ${HOME}/.inputrc is recommended as this will change the filename expansion
behavior to replace any text starting with “~” by the full path to the corresponding user’s home directory. While the
expansion of filenames will happen on all arguments where the context is not known (e.g. ~/compile/lamm<TAB>
will expand to ~/compile/lammps/), it will not replace the tilde by default. But since LAMMPS does not do tilde
expansion itself (unlike a shell), this will result in errors. Instead the tilde-expression should be expanded into a valid
path, where the plain “~/” stands for the current user’s home directory and “~someuser/” stands for “/home/someuser”
or whatever the full path to that user’s home directory is.

File extension association

Since the LAMMPS shell (unlike the regular LAMMPS executable) does not exit when an input file is passed on the
command line with the “-in” or “-i” flag (the behavior is like for python -i <filename>), it makes the LAMMPS
shell suitable for associating it with input files based on their filename extension (e.g. “.lmp”). Since lammps-shell
is a console application, you have to run it inside a terminal program with a command line like this:

xterm -title "LAMMPS Shell" -e /path/to/lammps-shell -i in.file.lmp

Use history to create an input file

When experimenting with commands to interactively to figure out a suitable choice of settings or simply the correct
syntax, you may want to record part of your commands to a file for later use. This can be done with the save_history
commands, which allows to selectively write a section of the command history to a file (Example: save_history
25-30 in.run). This file can be further edited (Example: |vim in.run) and then the file read back in and tried out
(Example: source in.run). If the input also creates a system box, you first need to use the clear command command.

10.4.18 lmp2arc tool

The lmp2arc sub-directory contains a tool for converting LAMMPS output files to the format for Accelrys’ Insight MD
code (formerly MSI/Biosym and its Discover MD code). See the README file for more information.
This tool was written by John Carpenter (Cray), Michael Peachey (Cray), and Steve Lustig (Dupont). John is now at
the Mayo Clinic (jec at mayo.edu), but still fields questions about the tool.
This tool was updated for the current LAMMPS C++ version by Jeff Greathouse at Sandia (jagreat at sandia.gov).

318 Chapter 10. Auxiliary tools

 LAMMPS Documentation, Release stable 29Sep2021

10.4.19 lmp2cfg tool

The lmp2cfg sub-directory contains a tool for converting LAMMPS output files into a series of *.cfg files which can
be read into the AtomEye visualizer. See the README file for more information.
This tool was written by Ara Kooser at Sandia (askoose at sandia.gov).

10.4.20 Magic patterns for the “file” command

New in version 10Mar2021.

The file magic contains patterns that are used by the file program available on most Unix-like operating systems which
enables it to detect various LAMMPS files and print some useful information about them. To enable these patterns,
append or copy the contents of the file to either the file .magic in your home directory or (as administrator) to /
etc/magic (for a system-wide installation). Afterwards the file command should be able to detect most LAMMPS
restarts, dump, data and log files. Examples:

$ file *.*
dihedral-quadratic.restart: LAMMPS binary restart file (rev 2), Version 10 Mar 2021,␣
,→Little Endian

mol-pair-wf_cut.restart: LAMMPS binary restart file (rev 2), Version 24 Dec 2020,␣
,→Little Endian

atom.bin: LAMMPS atom style binary dump (rev 2), Little Endian,␣
,→First time step: 445570

custom.bin: LAMMPS custom style binary dump (rev 2), Little Endian,␣
,→First time step: 100

bn1.lammpstrj: LAMMPS text mode dump, First time step: 5000

data.fourmol: LAMMPS data file written by LAMMPS
pnc.data: LAMMPS data file written by msi2lmp
data.spce: LAMMPS data file written by TopoTools
B.data: LAMMPS data file written by OVITO
log.lammps: LAMMPS log file written by version 10 Feb 2021

10.4.21 matlab tool

The matlab sub-directory contains several MATLAB scripts for post-processing LAMMPS output. The scripts include
readers for log and dump files, a reader for EAM potential files, and a converter that reads LAMMPS dump files and
produces CFG files that can be visualized with the AtomEye visualizer.
See the README.pdf file for more information.
These scripts were written by Arun Subramaniyan at Purdue Univ (asubrama at purdue.edu).

10.4. Tool descriptions 319

LAMMPS Documentation, Release stable 29Sep2021

10.4.22 micelle2d tool

The file micelle2d.f creates a LAMMPS data file containing short lipid chains in a monomer solution. It uses a text
file containing lipid definition parameters as an input. The created molecules and solvent atoms can strongly overlap,
so LAMMPS needs to run the system initially with a “soft” pair potential to un-overlap it. The syntax for running the
tool is

micelle2d < def.micelle2d > data.file

See the def.micelle2d file in the tools directory for an example of a definition file. This tool was used to create the
system for the micelle example.

10.4.23 moltemplate tool

The moltemplate sub-directory contains instructions for installing moltemplate, a Python-based tool for building molec-
ular systems based on a text-file description, and creating LAMMPS data files that encode their molecular topology as
lists of bonds, angles, dihedrals, etc. See the README.txt file for more information.
This tool was written by Andrew Jewett (jewett.aij at gmail.com), who supports it. It has its own WWW page at
https://moltemplate.org. The latest sources can be found on its GitHub page

10.4.24 msi2lmp tool

The msi2lmp sub-directory contains a tool for creating LAMMPS template input and data files from BIOVIA’s Materias
Studio files (formerly Accelrys’ Insight MD code, formerly MSI/Biosym and its Discover MD code).
This tool was written by John Carpenter (Cray), Michael Peachey (Cray), and Steve Lustig (Dupont). Several people
contributed changes to remove bugs and adapt its output to changes in LAMMPS.
This tool has several known limitations and is no longer under active development, so there are no changes except for
the occasional bug fix.
See the README file in the tools/msi2lmp folder for more information.

10.4.25 Scripts for building LAMMPS when offline

In some situations it might be necessary to build LAMMPS on a system without direct internet access. The scripts in
tools/offline folder allow you to pre-load external dependencies for both the documentation build and for building
LAMMPS with CMake.
It does so by
1. downloading necessary pip packages,
2. cloning git repositories
3. downloading tarballs

320 Chapter 10. Auxiliary tools

 LAMMPS Documentation, Release stable 29Sep2021

to a designated cache folder.

As of April 2021, all of these downloads make up around 600MB. By default, the offline scripts will download every-
thing into the $HOME/.cache/lammps folder, but this can be changed by setting the LAMMPS_CACHING_DIR environ-
ment variable.
Once the caches have been initialized, they can be used for building the LAMMPS documentation or compiling
LAMMPS using CMake on an offline system.
The use_caches.sh script must be sourced into the current shell to initialize the offline build environment. Note that
it must use the same LAMMPS_CACHING_DIR. This script does the following:
1. Set up environment variables that modify the behavior of both, pip and git
2. Start a simple local HTTP server using Python to host files for CMake
Afterwards, it will print out instruction on how to modify the CMake command line to make sure it uses the local HTTP
server.
To undo the environment changes and shutdown the local HTTP server, run the deactivate_caches command.

Examples

For all of the examples below, you first need to create the cache, which requires an internet connection.

./tools/offline/init_caches.sh

Afterwards, you can disconnect or copy the contents of the LAMMPS_CACHING_DIR folder to an offline system.

Documentation Build

The documentation build will create a new virtual environment that typically first installs dependencies from pip. With
the offline environment loaded, these installations will instead grab the necessary packages from your local cache.

# if LAMMPS_CACHING_DIR is different from default, make sure to set it first

# export LAMMPS_CACHING_DIR=path/to/folder
source tools/offline/use_caches.sh
cd doc/
make html

deactivate_caches

CMake Build

When compiling certain packages with external dependencies, the CMake build system will download necessary files
or sources from the web. For more flexibility the CMake configuration allows users to specify the URL of each of these
dependencies. What the init_caches.sh script does is create a CMake “preset” file, which sets the URLs for all of
the known dependencies and redirects the download to the local cache.

# if LAMMPS_CACHING_DIR is different from default, make sure to set it first

# export LAMMPS_CACHING_DIR=path/to/folder
source tools/offline/use_caches.sh

mkdir build
cd build
(continues on next page)

10.4. Tool descriptions 321

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../
,→cmake/presets/most.cmake ../cmake

make -j 8

deactivate_caches

10.4.26 phonon tool

The phonon sub-directory contains a post-processing tool useful for analyzing the output of the fix phonon command
in the PHONON package.
See the README file for instruction on building the tool and what library it needs. And see the exam-
ples/PACKAGES/phonon directory for example problems that can be post-processed with this tool.
This tool was written by Ling-Ti Kong at Shanghai Jiao Tong University.

10.4.27 polybond tool

The polybond sub-directory contains a Python-based tool useful for performing “programmable polymer bonding”.
The Python file lmpsdata.py provides a “Lmpsdata” class with various methods which can be invoked by a user-written
Python script to create data files with complex bonding topologies.
See the Manual.pdf for details and example scripts.
This tool was written by Zachary Kraus at Georgia Tech.

10.4.28 pymol_asphere tool

The pymol_asphere sub-directory contains a tool for converting a LAMMPS dump file that contains orientation info
for ellipsoidal particles into an input file for the PyMol visualization package or its open source variant.
Specifically, the tool triangulates the ellipsoids so they can be viewed as true ellipsoidal particles within PyMol. See
the README and examples directory within pymol_asphere for more information.
This tool was written by Mike Brown at Sandia.

10.4.29 python tool

The python sub-directory contains several Python scripts that perform common LAMMPS post-processing tasks, such
as:
• extract thermodynamic info from a log file as columns of numbers
• plot two columns of thermodynamic info from a log file using GnuPlot
• sort the snapshots in a dump file by atom ID

322 Chapter 10. Auxiliary tools

 LAMMPS Documentation, Release stable 29Sep2021

• convert multiple NEB dump files into one dump file for viz
• convert dump files into XYZ, CFG, or PDB format for viz by other packages
These are simple scripts built on Pizza.py modules. See the README for more info on Pizza.py and how to use these
scripts.

10.4.30 replica tool

The tools/replica directory contains the reorder_remd_traj python script which can be used to reorder the replica tra-
jectories (resulting from the use of the temper command) according to temperature. This will produce discontinu-
ous trajectories with all frames at the same temperature in each trajectory. Additional options can be used to calcu-
late the canonical configurational log-weight for each frame at each temperature using the pymbar package. See the
README.md file for further details. Try out the peptide example provided.
This tool was written by (and is maintained by) Tanmoy Sanyal, while at the Shell lab at UC Santa Barbara. (tanmoy
dot 7989 at gmail.com)

10.4.31 smd tool

The smd sub-directory contains a C++ file dump2vtk_tris.cpp and Makefile which can be compiled and used to convert
triangle output files created by the Smooth-Mach Dynamics (MACHDYN) package into a VTK-compatible unstruc-
tured grid file. It could then be read in and visualized by VTK.
See the header of dump2vtk.cpp for more details.
This tool was written by the MACHDYN package author, Georg Ganzenmuller at the Fraunhofer-Institute for High-
Speed Dynamics, Ernst Mach Institute in Germany (georg.ganzenmueller at emi.fhg.de).

10.4.32 spin tool

The spin sub-directory contains a C file interpolate.c which can be compiled and used to perform a cubic polynomial
interpolation of the MEP following a GNEB calculation.
See the README file in tools/spin/interpolate_gneb for more details.
This tool was written by the SPIN package author, Julien Tranchida at Sandia National Labs (jtranch at sandia.gov, and
by Aleksei Ivanov, at University of Iceland (ali5 at hi.is).

10.4.33 singularity tool

The singularity sub-directory contains container definitions files that can be used to build container images for building
and testing LAMMPS on specific OS variants using the Singularity container software. Contributions for additional
variants are welcome. For more details please see the README.md file in that folder.

10.4. Tool descriptions 323

LAMMPS Documentation, Release stable 29Sep2021

10.4.34 SWIG interface

The SWIG tool offers a mostly automated way to incorporate compiled code modules into scripting languages. It
processes the function prototypes in C and generates wrappers for a wide variety of scripting languages from it. Thus
it can also be applied to the C language library interface of LAMMPS so that build a wrapper that allows to call
LAMMPS from programming languages like: C#/Mono, Lua, Java, JavaScript, Perl, Python, R, Ruby, Tcl, and more.

What is included

We provide here an “interface file”, lammps.i, that has the content of the library.h file adapted so SWIG can process
it. That will create wrappers for all the functions that are present in the LAMMPS C library interface. Please note that
not all kinds of C functions can be automatically translated, so you would have to add custom functions to be able to
utilize those where the automatic translation does not work. A few functions for converting pointers and accessing
arrays are predefined. We provide the file here on an “as is” basis to help people getting started, but not as a fully
tested and supported feature of the LAMMPS distribution. Any contributions to complete this are, of course, welcome.
Please also note, that for the case of creating a Python wrapper, a fully supported Ctypes based lammps module already
exists. That module is designed to be object oriented while SWIG will generate a 1:1 translation of the functions in the
interface file.

Building the wrapper

When using CMake, the build steps for building a wrapper module are integrated for the languages: Java, Lua, Perl5,
Python, Ruby, and Tcl. These require that the LAMMPS library is build as a shared library and all necessary develop-
ment headers and libraries are present.

-D WITH_SWIG=on # to enable building any SWIG wrapper

-D BUILD_SWIG_JAVA=on # to enable building the Java wrapper
-D BUILD_SWIG_LUA=on # to enable building the Lua wrapper
-D BUILD_SWIG_PERL5=on # to enable building the Perl 5.x wrapper
-D BUILD_SWIG_PYTHON=on # to enable building the Python wrapper
-D BUILD_SWIG_RUBY=on # to enable building the Ruby wrapper
-D BUILD_SWIG_TCL=on # to enable building the Tcl wrapper

Manual building allows a little more flexibility. E.g. one can choose the name of the module and build and use a
dynamically loaded object for Tcl with:

$ swig -tcl -module tcllammps lammps.i

$ gcc -fPIC -shared $(pkgconf --cflags tcl) -o tcllammps.so \
lammps_wrap.c -L ../src/ -llammps
$ tclsh

Or one can build an extended Tcl shell command with the wrapped functions included with:

$ swig -tcl -module tcllmps lammps_shell.i

$ gcc -o tcllmpsh lammps_wrap.c -Xlinker -export-dynamic \
-DHAVE_CONFIG_H $(pkgconf --cflags tcl) \
$(pkgconf --libs tcl) -L ../src -llammps

In both cases it is assumed that the LAMMPS library was compiled as a shared library in the src folder. Otherwise
the last part of the commands needs to be adjusted.

324 Chapter 10. Auxiliary tools

 LAMMPS Documentation, Release stable 29Sep2021

Utility functions

Definitions for several utility functions required to manage and access data passed or returned as pointers are included
in the lammps.i file. So most of the functionality of the library interface should be accessible. What works and what
does not depends a bit on the individual language for which the wrappers are built and how well SWIG supports those.
The SWIG documentation has very detailed instructions and recommendations.

Usage examples

The tools/swig folder has multiple shell scripts, run_<name>_example.sh that will create a small example script
and demonstrate how to load the wrapper and run LAMMPS through it in the corresponding programming language.
For illustration purposes below is a part of the Tcl example script.

% load ./tcllammps.so
% set lmp [lammps_open_no_mpi 0 NULL NULL]
% lammps_command $lmp "units real"
% lammps_command $lmp "lattice fcc 2.5"
% lammps_command $lmp "region box block -5 5 -5 5 -5 5"
% lammps_command $lmp "create_box 1 box"
% lammps_command $lmp "create_atoms 1 box"
%
% set dt [doublep_value [voidp_to_doublep [lammps_extract_global $lmp dt]]]
% puts "LAMMPS version $ver"
% puts [format "Number of created atoms: %g" [lammps_get_natoms $lmp]]
% puts "Current size of timestep: $dt"
% puts "LAMMPS version: [lammps_version $lmp]"
% lammps_close $lmp

10.4.35 vim tool

The files in the tools/vim directory are add-ons to the VIM editor that allow easier editing of LAMMPS input scripts.
See the README.txt file for details.
These files were provided by Gerolf Ziegenhain (gerolf at ziegenhain.com)

10.4.36 xmgrace tool

The files in the tools/xmgrace directory can be used to plot the thermodynamic data in LAMMPS log files via the
xmgrace plotting package. There are several tools in the directory that can be used in post-processing mode. The
lammpsplot.cpp file can be compiled and used to create plots from the current state of a running LAMMPS simulation.
See the README file for details.
These files were provided by Vikas Varshney (vv0210 at gmail.com)

10.4. Tool descriptions 325

LAMMPS Documentation, Release stable 29Sep2021

326 Chapter 10. Auxiliary tools

 CHAPTER

ELEVEN

ERRORS

These doc pages describe many of the error and warning message you can encounter when using LAMMPS. The
common problems include conceptual issues. The messages and warnings doc pages give complete lists of all the
messages the code may generate, with additional details for many of them.

11.1 Common problems

If two LAMMPS runs do not produce the exact same answer on different machines or different numbers of processors,
this is typically not a bug. In theory you should get identical answers on any number of processors and on any machine.
In practice, numerical round-off can cause slight differences and eventual divergence of molecular dynamics phase
space trajectories within a few 100s or few 1000s of timesteps. However, the statistical properties of the two runs (e.g.
average energy or temperature) should still be the same.
If the velocity command is used to set initial atom velocities, a particular atom can be assigned a different velocity
when the problem is run on a different number of processors or on different machines. If this happens, the phase space
trajectories of the two simulations will rapidly diverge. See the discussion of the loop option in the velocity command
for details and options that avoid this issue.
Similarly, the create_atoms command generates a lattice of atoms. For the same physical system, the ordering and
numbering of atoms by atom ID may be different depending on the number of processors.
Some commands use random number generators which may be setup to produce different random number streams on
each processor and hence will produce different effects when run on different numbers of processors. A commonly-used
example is the fix langevin command for thermostatting.
A LAMMPS simulation typically has two stages, setup and run. Most LAMMPS errors are detected at setup time;
others like a bond stretching too far may not occur until the middle of a run.
LAMMPS tries to flag errors and print informative error messages so you can fix the problem. For most errors it will
also print the last input script command that it was processing. Of course, LAMMPS cannot figure out your physics or
numerical mistakes, like choosing too big a timestep, specifying erroneous force field coefficients, or putting 2 atoms
on top of each other! If you run into errors that LAMMPS does not catch that you think it should flag, please send an
email to the developers.
If you get an error message about an invalid command in your input script, you can determine what command is causing
the problem by looking in the log.lammps file or using the echo command to see it on the screen. If you get an error
like “Invalid . . . style”, with . . . being fix, compute, pair, etc, it means that you mistyped the style name or that the
command is part of an optional package which was not compiled into your executable. The list of available styles
in your executable can be listed by using the -h command-line switch. The installation and compilation of optional
packages is explained on the Build packages doc page.
For a given command, LAMMPS expects certain arguments in a specified order. If you mess this up, LAMMPS will
often flag the error, but it may also simply read a bogus argument and assign a value that is valid, but not what you
wanted. E.g. trying to read the string “abc” as an integer value of 0. Careful reading of the associated doc page for the

327
LAMMPS Documentation, Release stable 29Sep2021

command should allow you to fix these problems. In most cases, where LAMMPS expects to read a number, either
integer or floating point, it performs a stringent test on whether the provided input actually is an integer or floating-
point number, respectively, and reject the input with an error message (for instance, when an integer is required, but a
floating-point number 1.0 is provided):

ERROR: Expected integer parameter instead of '1.0' in input script or data file

Some commands allow for using variable references in place of numeric constants so that the value can be evaluated
and may change over the course of a run. This is typically done with the syntax v_name for a parameter, where name
is the name of the variable. On the other hand, immediate variable expansion with the syntax ${name} is performed
while reading the input and before parsing commands,

Note: Using a variable reference (i.e. v_name) is only allowed if the documentation of the corresponding command
explicitly says it is. Otherwise, you will receive an error message of this kind:

ERROR: Expected floating point parameter instead of 'v_name' in input script or data file

Generally, LAMMPS will print a message to the screen and logfile and exit gracefully when it encounters a fatal error.
Sometimes it will print a WARNING to the screen and logfile and continue on; you can decide if the WARNING is
important or not. A WARNING message that is generated in the middle of a run is only printed to the screen, not to
the logfile, to avoid cluttering up thermodynamic output. If LAMMPS crashes or hangs without spitting out an error
message first then it could be a bug (see this section) or one of the following cases:
LAMMPS runs in the available memory a processor allows to be allocated. Most reasonable MD runs are compute
limited, not memory limited, so this should not be a bottleneck on most platforms. Almost all large memory allocations
in the code are done via C-style malloc’s which will generate an error message if you run out of memory. Smaller chunks
of memory are allocated via C++ “new” statements. If you are unlucky you could run out of memory just when one of
these small requests is made, in which case the code will crash or hang (in parallel), since LAMMPS does not trap on
those errors.
Illegal arithmetic can cause LAMMPS to run slow or crash. This is typically due to invalid physics and numerics
that your simulation is computing. If you see wild thermodynamic values or NaN values in your LAMMPS output,
something is wrong with your simulation. If you suspect this is happening, it is a good idea to print out thermodynamic
info frequently (e.g. every timestep) via the thermo so you can monitor what is happening. Visualizing the atom
movement is also a good idea to insure your model is behaving as you expect.
In parallel, one way LAMMPS can hang is due to how different MPI implementations handle buffering of messages.
If the code hangs without an error message, it may be that you need to specify an MPI setting or two (usually via an
environment variable) to enable buffering or boost the sizes of messages that can be buffered.

11.2 Reporting bugs

If you are confident that you have found a bug in LAMMPS, please follow the steps outlined below:
• Check the New features and bug fixes section of the LAMMPS WWW site or the GitHub Releases page to see
if the bug has already been addressed in a patch release.
• Check that your issue can be reproduced with the latest development version of LAMMPS.
• Check the manual carefully to verify that the unexpected behavior you are observing is indeed in conflict with
the documentation
• Check the GitHub Issue page if your issue has already been reported and if it is still open.
• Check the GitHub Pull Requests page to see if there is already a fix for your bug pending.

328 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

• Check the mailing list archives or the LAMMPS forum to see if the issue has been discussed before.
If none of these steps yields any useful information, please file a new bug report on the GitHub Issue page. The website
will offer you to select a suitable template with explanations and then you should replace those explanations with the
information that you can provide to reproduce your issue.
The most useful thing you can do to help us verify and fix a bug is to isolate the problem. Run it on the smallest number
of atoms and fewest number of processors with the simplest input script that reproduces the bug. Try to identify what
command or combination of commands is causing the problem and upload the complete input deck as a tar or zip
archive. Please avoid using binary restart files unless the issue requires it. In the latter case you should also include
an input deck to quickly generate this restart from a data file or a simple additional input. This input deck can be used
with tools like a debugger or valgrind to further debug the crash.
You may also send an email to the LAMMPS mailing list at “lammps-users at lists.sourceforge.net” describing the
problem with the same kind of information. The mailing list can provide a faster response, especially if the bug
reported is actually expected behavior. But because of the high volume of the mailing list, it can happen that your
e-mail is overlooked and then forgotten. Issues on GitHub have to be explicitly closed, so that will guarantee that at
least one LAMMPS developer will have looked at it.

11.3 Debugging crashes

If LAMMPS crashes with a “segmentation fault” or a “bus error” or similar message, then you can use the following
two methods to further narrow down the origin of the issue. This will help the LAMMPS developers (or yourself) to
understand the reason for the crash and apply a fix (either to the input script or the source code). This requires that
your LAMMPS executable includes the required debug information. Otherwise it is not possible to look up the names
of functions or variables.
The following patch will introduce a bug into the code for pair style lj/cut when using the examples/melt/in.melt
input. We use it to show how to identify the origin of a segmentation fault.

--- a/src/pair_lj_cut.cpp
+++ b/src/pair_lj_cut.cpp
@@ -81,6 +81,7 @@ void PairLJCut::compute(int eflag, int vflag)
int nlocal = atom->nlocal;
double *special_lj = force->special_lj;
int newton_pair = force->newton_pair;
+ double comx = 0.0;

inum = list->inum;
ilist = list->ilist;
@@ -134,8 +135,10 @@ void PairLJCut::compute(int eflag, int vflag)
evdwl,0.0,fpair,delx,dely,delz);
}
}
- }

+ comx += atom->rmass[i]*x[i][0]; /* BUG */

+ }
+ printf("comx = %g\n",comx);
if (vflag_fdotr) virial_fdotr_compute();
}

After recompiling LAMMPS and running the input you should get something like this:

11.3. Debugging crashes 329

LAMMPS Documentation, Release stable 29Sep2021

$ ./lmp -in in.melt

LAMMPS (19 Mar 2020)
using 1 OpenMP thread(s) per MPI task
Lattice spacing in x,y,z = 1.6796 1.6796 1.6796
Created orthogonal box = (0 0 0) to (16.796 16.796 16.796)
1 by 1 by 1 MPI processor grid
Created 4000 atoms
create_atoms CPU = 0.000432253 secs
Neighbor list info ...
update every 20 steps, delay 0 steps, check no
max neighbors/atom: 2000, page size: 100000
master list distance cutoff = 2.8
ghost atom cutoff = 2.8
binsize = 1.4, bins = 12 12 12
1 neighbor lists, perpetual/occasional/extra = 1 0 0
(1) pair lj/cut, perpetual
attributes: half, newton on
pair build: half/bin/atomonly/newton
stencil: half/bin/3d/newton
bin: standard
Setting up Verlet run ...
Unit style : lj
Current step : 0
Time step : 0.005
Segmentation fault (core dumped)

11.3.1 Using the GDB debugger to get a stack trace

There are two options to use the GDB debugger for identifying the origin of the segmentation fault or similar crash.
The GDB debugger has many more features and options, as can be seen for example its online documentation.

Run LAMMPS from within the debugger

Running LAMMPS under the control of the debugger as shown below only works for a single MPI rank (for debugging
a program running in parallel you usually need a parallel debugger program). A simple way to launch GDB is to prefix
the LAMMPS command line with gdb --args and then type the command “run” at the GDB prompt. This will launch
the debugger, load the LAMMPS executable and its debug info, and then run it. When it reaches the code causing the
segmentation fault, it will stop with a message why it stopped, print the current line of code, and drop back to the GDB
prompt.

[...]
Setting up Verlet run ...
Unit style : lj
Current step : 0
Time step : 0.005

Program received signal SIGSEGV, Segmentation fault.

0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=
,→<optimized out>) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139

139 comx += atom->rmass[i]*x[i][0]; /* BUG */

(gdb)

330 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Now typing the command “where” will show the stack of functions starting from the current function back to “main()”.
(gdb) where
#0 0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=
,→<optimized out>) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139

#1 0x00000000004cf0a2 in LAMMPS_NS::Verlet::setup (this=0x7e6c90, flag=1) at /home/

,→akohlmey/compile/lammps/src/verlet.cpp:131

#2 0x000000000049db42 in LAMMPS_NS::Run::command (this=this@entry=0x7fffffffcca0,␣

,→narg=narg@entry=1, arg=arg@entry=0x7e8750)

at /home/akohlmey/compile/lammps/src/run.cpp:177
#3 0x000000000041258a in LAMMPS_NS::Input::command_creator<LAMMPS_NS::Run> (lmp=
,→<optimized out>, narg=1, arg=0x7e8750)

at /home/akohlmey/compile/lammps/src/input.cpp:878
#4 0x0000000000410ad3 in LAMMPS_NS::Input::execute_command (this=0x7d1410) at /home/
,→akohlmey/compile/lammps/src/input.cpp:864

#5 0x00000000004111fb in LAMMPS_NS::Input::file (this=0x7d1410) at /home/akohlmey/

,→compile/lammps/src/input.cpp:229

#6 0x000000000040933a in main (argc=<optimized out>, argv=<optimized out>) at /home/

,→akohlmey/compile/lammps/src/main.cpp:65

(gdb)

You can also print the value of variables and see if there is anything unexpected. Segmentation faults, for example,
commonly happen when a pointer variable is not assigned and still initialized to NULL.
(gdb) print x
$1 = (double **) 0x7ffff7ca1010
(gdb) print i
$2 = 0
(gdb) print x[0]
$3 = (double *) 0x7ffff6d80010
(gdb) print x[0][0]
$4 = 0
(gdb) print x[1][0]
$5 = 0.83979809569125363
(gdb) print atom->rmass
$6 = (double *) 0x0
(gdb)

Inspect a core dump file with the debugger

When an executable crashes with a “core dumped” message, it creates a file “core” or “core.<PID#>” which contains
the information about the current state. This file may be located in the folder where you ran LAMMPS or in some hidden
folder managed by the systemd daemon. In the latter case, you need to “extract” the core file with the coredumpctl
utility to the current folder. Example: coredumpctl -o core dump lmp. Now you can launch the debugger to load
the executable, its debug info and the core dump and drop you to a prompt like before.
$ gdb lmp core
Reading symbols from lmp...
[New LWP 1928535]
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib64/libthread_db.so.1".
Core was generated by `./lmp -in in.melt'.
Program terminated with signal SIGSEGV, Segmentation fault.
(continues on next page)

11.3. Debugging crashes 331

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

#0 0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x1b10740, eflag=1, vflag=
,→<optimized out>)

at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
139 comx += atom->rmass[i]*x[i][0]; /* BUG */
(gdb)

From here on, you use the same commands as shown before to get a stack trace and print current values of (pointer)
variables.

11.3.2 Using valgrind to get a stack trace

The valgrind suite of tools allows to closely inspect the behavior of a compiled program by essentially emulating a
CPU and instrumenting the program while running. This slows down execution quite significantly, but can also report
issues that are not resulting in a crash. The default valgrind tool is a memory checker and you can use it by prefixing the
normal command line with valgrind. Unlike GDB, this will also work for parallel execution, but it is recommended
to redirect the valgrind output to a file (e.g. with --log-file=crash-%p.txt, the %p will be substituted with the
process ID) so that the messages of the multiple valgrind instances to the console are not mixed.

$ valgrind ./lmp -in in.melt

==1933642== Memcheck, a memory error detector
==1933642== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
==1933642== Using Valgrind-3.15.0 and LibVEX; rerun with -h for copyright info
==1933642== Command: ./lmp -in in.melt
==1933642==
LAMMPS (19 Mar 2020)
OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:94)
using 1 OpenMP thread(s) per MPI task
Lattice spacing in x,y,z = 1.6796 1.6796 1.6796
Created orthogonal box = (0 0 0) to (16.796 16.796 16.796)
1 by 1 by 1 MPI processor grid
Created 4000 atoms
create_atoms CPU = 0.032964 secs
Neighbor list info ...
update every 20 steps, delay 0 steps, check no
max neighbors/atom: 2000, page size: 100000
master list distance cutoff = 2.8
ghost atom cutoff = 2.8
binsize = 1.4, bins = 12 12 12
1 neighbor lists, perpetual/occasional/extra = 1 0 0
(1) pair lj/cut, perpetual
attributes: half, newton on
pair build: half/bin/atomonly/newton
stencil: half/bin/3d/newton
bin: standard
Setting up Verlet run ...
Unit style : lj
Current step : 0
Time step : 0.005
==1933642== Invalid read of size 8
==1933642== at 0x6653AB: LAMMPS_NS::PairLJCut::compute(int, int) (pair_lj_cut.cpp:139)
==1933642== by 0x4CF0A1: LAMMPS_NS::Verlet::setup(int) (verlet.cpp:131)
(continues on next page)

332 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

==1933642== by 0x49DB41: LAMMPS_NS::Run::command(int, char**) (run.cpp:177)
==1933642== by 0x412589: void LAMMPS_NS::Input::command_creator<LAMMPS_NS::Run>
,→(LAMMPS_NS::LAMMPS*, int, char**) (input.cpp:881)
==1933642== by 0x410AD2: LAMMPS_NS::Input::execute_command() (input.cpp:864)
==1933642== by 0x4111FA: LAMMPS_NS::Input::file() (input.cpp:229)
==1933642== by 0x409339: main (main.cpp:65)
==1933642== Address 0x0 is not stack'd, malloc'd or (recently) free'd
==1933642==

As you can see, the stack trace information is similar to that obtained from GDB. In addition you get a more specific
hint about what cause the segmentation fault, i.e. that it is a NULL pointer dereference. To find out which pointer
exactly was NULL, you need to use the debugger, though.

11.4 Error messages

This is an alphabetic list of the ERROR messages LAMMPS prints out and the reason why. If the explanation here is
not sufficient, the documentation for the offending command may help. Error messages also list the source file and line
number where the error was generated. For example, a message like this:

ERROR: Illegal velocity command (velocity.cpp:78)

means that line #78 in the file src/velocity.cpp generated the error. Looking in the source code may help you figure out
what went wrong.
Doc page with WARNING messages

1-3 bond count is inconsistent An inconsistency was detected when computing the number of 1-3 neighbors for each
atom. This likely means something is wrong with the bond topologies you have defined.
1-4 bond count is inconsistent An inconsistency was detected when computing the number of 1-4 neighbors for each
atom. This likely means something is wrong with the bond topologies you have defined.
Accelerator sharing is not currently supported on system Multiple MPI processes cannot share the accelerator on
your system. For NVIDIA GPUs, see the nvidia-smi command to change this setting.
All angle coeffs are not set All angle coefficients must be set in the data file or by the angle_coeff command before
running a simulation.
All atom IDs = 0 but atom_modify id = yes Self-explanatory.
All atoms of a swapped type must have same charge. Self-explanatory.
All atoms of a swapped type must have the same charge. Self-explanatory.
All bond coeffs are not set All bond coefficients must be set in the data file or by the bond_coeff command before
running a simulation.
All dihedral coeffs are not set All dihedral coefficients must be set in the data file or by the dihedral_coeff command
before running a simulation.
All improper coeffs are not set All improper coefficients must be set in the data file or by the improper_coeff command
before running a simulation.
All masses are not set For atom styles that define masses for each atom type, all masses must be set in the data file or
by the mass command before running a simulation. They must also be set before using the velocity command.

11.4. Error messages 333

LAMMPS Documentation, Release stable 29Sep2021

All mol IDs should be set for fix gcmc group atoms The molecule flag is on, yet not all molecule ids in the fix group
have been set to non-zero positive values by the user. This is an error since all atoms in the fix gcmc group are
eligible for deletion, rotation, and translation and therefore must have valid molecule ids.
All pair coeffs are not set All pair coefficients must be set in the data file or by the pair_coeff command before running
a simulation.
All read_dump x,y,z fields must be specified for scaled, triclinic coords For triclinic boxes and scaled coordinates
you must specify all 3 of the x,y,z fields, else LAMMPS cannot reconstruct the unscaled coordinates.
All universe/uloop variables must have same # of values Self-explanatory.
All variables in next command must be same style Self-explanatory.
Angle atom missing in delete_bonds The delete_bonds command cannot find one or more atoms in a particular angle
on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid angle.
Angle atom missing in set command The set command cannot find one or more atoms in a particular angle on a par-
ticular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid angle.
Angle atoms %d %d %d missing on proc %d at step %ld One or more of 3 atoms needed to compute a particular an-
gle are missing on this processor. Typically this is because the pairwise cutoff is set too short or the angle has
blown apart and an atom is too far away.
Angle atoms missing on proc %d at step %ld One or more of 3 atoms needed to compute a particular angle are miss-
ing on this processor. Typically this is because the pairwise cutoff is set too short or the angle has blown apart
and an atom is too far away.
Angle coeff for hybrid has invalid style Angle style hybrid uses another angle style as one of its coefficients. The angle
style used in the angle_coeff command or read from a restart file is not recognized.
Angle coeffs are not set No angle coefficients have been assigned in the data file or via the angle_coeff command.
Angle extent > half of periodic box length This error was detected by the neigh_modify check yes setting. It is an
error because the angle atoms are so far apart it is ambiguous how it should be defined.
Angle potential must be defined for SHAKE When shaking angles, an angle_style potential must be used.
Angle style hybrid cannot have hybrid as an argument Self-explanatory.
Angle style hybrid cannot have none as an argument Self-explanatory.
Angle style hybrid cannot use same angle style twice Self-explanatory.
Angle table must range from 0 to 180 degrees Self-explanatory.
Angle table parameters did not set N List of angle table parameters must include N setting.
Angle_coeff command before angle_style is defined Coefficients cannot be set in the data file or via the angle_coeff
command until an angle_style has been assigned.
Angle_coeff command before simulation box is defined The angle_coeff command cannot be used before a
read_data, read_restart, or create_box command.
Angle_coeff command when no angles allowed The chosen atom style does not allow for angles to be defined.
Angle_style command when no angles allowed The chosen atom style does not allow for angles to be defined.
Angles assigned incorrectly Angles read in from the data file were not assigned correctly to atoms. This means there
is something invalid about the topology definitions.
Angles defined but no angle types The data file header lists angles but no angle types.
Append boundary must be shrink/minimum The boundary style of the face where atoms are added must be of type
m (shrink/minimum).

334 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Arccos of invalid value in variable formula Argument of arccos() must be between -1 and 1.
Arcsin of invalid value in variable formula Argument of arcsin() must be between -1 and 1.
Assigning body parameters to non-body atom Self-explanatory.
Assigning ellipsoid parameters to non-ellipsoid atom Self-explanatory.
Assigning line parameters to non-line atom Self-explanatory.
Assigning quat to non-body atom Self-explanatory.
Assigning tri parameters to non-tri atom Self-explanatory.
At least one atom of each swapped type must be present to define charges. Self-explanatory.
Atom IDs must be consecutive for velocity create loop all Self-explanatory.
Atom IDs must be used for molecular systems Atom IDs are used to identify and find partner atoms in bonds.
Atom count changed in fix neb This is not allowed in a NEB calculation.
Atom count is inconsistent, cannot write data file The sum of atoms across processors does not equal the global num-
ber of atoms. Probably some atoms have been lost.
Atom count is inconsistent, cannot write restart file Sum of atoms across processors does not equal initial total count.
This is probably because you have lost some atoms.
Atom in too many rigid bodies - boost MAXBODY Fix poems has a parameter MAXBODY (in fix_poems.cpp) which
determines the maximum number of rigid bodies a single atom can belong to (i.e. a multibody joint). The bodies
you have defined exceed this limit.
Atom sort did not operate correctly This is an internal LAMMPS error. Please report it to the developers.
Atom style hybrid cannot have hybrid as an argument Self-explanatory.
Atom style hybrid cannot use same atom style twice Self-explanatory.
Atom style template molecule must have atom types The defined molecule(s) does not specify atom types.
Atom style was redefined after using fix property/atom This is not allowed.
Atom type must be zero in fix gcmc mol command Self-explanatory.
Atom vector in equal-style variable formula Atom vectors generate one value per atom which is not allowed in an
equal-style variable.
Atom-style variable in equal-style variable formula Atom-style variables generate one value per atom which is not
allowed in an equal-style variable.
Atom_modify id command after simulation box is defined The atom_modify id command cannot be used after a
read_data, read_restart, or create_box command.
Atom_modify map command after simulation box is defined The atom_modify map command cannot be used after
a read_data, read_restart, or create_box command.
Atom_modify sort and first options cannot be used together Self-explanatory.
Atom_style command after simulation box is defined The atom_style command cannot be used after a read_data,
read_restart, or create_box command.
Atom_style line can only be used in 2d simulations Self-explanatory.
Atom_style tri can only be used in 3d simulations Self-explanatory.
Atomfile variable could not read values Check the file assigned to the variable.
Atomfile variable in equal-style variable formula Self-explanatory.

11.4. Error messages 335

LAMMPS Documentation, Release stable 29Sep2021

Atomfile-style variable in equal-style variable formula Self-explanatory.

Attempt to pop empty stack in fix box/relax Internal LAMMPS error. Please report it to the developers.
Attempt to push beyond stack limit in fix box/relax Internal LAMMPS error. Please report it to the developers.
Attempting to rescale a 0.0 temperature Cannot rescale a temperature that is already 0.0.
Attempting to insert more particles than available lattice points Self-explanatory.
Bad FENE bond Two atoms in a FENE bond have become so far apart that the bond cannot be computed.
Bad TIP4P angle type for PPPM/TIP4P Specified angle type is not valid.
Bad TIP4P angle type for PPPMDisp/TIP4P Specified angle type is not valid.
Bad TIP4P bond type for PPPM/TIP4P Specified bond type is not valid.
Bad TIP4P bond type for PPPMDisp/TIP4P Specified bond type is not valid.
Bad fix ID in fix append/atoms command The value of the fix_id for keyword spatial must start with “f_”.
Bad grid of processors The 3d grid of processors defined by the processors command does not match the number of
processors LAMMPS is being run on.
Bad kspace_modify kmax/ewald parameter Kspace_modify values for the kmax/ewald keyword must be integers > 0
Bad kspace_modify slab parameter Kspace_modify value for the slab/volume keyword must be >= 2.0.
Bad matrix inversion in mldivide3 This error should not occur unless the matrix is badly formed.
Bad principal moments Fix rigid did not compute the principal moments of inertia of a rigid group of atoms correctly.
Bad quadratic solve for particle/line collision This is an internal error. It should normally not occur.
Bad quadratic solve for particle/tri collision This is an internal error. It should normally not occur.
Bad real space Coulombic cutoff in fix tune/kspace Fix tune/kspace tried to find the optimal real space Coulombic
cutoff using the Newton-Rhaphson method, but found a non-positive or NaN cutoff
Balance command before simulation box is defined The balance command cannot be used before a read_data,
read_restart, or create_box command.
Balance produced bad splits This should not occur. It means two or more cutting plane locations are on top of each
other or out of order. Report the problem to the developers.
Balance rcb cannot be used with comm_style brick Comm_style tiled must be used instead.
Balance shift string is invalid The string can only contain the characters “x”, “y”, or “z”.
Bias compute does not calculate a velocity bias The specified compute must compute a bias for temperature.
Bias compute does not calculate temperature The specified compute must compute temperature.
Bias compute group does not match compute group The specified compute must operate on the same group as the
parent compute.
Big particle in fix srd cannot be point particle Big particles must be extended spheroids or ellipsoids.
Bigint setting in lmptype.h is invalid Size of bigint is less than size of tagint.
Bigint setting in lmptype.h is not compatible Format of bigint stored in restart file is not consistent with LAMMPS
version you are running. See the settings in src/lmptype.h
Bitmapped lookup tables require int/float be same size Cannot use pair tables on this machine, because of word sizes.
Use the pair_modify command with table 0 instead.
Bitmapped table in file does not match requested table Setting for bitmapped table in pair_coeff command must
match table in file exactly.

336 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Bitmapped table is incorrect length in table file Number of table entries is not a correct power of 2.
Bond and angle potentials must be defined for TIP4P Cannot use TIP4P pair potential unless bond and angle poten-
tials are defined.
Bond atom missing in box size check The second atom needed to compute a particular bond is missing on this pro-
cessor. Typically this is because the pairwise cutoff is set too short or the bond has blown apart and an atom is
too far away.
Bond atom missing in delete_bonds The delete_bonds command cannot find one or more atoms in a particular bond
on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid bond.
Bond atom missing in image check The second atom in a particular bond is missing on this processor. Typically this
is because the pairwise cutoff is set too short or the bond has blown apart and an atom is too far away.
Bond atom missing in set command The set command cannot find one or more atoms in a particular bond on a par-
ticular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid bond.
Bond atoms %d %d missing on proc %d at step %ld The second atom needed to compute a particular bond is missing
on this processor. Typically this is because the pairwise cutoff is set too short or the bond has blown apart and
an atom is too far away.
Bond atoms missing on proc %d at step %ld The second atom needed to compute a particular bond is missing on this
processor. Typically this is because the pairwise cutoff is set too short or the bond has blown apart and an atom
is too far away.
Bond coeff for hybrid has invalid style Bond style hybrid uses another bond style as one of its coefficients. The bond
style used in the bond_coeff command or read from a restart file is not recognized.
Bond coeffs are not set No bond coefficients have been assigned in the data file or via the bond_coeff command.
Bond extent > half of periodic box length This error was detected by the neigh_modify check yes setting. It is an
error because the bond atoms are so far apart it is ambiguous how it should be defined.
Bond potential must be defined for SHAKE Cannot use fix shake unless bond potential is defined.
Bond style hybrid cannot have hybrid as an argument Self-explanatory.
Bond style hybrid cannot have none as an argument Self-explanatory.
Bond style hybrid cannot use same bond style twice Self-explanatory.
Bond style quartic cannot be used with 3,4-body interactions No angle, dihedral, or improper styles can be defined
when using bond style quartic.
Bond style quartic cannot be used with atom style template This bond style can change the bond topology which is
not allowed with this atom style.
Bond style quartic requires special_bonds = 1,1,1 This is a restriction of the current bond quartic implementation.
Bond table parameters did not set N List of bond table parameters must include N setting.
Bond table values are not increasing The values in the tabulated file must be monotonically increasing.
BondAngle coeff for hybrid angle has invalid format No “ba” field should appear in data file entry.
BondBond coeff for hybrid angle has invalid format No “bb” field should appear in data file entry.
Bond_coeff command before bond_style is defined Coefficients cannot be set in the data file or via the bond_coeff
command until an bond_style has been assigned.
Bond_coeff command before simulation box is defined The bond_coeff command cannot be used before a read_data,
read_restart, or create_box command.
Bond_coeff command when no bonds allowed The chosen atom style does not allow for bonds to be defined.

11.4. Error messages 337

LAMMPS Documentation, Release stable 29Sep2021

Bond_style command when no bonds allowed The chosen atom style does not allow for bonds to be defined.
Bonds assigned incorrectly Bonds read in from the data file were not assigned correctly to atoms. This means there
is something invalid about the topology definitions.
Bonds defined but no bond types The data file header lists bonds but no bond types.
Bond/react: Cannot use fix bond/react with non-molecular systems Only systems with bonds that can be changed
can be used. Atom_style template does not qualify.
Bond/react: Invalid template atom ID in map file Atom IDs in molecule templates range from 1 to the number of
atoms in the template.
Bond/react: Rmax cutoff is longer than pairwise cutoff This is not allowed because bond creation is done using the
pairwise neighbor list.
Bond/react: Molecule template ID for fix bond/react does not exist A valid molecule template must have been cre-
ated with the molecule command.
Bond/react: Reaction templates must contain the same number of atoms There should be a one-to-one correspon-
dence between atoms in the pre-reacted and post-reacted templates, as specified by the map file.
Bond/react: Unknown section in map file Please ensure reaction map files are properly formatted.
Bond/react: Atom/Bond type affected by reaction too close to template edge This means an atom which changes type
or connectivity during the reaction is too close to an ‘edge’ atom defined in the map file. This could cause
incorrect assignment of bonds, angle, etc. Generally, this means you must include more atoms in your templates,
such that there are at least two atoms between each atom involved in the reaction and an edge atom.
Bond/react: Fix bond/react needs ghost atoms from farther away This is because a processor needs to map the entire
unreacted molecule template onto simulation atoms it knows about. The comm_modify cutoff command can be
used to extend the communication range.
Bond/react: A deleted atom cannot remain bonded to an atom that is not deleted Self-explanatory.
Bond/react: First neighbors of chiral atoms must be of mutually different types Self-explanatory.
Bond/react: Chiral atoms must have exactly four first neighbors Self-explanatory.
Bond/react: Molecule template ‘Coords’ section required for chiralIDs keyword The coordinates of atoms in the
pre-reacted template are used to determine chirality.
Bond/react special bond generation overflow The number of special bonds per-atom created by a reaction exceeds the
system setting. See the read_data or create_box command for how to specify this value.
Bond/react topology/atom exceed system topology/atom The number of bonds, angles etc per-atom created by a re-
action exceeds the system setting. See the read_data or create_box command for how to specify this value.
Both restart files must use % or neither Self-explanatory.
Both restart files must use MPI-IO or neither Self-explanatory.
Both sides of boundary must be periodic Cannot specify a boundary as periodic only on the lo or hi side. Must be
periodic on both sides.
Boundary command after simulation box is defined The boundary command cannot be used after a read_data,
read_restart, or create_box command.
Box bounds are invalid The box boundaries specified in the read_data file are invalid. The lo value must be less than
the hi value for all 3 dimensions.
Box command after simulation box is defined The box command cannot be used after a read_data, read_restart, or
create_box command.

338 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

CPU neighbor lists must be used for ellipsoid/sphere mix. When using Gay-Berne or RE-squared pair styles with
both ellipsoidal and spherical particles, the neighbor list must be built on the CPU
Can not specify Pxy/Pxz/Pyz in fix box/relax with non-triclinic box Only triclinic boxes can be used with off-
diagonal pressure components. See the region prism command for details.
Can not specify Pxy/Pxz/Pyz in fix nvt/npt/nph with non-triclinic box Only triclinic boxes can be used with off-
diagonal pressure components. See the region prism command for details.
Can only use -plog with multiple partitions Self-explanatory. See page discussion of command-line switches.
Can only use -pscreen with multiple partitions Self-explanatory. See page discussion of command-line switches.
Can only use Kokkos supported regions with Kokkos package Self-explanatory.
Can only use NEB with 1-processor replicas This is current restriction for NEB as implemented in LAMMPS.
Can only use TAD with 1-processor replicas for NEB This is current restriction for NEB as implemented in
LAMMPS.
Cannot (yet) do analytic differentiation with pppm/gpu This is a current restriction of this command.
Cannot (yet) request ghost atoms with Kokkos half neighbor list This feature is not yet supported.
Cannot (yet) use ‘electron’ units with dipoles This feature is not yet supported.
Cannot (yet) use Ewald with triclinic box and slab correction This feature is not yet supported.
Cannot (yet) use K-space slab correction with compute group/group for triclinic systems This option is not yet sup-
ported.
Cannot (yet) use MSM with 2d simulation This feature is not yet supported.
Cannot (yet) use PPPM with triclinic box and TIP4P This feature is not yet supported.
Cannot (yet) use PPPM with triclinic box and kspace_modify diff ad This feature is not yet supported.
Cannot (yet) use PPPM with triclinic box and slab correction This feature is not yet supported.
Cannot (yet) use kspace slab correction with long-range dipoles and non-neutral systems or per-atom energy This
feature is not yet supported.
Cannot (yet) use kspace_modify diff ad with compute group/group This option is not yet supported.
Cannot (yet) use kspace_style pppm/stagger with triclinic systems This feature is not yet supported.
Cannot (yet) use molecular templates with Kokkos Self-explanatory.
Cannot (yet) use respa with Kokkos Self-explanatory.
Cannot (yet) use rigid bodies with fix deform and Kokkos Self-explanatory.
Cannot (yet) use rigid bodies with fix nh and Kokkos Self-explanatory.
Cannot (yet) use single precision with MSM (remove -DFFT_SINGLE from Makefile and re-compile) Single pre-
cision cannot be used with MSM.
Cannot add atoms to fix move variable Atoms can not be added afterwards to this fix option.
Cannot append atoms to a triclinic box The simulation box must be defined with edges aligned with the Cartesian
axes.
Cannot balance in z dimension for 2d simulation Self-explanatory.
Cannot change box ortho/triclinic with certain fixes defined This is because those fixes store the shape of the box.
You need to use unfix to discard the fix, change the box, then redefine a new fix.

11.4. Error messages 339

LAMMPS Documentation, Release stable 29Sep2021

Cannot change box ortho/triclinic with dumps defined This is because some dumps store the shape of the box. You
need to use undump to discard the dump, change the box, then redefine a new dump.
Cannot change box tilt factors for orthogonal box Cannot use tilt factors unless the simulation box is non-orthogonal.
Cannot change box to orthogonal when tilt is non-zero Self-explanatory.
Cannot change box z boundary to non-periodic for a 2d simulation Self-explanatory.
Cannot change dump_modify every for dump dcd The frequency of writing dump dcd snapshots cannot be changed.
Cannot change dump_modify every for dump xtc The frequency of writing dump xtc snapshots cannot be changed.
Cannot change timestep once fix srd is setup This is because various SRD properties depend on the timestep size.
Cannot change timestep with fix pour This is because fix pour pre-computes the time delay for particles to fall out of
the insertion volume due to gravity.
Cannot change to comm_style brick from tiled layout Self-explanatory.
Cannot change_box after reading restart file with per-atom info This is because the restart file info cannot be mi-
grated with the atoms. You can get around this by performing a 0-timestep run which will assign the restart file
info to actual atoms.
Cannot change_box in xz or yz for 2d simulation Self-explanatory.
Cannot change_box in z dimension for 2d simulation Self-explanatory.
Cannot clear group all This operation is not allowed.
Cannot close restart file - MPI error: %s This error was generated by MPI when reading/writing an MPI-IO restart
file.
Cannot compute initial g_ewald_disp LAMMPS failed to compute an initial guess for the PPPM_disp g_ewald_6
factor that partitions the computation between real space and k-space for Dispersion interactions.
Cannot create an atom map unless atoms have IDs The simulation requires a mapping from global atom IDs to local
atoms, but the atoms that have been defined have no IDs.
Cannot create atoms with undefined lattice Must use the lattice command before using the create_atoms command.
Cannot create/grow a vector/array of pointers for %s LAMMPS code is making an illegal call to the templated mem-
ory allocators, to create a vector or array of pointers.
Cannot create_atoms after reading restart file with per-atom info The per-atom info was stored to be used when by
a fix that you may re-define. If you add atoms before re-defining the fix, then there will not be a correct amount
of per-atom info.
Cannot create_box after simulation box is defined A simulation box can only be defined once.
Cannot currently use pair reax with pair hybrid This is not yet supported.
Cannot currently use pppm/gpu with fix balance. Self-explanatory.
Cannot delete group all Self-explanatory.
Cannot delete group currently used by a compute Self-explanatory.
Cannot delete group currently used by a dump Self-explanatory.
Cannot delete group currently used by a fix Self-explanatory.
Cannot delete group currently used by atom_modify first Self-explanatory.
Cannot delete_atoms bond yes for non-molecular systems Self-explanatory.

340 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Cannot displace_atoms after reading restart file with per-atom info This is because the restart file info cannot be mi-
grated with the atoms. You can get around this by performing a 0-timestep run which will assign the restart file
info to actual atoms.
Cannot do GCMC on atoms in atom_modify first group This is a restriction due to the way atoms are organized in a
list to enable the atom_modify first command.
Cannot do atom/swap on atoms in atom_modify first group This is a restriction due to the way atoms are organized
in a list to enable the atom_modify first command.
Cannot dump sort on atom IDs with no atom IDs defined Self-explanatory.
Cannot dump sort when multiple dump files are written In this mode, each processor dumps its atoms to a file, so no
sorting is allowed.
Cannot embed Python when also extending Python with LAMMPS When running LAMMPS via Python through
the LAMMPS library interface you cannot also user the input script python command.
Cannot evaporate atoms in atom_modify first group This is a restriction due to the way atoms are organized in a list
to enable the atom_modify first command.
Cannot find create_bonds group ID Self-explanatory.
Cannot find delete_bonds group ID Group ID used in the delete_bonds command does not exist.
Cannot find specified group ID for core particles Self-explanatory.
Cannot find specified group ID for shell particles Self-explanatory.
Cannot have both pair_modify shift and tail set to yes These 2 options are contradictory.
Cannot intersect groups using a dynamic group This operation is not allowed.
Cannot mix molecular and molecule template atom styles Self-explanatory.
Cannot open -reorder file Self-explanatory.
Cannot open ADP potential file %s The specified ADP potential file cannot be opened. Check that the path and name
are correct.
Cannot open AIREBO potential file %s The specified AIREBO potential file cannot be opened. Check that the path
and name are correct.
Cannot open BOP potential file %s The specified BOP potential file cannot be opened. Check that the path and name
are correct.
Cannot open COMB potential file %s The specified COMB potential file cannot be opened. Check that the path and
name are correct.
Cannot open COMB3 lib.comb3 file The COMB3 library file cannot be opened. Check that the path and name are
correct.
Cannot open COMB3 potential file %s The specified COMB3 potential file cannot be opened. Check that the path
and name are correct.
Cannot open EAM potential file %s The specified EAM potential file cannot be opened. Check that the path and
name are correct.
Cannot open EIM potential file %s The specified EIM potential file cannot be opened. Check that the path and name
are correct.
Cannot open LCBOP potential file %s The specified LCBOP potential file cannot be opened. Check that the path and
name are correct.
Cannot open MEAM potential file %s The specified MEAM potential file cannot be opened. Check that the path and
name are correct.

11.4. Error messages 341

LAMMPS Documentation, Release stable 29Sep2021

Cannot open SNAP coefficient file %s The specified SNAP coefficient file cannot be opened. Check that the path and
name are correct.
Cannot open SNAP parameter file %s The specified SNAP parameter file cannot be opened. Check that the path and
name are correct.
Cannot open Stillinger-Weber potential file %s The specified SW potential file cannot be opened. Check that the path
and name are correct.
Cannot open Tersoff potential file %s The specified potential file cannot be opened. Check that the path and name
are correct.
Cannot open Vashishta potential file %s The specified Vashishta potential file cannot be opened. Check that the path
and name are correct.
Cannot open balance output file Self-explanatory.
Cannot open coul/streitz potential file %s The specified coul/streitz potential file cannot be opened. Check that the
path and name are correct.
Cannot open custom file Self-explanatory.
Cannot open data file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open dir to search for restart file Using a “*” in the name of the restart file will open the current directory to
search for matching file names.
Cannot open dump file Self-explanatory.
Cannot open dump file %s The output file for the dump command cannot be opened. Check that the path and name
are correct.
Cannot open file %s The specified file cannot be opened. Check that the path and name are correct. If the file is a
compressed file, also check that the gzip executable can be found and run.
Cannot open file variable file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix ave/chunk file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix ave/correlate file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix ave/histo file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix ave/time file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix balance output file Self-explanatory.
Cannot open fix poems file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix print file %s The output file generated by the fix print command cannot be opened
Cannot open fix qeq parameter file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix qeq/comb file %s The output file for the fix qeq/combs command cannot be opened. Check that the
path and name are correct.
Cannot open fix reax/bonds file %s The output file for the fix reax/bonds command cannot be opened. Check that the
path and name are correct.
Cannot open fix rigid infile %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix rigid restart file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix rigid/small infile %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open fix tmd file %s The output file for the fix tmd command cannot be opened. Check that the path and name
are correct.

342 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Cannot open fix ttm file %s The output file for the fix ttm command cannot be opened. Check that the path and name
are correct.
Cannot open gzipped file LAMMPS was compiled without support for reading and writing gzipped files through a
pipeline to the gzip program with -DLAMMPS_GZIP.
Cannot open input script %s Self-explanatory.
Cannot open log.cite file This file is created when you use some LAMMPS features, to indicate what paper you should
cite on behalf of those who implemented the feature. Check that you have write privileges into the directory you
are running in.
Cannot open log.lammps for writing The default LAMMPS log file cannot be opened. Check that the directory you
are running in allows for files to be created.
Cannot open logfile The LAMMPS log file named in a command-line argument cannot be opened. Check that the
path and name are correct.
Cannot open logfile %s The LAMMPS log file specified in the input script cannot be opened. Check that the path and
name are correct.
Cannot open molecule file %s The specified file cannot be opened. Check that the path and name are correct.
Cannot open nb3b/harmonic potential file %s The specified potential file cannot be opened. Check that the path and
name are correct.
Cannot open pair_write file The specified output file for pair energies and forces cannot be opened. Check that the
path and name are correct.
Cannot open polymorphic potential file %s The specified polymorphic potential file cannot be opened. Check that
the path and name are correct.
Cannot open print file %s Self-explanatory.
Cannot open processors output file Self-explanatory.
Cannot open restart file %s Self-explanatory.
Cannot open restart file for reading - MPI error: %s This error was generated by MPI when reading/writing an MPI-
IO restart file.
Cannot open restart file for writing - MPI error: %s This error was generated by MPI when reading/writing an MPI-
IO restart file.
Cannot open screen file The screen file specified as a command-line argument cannot be opened. Check that the
directory you are running in allows for files to be created.
Cannot open temporary file for world counter. Self-explanatory.
Cannot open universe log file For a multi-partition run, the master log file cannot be opened. Check that the directory
you are running in allows for files to be created.
Cannot open universe screen file For a multi-partition run, the master screen file cannot be opened. Check that the
directory you are running in allows for files to be created.
Cannot read from restart file - MPI error: %s This error was generated by MPI when reading/writing an MPI-IO
restart file.
Cannot read_data without add keyword after simulation box is defined Self-explanatory.
Cannot read_restart after simulation box is defined The read_restart command cannot be used after a read_data,
read_restart, or create_box command.
Cannot redefine variable as a different style An equal-style variable can be re-defined but only if it was originally an
equal-style variable.

11.4. Error messages 343

LAMMPS Documentation, Release stable 29Sep2021

Cannot replicate 2d simulation in z dimension The replicate command cannot replicate a 2d simulation in the z di-
mension.
Cannot replicate with fixes that store atom quantities Either fixes are defined that create and store atom-based vectors
or a restart file was read which included atom-based vectors for fixes. The replicate command cannot duplicate
that information for new atoms. You should use the replicate command before fixes are applied to the system.
Cannot reset timestep with a dynamic region defined Dynamic regions (see the region command) have a time depen-
dence. Thus you cannot change the timestep when one or more of these are defined.
Cannot reset timestep with a time-dependent fix defined You cannot reset the timestep when a fix that keeps track of
elapsed time is in place.
Cannot run 2d simulation with non-periodic Z dimension Use the boundary command to make the z dimension pe-
riodic in order to run a 2d simulation.
Cannot set bond topology types for atom style template The bond, angle, etc types cannot be changed for this atom
style since they are static settings in the molecule template files.
Cannot set both respa pair and inner/middle/outer In the rRESPA integrator, you must compute pairwise potentials
either all together (pair), or in pieces (inner/middle/outer). You can’t do both.
Cannot set cutoff/multi before simulation box is defined Self-explanatory.
Cannot set dpd/theta for this atom style Self-explanatory.
Cannot set dump_modify flush for dump xtc Self-explanatory.
Cannot set mass for this atom style This atom style does not support mass settings for each atom type. Instead they
are defined on a per-atom basis in the data file.
Cannot set meso/cv for this atom style Self-explanatory.
Cannot set meso/e for this atom style Self-explanatory.
Cannot set meso/rho for this atom style Self-explanatory.
Cannot set non-zero image flag for non-periodic dimension Self-explanatory.
Cannot set non-zero z velocity for 2d simulation Self-explanatory.
Cannot set quaternion for atom that has none Self-explanatory.
Cannot set quaternion with xy components for 2d system Self-explanatory.
Cannot set respa hybrid and any of pair/inner/middle/outer In the rRESPA integrator, you must compute pairwise
potentials either all together (pair), with different cutoff regions (inner/middle/outer), or per hybrid sub-style
(hybrid). You cannot mix those.
Cannot set respa middle without inner/outer In the rRESPA integrator, you must define both a inner and outer setting
in order to use a middle setting.
Cannot set restart file size - MPI error: %s This error was generated by MPI when reading/writing an MPI-IO restart
file.
Cannot set smd/contact/radius for this atom style Self-explanatory.
Cannot set smd/mass/density for this atom style Self-explanatory.
Cannot set temperature for fix rigid/nph The temp keyword cannot be specified.
Cannot set theta for atom that is not a line Self-explanatory.
Cannot set this attribute for this atom style The attribute being set does not exist for the defined atom style.
Cannot set variable z velocity for 2d simulation Self-explanatory.

344 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Cannot skew triclinic box in z for 2d simulation Self-explanatory.

Cannot subtract groups using a dynamic group This operation is not allowed.
Cannot union groups using a dynamic group This operation is not allowed.
Cannot use -kokkos on without KOKKOS installed Self-explanatory.
Cannot use -reorder after -partition Self-explanatory. See page discussion of command-line switches.
Cannot use Ewald with 2d simulation The kspace style ewald cannot be used in 2d simulations. You can use 2d Ewald
in a 3d simulation; see the kspace_modify command.
Cannot use Ewald/disp solver on system with no charge, dipole, or LJ particles No atoms in system have a non-zero
charge or dipole, or are LJ particles. Change charges/dipoles or change options of the kspace solver/pair style.
Cannot use EwaldDisp with 2d simulation This is a current restriction of this command.
Cannot use Kokkos pair style with rRESPA inner/middle Self-explanatory.
Cannot use NEB unless atom map exists Use the atom_modify command to create an atom map.
Cannot use NEB with a single replica Self-explanatory.
Cannot use NEB with atom_modify sort enabled This is current restriction for NEB implemented in LAMMPS.
Cannot use PPPM with 2d simulation The kspace style pppm cannot be used in 2d simulations. You can use 2d
PPPM in a 3d simulation; see the kspace_modify command.
Cannot use PPPMDisp with 2d simulation The kspace style pppm/disp cannot be used in 2d simulations. You can
use 2d pppm/disp in a 3d simulation; see the kspace_modify command.
Cannot use PRD with a changing box The current box dimensions are not copied between replicas
Cannot use PRD with a time-dependent fix defined PRD alters the timestep in ways that will mess up these fixes.
Cannot use PRD with a time-dependent region defined PRD alters the timestep in ways that will mess up these re-
gions.
Cannot use PRD with atom_modify sort enabled This is a current restriction of PRD. You must turn off sorting,
which is enabled by default, via the atom_modify command.
Cannot use PRD with multi-processor replicas unless atom map exists Use the atom_modify command to create an
atom map.
Cannot use TAD unless atom map exists for NEB See atom_modify map command to set this.
Cannot use TAD with a single replica for NEB NEB requires multiple replicas.
Cannot use TAD with atom_modify sort enabled for NEB This is a current restriction of NEB.
Cannot use a damped dynamics min style with fix box/relax This is a current restriction in LAMMPS. Use another
minimizer style.
Cannot use a damped dynamics min style with per-atom DOF This is a current restriction in LAMMPS. Use another
minimizer style.
Cannot use append/atoms in periodic dimension The boundary style of the face where atoms are added can not be of
type p (periodic).
Cannot use atomfile-style variable unless atom map exists Self-explanatory. See the atom_modify command to cre-
ate a map.
Cannot use both com and bias with compute temp/chunk Self-explanatory.
Cannot use chosen neighbor list style with buck/coul/cut/kk Self-explanatory.
Cannot use chosen neighbor list style with buck/coul/long/kk Self-explanatory.

11.4. Error messages 345

LAMMPS Documentation, Release stable 29Sep2021

Cannot use chosen neighbor list style with buck/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with coul/cut/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with coul/debye/kk Self-explanatory.
Cannot use chosen neighbor list style with coul/dsf/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with coul/wolf/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with lj/charmm/coul/charmm/implicit/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/charmm/coul/charmm/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/charmm/coul/long/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/class2/coul/cut/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/class2/coul/long/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/class2/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/cut/coul/cut/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with lj/cut/coul/debye/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/cut/coul/long/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with lj/cut/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with lj/expand/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/gromacs/coul/gromacs/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/gromacs/kk Self-explanatory.
Cannot use chosen neighbor list style with lj/sdk/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with pair eam/kk That style is not supported by Kokkos.
Cannot use chosen neighbor list style with pair eam/kk/alloy Self-explanatory.
Cannot use chosen neighbor list style with pair eam/kk/fs Self-explanatory.
Cannot use chosen neighbor list style with pair sw/kk Self-explanatory.
Cannot use chosen neighbor list style with tersoff/kk Self-explanatory.
Cannot use chosen neighbor list style with tersoff/zbl/kk Self-explanatory.
Cannot use compute chunk/atom bin z for 2d model Self-explanatory.
Cannot use compute cluster/atom unless atoms have IDs Atom IDs are used to identify clusters.
Cannot use create_atoms rotate unless single style Self-explanatory.
Cannot use create_bonds unless atoms have IDs This command requires a mapping from global atom IDs to local
atoms, but the atoms that have been defined have no IDs.
Cannot use create_bonds with non-molecular system Self-explanatory.
Cannot use cwiggle in variable formula between runs This is a function of elapsed time.
Cannot use delete_atoms bond yes with atom_style template This is because the bonds for that atom style are hard-
wired in the molecule template.
Cannot use delete_atoms unless atoms have IDs Your atoms do not have IDs, so the delete_atoms command cannot
be used.
Cannot use delete_bonds with non-molecular system Your choice of atom style does not have bonds.

346 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Cannot use dump_modify fileper without % in dump file name Self-explanatory.

Cannot use dump_modify nfile without % in dump file name Self-explanatory.
Cannot use dynamic group with fix adapt atom This is not yet supported.
Cannot use fix TMD unless atom map exists Using this fix requires the ability to lookup an atom index, which is
provided by an atom map. An atom map does not exist (by default) for non-molecular problems. Using the
atom_modify map command will force an atom map to be created.
Cannot use fix bond/break with non-molecular systems Only systems with bonds that can be changed can be used.
Atom_style template does not qualify.
Cannot use fix bond/create with non-molecular systems Only systems with bonds that can be changed can be used.
Atom_style template does not qualify.
Cannot use fix bond/swap with non-molecular systems Only systems with bonds that can be changed can be used.
Atom_style template does not qualify.
Cannot use fix box/relax on a 2nd non-periodic dimension When specifying an off-diagonal pressure component,
the second of the two dimensions must be periodic. E.g. if the xy component is specified, then the y dimension
must be periodic.
Cannot use fix box/relax on a non-periodic dimension When specifying a diagonal pressure component, the dimen-
sion must be periodic.
Cannot use fix box/relax with both relaxation and scaling on a tilt factor When specifying scaling on a tilt factor
component, that component can not also be controlled by the barostat. E.g. if scalexy yes is specified and
also keyword tri or xy, this is wrong.
Cannot use fix box/relax with tilt factor scaling on a 2nd non-periodic dimension When specifying scaling on a tilt
factor component, the second of the two dimensions must be periodic. E.g. if the xy component is specified,
then the y dimension must be periodic.
Cannot use fix deform on a shrink-wrapped boundary The x, y, z options cannot be applied to shrink-wrapped di-
mensions.
Cannot use fix deform tilt on a shrink-wrapped 2nd dim This is because the shrink-wrapping will change the value
of the strain implied by the tilt factor.
Cannot use fix deform trate on a box with zero tilt The trate style alters the current strain.
Cannot use fix deposit rigid and not molecule Self-explanatory.
Cannot use fix deposit rigid and shake These two attributes are conflicting.
Cannot use fix deposit shake and not molecule Self-explanatory.
Cannot use fix enforce2d with 3d simulation Self-explanatory.
Cannot use fix gcmc in a 2d simulation Fix gcmc is set up to run in 3d only. No 2d simulations with fix gcmc are
allowed.
Cannot use fix gcmc shake and not molecule Self-explanatory.
Cannot use fix msst without per-type mass defined Self-explanatory.
Cannot use fix npt and fix deform on same component of stress tensor This would be changing the same box dimen-
sion twice.
Cannot use fix nvt/npt/nph on a 2nd non-periodic dimension When specifying an off-diagonal pressure component,
the second of the two dimensions must be periodic. E.g. if the xy component is specified, then the y dimension
must be periodic.

11.4. Error messages 347

LAMMPS Documentation, Release stable 29Sep2021

Cannot use fix nvt/npt/nph on a non-periodic dimension When specifying a diagonal pressure component, the di-
mension must be periodic.
Cannot use fix nvt/npt/nph with both xy dynamics and xy scaling Self-explanatory.
Cannot use fix nvt/npt/nph with both xz dynamics and xz scaling Self-explanatory.
Cannot use fix nvt/npt/nph with both yz dynamics and yz scaling Self-explanatory.
Cannot use fix nvt/npt/nph with xy scaling when y is non-periodic dimension The second dimension in the barostat-
ted tilt factor must be periodic.
Cannot use fix nvt/npt/nph with xz scaling when z is non-periodic dimension The second dimension in the barostat-
ted tilt factor must be periodic.
Cannot use fix nvt/npt/nph with yz scaling when z is non-periodic dimension The second dimension in the barostat-
ted tilt factor must be periodic.
Cannot use fix pour rigid and not molecule Self-explanatory.
Cannot use fix pour rigid and shake These two attributes are conflicting.
Cannot use fix pour shake and not molecule Self-explanatory.
Cannot use fix pour with triclinic box This option is not yet supported.
Cannot use fix press/berendsen and fix deform on same component of stress tensor These commands both change
the box size/shape, so you cannot use both together.
Cannot use fix press/berendsen on a non-periodic dimension Self-explanatory.
Cannot use fix press/berendsen with triclinic box Self-explanatory.
Cannot use fix reax/bonds without pair_style reax Self-explanatory.
Cannot use fix rigid npt/nph and fix deform on same component of stress tensor This would be changing the same
box dimension twice.
Cannot use fix rigid npt/nph on a non-periodic dimension When specifying a diagonal pressure component, the di-
mension must be periodic.
Cannot use fix rigid/small npt/nph on a non-periodic dimension When specifying a diagonal pressure component,
the dimension must be periodic.
Cannot use fix shake with non-molecular system Your choice of atom style does not have bonds.
Cannot use fix ttm with 2d simulation This is a current restriction of this fix due to the grid it creates.
Cannot use fix ttm with triclinic box This is a current restriction of this fix due to the grid it creates.
Cannot use fix tune/kspace without a kspace style Self-explanatory.
Cannot use fix tune/kspace without a pair style This fix (tune/kspace) can only be used when a pair style has been
specified.
Cannot use fix wall in periodic dimension Self-explanatory.
Cannot use fix wall zlo/zhi for a 2d simulation Self-explanatory.
Cannot use fix wall/reflect in periodic dimension Self-explanatory.
Cannot use fix wall/reflect zlo/zhi for a 2d simulation Self-explanatory.
Cannot use fix wall/srd in periodic dimension Self-explanatory.
Cannot use fix wall/srd more than once Nor is their a need to since multiple walls can be specified in one command.
Cannot use fix wall/srd without fix srd Self-explanatory.

348 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Cannot use fix wall/srd zlo/zhi for a 2d simulation Self-explanatory.

Cannot use fix_deposit unless atoms have IDs Self-explanatory.
Cannot use fix_pour unless atoms have IDs Self-explanatory.
Cannot use include command within an if command Self-explanatory.
Cannot use lines with fix srd unless overlap is set This is because line segments are connected to each other.
Cannot use multiple fix wall commands with pair brownian Self-explanatory.
Cannot use multiple fix wall commands with pair lubricate Self-explanatory.
Cannot use multiple fix wall commands with pair lubricate/poly Self-explanatory.
Cannot use multiple fix wall commands with pair lubricateU Self-explanatory.
Cannot use neigh_modify exclude with GPU neighbor builds This is a current limitation of the GPU implementation
in LAMMPS.
Cannot use neighbor bins - box size << cutoff Too many neighbor bins will be created. This typically happens when
the simulation box is very small in some dimension, compared to the neighbor cutoff. Use the “nsq” style instead
of “bin” style.
Cannot use newton pair with beck/gpu pair style Self-explanatory.
Cannot use newton pair with born/coul/long/gpu pair style Self-explanatory.
Cannot use newton pair with born/coul/wolf/gpu pair style Self-explanatory.
Cannot use newton pair with born/gpu pair style Self-explanatory.
Cannot use newton pair with buck/coul/cut/gpu pair style Self-explanatory.
Cannot use newton pair with buck/coul/long/gpu pair style Self-explanatory.
Cannot use newton pair with buck/gpu pair style Self-explanatory.
Cannot use newton pair with colloid/gpu pair style Self-explanatory.
Cannot use newton pair with coul/cut/gpu pair style Self-explanatory.
Cannot use newton pair with coul/debye/gpu pair style Self-explanatory.
Cannot use newton pair with coul/dsf/gpu pair style Self-explanatory.
Cannot use newton pair with coul/long/gpu pair style Self-explanatory.
Cannot use newton pair with dipole/cut/gpu pair style Self-explanatory.
Cannot use newton pair with dipole/sf/gpu pair style Self-explanatory.
Cannot use newton pair with dpd/gpu pair style Self-explanatory.
Cannot use newton pair with dpd/tstat/gpu pair style Self-explanatory.
Cannot use newton pair with eam/alloy/gpu pair style Self-explanatory.
Cannot use newton pair with eam/fs/gpu pair style Self-explanatory.
Cannot use newton pair with eam/gpu pair style Self-explanatory.
Cannot use newton pair with gauss/gpu pair style Self-explanatory.
Cannot use newton pair with gayberne/gpu pair style Self-explanatory.
Cannot use newton pair with lj/charmm/coul/long/gpu pair style Self-explanatory.
Cannot use newton pair with lj/class2/coul/long/gpu pair style Self-explanatory.

11.4. Error messages 349

LAMMPS Documentation, Release stable 29Sep2021

Cannot use newton pair with lj/class2/gpu pair style Self-explanatory.

Cannot use newton pair with lj/cubic/gpu pair style Self-explanatory.
Cannot use newton pair with lj/cut/coul/cut/gpu pair style Self-explanatory.
Cannot use newton pair with lj/cut/coul/debye/gpu pair style Self-explanatory.
Cannot use newton pair with lj/cut/coul/dsf/gpu pair style Self-explanatory.
Cannot use newton pair with lj/cut/coul/long/gpu pair style Self-explanatory.
Cannot use newton pair with lj/cut/coul/msm/gpu pair style Self-explanatory.
Cannot use newton pair with lj/cut/gpu pair style Self-explanatory.
Cannot use newton pair with lj/expand/gpu pair style Self-explanatory.
Cannot use newton pair with lj/gromacs/gpu pair style Self-explanatory.
Cannot use newton pair with lj/sdk/coul/long/gpu pair style Self-explanatory.
Cannot use newton pair with lj/sdk/gpu pair style Self-explanatory.
Cannot use newton pair with lj96/cut/gpu pair style Self-explanatory.
Cannot use newton pair with mie/cut/gpu pair style Self-explanatory.
Cannot use newton pair with morse/gpu pair style Self-explanatory.
Cannot use newton pair with resquared/gpu pair style Self-explanatory.
Cannot use newton pair with soft/gpu pair style Self-explanatory.
Cannot use newton pair with table/gpu pair style Self-explanatory.
Cannot use newton pair with yukawa/colloid/gpu pair style Self-explanatory.
Cannot use newton pair with yukawa/gpu pair style Self-explanatory.
Cannot use newton pair with zbl/gpu pair style Self-explanatory.
Cannot use non-zero forces in an energy minimization Fix setforce cannot be used in this manner. Use fix addforce
instead.
Cannot use non-periodic boundares with fix ttm This fix requires a fully periodic simulation box.
Cannot use non-periodic boundaries with Ewald For kspace style ewald, all 3 dimensions must have periodic bound-
aries unless you use the kspace_modify command to define a 2d slab with a non-periodic z dimension.
Cannot use non-periodic boundaries with EwaldDisp For kspace style ewald/disp, all 3 dimensions must have peri-
odic boundaries unless you use the kspace_modify command to define a 2d slab with a non-periodic z dimension.
Cannot use non-periodic boundaries with PPPM For kspace style pppm, all 3 dimensions must have periodic bound-
aries unless you use the kspace_modify command to define a 2d slab with a non-periodic z dimension.
Cannot use non-periodic boundaries with PPPMDisp For kspace style pppm/disp, all 3 dimensions must have peri-
odic boundaries unless you use the kspace_modify command to define a 2d slab with a non-periodic z dimension.
Cannot use order greater than 8 with pppm/gpu. Self-explanatory.
Cannot use package gpu neigh yes with triclinic box This is a current restriction in LAMMPS.
Cannot use pair tail corrections with 2d simulations The correction factors are only currently defined for 3d systems.
Cannot use processors part command without using partitions See the command-line -partition switch.
Cannot use ramp in variable formula between runs This is because the ramp() function is time dependent.
Cannot use read_data add before simulation box is defined Self-explanatory.

350 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Cannot use read_data extra with add flag Self-explanatory.

Cannot use read_data offset without add flag Self-explanatory.
Cannot use read_data shift without add flag Self-explanatory.
Cannot use region INF or EDGE when box does not exist Regions that extend to the box boundaries can only be
used after the create_box command has been used.
Cannot use set atom with no atom IDs defined Atom IDs are not defined, so they cannot be used to identify an atom.
Cannot use set mol with no molecule IDs defined Self-explanatory.
Cannot use swiggle in variable formula between runs This is a function of elapsed time.
Cannot use tris with fix srd unless overlap is set This is because triangles are connected to each other.
Cannot use variable energy with constant efield in fix efield LAMMPS computes the energy itself when the E-field
is constant.
Cannot use variable energy with constant force in fix addforce This is because for constant force, LAMMPS can
compute the change in energy directly.
Cannot use variable every setting for dump dcd The format of DCD dump files requires snapshots be output at a con-
stant frequency.
Cannot use variable every setting for dump xtc The format of this file requires snapshots at regular intervals.
Cannot use vdisplace in variable formula between runs This is a function of elapsed time.
Cannot use velocity bias command without temp keyword Self-explanatory.
Cannot use velocity create loop all unless atoms have IDs Atoms in the simulation to do not have IDs, so this style
of velocity creation cannot be performed.
Cannot use wall in periodic dimension Self-explanatory.
Cannot use write_restart fileper without % in restart file name Self-explanatory.
Cannot use write_restart nfile without % in restart file name Self-explanatory.
Cannot wiggle and shear fix wall/gran Cannot specify both options at the same time.
Cannot write to restart file - MPI error: %s This error was generated by MPI when reading/writing an MPI-IO restart
file.
Cannot yet use KSpace solver with grid with comm style tiled This is current restriction in LAMMPS.
Cannot yet use comm_style tiled with multi-mode comm Self-explanatory.
Cannot yet use comm_style tiled with triclinic box Self-explanatory.
Cannot yet use compute tally with Kokkos This feature is not yet supported.
Cannot yet use fix bond/break with this improper style This is a current restriction in LAMMPS.
Cannot yet use fix bond/create with this improper style This is a current restriction in LAMMPS.
Cannot yet use minimize with Kokkos This feature is not yet supported.
Cannot yet use pair hybrid with Kokkos This feature is not yet supported.
Cannot zero Langevin force of 0 atoms The group has zero atoms, so you cannot request its force be zeroed.
Cannot zero gld force for zero atoms There are no atoms currently in the group.
Cannot zero momentum of no atoms Self-explanatory.
Change_box command before simulation box is defined Self-explanatory.

11.4. Error messages 351

LAMMPS Documentation, Release stable 29Sep2021

Change_box volume used incorrectly The “dim volume” option must be used immediately following one or two set-
tings for “dim1 . . . ” (and optionally “dim2 . . . ”) and must be for a different dimension, i.e. dim != dim1 and dim
!= dim2.
Chunk/atom compute does not exist for compute angmom/chunk Self-explanatory.
Chunk/atom compute does not exist for compute com/chunk Self-explanatory.
Chunk/atom compute does not exist for compute gyration/chunk Self-explanatory.
Chunk/atom compute does not exist for compute inertia/chunk Self-explanatory.
Chunk/atom compute does not exist for compute msd/chunk Self-explanatory.
Chunk/atom compute does not exist for compute omega/chunk Self-explanatory.
Chunk/atom compute does not exist for compute property/chunk Self-explanatory.
Chunk/atom compute does not exist for compute temp/chunk Self-explanatory.
Chunk/atom compute does not exist for compute torque/chunk Self-explanatory.
Chunk/atom compute does not exist for compute vcm/chunk Self-explanatory.
Chunk/atom compute does not exist for fix ave/chunk Self-explanatory.
Comm tiled invalid index in box drop brick Internal error check in comm_style tiled which should not occur. Contact
the developers.
Comm tiled mis-match in box drop brick Internal error check in comm_style tiled which should not occur. Contact
the developers.
Comm_modify group != atom_modify first group Self-explanatory.
Communication cutoff for comm_style tiled cannot exceed periodic box length Self-explanatory.
Communication cutoff too small for SNAP micro load balancing This can happen if you change the neighbor skin
after your pair_style command or if your box dimensions grow during a run. You can set the cutoff explicitly via
the comm_modify cutoff command.
Compute %s does not allow use of dynamic group Dynamic groups have not yet been enabled for this compute.
Compute for fix pafi does not calculate a local array Self-explanatory.
Compute for fix pafi must have 9 fields per atom Self-explanatory.
Compute ID for compute chunk /atom does not exist Self-explanatory.
Compute ID for compute chunk/atom does not exist Self-explanatory.
Compute gyration ID does not exist for compute gyration/shape Self-explanatory. Provide a valid compute ID.
Compute gyration/shape compute ID does not point to a gyration compute Self-explanatory. Provide and ID of a
compute gyration command.
Compute ID for compute reduce does not exist Self-explanatory.
Compute ID for compute slice does not exist Self-explanatory.
Compute ID for fix ave/atom does not exist Self-explanatory.
Compute ID for fix ave/chunk does not exist Self-explanatory.
Compute ID for fix ave/correlate does not exist Self-explanatory.
Compute ID for fix ave/histo does not exist Self-explanatory.
Compute ID for fix ave/time does not exist Self-explanatory.

352 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Compute ID for fix numdiff does not exist Self-explanatory.

Compute ID for fix store/state does not exist Self-explanatory.
Compute ID for fix vector does not exist Self-explanatory.
Compute ID must be alphanumeric or underscore characters Self-explanatory.
Compute angle/local used when angles are not allowed The atom style does not support angles.
Compute angmom/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute body/local requires atom style body Self-explanatory.
Compute bond/local used when bonds are not allowed The atom style does not support bonds.
Compute centro/atom requires a pair style be defined This is because the computation of the centro-symmetry values
uses a pairwise neighbor list.
Compute chunk/atom bin/cylinder radius is too large for periodic box Radius cannot be bigger than 1/2 of a non-axis
periodic dimension.
Compute chunk/atom bin/sphere radius is too large for periodic box Radius cannot be bigger than 1/2 of any peri-
odic dimension.
Compute chunk/atom compute array is accessed out-of-range The index for the array is out of bounds.
Compute chunk/atom compute does not calculate a per-atom array Self-explanatory.
Compute chunk/atom compute does not calculate a per-atom vector Self-explanatory.
Compute chunk/atom compute does not calculate per-atom values Self-explanatory.
Compute chunk/atom cylinder axis must be z for 2d Self-explanatory.
Compute chunk/atom fix array is accessed out-of-range the index for the array is out of bounds.
Compute chunk/atom fix does not calculate a per-atom array Self-explanatory.
Compute chunk/atom fix does not calculate a per-atom vector Self-explanatory.
Compute chunk/atom fix does not calculate per-atom values Self-explanatory.
Compute chunk/atom for triclinic boxes requires units reduced Self-explanatory.
Compute chunk/atom ids once but nchunk is not once You cannot assign chunks IDs to atom permanently if the
number of chunks may change.
Compute chunk/atom molecule for non-molecular system Self-explanatory.
Compute chunk/atom sphere z origin must be 0.0 for 2d Self-explanatory.
Compute chunk/atom stores no IDs for compute property/chunk It will only store IDs if its compress option is en-
abled.
Compute chunk/atom stores no coord1 for compute property/chunk Only certain binning options for compute
chunk/atom store coordinates.
Compute chunk/atom stores no coord2 for compute property/chunk Only certain binning options for compute
chunk/atom store coordinates.
Compute chunk/atom stores no coord3 for compute property/chunk Only certain binning options for compute
chunk/atom store coordinates.
Compute chunk/atom variable is not atom-style variable Self-explanatory.
Compute chunk/atom without bins cannot use discard mixed That discard option only applies to the binning styles.
Compute cluster/atom cutoff is longer than pairwise cutoff Cannot identify clusters beyond cutoff.

11.4. Error messages 353

LAMMPS Documentation, Release stable 29Sep2021

Compute cluster/atom requires a pair style be defined This is so that the pair style defines a cutoff distance which is
used to find clusters.
Compute cna/atom cutoff is longer than pairwise cutoff Self-explanatory.
Compute cna/atom requires a pair style be defined Self-explanatory.
Compute com/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute contact/atom requires a pair style be defined Self-explanatory.
Compute contact/atom requires atom style sphere Self-explanatory.
Compute coord/atom cutoff is longer than pairwise cutoff Cannot compute coordination at distances longer than the
pair cutoff, since those atoms are not in the neighbor list.
Compute coord/atom requires a pair style be defined Self-explanatory.
Compute damage/atom requires peridynamic potential Damage is a Peridynamic-specific metric. It requires you to
be running a Peridynamics simulation.
Compute dihedral/local used when dihedrals are not allowed The atom style does not support dihedrals.
Compute dilatation/atom cannot be used with this pair style Self-explanatory.
Compute dilatation/atom requires Peridynamic pair style Self-explanatory.
Compute does not allow an extra compute or fix to be reset This is an internal LAMMPS error. Please report it to
the developers.
Compute erotate/asphere requires atom style ellipsoid or line or tri Self-explanatory.
Compute erotate/asphere requires extended particles This compute cannot be used with point particles.
Compute erotate/rigid with non-rigid fix-ID Self-explanatory.
Compute erotate/sphere requires atom style sphere Self-explanatory.
Compute erotate/sphere/atom requires atom style sphere Self-explanatory.
Compute event/displace has invalid fix event assigned This is an internal LAMMPS error. Please report it to the de-
velopers.
Compute group/group group ID does not exist Self-explanatory.
Compute gyration/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute heat/flux compute ID does not compute ke/atom Self-explanatory.
Compute heat/flux compute ID does not compute pe/atom Self-explanatory.
Compute heat/flux compute ID does not compute stress/atom Self-explanatory.
Compute hexorder/atom cutoff is longer than pairwise cutoff Cannot compute order parameter beyond cutoff.
Compute hexorder/atom requires a pair style be defined Self-explanatory.
Compute improper/local used when impropers are not allowed The atom style does not support impropers.
Compute inertia/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute ke/rigid with non-rigid fix-ID Self-explanatory.
Compute msd/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute msd/chunk nchunk is not static This is required because the MSD cannot be computed consistently if the
number of chunks is changing. Compute chunk/atom allows setting nchunk to be static.
Compute nve/asphere requires atom style ellipsoid Self-explanatory.

354 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Compute nvt/nph/npt asphere requires atom style ellipsoid Self-explanatory.

Compute nvt/nph/npt body requires atom style body Self-explanatory.
Compute omega/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute orientorder/atom cutoff is longer than pairwise cutoff Cannot compute order parameter beyond cutoff.
Compute orientorder/atom requires a pair style be defined Self-explanatory.
Compute pair must use group all Pair styles accumulate energy on all atoms.
Compute pe must use group all Energies computed by potentials (pair, bond, etc) are computed on all atoms.
Compute plasticity/atom cannot be used with this pair style Self-explanatory.
Compute plasticity/atom requires Peridynamic pair style Self-explanatory.
Compute pressure must use group all Virial contributions computed by potentials (pair, bond, etc) are computed on
all atoms.
Compute pressure requires temperature ID to include kinetic energy The keflag cannot be used unless a temperature
compute is provided.
Compute pressure temperature ID does not compute temperature The compute ID assigned to a pressure computa-
tion must compute temperature.
Compute property/atom floating point vector does not exist The command is accessing a vector added by the fix prop-
erty/atom command, that does not exist.
Compute property/atom for atom property that is not allocated Self-explanatory.
Compute property/atom integer vector does not exist The command is accessing a vector added by the fix prop-
erty/atom command, that does not exist.
Compute property/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute property/local cannot use these inputs together Only inputs that generate the same number of datums can
be used together. E.g. bond and angle quantities cannot be mixed.
Compute property/local does not (yet) work with atom_style template Self-explanatory.
Compute property/local for property that is not allocated Self-explanatory.
Compute rdf requires a pair style be defined Self-explanatory.
Compute reduce compute array is accessed out-of-range An index for the array is out of bounds.
Compute reduce compute calculates global values A compute that calculates peratom or local values is required.
Compute reduce compute does not calculate a local array Self-explanatory.
Compute reduce compute does not calculate a local vector Self-explanatory.
Compute reduce compute does not calculate a per-atom array Self-explanatory.
Compute reduce compute does not calculate a per-atom vector Self-explanatory.
Compute reduce fix array is accessed out-of-range An index for the array is out of bounds.
Compute reduce fix calculates global values A fix that calculates peratom or local values is required.
Compute reduce fix does not calculate a local array Self-explanatory.
Compute reduce fix does not calculate a local vector Self-explanatory.
Compute reduce fix does not calculate a per-atom array Self-explanatory.
Compute reduce fix does not calculate a per-atom vector Self-explanatory.

11.4. Error messages 355

LAMMPS Documentation, Release stable 29Sep2021

Compute reduce replace requires min or max mode Self-explanatory.

Compute reduce variable is not atom-style variable Self-explanatory.
Compute slice compute array is accessed out-of-range An index for the array is out of bounds.
Compute slice compute does not calculate a global array Self-explanatory.
Compute slice compute does not calculate a global vector Self-explanatory.
Compute slice compute does not calculate global vector or array Self-explanatory.
Compute slice compute vector is accessed out-of-range The index for the vector is out of bounds.
Compute slice fix array is accessed out-of-range An index for the array is out of bounds.
Compute slice fix does not calculate a global array Self-explanatory.
Compute slice fix does not calculate a global vector Self-explanatory.
Compute slice fix does not calculate global vector or array Self-explanatory.
Compute slice fix vector is accessed out-of-range The index for the vector is out of bounds.
Compute sna/atom cutoff is longer than pairwise cutoff Self-explanatory.
Compute sna/atom requires a pair style be defined Self-explanatory.
Compute snad/atom cutoff is longer than pairwise cutoff Self-explanatory.
Compute snad/atom requires a pair style be defined Self-explanatory.
Compute snav/atom cutoff is longer than pairwise cutoff Self-explanatory.
Compute snav/atom requires a pair style be defined Self-explanatory.
Compute stress/atom temperature ID does not compute temperature The specified compute must compute tempera-
ture.
Compute temp/asphere requires atom style ellipsoid Self-explanatory.
Compute temp/asphere requires extended particles This compute cannot be used with point particles.
Compute temp/body requires atom style body Self-explanatory.
Compute temp/body requires bodies This compute can only be applied to body particles.
Compute temp/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute temp/cs requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Compute temp/cs used when bonds are not allowed This compute only works on pairs of bonded particles.
Compute temp/partial cannot use vz for 2d systemx Self-explanatory.
Compute temp/profile cannot bin z for 2d systems Self-explanatory.
Compute temp/profile cannot use vz for 2d systemx Self-explanatory.
Compute temp/sphere requires atom style sphere Self-explanatory.
Compute ti kspace style does not exist Self-explanatory.
Compute ti pair style does not exist Self-explanatory.
Compute ti tail when pair style does not compute tail corrections Self-explanatory.
Compute torque/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Compute used in dump between runs is not current The compute was not invoked on the current timestep, therefore
it cannot be used in a dump between runs.

356 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Compute used in variable between runs is not current Computes cannot be invoked by a variable in between runs.
Thus they must have been evaluated on the last timestep of the previous run in order for their value(s) to be
accessed. See the page for the variable command for more info.
Compute used in variable thermo keyword between runs is not current Some thermo keywords rely on a compute to
calculate their value(s). Computes cannot be invoked by a variable in between runs. Thus they must have been
evaluated on the last timestep of the previous run in order for their value(s) to be accessed. See the page for the
variable command for more info.
Compute vcm/chunk does not use chunk/atom compute The style of the specified compute is not chunk/atom.
Computed temperature for fix temp/berendsen cannot be 0.0 Self-explanatory.
Computed temperature for fix temp/rescale cannot be 0.0 Cannot rescale the temperature to a new value if the current
temperature is 0.0.
Core/shell partner atom not found Could not find one of the atoms in the bond pair.
Core/shell partners were not all found Could not find or more atoms in the bond pairs.
Could not adjust g_ewald_6 The Newton-Raphson solver failed to converge to a good value for g_ewald. This error
should not occur for typical problems. Please send an email to the developers.
Could not compute g_ewald The Newton-Raphson solver failed to converge to a good value for g_ewald. This error
should not occur for typical problems. Please send an email to the developers.
Could not compute grid size The code is unable to compute a grid size consistent with the desired accuracy. This
error should not occur for typical problems. Please send an email to the developers.
Could not compute grid size for Coulomb interaction The code is unable to compute a grid size consistent with the
desired accuracy. This error should not occur for typical problems. Please send an email to the developers.
Could not compute grid size for Dispersion The code is unable to compute a grid size consistent with the desired
accuracy. This error should not occur for typical problems. Please send an email to the developers.
Could not create 3d FFT plan The FFT setup for the PPPM solver failed, typically due to lack of memory. This is an
unusual error. Check the size of the FFT grid you are requesting.
Could not create 3d grid of processors The specified constraints did not allow a Px by Py by Pz grid to be created
where Px * Py * Pz = P = total number of processors.
Could not create 3d remap plan The FFT setup in pppm failed.
Could not create Python function arguments This is an internal Python error, possibly because the number of inputs
to the function is too large.
Could not create numa grid of processors The specified constraints did not allow this style of grid to be created. Usu-
ally this is because the total processor count is not a multiple of the cores/node or the user specified processor
count is > 1 in one of the dimensions.
Could not create twolevel 3d grid of processors The specified constraints did not allow this style of grid to be created.
Could not evaluate Python function input variable Self-explanatory.
Could not find Python function The provided Python code was run successfully, but it not define a callable function
with the required name.
Could not find atom_modify first group ID Self-explanatory.
Could not find change_box group ID Group ID used in the change_box command does not exist.
Could not find compute ID for PRD Self-explanatory.
Could not find compute ID for TAD Self-explanatory.
Could not find compute ID for temperature bias Self-explanatory.

11.4. Error messages 357

LAMMPS Documentation, Release stable 29Sep2021

Could not find compute ID to delete Self-explanatory.

Could not find compute displace/atom fix ID Self-explanatory.
Could not find compute event/displace fix ID Self-explanatory.
Could not find compute group ID Self-explanatory.
Could not find compute heat/flux compute ID Self-explanatory.
Could not find compute msd fix ID Self-explanatory.
Could not find compute msd/chunk fix ID The compute creates an internal fix, which has been deleted.
Could not find compute pressure temperature ID The compute ID for calculating temperature does not exist.
Could not find compute stress/atom temperature ID Self-explanatory.
Could not find compute vacf fix ID Self-explanatory.
Could not find compute/voronoi surface group ID Self-explanatory.
Could not find compute_modify ID Self-explanatory.
Could not find custom per-atom property ID Self-explanatory.
Could not find delete_atoms group ID Group ID used in the delete_atoms command does not exist.
Could not find delete_atoms region ID Region ID used in the delete_atoms command does not exist.
Could not find displace_atoms group ID Group ID used in the displace_atoms command does not exist.
Could not find dump custom compute ID Self-explanatory.
Could not find dump custom fix ID Self-explanatory.
Could not find dump custom variable name Self-explanatory.
Could not find dump group ID A group ID used in the dump command does not exist.
Could not find dump local compute ID Self-explanatory.
Could not find dump local fix ID Self-explanatory.
Could not find dump modify compute ID Self-explanatory.
Could not find dump modify custom atom floating point property ID Self-explanatory.
Could not find dump modify custom atom integer property ID Self-explanatory.
Could not find dump modify fix ID Self-explanatory.
Could not find dump modify variable name Self-explanatory.
Could not find fix ID to delete Self-explanatory.
Could not find fix adapt storage fix ID This should not happen unless you explicitly deleted a secondary fix that fix
adapt created internally.
Could not find fix halt variable name Self-explanatory.
Could not find fix gcmc exclusion group ID Self-explanatory.
Could not find fix gcmc rotation group ID Self-explanatory.
Could not find fix group ID A group ID used in the fix command does not exist.
Could not find fix msst compute ID Self-explanatory.
Could not find fix poems group ID A group ID used in the fix poems command does not exist.

358 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Could not find fix recenter group ID A group ID used in the fix recenter command does not exist.
Could not find fix rigid group ID A group ID used in the fix rigid command does not exist.
Could not find fix srd group ID Self-explanatory.
Could not find fix_modify ID A fix ID used in the fix_modify command does not exist.
Could not find fix_modify pressure ID The compute ID for computing pressure does not exist.
Could not find fix_modify temperature ID The compute ID for computing temperature does not exist.
Could not find group clear group ID Self-explanatory.
Could not find group delete group ID Self-explanatory.
Could not find pair fix ID A fix is created internally by the pair style to store shear history information. You cannot
delete it.
Could not find set group ID Group ID specified in set command does not exist.
Could not find specified fix gcmc group ID Self-explanatory.
Could not find thermo compute ID Compute ID specified in thermo_style command does not exist.
Could not find thermo custom compute ID The compute ID needed by thermo style custom to compute a requested
quantity does not exist.
Could not find thermo custom fix ID The fix ID needed by thermo style custom to compute a requested quantity does
not exist.
Could not find thermo custom variable name Self-explanatory.
Could not find thermo fix ID Fix ID specified in thermo_style command does not exist.
Could not find thermo variable name Self-explanatory.
Could not find thermo_modify pressure ID The compute ID needed by thermo style custom to compute pressure does
not exist.
Could not find thermo_modify temperature ID The compute ID needed by thermo style custom to compute temper-
ature does not exist.
Could not find undump ID A dump ID used in the undump command does not exist.
Could not find velocity group ID A group ID used in the velocity command does not exist.
Could not find velocity temperature ID The compute ID needed by the velocity command to compute temperature
does not exist.
Could not find/initialize a specified accelerator device Could not initialize at least one of the devices specified for the
gpu package
Could not grab element entry from EIM potential file Self-explanatory
Could not grab global entry from EIM potential file Self-explanatory.
Could not grab pair entry from EIM potential file Self-explanatory.
Could not initialize embedded Python The main module in Python was not accessible.
Could not open Python file The specified file of Python code cannot be opened. Check that the path and name are
correct.
Could not process Python file The Python code in the specified file was not run successfully by Python, probably due
to errors in the Python code.

11.4. Error messages 359

LAMMPS Documentation, Release stable 29Sep2021

Could not process Python string The Python code in the here string was not run successfully by Python, probably due
to errors in the Python code.
Coulomb PPPMDisp order has been reduced below minorder The default minimum order is 2. This can be reset by
the kspace_modify minorder command.
Coulombic cutoff not supported in pair_style buck/long/coul/coul Must use long-range Coulombic interactions.
Coulombic cutoff not supported in pair_style lj/long/coul/long Must use long-range Coulombic interactions.
Coulombic cutoff not supported in pair_style lj/long/tip4p/long Must use long-range Coulombic interactions.
Coulombic cutoffs of pair hybrid sub-styles do not match If using a Kspace solver, all Coulombic cutoffs of long pair
styles must be the same.
Coulombic cut not supported in pair_style lj/long/dipole/long Must use long-range Coulombic interactions.
Cound not find dump_modify ID Self-explanatory.
Create_atoms command before simulation box is defined The create_atoms command cannot be used before a
read_data, read_restart, or create_box command.
Create_atoms molecule has atom IDs, but system does not The atom_style id command can be used to force atom
IDs to be stored.
Create_atoms molecule must have atom types The defined molecule does not specify atom types.
Create_atoms molecule must have coordinates The defined molecule does not specify coordinates.
Create_atoms region ID does not exist A region ID used in the create_atoms command does not exist.
Create_bonds command before simulation box is defined Self-explanatory.
Create_bonds command requires no kspace_style be defined This is so that atom pairs that are already bonded to not
appear in the neighbor list.
Create_bonds command requires special_bonds 1-2 weights be 0.0 This is so that atom pairs that are already bonded
to not appear in the neighbor list.
Create_bonds max distance > neighbor cutoff Can only create bonds for atom pairs that will be in neighbor list.
Create_bonds requires a pair style be defined Self-explanatory.
Create_box region ID does not exist Self-explanatory.
Create_box region does not support a bounding box Not all regions represent bounded volumes. You cannot use
such a region with the create_box command.
Custom floating point vector for fix store/state does not exist The command is accessing a vector added by the fix
property/atom command, that does not exist.
Custom integer vector for fix store/state does not exist The command is accessing a vector added by the fix prop-
erty/atom command, that does not exist.
Custom per-atom property ID is not floating point Self-explanatory.
Custom per-atom property ID is not integer Self-explanatory.
Cut-offs missing in pair_style lj/long/dipole/long Self-explanatory.
Cutoffs missing in pair_style buck/long/coul/long Self-explanatory.
Cutoffs missing in pair_style lj/long/coul/long Self-explanatory.
Cyclic loop in joint connections Fix poems cannot (yet) work with coupled bodies whose joints connect the bodies in
a ring (or cycle).
Degenerate lattice primitive vectors Invalid set of 3 lattice vectors for lattice command.

360 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Delete region ID does not exist Self-explanatory.

Delete_atoms command before simulation box is defined The delete_atoms command cannot be used before a
read_data, read_restart, or create_box command.
Delete_atoms cutoff > max neighbor cutoff Can only delete atoms in atom pairs that will be in neighbor list.
Delete_atoms mol yes requires atom attribute molecule Cannot use this option with a non-molecular system.
Delete_atoms requires a pair style be defined This is because atom deletion within a cutoff uses a pairwise neighbor
list.
Delete_bonds command before simulation box is defined The delete_bonds command cannot be used before a
read_data, read_restart, or create_box command.
Delete_bonds command with no atoms existing No atoms are yet defined so the delete_bonds command cannot be
used.
Deposition region extends outside simulation box Self-explanatory.
Did not assign all atoms correctly Atoms read in from a data file were not assigned correctly to processors. This is
likely due to some atom coordinates being outside a non-periodic simulation box.
Did not assign all restart atoms correctly Atoms read in from the restart file were not assigned correctly to processors.
This is likely due to some atom coordinates being outside a non-periodic simulation box. Normally this should
not happen. You may wish to use the “remap” option on the read_restart command to see if this helps.
Did not find all elements in MEAM library file Some requested elements were not found in the MEAM file. Check
spelling etc.
Did not find fix shake partner info Could not find bond partners implied by fix shake command. This error can be
triggered if the delete_bonds command was used before fix shake, and it removed bonds without resetting the
1-2, 1-3, 1-4 weighting list via the special keyword.
Did not find keyword in table file Keyword used in pair_coeff command was not found in table file.
Did not set pressure for fix rigid/nph The press keyword must be specified.
Did not set temp for fix rigid/nvt/small Self-explanatory.
Did not set temp or press for fix rigid/npt/small Self-explanatory.
Did not set temperature for fix rigid/nvt The temp keyword must be specified.
Did not set temperature or pressure for fix rigid/npt The temp and press keywords must be specified.
Dihedral atom missing in delete_bonds The delete_bonds command cannot find one or more atoms in a particular
dihedral on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid
dihedral.
Dihedral atom missing in set command The set command cannot find one or more atoms in a particular dihedral on
a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid dihedral.
Dihedral atoms %d %d %d %d missing on proc %d at step %ld One or more of 4 atoms needed to compute a partic-
ular dihedral are missing on this processor. Typically this is because the pairwise cutoff is set too short or the
dihedral has blown apart and an atom is too far away.
Dihedral atoms missing on proc %d at step %ld One or more of 4 atoms needed to compute a particular dihedral are
missing on this processor. Typically this is because the pairwise cutoff is set too short or the dihedral has blown
apart and an atom is too far away.
Dihedral charmm is incompatible with Pair style Dihedral style charmm must be used with a pair style charmm in
order for the 1-4 epsilon/sigma parameters to be defined.

11.4. Error messages 361

LAMMPS Documentation, Release stable 29Sep2021

Dihedral coeff for hybrid has invalid style Dihedral style hybrid uses another dihedral style as one of its coefficients.
The dihedral style used in the dihedral_coeff command or read from a restart file is not recognized.
Dihedral coeffs are not set No dihedral coefficients have been assigned in the data file or via the dihedral_coeff com-
mand.
Dihedral style hybrid cannot have hybrid as an argument Self-explanatory.
Dihedral style hybrid cannot have none as an argument Self-explanatory.
Dihedral style hybrid cannot use same dihedral style twice Self-explanatory.
Dihedral/improper extent > half of periodic box length This error was detected by the neigh_modify check yes set-
ting. It is an error because the dihedral atoms are so far apart it is ambiguous how it should be defined.
Dihedral_coeff command before dihedral_style is defined Coefficients cannot be set in the data file or via the dihe-
dral_coeff command until an dihedral_style has been assigned.
Dihedral_coeff command before simulation box is defined The dihedral_coeff command cannot be used before a
read_data, read_restart, or create_box command.
Dihedral_coeff command when no dihedrals allowed The chosen atom style does not allow for dihedrals to be de-
fined.
Dihedral_style command when no dihedrals allowed The chosen atom style does not allow for dihedrals to be de-
fined.
Dihedrals assigned incorrectly Dihedrals read in from the data file were not assigned correctly to atoms. This means
there is something invalid about the topology definitions.
Dihedrals defined but no dihedral types The data file header lists dihedrals but no dihedral types.
Dimension command after simulation box is defined The dimension command cannot be used after a read_data,
read_restart, or create_box command.
Disk limit not supported by OS or illegal path Self-explanatory.
Dispersion PPPMDisp order has been reduced below minorder The default minimum order is 2. This can be reset
by the kspace_modify minorder command.
Displace_atoms command before simulation box is defined The displace_atoms command cannot be used before a
read_data, read_restart, or create_box command.
Distance must be > 0 for compute event/displace Self-explanatory.
Divide by 0 in influence function This should not normally occur. It is likely a problem with your model.
Divide by 0 in influence function of pair peri/lps This should not normally occur. It is likely a problem with your
model.
Divide by 0 in variable formula Self-explanatory.
Domain too large for neighbor bins The domain has become extremely large so that neighbor bins cannot be used.
Most likely, one or more atoms have been blown out of the simulation box to a great distance.
Double precision is not supported on this accelerator Self-explanatory
Dump atom/gz only writes compressed files The dump atom/gz output file name must have a .gz suffix.
Dump cfg arguments can not mix xs|ys|zs with xsu|ysu|zsu Self-explanatory.
Dump cfg arguments must start with ‘mass type xs ys zs’ or ‘mass type xsu ysu zsu’ This is a requirement of the
CFG output format. See the dump cfg doc page for more details.
Dump cfg requires one snapshot per file Use the wildcard “*” character in the filename.
Dump cfg/gz only writes compressed files The dump cfg/gz output file name must have a .gz suffix.

362 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Dump custom and fix not computed at compatible times The fix must produce per-atom quantities on timesteps that
dump custom needs them.
Dump custom compute does not calculate per-atom array Self-explanatory.
Dump custom compute does not calculate per-atom vector Self-explanatory.
Dump custom compute does not compute per-atom info Self-explanatory.
Dump custom compute vector is accessed out-of-range Self-explanatory.
Dump custom fix does not compute per-atom array Self-explanatory.
Dump custom fix does not compute per-atom info Self-explanatory.
Dump custom fix does not compute per-atom vector Self-explanatory.
Dump custom fix vector is accessed out-of-range Self-explanatory.
Dump custom variable is not atom-style variable Only atom-style variables generate per-atom quantities, needed for
dump output.
Dump custom/gz only writes compressed files The dump custom/gz output file name must have a .gz suffix.
Dump dcd of non-matching # of atoms Every snapshot written by dump dcd must contain the same # of atoms.
Dump dcd requires sorting by atom ID Use the dump_modify sort command to enable this.
Dump every variable returned a bad timestep The variable must return a timestep greater than the current timestep.
Dump file MPI-IO output not allowed with % in filename This is because a % signifies one file per processor and
MPI-IO creates one large file for all processors.
Dump file does not contain requested snapshot Self-explanatory.
Dump file is incorrectly formatted Self-explanatory.
Dump image body yes requires atom style body Self-explanatory.
Dump image bond not allowed with no bond types Self-explanatory.
Dump image cannot perform sorting Self-explanatory.
Dump image line requires atom style line Self-explanatory.
Dump image requires one snapshot per file Use a “*” in the filename.
Dump image tri requires atom style tri Self-explanatory.
Dump local and fix not computed at compatible times The fix must produce per-atom quantities on timesteps that
dump local needs them.
Dump local attributes contain no compute or fix Self-explanatory.
Dump local cannot sort by atom ID This is because dump local does not really dump per-atom info.
Dump local compute does not calculate local array Self-explanatory.
Dump local compute does not calculate local vector Self-explanatory.
Dump local compute does not compute local info Self-explanatory.
Dump local compute vector is accessed out-of-range Self-explanatory.
Dump local count is not consistent across input fields Every column of output must be the same length.
Dump local fix does not compute local array Self-explanatory.
Dump local fix does not compute local info Self-explanatory.

11.4. Error messages 363

LAMMPS Documentation, Release stable 29Sep2021

Dump local fix does not compute local vector Self-explanatory.

Dump local fix vector is accessed out-of-range Self-explanatory.
Dump modify bcolor not allowed with no bond types Self-explanatory.
Dump modify bdiam not allowed with no bond types Self-explanatory.
Dump modify compute ID does not compute per-atom array Self-explanatory.
Dump modify compute ID does not compute per-atom info Self-explanatory.
Dump modify compute ID does not compute per-atom vector Self-explanatory.
Dump modify compute ID vector is not large enough Self-explanatory.
Dump modify element names do not match atom types Number of element names must equal number of atom types.
Dump modify fix ID does not compute per-atom array Self-explanatory.
Dump modify fix ID does not compute per-atom info Self-explanatory.
Dump modify fix ID does not compute per-atom vector Self-explanatory.
Dump modify fix ID vector is not large enough Self-explanatory.
Dump modify variable is not atom-style variable Self-explanatory.
Dump sort column is invalid Self-explanatory.
Dump xtc requires sorting by atom ID Use the dump_modify sort command to enable this.
Dump xyz/gz only writes compressed files The dump xyz/gz output file name must have a .gz suffix.
Dump_modify buffer yes not allowed for this style Self-explanatory.
Dump_modify format string is too short There are more fields to be dumped in a line of output than your format string
specifies.
Dump_modify region ID does not exist Self-explanatory.
Dumping an atom property that is not allocated The chosen atom style does not define the per-atom quantity being
dumped.
Duplicate atom IDs exist Self-explanatory.
Duplicate fields in read_dump command Self-explanatory.
Duplicate particle in PeriDynamic bond - simulation box is too small This is likely because your box length is
shorter than 2 times the bond length.
Electronic temperature dropped below zero Something has gone wrong with the fix ttm electron temperature model.
Element not defined in potential file The specified element is not in the potential file.
Empty brackets in variable There is no variable syntax that uses empty brackets. Check the variable doc page.
Energy was not tallied on needed timestep You are using a thermo keyword that requires potentials to have tallied
energy, but they did not on this timestep. See the variable page for ideas on how to make this work.
Epsilon or sigma reference not set by pair style in PPPMDisp Self-explanatory.
Epsilon or sigma reference not set by pair style in ewald/n The pair style is not providing the needed epsilon or sigma
values.
Error in MEAM parameter file: keyword %s (further information) Self-explanatory. Check the parameter file.
Error in vdw spline: inner radius > outer radius A pre-tabulated spline is invalid. Likely a problem with the potential
parameters.

364 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Error writing averaged chunk data Something in the output to the file triggered an error.
Error writing file header Something in the output to the file triggered an error.
Error writing out correlation data Something in the output to the file triggered an error.
Error writing out histogram data Something in the output to the file triggered an error.
Error writing out time averaged data Something in the output to the file triggered an error.
Failed to allocate %ld bytes for array %s Your LAMMPS simulation has run out of memory. You need to run a
smaller simulation or on more processors.
Failed to open FFmpeg pipeline to file %s The specified file cannot be opened. Check that the path and name are
correct and writable and that the FFmpeg executable can be found and run.
Failed to reallocate %ld bytes for array %s Your LAMMPS simulation has run out of memory. You need to run a
smaller simulation or on more processors.
Fewer SRD bins than processors in some dimension This is not allowed. Make your SRD bin size smaller.
File variable could not read value Check the file assigned to the variable.
Final box dimension due to fix deform is < 0.0 Self-explanatory.
Fix %s does not allow use of dynamic group Dynamic groups have not yet been enabled for this fix.
Fix ID for compute chunk/atom does not exist Self-explanatory.
Fix ID for compute erotate/rigid does not exist Self-explanatory.
Fix ID for compute ke/rigid does not exist Self-explanatory.
Fix ID for compute reduce does not exist Self-explanatory.
Fix ID for compute slice does not exist Self-explanatory.
Fix ID for fix ave/atom does not exist Self-explanatory.
Fix ID for fix ave/chunk does not exist Self-explanatory.
Fix ID for fix ave/correlate does not exist Self-explanatory.
Fix ID for fix ave/histo does not exist Self-explanatory.
Fix ID for fix ave/time does not exist Self-explanatory.
Fix ID for fix store/state does not exist Self-explanatory
Fix ID for fix vector does not exist Self-explanatory.
Fix ID for read_data does not exist Self-explanatory.
Fix ID for velocity does not exist Self-explanatory.
Fix ID must be alphanumeric or underscore characters Self-explanatory.
Fix SRD: bad bin assignment for SRD advection Something has gone wrong in your SRD model; try using more
conservative settings.
Fix SRD: bad search bin assignment Something has gone wrong in your SRD model; try using more conservative
settings.
Fix SRD: bad stencil bin for big particle Something has gone wrong in your SRD model; try using more conservative
settings.
Fix SRD: too many big particles in bin Reset the ATOMPERBIN parameter at the top of fix_srd.cpp to a larger value,
and re-compile the code.

11.4. Error messages 365

LAMMPS Documentation, Release stable 29Sep2021

Fix SRD: too many walls in bin This should not happen unless your system has been setup incorrectly.
Fix adapt interface to this pair style not supported New coding for the pair style would need to be done.
Fix adapt kspace style does not exist Self-explanatory.
Fix adapt pair style does not exist Self-explanatory
Fix adapt pair style param not supported The pair style does not know about the parameter you specified.
Fix adapt requires atom attribute charge The atom style being used does not specify an atom charge.
Fix adapt requires atom attribute diameter The atom style being used does not specify an atom diameter.
Fix adapt type pair range is not valid for pair hybrid sub-style Self-explanatory.
Fix append/atoms requires a lattice be defined Use the lattice command for this purpose.
Fix ave/atom compute array is accessed out-of-range Self-explanatory.
Fix ave/atom compute does not calculate a per-atom array Self-explanatory.
Fix ave/atom compute does not calculate a per-atom vector A compute used by fix ave/atom must generate per-atom
values.
Fix ave/atom compute does not calculate per-atom values A compute used by fix ave/atom must generate per-atom
values.
Fix ave/atom fix array is accessed out-of-range Self-explanatory.
Fix ave/atom fix does not calculate a per-atom array Self-explanatory.
Fix ave/atom fix does not calculate a per-atom vector A fix used by fix ave/atom must generate per-atom values.
Fix ave/atom fix does not calculate per-atom values A fix used by fix ave/atom must generate per-atom values.
Fix ave/atom variable is not atom-style variable A variable used by fix ave/atom must generate per-atom values.
Fix ave/chunk compute does not calculate a per-atom array Self-explanatory.
Fix ave/chunk compute does not calculate a per-atom vector Self-explanatory.
Fix ave/chunk compute does not calculate per-atom values Self-explanatory.
Fix ave/chunk compute vector is accessed out-of-range Self-explanatory.
Fix ave/chunk does not use chunk/atom compute The specified compute is not for a compute chunk/atom command.
Fix ave/chunk fix does not calculate a per-atom array Self-explanatory.
Fix ave/chunk fix does not calculate a per-atom vector Self-explanatory.
Fix ave/chunk fix does not calculate per-atom values Self-explanatory.
Fix ave/chunk fix vector is accessed out-of-range Self-explanatory.
Fix ave/chunk variable is not atom-style variable Self-explanatory.
Fix ave/correlate compute does not calculate a scalar Self-explanatory.
Fix ave/correlate compute does not calculate a vector Self-explanatory.
Fix ave/correlate compute vector is accessed out-of-range The index for the vector is out of bounds.
Fix ave/correlate fix does not calculate a scalar Self-explanatory.
Fix ave/correlate fix does not calculate a vector Self-explanatory.
Fix ave/correlate fix vector is accessed out-of-range The index for the vector is out of bounds.
Fix ave/correlate variable is not equal-style variable Self-explanatory.

366 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Fix ave/histo cannot input local values in scalar mode Self-explanatory.

Fix ave/histo cannot input per-atom values in scalar mode Self-explanatory.
Fix ave/histo compute array is accessed out-of-range Self-explanatory.
Fix ave/histo compute does not calculate a global array Self-explanatory.
Fix ave/histo compute does not calculate a global scalar Self-explanatory.
Fix ave/histo compute does not calculate a global vector Self-explanatory.
Fix ave/histo compute does not calculate a local array Self-explanatory.
Fix ave/histo compute does not calculate a local vector Self-explanatory.
Fix ave/histo compute does not calculate a per-atom array Self-explanatory.
Fix ave/histo compute does not calculate a per-atom vector Self-explanatory.
Fix ave/histo compute does not calculate local values Self-explanatory.
Fix ave/histo compute does not calculate per-atom values Self-explanatory.
Fix ave/histo compute vector is accessed out-of-range Self-explanatory.
Fix ave/histo fix array is accessed out-of-range Self-explanatory.
Fix ave/histo fix does not calculate a global array Self-explanatory.
Fix ave/histo fix does not calculate a global scalar Self-explanatory.
Fix ave/histo fix does not calculate a global vector Self-explanatory.
Fix ave/histo fix does not calculate a local array Self-explanatory.
Fix ave/histo fix does not calculate a local vector Self-explanatory.
Fix ave/histo fix does not calculate a per-atom array Self-explanatory.
Fix ave/histo fix does not calculate a per-atom vector Self-explanatory.
Fix ave/histo fix does not calculate local values Self-explanatory.
Fix ave/histo fix does not calculate per-atom values Self-explanatory.
Fix ave/histo fix vector is accessed out-of-range Self-explanatory.
Fix ave/histo input is invalid compute Self-explanatory.
Fix ave/histo input is invalid fix Self-explanatory.
Fix ave/histo input is invalid variable Self-explanatory.
Fix ave/histo inputs are not all global, peratom, or local All inputs in a single fix ave/histo command must be of the
same style.
Fix ave/histo/weight value and weight vector lengths do not match Self-explanatory.
Fix ave/time cannot set output array intensive/extensive from these inputs One of more of the vector inputs has in-
dividual elements which are flagged as intensive or extensive. Such an input cannot be flagged as all inten-
sive/extensive when turned into an array by fix ave/time.
Fix ave/time cannot use variable with vector mode Variables produce scalar values.
Fix ave/time columns are inconsistent lengths Self-explanatory.
Fix ave/time compute array is accessed out-of-range An index for the array is out of bounds.
Fix ave/time compute does not calculate a scalar Self-explanatory.

11.4. Error messages 367

LAMMPS Documentation, Release stable 29Sep2021

Fix ave/time compute does not calculate a vector Self-explanatory.

Fix ave/time compute does not calculate an array Self-explanatory.
Fix ave/time compute vector is accessed out-of-range The index for the vector is out of bounds.
Fix ave/time fix array cannot be variable length Self-explanatory.
Fix ave/time fix array is accessed out-of-range An index for the array is out of bounds.
Fix ave/time fix does not calculate a scalar Self-explanatory.
Fix ave/time fix does not calculate a vector Self-explanatory.
Fix ave/time fix does not calculate an array Self-explanatory.
Fix ave/time fix vector cannot be variable length Self-explanatory.
Fix ave/time fix vector is accessed out-of-range The index for the vector is out of bounds.
Fix ave/time variable is not equal-style variable Self-explanatory.
Fix balance rcb cannot be used with comm_style brick Comm_style tiled must be used instead.
Fix balance shift string is invalid The string can only contain the characters “x”, “y”, or “z”.
Fix bond/break needs ghost atoms from further away This is because the fix needs to walk bonds to a certain distance
to acquire needed info, The comm_modify cutoff command can be used to extend the communication range.
Fix bond/create angle type is invalid Self-explanatory.
Fix bond/create cutoff is longer than pairwise cutoff This is not allowed because bond creation is done using the
pairwise neighbor list.
Fix bond/create dihedral type is invalid Self-explanatory.
Fix bond/create improper type is invalid Self-explanatory.
Fix bond/create induced too many angles/dihedrals/impropers per atom See the read_data command for info on us-
ing the “extra/angle/per/atom”, (or dihedral, improper) keywords to allow for additional angles, dihedrals, and
impropers to be formed.
Fix bond/create needs ghost atoms from further away This is because the fix needs to walk bonds to a certain dis-
tance to acquire needed info, The comm_modify cutoff command can be used to extend the communication
range.
Fix bond/swap cannot use dihedral or improper styles These styles cannot be defined when using this fix.
Fix bond/swap requires pair and bond styles Self-explanatory.
Fix bond/swap requires special_bonds = 0,1,1 Self-explanatory.
Fix box/relax generated negative box length The pressure being applied is likely too large. Try applying it incremen-
tally, to build to the high pressure.
Fix command before simulation box is defined The fix command cannot be used before a read_data, read_restart, or
create_box command.
Fix deform cannot use yz variable with xy The yz setting cannot be a variable if xy deformation is also specified. This
is because LAMMPS cannot determine if the yz setting will induce a box flip which would be invalid if xy is
also changing.
Fix deform is changing yz too much with xy When both yz and xy are changing, it induces changes in xz if the box
must flip from one tilt extreme to another. Thus it is not allowed for yz to grow so much that a flip is induced.
Fix deform tilt factors require triclinic box Cannot deform the tilt factors of a simulation box unless it is a triclinic
(non-orthogonal) box.

368 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Fix deform volume setting is invalid Cannot use volume style unless other dimensions are being controlled.
Fix deposit and fix rigid/small not using same molecule template ID Self-explanatory.
Fix deposit and fix shake not using same molecule template ID Self-explanatory.
Fix deposit molecule must have atom types The defined molecule does not specify atom types.
Fix deposit molecule must have coordinates The defined molecule does not specify coordinates.
Fix deposit molecule template ID must be same as atom_style template ID When using atom_style template, you
cannot deposit molecules that are not in that template.
Fix deposit region cannot be dynamic Only static regions can be used with fix deposit.
Fix deposit region does not support a bounding box Not all regions represent bounded volumes. You cannot use such
a region with the fix deposit command.
Fix deposit shake fix does not exist Self-explanatory.
Fix efield requires atom attribute q or mu The atom style defined does not have this attribute.
Fix efield with dipoles cannot use atom-style variables This option is not supported.
Fix evaporate molecule requires atom attribute molecule The atom style being used does not define a molecule ID.
Fix external callback function not set This must be done by an external program in order to use this fix.
Fix for fix ave/atom not computed at compatible time Fixes generate their values on specific timesteps. Fix ave/atom
is requesting a value on a non-allowed timestep.
Fix for fix ave/chunk not computed at compatible time Fixes generate their values on specific timesteps. Fix
ave/chunk is requesting a value on a non-allowed timestep.
Fix for fix ave/correlate not computed at compatible time Fixes generate their values on specific timesteps. Fix
ave/correlate is requesting a value on a non-allowed timestep.
Fix for fix ave/histo not computed at compatible time Fixes generate their values on specific timesteps. Fix ave/histo
is requesting a value on a non-allowed timestep.
Fix for fix ave/spatial not computed at compatible time Fixes generate their values on specific timesteps. Fix
ave/spatial is requesting a value on a non-allowed timestep.
Fix for fix ave/time not computed at compatible time Fixes generate their values on specific timesteps. Fix ave/time
is requesting a value on a non-allowed timestep.
Fix for fix store/state not computed at compatible time Fixes generate their values on specific timesteps. Fix
store/state is requesting a value on a non-allowed timestep.
Fix for fix vector not computed at compatible time Fixes generate their values on specific timesteps. Fix vector is
requesting a value on a non-allowed timestep.
Fix freeze requires atom attribute torque The atom style defined does not have this attribute.
Fix gcmc and fix shake not using same molecule template ID Self-explanatory.
Fix gcmc atom has charge, but atom style does not Self-explanatory.
Fix gcmc cannot exchange individual atoms belonging to a molecule This is an error since you should not delete
only one atom of a molecule. The user has specified atomic (non-molecular) gas exchanges, but an atom be-
longing to a molecule could be deleted.
Fix gcmc does not (yet) work with atom_style template Self-explanatory.
Fix gcmc molecule command requires that atoms have molecule attributes Should not choose the gcmc molecule
feature if no molecules are being simulated. The general molecule flag is off, but gcmc’s molecule flag is on.

11.4. Error messages 369

LAMMPS Documentation, Release stable 29Sep2021

Fix gcmc molecule has charges, but atom style does not Self-explanatory.
Fix gcmc molecule must have atom types The defined molecule does not specify atom types.
Fix gcmc molecule must have coordinates The defined molecule does not specify coordinates.
Fix gcmc molecule template ID must be same as atom_style template ID When using atom_style template, you can-
not insert molecules that are not in that template.
Fix gcmc put atom outside box This should not normally happen. Contact the developers.
Fix gcmc ran out of available atom IDs See the setting for tagint in the src/lmptype.h file.
Fix gcmc ran out of available molecule IDs See the setting for tagint in the src/lmptype.h file.
Fix gcmc region cannot be dynamic Only static regions can be used with fix gcmc.
Fix gcmc region does not support a bounding box Not all regions represent bounded volumes. You cannot use such
a region with the fix gcmc command.
Fix gcmc region extends outside simulation box Self-explanatory.
Fix gcmc shake fix does not exist Self-explanatory.
Fix gld c coefficients must be >= 0 Self-explanatory.
Fix gld needs more prony series coefficients Self-explanatory.
Fix gld prony terms must be > 0 Self-explanatory.
Fix gld series type must be pprony for now Self-explanatory.
Fix gld start temperature must be >= 0 Self-explanatory.
Fix gld stop temperature must be >= 0 Self-explanatory.
Fix gld tau coefficients must be > 0 Self-explanatory.
Fix halt variable is not equal-style variable Self-explanatory.
Fix heat group has no atoms Self-explanatory.
Fix heat kinetic energy of an atom went negative This will cause the velocity rescaling about to be performed by fix
heat to be invalid.
Fix heat kinetic energy went negative This will cause the velocity rescaling about to be performed by fix heat to be
invalid.
Fix in variable not computed at compatible time Fixes generate their values on specific timesteps. The variable is
requesting the values on a non-allowed timestep.
Fix langevin angmom is not yet implemented with kokkos This option is not yet available.
Fix langevin angmom requires atom style ellipsoid Self-explanatory.
Fix langevin angmom requires extended particles This fix option cannot be used with point particles.
Fix langevin gjf and respa are not compatible Self-explanatory.
Fix langevin gjf cannot have period equal to dt/2 If the period is equal to dt/2 then division by zero will happen.
Fix langevin gjf should come before fix nve Self-explanatory.
Fix langevin gjf with tbias is not yet implemented with kokkos This option is not yet available.
Fix langevin omega is not yet implemented with kokkos This option is not yet available.
Fix langevin omega requires atom style sphere Self-explanatory.
Fix langevin omega requires extended particles One of the particles has radius 0.0.

370 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Fix langevin period must be > 0.0 The time window for temperature relaxation must be > 0
Fix langevin variable returned negative temperature Self-explanatory.
Fix momentum group has no atoms Self-explanatory.
Fix move cannot define z or vz variable for 2d problem Self-explanatory.
Fix move cannot rotate aroung non z-axis for 2d problem Self-explanatory.
Fix move cannot set linear z motion for 2d problem Self-explanatory.
Fix move cannot set wiggle z motion for 2d problem Self-explanatory.
Fix msst compute ID does not compute potential energy Self-explanatory.
Fix msst compute ID does not compute pressure Self-explanatory.
Fix msst compute ID does not compute temperature Self-explanatory.
Fix msst requires a periodic box Self-explanatory.
Fix msst tscale must satisfy 0 <= tscale < 1 Self-explanatory.
Fix npt/nph has tilted box too far in one step - periodic cell is too far from equilibrium state Self-explanatory. The
change in the box tilt is too extreme on a short timescale.
Fix numdiff requires an atom map, see atom_modify Self-explanatory. Efficient loop over all atoms for numerical
difference requires an atom map.
Fix numdiff requires consecutive atom IDs Self-explanatory. Efficient loop over all atoms for numerical difference
requires consecutive atom IDs.
Fix nve/asphere requires extended particles This fix can only be used for particles with a shape setting.
Fix nve/asphere/noforce requires atom style ellipsoid Self-explanatory.
Fix nve/asphere/noforce requires extended particles One of the particles is not an ellipsoid.
Fix nve/body requires atom style body Self-explanatory.
Fix nve/body requires bodies This fix can only be used for particles that are bodies.
Fix nve/line can only be used for 2d simulations Self-explanatory.
Fix nve/line requires atom style line Self-explanatory.
Fix nve/line requires line particles Self-explanatory.
Fix nve/sphere dipole requires atom attribute mu An atom style with this attribute is needed.
Fix nve/sphere requires atom style sphere Self-explanatory.
Fix nve/sphere requires extended particles This fix can only be used for particles of a finite size.
Fix nve/tri can only be used for 3d simulations Self-explanatory.
Fix nve/tri requires atom style tri Self-explanatory.
Fix nve/tri requires tri particles Self-explanatory.
Fix nvt/nph/npt asphere requires extended particles The shape setting for a particle in the fix group has shape = 0.0,
which means it is a point particle.
Fix nvt/nph/npt body requires bodies Self-explanatory.
Fix nvt/nph/npt sphere requires atom style sphere Self-explanatory.
Fix nvt/npt/nph damping parameters must be > 0.0 Self-explanatory.

11.4. Error messages 371

LAMMPS Documentation, Release stable 29Sep2021

Fix nvt/npt/nph dilate group ID does not exist Self-explanatory.

Fix nvt/sphere requires extended particles This fix can only be used for particles of a finite size.
Fix orient/fcc file open failed The fix orient/fcc command could not open a specified file.
Fix orient/fcc file read failed The fix orient/fcc command could not read the needed parameters from a specified file.
Fix orient/fcc found self twice The neighbor lists used by fix orient/fcc are messed up. If this error occurs, it is likely
a bug, so send an email to the developers.
Fix peri neigh does not exist Somehow a fix that the pair style defines has been deleted.
Fix pour and fix rigid/small not using same molecule template ID Self-explanatory.
Fix pour and fix shake not using same molecule template ID Self-explanatory.
Fix pour insertion count per timestep is 0 Self-explanatory.
Fix pour molecule must have atom types The defined molecule does not specify atom types.
Fix pour molecule must have coordinates The defined molecule does not specify coordinates.
Fix pour molecule template ID must be same as atom style template ID When using atom_style template, you can-
not pour molecules that are not in that template.
Fix pour polydisperse fractions do not sum to 1.0 Self-explanatory.
Fix pour region ID does not exist Self-explanatory.
Fix pour region cannot be dynamic Only static regions can be used with fix pour.
Fix pour region does not support a bounding box Not all regions represent bounded volumes. You cannot use such
a region with the fix pour command.
Fix pour requires atom attributes radius, rmass The atom style defined does not have these attributes.
Fix pour rigid fix does not exist Self-explanatory.
Fix pour shake fix does not exist Self-explanatory.
Fix press/berendsen damping parameters must be > 0.0 Self-explanatory.
Fix property/atom cannot specify mol twice Self-explanatory.
Fix property/atom cannot specify q twice Self-explanatory.
Fix property/atom mol when atom_style already has molecule attribute Self-explanatory.
Fix property/atom q when atom_style already has charge attribute Self-explanatory.
Fix property/atom vector name already exists The name for an integer or floating-point vector must be unique.
Fix qeq has negative upper Taper radius cutoff Self-explanatory.
Fix qeq/comb group has no atoms Self-explanatory.
Fix qeq/comb requires atom attribute q An atom style with charge must be used to perform charge equilibration.
Fix qeq/dynamic group has no atoms Self-explanatory.
Fix qeq/dynamic requires atom attribute q Self-explanatory.
Fix qeq/fire group has no atoms Self-explanatory.
Fix qeq/fire requires atom attribute q Self-explanatory.
Fix qeq/point group has no atoms Self-explanatory.

372 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Fix qeq/point has insufficient QEq matrix size Occurs when number of neighbor atoms for an atom increased too
much during a run. Increase SAFE_ZONE and MIN_CAP in fix_qeq.h and re-compile.
Fix qeq/point requires atom attribute q Self-explanatory.
Fix qeq/shielded group has no atoms Self-explanatory.
Fix qeq/shielded has insufficient QEq matrix size Occurs when number of neighbor atoms for an atom increased too
much during a run. Increase SAFE_ZONE and MIN_CAP in fix_qeq.h and re-compile.
Fix qeq/shielded requires atom attribute q Self-explanatory.
Fix qeq/slater could not extract params from pair coul/streitz This should not happen unless pair coul/streitz has
been altered.
Fix qeq/slater group has no atoms Self-explanatory.
Fix qeq/slater has insufficient QEq matrix size Occurs when number of neighbor atoms for an atom increased too
much during a run. Increase SAFE_ZONE and MIN_CAP in fix_qeq.h and re-compile.
Fix qeq/slater requires atom attribute q Self-explanatory.
Fix reax/bonds numbonds > nsbmax_most The limit of the number of bonds expected by the ReaxFF force field was
exceeded.
Fix recenter group has no atoms Self-explanatory.
Fix restrain requires an atom map, see atom_modify Self-explanatory.
Fix rigid atom has non-zero image flag in a non-periodic dimension Image flags for non-periodic dimensions
should not be set.
Fix rigid file has no lines Self-explanatory.
Fix rigid langevin period must be > 0.0 Self-explanatory.
Fix rigid molecule requires atom attribute molecule Self-explanatory.
Fix rigid npt/nph dilate group ID does not exist Self-explanatory.
Fix rigid npt/nph does not yet allow triclinic box This is a current restriction in LAMMPS.
Fix rigid npt/nph period must be > 0.0 Self-explanatory.
Fix rigid npt/small t_chain should not be less than 1 Self-explanatory.
Fix rigid npt/small t_order must be 3 or 5 Self-explanatory.
Fix rigid nvt/npt/nph damping parameters must be > 0.0 Self-explanatory.
Fix rigid nvt/small t_chain should not be less than 1 Self-explanatory.
Fix rigid nvt/small t_iter should not be less than 1 Self-explanatory.
Fix rigid nvt/small t_order must be 3 or 5 Self-explanatory.
Fix rigid xy torque cannot be on for 2d simulation Self-explanatory.
Fix rigid z force cannot be on for 2d simulation Self-explanatory.
Fix rigid/npt period must be > 0.0 Self-explanatory.
Fix rigid/npt temperature order must be 3 or 5 Self-explanatory.
Fix rigid/npt/small period must be > 0.0 Self-explanatory.
Fix rigid/nvt period must be > 0.0 Self-explanatory.
Fix rigid/nvt temperature order must be 3 or 5 Self-explanatory.

11.4. Error messages 373

LAMMPS Documentation, Release stable 29Sep2021

Fix rigid/nvt/small period must be > 0.0 Self-explanatory.

Fix rigid/small atom has non-zero image flag in a non-periodic dimension Image flags for non-periodic dimensions
should not be set.
Fix rigid/small langevin period must be > 0.0 Self-explanatory.
Fix rigid/small molecule must have atom types The defined molecule does not specify atom types.
Fix rigid/small molecule must have coordinates The defined molecule does not specify coordinates.
Fix rigid/small npt/nph period must be > 0.0 Self-explanatory.
Fix rigid/small nvt/npt/nph damping parameters must be > 0.0 Self-explanatory.
Fix rigid/small nvt/npt/nph dilate group ID does not exist Self-explanatory.
Fix rigid/small requires an atom map, see atom_modify Self-explanatory.
Fix rigid/small requires atom attribute molecule Self-explanatory.
Fix rigid: Bad principal moments The principal moments of inertia computed for a rigid body are not within the
required tolerances.
Fix shake cannot be used with minimization Cannot use fix shake while doing an energy minimization since it turns
off bonds that should contribute to the energy.
Fix shake molecule template must have shake info The defined molecule does not specify SHAKE information.
Fix spring couple group ID does not exist Self-explanatory.
Fix srd can only currently be used with comm_style brick This is a current restriction in LAMMPS.
Fix srd lamda must be >= 0.6 of SRD grid size This is a requirement for accuracy reasons.
Fix srd no-slip requires atom attribute torque This is because the SRD collisions will impart torque to the solute par-
ticles.
Fix srd requires SRD particles all have same mass Self-explanatory.
Fix srd requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Fix srd requires newton pair on Self-explanatory.
Fix store/state compute array is accessed out-of-range Self-explanatory.
Fix store/state compute does not calculate a per-atom array The compute calculates a per-atom vector.
Fix store/state compute does not calculate a per-atom vector The compute calculates a per-atom vector.
Fix store/state compute does not calculate per-atom values Computes that calculate global or local quantities cannot
be used with fix store/state.
Fix store/state fix array is accessed out-of-range Self-explanatory.
Fix store/state fix does not calculate a per-atom array The fix calculates a per-atom vector.
Fix store/state fix does not calculate a per-atom vector The fix calculates a per-atom array.
Fix store/state fix does not calculate per-atom values Fixes that calculate global or local quantities cannot be used
with fix store/state.
Fix store/state for atom property that is not allocated Self-explanatory.
Fix store/state variable is not atom-style variable Only atom-style variables calculate per-atom quantities.
Fix temp/berendsen period must be > 0.0 Self-explanatory.
Fix temp/berendsen variable returned negative temperature Self-explanatory.

374 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Fix temp/csld is not compatible with fix rattle or fix shake These two commands cannot currently be used together
with fix temp/csld.
Fix temp/csld variable returned negative temperature Self-explanatory.
Fix temp/csvr variable returned negative temperature Self-explanatory.
Fix temp/rescale variable returned negative temperature Self-explanatory.
Fix tfmc displacement length must be > 0 Self-explanatory.
Fix tfmc is not compatible with fix shake These two commands cannot currently be used together.
Fix tfmc temperature must be > 0 Self-explanatory.
Fix thermal/conductivity swap value must be positive Self-explanatory.
Fix tmd must come after integration fixes Any fix tmd command must appear in the input script after all time inte-
gration fixes (nve, nvt, npt). See the fix tmd documentation for details.
Fix ttm electron temperatures must be > 0.0 Self-explanatory.
Fix ttm electronic_density must be > 0.0 Self-explanatory.
Fix ttm electronic_specific_heat must be > 0.0 Self-explanatory.
Fix ttm electronic_thermal_conductivity must be >= 0.0 Self-explanatory.
Fix ttm gamma_p must be > 0.0 Self-explanatory.
Fix ttm gamma_s must be >= 0.0 Self-explanatory.
Fix ttm number of nodes must be > 0 Self-explanatory.
Fix ttm v_0 must be >= 0.0 Self-explanatory.
Fix used in compute chunk/atom not computed at compatible time The chunk/atom compute cannot query the out-
put of the fix on a timestep it is needed.
Fix used in compute reduce not computed at compatible time Fixes generate their values on specific timesteps.
Compute reduce is requesting a value on a non-allowed timestep.
Fix used in compute slice not computed at compatible time Fixes generate their values on specific timesteps. Com-
pute slice is requesting a value on a non-allowed timestep.
Fix vector cannot set output array intensive/extensive from these inputs The inputs to the command have conflicting
intensive/extensive attributes. You need to use more than one fix vector command.
Fix vector compute does not calculate a scalar Self-explanatory.
Fix vector compute does not calculate a vector Self-explanatory.
Fix vector compute vector is accessed out-of-range Self-explanatory.
Fix vector fix does not calculate a scalar Self-explanatory.
Fix vector fix does not calculate a vector Self-explanatory.
Fix vector fix vector is accessed out-of-range Self-explanatory.
Fix vector variable is not equal-style variable Self-explanatory.
Fix viscosity swap value must be positive Self-explanatory.
Fix viscosity vtarget value must be positive Self-explanatory.
Fix wall cutoff <= 0.0 Self-explanatory.
Fix wall/colloid requires atom style sphere Self-explanatory.

11.4. Error messages 375

LAMMPS Documentation, Release stable 29Sep2021

Fix wall/colloid requires extended particles One of the particles has radius 0.0.
Fix wall/gran is incompatible with Pair style Must use a granular pair style to define the parameters needed for this
fix.
Fix wall/gran requires atom style sphere Self-explanatory.
Fix wall/piston command only available at zlo The face keyword must be zlo.
Fix wall/region colloid requires atom style sphere Self-explanatory.
Fix wall/region colloid requires extended particles One of the particles has radius 0.0.
Fix wall/region cutoff <= 0.0 Self-explanatory.
Fix_modify pressure ID does not compute pressure The compute ID assigned to the fix must compute pressure.
Fix_modify temperature ID does not compute temperature The compute ID assigned to the fix must compute tem-
perature.
For triclinic deformation, specified target stress must be hydrostatic Triclinic pressure control is allowed using the
tri keyword, but non-hydrostatic pressure control can not be used in this case.
Found no restart file matching pattern When using a “*” in the restart file name, no matching file was found.
GPU library not compiled for this accelerator Self-explanatory.
GPU package does not (yet) work with atom_style template Self-explanatory.
GPU particle split must be set to 1 for this pair style. For this pair style, you cannot run part of the force calculation
on the host. See the package command.
GPUs are requested but Kokkos has not been compiled for CUDA Re-compile Kokkos with CUDA support to use
GPUs.
Ghost velocity forward comm not yet implemented with Kokkos This is a current restriction.
Gmask function in equal-style variable formula Gmask is per-atom operation.
Gravity changed since fix pour was created The gravity vector defined by fix gravity must be static.
Gravity must point in -y to use with fix pour in 2d Self-explanatory.
Gravity must point in -z to use with fix pour in 3d Self-explanatory.
Grmask function in equal-style variable formula Grmask is per-atom operation.
Group ID does not exist A group ID used in the group command does not exist.
Group ID in variable formula does not exist Self-explanatory.
Group all cannot be made dynamic This operation is not allowed.
Group command before simulation box is defined The group command cannot be used before a read_data,
read_restart, or create_box command.
Group dynamic cannot reference itself Self-explanatory.
Group dynamic parent group cannot be dynamic Self-explanatory.
Group dynamic parent group does not exist Self-explanatory.
Group region ID does not exist A region ID used in the group command does not exist.
If read_dump purges it cannot replace or trim These operations are not compatible. See the read_dump doc page for
details.
Illegal . . . command Self-explanatory. Check the input script syntax and compare to the documentation for the com-
mand. You can use -echo screen as a command-line option when running LAMMPS to see the offending line.

376 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Illegal COMB parameter One or more of the coefficients defined in the potential file is invalid.
Illegal COMB3 parameter One or more of the coefficients defined in the potential file is invalid.
Illegal Stillinger-Weber parameter One or more of the coefficients defined in the potential file is invalid.
Illegal Tersoff parameter One or more of the coefficients defined in the potential file is invalid.
Illegal Vashishta parameter One or more of the coefficients defined in the potential file is invalid.
Illegal compute voronoi/atom command (occupation and (surface or edges)) Self-explanatory.
Illegal coul/streitz parameter One or more of the coefficients defined in the potential file is invalid.
Illegal dump_modify sfactor value (must be > 0.0) Self-explanatory.
Illegal dump_modify tfactor value (must be > 0.0) Self-explanatory.
Illegal fix gcmc gas mass <= 0 The computed mass of the designated gas molecule or atom type was less than or equal
to zero.
Illegal fix tfmc random seed Seeds can only be nonzero positive integers.
Illegal fix wall/piston velocity The piston velocity must be positive.
Illegal integrate style Self-explanatory.
Illegal nb3b/harmonic parameter One or more of the coefficients defined in the potential file is invalid.
Illegal number of angle table entries There must be at least 2 table entries.
Illegal number of bond table entries There must be at least 2 table entries.
Illegal number of pair table entries There must be at least 2 table entries.
Illegal or unset periodicity in restart This error should not normally occur unless the restart file is invalid.
Illegal range increment value The increment must be >= 1.
Illegal simulation box The lower bound of the simulation box is greater than the upper bound.
Illegal size double vector read requested This error should not normally occur unless the restart file is invalid.
Illegal size integer vector read requested This error should not normally occur unless the restart file is invalid.
Illegal size string or corrupt restart This error should not normally occur unless the restart file is invalid.
Imageint setting in lmptype.h is invalid Imageint must be as large or larger than smallint.
Imageint setting in lmptype.h is not compatible Format of imageint stored in restart file is not consistent with
LAMMPS version you are running. See the settings in src/lmptype.h
Improper atom missing in delete_bonds The delete_bonds command cannot find one or more atoms in a particular
improper on a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid
improper.
Improper atom missing in set command The set command cannot find one or more atoms in a particular improper on
a particular processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid improper.
Improper atoms %d %d %d %d missing on proc %d at step %ld One or more of 4 atoms needed to compute a par-
ticular improper are missing on this processor. Typically this is because the pairwise cutoff is set too short or the
improper has blown apart and an atom is too far away.
Improper atoms missing on proc %d at step %ld One or more of 4 atoms needed to compute a particular improper
are missing on this processor. Typically this is because the pairwise cutoff is set too short or the improper has
blown apart and an atom is too far away.

11.4. Error messages 377

LAMMPS Documentation, Release stable 29Sep2021

Improper coeff for hybrid has invalid style Improper style hybrid uses another improper style as one of its coefficients.
The improper style used in the improper_coeff command or read from a restart file is not recognized.
Improper coeffs are not set No improper coefficients have been assigned in the data file or via the improper_coeff
command.
Improper style hybrid cannot have hybrid as an argument Self-explanatory.
Improper style hybrid cannot have none as an argument Self-explanatory.
Improper style hybrid cannot use same improper style twice Self-explanatory.
Improper_coeff command before improper_style is defined Coefficients cannot be set in the data file or via the im-
proper_coeff command until an improper_style has been assigned.
Improper_coeff command before simulation box is defined The improper_coeff command cannot be used before a
read_data, read_restart, or create_box command.
Improper_coeff command when no impropers allowed The chosen atom style does not allow for impropers to be de-
fined.
Improper_style command when no impropers allowed The chosen atom style does not allow for impropers to be de-
fined.
Impropers assigned incorrectly Impropers read in from the data file were not assigned correctly to atoms. This means
there is something invalid about the topology definitions.
Impropers defined but no improper types The data file header lists improper but no improper types.
Incompatible KIM Simulator Model The requested KIM Simulator Model was defined for a different MD code and
thus is not compatible with LAMMPS.
Incompatible units for KIM Simulator Model The selected unit style is not compatible with the requested KIM Sim-
ulator Model.
Incomplete use of variables in create_atoms command The var and set options must be used together.
Inconsistent iparam/jparam values in fix bond/create command If itype and jtype are the same, then their maxbond
and newtype settings must also be the same.
Inconsistent line segment in data file The end points of the line segment are not equal distances from the center point
which is the atom coordinate.
Inconsistent triangle in data file The centroid of the triangle as defined by the corner points is not the atom coordinate.
Inconsistent use of finite-size particles by molecule template molecules Not all of the molecules define a radius for
their constituent particles.
Incorrect # of floating-point values in Bodies section of data file See page for body style.
Incorrect # of integer values in Bodies section of data file See page for body style.
Incorrect %s format in data file A section of the data file being read by fix property/atom does not have the correct
number of values per line.
Incorrect SNAP parameter file The file cannot be parsed correctly, check its internal syntax.
Incorrect args for angle coefficients Self-explanatory. Check the input script or data file.
Incorrect args for bond coefficients Self-explanatory. Check the input script or data file.
Incorrect args for dihedral coefficients Self-explanatory. Check the input script or data file.
Incorrect args for improper coefficients Self-explanatory. Check the input script or data file.
Incorrect args for pair coefficients Self-explanatory. Check the input script or data file.

378 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Incorrect args in pair_style command Self-explanatory.

Incorrect atom format in data file Number of values per atom line in the data file is not consistent with the atom style.
Incorrect atom format in neb file The number of fields per line is not what expected.
Incorrect bonus data format in data file See the read_data page for a description of how various kinds of bonus data
must be formatted for certain atom styles.
Incorrect boundaries with slab Ewald Must have periodic x,y dimensions and non-periodic z dimension to use 2d
slab option with Ewald.
Incorrect boundaries with slab EwaldDisp Must have periodic x,y dimensions and non-periodic z dimension to use
2d slab option with Ewald.
Incorrect boundaries with slab PPPM Must have periodic x,y dimensions and non-periodic z dimension to use 2d
slab option with PPPM.
Incorrect boundaries with slab PPPMDisp Must have periodic x,y dimensions and non-periodic z dimension to use
2d slab option with pppm/disp.
Incorrect conversion in format string A format style variable was not using either a %f, a %g, or a %e conversion.
Or an immediate variable with format suffix was not using either a %f, a %g or a %e conversion in the format
suffix.
Incorrect element names in ADP potential file The element names in the ADP file do not match those requested.
Incorrect element names in EAM potential file The element names in the EAM file do not match those requested.
Incorrect format of . . . section in data file Number or type of values per line in the given section of the data file is not
consistent with the requirements for this section.
Incorrect format in COMB potential file Incorrect number of words per line in the potential file.
Incorrect format in COMB3 potential file Incorrect number of words per line in the potential file.
Incorrect format in MEAM library file Incorrect number of words per line in the potential file.
Incorrect format in SNAP coefficient file Incorrect number of words per line in the coefficient file.
Incorrect format in SNAP parameter file Incorrect number of words per line in the parameter file.
Incorrect format in Stillinger-Weber potential file Incorrect number of words per line in the potential file.
Incorrect format in TMD target file Format of file read by fix tmd command is incorrect.
Incorrect format in Tersoff potential file Incorrect number of words per line in the potential file.
Incorrect format in Vashishta potential file Incorrect number of words per line in the potential file.
Incorrect format in coul/streitz potential file Incorrect number of words per line in the potential file.
Incorrect format in nb3b/harmonic potential file Incorrect number of words per line in the potential file.
Incorrect integer value in Bodies section of data file See page for body style.
Incorrect multiplicity arg for dihedral coefficients Self-explanatory. Check the input script or data file.
Incorrect number of elements in potential file Self-explanatory.
Incorrect rigid body format in fix rigid file The number of fields per line is not what expected.
Incorrect rigid body format in fix rigid/small file The number of fields per line is not what expected.
Incorrect sign arg for dihedral coefficients Self-explanatory. Check the input script or data file.
Incorrect table format check for element types Self-explanatory.

11.4. Error messages 379

LAMMPS Documentation, Release stable 29Sep2021

Incorrect velocity format in data file Each atom style defines a format for the Velocity section of the data file. The
read-in lines do not match.
Incorrect weight arg for dihedral coefficients Self-explanatory. Check the input script or data file.
Index between variable brackets must be positive Self-explanatory.
Indexed per-atom vector in variable formula without atom map Accessing a value from an atom vector requires the
ability to lookup an atom index, which is provided by an atom map. An atom map does not exist (by default) for
non-molecular problems. Using the atom_modify map command will force an atom map to be created.
Initial temperatures not all set in fix ttm Self-explanatory.
Input line quote not followed by white-space An end quote must be followed by white-space.
Insertion region extends outside simulation box Self-explanatory.
Insufficient Jacobi rotations for POEMS body Eigensolve for rigid body was not sufficiently accurate.
Insufficient Jacobi rotations for body nparticle Eigensolve for rigid body was not sufficiently accurate.
Insufficient Jacobi rotations for rigid body Eigensolve for rigid body was not sufficiently accurate.
Insufficient Jacobi rotations for rigid molecule Eigensolve for rigid body was not sufficiently accurate.
Insufficient Jacobi rotations for triangle The calculation of the inertia tensor of the triangle failed. This should not
happen if it is a reasonably shaped triangle.
Insufficient memory on accelerator There is insufficient memory on one of the devices specified for the gpu package
Internal error in atom_style body This error should not occur. Contact the developers.
Invalid -reorder N value Self-explanatory.
Invalid Angles section in molecule file Self-explanatory.
Invalid Bonds section in molecule file Self-explanatory.
Invalid Boolean syntax in if command Self-explanatory.
Invalid Charges section in molecule file Self-explanatory.
Invalid Coords section in molecule file Self-explanatory.
Invalid Diameters section in molecule file Self-explanatory.
Invalid Dihedrals section in molecule file Self-explanatory.
Invalid Impropers section in molecule file Self-explanatory.
Invalid Kokkos command-line args Self-explanatory. See Section 2.7 of the manual for details.
Invalid LAMMPS restart file The file does not appear to be a LAMMPS restart file since it does not contain the correct
magic string at the beginning.
Invalid Masses section in molecule file Self-explanatory.
Invalid molecule ID in molecule file Molecule ID must be a non-zero positive integer.
Invalid Molecules section in molecule file Self-explanatory.
Invalid REAX atom type There is a mis-match between LAMMPS atom types and the elements listed in the ReaxFF
force field file.
Invalid Special Bond Counts section in molecule file Self-explanatory.
Invalid Types section in molecule file Self-explanatory.
Invalid angle count in molecule file Self-explanatory.

380 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Invalid angle table length Length must be 2 or greater.

Invalid angle type in Angles section of data file Angle type must be positive integer and within range of specified
angle types.
Invalid angle type in Angles section of molecule file Self-explanatory.
Invalid angle type index for fix shake Self-explanatory.
Invalid args for non-hybrid pair coefficients “NULL” is only supported in pair_coeff calls when using pair hybrid
Invalid argument to factorial %d N must be >= 0 and <= 167, otherwise the factorial result is too large.
Invalid atom ID in %s section of data file An atom in a section of the data file being read by fix property/atom has an
invalid atom ID that is <= 0 or > the maximum existing atom ID.
Invalid atom ID in Angles section of data file Atom IDs must be positive integers and within range of defined atoms.
Invalid atom ID in Angles section of molecule file Self-explanatory.
Invalid atom ID in Atoms section of data file Atom IDs must be positive integers.
Invalid atom ID in Bodies section of data file Atom IDs must be positive integers and within range of defined atoms.
Invalid atom ID in Bonds section of data file Atom IDs must be positive integers and within range of defined atoms.
Invalid atom ID in Bonds section of molecule file Self-explanatory.
Invalid atom ID in Bonus section of data file Atom IDs must be positive integers and within range of defined atoms.
Invalid atom ID in Dihedrals section of data file Atom IDs must be positive integers and within range of defined
atoms.
Invalid atom ID in Fragments section of molecule file Self-explanatory.
Invalid atom ID in Impropers section of data file Atom IDs must be positive integers and within range of defined
atoms.
Invalid atom ID in Velocities section of data file Atom IDs must be positive integers and within range of defined
atoms.
Invalid atom ID in dihedrals section of molecule file Self-explanatory.
Invalid atom ID in impropers section of molecule file Self-explanatory.
Invalid atom ID in variable file Self-explanatory.
Invalid atom IDs in neb file An ID in the file was not found in the system.
Invalid atom diameter in molecule file Diameters must be >= 0.0.
Invalid atom mass for fix shake Mass specified in fix shake command must be > 0.0.
Invalid atom mass in molecule file Masses must be > 0.0.
Invalid atom type in Atoms section of data file Atom types must range from 1 to specified # of types.
Invalid atom type in create_atoms command The create_box command specified the range of valid atom types. An
invalid type is being requested.
Invalid atom type in create_atoms mol command The atom types in the defined molecule are added to the value spec-
ified in the create_atoms command, as an offset. The final value for each atom must be between 1 to N, where N
is the number of atom types.
Invalid atom type in fix atom/swap command The atom type specified in the atom/swap command does not exist.
Invalid atom type in fix bond/create command Self-explanatory.
Invalid atom type in fix deposit command Self-explanatory.

11.4. Error messages 381

LAMMPS Documentation, Release stable 29Sep2021

Invalid atom type in fix deposit mol command The atom types in the defined molecule are added to the value specified
in the create_atoms command, as an offset. The final value for each atom must be between 1 to N, where N is
the number of atom types.
Invalid atom type in fix gcmc command The atom type specified in the gcmc command does not exist.
Invalid atom type in fix pour command Self-explanatory.
Invalid atom type in fix pour mol command The atom types in the defined molecule are added to the value specified
in the create_atoms command, as an offset. The final value for each atom must be between 1 to N, where N is
the number of atom types.
Invalid atom type in molecule file Atom types must range from 1 to specified # of types.
Invalid atom type in neighbor exclusion list Atom types must range from 1 to Ntypes inclusive.
Invalid atom type index for fix shake Atom types must range from 1 to Ntypes inclusive.
Invalid atom types in pair_write command Atom types must range from 1 to Ntypes inclusive.
Invalid atom vector in variable formula The atom vector is not recognized.
Invalid atom_style body command No body style argument was provided.
Invalid atom_style command Self-explanatory.
Invalid attribute in dump custom command Self-explanatory.
Invalid attribute in dump local command Self-explanatory.
Invalid attribute in dump modify command Self-explanatory.
Invalid basis setting in create_atoms command The basis index must be between 1 to N where N is the number of
basis atoms in the lattice. The type index must be between 1 to N where N is the number of atom types.
Invalid basis setting in fix append/atoms command The basis index must be between 1 to N where N is the number
of basis atoms in the lattice. The type index must be between 1 to N where N is the number of atom types.
Invalid bin bounds in compute chunk/atom The lo/hi values are inconsistent.
Invalid bin bounds in fix ave/spatial The lo/hi values are inconsistent.
Invalid body nparticle command Arguments in atom-style command are not correct.
Invalid bond count in molecule file Self-explanatory.
Invalid bond table length Length must be 2 or greater.
Invalid bond type in Bonds section of data file Bond type must be positive integer and within range of specified bond
types.
Invalid bond type in Bonds section of molecule file Self-explanatory.
Invalid bond type in create_bonds command Self-explanatory.
Invalid bond type in fix bond/break command Self-explanatory.
Invalid bond type in fix bond/create command Self-explanatory.
Invalid bond type index for fix shake Self-explanatory. Check the fix shake command in the input script.
Invalid coeffs for this dihedral style Cannot set class 2 coeffs in data file for this dihedral style.
Invalid color in dump_modify command The specified color name was not in the list of recognized colors. See the
dump_modify doc page.
Invalid color map min/max values The min/max values are not consistent with either each other or with values in the
color map.

382 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Invalid command-line argument One or more command-line arguments is invalid. Check the syntax of the command
you are using to launch LAMMPS.
Invalid compute ID in variable formula The compute is not recognized.
Invalid create_atoms rotation vector for 2d model The rotation vector can only have a z component.
Invalid custom OpenCL parameter string. There are not enough or too many parameters in the custom string for pack-
age GPU.
Invalid cutoff in comm_modify command Specified cutoff must be >= 0.0.
Invalid cutoffs in pair_write command Inner cutoff must be larger than 0.0 and less than outer cutoff.
Invalid d1 or d2 value for pair colloid coeff Neither d1 or d2 can be < 0.
Invalid data file section: Angle Coeffs Atom style does not allow angles.
Invalid data file section: AngleAngle Coeffs Atom style does not allow impropers.
Invalid data file section: AngleAngleTorsion Coeffs Atom style does not allow dihedrals.
Invalid data file section: AngleTorsion Coeffs Atom style does not allow dihedrals.
Invalid data file section: Angles Atom style does not allow angles.
Invalid data file section: Bodies Atom style does not allow bodies.
Invalid data file section: Bond Coeffs Atom style does not allow bonds.
Invalid data file section: BondAngle Coeffs Atom style does not allow angles.
Invalid data file section: BondBond Coeffs Atom style does not allow angles.
Invalid data file section: BondBond13 Coeffs Atom style does not allow dihedrals.
Invalid data file section: Bonds Atom style does not allow bonds.
Invalid data file section: Dihedral Coeffs Atom style does not allow dihedrals.
Invalid data file section: Dihedrals Atom style does not allow dihedrals.
Invalid data file section: Ellipsoids Atom style does not allow ellipsoids.
Invalid data file section: EndBondTorsion Coeffs Atom style does not allow dihedrals.
Invalid data file section: Improper Coeffs Atom style does not allow impropers.
Invalid data file section: Impropers Atom style does not allow impropers.
Invalid data file section: Lines Atom style does not allow lines.
Invalid data file section: MiddleBondTorsion Coeffs Atom style does not allow dihedrals.
Invalid data file section: Triangles Atom style does not allow triangles.
Invalid delta_conf in tad command The value must be between 0 and 1 inclusive.
Invalid density in Atoms section of data file Density value cannot be <= 0.0.
Invalid density in set command Density must be > 0.0.
Invalid diameter in set command Self-explanatory.
Invalid dihedral count in molecule file Self-explanatory.
Invalid dihedral type in Dihedrals section of data file Dihedral type must be positive integer and within range of spec-
ified dihedral types.
Invalid dihedral type in dihedrals section of molecule file Self-explanatory.

11.4. Error messages 383

LAMMPS Documentation, Release stable 29Sep2021

Invalid dipole length in set command Self-explanatory.

Invalid displace_atoms rotate axis for 2d Axis must be in z direction.
Invalid dump dcd filename Filenames used with the dump dcd style cannot be binary or compressed or cause multiple
files to be written.
Invalid dump frequency Dump frequency must be 1 or greater.
Invalid dump image element name The specified element name was not in the standard list of elements. See the
dump_modify doc page.
Invalid dump image filename The file produced by dump image cannot be binary and must be for a single processor.
Invalid dump image theta value Theta must be between 0.0 and 180.0 inclusive.
Invalid dump image zoom value Zoom value must be > 0.0.
Invalid dump movie filename The file produced by dump movie cannot be binary or compressed and must be a single
file for a single processor.
Invalid dump xtc filename Filenames used with the dump xtc style cannot be binary or compressed or cause multiple
files to be written.
Invalid dump xyz filename Filenames used with the dump xyz style cannot be binary or cause files to be written by
each processor.
Invalid dump_modify threshold operator Operator keyword used for threshold specification in not recognized.
Invalid entry in -reorder file Self-explanatory.
Invalid fix ID in variable formula The fix is not recognized.
Invalid fix ave/time off column Self-explanatory.
Invalid fix box/relax command for a 2d simulation Fix box/relax styles involving the z dimension cannot be used in
a 2d simulation.
Invalid fix box/relax command pressure settings If multiple dimensions are coupled, those dimensions must be spec-
ified.
Invalid fix box/relax pressure settings Settings for coupled dimensions must be the same.
Invalid fix halt attribute Self-explanatory.
Invalid fix halt operator Self-explanatory.
Invalid fix nvt/npt/nph command for a 2d simulation Cannot control z dimension in a 2d model.
Invalid fix nvt/npt/nph command pressure settings If multiple dimensions are coupled, those dimensions must be
specified.
Invalid fix nvt/npt/nph pressure settings Settings for coupled dimensions must be the same.
Invalid fix press/berendsen for a 2d simulation The z component of pressure cannot be controlled for a 2d model.
Invalid fix press/berendsen pressure settings Settings for coupled dimensions must be the same.
Invalid fix qeq parameter file Element index > number of atom types.
Invalid fix rigid npt/nph command for a 2d simulation Cannot control z dimension in a 2d model.
Invalid fix rigid npt/nph command pressure settings If multiple dimensions are coupled, those dimensions must be
specified.
Invalid fix rigid/small npt/nph command for a 2d simulation Cannot control z dimension in a 2d model.

384 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Invalid fix rigid/small npt/nph command pressure settings If multiple dimensions are coupled, those dimensions
must be specified.
Invalid flag in force field section of restart file Unrecognized entry in restart file.
Invalid flag in header section of restart file Unrecognized entry in restart file.
Invalid flag in peratom section of restart file The format of this section of the file is not correct.
Invalid flag in type arrays section of restart file Unrecognized entry in restart file.
Invalid frequency in temper command Nevery must be > 0.
Invalid group ID in neigh_modify command A group ID used in the neigh_modify command does not exist.
Invalid group function in variable formula Group function is not recognized.
Invalid group in comm_modify command Self-explanatory.
Invalid image up vector Up vector cannot be (0,0,0).
Invalid immediate variable Syntax of immediate value is incorrect.
Invalid improper count in molecule file Self-explanatory.
Invalid improper type in Impropers section of data file Improper type must be positive integer and within range of
specified improper types.
Invalid improper type in impropers section of molecule file Self-explanatory.
Invalid index for non-body particles in compute body/local command Only indices 1,2,3 can be used for non-body
particles.
Invalid index in compute body/local command Self-explanatory.
Invalid is_active() function in variable formula Self-explanatory.
Invalid is_available() function in variable formula Self-explanatory.
Invalid is_defined() function in variable formula Self-explanatory.
Invalid keyword in angle table parameters Self-explanatory.
Invalid keyword in bond table parameters Self-explanatory.
Invalid keyword in compute angle/local command Self-explanatory.
Invalid keyword in compute bond/local command Self-explanatory.
Invalid keyword in compute dihedral/local command Self-explanatory.
Invalid keyword in compute improper/local command Self-explanatory.
Invalid keyword in compute pair/local command Self-explanatory.
Invalid keyword in compute property/atom command Self-explanatory.
Invalid keyword in compute property/chunk command Self-explanatory.
Invalid keyword in compute property/local command Self-explanatory.
Invalid keyword in dump cfg command Self-explanatory.
Invalid keyword in pair table parameters Keyword used in list of table parameters is not recognized.
Invalid length in set command Self-explanatory.
Invalid mass in set command Self-explanatory.
Invalid mass line in data file Self-explanatory.

11.4. Error messages 385

LAMMPS Documentation, Release stable 29Sep2021

Invalid mass value Self-explanatory.

Invalid math function in variable formula Self-explanatory.
Invalid math/group/special function in variable formula Self-explanatory.
Invalid option in lattice command for non-custom style Certain lattice keywords are not supported unless the lattice
style is “custom”.
Invalid order of forces within respa levels For respa, ordering of force computations within respa levels must obey
certain rules. E.g. bonds cannot be compute less frequently than angles, pairwise forces cannot be computed
less frequently than kspace, etc.
Invalid pair table cutoff Cutoffs in pair_coeff command are not valid with read-in pair table.
Invalid pair table length Length of read-in pair table is invalid
Invalid param file for fix qeq/shielded Invalid value of gamma.
Invalid param file for fix qeq/slater Zeta value is 0.0.
Invalid partitions in processors part command Valid partitions are numbered 1 to N and the sender and receiver can-
not be the same partition.
Invalid python command Self-explanatory. Check the input script syntax and compare to the documentation for the
command. You can use -echo screen as a command-line option when running LAMMPS to see the offending
line.
Invalid radius in Atoms section of data file Radius must be >= 0.0.
Invalid random number seed in fix ttm command Random number seed must be > 0.
Invalid random number seed in set command Random number seed must be > 0.
Invalid replace values in compute reduce Self-explanatory.
Invalid rigid body ID in fix rigid file The ID does not match the number of an existing ID of rigid bodies that are
defined by the fix rigid command.
Invalid rigid body ID in fix rigid/small file The ID does not match the number of an existing ID of rigid bodies that
are defined by the fix rigid/small command.
Invalid run command N value The number of timesteps must fit in a 32-bit integer. If you want to run for more steps
than this, perform multiple shorter runs.
Invalid run command start/stop value Self-explanatory.
Invalid run command upto value Self-explanatory.
Invalid seed for Marsaglia random # generator The initial seed for this random number generator must be a positive
integer less than or equal to 900 million.
Invalid seed for Park random # generator The initial seed for this random number generator must be a positive inte-
ger.
Invalid shake angle type in molecule file Self-explanatory.
Invalid shake atom in molecule file Self-explanatory.
Invalid shake bond type in molecule file Self-explanatory.
Invalid shake flag in molecule file Self-explanatory.
Invalid shape in Ellipsoids section of data file Self-explanatory.
Invalid shape in Triangles section of data file Two or more of the triangle corners are duplicate points.
Invalid shape in set command Self-explanatory.

386 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Invalid shear direction for fix wall/gran Self-explanatory.

Invalid special atom index in molecule file Self-explanatory.
Invalid special function in variable formula Self-explanatory.
Invalid style in pair_write command Self-explanatory. Check the input script.
Invalid syntax in variable formula Self-explanatory.
Invalid t_event in prd command Self-explanatory.
Invalid t_event in tad command The value must be greater than 0.
Invalid template atom in Atoms section of data file The atom indices must be between 1 to N, where N is the number
of atoms in the template molecule the atom belongs to.
Invalid template index in Atoms section of data file The template indices must be between 1 to N, where N is the
number of molecules in the template.
Invalid thermo keyword in variable formula The keyword is not recognized.
Invalid threads_per_atom specified. For 3-body potentials on the GPU, the threads_per_atom setting cannot be greater
than 4 for NVIDIA GPUs.
Invalid timestep reset for fix ave/atom Resetting the timestep has invalidated the sequence of timesteps this fix needs
to process.
Invalid timestep reset for fix ave/chunk Resetting the timestep has invalidated the sequence of timesteps this fix needs
to process.
Invalid timestep reset for fix ave/correlate Resetting the timestep has invalidated the sequence of timesteps this fix
needs to process.
Invalid timestep reset for fix ave/histo Resetting the timestep has invalidated the sequence of timesteps this fix needs
to process.
Invalid timestep reset for fix ave/spatial Resetting the timestep has invalidated the sequence of timesteps this fix needs
to process.
Invalid timestep reset for fix ave/time Resetting the timestep has invalidated the sequence of timesteps this fix needs
to process.
Invalid tmax in tad command The value must be greater than 0.0.
Invalid type for mass set Mass command must set a type from 1-N where N is the number of atom types.
Invalid use of library file() function This function is called through the library interface. This error should not occur.
Contact the developers if it does.
Invalid value in set command The value specified for the setting is invalid, likely because it is too small or too large.
Invalid variable evaluation in variable formula A variable used in a formula could not be evaluated.
Invalid variable in next command Self-explanatory.
Invalid variable name Variable name used in an input script line is invalid.
Invalid variable name in variable formula Variable name is not recognized.
Invalid variable style in special function next Only file-style or atomfile-style variables can be used with next().
Invalid variable style with next command Variable styles equal and world cannot be used in a next command.
Invalid volume in set command Volume must be > 0.0.
Invalid wiggle direction for fix wall/gran Self-explanatory.

11.4. Error messages 387

LAMMPS Documentation, Release stable 29Sep2021

Invoked angle equil angle on angle style none Self-explanatory.

Invoked angle single on angle style none Self-explanatory.
Invoked bond equil distance on bond style none Self-explanatory.
Invoked bond single on bond style none Self-explanatory.
Invoked pair single on pair style none A command (e.g. a dump) attempted to invoke the single() function on a pair
style none, which is illegal. You are probably attempting to compute per-atom quantities with an undefined pair
style.
Invoking coulombic in pair style lj/coul requires atom attribute q The atom style defined does not have this attribute.
Invoking coulombic in pair style lj/long/dipole/long requires atom attribute q The atom style defined does not have
these attributes.
KIM Simulator Model has no Model definition There is no model definition (key: model-defn) in the KIM Simulator
Model. Please contact the OpenKIM database maintainers to verify and potentially correct this.
KOKKOS package does not yet support comm_style tiled Self-explanatory.
KOKKOS package requires a kokkos enabled atom_style Self-explanatory.
KSpace accuracy must be > 0 The kspace accuracy designated in the input must be greater than zero.
KSpace accuracy too large to estimate G vector Reduce the accuracy request or specify gewald explicitly via the
kspace_modify command.
KSpace accuracy too low Requested accuracy must be less than 1.0.
KSpace solver requires a pair style No pair style is defined.
KSpace style does not yet support triclinic geometries The specified kspace style does not allow for non-orthogonal
simulation boxes.
KSpace style has not yet been set Cannot use kspace_modify command until a kspace style is set.
KSpace style is incompatible with Pair style Setting a kspace style requires that a pair style with matching long-range
Coulombic or dispersion components be used.
Keyword %s in MEAM parameter file not recognized Self-explanatory.
Kokkos has been compiled for CUDA but no GPUs are requested One or more GPUs must be used when Kokkos is
compiled for CUDA.
Kspace_modify mesh parameter must be all zero or all positive Valid kspace mesh parameters are >0. The code will
try to auto-detect suitable values when all three mesh sizes are set to zero (the default).
Kspace_modify mesh/disp parameter must be all zero or all positive Valid kspace mesh/disp parameters are >0. The
code will try to auto-detect suitable values when all three mesh sizes are set to zero and the required accuracy
via force/disp/real as well as force/disp/kspace is set.
Kspace style does not support compute group/group Self-explanatory.
Kspace style pppm/disp/tip4p requires newton on Self-explanatory.
Kspace style pppm/tip4p requires newton on Self-explanatory.
Kspace style requires atom attribute q The atom style defined does not have these attributes.
Kspace_modify eigtol must be smaller than one Self-explanatory.
LAMMPS is not built with Python embedded This is done by including the PYTHON package before LAMMPS is
built. This is required to use python-style variables.
LAMMPS unit_style lj not supported by KIM models Self-explanatory. Check the input script or data file.

388 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

LJ6 off not supported in pair_style buck/long/coul/long Self-explanatory.

Label wasn’t found in input script Self-explanatory.
Lattice orient vectors are not orthogonal The three specified lattice orientation vectors must be mutually orthogonal.
Lattice orient vectors are not right-handed The three specified lattice orientation vectors must create a right-handed
coordinate system such that a1 cross a2 = a3.
Lattice primitive vectors are collinear The specified lattice primitive vectors do not for a unit cell with non-zero vol-
ume.
Lattice settings are not compatible with 2d simulation One or more of the specified lattice vectors has a non-zero z
component.
Lattice spacings are invalid Each x,y,z spacing must be > 0.
Lattice style incompatible with simulation dimension 2d simulation can use sq, sq2, or hex lattice. 3d simulation can
use sc, bcc, or fcc lattice.
Log of zero/negative value in variable formula Self-explanatory.
Lost atoms via balance: original %ld current %ld This should not occur. Report the problem to the developers.
Lost atoms: original %ld current %ld Lost atoms are checked for each time thermo output is done. See the
thermo_modify lost command for options. Lost atoms usually indicate bad dynamics, e.g. atoms have been
blown far out of the simulation box, or moved further than one processor’s sub-domain away before reneighbor-
ing.
MEAM library error %d A call to the MEAM Fortran library returned an error.
MPI_LMP_BIGINT and bigint in lmptype.h are not compatible The size of the MPI datatype does not match the
size of a bigint.
MPI_LMP_TAGINT and tagint in lmptype.h are not compatible The size of the MPI datatype does not match the
size of a tagint.
MSM can only currently be used with comm_style brick This is a current restriction in LAMMPS.
MSM grid is too large The global MSM grid is larger than OFFSET in one or more dimensions. OFFSET is currently
set to 16384. You likely need to decrease the requested accuracy.
MSM order must be 4, 6, 8, or 10 This is a limitation of the MSM implementation in LAMMPS: the MSM order can
only be 4, 6, 8, or 10.
Mass command before simulation box is defined The mass command cannot be used before a read_data, read_restart,
or create_box command.
Matrix factorization to split dispersion coefficients failed This should not normally happen. Contact the developers.
Min_style command before simulation box is defined The min_style command cannot be used before a read_data,
read_restart, or create_box command.
Minimization could not find thermo_pe compute This compute is created by the thermo command. It must have been
explicitly deleted by a uncompute command.
Minimize command before simulation box is defined The minimize command cannot be used before a read_data,
read_restart, or create_box command.
Mismatched brackets in variable Self-explanatory.
Mismatched compute in variable formula A compute is referenced incorrectly or a compute that produces per-atom
values is used in an equal-style variable formula.
Mismatched fix in variable formula A fix is referenced incorrectly or a fix that produces per-atom values is used in
an equal-style variable formula.

11.4. Error messages 389

LAMMPS Documentation, Release stable 29Sep2021

Mismatched parameter in MEAM library file: z!=lat The coordination number and lattice do not match, check that
consistent values are given.
Mismatched variable in variable formula A variable is referenced incorrectly or an atom-style variable that produces
per-atom values is used in an equal-style variable formula.
Modulo 0 in variable formula Self-explanatory.
Molecule IDs too large for compute chunk/atom The IDs must not be larger than can be stored in a 32-bit integer
since chunk IDs are 32-bit integers.
Molecule auto special bond generation overflow Counts exceed maxspecial setting for other atoms in system.
Molecule file has angles but no nangles setting Self-explanatory.
Molecule file has body params but no setting for them Self-explanatory.
Molecule file has bonds but no nbonds setting Self-explanatory.
Molecule file has dihedrals but no ndihedrals setting Self-explanatory.
Molecule file has fragments but no nfragments setting Self-explanatory.
Molecule file has impropers but no nimpropers setting Self-explanatory.
Molecule file has no Body Doubles section Self-explanatory.
Molecule file has no Body Integers section Self-explanatory.
Molecule file has no Fragments section Self-explanatory.
Molecule file has special flags but no bonds Self-explanatory.
Molecule file needs both Special Bond sections Self-explanatory.
Molecule file requires atom style body Self-explanatory.
Molecule file shake flags not before shake atoms The order of the two sections is important.
Molecule file shake flags not before shake bonds The order of the two sections is important.
Molecule file shake info is incomplete All 3 SHAKE sections are needed.
Molecule file special list does not match special count The number of values in an atom’s special list does not match
count.
Molecule file z center-of-mass must be 0.0 for 2d Self-explanatory.
Molecule file z coord must be 0.0 for 2d Self-explanatory.
Molecule natoms must be 1 for body particle Self-explanatory.
Molecule sizescale must be 1.0 for body particle Self-explanatory.
Molecule template ID for atom_style template does not exist Self-explanatory.
Molecule template ID for create_atoms does not exist Self-explanatory.
Molecule template ID for fix deposit does not exist Self-explanatory.
Molecule template ID for fix gcmc does not exist Self-explanatory.
Molecule template ID for fix pour does not exist Self-explanatory.
Molecule template ID for fix rigid/small does not exist Self-explanatory.
Molecule template ID for fix shake does not exist Self-explanatory.
Molecule template ID must be alphanumeric or underscore characters Self-explanatory.

390 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Molecule topology/atom exceeds system topology/atom The number of bonds, angles, etc per-atom in the molecule
exceeds the system setting. See the create_box command for how to specify these values.
Molecule topology type exceeds system topology type The number of bond, angle, etc types in the molecule exceeds
the system setting. See the create_box command for how to specify these values.
More than one fix deform Only one fix deform can be defined at a time.
More than one fix freeze Only one of these fixes can be defined, since the granular pair potentials access it.
More than one fix shake Only one fix shake can be defined.
Mu not allowed when not using semi-grand in fix atom/swap command Self-explanatory.
Must define angle_style before Angle Coeffs Must use an angle_style command before reading a data file that defines
Angle Coeffs.
Must define angle_style before BondAngle Coeffs Must use an angle_style command before reading a data file that
defines Angle Coeffs.
Must define angle_style before BondBond Coeffs Must use an angle_style command before reading a data file that
defines Angle Coeffs.
Must define bond_style before Bond Coeffs Must use a bond_style command before reading a data file that defines
Bond Coeffs.
Must define dihedral_style before AngleAngleTorsion Coeffs Must use a dihedral_style command before reading a
data file that defines AngleAngleTorsion Coeffs.
Must define dihedral_style before AngleTorsion Coeffs Must use a dihedral_style command before reading a data file
that defines AngleTorsion Coeffs.
Must define dihedral_style before BondBond13 Coeffs Must use a dihedral_style command before reading a data file
that defines BondBond13 Coeffs.
Must define dihedral_style before Dihedral Coeffs Must use a dihedral_style command before reading a data file that
defines Dihedral Coeffs.
Must define dihedral_style before EndBondTorsion Coeffs Must use a dihedral_style command before reading a data
file that defines EndBondTorsion Coeffs.
Must define dihedral_style before MiddleBondTorsion Coeffs Must use a dihedral_style command before reading a
data file that defines MiddleBondTorsion Coeffs.
Must define improper_style before AngleAngle Coeffs Must use an improper_style command before reading a data
file that defines AngleAngle Coeffs.
Must define improper_style before Improper Coeffs Must use an improper_style command before reading a data file
that defines Improper Coeffs.
Must define pair_style before Pair Coeffs Must use a pair_style command before reading a data file that defines Pair
Coeffs.
Must define pair_style before PairIJ Coeffs Must use a pair_style command before reading a data file that defines
PairIJ Coeffs.
Must have more than one processor partition to temper Cannot use the temper command with only one processor
partition. Use the -partition command-line option.
Must not have multiple fixes change box parameter . . . Self-explanatory.
Must read Atoms before Angles The Atoms section of a data file must come before an Angles section.
Must read Atoms before Bodies The Atoms section of a data file must come before a Bodies section.
Must read Atoms before Bonds The Atoms section of a data file must come before a Bonds section.

11.4. Error messages 391

LAMMPS Documentation, Release stable 29Sep2021

Must read Atoms before Dihedrals The Atoms section of a data file must come before a Dihedrals section.
Must read Atoms before Ellipsoids The Atoms section of a data file must come before a Ellipsoids section.
Must read Atoms before Impropers The Atoms section of a data file must come before an Impropers section.
Must read Atoms before Lines The Atoms section of a data file must come before a Lines section.
Must read Atoms before Triangles The Atoms section of a data file must come before a Triangles section.
Must read Atoms before Velocities The Atoms section of a data file must come before a Velocities section.
Must re-specify non-restarted pair style (xxx) after read_restart For pair styles, that do not store their settings in a
restart file, it must be defined with a new ‘pair_style’ command after read_restart.
Must set both respa inner and outer Cannot use just the inner or outer option with respa without using the other.
Must set number of threads via package omp command Because you are using the OPENMP package, set the num-
ber of threads via its settings, not by the pair_style snap nthreads setting.
Must shrink-wrap piston boundary The boundary style of the face where the piston is applied must be of type s
(shrink-wrapped).
Must specify a region in fix deposit The region keyword must be specified with this fix.
Must specify a region in fix pour Self-explanatory.
Must specify at least 2 types in fix atom/swap command Self-explanatory.
Must use ‘kim_style init’ command before simulation box is defined Self-explanatory.
Must use ‘kim_style define’ command after simulation box is defined Self-explanatory.
Must use ‘kim_style init’ command before ‘kim_style define’ Self-explanatory.
Must use ‘kspace_modify pressure/scalar no’ for rRESPA with kspace_style MSM The kspace scalar pressure op-
tion cannot (yet) be used with rRESPA.
Must use ‘kspace_modify pressure/scalar no’ for tensor components with kspace_style msm Otherwise MSM will
compute only a scalar pressure. See the kspace_modify command for details on this setting.
Must use ‘kspace_modify pressure/scalar no’ to obtain per-atom virial with kspace_style MSM The kspace scalar
pressure option cannot be used to obtain per-atom virial.
Must use ‘kspace_modify pressure/scalar no’ with GPU MSM Pair styles The kspace scalar pressure option is not
(yet) compatible with GPU MSM Pair styles.
Must use ‘kspace_modify pressure/scalar no’ with kspace_style msm/cg The kspace scalar pressure option is not
compatible with kspace_style msm/cg.
Must use -in switch with multiple partitions A multi-partition simulation cannot read the input script from stdin. The
-in command-line option must be used to specify a file.
Must use Kokkos half/thread or full neighbor list with threads or GPUs Using Kokkos half-neighbor lists with
threading is not allowed.
Must use a block or cylinder region with fix pour Self-explanatory.
Must use a block region with fix pour for 2d simulations Self-explanatory.
Must use a bond style with TIP4P potential TIP4P potentials assume bond lengths in water are constrained by a fix
shake command.
Must use a molecular atom style with fix poems molecule Self-explanatory.
Must use a z-axis cylinder region with fix pour Self-explanatory.

392 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Must use an angle style with TIP4P potential TIP4P potentials assume angles in water are constrained by a fix shake
command.
Must use atom map style array with Kokkos See the atom_modify map command.
Must use atom style with molecule IDs with fix bond/swap Self-explanatory.
Must use pair_style comb or comb3 with fix qeq/comb Self-explanatory.
Must use variable energy with fix addforce Must define an energy variable when applying a dynamic force during
minimization.
Must use variable energy with fix efield You must define an energy when performing a minimization with a variable
E-field.
NEB command before simulation box is defined Self-explanatory.
NEB requires damped dynamics minimizer Use a different minimization style.
NEB requires use of fix neb Self-explanatory.
NL ramp in wall/piston only implemented in zlo for now The ramp keyword can only be used for piston applied to
face zlo.
Need nswaptypes mu values in fix atom/swap command Self-explanatory.
Needed bonus data not in data file Some atom styles require bonus data. See the read_data page for details.
Needed molecular topology not in data file The header of the data file indicated bonds, angles, etc would be included,
but they are not present.
Neigh_modify exclude molecule requires atom attribute molecule Self-explanatory.
Neigh_modify include group != atom_modify first group Self-explanatory.
Neighbor delay must be 0 or multiple of every setting The delay and every parameters set via the neigh_modify com-
mand are inconsistent. If the delay setting is non-zero, then it must be a multiple of the every setting.
Neighbor include group not allowed with ghost neighbors This is a current restriction within LAMMPS.
Neighbor list overflow, boost neigh_modify one There are too many neighbors of a single atom. Use the
neigh_modify command to increase the max number of neighbors allowed for one atom. You may also want
to boost the page size.
Neighbor multi not yet enabled for ghost neighbors This is a current restriction within LAMMPS.
Neighbor multi not yet enabled for granular Self-explanatory.
Neighbor multi not yet enabled for rRESPA Self-explanatory.
Neighbor page size must be >= 10x the one atom setting This is required to prevent wasting too much memory.
New atom IDs exceed maximum allowed ID See the setting for tagint in the src/lmptype.h file.
New bond exceeded bonds per atom in create_bonds See the read_data command for info on using the “ex-
tra/bond/per/atom” keyword to allow for additional bonds to be formed
New bond exceeded bonds per atom in fix bond/create See the read_data command for info on using the “ex-
tra/bond/per/atom” keyword to allow for additional bonds to be formed
New bond exceeded special list size in fix bond/create See the “read_data extra/special/per/atom” command (or the
“create_box extra/special/per/atom” command) for info on how to leave space in the special bonds list to allow
for additional bonds to be formed.
Newton bond change after simulation box is defined The newton command cannot be used to change the newton
bond value after a read_data, read_restart, or create_box command.

11.4. Error messages 393

LAMMPS Documentation, Release stable 29Sep2021

Next command must list all universe and uloop variables This is to insure they stay in sync.
No Kspace style defined for compute group/group Self-explanatory.
No OpenMP support compiled in An OpenMP flag is set, but LAMMPS was not built with OpenMP support.
No angle style is defined for compute angle/local Self-explanatory.
No angles allowed with this atom style Self-explanatory.
No atoms in data file The header of the data file indicated that atoms would be included, but they are not present.
No basis atoms in lattice Basis atoms must be defined for lattice style user.
No bodies allowed with this atom style Self-explanatory. Check data file.
No bond style is defined for compute bond/local Self-explanatory.
No bonds allowed with this atom style Self-explanatory.
No box information in dump. You have to use ‘box no’ Self-explanatory.
No count or invalid atom count in molecule file The number of atoms must be specified.
No dihedral style is defined for compute dihedral/local Self-explanatory.
No dihedrals allowed with this atom style Self-explanatory.
No dump custom arguments specified The dump custom command requires that atom quantities be specified to output
to dump file.
No dump local arguments specified Self-explanatory.
No ellipsoids allowed with this atom style Self-explanatory. Check data file.
No fix gravity defined for fix pour Gravity is required to use fix pour.
No improper style is defined for compute improper/local Self-explanatory.
No impropers allowed with this atom style Self-explanatory.
No input values for fix ave/spatial Self-explanatory.
No lines allowed with this atom style Self-explanatory. Check data file.
No matching element in ADP potential file The ADP potential file does not contain elements that match the requested
elements.
No matching element in EAM potential file The EAM potential file does not contain elements that match the re-
quested elements.
No molecule topology allowed with atom style template The data file cannot specify the number of bonds, angles, etc,
because this info if inferred from the molecule templates.
No overlap of box and region for create_atoms Self-explanatory.
No pair coul/streitz for fix qeq/slater These commands must be used together.
No pair hbond/dreiding coefficients set Self-explanatory.
No pair style defined for compute group/group Cannot calculate group interactions without a pair style defined.
No pair style is defined for compute pair/local Self-explanatory.
No pair style is defined for compute property/local Self-explanatory.
No rigid bodies defined The fix specification did not end up defining any rigid bodies.
No triangles allowed with this atom style Self-explanatory. Check data file.

394 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

No values in fix ave/chunk command Self-explanatory.

No values in fix ave/time command Self-explanatory.
Non digit character between brackets in variable Self-explanatory.
Non integer # of swaps in temper command Swap frequency in temper command must evenly divide the total # of
timesteps.
Non-numeric box dimensions - simulation unstable The box size has apparently blown up.
Non-zero atom IDs with atom_modify id = no Self-explanatory.
Non-zero read_data shift z value for 2d simulation Self-explanatory.
Nprocs not a multiple of N for -reorder Self-explanatory.
Number of core atoms != number of shell atoms There must be a one-to-one pairing of core and shell atoms.
Numeric index is out of bounds A command with an argument that specifies an integer or range of integers is using a
value that is less than 1 or greater than the maximum allowed limit.
One or more Atom IDs is negative Atom IDs must be positive integers.
One or more atom IDs is too big The limit on atom IDs is set by the SMALLBIG, BIGBIG, SMALLSMALL setting
in your LAMMPS build. See the Build settings page for more info.
One or more atom IDs is zero Either all atoms IDs must be zero or none of them.
One or more atoms belong to multiple rigid bodies Two or more rigid bodies defined by the fix rigid command cannot
contain the same atom.
One or more rigid bodies are a single particle Self-explanatory.
One or zero atoms in rigid body Any rigid body defined by the fix rigid command must contain 2 or more atoms.
Only 2 types allowed when not using semi-grand in fix atom/swap command Self-explanatory.
Only one cut-off allowed when requesting all long Self-explanatory.
Only one cutoff allowed when requesting all long Self-explanatory.
Only zhi currently implemented for fix append/atoms Self-explanatory.
Out of range atoms - cannot compute MSM One or more atoms are attempting to map their charge to a MSM grid
point that is not owned by a processor. This is likely for one of two reasons, both of them bad. First, it may mean
that an atom near the boundary of a processor’s sub-domain has moved more than 1/2 the neighbor skin distance
without neighbor lists being rebuilt and atoms being migrated to new processors. This also means you may be
missing pairwise interactions that need to be computed. The solution is to change the re-neighboring criteria
via the neigh_modify command. The safest settings are “delay 0 every 1 check yes”. Second, it may mean that
an atom has moved far outside a processor’s sub-domain or even the entire simulation box. This indicates bad
physics, e.g. due to highly overlapping atoms, too large a timestep, etc.
Out of range atoms - cannot compute PPPM One or more atoms are attempting to map their charge to a PPPM grid
point that is not owned by a processor. This is likely for one of two reasons, both of them bad. First, it may mean
that an atom near the boundary of a processor’s sub-domain has moved more than 1/2 the neighbor skin distance
without neighbor lists being rebuilt and atoms being migrated to new processors. This also means you may be
missing pairwise interactions that need to be computed. The solution is to change the re-neighboring criteria
via the neigh_modify command. The safest settings are “delay 0 every 1 check yes”. Second, it may mean that
an atom has moved far outside a processor’s sub-domain or even the entire simulation box. This indicates bad
physics, e.g. due to highly overlapping atoms, too large a timestep, etc.
Out of range atoms - cannot compute PPPMDisp One or more atoms are attempting to map their charge to a PPPM
grid point that is not owned by a processor. This is likely for one of two reasons, both of them bad. First, it may
mean that an atom near the boundary of a processor’s sub-domain has moved more than 1/2 the neighbor skin

11.4. Error messages 395

LAMMPS Documentation, Release stable 29Sep2021

distance without neighbor lists being rebuilt and atoms being migrated to new processors. This also means you
may be missing pairwise interactions that need to be computed. The solution is to change the re-neighboring
criteria via the neigh_modify command. The safest settings are “delay 0 every 1 check yes”. Second, it may mean
that an atom has moved far outside a processor’s sub-domain or even the entire simulation box. This indicates
bad physics, e.g. due to highly overlapping atoms, too large a timestep, etc.
Overflow of allocated fix vector storage This should not normally happen if the fix correctly calculated how long the
vector will grow to. Contact the developers.
Overlapping large/large in pair colloid This potential is infinite when there is an overlap.
Overlapping small/large in pair colloid This potential is infinite when there is an overlap.
POEMS fix must come before NPT/NPH fix NPT/NPH fix must be defined in input script after all poems fixes, else
the fix contribution to the pressure virial is incorrect.
PPPM can only currently be used with comm_style brick This is a current restriction in LAMMPS.
PPPM grid is too large The global PPPM grid is larger than OFFSET in one or more dimensions. OFFSET is currently
set to 4096. You likely need to decrease the requested accuracy.
PPPM grid stencil extends beyond nearest neighbor processor This is not allowed if the kspace_modify overlap set-
ting is no.
PPPM order < minimum allowed order The default minimum order is 2. This can be reset by the kspace_modify
minorder command.
PPPM order cannot be < 2 or > than %d This is a limitation of the PPPM implementation in LAMMPS.
PPPMDisp Coulomb grid is too large The global PPPM grid is larger than OFFSET in one or more dimensions. OFF-
SET is currently set to 4096. You likely need to decrease the requested accuracy.
PPPMDisp Dispersion grid is too large The global PPPM grid is larger than OFFSET in one or more dimensions.
OFFSET is currently set to 4096. You likely need to decrease the requested accuracy.
PPPMDisp can only currently be used with comm_style brick This is a current restriction in LAMMPS.
PPPMDisp coulomb order cannot be greater than %d This is a limitation of the PPPM implementation in
LAMMPS.
PPPMDisp used but no parameters set, for further information please see the pppm/disp documentation An effi-
cient and accurate usage of the pppm/disp requires settings via the kspace_modify command. Please see the
pppm/disp documentation for further instructions.
PRD command before simulation box is defined The prd command cannot be used before a read_data, read_restart,
or create_box command.
PRD nsteps must be multiple of t_event Self-explanatory.
PRD t_corr must be multiple of t_event Self-explanatory.
Package command after simulation box is defined The package command cannot be used after a read_data,
read_restart, or create_box command.
Package gpu command without GPU package installed The GPU package must be installed via “make yes-gpu” be-
fore LAMMPS is built.
Package intel command without INTEL package installed The INTEL package must be installed via “make yes-
intel” before LAMMPS is built.
Package kokkos command without KOKKOS package enabled The KOKKOS package must be installed via “make
yes-kokkos” before LAMMPS is built, and the “-k on” must be used to enable the package.
Package omp command without OPENMP package installed The OPENMP package must be installed via “make
yes-openmp” before LAMMPS is built.

396 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Pair body requires atom style body Self-explanatory.

Pair body requires body style nparticle This pair style is specific to the nparticle body style.
Pair brownian requires atom style sphere Self-explanatory.
Pair brownian requires extended particles One of the particles has radius 0.0.
Pair brownian requires monodisperse particles All particles must be the same finite size.
Pair brownian/poly requires atom style sphere Self-explanatory.
Pair brownian/poly requires extended particles One of the particles has radius 0.0.
Pair brownian/poly requires newton pair off Self-explanatory.
Pair coeff for hybrid has invalid style Style in pair coeff must have been listed in pair_style command.
Pair coul/wolf requires atom attribute q The atom style defined does not have this attribute.
Pair cutoff < Respa interior cutoff One or more pairwise cutoffs are too short to use with the specified rRESPA cut-
offs.
Pair dipole/cut requires atom attributes q, mu, torque The atom style defined does not have these attributes.
Pair dipole/cut/gpu requires atom attributes q, mu, torque The atom style defined does not have this attribute.
Pair dipole/long requires atom attributes q, mu, torque The atom style defined does not have these attributes.
Pair dipole/sf/gpu requires atom attributes q, mu, torque The atom style defined does not one or more of these at-
tributes.
Pair distance < table inner cutoff Two atoms are closer together than the pairwise table allows.
Pair distance > table outer cutoff Two atoms are further apart than the pairwise table allows.
Pair dpd requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Pair gayberne epsilon a,b,c coeffs are not all set Each atom type involved in pair_style gayberne must have these 3
coefficients set at least once.
Pair gayberne requires atom style ellipsoid Self-explanatory.
Pair gayberne requires atoms with same type have same shape Self-explanatory.
Pair gayberne/gpu requires atom style ellipsoid Self-explanatory.
Pair gayberne/gpu requires atoms with same type have same shape Self-explanatory.
Pair granular requires atom attributes radius, rmass The atom style defined does not have these attributes.
Pair granular requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Pair granular with shear history requires newton pair off This is a current restriction of the implementation of pair
granular styles with history.
Pair hybrid single calls do not support per sub-style special bond values Self-explanatory.
Pair hybrid sub-style does not support single call You are attempting to invoke a single() call on a pair style that does
not support it.
Pair hybrid sub-style is not used No pair_coeff command used a sub-style specified in the pair_style command.
Pair inner cutoff < Respa interior cutoff One or more pairwise cutoffs are too short to use with the specified rRESPA
cutoffs.
Pair inner cutoff >= Pair outer cutoff The specified cutoffs for the pair style are inconsistent.
Pair line/lj requires atom style line Self-explanatory.

11.4. Error messages 397

LAMMPS Documentation, Release stable 29Sep2021

Pair lj/long/dipole/long requires atom attributes mu, torque The atom style defined does not have these attributes.
Pair lubricate requires atom style sphere Self-explanatory.
Pair lubricate requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Pair lubricate requires monodisperse particles All particles must be the same finite size.
Pair lubricate/poly requires atom style sphere Self-explanatory.
Pair lubricate/poly requires extended particles One of the particles has radius 0.0.
Pair lubricate/poly requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Pair lubricate/poly requires newton pair off Self-explanatory.
Pair lubricateU requires atom style sphere Self-explanatory.
Pair lubricateU requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Pair lubricateU requires monodisperse particles All particles must be the same finite size.
Pair lubricateU/poly requires ghost atoms store velocity Use the comm_modify vel yes command to enable this.
Pair lubricateU/poly requires newton pair off Self-explanatory.
Pair peri lattice is not identical in x, y, and z The lattice defined by the lattice command must be cubic.
Pair peri requires a lattice be defined Use the lattice command for this purpose.
Pair peri requires an atom map, see atom_modify Even for atomic systems, an atom map is required to find Peridy-
namic bonds. Use the atom_modify command to define one.
Pair resquared epsilon a,b,c coeffs are not all set Self-explanatory.
Pair resquared epsilon and sigma coeffs are not all set Self-explanatory.
Pair resquared requires atom style ellipsoid Self-explanatory.
Pair resquared requires atoms with same type have same shape Self-explanatory.
Pair resquared/gpu requires atom style ellipsoid Self-explanatory.
Pair resquared/gpu requires atoms with same type have same shape Self-explanatory.
Pair style AIREBO requires atom IDs This is a requirement to use the AIREBO potential.
Pair style AIREBO requires newton pair on See the newton command. This is a restriction to use the AIREBO po-
tential.
Pair style BOP requires atom IDs This is a requirement to use the BOP potential.
Pair style BOP requires newton pair on See the newton command. This is a restriction to use the BOP potential.
Pair style COMB requires atom IDs This is a requirement to use the AIREBO potential.
Pair style COMB requires atom attribute q Self-explanatory.
Pair style COMB requires newton pair on See the newton command. This is a restriction to use the COMB potential.
Pair style COMB3 requires atom IDs This is a requirement to use the COMB3 potential.
Pair style COMB3 requires atom attribute q Self-explanatory.
Pair style COMB3 requires newton pair on See the newton command. This is a restriction to use the COMB3 poten-
tial.
Pair style LCBOP requires atom IDs This is a requirement to use the LCBOP potential.
Pair style LCBOP requires newton pair on See the newton command. This is a restriction to use the Tersoff potential.

398 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Pair style MEAM requires newton pair on See the newton command. This is a restriction to use the MEAM potential.
Pair style SNAP requires newton pair on See the newton command. This is a restriction to use the SNAP potential.
Pair style Stillinger-Weber requires atom IDs This is a requirement to use the SW potential.
Pair style Stillinger-Weber requires newton pair on See the newton command. This is a restriction to use the SW
potential.
Pair style Tersoff requires atom IDs This is a requirement to use the Tersoff potential.
Pair style Tersoff requires newton pair on See the newton command. This is a restriction to use the Tersoff potential.
Pair style Vashishta requires atom IDs This is a requirement to use the Vashishta potential.
Pair style Vashishta requires newton pair on See the newton command. This is a restriction to use the Vashishta
potential.
Pair style bop requires comm ghost cutoff at least 3x larger than %g Use the communicate ghost command to set
this. See the pair bop page for more details.
Pair style born/coul/long requires atom attribute q An atom style that defines this attribute must be used.
Pair style born/coul/long/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style born/coul/wolf requires atom attribute q The atom style defined does not have this attribute.
Pair style buck/coul/cut requires atom attribute q The atom style defined does not have this attribute.
Pair style buck/coul/long requires atom attribute q The atom style defined does not have these attributes.
Pair style buck/coul/long/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style buck/long/coul/long requires atom attribute q The atom style defined does not have this attribute.
Pair style coul/cut requires atom attribute q The atom style defined does not have these attributes.
Pair style coul/cut/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style coul/debye/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style coul/dsf requires atom attribute q The atom style defined does not have this attribute.
Pair style coul/dsf/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style coul/long/gpu requires atom attribute q The atom style defined does not have these attributes.
Pair style coul/streitz requires atom attribute q Self-explanatory.
Pair style does not have extra field requested by compute pair/local The pair style does not support the pN value re-
quested by the compute pair/local command.
Pair style does not support bond_style quartic The pair style does not have a single() function, so it can not be invoked
by bond_style quartic.
Pair style does not support compute group/group The pair_style does not have a single() function, so it cannot be
invoked by the compute group/group command.
Pair style does not support compute pair/local The pair style does not have a single() function, so it can not be invoked
by compute pair/local.
Pair style does not support compute property/local The pair style does not have a single() function, so it can not be
invoked by fix bond/swap.
Pair style does not support fix bond/swap The pair style does not have a single() function, so it can not be invoked by
fix bond/swap.

11.4. Error messages 399

LAMMPS Documentation, Release stable 29Sep2021

Pair style does not support pair_write The pair style does not have a single() function, so it can not be invoked by pair
write.
Pair style does not support rRESPA inner/middle/outer You are attempting to use rRESPA options with a pair style
that does not support them.
Pair style granular with history requires atoms have IDs Atoms in the simulation do not have IDs, so history effects
cannot be tracked by the granular pair potential.
Pair style hbond/dreiding requires an atom map, see atom_modify Self-explanatory.
Pair style hbond/dreiding requires atom IDs Self-explanatory.
Pair style hbond/dreiding requires molecular system Self-explanatory.
Pair style hbond/dreiding requires newton pair on See the newton command for details.
Pair style hybrid cannot have hybrid as an argument Self-explanatory.
Pair style hybrid cannot have none as an argument Self-explanatory.
Pair style is incompatible with KSpace style If a pair style with a long-range Coulombic component is selected, then
a kspace style must also be used.
Pair style is incompatible with TIP4P KSpace style The pair style does not have the requires TIP4P settings.
Pair style lj/charmm/coul/charmm requires atom attribute q The atom style defined does not have these attributes.
Pair style lj/charmm/coul/long requires atom attribute q The atom style defined does not have these attributes.
Pair style lj/charmm/coul/long/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/class2/coul/cut requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/class2/coul/long requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/class2/coul/long/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/coul/cut requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/coul/cut/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/coul/debye/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/coul/dsf requires atom attribute q The atom style defined does not have these attributes.
Pair style lj/cut/coul/dsf/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/coul/long requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/coul/long/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/tip4p/cut requires atom IDs This is a requirement to use this potential.
Pair style lj/cut/tip4p/cut requires atom attribute q The atom style defined does not have this attribute.
Pair style lj/cut/tip4p/cut requires newton pair on See the newton command. This is a restriction to use this potential.
Pair style lj/cut/tip4p/long requires atom IDs There are no atom IDs defined in the system and the TIP4P potential
requires them to find O,H atoms with a water molecule.
Pair style lj/cut/tip4p/long requires atom attribute q The atom style defined does not have these attributes.
Pair style lj/cut/tip4p/long requires newton pair on This is because the computation of constraint forces within a wa-
ter molecule adds forces to atoms owned by other processors.
Pair style lj/gromacs/coul/gromacs requires atom attribute q An atom_style with this attribute is needed.
Pair style lj/long/dipole/long does not currently support respa This feature is not yet supported.

400 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Pair style lj/long/tip4p/long requires atom IDs There are no atom IDs defined in the system and the TIP4P potential
requires them to find O,H atoms with a water molecule.
Pair style lj/long/tip4p/long requires atom attribute q The atom style defined does not have these attributes.
Pair style lj/long/tip4p/long requires newton pair on This is because the computation of constraint forces within a
water molecule adds forces to atoms owned by other processors.
Pair style lj/sdk/coul/long/gpu requires atom attribute q The atom style defined does not have this attribute.
Pair style nb3b/harmonic requires atom IDs This is a requirement to use this potential.
Pair style nb3b/harmonic requires newton pair on See the newton command. This is a restriction to use this potential.
Pair style nm/cut/coul/cut requires atom attribute q The atom style defined does not have this attribute.
Pair style nm/cut/coul/long requires atom attribute q The atom style defined does not have this attribute.
Pair style peri requires atom style peri Self-explanatory.
Pair style polymorphic requires atom IDs This is a requirement to use the polymorphic potential.
Pair style polymorphic requires newton pair on See the newton command. This is a restriction to use the polymorphic
potential.
Pair style reax requires atom IDs This is a requirement to use the ReaxFF potential.
Pair style reax requires atom attribute q The atom style defined does not have this attribute.
Pair style reax requires newton pair on This is a requirement to use the ReaxFF potential.
Pair style requires a KSpace style No kspace style is defined.
Pair style requires use of kspace_style ewald/disp Self-explanatory.
Pair style sw/gpu requires atom IDs This is a requirement to use this potential.
Pair style sw/gpu requires newton pair off See the newton command. This is a restriction to use this potential.
Pair style vashishta/gpu requires atom IDs This is a requirement to use this potential.
Pair style vashishta/gpu requires newton pair off See the newton command. This is a restriction to use this potential.
Pair style tersoff/gpu requires atom IDs This is a requirement to use the tersoff/gpu potential.
Pair style tersoff/gpu requires newton pair off See the newton command. This is a restriction to use this pair style.
Pair style tip4p/cut requires atom IDs This is a requirement to use this potential.
Pair style tip4p/cut requires atom attribute q The atom style defined does not have this attribute.
Pair style tip4p/cut requires newton pair on See the newton command. This is a restriction to use this potential.
Pair style tip4p/long requires atom IDs There are no atom IDs defined in the system and the TIP4P potential requires
them to find O,H atoms with a water molecule.
Pair style tip4p/long requires atom attribute q The atom style defined does not have these attributes.
Pair style tip4p/long requires newton pair on This is because the computation of constraint forces within a water
molecule adds forces to atoms owned by other processors.
Pair table cutoffs must all be equal to use with KSpace When using pair style table with a long-range KSpace solver,
the cutoffs for all atom type pairs must all be the same, since the long-range solver starts at that cutoff.
Pair table parameters did not set N List of pair table parameters must include N setting.
Pair tersoff/zbl requires metal or real units This is a current restriction of this pair potential.
Pair tersoff/zbl/kk requires metal or real units This is a current restriction of this pair potential.

11.4. Error messages 401

LAMMPS Documentation, Release stable 29Sep2021

Pair tri/lj requires atom style tri Self-explanatory.

Pair yukawa/colloid requires atom style sphere Self-explanatory.
Pair yukawa/colloid requires atoms with same type have same radius Self-explanatory.
Pair yukawa/colloid/gpu requires atom style sphere Self-explanatory.
PairKIM only works with 3D problems This is a current limitation.
Pair_coeff command before pair_style is defined Self-explanatory.
Pair_coeff command before simulation box is defined The pair_coeff command cannot be used before a read_data,
read_restart, or create_box command.
Pair_modify command before pair_style is defined Self-explanatory.
Pair_modify special setting for pair hybrid incompatible with global special_bonds setting Cannot override a set-
ting of 0.0 or 1.0 or change a setting between 0.0 and 1.0.
Pair_write command before pair_style is defined Self-explanatory.
Particle on or inside fix wall surface Particles must be “exterior” to the wall in order for energy/force to be calculated.
Particle outside surface of region used in fix wall/region Particles must be inside the region for energy/force to be
calculated. A particle outside the region generates an error.
Per-atom compute in equal-style variable formula Equal-style variables cannot use per-atom quantities.
Per-atom energy was not tallied on needed timestep You are using a thermo keyword that requires potentials to have
tallied energy, but they did not on this timestep. See the variable page for ideas on how to make this work.
Per-atom fix in equal-style variable formula Equal-style variables cannot use per-atom quantities.
Per-atom virial was not tallied on needed timestep You are using a thermo keyword that requires potentials to have
tallied the virial, but they did not on this timestep. See the variable page for ideas on how to make this work.
Per-processor system is too big The number of owned atoms plus ghost atoms on a single processor must fit in 32-bit
integer.
Potential energy ID for fix neb does not exist Self-explanatory.
Potential energy ID for fix nvt/nph/npt does not exist A compute for potential energy must be defined.
Potential file has duplicate entry The potential file has more than one entry for the same element.
Potential file is missing an entry The potential file does not have a needed entry.
Power by 0 in variable formula Self-explanatory.
Pressure ID for fix box/relax does not exist The compute ID needed to compute pressure for the fix does not exist.
Pressure ID for fix modify does not exist Self-explanatory.
Pressure ID for fix npt/nph does not exist Self-explanatory.
Pressure ID for fix press/berendsen does not exist The compute ID needed to compute pressure for the fix does not
exist.
Pressure ID for fix rigid npt/nph does not exist Self-explanatory.
Pressure ID for thermo does not exist The compute ID needed to compute pressure for thermodynamics does not
exist.
Pressure control can not be used with fix nvt Self-explanatory.
Pressure control can not be used with fix nvt/asphere Self-explanatory.
Pressure control can not be used with fix nvt/body Self-explanatory.

402 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Pressure control can not be used with fix nvt/sllod Self-explanatory.

Pressure control can not be used with fix nvt/sphere Self-explanatory.
Pressure control must be used with fix nph Self-explanatory.
Pressure control must be used with fix nph/asphere Self-explanatory.
Pressure control must be used with fix nph/body Self-explanatory.
Pressure control must be used with fix nph/small Self-explanatory.
Pressure control must be used with fix nph/sphere Self-explanatory.
Pressure control must be used with fix nphug A pressure control keyword (iso, aniso, tri, x, y, or z) must be provided.
Pressure control must be used with fix npt Self-explanatory.
Pressure control must be used with fix npt/asphere Self-explanatory.
Pressure control must be used with fix npt/body Self-explanatory.
Pressure control must be used with fix npt/sphere Self-explanatory.
Processor count in z must be 1 for 2d simulation Self-explanatory.
Processor partitions do not match number of allocated processors The total number of processors in all partitions
must match the number of processors LAMMPS is running on.
Processors command after simulation box is defined The processors command cannot be used after a read_data,
read_restart, or create_box command.
Processors custom grid file is inconsistent The vales in the custom file are not consistent with the number of proces-
sors you are running on or the Px,Py,Pz settings of the processors command. Or there was not a setting for every
processor.
Processors grid numa and map style are incompatible Using numa for gstyle in the processors command requires
using cart for the map option.
Processors part option and grid style are incompatible Cannot use gstyle numa or custom with the part option.
Processors twogrid requires proc count be a multiple of core count Self-explanatory.
Pstart and Pstop must have the same value Self-explanatory.
Python function evaluation failed The Python function did not run successfully and/or did not return a value (if it is
supposed to return a value). This is probably due to some error condition in the function.
Python function is not callable The provided Python code was run successfully, but it not define a callable function
with the required name.
Python invoke of undefined function Cannot invoke a function that has not been previously defined.
Python variable does not match Python function This matching is defined by the python-style variable and the python
command.
Python variable has no function No python command was used to define the function associated with the python-style
variable.
QEQ with ‘newton pair off’ not supported See the newton command. This is a restriction to use the QEQ fixes.
R0 < 0 for fix spring command Equilibrium spring length is invalid.
RATTLE coordinate constraints are not satisfied up to desired tolerance Self-explanatory.
RATTLE determinant = 0.0 The determinant of the matrix being solved for a single cluster specified by the fix rattle
command is numerically invalid.

11.4. Error messages 403

LAMMPS Documentation, Release stable 29Sep2021

RATTLE failed Certain constraints were not satisfied.

RATTLE velocity constraints are not satisfied up to desired tolerance Self-explanatory.
Read data add offset is too big It cannot be larger than the size of atom IDs, e.g. the maximum 32-bit integer.
Read dump of atom property that is not allocated Self-explanatory.
Read rerun dump file timestep > specified stop Self-explanatory.
Read restart MPI-IO input not allowed with % in filename This is because a % signifies one file per processor and
MPI-IO creates one large file for all processors.
Read_data shrink wrap did not assign all atoms correctly This is typically because the box-size specified in the data
file is large compared to the actual extent of atoms in a shrink-wrapped dimension. When LAMMPS shrink-
wraps the box atoms will be lost if the processor they are re-assigned to is too far away. Choose a box size closer
to the actual extent of the atoms.
Read_dump command before simulation box is defined The read_dump command cannot be used before a
read_data, read_restart, or create_box command.
Read_dump field not found in dump file Self-explanatory.
Read_dump triclinic status does not match simulation Both the dump snapshot and the current LAMMPS simulation
must be using either an orthogonal or triclinic box.
Read_dump xyz fields do not have consistent scaling/wrapping Self-explanatory.
Reading from MPI-IO filename when MPIIO package is not installed Self-explanatory.
Reax_defs.h setting for NATDEF is too small Edit the setting in the ReaxFF library and re-compile the library and
re-build LAMMPS.
Reax_defs.h setting for NNEIGHMAXDEF is too small Edit the setting in the ReaxFF library and re-compile the
library and re-build LAMMPS.
Receiving partition in processors part command is already a receiver Cannot specify a partition to be a receiver
twice.
Region ID for compute chunk/atom does not exist Self-explanatory.
Region ID for compute reduce/region does not exist Self-explanatory.
Region ID for compute temp/region does not exist Self-explanatory.
Region ID for dump custom does not exist Self-explanatory.
Region ID for fix addforce does not exist Self-explanatory.
Region ID for fix atom/swap does not exist Self-explanatory.
Region ID for fix ave/spatial does not exist Self-explanatory.
Region ID for fix aveforce does not exist Self-explanatory.
Region ID for fix deposit does not exist Self-explanatory.
Region ID for fix efield does not exist Self-explanatory.
Region ID for fix evaporate does not exist Self-explanatory.
Region ID for fix gcmc does not exist Self-explanatory.
Region ID for fix heat does not exist Self-explanatory.
Region ID for fix setforce does not exist Self-explanatory.
Region ID for fix wall/region does not exist Self-explanatory.

404 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Region ID for group dynamic does not exist Self-explanatory.

Region ID in variable formula does not exist Self-explanatory.
Region cannot have 0 length rotation vector Self-explanatory.
Region for fix oneway does not exist Self-explanatory.
Region intersect region ID does not exist Self-explanatory.
Region union or intersect cannot be dynamic The sub-regions can be dynamic, but not the combined region.
Region union region ID does not exist One or more of the region IDs specified by the region union command does
not exist.
Replacing a fix, but new style != old style A fix ID can be used a second time, but only if the style matches the previous
fix. In this case it is assumed you with to reset a fix’s parameters. This error may mean you are mistakenly re-
using a fix ID when you do not intend to.
Replicate command before simulation box is defined The replicate command cannot be used before a read_data,
read_restart, or create_box command.
Replicate did not assign all atoms correctly Atoms replicated by the replicate command were not assigned correctly
to processors. This is likely due to some atom coordinates being outside a non-periodic simulation box.
Replicated system atom IDs are too big See the setting for tagint in the src/lmptype.h file.
Replicated system is too big See the setting for bigint in the src/lmptype.h file.
Required border comm not yet implemented with Kokkos There are various limitations in the communication options
supported by Kokkos.
Rerun command before simulation box is defined The rerun command cannot be used before a read_data,
read_restart, or create_box command.
Rerun dump file does not contain requested snapshot Self-explanatory.
Resetting timestep size is not allowed with fix move This is because fix move is moving atoms based on elapsed time.
Respa inner cutoffs are invalid The first cutoff must be <= the second cutoff.
Respa levels must be >= 1 Self-explanatory.
Respa middle cutoffs are invalid The first cutoff must be <= the second cutoff.
Restart file MPI-IO output not allowed with % in filename This is because a % signifies one file per processor and
MPI-IO creates one large file for all processors.
Restart file byte ordering is not recognized The file does not appear to be a LAMMPS restart file since it does not
contain a recognized byte-ordering flag at the beginning.
Restart file byte ordering is swapped The file was written on a machine with different byte-ordering than the machine
you are reading it on. Convert it to a text data file instead, on the machine you wrote it on.
Restart file incompatible with current version This is probably because you are trying to read a file created with a
version of LAMMPS that is too old compared to the current version. Use your older version of LAMMPS and
convert the restart file to a data file.
Restart file is a MPI-IO file The file is inconsistent with the filename you specified for it.
Restart file is a multi-proc file The file is inconsistent with the filename you specified for it.
Restart file is not a MPI-IO file The file is inconsistent with the filename you specified for it.
Restart file is not a multi-proc file The file is inconsistent with the filename you specified for it.
Restart variable returned a bad timestep The variable must return a timestep greater than the current timestep.

11.4. Error messages 405

LAMMPS Documentation, Release stable 29Sep2021

Restrain atoms %d %d %d %d missing on proc %d at step %ld The 4 atoms in a restrain dihedral specified by the fix
restrain command are not all accessible to a processor. This probably means an atom has moved too far.
Restrain atoms %d %d %d missing on proc %d at step %ld The 3 atoms in a restrain angle specified by the fix re-
strain command are not all accessible to a processor. This probably means an atom has moved too far.
Restrain atoms %d %d missing on proc %d at step %ld The 2 atoms in a restrain bond specified by the fix restrain
command are not all accessible to a processor. This probably means an atom has moved too far.
Reuse of compute ID A compute ID cannot be used twice.
Reuse of dump ID A dump ID cannot be used twice.
Reuse of molecule template ID The template IDs must be unique.
Reuse of region ID A region ID cannot be used twice.
Rigid body atoms %d %d missing on proc %d at step %ld This means that an atom cannot find the atom that owns
the rigid body it is part of, or vice versa. The solution is to use the communicate cutoff command to insure
ghost atoms are acquired from far enough away to encompass the max distance printed when the fix rigid/small
command was invoked.
Rigid body has degenerate moment of inertia Fix poems will only work with bodies (collections of atoms) that have
non-zero principal moments of inertia. This means they must be 3 or more non-collinear atoms, even with joint
atoms removed.
Rigid fix must come before NPT/NPH fix NPT/NPH fix must be defined in input script after all rigid fixes, else the
rigid fix contribution to the pressure virial is incorrect.
Rmask function in equal-style variable formula Rmask is per-atom operation.
Run command before simulation box is defined The run command cannot be used before a read_data, read_restart,
or create_box command.
Run command start value is after start of run Self-explanatory.
Run command stop value is before end of run Self-explanatory.
Run_style command before simulation box is defined The run_style command cannot be used before a read_data,
read_restart, or create_box command.
SRD bin size for fix srd differs from user request Fix SRD had to adjust the bin size to fit the simulation box. See the
cubic keyword if you want this message to be an error vs warning.
SRD bins for fix srd are not cubic enough The bin shape is not within tolerance of cubic. See the cubic keyword if
you want this message to be an error vs warning.
SRD particle %d started inside big particle %d on step %ld bounce %d See the inside keyword if you want this mes-
sage to be an error vs warning.
SRD particle %d started inside wall %d on step %ld bounce %d See the inside keyword if you want this message to
be an error vs warning.
Same dimension twice in fix ave/spatial Self-explanatory.
Sending partition in processors part command is already a sender Cannot specify a partition to be a sender twice.
Set command before simulation box is defined The set command cannot be used before a read_data, read_restart, or
create_box command.
Set command floating point vector does not exist Self-explanatory.
Set command integer vector does not exist Self-explanatory.
Set command with no atoms existing No atoms are yet defined so the set command cannot be used.

406 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Set region ID does not exist Region ID specified in set command does not exist.
Shake angles have different bond types All 3-atom angle-constrained SHAKE clusters specified by the fix shake com-
mand that are the same angle type, must also have the same bond types for the 2 bonds in the angle.
Shake atoms %d %d %d %d missing on proc %d at step %ld The 4 atoms in a single shake cluster specified by the
fix shake command are not all accessible to a processor. This probably means an atom has moved too far.
Shake atoms %d %d %d missing on proc %d at step %ld The 3 atoms in a single shake cluster specified by the fix
shake command are not all accessible to a processor. This probably means an atom has moved too far.
Shake atoms %d %d missing on proc %d at step %ld The 2 atoms in a single shake cluster specified by the fix shake
command are not all accessible to a processor. This probably means an atom has moved too far.
Shake cluster of more than 4 atoms A single cluster specified by the fix shake command can have no more than 4
atoms.
Shake clusters are connected A single cluster specified by the fix shake command must have a single central atom
with up to 3 other atoms bonded to it.
Shake determinant = 0.0 The determinant of the matrix being solved for a single cluster specified by the fix shake
command is numerically invalid.
Shake fix must come before NPT/NPH fix NPT fix must be defined in input script after SHAKE fix, else the SHAKE
fix contribution to the pressure virial is incorrect.
Shear history overflow, boost neigh_modify one There are too many neighbors of a single atom. Use the
neigh_modify command to increase the max number of neighbors allowed for one atom. You may also want
to boost the page size.
Small to big integers are not sized correctly This error occurs when the sizes of smallint, imageint, tagint, bigint, as
defined in src/lmptype.h are not what is expected. Contact the developers if this occurs.
Smallint setting in lmptype.h is invalid It has to be the size of an integer.
Smallint setting in lmptype.h is not compatible Smallint stored in restart file is not consistent with LAMMPS version
you are running.
Special list size exceeded in fix bond/create See the “read_data extra/special/per/atom” command (or the “create_box
extra/special/per/atom” command) for info on how to leave space in the special bonds list to allow for additional
bonds to be formed.
Species XXX is not supported by this KIM Simulator Model The kim_style define command was referencing a
species that is not present in the requested KIM Simulator Model.
Specified processors != physical processors The 3d grid of processors defined by the processors command does not
match the number of processors LAMMPS is being run on.
Specified target stress must be uniaxial or hydrostatic Self-explanatory.
Sqrt of negative value in variable formula Self-explanatory.
Subsequent read data induced too many angles per atom See the extra/angle/per/atom keyword for the create_box or
the read_data command to set this limit larger
Subsequent read data induced too many bonds per atom See the extra/bond/per/atom keyword for the create_box or
the read_data command to set this limit larger
Subsequent read data induced too many dihedrals per atom See the extra/dihedral/per/atom keyword for the cre-
ate_box or the read_data command to set this limit larger
Subsequent read data induced too many impropers per atom See the extra/improper/per/atom keyword for the cre-
ate_box or the read_data command to set this limit larger
Substitution for illegal variable Input script line contained a variable that could not be substituted for.

11.4. Error messages 407

LAMMPS Documentation, Release stable 29Sep2021

Support for writing images in JPEG format not included LAMMPS was not built with the -DLAMMPS_JPEG
switch in the Makefile.
Support for writing images in PNG format not included LAMMPS was not built with the -DLAMMPS_PNG switch
in the Makefile.
Support for writing movies not included LAMMPS was not built with the -DLAMMPS_FFMPEG switch in the
Makefile
System in data file is too big See the setting for bigint in the src/lmptype.h file.
System is not charge neutral, net charge = %g The total charge on all atoms on the system is not 0.0. For some
KSpace solvers this is an error.
TAD nsteps must be multiple of t_event Self-explanatory.
TIP4P hydrogen has incorrect atom type The TIP4P pairwise computation found an H atom whose type does not
agree with the specified H type.
TIP4P hydrogen is missing The TIP4P pairwise computation failed to find the correct H atom within a water molecule.
TMD target file did not list all group atoms The target file for the fix tmd command did not list all atoms in the fix
group.
Tad command before simulation box is defined Self-explanatory.
Tagint setting in lmptype.h is invalid Tagint must be as large or larger than smallint.
Tagint setting in lmptype.h is not compatible Format of tagint stored in restart file is not consistent with LAMMPS
version you are running. See the settings in src/lmptype.h
Target pressure for fix rigid/nph cannot be < 0.0 Self-explanatory.
Target pressure for fix rigid/npt/small cannot be < 0.0 Self-explanatory.
Target temperature for fix nvt/npt/nph cannot be 0.0 Self-explanatory.
Target temperature for fix rigid/npt cannot be 0.0 Self-explanatory.
Target temperature for fix rigid/npt/small cannot be 0.0 Self-explanatory.
Target temperature for fix rigid/nvt cannot be 0.0 Self-explanatory.
Target temperature for fix rigid/nvt/small cannot be 0.0 Self-explanatory.
Temper command before simulation box is defined The temper command cannot be used before a read_data,
read_restart, or create_box command.
Temperature ID for fix bond/swap does not exist Self-explanatory.
Temperature ID for fix box/relax does not exist Self-explanatory.
Temperature ID for fix nvt/npt does not exist Self-explanatory.
Temperature ID for fix press/berendsen does not exist Self-explanatory.
Temperature ID for fix rigid nvt/npt/nph does not exist Self-explanatory.
Temperature ID for fix temp/berendsen does not exist Self-explanatory.
Temperature ID for fix temp/csld does not exist Self-explanatory.
Temperature ID for fix temp/csvr does not exist Self-explanatory.
Temperature ID for fix temp/rescale does not exist Self-explanatory.
Temperature compute degrees of freedom < 0 This should not happen if you are calculating the temperature on a valid
set of atoms.

408 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Temperature control can not be used with fix nph Self-explanatory.

Temperature control can not be used with fix nph/asphere Self-explanatory.
Temperature control can not be used with fix nph/body Self-explanatory.
Temperature control can not be used with fix nph/sphere Self-explanatory.
Temperature control must be used with fix nphug The temp keyword must be provided.
Temperature control must be used with fix npt Self-explanatory.
Temperature control must be used with fix npt/asphere Self-explanatory.
Temperature control must be used with fix npt/body Self-explanatory.
Temperature control must be used with fix npt/sphere Self-explanatory.
Temperature control must be used with fix nvt Self-explanatory.
Temperature control must be used with fix nvt/asphere Self-explanatory.
Temperature control must be used with fix nvt/body Self-explanatory.
Temperature control must be used with fix nvt/sllod Self-explanatory.
Temperature control must be used with fix nvt/sphere Self-explanatory.
Temperature control must not be used with fix nph/small Self-explanatory.
Temperature for fix nvt/sllod does not have a bias The specified compute must compute temperature with a bias.
Tempering could not find thermo_pe compute This compute is created by the thermo command. It must have been
explicitly deleted by a uncompute command.
Tempering fix ID is not defined The fix ID specified by the temper command does not exist.
Tempering temperature fix is not valid The fix specified by the temper command is not one that controls temperature
(nvt or langevin).
Test_descriptor_string already allocated This is an internal error. Contact the developers.
The package gpu command is required for gpu styles Self-explanatory.
Thermo and fix not computed at compatible times Fixes generate values on specific timesteps. The thermo output
does not match these timesteps.
Thermo compute array is accessed out-of-range Self-explanatory.
Thermo compute does not compute array Self-explanatory.
Thermo compute does not compute scalar Self-explanatory.
Thermo compute does not compute vector Self-explanatory.
Thermo compute vector is accessed out-of-range Self-explanatory.
Thermo custom variable cannot be indexed Self-explanatory.
Thermo custom variable is not equal-style variable Only equal-style variables can be output with thermodynamics,
not atom-style variables.
Thermo every variable returned a bad timestep The variable must return a timestep greater than the current timestep.
Thermo fix array is accessed out-of-range Self-explanatory.
Thermo fix does not compute array Self-explanatory.
Thermo fix does not compute scalar Self-explanatory.

11.4. Error messages 409

LAMMPS Documentation, Release stable 29Sep2021

Thermo fix does not compute vector Self-explanatory.

Thermo fix vector is accessed out-of-range Self-explanatory.
Thermo keyword in variable requires thermo to use/init pe You are using a thermo keyword in a variable that requires
potential energy to be calculated, but your thermo output does not use it. Add it to your thermo output.
Thermo keyword in variable requires thermo to use/init press You are using a thermo keyword in a variable that re-
quires pressure to be calculated, but your thermo output does not use it. Add it to your thermo output.
Thermo keyword in variable requires thermo to use/init temp You are using a thermo keyword in a variable that re-
quires temperature to be calculated, but your thermo output does not use it. Add it to your thermo output.
Thermo style does not use press Cannot use thermo_modify to set this parameter since the thermo_style is not com-
puting this quantity.
Thermo style does not use temp Cannot use thermo_modify to set this parameter since the thermo_style is not com-
puting this quantity.
Thermo_modify every variable returned a bad timestep The returned timestep is less than or equal to the current
timestep.
Thermo_modify int format does not contain d character Self-explanatory.
Thermo_modify pressure ID does not compute pressure The specified compute ID does not compute pressure.
Thermo_modify temperature ID does not compute temperature The specified compute ID does not compute temper-
ature.
Thermo_style command before simulation box is defined The thermo_style command cannot be used before a
read_data, read_restart, or create_box command.
This variable thermo keyword cannot be used between runs Keywords that refer to time (such as cpu, elapsed) do not
make sense in between runs.
Threshold for an atom property that is not allocated A dump threshold has been requested on a quantity that is not
defined by the atom style used in this simulation.
Timestep must be >= 0 Specified timestep is invalid.
Too big a problem to use velocity create loop all The system size must fit in a 32-bit integer to use this option.
Too big a timestep for dump dcd The timestep must fit in a 32-bit integer to use this dump style.
Too big a timestep for dump xtc The timestep must fit in a 32-bit integer to use this dump style.
Too few bits for lookup table Table size specified via pair_modify command does not work with your machine’s float-
ing point representation.
Too few lines in %s section of data file Self-explanatory.
Too few values in body lines in data file Self-explanatory.
Too few values in body section of molecule file Self-explanatory.
Too many -pk arguments in command line The string formed by concatenating the arguments is too long. Use a
package command in the input script instead.
Too many MSM grid levels The max number of MSM grid levels is hardwired to 10.
Too many args in variable function More args are used than any variable function allows.
Too many atom pairs for pair bop The number of atomic pairs exceeds the expected number. Check your atomic struc-
ture to ensure that it is realistic.
Too many atom sorting bins This is likely due to an immense simulation box that has blown up to a large size.

410 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Too many atom triplets for pair bop The number of three atom groups for angle determinations exceeds the expected
number. Check your atomic structure to ensure that it is realistic.
Too many atoms for dump dcd The system size must fit in a 32-bit integer to use this dump style.
Too many atoms for dump xtc The system size must fit in a 32-bit integer to use this dump style.
Too many atoms to dump sort Cannot sort when running with more than 2^31 atoms.
Too many elements extracted from MEAM library. Increase ‘maxelt’ in meam.h and recompile.
Too many exponent bits for lookup table Table size specified via pair_modify command does not work with your ma-
chine’s floating point representation.
Too many groups The maximum number of atom groups (including the “all” group) is given by MAX_GROUP in
group.cpp and is 32.
Too many iterations You must use a number of iterations that fit in a 32-bit integer for minimization.
Too many lines in one body in data file - boost MAXBODY MAXBODY is a setting at the top of the
src/read_data.cpp file. Set it larger and re-compile the code.
Too many local+ghost atoms for neighbor list The number of nlocal + nghost atoms on a processor is limited by the
size of a 32-bit integer with 2 bits removed for masking 1-2, 1-3, 1-4 neighbors.
Too many mantissa bits for lookup table Table size specified via pair_modify command does not work with your ma-
chine’s floating point representation.
Too many masses for fix shake The fix shake command cannot list more masses than there are atom types.
Too many molecules for fix poems The limit is 2^31 = ~2 billion molecules.
Too many molecules for fix rigid The limit is 2^31 = ~2 billion molecules.
Too many neighbor bins This is likely due to an immense simulation box that has blown up to a large size.
Too many timesteps The cumulative timesteps must fit in a 64-bit integer.
Too many timesteps for NEB You must use a number of timesteps that fit in a 32-bit integer for NEB.
Too many total atoms See the setting for bigint in the src/lmptype.h file.
Too many total bits for bitmapped lookup table Table size specified via pair_modify command is too large. Note that
a value of N generates a 2^N size table.
Too many values in body lines in data file Self-explanatory.
Too many values in body section of molecule file Self-explanatory.
Too much buffered per-proc info for dump The size of the buffered string must fit in a 32-bit integer for a dump.
Too much per-proc info for dump Number of local atoms times number of columns must fit in a 32-bit integer for
dump.
Tree structure in joint connections Fix poems cannot (yet) work with coupled bodies whose joints connect the bodies
in a tree structure.
Triclinic box skew is too large The displacement in a skewed direction must be less than half the box length in that
dimension. E.g. the xy tilt must be between -half and +half of the x box length. This constraint can be relaxed
by using the box tilt command.
Tried to convert a double to int, but input_double > INT_MAX Self-explanatory.
Trying to build an occasional neighbor list before initialization completed This is not allowed. Source code caller
needs to be modified.

11.4. Error messages 411

LAMMPS Documentation, Release stable 29Sep2021

Two fix ave commands using same compute chunk/atom command in incompatible ways They are both attempting
to “lock” the chunk/atom command so that the chunk assignments persist for some number of timesteps, but are
doing it in different ways.
Two groups cannot be the same in fix spring couple Self-explanatory.
Unable to initialize accelerator for use There was a problem initializing an accelerator for the gpu package
Unbalanced quotes in input line No matching end double quote was found following a leading double quote.
Unexpected end of -reorder file Self-explanatory.
Unexpected empty line in Angle Coeffs section Read a blank line where there should be coefficient data.
Unexpected empty line in Bond Coeffs section Read a blank line where there should be coefficient data.
Unexpected empty line in Dihedral Coeffs section Read a blank line where there should be coefficient data.
Unexpected empty line in Improper Coeffs section Read a blank line where there should be coefficient data.
Unexpected empty line in Pair Coeffs section Read a blank line where there should be coefficient data.
Unexpected end of custom file Self-explanatory.
Unexpected end of data file LAMMPS hit the end of the data file while attempting to read a section. Something is
wrong with the format of the data file.
Unexpected end of dump file A read operation from the file failed.
Unexpected end of fix rigid file A read operation from the file failed.
Unexpected end of fix rigid/small file A read operation from the file failed.
Unexpected end of molecule file Self-explanatory.
Unexpected end of neb file A read operation from the file failed.
Units command after simulation box is defined The units command cannot be used after a read_data, read_restart, or
create_box command.
Universe/uloop variable count < # of partitions A universe or uloop style variable must specify a number of values
>= to the number of processor partitions.
Unrecognized angle style The choice of angle style is unknown.
Unrecognized atom style The choice of atom style is unknown.
Unrecognized body style The choice of body style is unknown.
Unrecognized bond style The choice of bond style is unknown.
Unknown category for info is_active() Self-explanatory.
Unknown category for info is_available() Self-explanatory.
Unknown category for info is_defined() Self-explanatory.
Unrecognized command: %s The command is not known to LAMMPS. Check the input script.
Unrecognized compute style The choice of compute style is unknown.
Unrecognized dihedral style The choice of dihedral style is unknown.
Unrecognized dump reader style The choice of dump reader style via the format keyword is unknown.
Unrecognized dump style The choice of dump style is unknown.
Unknown error in GPU library Self-explanatory.
Unrecognized fix style The choice of fix style is unknown.

412 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Unknown identifier in data file: %s A section of the data file cannot be read by LAMMPS.
Unrecognized improper style The choice of improper style is unknown.
Unknown keyword in thermo_style custom command One or more specified keywords are not recognized.
Unrecognized kspace style The choice of kspace style is unknown.
Unknown name for info newton category Self-explanatory.
Unknown name for info package category Self-explanatory.
Unknown name for info pair category Self-explanatory.
Unrecognized pair style The choice of pair style is unknown.
Unknown pair_modify hybrid sub-style The choice of sub-style is unknown.
Unrecognized region style The choice of region style is unknown.
Unknown section in molecule file Self-explanatory.
Unknown table style in angle style table Self-explanatory.
Unknown table style in bond style table Self-explanatory.
Unknown table style in pair_style command Style of table is invalid for use with pair_style table command.
Unknown unit_style Self-explanatory. Check the input script or data file.
Unrecognized lattice type in MEAM library file The lattice type in an entry of the MEAM library file is not valid.
Unrecognized lattice type in MEAM parameter file The lattice type in an entry of the MEAM parameter file is not
valid.
Unrecognized pair style in compute pair command Self-explanatory.
Unsupported mixing rule in kspace_style ewald/disp Only geometric mixing is supported.
Unsupported order in kspace_style ewald/disp Only 1/r^6 dispersion or dipole terms are supported.
Unsupported order in kspace_style pppm/disp, pair_style %s Only pair styles with 1/r and 1/r^6 dependence are cur-
rently supported.
Unsupported parameter in MEAM library file Self-explanatory.
Use cutoff keyword to set cutoff in single mode Mode is single so cutoff/multi keyword cannot be used.
Use cutoff/multi keyword to set cutoff in multi mode Mode is multi so cutoff keyword cannot be used.
Using fix nvt/sllod with inconsistent fix deform remap option Fix nvt/sllod requires that deforming atoms have a ve-
locity profile provided by “remap v” as a fix deform option.
Using fix nvt/sllod with no fix deform defined Self-explanatory.
Using fix srd with inconsistent fix deform remap option When shearing the box in an SRD simulation, the remap v
option for fix deform needs to be used.
Using pair lubricate with inconsistent fix deform remap option Must use remap v option with fix deform with this
pair style.
Using pair lubricate/poly with inconsistent fix deform remap option If fix deform is used, the remap v option is re-
quired.
Using suffix gpu without GPU package installed Self-explanatory.
Using suffix intel without INTEL package installed Self-explanatory.
Using suffix kk without KOKKOS package enabled Self-explanatory.

11.4. Error messages 413

LAMMPS Documentation, Release stable 29Sep2021

Using suffix omp without OPENMP package installed Self-explanatory.

Using update dipole flag requires atom attribute mu Self-explanatory.
Using update dipole flag requires atom style sphere Self-explanatory.
Variable ID in variable formula does not exist Self-explanatory.
Variable atom ID is too large Specified ID is larger than the maximum allowed atom ID.
Variable evaluation before simulation box is defined Cannot evaluate a compute or fix or atom-based value in a vari-
able before the simulation has been setup.
Variable evaluation in fix wall gave bad value The returned value for epsilon or sigma < 0.0.
Variable evaluation in region gave bad value Variable returned a radius < 0.0.
Variable for compute ti is invalid style Self-explanatory.
Variable for create_atoms is invalid style The variables must be equal-style variables.
Variable for displace_atoms is invalid style It must be an equal-style or atom-style variable.
Variable for dump every is invalid style Only equal-style variables can be used.
Variable for dump image center is invalid style Must be an equal-style variable.
Variable for dump image phi is invalid style Must be an equal-style variable.
Variable for dump image theta is invalid style Must be an equal-style variable.
Variable for dump image zoom is invalid style Must be an equal-style variable.
Variable for fix adapt is invalid style Only equal-style variables can be used.
Variable for fix addforce is invalid style Self-explanatory.
Variable for fix aveforce is invalid style Only equal-style variables can be used.
Variable for fix deform is invalid style The variable must be an equal-style variable.
Variable for fix efield is invalid style The variable must be an equal- or atom-style variable.
Variable for fix gravity is invalid style Only equal-style variables can be used.
Variable for fix heat is invalid style Only equal-style or atom-style variables can be used.
Variable for fix indent is invalid style Only equal-style variables can be used.
Variable for fix indent is not equal style Only equal-style variables can be used.
Variable for fix langevin is invalid style It must be an equal-style variable.
Variable for fix move is invalid style Only equal-style variables can be used.
Variable for fix setforce is invalid style Only equal-style variables can be used.
Variable for fix temp/berendsen is invalid style Only equal-style variables can be used.
Variable for fix temp/csld is invalid style Only equal-style variables can be used.
Variable for fix temp/csvr is invalid style Only equal-style variables can be used.
Variable for fix temp/rescale is invalid style Only equal-style variables can be used.
Variable for fix wall is invalid style Only equal-style variables can be used.
Variable for fix wall/reflect is invalid style Only equal-style variables can be used.
Variable for fix wall/srd is invalid style Only equal-style variables can be used.

414 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Variable for group dynamic is invalid style The variable must be an atom-style variable.
Variable for group is invalid style Only atom-style variables can be used.
Variable for region cylinder is invalid style Only equal-style variables are allowed.
Variable for region is invalid style Only equal-style variables can be used.
Variable for region is not equal style Self-explanatory.
Variable for region sphere is invalid style Only equal-style variables are allowed.
Variable for restart is invalid style Only equal-style variables can be used.
Variable for set command is invalid style Only atom-style variables can be used.
Variable for thermo every is invalid style Only equal-style variables can be used.
Variable for velocity set is invalid style Only atom-style variables can be used.
Variable for voronoi radius is not atom style Self-explanatory.
Variable formula compute array is accessed out-of-range Self-explanatory.
Variable formula compute vector is accessed out-of-range Self-explanatory.
Variable formula fix array is accessed out-of-range Self-explanatory.
Variable formula fix vector is accessed out-of-range Self-explanatory.
Variable has circular dependency A circular dependency is when variable “a” in used by variable “b” and variable
“b” is also used by variable “a”. Circular dependencies with longer chains of dependence are also not allowed.
Variable name between brackets must be alphanumeric or underscore characters Self-explanatory.
Variable name for compute chunk/atom does not exist Self-explanatory.
Variable name for compute reduce does not exist Self-explanatory.
Variable name for compute ti does not exist Self-explanatory.
Variable name for create_atoms does not exist Self-explanatory.
Variable name for displace_atoms does not exist Self-explanatory.
Variable name for dump every does not exist Self-explanatory.
Variable name for dump image center does not exist Self-explanatory.
Variable name for dump image phi does not exist Self-explanatory.
Variable name for dump image theta does not exist Self-explanatory.
Variable name for dump image zoom does not exist Self-explanatory.
Variable name for fix adapt does not exist Self-explanatory.
Variable name for fix addforce does not exist Self-explanatory.
Variable name for fix ave/atom does not exist Self-explanatory.
Variable name for fix ave/chunk does not exist Self-explanatory.
Variable name for fix ave/correlate does not exist Self-explanatory.
Variable name for fix ave/histo does not exist Self-explanatory.
Variable name for fix ave/spatial does not exist Self-explanatory.
Variable name for fix ave/time does not exist Self-explanatory.

11.4. Error messages 415

LAMMPS Documentation, Release stable 29Sep2021

Variable name for fix aveforce does not exist Self-explanatory.

Variable name for fix deform does not exist Self-explanatory.
Variable name for fix efield does not exist Self-explanatory.
Variable name for fix gravity does not exist Self-explanatory.
Variable name for fix heat does not exist Self-explanatory.
Variable name for fix indent does not exist Self-explanatory.
Variable name for fix langevin does not exist Self-explanatory.
Variable name for fix move does not exist Self-explanatory.
Variable name for fix setforce does not exist Self-explanatory.
Variable name for fix store/state does not exist Self-explanatory.
Variable name for fix temp/berendsen does not exist Self-explanatory.
Variable name for fix temp/csld does not exist Self-explanatory.
Variable name for fix temp/csvr does not exist Self-explanatory.
Variable name for fix temp/rescale does not exist Self-explanatory.
Variable name for fix vector does not exist Self-explanatory.
Variable name for fix wall does not exist Self-explanatory.
Variable name for fix wall/reflect does not exist Self-explanatory.
Variable name for fix wall/srd does not exist Self-explanatory.
Variable name for group does not exist Self-explanatory.
Variable name for group dynamic does not exist Self-explanatory.
Variable name for region cylinder does not exist Self-explanatory.
Variable name for region does not exist Self-explanatory.
Variable name for region sphere does not exist Self-explanatory.
Variable name for restart does not exist Self-explanatory.
Variable name for set command does not exist Self-explanatory.
Variable name for thermo every does not exist Self-explanatory.
Variable name for velocity set does not exist Self-explanatory.
Variable name for voronoi radius does not exist Self-explanatory.
Variable name must be alphanumeric or underscore characters Self-explanatory.
Variable uses atom property that is not allocated Self-explanatory.
Velocity command before simulation box is defined The velocity command cannot be used before a read_data,
read_restart, or create_box command.
Velocity command with no atoms existing A velocity command has been used, but no atoms yet exist.
Velocity ramp in z for a 2d problem Self-explanatory.
Velocity rigid used with non-rigid fix-ID Self-explanatory.
Velocity temperature ID does calculate a velocity bias The specified compute must compute a bias for temperature.

416 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Velocity temperature ID does not compute temperature The compute ID given to the velocity command must com-
pute temperature.
Verlet/split can only currently be used with comm_style brick This is a current restriction in LAMMPS.
Verlet/split does not yet support TIP4P This is a current limitation.
Verlet/split requires 2 partitions See the -partition command-line switch.
Verlet/split requires Rspace partition layout be multiple of Kspace partition layout in each dim This is controlled
by the processors command.
Verlet/split requires Rspace partition size be multiple of Kspace partition size This is so there is an equal number of
Rspace processors for every Kspace processor.
Virial was not tallied on needed timestep You are using a thermo keyword that requires potentials to have tallied the
virial, but they did not on this timestep. See the variable page for ideas on how to make this work.
Voro++ error: narea and neigh have a different size This error is returned by the Voro++ library.
Wall defined twice in fix wall command Self-explanatory.
Wall defined twice in fix wall/reflect command Self-explanatory.
Wall defined twice in fix wall/srd command Self-explanatory.
Water H epsilon must be 0.0 for pair style lj/cut/tip4p/cut This is because LAMMPS does not compute the Lennard-
Jones interactions with these particles for efficiency reasons.
Water H epsilon must be 0.0 for pair style lj/cut/tip4p/long This is because LAMMPS does not compute the Lennard-
Jones interactions with these particles for efficiency reasons.
Water H epsilon must be 0.0 for pair style lj/long/tip4p/long This is because LAMMPS does not compute the
Lennard-Jones interactions with these particles for efficiency reasons.
World variable count does not match # of partitions A world-style variable must specify a number of values equal to
the number of processor partitions.
Write_data command before simulation box is defined Self-explanatory.
Write_restart command before simulation box is defined The write_restart command cannot be used before a
read_data, read_restart, or create_box command.
Writing to MPI-IO filename when MPIIO package is not installed Self-explanatory.
Zero length rotation vector with displace_atoms Self-explanatory.
Zero length rotation vector with fix move Self-explanatory.
Zero-length lattice orient vector Self-explanatory.

11.5 Warning messages

This is an alphabetic list of the WARNING messages LAMMPS prints out and the reason why. If the explanation here
is not sufficient, the documentation for the offending command may help. Warning messages also list the source file
and line number where the warning was generated. For example, a message like this:

WARNING: Bond atom missing in box size check (domain.cpp:187)

means that line #187 in the file src/domain.cpp generated the error. Looking in the source code may help you figure
out what went wrong.
Doc page with ERROR messages

11.5. Warning messages 417

LAMMPS Documentation, Release stable 29Sep2021

Adjusting Coulombic cutoff for MSM, new cutoff = %g The adjust/cutoff command is turned on and the Coulombic
cutoff has been adjusted to match the user-specified accuracy.
Angle atoms missing at step %ld One or more of 3 atoms needed to compute a particular angle are missing on this
processor. Typically this is because the pairwise cutoff is set too short or the angle has blown apart and an atom
is too far away.
Angle style in data file differs from currently defined angle style Self-explanatory.
Angles are defined but no angle style is set The topology contains angles, but there are no angle forces computed
since there was no angle_style command.
Atom style in data file differs from currently defined atom style Self-explanatory.
Bond atom missing in box size check The second atom needed to compute a particular bond is missing on this pro-
cessor. Typically this is because the pairwise cutoff is set too short or the bond has blown apart and an atom is
too far away.
Bond atom missing in image check The second atom in a particular bond is missing on this processor. Typically this
is because the pairwise cutoff is set too short or the bond has blown apart and an atom is too far away.
Bond atoms missing at step %ld The second atom needed to compute a particular bond is missing on this processor.
Typically this is because the pairwise cutoff is set too short or the bond has blown apart and an atom is too far
away.
Bond style in data file differs from currently defined bond style Self-explanatory.
Bonds are defined but no bond style is set The topology contains bonds, but there are no bond forces computed since
there was no bond_style command.
Bond/angle/dihedral extent > half of periodic box length This is a restriction because LAMMPS can be confused
about which image of an atom in the bonded interaction is the correct one to use. “Extent” in this context means
the maximum end-to-end length of the bond/angle/dihedral. LAMMPS computes this by taking the maximum
bond length, multiplying by the number of bonds in the interaction (e.g. 3 for a dihedral) and adding a small
amount of stretch.
Bond/react: Atom affected by reaction too close to template edge This means an atom which changes type or con-
nectivity during the reaction is too close to an ‘edge’ atom defined in the superimpose file. This could cause
incorrect assignment of bonds, angle, etc. Generally, this means you must include more atoms in your templates,
such that there are at least two atoms between each atom involved in the reaction and an edge atom.
Both groups in compute group/group have a net charge; the Kspace boundary correction to energy will be non-zero
Self-explanatory.
Calling write_dump before a full system init. The write_dump command is used before the system has been fully
initialized as part of a ‘run’ or ‘minimize’ command. Not all dump styles and features are fully supported at
this point and thus the command may fail or produce incomplete or incorrect output. Insert a “run 0” command,
if a full system init is required.
Cannot count rigid body degrees-of-freedom before bodies are fully initialized This means the temperature associ-
ated with the rigid bodies may be incorrect on this timestep.
Cannot count rigid body degrees-of-freedom before bodies are initialized This means the temperature associated
with the rigid bodies may be incorrect on this timestep.
Cannot include log terms without 1/r terms; setting flagHI to 1 Self-explanatory.
Cannot include log terms without 1/r terms; setting flagHI to 1. Self-explanatory.
Charges are set, but coulombic solver is not used Self-explanatory.

418 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Charges did not converge at step %ld: %lg Self-explanatory.

Communication cutoff is 0.0. No ghost atoms will be generated. Atoms may get lost The communication cutoff de-
faults to the maximum of what is inferred from pair and bond styles (will be zero, if none are defined) and what
is specified via comm_modify cutoff (defaults to 0.0). If this results to 0.0, no ghost atoms will be generated and
LAMMPS may lose atoms or use incorrect periodic images of atoms in interaction lists. To avoid, either use pair
style zero with a suitable cutoff or use comm_modify cutoff .
Communication cutoff is shorter than a bond length based estimate. This may lead to errors. Since LAMMPS
stores topology data with individual atoms, all atoms comprising a bond, angle, dihedral or improper must be
present on any sub-domain that “owns” the atom with the information, either as a local or a ghost atom. The
communication cutoff is what determines up to what distance from a sub-domain boundary ghost atoms are
created. The communication cutoff is by default the largest non-bonded cutoff plus the neighbor skin distance,
but for short or non-bonded cutoffs and/or long bonds, this may not be sufficient. This warning indicates that
there is an increased risk of a simulation stopping unexpectedly because of Bond/Angle/Dihedral/Improper
atoms missing. It can be silenced by manually setting the communication cutoff via comm_modify cutoff .
However, since the heuristic used to determine the estimate is not always accurate, it is not changed automatically
and the warning may be ignored depending on the specific system being simulated.
Communication cutoff is too small for SNAP micro load balancing, increased to %lf Self-explanatory.
Compute cna/atom cutoff may be too large to find ghost atom neighbors The neighbor cutoff used may not encom-
pass enough ghost atoms to perform this operation correctly.
Computing temperature of portions of rigid bodies The group defined by the temperature compute does not encom-
pass all the atoms in one or more rigid bodies, so the change in degrees-of-freedom for the atoms in those partial
rigid bodies will not be accounted for.
Create_bonds max distance > minimum neighbor cutoff This means atom pairs for some atom types may not be in
the neighbor list and thus no bond can be created between them.
Delete_atoms cutoff > minimum neighbor cutoff This means atom pairs for some atom types may not be in the neigh-
bor list and thus an atom in that pair cannot be deleted.
Dihedral atoms missing at step %ld One or more of 4 atoms needed to compute a particular dihedral are missing on
this processor. Typically this is because the pairwise cutoff is set too short or the dihedral has blown apart and
an atom is too far away.
Dihedral problem Conformation of the 4 listed dihedral atoms is extreme; you may want to check your simulation
geometry.
Dihedral problem: %d %ld %d %d %d %d Conformation of the 4 listed dihedral atoms is extreme; you may want to
check your simulation geometry.
Dihedral style in data file differs from currently defined dihedral style Self-explanatory.
Dihedrals are defined but no dihedral style is set The topology contains dihedrals, but there are no dihedral forces
computed since there was no dihedral_style command.
Dump dcd/xtc timestamp may be wrong with fix dt/reset If the fix changes the timestep, the dump dcd file will not
reflect the change.
Energy due to X extra global DOFs will be included in minimizer energies When using fixes like box/relax, the po-
tential energy used by the minimizer is augmented by an additional energy provided by the fix. Thus the printed
converged energy may be different from the total potential energy.
Estimated error in splitting of dispersion coeffs is %g Error is greater than 0.0001 percent.
Ewald/disp Newton solver failed, using old method to estimate g_ewald Self-explanatory. Choosing a different cut-
off value may help.

11.5. Warning messages 419

LAMMPS Documentation, Release stable 29Sep2021

FENE bond too long A FENE bond has stretched dangerously far. It’s interaction strength will be truncated to attempt
to prevent the bond from blowing up.
FENE bond too long: %ld %d %d %g A FENE bond has stretched dangerously far. It’s interaction strength will be
truncated to attempt to prevent the bond from blowing up.
FENE bond too long: %ld %g A FENE bond has stretched dangerously far. It’s interaction strength will be truncated
to attempt to prevent the bond from blowing up.
Fix halt condition for fix-id %s met on step %ld with value %g Self explanatory.
Fix SRD walls overlap but fix srd overlap not set You likely want to set this in your input script.
• Fix bond/create is used multiple times or with fix bond/break - may not work as expected* When using
fix bond/create multiple times or in combination with fix bond/break, the individual fix instances do not
share information about changes they made at the same time step and thus it may result in unexpected
behavior.
Fix bond/swap will ignore defined angles See the page for fix bond/swap for more info on this restriction.
Fix deposit near setting < possible overlap separation %g This test is performed for finite size particles with a diam-
eter, not for point particles. The near setting is smaller than the particle diameter which can lead to overlaps.
Fix evaporate may delete atom with non-zero molecule ID This is probably an error, since you should not delete only
one atom of a molecule.
Fix gcmc using full_energy option Fix gcmc has automatically turned on the full_energy option since it is required
for systems like the one specified by the user. User input included one or more of the following: kspace, triclinic,
a hybrid pair style, an eam pair style, or no “single” function for the pair style.
Fix langevin gjf using random gaussians is not implemented with kokkos This will most likely cause errors in kinetic
fluctuations.
Fix property/atom mol or charge w/out ghost communication A model typically needs these properties defined for
ghost atoms.
Fix qeq CG convergence failed (%g) after %d iterations at %ld step Self-explanatory.
Fix qeq has non-zero lower Taper radius cutoff Absolute value must be <= 0.01.
Fix qeq has very low Taper radius cutoff Value should typically be >= 5.0.
Fix qeq/dynamic tolerance may be too small for damped dynamics Self-explanatory.
Fix qeq/fire tolerance may be too small for damped fires Self-explanatory.
Fix rattle should come after all other integration fixes This fix is designed to work after all other integration fixes
change atom positions. Thus it should be the last integration fix specified. If not, it will not satisfy the desired
constraints as well as it otherwise would.
Fix recenter should come after all other integration fixes Other fixes may change the position of the center-of-mass,
so fix recenter should come last.
Fix srd SRD moves may trigger frequent reneighboring This is because the SRD particles may move long distances.
Fix srd grid size > 1/4 of big particle diameter This may cause accuracy problems.
Fix srd particle moved outside valid domain This may indicate a problem with your simulation parameters.
Fix srd particles may move > big particle diameter This may cause accuracy problems.
Fix srd viscosity < 0.0 due to low SRD density This may cause accuracy problems.
Fixes cannot send data in Kokkos communication, switching to classic communication This is current restriction
with Kokkos.

420 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

For better accuracy use ‘pair_modify table 0’ The user-specified force accuracy cannot be achieved unless the table
feature is disabled by using ‘pair_modify table 0’.
Geometric mixing assumed for 1/r^6 coefficients Self-explanatory.
Group for fix_modify temp != fix group The fix_modify command is specifying a temperature computation that com-
putes a temperature on a different group of atoms than the fix itself operates on. This is probably not what you
want to do.
H matrix size has been exceeded: m_fill=%d H.m=%dn This is the size of the matrix.
Ignoring unknown or incorrect info command flag Self-explanatory. An unknown argument was given to the info
command. Compare your input with the documentation.
Improper atoms missing at step %ld One or more of 4 atoms needed to compute a particular improper are missing on
this processor. Typically this is because the pairwise cutoff is set too short or the improper has blown apart and
an atom is too far away.
Improper problem: %d %ld %d %d %d %d Conformation of the 4 listed improper atoms is extreme; you may want
to check your simulation geometry.
Improper style in data file differs from currently defined improper style Self-explanatory.
Impropers are defined but no improper style is set The topology contains impropers, but there are no improper forces
computed since there was no improper_style command.
Inconsistent image flags The image flags for a pair on bonded atoms appear to be inconsistent. Inconsistent means
that when the coordinates of the two atoms are unwrapped using the image flags, the two atoms are far apart.
Specifically they are further apart than half a periodic box length. Or they are more than a box length apart in
a non-periodic dimension. This is usually due to the initial data file not having correct image flags for the 2
atoms in a bond that straddles a periodic boundary. They should be different by 1 in that case. This is a warning
because inconsistent image flags will not cause problems for dynamics or most LAMMPS simulations. However
they can cause problems when such atoms are used with the fix rigid or replicate commands. Note that if you
have an infinite periodic crystal with bonds then it is impossible to have fully consistent image flags, since some
bonds will cross periodic boundaries and connect two atoms with the same image flag.
Increasing communication cutoff for GPU style The pair style has increased the communication cutoff to be consis-
tent with the communication cutoff requirements for this pair style when run on the GPU.
KIM Model does not provide ‘energy’; Potential energy will be zero Self-explanatory.
KIM Model does not provide ‘forces’; Forces will be zero Self-explanatory.
KIM Model does not provide ‘particleEnergy’; energy per atom will be zero Self-explanatory.
KIM Model does not provide ‘particleVirial’; virial per atom will be zero Self-explanatory.
Kspace_modify slab param < 2.0 may cause unphysical behavior The kspace_modify slab parameter should be
larger to insure periodic grids padded with empty space do not overlap.
Less insertions than requested The fix pour command was unsuccessful at finding open space for as many particles
as it tried to insert.
Library error in lammps_gather_atoms This library function cannot be used if atom IDs are not defined or are not
consecutively numbered.
Library error in lammps_scatter_atoms This library function cannot be used if atom IDs are not defined or are not
consecutively numbered, or if no atom map is defined. See the atom_modify command for details about atom
maps.
Likewise 1-2 special neighbor interactions != 1.0 The topology contains bonds, but there is no bond style defined
and a 1-2 special neighbor scaling factor was not 1.0. This means that pair style interactions may have scaled

11.5. Warning messages 421

LAMMPS Documentation, Release stable 29Sep2021

or missing pairs in the neighbor list in expectation of interactions for those pairs being computed from the bond
style.
Likewise 1-3 special neighbor interactions != 1.0 The topology contains angles, but there is no angle style defined
and a 1-3 special neighbor scaling factor was not 1.0. This means that pair style interactions may have scaled
or missing pairs in the neighbor list in expectation of interactions for those pairs being computed from the angle
style.
Likewise 1-4 special neighbor interactions != 1.0 The topology contains dihedrals, but there is no dihedral style de-
fined and a 1-4 special neighbor scaling factor was not 1.0. This means that pair style interactions may have
scaled or missing pairs in the neighbor list in expectation of interactions for those pairs being computed from the
dihedral style.
Lost atoms via change_box: original %ld current %ld The command options you have used caused atoms to be lost.
Lost atoms via displace_atoms: original %ld current %ld The command options you have used caused atoms to be
lost.
Lost atoms: original %ld current %ld Lost atoms are checked for each time thermo output is done. See the
thermo_modify lost command for options. Lost atoms usually indicate bad dynamics, e.g. atoms have been
blown far out of the simulation box, or moved further than one processor’s sub-domain away before reneighbor-
ing.
MSM mesh too small, increasing to 2 points in each direction Self-explanatory.
Mismatch between velocity and compute groups The temperature computation used by the velocity command will
not be on the same group of atoms that velocities are being set for.
Mixing forced for lj coefficients Self-explanatory.
Molecule attributes do not match system attributes An attribute is specified (e.g. diameter, charge) that is not defined
for the specified atom style.
Molecule has bond topology but no special bond settings This means the bonded atoms will not be excluded in pair-
wise interactions.
Molecule template for create_atoms has multiple molecules The create_atoms command will only create molecules
of a single type, i.e. the first molecule in the template.
Molecule template for fix gcmc has multiple molecules The fix gcmc command will only create molecules of a single
type, i.e. the first molecule in the template.
Molecule template for fix shake has multiple molecules The fix shake command will only recognize molecules of a
single type, i.e. the first molecule in the template.
More than one compute centro/atom It is not efficient to use compute centro/atom more than once.
More than one compute cluster/atom It is not efficient to use compute cluster/atom more than once.
More than one compute cna/atom defined It is not efficient to use compute cna/atom more than once.
More than one compute contact/atom It is not efficient to use compute contact/atom more than once.
More than one compute coord/atom It is not efficient to use compute coord/atom more than once.
More than one compute damage/atom It is not efficient to use compute ke/atom more than once.
More than one compute dilatation/atom Self-explanatory.
More than one compute erotate/sphere/atom It is not efficient to use compute erorate/sphere/atom more than once.
More than one compute hexorder/atom It is not efficient to use compute hexorder/atom more than once.
More than one compute ke/atom It is not efficient to use compute ke/atom more than once.
More than one compute orientorder/atom It is not efficient to use compute orientorder/atom more than once.

422 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

More than one compute plasticity/atom Self-explanatory.

More than one compute sna/atom Self-explanatory.
More than one compute snad/atom Self-explanatory.
More than one compute snav/atom Self-explanatory.
More than one fix poems It is not efficient to use fix poems more than once.
More than one fix rigid It is not efficient to use fix rigid more than once.
Neighbor exclusions used with KSpace solver may give inconsistent Coulombic energies This is because excluding
specific pair interactions also excludes them from long-range interactions which may not be the desired effect.
The special_bonds command handles this consistently by insuring excluded (or weighted) 1-2, 1-3, 1-4 interac-
tions are treated consistently by both the short-range pair style and the long-range solver. This is not done for
exclusions of charged atom pairs via the neigh_modify exclude command.
New thermo_style command, previous thermo_modify settings will be lost If a thermo_style command is used after a
thermo_modify command, the settings changed by the thermo_modify command will be reset to their default val-
ues. This is because the thermo_modify command acts on the currently defined thermo style, and a thermo_style
command creates a new style.
No Kspace calculation with verlet/split The second partition performs a kspace calculation so the kspace_style com-
mand must be used.
No automatic unit conversion to XTC file format conventions possible for units lj This means no scaling will be per-
formed.
No fixes defined, atoms won’t move If you are not using a fix like nve, nvt, npt then atom velocities and coordinates
will not be updated during timestepping.
No joints between rigid bodies, use fix rigid instead The bodies defined by fix poems are not connected by joints.
POEMS will integrate the body motion, but it would be more efficient to use fix rigid.
Not using real units with pair reaxff This is most likely an error, unless you have created your own ReaxFF parameter
file in a different set of units.
Number of MSM mesh points changed to be a multiple of 2 MSM requires that the number of grid points in each
direction be a multiple of two and the number of grid points in one or more directions have been adjusted to meet
this requirement.
OMP_NUM_THREADS environment is not set. This environment variable must be set appropriately to use the
OPENMP package.
One or more atoms are time integrated more than once This is probably an error since you typically do not want to
advance the positions or velocities of an atom more than once per timestep.
One or more chunks do not contain all atoms in molecule This may not be what you intended.
One or more dynamic groups may not be updated at correct point in timestep If there are other fixes that act imme-
diately after the initial stage of time integration within a timestep (i.e. after atoms move), then the command that
sets up the dynamic group should appear after those fixes. This will insure that dynamic group assignments are
made after all atoms have moved.
One or more respa levels compute no forces This is computationally inefficient.
Pair COMB charge %.10f with force %.10f hit max barrier Something is possibly wrong with your model.
Pair COMB charge %.10f with force %.10f hit min barrier Something is possibly wrong with your model.
Pair brownian needs newton pair on for momentum conservation Self-explanatory.
Pair dpd needs newton pair on for momentum conservation Self-explanatory.

11.5. Warning messages 423

LAMMPS Documentation, Release stable 29Sep2021

Pair dsmc: num_of_collisions > number_of_A Collision model in DSMC is breaking down.
Pair dsmc: num_of_collisions > number_of_B Collision model in DSMC is breaking down.
Pair style in data file differs from currently defined pair style Self-explanatory.
Pair style restartinfo set but has no restart support This pair style has a bug, where it does not support reading and
writing information to a restart file, but does not set the member variable “restartinfo” to 0 as required in that
case.
Particle deposition was unsuccessful The fix deposit command was not able to insert as many atoms as needed. The
requested volume fraction may be too high, or other atoms may be in the insertion region.
Proc sub-domain size < neighbor skin, could lead to lost atoms The decomposition of the physical domain (likely
due to load balancing) has led to a processor’s sub-domain being smaller than the neighbor skin in one or more
dimensions. Since reneighboring is triggered by atoms moving the skin distance, this may lead to lost atoms, if
an atom moves all the way across a neighboring processor’s sub-domain before reneighboring is triggered.
Reducing PPPM order b/c stencil extends beyond nearest neighbor processor This may lead to a larger grid than de-
sired. See the kspace_modify overlap command to prevent changing of the PPPM order.
Reducing PPPMDisp Coulomb order b/c stencil extends beyond neighbor processor This may lead to a larger grid
than desired. See the kspace_modify overlap command to prevent changing of the PPPM order.
Reducing PPPMDisp dispersion order b/c stencil extends beyond neighbor processor This may lead to a larger grid
than desired. See the kspace_modify overlap command to prevent changing of the PPPM order.
Replacing a fix, but new group != old group The ID and style of a fix match for a fix you are changing with a fix
command, but the new group you are specifying does not match the old group.
Replicating in a non-periodic dimension The parameters for a replicate command will cause a non-periodic dimen-
sion to be replicated; this may cause unwanted behavior.
Resetting reneighboring criteria during PRD A PRD simulation requires that neigh_modify settings be delay = 0,
every = 1, check = yes. Since these settings were not in place, LAMMPS changed them and will restore them to
their original values after the PRD simulation.
Resetting reneighboring criteria during TAD A TAD simulation requires that neigh_modify settings be delay = 0,
every = 1, check = yes. Since these settings were not in place, LAMMPS changed them and will restore them to
their original values after the PRD simulation.
Resetting reneighboring criteria during minimization Minimization requires that neigh_modify settings be delay =
0, every = 1, check = yes. Since these settings were not in place, LAMMPS changed them and will restore them
to their original values after the minimization.
Restart file used different # of processors The restart file was written out by a LAMMPS simulation running on a
different number of processors. Due to round-off, the trajectories of your restarted simulation may diverge a
little more quickly than if you ran on the same # of processors.
Restart file used different 3d processor grid The restart file was written out by a LAMMPS simulation running on a
different 3d grid of processors. Due to round-off, the trajectories of your restarted simulation may diverge a little
more quickly than if you ran on the same # of processors.
Restart file used different boundary settings, using restart file values Your input script cannot change these restart
file settings.
Restart file used different newton bond setting, using restart file value The restart file value will override the setting
in the input script.
Restart file used different newton pair setting, using input script value The input script value will override the set-
ting in the restart file.

424 Chapter 11. Errors

 LAMMPS Documentation, Release stable 29Sep2021

Restrain problem: %d %ld %d %d %d %d Conformation of the 4 listed dihedral atoms is extreme; you may want to
check your simulation geometry.
Running PRD with only one replica This is allowed, but you will get no parallel speed-up.
SRD bin shifting turned on due to small lamda This is done to try to preserve accuracy.
SRD bin size for fix srd differs from user request Fix SRD had to adjust the bin size to fit the simulation box. See the
cubic keyword if you want this message to be an error vs warning.
SRD bins for fix srd are not cubic enough The bin shape is not within tolerance of cubic. See the cubic keyword if
you want this message to be an error vs warning.
SRD particle %d started inside big particle %d on step %ld bounce %d See the inside keyword if you want this mes-
sage to be an error vs warning.
SRD particle %d started inside wall %d on step %ld bounce %d See the inside keyword if you want this message to
be an error vs warning.
Shake determinant < 0.0 The determinant of the quadratic equation being solved for a single cluster specified by the
fix shake command is numerically suspect. LAMMPS will set it to 0.0 and continue.
Shell command ‘%s’ failed with error ‘%s’ Self-explanatory.
Shell command returned with non-zero status This may indicate the shell command did not operate as expected.
Should not allow rigid bodies to bounce off reflecting walls LAMMPS allows this, but their dynamics are not com-
puted correctly.
Should not use fix nve/limit with fix shake or fix rattle This will lead to invalid constraint forces in the
SHAKE/RATTLE computation.
Simulations might be very slow because of large number of structure factors Self-explanatory.
Slab correction not needed for MSM Slab correction is intended to be used with Ewald or PPPM and is not needed
by MSM.
Specifying an ‘subset’ value of ‘0’ is equivalent to no ‘subset’ keyword Self-explanatory.
System is not charge neutral, net charge = %g The total charge on all atoms on the system is not 0.0. For some
KSpace solvers this is only a warning.
Table inner cutoff >= outer cutoff You specified an inner cutoff for a Coulombic table that is longer than the global
cutoff. Probably not what you wanted.
Temperature for MSST is not for group all User-assigned temperature to MSST fix does not compute temperature
for all atoms. Since MSST computes a global pressure, the kinetic energy contribution from the temperature is
assumed to also be for all atoms. Thus the pressure used by MSST could be inaccurate.
Temperature for NPT is not for group all User-assigned temperature to NPT fix does not compute temperature for all
atoms. Since NPT computes a global pressure, the kinetic energy contribution from the temperature is assumed
to also be for all atoms. Thus the pressure used by NPT could be inaccurate.
Temperature for fix modify is not for group all The temperature compute is being used with a pressure calculation
which does operate on group all, so this may be inconsistent.
Temperature for thermo pressure is not for group all User-assigned temperature to thermo via the thermo_modify
command does not compute temperature for all atoms. Since thermo computes a global pressure, the kinetic
energy contribution from the temperature is assumed to also be for all atoms. Thus the pressure printed by
thermo could be inaccurate.
The fix ave/spatial command has been replaced by the more flexible fix ave/chunk and compute chunk/atom commands – fix ave/spa
Self-explanatory.

11.5. Warning messages 425

LAMMPS Documentation, Release stable 29Sep2021

The minimizer does not re-orient dipoles when using fix efield This means that only the atom coordinates will be
minimized, not the orientation of the dipoles.
Too many common neighbors in CNA %d times More than the maximum # of neighbors was found multiple times.
This was unexpected.
Too many inner timesteps in fix ttm Self-explanatory.
Too many neighbors in CNA for %d atoms More than the maximum # of neighbors was found multiple times. This
was unexpected.
Triclinic box skew is large The displacement in a skewed direction is normally required to be less than half the box
length in that dimension. E.g. the xy tilt must be between -half and +half of the x box length. You have relaxed
the constraint using the box tilt command, but the warning means that a LAMMPS simulation may be inefficient
as a result.
Use special bonds = 0,1,1 with bond style fene Most FENE models need this setting for the special_bonds command.
Use special bonds = 0,1,1 with bond style fene/expand Most FENE models need this setting for the special_bonds
command.
Using a many-body potential with bonds/angles/dihedrals and special_bond exclusions This is likely not what you
want to do. The exclusion settings will eliminate neighbors in the neighbor list, which the many-body potential
needs to calculated its terms correctly.
Using compute temp/deform with inconsistent fix deform remap option Fix nvt/sllod assumes deforming atoms have
a velocity profile provided by “remap v” or “remap none” as a fix deform option.
Using compute temp/deform with no fix deform defined This is probably an error, since it makes little sense to use
compute temp/deform in this case.
Using fix srd with box deformation but no SRD thermostat The deformation will heat the SRD particles so this can
be dangerous.
Using kspace solver on system with no charge Self-explanatory.
Using largest cut-off for lj/long/dipole/long long long Self-explanatory.
Using largest cutoff for buck/long/coul/long Self-explanatory.
Using largest cutoff for lj/long/coul/long Self-explanatory.
Using largest cutoff for pair_style lj/long/tip4p/long Self-explanatory.
Using package gpu without any pair style defined Self-explanatory.
Using pair potential shift with pair_modify compute no The shift effects will thus not be computed.
Using pair tail corrections with nonperiodic system This is probably a bogus thing to do, since tail corrections are
computed by integrating the density of a periodic system out to infinity.
Using pair tail corrections with pair_modify compute no The tail corrections will thus not be computed.

426 Chapter 11. Errors

 Part II

Programmer Guide

427
 CHAPTER

TWELVE

LAMMPS LIBRARY INTERFACES

As described on the library interface to LAMMPS page, LAMMPS can be built as a library (static or shared), so that it
can be called by another code, used in a coupled manner with other codes, or driven through a Python script. Even the
LAMMPS standalone executable is essentially a thin wrapper on top of the LAMMPS library, creating a LAMMPS
instance, processing input and then existing.
Most of the APIs described below are based on C language wrapper functions in the files src/library.h and src/
library.cpp, but it is also possible to use C++ directly. The basic procedure is always the same: you create one or
more instances of LAMMPS, pass commands as strings or from files to that LAMMPS instance to execute calculations,
and/or call functions that read, manipulate, and update data from the active class instances inside LAMMPS to do
analysis or perform operations that are not possible with existing input script commands.

Thread-safety
LAMMPS was initially not conceived as a thread-safe program, but over the years changes have been applied to replace
operations that collide with creating multiple LAMMPS instances from multiple-threads of the same process with
thread-safe alternatives. This primarily applies to the core LAMMPS code and less so on add-on packages, especially
when those packages require additional code in the lib folder, interface LAMMPS to Fortran libraries, or the code uses
static variables (like the COLVARS package).
Another major issue to deal with is to correctly handle MPI. Creating a LAMMPS instance requires passing an MPI
communicator, or it assumes the MPI_COMM_WORLD communicator, which spans all MPI processor ranks. When creat-
ing multiple LAMMPS object instances from different threads, this communicator has to be different for each thread
or else collisions can happen. Or it has to be guaranteed, that only one thread at a time is active. MPI communicators,
however, are not a problem, if LAMMPS is compiled with the MPI STUBS library, which implies that there is no MPI
communication and only 1 MPI rank.

12.1 LAMMPS C Library API

The C library interface is the most commonly used path to manage LAMMPS instances from a compiled code and
it is the basis for the Python and Fortran modules. Almost all functions of the C language API require an argument
containing a “handle” in the form of a void * type variable, which points to the location of a LAMMPS class instance.
The library.h header file by default does not include the mpi.h header file and thus hides the lammps_open()
function which requires the declaration of the MPI_comm data type. This is only a problem when the communicator
that would be passed is different from MPI_COMM_WORLD. Otherwise calling lammps_open_no_mpi() will work just
as well. To make lammps_open() available, you need to compile the code with -DLAMMPS_LIB_MPI or add the line
#define LAMMPS_LIB_MPI before #include "library.h".

429
LAMMPS Documentation, Release stable 29Sep2021

Please note the mpi.h file must usually be the same (and thus the MPI library in use) for the LAMMPS code and library
and the calling code. The exception is when LAMMPS was compiled in serial mode using the STUBS MPI library. In
that case the calling code may be compiled with a different MPI library so long as lammps_open_no_mpi() is called
to create a LAMMPS instance. In that case each MPI rank will run LAMMPS in serial mode.

Errors versus exceptions

If the LAMMPS executable encounters an error condition, it will abort after printing an error message. For a library
interface this is usually not desirable. Thus LAMMPS can be compiled to to throw a C++ exception instead. If enabled,
the library functions will catch those exceptions and return. The error status can be queried and an error message
retrieved. We thus recommend enabling C++ exceptions when using the library interface,

Warning: No checks are made on the arguments of the function calls of the C library interface. All function
arguments must be non-NULL unless explicitly allowed, and must point to consistent and valid data. Buffers for
storing returned data must be allocated to a suitable size. Passing invalid or unsuitable information will likely cause
crashes or corrupt data.

12.1.1 Creating or deleting a LAMMPS object

This section documents the following functions:

• lammps_open()
• lammps_open_no_mpi()
• lammps_open_fortran()
• lammps_close()
• lammps_mpi_init()
• lammps_mpi_finalize()
• lammps_kokkos_finalize()
• lammps_python_finalize()

The lammps_open() and lammps_open_no_mpi() functions are used to create and initialize a LAMMPS() instance.
They return a reference to this instance as a void * pointer to be used as the “handle” argument in subsequent function
calls until that instance is destroyed by calling lammps_close(). Here is a simple example demonstrating its use:

#include "library.h"
#include <stdio.h>

int main(int argc, char **argv)

{
void *handle;
int version;
const char *lmpargv[] = { "liblammps", "-log", "none"};
int lmpargc = sizeof(lmpargv)/sizeof(const char *);

(continues on next page)

430 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

/* create LAMMPS instance */
handle = lammps_open_no_mpi(lmpargc, (char **)lmpargv, NULL);
if (handle == NULL) {
printf("LAMMPS initialization failed");
lammps_mpi_finalize();
return 1;
}

/* get and print numerical version code */

version = lammps_version(handle);
printf("LAMMPS Version: %d\n",version);

/* delete LAMMPS instance and shut down MPI */

lammps_close(handle);
lammps_mpi_finalize();
return 0;
}

The LAMMPS library uses the MPI library it was compiled with and will either run on all processors in the
MPI_COMM_WORLD communicator or on the set of processors in the communicator passed as the comm argument of
lammps_open(). This means the calling code can run LAMMPS on all or a subset of processors. For example, a
wrapper code might decide to alternate between LAMMPS and another code, allowing them both to run on all the
processors. Or it might allocate part of the processors to LAMMPS and the rest to the other code by creating a custom
communicator with MPI_Comm_split() and running both codes concurrently before syncing them up periodically.
Or it might instantiate multiple instances of LAMMPS to perform different calculations and either alternate between
them, run them concurrently on split communicators, or run them one after the other. The lammps_open() function
may be called multiple times for this latter purpose.
The lammps_close() function is used to shut down the LAMMPS class pointed to by the handle passed as an argument
and free all its memory. This has to be called for every instance created with one of the lammps_open() functions. It
will, however, not call MPI_Finalize(), since that may only be called once. See lammps_mpi_finalize() for an
alternative to invoking MPI_Finalize() explicitly from the calling program.

void *lammps_open(int argc, char **argv, MPI_Comm comm, void **ptr)

Create instance of the LAMMPS class and return pointer to it.

The lammps_open() function creates a new LAMMPS class instance while passing in a list of strings as if they
were command-line arguments for the LAMMPS executable, and an MPI communicator for LAMMPS to run
under. Since the list of arguments is exactly as when called from the command line, the first argument would be
the name of the executable and thus is otherwise ignored. However argc may be set to 0 and then argv may be
NULL. If MPI is not yet initialized, MPI_Init() will be called during creation of the LAMMPS class instance.
If for some reason the creation or initialization of the LAMMPS instance fails a null pointer is returned.
Changed in version 18Sep2020: This function now has the pointer to the created LAMMPS class instance as
return value. For backward compatibility it is still possible to provide the address of a pointer variable as final
argument ptr.
Deprecated since version 18Sep2020: The ptr argument will be removed in a future release of LAMMPS. It
should be set to NULL instead.
See also lammps_open_no_mpi(), lammps_open_fortran()

12.1. LAMMPS C Library API 431

LAMMPS Documentation, Release stable 29Sep2021

Note: This function is only declared when the code using the LAMMPS library.h include file is com-
piled with -DLAMMPS_LIB_MPI, or contains a #define LAMMPS_LIB_MPI 1 statement before #include
"library.h". Otherwise you can only use the lammps_open_no_mpi() or lammps_open_fortran() func-
tions.

Parameters
• argc – number of command line arguments
• argv – list of command line argument strings
• comm – MPI communicator for this LAMMPS instance
• ptr – pointer to a void pointer variable which serves as a handle; may be NULL
Returns pointer to new LAMMPS instance cast to void *

void *lammps_open_no_mpi(int argc, char **argv, void **ptr)

Variant of lammps_open() that implicitly uses MPI_COMM_WORLD.

This function is a version of lammps_open(), that is missing the MPI communicator argument. It will use
MPI_COMM_WORLD instead. The type and purpose of arguments and return value are otherwise the same.
Outside of the convenience, this function is useful, when the LAMMPS library was compiled in serial mode, but
the calling code runs in parallel and the MPI_Comm data type of the STUBS library would not be compatible with
that of the calling code.
If for some reason the creation or initialization of the LAMMPS instance fails a null pointer is returned.
Changed in version 18Sep2020: This function now has the pointer to the created LAMMPS class instance as
return value. For backward compatibility it is still possible to provide the address of a pointer variable as final
argument ptr.
Deprecated since version 18Sep2020: The ptr argument will be removed in a future release of LAMMPS. It
should be set to NULL instead.
See also lammps_open(), lammps_open_fortran()

Parameters
• argc – number of command line arguments
• argv – list of command line argument strings
• ptr – pointer to a void pointer variable which serves as a handle; may be NULL
Returns pointer to new LAMMPS instance cast to void *

void *lammps_open_fortran(int argc, char **argv, int f_comm)

Variant of lammps_open() using a Fortran MPI communicator.

This function is a version of lammps_open(), that uses an integer for the MPI communicator as the MPI Fortran
interface does. It is used in the lammps() constructor of the LAMMPS Fortran module. Internally it converts
the f_comm argument into a C-style MPI communicator with MPI_Comm_f2c() and then calls lammps_open().

432 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

If for some reason the creation or initialization of the LAMMPS instance fails a null pointer is returned.
New in version 18Sep2020.
See also lammps_open_fortran(), lammps_open_no_mpi()

Parameters
• argc – number of command line arguments
• argv – list of command line argument strings
• f_comm – Fortran style MPI communicator for this LAMMPS instance
Returns pointer to new LAMMPS instance cast to void *

void lammps_close(void *handle)

Delete a LAMMPS instance created by lammps_open() or its variants.
This function deletes the LAMMPS class instance pointed to by handle that was created by one of the
lammps_open() variants. It does not call MPI_Finalize() to allow creating and deleting multiple LAMMPS
instances concurrently or sequentially. See lammps_mpi_finalize() for a function performing this operation.
Parameters handle – pointer to a previously created LAMMPS instance

void lammps_mpi_init()
Ensure the MPI environment is initialized.

The MPI standard requires that any MPI application must call MPI_Init() exactly once before performing any
other MPI function calls. This function checks, whether MPI is already initialized and calls MPI_Init() in case
it is not.
New in version 18Sep2020.

void lammps_mpi_finalize()
Shut down the MPI infrastructure.

The MPI standard requires that any MPI application calls MPI_Finalize() before exiting. Even if a calling
program does not do any MPI calls, MPI is still initialized internally to avoid errors accessing any MPI functions.
This function should then be called right before exiting the program to wait until all (parallel) tasks are completed
and then MPI is cleanly shut down. After calling this function no more MPI calls may be made.
New in version 18Sep2020.
See also lammps_kokkos_finalize(), lammps_python_finalize()

12.1. LAMMPS C Library API 433

LAMMPS Documentation, Release stable 29Sep2021

void lammps_kokkos_finalize()
Shut down the Kokkos library environment.

The Kokkos library may only be initialized once during the execution of a process. This is done automatically
the first time Kokkos functionality is used. This requires that the Kokkos environment must be explicitly shut
down after any LAMMPS instance using it is closed (to release associated resources). After calling this function
no Kokkos functionality may be used.
New in version 2Jul2021.
See also lammps_mpi_finalize(), lammps_python_finalize()

void lammps_python_finalize()
Clear the embedded Python environment

This function resets and clears an embedded Python environment by calling the Py_Finalize() function of the
embedded Python library, if enabled. This call would free up all allocated resources and release loaded shared
objects.
However, this is not done when a LAMMPS instance is deleted because a) LAMMPS may have been used
through the Python module and thus the Python interpreter is external and not embedded into LAMMPS and
therefore may not be reset by LAMMPS b) some Python modules and extensions, most notably NumPy, are not
compatible with being initialized multiple times, which would happen if additional LAMMPS instances using
Python would be created after after calling Py_Finalize().
This function can be called to explicitly clear the Python environment in case it is safe to do so.
New in version TBD.
See also lammps_mpi_finalize(), lammps_kokkos_finalize()

12.1.2 Executing commands

This section documents the following functions:

• lammps_file()
• lammps_command()
• lammps_commands_list()
• lammps_commands_string()

Once a LAMMPS instance is created, there are multiple ways to “drive” a simulation. In most cases it is easiest to
process single or multiple LAMMPS commands like in an input file. This can be done through reading a file or passing
single commands or lists of commands or blocks of commands with the following functions.
Via these functions, the calling code can have LAMMPS act on a series of input file commands that are either read
from a file or passed as strings. For example, this allows setup of a problem from an input script, and then running it in
stages while performing other operations in between or concurrently. The caller can interleave the LAMMPS function

434 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

calls with operations it performs, such as calls to extract information from or set information within LAMMPS, or calls
to another code’s library.
Just as with input script parsing comments can be included in the file or strings, and expansion of variables with
${name} or $(expression) syntax is performed. Below is a short example using some of these functions.

/* define to make the otherwise hidden prototype for "lammps_open()" visible */

#define LAMMPS_LIB_MPI
#include "library.h"

#include <mpi.h>
#include <stdio.h>

int main(int argc, char **argv)

{
void *handle;
int i;

MPI_Init(&argc, &argv);
handle = lammps_open(0, NULL, MPI_COMM_WORLD, NULL);
lammps_file(handle,"in.sysinit");
lammps_command(handle,"run 1000 post no");

for (i=0; i < 100; ++i) {

lammps_commands_string(handle,"run 100 pre no post no\n"
"print 'PE = $(pe)'\n"
"print 'KE = $(ke)'\n");
}
lammps_close(handle);
MPI_Finalize();
return 0;
}

void lammps_file(void *handle, const char *file)

Process LAMMPS input from a file.

This function processes commands in the file pointed to by filename line by line and thus functions very similar
to the include command. The function returns when the end of the file is reached and the commands have
completed.
The actual work is done by the functions Input::file(const char *) and Input::file().

Parameters
• handle – pointer to a previously created LAMMPS instance
• filename – name of a file with LAMMPS input

char *lammps_command(void *handle, const char *cmd)

Process a single LAMMPS input command from a string.

12.1. LAMMPS C Library API 435

LAMMPS Documentation, Release stable 29Sep2021

This function tells LAMMPS to execute the single command in the string cmd. The entire string is con-
sidered as command and need not have a (final) newline character. Newline characters in the body of the
string, however, will be treated as part of the command and will not start a second command. The function
lammps_commands_string() processes a string with multiple command lines.
The function returns the name of the command on success or NULL when passing a string without a command.

Parameters
• handle – pointer to a previously created LAMMPS instance
• cmd – string with a single LAMMPS command
Returns string with parsed command name or NULL

void lammps_commands_list(void *handle, int ncmd, const char **cmds)

Process multiple LAMMPS input commands from list of strings.
This function processes multiple commands from a list of strings by first concatenating the individual strings
in cmds into a single string, inserting newline characters as needed. The combined string is passed to
lammps_commands_string() for processing.
Parameters
• handle – pointer to a previously created LAMMPS instance
• ncmd – number of lines in cmds
• cmds – list of strings with LAMMPS commands

void lammps_commands_string(void *handle, const char *str)

Process a block of LAMMPS input commands from a single string.
This function processes a multi-line string similar to a block of commands from a file. The string may have
multiple lines (separated by newline characters) and also single commands may be distributed over multiple lines
with continuation characters (‘&’). Those lines are combined by removing the ‘&’ and the following newline
character. After this processing the string is handed to LAMMPS for parsing and executing.

Note: Multi-line commands enabled by triple quotes will NOT work with this function.

Parameters
• handle – pointer to a previously created LAMMPS instance
• str – string with block of LAMMPS input commands

436 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

12.1.3 System properties

This section documents the following functions:

• lammps_get_natoms()
• lammps_get_thermo()
• lammps_extract_box()
• lammps_reset_box()
• lammps_memory_usage()
• lammps_get_mpi_comm()
• lammps_extract_setting()
• lammps_extract_global_datatype()
• lammps_extract_global()

The library interface allows extraction of different kinds of information about the active simulation instance and also
modifications to it. This enables combining of a LAMMPS simulation with other processing and simulation methods
computed by the calling code, or by another code that is coupled to LAMMPS via the library interface. In some
cases the data returned is direct reference to the original data inside LAMMPS, cast to a void pointer. In that case the
data needs to be cast to a suitable pointer for the calling program to access it, and you may need to know the correct
dimensions and lengths. This also means you can directly change those value(s) from the calling program, e.g. to
modify atom positions. Of course, this should be done with care. When accessing per-atom data, please note that this
data is the per-processor local data and is indexed accordingly. Per-atom data can change sizes and ordering at every
neighbor list rebuild or atom sort event as atoms migrate between sub-domains and processors.

#include "library.h"
#include <stdio.h>

int main(int argc, char **argv)

{
void *handle;
int i;

handle = lammps_open_no_mpi(0, NULL, NULL);

lammps_file(handle,"in.sysinit");
printf("Running a simulation with %g atoms.\n",
lammps_get_natoms(handle));

printf(" %d local and %d ghost atoms. %d atom types\n",

lammps_extract_setting(handle,"nlocal"),
lammps_extract_setting(handle,"nghost"),
lammps_extract_setting(handle,"ntypes"));

double *dt = (double *)lammps_extract_global(handle,"dt");

printf("Changing timestep from %g to 0.5\n", *dt);
*dt = 0.5;

lammps_command(handle,"run 1000 post no");

for (i=0; i < 10; ++i) {

(continues on next page)

12.1. LAMMPS C Library API 437

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

lammps_command(handle,"run 100 pre no post no");
printf("PE = %g\nKE = %g\n",
lammps_get_thermo(handle,"pe"),
lammps_get_thermo(handle,"ke"));
}
lammps_close(handle);
return 0;
}

double lammps_get_natoms(void *handle)

Return the total number of atoms in the system.

This number may be very large when running large simulations across multiple processors. Depending on com-
pile time choices, LAMMPS may be using either 32-bit or a 64-bit integer to store this number. For portability
this function returns thus a double precision floating point number, which can represent up to a 53-bit signed
integer exactly (≈ 1016 ).
As an alternative, you can use lammps_extract_global() and cast the resulting pointer to an integer
pointer of the correct size and dereference it. The size of that integer (in bytes) can be queried by calling
lammps_extract_setting() to return the size of a bigint integer.
Changed in version 18Sep2020: The type of the return value was changed from int to double to accommodate
reporting atom counts for larger systems that would overflow a 32-bit int without having to depend on a 64-bit
bit integer type definition.

Parameters handle – pointer to a previously created LAMMPS instance

Returns total number of atoms or 0 if value is too large

double lammps_get_thermo(void *handle, const char *keyword)

Get current value of a thermo keyword.
This function returns the current value of a thermo keyword. Unlike lammps_extract_global() it does not
give access to the storage of the desired data but returns its value as a double, so it can also return information
that is computed on-the-fly.
Parameters
• handle – pointer to a previously created LAMMPS instance
• keyword – string with the name of the thermo keyword
Returns value of the requested thermo property or 0.0

void lammps_extract_box(void *handle, double *boxlo, double *boxhi, double *xy, double *yz, double *xz, int
*pflags, int *boxflag)
Extract simulation box parameters.
This function (re-)initializes the simulation box and boundary information and then assign the designated data
to the locations in the pointers passed as arguments. Any argument (except the first) may be a NULL pointer and
then will not be assigned.

438 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

Parameters
• handle – pointer to a previously created LAMMPS instance
• boxlo – pointer to 3 doubles where the lower box boundary is stored
• boxhi – pointer to 3 doubles where the upper box boundary is stored
• xy – pointer to a double where the xy tilt factor is stored
• yz – pointer to a double where the yz tilt factor is stored
• xz – pointer to a double where the xz tilt factor is stored
• pflags – pointer to 3 ints, set to 1 for periodic boundaries and 0 for non-periodic
• boxflag – pointer to an int, which is set to 1 if the box will be changed during a simulation
by a fix and 0 if not.

void lammps_reset_box(void *handle, double *boxlo, double *boxhi, double xy, double yz, double xz)
Reset simulation box parameters.
This function sets the simulation box dimensions (upper and lower bounds and tilt factors) from the provided
data and then re-initializes the box information and all derived settings. It may only be called before atoms are
created.
Parameters
• handle – pointer to a previously created LAMMPS instance
• boxlo – pointer to 3 doubles containing the lower box boundary
• boxhi – pointer to 3 doubles containing the upper box boundary
• xy – xy tilt factor
• yz – yz tilt factor
• xz – xz tilt factor

void lammps_memory_usage(void *handle, double *meminfo)

Get memory usage information

This function will retrieve memory usage information for the current LAMMPS instance or process. The meminfo
buffer will be filled with 3 different numbers (if supported by the operating system). The first is the tally (in
MBytes) of all large memory allocations made by LAMMPS. This is a lower boundary of how much memory is
requested and does not account for memory allocated on the stack or allocations via new. The second number is
the current memory allocation of the current process as returned by a memory allocation reporting in the system
library. The third number is the maximum amount of RAM (not swap) used by the process so far. If any of the
two latter parameters is not supported by the operating system it will be set to zero.
New in version 18Sep2020.

Parameters
• handle – pointer to a previously created LAMMPS instance
• meminfo – buffer with space for at least 3 double to store data in.

12.1. LAMMPS C Library API 439

LAMMPS Documentation, Release stable 29Sep2021

int lammps_get_mpi_comm(void *handle)

Return current LAMMPS world communicator as integer

This will take the LAMMPS “world” communicator and convert it to an integer using MPI_Comm_c2f(), so it is
equivalent to the corresponding MPI communicator in Fortran. This way it can be safely passed around between
different programming languages. To convert it to the C language representation use MPI_Comm_f2c().
If LAMMPS was compiled with MPI_STUBS, this function returns -1.
New in version 18Sep2020.
See also lammps_open_fortran()

Parameters handle – pointer to a previously created LAMMPS instance

Returns Fortran representation of the LAMMPS world communicator

int lammps_extract_setting(void *handle, const char *keyword)

Query LAMMPS about global settings.

This function will retrieve or compute global properties. In contrast to lammps_get_thermo() this function
returns an int. The following tables list the currently supported keyword. If a keyword is not recognized, the
function returns -1.
• Integer sizes
• System status
• System sizes
• Atom style flags
Integer sizes

Keyword Description / Return value

bigint size of the bigint integer type, 4 or 8 bytes. Set at compile time.
tagint size of the tagint integer type, 4 or 8 bytes. Set at compile time.
imageint size of the imageint integer type, 4 or 8 bytes. Set at compile time.

System status

Keyword Description / Return value

dimension Number of dimensions: 2 or 3. See dimension command.
box_exist 1 if the simulation box is defined, 0 if not. See create_box command.
nthreads Number of requested OpenMP threads for LAMMPS’ execution
newton_bond 1 if Newton’s 3rd law is applied to bonded interactions, 0 if not.
newton_pair 1 if Newton’s 3rd law is applied to non-bonded interactions, 0 if not.
triclinic 1 if the the simulation box is triclinic, 0 if orthogonal. See change_box command.
universe_rank MPI rank on LAMMPS’ universe communicator (0 <= universe_rank < universe_size)
universe_size Number of ranks on LAMMPS’ universe communicator (world_size <= universe_size)
world_rank MPI rank on LAMMPS’ world communicator (0 <= world_rank < world_size)
world_size Number of ranks on LAMMPS’ world communicator

440 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

System sizes

Keyword Description / Return value

nlocal number of “owned” atoms of the current MPI rank.
nghost number of “ghost” atoms of the current MPI rank.
nall number of all “owned” and “ghost” atoms of the current MPI rank.
nmax maximum of nlocal+nghost across all MPI ranks (for per-atom data array size).
ntypes number of atom types
nbondtypes number of bond types
nangletypes number of angle types
ndihedraltypes number of dihedral types
nimpropertypes number of improper types

Atom style flags

Keyword Description / Return value

molecule_flag
1 if the atom style includes molecular topology data. See atom_style command.
q_flag 1 if the atom style includes point charges. See atom_style command.
mu_flag 1 if the atom style includes point dipoles. See atom_style command.
rmass_flag 1 if the atom style includes per-atom masses, 0 if there are per-type masses. See atom_style
command.
radius_flag 1 if the atom style includes a per-atom radius. See atom_style command.
sphere_flag 1 if the atom style describes extended particles that can rotate. See atom_style command.
ellip- 1 if the atom style describes extended particles that may be ellipsoidal. See atom_style com-
soid_flag mand.
omega_flag 1 if the atom style can store per-atom rotational velocities. See atom_style command.
torque_flag 1 if the atom style can store per-atom torques. See atom_style command.
angmom_flag 1 if the atom style can store per-atom angular momentum. See atom_style command.

See also lammps_extract_global()

Parameters
• handle – pointer to a previously created LAMMPS instance
• keyword – string with the name of the thermo keyword
Returns value of the queried setting or -1 if unknown

int lammps_extract_global_datatype(void *handle, const char *name)

Get data type of internal global LAMMPS variables or arrays.

This function returns an integer that encodes the data type of the global property with the specified name. See
_LMP_DATATYPE_CONST for valid values. Callers of lammps_extract_global() can use this information to
then decide how to cast the (void*) pointer and access the data.
New in version 18Sep2020.

Parameters
• handle – pointer to a previously created LAMMPS instance (unused)
• name – string with the name of the extracted property

12.1. LAMMPS C Library API 441

LAMMPS Documentation, Release stable 29Sep2021

Returns integer constant encoding the data type of the property or -1 if not found.

void *lammps_extract_global(void *handle, const char *name)

Get pointer to internal global LAMMPS variables or arrays.

This function returns a pointer to the location of some global property stored in one of the constituent classes of
a LAMMPS instance. The returned pointer is cast to void * and needs to be cast to a pointer of the type that the
entity represents. The pointers returned by this function are generally persistent; therefore it is not necessary to
call the function again, unless a clear command command is issued which wipes out and recreates the contents
of the LAMMPS class.
Please also see lammps_extract_setting(), lammps_get_thermo(), and lammps_extract_box().
The following tables list the supported names, their data types, length of the data area, and a short de-
scription. The data type can also be queried through calling lammps_extract_global_datatype().
The bigint type may be defined to be either an int or an int64_t. This is set at compile time of
the LAMMPS library and can be queried through calling lammps_extract_setting(). The function
lammps_extract_global_datatype() will directly report the “native” data type. The following tables are
provided:
• Timestep settings
• Simulation box settings
• System property settings
• Unit settings
Timestep settings

Name Type Length Description

dt dou- 1 length of the time step. See timestep command.
ble
ntimestep bigint 1 current time step number. See reset_timestep command.
atime dou- 1 accumulated simulation time in time units.
ble
atimestep bigint 1 the number of the timestep when “atime” was last updated.
respa_levels int 1 number of r-RESPA levels. See run_style command.
respa_dt dou- number of r-RESPA length of the time steps with r-RESPA. See run_style com-
ble levels mand.

Simulation box settings

442 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

Name Type Length Description

boxlo dou- 3 lower box boundaries. See create_box command.
ble
boxhi dou- 3 upper box boundaries. See create_box command.
ble
boxxlo dou- 1 lower box boundary in x-direction. See create_box command.
ble
boxxhi dou- 1 upper box boundary in x-direction. See create_box command.
ble
boxylo dou- 1 lower box boundary in y-direction. See create_box command.
ble
boxyhi dou- 1 upper box boundary in y-direction. See create_box command.
ble
boxzlo dou- 1 lower box boundary in z-direction. See create_box command.
ble
boxzhi dou- 1 upper box boundary in z-direction. See create_box command.
ble
sublo dou- 3 subbox lower boundaries
ble
subhi dou- 3 subbox upper boundaries
ble
sublo_lambda dou- 3 subbox lower boundaries in fractional coordinates (for triclinic cells)
ble
subhi_lambda dou- 3 subbox upper boundaries in fractional coordinates (for triclinic cells)
ble
periodicity int 3 0 if non-periodic, 1 if periodic for x, y, and z; See boundary command.
triclinic int 1 1 if the the simulation box is triclinic, 0 if orthogonal; See change_box
command.
xy dou- 1 triclinic tilt factor. See Triclinic (non-orthogonal) simulation boxes.
ble
yz dou- 1 triclinic tilt factor. See Triclinic (non-orthogonal) simulation boxes.
ble
xz dou- 1 triclinic tilt factor. See Triclinic (non-orthogonal) simulation boxes.
ble

System property settings

12.1. LAMMPS C Library API 443

LAMMPS Documentation, Release stable 29Sep2021

Name Type Length Description

ntypes int 1 number of atom types
nbonds big- 1 total number of bonds in the simulation.
int
nangles big- 1 total number of angles in the simulation.
int
ndihedrals big- 1 total number of dihedrals in the simulation.
int
nimprop- big- 1 total number of impropers in the simulation.
ers int
natoms big- 1 total number of atoms in the simulation.
int
nlocal int 1 number of “owned” atoms of the current MPI rank.
nghost int 1 number of “ghost” atoms of the current MPI rank.
nmax int 1 maximum of nlocal+nghost across all MPI ranks (for per-atom data array
size).
q_flag int 1 deprecated. Use lammps_extract_setting() instead.

Unit settings

444 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

Name Type Length Description

units char 1 string with the current unit style. See units command.
*
boltz dou- 1 value of the “boltz” constant. See units command.
ble
hplanck dou- 1 value of the “hplanck” constant. See units command.
ble
mvv2e dou- 1 factor to convert 12 mv 2 for a particle to the current energy unit; See units com-
ble mand.
ftm2v dou- 1 (description missing) See units command.
ble
mv2d dou- 1 (description missing) See units command.
ble
nktv2p dou- 1 (description missing) See units command.
ble
qi qj
qqr2e dou- 1 factor to convert r to energy units; See units command.
ble
qe2f dou- 1 (description missing) See units command.
ble
vxmu2f dou- 1 (description missing) See units command.
ble
xxt2kmu dou- 1 (description missing) See units command.
ble
dielectric dou- 1 value of the dielectric constant. See dielectric command.
ble
qqrd2e dou- 1 (description missing) See units command.
ble
e_mass dou- 1 (description missing) See units command.
ble
hhmrr2e dou- 1 (description missing) See units command.
ble
mvh2r dou- 1 (description missing) See units command.
ble
angstrom dou- 1 constant to convert current length unit to angstroms; 1.0 for reduced (aka “lj”)
ble units. See units command.
fem- dou- 1 constant to convert current time unit to femtoseconds; 1.0 for reduced (aka “lj”)
tosecond ble units
qelectron dou- 1 (description missing) See units command.
ble

Warning: Modifying the data in the location pointed to by the returned pointer may lead to inconsistent
internal data and thus may cause failures or crashes or bogus simulations. In general it is thus usually better
to use a LAMMPS input command that sets or changes these parameters. Those will takes care of all side
effects and necessary updates of settings derived from such settings. Where possible a reference to such a
command or a relevant section of the manual is given below.

Parameters
• handle – pointer to a previously created LAMMPS instance
• name – string with the name of the extracted property

12.1. LAMMPS C Library API 445

LAMMPS Documentation, Release stable 29Sep2021

Returns pointer (cast to void *) to the location of the requested property. NULL if name is not
known.

12.1.4 Per-atom properties

This section documents the following functions:

• lammps_extract_atom_datatype()
• lammps_extract_atom()

int lammps_extract_atom_datatype(void *handle, const char *name)

Get data type of a LAMMPS per-atom property

This function returns an integer that encodes the data type of the per-atom property with the specified name.
See _LMP_DATATYPE_CONST for valid values. Callers of lammps_extract_atom() can use this information to
then decide how to cast the (void*) pointer and access the data.
New in version 18Sep2020.

Parameters
• handle – pointer to a previously created LAMMPS instance
• name – string with the name of the extracted property
Returns integer constant encoding the data type of the property or -1 if not found.

void *lammps_extract_atom(void *handle, const char *name)

Get pointer to a LAMMPS per-atom property.

This function returns a pointer to the location of per-atom properties (and per-atom-type properties in the case of
the ‘mass’ keyword). Per-atom data is distributed across sub-domains and thus MPI ranks. The returned pointer
is cast to void * and needs to be cast to a pointer of data type that the entity represents.
A table with supported keywords is included in the documentation of the Atom::extract() function.

Warning: The pointers returned by this function are generally not persistent since per-atom data may be
re-distributed, re-allocated, and re-ordered at every re-neighboring operation.

Parameters
• handle – pointer to a previously created LAMMPS instance
• name – string with the name of the extracted property
Returns pointer (cast to void *) to the location of the requested data or NULL if not found.

446 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

12.1.5 Compute, fixes, variables

This section documents accessing or modifying data stored by computes, fixes, or variables in LAMMPS using the
following functions:
• lammps_extract_compute()
• lammps_extract_fix()
• lammps_extract_variable()
• lammps_set_variable()

void *lammps_extract_compute(void *handle, const char*, int, int)

Get pointer to data from a LAMMPS compute.

This function returns a pointer to the location of data provided by a compute command instance identified by
the compute-ID. Computes may provide global, per-atom, or local data, and those may be a scalar, a vector, or
an array or they may provide the information about the dimensions of the respective data. Since computes may
provide multiple kinds of data, it is required to set style and type flags representing what specific data is desired.
This also determines to what kind of pointer the returned pointer needs to be cast to access the data correctly.
The function returns NULL if the compute ID is not found or the requested data is not available or current. The
following table lists the available options.

Style (see Type (see Returned Returned data

_LMP_STYLE_CONST) _LMP_TYPE_CONST) type
LMP_STYLE_GLOBAL LMP_TYPE_SCALAR double * Global scalar
LMP_STYLE_GLOBAL LMP_TYPE_VECTOR double * Global vector
LMP_STYLE_GLOBAL LMP_TYPE_ARRAY double ** Global array
LMP_STYLE_GLOBAL LMP_SIZE_VECTOR int * Length of global vector
LMP_STYLE_GLOBAL LMP_SIZE_ROWS int * Rows of global array
LMP_STYLE_GLOBAL LMP_SIZE_COLS int * Columns of global array
LMP_STYLE_ATOM LMP_TYPE_VECTOR double * Per-atom value
LMP_STYLE_ATOM LMP_TYPE_ARRAY double ** Per-atom vector
LMP_STYLE_ATOM LMP_SIZE_COLS int * Columns in per-atom array, 0 if
vector
LMP_STYLE_LOCAL LMP_TYPE_VECTOR double * Local data vector
LMP_STYLE_LOCAL LMP_TYPE_ARRAY double ** Local data array
LMP_STYLE_LOCAL LMP_SIZE_ROWS int * Number of local data rows
LMP_STYLE_LOCAL LMP_SIZE_COLS int * Number of local data columns

Note: If the compute’s data is not computed for the current step, the compute will be invoked. LAMMPS cannot
easily check at that time, if it is valid to invoke a compute, so it may fail with an error. The caller has to check to
avoid such an error.

Warning: The pointers returned by this function are generally not persistent since the computed data may
be re-distributed, re-allocated, and re-ordered at every invocation. It is advisable to re-invoke this function
before the data is accessed, or make a copy if the data shall be used after other LAMMPS commands have
been issued.

12.1. LAMMPS C Library API 447

LAMMPS Documentation, Release stable 29Sep2021

Parameters
• handle – pointer to a previously created LAMMPS instance
• id – string with ID of the compute
• style – constant indicating the style of data requested (global, per-atom, or local)
• type – constant indicating type of data (scalar, vector, or array) or size of rows or columns
Returns pointer (cast to void *) to the location of the requested data or NULL if not found.

void *lammps_extract_fix(void *handle, const char*, int, int, int, int)

Get pointer to data from a LAMMPS fix.

This function returns a pointer to data provided by a fix command instance identified by its fix-ID. Fixes may
provide global, per-atom, or local data, and those may be a scalar, a vector, or an array, or they may provide the
information about the dimensions of the respective data. Since individual fixes may provide multiple kinds of
data, it is required to set style and type flags representing what specific data is desired. This also determines to
what kind of pointer the returned pointer needs to be cast to access the data correctly. The function returns NULL
if the fix ID is not found or the requested data is not available.
The following table lists the available options.

Style (see Type (see Returned Returned data

_LMP_STYLE_CONST) _LMP_TYPE_CONST) type
LMP_STYLE_GLOBAL LMP_TYPE_SCALAR double * Copy of global scalar
LMP_STYLE_GLOBAL LMP_TYPE_VECTOR double * Copy of global vector element at
index nrow
LMP_STYLE_GLOBAL LMP_TYPE_ARRAY double * Copy of global array element at
nrow, ncol
LMP_STYLE_GLOBAL LMP_SIZE_VECTOR int * Length of global vector
LMP_STYLE_GLOBAL LMP_SIZE_ROWS int * Rows in global array
LMP_STYLE_GLOBAL LMP_SIZE_COLS int * Columns in global array
LMP_STYLE_ATOM LMP_TYPE_VECTOR double * Per-atom value
LMP_STYLE_ATOM LMP_TYPE_ARRAY double ** Per-atom vector
LMP_STYLE_ATOM LMP_SIZE_COLS int * Columns of per-atom array, 0 if
vector
LMP_STYLE_LOCAL LMP_TYPE_VECTOR double * Local data vector
LMP_STYLE_LOCAL LMP_TYPE_ARRAY double ** Local data array
LMP_STYLE_LOCAL LMP_SIZE_ROWS int * Number of local data rows
LMP_STYLE_LOCAL LMP_SIZE_COLS int * Number of local data columns

Note: When requesting global data, the fix data can only be accessed one item at a time without access to the
pointer itself. Thus this function will allocate storage for a single double value, copy the returned value to it,
and returns a pointer to the location of the copy. Therefore the allocated storage needs to be freed after its use to
avoid a memory leak. Example:

double *dptr = (double *) lammps_extract_fix(handle,name,0,1,0,0);

double value = *dptr;
lammps_free((void *)dptr);

448 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

Note: LAMMPS cannot easily check if it is valid to access the data, so it may fail with an error. The caller has
to avoid such an error.

Warning: The pointers returned by this function for per-atom or local data are generally not persistent, since
the computed data may be re-distributed, re-allocated, and re-ordered at every invocation of the fix. It is thus
advisable to re-invoke this function before the data is accessed, or make a copy, if the data shall be used after
other LAMMPS commands have been issued.

Parameters
• handle – pointer to a previously created LAMMPS instance
• id – string with ID of the fix
• style – constant indicating the style of data requested (global, per-atom, or local)
• type – constant indicating type of data (scalar, vector, or array) or size of rows or columns
• nrow – row index (only used for global vectors and arrays)
• ncol – column index (only used for global arrays)
Returns pointer (cast to void *) to the location of the requested data or NULL if not found.

void *lammps_extract_variable(void *handle, const char*, const char*)

Get pointer to data from a LAMMPS variable.

This function returns a pointer to data from a LAMMPS variable command identified by its name. When the vari-
able is either an equal-style compatible or an atom-style variable the variable is evaluated and the corresponding
value(s) returned. Variables of style internal are compatible with equal-style variables and so are python-style
variables, if they return a numeric value. For other variable styles their string value is returned. The function
returns NULL when a variable of the provided name is not found or of an incompatible style. The group argu-
ment is only used for atom-style variables and ignored otherwise. If set to NULL when extracting data from and
atom-style variable, the group is assumed to be “all”.
When requesting data from an equal-style or compatible variable this function allocates storage for a single
double value, copies the returned value to it, and returns a pointer to the location of the copy. Therefore the
allocated storage needs to be freed after its use to avoid a memory leak. Example:

double *dptr = (double *) lammps_extract_variable(handle,name,NULL);

double value = *dptr;
lammps_free((void *)dptr);

For atom-style variables the data returned is a pointer to an allocated block of storage of double of the length
atom->nlocal. Since the data is returned a copy, the location will persist, but its content will not be updated,
in case the variable is re-evaluated. To avoid a memory leak this pointer needs to be freed after use in the calling
program.
For other variable styles the returned pointer needs to be cast to a char pointer.

12.1. LAMMPS C Library API 449

LAMMPS Documentation, Release stable 29Sep2021

const char *cptr = (const char *) lammps_extract_variable(handle,name,NULL);

printf("The value of variable %s is %s\n", name, cptr);

Note: LAMMPS cannot easily check if it is valid to access the data referenced by the variables, e.g. computes or
fixes or thermodynamic info, so it may fail with an error. The caller has to make certain, that the data is extracted
only when it safe to evaluate the variable and thus an error and crash is avoided.

Parameters
• handle – pointer to a previously created LAMMPS instance
• name – name of the variable
• group – group-ID for atom style variable or NULL
Returns pointer (cast to void *) to the location of the requested data or NULL if not found.

int lammps_set_variable(void*, char*, char*)

Set the value of a string-style variable.
This function assigns a new value from the string str to the string-style variable name. Returns -1 if a variable of
that name does not exist or is not a string-style variable, otherwise 0.
Parameters
• handle – pointer to a previously created LAMMPS instance
• name – name of the variable
• str – new value of the variable
Returns 0 on success or -1 on failure

enum _LMP_DATATYPE_CONST
Data type constants for extracting data from atoms, computes and fixes
Must be kept in sync with the equivalent constants in lammps/constants.py
Values:

enumerator LAMMPS_INT
32-bit integer (array)

enumerator LAMMPS_INT_2D
two-dimensional 32-bit integer array

enumerator LAMMPS_DOUBLE
64-bit double (array)

enumerator LAMMPS_DOUBLE_2D
two-dimensional 64-bit double array

enumerator LAMMPS_INT64
64-bit integer (array)

450 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

enumerator LAMMPS_INT64_2D
two-dimensional 64-bit integer array

enumerator LAMMPS_STRING
C-String

enum _LMP_STYLE_CONST
Style constants for extracting data from computes and fixes.
Must be kept in sync with the equivalent constants in lammps/constants.py
Values:

enumerator LMP_STYLE_GLOBAL
return global data

enumerator LMP_STYLE_ATOM
return per-atom data

enumerator LMP_STYLE_LOCAL
return local data

enum _LMP_TYPE_CONST
Type and size constants for extracting data from computes and fixes.
Must be kept in sync with the equivalent constants in lammps/constants.py
Values:

enumerator LMP_TYPE_SCALAR
return scalar

enumerator LMP_TYPE_VECTOR
return vector

enumerator LMP_TYPE_ARRAY
return array

enumerator LMP_SIZE_VECTOR
return length of vector

enumerator LMP_SIZE_ROWS
return number of rows

enumerator LMP_SIZE_COLS
return number of columns

12.1. LAMMPS C Library API 451

LAMMPS Documentation, Release stable 29Sep2021

12.1.6 Scatter/gather operations

This section has functions which gather per-atom data from one or more processors into a contiguous global list ordered
by atom ID. The same list is returned to all calling processors. It also contains functions which scatter per-atom data
from a contiguous global list across the processors that own those atom IDs. It also has a create_atoms() function which
can create new atoms by scattering them appropriately to owning processors in the LAMMPS spatial decomposition.
It documents the following functions:
• lammps_gather_atoms()
• lammps_gather_atoms_concat()
• lammps_gather_atoms_subset()
• lammps_scatter_atoms()
• lammps_scatter_atoms_subset()
• lammps_gather_bonds()
• lammps_gather()
• lammps_gather_concat()
• lammps_gather_subset()
• lammps_scatter()
• lammps_scatter_subset()
• lammps_create_atoms()

void lammps_gather_atoms(void *handle, char *name, int type, int count, void *data)

void lammps_gather_atoms_concat(void *handle, char *name, int type, int count, void *data)

void lammps_gather_atoms_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)

void lammps_scatter_atoms(void *handle, char *name, int type, int count, void *data)

void lammps_scatter_atoms_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)

452 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

void lammps_gather_bonds(void *handle, void *data)

Gather type and constituent atom info for all bonds

This function copies the list of all bonds into a buffer provided by the calling code. The buffer will be filled with
bond type, bond atom 1, bond atom 2 for each bond. Thus the buffer has to be allocated to the dimension of 3 times
the total number of bonds times the size of the LAMMPS “tagint” type, which is either 4 or 8 bytes depending on
whether they are stored in 32-bit or 64-bit integers, respectively. This size depends on the compile time settings
used when compiling the LAMMPS library and can be queried by calling lammps_extract_setting() with
the keyword “tagint”.
When running in parallel, the data buffer must be allocated on all MPI ranks and will be filled with the information
for all bonds in the system.
New in version 28Jul2021.
Below is a brief C code demonstrating accessing this collected bond information.

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include "library.h"

int main(int argc, char **argv)

{
int tagintsize;
int64_t i, nbonds;
void *handle, *bonds;

handle = lammps_open_no_mpi(0, NULL, NULL);

lammps_file(handle, "in.some_input");

tagintsize = lammps_extract_setting(handle, "tagint");

if (tagintsize == 4)
nbonds = *(int32_t *)lammps_extract_global(handle, "nbonds");
else
nbonds = *(int64_t *)lammps_extract_global(handle, "nbonds");
bonds = malloc(nbonds * 3 * tagintsize);

lammps_gather_bonds(handle, bonds);

if (lammps_extract_setting(handle, "world_rank") == 0) {
if (tagintsize == 4) {
int32_t *bonds_real = (int32_t *)bonds;
for (i = 0; i < nbonds; ++i) {
printf("bond % 4ld: type = %d, atoms: % 4d % 4d\n",i,
bonds_real[3*i], bonds_real[3*i+1], bonds_real[3*i+2]);
}
} else {
int64_t *bonds_real = (int64_t *)bonds;
for (i = 0; i < nbonds; ++i) {
printf("bond % 4ld: type = %ld, atoms: % 4ld % 4ld\n",i,
bonds_real[3*i], bonds_real[3*i+1], bonds_real[3*i+2]);
}
}
(continues on next page)

12.1. LAMMPS C Library API 453

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

}

lammps_close(handle);
lammps_mpi_finalize();
free(bonds);
return 0;
}

Parameters
• handle – pointer to a previously created LAMMPS instance
• data – pointer to data to copy the result to

void lammps_gather(void *handle, char *name, int type, int count, void *data)

void lammps_gather_concat(void *handle, char *name, int type, int count, void *data)

void lammps_gather_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)

void lammps_scatter(void *handle, char *name, int type, int count, void *data)

void lammps_scatter_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)

int lammps_create_atoms(void *handle, int n, const int *id, const int *type, const double *x, const double *v,
const int *image, int bexpand)
Create N atoms from list of coordinates

The prototype for this function when compiling with -DLAMMPS_BIGBIG is:

int lammps_create_atoms(void *handle, int n, int64_t *id, int *type, double *x,␣
,→double *v, int64_t *image, int bexpand);

This function creates additional atoms from a given list of coordinates and a list of atom types. Additionally the
atom-IDs, velocities, and image flags may be provided. If atom-IDs are not provided, they will be automatically
created as a sequence following the largest existing atom-ID.
This function is useful to add atoms to a simulation or - in tandem with lammps_reset_box() - to restore a
previously extracted and saved state of a simulation. Additional properties for the new atoms can then be assigned
via the lammps_scatter_atoms() lammps_extract_atom() functions.

454 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

For non-periodic boundaries, atoms will not be created that have coordinates outside the box unless it is a shrink-
wrap boundary and the shrinkexceed flag has been set to a non-zero value. For periodic boundaries atoms will
be wrapped back into the simulation cell and its image flags adjusted accordingly, unless explicit image flags are
provided.
The function returns the number of atoms created or -1 on failure, e.g. when called before as box has been
created.
Coordinates and velocities have to be given in a 1d-array in the order
X(1),Y(1),Z(1),X(2),Y(2),Z(2),. . . ,X(N),Y(N),Z(N).

Parameters
• handle – pointer to a previously created LAMMPS instance
• n – number of atoms, N, to be added to the system
• id – pointer to N atom IDs; NULL will generate IDs
• type – pointer to N atom types (required)
• x – pointer to 3N doubles with x-,y-,z- positions of the new atoms (required)
• v – pointer to 3N doubles with x-,y-,z- velocities of the new atoms (set to 0.0 if NULL)
• image – pointer to N imageint sets of image flags, or NULL
• bexpand – if 1, atoms outside of shrink-wrap boundaries will still be created and not dropped
and the box extended
Returns number of atoms created on success; -1 on failure (no box, no atom IDs, etc.)

12.1.7 Neighbor list access

The following functions enable access to neighbor lists generated by LAMMPS or querying of their properties:
• lammps_find_compute_neighlist()
• lammps_find_fix_neighlist()
• lammps_find_pair_neighlist()
• lammps_neighlist_num_elements()
• lammps_neighlist_element_neighbors()

int lammps_find_compute_neighlist(void *handle, const char *id, int request)

Find index of a neighbor list requested by a compute
The neighbor list request from a compute is identified by the compute ID and the request ID. The request ID is
typically 0, but will be
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – Identifier of compute instance
• reqid – request id to identify neighbor list in case there are multiple requests from the same
compute
Returns return neighbor list index if found, otherwise -1

12.1. LAMMPS C Library API 455

LAMMPS Documentation, Release stable 29Sep2021

int lammps_find_fix_neighlist(void *handle, const char *id, int request)

Find index of a neighbor list requested by a fix
The neighbor list request from a fix is identified by the fix ID and the request ID. The request ID is typically 0,
but will be > 0 in case a fix has multiple neighbor list requests.
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – Identifier of fix instance
• reqid – request id to identify neighbor list in case there are multiple requests from the same
fix
Returns return neighbor list index if found, otherwise -1

int lammps_find_pair_neighlist(void *handle, const char *style, int exact, int nsub, int request)
Find index of a neighbor list requested by a pair style
This function determines which of the available neighbor lists for pair styles matches the given conditions. It first
matches the style name. If exact is 1 the name must match exactly, if exact is 0, a regular expression or sub-string
match is done. If the pair style is hybrid or hybrid/overlay the style is matched against the sub styles instead.
If a the same pair style is used multiple times as a sub-style, the nsub argument must be > 0 and represents the
nth instance of the sub-style (same as for the pair_coeff command, for example). In that case nsub=0 will not
produce a match and this function will return -1.
The final condition to be checked is the request ID (reqid). This will normally be 0, but some pair styles request
multiple neighbor lists and set the request ID to a value > 0.
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• style – String used to search for pair style instance
• exact – Flag to control whether style should match exactly or only a regular expression /
sub-string match is applied.
• nsub – match nsub-th hybrid sub-style instance of the same style
• reqid – request id to identify neighbor list in case there are multiple requests from the same
pair style instance
Returns return neighbor list index if found, otherwise -1

int lammps_neighlist_num_elements(void *handle, int idx)

Return the number of entries in the neighbor list with given index
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• idx – neighbor list index
Returns return number of entries in neighbor list, -1 if idx is not a valid index

456 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

void lammps_neighlist_element_neighbors(void *handle, int idx, int element, int *iatom, int *numneigh, int
**neighbors)
Return atom local index, number of neighbors, and array of neighbor local atom indices of neighbor list entry
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• idx – index of this neighbor list in the list of all neighbor lists
• element – index of this neighbor list entry
• iatom – [out] local atom index (i.e. in the range [0, nlocal + nghost), -1 if invalid idx or
element value
• numneigh – [out] number of neighbors of atom iatom or 0
• neighbors – [out] pointer to array of neighbor atom local indices or NULL

12.1.8 Configuration information

This section documents the following functions:

• lammps_version()
• lammps_get_os_info()
• lammps_config_has_mpi_support()
• lammps_config_has_gzip_support()
• lammps_config_has_png_support()
• lammps_config_has_jpeg_support()
• lammps_config_has_ffmpeg_support()
• lammps_config_has_exceptions()
• lammps_config_has_package()
• lammps_config_package_count()
• lammps_config_package_name()
• lammps_config_accelerator()
• lammps_has_gpu_device()
• lammps_gpu_device_info()
• lammps_has_style()
• lammps_style_count()
• lammps_style_name()
• lammps_has_id()
• lammps_id_count()
• lammps_id_name()

These library functions can be used to query the LAMMPS library for compile time settings and included packages
and styles. This enables programs that use the library interface to determine whether the linked LAMMPS library

12.1. LAMMPS C Library API 457

LAMMPS Documentation, Release stable 29Sep2021

is compatible with the requirements of the application without crashing during the LAMMPS functions (e.g. due to
missing pair styles from packages) or to choose between different options (e.g. whether to use lj/cut, lj/cut/
opt, lj/cut/omp or lj/cut/intel). Most of the functions can be called directly without first creating a LAMMPS
instance. While crashes within LAMMPS may be recovered from by enabling exceptions, avoiding them proactively
is a safer approach.

Listing 1: Example for using configuration settings functions

#include "library.h"
#include <stdio.h>

int main(int argc, char **argv)

{
void *handle;

handle = lammps_open_no_mpi(0, NULL, NULL);

lammps_file(handle, "in.missing");
if (lammps_has_error(handle)) {
char errmsg[256];
int errtype;
errtype = lammps_get_last_error_message(handle, errmsg, 256);
fprintf(stderr, "LAMMPS failed with error: %s\n", errmsg);
return 1;
}
/* write compressed dump file depending on available of options */
if (lammps_has_style(handle, "dump", "atom/zstd")) {
lammps_command(handle, "dump d1 all atom/zstd 100 dump.zst");
} else if (lammps_has_style(handle, "dump", "atom/gz")) {
lammps_command(handle, "dump d1 all atom/gz 100 dump.gz");
} else if (lammps_config_has_gzip_support()) {
lammps_command(handle, "dump d1 all atom 100 dump.gz");
} else {
lammps_command(handle, "dump d1 all atom 100 dump");
}
lammps_close(handle);
return 0;
}

int lammps_version(void *handle)

Get numerical representation of the LAMMPS version date.
The lammps_version() function returns an integer representing the version of the LAMMPS code in the format
YYYYMMDD. This can be used to implement backward compatibility in software using the LAMMPS library
interface. The specific format guarantees, that this version number is growing with every new LAMMPS release.
Parameters handle – pointer to a previously created LAMMPS instance
Returns an integer representing the version data in the format YYYYMMDD

void lammps_get_os_info(char *buffer, int buf_size)

Get operating system and architecture information

458 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

The lammps_get_os_info() function can be used to retrieve detailed information about the hosting operating
system and compiler/runtime.
A suitable buffer for a C-style string has to be provided and its length. The assembled text will be truncated to
not overflow this buffer. The string is typically a few hundred bytes long.
New in version 9Oct2020.

Parameters
• buffer – string buffer to copy the information to
• buf_size – size of the provided string buffer

int lammps_config_has_mpi_support()
This function is used to query whether LAMMPS was compiled with a real MPI library or in serial. For the real
MPI library it reports the size of the MPI communicator in bytes (4 or 8), which allows to check for compatibility
with a hosting code.
Returns 0 when compiled with MPI STUBS, otherwise the MPI_Comm size in bytes

int lammps_config_has_gzip_support()
Check if the LAMMPS library supports compressed files via a pipe to gzip
Several LAMMPS commands (e.g. read_data command, write_data command, dump styles atom, custom, and
xyz) support reading and writing compressed files via creating a pipe to the gzip program. This function checks
whether this feature was enabled at compile time. It does not check whether the gzip itself is installed and
usable.
Returns 1 if yes, otherwise 0

int lammps_config_has_png_support()
Check if the LAMMPS library supports writing PNG format images
The LAMMPS dump style image supports writing multiple image file formats. Most of them need, however,
support from an external library and using that has to be enabled at compile time. This function checks whether
support for the PNG image file format is available in the current LAMMPS library.
Returns 1 if yes, otherwise 0

int lammps_config_has_jpeg_support()
Check if the LAMMPS library supports writing JPEG format images
The LAMMPS dump style image supports writing multiple image file formats. Most of them need, however,
support from an external library and using that has to be enabled at compile time. This function checks whether
support for the JPEG image file format is available in the current LAMMPS library.
Returns 1 if yes, otherwise 0

12.1. LAMMPS C Library API 459

LAMMPS Documentation, Release stable 29Sep2021

int lammps_config_has_ffmpeg_support()
Check if the LAMMPS library supports creating movie files via a pipe to ffmpeg
The LAMMPS dump style movie supports generating movies from images on-the-fly via creating a pipe to the
ffmpeg program. This function checks whether this feature was enabled at compile time. It does not check
whether the ffmpeg itself is installed and usable.
Returns 1 if yes, otherwise 0

int lammps_config_has_exceptions()
Check whether LAMMPS errors will throw a C++ exception

In case of errors LAMMPS will either abort or throw a C++ exception. The latter has to be enabled at compile
time. This function checks if exceptions were enabled.
When using the library interface and C++ exceptions are enabled, the library interface functions will “catch” them
and the error status can then be checked by calling lammps_has_error() and the most recent error message
can be retrieved via lammps_get_last_error_message(). This can allow to restart a calculation or delete
and recreate the LAMMPS instance when C++ exceptions are enabled. One application of using exceptions this
way is the LAMMPS shell. If C++ exceptions are disabled and an error happens during a call to LAMMPS, the
application will terminate.

Returns 1 if yes, otherwise 0

int lammps_config_has_package(const char*)

Check if a specific package has been included in LAMMPS
This function checks if the LAMMPS library in use includes the specific LAMMPS package provided as argu-
ment.
Parameters name – string with the name of the package
Returns 1 if included, 0 if not.

int lammps_config_package_count()
Count the number of installed packages in the LAMMPS library.
This function counts how many LAMMPS packages are included in the LAMMPS library in use.
Returns number of packages included

int lammps_config_package_name(int, char*, int)

Get the name of a package in the list of installed packages in the LAMMPS library.
This function copies the name of the package with the index idx into the provided C-style string buffer. The
length of the buffer must be provided as buf_size argument. If the name of the package exceeds the length of the
buffer, it will be truncated accordingly. If the index is out of range, the function returns 0 and buffer is set to an
empty string, otherwise 1;
Parameters

460 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

• idx – index of the package in the list of included packages (0 <= idx < package count)
• buffer – string buffer to copy the name of the package to
• buf_size – size of the provided string buffer
Returns 1 if successful, otherwise 0

int lammps_config_accelerator(const char*, const char*, const char*)

Check for compile time settings in accelerator packages included in LAMMPS.
This function checks availability of compile time settings of included accelerator packages in LAMMPS. Sup-
ported packages names are “GPU”, “KOKKOS”, “INTEL”, and “OPENMP”. Supported categories are “api”
with possible settings “cuda”, “hip”, “phi”, “pthreads”, “opencl”, “openmp”, and “serial”, and “precision” with
possible settings “double”, “mixed”, and “single”. If the combination of package, category, and setting is avail-
able, the function returns 1, otherwise 0.
Parameters
• package – string with the name of the accelerator package
• category – string with the category name of the setting
• setting – string with the name of the specific setting
Returns 1 if available, 0 if not.

int lammps_has_gpu_device()
Check for presence of a viable GPU package device

The lammps_has_gpu_device() function checks at runtime if an accelerator device is present that can be used
with the GPU package. If at least one suitable device is present the function will return 1, otherwise 0.
More detailed information about the available device or devices can be obtained by calling the
lammps_get_gpu_device_info() function.
New in version 14May2021.

Returns 1 if viable device is available, 0 if not.

void lammps_get_gpu_device_info(char *buffer, int buf_size)

Get GPU package device information

The lammps_get_gpu_device_info() function can be used to retrieve detailed information about any accel-
erator devices that are viable for use with the GPU package. It will produce a string that is equivalent to the
output of the nvc_get_device or ocl_get_device or hip_get_device tools that are compiled alongside
LAMMPS if the GPU package is enabled.
A suitable buffer for a C-style string has to be provided and its length. The assembled text will be truncated to
not overflow this buffer. This string can be several kilobytes long, if multiple devices are present.
New in version 14May2021.

Parameters

12.1. LAMMPS C Library API 461

LAMMPS Documentation, Release stable 29Sep2021

• buffer – string buffer to copy the information to

• buf_size – size of the provided string buffer

int lammps_has_style(void*, const char*, const char*)

Check if a specific style has been included in LAMMPS
This function checks if the LAMMPS library in use includes the specific style of a specific category provided
as an argument. Valid categories are: atom, integrate, minimize, pair, bond, angle, dihedral, improper, kspace,
compute, fix, region, dump, and command.
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• category – category of the style
• name – name of the style
Returns 1 if included, 0 if not.

int lammps_style_count(void*, const char*)

Count the number of styles of category in the LAMMPS library.
This function counts how many styles in the provided category are included in the LAMMPS library in use.
Please see lammps_has_style() for a list of valid categories.
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• category – category of styles
Returns number of styles in category

int lammps_style_name(void*, const char*, int, char*, int)

Look up the name of a style by index in the list of style of a given category in the LAMMPS library.
This function copies the name of the category style with the index idx into the provided C-style string buffer.
The length of the buffer must be provided as buf_size argument. If the name of the style exceeds the length of
the buffer, it will be truncated accordingly. If the index is out of range, the function returns 0 and buffer is set to
an empty string, otherwise 1.
Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• category – category of styles
• idx – index of the style in the list of category styles (0 <= idx < style count)
• buffer – string buffer to copy the name of the style to
• buf_size – size of the provided string buffer
Returns 1 if successful, otherwise 0

462 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

int lammps_has_id(void*, const char*, const char*)

Check if a specific ID exists in the current LAMMPS instance

This function checks if the current LAMMPS instance a category ID of the given name exists. Valid categories
are: compute, dump, fix, group, molecule, region, and variable.
New in version 9Oct2020.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• category – category of the id
• name – name of the id
Returns 1 if included, 0 if not.

int lammps_id_count(void*, const char*)

Count the number of IDs of a category.

This function counts how many IDs in the provided category are defined in the current LAMMPS instance.
Please see lammps_has_id() for a list of valid categories.
New in version 9Oct2020.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• category – category of IDs
Returns number of IDs in category

int lammps_id_name(void*, const char*, int, char*, int)

Look up the name of an ID by index in the list of IDs of a given category.

This function copies the name of the category ID with the index idx into the provided C-style string buffer. The
length of the buffer must be provided as buf_size argument. If the name of the style exceeds the length of the
buffer, it will be truncated accordingly. If the index is out of range, the function returns 0 and buffer is set to an
empty string, otherwise 1.
New in version 9Oct2020.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• category – category of IDs
• idx – index of the ID in the list of category styles (0 <= idx < count)
• buffer – string buffer to copy the name of the style to
• buf_size – size of the provided string buffer

12.1. LAMMPS C Library API 463

LAMMPS Documentation, Release stable 29Sep2021

Returns 1 if successful, otherwise 0

12.1.9 Utility functions

To simplify some tasks, the library interface contains these utility functions. They do not directly call the LAMMPS
library.
• lammps_encode_image_flags()
• lammps_decode_image_flags()
• lammps_set_fix_external_callback()
• lammps_fix_external_set_energy_global()
• lammps_fix_external_set_energy_peratom()
• lammps_fix_external_set_virial_global()
• lammps_fix_external_set_virial_peratom()
• lammps_fix_external_set_vector_length()
• lammps_fix_external_set_vector()
• lammps_free()
• lammps_is_running()
• lammps_force_timeout()
• lammps_has_error()
• lammps_get_last_error_message()
The lammps_free() function is a clean-up function to free memory that the library had allocated previously via
other function calls. Look for notes in the descriptions of the individual commands where such memory buffers were
allocated that require the use of lammps_free().

int lammps_encode_image_flags(int ix, int iy, int iz)

Encode three integer image flags into a single imageint.

The prototype for this function when compiling with -DLAMMPS_BIGBIG is:

int64_t lammps_encode_image_flags(int ix, int iy, int iz);

This function performs the bit-shift, addition, and bit-wise OR operations necessary to combine the values
of three integers representing the image flags in x-, y-, and z-direction. Unless LAMMPS is compiled with -
DLAMMPS_BIGBIG, those integers are limited 10-bit signed integers [-512, 511]. Otherwise the return type
changes from int to int64_t and the valid range for the individual image flags becomes [-1048576,1048575],
i.e. that of a 21-bit signed integer. There is no check on whether the arguments conform to these requirements.

Parameters
• ix – image flag value in x
• iy – image flag value in y
• iz – image flag value in z

464 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

Returns encoded image flag integer

void lammps_decode_image_flags(int image, int *flags)

Decode a single image flag integer into three regular integers

The prototype for this function when compiling with -DLAMMPS_BIGBIG is:

void lammps_decode_image_flags(int64_t image, int *flags);

This function does the reverse operation of lammps_encode_image_flags() and takes an image flag integer
does the bit-shift and bit-masking operations to decode it and stores the resulting three regular integers into the
buffer pointed to by flags.

Parameters
• image – encoded image flag integer
• flags – pointer to storage where the decoded image flags are stored.

void lammps_set_fix_external_callback(void *handle, const char *id, FixExternalFnPtr funcptr, void *ptr)
Set up the callback function for a fix external instance with the given ID.

Fix external allows programs that are running LAMMPS through its library interface to modify certain LAMMPS
properties on specific timesteps, similar to the way other fixes do.
This function sets the callback function for use with the “pf/callback” mode. The function has to have C language
bindings with the prototype:

void func(void *ptr, bigint timestep, int nlocal, tagint *ids, double **x, double␣
,→**fexternal);

The argument ptr to this function will be stored in fix external and the passed as the first argument calling the
callback function func(). This would usually be a pointer to the active LAMMPS instance, i.e. the same pointer
as the handle argument. This would be needed to call functions that set the global or per-atom energy or virial
contributions from within the callback function.
The callback mechanism is one of the two modes of how forces and can be applied to a simulation with the help
of fix external. The alternative is the array mode where you call lammps_fix_external_get_force().
Please see the documentation for fix external for more information about how to use the fix and how to couple it
with an external code.
Changed in version 28Jul2021.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – fix ID of fix external instance
• funcptr – pointer to callback function
• ptr – pointer to object in calling code, passed to callback function as first argument

12.1. LAMMPS C Library API 465

LAMMPS Documentation, Release stable 29Sep2021

void lammps_fix_external_set_energy_global(void *handle, const char *id, double eng)

Set the global energy contribution for a fix external instance with the given ID.

This is a companion function to lammps_set_fix_external_callback() and

lammps_fix_external_get_force() to also set the contribution to the global energy from the exter-
nal code. The value of the eng argument will be stored in the fix and applied on the current and all following
timesteps until changed by another call to this function. The energy is in energy units as determined by the
current units settings and is the total energy of the contribution. Thus when running in parallel all MPI
processes have to call this function with the same value and this will be returned as scalar property of the fix
external instance when accessed in LAMMPS input commands or from variables.
Please see the documentation for fix external for more information about how to use the fix and how to couple it
with an external code.
New in version 28Jul2021.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – fix ID of fix external instance
• eng – total energy to be added to the global energy

void lammps_fix_external_set_energy_peratom(void *handle, const char *id, double *eng)

Set the per-atom energy contribution for a fix external instance with the given ID.

This is a companion function to lammps_set_fix_external_callback() to set the per-atom energy contri-

bution due to the fix from the external code as part of the callback function. For this to work, the handle to the
LAMMPS object must be passed as the ptr argument when registering the callback function.
Please see the documentation for fix external for more information about how to use the fix and how to couple it
with an external code.
New in version 28Jul2021.

Note: This function is fully independent from lammps_fix_external_set_energy_global() and will

NOT add any contributions to the global energy tally and NOT check whether the sum of the contributions
added here are consistent with the global added energy.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – fix ID of fix external instance
• eng – pointer to array of length nlocal with the energy to be added to the per-atom energy

466 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

void lammps_fix_external_set_virial_global(void *handle, const char *id, double *virial)

Set the global virial contribution for a fix external instance with the given ID.

This is a companion function to lammps_set_fix_external_callback() and

lammps_fix_external_get_force() to set the contribution to the global virial from the external code.
The 6 values of the virial array will be stored in the fix and applied on the current and all following timesteps
until changed by another call to this function. The components of the virial need to be stored in the order: xx,
yy, zz, xy, xz, yz. In LAMMPS the virial is stored internally as stress*volume in units of pressure*volume as
determined by the current units settings and is the total contribution. Thus when running in parallel all MPI
processes have to call this function with the same value and this will then be added by fix external.
Please see the documentation for fix external for more information about how to use the fix and how to couple it
with an external code.
New in version 28Jul2021.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – fix ID of fix external instance
• virial – the 6 global stress tensor components to be added to the global virial

void lammps_fix_external_set_virial_peratom(void *handle, const char *id, double **virial)

Set the per-atom virial contribution for a fix external instance with the given ID.

This is a companion function to lammps_set_fix_external_callback() to set the per-atom virial contri-

bution due to the fix from the external code as part of the callback function. For this to work, the handle to the
LAMMPS object must be passed as the ptr argument when registering the callback function.
The order and units of the per-atom stress tensor elements are the same as for the global virial. The code in fix
external assumes the dimensions of the per-atom virial array is double virial[nlocal][6].
Please see the documentation for fix external for more information about how to use the fix and how to couple it
with an external code.
New in version 28Jul2021.

Note: This function is fully independent from lammps_fix_external_set_virial_global() and will

NOT add any contributions to the global virial tally and NOT check whether the sum of the contributions added
here are consistent with the global added virial.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – fix ID of fix external instance
• virial – a list of nlocal entries with the 6 per-atom stress tensor components to be added
to the per-atom virial

12.1. LAMMPS C Library API 467

LAMMPS Documentation, Release stable 29Sep2021

void lammps_fix_external_set_vector_length(void *handle, const char *id, int len)

Set the vector length for a global vector stored with fix external for analysis

This is a companion function to lammps_set_fix_external_callback() and

lammps_fix_external_get_force() to set the length of a global vector of properties that will be
stored with the fix via lammps_fix_external_set_vector().
This function needs to be called before a call to lammps_fix_external_set_vector() and before a run or
minimize command. When running in parallel it must be called from all MPI processes and with the same length
parameter.
Please see the documentation for fix external for more information about how to use the fix and how to couple it
with an external code.
New in version 28Jul2021.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – fix ID of fix external instance
• len – length of the global vector to be stored with the fix

void lammps_fix_external_set_vector(void *handle, const char *id, int idx, double val)
Store a global vector value for a fix external instance with the given ID.

This is a companion function to lammps_set_fix_external_callback() and

lammps_fix_external_get_force() to set the values of a global vector of properties that will be
stored with the fix. And can be accessed from within LAMMPS input commands (e.g. fix ave/time or variables)
when used in a vector context.
This function needs to be called after a call to lammps_fix_external_set_vector_length() and the and
before a run or minimize command. When running in parallel it must be called from all MPI processes and with
the same index and value parameters. The value is assumed to be extensive.
Please see the documentation for fix external for more information about how to use the fix and how to couple it
with an external code.
New in version 28Jul2021.

Note: The index in the idx parameter is 1-based, i.e. the first element is set with idx = 1 and
the last element of the vector with idx = N, where N is the value of the len parameter of the call to
lammps_fix_external_set_vector_length().

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• id – fix ID of fix external instance
• idx – 1-based index of in global vector
• val – value to be stored in global vector

468 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

void lammps_free(void *ptr)

Free memory buffer allocated by LAMMPS.
Some of the LAMMPS C library interface functions return data as pointer to a buffer that has been allocated by
LAMMPS or the library interface. This function can be used to delete those in order to avoid memory leaks.
Parameters ptr – pointer to data allocated by LAMMPS

int lammps_is_running(void *handle)

Check if LAMMPS is currently inside a run or minimization
This function can be used from signal handlers or multi-threaded applications to determine if the LAMMPS
instance is currently active.
Parameters handle – pointer to a previously created LAMMPS instance cast to void *.
Returns 0 if idle or >0 if active

void lammps_force_timeout(void *handle)

Force a timeout to cleanly stop an ongoing run
This function can be used from signal handlers or multi-threaded applications to cleanly terminate an ongoing
run.
Parameters handle – pointer to a previously created LAMMPS instance cast to void *

int lammps_has_error(void *handle)

Check if there is a (new) error message available
This function can be used to query if an error inside of LAMMPS has thrown a C++ exception.

Note: This function will always report “no error” when the LAMMPS library has been compiled without
-DLAMMPS_EXCEPTIONS which turns fatal errors aborting LAMMPS into a C++ exceptions. You can use the
library function lammps_config_has_exceptions() to check if this is the case.

Parameters handle – pointer to a previously created LAMMPS instance cast to void *.

Returns 0 on no error, 1 on error.

int lammps_get_last_error_message(void *handle, char *buffer, int buf_size)

Copy the last error message into the provided buffer
This function can be used to retrieve the error message that was set in the event of an error inside of LAMMPS
which resulted in a C++ exception. A suitable buffer for a C-style string has to be provided and its length. If
the internally stored error message is longer, it will be truncated accordingly. The return value of the function
corresponds to the kind of error: a “1” indicates an error that occurred on all MPI ranks and is often recoverable,
while a “2” indicates an abort that would happen only in a single MPI rank and thus may not be recoverable as
other MPI ranks may be waiting on the failing MPI ranks to send messages.

12.1. LAMMPS C Library API 469

LAMMPS Documentation, Release stable 29Sep2021

Note: This function will do nothing when the LAMMPS library has been compiled without
-DLAMMPS_EXCEPTIONS which turns errors aborting LAMMPS into a C++ exceptions. You can use the library
function lammps_config_has_exceptions() to check if this is the case.

Parameters
• handle – pointer to a previously created LAMMPS instance cast to void *.
• buffer – string buffer to copy the error message to
• buf_size – size of the provided string buffer
Returns 1 when all ranks had the error, 2 on a single rank error.

12.1.10 Extending the C API

The functionality of the LAMMPS library interface has historically been motivated by the needs of its users. Functions
have been added or expanded as they were needed and used. Contributions to the interface are always welcome.
However with a refactoring of the library interface and its documentation that started in Spring 2020, there are now a
few requirements for including new changes or extensions.
• New functions should be orthogonal to existing ones and not implement functionality that can already be achieved
with the existing APIs.
• All changes and additions should be documented with Doxygen style comments and references to those functions
added to the corresponding files in the doc/src folder.
• If possible, new unit tests to test those new features should be added.
• New features should also be implemented and documented not just for the C interface, but also the Python and
Fortran interfaces.
• All additions should work and be compatible with -DLAMMPS_BIGBIG, -DLAMMPS_SMALLBIG,
-DLAMMPS_SMALLSMALL as well as when compiling with and without MPI support.
• The library.h file should be kept compatible to C code at a level similar to C89. Its interfaces may not reference
any custom data types (e.g. bigint, tagint, and so on) that are only known inside of LAMMPS; instead int
and int64_t should be used.
• only use C style comments, not C++ style
Please note that these are not strict requirements, but the LAMMPS developers very much appreciate, if they are
followed and can assist with implementing what is missing. It helps maintaining the code base and keeping it consistent.

12.2 LAMMPS Python APIs

The LAMMPS Python module enables calling the LAMMPS C library API from Python by dynamically loading
functions in the LAMMPS shared library through the Python ctypes module. Because of the dynamic loading, it is
required that LAMMPS is compiled in “shared” mode. The Python interface is object oriented, but otherwise tries
to be very similar to the C library API. Three different Python classes to run LAMMPS are available and they build on
each other. More information on this is in the Use Python with LAMMPS section of the manual. Use of the LAMMPS
Python module is described in The lammps Python module.

470 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

12.3 LAMMPS Fortran API

The LAMMPS Fortran module is a wrapper around calling functions from the LAMMPS C library API. This is done
using the ISO_C_BINDING feature in Fortran 2003. The interface is object oriented but otherwise tries to be very
similar to the C library API and the basic Python module.

12.3.1 The LIBLAMMPS Fortran Module

The LIBLAMMPS module provides an interface to call LAMMPS from a Fortran code. It is based on the LAMMPS
C-library interface and requires a Fortran 2003 compatible compiler to be compiled.
While C libraries have a defined binary interface (ABI) and can thus be used from multiple compiler versions from
different vendors for as long as they are compatible with the hosting operating system, the same is not true for Fortran
codes. Thus the LAMMPS Fortran module needs to be compiled alongside the code using it from the source code in
fortran/lammps.f90. When linking, you also need to link to the LAMMPS library. A typical command line for a
simple program using the Fortran interface would be:

mpifort -o testlib.x lammps.f90 testlib.f90 -L. -llammps

Please note, that the MPI compiler wrapper is only required when the calling the library from an MPI parallel code.
Please also note the order of the source files: the lammps.f90 file needs to be compiled first, since it provides the
LIBLAMMPS module that is imported by the Fortran code using the interface. A working example code can be found
together with equivalent examples in C and C++ in the examples/COUPLE/simple folder of the LAMMPS distribu-
tion.
New in version 9Oct2020.

Work in Progress
This Fortran module is work in progress and only the documented functionality is currently available. The final imple-
mentation should cover the entire range of functionality available in the C and Python library interfaces.

Note: A contributed (and complete!) Fortran interface that more closely resembles the C-library interface is available
in the examples/COUPLE/fortran2 folder. Please see the README file in that folder for more information about it
and how to contact its author and maintainer.

12.3.2 Creating or deleting a LAMMPS object

With the Fortran interface the creation of a LAMMPS instance is included in the constructor for creating the lammps()
derived type. To import the definition of that type and its type bound procedures you need to add a USE LIBLAMMPS
statement. Internally it will call either lammps_open_fortran() or lammps_open_no_mpi() from the C library API
to create the class instance. All arguments are optional and lammps_mpi_init() will be called automatically, if it is
needed. Similarly, a possible call to lammps_finalize() is integrated into the close() function and triggered with
the optional logical argument set to .true.. Here is a simple example:

PROGRAM testlib
USE LIBLAMMPS ! include the LAMMPS library interface
TYPE(lammps) :: lmp ! derived type to hold LAMMPS instance
(continues on next page)

12.3. LAMMPS Fortran API 471

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

CHARACTER(len=*), DIMENSION(*), PARAMETER :: args = &
[ CHARACTER(len=12) :: 'liblammps', '-log', 'none' ]

! create a LAMMPS instance (and initialize MPI)

lmp = lammps(args)
! get and print numerical version code
PRINT*, 'LAMMPS Version: ', lmp%version()
! delete LAMMPS instance (and shuts down MPI)
CALL lmp%close(.true.)

END PROGRAM testlib

Executing LAMMPS commands

Once a LAMMPS instance is created, it is possible to “drive” the LAMMPS simulation by telling LAMMPS to
read commands from a file, or pass individual or multiple commands from strings or lists of strings. This is done
similar to how it is implemented in the C-library <pg_lib_execute> interface. Before handing off the calls to the
C-library interface, the corresponding Fortran versions of the calls (file(), command(), commands_list(), and
commands_string()) have to make a copy of the strings passed as arguments so that they can be modified to be
compatible with the requirements of strings in C without affecting the original strings. Those copies are automatically
deleted after the functions return. Below is a small demonstration of the uses of the different functions:

PROGRAM testcmd
USE LIBLAMMPS
TYPE(lammps) :: lmp
CHARACTER(len=512) :: cmds
CHARACTER(len=40),ALLOCATABLE :: cmdlist(:)
CHARACTER(len=10) :: trimmed
INTEGER :: i

lmp = lammps()
CALL lmp%file('in.melt')
CALL lmp%command('variable zpos index 1.0')
! define 10 groups of 10 atoms each
ALLOCATE(cmdlist(10))
DO i=1,10
WRITE(trimmed,'(I10)') 10*i
WRITE(cmdlist(i),'(A,I1,A,I10,A,A)') &
'group g',i-1,' id ',10*(i-1)+1,':',ADJUSTL(trimmed)
END DO
CALL lmp%commands_list(cmdlist)
! run multiple commands from multi-line string
cmds = 'clear' // NEW_LINE('A') // &
'region box block 0 2 0 2 0 2' // NEW_LINE('A') // &
'create_box 1 box' // NEW_LINE('A') // &
'create_atoms 1 single 1.0 1.0 ${zpos}'
CALL lmp%commands_string(cmds)
CALL lmp%close()

END PROGRAM testcmd

472 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

12.3.3 The LIBLAMMPS module API

Below are the detailed descriptions of definitions and interfaces of the contents of the LIBLAMMPS Fortran interface to
LAMMPS.
type lammps
Derived type that is the general class of the Fortran interface. It holds a reference to the LAMMPS class instance
that any of the included calls are forwarded to.
Type fields
• % handle [c_ptr] :: reference to the LAMMPS class
• % close :: close()
• % version :: version()
• % file :: file()
• % command :: command()
• % commands_list :: commands_list()
• % commands_string :: commands_string()
function lammps(args[, comm ])
This is the constructor for the Fortran class and will forward the arguments to a call to either
lammps_open_fortran() or lammps_open_no_mpi(). If the LAMMPS library has been compiled with MPI
support, it will also initialize MPI, if it has not already been initialized before.
The args argument with the list of command line parameters is optional and so it the comm argument with the
MPI communicator. If comm is not provided, MPI_COMM_WORLD is assumed. For more details please see the
documentation of lammps_open().
Parameters args (*) [character(len=*),optional] :: arguments as list of strings
Options comm [integer,optional] :: MPI communicator
Return lammps :: an instance of the lammps derived type
subroutine close([finalize ])
This method will close down the LAMMPS instance through calling lammps_close(). If the finalize argument
is present and has a value of .true., then this subroutine also calls lammps_mpi_finalize().
Options finalize [logical,optional] :: shut down the MPI environment of the LAMMPS library if
true.
function version()
This method returns the numeric LAMMPS version like lammps_version()
Return integer :: LAMMPS version

subroutine file(filename)
This method will call lammps_file() to have LAMMPS read and process commands from a file.
Parameters filename [character(len=*)] :: name of file with LAMMPS commands
subroutine command(cmd)
This method will call lammps_command() to have LAMMPS execute a single command.

12.3. LAMMPS Fortran API 473

LAMMPS Documentation, Release stable 29Sep2021

Parameters cmd [character(len=*)] :: single LAMMPS command

subroutine commands_list(cmds)
This method will call lammps_commands_list() to have LAMMPS execute a list of input lines.
Parameters cmd (*) [character(len=*)] :: list of LAMMPS input lines
subroutine commands_string(str)
This method will call lammps_commands_string() to have LAMMPS execute a block of commands from a
string.
Parameters str [character(len=*)] :: LAMMPS input in string

12.4 LAMMPS C++ API

It is also possible to invoke the LAMMPS C++ API directly in your code. It lacks some of the convenience of the C
library API, but it allows more direct access to simulation data and thus more low-level manipulations. The following
links provide some examples and references to the C++ API.

12.4.1 Using the C++ API directly

Using the C++ classes of the LAMMPS library is lacking some of the convenience of the C library API, but it allows a
more direct access to simulation data and thus more low-level manipulations and tighter integration of LAMMPS into
another code. While for the complete C library API is provided in the library.h header file, for using the C++ API it
is required to include the individual header files defining the individual classes in use. Typically the name of the class
and the name of the header follow some simple rule. Examples are given below.

12.4.2 Creating or deleting a LAMMPS object

When using the LAMMPS library interfaces, the core task is to create an instance of the LAMMPS_NS::LAMMPS class.
In C++ this can be done directly through the new operator. All further operations are then initiated through calling
member functions of some of the components of the LAMMPS class or accessing their data members. The destruction
of the LAMMPS instance is correspondingly initiated by using the delete operator. Here is a simple example:

#include "lammps.h"

#include <mpi.h>
#include <iostream>

int main(int argc, char **argv)

{
LAMMPS_NS::LAMMPS *lmp;
// custom argument vector for LAMMPS library
const char *lmpargv[] {"liblammps", "-log", "none"};
int lmpargc = sizeof(lmpargv)/sizeof(const char *);

// explicitly initialize MPI

MPI_Init(&argc, &argv);

// create LAMMPS instance

(continues on next page)

474 Chapter 12. LAMMPS Library Interfaces

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

lmp = new LAMMPS_NS::LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);
// output numerical version string
std::cout << "LAMMPS version ID: " << lmp->num_ver << std::endl;
// delete LAMMPS instance
delete lmp;

// stop MPI environment

MPI_Finalize();
return 0;
}

This minimal example only requires to include the lammps.h header file since it only accesses a non-pointer member
of the LAMMPS class.

12.4.3 Executing LAMMPS commands

Once a LAMMPS instance is created by your C++ code, you need to set up a simulation and that is most conveniently
done by “driving” it through issuing commands like you would do when running a LAMMPS simulation from an input
script. Processing of input in LAMMPS is handled by the Input class an instance of which is a member of the LAMMPS
class. You have two options: reading commands from a file, or executing a single command from a string. See below
for a small example:

#include "lammps.h"
#include "input.h"
#include <mpi.h>

using namespace LAMMPS_NS;

int main(int argc, char **argv)

{
const char *lmpargv[] {"liblammps", "-log", "none"};
int lmpargc = sizeof(lmpargv)/sizeof(const char *);

MPI_Init(&argc, &argv);
LAMMPS *lmp = new LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);
lmp->input->file("in.melt");
lmp->input->one("run 100 post no");
delete lmp;
return 0;
}

12.4. LAMMPS C++ API 475

LAMMPS Documentation, Release stable 29Sep2021

476 Chapter 12. LAMMPS Library Interfaces

 CHAPTER

THIRTEEN

USE PYTHON WITH LAMMPS

These pages describe various ways that LAMMPS and Python can be used together.

13.1 Overview

The LAMMPS distribution includes a python directory with the Python code needed to run LAMMPS from Python.
The python/lammps package contains the “lammps” Python module that wraps the LAMMPS C-library interface.
This module makes it is possible to do the following either from a Python script, or interactively from a Python prompt:
• create one or more instances of LAMMPS
• invoke LAMMPS commands or read them from an input script
• run LAMMPS incrementally
• extract LAMMPS results
• and modify internal LAMMPS data structures.
From a Python script you can do this in serial or in parallel. Running Python interactively in parallel does not generally
work, unless you have a version of Python that extends Python to enable multiple instances of Python to read what you
type.
To do all of this, you must build LAMMPS in “shared” mode and make certain that your Python interpreter can find
the lammps Python package and the LAMMPS shared library file.
The Python wrapper for LAMMPS uses the ctypes package in Python, which auto-generates the interface code needed
between Python and a set of C-style library functions. Ctypes has been part of the standard Python distribution since
version 2.5. You can check which version of Python you have by simply typing “python” at a shell prompt. Below is
an example output for Python version 3.8.5.

$ python
Python 3.8.5 (default, Aug 12 2020, 00:00:00)
[GCC 10.2.1 20200723 (Red Hat 10.2.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>

Warning: The options described in this section of the manual for using Python with LAMMPS currently support
either Python 2 or 3. Specifically version 2.7 or later and 3.6 or later. Since the Python community no longer
maintains Python 2 (see this notice), we recommend use of Python 3 with LAMMPS. While Python 2 code should
continue to work, that is not something we can guarantee long-term.

477
LAMMPS Documentation, Release stable 29Sep2021

LAMMPS can work together with Python in three ways. First, Python can wrap LAMMPS through the its library
interface, so that a Python script can create one or more instances of LAMMPS and launch one or more simulations.
In Python terms, this is referred to as “extending” Python with a LAMMPS module.

Fig. 1: Launching LAMMPS via Python

Second, the lower-level Python interface in the lammps Python class can be used indirectly through the provided
PyLammps and IPyLammps wrapper classes, also written in Python. These wrappers try to simplify the usage of
LAMMPS in Python by providing a more object-based interface to common LAMMPS functionality. They also reduce
the amount of code necessary to parameterize LAMMPS scripts through Python and make variables and computes
directly accessible.

Fig. 2: Using the PyLammps / IPyLammps wrappers

Third, LAMMPS can use the Python interpreter, so that a LAMMPS input script or styles can invoke Python code
directly, and pass information back-and-forth between the input script and Python functions you write. This Python
code can also call back to LAMMPS to query or change its attributes through the LAMMPS Python module mentioned
above. In Python terms, this is called “embedding” Python into LAMMPS. When used in this mode, Python can
perform script operations that the simple LAMMPS input script syntax can not.

478 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Fig. 3: Calling Python code from LAMMPS

13.2 Installation

The LAMMPS Python module enables calling the LAMMPS C library API from Python by dynamically loading func-
tions in the LAMMPS shared library through the Python ctypes module. Because of the dynamic loading, it is required
that LAMMPS is compiled in “shared” mode. It is also recommended to compile LAMMPS with C++ exceptions
enabled.
Two components are necessary for Python to be able to invoke LAMMPS code:
• The LAMMPS Python Package (lammps) from the python folder
• The LAMMPS Shared Library (liblammps.so, liblammps.dylib or liblammps.dll) from the folder where
you compiled LAMMPS.

13.2.1 Installing the LAMMPS Python Module and Shared Library

Making LAMMPS usable within Python and vice versa requires putting the LAMMPS Python package (lammps) into
a location where the Python interpreter can find it and installing the LAMMPS shared library into a folder that the
dynamic loader searches or inside of the installed lammps package folder. There are multiple ways to achieve this.
1. Do a full LAMMPS installation of libraries, executables, selected headers, documentation (if enabled), and
supporting files (only available via CMake), which can also be either system-wide or into user specific folders.
2. Install both components into a Python site-packages folder, either system-wide or in the corresponding user-
specific folder. This way no additional environment variables need to be set, but the shared library is otherwise
not accessible.
3. Do an installation into a virtual environment. This can either be an installation of the Python package only or a
full installation of LAMMPS.
4. Leave the files where they are in the source/development tree and adjust some environment variables.

Full install (CMake-only)

Build the LAMMPS executable and library with -DBUILD_SHARED_LIBS=on, -DLAMMPS_EXCEPTIONS=on and
-DPKG_PYTHON=on (The first option is required, the other two are optional by recommended). The exact file
name of the shared library depends on the platform (Unix/Linux, MacOS, Windows) and the build configuration

13.2. Installation 479

LAMMPS Documentation, Release stable 29Sep2021

being used. The installation base folder is already set by default to the $HOME/.local directory, but it can be
changed to a custom location defined by the CMAKE_INSTALL_PREFIX CMake variable. This uses a folder called
build to store files generated during compilation.

# create build folder

mkdir build
cd build

# configure LAMMPS compilation

cmake -C ../cmake/presets/basic.cmake -D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake

# compile LAMMPS
cmake --build .

# install LAMMPS into $HOME/.local

cmake --install .

This leads to an installation to the following locations:

File Location Notes

LAMMPS Python package X.Y depends on the installed
• $HOME/.local/
Python version
lib/pythonX.Y/
site-packages/lammps
(32bit)
• $HOME/.local/
lib64/pythonX.Y/
site-packages/lammps
(64bit)

LAMMPS shared library Set shared loader environment

• $HOME/.local/lib/
variable to this path (see below for
(32bit)
more info on this)
• $HOME/.local/lib64/
(64bit)

LAMMPS executable
• $HOME/.local/bin/

LAMMPS potential files Set LAMMPS_POTENTIALS envi-

• $HOME/.local/share/
ronment variable to this path
lammps/potentials/

For a system-wide installation you need to set CMAKE_INSTALL_PREFIX to a system folder like /usr (or /
usr/local); the default is ${HOME}/.local. The installation step for a system folder installation (not the
configuration/compilation) needs to be done with superuser privilege, e.g. by using sudo cmake --install
.. The installation folders will then be changed to (assuming /usr as prefix):

480 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

File Location Notes

LAMMPS Python package X.Y depends on the installed
• /usr/lib/pythonX.Y/
Python version
site-packages/lammps
(32bit)
• /usr/lib64/pythonX.Y/
site-packages/lammps
(64bit)

LAMMPS shared library

• /usr/lib/ (32bit)
• /usr/lib64/ (64bit)

LAMMPS executable
• /usr/bin/

LAMMPS potential files

• /usr/share/lammps/
potentials/

To be able to use the “user” installation you have to ensure that the folder containing the LAMMPS shared
library is either included in a path searched by the shared linker (e.g. like /usr/lib64/) or part of the
LD_LIBRARY_PATH environment variable (or DYLD_LIBRARY_PATH on MacOS). Otherwise you will get an error
when trying to create a LAMMPS object through the Python module.

# Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH

# MacOS
export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH

If you plan to use the LAMMPS executable (e.g., lmp), you may also need to adjust the PATH environment
variable (but many newer Linux distributions already have $HOME/.local/bin included). Example:

export PATH=$HOME/.local/bin:$PATH

To make those changes permanent, you can add the commands to your $HOME/.bashrc file. For a system-wide
installation is is not necessary due to files installed in system folders that are loaded automatically when a login
shell is started.

Python package only

Compile LAMMPS with either CMake or the traditional make procedure in shared mode. After compilation has
finished type (in the compilation folder):

make install-python

This will try to install (only) the shared library and the Python package into a system folder and if that fails
(due to missing write permissions) will instead do the installation to a user folder under $HOME/.local. For a
system-wide installation you would have to gain superuser privilege, e.g. though sudo

13.2. Installation 481

LAMMPS Documentation, Release stable 29Sep2021

File Location Notes

LAMMPS Python package X.Y depends on the installed
• $HOME/.local/
Python version
lib/pythonX.Y/
site-packages/lammps
(32bit)
• $HOME/.local/
lib64/pythonX.Y/
site-packages/lammps
(64bit)

LAMMPS shared library X.Y depends on the installed

• $HOME/.local/
Python version
lib/pythonX.Y/
site-packages/lammps
(32bit)
• $HOME/.local/
lib64/pythonX.Y/
site-packages/lammps
(64bit)

For a system-wide installation those folders would then become.

File Location Notes

LAMMPS Python package X.Y depends on the installed
• /usr/lib/pythonX.Y/
Python version
site-packages/lammps
(32bit)
• /usr/lib64/pythonX.Y/
site-packages/lammps
(64bit)

LAMMPS shared library X.Y depends on the installed

• /usr/lib/pythonX.Y/
Python version
site-packages/lammps
(32bit)
• /usr/lib64/pythonX.Y/
site-packages/lammps
(64bit)

No environment variables need to be set for those, as those folders are searched by default by Python or the
LAMMPS Python package.
For the traditional make process you can override the python version to version x.y when calling make with
PYTHON=pythonX.Y. For a CMake based compilation this choice has to be made during the CMake configuration
step.
If the default settings of make install-python are not what you want, you can invoke install.py from the
python directory manually as

$ python install.py -p <python package> -l <shared library> -v <version.h file> [-d

,→<pydir>]

482 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• The -p flag points to the lammps Python package folder to be installed,

• the -l flag points to the LAMMPS shared library file to be installed,
• the -v flag points to the version.h file in the LAMMPS source
• and the optional -d flag to a custom (legacy) installation folder
If you use a legacy installation folder, you will need to set your PYTHONPATH and LD_LIBRARY_PATH (and/or
DYLD_LIBRARY_PATH) environment variables accordingly as explained in the description for “In place use”.

Virtual environment
A virtual environment is a minimal Python installation inside of a folder. It allows isolating and customizing
a Python environment that is mostly independent from a user or system installation. For the core Python envi-
ronment, it uses symbolic links to the system installation and thus it can be set up quickly and will not take up
much disk space. This gives you the flexibility to install (newer/different) versions of Python packages that would
potentially conflict with already installed system packages. It also does not requite any superuser privileges. See
PEP 405: Python Virtual Environments for more information.
To create a virtual environment in the folder $HOME/myenv, use the venv module as follows.

# create virtual environment in folder $HOME/myenv

python3 -m venv $HOME/myenv

For Python versions prior 3.3 you can use virtualenv command instead of “python3 -m venv”. This step has to
be done only once.
To activate the virtual environment type:

source $HOME/myenv/bin/activate

This has to be done every time you log in or open a new terminal window and after you turn off the virtual
environment with the deactivate command.
When using CMake to build LAMMPS, you need to set CMAKE_INSTALL_PREFIX to the value of the
$VIRTUAL_ENV environment variable during the configuration step. For the traditional make procedure, no ad-
ditional steps are needed. After compiling LAMMPS you can do a “Python package only” installation with make
install-python and the LAMMPS Python package and the shared library file are installed into the following
locations:

13.2. Installation 483

LAMMPS Documentation, Release stable 29Sep2021

File Location Notes

LAMMPS Python Module X.Y depends on the installed
• $VIRTUAL_ENV/
Python version
lib/pythonX.Y/
site-packages/lammps
(32bit)
• $VIRTUAL_ENV/
lib64/pythonX.Y/
site-packages/lammps
(64bit)

LAMMPS shared library X.Y depends on the installed

• $VIRTUAL_ENV/
Python version
lib/pythonX.Y/
site-packages/lammps
(32bit)
• $VIRTUAL_ENV/
lib64/pythonX.Y/
site-packages/lammps
(64bit)

If you do a full installation (CMake only) with “install”, this leads to the following installation locations:

File Location Notes

LAMMPS Python Module X.Y depends on the installed
• $VIRTUAL_ENV/
Python version
lib/pythonX.Y/
site-packages/lammps
(32bit)
• $VIRTUAL_ENV/
lib64/pythonX.Y/
site-packages/lammps
(64bit)

LAMMPS shared library Set shared loader environment

• $VIRTUAL_ENV/lib/
variable to this path (see below for
(32bit)
more info on this)
• $VIRTUAL_ENV/lib64/
(64bit)

LAMMPS executable
• $VIRTUAL_ENV/bin/

LAMMPS potential files Set LAMMPS_POTENTIALS envi-

• $VIRTUAL_ENV/share/
ronment variable to this path
lammps/potentials/

In that case you need to modify the $HOME/myenv/bin/activate script in a similar fashion you need to up-
date your $HOME/.bashrc file to include the shared library and executable locations in LD_LIBRARY_PATH (or
DYLD_LIBRARY_PATH on MacOS) and PATH, respectively.
For example with:

484 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

# Unix/Linux
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/
,→activate

# MacOS
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> $HOME/myenv/
,→bin/activate

In place usage
You can also compile LAMMPS as usual in “shared” mode leave the shared library and Python package inside the
source/compilation folders. Instead of copying the files where they can be found, you need to set the environment
variables PYTHONPATH (for the Python package) and LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH on MacOS
For Bourne shells (bash, ksh and similar) the commands are:

export PYTHONPATH=${PYTHONPATH}:${HOME}/lammps/python
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/lammps/src

For the C-shells like csh or tcsh the commands are:

setenv PYTHONPATH ${PYTHONPATH}:${HOME}/lammps/python

setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src

On MacOS you may also need to set DYLD_LIBRARY_PATH accordingly. You can make those changes permanent
by editing your $HOME/.bashrc or $HOME/.login files, respectively.

Note: The PYTHONPATH needs to point to the parent folder that contains the lammps package!

To verify if LAMMPS can be successfully started from Python, start the Python interpreter, load the lammps Python
module and create a LAMMPS instance. This should not generate an error message and produce output similar to the
following:

$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import lammps
>>> lmp = lammps.lammps()
LAMMPS (18 Sep 2020)
using 1 OpenMP thread(s) per MPI task
>>>

Note: Unless you opted for “In place use”, you will have to rerun the installation any time you recompile LAMMPS
to ensure the latest Python package and shared library are installed and used.

Note: If you want Python to be able to load different versions of the LAMMPS shared library with different settings,
you will need to manually copy the files under different names (e.g. liblammps_mpi.so or liblammps_gpu.so) into

13.2. Installation 485

LAMMPS Documentation, Release stable 29Sep2021

the appropriate folder as indicated above. You can then select the desired library through the name argument of the
LAMMPS object constructor (see Creating or deleting a LAMMPS object).

13.2.2 Extending Python to run in parallel

If you wish to run LAMMPS in parallel from Python, you need to extend your Python with an interface to MPI. This
also allows you to make MPI calls directly from Python in your script, if you desire.
We have tested this with MPI for Python (aka mpi4py) and you will find installation instruction for it below.
Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as follows:
• Via pip into a local user folder with:

pip install --user mpi4py

• Via dnf into a system folder for RedHat/Fedora systems:

# for use with OpenMPI

sudo dnf install python3-mpi4py-openmpi
# for use with MPICH
sudo dnf install python3-mpi4py-openmpi

• Via pip into a virtual environment (see above):

$ source $HOME/myenv/activate
(myenv)$ pip install mpi4py

• Via pip into a system folder (not recommended):

sudo pip install mpi4py

For more detailed installation instructions and additional options, please see the mpi4py installation page.
To use mpi4py and LAMMPS in parallel from Python, you must make certain that both are using the same imple-
mentation and version of MPI library. If you only have one MPI library installed on your system this is not an issue, but
it can be if you have multiple MPI installations (e.g. on an HPC cluster to be selected through environment modules).
Your LAMMPS build is explicit about which MPI it is using, since it is either detected during CMake configuration
or in the traditional make build system you specify the details in your low-level src/MAKE/Makefile.foo file. The
installation process of mpi4py uses the mpicc command to find information about the MPI it uses to build against.
And it tries to load “libmpi.so” from the LD_LIBRARY_PATH. This may or may not find the MPI library that LAMMPS
is using. If you have problems running both mpi4py and LAMMPS together, this is an issue you may need to address,
e.g. by loading the module for different MPI installation so that mpi4py finds the right one.
If you have successfully installed mpi4py, you should be able to run Python and type

from mpi4py import MPI

without error. You should also be able to run Python in parallel on a simple test script

$ mpirun -np 4 python3 test.py

where test.py contains the lines

486 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

from mpi4py import MPI

comm = MPI.COMM_WORLD
print("Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()))

and see one line of output for each processor you run on.

# NOTE: the line order is not deterministic

$ mpirun -np 4 python3 test.py
Proc 0 out of 4 procs
Proc 1 out of 4 procs
Proc 2 out of 4 procs
Proc 3 out of 4 procs

13.3 Run LAMMPS from Python

After compiling the LAMMPS shared library and making it ready to use, you can now write and run Python scripts
that import the LAMMPS Python module and launch LAMMPS simulations through Python scripts. The following
pages take you through the various steps necessary, what functionality is available and give some examples how to use
it.

13.3.1 Running LAMMPS and Python in serial

To run a LAMMPS in serial, type these lines into Python interactively from the bench directory:

>>> from lammps import lammps

>>> lmp = lammps()
>>> lmp.file("in.lj")

Or put the same lines in the file test.py and run it as

$ python3 test.py

Either way, you should see the results of running the in.lj benchmark on a single processor appear on the screen, the
same as if you had typed something like:

lmp_serial -in in.lj

13.3.2 Running LAMMPS and Python in parallel with MPI

To run LAMMPS in parallel, assuming you have installed the mpi4py package as discussed Extending Python to run
in parallel, create a test.py file containing these lines:

from mpi4py import MPI

from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
me = MPI.COMM_WORLD.Get_rank()
nprocs = MPI.COMM_WORLD.Get_size()
(continues on next page)

13.3. Run LAMMPS from Python 487

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

print("Proc %d out of %d procs has" % (me,nprocs),lmp)
MPI.Finalize()

You can run the script in parallel as:

$ mpirun -np 4 python3 test.py

and you should see the same output as if you had typed

$ mpirun -np 4 lmp_mpi -in in.lj

Note that without the mpi4py specific lines from test.py

from lammps import lammps

lmp = lammps()
lmp.file("in.lj")

running the script with mpirun on P processors would lead to P independent simulations to run parallel, each with
a single processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS single processor outputs,
mpi4py is not working correctly.
Also note that once you import the mpi4py module, mpi4py initializes MPI for you, and you can use MPI calls directly
in your Python script, as described in the mpi4py documentation. The last line of your Python script should be MPI.
finalize(), to insure MPI is shut down correctly.

13.3.3 Running Python scripts

Note that any Python script (not just for LAMMPS) can be invoked in one of several ways:

$ python script.py
$ python -i script.py
$ ./script.py

The last command requires that the first line of the script be something like this:

#!/usr/bin/python
#!/usr/bin/python -i

where the path points to where you have Python installed, and that you have made the script file executable:

$ chmod +x script.py

Without the -i flag, Python will exit when the script finishes. With the -i flag, you will be left in the Python inter-
preter when the script finishes, so you can type subsequent commands. As mentioned above, you can only run Python
interactively when running Python on a single processor, not in parallel.

488 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

13.3.4 Creating or deleting a LAMMPS object

With the Python interface the creation of a LAMMPS instance is included in the constructors for the lammps, PyLammps,
and IPyLammps classes. Internally it will call either lammps_open() or lammps_open_no_mpi() from the C library
API to create the class instance.
All arguments are optional. The name argument allows loading a LAMMPS shared library that is named
liblammps_machine.so instead of the default name of liblammps.so. In most cases the latter will be installed
or used. The ptr argument is for use of the lammps module from inside a LAMMPS instance, e.g. with the python
command, where a pointer to the already existing LAMMPS class instance can be passed to the Python class and used
instead of creating a new instance. The comm argument may be used in combination with the mpi4py module to pass
an MPI communicator to LAMMPS and thus it is possible to run the Python module like the library interface on a
subset of the MPI ranks after splitting the communicator.
Here are simple examples using all three Python interfaces:

lammps API

from lammps import lammps

# NOTE: argv[0] is set by the lammps class constructor

args = ["-log", "none"]

# create LAMMPS instance

lmp = lammps(cmdargs=args)

# get and print numerical version code

print("LAMMPS Version: ", lmp.version())

# explicitly close and delete LAMMPS instance (optional)

lmp.close()

PyLammps API
The PyLammps class is a wrapper around the lammps class and all of its lower level functions. By default,
it will create a new instance of lammps passing along all arguments to the constructor of lammps.

from lammps import PyLammps

# NOTE: argv[0] is set by the lammps class constructor

args = ["-log", "none"]

# create LAMMPS instance

L = PyLammps(cmdargs=args)

# get and print numerical version code

print("LAMMPS Version: ", L.version())

# explicitly close and delete LAMMPS instance (optional)

L.close()

PyLammps objects can also be created on top of an existing lammps object:

13.3. Run LAMMPS from Python 489

LAMMPS Documentation, Release stable 29Sep2021

from lammps import lammps, PyLammps

...
# create LAMMPS instance
lmp = lammps(cmdargs=args)

# create PyLammps instance using previously created LAMMPS instance

L = PyLammps(ptr=lmp)

This is useful if you have to create the lammps instance is a specific way, but want to take advantage of the
PyLammps interface.

IPyLammps API
The IPyLammps class is an extension of the PyLammps class. It has the same construction behavior. By
default, it will create a new instance of lammps passing along all arguments to the constructor of lammps.

from lammps import IPyLammps

# NOTE: argv[0] is set by the lammps class constructor

args = ["-log", "none"]

# create LAMMPS instance

L = IPyLammps(cmdargs=args)

# get and print numerical version code

print("LAMMPS Version: ", L.version())

# explicitly close and delete LAMMPS instance (optional)

L.close()

You can also initialize IPyLammps on top of an existing lammps or PyLammps object:

from lammps import lammps, IPyLammps

...
# create LAMMPS instance
lmp = lammps(cmdargs=args)

# create PyLammps instance using previously created LAMMPS instance

L = PyLammps(ptr=lmp)

This is useful if you have to create the lammps instance is a specific way, but want to take advantage of the
IPyLammps interface.

In all of the above cases, same as with the C library API, this will use the MPI_COMM_WORLD communicator for the
MPI library that LAMMPS was compiled with.
The lmp.close() call is optional since the LAMMPS class instance will also be deleted automatically during the
lammps class destructor. Instead of lmp.close() it is also possible to call lmp.finalize(); this will destruct the
LAMMPS instance, but also finalized and release the MPI and/or Kokkos environment if enabled and active.
Note that you can create multiple LAMMPS objects in your Python script, and coordinate and run multiple simulations,
e.g.

490 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

from lammps import lammps

lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2")

13.3.5 Executing commands

Once an instance of the lammps, PyLammps, or IPyLammps class is created, there are multiple ways to “feed” it com-
mands. In a way that is not very different from running a LAMMPS input script, except that Python has many more
facilities for structured programming than the LAMMPS input script syntax. Furthermore it is possible to “compute”
what the next LAMMPS command should be.

lammps API
Same as in the equivalent C library functions, commands can be read from a file, a single string, a list of
strings and a block of commands in a single multi-line string. They are processed under the same boundary
conditions as the C library counterparts. The example below demonstrates the use of lammps.file(),
lammps.command(), lammps.commands_list(), and lammps.commands_string():

from lammps import lammps

lmp = lammps()

# read commands from file 'in.melt'

lmp.file('in.melt')

# issue a single command

lmp.command('variable zpos index 1.0')

# create 10 groups with 10 atoms each

cmds = ["group g{} id {}:{}".format(i,10*i+1,10*(i+1)) for i in range(10)]
lmp.commands_list(cmds)

# run commands from a multi-line string

block = """
clear
region box block 0 2 0 2 0 2
create_box 1 box
create_atoms 1 single 1.0 1.0 ${zpos}
"""
lmp.commands_string(block)

PyLammps/IPyLammps API
Unlike the lammps API, the PyLammps/IPyLammps APIs allow running LAMMPS commands by calling
equivalent member functions of PyLammps and IPyLammps instances.
For instance, the following LAMMPS command

region box block 0 10 0 5 -0.5 0.5

13.3. Run LAMMPS from Python 491

LAMMPS Documentation, Release stable 29Sep2021

can be executed using with the lammps API with the following Python code if lmp is an instance of lammps:

from lammps import lammps

lmp = lammps()
lmp.command("region box block 0 10 0 5 -0.5 0.5")

With the PyLammps interface, any LAMMPS command can be split up into arbitrary parts. These parts
are then passed to a member function with the name of the command. For the region command that means
the region() method can be called. The arguments of the command can be passed as one string, or
individually.

from lammps import PyLammps

L = PyLammps()

# pass command parameters as one string

L.region("box block 0 10 0 5 -0.5 0.5")

# OR pass them individually

L.region("box block", 0, 10, 0, 5, -0.5, 0.5)

In the latter example, all parameters except the first are Python floating-point literals. The member function
takes the entire parameter list and transparently merges it to a single command string.
The benefit of this approach is avoiding redundant command calls and easier parameterization. In the
lammps API parameterization needed to be done manually by creating formatted command strings.

lmp.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo,␣

,→zhi))

In contrast, methods of PyLammps accept parameters directly and will convert them automatically to a
final command string.

L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)

Using these facilities, the example shown for the lammps API can be rewritten as follows:

from lammps import PyLammps

L = PyLammps()

# read commands from file 'in.melt'

L.file('in.melt')

# issue a single command

L.variable('zpos', 'index', 1.0)

# create 10 groups with 10 atoms each

for i in range(10):
L.group(f"g{i}", "id", f"{10*i+1}:{10*(i+1)}")

L.clear()
L.region("box block", 0, 2, 0, 2, 0, 2)
L.create_box(1, "box")
L.create_atoms(1, "single", 1.0, 1.0, "${zpos}")

492 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

13.3.6 System properties

Similar to what is described in System properties, the instances of lammps, PyLammps, or IPyLammps can be used to
extract different kinds of information about the active LAMMPS instance and also to modify some of it. The main
difference between the interfaces is how the information is exposed.
While the lammps is just a thin layer that wraps C API calls, PyLammps and IPyLammps expose information as objects
and properties.
In some cases the data returned is a direct reference to the original data inside LAMMPS cast to ctypes pointers.
Where possible, the wrappers will determine the ctypes data type and cast pointers accordingly. If numpy is installed
arrays can also be extracted as numpy arrays, which will access the C arrays directly and have the correct dimensions
to protect against invalid accesses.

Warning: When accessing per-atom data, please note that this data is the per-processor local data and indexed
accordingly. These arrays can change sizes and order at every neighbor list rebuild and atom sort event as atoms
are migrating between sub-domains.

lammps API
from lammps import lammps

lmp = lammps()
lmp.file("in.sysinit")

natoms = lmp.get_natoms()
print(f"running simulation with {natoms} atoms")

lmp.command("run 1000 post no");

for i in range(10):
lmp.command("run 100 pre no post no")
pe = lmp.get_thermo("pe")
ke = lmp.get_thermo("ke")
print(f"PE = {pe}\nKE = {ke}")

lmp.close()

Methods:
• version(): return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
• get_thermo(): return current value of a thermo keyword
• get_natoms(): total # of atoms as int
• reset_box(): reset the simulation box size
• extract_setting(): return a global setting
• extract_global(): extract a global quantity
• extract_box(): extract box info
• create_atoms(): create N atoms with IDs, types, x, v, and image flags

13.3. Run LAMMPS from Python 493

LAMMPS Documentation, Release stable 29Sep2021

PyLammps/IPyLammps API
In addition to the functions provided by lammps, PyLammps objects have several properties which allow you to
query the system state:
L.system Is a dictionary describing the system such as the bounding box or number of atoms
L.system.xlo, L.system.xhi bounding box limits along x-axis
L.system.ylo, L.system.yhi bounding box limits along y-axis
L.system.zlo, L.system.zhi bounding box limits along z-axis
L.communication configuration of communication subsystem, such as the number of threads or processors
L.communication.nthreads number of threads used by each LAMMPS process
L.communication.nprocs number of MPI processes used by LAMMPS
L.fixes List of fixes in the current system
L.computes List of active computes in the current system
L.dump List of active dumps in the current system
L.groups List of groups present in the current system
Retrieving the value of an arbitrary LAMMPS expressions
LAMMPS expressions can be immediately evaluated by using the eval method. The passed string parameter
can be any expression containing global thermo command values, variables, compute or fix data (see Output from
LAMMPS (thermo, dumps, computes, fixes, variables)):
result = L.eval("ke") # kinetic energy
result = L.eval("pe") # potential energy

result = L.eval("v_t/2.0")

Example
from lammps import PyLammps

L = PyLammps()
L.file("in.sysinit")

print(f"running simulation with {L.system.natoms} atoms")

L.run(1000, "post no");

for i in range(10):
L.run(100, "pre no post no")
pe = L.eval("pe")
ke = L.eval("ke")
print(f"PE = {pe}\nKE = {ke}")

494 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

13.3.7 Per-atom properties

Similar to what is described in Per-atom properties, the instances of lammps, PyLammps, or IPyLammps can be used to
extract atom quantities and modify some of them. The main difference between the interfaces is how the information
is exposed.
While the lammps is just a thin layer that wraps C API calls, PyLammps and IPyLammps expose information as objects
and properties.
In some cases the data returned is a direct reference to the original data inside LAMMPS cast to ctypes pointers.
Where possible, the wrappers will determine the ctypes data type and cast pointers accordingly. If numpy is installed
arrays can also be extracted as numpy arrays, which will access the C arrays directly and have the correct dimensions
to protect against invalid accesses.

Warning: When accessing per-atom data, please note that this data is the per-processor local data and indexed
accordingly. These arrays can change sizes and order at every neighbor list rebuild and atom sort event as atoms
are migrating between sub-domains.

lammps API
from lammps import lammps

lmp = lammps()
lmp.file("in.sysinit")

nlocal = lmp.extract_global("nlocal")
x = lmp.extract_atom("x")

for i in range(nlocal):
print("(x,y,z) = (", x[i][0], x[i][1], x[i][2], ")")

lmp.close()

Methods:
• extract_atom(): extract a per-atom quantity
Numpy Methods:
• numpy.extract_atom(): extract a per-atom quantity as numpy array

PyLammps/IPyLammps API
All atoms in the current simulation can be accessed by using the PyLammps.atoms property. Each element of this
list is a Atom or Atom2D object. The attributes of these objects provide access to their data (id, type, position,
velocity, force, etc.):
# access first atom
L.atoms[0].id
L.atoms[0].type

# access second atom

L.atoms[1].position
L.atoms[1].velocity
L.atoms[1].force

13.3. Run LAMMPS from Python 495

LAMMPS Documentation, Release stable 29Sep2021

Some attributes can be changed:

# set position in 2D simulation
L.atoms[0].position = (1.0, 0.0)

# set position in 3D simulation

L.atoms[0].position = (1.0, 0.0, 1.0)

13.3.8 Compute, fixes, variables

This section documents accessing or modifying data from objects like computes, fixes, or variables in LAMMPS using
the lammps module.

lammps API
For lammps.extract_compute() and lammps.extract_fix(), the global, per-atom, or local data cal-
culated by the compute or fix can be accessed. What is returned depends on whether the compute or fix
calculates a scalar or vector or array. For a scalar, a single double value is returned. If the compute or
fix calculates a vector or array, a pointer to the internal LAMMPS data is returned, which you can use via
normal Python subscripting.
The one exception is that for a fix that calculates a global vector or array, a single double value from the
vector or array is returned, indexed by I (vector) or I and J (array). I,J are zero-based indices. See the
Howto output page for a discussion of global, per-atom, and local data, and of scalar, vector, and array
data types. See the doc pages for individual computes and fixes for a description of what they calculate
and store.
For lammps.extract_variable(), an equal-style or atom-style variable is evaluated and its result re-
turned.
For equal-style variables a single c_double value is returned and the group argument is ignored. For
atom-style variables, a vector of c_double is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the specified group.
lammps.numpy.extract_compute(), lammps.numpy.extract_fix(), and lammps.numpy.
extract_variable() are equivalent NumPy implementations that return NumPy arrays instead of
ctypes pointers.
The lammps.set_variable() method sets an existing string-style variable to a new string value, so that
subsequent LAMMPS commands can access the variable.
Methods:
• lammps.extract_compute(): extract value(s) from a compute
• lammps.extract_fix(): extract value(s) from a fix
• lammps.extract_variable(): extract value(s) from a variable
• lammps.set_variable(): set existing named string-style variable to value
NumPy Methods:
• lammps.numpy.extract_compute(): extract value(s) from a compute, return arrays as numpy
arrays
• lammps.numpy.extract_fix(): extract value(s) from a fix, return arrays as numpy arrays

496 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• lammps.numpy.extract_variable(): extract value(s) from a variable, return arrays as numpy

arrays

PyLammps/IPyLammps API
PyLammps and IPyLammps classes currently do not add any additional ways of retrieving information out
of computes and fixes. This information can still be accessed by using the lammps API:

L.lmp.extract_compute(...)
L.lmp.extract_fix(...)
# OR
L.lmp.numpy.extract_compute(...)
L.lmp.numpy.extract_fix(...)

LAMMPS variables can be both defined and accessed via the PyLammps interface.
To define a variable you can use the variable command:

L.variable("a index 2")

A dictionary of all variables is returned by the PyLammps.variables property:

you can access an individual variable by retrieving a variable object from the L.variables dictionary by
name

a = L.variables['a']

The variable value can then be easily read and written by accessing the value property of this object.

print(a.value)
a.value = 4

13.3.9 Scatter/gather operations

data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms␣

,→gathered into data, ordered by atom ID

# name = "x", "charge", "type", etc

data = lmp.gather_atoms_concat(name,type,count) # ditto, but concatenated atom values␣
,→from each proc (unordered)

data = lmp.gather_atoms_subset(name,type,count,ndata,ids) # ditto, but for subset of␣

,→Ndata atoms with IDs

lmp.scatter_atoms(name,type,count,data) # scatter per-atom property to all atoms from␣

,→data, ordered by atom ID

# name = "x", "charge", "type", etc

# count = # of per-atom values, 1 or 3, etc

lmp.scatter_atoms_subset(name,type,count,ndata,ids,data) # ditto, but for subset of␣

,→Ndata atoms with IDs

The gather methods collect peratom info of the requested type (atom coords, atom types, forces, etc) from all processors,
and returns the same vector of values to each calling processor. The scatter functions do the inverse. They distribute

13.3. Run LAMMPS from Python 497

LAMMPS Documentation, Release stable 29Sep2021

a vector of peratom values, passed by all calling processors, to individual atoms, which may be owned by different
processors.
Note that the data returned by the gather methods, e.g. gather_atoms(“x”), is different from the data structure returned
by extract_atom(“x”) in four ways. (1) Gather_atoms() returns a vector which you index as x[i]; extract_atom() returns
an array which you index as x[i][j]. (2) Gather_atoms() orders the atoms by atom ID while extract_atom() does not. (3)
Gather_atoms() returns a list of all atoms in the simulation; extract_atoms() returns just the atoms local to each proces-
sor. (4) Finally, the gather_atoms() data structure is a copy of the atom coords stored internally in LAMMPS, whereas
extract_atom() returns an array that effectively points directly to the internal data. This means you can change values
inside LAMMPS from Python by assigning a new values to the extract_atom() array. To do this with the gather_atoms()
vector, you need to change values in the vector, then invoke the scatter_atoms() method.
For the scatter methods, the array of coordinates passed to must be a ctypes vector of ints or doubles, allocated and
initialized something like this:
from ctypes import c_double
natoms = lmp.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
x[0] = x coord of atom with ID 1
x[1] = y coord of atom with ID 1
x[2] = z coord of atom with ID 1
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
lmp.scatter_atoms("x",1,3,x)

Alternatively, you can just change values in the vector returned by the gather methods, since they are also ctypes vectors.

13.3.10 Neighbor list access

Access to neighbor lists is handled through a couple of wrapper classes that allows to treat it like either a python list
or a NumPy array. The access procedure is similar to that of the C-library interface: use one of the “find” functions to
look up the index of the neighbor list in the global table of neighbor lists and then get access to the neighbor list data.
The code sample below demonstrates reading the neighbor list data using the NumPy access method.
from lammps import lammps
import numpy as np

lmp = lammps()
lmp.commands_string("""
region box block -2 2 -2 2 -2 2
lattice fcc 1.0
create_box 1 box
create_atoms 1 box
mass 1 1.0
pair_style lj/cut 2.5
pair_coeff 1 1 1.0 1.0
run 0 post no""")

# look up the neighbor list

nlidx = lmp.find_pair_neighlist('lj/cut')
nl = lmp.numpy.get_neighlist(nlidx)
tags = lmp.extract_atom('id')
(continues on next page)

498 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

print("half neighbor list with {} entries".format(nl.size))
# print neighbor list contents
for i in range(0,nl.size):
idx, nlist = nl.get(i)
print("\natom {} with ID {} has {} neighbors:".format(idx,tags[idx],nlist.size))
if nlist.size > 0:
for n in np.nditer(nlist):
print(" atom {} with ID {}".format(n,tags[n]))

Methods:
• lammps.get_neighlist(): Get neighbor list for given index
• lammps.get_neighlist_size(): Get number of elements in neighbor list
• lammps.get_neighlist_element_neighbors(): Get element in neighbor list and its neighbors
• lammps.find_pair_neighlist(): Find neighbor list of pair style
• lammps.find_fix_neighlist(): Find neighbor list of pair style
• lammps.find_compute_neighlist(): Find neighbor list of pair style
NumPy Methods:
• lammps.numpy.get_neighlist(): Get neighbor list for given index, which uses NumPy arrays for its element
neighbor arrays
• lammps.numpy.get_neighlist_element_neighbors(): Get element in neighbor list and its neighbors (as
numpy array)

13.3.11 Configuration information

The following methods can be used to query the LAMMPS library about compile time settings and included packages
and styles.

Listing 1: Example for using configuration settings functions

from lammps import lammps

lmp = lammps()

try:
lmp.file("in.missing")
except Exception as e:
print("LAMMPS failed with error:", e)

# write compressed dump file depending on available of options

if lmp.has_style("dump", "atom/zstd"):
lmp.command("dump d1 all atom/zstd 100 dump.zst")
elif lmp.has_style("dump", "atom/gz"):
lmp.command("dump d1 all atom/gz 100 dump.gz")
elif lmp.has_gzip_support():
lmp.command("dump d1 all atom 100 dump.gz")
(continues on next page)

13.3. Run LAMMPS from Python 499

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

else:
lmp.command("dump d1 all atom 100 dump")

Methods:
• lammps.has_mpi_support
• lammps.has_exceptions
• lammps.has_gzip_support
• lammps.has_png_support
• lammps.has_jpeg_support
• lammps.has_ffmpeg_support
• lammps.installed_packages
• lammps.get_accelerator_config
• lammps.has_style()
• lammps.available_styles()

13.4 The lammps Python module

The LAMMPS Python interface is implemented as a module called lammps which is defined in the lammps package
in the python folder of the LAMMPS source code distribution. After compilation of LAMMPS, the module can be
installed into a Python system folder or a user folder with make install-python. Components of the module can
then loaded into a Python session with the import command.
There are multiple Python interface classes in the lammps module:
• the lammps class. This is a wrapper around the C-library interface and its member functions try to replicate the
C-library API closely. This is the most feature-complete Python API.
• the PyLammps class. This is a more high-level and more Python style class implemented on top of the lammps
class.
• the IPyLammps class is derived from PyLammps and adds embedded graphics features to conveniently include
LAMMPS into Jupyter notebooks.

Version check
The lammps module stores the version number of the LAMMPS version it is installed from. When initializing the
lammps class, this version is checked to be the same as the result from lammps.version(), the version of the
LAMMPS shared library that the module interfaces to. If the they are not the same an AttributeError exception is
raised since a mismatch of versions (e.g. due to incorrect use of the LD_LIBRARY_PATH or PYTHONPATH environment
variables can lead to crashes or data corruption and otherwise incorrect behavior.

LAMMPS module global members:

lammps.__version__
Numerical representation of the LAMMPS version this module was taken from. Has the same format as the
result of lammps.version().

500 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

13.4.1 The lammps class API

The lammps class is the core of the LAMMPS Python interfaces. It is a wrapper around the LAMMPS C library
API using the Python ctypes module and a shared library compiled from the LAMMPS sources code. The individual
methods in this class try to closely follow the corresponding C functions. The handle argument that needs to be passed
to the C functions is stored internally in the class and automatically added when calling the C library functions. Below
is a detailed documentation of the API.
class lammps.lammps(name='', cmdargs=None, ptr=None, comm=None)
Create an instance of the LAMMPS Python class.
This is a Python wrapper class that exposes the LAMMPS C-library interface to Python. It either requires that
LAMMPS has been compiled as shared library which is then dynamically loaded via the ctypes Python module
or that this module called from a Python function that is called from a Python interpreter embedded into a
LAMMPS executable, for example through the python invoke command. When the class is instantiated it calls
the lammps_open() function of the LAMMPS C-library interface, which in turn will create an instance of the
LAMMPS C++ class. The handle to this C++ class is stored internally and automatically passed to the calls to the
C library interface.
Parameters
• name (string) – “machine” name of the shared LAMMPS library (“mpi” loads
liblammps_mpi.so, “” loads liblammps.so)
• cmdargs (list) – list of command line arguments to be passed to the lammps_open()
function. The executable name is automatically added.
• ptr (pointer) – pointer to a LAMMPS C++ class instance when called from an embedded
Python interpreter. None means load symbols from shared library.
• comm (MPI_Comm) – MPI communicator (as provided by mpi4py). None means use
MPI_COMM_WORLD implicitly.
property numpy
Return object to access numpy versions of API
It provides alternative implementations of API functions that return numpy arrays instead of ctypes pointers.
If numpy is not installed, accessing this property will lead to an ImportError.
Returns instance of numpy wrapper object
Return type numpy_wrapper
close()
Explicitly delete a LAMMPS instance through the C-library interface.
This is a wrapper around the lammps_close() function of the C-library interface.
finalize()
Shut down the MPI communication and Kokkos environment (if active) through the library interface by
calling lammps_mpi_finalize() and lammps_kokkos_finalize().
You cannot create or use any LAMMPS instances after this function is called unless LAMMPS was com-
piled without MPI and without Kokkos support.
version()
Return a numerical representation of the LAMMPS version in use.
This is a wrapper around the lammps_version() function of the C-library interface.
Returns version number
Return type int

13.4. The lammps Python module 501

LAMMPS Documentation, Release stable 29Sep2021

get_os_info()
Return a string with information about the OS and compiler runtime
This is a wrapper around the lammps_get_os_info() function of the C-library interface.
Returns OS info string
Return type string
get_mpi_comm()
Get the MPI communicator in use by the current LAMMPS instance
This is a wrapper around the lammps_get_mpi_comm() function of the C-library interface. It will return
None if either the LAMMPS library was compiled without MPI support or the mpi4py Python module is
not available.
Returns MPI communicator
Return type MPI_Comm
file(path)
Read LAMMPS commands from a file.
This is a wrapper around the lammps_file() function of the C-library interface. It will open the file with
the name/path file and process the LAMMPS commands line by line until the end. The function will return
when the end of the file is reached.
Parameters path (string) – Name of the file/path with LAMMPS commands
command(cmd)
Process a single LAMMPS input command from a string.
This is a wrapper around the lammps_command() function of the C-library interface.
Parameters cmd (string) – a single lammps command
commands_list(cmdlist)
Process multiple LAMMPS input commands from a list of strings.
This is a wrapper around the lammps_commands_list() function of the C-library interface.
Parameters cmdlist (list of strings) – a single lammps command
commands_string(multicmd)
Process a block of LAMMPS input commands from a string.
This is a wrapper around the lammps_commands_string() function of the C-library interface.
Parameters multicmd (string) – text block of lammps commands
get_natoms()
Get the total number of atoms in the LAMMPS instance.
Will be precise up to 53-bit signed integer due to the underlying lammps_get_natoms() function returning
a double.
Returns number of atoms
Return type int
extract_box()
Extract simulation box parameters
This is a wrapper around the lammps_extract_box() function of the C-library interface. Unlike in the
C function, the result is returned as a list.
Returns list of the extracted data: boxlo, boxhi, xy, yz, xz, periodicity, box_change

502 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Return type [ 3*double, 3*double, double, double, 3*int, int]

reset_box(boxlo, boxhi, xy, yz, xz)
Reset simulation box parameters
This is a wrapper around the lammps_reset_box() function of the C-library interface.
Parameters
• boxlo (list of 3 floating point numbers) – new lower box boundaries
• boxhi (list of 3 floating point numbers) – new upper box boundaries
• xy (float) – xy tilt factor
• yz (float) – yz tilt factor
• xz (float) – xz tilt factor
get_thermo(name)
Get current value of a thermo keyword
This is a wrapper around the lammps_get_thermo() function of the C-library interface.
Parameters name (string) – name of thermo keyword
Returns value of thermo keyword
Return type double or None
extract_setting(name)
Query LAMMPS about global settings that can be expressed as an integer.
This is a wrapper around the lammps_extract_setting() function of the C-library interface. Its docu-
mentation includes a list of the supported keywords.
Parameters name (string) – name of the setting
Returns value of the setting
Return type int
extract_global_datatype(name)
Retrieve global property datatype from LAMMPS
This is a wrapper around the lammps_extract_global_datatype() function of the C-library interface.
Its documentation includes a list of the supported keywords. This function returns None if the keyword is
not recognized. Otherwise it will return a positive integer value that corresponds to one of the data type
constants define in the lammps module.
Parameters name (string) – name of the property
Returns data type of global property, see Data Types
Return type int
extract_global(name, dtype=None)
Query LAMMPS about global settings of different types.
This is a wrapper around the lammps_extract_global() function of the C-library interface. Since there
are no pointers in Python, this method will - unlike the C function - return the value or a list of values.
The lammps_extract_global() documentation includes a list of the supported keywords and their data
types. Since Python needs to know the data type to be able to interpret the result, by default, this function
will try to auto-detect the data type by asking the library. You can also force a specific data type. For that
purpose the lammps module contains data type constants. This function returns None if either the keyword
is not recognized, or an invalid data type constant is used.

13.4. The lammps Python module 503

LAMMPS Documentation, Release stable 29Sep2021

Parameters
• name (string) – name of the property
• dtype (int, optional) – data type of the returned data (see Data Types)
Returns value of the property or list of values or None
Return type int, float, list, or NoneType
extract_atom_datatype(name)
Retrieve per-atom property datatype from LAMMPS
This is a wrapper around the lammps_extract_atom_datatype() function of the C-library interface.
Its documentation includes a list of the supported keywords. This function returns None if the keyword is
not recognized. Otherwise it will return an integer value that corresponds to one of the data type constants
defined in the lammps module.
Parameters name (string) – name of the property
Returns data type of per-atom property (see Data Types)
Return type int
extract_atom(name, dtype=None)
Retrieve per-atom properties from LAMMPS
This is a wrapper around the lammps_extract_atom() function of the C-library interface. Its documen-
tation includes a list of the supported keywords and their data types. Since Python needs to know the data
type to be able to interpret the result, by default, this function will try to auto-detect the data type by asking
the library. You can also force a specific data type by setting dtype to one of the data type constants defined
in the lammps module. This function returns None if either the keyword is not recognized, or an invalid
data type constant is used.

Note: While the returned arrays of per-atom data are dimensioned for the range [0:nmax] - as is the
underlying storage - the data is usually only valid for the range of [0:nlocal], unless the property of interest
is also updated for ghost atoms. In some cases, this depends on a LAMMPS setting, see for example
comm_modify vel yes.

Parameters
• name (string) – name of the property
• dtype (int, optional) – data type of the returned data (see Data Types)
Returns requested data or None
Return type ctypes.POINTER(ctypes.c_int32), ctypes.POINTER(ctypes.POINTER(ctypes.c_int32)),
ctypes.POINTER(ctypes.c_int64), ctypes.POINTER(ctypes.POINTER(ctypes.c_int64)),
ctypes.POINTER(ctypes.c_double), ctypes.POINTER(ctypes.POINTER(ctypes.c_double)),
or NoneType

extract_compute(cid, cstyle, ctype)

Retrieve data from a LAMMPS compute
This is a wrapper around the lammps_extract_compute() function of the C-library interface. This func-
tion returns None if either the compute id is not recognized, or an invalid combination of cstyle and ctype
constants is used. The names and functionality of the constants are the same as for the corresponding
C-library function. For requests to return a scalar or a size, the value is returned, otherwise a pointer.
Parameters

504 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• cid (string) – compute ID

• cstyle (int) – style of the data retrieve (global, atom, or local), see Style Constants
• ctype (int) – type or size of the returned data (scalar, vector, or array), see Type Constants
Returns requested data as scalar, pointer to 1d or 2d double array, or None
Return type c_double, ctypes.POINTER(c_double), ctypes.POINTER(ctypes.POINTER(c_double)),
or NoneType
extract_fix(fid, fstyle, ftype, nrow=0, ncol=0)
Retrieve data from a LAMMPS fix
This is a wrapper around the lammps_extract_fix() function of the C-library interface. This function
returns None if either the fix id is not recognized, or an invalid combination of fstyle and ftype constants is
used. The names and functionality of the constants are the same as for the corresponding C-library function.
For requests to return a scalar or a size, the value is returned, also when accessing global vectors or arrays,
otherwise a pointer.
Parameters
• fid (string) – fix ID
• fstyle (int) – style of the data retrieve (global, atom, or local), see Style Constants
• ftype (int) – type or size of the returned data (scalar, vector, or array), see Type Constants
• nrow (int) – index of global vector element or row index of global array element
• ncol (int) – column index of global array element
Returns requested data or None
Return type c_double, ctypes.POINTER(c_double), ctypes.POINTER(ctypes.POINTER(c_double)),
or NoneType
extract_variable(name, group=None, vartype=0)
Evaluate a LAMMPS variable and return its data
This function is a wrapper around the function lammps_extract_variable() of the C-library interface,
evaluates variable name and returns a copy of the computed data. The memory temporarily allocated by
the C-interface is deleted after the data is copied to a Python variable or list. The variable must be either an
equal-style (or equivalent) variable or an atom-style variable. The variable type has to provided as vartype
parameter which may be one of two constants: LMP_VAR_EQUAL or LMP_VAR_ATOM; it defaults to equal-
style variables. The group parameter is only used for atom-style variables and defaults to the group “all” if
set to None, which is the default.
Parameters
• name (string) – name of the variable to execute
• group (string, only for atom-style variables) – name of group for atom-style
variable
• vartype (int) – type of variable, see Variable Type Constants
Returns the requested data
Return type c_double, (c_double), or NoneType
set_variable(name, value)
Set a new value for a LAMMPS string style variable
This is a wrapper around the lammps_set_variable() function of the C-library interface.

13.4. The lammps Python module 505

LAMMPS Documentation, Release stable 29Sep2021

Parameters
• name (string) – name of the variable
• value (any. will be converted to a string) – new variable value
Returns either 0 on success or -1 on failure
Return type int
gather_bonds()
Retrieve global list of bonds
This is a wrapper around the lammps_gather_bonds() function of the C-library interface.
This function returns a tuple with the number of bonds and a flat list of ctypes integer values with the bond
type, bond atom1, bond atom2 for each bond.
New in version 28Jul2021.
Returns a tuple with the number of bonds and a list of c_int or c_long
Return type (int, 3*nbonds*c_tagint)
encode_image_flags(ix, iy, iz)
convert 3 integers with image flags for x-, y-, and z-direction into a single integer like it is used internally
in LAMMPS
This method is a wrapper around the lammps_encode_image_flags() function of library interface.
Parameters
• ix (int) – x-direction image flag
• iy (int) – y-direction image flag
• iz (int) – z-direction image flag
Returns encoded image flags
Return type lammps.c_imageint
decode_image_flags(image)
Convert encoded image flag integer into list of three regular integers.
This method is a wrapper around the lammps_decode_image_flags() function of library interface.
Parameters image (lammps.c_imageint) – encoded image flags
Returns list of three image flags in x-, y-, and z- direction
Return type list of 3 int
create_atoms(n, id, type, x, v=None, image=None, shrinkexceed=False)
Create N atoms from list of coordinates and properties
This function is a wrapper around the lammps_create_atoms() function of the C-library interface, and
the behavior is similar except that the v, image, and shrinkexceed arguments are optional and default to
None, None, and False, respectively. With none being equivalent to a NULL pointer in C.
The lists of coordinates, types, atom IDs, velocities, image flags can be provided in any format that may
be converted into the required internal data types. Also the list may contain more than N entries, but not
fewer. In the latter case, the function will return without attempting to create atoms. You may use the
encode_image_flags method to properly combine three integers with image flags into a single integer.
Parameters
• n (int) – number of atoms for which data is provided

506 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• id (list of lammps.tagint) – list of atom IDs with at least n elements or None

• type (list of int) – list of atom types
• x (list of float) – list of coordinates for x-, y-, and z (flat list of 3n entries)
• v (list of float) – list of velocities for x-, y-, and z (flat list of 3n entries) or None
(optional)
• image (list of lammps.imageint) – list of encoded image flags (optional)
• shrinkexceed (bool) – whether to expand shrink-wrap boundaries if atoms are outside
the box (optional)
Returns number of atoms created. 0 if insufficient or invalid data
Return type int
property has_mpi_support
Report whether the LAMMPS shared library was compiled with a real MPI library or in serial.
This is a wrapper around the lammps_config_has_mpi_support() function of the library interface.
Returns False when compiled with MPI STUBS, otherwise True
Return type bool
property is_running
Report whether being called from a function during a run or a minimization
Various LAMMPS commands must not be called during an ongoing run or minimization. This property
allows to check for that. This is a wrapper around the lammps_is_running() function of the library
interface.
New in version 9Oct2020.
Returns True when called during a run otherwise false
Return type bool
force_timeout()
Trigger an immediate timeout, i.e. a “soft stop” of a run.
This function allows to cleanly stop an ongoing run or minimization at the next loop iteration. This is a
wrapper around the lammps_force_timeout() function of the library interface.
New in version 9Oct2020.
property has_exceptions
Report whether the LAMMPS shared library was compiled with C++ exceptions handling enabled
This is a wrapper around the lammps_config_has_exceptions() function of the library interface.
Returns state of C++ exception support
Return type bool
property has_gzip_support
Report whether the LAMMPS shared library was compiled with support for reading and writing com-
pressed files through gzip.
This is a wrapper around the lammps_config_has_gzip_support() function of the library interface.
Returns state of gzip support
Return type bool

13.4. The lammps Python module 507

LAMMPS Documentation, Release stable 29Sep2021

property has_png_support
Report whether the LAMMPS shared library was compiled with support for writing images in PNG format.
This is a wrapper around the lammps_config_has_png_support() function of the library interface.
Returns state of PNG support
Return type bool
property has_jpeg_support
Report whether the LAMMPS shared library was compiled with support for writing images in JPEG format.
This is a wrapper around the lammps_config_has_jpeg_support() function of the library interface.
Returns state of JPEG support
Return type bool
property has_ffmpeg_support
State of support for writing movies with ffmpeg in the LAMMPS shared library
This is a wrapper around the lammps_config_has_ffmpeg_support() function of the library interface.
Returns state of ffmpeg support
Return type bool
property accelerator_config
Return table with available accelerator configuration settings.
This is a wrapper around the lammps_config_accelerator() function of the library interface which
loops over all known packages and categories and returns enabled features as a nested dictionary with all
enabled settings as list of strings.
Returns nested dictionary with all known enabled settings as list of strings
Return type dictionary
property has_gpu_device
Availability of GPU package compatible device
This is a wrapper around the lammps_has_gpu_device() function of the C library interface.
Returns True if a GPU package compatible device is present, otherwise False
Return type bool
get_gpu_device_info()
Return a string with detailed information about any devices that are usable by the GPU package.
This is a wrapper around the lammps_get_gpu_device_info() function of the C-library interface.
Returns GPU device info string
Return type string
property installed_packages
List of the names of enabled packages in the LAMMPS shared library
This is a wrapper around the functions lammps_config_package_count() and
:cpp:func`lammps_config_package_name` of the library interface.
:return
has_style(category, name)
Returns whether a given style name is available in a given category
This is a wrapper around the function lammps_has_style() of the library interface.

508 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Parameters
• category (string) – name of category
• name (string) – name of the style
Returns true if style is available in given category
Return type bool
available_styles(category)
Returns a list of styles available for a given category
This is a wrapper around the functions lammps_style_count() and lammps_style_name() of the li-
brary interface.
Parameters category (string) – name of category
Returns list of style names in given category
Return type list
has_id(category, name)
Returns whether a given ID name is available in a given category
This is a wrapper around the function lammps_has_id() of the library interface.
New in version 9Oct2020.
Parameters
• category (string) – name of category
• name (string) – name of the ID
Returns true if ID is available in given category
Return type bool
available_ids(category)
Returns a list of IDs available for a given category
This is a wrapper around the functions lammps_id_count() and lammps_id_name() of the library in-
terface.
New in version 9Oct2020.
Parameters category (string) – name of category
Returns list of id names in given category
Return type list
available_plugins(category)
Returns a list of plugins available for a given category
This is a wrapper around the functions lammps_plugin_count() and lammps_plugin_name() of the
library interface.
New in version 10Mar2021.
Returns list of style/name pairs of loaded plugins
Return type list
set_fix_external_callback(fix_id, callback, caller=None)
Set the callback function for a fix external instance with a given fix ID.
Optionally also set a reference to the calling object.

13.4. The lammps Python module 509

LAMMPS Documentation, Release stable 29Sep2021

This is a wrapper around the lammps_set_fix_external_callback() function of the C-library inter-

face. However this is set up to call a Python function with the following arguments.
• object is the value of the “caller” argument
• ntimestep is the current timestep
• nlocal is the number of local atoms on the current MPI process
• tag is a 1d NumPy array of integers representing the atom IDs of the local atoms
• x is a 2d NumPy array of doubles of the coordinates of the local atoms
• f is a 2d NumPy array of doubles of the forces on the local atoms that will be added
Changed in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• callback – Python function that will be called from fix external
• caller – reference to some object passed to the callback function
Type string
Type function
Type object, optional
fix_external_get_force(fix_id)
Get access to the array with per-atom forces of a fix external instance with a given fix ID.
This is a wrapper around the lammps_fix_external_get_force() function of the C-library interface.
New in version 28Jul2021.
Parameters fix_id – Fix-ID of a fix external instance
Type string
Returns requested data
Return type ctypes.POINTER(ctypes.POINTER(ctypes.double))
fix_external_set_energy_global(fix_id, eng)
Set the global energy contribution for a fix external instance with the given ID.
This is a wrapper around the lammps_fix_external_set_energy_global() function of the C-library
interface.
New in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• eng – potential energy value to be added by fix external
Type string
Type float
fix_external_set_virial_global(fix_id, virial)
Set the global virial contribution for a fix external instance with the given ID.
This is a wrapper around the lammps_fix_external_set_virial_global() function of the C-library
interface.

510 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

New in version 28Jul2021.

Parameters
• fix_id – Fix-ID of a fix external instance
• eng – list of 6 floating point numbers with the virial to be added by fix external
Type string
Type float
fix_external_set_energy_peratom(fix_id, eatom)
Set the per-atom energy contribution for a fix external instance with the given ID.
This is a wrapper around the lammps_fix_external_set_energy_peratom() function of the C-library
interface.
New in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• eatom – list of potential energy values for local atoms to be added by fix external
Type string
Type float
fix_external_set_virial_peratom(fix_id, vatom)
Set the per-atom virial contribution for a fix external instance with the given ID.
This is a wrapper around the lammps_fix_external_set_virial_peratom() function of the C-library
interface.
New in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• vatom – list of natoms lists with 6 floating point numbers to be added by fix external
Type string
Type float
fix_external_set_vector_length(fix_id, length)
Set the vector length for a global vector stored with fix external for analysis
This is a wrapper around the lammps_fix_external_set_vector_length() function of the C-library
interface.
New in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• length – length of the global vector
Type string
Type int

13.4. The lammps Python module 511

LAMMPS Documentation, Release stable 29Sep2021

fix_external_set_vector(fix_id, idx, val)

Store a global vector value for a fix external instance with the given ID.
This is a wrapper around the lammps_fix_external_set_vector() function of the C-library interface.
New in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• idx – 1-based index of the value in the global vector
• val – value to be stored in the global vector
Type string
Type int
Type float
get_neighlist(idx)
Returns an instance of NeighList which wraps access to the neighbor list with the given index
See lammps.numpy.get_neighlist() if you want to use NumPy arrays instead of c_int pointers.
Parameters idx (int) – index of neighbor list
Returns an instance of NeighList wrapping access to neighbor list data
Return type NeighList
get_neighlist_size(idx)
Return the number of elements in neighbor list with the given index
Parameters idx (int) – neighbor list index
Returns number of elements in neighbor list with index idx
Return type int
get_neighlist_element_neighbors(idx, element)
Return data of neighbor list entry
Parameters
• element (int) – neighbor list index
• element – neighbor list element index
Returns tuple with atom local index, number of neighbors and array of neighbor local atom
indices
Return type (int, int, POINTER(c_int))
find_pair_neighlist(style, exact=True, nsub=0, reqid=0)
Find neighbor list index of pair style neighbor list
Search for a neighbor list requested by a pair style instance that matches “style”. If exact is True, the pair
style name must match exactly. If exact is False, the pair style name is matched against “style” as regular
expression or sub-string. If the pair style is a hybrid pair style, the style is instead matched against the
hybrid sub-styles. If the same pair style is used as sub-style multiple types, you must set nsub to a value n
> 0 which indicates the nth instance of that sub-style to be used (same as for the pair_coeff command). The
default value of 0 will fail to match in that case.
Once the pair style instance has been identified, it may have requested multiple neighbor lists. Those are
uniquely identified by a request ID > 0 as set by the pair style. Otherwise the request ID is 0.

512 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Parameters
• style (string) – name of pair style that should be searched for
• exact (bool, optional) – controls whether style should match exactly or only must be
contained in pair style name, defaults to True
• nsub (int, optional) – match nsub-th hybrid sub-style, defaults to 0
• reqid (int, optional) – list request id, > 0 in case there are more than one, defaults to
0
Returns neighbor list index if found, otherwise -1
Return type int
find_fix_neighlist(fixid, reqid=0)
Find neighbor list index of fix neighbor list
The fix instance requesting the neighbor list is uniquely identified by the fix ID. In case the fix has requested
multiple neighbor lists, those are uniquely identified by a request ID > 0 as set by the fix. Otherwise the
request ID is 0 (the default).
Parameters
• fixid (string) – name of fix
• reqid (int, optional) – id of neighbor list request, in case there are more than one
request, defaults to 0
Returns neighbor list index if found, otherwise -1
Return type int
find_compute_neighlist(computeid, reqid=0)
Find neighbor list index of compute neighbor list
The compute instance requesting the neighbor list is uniquely identified by the compute ID. In case the
compute has requested multiple neighbor lists, those are uniquely identified by a request ID > 0 as set by
the compute. Otherwise the request ID is 0 (the default).
Parameters
• computeid (string) – name of compute
• reqid (int, optional) – index of neighbor list request, in case there are more than one
request, defaults to 0
Returns neighbor list index if found, otherwise -1
Return type int
class lammps.numpy_wrapper.numpy_wrapper(lmp)
lammps API NumPy Wrapper
This is a wrapper class that provides additional methods on top of an existing lammps instance. The methods
transform raw ctypes pointers into NumPy arrays, which give direct access to the original data while protecting
against out-of-bounds accesses.
There is no need to explicitly instantiate this class. Each instance of lammps has a numpy property that returns
an instance.
Parameters lmp (lammps) – instance of the lammps class
extract_atom(name, dtype=None, nelem=None, dim=None)
Retrieve per-atom properties from LAMMPS as NumPy arrays

13.4. The lammps Python module 513

LAMMPS Documentation, Release stable 29Sep2021

This is a wrapper around the lammps.extract_atom() method. It behaves the same as the original
method, but returns NumPy arrays instead of ctypes pointers.

Note: While the returned arrays of per-atom data are dimensioned for the range [0:nmax] - as is the
underlying storage - the data is usually only valid for the range of [0:nlocal], unless the property of interest
is also updated for ghost atoms. In some cases, this depends on a LAMMPS setting, see for example
comm_modify vel yes.

Parameters
• name (string) – name of the property
• dtype (int, optional) – type of the returned data (see Data Types)
• nelem (int, optional) – number of elements in array
• dim (int, optional) – dimension of each element
Returns requested data as NumPy array with direct access to C data or None
Return type numpy.array or NoneType

extract_compute(cid, cstyle, ctype)

Retrieve data from a LAMMPS compute
This is a wrapper around the lammps.extract_compute() method. It behaves the same as the original
method, but returns NumPy arrays instead of ctypes pointers.
Parameters
• cid (string) – compute ID
• cstyle (int) – style of the data retrieve (global, atom, or local), see Style Constants
• ctype (int) – type of the returned data (scalar, vector, or array), see Type Constants
Returns requested data either as float, as NumPy array with direct access to C data, or None
Return type float, numpy.array, or NoneType
extract_fix(fid, fstyle, ftype, nrow=0, ncol=0)
Retrieve data from a LAMMPS fix
This is a wrapper around the lammps.extract_fix() method. It behaves the same as the original method,
but returns NumPy arrays instead of ctypes pointers.
Parameters
• fid (string) – fix ID
• fstyle (int) – style of the data retrieve (global, atom, or local), see Style Constants
• ftype (int) – type or size of the returned data (scalar, vector, or array), see Type Constants
• nrow (int) – index of global vector element or row index of global array element
• ncol (int) – column index of global array element
Returns requested data
Return type integer or double value, pointer to 1d or 2d double array or None

514 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

extract_variable(name, group=None, vartype=0)

Evaluate a LAMMPS variable and return its data
This function is a wrapper around the function lammps.extract_variable() method. It behaves the
same as the original method, but returns NumPy arrays instead of ctypes pointers.
Parameters
• name (string) – name of the variable to execute
• group (string) – name of group for atom-style variable (ignored for equal-style variables)
• vartype (int) – type of variable, see Variable Type Constants
Returns the requested data or None
Return type c_double, numpy.array, or NoneType
gather_bonds()
Retrieve global list of bonds as NumPy array
This is a wrapper around lammps.gather_bonds() It behaves the same as the original method, but returns
a NumPy array instead of a ctypes list.
New in version 28Jul2021.
Returns the requested data as a 2d-integer numpy array
Return type numpy.array(nbonds,3)
fix_external_get_force(fix_id)
Get access to the array with per-atom forces of a fix external instance with a given fix ID.
This function is a wrapper around the lammps.fix_external_get_force() method. It behaves the
same as the original method, but returns a NumPy array instead of a ctypes pointer.
Changed in version 28Jul2021.
Parameters fix_id – Fix-ID of a fix external instance
Type string
Returns requested data
Return type numpy.array
fix_external_set_energy_peratom(fix_id, eatom)
Set the per-atom energy contribution for a fix external instance with the given ID.
This function is an alternative to lammps.fix_external_set_energy_peratom() method. It behaves
the same as the original method, but accepts a NumPy array instead of a list as argument.
New in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• eatom – per-atom potential energy
Type string
Type numpy.array
fix_external_set_virial_peratom(fix_id, vatom)
Set the per-atom virial contribution for a fix external instance with the given ID.

13.4. The lammps Python module 515

LAMMPS Documentation, Release stable 29Sep2021

This function is an alternative to lammps.fix_external_set_virial_peratom() method. It behaves

the same as the original method, but accepts a NumPy array instead of a list as argument.
New in version 28Jul2021.
Parameters
• fix_id – Fix-ID of a fix external instance
• eatom – per-atom potential energy
Type string
Type numpy.array
get_neighlist(idx)
Returns an instance of NumPyNeighList which wraps access to the neighbor list with the given index
Parameters idx (int) – index of neighbor list
Returns an instance of NumPyNeighList wrapping access to neighbor list data
Return type NumPyNeighList
get_neighlist_element_neighbors(idx, element)
Return data of neighbor list entry
This function is a wrapper around the function lammps.get_neighlist_element_neighbors()
method. It behaves the same as the original method, but returns a NumPy array containing the neighbors
instead of a ctypes pointer.
Parameters
• element (int) – neighbor list index
• element – neighbor list element index
Returns tuple with atom local index and numpy array of neighbor local atom indices
Return type (int, numpy.array)

13.4.2 The PyLammps class API

The PyLammps class is a wrapper that creates a simpler, more “Pythonic” interface to common LAMMPS functionality.
LAMMPS data structures are exposed through objects and properties. This makes Python scripts shorter and more
concise. See the PyLammps Tutorial for an introduction on how to use this interface.
class lammps.PyLammps(name='', cmdargs=None, ptr=None, comm=None)
This is a Python wrapper class around the lower-level lammps class, exposing a more Python-like, object-oriented
interface for prototyping system inside of IPython and Jupyter notebooks.
It either creates its own instance of lammps or can be initialized with an existing instance. The arguments are
the same of the lower-level interface. The original interface can still be accessed via PyLammps.lmp.
Parameters
• name (string) – “machine” name of the shared LAMMPS library (“mpi” loads
liblammps_mpi.so, “” loads liblammps.so)
• cmdargs (list) – list of command line arguments to be passed to the lammps_open()
function. The executable name is automatically added.

516 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• ptr (pointer) – pointer to a LAMMPS C++ class instance when called from an embedded
Python interpreter. None means load symbols from shared library.
• comm (MPI_Comm) – MPI communicator (as provided by mpi4py). None means use
MPI_COMM_WORLD implicitly.
Variables
• lmp (lammps) – instance of original LAMMPS Python interface
• runs – list of completed runs, each storing the thermo output
close()
Explicitly delete a LAMMPS instance
This is a wrapper around the lammps.close() of the Python interface.
version()
Return a numerical representation of the LAMMPS version in use.
This is a wrapper around the lammps.version() function of the Python interface.
Returns version number
Return type int
file(file)
Read LAMMPS commands from a file.
This is a wrapper around the lammps.file() function of the Python interface.
Parameters path (string) – Name of the file/path with LAMMPS commands
property enable_cmd_history
Getter Return whether command history is saved
Setter Set if command history should be saved
Type bool
write_script(filepath)
Write LAMMPS script file containing all commands executed up until now
Parameters filepath (string) – path to script file that should be written
clear_cmd_history()
Clear LAMMPS command history up to this point
command(cmd)
Execute LAMMPS command
If PyLammps.enable_cmd_history is set to True, commands executed will be recorded. The entire com-
mand history can be written to a file using PyLammps.write_script(). To clear the command history,
use PyLammps.clear_cmd_history().
Parameters cmd – command string that should be executed
Type cmd: string
run(*args, **kwargs)
Execute LAMMPS run command with given arguments
All thermo output during the run is captured and saved as new entry in PyLammps.runs. The latest run
can be retrieved by PyLammps.last_run.

13.4. The lammps Python module 517

LAMMPS Documentation, Release stable 29Sep2021

property last_run
Return data produced of last completed run command
Getter Returns an object containing information about the last run command
Type dict
property atoms
All atoms of this LAMMPS instance
Getter Returns a list of atoms currently in the system
Type AtomList
property system
The system state of this LAMMPS instance
Getter Returns an object with properties storing the current system state
Type namedtuple
property communication
The communication state of this LAMMPS instance
Getter Returns an object with properties storing the current communication state
Type namedtuple
property computes
The list of active computes of this LAMMPS instance
Getter Returns a list of computes that are currently active in this LAMMPS instance
Type list
property dumps
The list of active dumps of this LAMMPS instance
Getter Returns a list of dumps that are currently active in this LAMMPS instance
Type list
property fixes
The list of active fixes of this LAMMPS instance
Getter Returns a list of fixes that are currently active in this LAMMPS instance
Type list
property groups
The list of active atom groups of this LAMMPS instance
Getter Returns a list of atom groups that are currently active in this LAMMPS instance
Type list
property variables
Returns a dictionary of all variables defined in the current LAMMPS instance
Getter Returns a dictionary of all variables that are defined in this LAMMPS instance
Type dict
eval(expr)
Evaluate expression
Parameters expr (string) – the expression string that should be evaluated inside of LAMMPS

518 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Returns the value of the evaluated expression

Return type float if numeric, string otherwise
lmp_print(s)
needed for Python2 compatibility, since print is a reserved keyword
class lammps.AtomList(pylammps_instance)
A dynamic list of atoms that returns either an Atom or Atom2D instance for each atom. Instances are only allocated
when accessed.
Variables
• natoms – total number of atoms
• dimensions – number of dimensions in system
class lammps.Atom(pylammps_instance, index)
A wrapper class then represents a single atom inside of LAMMPS
It provides access to properties of the atom and allows you to change some of them.
property id
Return the atom ID
Type int
property type
Return the atom type
Type int
property mol
Return the atom molecule index
Type int
property mass
Return the atom mass
Type float
property position
Getter Return position of atom
Setter Set position of atom
Type tuple (float, float, float)
property force
Return the total force acting on the atom
Type tuple (float, float, float)
property charge
Return the atom charge
Type float
class lammps.Atom2D(pylammps_instance, index)
A wrapper class then represents a single 2D atom inside of LAMMPS
Inherits all properties from the Atom class, but returns 2D versions of position, velocity, and force.
It provides access to properties of the atom and allows you to change some of them.

13.4. The lammps Python module 519

LAMMPS Documentation, Release stable 29Sep2021

property position
Access to coordinates of an atom
Getter Return position of atom
Setter Set position of atom
Type tuple (float, float)
property velocity
Access to velocity of an atom :getter: Return velocity of atom :setter: Set velocity of atom :type: tuple
(float, float)
property force
Access to force of an atom
Type tuple (float, float)

13.4.3 The IPyLammps class API

The IPyLammps class is an extension of PyLammps, adding additional functions to quickly display visualizations such
as images and videos inside of IPython. See the PyLammps Tutorial for examples.
class lammps.IPyLammps(name='', cmdargs=None, ptr=None, comm=None)
IPython wrapper for LAMMPS which adds embedded graphics capabilities to PyLammmps interface
It either creates its own instance of lammps or can be initialized with an existing instance. The arguments are
the same of the lower-level interface. The original interface can still be accessed via PyLammps.lmp.
Parameters
• name (string) – “machine” name of the shared LAMMPS library (“mpi” loads
liblammps_mpi.so, “” loads liblammps.so)
• cmdargs (list) – list of command line arguments to be passed to the lammps_open()
function. The executable name is automatically added.
• ptr (pointer) – pointer to a LAMMPS C++ class instance when called from an embedded
Python interpreter. None means load symbols from shared library.
• comm (MPI_Comm) – MPI communicator (as provided by mpi4py). None means use
MPI_COMM_WORLD implicitly.
image(filename='snapshot.png', group='all', color='type', diameter='type', size=None, view=None,
center=None, up=None, zoom=1.0, background_color='white')
Generate image using write_dump command and display it
See dump image for more information.
Parameters
• filename (string) – Name of the image file that should be generated. The extension
determines whether it is PNG or JPEG
• group (string) – the group of atoms write_image should use
• color (string) – name of property used to determine color
• diameter (string) – name of property used to determine atom diameter
• size (tuple (width , height)) – dimensions of image

520 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

• view (tuple (theta, phi)) – view parameters

• center (tuple (flag, center_x, center_y, center_z)) – center parameters
• up (tuple (up_x, up_y, up_z)) – vector pointing to up direction
• zoom (float) – zoom factor
• background_color (string) – background color of scene
Returns Image instance used to display image in notebook
Return type IPython.core.display.Image
video(filename)
Load video from file
Can be used to visualize videos from dump movie.
Parameters filename (string) – Path to video file
Returns HTML Video Tag used by notebook to embed a video
Return type IPython.display.HTML

13.4.4 Additional components of the lammps module

The lammps module additionally contains several constants and the NeighList class:

Data Types

LAMMPS_INT, LAMMPS_INT_2D, LAMMPS_DOUBLE, LAMMPS_DOUBLE_2D, LAMMPS_INT64,

LAMMPS_INT64_2D, LAMMPS_STRING
Constants in the lammps module to indicate how to cast data when the C library function returns a void pointer.
Used in lammps.extract_global() and lammps.extract_atom(). See _LMP_DATATYPE_CONST for the
equivalent constants in the C library interface.

Style Constants

LMP_STYLE_GLOBAL, LMP_STYLE_ATOM, LMP_STYLE_LOCAL

Constants in the lammps module to select what style of data to request from computes or fixes.
See _LMP_STYLE_CONST for the equivalent constants in the C library interface. Used in lammps.
extract_compute(), lammps.extract_fix(), and their NumPy variants lammps.numpy.
extract_compute() and lammps.numpy.extract_fix().

Type Constants

LMP_TYPE_SCALAR, LMP_TYPE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS,

LMP_SIZE_COLS
Constants in the lammps module to select what type of data to request from computes or fixes.
See _LMP_TYPE_CONST for the equivalent constants in the C library interface. Used in lammps.
extract_compute(), lammps.extract_fix(), and their NumPy variants lammps.numpy.
extract_compute() and lammps.numpy.extract_fix().

13.4. The lammps Python module 521

LAMMPS Documentation, Release stable 29Sep2021

Variable Type Constants

LMP_VAR_EQUAL, LMP_VAR_ATOM
Constants in the lammps module to select what type of variable to query when calling lammps.
extract_variable(). See also: variable command.

Classes representing internal objects

class lammps.NeighList(lmp, idx)

This is a wrapper class that exposes the contents of a neighbor list.
It can be used like a regular Python list. Each element is a tuple of:
• the atom local index
• its number of neighbors
• and a pointer to an c_int array containing local atom indices of its neighbors
Internally it uses the lower-level LAMMPS C-library interface.
Parameters
• lmp (lammps) – reference to instance of lammps
• idx (int) – neighbor list index
property size
Returns number of elements in neighbor list
get(element)
Access a specific neighbor list entry. “element” must be a number from 0 to the size-1 of the list
Returns tuple with atom local index, number of neighbors and ctypes pointer to neighbor’s local
atom indices
Return type (int, int, ctypes.POINTER(c_int))
find(iatom)
Find the neighbor list for a specific (local) atom iatom. If there is no list for iatom, (-1, None) is returned.
Returns tuple with number of neighbors and ctypes pointer to neighbor’s local atom indices
Return type (int, ctypes.POINTER(c_int))
class lammps.numpy_wrapper.NumPyNeighList(lmp, idx)
This is a wrapper class that exposes the contents of a neighbor list.
It can be used like a regular Python list. Each element is a tuple of:
• the atom local index
• a NumPy array containing the local atom indices of its neighbors
Internally it uses the lower-level LAMMPS C-library interface.
Parameters
• lmp (lammps) – reference to instance of lammps
• idx (int) – neighbor list index
get(element)
Access a specific neighbor list entry. “element” must be a number from 0 to the size-1 of the list

522 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Returns tuple with atom local index, numpy array of neighbor local atom indices
Return type (int, numpy.array)
find(iatom)
Find the neighbor list for a specific (local) atom iatom. If there is no list for iatom, None is returned.
Returns numpy array of neighbor local atom indices
Return type numpy.array or None

13.5 Extending the Python interface

As noted previously, most of the lammps Python class methods correspond one-to-one with the functions in the
LAMMPS library interface in src/library.cpp and library.h. This means you can extend the Python wrapper
by following these steps:
• Add a new interface function to src/library.cpp and src/library.h.
• Rebuild LAMMPS as a shared library.
• Add a wrapper method to python/lammps/core.py for this interface function.
• Define the corresponding argtypes list and restype in the lammps.__init__() function.
• Re-install the shared library and the python module, if needed
• You should now be able to invoke the new interface function from a Python script.

13.6 Calling Python from LAMMPS

LAMMPS has several commands which can be used to invoke Python code directly from an input script:
• python
• variable python
• fix python/invoke
• pair_style python
The python command which can be used to define and execute a Python function that you write the code for. The Python
function can also be assigned to a LAMMPS python-style variable via the variable command. Each time the variable
is evaluated, either in the LAMMPS input script itself, or by another LAMMPS command that uses the variable, this
will trigger the Python function to be invoked.
The Python code for the function can be included directly in the input script or in an auxiliary file. The function can
have arguments which are mapped to LAMMPS variables (also defined in the input script) and it can return a value to
a LAMMPS variable. This is thus a mechanism for your input script to pass information to a piece of Python code, ask
Python to execute the code, and return information to your input script.
Note that a Python function can be arbitrarily complex. It can import other Python modules, instantiate Python classes,
call other Python functions, etc. The Python code that you provide can contain more code than the single function. It
can contain other functions or Python classes, as well as global variables or other mechanisms for storing state between
calls from LAMMPS to the function.
The Python function you provide can consist of “pure” Python code that only performs operations provided by standard
Python. However, the Python function can also “call back” to LAMMPS through its Python-wrapped library interface,
in the manner described in the Python run doc page. This means it can issue LAMMPS input script commands or
query and set internal LAMMPS state. As an example, this can be useful in an input script to create a more complex

13.5. Extending the Python interface 523

LAMMPS Documentation, Release stable 29Sep2021

loop with branching logic, than can be created using the simple looping and branching logic enabled by the next and
if commands.
See the python page and the variable doc page for its python-style variables for more info, including examples of Python
code you can write for both pure Python operations and callbacks to LAMMPS.

13.7 Output Readers

The Python package contains the lammps.formats module, which provides classes to post-process some of the output
files generated by LAMMPS.
class lammps.formats.LogFile(filename)
Reads LAMMPS log files and extracts the thermo information
It supports both the default thermo output style (including custom) and multi.
Parameters filename (str) – path to log file
Variables
• runs – List of LAMMPS runs in log file. Each run is a dictionary with thermo fields as keys,
storing the values over time
• errors – List of error lines in log file
class lammps.formats.AvgChunkFile(filename)
Reads files generated by fix ave/chunk
Parameters filename (str) – path to ave/chunk file
Variables
• timesteps – List of timesteps stored in file
• total_count – total count over time
• chunks – List of chunks. Each chunk is a dictionary containing its ID, the coordinates, and
the averaged quantities

13.8 Example Python scripts

The python/examples directory has Python scripts which show how Python can run LAMMPS, grab data, change it,
and put it back into LAMMPS.
These are the Python scripts included as demos in the python/examples directory of the LAMMPS distribution, to
illustrate the kinds of things that are possible when Python wraps LAMMPS. If you create your own scripts, send them
to us and we can include them in the LAMMPS distribution.

trivial.py read/run a LAMMPS input script through Python

demo.py invoke various LAMMPS library interface routines
simple.py run in parallel, similar to examples/COUPLE/simple/simple.cpp
split.py same as simple.py but running in parallel on a subset of procs
gui.py GUI go/stop/temperature-slider to control LAMMPS
plot.py real-time temperature plot with GnuPlot via Pizza.py
viz_TOOL.py real-time viz via some viz package
vizplotgui_TOOL.py combination of viz_TOOL.py and plot.py and gui.py

524 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

For the viz_TOOL.py and vizplotgui_TOOL.py commands, replace TOOL with gl or atomeye or pymol or vmd,
depending on what visualization package you have installed.
Note that for GL, you need to be able to run the Pizza.py GL tool, which is included in the pizza sub-directory. See the
Pizza.py doc pages for more info:
• https://lammps.github.io/pizza
Note that for AtomEye, you need version 3, and there is a line in the scripts that specifies the path and name of the
executable. See the AtomEye web pages for more details:
• http://li.mit.edu/Archive/Graphics/A/
• http://li.mit.edu/Archive/Graphics/A3/A3.html
The latter link is to AtomEye 3 which has the scripting capability needed by these Python scripts.
Note that for PyMol, you need to have built and installed the open-source version of PyMol in your Python, so that you
can import it from a Python script. See the PyMol web pages for more details:
• https://www.pymol.org
• https://github.com/schrodinger/pymol-open-source
The latter link is to the open-source version.
Note that for VMD, you need a fairly current version (1.8.7 works for me) and there are some lines in the pizza/vmd.py
script for 4 PIZZA variables that have to match the VMD installation on your system.

See the python/README file for instructions on how to run them and the source code for individual scripts for comments
about what they do.
Here are screenshots of the vizplotgui_tool.py script in action for different visualization package options:

13.9 Handling LAMMPS errors

Compiling the shared library with C++ exception support provides a better error handling experience. Without ex-
ceptions the LAMMPS code will terminate the current Python process with an error message. C++ exceptions allow
capturing them on the C++ side and rethrowing them on the Python side. This way LAMMPS errors can be handled
through the Python exception handling mechanism.

from lammps import lammps, MPIAbortException

lmp = lammps()

try:
(continues on next page)

13.9. Handling LAMMPS errors 525

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

# LAMMPS will normally terminate itself and the running process if an error
# occurs. This would kill the Python interpreter. To avoid this, make sure to
# compile with LAMMPS_EXCEPTIONS enabled. This ensures the library API calls
# will not terminate the parent process. Instead, the library wrapper will
# detect that an error has occured and throw a Python exception

lmp.command('unknown')
except MPIAbortException as ae:
# Single MPI process got killed. This would normally be handled by an MPI abort
pass
except Exception as e:
# All (MPI) processes have reached this error
pass

Warning: Capturing a LAMMPS exception in Python can still mean that the current LAMMPS process is in an
illegal state and must be terminated. It is advised to save your data and terminate the Python instance as quickly as
possible.

13.10 Troubleshooting

13.10.1 Testing if Python can launch LAMMPS

To test if LAMMPS is callable from Python, launch Python interactively and type:

>>> from lammps import lammps

>>> lmp = lammps()

If you get no errors, you’re ready to use LAMMPS from Python. If the second command fails, the most common error
to see is

OSError: Could not load LAMMPS dynamic library

which means Python was unable to load the LAMMPS shared library. This typically occurs if the system can’t find
the LAMMPS shared library or one of the auxiliary shared libraries it depends on, or if something about the library is
incompatible with your Python. The error message should give you an indication of what went wrong.
If your shared library uses a suffix, such as liblammps_mpi.so, change the constructor call as follows (see Creating
or deleting a LAMMPS object for more details):

>>> lmp = lammps(name='mpi')

You can also test the load directly in Python as follows, without first importing from the lammps module:

>>> from ctypes import CDLL

>>> CDLL("liblammps.so")

If an error occurs, carefully go through the steps in Installing the LAMMPS Python Module and Shared Library and
on the Build_basics page about building a shared library.
If you are not familiar with Python, it is a powerful scripting and programming language which can do almost everything
that compiled languages like C, C++, or Fortran can do in fewer lines of code. It also comes with a large collection

526 Chapter 13. Use Python with LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

of add-on modules for many purposes (either bundled or easily installed from Python code repositories). The major
drawback is slower execution speed of the script code compared to compiled programming languages. But when the
script code is interfaced to optimized compiled code, performance can be on par with a standalone executable, for as
long as the scripting is restricted to high-level operations. Thus Python is also convenient to use as a “glue” language
to “drive” a program through its library interface, or to hook multiple pieces of software together, such as a simulation
code and a visualization tool, or to run a coupled multi-scale or multi-physics model.
See the Coupling LAMMPS to other codes page for more ideas about coupling LAMMPS to other codes. See the
LAMMPS Library Interfaces page for a description of the LAMMPS library interfaces. That interface is exposed to
Python either when calling LAMMPS from Python or when calling Python from a LAMMPS input script and then
calling back to LAMMPS from Python code. The C-library interface is designed to be easy to add functionality to,
thus the Python interface to LAMMPS is easy to extend as well.
If you create interesting Python scripts that run LAMMPS or interesting Python functions that can be called from a
LAMMPS input script, that you think would be generally useful, please post them as a pull request to our GitHub site,
and they can be added to the LAMMPS distribution or web page.

13.10. Troubleshooting 527

LAMMPS Documentation, Release stable 29Sep2021

528 Chapter 13. Use Python with LAMMPS

 CHAPTER

FOURTEEN

MODIFYING & EXTENDING LAMMPS

LAMMPS is designed in a modular fashion so as to be easy to modify and extend with new functionality. In fact, about
95% of its source code is add-on files. These doc pages give basic instructions on how to do this.
If you add a new feature to LAMMPS and think it will be of interest to general users, we encourage you to submit
it for inclusion in LAMMPS as a pull request on our GitHub site, after reading about how to prepare your code for
submission and the style requirements and recommendations.

14.1 Overview

The best way to add a new feature to LAMMPS is to find a similar feature and look at the corresponding source and
header files to figure out what it does. You will need some knowledge of C++ to be able to understand the high-level
structure of LAMMPS and its class organization, but functions (class methods) that do actual computations are written
in vanilla C-style code and operate on simple C-style data structures (vectors and arrays).
Most of the new features described on the Modify doc page require you to write a new C++ derived class (except for
exceptions described below, where you can make small edits to existing files). Creating a new class requires 2 files,
a source code file (*.cpp) and a header file (*.h). The derived class must provide certain methods to work as a new
option. Depending on how different your new feature is compared to existing features, you can either derive from the
base class itself, or from a derived class that already exists. Enabling LAMMPS to invoke the new class is as simple
as putting the two source files in the src directory and re-building LAMMPS.
The advantage of C++ and its object-orientation is that all the code and variables needed to define the new feature are
in the 2 files you write, and thus should not make the rest of LAMMPS more complex or cause side-effect bugs.
Here is a concrete example. Suppose you write 2 files pair_foo.cpp and pair_foo.h that define a new class PairFoo that
computes pairwise potentials described in the classic 1997 paper by Foo, et al. If you wish to invoke those potentials
in a LAMMPS input script with a command like

pair_style foo 0.1 3.5

then your pair_foo.h file should be structured as follows:

#ifdef PAIR_CLASS
// clang-format off
PairStyle(foo,PairFoo);
#else
// clanf-format on
...
(class definition for PairFoo)
...
#endif

529
LAMMPS Documentation, Release stable 29Sep2021

where “foo” is the style keyword in the pair_style command, and PairFoo is the class name defined in your pair_foo.cpp
and pair_foo.h files.
When you re-build LAMMPS, your new pairwise potential becomes part of the executable and can be invoked with a
pair_style command like the example above. Arguments like 0.1 and 3.5 can be defined and processed by your new
class.

Note: With the traditional make process, simply adding the new files to the src folder and compiling LAMMPS again
for the desired configuration with “make machine” is sufficient. When using CMake, you need to re-run CMake with
“cmake .” in the build folder to have it recognize the added files and include them into the build system.

As illustrated by this example pair style, many kinds of options are referred to in the LAMMPS documentation as the
“style” of a particular command.
The Modify page lists all the common styles in LAMMPS, and discusses the header file for the base class that these
styles are derived from. Public variables in that file are ones used and set by the derived classes which are also used by
the base class. Sometimes they are also used by the rest of LAMMPS. Pure functions, which means functions declared
as virtual in the base class header file which are also set to 0, are functions you must implement in your new derived
class to give it the functionality LAMMPS expects. Virtual functions that are not set to 0 are functions you may override
or not. Those are usually defined with an empty function body.
Additionally, new output options can be added directly to the thermo.cpp, dump_custom.cpp, and variable.cpp files.
These are also listed on the Modify page.
Here are additional guidelines for modifying LAMMPS and adding new functionality:
• Think about whether what you want to do would be better as a pre- or post-processing step. Many computations
are more easily and more quickly done that way.
• Do not try to do anything within the timestepping of a run that is not parallel. For example do not accumulate a
bunch of data on a single processor and analyze it. You run the risk of seriously degrading the parallel efficiency
this way.
• If your new feature reads arguments or writes output, make sure you follow the unit conventions discussed by
the units command.

(Foo) Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).

14.2 Submitting new features for inclusion in LAMMPS

We encourage LAMMPS users to submit new features they wrote for LAMMPS to be included into the LAMMPS
distribution and thus become easily accessible to all LAMMPS users. The LAMMPS source code is managed with
git and public development is hosted on GitHub. You can monitor the repository to be notified of releases, follow the
ongoing development, and comment on topics of interest to you.

530 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

14.2.1 Communication with the LAMMPS developers

For any larger modifications or programming project, you are encouraged to contact the LAMMPS developers ahead
of time in order to discuss implementation strategies and coding guidelines. That will make it easier to integrate your
contribution and results in less work for everybody involved. You are also encouraged to search through the list of open
issues on GitHub and submit a new issue for a planned feature, so you would not duplicate the work of others (and
possibly get scooped by them) or have your work duplicated by others.
For informal communication with the LAMMPS developers you may ask to join the LAMMPS developers on Slack.
This slack work space is by invitation only. Thus for access, please send an e-mail to [email protected] explaining
what part of LAMMPS you are working on. Only discussions related to LAMMPS development are tolerated in that
work space, so this is NOT for people that look for help with compiling, installing, or using LAMMPS. Please post a
message to the lammps-users mailing list or the LAMMPS forum for those purposes.

14.2.2 Packages versus individual files

The remainder of this chapter describes how to add new “style” files of various kinds to LAMMPS. Packages are simply
collections of one or more such new class files which are invoked as a new style within a LAMMPS input script. In
some cases also collections of supporting functions or classes are included as separate files in a package, especially
when they can be shared between multiple styles. If designed correctly, these additions typically do not require any
changes to the core code of LAMMPS; they are simply add-on files that are compiled with the rest of LAMMPS. To
make those styles work, you may need some trivial changes to the core code; an example of a trivial change is making
a parent-class method “virtual” when you derive a new child class from it.
If you think your new feature or package requires some non-trivial changes in core LAMMPS files, you should com-
municate with the LAMMPS developers on Slack, on GitHub, or via email, since we may have recommendations about
what changes to do where, or may not want to include certain changes for some reason and thus you would need to look
for alternatives.

14.2.3 Time and effort required

How quickly your contribution will be integrated can vary a lot. It depends largely on how much effort it will cause the
LAMMPS developers to integrate and test it, how many and what kind of changes to the core code are required, how
quickly you can address them and of how much interest it is to the larger LAMMPS community. Please see the section
on LAMMPS programming style and requirements for instructions, recommendations, and formal requirements. A
small, modular, well written contribution may be integrated within hours, but a complex change that will require a
redesign of some core functionality in LAMMPS for a clean integration can take many months until it is considered
ready for inclusion (though this is rare).

14.2.4 Submission procedure

All changes to LAMMPS (including those from LAMMPS developers) are integrated via pull requests on GitHub and
cannot be merged without passing the automated testing and an approving review by a LAMMPS core developer. Thus
before submitting your contribution, you should first make certain, that your added or modified code compiles and
works correctly with the latest patch-level or development version of LAMMPS and contains all bug fixes from it.
Once you have prepared everything, see the LAMMPS GitHub Tutorial page for instructions on how to submit your
changes or new files through a GitHub pull request yourself. If you are unable or unwilling to submit via GitHub
yourself, you may also submit patch files or full files to the LAMMPS developers and ask them to submit a pull request
on GitHub on your behalf. Then create a gzipped tar file of all changed or added files or a corresponding patch file
using ‘diff -u’ or ‘diff -c’ format and compress it with gzip. Please only use gzip compression, as this works well and
is available on all platforms.

14.2. Submitting new features for inclusion in LAMMPS 531

LAMMPS Documentation, Release stable 29Sep2021

If the new features/files are broadly useful we may add them as core files to LAMMPS or as part of a package. All
packages are listed and described on the Packages details doc page.

14.2.5 Licensing

Note that by providing us files to release, you agree to make them open-source, i.e. we can release them under the
terms of the GPL (version 2) with the rest of LAMMPS. And similarly as part of a LGPL (version 2.1) distribution of
LAMMPS that we make available to developers on request only and with files that are not authorized for that kind of
distribution removed (e.g. interface to FFTW). See the LAMMPS license page for details.

14.2.6 External contributions

If you prefer to do so, you can also develop and support your add-on feature without having it included in the LAMMPS
distribution, for example as a download from a website of your own. See the External LAMMPS packages and tools
page of the LAMMPS website for examples of groups that do this. We are happy to advertise your package and website
from that page. Simply email the developers with info about your package and we will post it there. We recommend
to name external packages USER-<name> so they can be easily distinguished from bundled packages that do not have
the USER- prefix.

14.3 LAMMPS programming style and requirements for contributions

The following is a summary of the current requirements and recommendations for including contributed source code
or documentation into the LAMMPS software distribution.

14.3.1 Motivation

The LAMMPS developers are committed to providing a software package that is versatile, reliable, high-quality, ef-
ficient, portable, and easy to maintain and modify. Achieving all of these goals is challenging since a large part of
LAMMPS consists of contributed code from many different authors and not many of them are professionally trained
programmers and familiar with the idiosyncrasies of maintaining a large software package. In addition, changes that
interfere with the parallel efficiency of the core code must be avoided. As LAMMPS continues to grow and more
features and functionality are added, it becomes a necessity to be more discriminating with new contributions while
also working at the same time to improve the existing code.
The following requirements and recommendations are provided to help maintaining or improving that status. Where
possible we utilize available continuous integration tools to search for common programming mistakes, portability
limitations, incompatible formatting, and undesired side effects. It is indicated which requirements are strict, and
which represent a preference and thus are negotiable or optional.
Please feel free to contact the LAMMPS core developers in case you need additional explanations or clarifications or
in case you need assistance in realizing the (strict) requirements for your contributions.

532 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

14.3.2 Licensing requirements (strict)

Contributing authors agree when submitting a pull request that their contributions can be distributed under the
LAMMPS license conditions. This is the GNU public license in version 2 (not 3 or later) for the publicly distributed
versions, e.g. on the LAMMPS homepage or on GitHub. On request we also make a version of LAMMPS avail-
able under LGPL 2.1 terms; this will usually be the latest available or a previous stable version with a few LGPL 2.1
incompatible files removed.
Your new source files should have the LAMMPS copyright, GPL notice, and your name and email address at the top,
like other user-contributed LAMMPS source files.
Contributions may be under a different license for long as that license does not conflict with the aforementioned terms.
Contributions that use code with a conflicting license can be split into two parts:
1. the core parts (i.e. parts that must be in the src tree) that are licensed under compatible terms and bundled with
the LAMMPS sources
2. an external library that must be downloaded and compiled (either separately or as part of the LAMMPS compi-
lation)
Please note, that this split licensed mode may complicate including the contribution in binary packages.

14.3.3 Using Pull Requests on GitHub (preferred)

All contributions to LAMMPS are processed as pull requests on GitHub (this also applies to the work of the core
LAMMPS developers). A tutorial for submitting pull requests on GitHub is provided. If this is still problematic,
contributors may contact any of the core LAMMPS developers for help or to create a pull request on their behalf. This
latter way of submission may delay the integration as it depends on the amount of time required to prepare the pull
request and free time available by the LAMMPS developer in question to spend on this task.

14.3.4 Integration Testing (strict)

Contributed code, like all pull requests, must pass the automated tests on GitHub before it can be merged with the
LAMMPS distribution. These tests compile LAMMPS in a variety of environments and settings and run the bundled
unit tests. At the discretion of the LAMMPS developer managing the pull request, additional tests may be activated
that test for “side effects” on running a collection of input decks and create consistent results. Also, the translation of
the documentation to HTML and PDF is tested for.
More specifically, this means that contributed source code must compile with the most current version of LAMMPS
with -DLAMMPS_BIGBIG in addition to the default setting of -DLAMMPS_SMALLBIG. The code needs to work correctly
in both cases and also in serial and parallel using MPI.
Some “disruptive” changes may break tests and require updates to the testing tools or scripts or tests themselves. This is
rare. If in doubt, contact the LAMMPS developer that is assigned to the pull request for further details and explanations
and suggestions of what needs to be done.

14.3. LAMMPS programming style and requirements for contributions 533

LAMMPS Documentation, Release stable 29Sep2021

14.3.5 Documentation (strict)

Contributions that add new styles or commands or augment existing ones must include the corresponding new or
modified documentation in ReStructuredText format (.rst files in the doc/src/ folder). The documentation shall be
written in American English and the .rst file must use only ASCII characters so it can be cleanly translated to PDF files
(via sphinx and PDFLaTeX). Special characters may be included via embedded math expression typeset in a LaTeX
subset.
When adding new commands, they need to be integrated into the sphinx documentation system, and the corresponding
command tables and lists updated. When translating the documentation into html files there should be no warnings.
When adding a new package also some lists describing packages must be updated as well as a package specific descrip-
tion added and, if necessary, some package specific build instructions included.
As appropriate, the text files with the documentation can include inline mathematical expression or figures (see doc/
JPG for examples). Additional PDF files with further details (see doc/PDF for examples) may also be included. The
page should also include literature citations as appropriate; see the bottom of doc/fix_nh.rst for examples and the
earlier part of the same file for how to format the cite itself. Citation labels must be unique across all .rst files. The
“Restrictions” section of the page should indicate if your command is only available if LAMMPS is built with the
appropriate FOO package. See other package doc files for examples of how to do this.
Please run at least “make html” and “make spelling” and carefully inspect and proofread the resulting HTML format
doc page before submitting your code. Upon submission of a pull request, checks for error free completion of the
HTML and PDF build will be performed and also a spell check, a check for correct anchors and labels, and a check for
completeness of references all styles in their corresponding tables and lists is run. In case the spell check reports false
positives they can be added to the file doc/utils/sphinx-config/false_positives.txt
Contributions that add or modify the library interface or “public” APIs from the C++ code or the Fortran module must
include suitable doxygen comments in the source and corresponding changes to the documentation sources for the
“Programmer Guide” guide section of the LAMMPS manual.

14.3.6 Examples (preferred)

In most cases, it is preferred that example scripts (simple, small, fast to complete on 1 CPU) are included that demon-
strate the use of new or extended functionality. These are typically under the examples or examples/PACKAGES
directory. A few guidelines for such example input decks.
• commands that generate output should be commented out (except when the output is the sole purpose or the
feature, e.g. for a new compute).
• commands like log, echo, package, processors, suffix may not be used in the input file (exception: “processors *
* 1” or similar is acceptable when used to avoid unwanted domain decomposition of empty volumes).
• outside of the log files no generated output should be included
• custom thermo_style settings may not include output measuring CPU or other time as that makes comparing the
thermo output between different runs more complicated.
• input files should be named in.name, data files should be named data.name and log files should be named
log.version.name.<compiler>.<ncpu>
• the total file size of all the inputs and outputs should be small
• where possible potential files from the “potentials” folder or data file from other folders should be re-used through
symbolic links

534 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

14.3.7 Howto document (optional)

If your feature requires some more complex steps and explanations to be used correctly or some external or bundled tools
or scripts, we recommend that you also contribute a Howto document providing some more background information
and some tutorial material. This can also be used to provide more in-depth explanations for bundled examples.
As a general rule-of-thumb, the more clear and self-explanatory you make your documentation, README files and
examples, and the easier you make it for people to get started, the more likely it is that users will try out your new
feature.

14.3.8 Programming Style Requirements (varied)

The LAMMPS developers aim to employ a consistent programming style and naming conventions across the entire
code base, as this helps with maintenance, debugging, and understanding the code, both for developers and users.
The files pair_lj_cut.h, pair_lj_cut.cpp, utils.h, and utils.cpp may serve as representative examples.

Command or Style names, file names, and keywords (mostly strict)

All user-visible command or style names should be all lower case and should only use letters, numbers, or forward
slashes. They should be descriptive and initialisms should be avoided unless they are well established (e.g. lj for
Lennard-Jones). For a compute style “some/name” the source files must be called compute_some_name.h and com-
pute_some_name.cpp. The “include guard” would then be LMP_COMPUTE_SOME_NAME_H and the class name
ComputeSomeName.

Whitespace and permissions (preferred)

Source files should not contain TAB characters unless required by the syntax (e.g. in makefiles) and no trailing whites-
pace. Text files should be added with Unix-style line endings (LF-only). Git will automatically convert those in both
directions when running on Windows; use dos2unix on Linux machines to convert files. Text files should have a line
ending on the last line.
All files should have 0644 permissions, i.e writable to the user only and readable by all and no executable permis-
sions. Executable permissions (0755) should only be on shell scripts or python or similar scripts for interpreted script
languages.

Indentation and Placement of Braces (strongly preferred)

LAMMPS uses 2 characters per indentation level and lines should be kept within 100 characters wide.
For new files added to the “src” tree, a clang-format configuration file is provided under the name .clang-format. This
file is compatible with clang-format version 8 and later. With that file present files can be reformatted according to the
configuration with a command like: clang-format -i new-file.cpp. Ideally, this is done while writing the code or before
a pull request is submitted. Blocks of code where the reformatting from clang-format yields undesirable output may
be protected with placing a pair // clang-format off and // clang-format on comments around that block.

14.3. LAMMPS programming style and requirements for contributions 535

LAMMPS Documentation, Release stable 29Sep2021

Programming language standards (required)

The core of LAMMPS is written in C++11 in a style that can be mostly described as “C with classes”. Advanced C++
features like operator overloading or excessive use of templates are avoided with the intent to keep the code readable to
programmers that have limited C++ programming experience. C++ constructs are acceptable when they help improving
the readability and reliability of the code, e.g. when using the std::string class instead of manipulating pointers and
calling the string functions of the C library. In addition and number of convenient utility functions and classes for
recurring tasks are provided.
Included Fortran code has to be compatible with the Fortran 2003 standard. Python code must be compatible with
Python 3.5. Large parts or LAMMPS (including the PYTHON package) are also compatible with Python 2.7. Com-
patibility with Python 2.7 is desirable, but compatibility with Python 3.5 is required.
Compatibility with these older programming language standards is very important to maintain portability, especially
with HPC cluster environments, which tend to be running older software stacks and LAMMPS users may be required
to use those older tools or not have the option to install newer compilers.

Programming conventions (varied)

The following is a collection of conventions that should be applied when writing code for LAMMPS. Following these
steps will make it much easier to integrate your contribution. Please have a look at the existing files in packages in
the src directory for examples. As a demonstration for how can be adapted to these conventions you may compare the
REAXFF package with the what it looked like when it was called USER-REAXC. If you are uncertain, please ask.
• system headers or from installed libraries are include with angular brackets (example: #include <vector>),
while local include file use double quotes (example: #include "atom.h").
• when including system header files from the C library use the C++-style names (<cstdlib> or
<cstring>) instead of the C-style names (<stdlib.h> or <string.h>)
• the order of #include statements in a file some_name.cpp that implements a class SomeName defined in a
header file some_name.h should be as follows:
– #include "some_name.h" followed by an empty line
– LAMMPS include files e.g. #include "comm.h" or #include "modify.h" in alphabetical order fol-
lowed by an empty line
– system header files from the C++ or C standard library followed by an empty line
– using namespace LAMMPS_NS or other namespace imports.
• I/O is done via the C-style stdio library and not iostreams.
• Output to the screen and the logfile should be using the corresponding FILE pointers and only be done on MPI
rank 0. Use the utils::logmesg() convenience function where possible.
• Header files, especially those defining a “style”, should only use the absolute minimum number of include files
and must not contain any using statements. Typically that would be only the header for the base class. Instead
any include statements should be put into the corresponding implementation files and forward declarations be
used. For implementation files, the “include what you use” principle should be employed. However, there is
the notable exception that when the pointers.h header is included (or one of the base classes derived from it)
certain headers will always be included and thus do not need to be explicitly specified. These are: mpi.h, cstddef,
cstdio, cstdlib, string, utils.h, vector, fmt/format.h, climits, cinttypes. This also means any such file can assume
that FILE, NULL, and INT_MAX are defined.
• Header files that define a new LAMMPS style (i.e. that have a SomeStyle(some/name,SomeName); macro
in them) should only use the include file for the base class and otherwise use forward declarations and pointers;
when interfacing to a library use the PIMPL (pointer to implementation) approach where you have a pointer to
a struct that contains all library specific data (and thus requires the library header) but use a forward declaration

536 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

and define the struct only in the implementation file. This is a strict requirement since this is where type clashes
between packages and hard to find bugs have regularly manifested in the past.
• Please use clang-format only to reformat files that you have contributed. For header files containing a
SomeStyle(keyword, ClassName) macros it is required to have this macro embedded with a pair of //
clang-format off, // clang-format on commends and the line must be terminated with a semi-colon
(;). Example:

#ifdef COMMAND_CLASS
// clang-format off
CommandStyle(run,Run);
// clang-format on
#else

#ifndef LMP_RUN_H
[...]

You may also use // clang-format on/off throughout your files to protect individual sections from being
reformatted.
• We rarely accept new styles in the core src folder. Thus please review the list of available Packages to see if your
contribution could be added to be added to one of them. It should fit into the general purposed of that package.
If it does not fit well, it may be added to one of the EXTRA- packages or the MISC package.

14.3.9 Contributing a package

If your contribution has several related features that are not covered by one of the existing packages or is dependent
on a library (bundled or external), it is best to make it a package directory with a name like FOO. In addition to your
new files, the directory should contain a README text file. The README should contain your name and contact
information and a brief description of what your new package does.

14.3.10 Build system (strongly preferred)

LAMMPS currently supports two build systems: one that is based on traditional Makefiles and one that is based on
CMake. Thus your contribution must be compatible with and support both.
For a single pair of header and implementation files that are an independent feature, it is usually only required to add
them to src/.gitignore`.
For traditional make, if your contributed files or package depend on other LAMMPS style files or packages also being
installed (e.g. because your file is a derived class from the other LAMMPS class), then an Install.sh file is also needed
to check for those dependencies and modifications to src/Depend.sh to trigger the checks. See other README and
Install.sh files in other directories as examples.
Similarly for CMake support, changes may need to be made to cmake/CMakeLists.txt, some of the files in
cmake/presets, and possibly a file with specific instructions needs to be added to cmake/Modules/Packages/. Please
check out how this is handled for existing packages and ask the LAMMPS developers if you need assistance.

14.3. LAMMPS programming style and requirements for contributions 537

LAMMPS Documentation, Release stable 29Sep2021

14.3.11 Citation reminder (suggested)

If there is a paper of yours describing your feature (either the algorithm/science behind the feature itself, or its initial
usage, or its implementation in LAMMPS), you can add the citation to the *.cpp source file. See src/DIFFRACTION/
compute_saed.cpp for an example. A BibTeX format citation is stored in a string variable at the top of the file and
a single line of code registering this variable is added to the constructor of the class. When your feature is used, by
default, LAMMPS will print the brief info and the DOI in the first line to the screen and the full citation to the log file.
If there is additional functionality (which may have been added later) described in a different publication, additional
citation descriptions may be added for as long as they are only registered when the corresponding keyword activating this
functionality is used. With these options it is possible to have LAMMPS output a specific citation reminder whenever
a user invokes your feature from their input script. Please note that you should only use this for the most relevant paper
for a feature and a publication that you or your group authored. E.g. adding a citation in the code for a paper by Nose
and Hoover if you write a fix that implements their integrator is not the intended usage. That latter kind of citation
should just be included in the documentation page you provide describing your contribution. If you are not sure what
the best option would be, please contact the LAMMPS developers for advice.

14.3.12 Testing (optional)

If your contribution contains new utility functions or a supporting class (i.e. anything that does not depend on a
LAMMPS object), new unit tests should be added to a suitable folder in the unittest tree. When adding a new
LAMMPS style computing forces or selected fixes, a .yaml file with a test configuration and reference data should be
added for the styles where a suitable tester program already exists (e.g. pair styles, bond styles, etc.). Please see this
section in the manual for more information on how to enable, run, and expand testing.

14.4 Atom styles

Classes that define an atom style are derived from the AtomVec class and managed by the Atom class. The atom style
determines what attributes are associated with an atom and communicated when it is a ghost atom or migrates to a new
processor. A new atom style can be created if one of the existing atom styles does not define all the attributes you need
to store and communicate with atoms.
Atom_vec_atomic.cpp is the simplest example of an atom style. Examining the code for others will make these instruc-
tions more clear.
Note that the atom style hybrid command can be used to define atoms or particles which have the union of properties of
individual styles. Also the fix property/atom command can be used to add a single property (e.g. charge or a molecule
ID) to a style that does not have it. It can also be used to add custom properties to an atom, with options to communicate
them with ghost atoms or read them from a data file. Other LAMMPS commands can access these custom properties,
as can new pair, fix, compute styles that are written to work with these properties. For example, the set command can
be used to set the values of custom per-atom properties from an input script. All of these methods are less work than
writing code for a new atom style.
If you follow these directions your new style will automatically work in tandem with others via the atom_style hybrid
command.
The first step is to define a set of strings in the constructor of the new derived class. Each string will have zero or more
space-separated variable names which are identical to those used in the atom.h header file for per-atom properties. Note
that some represent per-atom vectors (q, molecule) while other are per-atom arrays (x,v). For all but the last 2 strings
you do not need to specify any of (id,type,x,v,f). Those are included automatically as needed in the other strings.

538 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

fields_grow full list of properties which is allocated and stored

fields_copy list of properties to copy atoms are rearranged on-processor
fields_comm list of properties communicated to ghost atoms every step
fields_comm_vel additional properties communicated if comm_modify vel is used
fields_reverse list of properties summed from ghost atoms every step
fields_border list of properties communicated with ghost atoms every reneighboring step
fields_border_vel additional properties communicated if comm_modify vel is used
fields_exchange list of properties communicated when an atom migrates to another processor
fields_restart list of properties written/read to/from a restart file
fields_create list of properties defined when an atom is created by create_atoms
fields_data_atom list of properties (in order) in the Atoms section of a data file, as read by read_data
fields_data_vel list of properties (in order) in the Velocities section of a data file, as read by read_data

In these strings you can list variable names which LAMMPS already defines (in some other atom style), or you can
create new variable names. You should not re-use a LAMMPS variable for something with different meaning in your
atom style. If the meaning is related, but interpreted differently by your atom style, then using the same variable name
means a user should not use your style and the other style together in a atom_style hybrid command. Because there
will only be one value of the variable and different parts of LAMMPS will then likely use it differently. LAMMPS has
no way of checking for this.
If you are defining new variable names then make them descriptive and unique to your new atom style. For example
choosing “e” for energy is a bad choice; it is too generic. A better choice would be “e_foo”, where “foo” is specific to
your style.
If any of the variable names in your new atom style do not exist in LAMMPS, you need to add them to the src/atom.h
and atom.cpp files.
Search for the word “customize” or “customization” in these 2 files to see where to add your variable. Adding a flag to
the 2nd customization section in atom.h is only necessary if your code (e.g. a pair style) needs to check that a per-atom
property is defined. These flags should also be set in the constructor of the atom style child class.
In atom.cpp, aside from the constructor and destructor, there are 3 methods that a new variable name or flag needs to
be added to.
In Atom::peratom_create() when using the add_peratom() method, a final length argument of 0 is for per-atom vectors,
a length > 1 is for per-atom arrays. Note the use of an extra per-thread flag and the add_peratom_vary() method when
last dimension of the array is variable-length.
Adding the variable name to Atom::extract() enable the per-atom data to be accessed through the LAMMPS library
interface by a calling code, including from Python.
The constructor of the new atom style will also typically set a few flags which are defined at the top of atom_vec.h. If
these are unclear, see how other atom styles use them.
The grow_pointers() method is also required to make a copy of peratom data pointers, as explained in the code.
There are a number of other optional methods which your atom style can implement. These are only needed if you
need to do something out-of-the-ordinary which the default operation of the AtomVec parent class does not take care
of. The best way to figure out why they are sometimes useful is to look at how other atom styles use them.
• process_args = use if the atom style has arguments
• init = called before each run
• force_clear = called before force computations each timestep
A few atom styles define “bonus” data associated with some or all of their particles, such as atom_style ellipsoid or tri.
These methods work with that data:
• copy_bonus

14.4. Atom styles 539

LAMMPS Documentation, Release stable 29Sep2021

• clear_bonus
• pack_comm_bonus
• unpack_comm_bonus
• pack_border_bonus
• unpack_border_bonus
• pack_exchange_bonus
• unpack_exchange_bonus
• size_restart_bonus
• pack_restart_bonus
• unpack_restart_bonus
• data_atom_bonus
• memory_usage_bonus
The atom_style body command can define a particle geometry with an arbitrary number of values. This method reads
it from a data file:
• data_body
These methods are called before or after operations handled by the parent AtomVec class. They allow an atom style to
do customized operations on the per-atom values. For example atom_style sphere reads a diameter and density of each
particle from a data file. But these need to be converted internally to a radius and mass. That operation is done in the
data_atom_post() method.
• pack_restart_pre
• pack_restart_post
• unpack_restart_init
• create_atom_post
• data_atom_post
• pack_data_pre
• pack_data_post
These methods enable the compute property/atom command to access per-atom variables it does not already define as
arguments, so that they can be written to a dump file or used by other LAMMPS commands.
• property_atom
• pack_property_atom

14.5 Pair styles

Classes that compute pairwise interactions are derived from the Pair class. In LAMMPS, pairwise calculation include
many-body potentials such as EAM or Tersoff where particles interact without a static bond topology. New styles can
be created to add new pair potentials to LAMMPS.
Pair_lj_cut.cpp is a simple example of a Pair class, though it includes some optional methods to enable its use with
rRESPA.
Here is a brief description of the class methods in pair.h:

540 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

compute workhorse routine that computes pairwise interactions

settings reads the input script line with arguments you define
coeff set coefficients for one i,j type pair
init_one perform initialization for one i,j type pair
init_style initialization specific to this pair style
write & read_restart write/read i,j pair coeffs to restart files
write & read_restart_settings write/read global settings to restart files
single force and energy of a single pairwise interaction between 2 atoms
compute_inner/middle/outer versions of compute used by rRESPA

The inner/middle/outer routines are optional.

14.6 Bond, angle, dihedral, improper styles

Classes that compute molecular interactions are derived from the Bond, Angle, Dihedral, and Improper classes. New
styles can be created to add new potentials to LAMMPS.
Bond_harmonic.cpp is the simplest example of a bond style. Ditto for the harmonic forms of the angle, dihedral, and
improper style commands.
Here is a brief description of common methods you define in your new derived class. See bond.h, angle.h, dihedral.h,
and improper.h for details and specific additional methods.

init check if all coefficients are set, calls init_style (optional)

init_style check if style specific conditions are met (optional)
compute compute the molecular interactions (required)
settings apply global settings for all types (optional)
coeff set coefficients for one type (required)
equilibrium_distance length of bond, used by SHAKE (required, bond only)
equilibrium_angle opening of angle, used by SHAKE (required, angle only)
write & read_restart writes/reads coeffs to restart files (required)
single force (bond only) and energy of a single bond or angle (required, bond or angle only)
memory_usage tally memory allocated by the style (optional)

14.7 Compute styles

Classes that compute scalar and vector quantities like temperature and the pressure tensor, as well as classes that
compute per-atom quantities like kinetic energy and the centro-symmetry parameter are derived from the Compute
class. New styles can be created to add new calculations to LAMMPS.
Compute_temp.cpp is a simple example of computing a scalar temperature. Compute_ke_atom.cpp is a simple example
of computing per-atom kinetic energy.
Here is a brief description of methods you define in your new derived class. See compute.h for details.

14.6. Bond, angle, dihedral, improper styles 541

LAMMPS Documentation, Release stable 29Sep2021

init perform one time setup (required)

init_list neighbor list setup, if needed (optional)
compute_scalar compute a scalar quantity (optional)
compute_vector compute a vector of quantities (optional)
compute_peratom compute one or more quantities per atom (optional)
compute_local compute one or more quantities per processor (optional)
pack_comm pack a buffer with items to communicate (optional)
unpack_comm unpack the buffer (optional)
pack_reverse pack a buffer with items to reverse communicate (optional)
unpack_reverse unpack the buffer (optional)
remove_bias remove velocity bias from one atom (optional)
remove_bias_all remove velocity bias from all atoms in group (optional)
restore_bias restore velocity bias for one atom after remove_bias (optional)
restore_bias_all same as before, but for all atoms in group (optional)
pair_tally_callback callback function for tally-style computes (optional).
memory_usage tally memory usage (optional)

Tally-style computes are a special case, as their computation is done in two stages: the callback function is registered
with the pair style and then called from the Pair::ev_tally() function, which is called for each pair after force and
energy has been computed for this pair. Then the tallied values are retrieved with the standard compute_scalar or
compute_vector or compute_peratom methods. The compute styles in the TALLY package provide examples for utilizing
this mechanism.

14.8 Fix styles

In LAMMPS, a “fix” is any operation that is computed during timestepping that alters some property of the system.
Essentially everything that happens during a simulation besides force computation, neighbor list construction, and
output, is a “fix”. This includes time integration (update of coordinates and velocities), force constraints or boundary
conditions (SHAKE or walls), and diagnostics (compute a diffusion coefficient). New styles can be created to add new
options to LAMMPS.
Fix_setforce.cpp is a simple example of setting forces on atoms to prescribed values. There are dozens of fix options
already in LAMMPS; choose one as a template that is similar to what you want to implement.
Here is a brief description of methods you can define in your new derived class. See fix.h for details.

setmask determines when the fix is called during the timestep (required)
init initialization before a run (optional)
setup_pre_exchange called before atom exchange in setup (optional)
setup_pre_force called before force computation in setup (optional)
setup called immediately before the first timestep and after forces are computed (optional)
min_setup_pre_force like setup_pre_force, but for minimizations instead of MD runs (optional)
min_setup like setup, but for minimizations instead of MD runs (optional)
initial_integrate called at very beginning of each timestep (optional)
pre_exchange called before atom exchange on re-neighboring steps (optional)
pre_neighbor called before neighbor list build (optional)
pre_force called before pair & molecular forces are computed (optional)
post_force called after pair & molecular forces are computed and communicated (optional)
final_integrate called at end of each timestep (optional)
end_of_step called at very end of timestep (optional)
continues on next page

542 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Table 1 – continued from previous page

write_restart dumps fix info to restart file (optional)
restart uses info from restart file to re-initialize the fix (optional)
grow_arrays allocate memory for atom-based arrays used by fix (optional)
copy_arrays copy atom info when an atom migrates to a new processor (optional)
pack_exchange store atom’s data in a buffer (optional)
unpack_exchange retrieve atom’s data from a buffer (optional)
pack_restart store atom’s data for writing to restart file (optional)
unpack_restart retrieve atom’s data from a restart file buffer (optional)
size_restart size of atom’s data (optional)
maxsize_restart max size of atom’s data (optional)
setup_pre_force_respa same as setup_pre_force, but for rRESPA (optional)
initial_integrate_respa same as initial_integrate, but for rRESPA (optional)
post_integrate_respa called after the first half integration step is done in rRESPA (optional)
pre_force_respa same as pre_force, but for rRESPA (optional)
post_force_respa same as post_force, but for rRESPA (optional)
final_integrate_respa same as final_integrate, but for rRESPA (optional)
min_pre_force called after pair & molecular forces are computed in minimizer (optional)
min_post_force called after pair & molecular forces are computed and communicated in minimizer (optional)
min_store store extra data for linesearch based minimization on a LIFO stack (optional)
min_pushstore push the minimization LIFO stack one element down (optional)
min_popstore pop the minimization LIFO stack one element up (optional)
min_clearstore clear minimization LIFO stack (optional)
min_step reset or move forward on line search minimization (optional)
min_dof report number of degrees of freedom added by this fix in minimization (optional)
max_alpha report maximum allowed step size during linesearch minimization (optional)
pack_comm pack a buffer to communicate a per-atom quantity (optional)
unpack_comm unpack a buffer to communicate a per-atom quantity (optional)
pack_reverse_comm pack a buffer to reverse communicate a per-atom quantity (optional)
unpack_reverse_comm unpack a buffer to reverse communicate a per-atom quantity (optional)
dof report number of degrees of freedom removed by this fix during MD (optional)
compute_scalar return a global scalar property that the fix computes (optional)
compute_vector return a component of a vector property that the fix computes (optional)
compute_array return a component of an array property that the fix computes (optional)
deform called when the box size is changed (optional)
reset_target called when a change of the target temperature is requested during a run (optional)
reset_dt is called when a change of the time step is requested during a run (optional)
modify_param called when a fix_modify request is executed (optional)
memory_usage report memory used by fix (optional)
thermo compute quantities for thermodynamic output (optional)

Typically, only a small fraction of these methods are defined for a particular fix. Setmask is mandatory, as it deter-
mines when the fix will be invoked during the timestep. Fixes that perform time integration (nve, nvt, npt) imple-
ment initial_integrate() and final_integrate() to perform velocity Verlet updates. Fixes that constrain forces implement
post_force().
Fixes that perform diagnostics typically implement end_of_step(). For an end_of_step fix, one of your fix arguments
must be the variable “nevery” which is used to determine when to call the fix and you must set this variable in the
constructor of your fix. By convention, this is the first argument the fix defines (after the ID, group-ID, style).
If the fix needs to store information for each atom that persists from timestep to timestep, it can manage that memory
and migrate the info with the atoms as they move from processors to processor by implementing the grow_arrays,
copy_arrays, pack_exchange, and unpack_exchange methods. Similarly, the pack_restart and unpack_restart methods
can be implemented to store information about the fix in restart files. If you wish an integrator or force constraint fix to

14.8. Fix styles 543

LAMMPS Documentation, Release stable 29Sep2021

work with rRESPA (see the run_style command), the initial_integrate, post_force_integrate, and final_integrate_respa
methods can be implemented. The thermo method enables a fix to contribute values to thermodynamic output, as
printed quantities and/or to be summed to the potential energy of the system.

14.9 Input script command style

New commands can be added to LAMMPS input scripts by adding new classes that are derived from the Command
class and thus must have a “command” method. For example, the create_atoms, read_data, velocity, and run commands
are all implemented in this fashion. When such a command is encountered in the LAMMPS input script, LAMMPS
simply creates a class instance with the corresponding name, invokes the “command” method of the class, and passes
it the arguments from the input script. The command method can perform whatever operations it wishes on LAMMPS
data structures.
The single method your new class must define is as follows:

command operations performed by the new command

Of course, the new class can define other methods and variables as needed.

14.10 Dump styles

Classes that dump per-atom info to files are derived from the Dump class. To dump new quantities or in a new format,
a new derived dump class can be added, but it is typically simpler to modify the DumpCustom class contained in the
dump_custom.cpp file.
Dump_atom.cpp is a simple example of a derived dump class.
Here is a brief description of methods you define in your new derived class. See dump.h for details.

write_header write the header section of a snapshot of atoms

count count the number of lines a processor will output
pack pack a proc’s output data into a buffer
write_data write a proc’s data to a file

See the dump command and its custom style for a list of keywords for atom information that can already be dumped
by DumpCustom. It includes options to dump per-atom info from Compute classes, so adding a new derived Compute
class is one way to calculate new quantities to dump.
Note that new keywords for atom properties are not typically added to the dump custom command. Instead they are
added to the compute property/atom command.

14.11 Kspace styles

Classes that compute long-range Coulombic interactions via K-space representations (Ewald, PPPM) are derived from
the KSpace class. New styles can be created to add new K-space options to LAMMPS.
Ewald.cpp is an example of computing K-space interactions.
Here is a brief description of methods you define in your new derived class. See kspace.h for details.

544 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

init initialize the calculation before a run

setup computation before the first timestep of a run
compute every-timestep computation
memory_usage tally of memory usage

14.12 Minimization styles

Classes that perform energy minimization derived from the Min class. New styles can be created to add new minimiza-
tion algorithms to LAMMPS.
Min_cg.cpp is an example of conjugate gradient minimization.
Here is a brief description of methods you define in your new derived class. See min.h for details.

init initialize the minimization before a run

run perform the minimization
memory_usage tally of memory usage

14.13 Region styles

Classes that define geometric regions are derived from the Region class. Regions are used elsewhere in LAMMPS to
group atoms, delete atoms to create a void, insert atoms in a specified region, etc. New styles can be created to add
new region shapes to LAMMPS.
Region_sphere.cpp is an example of a spherical region.
Here is a brief description of methods you define in your new derived class. See region.h for details.

inside determine whether a point is in the region

surface_interior determine if a point is within a cutoff distance inside of surface
surface_exterior determine if a point is within a cutoff distance outside of surface
shape_update change region shape if set by time-dependent variable

14.14 Body styles

Classes that define body particles are derived from the Body class. Body particles can represent complex entities, such
as surface meshes of discrete points, collections of sub-particles, deformable objects, etc.
See the Howto body page for an overview of using body particles and the various body styles LAMMPS supports. New
styles can be created to add new kinds of body particles to LAMMPS.
Body_nparticle.cpp is an example of a body particle that is treated as a rigid body containing N sub-particles.
Here is a brief description of methods you define in your new derived class. See body.h for details.

14.12. Minimization styles 545

LAMMPS Documentation, Release stable 29Sep2021

data_body process a line from the Bodies section of a data file

noutrow number of sub-particles output is generated for
noutcol number of values per-sub-particle output is generated for
output output values for the Mth sub-particle
pack_comm_body body attributes to communicate every timestep
unpack_comm_body unpacking of those attributes
pack_border_body body attributes to communicate when reneighboring is done
unpack_border_body unpacking of those attributes

14.15 Thermodynamic output options

There is one class that computes and prints thermodynamic information to the screen and log file; see the file
thermo.cpp.
There are two styles defined in thermo.cpp: “one” and “multi”. There is also a flexible “custom” style which allows
the user to explicitly list keywords for quantities to print when thermodynamic info is output. See the thermo_style
command for a list of defined quantities.
The thermo styles (one, multi, etc) are simply lists of keywords. Adding a new style thus only requires defining a
new list of keywords. Search for the word “customize” with references to “thermo style” in thermo.cpp to see the two
locations where code will need to be added.
New keywords can also be added to thermo.cpp to compute new quantities for output. Search for the word “customize”
with references to “keyword” in thermo.cpp to see the several locations where code will need to be added.
Note that the thermo_style custom command already allows for thermo output of quantities calculated by fixes, com-
putes, and variables. Thus, it may be simpler to compute what you wish via one of those constructs, than by adding a
new keyword to the thermo command.

14.16 Variable options

There is one class that computes and stores variable information in LAMMPS; see the file variable.cpp. The value
associated with a variable can be periodically printed to the screen via the print, fix print, or thermo_style custom
commands. Variables of style “equal” can compute complex equations that involve the following types of arguments:

thermo keywords = ke, vol, atoms, ...

other variables = v_a, v_myvar, ...
math functions = div(x,y), mult(x,y), add(x,y), ...
group functions = mass(group), xcm(group,x), ...
atom values = x[123], y[3], vx[34], ...
compute values = c_mytemp[0], c_thermo_press[3], ...

Adding keywords for the thermo_style custom command (which can then be accessed by variables) is discussed on the
Modify thermo doc page.
Adding a new math function of one or two arguments can be done by editing one section of the Variable::evaluate()
method. Search for the word “customize” to find the appropriate location.
Adding a new group function can be done by editing one section of the Variable::evaluate() method. Search for the
word “customize” to find the appropriate location. You may need to add a new method to the Group class as well (see
the group.cpp file).

546 Chapter 14. Modifying & extending LAMMPS

 LAMMPS Documentation, Release stable 29Sep2021

Accessing a new atom-based vector can be done by editing one section of the Variable::evaluate() method. Search for
the word “customize” to find the appropriate location.
Adding new compute styles (whose calculated values can then be accessed by variables) is discussed on the Modify
compute doc page.

14.16. Variable options 547

LAMMPS Documentation, Release stable 29Sep2021

548 Chapter 14. Modifying & extending LAMMPS

 CHAPTER

FIFTEEN

INFORMATION FOR DEVELOPERS

This section describes the internal structure and basic algorithms of the LAMMPS code. This is a work in progress and
additional information will be added incrementally depending on availability of time and requests from the LAMMPS
user community.

15.1 Source files

The source files of the LAMMPS code are found in two directories of the distribution: src and lib. Most of the code
is written in C++ but there are small a number of files in several other languages like C, Fortran, Shell script, or Python.
The core of the code is located in the src folder and its sub-directories. A sizable number of these files are in the src
directory itself, but there are plenty of packages, which can be included or excluded when LAMMPS is built. See the
Include packages in build section of the manual for more information about that part of the build process. LAMMPS
currently supports building with conventional makefiles and through CMake. Those procedures differ in how packages
are enabled or disabled for inclusion into a LAMMPS binary so they cannot be mixed. The source files for each
package are in all-uppercase sub-directories of the src folder, for example src/MOLECULE or src/EXTRA-MOLECULE.
The src/STUBS sub-directory is not a package but contains a dummy MPI library, that is used when building a serial
version of the code. The src/MAKE directory and its sub-directories contain makefiles with settings and flags for a
variety of configuration and machines for the build process with traditional makefiles.
The lib directory contains the source code for several supporting libraries or files with configuration settings to use
globally installed libraries, that are required by some of the optional packages. They may include python scripts that can
transparently download additional source code on request. Each sub-directory, like lib/poems or lib/gpu, contains
the source files, some of which are in different languages such as Fortran or CUDA. These libraries included in the
LAMMPS build, if the corresponding package is installed.
LAMMPS C++ source files almost always come in pairs, such as src/run.cpp (implementation file) and src/run.h
(header file). Each pair of files defines a C++ class, for example the LAMMPS_NS::Run class which contains the code
invoked by the run command in a LAMMPS input script. As this example illustrates, source file and class names often
have a one-to-one correspondence with a command used in a LAMMPS input script. Some source files and classes do
not have a corresponding input script command, e.g. src/force.cpp and the LAMMPS_NS::Force class. They are
discussed in the next section.
The names of all source files are in lower case and may use the underscore character ‘_’ to separate words. Outside of
bundled libraries which may have different conventions, all C and C++ header files have a .h extension, all C++ files
have a .cpp extension, and C files a .c extension. A small number of C++ classes and utility functions are implemented
with only a .h file. Examples are the Pointers and Commands classes or the MathVec functions.

549
LAMMPS Documentation, Release stable 29Sep2021

15.2 Class topology

Though LAMMPS has a lot of source files and classes, its class topology is not very deep, which can be seen from
the LAMMPS class topology figure. In that figure, each name refers to a class and has a pair of associated source files
in the src folder, for example the class LAMMPS_NS::Memory corresponds to the files memory.cpp and memory.h,
or the class LAMMPS_NS::AtomVec corresponds to the files atom_vec.cpp and atom_vec.h. Full lines in the figure
represent compositing: that is the class at the base of the arrow holds a pointer to an instance of the class at the tip.
Dashed lines instead represent inheritance: the class to the tip of the arrow is derived from the class at the base. Classes
with a red boundary are not instantiated directly, but they represent the base classes for “styles”. Those “styles” make
up the bulk of the LAMMPS code and only a few representative examples are included in the figure so it remains
readable.
The LAMMPS_NS::LAMMPS class is the topmost class and represents what is generally referred to an “instance” of
LAMMPS. It is a composite holding pointers to instances of other core classes providing the core functionality of the
MD engine in LAMMPS and through them abstractions of the required operations. The constructor of the LAMMPS
class will instantiate those instances, process the command line flags, initialize MPI (if not already done) and set up file
pointers for input and output. The destructor will shut everything down and free all associated memory. Thus code for
the standalone LAMMPS executable in main.cpp simply initializes MPI, instantiates a single instance of LAMMPS
while passing it the command line flags and input script. It deletes the LAMMPS instance after the method reading the
input returns and shuts down the MPI environment before it exits the executable.
The LAMMPS_NS::Pointers is not shown in the LAMMPS class topology figure for clarity. It holds references to
many of the members of the LAMMPS_NS::LAMMPS, so that all classes derived from LAMMPS_NS::Pointers have
direct access to those reference. From the class topology all classes with blue boundary are referenced in the Pointers
class and all classes in the second and third columns, that are not listed as derived classes are instead derived from
LAMMPS_NS::Pointers. To initialize the pointer references in Pointers, a pointer to the LAMMPS class instance
needs to be passed to the constructor and thus all constructors for classes derived from it must do so and pass this
pointer to the constructor for Pointers.
Since all storage is supposed to be encapsulated (there are a few exceptions), the LAMMPS class can also be instantiated
multiple times by a calling code. Outside of the aforementioned exceptions, those LAMMPS instances can be used
alternately. As of the time of this writing (early 2021) LAMMPS is not yet sufficiently thread-safe for concurrent
execution. When running in parallel with MPI, care has to be taken, that suitable copies of communicators are used to
not create conflicts between different instances.
The LAMMPS class currently (early 2021) holds instances of 19 classes representing the core functionality. There are
a handful of virtual parent classes in LAMMPS that define what LAMMPS calls styles. They are shaded red in the
LAMMPS class topology figure. Each of these are parents of a number of child classes that implement the interface
defined by the parent class. There are two main categories of these styles: some may only have one instance active
at a time (e.g. atom, pair, bond, angle, dihedral, improper, kspace, comm) and there is a dedicated pointer variable for
each of them in the composite class. Setups that require a mix of different such styles have to use a hybrid class that
takes the place of the one allowed instance and then manages and forwards calls to the corresponding sub-styles for the
designated subset of atoms or data. The composite class may also have lists of class instances, e.g. Modify handles
lists of compute and fix styles, while Output handles a list of dump class instances.
The exception to this scheme are the command style classes. These implement specific commands that can be invoked
before, after, or in between runs. For these an instance of the class is created, its command() method called and then,
after completion, the class instance deleted. Examples for this are the create_box, create_atoms, minimize, run, set, or
velocity command styles.
For all those styles certain naming conventions are employed: for the fix nve command the class is called
FixNVE and the source files are fix_nve.h and fix_nve.cpp. Similarly for fix ave/time we have FixAveTime and
fix_ave_time.h and fix_ave_time.cpp. Style names are lower case and without spaces or special characters. A
suffix or words are appended with a forward slash ‘/’ which denotes a variant of the corresponding class without the
suffix. To connect the style name and the class name, LAMMPS uses macros like: AtomStyle(), PairStyle(),
BondStyle(), RegionStyle(), and so on in the corresponding header file. During configuration or compilation files

550 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Fig. 1: LAMMPS class topology

This figure shows some of the relations of the base classes of the LAMMPS simulation package. Full lines indicate that a class
holds an instance of the class it is pointing to; dashed lines point to derived classes that are given as examples of what classes may
be instantiated during a LAMMPS run based on the input commands and accessed through the API define by their respective base
classes. At the core is the LAMMPS class, which holds pointers to class instances with specific purposes. Those may hold instances
of other classes, sometimes directly, or only temporarily, sometimes as derived classes or derived classes of derived classes, which
may also hold instances of other classes.

15.2. Class topology 551

LAMMPS Documentation, Release stable 29Sep2021

with the pattern style_<name>.h are created that consist of a list of include statements including all headers of all
styles of a given type that are currently active (or “installed).
More details on individual classes in the LAMMPS class topology are as follows:
• The Memory class handles allocation of all large vectors and arrays.
• The Error class prints all (terminal) error and warning messages.
• The Universe class sets up one or more partitions of processors so that one or multiple simulations can be run,
on the processors allocated for a run, e.g. by the mpirun command.
• The Input class reads and processes input input strings and files, stores variables, and invokes commands.
• Command style classes are derived from the Command class. They provide input script commands that perform
one-time operations before/after/between simulations or which invoke a simulation. They are usually instantiated
from within the Input class, its command method invoked, and then immediately destructed.
• The Finish class is instantiated to print statistics to the screen after a simulation is performed, by commands like
run and minimize.
• The Special class walks the bond topology of a molecular system to find first, second, third neighbors of each
atom. It is invoked by several commands, like read_data, read_restart, or replicate.
• The Atom class stores per-atom properties associated with atom styles. More precisely, they are allocated and
managed by a class derived from the AtomVec class, and the Atom class simply stores pointers to them. The
classes derived from AtomVec represent the different atom styles and they are instantiated through the atom_style
command.
• The Update class holds instances of an integrator and a minimizer class. The Integrate class is a parent style for
the Verlet and r-RESPA time integrators, as defined by the run_style command. The Min class is a parent style
for various energy minimizers.
• The Neighbor class builds and stores neighbor lists. The NeighList class stores a single list (for all atoms). A
NeighRequest class instance is created by pair, fix, or compute styles when they need a particular kind of neighbor
list and use the NeighRequest properties to select the neighbor list settings for the given request. There can be
multiple instances of the NeighRequest class and the Neighbor class will try to optimize how they are computed
by creating copies or sub-lists where possible.
• The Comm class performs inter-processor communication, typically of ghost atom information. This usually
involves MPI message exchanges with 6 neighboring processors in the 3d logical grid of processors mapped to
the simulation box. There are two communication styles enabling different ways to do the domain decomposition.
Sometimes the Irregular class is used, when atoms may migrate to arbitrary processors.
• The Domain class stores the simulation box geometry, as well as geometric Regions and any user definition of a
Lattice. The latter are defined by the region and lattice commands in an input script.
• The Force class computes various forces between atoms. The Pair parent class is for non-bonded or pair-wise
forces, which in LAMMPS also includes many-body forces such as the Tersoff 3-body potential if those are
computed by walking pairwise neighbor lists. The Bond, Angle, Dihedral, Improper parent classes are styles for
bonded interactions within a static molecular topology. The KSpace parent class is for computing long-range
Coulombic interactions. One of its child classes, PPPM, uses the FFT3D and Remap classes to redistribute and
communicate grid-based information across the parallel processors.
• The Modify class stores lists of class instances derived from the Fix and Compute base classes.
• The Group class manipulates groups that atoms are assigned to via the group command. It also has functions to
compute various attributes of groups of atoms.
• The Output class is used to generate 3 kinds of output from a LAMMPS simulation: thermodynamic information
printed to the screen and log file, dump file snapshots, and restart files. These correspond to the Thermo, Dump,

552 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

and WriteRestart classes respectively. The Dump class is a base class with several derived classes implementing
various dump style variants.
• The Timer class logs timing information, output at the end of a run.

15.3 Parallel algorithms

LAMMPS is designed to enable running simulations in parallel using the MPI parallel communication standard with
distributed data via domain decomposition. The parallelization aims to be efficient result in good strong scaling (= good
speedup for the same system) and good weak scaling (= the computational cost of enlarging the system is proportional
to the system size). Additional parallelization using GPUs or OpenMP can also be applied within the sub-domain
assigned to an MPI process. For clarity, most of the following illustrations show the 2d simulation case. The underlying
algorithms in those cases, however, apply to both 2d and 3d cases equally well.

Note: The text and most of the figures in this chapter were adapted for the manual from the section on parallel
algorithms in the new LAMMPS paper.

15.3.1 Partitioning

The underlying spatial decomposition strategy used by LAMMPS for distributed-memory parallelism is set with the
comm_style command and can be either “brick” (a regular grid) or “tiled”.

Fig. 2: domain decomposition

This figure shows the different kinds of domain decomposition used for MPI parallelization: “brick” on the left with an orthogonal
(left) and a triclinic (middle) simulation domain, and a “tiled” decomposition (right). The black lines show the division into
sub-domains and the contained atoms are “owned” by the corresponding MPI process. The green dashed lines indicate how
sub-domains are extended with “ghost” atoms up to the communication cutoff distance.

The LAMMPS simulation box is a 3d or 2d volume, which can be orthogonal or triclinic in shape, as illustrated in the
domain decomposition figure for the 2d case. Orthogonal means the box edges are aligned with the x, y, z Cartesian
axes, and the box faces are thus all rectangular. Triclinic allows for a more general parallelepiped shape in which edges
are aligned with three arbitrary vectors and the box faces are parallelograms. In each dimension box faces can be
periodic, or non-periodic with fixed or shrink-wrapped boundaries. In the fixed case, atoms which move outside the
face are deleted; shrink-wrapped means the position of the box face adjusts continuously to enclose all the atoms.
For distributed-memory MPI parallelism, the simulation box is spatially decomposed (partitioned) into non-overlapping
sub-domains which fill the box. The default partitioning, “brick”, is most suitable when atom density is roughly uni-
form, as shown in the left-side images of the domain decomposition figure. The sub-domains comprise a regular grid
and all sub-domains are identical in size and shape. Both the orthogonal and triclinic boxes can deform continuously
during a simulation, e.g. to compress a solid or shear a liquid, in which case the processor sub-domains likewise
deform.

15.3. Parallel algorithms 553

LAMMPS Documentation, Release stable 29Sep2021

For models with non-uniform density, the number of particles per processor can be load-imbalanced with the default
partitioning. This reduces parallel efficiency, as the overall simulation rate is limited by the slowest processor, i.e. the
one with the largest computational load. For such models, LAMMPS supports multiple strategies to reduce the load
imbalance:
• The processor grid decomposition is by default based on the simulation cell volume and tries to optimize the
volume to surface ratio for the sub-domains. This can be changed with the processors command.
• The parallel planes defining the size of the sub-domains can be shifted with the balance command. Which can
be done in addition to choosing a more optimal processor grid.
• The recursive bisectioning algorithm in combination with the “tiled” communication style can produce a parti-
tioning with equal numbers of particles in each sub-domain.

The pictures above demonstrate different decompositions for a 2d system with 12 MPI ranks. The atom colors indicate
the load imbalance of each sub-domain with green being optimal and red the least optimal.
Due to the vacuum in the system, the default decomposition is unbalanced with several MPI ranks without atoms (left).
By forcing a 1x12x1 processor grid, every MPI rank does computations now, but number of atoms per sub-domain is
still uneven and the thin slice shape increases the amount of communication between sub-domains (center left). With
a 2x6x1 processor grid and shifting the sub-domain divisions, the load imbalance is further reduced and the amount
of communication required between sub-domains is less (center right). And using the recursive bisectioning leads to
further improved decomposition (right).

15.3.2 Communication

Following the partitioning scheme in use all per-atom data is distributed across the MPI processes, which allows
LAMMPS to handle very large systems provided it uses a correspondingly large number of MPI processes. Since
The per-atom data (atom IDs, positions, velocities, types, etc.) To be able to compute the short-range interactions MPI
processes need not only access to data of atoms they “own” but also information about atoms from neighboring sub-
domains, in LAMMPS referred to as “ghost” atoms. These are copies of atoms storing required per-atom data for up
to the communication cutoff distance. The green dashed-line boxes in the domain decomposition figure illustrate the
extended ghost-atom sub-domain for one processor.
This approach is also used to implement periodic boundary conditions: atoms that lie within the cutoff distance across
a periodic boundary are also stored as ghost atoms and taken from the periodic replication of the sub-domain, which
may be the same sub-domain, e.g. if running in serial. As a consequence of this, force computation in LAMMPS is
not subject to minimum image conventions and thus cutoffs may be larger than half the simulation domain.
Efficient communication patterns are needed to update the “ghost” atom data, since that needs to be done at every MD
time step or minimization step. The diagrams of the ghost-atom-comm figure illustrate how ghost atom communication
is performed in two stages for a 2d simulation (three in 3d) for both a regular and irregular partitioning of the simulation
box. For the regular case (left) atoms are exchanged first in the x-direction, then in y, with four neighbors in the grid of
processor sub-domains.
In the x stage, processor ranks 1 and 2 send owned atoms in their red-shaded regions to rank 0 (and vice versa). Then in
the y stage, ranks 3 and 4 send atoms in their blue-shaded regions to rank 0, which includes ghost atoms they received

554 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Fig. 3: ghost atom communication

This figure shows the ghost atom communication patterns between sub-domains for “brick” (left) and “tiled” communication styles
for 2d simulations. The numbers indicate MPI process ranks. Here the sub-domains are drawn spatially separated for clarity. The
dashed-line box is the extended sub-domain of processor 0 which includes its ghost atoms. The red- and blue-shaded boxes are the
regions of communicated ghost atoms.

in the x stage. Rank 0 thus acquires all its ghost atoms; atoms in the solid blue corner regions are communicated twice
before rank 0 receives them.
For the irregular case (right) the two stages are similar, but a processor can have more than one neighbor in each
direction. In the x stage, MPI ranks 1,2,3 send owned atoms in their red-shaded regions to rank 0 (and vice versa).
These include only atoms between the lower and upper y-boundary of rank 0’s sub-domain. In the y stage, ranks 4,5,6
send atoms in their blue-shaded regions to rank 0. This may include ghost atoms they received in the x stage, but only
if they are needed by rank 0 to fill its extended ghost atom regions in the +/-y directions (blue rectangles). Thus in this
case, ranks 5 and 6 do not include ghost atoms they received from each other (in the x stage) in the atoms they send to
rank 0. The key point is that while the pattern of communication is more complex in the irregular partitioning case, it
can still proceed in two stages (three in 3d) via atom exchanges with only neighboring processors.
When attributes of owned atoms are sent to neighboring processors to become attributes of their ghost atoms, LAMMPS
calls this a “forward” communication. On timesteps when atoms migrate to new owning processors and neighbor lists
are rebuilt, each processor creates a list of its owned atoms which are ghost atoms in each of its neighbor processors.
These lists are used to pack per-atom coordinates (for example) into message buffers in subsequent steps until the next
reneighboring.
A “reverse” communication is when computed ghost atom attributes are sent back to the processor who owns the atom.
This is used (for example) to sum partial forces on ghost atoms to the complete force on owned atoms. The order of the
two stages described in the ghost atom communication figure is inverted and the same lists of atoms are used to pack
and unpack message buffers with per-atom forces. When a received buffer is unpacked, the ghost forces are summed to
owned atom forces. As in forward communication, forces on atoms in the four blue corners of the diagrams are sent,
received, and summed twice (once at each stage) before owning processors have the full force.
These two operations are used many places within LAMMPS aside from exchange of coordinates and forces, for exam-
ple by manybody potentials to share intermediate per-atom values, or by rigid-body integrators to enable each atom in
a body to access body properties. Here are additional details about how these communication operations are performed
in LAMMPS:
• When exchanging data with different processors, forward and reverse communication is done using MPI_Send()

15.3. Parallel algorithms 555

LAMMPS Documentation, Release stable 29Sep2021

and MPI_IRecv() calls. If a processor is “exchanging” atoms with itself, only the pack and unpack operations
are performed, e.g. to create ghost atoms across periodic boundaries when running on a single processor.
• For forward communication of owned atom coordinates, periodic box lengths are added and subtracted when the
receiving processor is across a periodic boundary from the sender. There is then no need to apply a minimum
image convention when calculating distances between atom pairs when building neighbor lists or computing
forces.
• The cutoff distance for exchanging ghost atoms is typically equal to the neighbor cutoff. But it can also chosen
to be longer if needed, e.g. half the diameter of a rigid body composed of multiple atoms or over 3x the length
of a stretched bond for dihedral interactions. It can also exceed the periodic box size. For the regular commu-
nication pattern (left), if the cutoff distance extends beyond a neighbor processor’s sub-domain, then multiple
exchanges are performed in the same direction. Each exchange is with the same neighbor processor, but buffers
are packed/unpacked using a different list of atoms. For forward communication, in the first exchange a processor
sends only owned atoms. In subsequent exchanges, it sends ghost atoms received in previous exchanges. For the
irregular pattern (right) overlaps of a processor’s extended ghost-atom sub-domain with all other processors in
each dimension are detected.

15.3.3 Neighbor lists

To compute forces efficiently, each processor creates a Verlet-style neighbor list which enumerates all pairs of atoms
i,j (i = owned, j = owned or ghost) with separation less than the applicable neighbor list cutoff distance. In LAMMPS
the neighbor lists are stored in a multiple-page data structure; each page is a contiguous chunk of memory which stores
vectors of neighbor atoms j for many i atoms. This allows pages to be incrementally allocated or deallocated in blocks
as needed. Neighbor lists typically consume the most memory of any data structure in LAMMPS. The neighbor list is
rebuilt (from scratch) once every few timesteps, then used repeatedly each step for force or other computations. The
neighbor cutoff distance is Rn = Rf + ∆s , where Rf is the (largest) force cutoff defined by the interatomic potential
for computing short-range pairwise or manybody forces and ∆s is a “skin” distance that allows the list to be used for
multiple steps assuming that atoms do not move very far between consecutive time steps. Typically the code triggers
reneighboring when any atom has moved half the skin distance since the last reneighboring; this and other options of
the neighbor list rebuild can be adjusted with the neigh_modify command.
On steps when reneighboring is performed, atoms which have moved outside their owning processor’s sub-domain are
first migrated to new processors via communication. Periodic boundary conditions are also (only) enforced on these
steps to ensure each atom is re-assigned to the correct processor. After migration, the atoms owned by each processor
are stored in a contiguous vector. Periodically each processor spatially sorts owned atoms within its vector to reorder
it for improved cache efficiency in force computations and neighbor list building. For that atoms are spatially binned
and then reordered so that atoms in the same bin are adjacent in the vector. Atom sorting can be disabled or its settings
modified with the atom_modify command.
To build a local neighbor list in linear time, the simulation domain is overlaid (conceptually) with a regular 3d (or 2d)
grid of neighbor bins, as shown in the neighbor list stencils figure for 2d models and a single MPI processor’s sub-
domain. Each processor stores a set of neighbor bins which overlap its sub-domain extended by the neighbor cutoff
distance Rn . As illustrated, the bins need not align with processor boundaries; an integer number in each dimension is
fit to the size of the entire simulation box.
Most often LAMMPS builds what it calls a “half” neighbor list where each i,j neighbor pair is stored only once, with
either atom i or j as the central atom. The build can be done efficiently by using a pre-computed “stencil” of bins around
a central origin bin which contains the atom whose neighbors are being searched for. A stencil is simply a list of integer
offsets in x,y,z of nearby bins surrounding the origin bin which are close enough to contain any neighbor atom j within
a distance Rn from any atom i in the origin bin. Note that for a half neighbor list, the stencil can be asymmetric since
each atom only need store half its nearby neighbors.
These stencils are illustrated in the figure for a half list and a bin size of 12 Rn . There are 13 red+blue stencil bins in 2d
(for the orthogonal case, 15 for triclinic). In 3d there would be 63, 13 in the plane of bins that contain the origin bin
and 25 in each of the two planes above it in the z direction (75 for triclinic). The reason the triclinic stencil has extra

556 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Fig. 4: neighbor list stencils

A 2d simulation sub-domain (thick black line) and the corresponding ghost atom cutoff region (dashed blue line) for both
orthogonal (left) and triclinic (right) domains. A regular grid of neighbor bins (thin lines) overlays the entire simulation domain
and need not align with sub-domain boundaries; only the portion overlapping the augmented sub-domain is shown. In the triclinic
case it overlaps the bounding box of the tilted rectangle. The blue- and red-shaded bins represent a stencil of bins searched to find
neighbors of a particular atom (black dot).

bins is because the bins tile the bounding box of the entire triclinic domain and thus are not periodic with respect to
the simulation box itself. The stencil and logic for determining which i,j pairs to include in the neighbor list are altered
slightly to account for this.
To build a neighbor list, a processor first loops over its “owned” plus “ghost” atoms and assigns each to a neighbor bin.
This uses an integer vector to create a linked list of atom indices within each bin. It then performs a triply-nested loop
over its owned atoms i, the stencil of bins surrounding atom i’s bin, and the j atoms in each stencil bin (including ghost
atoms). If the distance rij < Rn , then atom j is added to the vector of atom i’s neighbors.
Here are additional details about neighbor list build options LAMMPS supports:
• The choice of bin size is an option; a size half of Rn has been found to be optimal for many typical cases. Smaller
bins incur additional overhead to loop over; larger bins require more distance calculations. Note that for smaller
bin sizes, the 2d stencil in the figure would be more semi-circular in shape (hemispherical in 3d), with bins near
the corners of the square eliminated due to their distance from the origin bin.
• Depending on the interatomic potential(s) and other commands used in an input script, multiple neighbor lists
and stencils with different attributes may be needed. This includes lists with different cutoff distances, e.g. for
force computation versus occasional diagnostic computations such as a radial distribution function, or for the
r-RESPA time integrator which can partition pairwise forces by distance into subsets computed at different time
intervals. It includes “full” lists (as opposed to half lists) where each i,j pair appears twice, stored once with
i and j, and which use a larger symmetric stencil. It also includes lists with partial enumeration of ghost atom
neighbors. The full and ghost-atom lists are used by various manybody interatomic potentials. Lists may also use
different criteria for inclusion of a pair interaction. Typically this simply depends only on the distance between
two atoms and the cutoff distance. But for finite-size coarse-grained particles with individual diameters (e.g.
polydisperse granular particles), it can also depend on the diameters of the two particles.
• When using pair style hybrid multiple sub-lists of the master neighbor list for the full system need to be generated,
one for each sub-style, which contains only the i,j pairs needed to compute interactions between subsets of atoms
for the corresponding potential. This means not all i or j atoms owned by a processor are included in a particular
sub-list.
• Some models use different cutoff lengths for pairwise interactions between different kinds of particles which are
stored in a single neighbor list. One example is a solvated colloidal system with large colloidal particles where
colloid/colloid, colloid/solvent, and solvent/solvent interaction cutoffs can be dramatically different. Another is a
model of polydisperse finite-size granular particles; pairs of particles interact only when they are in contact with
each other. Mixtures with particle size ratios as high as 10-100x may be used to model realistic systems. Efficient

15.3. Parallel algorithms 557

LAMMPS Documentation, Release stable 29Sep2021

neighbor list building algorithms for these kinds of systems are available in LAMMPS. They include a method
which uses different stencils for different cutoff lengths and trims the stencil to only include bins that straddle the
cutoff sphere surface. More recently a method which uses both multiple stencils and multiple bin sizes was devel-
oped; it builds neighbor lists efficiently for systems with particles of any size ratio, though other considerations
(timestep size, force computations) may limit the ability to model systems with huge polydispersity.
• For small and sparse systems and as a fallback method, LAMMPS also supports neighbor list construction without
binning by using a full O(N 2 ) loop over all i,j atom pairs in a sub-domain when using the neighbor nsq command.
• Dependent on the “pair” setting of the newton command, the “half” neighbor lists may contain all pairs of atoms
where atom j is a ghost atom (i.e. when the newton pair setting is off ) For the newton pair on setting the atom
j is only added to the list if its z coordinate is larger, or if equal the y coordinate is larger, and that is equal, too,
the x coordinate is larger. For homogeneously dense systems that will result in picking neighbors from a same
size sector in always the same direction relative to the “owned” atom and thus it should lead to similar length
neighbor lists and thus reduce the chance of a load imbalance.

15.3.4 Long-range interactions

For charged systems, LAMMPS can compute long-range Coulombic interactions via the FFT-based particle-
particle/particle-mesh (PPPM) method implemented in kspace style pppm and its variants. For that Coulombic in-
teractions are partitioned into short- and long-range components. The short-ranged portion is computed in real space
as a loop over pairs of charges within a cutoff distance, using neighbor lists. The long-range portion is computed in
reciprocal space using a kspace style. For the PPPM implementation the simulation cell is overlaid with a regular FFT
grid in 3d. It proceeds in several stages:
a) each atom’s point charge is interpolated to nearby FFT grid points,
b) a forward 3d FFT is performed,
c) a convolution operation is performed in reciprocal space,
d) one or more inverse 3d FFTs are performed, and
e) electric field values from grid points near each atom are interpolated to compute its forces.
For any of the spatial-decomposition partitioning schemes each processor owns the brick-shaped portion of FFT grid
points contained within its sub-domain. The two interpolation operations use a stencil of grid points surrounding each
atom. To accommodate the stencil size, each processor also stores a few layers of ghost grid points surrounding its
brick. Forward and reverse communication of grid point values is performed similar to the corresponding atom data
communication. In this case, electric field values on owned grid points are sent to neighboring processors to become
ghost point values. Likewise charge values on ghost points are sent and summed to values on owned points.
For triclinic simulation boxes, the FFT grid planes are parallel to the box faces, but the mapping of charge and electric
field values to/from grid points is done in reduced coordinates where the tilted box is conceptually a unit cube, so that
the stencil and FFT operations are unchanged. However the FFT grid size required for a given accuracy is larger for
triclinic domains than it is for orthogonal boxes.
Parallel 3d FFTs require substantial communication relative to their computational cost. A 3d FFT is implemented by
a series of 1d FFTs along the x-, y-, and z-direction of the FFT grid. Thus the FFT grid cannot be decomposed like
atoms into 3 dimensions for parallel processing of the FFTs but only in 1 (as planes) or 2 (as pencils) dimensions and in
between the steps the grid needs to be transposed to have the FFT grid portion “owned” by each MPI process complete
in the direction of the 1d FFTs it has to perform. LAMMPS uses the pencil-decomposition algorithm as shown in the
parallel FFT in PPPM figure.
Initially (far left), each processor owns a brick of same-color grid cells (actually grid points) contained within in its
sub-domain. A brick-to-pencil communication operation converts this layout to 1d pencils in the x-dimension (center
left). Again, cells of the same color are owned by the same processor. Each processor can then compute a 1d FFT on
each pencil of data it wholly owns using a call to the configured FFT library. A pencil-to-pencil communication then
converts this layout to pencils in the y dimension (center right) which effectively transposes the x and y dimensions of

558 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Fig. 5: parallel FFT in PPPM

Stages of a parallel FFT for a simulation domain overlaid with an 8x8x8 3d FFT grid, partitioned across 64 processors. Within
each of the 4 diagrams, grid cells of the same color are owned by a single processor; for simplicity only cells owned by 4 or 8 of
the 64 processors are colored. The two images on the left illustrate brick-to-pencil communication. The two images on the right
illustrate pencil-to-pencil communication, which in this case transposes the y and z dimensions of the grid.

the grid, followed by 1d FFTs in y. A final transpose of pencils from y to z (far right) followed by 1d FFTs in z completes
the forward FFT. The data is left in a z-pencil layout for the convolution operation. One or more inverse FFTs then
perform the sequence of 1d FFTs and communication steps in reverse order; the final layout of resulting grid values is
the same as the initial brick layout.
Each communication operation within the FFT (brick-to-pencil or pencil-to-pencil or pencil-to-brick) converts one
tiling of the 3d grid to another, where a tiling in this context means an assignment of a small brick-shaped subset of
grid points to each processor, the union of which comprise the entire grid. The parallel fftMPI library written for
LAMMPS allows arbitrary definitions of the tiling so that an irregular partitioning of the simulation domain can use it
directly. Transforming data from one tiling to another is implemented in fftMPI using point-to-point communication,
where each processor sends data to a few other processors, since each tile in the initial tiling overlaps with a handful of
tiles in the final tiling.
The transformations could also be done using collective communication across all $P$ processors with a single call to
MPI_Alltoall(), but this is typically much slower. However, for the specialized brick and pencil tiling illustrated in
parallel FFT in PPPM figure, collective communication across the entire MPI communicator is not required. In the
example an 83 grid with 512 grid cells is partitioned across 64 processors; each processor owns a 2x2x2 3d brick of
grid cells. The initial brick-to-pencil communication (upper left to upper right) only requires collective communication
within subgroups of 4 processors, as illustrated by the 4 colors. More generally, a brick-to-pencil communication can be
2 1
performed by partitioning P processors into P 3 subgroups of P 3 processors each. Each subgroup performs collective
communication only within its subgroup. Similarly, pencil-to-pencil communication can be performed by partitioning
1 1
P processors into P 2 subgroups of P 2 processors each. This is illustrated in the figure for the y ⇒ z communication
(center). An eight-processor subgroup owns the front yz plane of data and performs collective communication within
the subgroup to transpose from a y-pencil to z-pencil layout.
LAMMPS invokes point-to-point communication by default, but also provides the option of partitioned collective
communication when using a kspace_modify collective yes command to switch to that mode. In the latter case, the
code detects the size of the disjoint subgroups and partitions the single P-size communicator into multiple smaller
communicators, each of which invokes collective communication. Testing on a large IBM Blue Gene/Q machine at
Argonne National Labs showed a significant improvement in FFT performance for large processor counts; partitioned
collective communication was faster than point-to-point communication or global collective communication involving
all P processors.
Here are some additional details about FFTs for long-range and related grid/particle operations that LAMMPS supports:
• The fftMPI library allows each grid dimension to be a multiple of small prime factors (2,3,5), and allows any
number of processors to perform the FFT. The resulting brick and pencil decompositions are thus not always
as well-aligned but the size of subgroups of processors for the two modes of communication (brick/pencil and
1 1
pencil/pencil) still scale as O(P 3 ) and O(P 2 ).

15.3. Parallel algorithms 559

LAMMPS Documentation, Release stable 29Sep2021

• For efficiency in performing 1d FFTs, the grid transpose operations illustrated in Figure ref{fig:fft} also involve
reordering the 3d data so that a different dimension is contiguous in memory. This reordering can be done during
the packing or unpacking of buffers for MPI communication.
• For large systems and particularly a large number of MPI processes, the dominant cost for parallel FFTs is often
the communication, not the computation of 1d FFTs, even though the latter scales as N log(N ) in the number of
grid points N per grid direction. This is due to the fact that only a 2d decomposition into pencils is possible while
atom data (and their corresponding short-range force and energy computations) can be decomposed efficiently
in 3d.
This can be addressed by reducing the number of MPI processes involved in the MPI communication by using
hybrid MPI + OpenMP parallelization. This will use OpenMP parallelization inside the MPI domains and while
that may have a lower parallel efficiency, it reduces the communication overhead.
As an alternative it is also possible to start a multi-partition calculation and then use the verlet/split integrator to
perform the PPPM computation on a dedicated, separate partition of MPI processes. This uses an integer “1:p”
mapping of p sub-domains of the atom decomposition to one sub-domain of the FFT grid decomposition and
where pairwise non-bonded and bonded forces and energies are computed on the larger partition and the PPPM
kspace computation concurrently on the smaller partition.
• LAMMPS also implements PPPM-based solvers for other long-range interactions, dipole and dispersion
(Lennard-Jones), which can be used in conjunction with long-range Coulombics for point charges.
• LAMMPS implements a GridComm class which overlays the simulation domain with a regular grid, partitions
it across processors in a manner consistent with processor sub-domains, and provides methods for forward and
reverse communication of owned and ghost grid point values. It is used for PPPM as an FFT grid (as outlined
above) and also for the MSM algorithm which uses a cascade of grid sizes from fine to coarse to compute long-
range Coulombic forces. The GridComm class is also useful for models where continuum fields interact with
particles. For example, the two-temperature model (TTM) defines heat transfer between atoms (particles) and
electrons (continuum gas) where spatial variations in the electron temperature are computed by finite differences
of a discretized heat equation on a regular grid. The fix ttm/grid command uses the GridComm class internally to
perform its grid operations on a distributed grid instead of the original fix ttm which uses a replicated grid.

15.3.5 OpenMP Parallelism

The styles in the INTEL, KOKKOS, and OPENMP package offer to use OpenMP thread parallelism to predominantly
distribute loops over local data and thus follow an orthogonal parallelization strategy to the decomposition into spatial
domains used by the MPI partitioning. For clarity, this section discusses only the implementation in the OPENMP
package as it is the simplest. The INTEL and KOKKOS package offer additional options and are more complex since
they support more features and different hardware like co-processors or GPUs.
One of the key decisions when implementing the OPENMP package was to keep the changes to the source code small,
so that it would be easier to maintain the code and keep it in sync with the non-threaded standard implementation. this
is achieved by a) making the OPENMP version a derived class from the regular version (e.g. PairLJCutOMP from
PairLJCut) and overriding only methods that are multi-threaded or need to be modified to support multi-threading
(similar to what was done in the OPT package), b) keeping the structure in the modified code very similar so that side-
by-side comparisons are still useful, and c) offloading additional functionality and multi-thread support functions into
three separate classes ThrOMP, ThrData, and FixOMP. ThrOMP provides additional, multi-thread aware functionality
not available in the corresponding base class (e.g. Pair for PairLJCutOMP) like multi-thread aware variants of the
“tally” functions. Those functions are made available through multiple inheritance so those new functions have to have
unique names to avoid ambiguities; typically _thr is appended to the name of the function. ThrData is a classes that
manages per-thread data structures. It is used instead of extending the corresponding storage to per-thread arrays to
avoid slowdowns due to “false sharing” when multiple threads update adjacent elements in an array and thus force the
CPU cache lines to be reset and re-fetched. FixOMP finally manages the “multi-thread state” like settings and access to
per-thread storage, it is activated by the package omp command.

560 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Avoiding data races

A key problem when implementing thread parallelism in an MD code is to avoid data races when updating accumulated
properties like forces, energies, and stresses. When interactions are computed, they always involve multiple atoms and
thus there are race conditions when multiple threads want to update per-atom data of the same atoms. Five possible
strategies have been considered to avoid this:
1) restructure the code so that there is no overlapping access possible when computing in parallel, e.g. by breaking
lists into multiple parts and synchronizing threads in between.
2) have each thread be “responsible” for a specific group of atoms and compute these interactions multiple times,
once on each thread that is responsible for a given atom and then have each thread only update the properties of
this atom.
3) use mutexes around functions and regions of code where the data race could happen
4) use atomic operations when updating per-atom properties
5) use replicated per-thread data structures to accumulate data without conflicts and then use a reduction to combine
those results into the data structures used by the regular style.
Option 5 was chosen for the OPENMP package because it would retain the performance for the case of 1 thread and
the code would be more maintainable. Option 1 would require extensive code changes, particularly to the neighbor list
code; options 2 would have incurred a 2x or more performance penalty for the serial case; option 3 causes significant
overhead and would enforce serialization of operations in inner loops and thus defeat the purpose of multi-threading;
option 4 slows down the serial case although not quite as bad as option 2. The downside of option 5 is that the overhead
of the reduction operations grows with the number of threads used, so there would be a crossover point where options
2 or 4 would result in faster executing. That is why option 2 for example is used in the GPU package because a GPU is
a processor with a massive number of threads. However, since the MPI parallelization is generally more effective for
typical MD systems, the expectation is that thread parallelism is only used for a smaller number of threads (2-8). At
the time of its implementation, that number was equivalent to the number of CPU cores per CPU socket on high-end
supercomputers.
Thus arrays like the force array are dimensioned to the number of atoms times the number of threads when enabling
OpenMP support and inside the compute functions a pointer to a different chunk is obtained by each thread. Similarly,
accumulators like potential energy or virial are kept in per-thread instances of the ThrData class and then only reduced
and stored in their global counterparts at the end of the force computation.

Loop scheduling

Multi-thread parallelization is applied by distributing (outer) loops statically across threads. Typically this would be
the loop over local atoms i when processing i,j pairs of atoms from a neighbor list. The design of the neighbor list
code results in atoms having a similar number of neighbors for homogeneous systems and thus load imbalances across
threads are not common and typically happen for systems where also the MPI parallelization would be unbalanced,
which would typically have a more pronounced impact on the performance. This same loop scheduling scheme can
also be applied to the reduction operations on per-atom data to try and reduce the overhead of the reduction operation.

15.3. Parallel algorithms 561

LAMMPS Documentation, Release stable 29Sep2021

Neighbor list parallelization

In addition to the parallelization of force computations, also the generation of the neighbor lists is parallelized. As
explained previously, neighbor lists are built by looping over “owned” atoms and storing the neighbors in “pages”.
In the OPENMP variants of the neighbor list code, each thread operates on a different chunk of “owned” atoms and
allocates and fills its own set of pages with neighbor list data. This is achieved by each thread keeping its own instance
of the MyPage page allocator class.

15.4 How a timestep works

The first and most fundamental operation within LAMMPS to understand is how a timestep is structured. Timestepping
is performed by calling methods of the Integrate class instance within the Update class. Since Integrate is a base class,
it will point to an instance of a derived class corresponding to what is selected by the run_style input script command.
In this section, the timestep implemented by the Verlet class is described. A similar timestep protocol is implemented
by the Respa class, for the r-RESPA hierarchical timestepping method.
The Min base class performs energy minimization, so does not perform a literal timestep. But it has logic similar to
what is described here, to compute forces and invoke fixes at each iteration of a minimization. Differences between
time integration and minimization are highlighted at the end of this section.
The Verlet class is encoded in the src/verlet.cpp and verlet.h files. It implements the velocity-Verlet timestep-
ping algorithm. The workhorse method is Verlet::run(), but first we highlight several other methods in the class.
• The init() method is called at the beginning of each dynamics run. It simply sets some internal flags, based
on user settings in other parts of the code.
• The setup() or setup_minimal() methods are also called before each run. The velocity-Verlet method re-
quires current forces be calculated before the first timestep, so these routines compute forces due to all atomic
interactions, using the same logic that appears in the timestepping described next. A few fixes are also invoked,
using the mechanism described in the next section. Various counters are also initialized before the run begins.
The setup_minimal() method is a variant that has a flag for performing less setup. This is used when runs are
continued and information from the previous run is still valid. For example, if repeated short LAMMPS runs
are being invoked, interleaved by other commands, via the pre no and every options of the run command, the
setup_minimal() method is used.
• The force_clear() method initializes force and other arrays to zero before each timestep, so that forces
(torques, etc) can be accumulated.
Now for the Verlet::run() method. Its basic structure in hi-level pseudo code is shown below. In the actual code in
src/verlet.cpp some of these operations are conditionally invoked.

loop over N timesteps:

if timeout condition: break
ev_set()

fix->initial_integrate()
fix->post_integrate()

nflag = neighbor->decide()
if nflag:
fix->pre_exchange()
domain->pbc()
domain->reset_box()
comm->setup()
(continues on next page)

562 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

neighbor->setup_bins()
comm->exchange()
comm->borders()
fix->pre_neighbor()
neighbor->build()
fix->post_neighbor()
else:
comm->forward_comm()

force_clear()
fix->pre_force()

pair->compute()
bond->compute()
angle->compute()
dihedral->compute()
improper->compute()
kspace->compute()

fix->pre_reverse()
comm->reverse_comm()

fix->post_force()
fix->final_integrate()
fix->end_of_step()

if any output on this step:

output->write()

# after loop
fix->post_run()

The ev_set() method (in the parent Integrate class), sets two flags (eflag and vflag) for energy and virial computation.
Each flag encodes whether global and/or per-atom energy and virial should be calculated on this timestep, because some
fix or variable or output will need it. These flags are passed to the various methods that compute particle interactions,
so that they either compute and tally the corresponding data or can skip the extra calculations if the energy and virial
are not needed. See the comments for the Integrate::ev_set() method which document the flag values.
At various points of the timestep, fixes are invoked, e.g. fix->initial_integrate(). In the code, this is actu-
ally done via the Modify class which stores all the Fix objects and lists of which should be invoked at what point in
the timestep. Fixes are the LAMMPS mechanism for tailoring the operations of a timestep for a particular simula-
tion. As described elsewhere, each fix has one or more methods, each of which is invoked at a specific stage of the
timestep, as show in the timestep pseudo-code. All the active fixes defined in an input script, that are flagged to have an
initial_integrate() method are invoked at the beginning of each timestep. Examples are fix nve or fix nvt or fix
npt which perform the start-of-timestep velocity-Verlet integration operations to update velocities by a half-step, and
coordinates by a full step. The post_integrate() method is next for operations that need to happen immediately
after those updates. Only a few fixes use this, e.g. to reflect particles off box boundaries in the FixWallReflect class.
The decide() method in the Neighbor class determines whether neighbor lists need to be rebuilt on the current timestep
(conditions can be changed using the neigh_modify every/delay/check command. If not, coordinates of ghost atoms
are acquired by each processor via the forward_comm() method of the Comm class. If neighbor lists need to be built,
several operations within the inner if clause of the pseudo-code are first invoked. The pre_exchange() method of
any defined fixes is invoked first. Typically this inserts or deletes particles from the system.

15.4. How a timestep works 563

LAMMPS Documentation, Release stable 29Sep2021

Periodic boundary conditions are then applied by the Domain class via its pbc() method to remap particles that have
moved outside the simulation box back into the box. Note that this is not done every timestep, but only when neighbor
lists are rebuilt. This is so that each processor’s sub-domain will have consistent (nearby) atom coordinates for its
owned and ghost atoms. It is also why dumped atom coordinates may be slightly outside the simulation box if not
dumped on a step where the neighbor lists are rebuilt.
The box boundaries are then reset (if needed) via the reset_box() method of the Domain class, e.g. if box boundaries
are shrink-wrapped to current particle coordinates. A change in the box size or shape requires internal information for
communicating ghost atoms (Comm class) and neighbor list bins (Neighbor class) be updated. The setup() method
of the Comm class and setup_bins() method of the Neighbor class perform the update.
The code is now ready to migrate atoms that have left a processor’s geometric sub-domain to new processors. The
exchange() method of the Comm class performs this operation. The borders() method of the Comm class then
identifies ghost atoms surrounding each processor’s sub-domain and communicates ghost atom information to neigh-
boring processors. It does this by looping over all the atoms owned by a processor to make lists of those to send to each
neighbor processor. On subsequent timesteps, the lists are used by the Comm::forward_comm() method.
Fixes with a pre_neighbor() method are then called. These typically re-build some data structure stored by the fix
that depends on the current atoms owned by each processor.
Now that each processor has a current list of its owned and ghost atoms, LAMMPS is ready to rebuild neighbor lists via
the build() method of the Neighbor class. This is typically done by binning all owned and ghost atoms, and scanning
a stencil of bins around each owned atom’s bin to make a Verlet list of neighboring atoms within the force cutoff plus
neighbor skin distance.
In the next portion of the timestep, all interaction forces between particles are computed, after zeroing the per-atom
force vector via the force_clear() method. If the newton flag is set to on by the newton command, forces are added
to both owned and ghost atoms, otherwise only to owned (aka local) atoms.
Pairwise forces are calculated first, which enables the global virial (if requested) to be calculated cheaply (at O(N) cost
instead of O(N**2) at the end of the Pair::compute() method), by a dot product of atom coordinates and forces. By
including owned and ghost atoms in the dot product, the effect of periodic boundary conditions is correctly accounted
for. Molecular topology interactions (bonds, angles, dihedrals, impropers) are calculated next (if supported by the
current atom style). The final contribution is from long-range Coulombic interactions, invoked by the KSpace class.
The pre_reverse() method in fixes is used for operations that have to be done before the upcoming reverse commu-
nication (e.g. to perform additional data transfers or reductions for data computed during the force computation and
stored with ghost atoms).
If the newton flag is on, forces on ghost atoms are communicated and summed back to their corresponding owned
atoms. The reverse_comm() method of the Comm class performs this operation, which is essentially the inverse
operation of sending copies of owned atom coordinates to other processor’s ghost atoms.
At this point in the timestep, the total force on each (local) atom is known. Additional force constraints (external
forces, SHAKE, etc) are applied by Fixes that have a post_force() method. The second half of the velocity-Verlet
integration, final_integrate() is then performed (another half-step update of the velocities) via fixes like nve, nvt,
npt.
At the end of the timestep, fixes that contain an end_of_step() method are invoked. These typically perform a
diagnostic calculation, e.g. the ave/time and ave/spatial fixes. The final operation of the timestep is to perform any
requested output, via the write() method of the Output class. There are 3 kinds of LAMMPS output: thermodynamic
output to the screen and log file, snapshots of atom data to a dump file, and restart files. See the thermo_style, dump,
and restart commands for more details.
The the flow of control during energy minimization iterations is similar to that of a molecular dynamics timestep.
Forces are computed, neighbor lists are built as needed, atoms migrate to new processors, and atom coordinates and
forces are communicated to neighboring processors. The only difference is what Fix class operations are invoked when.
Only a subset of LAMMPS fixes are useful during energy minimization, as explained in their individual doc pages.
The relevant Fix class methods are min_pre_exchange(), min_pre_force(), and min_post_force(). Each fix

564 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

is invoked at the appropriate place within the minimization iteration. For example, the min_post_force() method
is analogous to the post_force() method for dynamics; it is used to alter or constrain forces on each atom, which
affects the minimization procedure.
After all iterations are completed there is a cleanup step which calls the post_run() method of fixes to perform
operations only required at the end of a calculations (like freeing temporary storage or creating final outputs).

15.5 Writing new styles

The Modifying & extending LAMMPS section of the manual gives an overview of how LAMMPS can be extended
by writing new classes that derive from existing parent classes in LAMMPS. Here, some specific coding details are
provided for writing code for LAMMPS.

15.5.1 Writing a new fix style

Writing fixes is a flexible way of extending LAMMPS. Users can implement many things using fixes:
• changing particles attributes (positions, velocities, forces, etc.). Examples: FixNVE, FixFreeze.
• reading/writing data. Example: FixRestart.
• adding or modifying properties due to geometry. Example: FixWall.
• interacting with other subsystems or external code: Examples: FixTTM, FixExternal, FixLATTE
• saving information for analysis or future use (previous positions, for instance). Examples: Fix AveTime, FixS-
toreState.
All fixes are derived from the Fix base class and must have a constructor with the signature: FixPrintVel(class
LAMMPS *, int, char **).
Every fix must be registered in LAMMPS by writing the following lines of code in the header before include guards:

#ifdef FIX_CLASS
FixStyle(print/vel,FixPrintVel)
#else
/* the definition of the FixPrintVel class comes here */
...
#endif

Where print/vel is the style name of your fix in the input script and FixPrintVel is the name of the class. The
header file would be called fix_print_vel.h and the implementation file fix_print_vel.cpp. These conventions
allow LAMMPS to automatically integrate it into the executable when compiling and associate your new fix class with
the designated keyword when it parses the input script.
Let’s write a simple fix which will print the average velocity at the end of each timestep. First of all, implement a
constructor:

FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)

: Fix(lmp, narg, arg)
{
if (narg < 4)
error->all(FLERR,"Illegal fix print/vel command");

nevery = force->inumeric(FLERR,arg[3]);
(continues on next page)

15.5. Writing new styles 565

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

if (nevery <= 0)
error->all(FLERR,"Illegal fix print/vel command");
}

In the constructor you should parse your fix arguments which are specified in the script. All fixes have pretty much
the same syntax: fix <fix-ID> <fix group> <fix name> <fix arguments ...>. The first 3 parameters are
parsed by Fix base class constructor, while <fix arguments> should be parsed by you. In our case, we need to specify
how often we want to print an average velocity. For instance, once in 50 timesteps: fix 1 print/vel 50. There is a
special variable in the Fix class called nevery which specifies how often the method end_of_step() is called. Thus
all we need to do is just set it up.
The next method we need to implement is setmask():

int FixPrintVel::setmask()
{
int mask = 0;
mask |= FixConst::END_OF_STEP;
return mask;
}

Here the user specifies which methods of your fix should be called during execution. The constant END_OF_STEP
corresponds to the end_of_step() method. The most important available methods that are called during a timestep
and the order in which they are called are shown in the previous section.

void FixPrintVel::end_of_step()
{
// for add3, scale3
using namespace MathExtra;

double** v = atom->v;
int nlocal = atom->nlocal;
double localAvgVel[4]; // 4th element for particles count
memset(localAvgVel, 0, 4 * sizeof(double));
for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
add3(localAvgVel, v[particleInd], localAvgVel);
}
localAvgVel[3] = nlocal;
double globalAvgVel[4];
memset(globalAvgVel, 0, 4 * sizeof(double));
MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world);
scale3(1.0 / globalAvgVel[3], globalAvgVel);
if ((comm->me == 0) && screen) {
fmt::print(screen,"{}, {}, {}\n",
globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]);
}
}

In the code above, we use MathExtra routines defined in math_extra.h. There are bunch of math functions to work
with arrays of doubles as with math vectors. It is also important to note that LAMMPS code should always assume to
be run in parallel and that atom data is thus distributed across the MPI ranks. Thus you can only process data from
local atoms directly and need to use MPI library calls to combine or exchange data. For serial execution, LAMMPS
comes bundled with the MPI STUBS library that contains the MPI library function calls in dummy versions that only
work for a single MPI rank.

566 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

In this code we use an instance of Atom class. This object is stored in the Pointers class (see pointers.h) which is
the base class of the Fix base class. This object contains references to various class instances (the original instances
are created and held by the LAMMPS class) with all global information about the simulation system. Data from the
Pointers class is available to all classes inherited from it using protected inheritance. Hence when you write you own
class, which is going to use LAMMPS data, don’t forget to inherit from Pointers or pass an Pointer to it to all functions
that need access. When writing fixes we inherit from class Fix which is inherited from Pointers so there is no need to
inherit from it directly.
The code above computes average velocity for all particles in the simulation. Yet you have one unused parameter in
fix call from the script: group_name. This parameter specifies the group of atoms used in the fix. So we should
compute average for all particles in the simulation only if group_name == "all", but it can be any group. The group
membership information of an atom is contained in the mask property of and atom and the bit corresponding to a given
group is stored in the groupbit variable which is defined in Fix base class:

for (int i = 0; i < nlocal; ++i) {

if (atom->mask[i] & groupbit) {
// Do all job here
}
}

Class Atom encapsulates atoms positions, velocities, forces, etc. User can access them using particle index. Note,
that particle indexes are usually changed every few timesteps because of neighbor list rebuilds and spatial sorting (to
improve cache efficiency).
Let us consider another Fix example: We want to have a fix which stores atoms position from previous time step in your
fix. The local atoms indexes may not be valid on the next iteration. In order to handle this situation there are several
methods which should be implemented:
• double memory_usage(): return how much memory the fix uses (optional)
• void grow_arrays(int): do reallocation of the per particle arrays in your fix
• void copy_arrays(int i, int j, int delflag): copy i-th per-particle information to j-th. Used when
atom sorting is performed. if delflag is set and atom j owns a body, move the body information to atom i.
• void set_arrays(int i): sets i-th particle related information to zero
Note, that if your class implements these methods, it must call add calls of add_callback and delete_callback to con-
structor and destructor. Since we want to store positions of atoms from previous timestep, we need to add double**
xold to the header file. Than add allocation code to the constructor:

FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)

{
//...
memory->create(xold, atom->nmax, 3, "FixSavePos:x");
atom->add_callback(0);
}

FixSavePos::~FixSavePos() {
atom->delete_callback(id, 0);
memory->destroy(xold);
}

Implement the aforementioned methods:

double FixSavePos::memory_usage()
{
(continues on next page)

15.5. Writing new styles 567

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

int nmax = atom->nmax;
double bytes = 0.0;
bytes += nmax * 3 * sizeof(double);
return bytes;
}

void FixSavePos::grow_arrays(int nmax)

{
memory->grow(xold, nmax, 3, "FixSavePos:xold");
}

void FixSavePos::copy_arrays(int i, int j, int delflag)

{
memcpy(xold[j], xold[i], sizeof(double) * 3);
}

void FixSavePos::set_arrays(int i)
{
memset(xold[i], 0, sizeof(double) * 3);
}

int FixSavePos::pack_exchange(int i, double *buf)

{
int m = 0;
buf[m++] = xold[i][0];
buf[m++] = xold[i][1];
buf[m++] = xold[i][2];

return m;
}

int FixSavePos::unpack_exchange(int nlocal, double *buf)

{
int m = 0;
xold[nlocal][0] = buf[m++];
xold[nlocal][1] = buf[m++];
xold[nlocal][2] = buf[m++];

return m;
}

Now, a little bit about memory allocation. We use the Memory class which is just a bunch of template functions for
allocating 1D and 2D arrays. So you need to add include memory.h to have access to them.
Finally, if you need to write/read some global information used in your fix to the restart file, you might do it by setting flag
restart_global = 1 in the constructor and implementing methods void write_restart(FILE *fp) and void
restart(char *buf). If, in addition, you want to write the per-atom property to restart files additional settings and
functions are needed:
• a fix flag indicating this needs to be set restart_peratom = 1;
• atom->add_callback() and atom->delete_callback() must be called a second time with the final argu-
ment set to 1 instead of 0 (indicating restart processing instead of per-atom data memory management).
• the functions void pack_restart(int i, double *buf) and void unpack_restart(int nlocal,

568 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

int nth) need to be implemented

15.6 Notes for developers and code maintainers

This section documents how some of the code functionality within LAMMPS works at a conceptual level. Comments
on code in source files typically document what a variable stores, what a small section of code does, or what a function
does and its input/outputs. The topics on this page are intended to document code functionality at a higher level.

15.6.1 Fix contributions to instantaneous energy, virial, and cumulative energy

Fixes can calculate contributions to the instantaneous energy and/or virial of the system, both in a global and peratom
sense. Fixes that perform thermostatting or barostatting can calculate the cumulative energy they add to or subtract
from the system, which is accessed by the ecouple and econserve thermodynamic keywords. This subsection explains
how both work and what flags to set in a new fix to enable this functionality.
Let’s start with thermostatting and barostatting fixes. Examples are the fix langevin and fix npt commands. Here is
what the fix needs to do:
• Set the variable ecouple_flag = 1 in the constructor. Also set scalar_flag = 1, extscalar = 1, and global_freq to
a timestep increment which matches how often the fix is invoked.
• Implement a compute_scalar() method that returns the cumulative energy added or subtracted by the fix, e.g.
by rescaling the velocity of atoms. The sign convention is that subtracted energy is positive, added energy is
negative. This must be the total energy added to the entire system, i.e. an “extensive” quantity, not a per-atom
energy. Cumulative means the summed energy since the fix was instantiated, even across multiple runs. This is
because the energy is used by the econserve thermodynamic keyword to check that the fix is conserving the total
energy of the system, i.e. potential energy + kinetic energy + coupling energy = a constant.
And here is how the code operates:
• The Modify class makes a list of all fixes that set ecouple_flag = 1.
• The thermo_style custom command defines ecouple and econserve keywords.
• These keywords sum the energy contributions from all the ecouple_flag = 1 fixes by invoking the energy_couple()
method in the Modify class, which calls the compute_scalar() method of each fix in the list.

Next, here is how a fix contributes to the instantaneous energy and virial of the system. First, it sets any or all of these
flags to a value of 1 in their constructor:
• energy_global_flag to contribute to global energy, example: fix indent
• energy_peratom_flag to contribute to peratom energy, fix cmap
• virial_global_flag to contribute to global virial, example: fix wall
• virial_peratom_flag to contribute to peratom virial, example: fix wall
The fix must also do the following:
• For global energy, implement a compute_scalar() method that returns the energy added or subtracted on this
timestep. Here the sign convention is that added energy is positive, subtracted energy is negative.
• For peratom energy, invoke the ev_init(eflag,vflag) function each time the fix is invoked, which initializes per-
atom energy storage. The value of eflag may need to be stored from an earlier call to the fix during the same
timestep. See how the fix cmap command does this in src/MOLECULE/fix_cmap.cpp. When an energy for
one or more atoms is calculated, invoke the ev_tally() function to tally the contribution to each atom. Both the
ev_init() and ev_tally() methods are in the parent Fix class.

15.6. Notes for developers and code maintainers 569

LAMMPS Documentation, Release stable 29Sep2021

• For global and/or peratom virial, invoke the v_init(vflag) function each time the fix is invoked, which initializes
virial storage. When forces on one or more atoms are calculated, invoke the v_tally() function to tally the con-
tribution. Both the v_init() and v_tally() methods are in the parent Fix class. Note that there are several variants
of v_tally(); choose the one appropriate to your fix.

Note: The ev_init() and ev_tally() methods also account for global and peratom virial contributions. Thus you do not
need to invoke the v_init() and v_tally() methods, if the fix also calculates peratom energies.

The fix must also specify whether (by default) to include or exclude these contributions to the global/peratom en-
ergy/virial of the system. For the fix to include the contributions, set either of both of these variables in the constructor:
• thermo_energy = 1, for global and peratom energy
• thermo_virial = 1, for global and peratom virial
Note that these variables are zeroed in fix.cpp. Thus if you don’t set the variables, the contributions will be excluded
(by default)
However, the user has ultimate control over whether to include or exclude the contributions of the fix via the fix modify
command:
• fix modify energy yes to include global and peratom energy contributions
• fix modify virial yes to include global and peratom virial contributions
If the fix contributes to any of the global/peratom energy/virial values for the system, it should be explained on the fix
doc page, along with the default values for the energy yes/no and virial yes/no settings of the fix modify command.
Finally, these 4 contributions are included in the output of 4 computes:
• global energy in compute pe
• peratom energy in compute pe/atom
• global virial in compute pressure
• peratom virial in compute stress/atom
These computes invoke a method of the Modify class to include contributions from fixes that have the corresponding
flags set, e.g. energy_peratom_flag and thermo_energy for compute pe/atom.
Note that each compute has an optional keyword to either include or exclude all contributions from fixes. Also note
that compute pe and compute pressure are what is used (by default) by thermodynamic output to calculate values for
its pe and press keywords.

15.6.2 KSpace PPPM FFT grids

The various KSpace PPPM styles in LAMMPS use FFTs to solve Poisson’s equation. This subsection describes:
• how FFT grids are defined
• how they are decomposed across processors
• how they are indexed by each processor
• how particle charge and electric field values are mapped to/from the grid
An FFT grid cell is a 3d volume; grid points are corners of a grid cell and the code stores values assigned to grid points
in vectors or 3d arrays. A global 3d FFT grid has points indexed 0 to N-1 inclusive in each dimension.

570 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Each processor owns two subsets of the grid, each subset is brick-shaped. Depending on how it is used, these subsets
are allocated as a 1d vector or 3d array. Either way, the ordering of values within contiguous memory x fastest, then y,
z slowest.
For the 3d decomposition of the grid, the global grid is partitioned into bricks that correspond to the sub-domains
of the simulation box that each processor owns. Often, this is a regular 3d array (Px by Py by Pz) of bricks, where P
= number of processors = Px * Py * Pz. More generally it can be a tiled decomposition, where each processor owns a
brick and the union of all the bricks is the global grid. Tiled decompositions are produced by load balancing with the
RCB algorithm; see the balance rcb command.
For the FFT decompostion of the grid, each processor owns a brick that spans the entire x dimension of the grid while
the y and z dimensions are partitioned as a regular 2d array (P1 by P2), where P = P1 * P2.
The following indices store the inclusive bounds of the brick a processor owns, within the global grid:

nxlo_in,nxhi_in,nylo_in,nyhi_in,nzlo_in,nzhi_in = 3d decomposition brick

nxlo_fft,nxhi_fft,nylo_fft,nyhi_fft,nzlo_fft,nzhi_fft = FFT decomposition brick
nxlo_out,nxhi_out,nylo_out,nyhi_out,nzlo_out,nzhi_out = 3d decomposition brick + ghost␣
,→cells

The in and fft indices are from 0 to N-1 inclusive in each dimension, where N is the grid size.
The out indices index an array which stores the in subset of the grid plus ghost cells that surround it. These indices
can thus be < 0 or >= N.
The number of ghost cells a processor owns in each of the 6 directions is a function of:

neighbor skin distance (since atoms can move outside a proc subdomain)
qdist = offset or charge from atom due to TIP4P fictitious charge
order = mapping stencil size
shift = factor used when order is an even number (see below)

Here is an explanation of how the PPPM variables order, nlower / nupper, shift, and OFFSET work. They are the
relevant variables that determine how atom charge is mapped to grid points and how field values are mapped from grid
points to atoms:

order = # of nearby grid points in each dim that atom charge/field are mapped to/from
nlower,nupper = extent of stencil around the grid point an atom is assigned to
OFFSET = large integer added/subtracted when mapping to avoid int(-0.75) = 0 when -1 is␣
,→the desired result

The particle_map() method assigns each atom to a grid point.

If order is even, say 4:

atom is assigned to grid point to its left (in each dim)

shift = OFFSET
nlower = -1, nupper = 2, which are offsets from assigned grid point
window of mapping grid pts is thus 2 grid points to left of atom, 2 to right

If order is odd, say 5:

atom is assigned to left/right grid pt it is closest to (in each dim)

shift = OFFSET + 0.5
nlower = 2, nupper = 2
(continues on next page)

15.6. Notes for developers and code maintainers 571

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

if point is in left half of cell, then window of affected grid pts is 3 grid points to␣
,→left of atom, 2 to right

if point is in right half of cell, then window of affected grid pts is 2 grid points to␣
,→left of atom, 3 to right

These settings apply to each dimension, so that if order = 5, an atom’s charge is mapped to 125 grid points that surround
the atom.

15.7 Writing plugins

Plugins provide a mechanism to add functionality to a LAMMPS executable without recompiling LAMMPS. The
functionality for this and the plugin command are implemented in the PLUGIN package which must be installed to use
plugins.
Plugins use the operating system’s capability to load dynamic shared object (DSO) files in a way similar shared libraries
and then reference specific functions in those DSOs. Any DSO file with plugins has to include an initialization function
with a specific name, “lammpsplugin_init”, that has to follow specific rules described below. When loading the DSO
with the “plugin” command, this function is looked up and called and will then register the contained plugin(s) with
LAMMPS.
From the programmer perspective this can work because of the object oriented design of LAMMPS where all pair
style commands are derived from the class Pair, all fix style commands from the class Fix and so on and usually only
functions present in those base classes are called directly. When a pair_style command command or fix command
command is issued a new instance of such a derived class is created. This is done by a so-called factory function which
is mapped to the style name. Thus when, for example, the LAMMPS processes the command pair_style lj/cut
2.5, LAMMPS will look up the factory function for creating the PairLJCut class and then execute it. The return
value of that function is a Pair * pointer and the pointer will be assigned to the location for the currently active pair
style.
A DSO file with a plugin thus has to implement such a factory function and register it with LAMMPS so that it gets
added to the map of available styles of the given category. To register a plugin with LAMMPS an initialization function
has to be present in the DSO file called lammpsplugin_init which is called with three void * arguments: a pointer
to the current LAMMPS instance, a pointer to the opened DSO handle, and a pointer to the registration function. The
registration function takes two arguments: a pointer to a lammpsplugin_t struct with information about the plugin
and a pointer to the current LAMMPS instance. Please see below for an example of how the registration is done.

15.7.1 Members of lammpsplugin_t

Member Description
version LAMMPS Version string the plugin was compiled for
style Style of the plugin (pair, bond, fix, command, etc.)
name Name of the plugin style
info String with information about the plugin
author String with the name and email of the author
creator.v1 Pointer to factory function for pair, bond, angle, dihedral, improper or command styles
creator.v2 Pointer to factory function for compute, fix, or region styles
handle Pointer to the open DSO file handle

Only one of the three alternate creator entries can be used at a time and which of those is determined by the style
of plugin. The “creator.v1” element is for factory functions of supported styles computing forces (i.e. command,

572 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

pair, bond, angle, dihedral, or improper styles) and the function takes as single argument the pointer to the LAMMPS
instance. The factory function is cast to the lammpsplugin_factory1 type before assignment. The “creator.v2”
element is for factory functions creating an instance of a fix, compute, or region style and takes three arguments: a
pointer to the LAMMPS instance, an integer with the length of the argument list and a char ** pointer to the list of
arguments. The factory function pointer needs to be cast to the lammpsplugin_factory2 type before assignment.

15.7.2 Pair style example

As an example, a hypothetical pair style plugin “morse2” implemented in a class PairMorse2 in the files
pair_morse2.h and pair_morse2.cpp with the factory function and initialization function would look like this:

#include "lammpsplugin.h"
#include "version.h"
#include "pair_morse2.h"

using namespace LAMMPS_NS;

static Pair *morse2creator(LAMMPS *lmp)

{
return new PairMorse2(lmp);
}

extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)

{
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
lammpsplugin_t plugin;

plugin.version = LAMMPS_VERSION;
plugin.style = "pair";
plugin.name = "morse2";
plugin.info = "Morse2 variant pair style v1.0";
plugin.author = "Axel Kohlmeyer ([email protected])";
plugin.creator.v1 = (lammpsplugin_factory1 *) &morse2creator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}

The factory function in this example is called morse2creator(). It receives a pointer to the LAMMPS class
as only argument and thus has to be assigned to the creator.v1 member of the plugin struct and cast to the
lammpsplugin_factory1 function pointer type. It returns a pointer to the allocated class instance derived from
the Pair class. This function may be declared static to avoid clashes with other plugins. The name of the derived class,
PairMorse2, however must be unique inside the entire LAMMPS executable.

15.7. Writing plugins 573

LAMMPS Documentation, Release stable 29Sep2021

15.7.3 Fix style example

If the factory function would be for a fix or compute, which take three arguments (a pointer to the LAMMPS class, the
number of arguments and the list of argument strings), then the pointer type is lammpsplugin_factory2 and it must
be assigned to the creator.v2 member of the plugin struct. Below is an example for that:

#include "lammpsplugin.h"
#include "version.h"
#include "fix_nve2.h"

using namespace LAMMPS_NS;

static Fix *nve2creator(LAMMPS *lmp, int argc, char **argv)

{
return new FixNVE2(lmp,argc,argv);
}

extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)

{
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
lammpsplugin_t plugin;

plugin.version = LAMMPS_VERSION;
plugin.style = "fix";
plugin.name = "nve2";
plugin.info = "NVE2 variant fix style v1.0";
plugin.author = "Axel Kohlmeyer ([email protected])";
plugin.creator.v2 = (lammpsplugin_factory2 *) &nve2creator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}

15.7.4 Command style example

Command styles also use the first variant of factory function as demonstrated in the following example, which also
shows that the implementation of the plugin class may be within the same source file as the plugin interface code:

#include "lammpsplugin.h"

#include "comm.h"
#include "error.h"
#include "command.h"
#include "version.h"

#include <cstring>

namespace LAMMPS_NS {
class Hello : public Command {
public:
Hello(class LAMMPS *lmp) : Command(lmp) {};
void command(int, char **);
};
(continues on next page)

574 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

}

using namespace LAMMPS_NS;

void Hello::command(int argc, char **argv)

{
if (argc != 1) error->all(FLERR,"Illegal hello command");
if (comm->me == 0)
utils::logmesg(lmp,fmt::format("Hello, {}!\n",argv[0]));
}

static void hellocreator(LAMMPS *lmp)

{
return new Hello(lmp);
}

extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)

{
lammpsplugin_t plugin;
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;

plugin.version = LAMMPS_VERSION;
plugin.style = "command";
plugin.name = "hello";
plugin.info = "Hello world command v1.1";
plugin.author = "Axel Kohlmeyer ([email protected])";
plugin.creator.v1 = (lammpsplugin_factory1 *) &hellocreator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}

15.7.5 Additional Details

The initialization function must be called lammpsplugin_init, it must have C bindings and it takes three void
pointers as arguments. The first is a pointer to the LAMMPS class that calls it and it needs to be passed to the registration
function. The second argument is a pointer to the internal handle of the DSO file, this needs to be added to the plugin
info struct, so that the DSO can be closed and unloaded when all its contained plugins are unloaded. The third argument
is a function pointer to the registration function and needs to be stored in a variable of lammpsplugin_regfunc type
and then called with a pointer to the lammpsplugin_t struct and the pointer to the LAMMPS instance as arguments
to register a single plugin. There may be multiple calls to multiple plugins in the same initialization function.
To register a plugin a struct of the lammpsplugin_t needs to be filled with relevant info: current LAMMPS version
string, kind of style, name of style, info string, author string, pointer to factory function, and the DSO handle. The
registration function is called with a pointer to the address of this struct and the pointer of the LAMMPS class. The
registration function will then add the factory function of the plugin style to the respective style map under the provided
name. It will also make a copy of the struct in a list of all loaded plugins and update the reference counter for loaded
plugins from this specific DSO file.
The pair style itself (i.e. the PairMorse2 class in this example) can be written just like any other pair style that is included
in LAMMPS. For a plugin, the use of the PairStyle macro in the section encapsulated by #ifdef PAIR_CLASS is
not needed, since the mapping of the class name to the style name is done by the plugin registration function with the
information from the lammpsplugin_t struct. It may be included in case the new code is intended to be later included

15.7. Writing plugins 575

LAMMPS Documentation, Release stable 29Sep2021

in LAMMPS directly.

15.8 Adding tests for unit testing

This section discusses adding or expanding tests for the unit test infrastructure included into the LAMMPS source code
distribution. Unlike example inputs, unit tests focus on testing the “local” behavior of individual features, tend to run
fast, and should be set up to cover as much of the added code as possible. When contributing code to the distribution,
the LAMMPS developers will appreciate if additions to the integrated unit test facility are included.
Given the complex nature of MD simulations where many operations can only be performed when suitable “real”
simulation environment has been set up, not all tests will be unit tests in the strict definition of the term. They are rather
executed on a more abstract level by issuing LAMMPS script commands and then inspecting the changes to the internal
data. For some classes of tests, generic test programs have been written that can be applied to parts of LAMMPS that
use the same interface (via polymorphism) and those are driven by input files, so tests can be added by simply adding
more of those input files. Those tests should be seen more as a hybrid between unit and regression tests.
When adding tests it is recommended to also enable support for code coverage reporting, and study the coverage reports
so that it is possible to monitor which parts of the code of a given file are executed during the tests and which tests
would need to be added to increase the coverage.
The tests are grouped into categories and corresponding folders. The following sections describe how the tests are
implemented and executed in those categories with increasing complexity of tests and implementation.

15.8.1 Tests for utility functions

These tests are driven by programs in the unittest/utils folder and most closely resemble conventional unit tests.
There is one test program for each namespace or group of classes or file. The naming convention for the sources and
executables is that they start with with test_. The following sources and groups of tests are currently available:

File name: Test name: Description:

test_argutils.cpp ArgInfo Tests for ArgInfo class used by LAMMPS
test_fmtlib.cpp FmtLib Tests for fmtlib:: functions used by LAMMPS
test_math_eigen_impl.cpp MathEigen Tests for MathEigen:: classes and functions
test_mempool.cpp MemPool Tests for MyPage and MyPoolChunk
test_tokenizer.cpp Tokenizer Tests for Tokenizer and ValueTokenizer
test_utils.cpp Utils Tests for utils:: functions

To add tests either an existing source file needs to be modified or a new source file needs to be added to the distribution
and enabled for testing. To add a new file suitable CMake script code needs to be added to the CMakeLists.txt file
in the unittest/utils folder. Example:

add_executable(test_tokenizer test_tokenizer.cpp)
target_link_libraries(test_tokenizer PRIVATE lammps GTest::GMockMain GTest::GMock␣
,→GTest::GTest)

add_test(Tokenizer test_tokenizer)

This adds instructions to build the test_tokenizer executable from test_tokenizer.cpp and links it with the
GoogleTest libraries and the LAMMPS library as well as it uses the main() function from the GoogleMock library of
GoogleTest. The third line registers the executable as a test program to be run from ctest under the name Tokenizer.
The test executable itself will execute multiple individual tests through the GoogleTest framework. In this case each
test consists of creating a tokenizer class instance with a given string and explicit or default separator choice, and then
executing member functions of the class and comparing their results with expected values. A few examples:

576 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

TEST(Tokenizer, empty_string)
{
Tokenizer t("", " ");
ASSERT_EQ(t.count(), 0);
}

TEST(Tokenizer, two_words)
{
Tokenizer t("test word", " ");
ASSERT_EQ(t.count(), 2);
}

TEST(Tokenizer, default_separators)
{
Tokenizer t(" \r\n test \t word \f");
ASSERT_THAT(t.next(), Eq("test"));
ASSERT_THAT(t.next(), Eq("word"));
ASSERT_EQ(t.count(), 2);
}

Each of these TEST functions will become an individual test run by the test program. When using the ctest command
as a front end to run the tests, their output will be suppressed and only a summary printed, but adding the ‘-V’ option
will then produce output from the tests above like the following:

[...]
1: [ RUN ] Tokenizer.empty_string
1: [ OK ] Tokenizer.empty_string (0 ms)
1: [ RUN ] Tokenizer.two_words
1: [ OK ] Tokenizer.two_words (0 ms)
1: [ RUN ] Tokenizer.default_separators
1: [ OK ] Tokenizer.default_separators (0 ms)
[...]

The MathEigen test collection has been adapted from a standalone test and does not use the GoogleTest framework and
thus not representative. The other test sources, however, can serve as guiding examples for additional tests.

15.8.2 Tests for individual LAMMPS commands

The tests unittest/commands are a bit more complex as they require to first create a LAMMPS class instance and then
use the C++ API to pass individual commands to that LAMMPS instance. For that reason these tests use a GoogleTest
“test fixture”, i.e. a class derived from testing::Test that will create (and delete) the required LAMMPS class
instance for each set of tests in a TEST_F() function. Please see the individual source files for different examples of
setting up suitable test fixtures. Here is an example for implementing a test using a fixture by first checking the default
value and then issuing LAMMPS commands and checking whether they have the desired effect:

TEST_F(SimpleCommandsTest, ResetTimestep)
{
ASSERT_EQ(lmp->update->ntimestep, 0);

BEGIN_HIDE_OUTPUT();
command("reset_timestep 10");
END_HIDE_OUTPUT();
(continues on next page)

15.8. Adding tests for unit testing 577

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

ASSERT_EQ(lmp->update->ntimestep, 10);

BEGIN_HIDE_OUTPUT();
command("reset_timestep 0");
END_HIDE_OUTPUT();
ASSERT_EQ(lmp->update->ntimestep, 0);

TEST_FAILURE(".*ERROR: Timestep must be >= 0.*", command("reset_timestep -10"););

TEST_FAILURE(".*ERROR: Illegal reset_timestep .*", command("reset_timestep"););
TEST_FAILURE(".*ERROR: Illegal reset_timestep .*", command("reset_timestep 10 10"););
TEST_FAILURE(".*ERROR: Expected integer .*", command("reset_timestep xxx"););
}

Please note the use of the BEGIN_HIDE_OUTPUT and END_HIDE_OUTPUT functions that will capture output from run-
ning LAMMPS. This is normally discarded but by setting the verbose flag (via setting the TEST_ARGS environment
variable, TEST_ARGS=-v) it can be printed and used to understand why tests fail unexpectedly.
Another complexity of these tests stems from the need to capture situations where LAMMPS will stop with an error,
i.e. handle so-called “death tests”. Here the LAMMPS code will operate differently depending on whether it was
configured to throw C++ exceptions on errors or call either exit() or MPI_Abort(). In the latter case, the test code
also needs to detect whether LAMMPS was compiled with the OpenMPI library, as OpenMPI is only compatible the
death test options of the GoogleTest library when C++ exceptions are enabled; otherwise those “death tests” must be
skipped to avoid reporting bogus failures. The specifics of this step are implemented in the TEST_FAILURE() macro.
These tests operate by capturing the screen output when executing the failing command and then comparing that with
a provided regular expression string pattern. Example:

TEST_F(SimpleCommandsTest, UnknownCommand)
{
TEST_FAILURE(".*ERROR: Unknown command.*", lmp->input->one("XXX one two"););
}

The following test programs are currently available:

File name: Test name: Description:

test_simple_commands. SimpleCom- Tests for LAMMPS commands that do not require a box
cpp mands
test_lattice_region. LatticeRegion Tests to validate the lattice and region commands
cpp
test_groups.cpp GroupTest Tests to validate the group command
test_variables.cpp VariableTest Tests to validate the variable command
test_kim_commands.cpp KimCommands Tests for several commands from the KIM package
test_reset_ids.cpp ResetIDs Tests to validate the reset_atom_ids and reset_mol_ids com-
mands

578 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

15.8.3 Tests for the C-style library interface

Tests for validating the LAMMPS C-style library interface are in the unittest/c-library folder. They are imple-
mented in either way used for utility functions and for LAMMPS commands, but use the functions implemented in the
src/library.cpp file as much as possible. There may be some overlap with other tests, but only in as much as is
required to test the C-style library API. The tests are distributed over multiple test programs which tries to match the
grouping of the functions in the source code and in the manual.
This group of tests also includes tests invoking LAMMPS in parallel through the library interface, provided that
LAMMPS was compiled with MPI support. These include tests where LAMMPS is run in multi-partition mode or
only on a subset of the MPI world communicator. The CMake script code for adding this kind of test looks like this:

if (BUILD_MPI)
add_executable(test_library_mpi test_library_mpi.cpp)
target_link_libraries(test_library_mpi PRIVATE lammps GTest::GTest GTest::GMock)
target_compile_definitions(test_library_mpi PRIVATE ${TEST_CONFIG_DEFS})
add_mpi_test(NAME LibraryMPI NUM_PROCS 4 COMMAND $<TARGET_FILE:test_library_mpi>)
endif()

Note the custom function add_mpi_test() which adapts how ctest will execute the test so it is launched in parallel
(with 4 MPI ranks).

15.8.4 Tests for the Python module and package

The unittest/python folder contains primarily tests for classes and functions in the LAMMPS python module but
also for commands in the PYTHON package. These tests are only enabled, if the necessary prerequisites are detected
or enabled during configuration and compilation of LAMMPS (shared library build enabled, Python interpreter found,
Python development files found).
The Python tests are implemented using the unittest standard Python module and split into multiple files with similar
categories as the tests for the C-style library interface.

15.8.5 Tests for the Fortran interface

Tests for using the Fortran module are in the unittest/fortran folder. Since they are also using the GoogleTest
library, they require to also implement test wrappers in C++ that will call fortran functions which provide a C function
interface through ISO_C_BINDINGS that will in turn call the functions in the LAMMPS Fortran module. This part
of the unit tests is incomplete since the Fortran module it is based on is incomplete as well.

15.8.6 Tests for the C++-style library interface

The tests in the unittest/cplusplus folder are somewhat similar to the tests for the C-style library interface, but
do not need to test the several convenience and utility functions that are only available through the C-style interface.
Instead it can focus on the more generic features that are used internally. This part of the unit tests is currently still
mostly in the planning stage.

15.8. Adding tests for unit testing 579

LAMMPS Documentation, Release stable 29Sep2021

15.8.7 Tests for reading and writing file formats

The unittest/formats folder contains test programs for reading and writing files like data files, restart files, potential
files or dump files. This covers simple things like the file i/o convenience functions in the utils:: namespace to
complex tests of atom styles where creating and deleting of atoms with different properties is tested in different ways
and through script commands or reading and writing of data or restart files.

15.8.8 Tests for styles computing or modifying forces

These are tests common configurations for pair styles, bond styles, angle styles, kspace styles and certain fix styles.
Those are tests driven by some test executables build from sources in the unittest/force-styles folder and use
LAMMPS input template and data files as well as input files in YAML format from the unittest/force-styles/
tests folder. The YAML file names have to follow some naming conventions so they get associated with the test
programs and categorized and listed with canonical names in the list of tests as displayed by ctest -N. If you add a
new YAML file, you need to re-run CMake to update the corresponding list of tests.
A minimal YAML file for a (molecular) pair style test will looks something like the following (see mol-pair-zero.
yaml):

---
lammps_version: 24 Aug 2020
date_generated: Tue Sep 15 09:44:21 202
epsilon: 1e-14
prerequisites: ! |
atom full
pair zero
pre_commands: ! ""
post_commands: ! ""
input_file: in.fourmol
pair_style: zero 8.0
pair_coeff: ! |
* *
extract: ! ""
natoms: 29
init_vdwl: 0
init_coul: 0

[...]

The following table describes the available keys and their purpose for testing pair styles:

580 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Key: Description:
lammps_version LAMMPS version used to last update the reference data
date_generated date when the file was last updated
epsilon base value for the relative precision required for tests to pass
prerequisites list of style kind / style name pairs required to run the test
pre_commands LAMMPS commands to be executed before the input template file is read
post_commands LAMMPS commands to be executed right before the actual tests
input_file LAMMPS input file template based on pair style zero
pair_style arguments to the pair_style command to be tested
pair_coeff list of pair_coeff arguments to set parameters for the input template
extract list of keywords supported by Pair::extract() and their dimension
natoms number of atoms in the input file template
init_vdwl non-Coulomb pair energy after “run 0”
init_coul Coulomb pair energy after “run 0”
init_stress stress tensor after “run 0”
init_forces forces on atoms after “run 0”
run_vdwl non-Coulomb pair energy after “run 4”
run_coul Coulomb pair energy after “run 4”
run_stress stress tensor after “run 4”
run_forces forces on atoms after “run 4”

The test program will read all this data from the YAML file and then create a LAMMPS instance, apply the set-
tings/commands from the YAML file as needed and then issue a “run 0” command, write out a restart file, a data file
and a coeff file. The actual test will then compare computed energies, stresses, and forces with the reference data, issue
a “run 4” command and compare to the second set of reference data. This will be run with both the newton_pair setting
enabled and disabled and is expected to generate the same results (allowing for some numerical noise). Then it will
restart from the previously generated restart and compare with the reference and also start from the data file. A final
check will use multi-cutoff r-RESPA (if supported by the pair style) at a 1:1 split and compare to the Verlet results.
These sets of tests are run with multiple test fixtures for accelerated styles (OPT, OPENMP, INTEL) and for the latter
two with 4 OpenMP threads enabled. For these tests the relative error (epsilon) is lowered by a common factor due to
the additional numerical noise, but the tests are still comparing to the same reference data.
Additional tests will check whether all listed extract keywords are supported and have the correct dimensionality and
the final set of tests will set up a few pairs of atoms explicitly and in such a fashion that the forces on the atoms computed
from Pair::compute() will match individually with the results from Pair::single(), if the pair style does support
that functionality.
With this scheme a large fraction of the code of any tested pair style will be executed and consistent results are required
for different settings and between different accelerated pair style variants and the base class, as well as for computing
individual pairs through the Pair::single() where supported.
The test_pair_style tester is used with 4 categories of test inputs:
• pair styles compatible with molecular systems using bonded interactions and exclusions. For pair styles requiring
a KSpace style the KSpace computations are disabled. The YAML files match the pattern “mol-pair-*.yaml” and
the tests are correspondingly labeled with “MolPairStyle:*”
• pair styles not compatible with the previous input template. The YAML files match the pattern “atomic-pair-
*.yaml” and the tests are correspondingly labeled with “AtomicPairStyle:*”
• manybody pair styles. The YAML files match the pattern “atomic-pair-*.yaml” and the tests are correspondingly
labeled with “AtomicPairStyle:*”
• kspace styles. The YAML files match the pattern “kspace-*.yaml” and the tests are correspondingly labeled
with “KSpaceStyle:*”. In these cases a compatible pair style is defined, but the computation of the pair style
contributions is disabled.

15.8. Adding tests for unit testing 581

LAMMPS Documentation, Release stable 29Sep2021

The test_bond_style and test_angle_style are set up in a similar fashion and share support functions with the
pair style tester. The final group of tests in this section is for fix styles that add/manipulate forces and velocities, e.g.
for time integration, thermostats and more.
Adding a new test is easiest done by copying and modifying an existing test for a style that is similar to one to be
tested. The file name should follow the naming conventions described above and after copying the file, the first step
is to replace the style names where needed. The coefficient values do not have to be meaningful, just in a reasonable
range for the given system. It does not matter if some forces are large, for as long as they do not diverge.
The template input files define a large number of index variables at the top that can be modified inside the YAML file
to control the behavior. For example, if a pair style requires a “newton on” setting, the following can be used in as the
“pre_commands” section:

pre_commands: ! |
variable newton_pair delete
variable newton_pair index on

And for a pair style requiring a kspace solver the following would be used as the “post_commands” section:

post_commands: ! |
pair_modify table 0
kspace_style pppm/tip4p 1.0e-6
kspace_modify gewald 0.3
kspace_modify compute no

Note that this disables computing the kspace contribution, but still will run the setup. The “gewald” parameter should
be set explicitly to speed up the run. For styles with long-range electrostatics, typically two tests are added one using
the (slower) analytic approximation of the erfc() function and the other using the tabulated coulomb, to test both code
paths. The reference results in the YAML files then should be compared manually, if they agree well enough within
the limits of those two approximations.
The test_pair_style and equivalent programs have special command line options to update the YAML files. Run-
ning a command like

$ test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml

will read the settings from the mol-pair-lennard_mdf.yaml file and then compute the reference data and write a
new file with to new.yaml. If this step fails, there are likely some (LAMMPS or YAML) syntax issues in the YAML
file that need to be resolved and then one can compare the two files to see if the output is as expected.
It is also possible to do an update in place with:

$ test_pair_style mol-pair-lennard_mdf.yaml -u

And one can finally run the full set of tests with:

$ test_pair_style mol-pair-lennard_mdf.yaml

This will just print a summary of the groups of tests. When using the “-v” flag the test will also keep any LAMMPS
output and when using the “-s” flag, there will be some statistics reported on the relative errors for the individual checks
which can help to figure out what would be a good choice of the epsilon parameter. It should be as small as possible to
catch any unintended side effects from changes elsewhere, but large enough to accommodate the numerical noise due
to the implementation of the potentials and differences in compilers.

Note: These kinds of tests can be very sensitive to compiler optimization and thus the expectation is that they pass
with compiler optimization turned off. When compiler optimization is enabled, there may be some failures, but one

582 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

has to carefully check whether those are acceptable due to the enhanced numerical noise from reordering floating-point
math operations or due to the compiler mis-compiling the code. That is not always obvious.

15.8.9 Tests for programs in the tools folder

The unittest/tools folder contains tests for programs in the tools folder. This currently only contains tests for
the LAMMPS shell, which are implemented as a python scripts using the unittest Python module and launching the
tool commands through the subprocess Python module.

15.9 C++ base classes

LAMMPS is designed to be used as a C++ class library where one can set up and drive a simulation through creating
a class instance and then calling some abstract operations or commands on that class or its member class instances.
These are interfaced to the C library API, which providing an additional level of abstraction simplification for common
operations. The C API is also the basis for calling LAMMPS from Python or Fortran.
When used from a C++ program, most of the symbols and functions in LAMMPS are wrapped into the LAMMPS_NS
namespace so they will not collide with your own classes or other libraries. This, however, does not extend to the
additional libraries bundled with LAMMPS in the lib folder and some of the low-level code of some packages.
Behind the scenes this is implemented through inheritance and polymorphism where base classes define the abstract
interface and derived classes provide the specialized implementation for specific models or optimizations or ports to
accelerator platforms. This document will provide an outline of the fundamental class hierarchy and some selected
examples for derived classes of specific models.

Note: Please see the note about thread-safety in the library Howto doc page.

15.9.1 LAMMPS Class

The LAMMPS class is encapsulating an MD simulation state and thus it is the class that needs to be created when
starting a new simulation system state. The LAMMPS executable essentially creates one instance of this class and
passes the command line flags and tells it to process the provided input (a file or stdin). It shuts the class down when
control is returned to it and then exits. When using LAMMPS as a library from another code it is required to create an
instance of this class, either directly from C++ with new LAMMPS() or through one of the library interface functions
like lammps_open() of the C-library interface, or the lammps.lammps class constructor of the Python module, or the
lammps() constructor of the Fortran module.
In order to avoid clashes of function names, all of the core code in LAMMPS is placed into the LAMMPS_NS namespace.
Functions or variables outside of that namespace must be “static”, i.e. visible only to the scope of the file/object they
are defined in. Code in packages or the libraries in the lib folder may not adhere to this as some of them are adapted
from legacy code or consist of external libraries with their own requirements and policies.

class LAMMPS_NS::LAMMPS
LAMMPS simulation instance.
The LAMMPS class contains pointers of all constituent class instances and global variables that are used by a
LAMMPS simulation. Its contents represent the entire state of the simulation.

15.9. C++ base classes 583

LAMMPS Documentation, Release stable 29Sep2021

The LAMMPS class manages the components of an MD simulation by creating, deleting, and initializing in-
stances of the classes it is composed of, processing command line flags, and providing access to some global
properties. The specifics of setting up and running a simulation are handled by the individual component class
instances.

Public Functions

const char *match_style(const char *style, const char *name)

Return name of package that a specific style belongs to.
This function checks the given name against all list of styles for all type of styles and if the name and the
style match, it returns which package this style belongs to.
Parameters
• style – Type of style (e.g. atom, pair, fix, etc.)
• name – Name of style
Returns Name of the package this style is part of
LAMMPS(int, char**, MPI_Comm)
Create a LAMMPS simulation instance
The LAMMPS constructor starts up a simulation by allocating all fundamental classes in the necessary
order, parses input switches and their arguments, initializes communicators, screen and logfile output FILE
pointers.
Parameters
• narg – number of arguments
• arg – list of arguments
• communicator – MPI communicator used by this LAMMPS instance
~LAMMPS()
Shut down a LAMMPS simulation instance
The LAMMPS destructor shuts down the simulation by deleting top-level class instances, closing screen
and log files for the global instance (aka “world”) and files and MPI communicators in sub-partitions (“uni-
verses”). Then it deletes the fundamental class instances and copies of data inside the class.

Public Static Functions

static bool is_installed_pkg(const char *pkg)

Return true if a LAMMPS package is enabled in this binary
Parameters pkg – name of package
Returns true if yes, else false

class Pointers
Base class for LAMMPS features.
The Pointers class contains references to many of the pointers and members of the LAMMPS_NS::LAMMPS
class. Derived classes thus gain access to the constituent class instances in the LAMMPS composite class and
thus to the core functionality of LAMMPS.

584 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

This kind of construct is needed, since the LAMMPS constructor should only be run once per LAMMPS instance
and thus classes cannot be derived from LAMMPS itself. The Pointers class constructor instead only initializes
C++ references to component pointer in the LAMMPS class.
Subclassed by Atom, Input, PotentialFileReader

15.9.2 LAMMPS Atom and AtomVec Base Classes

class LAMMPS_NS::Atom : protected Pointers

Class to provide access to atom data.

The Atom class provides access to atom style related global settings and per-atom data that is stored with atoms
and migrates with them from sub-domain to sub-domain as atoms move around. This includes topology data,
which is stored with either one specific atom or all atoms involved depending on the settings of the newton
command.
The actual per-atom data is allocated and managed by one of the various classes derived from the AtomVec class
as determined by the atom_style command. The pointers in the Atom class are updated by the AtomVec class as
needed.

Public Functions

Atom(class LAMMPS*)
Atom class constructor
This resets and initialized all kinds of settings, parameters, and pointer variables for per-atom arrays. This
also initializes the factory for creating instances of classes derived from the AtomVec base class, which
correspond to the selected atom style.
Parameters lmp – pointer to the base LAMMPS class
virtual int add_custom(const char*, int, int)
Add a custom per-atom property with the given name and type and size.

This function will add a custom per-atom property with one or more values with the name “name” to the
list of custom properties. This function is called, e.g. from fix property/atom.

Parameters
• name – Name of the property (w/o a “i_” or “d_” or “i2_” or “d2_” prefix)
• flag – Data type of property: 0 for int, 1 for double
• cols – Number of values: 0 for a single value, 1 or more for a vector of values
Returns index of property in the respective list of properties

virtual void remove_custom(int, int, int)

Remove a custom per-atom property of a given type and size.

15.9. C++ base classes 585

LAMMPS Documentation, Release stable 29Sep2021

This will remove a property that was requested, e.g. by the fix property/atom command. It frees the allocated
memory and sets the pointer to nullptr for the entry in the list so it can be reused. The lists of these pointers
are never compacted or shrink, so that indices to name mappings remain valid.

Parameters
• index – Index of property in the respective list of properties
• flag – Data type of property: 0 for int, 1 for double
• cols – Number of values: 0 for a single value, 1 or more for a vector of values

void *extract(const char*)

Provide access to internal data of the Atom class by keyword

This function is a way to access internal per-atom data. This data is distributed across MPI ranks and thus
only the data for “local” atoms are expected to be available. Whether also data for “ghost” atoms is stored
and up-to-date depends on various simulation settings.
This table lists a large part of the supported names, their data types, length of the data area, and a short
description.

586 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Name Type Items per Description

atom
mass dou- 1 per-type mass. This array is NOT a per-atom array but of length
ble ntypes+1, element 0 is ignored.
id tagint 1 atom ID of the particles
type int 1 atom type of the particles
mask int 1 bitmask for mapping to groups. Individual bits are set to 0 or 1 for
each group.
image im- 1 3 image flags encoded into a single integer. See
ageint lammps_encode_image_flags().
x dou- 3 x-, y-, and z-coordinate of the particles
ble
v dou- 3 x-, y-, and z-component of the velocity of the particles
ble
f dou- 3 x-, y-, and z-component of the force on the particles
ble
molecule int 1 molecule ID of the particles
q dou- 1 charge of the particles
ble
mu dou- 3 dipole moment of the particles
ble
omega dou- 3 x-, y-, and z-component of rotational velocity of the particles
ble
angmom dou- 3 x-, y-, and z-component of angular momentum of the particles
ble
torque dou- 3 x-, y-, and z-component of the torque on the particles
ble
radius dou- 1 radius of the (extended) particles
ble
rmass dou- 1 per-atom mass of the particles. nullptr if per-type masses are used.
ble See the rmass_flag setting.
ellip- int 1 1 if the particle is an ellipsoidal particle, 0 if not
soid
line int 1 1 if the particle is a line particle, 0 if not
tri int 1 1 if the particle is a triangulated particle, 0 if not
body int 1 1 if the particle is a body particle, 0 if not
i_name int 1 single integer value defined by fix property/atom vector name
d_name dou- 1 single double value defined by fix property/atom vector name
ble
i2_name int n N integer values defined by fix property/atom array name
d2_name dou- n N double values defined by fix property/atom array name
ble

See also lammps_extract_atom()

See extract_datatype

Parameters name – string with the keyword of the desired property. Typically the name of the
pointer variable returned
Returns pointer to the requested data cast to void * or nullptr

15.9. C++ base classes 587

LAMMPS Documentation, Release stable 29Sep2021

int extract_datatype(const char*)

Provide data type info about internal data of the Atom class

New in version 18Sep2020.

See extract

Parameters name – string with the keyword of the desired property.

Returns data type constant for desired property or -1

struct PerAtom

15.9.3 LAMMPS Input Base Class

class LAMMPS_NS::Input : protected Pointers

Class for processing commands and input files.

The Input class contains methods for reading, pre-processing and parsing LAMMPS commands and input files
and will dispatch commands to the respective class instances or contains the code to execute the commands
directly. It also contains the instance of the Variable class which performs computations and text substitutions.

Public Functions

Input(class LAMMPS*, int, char**)

Input class constructor

This sets up the input processing, processes the -var and -echo command line flags, holds the factory of
commands and creates and initializes an instance of the Variable class.
To execute a command, a specific class instance, derived from Command, is created, then its command()
member function executed, and finally the class instance is deleted.

Parameters
• lmp – pointer to the base LAMMPS class
• argc – number of entries in argv
• argv – argument vector

void file()
Process all input from the FILE * pointer infile

This will read lines from infile, parse and execute them until the end of the file is reached. The infile pointer
will usually point to stdin or the input file given with the -in command line flag.

588 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

void file(const char*)

Process all input from the file filename
This function opens the file at the path filename, put the current file pointer stored in infile on a stack and
instead assign infile with the newly opened file pointer. Then it will call the Input::file() function to
read, parse and execute the contents of that file. When the end of the file is reached, it is closed and the
previous file pointer from the infile file pointer stack restored to infile.
Parameters filename – name of file with LAMMPS commands
char *one(const std::string&)
Process a single command from a string in single
This function takes the text in single, makes a copy, parses that, executes the command and returns the name
of the command (without the arguments). If there was no command in single it will return nullptr.
Parameters single – string with LAMMPS command
Returns string with name of the parsed command w/o arguments

15.10 Utility functions

The utils sub-namespace inside the LAMMPS_NS namespace provides a collection of convenience functions and util-
ities that perform common tasks that are required repeatedly throughout the LAMMPS code like reading or writing to
files with error checking or translation of strings into specific types of numbers with checking for validity. This reduces
redundant implementations and encourages consistent behavior.

15.10.1 I/O with status check and similar functions

The the first two functions are wrappers around the corresponding C library calls fgets() or fread(). They will
check if there were errors on reading or an unexpected end-of-file state was reached. In that case, the functions will
stop with an error message, indicating the name of the problematic file, if possible unless the error argument is a NULL
pointer.
The fgets_trunc() function will work similar for fgets() but it will read in a whole line (i.e. until the end of line
or end of file), but store only as many characters as will fit into the buffer including a final newline character and the
terminating NULL byte. If the line in the file is longer it will thus be truncated in the buffer. This function is used by
read_lines_from_file() to read individual lines but make certain they follow the size constraints.
The read_lines_from_file() function will read the requested number of lines of a maximum length into a buffer
and will return 0 if successful or 1 if not. It also guarantees that all lines are terminated with a newline character and
the entire buffer with a NULL character.

void LAMMPS_NS::utils::sfgets(const char *srcname, int srcline, char *s, int size, FILE *fp, const char
*filename, Error *error)
Safe wrapper around fgets() which aborts on errors or EOF and prints a suitable error message to help debugging.
Use nullptr as the error parameter to avoid the abort on EOF or error.
Parameters
• srcname – name of the calling source file (from FLERR macro)
• srcline – line in the calling source file (from FLERR macro)
• s – buffer for storing the result of fgets()

15.10. Utility functions 589

LAMMPS Documentation, Release stable 29Sep2021

• size – size of buffer s (max number of bytes read by fgets())

• fp – file pointer used by fgets()
• filename – file name associated with fp (may be a null pointer; then LAMMPS will try to
detect)
• error – pointer to Error class instance (for abort) or nullptr
void LAMMPS_NS::utils::sfread(const char *srcname, int srcline, void *s, size_t size, size_t num, FILE *fp,
const char *filename, Error *error)
Safe wrapper around fread() which aborts on errors or EOF and prints a suitable error message to help debugging.
Use nullptr as the error parameter to avoid the abort on EOF or error.
Parameters
• srcname – name of the calling source file (from FLERR macro)
• srcline – line in the calling source file (from FLERR macro)
• s – buffer for storing the result of fread()
• size – size of data elements read by fread()
• num – number of data elements read by fread()
• fp – file pointer used by fread()
• filename – file name associated with fp (may be a null pointer; then LAMMPS will try to
detect)
• error – pointer to Error class instance (for abort) or nullptr
char *LAMMPS_NS::utils::fgets_trunc(char *s, int size, FILE *fp)
Wrapper around fgets() which reads whole lines but truncates the data to the buffer size and ensures a newline
char at the end.
This function is useful for reading line based text files with possible comments that should be parsed later.
This applies to data files, potential files, atomfile variable files and so on. It is used instead of fgets() by
utils::read_lines_from_file().
Parameters
• s – buffer for storing the result of fgets()
• size – size of buffer s (max number of bytes returned)
• fp – file pointer used by fgets()
int LAMMPS_NS::utils::read_lines_from_file(FILE *fp, int nlines, int nmax, char *buffer, int me,
MPI_Comm comm)
Read N lines of text from file into buffer and broadcast them
This function uses repeated calls to fread() to fill a buffer with newline terminated text. If a line does not end
in a newline (e.g. at the end of a file), it is added. The caller has to allocate an nlines by nmax sized buffer for
storing the text data. Reading is done by MPI rank 0 of the given communicator only, and thus only MPI rank 0
needs to provide a valid file pointer.
Parameters
• fp – file pointer used by fread
• nlines – number of lines to be read
• nmax – maximum length of a single line

590 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

• buffer – buffer for storing the data.

• me – MPI rank of calling process in MPI communicator
• comm – MPI communicator for broadcast
Returns 1 if the read was short, 0 if read was successful

15.10.2 String to number conversions with validity check

These functions should be used to convert strings to numbers. They are are strongly preferred over C library calls like
atoi() or atof() since they check if the entire provided string is a valid (floating-point or integer) number, and will
error out instead of silently returning the result of a partial conversion or zero in cases where the string is not a valid
number. This behavior allows to more easily detect typos or issues when processing input files.
The do_abort flag should be set to true in case this function is called only on a single MPI rank, as that will then
trigger the a call to Error::one() for errors instead of Error::all() and avoids a “hanging” calculation when run
in parallel.
Please also see is_integer() and is_double() for testing strings for compliance without conversion.

double LAMMPS_NS::utils::numeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
Convert a string to a floating point number while checking if it is a valid floating point or integer number
Parameters
• file – name of source file for error message
• line – line number in source file for error message
• str – string to be converted to number
• do_abort – determines whether to call Error::one() or Error::all()
• lmp – pointer to top-level LAMMPS class instance
Returns double precision floating point number
int LAMMPS_NS::utils::inumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
Convert a string to an integer number while checking if it is a valid integer number (regular int)
Parameters
• file – name of source file for error message
• line – line number in source file for error message
• str – string to be converted to number
• do_abort – determines whether to call Error::one() or Error::all()
• lmp – pointer to top-level LAMMPS class instance
Returns integer number (regular int)
bigint LAMMPS_NS::utils::bnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
Convert a string to an integer number while checking if it is a valid integer number (bigint)
Parameters
• file – name of source file for error message

15.10. Utility functions 591

LAMMPS Documentation, Release stable 29Sep2021

• line – line number in source file for error message

• str – string to be converted to number
• do_abort – determines whether to call Error::one() or Error::all()
• lmp – pointer to top-level LAMMPS class instance
Returns integer number (bigint)
tagint LAMMPS_NS::utils::tnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
Convert a string to an integer number while checking if it is a valid integer number (tagint)
Parameters
• file – name of source file for error message
• line – line number in source file for error message
• str – string to be converted to number
• do_abort – determines whether to call Error::one() or Error::all()
• lmp – pointer to top-level LAMMPS class instance
Returns integer number (tagint)

15.10.3 String processing

The following are functions to help with processing strings and parsing files or arguments.

char *LAMMPS_NS::utils::strdup(const std::string &text)

Make C-style copy of string in new storage
This allocates a storage buffer and copies the C-style or C++ style string into it. The buffer is allocated with
“new” and thus needs to be deallocated with “delete[]”.
Parameters text – string that should be copied
Returns new buffer with copy of string
std::string LAMMPS_NS::utils::trim(const std::string &line)
Trim leading and trailing whitespace. Like TRIM() in Fortran.
Parameters line – string that should be trimmed
Returns new string without whitespace (string)
std::string LAMMPS_NS::utils::trim_comment(const std::string &line)
Return string with anything from ‘#’ onward removed
Parameters line – string that should be trimmed
Returns new string without comment (string)
inline bool LAMMPS_NS::utils::has_utf8(const std::string &line)
Check if a string will likely have UTF-8 encoded characters
UTF-8 uses the 7-bit standard ASCII table for the first 127 characters and all other characters are encoded as
multiple bytes. For the multi-byte characters the first byte has either the highest two, three, or four bits set
followed by a zero bit and followed by one, two, or three more bytes, respectively, where the highest bit is set
and the second highest bit set to 0. The remaining bits combined are the character code, which is thus limited to
21-bits.

592 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

For the sake of efficiency this test only checks if a character in the string has the highest bit set and thus is very
likely an UTF-8 character. It will not be able to tell this this is a valid UTF-8 character or whether it is a 2-byte,
3-byte, or 4-byte character.

See also utils::utf8_subst()

Parameters line – string that should be checked

Returns true if string contains UTF-8 encoded characters (bool)

std::string LAMMPS_NS::utils::utf8_subst(const std::string &line)

Replace known UTF-8 characters with ASCII equivalents

See also utils::has_utf8()

Parameters line – string that should be converted

Returns new string with ascii replacements (string)

size_t LAMMPS_NS::utils::count_words(const char *text)

Count words in C-string, ignore any whitespace matching ” \t\r\n\f”
Parameters text – string that should be searched
Returns number of words found
size_t LAMMPS_NS::utils::count_words(const std::string &text)
Count words in string, ignore any whitespace matching ” \t\r\n\f”
Parameters text – string that should be searched
Returns number of words found
size_t LAMMPS_NS::utils::count_words(const std::string &text, const std::string &separators)
Count words in string with custom choice of separating characters
Parameters
• text – string that should be searched
• separators – string containing characters that will be treated as whitespace
Returns number of words found
size_t LAMMPS_NS::utils::trim_and_count_words(const std::string &text, const std::string &separators = "
\t\r\n\f")
Count words in a single line, trim anything from ‘#’ onward
Parameters
• text – string that should be trimmed and searched
• separators – string containing characters that will be treated as whitespace
Returns number of words found

15.10. Utility functions 593

LAMMPS Documentation, Release stable 29Sep2021

std::vector<std::string> LAMMPS_NS::utils::split_words(const std::string &text)

Take text and split into non-whitespace words.
This can handle strings with single and double quotes, escaped quotes, and escaped codes within quotes, but
due to using an STL container and STL strings is rather slow because of making copies. Designed for parsing
command lines and similar text and not for time critical processing. Use a tokenizer class if performance matters.

See also Tokenizer, ValueTokenizer

Parameters text – string that should be split

Returns STL vector with the words

std::vector<std::string> LAMMPS_NS::utils::split_lines(const std::string &text)

Take multi-line text and split into lines
Parameters text – string that should be split
Returns STL vector with the lines
bool LAMMPS_NS::utils::strmatch(const std::string &text, const std::string &pattern)
Match text against a simplified regex pattern

More flexible and specific matching of a string against a pattern. This function is supposed to be a more safe,
more specific and simple to use API to find pattern matches. The purpose is to replace uses of either strncmp()
or strstr() in the code base to find sub-strings safely. With strncmp() finding prefixes, the number of characters
to match must be counted, which can lead to errors, while using “^pattern” will do the same with less problems.
Matching for suffixes using strstr() is not as specific as ‘pattern$’, and complex matches, e.g. “^rigid.*\/small.*”,
to match all small body optimized rigid fixes require only one test.
The use of std::string arguments allows for simple concatenation even with char * type variables. Example:
utils::strmatch(text, std::string(“^”) + charptr)
Parameters
• text – the text to be matched against the pattern
• pattern – the search pattern, which may contain regexp markers
Returns true if the pattern matches, false if not
std::string LAMMPS_NS::utils::strfind(const std::string &text, const std::string &pattern)
Find sub-string that matches a simplified regex pattern

This function is a companion function to utils::strmatch(). Arguments and logic is the same, but instead of a
boolean, it returns the sub-string that matches the regex pattern. There can be only one match. This can be used
as a more flexible alternative to strstr().
Parameters
• text – the text to be matched against the pattern
• pattern – the search pattern, which may contain regexp markers
Returns the string that matches the pattern or an empty one

594 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

bool LAMMPS_NS::utils::is_integer(const std::string &str)

Check if string can be converted to valid integer
Parameters str – string that should be checked
Returns true, if string contains valid a integer, false otherwise
bool LAMMPS_NS::utils::is_double(const std::string &str)
Check if string can be converted to valid floating-point number
Parameters str – string that should be checked
Returns true, if string contains valid number, false otherwise

15.10.4 File and path functions

const char *LAMMPS_NS::utils::guesspath(char *buf, int len, FILE *fp)

Try to detect pathname from FILE pointer.
Currently supported on Linux, MacOS, and Windows, otherwise will report “(unknown)”.

On Linux the folder /proc/self/fd holds symbolic links to the actual pathnames associated with each open file
descriptor of the current process. On MacOS the same kind of information can be obtained using fcntl(fd,
F_GETPATH,buf). On Windows we use GetFinalPathNameByHandleA() which is available with Windows
Vista and later.
This function is used to provide a filename with error messages in functions where the filename is not passed as
an argument, but the FILE * pointer.
Parameters
• buf – storage buffer for pathname. output will be truncated if not large enough
• len – size of storage buffer. output will be truncated to this length - 1
• fp – FILE pointer struct from STDIO library for which we want to detect the name
Returns pointer to the storage buffer, i.e. buf
std::string LAMMPS_NS::utils::path_basename(const std::string &path)
Strip off leading part of path, return just the filename
Parameters path – file path
Returns file name
std::string LAMMPS_NS::utils::path_join(const std::string &a, const std::string &b)
Join two pathname segments
This uses the forward slash ‘/’ character unless LAMMPS is compiled for Windows where it used the equivalent
backward slash ‘'.
Parameters
• a – first path
• b – second path
Returns combined path
bool LAMMPS_NS::utils::file_is_readable(const std::string &path)
Check if file exists and is readable

15.10. Utility functions 595

LAMMPS Documentation, Release stable 29Sep2021

Parameters path – file path

Returns true if file exists and is readable

15.10.5 Potential file functions

std::string LAMMPS_NS::utils::get_potential_file_path(const std::string &path)

Determine full path of potential file. If file is not found in current directory, search directories listed in
LAMMPS_POTENTIALS environment variable
Parameters path – file path
Returns full path to potential file
std::string LAMMPS_NS::utils::get_potential_date(const std::string &path, const std::string
&potential_name)
Read potential file and return DATE field if it is present
Parameters
• path – file path
• potential_name – name of potential that is being read
Returns DATE field if present
std::string LAMMPS_NS::utils::get_potential_units(const std::string &path, const std::string
&potential_name)
Read potential file and return UNITS field if it is present
Parameters
• path – file path
• potential_name – name of potential that is being read
Returns UNITS field if present
int LAMMPS_NS::utils::get_supported_conversions(const int property)
Return bitmask of available conversion factors for a given property
Parameters property – property to be converted
Returns bitmask indicating available conversions
double LAMMPS_NS::utils::get_conversion_factor(const int property, const int conversion)
Return unit conversion factor for given property and selected from/to units
Parameters
• property – property to be converted
• conversion – constant indicating the conversion
Returns conversion factor
FILE *LAMMPS_NS::utils::open_potential(const std::string &name, LAMMPS *lmp, int *auto_convert)
Open a potential file as specified by name
If opening the file directly fails, the function will search for it in the list of folder pointed to by the environment
variable LAMMPS_POTENTIALS (if it is set).
If the potential file has a UNITS tag in the first line, the tag’s value is compared to the current unit style setting.
The behavior of the function then depends on the value of the auto_convert parameter. If it is a null pointer, then
the unit values must match or else the open will fail with an error. Otherwise the bitmask that auto_convert points

596 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

to is used check for compatibility with possible automatic conversions by the calling function. If compatible, the
bitmask is set to the required conversion or utils::NOCONVERT.
Parameters
• name – file- or pathname of the potential file
• lmp – pointer to top-level LAMMPS class instance
• auto_convert – pointer to unit conversion bitmask or nullptr
Returns FILE pointer of the opened potential file or nullptr

15.10.6 Argument processing

template<typename TYPE>
void LAMMPS_NS::utils::bounds(const char *file, int line, const std::string &str, bigint nmin, bigint nmax, TYPE
&nlo, TYPE &nhi, Error *error)
Compute index bounds derived from a string with a possible wildcard
This functions processes the string in str and set the values of nlo and nhi according to the following five cases:

• a single number, i: nlo = i; nhi = i;

• a single asterisk, *: nlo = nmin; nhi = nmax;
• a single number followed by an asterisk, i*: nlo = i; nhi = nmax;
• a single asterisk followed by a number, *i: nlo = nmin; nhi = i;
• two numbers with an asterisk in between. i*j: nlo = i; nhi = j;

Parameters
• file – name of source file for error message
• line – line number in source file for error message
• str – string to be processed
• nmin – smallest possible lower bound
• nmax – largest allowed upper bound
• nlo – lower bound
• nhi – upper bound
• error – pointer to Error class for out-of-bounds messages

int LAMMPS_NS::utils::expand_args(const char *file, int line, int narg, char **arg, int mode, char **&earg,
LAMMPS *lmp)
Expand list of arguments when containing fix/compute wildcards
This function searches the list of arguments in arg for strings of the kind c_ID[*] or f_ID[*] referring to computes
or fixes. Any such strings are replaced by one or more strings with the ‘*’ character replaced by the corresponding
possible numbers as determined from the fix or compute instance. Other strings are just copied. If the mode
parameter is set to 0, expand global vectors, but not global arrays; if it is set to 1, expand global arrays (by
column) but not global vectors.
If any expansion happens, the earg list and all its strings are new allocations and must be freed explicitly by the
caller. Otherwise arg and earg will point to the same address and no explicit de-allocation is needed by the caller.

15.10. Utility functions 597

LAMMPS Documentation, Release stable 29Sep2021

Parameters
• file – name of source file for error message
• line – line number in source file for error message
• narg – number of arguments in current list
• arg – argument list, possibly containing wildcards
• mode – select between global vectors(=0) and arrays (=1)
• earg – new argument list with wildcards expanded
• lmp – pointer to top-level LAMMPS class instance
Returns number of arguments in expanded list

15.10.7 Convenience functions

template<typename S, typename ...Args>

void LAMMPS_NS::utils::logmesg(LAMMPS *lmp, const S &format, Args&&... args)
Send formatted message to screen and logfile, if available
This function simplifies the repetitive task of outputting some message to both the screen and/or the log file.
The template wrapper with fmtlib format and argument processing allows this function to work similar to
fmt::print().
Parameters
• lmp – pointer to LAMMPS class instance
• format – format string of message to be printed
• args – arguments to format string
void LAMMPS_NS::utils::logmesg(LAMMPS *lmp, const std::string &mesg)
This is an overloaded member function, provided for convenience. It differs from the above function only in what
argument(s) it accepts.
Parameters
• lmp – pointer to LAMMPS class instance
• mesg – string with message to be printed
std::string LAMMPS_NS::utils::getsyserror()
Return a string representing the current system error status
This is a wrapper around calling strerror(errno).
Returns error string
std::string LAMMPS_NS::utils::check_packages_for_style(const std::string &style, const std::string &name,
LAMMPS *lmp)
Report if a requested style is in a package or may have a typo
Parameters
• style – type of style that is to be checked for
• name – name of style that was not found
• lmp – pointer to top-level LAMMPS class instance
Returns string usable for error messages

598 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

double LAMMPS_NS::utils::timespec2seconds(const std::string &timespec)

Convert a time string to seconds
The strings “off” and “unlimited” result in -1
Parameters timespec – a string in the following format: ([[HH:]MM:]SS)
Returns total in seconds
int LAMMPS_NS::utils::date2num(const std::string &date)
Convert a LAMMPS version date to a number
This will generate a number YYYYMMDD from a date string (with or without blanks) that is suitable for nu-
merical comparisons, i.e. later dates will generate a larger number.
The day may or may not have a leading zero, the month is identified by the first 3 letters (so there may be more)
and the year may be 2 or 4 digits (the missing 2 digits will be assumed as 20. That is 04 corresponds to 2004).
No check is made whether the date is valid.
Parameters date – string in the format (Day Month Year)
Returns date code
std::string LAMMPS_NS::utils::current_date()
Return current date as string
This will generate a string containing the current date in YYYY-MM-DD format.
Returns string with current date

15.10.8 Customized standard functions

int LAMMPS_NS::utils::binary_search(const double needle, const int n, const double *haystack)

Binary search in a vector of ascending doubles of length N
If the value is smaller than the smallest value in the vector, 0 is returned. If the value is larger or equal than the
largest value in the vector, N-1 is returned. Otherwise the index that satisfies the condition
haystack[index] <= value < haystack[index+1]
is returned, i.e. a value from 1 to N-2. Note that if there are tied values in the haystack, always the larger index
is returned as only that satisfied the condition.
Parameters
• needle – search value for which are are looking for the closest index
• n – size of the haystack array
• haystack – array with data in ascending order.
Returns index of value in the haystack array smaller or equal to needle
void LAMMPS_NS::utils::merge_sort(int *index, int num, void *ptr, int (*comp)(int, int, void*))
Custom merge sort implementation
This function provides a custom upward hybrid merge sort implementation with support to pass an opaque pointer
to the comparison function, e.g. for access to class members. This avoids having to use global variables. For
improved performance, it uses an in-place insertion sort on initial chunks of up to 64 elements and switches to
merge sort from then on.
Parameters
• index – Array with indices to be sorted

15.10. Utility functions 599

LAMMPS Documentation, Release stable 29Sep2021

• num – Length of the index array

• ptr – Pointer to opaque object passed to comparison function
• comp – Pointer to comparison function

15.11 Tokenizer classes

The purpose of the tokenizer classes is to simplify the recurring task of breaking lines of text down into words and/or
numbers. Traditionally, LAMMPS code would be using the strtok() function from the C library for that purpose, but
that function has two significant disadvantages: 1) it cannot be used concurrently from different LAMMPS instances
since it stores its status in a global variable and 2) it modifies the string that it is processing. These classes were
implemented to avoid both of these issues and also to reduce the amount of code that needs to be written.
The basic procedure is to create an instance of the tokenizer class with the string to be processed as an argument and
then do a loop until all available tokens are read. The constructor has a default set of separator characters, but that can
be overridden. The default separators are all “whitespace” characters, i.e. the space character, the tabulator character,
the carriage return character, the linefeed character, and the form feed character.

Listing 1: Tokenizer class example listing entries of the PATH environ-

ment variable
#include "tokenizer.h"
#include <cstdlib>
#include <string>
#include <iostream>

using namespace LAMMPS_NS;

int main(int, char **)

{
const char *path = getenv("PATH");

if (path != nullptr) {
Tokenizer p(path,":");
while (p.has_next())
std::cout << "Entry: " << p.next() << "\n";
}
return 0;
}

Most tokenizer operations cannot fail except for LAMMPS_NS::Tokenizer::next() (when used without first checking
with LAMMPS_NS::Tokenizer::has_next()) and LAMMPS_NS::Tokenizer::skip(). In case of failure, the class
will throw an exception, so you may need to wrap the code using the tokenizer into a try / catch block to handle
errors. The LAMMPS_NS::ValueTokenizer class may also throw an exception when a (type of) number is requested
as next token that is not compatible with the string representing the next word.

Listing 2: ValueTokenizer class example with exception handling

#include "tokenizer.h"
#include <cstdlib>
#include <string>
(continues on next page)

600 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

#include <iostream>

using namespace LAMMPS_NS;

int main(int, char **)

{
const char *text = "1 2 3 4 5 20.0 21 twentytwo 2.3";
double num1(0),num2(0),num3(0),num4(0);

ValueTokenizer t(text);
// read 4 doubles after skipping over 5 numbers
try {
t.skip(5);
num1 = t.next_double();
num2 = t.next_double();
num3 = t.next_double();
num4 = t.next_double();
} catch (TokenizerException &e) {
std::cout << "Reading numbers failed: " << e.what() << "\n";
}
std::cout << "Values: " << num1 << " " << num2 << " " << num3 << " " << num4 << "\n";
return 0;
}

This code example should produce the following output:

Reading numbers failed: Not a valid floating-point number: 'twentytwo'

Values: 20 21 0 0

class LAMMPS_NS::Tokenizer

Public Functions

Tokenizer(const std::string &str, const std::string &separators = TOKENIZER_DEFAULT_SEPARATORS)

Class for splitting text into words
This tokenizer will break down a string into sub-strings (i.e words) separated by the given separator charac-
ters. If the string contains certain known UTF-8 characters they will be replaced by their ASCII equivalents
processing the string.

See also ValueTokenizer, utils::split_words(), utils::utf8_subst()

Parameters
• str – string to be processed
• separators – string with separator characters (default: ” \t\r\n\f”)

void reset()
Re-position the tokenizer state to the first word, i.e. the first non-separator character

15.11. Tokenizer classes 601

LAMMPS Documentation, Release stable 29Sep2021

void skip(int n = 1)
Skip over a given number of tokens
Parameters n – number of tokens to skip over
bool has_next() const
Indicate whether more tokens are available
Returns true if there are more tokens, false if not
bool contains(const std::string &str) const
Search the text to be processed for a sub-string.
Parameters str – string to be searched for
Returns true if string was found, false if not
std::string next()
Retrieve next token.
Returns string with the next token
size_t count()
Count number of tokens in text.
Returns number of counted tokens
std::vector<std::string> as_vector()
Retrieve the entire text converted to an STL vector of tokens.
Returns The STL vector

class LAMMPS_NS::TokenizerException : public exception

Subclassed by InvalidFloatException, InvalidIntegerException

Public Functions

TokenizerException(const std::string &msg, const std::string &token)

Thrown during retrieving or skipping tokens
Parameters
• msg – String with error message
• token – String of the token/word that caused the error
inline virtual const char *what() const
Retrieve message describing the thrown exception
Returns string with error message

class LAMMPS_NS::ValueTokenizer

602 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Public Functions

ValueTokenizer(const std::string &str, const std::string &separators =

TOKENIZER_DEFAULT_SEPARATORS)
Class for reading text with numbers

See also Tokenizer

See Tokenizer InvalidIntegerException InvalidFloatException

Parameters
• str – String to be processed
• separators – String with separator characters (default: ” \t\r\n\f”)

std::string next_string()
Retrieve next token
Returns string with next token
tagint next_tagint()
Retrieve next token and convert to tagint
Returns value of next token
bigint next_bigint()
Retrieve next token and convert to bigint
Returns value of next token
int next_int()
Retrieve next token and convert to int
Returns value of next token
double next_double()
Retrieve next token and convert to double
Returns value of next token
bool has_next() const
Indicate whether more tokens are available
Returns true if there are more tokens, false if not
bool contains(const std::string &value) const
Search the text to be processed for a sub-string.
Parameters value – string with value to be searched for
Returns true if string was found, false if not
void skip(int ntokens = 1)
Skip over a given number of tokens
Parameters n – number of tokens to skip over
size_t count()
Count number of tokens in text.
Returns number of counted tokens

15.11. Tokenizer classes 603

LAMMPS Documentation, Release stable 29Sep2021

class InvalidIntegerException : public TokenizerException

class InvalidFloatException : public TokenizerException

15.12 Argument parsing classes

The purpose of argument parsing classes it to simplify and unify how arguments of commands in LAMMPS are parsed
and to make abstractions of repetitive tasks.
The LAMMPS_NS::ArgInfo class provides an abstraction for parsing references to compute or fix styles, variables or
custom integer or double properties handled by fix property/atom. These would start with a “c_”, “f_”, “v_”, “d_”,
“d2_”, “i_”, or “i2_” followed by the ID or name of than instance and may be postfixed with one or two array indices
“[<number>]” with numbers > 0.
A typical code segment would look like this:

Listing 3: Usage example for ArgInfo class

int nvalues = 0;
for (iarg = 0; iarg < nargnew; iarg++) {
ArgInfo argi(arg[iarg]);

which[nvalues] = argi.get_type();
argindex[nvalues] = argi.get_index1();
ids[nvalues] = argi.copy_name();

if ((which[nvalues] == ArgInfo::UNKNOWN)
|| (which[nvalues] == ArgInfo::NONE)
|| (argi.get_dim() > 1))
error->all(FLERR,"Illegal compute XXX command");

nvalues++;
}

class LAMMPS_NS::ArgInfo

Public Types

enum ArgTypes
constants for argument types
Values:

enumerator ERROR
enumerator UNKNOWN
enumerator NONE
enumerator X

604 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

enumerator V
enumerator F
enumerator COMPUTE
enumerator FIX
enumerator VARIABLE
enumerator KEYWORD
enumerator TYPE
enumerator MOLECULE
enumerator DNAME
enumerator INAME
enumerator DENSITY_NUMBER
enumerator DENSITY_MASS
enumerator MASS
enumerator TEMPERATURE
enumerator BIN1D
enumerator BIN2D
enumerator BIN3D
enumerator BINSPHERE
enumerator BINCYLINDER

Public Functions

ArgInfo(const std::string &arg, int allowed = COMPUTE | FIX | VARIABLE)

Class for processing references to fixes, computes and variables
This class provides an abstraction for the repetitive task of parsing arguments that may contain references
to fixes, computes, variables, or custom per-atom properties. It will identify the name and the index value
in the first and second dimension, if present.
Parameters
• arg – string with possible reference
• allowed – integer with bitmap of allowed types of references
inline int get_type() const
get type of reference
Return a type constant for the reference. This may be either COMPUTE, FIX, VARIABLE (if not restricted
to a subset of those by the “allowed” argument of the constructor) or NONE, if it if not a recognized or
allowed reference, or UNKNOWN, in case some error happened identifying or parsing the values of the
indices
Returns integer with a constant from ArgTypes enumerator

15.12. Argument parsing classes 605

LAMMPS Documentation, Release stable 29Sep2021

inline int get_dim() const

get dimension of reference
This will return either 0, 1, 2 depending on whether the reference has no, one or two “[{number}]” postfixes.
Returns integer with the dimensionality of the reference
inline int get_index1() const
get index of first dimension
This will return the number in the first “[{number}]” postfix or 0 if there is no postfix.
Returns integer with index or the postfix or 0
inline int get_index2() const
get index of second dimension
This will return the number in the second “[{number}]” postfix or -1 if there is no second postfix.
Returns integer with index of the postfix or -1
inline const char *get_name() const
return reference to the ID or name of the reference
This string is pointing to an internal storage element and is only valid to use while the ArgInfo class instance
is in scope. If you need a long-lived string make a copy with copy_name().
Returns C-style char * string
char *copy_name()
make copy of the ID of the reference as C-style string
The ID is copied into a buffer allocated with “new” and thus must be later deleted with “delete []” to avoid a
memory leak. Because it is a full copy in a newly allocated buffer, the lifetime of this string extends beyond
the the time the ArgInfo class is in scope.
Returns copy of string as char *

15.13 File reader classes

The purpose of the file reader classes is to simplify the recurring task of reading and parsing files. They can
use the LAMMPS_NS::ValueTokenizer class to process the read in text. The LAMMPS_NS::TextFileReader
is a more general version while LAMMPS_NS::PotentialFileReader is specialized to implement the be-
havior expected for looking up and reading/parsing files with potential parameters in LAMMPS. The poten-
tial file reader class requires a LAMMPS instance, requires to be run on MPI rank 0 only, will use the
LAMMPS_NS::utils::get_potential_file_path() function to look up and open the file, and will call the
LAMMPS_NS::Error class in case of failures to read or to convert numbers, so that LAMMPS will be aborted.

Listing 4: Use of PotentialFileReader class in pair style coul/streitz

PotentialFileReader reader(lmp, file, "coul/streitz");
char * line;

while((line = reader.next_line(NPARAMS_PER_LINE))) {
try {
ValueTokenizer values(line);
std::string iname = values.next_string();
(continues on next page)

606 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

int ielement;
for (ielement = 0; ielement < nelements; ielement++)
if (iname == elements[ielement]) break;

if (nparams == maxparam) {
maxparam += DELTA;
params = (Param *) memory->srealloc(params,maxparam*sizeof(Param),
"pair:params");
}

params[nparams].ielement = ielement;
params[nparams].chi = values.next_double();
params[nparams].eta = values.next_double();
params[nparams].gamma = values.next_double();
params[nparams].zeta = values.next_double();
params[nparams].zcore = values.next_double();

} catch (TokenizerException & e) {

error->one(FLERR, e.what());
}
nparams++;
}

A file that would be parsed by the reader code fragment looks like this:
# DATE: 2015-02-19 UNITS: metal CONTRIBUTOR: Ray Shan CITATION: Streitz and Mintmire,␣
,→Phys Rev B, 50, 11996-12003 (1994)

#
# X (eV) J (eV) gamma (1/AA) zeta (1/AA) Z (e)

Al 0.000000 10.328655 0.000000 0.968438 0.763905

O 5.484763 14.035715 0.000000 2.143957 0.000000

class LAMMPS_NS::TextFileReader

Public Functions

TextFileReader(const std::string &filename, const std::string &filetype)

Class for reading and parsing text files
The value of the class member variable ignore_comments controls whether any text following the pound
sign (#) should be ignored (true) or not (false). Default: true, i.e. ignore.
See also TextFileReader

Parameters
• filename – Name of file to be read
• filetype – Description of file type for error messages

15.13. File reader classes 607

LAMMPS Documentation, Release stable 29Sep2021

TextFileReader(FILE *fp, const std::string &filetype)

This is an overloaded member function, provided for convenience. It differs from the above function only
in what argument(s) it accepts.
This function is useful in combination with utils::open_potential().

Note: The FILE pointer is not closed in the destructor, but will be advanced when reading from it.

Parameters
• fp – File descriptor of the already opened file
• filetype – Description of file type for error messages

~TextFileReader()
Closes the file
void skip_line()
Read the next line and ignore it
char *next_line(int nparams = 0)
Read the next line(s) until nparams words have been read.
This reads a line and counts the words in it, if the number is less than the requested number, it will read
the next line, as well. Output will be a string with all read lines combined. The purpose is to somewhat
replicate the reading behavior of formatted files in Fortran.
If the ignore_comments class member has the value true, then any text read in is truncated at the first ‘#’
character.
Parameters nparams – Number of words that must be read. Default: 0
Returns String with the concatenated text
void next_dvector(double *list, int n)
Read lines until n doubles have been read and stored in array list
This reads lines from the file using the next_line() function, and splits them into floating-point numbers
using the ValueTokenizer class and stores the number is the provided list.
Parameters
• list – Pointer to array with suitable storage for n doubles
• n – Number of doubles to be read
ValueTokenizer next_values(int nparams, const std::string &separators =
TOKENIZER_DEFAULT_SEPARATORS)
Read text until nparams words are read and passed to a tokenizer object for custom parsing.
This reads lines from the file using the next_line() function, and splits them into floating-point numbers
using the ValueTokenizer class and stores the number is the provided list.
Parameters
• nparams – Number of words to be read
• separators – String with list of separators.
Returns ValueTokenizer object for read in text

608 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

Public Members

bool ignore_comments
Controls whether comments are ignored.

class LAMMPS_NS::PotentialFileReader : protected Pointers

Public Functions

PotentialFileReader(class LAMMPS *lmp, const std::string &filename, const std::string

&potential_name, const std::string &name_suffix, const int auto_convert = 0)
Class for reading and parsing LAMMPS potential files
The value of the class member variable ignore_comments controls whether any text following the pound
sign (#) should be ignored (true) or not (false). Default: true, i.e. ignore.
See also TextFileReader

Parameters
• lmp – Pointer to LAMMPS instance
• filename – Name of file to be read
• potential_name – Name of potential style for error messages
• name_suffix – Suffix added to potential name in error messages
• auto_convert – Bitmask of supported unit conversions

virtual ~PotentialFileReader()
Closes the file
void ignore_comments(bool value)
Set comment (= text after ‘#’) handling preference for the file to be read
Parameters value – Comment text is ignored if true, or not if false
void skip_line()
Read a line but ignore its content
char *next_line(int nparams = 0)
Read the next line(s) until nparams words have been read.
This reads a line and counts the words in it, if the number is less than the requested number, it will read
the next line, as well. Output will be a string with all read lines combined. The purpose is to somewhat
replicate the reading behavior of formatted files in Fortran.
Parameters nparams – Number of words that must be read. Default: 0
Returns String with the concatenated text
void next_dvector(double *list, int n)
Read lines until n doubles have been read and stored in array list
This reads lines from the file using the next_line() function, and splits them into floating-point numbers
using the ValueTokenizer class and stores the number is the provided list.
Parameters
• list – Pointer to array with suitable storage for n doubles

15.13. File reader classes 609

LAMMPS Documentation, Release stable 29Sep2021

• n – Number of doubles to be read

ValueTokenizer next_values(int nparams, const std::string &separators =
TOKENIZER_DEFAULT_SEPARATORS)
Read text until nparams words are read and passed to a tokenizer object for custom parsing.
This reads lines from the file using the next_line() function, and splits them into floating-point numbers
using the ValueTokenizer class and stores the number is the provided list.
Parameters
• nparams – Number of words to be read
• separators – String with list of separators.
Returns ValueTokenizer object for read in text
double next_double()
Read next line and convert first word to a double
Returns Value of first word in line as double
int next_int()
Read next line and convert first word to an int
Returns Value of first word in line as int
tagint next_tagint()
Read next line and convert first word to a tagint
Returns Value of first word in line as tagint
bigint next_bigint()
Read next line and convert first word to a bigint
Returns Value of first word in line as bigint
std::string next_string()
Read next line and return first word
Returns First word of read in line

15.14 Memory pool classes

The memory pool classes are used for cases where otherwise many small memory allocations would be needed and
where the data would be either all used or all freed. One example for that is the storage of neighbor lists. The memory
management strategy is based on the assumption that allocations will be in chunks of similar sizes. The allocation is
then not done per individual call for a reserved chunk of memory, but for a “page” that can hold multiple chunks of
data. A parameter for the maximum chunk size must be provided, as that is used to determine whether a new page of
memory must be used.
The MyPage class offers two ways to reserve a chunk: 1) with get() the chunk size needs to be known in advance, 2)
with vget() a pointer to the next chunk is returned, but its size is registered later with vgot().

Listing 5: Example of using MyPage

#include "my_page.h"
using namespace LAMMPS_NS;

(continues on next page)

610 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

MyPage<double> *dpage = new MyPage<double>;
// max size of chunk: 256, size of page: 10240 doubles (=81920 bytes)
dpage->init(256,10240);

double **build_some_lists(int num)

{
dpage->reset();
double **dlist = new double*[num];
for (int i=0; i < num; ++i) {
double *dptr = dpage.vget();
int jnum = 0;
for (int j=0; j < jmax; ++j) {
// compute some dvalue for eligible loop index j
dptr[j] = dvalue;
++jnum;
}
if (dpage.status() != 0) {
// handle out of memory or jnum too large errors
}
dpage.vgot(jnum);
dlist[i] = dptr;
}
return dlist;
}

template<class T>

class LAMMPS_NS::MyPage
Templated class for storing chunks of datums in pages.
The size of the chunk may vary from call to call, but must be less or equal than the maxchunk setting. The
chunks are not returnable like with malloc() (i.e. you cannot call free() on them individually). One can only reset
and start over. The purpose of this class is to replace many small memory allocations via malloc() with a few
large ones. Since the pages are never freed until the class is re-initialized, they can be re-used without having to
re-allocate them by calling the reset() method.
The settings maxchunk, pagesize, and pagedelta control the memory allocation strategy. The maxchunk value
represents the expected largest number of items per chunk. If there is less space left on the current page, a new
page is allocated for the next chunk. The pagesize value represents how many items can fit on a single page. It
should have space for multiple chunks of size maxchunk. The combination of these two parameters determines
how much memory is wasted by either switching to the next page too soon or allocating too large pages that
never get properly used. It is an error, if a requested chunk is larger than maxchunk. The pagedelta parameter
determines how many pages are allocated in one go. In combination with the pagesize setting, this determines
how often blocks of memory get allocated (fewer allocations will result in faster execution).

Note: This is a template class with explicit instantiation. If the class is used with a new data type a new explicit
instantiation may need to be added at the end of the file src/my_page.cpp to avoid symbol lookup errors.

15.14. Memory pool classes 611

LAMMPS Documentation, Release stable 29Sep2021

Public Functions

MyPage()
Create a class instance
Need to call init() before use to define allocation settings
int init(int user_maxchunk = 1, int user_pagesize = 1024, int user_pagedelta = 1)
(Re-)initialize the set of pages and allocation parameters.
This also frees all previously allocated storage and allocates the first page(s).
Parameters
• user_maxchunk – Expected maximum number of items for one chunk
• user_pagesize – Number of items on a single memory page
• user_pagedelta – Number of pages to allocate with one malloc
Returns 1 if there were invalid parameters, 2 if there was an allocation error or 0 if successful
T *get(int n = 1)
Pointer to location that can store N items.
This will allocate more pages as needed. If the parameter N is larger than the maxchunk setting an error is
flagged.
Parameters n – number of items for which storage is requested
Returns memory location or null pointer, if error or allocation failed
inline T *vget()
Get pointer to location that can store maxchunk items.
This will return the same pointer as the previous call to this function unless vgot() is called afterwards to
record how many items of the chunk were actually used.
Returns pointer to chunk of memory or null pointer if run out of memory
inline void vgot(int n)
Mark N items as used of the chunk reserved with a preceding call to vget().
This will advance the internal pointer inside the current memory page. It is not necessary to call this
function for N = 0, that is the reserved storage was not used. A following call to vget() will then reserve the
same location again. It is an error if N > maxchunk.
Parameters n – Number of items used in previously reserved chunk
void reset()
Reset state of memory pool without freeing any memory
inline double size() const
Return total size of allocated pages
Returns total storage used in bytes
inline int status() const
Return error status
Returns 0 if no error, 1 requested chunk size > maxchunk, 2 if malloc failed
template<class T>

612 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

class LAMMPS_NS::MyPoolChunk
Templated class for storing chunks of datums in pages.
The size of the chunk may vary from call to call between the minchunk and maxchunk setting. Chunks may
be returned to the pool for re-use. Chunks can be reserved in nbin different sizes between minchunk and max-
chunk. The chunksperpage setting specifies how many chunks are stored on any page and the pagedelta setting
determines how many pages are allocated in one go. Pages are never freed, so they can be re-used without
re-allocation.

Note: This is a template class with explicit instantiation. If the class is used with a new data type a new explicit
instantiation may need to be added at the end of the file src/my_pool_chunk.cpp to avoid symbol lookup
errors.

Public Functions

MyPoolChunk(int user_minchunk = 1, int user_maxchunk = 1, int user_nbin = 1, int user_chunkperpage =

1024, int user_pagedelta = 1)
Create a class instance and set memory pool parameters
Parameters
• user_minchunk – Minimal chunk size
• user_maxchunk – Maximal chunk size
• user_nbin – Number of bins of different chunk sizes
• user_chunkperpage – Number of chunks per page
• user_pagedelta – Number of pages to allocate in one go
~MyPoolChunk()
Destroy class instance and free all allocated memory
T *get(int &index)
Return pointer/index of unused chunk of size maxchunk
Parameters index – Index of chunk in memory pool
Returns Pointer to requested chunk of storage
T *get(int n, int &index)
Return pointer/index of unused chunk of size N
Parameters
• n – Size of chunk
• index – Index of chunk in memory pool
Returns Pointer to requested chunk of storage
void put(int index)
Put indexed chunk back into memory pool via free list
Parameters index – Memory chunk index returned by call to get()
double size() const
Return total size of allocated pages

15.14. Memory pool classes 613

LAMMPS Documentation, Release stable 29Sep2021

Returns total storage used in bytes

inline int status() const
Return error status
Returns 0 if no error, 1 if invalid input, 2 if malloc() failed, 3 if chunk > maxchunk

15.15 Eigensolver functions

The MathEigen sub-namespace of the LAMMPS_NS namespace contains functions and classes for eigensolvers. Cur-
rently only the jacobi3 function is used in various places in LAMMPS. That function is built on top of a group
of more generic eigensolvers that are maintained in the math_eigen_impl.h header file. This header contains the
implementation of three template classes:
1. “Jacobi” calculates all of the eigenvalues and eigenvectors of a dense, symmetric, real matrix.
2. The “PEigenDense” class only calculates the principal eigenvalue (ie. the largest or smallest eigenvalue), and
its corresponding eigenvector. However it is much more efficient than “Jacobi” when applied to large matrices
(larger than 13x13). PEigenDense also can understand complex-valued Hermitian matrices.
3. The “LambdaLanczos” class is a generalization of “PEigenDense” which can be applied to arbitrary sparse
matrices.
The “math_eigen_impl.h” code is an amalgamation of jacobi_pd by Andrew Jewett at Scripps Research (under CC0-1.0
license) and Lambda Lanczos by Yuya Kurebayashi at Tohoku University (under MIT license)

int MathEigen::jacobi3(double const *const *mat, double *eval, double **evec)

A specialized function which finds the eigenvalues and eigenvectors of a 3x3 matrix (in double ** format).
Parameters
• mat – the 3x3 matrix you wish to diagonalize
• eval – store the eigenvalues here
• evec – store the eigenvectors here. . .
Returns 0 if eigenvalue calculation converged, 1 if it failed
int MathEigen::jacobi3(double const mat[3][3], double *eval, double evec[3][3])
This is an overloaded member function, provided for convenience. It differs from the above function only in what
argument(s) it accepts.

15.16 Communication buffer coding with ubuf

LAMMPS uses communication buffers where it collects data from various class instances and then exchanges the data
with neighboring sub-domains. For simplicity those buffers are defined as double buffers and used for doubles and
integer numbers. This presents a unique problem when 64-bit integers are used. While the storage needed for a double
is also 64-bit, it cannot be used by a simple assignment. To get around that limitation, LAMMPS uses the ubuf union.
It is used in the various “pack” and “unpack” functions in the LAMMPS classes to store and retrieve integers that may
be 64-bit from the communication buffers.

614 Chapter 15. Information for Developers

 LAMMPS Documentation, Release stable 29Sep2021

union LAMMPS_NS::ubuf
#include <lmptype.h> Data structure for packing 32-bit and 64-bit integers into double (communication) buffers
Using this union avoids aliasing issues by having member types (double, int) referencing the same buffer memory
location.
The explicit constructor for 32-bit integers prevents compilers from (incorrectly) calling the double constructor
when storing an int into a double buffer.
Usage:

Listing 6: To copy an integer into a double buffer:

double buf[2];
int foo = 1;
tagint bar = 2<<40;
buf[1] = ubuf(foo).d;
buf[2] = ubuf(bar).d;

Listing 7: To copy from a double buffer back to an int:

foo = (int) ubuf(buf[1]).i;
bar = (tagint) ubuf(buf[2]).i;

The typecasts prevent compiler warnings about possible truncation issues.

Public Functions

inline ubuf(const double &arg)

inline ubuf(const int64_t &arg)

inline ubuf(const int &arg)

Public Members

double d
int64_t i

15.16. Communication buffer coding with ubuf 615

LAMMPS Documentation, Release stable 29Sep2021

616 Chapter 15. Information for Developers

 Part III

Command Reference

617
 CHAPTER

SIXTEEN

COMMANDS

16.1 angle_coeff command

16.1.1 Syntax

angle_coeff N args

• N = angle type (see asterisk form below)

• args = coefficients for one or more angle types

16.1.2 Examples

angle_coeff 1 300.0 107.0

angle_coeff * 5.0
angle_coeff 2*10 5.0

16.1.3 Description

Specify the angle force field coefficients for one or more angle types. The number and meaning of the coefficients
depends on the angle style. Angle coefficients can also be set in the data file read by the read_data command or in a
restart file.
N can be specified in one of two ways. An explicit numeric value can be used, as in the first example above. Or a
wild-card asterisk can be used to set the coefficients for multiple angle types. This takes the form “*” or “*n” or “n*”
or “m*n”. If N = the number of angle types, then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A
middle asterisk means all types from m to n (inclusive).
Note that using an angle_coeff command can override a previous setting for the same angle type. For example, these
commands set the coeffs for all angle types, then overwrite the coeffs for just angle type 2:

angle_coeff * 200.0 107.0 1.2

angle_coeff 2 50.0 107.0

A line in a data file that specifies angle coefficients uses the exact same format as the arguments of the angle_coeff
command in an input script, except that wild-card asterisks should not be used since coefficients for all N types must
be listed in the file. For example, under the “Angle Coeffs” section of a data file, the line that corresponds to the first
example above would be listed as

619
LAMMPS Documentation, Release stable 29Sep2021

1 300.0 107.0

The angle_style class2 is an exception to this rule, in that an additional argument is used in the input script to allow
specification of the cross-term coefficients. See its doc page for details.

The list of all angle styles defined in LAMMPS is given on the angle_style doc page. They are also listed in more
compact form on the Commands angle doc page.
On either of those pages, click on the style to display the formula it computes and its coefficients as specified by the
associated angle_coeff command.

16.1.4 Restrictions

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.
An angle style must be defined before any angle coefficients are set, either in the input script or in a data file.

16.1.5 Related commands

angle_style

16.1.6 Default

none

16.2 angle_style command

16.2.1 Syntax

angle_style style

• style = none or hybrid or charmm or class2 or cosine or cosine/squared or harmonic

16.2.2 Examples

angle_style harmonic
angle_style charmm
angle_style hybrid harmonic cosine

620 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.2.3 Description

Set the formula(s) LAMMPS uses to compute angle interactions between triplets of atoms, which remain in force for
the duration of the simulation. The list of angle triplets is read in by a read_data or read_restart command from a data
or restart file.
Hybrid models where angles are computed using different angle potentials can be setup using the hybrid angle style.
The coefficients associated with a angle style can be specified in a data or restart file or via the angle_coeff command.
All angle potentials store their coefficient data in binary restart files which means angle_style and angle_coeff com-
mands do not need to be re-specified in an input script that restarts a simulation. See the read_restart command for
details on how to do this. The one exception is that angle_style hybrid only stores the list of sub-styles in the restart
file; angle coefficients need to be re-specified.

Note: When both an angle and pair style is defined, the special_bonds command often needs to be used to turn off (or
weight) the pairwise interaction that would otherwise exist between 3 bonded atoms.

In the formulas listed for each angle style, theta is the angle between the 3 atoms in the angle.

Here is an alphabetic list of angle styles defined in LAMMPS. Click on the style to display the formula it computes and
coefficients specified by the associated angle_coeff command.
Click on the style to display the formula it computes, any additional arguments specified in the angle_style command,
and coefficients specified by the associated angle_coeff command.
There are also additional accelerated pair styles included in the LAMMPS distribution for faster performance on CPUs,
GPUs, and KNLs. The individual style names on the Commands angle page are followed by one or more of (g,i,k,o,t)
to indicate which accelerated styles exist.
• none - turn off angle interactions
• zero - topology but no interactions
• hybrid - define multiple styles of angle interactions
• charmm - CHARMM angle
• class2 - COMPASS (class 2) angle
• class2/p6 - COMPASS (class 2) angle expanded to 6th order
• cosine - angle with cosine term
• cosine/buck6d - same as cosine with Buckingham term between 1-3 atoms
• cosine/delta - angle with difference of cosines
• cosine/periodic - DREIDING angle
• cosine/shift - angle cosine with a shift
• cosine/shift/exp - cosine with shift and exponential term in spring constant
• cosine/squared - angle with cosine squared term
• cross - cross term coupling angle and bond lengths
• dipole - angle that controls orientation of a point dipole
• fourier - angle with multiple cosine terms
• fourier/simple - angle with a single cosine term

16.2. angle_style command 621

LAMMPS Documentation, Release stable 29Sep2021

• gaussian - multicentered Gaussian-based angle potential

• harmonic - harmonic angle
• mm3 - anharmonic angle
• quartic - angle with cubic and quartic terms
• sdk - harmonic angle with repulsive SDK pair style between 1-3 atoms
• table - tabulated by angle

16.2.4 Restrictions

Angle styles can only be set for atom_styles that allow angles to be defined.
Most angle styles are part of the MOLECULE package. They are only enabled if LAMMPS was built with that package.
See the Build package page for more info. The doc pages for individual bond potentials tell if it is part of a package.

16.2.5 Related commands

angle_coeff

16.2.6 Default

angle_style none

16.3 atom_modify command

16.3.1 Syntax

atom_modify keyword values ...

• one or more keyword/value pairs may be appended

• keyword = id or map or first or sort
id value = yes or no
map value = yes or array or hash
first value = group-ID = group whose atoms will appear first in internal atom lists
sort values = Nfreq binsize
Nfreq = sort atoms spatially every this many time steps
binsize = bin size for spatial sorting (distance units)

622 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.3.2 Examples

atom_modify map yes

atom_modify map hash sort 10000 2.0
atom_modify first colloid

16.3.3 Description

Modify certain attributes of atoms defined and stored within LAMMPS, in addition to what is specified by the
atom_style command. The id and map keywords must be specified before a simulation box is defined; other keywords
can be specified any time.
The id keyword determines whether non-zero atom IDs can be assigned to each atom. If the value is yes, which is the
default, IDs are assigned, whether you use the create atoms or read_data or read_restart commands to initialize atoms.
If the value is no the IDs for all atoms are assumed to be 0.
If atom IDs are used, they must all be positive integers. They should also be unique, though LAMMPS does not
check for this. Typically they should also be consecutively numbered (from 1 to Natoms), though this is not required.
Molecular atom styles are those that store bond topology information (styles bond, angle, molecular, full). These styles
require atom IDs since the IDs are used to encode the topology. Some other LAMMPS commands also require the use
of atom IDs. E.g. some many-body pair styles use them to avoid double computation of the I-J interaction between
two atoms.
The only reason not to use atom IDs is if you are running an atomic simulation so large that IDs cannot be uniquely
assigned. For a default LAMMPS build this limit is 2^31 or about 2 billion atoms. However, even in this case, you
can use 64-bit atom IDs, allowing 2^63 or about 9e18 atoms, if you build LAMMPS with the - DLAMMPS_BIGBIG
switch. This is described on the Build_settings doc page. If atom IDs are not used, they must be specified as 0 for all
atoms, e.g. in a data or restart file.
The map keyword determines how atoms with specific IDs are found when required. An example are the bond (angle,
etc) methods which need to find the local index of an atom with a specific global ID which is a bond (angle, etc) partner.
LAMMPS performs this operation efficiently by creating a “map”, which is either an array or hash table, as described
below.
When the map keyword is not specified in your input script, LAMMPS only creates a map for atom_styles for molecular
systems which have permanent bonds (angles, etc). No map is created for atomic systems, since it is normally not
needed. However some LAMMPS commands require a map, even for atomic systems, and will generate an error if
one does not exist. The map keyword thus allows you to force the creation of a map. The yes value will create either
an array or hash style map, as explained in the next paragraph. The array and hash values create an array-style or
hash-style map respectively.
For an array-style map, each processor stores a lookup table of length N, where N is the largest atom ID in the system.
This is a fast, simple method for many simulations, but requires too much memory for large simulations. For a hash-
style map, a hash table is created on each processor, which finds an atom ID in constant time (independent of the global
number of atom IDs). It can be slightly slower than the array map, but its memory cost is proportional to the number
of atoms owned by a processor, i.e. N/P when N is the total number of atoms in the system and P is the number of
processors.
The first keyword allows a group to be specified whose atoms will be maintained as the first atoms in each processor’s
list of owned atoms. This in only useful when the specified group is a small fraction of all the atoms, and there are
other operations LAMMPS is performing that will be sped-up significantly by being able to loop over the smaller set
of atoms. Otherwise the reordering required by this option will be a net slow-down. The neigh_modify include and
comm_modify group commands are two examples of commands that require this setting to work efficiently. Several
fixes, most notably time integration fixes like fix nve, also take advantage of this setting if the group they operate on is
the group specified by this command. Note that specifying “all” as the group-ID effectively turns off the first option.

16.3. atom_modify command 623

LAMMPS Documentation, Release stable 29Sep2021

It is OK to use the first keyword with a group that has not yet been defined, e.g. to use the atom_modify first command
at the beginning of your input script. LAMMPS does not use the group until a simulation is run.
The sort keyword turns on a spatial sorting or reordering of atoms within each processor’s sub-domain every Nfreq
timesteps. If Nfreq is set to 0, then sorting is turned off. Sorting can improve cache performance and thus speed-up a
LAMMPS simulation, as discussed in a paper by (Meloni). Its efficacy depends on the problem size (atoms/processor),
how quickly the system becomes disordered, and various other factors. As a general rule, sorting is typically more
effective at speeding up simulations of liquids as opposed to solids. In tests we have done, the speed-up can range from
zero to 3-4x.
Reordering is performed every Nfreq timesteps during a dynamics run or iterations during a minimization. More
precisely, reordering occurs at the first reneighboring that occurs after the target timestep. The reordering is performed
locally by each processor, using bins of the specified binsize. If binsize is set to 0.0, then a binsize equal to half the
neighbor cutoff distance (force cutoff plus skin distance) is used, which is a reasonable value. After the atoms have
been binned, they are reordered so that atoms in the same bin are adjacent to each other in the processor’s 1d list of
atoms.
The goal of this procedure is for atoms to put atoms close to each other in the processor’s one-dimensional list of atoms
that are also near to each other spatially. This can improve cache performance when pairwise interactions and neighbor
lists are computed. Note that if bins are too small, there will be few atoms/bin. Likewise if bins are too large, there will
be many atoms/bin. In both cases, the goal of cache locality will be undermined.

Note: Running a simulation with sorting on versus off should not change the simulation results in a statistical sense.
However, a different ordering will induce round-off differences, which will lead to diverging trajectories over time when
comparing two simulations. Various commands, particularly those which use random numbers (e.g. velocity create,
and fix langevin), may generate (statistically identical) results which depend on the order in which atoms are processed.
The order of atoms in a dump file will also typically change if sorting is enabled.

16.3.4 Restrictions

The first and sort options cannot be used together. Since sorting is on by default, it will be turned off if the first keyword
is used with a group-ID that is not “all”.

16.3.5 Related commands

none

16.3.6 Default

By default, id is yes. By default, atomic systems (no bond topology info) do not use a map. For molecular systems
(with bond topology info), a map is used. The default map style is array if no atom ID is larger than 1 million, otherwise
the default is hash. By default, a “first” group is not defined. By default, sorting is enabled with a frequency of 1000
and a binsize of 0.0, which means the neighbor cutoff will be used to set the bin size. If no neighbor cutoff is defined,
sorting will be turned off.

(Meloni) Meloni, Rosati and Colombo, J Chem Phys, 126, 121102 (2007).

624 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.4 atom_style command

16.4.1 Syntax

atom_style style args

• style = angle or atomic or body or bond or charge or dipole or dpd or edpd or electron or ellipsoid or full or line
or mdpd or molecular or oxdna or peri or smd or sph or sphere or spin or tdpd or tri or template or hybrid
args = none for any style except the following
body args = bstyle bstyle-args
bstyle = style of body particles
bstyle-args = additional arguments specific to the bstyle
see the Howto body doc
page for details
sphere arg = 0/1 (optional) for static/dynamic particle radii
tdpd arg = Nspecies
Nspecies = # of chemical species
template arg = template-ID
template-ID = ID of molecule template specified in a separate molecule command
hybrid args = list of one or more sub-styles, each with their args
• accelerated styles (with same args) = angle/kk or atomic/kk or bond/kk or charge/kk or full/kk or molecular/kk or
spin/kk

16.4.2 Examples

atom_style atomic
atom_style bond
atom_style full
atom_style body nparticle 2 10
atom_style hybrid charge bond
atom_style hybrid charge body nparticle 2 5
atom_style spin
atom_style template myMols
atom_style hybrid template twomols charge
atom_style tdpd 2

16.4.3 Description

Define what style of atoms to use in a simulation. This determines what attributes are associated with the atoms. This
command must be used before a simulation is setup via a read_data, read_restart, or create_box command.

Note: Many of the atom styles discussed here are only enabled if LAMMPS was built with a specific package, as
listed below in the Restrictions section.

Once a style is assigned, it cannot be changed, so use a style general enough to encompass all attributes. E.g. with
style bond, angular terms cannot be used or added later to the model. It is OK to use a style more general than needed,
though it may be slightly inefficient.

16.4. atom_style command 625

LAMMPS Documentation, Release stable 29Sep2021

The choice of style affects what quantities are stored by each atom, what quantities are communicated between proces-
sors to enable forces to be computed, and what quantities are listed in the data file read by the read_data command.
These are the additional attributes of each style and the typical kinds of physical systems they are used to model. All
styles store coordinates, velocities, atom IDs and types. See the read_data, create_atoms, and set commands for info
on how to set these various quantities.

angle bonds and angles bead-spring polymers with stiffness

atomic only the default values coarse-grain liquids, solids, metals
body mass, inertia moments, quaternion, angular momentum arbitrary bodies
bond bonds bead-spring polymers
charge charge atomic system with charges
dielectric dipole, area, curvature system with surface polarization
dipole charge and dipole moment system with dipolar particles
dpd internal temperature and internal energies DPD particles
edpd temperature and heat capacity eDPD particles
electron charge and spin and eradius electronic force field
ellipsoid shape, quaternion, angular momentum aspherical particles
full molecular + charge bio-molecules
line end points, angular velocity rigid bodies
mdpd density mDPD particles
mesont mass, radius, length, buckling, connections, tube id mesoscopic nanotubes
molecular bonds, angles, dihedrals, impropers uncharged molecules
oxdna nucleotide polarity coarse-grained DNA and RNA models
peri mass, volume mesoscopic Peridynamic models
smd volume, kernel diameter, contact radius, mass solid and fluid SPH particles
sph rho, esph, cv SPH particles
sphere diameter, mass, angular velocity granular models
spin magnetic moment system with magnetic particles
tdpd chemical concentration tDPD particles
template template index, template atom small molecules with fixed topology
tri corner points, angular momentum rigid bodies
wavepacket charge, spin, eradius, etag, cs_re, cs_im AWPMD

Note: It is possible to add some attributes, such as a molecule ID, to atom styles that do not have them via the fix
property/atom command. This command also allows new custom attributes consisting of extra integer or floating-point
values to be added to atoms. See the fix property/atom page for examples of cases where this is useful and details on
how to initialize, access, and output the custom values.

All of the above styles define point particles, except the sphere, ellipsoid, electron, peri, wavepacket, line, tri, and body
styles, which define finite-size particles. See the Howto spherical page for an overview of using finite-size particle
models with LAMMPS.
All of the point-particle styles assign mass to particles on a per-type basis, using the mass command, The finite-size
particle styles assign mass to individual particles on a per-particle basis.
For the sphere style, the particles are spheres and each stores a per-particle diameter and mass. If the diameter > 0.0,
the particle is a finite-size sphere. If the diameter = 0.0, it is a point particle. Note that by use of the disc keyword
with the fix nve/sphere, fix nvt/sphere, fix nph/sphere, fix npt/sphere commands, spheres can be effectively treated as
2d discs for a 2d simulation if desired. See also the set density/disc command. The sphere style takes an optional 0 or
1 argument. A value of 0 means the radius of each sphere is constant for the duration of the simulation. A value of 1
means the radii may vary dynamically during the simulation, e.g. due to use of the fix adapt command.

626 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

For the ellipsoid style, the particles are ellipsoids and each stores a flag which indicates whether it is a finite-size
ellipsoid or a point particle. If it is an ellipsoid, it also stores a shape vector with the 3 diameters of the ellipsoid and a
quaternion 4-vector with its orientation.
For the dielectric style, each particle can be either a physical particle (e.g. an ion), or an interface particle representing
a boundary element. For physical particles, the per-particle properties are the same as atom_style full. For interface
particles, in addition to these properties, each particle also has an area, a normal unit vector, a mean local curvature,
the mean and difference of the dielectric constants of two sides of the interface, and the local dielectric constant at the
boundary element. The distinction between the physical and interface particles is only meaningful when fix polarize
commands are applied to the interface particles.
For the dipole style, a point dipole is defined for each point particle. Note that if you wish the particles to be finite-size
spheres as in a Stockmayer potential for a dipolar fluid, so that the particles can rotate due to dipole-dipole interactions,
then you need to use atom_style hybrid sphere dipole, which will assign both a diameter and dipole moment to each
particle.
For the electron style, the particles representing electrons are 3d Gaussians with a specified position and bandwidth or
uncertainty in position, which is represented by the eradius = electron size.
For the peri style, the particles are spherical and each stores a per-particle mass and volume.
The oxdna style is for coarse-grained nucleotides and stores the 3’-to-5’ polarity of the nucleotide strand, which is set
through the bond topology in the data file. The first (second) atom in a bond definition is understood to point towards
the 3’-end (5’-end) of the strand. Note that this style is part of the CG-DNA package.
The dpd style is for dissipative particle dynamics (DPD) particles. Note that it is part of the DPD-REACT package, and
is not for use with the pair_style dpd or dpd/stat commands, which can simply use atom_style atomic. Atom_style dpd
extends DPD particle properties with internal temperature (dpdTheta), internal conductive energy (uCond), internal
mechanical energy (uMech), and internal chemical energy (uChem).
The edpd style is for energy-conserving dissipative particle dynamics (eDPD) particles which store a temperature
(edpd_temp), and heat capacity(edpd_cv).
The mdpd style is for many-body dissipative particle dynamics (mDPD) particles which store a density (rho) for con-
sidering density-dependent many-body interactions.
The tdpd style is for transport dissipative particle dynamics (tDPD) particles which store a set of chemical concentration.
An integer “cc_species” is required to specify the number of chemical species involved in a tDPD system.
The sph style is for smoothed particle hydrodynamics (SPH) particles which store a density (rho), energy (esph), and
heat capacity (cv).
The smd style is for a general formulation of Smooth Particle Hydrodynamics. Both fluids and solids can be modeled.
Particles store the mass and volume of an integration point, a kernel diameter used for calculating the field variables
(e.g. stress and deformation) and a contact radius for calculating repulsive forces which prevent individual physical
bodies from penetrating each other.
For the spin style, a magnetic spin is associated to each atom. Those spins have a norm (their magnetic moment) and
a direction.
The wavepacket style is similar to electron, but the electrons may consist of several Gaussian wave packets, summed
up with coefficients cs= (cs_re,cs_im). Each of the wave packets is treated as a separate particle in LAMMPS, wave
packets belonging to the same electron must have identical etag values.
For the line style, the particles are idealized line segments and each stores a per-particle mass and length and orientation
(i.e. the end points of the line segment).
For the tri style, the particles are planar triangles and each stores a per-particle mass and size and orientation (i.e. the
corner points of the triangle).
The template style allows molecular topology (bonds,angles,etc) to be defined via a molecule template using
the molecule command. The template stores one or more molecules with a single copy of the topology info

16.4. atom_style command 627

LAMMPS Documentation, Release stable 29Sep2021

(bonds,angles,etc) of each. Individual atoms only store a template index and template atom to identify which molecule
and which atom-within-the-molecule they represent. Using the template style instead of the bond, angle, molecular
styles can save memory for systems comprised of a large number of small molecules, all of a single type (or small
number of types). See the paper by Grime and Voth, in (Grime), for examples of how this can be advantageous for
large-scale coarse-grained systems. The examples/template directory has a few demo inputs and examples showing
the use of the template atom style versus molecular.

Note: When using the template style with a molecule template that contains multiple molecules, you should insure the
atom types, bond types, angle_types, etc in all the molecules are consistent. E.g. if one molecule represents H2O and
another CO2, then you probably do not want each molecule file to define 2 atom types and a single bond type, because
they will conflict with each other when a mixture system of H2O and CO2 molecules is defined, e.g. by the read_data
command. Rather the H2O molecule should define atom types 1 and 2, and bond type 1. And the CO2 molecule should
define atom types 3 and 4 (or atom types 3 and 2 if a single oxygen type is desired), and bond type 2.

For the body style, the particles are arbitrary bodies with internal attributes defined by the “style” of the bodies, which
is specified by the bstyle argument. Body particles can represent complex entities, such as surface meshes of discrete
points, collections of sub-particles, deformable objects, etc.
The Howto body page describes the body styles LAMMPS currently supports, and provides more details as to the kind
of body particles they represent. For all styles, each body particle stores moments of inertia and a quaternion 4-vector,
so that its orientation and position can be time integrated due to forces and torques.
Note that there may be additional arguments required along with the bstyle specification, in the atom_style body com-
mand. These arguments are described on the Howto body doc page.

Typically, simulations require only a single (non-hybrid) atom style. If some atoms in the simulation do not have all
the properties defined by a particular style, use the simplest style that defines all the needed properties by any atom.
For example, if some atoms in a simulation are charged, but others are not, use the charge style. If some atoms have
bonds, but others do not, use the bond style.
The only scenario where the hybrid style is needed is if there is no single style which defines all needed properties of
all atoms. For example, as mentioned above, if you want dipolar particles which will rotate due to torque, you need
to use “atom_style hybrid sphere dipole”. When a hybrid style is used, atoms store and communicate the union of all
quantities implied by the individual styles.
When using the hybrid style, you cannot combine the template style with another molecular style that stores
bond,angle,etc info on a per-atom basis.
LAMMPS can be extended with new atom styles as well as new body styles; see the Modify doc page.

Styles with a kk suffix are functionally the same as the corresponding style without the suffix. They have been optimized
to run faster, depending on your available hardware, as discussed in on the Speed packages doc page. The accelerated
styles take the same arguments and should produce the same results, except for round-off and precision issues.
Note that other acceleration packages in LAMMPS, specifically the GPU, INTEL, OPENMP, and OPT packages do
not use accelerated atom styles.
The accelerated styles are part of the KOKKOS package. They are only enabled if LAMMPS was built with those
packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

628 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.4.4 Restrictions

This command cannot be used after the simulation box is defined by a read_data or create_box command.
Many of the styles listed above are only enabled if LAMMPS was built with a specific package, as listed below. See
the Build package page for more info.
The angle, bond, full, molecular, and template styles are part of the MOLECULE package.
The line and tri styles are part of the ASPHERE package.
The body style is part of the BODY package.
The dipole style is part of the DIPOLE package.
The peri style is part of the PERI package for Peridynamics.
The oxdna style is part of the CG-DNA package for coarse-grained simulation of DNA and RNA.
The electron style is part of the EFF package for electronic force fields.
The dpd style is part of the DPD-REACT package for dissipative particle dynamics (DPD).
The edpd, mdpd, and tdpd styles are part of the DPD-MESO package for energy-conserving dissipative particle dy-
namics (eDPD), many-body dissipative particle dynamics (mDPD), and transport dissipative particle dynamics (tDPD),
respectively.
The sph style is part of the SPH package for smoothed particle hydrodynamics (SPH). See this PDF guide to using SPH
in LAMMPS.
The mesont style is part of the MESONT package.
The spin style is part of the SPIN package.
The wavepacket style is part of the AWPMD package for the antisymmetrized wave packet MD method.

16.4.5 Related commands

read_data, pair_style

16.4.6 Default

The default atom style is atomic. If atom_style sphere is used its default argument is 0.

(Grime) Grime and Voth, to appear in J Chem Theory & Computation (2014).

16.5 balance command

16.5.1 Syntax

balance thresh style args ... keyword args ...

• thresh = imbalance threshold that must be exceeded to perform a re-balance

• one style/arg pair can be used (or multiple for x,y,z)
• style = x or y or z or shift or rcb

16.5. balance command 629

LAMMPS Documentation, Release stable 29Sep2021

x args = uniform or Px-1 numbers between 0 and 1

uniform = evenly spaced cuts between processors in x dimension
numbers = Px-1 ascending values between 0 and 1, Px - # of processors in x␣
,→dimension

x can be specified together with y or z

y args = uniform or Py-1 numbers between 0 and 1
uniform = evenly spaced cuts between processors in y dimension
numbers = Py-1 ascending values between 0 and 1, Py - # of processors in y␣
,→dimension

y can be specified together with x or z

z args = uniform or Pz-1 numbers between 0 and 1
uniform = evenly spaced cuts between processors in z dimension
numbers = Pz-1 ascending values between 0 and 1, Pz - # of processors in z␣
,→dimension

z can be specified together with x or y

shift args = dimstr Niter stopthresh
dimstr = sequence of letters containing "x" or "y" or "z", each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshold is reached
rcb args = none
• zero or more keyword/arg pairs may be appended
• keyword = weight or out
weight style args = use weighted particle counts for the balancing
style = group or neigh or time or var or store
group args = Ngroup group1 weight1 group2 weight2 ...
Ngroup = number of groups with assigned weights
group1, group2, ... = group IDs
weight1, weight2, ... = corresponding weight factors
neigh factor = compute weight based on number of neighbors
factor = scaling factor (> 0)
time factor = compute weight based on time spend computing
factor = scaling factor (> 0)
var name = take weight from atom-style variable
name = name of the atom-style variable
store name = store weight in custom atom property defined by fix property/atom␣
,→command

name = atom property name (without d_ prefix)

out arg = filename
filename = write each processor's sub-domain to a file

16.5.2 Examples

balance 0.9 x uniform y 0.4 0.5 0.6

balance 1.2 shift xz 5 1.1
balance 1.0 shift xz 5 1.1
balance 1.1 rcb
balance 1.0 shift x 10 1.1 weight group 2 fast 0.5 slow 2.0
balance 1.0 shift x 10 1.1 weight time 0.8 weight neigh 0.5 weight store balance
balance 1.0 shift x 20 1.0 out tmp.balance

630 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.5.3 Description

This command adjusts the size and shape of processor sub-domains within the simulation box, to attempt to balance
the number of atoms or particles and thus indirectly the computational cost (load) more evenly across processors. The
load balancing is “static” in the sense that this command performs the balancing once, before or between simulations.
The processor sub-domains will then remain static during the subsequent run. To perform “dynamic” balancing, see
the fix balance command, which can adjust processor sub-domain sizes and shapes on-the-fly during a run.
Load-balancing is typically most useful if the particles in the simulation box have a spatially-varying density distribution
or when the computational cost varies significantly between different particles. E.g. a model of a vapor/liquid interface,
or a solid with an irregular-shaped geometry containing void regions, or hybrid pair style simulations which combine
pair styles with different computational cost. In these cases, the LAMMPS default of dividing the simulation box
volume into a regular-spaced grid of 3d bricks, with one equal-volume sub-domain per processor, may assign numbers
of particles per processor in a way that the computational effort varies significantly. This can lead to poor performance
when the simulation is run in parallel.
The balancing can be performed with or without per-particle weighting. With no weighting, the balancing attempts
to assign an equal number of particles to each processor. With weighting, the balancing attempts to assign an equal
aggregate computational weight to each processor, which typically induces a different number of atoms assigned to
each processor. Details on the various weighting options and examples for how they can be used are given below.
Note that the processors command allows some control over how the box volume is split across processors. Specifically,
for a Px by Py by Pz grid of processors, it allows choice of Px, Py, and Pz, subject to the constraint that Px * Py * Pz =
P, the total number of processors. This is sufficient to achieve good load-balance for some problems on some processor
counts. However, all the processor sub-domains will still have the same shape and same volume.
The requested load-balancing operation is only performed if the current “imbalance factor” in particles owned by each
processor exceeds the specified thresh parameter. The imbalance factor is defined as the maximum number of particles
(or weight) owned by any processor, divided by the average number of particles (or weight) per processor. Thus an
imbalance factor of 1.0 is perfect balance.
As an example, for 10000 particles running on 10 processors, if the most heavily loaded processor has 1200 particles,
then the factor is 1.2, meaning there is a 20% imbalance. Note that a re-balance can be forced even if the current balance
is perfect (1.0) be specifying a thresh < 1.0.

Note: Balancing is performed even if the imbalance factor does not exceed the thresh parameter if a “grid” style
is specified when the current partitioning is “tiled”. The meaning of “grid” vs “tiled” is explained below. This is to
allow forcing of the partitioning to “grid” so that the comm_style brick command can then be used to replace a current
comm_style tiled setting.

When the balance command completes, it prints statistics about the result, including the change in the imbalance factor
and the change in the maximum number of particles on any processor. For “grid” methods (defined below) that create
a logical 3d grid of processors, the positions of all cutting planes in each of the 3 dimensions (as fractions of the box
length) are also printed.

Note: This command attempts to minimize the imbalance factor, as defined above. But depending on the method a
perfect balance (1.0) may not be achieved. For example, “grid” methods (defined below) that create a logical 3d grid
cannot achieve perfect balance for many irregular distributions of particles. Likewise, if a portion of the system is a
perfect lattice, e.g. the initial system is generated by the create_atoms command, then “grid” methods may be unable
to achieve exact balance. This is because entire lattice planes will be owned or not owned by a single processor.

Note: The imbalance factor is also an estimate of the maximum speed-up you can hope to achieve by running a
perfectly balanced simulation versus an imbalanced one. In the example above, the 10000 particle simulation could

16.5. balance command 631

LAMMPS Documentation, Release stable 29Sep2021

run up to 20% faster if it were perfectly balanced, versus when imbalanced. However, computational cost is not strictly
proportional to particle count, and changing the relative size and shape of processor sub-domains may lead to additional
computational and communication overheads, e.g. in the PPPM solver used via the kspace_style command. Thus you
should benchmark the run times of a simulation before and after balancing.

The method used to perform a load balance is specified by one of the listed styles (or more in the case of x,y,z), which
are described in detail below. There are 2 kinds of styles.
The x, y, z, and shift styles are “grid” methods which produce a logical 3d grid of processors. They operate by changing
the cutting planes (or lines) between processors in 3d (or 2d), to adjust the volume (area in 2d) assigned to each
processor, as in the following 2d diagram where processor sub-domains are shown and particles are colored by the
processor that owns them.

The leftmost diagram is the default partitioning of the simulation box across processors (one sub-box for each of 16
processors); the middle diagram is after a “grid” method has been applied. The rcb style is a “tiling” method which
does not produce a logical 3d grid of processors. Rather it tiles the simulation domain with rectangular sub-boxes of
varying size and shape in an irregular fashion so as to have equal numbers of particles (or weight) in each sub-box, as
in the rightmost diagram above.
The “grid” methods can be used with either of the comm_style command options, brick or tiled. The “tiling” methods
can only be used with comm_style tiled. Note that it can be useful to use a “grid” method with comm_style tiled to
return the domain partitioning to a logical 3d grid of processors so that “comm_style brick” can afterwords be specified
for subsequent run commands.
When a “grid” method is specified, the current domain partitioning can be either a logical 3d grid or a tiled partitioning.
In the former case, the current logical 3d grid is used as a starting point and changes are made to improve the imbalance
factor. In the latter case, the tiled partitioning is discarded and a logical 3d grid is created with uniform spacing in all
dimensions. This becomes the starting point for the balancing operation.
When a “tiling” method is specified, the current domain partitioning (“grid” or “tiled”) is ignored, and a new partition-
ing is computed from scratch.

The x, y, and z styles invoke a “grid” method for balancing, as described above. Note that any or all of these 3 styles can
be specified together, one after the other, but they cannot be used with any other style. This style adjusts the position
of cutting planes between processor sub-domains in specific dimensions. Only the specified dimensions are altered.
The uniform argument spaces the planes evenly, as in the left diagrams above. The numeric argument requires listing
Ps-1 numbers that specify the position of the cutting planes. This requires knowing Ps = Px or Py or Pz = the number
of processors assigned by LAMMPS to the relevant dimension. This assignment is made (and the Px, Py, Pz values
printed out) when the simulation box is created by the “create_box” or “read_data” or “read_restart” command and is
influenced by the settings of the processors command.

632 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Each of the numeric values must be between 0 and 1, and they must be listed in ascending order. They represent the
fractional position of the cutting place. The left (or lower) edge of the box is 0.0, and the right (or upper) edge is 1.0.
Neither of these values is specified. Only the interior Ps-1 positions are specified. Thus is there are 2 processors in the
x dimension, you specify a single value such as 0.75, which would make the left processor’s sub-domain 3x larger than
the right processor’s sub-domain.

The shift style invokes a “grid” method for balancing, as described above. It changes the positions of cutting planes
between processors in an iterative fashion, seeking to reduce the imbalance factor, similar to how the fix balance shift
command operates.
The dimstr argument is a string of characters, each of which must be an “x” or “y” or “z”. Each character can appear
zero or one time, since there is no advantage to balancing on a dimension more than once. You should normally only
list dimensions where you expect there to be a density variation in the particles.
Balancing proceeds by adjusting the cutting planes in each of the dimensions listed in dimstr, one dimension at a time.
For a single dimension, the balancing operation (described below) is iterated on up to Niter times. After each dimension
finishes, the imbalance factor is re-computed, and the balancing operation halts if the stopthresh criterion is met.
A re-balance operation in a single dimension is performed using a recursive multisectioning algorithm, where the
position of each cutting plane (line in 2d) in the dimension is adjusted independently. This is similar to a recursive
bisectioning for a single value, except that the bounds used for each bisectioning take advantage of information from
neighboring cuts if possible. At each iteration, the count of particles on either side of each plane is tallied. If the counts
do not match the target value for the plane, the position of the cut is adjusted to be halfway between a low and high
bound. The low and high bounds are adjusted on each iteration, using new count information, so that they become
closer together over time. Thus as the recursion progresses, the count of particles on either side of the plane gets closer
to the target value.
After the balanced plane positions are determined, if any pair of adjacent planes are closer together than the neighbor
skin distance (as specified by the neigh_modify command), then the plane positions are shifted to separate them by at
least this amount. This is to prevent particles being lost when dynamics are run with processor sub-domains that are
too narrow in one or more dimensions.
Once the re-balancing is complete and final processor sub-domains assigned, particles are migrated to their new owning
processor, and the balance procedure ends.

Note: At each re-balance operation, the bisectioning for each cutting plane (line in 2d) typically starts with low and
high bounds separated by the extent of a processor’s sub-domain in one dimension. The size of this bracketing region
shrinks by 1/2 every iteration. Thus if Niter is specified as 10, the cutting plane will typically be positioned to 1 part
in 1000 accuracy (relative to the perfect target position). For Niter = 20, it will be accurate to 1 part in a million. Thus
there is no need to set Niter to a large value. LAMMPS will check if the threshold accuracy is reached (in a dimension)
is less iterations than Niter and exit early. However, Niter should also not be set too small, since it will take roughly
the same number of iterations to converge even if the cutting plane is initially close to the target value.

The rcb style invokes a “tiled” method for balancing, as described above. It performs a recursive coordinate bisectioning
(RCB) of the simulation domain. The basic idea is as follows.
The simulation domain is cut into 2 boxes by an axis-aligned cut in one of the dimensions, leaving one new sub-box on
either side of the cut. Which dimension is chosen for the cut depends on the particle (weight) distribution within the
parent box. Normally the longest dimension of the box is cut, but if all (or most) of the particles are at one end of the
box, a cut may be performed in another dimension to induce sub-boxes that are more cube-ish (3d) or square-ish (2d)
in shape.
After the cut is made, all the processors are also partitioned into 2 groups, half assigned to the box on the lower side
of the cut, and half to the box on the upper side. (If the processor count is odd, one side gets an extra processor.) The

16.5. balance command 633

LAMMPS Documentation, Release stable 29Sep2021

cut is positioned so that the number of (weighted) particles in the lower box is exactly the number that the processors
assigned to that box should own for load balance to be perfect. This also makes load balance for the upper box perfect.
The positioning of the cut is done iteratively, by a bisectioning method (median search). Note that counting particles
on either side of the cut requires communication between all processors at each iteration.
That is the procedure for the first cut. Subsequent cuts are made recursively, in exactly the same manner. The subset of
processors assigned to each box make a new cut in one dimension of that box, splitting the box, the subset of processors,
and the particles in the box in two. The recursion continues until every processor is assigned a sub-box of the entire
simulation domain, and owns the (weighted) particles in that sub-box.

This sub-section describes how to perform weighted load balancing using the weight keyword.
By default, all particles have a weight of 1.0, which means each particle is assumed to require the same amount of
computation during a timestep. There are, however, scenarios where this is not a good assumption. Measuring the
computational cost for each particle accurately would be impractical and slow down the computation. Instead the weight
keyword implements several ways to influence the per-particle weights empirically by properties readily available or
using the user’s knowledge of the system. Note that the absolute value of the weights are not important; only their
relative ratios affect which particle is assigned to which processor. A particle with a weight of 2.5 is assumed to require
5x more computational than a particle with a weight of 0.5. For all the options below the weight assigned to a particle
must be a positive value; an error will be be generated if a weight is <= 0.0.
Below is a list of possible weight options with a short description of their usage and some example scenarios where
they might be applicable. It is possible to apply multiple weight flags and the weightings they induce will be combined
through multiplication. Most of the time, however, it is sufficient to use just one method.
The group weight style assigns weight factors to specified groups of particles. The group style keyword is followed by
the number of groups, then pairs of group IDs and the corresponding weight factor. If a particle belongs to none of
the specified groups, its weight is not changed. If it belongs to multiple groups, its weight is the product of the weight
factors.
This weight style is useful in combination with pair style hybrid, e.g. when combining a more costly many-body
potential with a fast pair-wise potential. It is also useful when using run_style respa where some portions of the system
have many bonded interactions and others none. It assumes that the computational cost for each group remains constant
over time. This is a purely empirical weighting, so a series test runs to tune the assigned weight factors for optimal
performance is recommended.
The neigh weight style assigns the same weight to each particle owned by a processor based on the total count of neigh-
bors in the neighbor list owned by that processor. The motivation is that more neighbors means a higher computational
cost. The style does not use neighbors per atom to assign a unique weight to each atom, because that value can vary
depending on how the neighbor list is built.
The factor setting is applied as an overall scale factor to the neigh weights which allows adjustment of their impact
on the balancing operation. The specified factor value must be positive. A value > 1.0 will increase the weights so
that the ratio of max weight to min weight increases by factor. A value < 1.0 will decrease the weights so that the
ratio of max weight to min weight decreases by factor. In both cases the intermediate weight values increase/decrease
proportionally as well. A value = 1.0 has no effect on the neigh weights. As a rule of thumb, we have found a factor of
about 0.8 often results in the best performance, since the number of neighbors is likely to overestimate the ideal weight.
This weight style is useful for systems where there are different cutoffs used for different pairs of interactions, or the
density fluctuates, or a large number of particles are in the vicinity of a wall, or a combination of these effects. If
a simulation uses multiple neighbor lists, this weight style will use the first suitable neighbor list it finds. It will not
request or compute a new list. A warning will be issued if there is no suitable neighbor list available or if it is not
current, e.g. if the balance command is used before a run or minimize command is used, in which case the neighbor list
may not yet have been built. In this case no weights are computed. Inserting a run 0 post no command before issuing
the balance command, may be a workaround for this case, as it will induce the neighbor list to be built.
The time weight style uses timer data to estimate weights. It assigns the same weight to each particle owned by a
processor based on the total computational time spent by that processor. See details below on what time window is

634 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

used. It uses the same timing information as is used for the MPI task timing breakdown, namely, for sections Pair,
Bond, Kspace, and Neigh. The time spent in those portions of the timestep are measured for each MPI rank, summed,
then divided by the number of particles owned by that processor. I.e. the weight is an effective CPU time/particle
averaged over the particles on that processor.
The factor setting is applied as an overall scale factor to the time weights which allows adjustment of their impact
on the balancing operation. The specified factor value must be positive. A value > 1.0 will increase the weights so
that the ratio of max weight to min weight increases by factor. A value < 1.0 will decrease the weights so that the
ratio of max weight to min weight decreases by factor. In both cases the intermediate weight values increase/decrease
proportionally as well. A value = 1.0 has no effect on the time weights. As a rule of thumb, effective values to use are
typically between 0.5 and 1.2. Note that the timer quantities mentioned above can be affected by communication which
occurs in the middle of the operations, e.g. pair styles with intermediate exchange of data witin the force computation,
and likewise for KSpace solves.
When using the time weight style with the balance command, the timing data is taken from the preceding run command,
i.e. the timings are for the entire previous run. For the fix balance command the timing data is for only the timesteps
since the last balancing operation was performed. If timing information for the required sections is not available, e.g.
at the beginning of a run, or when the timer command is set to either loop or off, a warning is issued. In this case no
weights are computed.

Note: The time weight style is the most generic option, and should be tried first, unless the group style is easily
applicable. However, since the computed cost function is averaged over all particles on a processor, the weights may
not be highly accurate. This style can also be effective as a secondary weight in combination with either group or neigh
to offset some of inaccuracies in either of those heuristics.

The var weight style assigns per-particle weights by evaluating an atom-style variable specified by name. This is
provided as a more flexible alternative to the group weight style, allowing definition of a more complex heuristics based
on information (global and per atom) available inside of LAMMPS. For example, atom-style variables can reference
the position of a particle, its velocity, the volume of its Voronoi cell, etc.
The store weight style does not compute a weight factor. Instead it stores the current accumulated weights in a custom
per-atom vector specified by name. This must be a vector defined as d_name via the fix property/atom command. This
means the values in the vector can be read as part of a data file with the read_data command or specified with the
set command. These weights can also be output in a dump file, so this is a way to examine, debug, or visualize the
per-particle weights used during the load-balancing operation.
Note that the name of the custom per-atom vector is specified just as name, not as d_name as it is for other commands
that use different kinds of custom atom vectors or arrays as arguments.

The out keyword writes a text file to the specified filename with the results of the balancing operation. The file contains
the bounds of the sub-domain for each processor after the balancing operation completes. The format of the file is
compatible with the Pizza.py mdump tool which has support for manipulating and visualizing mesh files. An example
is shown here for a balancing by 4 processors for a 2d problem:

ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
16
ITEM: BOX BOUNDS
0 10
0 10
0 10
ITEM: NODES
(continues on next page)

16.5. balance command 635

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

1 1 0 0 0
2 1 5 0 0
3 1 5 5 0
4 1 0 5 0
5 1 5 0 0
6 1 10 0 0
7 1 10 5 0
8 1 5 5 0
9 1 0 5 0
10 1 5 5 0
11 1 5 10 0
12 1 10 5 0
13 1 5 5 0
14 1 10 5 0
15 1 10 10 0
16 1 5 10 0
ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
4
ITEM: SQUARES
1 1 1 2 3 4
2 1 5 6 7 8
3 1 9 10 11 12
4 1 13 14 15 16

The coordinates of all the vertices are listed in the NODES section, 5 per processor. Note that the 4 sub-domains share
vertices, so there will be duplicate nodes in the list.
The “SQUARES” section lists the node IDs of the 4 vertices in a rectangle for each processor (1 to 4).
For a 3d problem, the syntax is similar with 8 vertices listed for each processor, instead of 4, and “SQUARES” replaced
by “CUBES”.

16.5.4 Restrictions

For 2d simulations, the z style cannot be used. Nor can a “z” appear in dimstr for the shift style.
Balancing through recursive bisectioning (rcb style) requires comm_style tiled

16.5.5 Related commands

group, processors, fix balance, comm_style

636 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.5.6 Default

none

16.6 bond_coeff command

16.6.1 Syntax

bond_coeff N args

• N = bond type (see asterisk form below)

• args = coefficients for one or more bond types

16.6.2 Examples

bond_coeff 5 80.0 1.2

bond_coeff * 30.0 1.5 1.0 1.0
bond_coeff 1*4 30.0 1.5 1.0 1.0
bond_coeff 1 harmonic 200.0 1.0

16.6.3 Description

Specify the bond force field coefficients for one or more bond types. The number and meaning of the coefficients
depends on the bond style. Bond coefficients can also be set in the data file read by the read_data command or in a
restart file.
N can be specified in one of two ways. An explicit numeric value can be used, as in the first example above. Or a
wild-card asterisk can be used to set the coefficients for multiple bond types. This takes the form “*” or “*n” or “n*”
or “m*n”. If N = the number of bond types, then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A
middle asterisk means all types from m to n (inclusive).
Note that using a bond_coeff command can override a previous setting for the same bond type. For example, these
commands set the coeffs for all bond types, then overwrite the coeffs for just bond type 2:

bond_coeff * 100.0 1.2

bond_coeff 2 200.0 1.2

A line in a data file that specifies bond coefficients uses the exact same format as the arguments of the bond_coeff
command in an input script, except that wild-card asterisks should not be used since coefficients for all N types must
be listed in the file. For example, under the “Bond Coeffs” section of a data file, the line that corresponds to the first
example above would be listed as

5 80.0 1.2

The list of all bond styles defined in LAMMPS is given on the bond_style doc page. They are also listed in more
compact form on the Commands bond doc page.

16.6. bond_coeff command 637

LAMMPS Documentation, Release stable 29Sep2021

On either of those pages, click on the style to display the formula it computes and its coefficients as specified by the
associated bond_coeff command.

16.6.4 Restrictions

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.
A bond style must be defined before any bond coefficients are set, either in the input script or in a data file.

16.6.5 Related commands

bond_style

16.6.6 Default

none

16.7 bond_style command

16.7.1 Syntax

bond_style style args

• style = none or hybrid or class2 or fene or fene/expand or harmonic or morse or nonlinear or quartic
• args = none for any style except hybrid
– hybrid args = list of one or more styles

16.7.2 Examples

bond_style harmonic
bond_style fene
bond_style hybrid harmonic fene

16.7.3 Description

Set the formula(s) LAMMPS uses to compute bond interactions between pairs of atoms. In LAMMPS, a bond differs
from a pairwise interaction, which are set via the pair_style command. Bonds are defined between specified pairs of
atoms and remain in force for the duration of the simulation (unless the bond breaks which is possible in some bond
potentials). The list of bonded atoms is read in by a read_data or read_restart command from a data or restart file. By
contrast, pair potentials are typically defined between all pairs of atoms within a cutoff distance and the set of active
interactions changes over time.
Hybrid models where bonds are computed using different bond potentials can be setup using the hybrid bond style.
The coefficients associated with a bond style can be specified in a data or restart file or via the bond_coeff command.

638 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

All bond potentials store their coefficient data in binary restart files which means bond_style and bond_coeff commands
do not need to be re-specified in an input script that restarts a simulation. See the read_restart command for details
on how to do this. The one exception is that bond_style hybrid only stores the list of sub-styles in the restart file; bond
coefficients need to be re-specified.

Note: When both a bond and pair style is defined, the special_bonds command often needs to be used to turn off (or
weight) the pairwise interaction that would otherwise exist between 2 bonded atoms.

In the formulas listed for each bond style, r is the distance between the 2 atoms in the bond.

Here is an alphabetic list of bond styles defined in LAMMPS. Click on the style to display the formula it computes and
coefficients specified by the associated bond_coeff command.
Click on the style to display the formula it computes, any additional arguments specified in the bond_style command,
and coefficients specified by the associated bond_coeff command.
There are also additional accelerated pair styles included in the LAMMPS distribution for faster performance on CPUs,
GPUs, and KNLs. The individual style names on the Commands bond doc page are followed by one or more of (g,i,k,o,t)
to indicate which accelerated styles exist.
• none - turn off bonded interactions
• zero - topology but no interactions
• hybrid - define multiple styles of bond interactions
• class2 - COMPASS (class 2) bond
• fene - FENE (finite-extensible non-linear elastic) bond
• fene/expand - FENE bonds with variable size particles
• gaussian - multicentered Gaussian-based bond potential
• gromos - GROMOS force field bond
• harmonic - harmonic bond
• harmonic/shift - shifted harmonic bond
• harmonic/shift/cut - shifted harmonic bond with a cutoff
• mm3 - MM3 anharmonic bond
• morse - Morse bond
• nonlinear - nonlinear bond
• oxdna/fene - modified FENE bond suitable for DNA modeling
• oxdna2/fene - same as oxdna but used with different pair styles
• oxrna2/fene - modified FENE bond suitable for RNA modeling
• quartic - breakable quartic bond
• special - enable special bond exclusions for 1-5 pairs and beyond
• table - tabulated by bond length

16.7. bond_style command 639

LAMMPS Documentation, Release stable 29Sep2021

16.7.4 Restrictions

Bond styles can only be set for atom styles that allow bonds to be defined.
Most bond styles are part of the MOLECULE package. They are only enabled if LAMMPS was built with that package.
See the Build package page for more info. The doc pages for individual bond potentials tell if it is part of a package.

16.7.5 Related commands

bond_coeff , delete_bonds

16.7.6 Default

bond_style none

16.8 bond_write command

16.8.1 Syntax

bond_write btype N inner outer file keyword itype jtype

• btype = bond types

• N = # of values
• inner,outer = inner and outer bond length (distance units)
• file = name of file to write values to
• keyword = section name in file for this set of tabulated values
• itype,jtype = 2 atom types (optional)

16.8.2 Examples

bond_write 1 500 0.5 3.5 table.txt Harmonic_1

bond_write 3 1000 0.1 6.0 table.txt Morse

16.8.3 Description

Write energy and force values to a file as a function of distance for the currently defined bond potential. This is useful
for plotting the potential function or otherwise debugging its values. If the file already exists, the table of values is
appended to the end of the file to allow multiple tables of energy and force to be included in one file.
The energy and force values are computed at distances from inner to outer for 2 interacting atoms forming a bond of
type btype, using the appropriate bond_coeff coefficients. N evenly spaced distances are used.
For example, for N = 7, inner = 1.0, and outer = 4.0, values are computed at r = 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0.
The file is written in the format used as input for the bond_style table option with keyword as the section name. Each
line written to the file lists an index number (1-N), a distance (in distance units), an energy (in energy units), and a force

640 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(in force units). In case a new file is created, the first line will be a comment with a “DATE:” and “UNITS:” tag with
the current date and units settings. For subsequent invocations of the bond_write command for the same file, data will
be appended and the current units settings will be compared to the data from the header, if present, and bond_write
will refuse to add a table if the units are not the same.

16.8.4 Restrictions

All force field coefficients for bond and other kinds of interactions must be set before this command can be invoked.
Due to how the bond force is computed, an inner value > 0.0 must be specified even if the potential has a finite value
at r = 0.0.

16.8.5 Related commands

bond_style table, bond_style, bond_coeff

16.8.6 Default

none

16.9 boundary command

16.9.1 Syntax

boundary x y z

• x,y,z = p or s or f or m, one or two letters

p is periodic
f is non-periodic and fixed
s is non-periodic and shrink-wrapped
m is non-periodic and shrink-wrapped with a minimum value

16.9.2 Examples

boundary p p f
boundary p fs p
boundary s f fm

16.9. boundary command 641

LAMMPS Documentation, Release stable 29Sep2021

16.9.3 Description

Set the style of boundaries for the global simulation box in each dimension. A single letter assigns the same style to
both the lower and upper face of the box. Two letters assigns the first style to the lower face and the second style to the
upper face. The initial size of the simulation box is set by the read_data, read_restart, or create_box commands.
The style p means the box is periodic, so that particles interact across the boundary, and they can exit one end of the box
and re-enter the other end. A periodic dimension can change in size due to constant pressure boundary conditions or
box deformation (see the fix npt and fix deform commands). The p style must be applied to both faces of a dimension.
The styles f, s, and m mean the box is non-periodic, so that particles do not interact across the boundary and do not
move from one side of the box to the other.
For style f, the position of the face is fixed. If an atom moves outside the face it will be deleted on the next timestep
that reneighboring occurs. This will typically generate an error unless you have set the thermo_modify lost option to
allow for lost atoms.
For style s, the position of the face is set so as to encompass the atoms in that dimension (shrink-wrapping), no mat-
ter how far they move. Note that when the difference between the current box dimensions and the shrink-wrap box
dimensions is large, this can lead to lost atoms at the beginning of a run when running in parallel. This is due to the
large change in the (global) box dimensions also causing significant changes in the individual sub-domain sizes. If
these changes are farther than the communication cutoff, atoms will be lost. This is best addressed by setting initial
box dimensions to match the shrink-wrapped dimensions more closely, by using m style boundaries (see below).
For style m, shrink-wrapping occurs, but is bounded by the value specified in the data or restart file or set by the
create_box command. For example, if the upper z face has a value of 50.0 in the data file, the face will always be
positioned at 50.0 or above, even if the maximum z-extent of all the atoms becomes less than 50.0. This can be useful
if you start a simulation with an empty box or if you wish to leave room on one side of the box, e.g. for atoms to
evaporate from a surface.
For triclinic (non-orthogonal) simulation boxes, if the second dimension of a tilt factor (e.g. y for xy) is periodic, then
the periodicity is enforced with the tilt factor offset. If the first dimension is shrink-wrapped, then the shrink wrapping
is applied to the tilted box face, to encompass the atoms. E.g. for a positive xy tilt, the xlo and xhi faces of the box are
planes tilting in the +y direction as y increases. These tilted planes are shrink-wrapped around the atoms to determine
the x extent of the box.
See the Howto triclinic page for a geometric description of triclinic boxes, as defined by LAMMPS, and how to trans-
form these parameters to and from other commonly used triclinic representations.

642 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.9.4 Restrictions

This command cannot be used after the simulation box is defined by a read_data or create_box command or
read_restart command. See the change_box command for how to change the simulation box boundaries after it has
been defined.
For 2d simulations, the z dimension must be periodic.

16.9.5 Related commands

See the thermo_modify command for a discussion of lost atoms.

16.9.6 Default

boundary p p p

16.10 box command

16.10.1 Syntax

box keyword value ...

• one or more keyword/value pairs may be appended

• keyword = tilt
tilt value = small or large

16.10.2 Examples

box tilt large

box tilt small

16.10.3 Description

Set attributes of the simulation box.

For triclinic (non-orthogonal) simulation boxes, the tilt keyword allows simulation domains to be created with arbitrary
tilt factors, e.g. via the create_box or read_data commands. Tilt factors determine how skewed the triclinic box is; see
the Howto triclinic page for a discussion of triclinic boxes in LAMMPS.
LAMMPS normally requires that no tilt factor can skew the box more than half the distance of the parallel box length,
which is the first dimension in the tilt factor (x for xz). If tilt is set to small, which is the default, then an error will be
generated if a box is created which exceeds this limit. If tilt is set to large, then no limit is enforced. You can create a
box with any tilt factors you wish.
Note that if a simulation box has a large tilt factor, LAMMPS will run less efficiently, due to the large volume of
communication needed to acquire ghost atoms around a processor’s irregular-shaped sub-domain. For extreme values
of tilt, LAMMPS may also lose atoms and generate an error.

16.10. box command 643

LAMMPS Documentation, Release stable 29Sep2021

16.10.4 Restrictions

This command cannot be used after the simulation box is defined by a read_data or create_box command or
read_restart command.

16.10.5 Related commands

none

16.10.6 Default

The default value is tilt = small.

16.11 change_box command

16.11.1 Syntax

change_box group-ID parameter args ... keyword args ...

• group-ID = ID of group of atoms to (optionally) displace

• one or more parameter/arg pairs may be appended
parameter = x or y or z or xy or xz or yz or boundary or ortho or triclinic or set␣
,→or remap

x, y, z args = style value(s)

style = final or delta or scale or volume
final values = lo hi
lo hi = box boundaries after displacement (distance units)
delta values = dlo dhi
dlo dhi = change in box boundaries after displacement (distance units)
scale values = factor
factor = multiplicative factor for change in box length after displacement
volume value = none = adjust this dim to preserve volume of system
xy, xz, yz args = style value
style = final or delta
final value = tilt
tilt = tilt factor after displacement (distance units)
delta value = dtilt
dtilt = change in tilt factor after displacement (distance units)
boundary args = x y z
x,y,z = p or s or f or m, one or two letters
p is periodic
f is non-periodic and fixed
s is non-periodic and shrink-wrapped
m is non-periodic and shrink-wrapped with a minimum value
ortho args = none = change box to orthogonal
triclinic args = none = change box to triclinic
set args = none = store state of current box
remap args = none = remap atom coords from last saved state to current box

644 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• zero or more keyword/value pairs may be appended

• keyword = units
units value = lattice or box
lattice = distances are defined in lattice units
box = distances are defined in simulation box units

16.11.2 Examples

change_box all xy final -2.0 z final 0.0 5.0 boundary p p f remap units box
change_box all x scale 1.1 y volume z volume remap

16.11.3 Description

Change the volume and/or shape and/or boundary conditions for the simulation box. Orthogonal simulation boxes
have 3 adjustable size parameters (x,y,z). Triclinic (non-orthogonal) simulation boxes have 6 adjustable size/shape
parameters (x,y,z,xy,xz,yz). Any or all of them can be adjusted independently by this command. Thus it can be used to
expand or contract a box, or to apply a shear strain to a non-orthogonal box. It can also be used to change the boundary
conditions for the simulation box, similar to the boundary command.
The size and shape of the initial simulation box are specified by the create_box or read_data or read_restart command
used to setup the simulation. The size and shape may be altered by subsequent runs, e.g. by use of the fix npt or fix
deform commands. The create_box, read data, and read_restart commands also determine whether the simulation box
is orthogonal or triclinic and their doc pages explain the meaning of the xy,xz,yz tilt factors.
See the Howto triclinic page for a geometric description of triclinic boxes, as defined by LAMMPS, and how to trans-
form these parameters to and from other commonly used triclinic representations.
The keywords used in this command are applied sequentially to the simulation box and the atoms in it, in the order
specified.
Before the sequence of keywords are invoked, the current box size/shape is stored, in case a remap keyword is used to
map the atom coordinates from a previously stored box size/shape to the current one.
After all the keywords have been processed, any shrink-wrap boundary conditions are invoked (see the boundary com-
mand) which may change simulation box boundaries, and atoms are migrated to new owning processors.

Note: This means that you cannot use the change_box command to enlarge a shrink-wrapped box, e.g. to make room
to insert more atoms via the create_atoms command, because the simulation box will be re-shrink-wrapped before
the change_box command completes. Instead you could do something like this, assuming the simulation box is non-
periodic and atoms extend from 0 to 20 in all dimensions:

change_box all x final -10 20

create_atoms 1 single -5 5 5 # this will fail to insert an atom

change_box all x final -10 20 boundary f s s

create_atoms 1 single -5 5 5
change_box all boundary s s s # this will work

Note: Unlike the earlier “displace_box” version of this command, atom remapping is NOT performed by default. This
command allows remapping to be done in a more general way, exactly when you specify it (zero or more times) in the

16.11. change_box command 645

LAMMPS Documentation, Release stable 29Sep2021

sequence of transformations. Thus if you do not use the remap keyword, atom coordinates will not be changed even if
the box size/shape changes. If a uniformly strained state is desired, the remap keyword should be specified.

Note: It is possible to lose atoms with this command. E.g. by changing the box without remapping the atoms, and
having atoms end up outside of non-periodic boundaries. It is also possible to alter bonds between atoms straddling a
boundary in bad ways. E.g. by converting a boundary from periodic to non-periodic. It is also possible when remapping
atoms to put them (nearly) on top of each other. E.g. by converting a boundary from non-periodic to periodic. All of
these will typically lead to bad dynamics and/or generate error messages.

Note: The simulation box size/shape can be changed by arbitrarily large amounts by this command. This is not a
problem, except that the mapping of processors to the simulation box is not changed from its initial 3d configuration;
see the processors command. Thus, if the box size/shape changes dramatically, the mapping of processors to the
simulation box may not end up as optimal as the initial mapping attempted to be. You may wish to re-balance the
atoms by using the balance command if that is the case.

Note: You cannot use this command after reading a restart file (and before a run is performed) if the restart file stored
per-atom information from a fix and any of the specified keywords change the box size or shape or boundary conditions.
This is because atoms may be moved to new processors and the restart info will not migrate with them. LAMMPS will
generate an error if this could happen. Only the ortho and triclinic keywords do not trigger this error. One solution is
to perform a “run 0” command before using the change_box command. This clears the per-atom restart data, whether
it has been re-assigned to a new fix or not.

Note: Because the keywords used in this command are applied one at a time to the simulation box and the atoms in it,
care must be taken with triclinic cells to avoid exceeding the limits on skew after each transformation in the sequence. If
skew is exceeded before the final transformation this can be avoided by changing the order of the sequence, or breaking
the transformation into two or more smaller transformations. For more information on the allowed limits for box skew
see the discussion on triclinic boxes on Howto triclinic doc page.

For the x, y, and z parameters, this is the meaning of their styles and values.
For style final, the final lo and hi box boundaries of a dimension are specified. The values can be in lattice or box
distance units. See the discussion of the units keyword below.
For style delta, plus or minus changes in the lo/hi box boundaries of a dimension are specified. The values can be in
lattice or box distance units. See the discussion of the units keyword below.
For style scale, a multiplicative factor to apply to the box length of a dimension is specified. For example, if the initial
box length is 10, and the factor is 1.1, then the final box length will be 11. A factor less than 1.0 means compression.
The volume style changes the specified dimension in such a way that the overall box volume remains constant with
respect to the operation performed by the preceding keyword. The volume style can only be used following a keyword
that changed the volume, which is any of the x, y, z keywords. If the preceding keyword “key” had a volume style, then
both it and the current keyword apply to the keyword preceding “key”. I.e. this sequence of keywords is allowed:

change_box all x scale 1.1 y volume z volume

The volume style changes the associated dimension so that the overall box volume is unchanged relative to its value
before the preceding keyword was invoked.

646 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

If the following command is used, then the z box length will shrink by the same 1.1 factor the x box length was increased
by:

change_box all x scale 1.1 z volume

If the following command is used, then the y,z box lengths will each shrink by sqrt(1.1) to keep the volume constant.
In this case, the y,z box lengths shrink so as to keep their relative aspect ratio constant:

change_box all x scale 1.1 y volume z volume

If the following command is used, then the final box will be a factor of 10% larger in x and y, and a factor of 21%
smaller in z, so as to keep the volume constant:

change_box all x scale 1.1 z volume y scale 1.1 z volume

Note: For solids or liquids, when one dimension of the box is expanded, it may be physically undesirable to hold the
other 2 box lengths constant since that implies a density change. For solids, adjusting the other dimensions via the
volume style may make physical sense (just as for a liquid), but may not be correct for materials and potentials whose
Poisson ratio is not 0.5.

For the scale and volume styles, the box length is expanded or compressed around its mid point.

For the xy, xz, and yz parameters, this is the meaning of their styles and values. Note that changing the tilt factors of a
triclinic box does not change its volume.
For style final, the final tilt factor is specified. The value can be in lattice or box distance units. See the discussion of
the units keyword below.
For style delta, a plus or minus change in the tilt factor is specified. The value can be in lattice or box distance units.
See the discussion of the units keyword below.
All of these styles change the xy, xz, yz tilt factors. In LAMMPS, tilt factors (xy,xz,yz) for triclinic boxes are required
to be no more than half the distance of the parallel box length. For example, if xlo = 2 and xhi = 12, then the x box
length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2
and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then
configurations with tilt = . . . , -15, -5, 5, 15, 25, . . . are all equivalent. Any tilt factor specified by this command must
be within these limits.

The boundary keyword takes arguments that have exactly the same meaning as they do for the boundary command. In
each dimension, a single letter assigns the same style to both the lower and upper face of the box. Two letters assigns
the first style to the lower face and the second style to the upper face.
The style p means the box is periodic; the other styles mean non-periodic. For style f, the position of the face is fixed.
For style s, the position of the face is set so as to encompass the atoms in that dimension (shrink-wrapping), no matter
how far they move. For style m, shrink-wrapping occurs, but is bounded by the current box edge in that dimension, so
that the box will become no smaller. See the boundary command for more explanation of these style options.
Note that the “boundary” command itself can only be used before the simulation box is defined via a read_data or
create_box or read_restart command. This command allows the boundary conditions to be changed later in your input
script. Also note that the read_restart will change boundary conditions to match what is stored in the restart file. So if
you wish to change them, you should use the change_box command after the read_restart command.

Note: Changing a periodic boundary to a non-periodic one will also cause the image flag for that dimension of all
atoms to be reset to 0. LAMMPS will print a warning message, if that happens. Please note that this reset can lead

16.11. change_box command 647

LAMMPS Documentation, Release stable 29Sep2021

to undesired changes when atoms are involved in bonded interactions that straddle periodic boundaries and thus the
values of the image flag differs for those atoms.

The ortho and triclinic keywords convert the simulation box to be orthogonal or triclinic (non-orthogonal).
The simulation box is defined as either orthogonal or triclinic when it is created via the create_box, read_data, or
read_restart commands.
These keywords allow you to toggle the existing simulation box from orthogonal to triclinic and vice versa. For example,
an initial equilibration simulation can be run in an orthogonal box, the box can be toggled to triclinic, and then a non-
equilibrium MD (NEMD) simulation can be run with deformation via the fix deform command.
If the simulation box is currently triclinic and has non-zero tilt in xy, yz, or xz, then it cannot be converted to an
orthogonal box.

The set keyword saves the current box size/shape. This can be useful if you wish to use the remap keyword more than
once or if you wish it to be applied to an intermediate box size/shape in a sequence of keyword operations. Note that
the box size/shape is saved before any of the keywords are processed, i.e. the box size/shape at the time the create_box
command is encountered in the input script.
The remap keyword remaps atom coordinates from the last saved box size/shape to the current box state. For example,
if you stretch the box in the x dimension or tilt it in the xy plane via the x and xy keywords, then the remap command
will dilate or tilt the atoms to conform to the new box size/shape, as if the atoms moved with the box as it deformed.
Note that this operation is performed without regard to periodic boundaries. Also, any shrink-wrapping of non-periodic
boundaries (see the boundary command) occurs after all keywords, including this one, have been processed.
Only atoms in the specified group are remapped.

The units keyword determines the meaning of the distance units used to define various arguments. A box value selects
standard distance units as defined by the units command, e.g. Angstroms for units = real or metal. A lattice value
means the distance units are in lattice spacings. The lattice command must have been previously used to define the
lattice spacing.

16.11.4 Restrictions

If you use the ortho or triclinic keywords, then at the point in the input script when this command is issued, no dumps can
be active, nor can a fix deform be active. This is because these commands test whether the simulation box is orthogonal
when they are first issued. Note that these commands can be used in your script before a change_box command is
issued, so long as an undump or unfix command is also used to turn them off.

16.11.5 Related commands

fix deform, boundary

648 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.11.6 Default

The option default is units = lattice.

16.12 clear command

16.12.1 Syntax

clear

16.12.2 Examples

(commands for 1st simulation)

clear
(commands for 2nd simulation)

16.12.3 Description

This command deletes all atoms, restores all settings to their default values, and frees all memory allocated by
LAMMPS. Once a clear command has been executed, it is almost as if LAMMPS were starting over, with only the
exceptions noted below. This command enables multiple jobs to be run sequentially from one input script.
These settings are not affected by a clear command: the working directory (shell command), log file status (log com-
mand), echo status (echo command), and input script variables (variable command).

16.12.4 Restrictions

none

16.12.5 Related commands

none

16.12.6 Default

none

16.12. clear command 649

LAMMPS Documentation, Release stable 29Sep2021

16.13 comm_modify command

16.13.1 Syntax

comm_modify keyword value ...

• zero or more keyword/value pairs may be appended

• keyword = mode or cutoff or cutoff/multi or multi/reduce or group or vel
mode value = single, multi, or multi/old = communicate atoms within a single or␣
,→multiple distances

cutoff value = Rcut (distance units) = communicate atoms from this far away
cutoff/multi collection value
collection = atom collection or collection range (supports asterisk notation)
value = Rcut (distance units) = communicate atoms for selected types from this␣
,→far away

reduce/multi arg = none = reduce number of communicated ghost atoms for multi style
cutoff/multi/old type value
type = atom type or type range (supports asterisk notation)
value = Rcut (distance units) = communicate atoms for selected types from this␣
,→far away

group value = group-ID = only communicate atoms in the group

vel value = yes or no = do or do not communicate velocity info with ghost atoms

16.13.2 Examples

comm_modify mode multi reduce/multi

comm_modify mode multi group solvent
comm_modify mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0
comm_modify vel yes
comm_modify mode single cutoff 5.0 vel yes
comm_modify cutoff/multi * 0.0

16.13.3 Description

This command sets parameters that affect the inter-processor communication of atom information that occurs each
timestep as coordinates and other properties are exchanged between neighboring processors and stored as properties of
ghost atoms.

Note: These options apply to the currently defined comm style. When you specify a comm_style or read_restart
command, all communication settings are restored to their default or stored values, including those previously reset by
a comm_modify command. Thus if your input script specifies a comm_style or read_restart command, you should use
the comm_modify command after it.

The mode keyword determines whether a single or multiple cutoff distances are used to determine which atoms to
communicate.
The default mode is single which means each processor acquires information for ghost atoms that are within a single
distance from its sub-domain. The distance is by default the maximum of the neighbor cutoff across all atom type pairs.

650 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

For many systems this is an efficient algorithm, but for systems with widely varying cutoffs for different type pairs, the
multi or multi/old mode can be faster. In multi, each atom is assigned to a collection which should correspond to a
set of atoms with similar interaction cutoffs. In this case, each atom collection is assigned its own distance cutoff for
communication purposes, and fewer atoms will be communicated. in multi/old, a similar technique is used but atoms
are grouped by atom type. See the neighbor multi and neighbor multi/old commands for neighbor list construction
options that may also be beneficial for simulations of this kind. The multi communication mode is only compatible
with the multi neighbor style. The multi/old communication mode is comparable with both the multi and multi/old
neighbor styles.
The cutoff keyword allows you to extend the ghost cutoff distance for communication mode single, which is the distance
from the borders of a processor’s sub-domain at which ghost atoms are acquired from other processors. By default the
ghost cutoff = neighbor cutoff = pairwise force cutoff + neighbor skin. See the neighbor command for more information
about the skin distance. If the specified Rcut is greater than the neighbor cutoff, then extra ghost atoms will be acquired.
If the provided cutoff is smaller, the provided value will be ignored, the ghost cutoff is set to the neighbor cutoff and
a warning will be printed. Specifying a cutoff value of 0.0 will reset any previous value to the default. If bonded
interactions exist and equilibrium bond length information is available, then also a heuristic based on that bond length
is computed. It is used as communication cutoff, if there is no pair style present and no comm_modify cutoff command
used. Otherwise a warning is printed, if this bond based estimate is larger than the communication cutoff used.
The cutoff/multi option is equivalent to cutoff, but applies to communication mode multi instead. Since the commu-
nication cutoffs are determined per atom collections, a collection specifier is needed and cutoff for one or multiple
collections can be extended. Also ranges of collections using the usual asterisk notation can be given. Collections are
indexed from 1 to N where N is the total number of collections. Note that the arguments for cutoff/multi are parsed
right before each simulation to account for potential changes in the number of collections. Custom cutoffs are preserved
between runs but if collections are redefined, one may want to re-specify the communication cutoffs. For granular pair
styles,the default cutoff is set to the sum of the current maximum atomic radii for each collection. The cutoff/multi/old
option is similar to cutoff/multi except it operates on atom types as opposed to collections.
The reduce/multi option applies to multi and sets the communication cutoff for a particle equal to the maximum in-
teraction distance between particles in the same collection. This reduces the number of ghost atoms that need to be
communicated. This method is only compatible with the multi neighbor style and requires a half neighbor list and
Newton on. See the neighbor multi command for more information.
These are simulation scenarios in which it may be useful or even necessary to set a ghost cutoff > neighbor cutoff:
• a single polymer chain with bond interactions, but no pairwise interactions
• bonded interactions (e.g. dihedrals) extend further than the pairwise cutoff
• ghost atoms beyond the pairwise cutoff are needed for some computation
In the first scenario, a pairwise potential is not defined. Thus the pairwise neighbor cutoff will be 0.0. But ghost
atoms are still needed for computing bond, angle, etc interactions between atoms on different processors, or when the
interaction straddles a periodic boundary.
The appropriate ghost cutoff depends on the newton bond setting. For newton bond off, the distance needs to be the
furthest distance between any two atoms in the bond, angle, etc. E.g. the distance between 1-4 atoms in a dihedral. For
newton bond on, the distance between the central atom in the bond, angle, etc and any other atom is sufficient. E.g. the
distance between 2-4 atoms in a dihedral.
In the second scenario, a pairwise potential is defined, but its neighbor cutoff is not sufficiently long enough to enable
bond, angle, etc terms to be computed. As in the previous scenario, an appropriate ghost cutoff should be set.
In the last scenario, a fix or compute or pairwise potential needs to calculate with ghost atoms beyond the normal
pairwise cutoff for some computation it performs (e.g. locate neighbors of ghost atoms in a manybody pair potential).
Setting the ghost cutoff appropriately can insure it will find the needed atoms.

Note: In these scenarios, if you do not set the ghost cutoff long enough, and if there is only one processor in a periodic
dimension (e.g. you are running in serial), then LAMMPS may “find” the atom it is looking for (e.g. the partner atom

16.13. comm_modify command 651

LAMMPS Documentation, Release stable 29Sep2021

in a bond), that is on the far side of the simulation box, across a periodic boundary. This will typically lead to bad
dynamics (i.e. the bond length is now the simulation box length). To detect if this is happening, see the neigh_modify
cluster command.

The group keyword will limit communication to atoms in the specified group. This can be useful for models where no
ghost atoms are needed for some kinds of particles. All atoms (not just those in the specified group) will still migrate
to new processors as they move. The group specified with this option must also be specified via the atom_modify first
command.
The vel keyword enables velocity information to be communicated with ghost particles. Depending on the atom_style,
velocity info includes the translational velocity, angular velocity, and angular momentum of a particle. If the vel option
is set to yes, then ghost atoms store these quantities; if no then they do not. The yes setting is needed by some pair
styles which require the velocity state of both the I and J particles to compute a pairwise I,J interaction, as well as by
some compute and fix commands.
Note that if the fix deform command is being used with its “remap v” option enabled, then the velocities for ghost atoms
(in the fix deform group) mirrored across a periodic boundary will also include components due to any velocity shift
that occurs across that boundary (e.g. due to dilation or shear).

16.13.4 Restrictions

Communication mode multi is currently only available for comm_style brick.

16.13.5 Related commands

comm_style, neighbor

16.13.6 Default

The option defaults are mode = single, group = all, cutoff = 0.0, vel = no. The cutoff default of 0.0 means that ghost
cutoff = neighbor cutoff = pairwise force cutoff + neighbor skin.

16.14 comm_style command

16.14.1 Syntax

comm_style style

• style = brick or tiled

652 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.14.2 Examples

comm_style brick
comm_style tiled

16.14.3 Description

This command sets the style of inter-processor communication of atom information that occurs each timestep as coor-
dinates and other properties are exchanged between neighboring processors and stored as properties of ghost atoms.
For the default brick style, the domain decomposition used by LAMMPS to partition the simulation box must be a
regular 3d grid of bricks, one per processor. Each processor communicates with its 6 Cartesian neighbors in the grid
to acquire information for nearby atoms.
For the tiled style, a more general domain decomposition can be used, as triggered by the balance or fix balance
commands. The simulation box can be partitioned into non-overlapping rectangular-shaped “tiles” or varying sizes
and shapes. Again there is one tile per processor. To acquire information for nearby atoms, communication must now
be done with a more complex pattern of neighboring processors.
Note that this command does not actually define a partitioning of the simulation box (a domain decomposition), rather
it determines what kinds of decompositions are allowed and the pattern of communication used to enable the decom-
position. A decomposition is created when the simulation box is first created, via the create_box or read_data or
read_restart commands. For both the brick and tiled styles, the initial decomposition will be the same, as described by
create_box and processors commands. The decomposition can be changed via the balance or fix balance commands.

16.14.4 Restrictions

None

16.14.5 Related commands

comm_modify, processors, balance, fix balance

16.14.6 Default

The default style is brick.

16.15 compute command

16.15.1 Syntax

compute ID group-ID style args

• ID = user-assigned name for the computation

• group-ID = ID of the group of atoms to perform the computation on
• style = one of a list of possible style names (see below)
• args = arguments used by a particular style

16.15. compute command 653

LAMMPS Documentation, Release stable 29Sep2021

16.15.2 Examples

compute 1 all temp

compute newtemp flow temp/partial 1 1 0
compute 3 all ke/atom

16.15.3 Description

Define a computation that will be performed on a group of atoms. Quantities calculated by a compute are instantaneous
values, meaning they are calculated from information about atoms on the current timestep or iteration, though a compute
may internally store some information about a previous state of the system. Defining a compute does not perform a
computation. Instead computes are invoked by other LAMMPS commands as needed, e.g. to calculate a temperature
needed for a thermostat fix or to generate thermodynamic or dump file output. See the Howto output page for a summary
of various LAMMPS output options, many of which involve computes.
The ID of a compute can only contain alphanumeric characters and underscores.

Computes calculate one of three styles of quantities: global, per-atom, or local. A global quantity is one or more
system-wide values, e.g. the temperature of the system. A per-atom quantity is one or more values per atom, e.g.
the kinetic energy of each atom. Per-atom values are set to 0.0 for atoms not in the specified compute group. Local
quantities are calculated by each processor based on the atoms it owns, but there may be zero or more per atom, e.g.
a list of bond distances. Computes that produce per-atom quantities have the word “atom” in their style, e.g. ke/atom.
Computes that produce local quantities have the word “local” in their style, e.g. bond/local. Styles with neither “atom”
or “local” in their style produce global quantities.
Note that a single compute can produce either global or per-atom or local quantities, but not both global and per-atom.
It can produce local quantities in tandem with global or per-atom quantities. The compute page will explain.
Global, per-atom, and local quantities each come in three kinds: a single scalar value, a vector of values, or a 2d array
of values. The doc page for each compute describes the style and kind of values it produces, e.g. a per-atom vector.
Some computes produce more than one kind of a single style, e.g. a global scalar and a global vector.
When a compute quantity is accessed, as in many of the output commands discussed below, it can be referenced via
the following bracket notation, where ID is the ID of the compute:

c_ID entire scalar, vector, or array

c_ID[I] one element of vector, one column of array
c_ID[I][J] one element of array

In other words, using one bracket reduces the dimension of the quantity once (vector -> scalar, array -> vector). Using
two brackets reduces the dimension twice (array -> scalar). Thus a command that uses scalar compute values as input
can also process elements of a vector or array.
Note that commands and variables which use compute quantities typically do not allow for all kinds, e.g. a command
may require a vector of values, not a scalar. This means there is no ambiguity about referring to a compute quantity
as c_ID even if it produces, for example, both a scalar and vector. The doc pages for various commands explain the
details.

In LAMMPS, the values generated by a compute can be used in several ways:

• The results of computes that calculate a global temperature or pressure can be used by fixes that do thermostatting
or barostatting or when atom velocities are created.

654 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• Global values can be output via the thermo_style custom or fix ave/time command. Or the values can be referenced
in a variable equal or variable atom command.
• Per-atom values can be output via the dump custom command. Or they can be time-averaged via the fix ave/atom
command or reduced by the compute reduce command. Or the per-atom values can be referenced in an atom-style
variable.
• Local values can be reduced by the compute reduce command, or histogrammed by the fix ave/histo command,
or output by the dump local command.
The results of computes that calculate global quantities can be either “intensive” or “extensive” values. Intensive means
the value is independent of the number of atoms in the simulation, e.g. temperature. Extensive means the value scales
with the number of atoms in the simulation, e.g. total rotational kinetic energy. Thermodynamic output will normalize
extensive values by the number of atoms in the system, depending on the “thermo_modify norm” setting. It will not
normalize intensive values. If a compute value is accessed in another way, e.g. by a variable, you may want to know
whether it is an intensive or extensive value. See the page for individual computes for further info.

LAMMPS creates its own computes internally for thermodynamic output. Three computes are always created, named
“thermo_temp”, “thermo_press”, and “thermo_pe”, as if these commands had been invoked in the input script:

compute thermo_temp all temp

compute thermo_press all pressure thermo_temp
compute thermo_pe all pe

Additional computes for other quantities are created if the thermo style requires it. See the documentation for the
thermo_style command.
Fixes that calculate temperature or pressure, i.e. for thermostatting or barostatting, may also create computes. These
are discussed in the documentation for specific fix commands.
In all these cases, the default computes LAMMPS creates can be replaced by computes defined by the user in the input
script, as described by the thermo_modify and fix modify commands.
Properties of either a default or user-defined compute can be modified via the compute_modify command.
Computes can be deleted with the uncompute command.
Code for new computes can be added to LAMMPS; see the Modify page for details. The results of their calculations
accessed in the various ways described above.

Each compute style has its own page which describes its arguments and what it does. Here is an alphabetic list of
compute styles available in LAMMPS. They are also listed in more compact form on the Commands compute doc
page.
There are also additional accelerated compute styles included in the LAMMPS distribution for faster performance on
CPUs, GPUs, and KNLs. The individual style names on the Commands compute page are followed by one or more of
(g,i,k,o,t) to indicate which accelerated styles exist.
• ackland/atom - determines the local lattice structure based on the Ackland formulation
• adf - angular distribution function of triples of atoms
• aggregate/atom - aggregate ID for each atom
• angle - energy of each angle sub-style
• angle/local - theta and energy of each angle
• angmom/chunk - angular momentum for each chunk

16.15. compute command 655

LAMMPS Documentation, Release stable 29Sep2021

• basal/atom - calculates the hexagonal close-packed “c” lattice vector of each atom
• body/local - attributes of body sub-particles
• bond - energy of each bond sub-style
• bond/local - distance and energy of each bond
• centro/atom - centro-symmetry parameter for each atom
• centroid/stress/atom - centroid based stress tensor for each atom
• chunk/atom - assign chunk IDs to each atom
• chunk/spread/atom - spreads chunk values to each atom in chunk
• cluster/atom - cluster ID for each atom
• cna/atom - common neighbor analysis (CNA) for each atom
• cnp/atom - common neighborhood parameter (CNP) for each atom
• com - center-of-mass of group of atoms
• com/chunk - center-of-mass for each chunk
• contact/atom - contact count for each spherical particle
• coord/atom - coordination number for each atom
• damage/atom - Peridynamic damage for each atom
• dihedral - energy of each dihedral sub-style
• dihedral/local - angle of each dihedral
• dilatation/atom - Peridynamic dilatation for each atom
• dipole - dipole vector and total dipole
• dipole/chunk - dipole vector and total dipole for each chunk
• displace/atom - displacement of each atom
• dpd -
• dpd/atom -
• edpd/temp/atom - per-atom temperature for each eDPD particle in a group
• efield/atom -
• entropy/atom - pair entropy fingerprint of each atom
• erotate/asphere - rotational energy of aspherical particles
• erotate/rigid - rotational energy of rigid bodies
• erotate/sphere - rotational energy of spherical particles
• erotate/sphere/atom - rotational energy for each spherical particle
• event/displace - detect event on atom displacement
• fabric - calculates fabric tensors from pair interactions
• fep -
• force/tally - force between two groups of atoms via the tally callback mechanism
• fragment/atom - fragment ID for each atom

656 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• global/atom -
• group/group - energy/force between two groups of atoms
• gyration - radius of gyration of group of atoms
• gyration/chunk - radius of gyration for each chunk
• gyration/shape - shape parameters from gyration tensor
• gyration/shape/chunk - shape parameters from gyration tensor for each chunk
• heat/flux - heat flux through a group of atoms
• heat/flux/tally - heat flux through a group of atoms via the tally callback mechanism
• heat/flux/virial/tally - virial heat flux between two groups via the tally callback mechanism
• hexorder/atom - bond orientational order parameter q6
• hma - harmonically mapped averaging for atomic crystals
• improper - energy of each improper sub-style
• improper/local - angle of each improper
• inertia/chunk - inertia tensor for each chunk
• ke - translational kinetic energy
• ke/atom - kinetic energy for each atom
• ke/atom/eff - per-atom translational and radial kinetic energy in the electron force field model
• ke/eff - kinetic energy of a group of nuclei and electrons in the electron force field model
• ke/rigid - translational kinetic energy of rigid bodies
• mliap - gradients of energy and forces w.r.t. model parameters and related quantities for training machine learning
interatomic potentials
• momentum - translational momentum
• msd - mean-squared displacement of group of atoms
• msd/chunk - mean-squared displacement for each chunk
• msd/nongauss - MSD and non-Gaussian parameter of group of atoms
• omega/chunk - angular velocity for each chunk
• orientorder/atom - Steinhardt bond orientational order parameters Ql
• pair - values computed by a pair style
• pair/local - distance/energy/force of each pairwise interaction
• pe - potential energy
• pe/atom - potential energy for each atom
• mesont - Nanotube bending,stretching, and intertube energies
• pe/mol/tally - potential energy between two groups of atoms separated into intermolecular and intramolecular
components via the tally callback mechanism
• pe/tally - potential energy between two groups of atoms via the tally callback mechanism
• plasticity/atom - Peridynamic plasticity for each atom
• pressure - total pressure and pressure tensor

16.15. compute command 657

LAMMPS Documentation, Release stable 29Sep2021

• pressure/cylinder - pressure tensor in cylindrical coordinates

• pressure/uef - pressure tensor in the reference frame of an applied flow field
• property/atom - convert atom attributes to per-atom vectors/arrays
• property/chunk - extract various per-chunk attributes
• property/local - convert local attributes to localvectors/arrays
• ptm/atom - determines the local lattice structure based on the Polyhedral Template Matching method
• rdf - radial distribution function g(r) histogram of group of atoms
• reduce - combine per-atom quantities into a single global value
• reduce/chunk - reduce per-atom quantities within each chunk
• reduce/region - same as compute reduce, within a region
• rigid/local - extract rigid body attributes
• saed - electron diffraction intensity on a mesh of reciprocal lattice nodes
• slice - extract values from global vector or array
• smd/contact/radius -
• smd/damage - damage status of SPH particles in Smooth Mach Dynamics
• smd/hourglass/error -
• smd/internal/energy - per-particle enthalpy in Smooth Mach Dynamics
• smd/plastic/strain - equivalent plastic strain per particle in Smooth Mach Dynamics
• smd/plastic/strain/rate - time rate of the equivalent plastic strain in Smooth Mach Dynamics
• smd/rho - per-particle mass density in Smooth Mach Dynamics
• smd/tlsph/defgrad - deformation gradient in Smooth Mach Dynamics
• smd/tlsph/dt - CFL-stable time increment per particle in Smooth Mach Dynamics
• smd/tlsph/num/neighs -
• smd/tlsph/shape -
• smd/tlsph/strain -
• smd/tlsph/strain/rate -
• smd/tlsph/stress - per-particle Cauchy stress tensor for SPH particles
• smd/triangle/vertices -
• smd/ulsph/effm - per-particle effective shear modulus
• smd/ulsph/num/neighs -
• smd/ulsph/strain -
• smd/ulsph/strain/rate -
• smd/ulsph/stress - per-particle Cauchy stress tensor and von Mises equivalent stress in Smooth Mach Dynamics
• smd/vol - per-particle volumes and their sum in Smooth Mach Dynamics
• snap - gradients of SNAP energy and forces w.r.t. linear coefficients and related quantities for fitting SNAP
potentials

658 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• sna/atom - bispectrum components for each atom

• snad/atom - derivative of bispectrum components for each atom
• snav/atom - virial contribution from bispectrum components for each atom
• sph/e/atom - per-atom internal energy of Smooth-Particle Hydrodynamics atoms
• sph/rho/atom - per-atom density of Smooth-Particle Hydrodynamics atoms
• sph/t/atom - per-atom internal temperature of Smooth-Particle Hydrodynamics atoms
• spin - magnetic quantities for a system of atoms having spins
• stress/atom - stress tensor for each atom
• stress/mop - normal components of the local stress tensor using the method of planes
• stress/mop/profile - profile of the normal components of the local stress tensor using the method of planes
• stress/tally - stress between two groups of atoms via the tally callback mechanism
• tdpd/cc/atom - per-atom chemical concentration of a specified species for each tDPD particle
• temp - temperature of group of atoms
• temp/asphere - temperature of aspherical particles
• temp/body - temperature of body particles
• temp/chunk - temperature of each chunk
• temp/com - temperature after subtracting center-of-mass velocity
• temp/cs - temperature based on the center-of-mass velocity of atom pairs that are bonded to each other
• temp/deform - temperature excluding box deformation velocity
• temp/deform/eff - temperature excluding box deformation velocity in the electron force field model
• temp/drude - temperature of Core-Drude pairs
• temp/eff - temperature of a group of nuclei and electrons in the electron force field model
• temp/partial - temperature excluding one or more dimensions of velocity
• temp/profile - temperature excluding a binned velocity profile
• temp/ramp - temperature excluding ramped velocity component
• temp/region - temperature of a region of atoms
• temp/region/eff - temperature of a region of nuclei and electrons in the electron force field model
• temp/rotate - temperature of a group of atoms after subtracting out their center-of-mass and angular velocities
• temp/sphere - temperature of spherical particles
• temp/uef - kinetic energy tensor in the reference frame of an applied flow field
• ti - thermodynamic integration free energy values
• torque/chunk - torque applied on each chunk
• vacf - velocity auto-correlation function of group of atoms
• vcm/chunk - velocity of center-of-mass for each chunk
• viscosity/cos - velocity profile under cosine-shaped acceleration
• voronoi/atom - Voronoi volume and neighbors for each atom

16.15. compute command 659

LAMMPS Documentation, Release stable 29Sep2021

• xrd - x-ray diffraction intensity on a mesh of reciprocal lattice nodes

16.15.4 Restrictions

none

16.15.5 Related commands

uncompute, compute_modify, fix ave/atom, fix ave/time, fix ave/histo

16.15.6 Default

none

16.16 compute_modify command

16.16.1 Syntax

compute_modify compute-ID keyword value ...

• compute-ID = ID of the compute to modify

• one or more keyword/value pairs may be listed
• keyword = extra/dof or extra or dynamic/dof or dynamic
extra/dof value = N
N = # of extra degrees of freedom to subtract
extra syntax is identical to extra/dof , will be disabled at some point
dynamic/dof value = yes or no
yes/no = do or do not re-compute the number of degrees of freedom (DOF)␣
,→contributing to the temperature

dynamic syntax is identical to dynamic/dof , will be disabled at some point

16.16.2 Examples

compute_modify myTemp extra/dof 0

compute_modify newtemp dynamic/dof yes extra/dof 600

660 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.16.3 Description

Modify one or more parameters of a previously defined compute. Not all compute styles support all parameters.
The extra/dof or extra keyword refers to how many degrees-of-freedom are subtracted (typically from 3N) as a nor-
malizing factor in a temperature computation. Only computes that compute a temperature use this option. The default
is 2 or 3 for 2d or 3d systems which is a correction factor for an ensemble of velocities with zero total linear momen-
tum. For compute temp/partial, if one or more velocity components are excluded, the value used for extra is scaled
accordingly. You can use a negative number for the extra parameter if you need to add degrees-of-freedom. See the
compute temp/asphere command for an example.
The dynamic/dof or dynamic keyword determines whether the number of atoms N in the compute group and their
associated degrees of freedom are re-computed each time a temperature is computed. Only compute styles that calculate
a temperature use this option. By default, N and their DOF are assumed to be constant. If you are adding atoms or
molecules to the system (see the fix pour, fix deposit, and fix gcmc commands) or expect atoms or molecules to be lost
(e.g. due to exiting the simulation box or via fix evaporate), then this option should be used to insure the temperature
is correctly normalized.

Note: The extra and dynamic keywords should not be used as they are deprecated (March 2017) and will eventually
be disabled. Instead, use the equivalent extra/dof and dynamic/dof keywords.

16.16.4 Restrictions

none

16.16.5 Related commands

compute

16.16.6 Default

The option defaults are extra/dof = 2 or 3 for 2d or 3d systems and dynamic/dof = no.

16.17 create_atoms command

16.17.1 Syntax

create_atoms type style args keyword values ...

• type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)
• style = box or region or single or random
box args = none
region args = region-ID
region-ID = particles will only be created if contained in the region
single args = x y z
x,y,z = coordinates of a single particle (distance units)
random args = N seed region-ID
N = number of particles to create

16.17. create_atoms command 661

LAMMPS Documentation, Release stable 29Sep2021

seed = random # seed (positive integer)

region-ID = create atoms within this region, use NULL for entire simulation box
• zero or more keyword/value pairs may be appended
• keyword = mol or basis or ratio or subset or remap or var or set or rotate or units
mol value = template-ID seed
template-ID = ID of molecule template specified in a separate molecule command
seed = random # seed (positive integer)
basis values = M itype
M = which basis atom
itype = atom type (1-N) to assign to this basis atom
ratio values = frac seed
frac = fraction of lattice sites (0 to 1) to populate randomly
seed = random # seed (positive integer)
subset values = Nsubset seed
Nsubset = # of lattice sites to populate randomly
seed = random # seed (positive integer)
remap value = yes or no
var value = name = variable name to evaluate for test of atom creation
set values = dim name
dim = x or y or z
name = name of variable to set with x, y, or z atom position
rotate values = theta Rx Ry Rz
theta = rotation angle for single molecule (degrees)
Rx,Ry,Rz = rotation vector for single molecule
units value = lattice or box
lattice = the geometry is defined in lattice units
box = the geometry is defined in simulation box units

16.17.2 Examples

create_atoms 1 box
create_atoms 3 region regsphere basis 2 3
create_atoms 3 region regsphere basis 2 3 ratio 0.5 74637
create_atoms 3 single 0 0 5
create_atoms 1 box var v set x xpos set y ypos

16.17.3 Description

This command creates atoms (or molecules) on a lattice, or a single atom (or molecule), or a random collection of atoms
(or molecules), as an alternative to reading in their coordinates explicitly via a read_data or read_restart command. A
simulation box must already exist, which is typically created via the create_box command. Before using this command,
a lattice must also be defined using the lattice command, unless you specify the single style with units = box or the
random style. For the remainder of this doc page, a created atom or molecule is referred to as a “particle”.
If created particles are individual atoms, they are assigned the specified atom type, though this can be altered via the
basis keyword as discussed below. If molecules are being created, the type of each atom in the created molecule is
specified in the file read by the molecule command, and those values are added to the specified atom type. E.g. if type
= 2, and the file specifies atom types 1,2,3, then each created molecule will have atom types 3,4,5.
For the box style, the create_atoms command fills the entire simulation box with particles on the lattice. If your simu-
lation box is periodic, you should insure its size is a multiple of the lattice spacings, to avoid unwanted atom overlaps

662 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

at the box boundaries. If your box is periodic and a multiple of the lattice spacing in a particular dimension, LAMMPS
is careful to put exactly one particle at the boundary (on either side of the box), not zero or two.
For the region style, a geometric volume is filled with particles on the lattice. This volume what is inside the simulation
box and is also consistent with the region volume. See the region command for details. Note that a region can be
specified so that its “volume” is either inside or outside a geometric boundary. Also note that if your region is the same
size as a periodic simulation box (in some dimension), LAMMPS does not implement the same logic described above
as for the box style, to insure exactly one particle at periodic boundaries. if this is what you desire, you should either
use the box style, or tweak the region size to get precisely the particles you want.
For the single style, a single particle is added to the system at the specified coordinates. This can be useful for debugging
purposes or to create a tiny system with a handful of particles at specified positions.
For the random style, N particles are added to the system at randomly generated coordinates, which can be useful
for generating an amorphous system. The particles are created one by one using the specified random number seed,
resulting in the same set of particles coordinates, independent of how many processors are being used in the simulation.
If the region-ID argument is specified as NULL, then the created particles will be anywhere in the simulation box. If a
region-ID is specified, a geometric volume is filled which is both inside the simulation box and is also consistent with
the region volume. See the region command for details. Note that a region can be specified so that its “volume” is
either inside or outside a geometric boundary.

Note: Particles generated by the random style will typically be highly overlapped which will cause many interatomic
potentials to compute large energies and forces. Thus you should either perform an energy minimization or run dynamics
with fix nve/limit to equilibrate such a system, before running normal dynamics.

Note that this command adds particles to those that already exist. This means it can be used to add particles to a
system previously read in from a data or restart file. Or the create_atoms command can be used multiple times, to add
multiple sets of particles to the simulation. For example, grain boundaries can be created, by interleaving create_atoms
with lattice commands specifying different orientations. By using the create_atoms command in conjunction with the
delete_atoms command, reasonably complex geometries can be created, or a protein can be solvated with a surrounding
box of water molecules.
In all these cases, care should be taken to insure that new atoms do not overlap existing atoms inappropriately, especially
if molecules are being added. The delete_atoms command can be used to remove overlapping atoms or molecules.

Note: You cannot use any of the styles explained above to create atoms that are outside the simulation box; they will
just be ignored by LAMMPS. This is true even if you are using shrink-wrapped box boundaries, as specified by the
boundary command. However, you can first use the change_box command to temporarily expand the box, then add
atoms via create_atoms, then finally use change_box command again if needed to re-shrink-wrap the new atoms. See
the change_box page for an example of how to do this, using the create_atoms single style to insert a new atom outside
the current simulation box.

Individual atoms are inserted by this command, unless the mol keyword is used. It specifies a template-ID previously
defined using the molecule command, which reads a file that defines the molecule. The coordinates, atom types, charges,
etc, as well as any bond/angle/etc and special neighbor information for the molecule can be specified in the molecule
file. See the molecule command for details. The only settings required to be in this file are the coordinates and types
of atoms in the molecule.
Using a lattice to add molecules, e.g. via the box or region or single styles, is exactly the same as adding atoms on
lattice points, except that entire molecules are added at each point, i.e. on the point defined by each basis atom in the
unit cell as it tiles the simulation box or region. This is done by placing the geometric center of the molecule at the
lattice point, and giving the molecule a random orientation about the point. The random seed specified with the mol
keyword is used for this operation, and the random numbers generated by each processor are different. This means the

16.17. create_atoms command 663

LAMMPS Documentation, Release stable 29Sep2021

coordinates of individual atoms (in the molecules) will be different when running on different numbers of processors,
unlike when atoms are being created in parallel.
Also note that because of the random rotations, it may be important to use a lattice with a large enough spacing that
adjacent molecules will not overlap, regardless of their relative orientations.

Note: If the create_box command is used to create the simulation box, followed by the create_atoms command with
its mol option for adding molecules, then you typically need to use the optional keywords allowed by the create_box
command for extra bonds (angles,etc) or extra special neighbors. This is because by default, the create_box command
sets up a non-molecular system which does not allow molecules to be added.

This is the meaning of the other allowed keywords.

The basis keyword is only used when atoms (not molecules) are being created. It specifies an atom type that will be
assigned to specific basis atoms as they are created. See the lattice command for specifics on how basis atoms are
defined for the unit cell of the lattice. By default, all created atoms are assigned the argument type as their atom type.
The ratio and subset keywords can be used in conjunction with the box or region styles to limit the total number of
particles inserted. The lattice defines a set of Nlatt eligible sites for inserting particles, which may be limited by the
region style or the var and set keywords. For the ratio keyword only the specified fraction of them (0 <= frac <= 1) will
be assigned particles. For the subset keyword only the specified Nsubset of them will be assigned particles. In both
cases the assigned lattice sites are chosen randomly. An iterative algorithm is used which insures the correct number
of particles are inserted, in a perfectly random fashion. Which lattice sites are selected will change with the number of
processors used.
The remap keyword only applies to the single style. If it is set to yes, then if the specified position is outside the
simulation box, it will mapped back into the box, assuming the relevant dimensions are periodic. If it is set to no, no
remapping is done and no particle is created if its position is outside the box.
The var and set keywords can be used together to provide a criterion for accepting or rejecting the addition of an
individual atom, based on its coordinates. The name specified for the var keyword is the name of an equal-style variable
which should evaluate to a zero or non-zero value based on one or two or three variables which will store the x, y, or
z coordinates of an atom (one variable per coordinate). If used, these other variables must be internal-style variables
defined in the input script; their initial numeric value can be anything. They must be internal-style variables, because
this command resets their values directly. The set keyword is used to identify the names of these other variables, one
variable for the x-coordinate of a created atom, one for y, and one for z.
When an atom is created, its x,y,z coordinates become the values for any set variable that is defined. The var variable
is then evaluated. If the returned value is 0.0, the atom is not created. If it is non-zero, the atom is created.
As an example, these commands can be used in a 2d simulation, to create a sinusoidal surface. Note that the surface
is “rough” due to individual lattice points being “above” or “below” the mathematical expression for the sinusoidal
curve. If a finer lattice were used, the sinusoid would appear to be “smoother”. Also note the use of the “xlat” and
“ylat” thermo_style keywords which converts lattice spacings to distance.

dimension 2
variable x equal 100
variable y equal 25
lattice hex 0.8442
region box block 0 $x 0 $y -0.5 0.5
create_box 1 box

variable xx internal 0.0

variable yy internal 0.0
(continues on next page)

664 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

variable v equal "(0.2*v_y*ylat * cos(v_xx/xlat * 2.0*PI*4.0/v_x) + 0.5*v_y*ylat -
,→ v_yy) > 0.0"

create_atoms 1 box var v set x xx set y yy

write_dump all atom sinusoid.lammpstrj

The rotate keyword allows specification of the orientation at which molecules are inserted. The axis of rotation is
determined by the rotation vector (Rx,Ry,Rz) that goes through the insertion point. The specified theta determines the
angle of rotation around that axis. Note that the direction of rotation for the atoms around the rotation axis is consistent
with the right-hand rule: if your right-hand’s thumb points along R, then your fingers wrap around the axis in the
direction of rotation.
The units keyword determines the meaning of the distance units used to specify the coordinates of the one particle
created by the single style. A box value selects standard distance units as defined by the units command, e.g. Angstroms
for units = real or metal. A lattice value means the distance units are in lattice spacings.

Atom IDs are assigned to created atoms in the following way. The collection of created atoms are assigned consecutive
IDs that start immediately following the largest atom ID existing before the create_atoms command was invoked. This
is done by the processor’s communicating the number of atoms they each own, the first processor numbering its atoms
from 1 to N1, the second processor from N1+1 to N2, etc. Where N1 = number of atoms owned by the first processor,
N2 = number owned by the second processor, etc. Thus when the same simulation is performed on different numbers
of processors, there is no guarantee a particular created atom will be assigned the same ID in both simulations. If
molecules are being created, molecule IDs are assigned to created molecules in a similar fashion.
Aside from their ID, atom type, and xyz position, other properties of created atoms are set to default values, depending
on which quantities are defined by the chosen atom style. See the atom style command for more details. See the set and
velocity commands for info on how to change these values.
• charge = 0.0
• dipole moment magnitude = 0.0
• diameter = 1.0
• shape = 0.0 0.0 0.0
• density = 1.0
• volume = 1.0
• velocity = 0.0 0.0 0.0
• angular velocity = 0.0 0.0 0.0

16.17. create_atoms command 665

LAMMPS Documentation, Release stable 29Sep2021

• angular momentum = 0.0 0.0 0.0

• quaternion = (1,0,0,0)
• bonds, angles, dihedrals, impropers = none
If molecules are being created, these defaults can be overridden by values specified in the file read by the molecule
command. E.g. the file typically defines bonds (angles,etc) between atoms in the molecule, and can optionally define
charges on each atom.
Note that the sphere atom style sets the default particle diameter to 1.0 as well as the density. This means the mass for
the particle is not 1.0, but is PI/6 * diameter^3 = 0.5236.
Note that the ellipsoid atom style sets the default particle shape to (0.0 0.0 0.0) and the density to 1.0 which means it
is a point particle, not an ellipsoid, and has a mass of 1.0.
Note that the peri style sets the default volume and density to 1.0 and thus also set the mass for the particle to 1.0.
The set command can be used to override many of these default settings.

16.17.4 Restrictions

An atom_style must be previously defined to use this command.

A rotation vector specified for a single molecule must be in the z-direction for a 2d model.

16.17.5 Related commands

lattice, region, create_box, read_data, read_restart

16.17.6 Default

The default for the basis keyword is that all created atoms are assigned the argument type as their atom type (when
single atoms are being created). The other defaults are remap = no, rotate = random, and units = lattice.

16.18 create_bonds command

16.18.1 Syntax

create_bonds style args ... keyword value ...

• style = many or single/bond or single/angle or single/dihedral

many args = group-ID group2-ID btype rmin rmax
group-ID = ID of first group
group2-ID = ID of second group, bonds will be between atoms in the 2 groups
btype = bond type of created bonds
rmin = minimum distance between pair of atoms to bond together
rmax = maximum distance between pair of atoms to bond together
single/bond args = btype batom1 batom2
btype = bond type of new bond
batom1,batom2 = atom IDs for two atoms in bond

666 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

single/angle args = atype aatom1 aatom2 aatom3

atype = angle type of new angle
aatom1,aatom2,aatom3 = atom IDs for three atoms in angle
single/dihedral args = dtype datom1 datom2 datom3 datom4
dtype = dihedral type of new dihedral
datom1,datom2,datom3,datom4 = atom IDs for four atoms in dihedral
single/improper args = itype iatom1 iatom2 iatom3 iatom4
itype = improper type of new improper
iatom1,iatom2,iatom3,iatom4 = atom IDs for four atoms in improper
• zero or more keyword/value pairs may be appended
• keyword = special
special value = yes or no

16.18.2 Examples

create_bonds many all all 1 1.0 1.2

create_bonds many surf solvent 3 2.0 2.4
create_bonds single/bond 1 1 2
create_bonds single/angle 5 52 98 107 special no
create_bonds single/dihedral 2 4 19 27 101
create_bonds single/improper 3 23 26 31 57

16.18.3 Description

Create bonds between pairs of atoms that meet a specified distance criteria. Or create a single bond, angle, dihedral or
improper between 2, 3, or 4 specified atoms.
The new bond (angle, dihedral, improper) interactions will then be computed during a simulation by the bond (angle,
dihedral, improper) potential defined by the bond_style, bond_coeff , angle_style, angle_coeff , dihedral_style, dihe-
dral_coeff , improper_style, improper_coeff commands.
The many style is useful for adding bonds to a system, e.g. between nearest neighbors in a lattice of atoms, without
having to enumerate all the bonds in the data file read by the read_data command.
The single styles are useful for adding bonds, angles, dihedrals, impropers to a system incrementally, then continuing
a simulation.
Note that this command does not auto-create any angle, dihedral or improper interactions when a bond is added. Nor
does it auto-create any bonds when an angle, dihedral or improper is added. Or auto-create any angles when a dihedral
or improper is added. Thus the flexibility of this command is limited. It can be used several times to create different
types of bond at different distances. But it cannot typically auto-create all the bonds or angles or dihedrals or impropers
that would normally be defined in a data file for a complex system of molecules.

Note: If the system has no bonds (angles, dihedrals, impropers) to begin with, or if more bonds per atom are being
added than currently exist, then you must insure that the number of bond types and the maximum number of bonds per
atom are set to large enough values. And similarly for angles, dihedrals and impropers. Otherwise an error may occur
when too many bonds (angles, dihedrals, impropers) are added to an atom. If the read_data command is used to define
the system, these parameters can be set via the “bond types” and “extra bond per atom” fields in the header section of
the data file. If the create_box command is used to define the system, these 2 parameters can be set via its optional
“bond/types” and “extra/bond/per/atom” arguments. And similarly for angles, dihedrals and impropers. See the doc
pages for these 2 commands for details.

16.18. create_bonds command 667

LAMMPS Documentation, Release stable 29Sep2021

The many style will create bonds between pairs of atoms I,J where I is in one of the two specified groups, and J is in the
other. The two groups can be the same, e.g. group “all”. The created bonds will be of bond type btype, where btype
must be a value between 1 and the number of bond types defined.
For a bond to be created, an I,J pair of atoms must be a distance D apart such that rmin <= D <= rmax.
The following settings must have been made in an input script before this style is used:
• special_bonds weight for 1-2 interactions must be 0.0
• a pair_style must be defined
• no kspace_style defined
• minimum pair_style cutoff + neighbor skin >= rmax
These settings are required so that a neighbor list can be created to search for nearby atoms. Pairs of atoms that are
already bonded cannot appear in the neighbor list, to avoid creation of duplicate bonds. The neighbor list for all atom
type pairs must also extend to a distance that encompasses the rmax for new bonds to create.

Note: If you want to create bonds between pairs of 1-3 or 1-4 atoms in the current bond topology, then you need
to use special_bonds lj 0 1 1 to insure those pairs appear in the neighbor list. They will not appear with the default
special_bonds settings which are zero for 1-2, 1-3, and 1-4 atoms. 1-3 or 1-4 atoms are those which are 2 hops or 3
hops apart in the bond topology.

An additional requirement for this style is that your system must be ready to perform a simulation. This means, for
example, that all pair_style coefficients be set via the pair_coeff command. A bond_style command and all bond
coefficients must also be set, even if no bonds exist before this command is invoked. This is because the building of
neighbor list requires initialization and setup of a simulation, similar to what a run command would require.
Note that you can change any of these settings after this command executes, e.g. if you wish to use long-range Coulom-
bic interactions via the kspace_style command for your subsequent simulation.

The single/bond style creates a single bond of type btype between two atoms with IDs batom1 and batom2. Btype must
be a value between 1 and the number of bond types defined.
The single/angle style creates a single angle of type atype between three atoms with IDs aatom1, aatom2, and aatom3.
The ordering of the atoms is the same as in the Angles section of a data file read by the read_data command. I.e. the
3 atoms are ordered linearly within the angle; the central atom is aatom2. Atype must be a value between 1 and the
number of angle types defined.
The single/dihedral style creates a single dihedral of type dtype between four atoms with IDs datom1, datom2, datom3,
and datom4. The ordering of the atoms is the same as in the Dihedrals section of a data file read by the read_data
command. I.e. the 4 atoms are ordered linearly within the dihedral. dtype must be a value between 1 and the number
of dihedral types defined.
The single/improper style creates a single improper of type itype between four atoms with IDs iatom1, iatom2, iatom3,
and iatom4. The ordering of the atoms is the same as in the Impropers section of a data file read by the read_data
command. I.e. the 4 atoms are ordered linearly within the improper. itype must be a value between 1 and the number
of improper types defined.

The keyword special controls whether an internal list of special bonds is created after one or more bonds, or a single
angle, dihedral or improper is added to the system.
The default value is yes. A value of no cannot be used with the many style.

668 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

This is an expensive operation since the bond topology for the system must be walked to find all 1-2, 1-3, 1-4 interactions
to store in an internal list, which is used when pairwise interactions are weighted; see the special_bonds command for
details.
Thus if you are adding a few bonds or a large list of angles all at the same time, by using this command repeatedly, it is
more efficient to only trigger the internal list to be created once, after the last bond (or angle, or dihedral, or improper)
is added:

create_bonds single/bond 5 52 98 special no

create_bonds single/bond 5 73 74 special no
...
create_bonds single/bond 5 17 386 special no
create_bonds single/bond 4 112 183 special yes

Note that you MUST insure the internal list is re-built after the last bond (angle, dihedral, improper) is added, before
performing a simulation. Otherwise pairwise interactions will not be properly excluded or weighted. LAMMPS does
NOT check that you have done this correctly.

16.18.4 Restrictions

This command cannot be used with molecular systems defined using molecule template files via the molecule and
atom_style template commands.

16.18.5 Related commands

create_atoms, delete_bonds

16.18.6 Default

The keyword default is special = yes.

16.19 create_box command

16.19.1 Syntax

create_box N region-ID keyword value ...

• N = # of atom types to use in this simulation

• region-ID = ID of region to use as simulation domain
• zero or more keyword/value pairs may be appended
• keyword = bond/types or angle/types or dihedral/types or improper/types or extra/bond/per/atom or ex-
tra/angle/per/atom or extra/dihedral/per/atom or extra/improper/per/atom or extra/special/per/atom
bond/types value = # of bond types
angle/types value = # of angle types
dihedral/types value = # of dihedral types
improper/types value = # of improper types

16.19. create_box command 669

LAMMPS Documentation, Release stable 29Sep2021

extra/bond/per/atom value = # of bonds per atom

extra/angle/per/atom value = # of angles per atom
extra/dihedral/per/atom value = # of dihedrals per atom
extra/improper/per/atom value = # of impropers per atom
extra/special/per/atom value = # of special neighbors per atom

16.19.2 Examples

create_box 2 mybox
create_box 2 mybox bond/types 2 extra/bond/per/atom 1

16.19.3 Description

This command creates a simulation box based on the specified region. Thus a region command must first be used to
define a geometric domain. It also partitions the simulation box into a regular 3d grid of rectangular bricks, one per
processor, based on the number of processors being used and the settings of the processors command. The partitioning
can later be changed by the balance or fix balance commands.
The argument N is the number of atom types that will be used in the simulation.
If the region is not of style prism, then LAMMPS encloses the region (block, sphere, etc) with an axis-aligned orthog-
onal bounding box which becomes the simulation domain.
If the region is of style prism, LAMMPS creates a non-orthogonal simulation domain shaped as a parallelepiped with
triclinic symmetry. As defined by the region prism command, the parallelepiped has its “origin” at (xlo,ylo,zlo) and
is defined by 3 edge vectors starting from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C = (xz,yz,zhi-
zlo). Xy,xz,yz can be 0.0 or positive or negative values and are called “tilt factors” because they are the amount of
displacement applied to faces of an originally orthogonal box to transform it into the parallelepiped.
By default, a prism region used with the create_box command must have tilt factors (xy,xz,yz) that do not skew the box
more than half the distance of the parallel box length. For example, if xlo = 2 and xhi = 12, then the x box length is 10
and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2.
Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then configurations with tilt
= . . . , -15, -5, 5, 15, 25, . . . are all geometrically equivalent. If you wish to define a box with tilt factors that exceed
these limits, you can use the box tilt command, with a setting of large; a setting of small is the default.
See the Howto triclinic page for a geometric description of triclinic boxes, as defined by LAMMPS, and how to trans-
form these parameters to and from other commonly used triclinic representations.
When a prism region is used, the simulation domain should normally be periodic in the dimension that the tilt is applied
to, which is given by the second dimension of the tilt factor (e.g. y for xy tilt). This is so that pairs of atoms interacting
across that boundary will have one of them shifted by the tilt factor. Periodicity is set by the boundary command. For
example, if the xy tilt factor is non-zero, then the y dimension should be periodic. Similarly, the z dimension should be
periodic if xz or yz is non-zero. LAMMPS does not require this periodicity, but you may lose atoms if this is not the
case.
Also note that if your simulation will tilt the box, e.g. via the fix deform command, the simulation box must be setup
to be triclinic, even if the tilt factors are initially 0.0. You can also change an orthogonal box to a triclinic box or vice
versa by using the change box command with its ortho and triclinic options.

Note: If the system is non-periodic (in a dimension), then you should not make the lo/hi box dimensions (as defined
in your region command) radically smaller/larger than the extent of the atoms you eventually plan to create, e.g. via
the create_atoms command. For example, if your atoms extend from 0 to 50, you should not specify the box bounds as
-10000 and 10000. This is because as described above, LAMMPS uses the specified box size to layout the 3d grid of

670 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

processors. A huge (mostly empty) box will be sub-optimal for performance when using “fixed” boundary conditions
(see the boundary command). When using “shrink-wrap” boundary conditions (see the boundary command), a huge
(mostly empty) box may cause a parallel simulation to lose atoms the first time that LAMMPS shrink-wraps the box
around the atoms.

The optional keywords can be used to create a system that allows for bond (angle, dihedral, improper) interactions, or
for molecules with special 1-2,1-3,1-4 neighbors to be added later. These optional keywords serve the same purpose
as the analogous keywords that can be used in a data file which are recognized by the read_data command when it sets
up a system.
Note that if these keywords are not used, then the create_box command creates an atomic (non-molecular) simulation
that does not allow bonds between pairs of atoms to be defined, or a bond potential to be specified, or for molecules
with special neighbors to be added to the system by commands such as create_atoms mol, fix deposit or fix pour.
As an example, see the examples/deposit/in.deposit.molecule script, which deposits molecules onto a substrate. Initially
there are no molecules in the system, but they are added later by the fix deposit command. The create_box command in
the script uses the bond/types and extra/bond/per/atom keywords to allow this. If the added molecule contained more
than 1 special bond (allowed by default), an extra/special/per/atom keyword would also need to be specified.

16.19.4 Restrictions

An atom_style and region must have been previously defined to use this command.

16.19.5 Related commands

read_data, create_atoms, region

16.19.6 Default

none

16.20 delete_atoms command

16.20.1 Syntax

delete_atoms style args keyword value ...

• style = group or region or overlap or porosity

group args = group-ID
region args = region-ID
overlap args = cutoff group1-ID group2-ID
cutoff = delete one atom from pairs of atoms within the cutoff (distance units)
group1-ID = one atom in pair must be in this group
group2-ID = other atom in pair must be in this group
porosity args = region-ID fraction seed
region-ID = region within which to perform deletions

16.20. delete_atoms command 671

LAMMPS Documentation, Release stable 29Sep2021

fraction = delete this fraction of atoms

seed = random number seed (positive integer)
• zero or more keyword/value pairs may be appended
• keyword = compress or bond or mol
compress value = no or yes
bond value = no or yes
mol value = no or yes

16.20.2 Examples

delete_atoms group edge

delete_atoms region sphere compress no
delete_atoms overlap 0.3 all all
delete_atoms overlap 0.5 solvent colloid
delete_atoms porosity cube 0.1 482793 bond yes

16.20.3 Description

Delete the specified atoms. This command can be used to carve out voids from a block of material or to delete created
atoms that are too close to each other (e.g. at a grain boundary).
For style group, all atoms belonging to the group are deleted.
For style region, all atoms in the region volume are deleted. Additional atoms can be deleted if they are in a molecule
for which one or more atoms were deleted within the region; see the mol keyword discussion below.
For style overlap pairs of atoms whose distance of separation is within the specified cutoff distance are searched for,
and one of the 2 atoms is deleted. Only pairs where one of the two atoms is in the first group specified and the other
atom is in the second group are considered. The atom that is in the first group is the one that is deleted.
Note that it is OK for the two group IDs to be the same (e.g. group all), or for some atoms to be members of both groups.
In these cases, either atom in the pair may be deleted. Also note that if there are atoms which are members of both
groups, the only guarantee is that at the end of the deletion operation, enough deletions will have occurred that no atom
pairs within the cutoff will remain (subject to the group restriction). There is no guarantee that the minimum number
of atoms will be deleted, or that the same atoms will be deleted when running on different numbers of processors.
For style porosity a specified fraction of atoms are deleted within the specified region. For example, if fraction is
0.1, then 10% of the atoms will be deleted. The atoms to delete are chosen randomly. There is no guarantee that the
exact fraction of atoms will be deleted, or that the same atoms will be deleted when running on different numbers of
processors.
If the compress keyword is set to yes, then after atoms are deleted, then atom IDs are re-assigned so that they run from
1 to the number of atoms in the system. Note that this is not done for molecular systems (see the atom_style command),
regardless of the compress setting, since it would foul up the bond connectivity that has already been assigned. However,
the reset_atom_ids command can be used after this command to accomplish the same thing.
Note that the re-assignment of IDs is not really a compression, where gaps in atom IDs are removed by decrementing
atom IDs that are larger. Instead the IDs for all atoms are erased, and new IDs are assigned so that the atoms owned by
individual processors have consecutive IDs, as the create_atoms command explains.
A molecular system with fixed bonds, angles, dihedrals, or improper interactions, is one where the topology of the
interactions is typically defined in the data file read by the read_data command, and where the interactions themselves
are defined with the bond_style, angle_style, etc commands. If you delete atoms from such a system, you must be
careful not to end up with bonded interactions that are stored by remaining atoms but which include deleted atoms.

672 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

This will cause LAMMPS to generate a “missing atoms” error when the bonded interaction is computed. The bond
and mol keywords offer two ways to do that.
It the bond keyword is set to yes then any bond or angle or dihedral or improper interaction that includes a deleted atom
is also removed from the lists of such interactions stored by non-deleted atoms. Note that simply deleting interactions
due to dangling bonds (e.g. at a surface) may result in a inaccurate or invalid model for the remaining atoms.
It the mol keyword is set to yes, then for every atom that is deleted, all other atoms in the same molecule (with the same
molecule ID) will also be deleted. This is not done for atoms with molecule ID = 0, since such an ID is assumed to flag
isolated atoms that are not part of molecules.

Note: The molecule deletion operation in invoked after all individual atoms have been deleted using the rules described
above for each style. This means additional atoms may be deleted that are not in the group or region, that are not required
by the overlap cutoff criterion, or that will create a higher fraction of porosity than was requested.

16.20.4 Restrictions

The overlap styles requires inter-processor communication to acquire ghost atoms and build a neighbor list. This means
that your system must be ready to perform a simulation before using this command (force fields setup, atom masses set,
etc). Since a neighbor list is used to find overlapping atom pairs, it also means that you must define a pair style with
the minimum force cutoff distance between any pair of atoms types (plus the neighbor skin) >= the specified overlap
cutoff.
If the special_bonds command is used with a setting of 0, then a pair of bonded atoms (1-2, 1-3, or 1-4) will not appear
in the neighbor list, and thus will not be considered for deletion by the overlap styles. You probably don’t want to be
deleting one atom in a bonded pair anyway.
The bond yes option cannot be used with molecular systems defined using molecule template files via the molecule and
atom_style template commands.

16.20.5 Related commands

create_atoms, reset_atom_ids

16.20.6 Default

The option defaults are compress = yes, bond = no, mol = no.

16.21 delete_bonds command

16.21.1 Syntax

delete_bonds group-ID style arg keyword ...

• group-ID = group ID
• style = multi or atom or bond or angle or dihedral or improper or stats

16.21. delete_bonds command 673

LAMMPS Documentation, Release stable 29Sep2021

multi arg = none

atom arg = an atom type or range of types (see below)
bond arg = a bond type or range of types (see below)
angle arg = an angle type or range of types (see below)
dihedral arg = a dihedral type or range of types (see below)
improper arg = an improper type or range of types (see below)
stats arg = none
• zero or more keywords may be appended
• keyword = any or undo or remove or special

16.21.2 Examples

delete_bonds frozen multi remove

delete_bonds all atom 4 special
delete_bonds all bond 0*3 special
delete_bonds all stats

16.21.3 Description

Turn off (or on) molecular topology interactions, i.e. bonds, angles, dihedrals, impropers. This command is useful
for deleting interactions that have been previously turned off by bond-breaking potentials. It is also useful for turning
off topology interactions between frozen or rigid atoms. Pairwise interactions can be turned off via the neigh_modify
exclude command. The fix shake command also effectively turns off certain bond and angle interactions.
For all styles, by default, an interaction is only turned off (or on) if all the atoms involved are in the specified group.
See the any keyword to change the behavior.
Several of the styles (atom, bond, angle, dihedral, improper) take a type as an argument. The specified type should be
an integer from 0 to N, where N is the number of relevant types (atom types, bond types, etc). A value of 0 is only
relevant for style bond; see details below. In all cases, a wildcard asterisk can be used in place of or in conjunction with
the type argument to specify a range of types. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of
types, then an asterisk with no numeric values means all types from 0 to N. A leading asterisk means all types from 0
to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m
to n (inclusive). Note that it is fine to include a type of 0 for non-bond styles; it will simply be ignored.
For style multi all bond, angle, dihedral, and improper interactions of any type, involving atoms in the group, are turned
off.
Style atom is the same as style multi except that in addition, one or more of the atoms involved in the bond, angle,
dihedral, or improper interaction must also be of the specified atom type.
For style bond, only bonds are candidates for turn-off, and the bond must also be of the specified type. Styles angle,
dihedral, and improper are treated similarly.
For style bond, you can set the type to 0 to delete bonds that have been previously broken by a bond-breaking potential
(which sets the bond type to 0 when a bond is broken); e.g. see the bond_style quartic command.
For style stats no interactions are turned off (or on); the status of all interactions in the specified group is simply reported.
This is useful for diagnostic purposes if bonds have been turned off by a bond-breaking potential during a previous run.
The default behavior of the delete_bonds command is to turn off interactions by toggling their type to a negative value,
but not to permanently remove the interaction. E.g. a bond_type of 2 is set to -2. The neighbor list creation routines
will not include such an interaction in their interaction lists. The default is also to not alter the list of 1-2, 1-3, 1-4

674 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

neighbors computed by the special_bonds command and used to weight pairwise force and energy calculations. This
means that pairwise computations will proceed as if the bond (or angle, etc) were still turned on.
Several keywords can be appended to the argument list to alter the default behaviors.
The any keyword changes the requirement that all atoms in the bond (angle, etc) must be in the specified group in order
to turn-off the interaction. Instead, if any of the atoms in the interaction are in the specified group, it will be turned off
(or on if the undo keyword is used).
The undo keyword inverts the delete_bonds command so that the specified bonds, angles, etc are turned on if they are
currently turned off. This means a negative value is toggled to positive. For example, for style angle, if type is specified
as 2, then all angles with current type = -2, are reset to type = 2. Note that the fix shake command also sets bond and
angle types negative, so this option should not be used on those interactions.
The remove keyword is invoked at the end of the delete_bonds operation. It causes turned-off bonds (angles, etc) to
be removed from each atom’s data structure and then adjusts the global bond (angle, etc) counts accordingly. Removal
is a permanent change; removed bonds cannot be turned back on via the undo keyword. Removal does not alter the
pairwise 1-2, 1-3, 1-4 weighting list.
The special keyword is invoked at the end of the delete_bonds operation, after (optional) removal. It re-computes the
pairwise 1-2, 1-3, 1-4 weighting list. The weighting list computation treats turned-off bonds the same as turned-on.
Thus, turned-off bonds must be removed if you wish to change the weighting list.
Note that the choice of remove and special options affects how 1-2, 1-3, 1-4 pairwise interactions will be computed
across bonds that have been modified by the delete_bonds command.

16.21.4 Restrictions

This command requires inter-processor communication to acquire ghost atoms, to coordinate the deleting of bonds,
angles, etc between atoms shared by multiple processors. This means that your system must be ready to perform
a simulation before using this command (force fields setup, atom masses set, etc). Just as would be needed to run
dynamics, the force field you define should define a cutoff (e.g. through a pair_style command) which is long enough
for a processor to acquire the ghost atoms its needs to compute bond, angle, etc interactions.
If deleted bonds (angles, etc) are removed but the 1-2, 1-3, 1-4 weighting list is not re-computed, this can cause a later
fix shake command to fail due to an atom’s bonds being inconsistent with the weighting list. This should only happen if
the group used in the fix command includes both atoms in the bond, in which case you probably should be recomputing
the weighting list.

16.21.5 Related commands

neigh_modify exclude, special_bonds, fix shake

16.21.6 Default

none

16.21. delete_bonds command 675

LAMMPS Documentation, Release stable 29Sep2021

16.22 dielectric command

16.22.1 Syntax

dielectric value

• value = dielectric constant

16.22.2 Examples

dielectric 2.0

16.22.3 Description

Set the dielectric constant for Coulombic interactions (pairwise and long-range) to this value. The constant is unitless,
since it is used to reduce the strength of the interactions. The value is used in the denominator of the formulas for
Coulombic interactions - e.g. a value of 4.0 reduces the Coulombic interactions to 25% of their default strength. See
the pair_style command for more details.

16.22.4 Restrictions

none

16.22.5 Related commands

pair_style

16.22.6 Default

dielectric 1.0

16.23 dihedral_coeff command

16.23.1 Syntax

dihedral_coeff N args

• N = dihedral type (see asterisk form below)

• args = coefficients for one or more dihedral types

676 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.23.2 Examples

dihedral_coeff 1 80.0 1 3
dihedral_coeff * 80.0 1 3 0.5
dihedral_coeff 2* 80.0 1 3 0.5

16.23.3 Description

Specify the dihedral force field coefficients for one or more dihedral types. The number and meaning of the coefficients
depends on the dihedral style. Dihedral coefficients can also be set in the data file read by the read_data command or
in a restart file.
N can be specified in one of two ways. An explicit numeric value can be used, as in the first example above. Or a
wild-card asterisk can be used to set the coefficients for multiple dihedral types. This takes the form “*” or “*n” or
“n*” or “m*n”. If N = the number of dihedral types, then an asterisk with no numeric values means all types from 1 to
N. A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive).
A middle asterisk means all types from m to n (inclusive).
Note that using a dihedral_coeff command can override a previous setting for the same dihedral type. For example,
these commands set the coeffs for all dihedral types, then overwrite the coeffs for just dihedral type 2:

dihedral_coeff * 80.0 1 3
dihedral_coeff 2 200.0 1 3

A line in a data file that specifies dihedral coefficients uses the exact same format as the arguments of the dihedral_coeff
command in an input script, except that wild-card asterisks should not be used since coefficients for all N types must
be listed in the file. For example, under the “Dihedral Coeffs” section of a data file, the line that corresponds to the first
example above would be listed as

1 80.0 1 3

The dihedral_style class2 is an exception to this rule, in that an additional argument is used in the input script to allow
specification of the cross-term coefficients. See its doc page for details.

Note: When comparing the formulas and coefficients for various LAMMPS dihedral styles with dihedral equations
defined by other force fields, note that some force field implementations divide/multiply the energy prefactor K by
the multiple number of torsions that contain the J-K bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the
listed dihedral equation applies to each individual dihedral. Thus you need to define K appropriately to account for this
difference if necessary.

The list of all dihedral styles defined in LAMMPS is given on the dihedral_style doc page. They are also listed in more
compact form on the Commands dihedral doc page.
On either of those pages, click on the style to display the formula it computes and its coefficients as specified by the
associated dihedral_coeff command.

16.23. dihedral_coeff command 677

LAMMPS Documentation, Release stable 29Sep2021

16.23.4 Restrictions

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.
A dihedral style must be defined before any dihedral coefficients are set, either in the input script or in a data file.

16.23.5 Related commands

dihedral_style

16.23.6 Default

none

16.24 dihedral_style command

16.24.1 Syntax

dihedral_style style

• style = none or hybrid or charmm or class2 or harmonic or helix or multi/harmonic or opls

16.24.2 Examples

dihedral_style harmonic
dihedral_style multi/harmonic
dihedral_style hybrid harmonic charmm

16.24.3 Description

Set the formula(s) LAMMPS uses to compute dihedral interactions between quadruplets of atoms, which remain in
force for the duration of the simulation. The list of dihedral quadruplets is read in by a read_data or read_restart
command from a data or restart file.
Hybrid models where dihedrals are computed using different dihedral potentials can be setup using the hybrid dihedral
style.
The coefficients associated with a dihedral style can be specified in a data or restart file or via the dihedral_coeff
command.
All dihedral potentials store their coefficient data in binary restart files which means dihedral_style and dihedral_coeff
commands do not need to be re-specified in an input script that restarts a simulation. See the read_restart command
for details on how to do this. The one exception is that dihedral_style hybrid only stores the list of sub-styles in the
restart file; dihedral coefficients need to be re-specified.

Note: When both a dihedral and pair style is defined, the special_bonds command often needs to be used to turn off
(or weight) the pairwise interaction that would otherwise exist between 4 bonded atoms.

678 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

In the formulas listed for each dihedral style, phi is the torsional angle defined by the quadruplet of atoms. This angle
has a sign convention as shown in this diagram:

where the I,J,K,L ordering of the 4 atoms that define the dihedral is from left to right.
This sign convention effects several of the dihedral styles listed below (e.g. charmm, helix) in the sense that the energy
formula depends on the sign of phi, which may be reflected in the value of the coefficients you specify.

Note: When comparing the formulas and coefficients for various LAMMPS dihedral styles with dihedral equations
defined by other force fields, note that some force field implementations divide/multiply the energy prefactor K by the
multiple number of torsions that contain the J-K bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the listed
dihedral equation applies to each individual dihedral. Thus you need to define K appropriately via the dihedral_coeff
command to account for this difference if necessary.

Here is an alphabetic list of dihedral styles defined in LAMMPS. Click on the style to display the formula it computes
and coefficients specified by the associated dihedral_coeff command.
Click on the style to display the formula it computes, any additional arguments specified in the dihedral_style command,
and coefficients specified by the associated dihedral_coeff command.
There are also additional accelerated pair styles included in the LAMMPS distribution for faster performance on CPUs,
GPUs, and KNLs. The individual style names on the Commands dihedral page are followed by one or more of (g,i,k,o,t)
to indicate which accelerated styles exist.
• none - turn off dihedral interactions
• zero - topology but no interactions
• hybrid - define multiple styles of dihedral interactions
• charmm - CHARMM dihedral
• charmmfsw - CHARMM dihedral with force switching
• class2 - COMPASS (class 2) dihedral
• cosine/shift/exp - dihedral with exponential in spring constant
• fourier - dihedral with multiple cosine terms
• harmonic - harmonic dihedral
• helix - helix dihedral
• multi/harmonic - dihedral with 5 harmonic terms
• nharmonic - same as multi-harmonic with N terms
• opls - OPLS dihedral
• quadratic - dihedral with quadratic term in angle
• spherical - dihedral which includes angle terms to avoid singularities

16.24. dihedral_style command 679

LAMMPS Documentation, Release stable 29Sep2021

• table - tabulated dihedral

• table/cut - tabulated dihedral with analytic cutoff

16.24.4 Restrictions

Dihedral styles can only be set for atom styles that allow dihedrals to be defined.
Most dihedral styles are part of the MOLECULE package. They are only enabled if LAMMPS was built with that
package. See the Build package page for more info. The doc pages for individual dihedral potentials tell if it is part of
a package.

16.24.5 Related commands

dihedral_coeff

16.24.6 Default

dihedral_style none

16.25 dimension command

16.25.1 Syntax

dimension N

• N = 2 or 3

16.25.2 Examples

dimension 2

16.25.3 Description

Set the dimensionality of the simulation. By default LAMMPS runs 3d simulations. To run a 2d simulation, this
command should be used prior to setting up a simulation box via the create_box or read_data commands. Restart files
also store this setting.
See the discussion on the Howto 2d page for additional instructions on how to run 2d simulations.

Note: Some models in LAMMPS treat particles as finite-size spheres or ellipsoids, as opposed to point particles. In
2d, the particles will still be spheres or ellipsoids, not circular disks or ellipses, meaning their moment of inertia will
be the same as in 3d.

680 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.25.4 Restrictions

This command must be used before the simulation box is defined by a read_data or create_box command.

16.25.5 Related commands

fix enforce2d

16.25.6 Default

dimension 3

16.26 displace_atoms command

16.26.1 Syntax

displace_atoms group-ID style args keyword value ...

• group-ID = ID of group of atoms to displace

• style = move or ramp or random or rotate
move args = delx dely delz
delx,dely,delz = distance to displace in each dimension (distance units)
any of delx,dely,delz can be a variable (see below)
ramp args = ddim dlo dhi dim clo chi
ddim = x or y or z
dlo,dhi = displacement distance between dlo and dhi (distance units)
dim = x or y or z
clo,chi = lower and upper bound of domain to displace (distance units)
random args = dx dy dz seed
dx,dy,dz = random displacement magnitude in each dimension (distance units)
seed = random # seed (positive integer)
rotate args = Px Py Pz Rx Ry Rz theta
Px,Py,Pz = origin point of axis of rotation (distance units)
Rx,Ry,Rz = axis of rotation vector
theta = angle of rotation (degrees)
• zero or more keyword/value pairs may be appended
keyword = units
value = box or lattice

16.26. displace_atoms command 681

LAMMPS Documentation, Release stable 29Sep2021

16.26.2 Examples

displace_atoms top move 0 -5 0 units box

displace_atoms flow ramp x 0.0 5.0 y 2.0 20.5

16.26.3 Description

Displace a group of atoms. This can be used to move atoms a large distance before beginning a simulation or to
randomize atoms initially on a lattice. For example, in a shear simulation, an initial strain can be imposed on the
system. Or two groups of atoms can be brought into closer proximity.
The move style displaces the group of atoms by the specified 3d displacement vector. Any of the 3 quantities defining
the vector components can be specified as an equal-style or atom-style variable. If the value is a variable, it should be
specified as v_name, where name is the variable name. In this case, the variable will be evaluated, and its value(s) used
for the displacement(s). The scale factor implied by the units keyword will also be applied to the variable result.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Atom-style variables can specify the same
formulas as equal-style variables but can also include per-atom values, such as atom coordinates or per-atom values
read from a file. Note that if the variable references other compute or fix commands, those values must be up-to-date
for the current timestep. See the “Variable Accuracy” section of the variable doc page for more details.
The ramp style displaces atoms a variable amount in one dimension depending on the atom’s coordinate in a (possibly)
different dimension. For example, the second example command displaces atoms in the x-direction an amount between
0.0 and 5.0 distance units. Each atom’s displacement depends on the fractional distance its y coordinate is between 2.0
and 20.5. Atoms with y-coordinates outside those bounds will be moved the minimum (0.0) or maximum (5.0) amount.
The random style independently moves each atom in the group by a random displacement, uniformly sampled from a
value between -dx and +dx in the x dimension, and similarly for y and z. Random numbers are used in such a way that
the displacement of a particular atom is the same, regardless of how many processors are being used.
The rotate style rotates each atom in the group by the angle theta around a rotation axis R = (Rx,Ry,Rz) that goes
through a point P = (Px,Py,Pz). The direction of rotation for the atoms around the rotation axis is consistent with the
right-hand rule: if your right-hand thumb points along R, then your fingers wrap around the axis in the direction of
positive theta.
If the defined atom_style assigns an orientation to each atom (atom styles ellipsoid, line, tri, body), then that property
is also updated appropriately to correspond to the atom’s rotation.
Distance units for displacements and the origin point of the rotate style are determined by the setting of box or lattice
for the units keyword. Box means distance units as defined by the units command - e.g. Angstroms for real units.
Lattice means distance units are in lattice spacings. The lattice command must have been previously used to define the
lattice spacing.

Note: Care should be taken not to move atoms on top of other atoms. After the move, atoms are remapped into the
periodic simulation box if needed, and any shrink-wrap boundary conditions (see the boundary command) are enforced
which may change the box size. Other than this effect, this command does not change the size or shape of the simulation
box. See the change_box command if that effect is desired.

Note: Atoms can be moved arbitrarily long distances by this command. If the simulation box is non-periodic and
shrink-wrapped (see the boundary command), this can change its size or shape. This is not a problem, except that the
mapping of processors to the simulation box is not changed by this command from its initial 3d configuration; see the

682 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

processors command. Thus, if the box size/shape changes dramatically, the mapping of processors to the simulation
box may not end up as optimal as the initial mapping attempted to be.

16.26.4 Restrictions

For a 2d simulation, only rotations around the a vector parallel to the z-axis are allowed.

16.26.5 Related commands

lattice, change_box, fix move

16.26.6 Default

The option defaults are units = lattice.

16.27 dump command

16.28 dump vtk command

16.29 dump h5md command

16.30 dump molfile command

16.31 dump netcdf command

16.32 dump image command

16.33 dump movie command

16.34 dump atom/adios command

16.35 dump custom/adios command

16.35.1 Syntax

dump ID group-ID style N file args

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be dumped

16.27. dump command 683

LAMMPS Documentation, Release stable 29Sep2021

• style = atom or atom/gz or atom/zstd or *atom/mpiio or cfg or cfg/gz or cfg/zstd or cfg/mpiio or custom or cus-
tom/gz or custom/zstd or custom/mpiio or dcd or h5md or image or local or local/gz or local/zstd or molfile or
movie or netcdf or netcdf/mpiio or vtk or xtc or xyz or xyz/gz or xyz/zstd or xyz/mpiio
• N = dump every this many timesteps
• file = name of file to write dump info to
• args = list of arguments for a particular style
atom args = none
atom/gz args = none
atom/zstd args = none
atom/mpiio args = none
atom/adios args = none, discussed on dump atom/adios doc page
cfg args = same as custom args, see below
cfg/gz args = same as custom args, see below
cfg/zstd args = same as custom args, see below
cfg/mpiio args = same as custom args, see below
custom, custom/gz, custom/zstd, custom/mpiio args = see below
custom/adios args = same as custom args, discussed on dump custom/adios doc page
dcd args = none
h5md args = discussed on dump h5md doc page
image args = discussed on dump image doc page
local, local/gz, local/zstd args = see below
molfile args = discussed on dump molfile doc page
movie args = discussed on dump image doc page
netcdf args = discussed on dump netcdf doc page
netcdf/mpiio args = discussed on dump netcdf doc page
vtk args = same as custom args, see below, also dump vtk doc page
xtc args = none
xyz args = none
xyz/gz args = none
xyz/zstd args = none
xyz/mpiio args = none
• custom or custom/gz or custom/zstd or custom/mpiio or netcdf or netcdf/mpiio args = list of atom attributes

possible attributes = id, mol, proc, procp1, type, element, mass,

x, y, z, xs, ys, zs, xu, yu, zu,
xsu, ysu, zsu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz, mu,
radius, diameter, omegax, omegay, omegaz,
angmomx, angmomy, angmomz, tqx, tqy, tqz,
c_ID, c_ID[I], f_ID, f_ID[I], v_name,
i_name, d_name, i2_name[I], d2_name[I]

id = atom ID
mol = molecule ID
proc = ID of processor that owns atom
procp1 = ID+1 of processor that owns atom
type = atom type
element = name of atom element, as defined by dump_modify command
mass = atom mass
x,y,z = unscaled atom coordinates
xs,ys,zs = scaled atom coordinates

684 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

xu,yu,zu = unwrapped atom coordinates

xsu,ysu,zsu = scaled unwrapped atom coordinates
ix,iy,iz = box image that the atom is in
vx,vy,vz = atom velocities
fx,fy,fz = forces on atoms
q = atom charge
mux,muy,muz = orientation of dipole moment of atom
mu = magnitude of dipole moment of atom
radius,diameter = radius,diameter of spherical particle
omegax,omegay,omegaz = angular velocity of spherical particle
angmomx,angmomy,angmomz = angular momentum of aspherical particle
tqx,tqy,tqz = torque on finite-size particles
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can␣
,→include wildcard (see below)

f_ID = per-atom vector calculated by a fix with ID

f_ID[I] = Ith column of per-atom array calculated by a fix with ID, I can include␣
,→wildcard (see below)

v_name = per-atom vector calculated by an atom-style variable with name

i_name = custom integer vector with name
d_name = custom floating point vector with name
i2_name[I] = Ith column of custom integer array with name, I can include wildcard␣
,→(see below)

d2_name[I] = Ith column of custom floating point vector with name, I can include␣
,→wildcard (see below)

• local or local/gz or local/zstd args = list of local attributes

possible attributes = index, c_ID, c_ID[I], f_ID, f_ID[I]

index = enumeration of local values
c_ID = local vector calculated by a compute with ID
c_ID[I] = Ith column of local array calculated by a compute with ID, I can␣
,→include wildcard (see below)

f_ID = local vector calculated by a fix with ID

f_ID[I] = Ith column of local array calculated by a fix with ID, I can include␣
,→wildcard (see below)

16.35.2 Examples

dump myDump all atom 100 dump.atom

dump myDump all atom/mpiio 100 dump.atom.mpiio
dump myDump all atom/gz 100 dump.atom.gz
dump myDump all atom/zstd 100 dump.atom.zst
dump 2 subgroup atom 50 dump.run.bin
dump 2 subgroup atom 50 dump.run.mpiio.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
dump 4b flow custom 100 dump.%.myforce id type c_myF[*] v_ke
dump 2 inner cfg 10 dump.snap.*.cfg mass type xs ys zs vx vy vz
dump snap all cfg 100 dump.config.*.cfg mass type xs ys zs id type c_Stress[2]
dump 1 all xtc 1000 file.xtc

16.35. dump custom/adios command 685

LAMMPS Documentation, Release stable 29Sep2021

16.35.3 Description

Dump a snapshot of atom quantities to one or more files every N timesteps in one of several styles. The image and
movie styles are the exception: the image style renders a JPG, PNG, or PPM image file of the atom configuration every
N timesteps while the movie style combines and compresses them into a movie file; both are discussed in detail on the
dump image doc page. The timesteps on which dump output is written can also be controlled by a variable. See the
dump_modify every command.
Only information for atoms in the specified group is dumped. The dump_modify thresh and region and refresh com-
mands can also alter what atoms are included. Not all styles support these options; see details on the dump_modify doc
page.
As described below, the filename determines the kind of output (text or binary or gzipped, one big file or one per
timestep, one big file or multiple smaller files).

Note: Because periodic boundary conditions are enforced only on timesteps when neighbor lists are rebuilt, the
coordinates of an atom written to a dump file may be slightly outside the simulation box. Re-neighbor timesteps will
not typically coincide with the timesteps dump snapshots are written. See the dump_modify pbc command if you with
to force coordinates to be strictly inside the simulation box.

Note: Unless the dump_modify sort option is invoked, the lines of atom information written to dump files (typically
one line per atom) will be in an indeterminate order for each snapshot. This is even true when running on a single
processor, if the atom_modify sort option is on, which it is by default. In this case atoms are re-ordered periodically
during a simulation, due to spatial sorting. It is also true when running in parallel, because data for a single snapshot
is collected from multiple processors, each of which owns a subset of the atoms.

For the atom, custom, cfg, and local styles, sorting is off by default. For the dcd, xtc, xyz, and molfile styles, sorting by
atom ID is on by default. See the dump_modify doc page for details.
The atom/gz, cfg/gz, custom/gz, local/gz, and xyz/gz styles are identical in command syntax to the corresponding styles
without “gz”, however, they generate compressed files using the zlib library. Thus the filename suffix “.gz” is mandatory.
This is an alternative approach to writing compressed files via a pipe, as done by the regular dump styles, which may
be required on clusters where the interface to the high-speed network disallows using the fork() library call (which is
needed for a pipe). For the remainder of this doc page, you should thus consider the atom and atom/gz styles (etc) to
be inter-changeable, with the exception of the required filename suffix.
Similarly, the atom/zstd, cfg/zstd, custom/zstd, local/zstd, and xyz/zstd styles are identical to the gz styles, but use the
Zstd compression library instead and require the “.zst” suffix. See the dump_modify page for details on how to control
the compression level in both variants.
As explained below, the atom/mpiio, cfg/mpiio, custom/mpiio, and xyz/mpiio styles are identical in command syntax
and in the format of the dump files they create, to the corresponding styles without “mpiio”, except the single dump file
they produce is written in parallel via the MPI-IO library. For the remainder of this doc page, you should thus consider
the atom and atom/mpiio styles (etc) to be inter-changeable. The one exception is how the filename is specified for the
MPI-IO styles, as explained below.
The precision of values output to text-based dump files can be controlled by the dump_modify format command and
its options.

The style keyword determines what atom quantities are written to the file and in what format. Settings made via the
dump_modify command can also alter the format of individual values and the file itself.

686 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The atom, local, and custom styles create files in a simple text format that is self-explanatory when viewing a dump
file. Some of the LAMMPS post-processing tools described on the Tools doc page, including Pizza.py, work with this
format, as does the rerun command.
For post-processing purposes the atom, local, and custom text files are self-describing in the following sense.
The dimensions of the simulation box are included in each snapshot. For an orthogonal simulation box this information
is formatted as:

ITEM: BOX BOUNDS xx yy zz

xlo xhi
ylo yhi
zlo zhi

where xlo,xhi are the maximum extents of the simulation box in the x-dimension, and similarly for y and z. The “xx yy
zz” represent 6 characters that encode the style of boundary for each of the 6 simulation box boundaries (xlo,xhi and
ylo,yhi and zlo,zhi). Each of the 6 characters is either p = periodic, f = fixed, s = shrink wrap, or m = shrink wrapped
with a minimum value. See the boundary command for details.
For triclinic simulation boxes (non-orthogonal), an orthogonal bounding box which encloses the triclinic simulation
box is output, along with the 3 tilt factors (xy, xz, yz) of the triclinic box, formatted as follows:

ITEM: BOX BOUNDS xy xz yz xx yy zz

xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz

The presence of the text “xy xz yz” in the ITEM line indicates that the 3 tilt factors will be included on each of the
3 following lines. This bounding box is convenient for many visualization programs. The meaning of the 6 character
flags for “xx yy zz” is the same as above.
Note that the first two numbers on each line are now xlo_bound instead of xlo, etc, since they represent a bounding box.
See the Howto triclinic page for a geometric description of triclinic boxes, as defined by LAMMPS, simple formulas
for how the 6 bounding box extents (xlo_bound,xhi_bound,etc) are calculated from the triclinic parameters, and how
to transform those parameters to and from other commonly used triclinic representations.
The “ITEM: ATOMS” line in each snapshot lists column descriptors for the per-atom lines that follow. For example,
the descriptors would be “id type xs ys zs” for the default atom style, and would be the atom attributes you specify in
the dump command for the custom style.
For style atom, atom coordinates are written to the file, along with the atom ID and atom type. By default, atom coords
are written in a scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom is at a location 1/4 of the distance
from xlo to xhi of the box boundaries. The format can be changed to unscaled coords via the dump_modify settings.
Image flags can also be added for each atom via dump_modify.
Style custom allows you to specify a list of atom attributes to be written to the dump file for each atom. Possible
attributes are listed above and will appear in the order specified. You cannot specify a quantity that is not defined for
a particular simulation - such as q for atom style bond, since that atom style does not assign charges. Dumps occur at
the very end of a timestep, so atom attributes will include effects due to fixes that are applied during the timestep. An
explanation of the possible dump custom attributes is given below.
For style local, local output generated by computes and fixes is used to generate lines of output that is written to the
dump file. This local data is typically calculated by each processor based on the atoms it owns, but there may be zero
or more entities per atom, e.g. a list of bond distances. An explanation of the possible dump local attributes is given
below. Note that by using input from the compute property/local command with dump local, it is possible to generate
information on bonds, angles, etc that can be cut and pasted directly into a data file read by the read_data command.
Style cfg has the same command syntax as style custom and writes extended CFG format files, as used by the AtomEye
visualization package. Since the extended CFG format uses a single snapshot of the system per file, a wildcard “*” must

16.35. dump custom/adios command 687

LAMMPS Documentation, Release stable 29Sep2021

be included in the filename, as discussed below. The list of atom attributes for style cfg must begin with either “mass
type xs ys zs” or “mass type xsu ysu zsu” since these quantities are needed to write the CFG files in the appropriate
format (though the “mass” and “type” fields do not appear explicitly in the file). Any remaining attributes will be stored
as “auxiliary properties” in the CFG files. Note that you will typically want to use the dump_modify element command
with CFG-formatted files, to associate element names with atom types, so that AtomEye can render atoms appropriately.
When unwrapped coordinates xsu, ysu, and zsu are requested, the nominal AtomEye periodic cell dimensions are
expanded by a large factor UNWRAPEXPAND = 10.0, which ensures atoms that are displayed correctly for up to
UNWRAPEXPAND/2 periodic boundary crossings in any direction. Beyond this, AtomEye will rewrap the unwrapped
coordinates. The expansion causes the atoms to be drawn farther away from the viewer, but it is easy to zoom the atoms
closer, and the interatomic distances are unaffected.
The dcd style writes DCD files, a standard atomic trajectory format used by the CHARMM, NAMD, and XPlor molec-
ular dynamics packages. DCD files are binary and thus may not be portable to different machines. The number of
atoms per snapshot cannot change with the dcd style. The unwrap option of the dump_modify command allows DCD
coordinates to be written “unwrapped” by the image flags for each atom. Unwrapped means that if the atom has passed
through a periodic boundary one or more times, the value is printed for what the coordinate would be if it had not been
wrapped back into the periodic box. Note that these coordinates may thus be far outside the box size stored with the
snapshot.
The xtc style writes XTC files, a compressed trajectory format used by the GROMACS molecular dynamics package,
and described here. The precision used in XTC files can be adjusted via the dump_modify command. The default value
of 1000 means that coordinates are stored to 1/1000 nanometer accuracy. XTC files are portable binary files written
in the NFS XDR data format, so that any machine which supports XDR should be able to read them. The number of
atoms per snapshot cannot change with the xtc style. The unwrap option of the dump_modify command allows XTC
coordinates to be written “unwrapped” by the image flags for each atom. Unwrapped means that if the atom has passed
through a periodic boundary one or more times, the value is printed for what the coordinate would be if it had not been
wrapped back into the periodic box. Note that these coordinates may thus be far outside the box size stored with the
snapshot.
The xyz style writes XYZ files, which is a simple text-based coordinate format that many codes can read. Specifically
it has a line with the number of atoms, then a comment line that is usually ignored followed by one line per atom
with the atom type and the x-, y-, and z-coordinate of that atom. You can use the dump_modify element option to
change the output from using the (numerical) atom type to an element name (or some other label). This will help many
visualization programs to guess bonds and colors.
Note that atom, custom, dcd, xtc, and xyz style dump files can be read directly by VMD, a popular molecular viewing
program.

Dumps are performed on timesteps that are a multiple of N (including timestep 0) and on the last timestep of a min-
imization if the minimization converges. Note that this means a dump will not be performed on the initial timestep
after the dump command is invoked, if the current timestep is not a multiple of N. This behavior can be changed via
the dump_modify first command, which can also be useful if the dump command is invoked after a minimization ended
on an arbitrary timestep. N can be changed between runs by using the dump_modify every command (not allowed for
dcd style). The dump_modify every command also allows a variable to be used to determine the sequence of timesteps
on which dump files are written. In this mode a dump on the first timestep of a run will also not be written unless the
dump_modify first command is used.
The specified filename determines how the dump file(s) is written. The default is to write one large text file, which is
opened when the dump command is invoked and closed when an undump command is used or when LAMMPS exits.
For the dcd and xtc styles, this is a single large binary file.
Dump filenames can contain two wildcard characters. If a “*” character appears in the filename, then one file per
snapshot is written and the “*” character is replaced with the timestep value. For example, tmp.dump.* becomes
tmp.dump.0, tmp.dump.10000, tmp.dump.20000, etc. This option is not available for the dcd and xtc styles. Note that
the dump_modify pad command can be used to insure all timestep numbers are the same length (e.g. 00010), which
can make it easier to read a series of dump files in order with some post-processing tools.

688 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

If a “%” character appears in the filename, then each of P processors writes a portion of the dump file, and the “%” char-
acter is replaced with the processor ID from 0 to P-1. For example, tmp.dump.% becomes tmp.dump.0, tmp.dump.1,
. . . tmp.dump.P-1, etc. This creates smaller files and can be a fast mode of output on parallel machines that support
parallel I/O for output. This option is not available for the dcd, xtc, and xyz styles.
By default, P = the number of processors meaning one file per processor, but P can be set to a smaller value via the nfile
or fileper keywords of the dump_modify command. These options can be the most efficient way of writing out dump
files when running on large numbers of processors.
Note that using the “*” and “%” characters together can produce a large number of small dump files!
For the atom/mpiio, cfg/mpiio, custom/mpiio, and xyz/mpiio styles, a single dump file is written in parallel via the MPI-
IO library, which is part of the MPI standard for versions 2.0 and above. Using MPI-IO requires two steps. First, build
LAMMPS with its MPIIO package installed, e.g.

make yes-mpiio # installs the MPIIO package

make mpi # build LAMMPS for your platform

Second, use a dump filename which contains “.mpiio”. Note that it does not have to end in “.mpiio”, just contain those
characters. Unlike MPI-IO restart files, which must be both written and read using MPI-IO, the dump files produced by
these MPI-IO styles are identical in format to the files produced by their non-MPI-IO style counterparts. This means
you can write a dump file using MPI-IO and use the read_dump command or perform other post-processing, just as if
the dump file was not written using MPI-IO.
Note that MPI-IO dump files are one large file which all processors write to. You thus cannot use the “%” wildcard
character described above in the filename since that specifies generation of multiple files. You can use the “.bin” suffix
described below in an MPI-IO dump file; again this file will be written in parallel and have the same binary format as
if it were written without MPI-IO.
If the filename ends with “.bin”, the dump file (or files, if “*” or “%” is also used) is written in binary format. A
binary dump file will be about the same size as a text version, but will typically write out much faster. Of course, when
post-processing, you will need to convert it back to text format (see the binary2txt tool) or write your own code to read
the binary file. The format of the binary file can be understood by looking at the tools/binary2txt.cpp file. This option
is only available for the atom and custom styles.
If the filename ends with “.gz”, the dump file (or files, if “*” or “%” is also used) is written in gzipped format. A
gzipped dump file will be about 3x smaller than the text version, but will also take longer to write. This option is not
available for the dcd and xtc styles.

Note that in the discussion which follows, for styles which can reference values from a compute or fix or custom atom
property, like the custom, cfg, or local styles, the bracketed index I can be specified using a wildcard asterisk with the
index to effectively specify multiple values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of
columns in the array, then an asterisk with no numeric values means all column indices from 1 to N. A leading asterisk
means all indices from 1 to n (inclusive). A trailing asterisk means all indices from n to N (inclusive). A middle asterisk
means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual columns of the array had been listed one by one. E.g. these 2 dump
commands are equivalent, since the compute stress/atom command creates a per-atom array with 6 columns:

compute myPress all stress/atom NULL

dump 2 all custom 100 tmp.dump id myPress[*]
dump 2 all custom 100 tmp.dump id myPress[1] myPress[2] myPress[3] &
myPress[4] myPress[5] myPress[6]

This section explains the local attributes that can be specified as part of the local style.

16.35. dump custom/adios command 689

LAMMPS Documentation, Release stable 29Sep2021

The index attribute can be used to generate an index number from 1 to N for each line written into the dump file, where
N is the total number of local datums from all processors, or lines of output that will appear in the snapshot. Note
that because data from different processors depend on what atoms they currently own, and atoms migrate between
processor, there is no guarantee that the same index will be used for the same info (e.g. a particular bond) in successive
snapshots.
The c_ID and c_ID[I] attributes allow local vectors or arrays calculated by a compute to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has been defined previously in the input script. See
the compute command for details. There are computes for calculating local information such as indices, types, and
energies for bonds and angles.
Note that computes which calculate global or per-atom quantities, as opposed to local quantities, cannot be output in
a dump local command. Instead, global quantities can be output by the thermo_style custom command, and per-atom
quantities can be output by the dump custom command.
If c_ID is used as a attribute, then the local vector calculated by the compute is printed. If c_ID[I] is used, then I must
be in the range from 1-M, which will print the Ith column of the local array with M columns calculated by the compute.
See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values.
The f_ID and f_ID[I] attributes allow local vectors or arrays calculated by a fix to be output. The ID in the attribute
should be replaced by the actual ID of the fix that has been defined previously in the input script.
If f_ID is used as a attribute, then the local vector calculated by the fix is printed. If f_ID[I] is used, then I must be in the
range from 1-M, which will print the Ith column of the local with M columns calculated by the fix. See the discussion
above for how I can be specified with a wildcard asterisk to effectively specify multiple values.
Here is an example of how to dump bond info for a system, including the distance and energy of each bond:

compute 1 all property/local batom1 batom2 btype

compute 2 all bond/local dist eng
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]

This section explains the atom attributes that can be specified as part of the custom and cfg styles.
The id, mol, proc, procp1, type, element, mass, vx, vy, vz, fx, fy, fz, q attributes are self-explanatory.
Id is the atom ID. Mol is the molecule ID, included in the data file for molecular systems. Proc is the ID of the processor
(0 to Nprocs-1) that currently owns the atom. Procp1 is the proc ID+1, which can be convenient in place of a type
attribute (1 to Ntypes) for coloring atoms in a visualization program. Type is the atom type (1 to Ntypes). Element is
typically the chemical name of an element, which you must assign to each type via the dump_modify element command.
More generally, it can be any string you wish to associated with an atom type. Mass is the atom mass. Vx, vy, vz, fx,
fy, fz, and q are components of atom velocity and force and atomic charge.
There are several options for outputting atom coordinates. The x, y, z attributes write atom coordinates “unscaled”, in
the appropriate distance units (Angstroms, sigma, etc). Use xs, ys, zs if you want the coordinates “scaled” to the box
size, so that each value is 0.0 to 1.0. If the simulation box is triclinic (tilted), then all atom coords will still be between
0.0 and 1.0. I.e. actual unscaled (x,y,z) = xs*A + ys*B + zs*C, where (A,B,C) are the non-orthogonal vectors of the
simulation box edges, as discussed on the Howto triclinic doc page.
Use xu, yu, zu if you want the coordinates “unwrapped” by the image flags for each atom. Unwrapped means that if the
atom has passed through a periodic boundary one or more times, the value is printed for what the coordinate would be
if it had not been wrapped back into the periodic box. Note that using xu, yu, zu means that the coordinate values may
be far outside the box bounds printed with the snapshot. Using xsu, ysu, zsu is similar to using xu, yu, zu, except that
the unwrapped coordinates are scaled by the box size. Atoms that have passed through a periodic boundary will have
the corresponding coordinate increased or decreased by 1.0.
The image flags can be printed directly using the ix, iy, iz attributes. For periodic dimensions, they specify which image
of the simulation box the atom is considered to be in. An image of 0 means it is inside the box as defined. A value

690 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

of 2 means add 2 box lengths to get the true value. A value of -1 means subtract 1 box length to get the true value.
LAMMPS updates these flags as atoms cross periodic boundaries during the simulation.
The mux, muy, muz attributes are specific to dipolar systems defined with an atom style of dipole. They give the
orientation of the atom’s point dipole moment. The mu attribute gives the magnitude of the atom’s dipole moment.
The radius and diameter attributes are specific to spherical particles that have a finite size, such as those defined with
an atom style of sphere.
The omegax, omegay, and omegaz attributes are specific to finite-size spherical particles that have an angular velocity.
Only certain atom styles, such as sphere define this quantity.
The angmomx, angmomy, and angmomz attributes are specific to finite-size aspherical particles that have an angular
momentum. Only the ellipsoid atom style defines this quantity.
The tqx, tqy, tqz attributes are for finite-size particles that can sustain a rotational torque due to interactions with other
particles.
The c_ID and c_ID[I] attributes allow per-atom vectors or arrays calculated by a compute to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has been defined previously in the input script. See
the compute command for details. There are computes for calculating the per-atom energy, stress, centro-symmetry
parameter, and coordination number of individual atoms.
Note that computes which calculate global or local quantities, as opposed to per-atom quantities, cannot be output in
a dump custom command. Instead, global quantities can be output by the thermo_style custom command, and local
quantities can be output by the dump local command.
If c_ID is used as a attribute, then the per-atom vector calculated by the compute is printed. If c_ID[I] is used, then I
must be in the range from 1-M, which will print the Ith column of the per-atom array with M columns calculated by the
compute. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple
values.
The f_ID and f_ID[I] attributes allow vector or array per-atom quantities calculated by a fix to be output. The ID in
the attribute should be replaced by the actual ID of the fix that has been defined previously in the input script. The fix
ave/atom command is one that calculates per-atom quantities. Since it can time-average per-atom quantities produced
by any compute, fix, or atom-style variable, this allows those time-averaged results to be written to a dump file.
If f_ID is used as a attribute, then the per-atom vector calculated by the fix is printed. If f_ID[I] is used, then I must
be in the range from 1-M, which will print the Ith column of the per-atom array with M columns calculated by the fix.
See the discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values.
The v_name attribute allows per-atom vectors calculated by a variable to be output. The name in the attribute should
be replaced by the actual name of the variable that has been defined previously in the input script. Only an atom-style
variable can be referenced, since it is the only style that generates per-atom values. Variables of style atom can reference
individual atom attributes, per-atom attributes, thermodynamic keywords, or invoke other computes, fixes, or variables
when they are evaluated, so this is a very general means of creating quantities to output to a dump file.
The i_name, d_name, i2_name, d2_name attributes refer to per-atom integer and floating-point vectors or arrays that
have been added via the fix property/atom command. When that command is used specific names are given to each
attribute which are the “name” portion of these keywords. For arrays i2_name and d2_name, the column of the array
must also be included following the name in brackets: e.g. d2_xyz[I], i2_mySpin[I], where I is in the range from 1-M,
where M is the number of columns in the custom array. See the discussion above for how I can be specified with a
wildcard asterisk to effectively specify multiple values.
See the Modify page for information on how to add new compute and fix styles to LAMMPS to calculate per-atom
quantities which could then be output into dump files.

16.35. dump custom/adios command 691

LAMMPS Documentation, Release stable 29Sep2021

16.35.4 Restrictions

To write gzipped dump files, you must either compile LAMMPS with the -DLAMMPS_GZIP option or use the styles
from the COMPRESS package. See the Build settings page for details.
The atom/gz, cfg/gz, custom/gz, and xyz/gz styles are part of the COMPRESS package. They are only enabled if
LAMMPS was built with that package. See the Build package page for more info.
The atom/mpiio, cfg/mpiio, custom/mpiio, and xyz/mpiio styles are part of the MPIIO package. They are only enabled
if LAMMPS was built with that package. See the Build package doc page for more info.
The xtc style is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

16.35.5 Related commands

dump atom/adios, dump custom/adios, dump h5md, dump image, dump molfile, dump_modify, undump

16.35.6 Default

The defaults for the image and movie styles are listed on the dump image doc page.

16.36 dump atom/adios command

16.37 dump custom/adios command

16.37.1 Syntax

dump ID group-ID atom/adios N file.bp

dump ID group-ID custom/adios N file.bp args

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be imaged
• adios = style of dump command (other styles atom or cfg or dcd or xtc or xyz or local or custom are discussed
on the dump doc page)
• N = dump every this many timesteps
• file.bp = name of file/stream to write to
• args = same options as in *dump custom* command

692 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.37.2 Examples

dump adios1 all atom/adios 100 atoms.bp

dump 4a all custom/adios 100 dump_adios.bp id v_p x y z
dump 2 subgroup custom/adios 100 dump_adios.bp mass type xs ys zs vx vy vz

16.37.3 Description

Dump a snapshot of atom coordinates every N timesteps in the ADIOS based “BP” file format, or using different I/O
solutions in ADIOS, to a stream that can be read on-line by another program. ADIOS-BP files are binary, portable and
self-describing.
Use from write_dump:
It is possible to use these dump styles with the write_dump command. In this case, the sub-intervals must not be set at
all. The write_dump command can be used to create a new file at each individual dump.

dump 4 all atom/adios 100 dump.bp

write_dump all atom/adios singledump.bp

16.37.4 Restrictions

The number of atoms per snapshot CAN change with the adios style. When using the ADIOS tool ‘bpls’ to list the
content of a .bp file, bpls will print __ for the size of the output table indicating that its size is changing every step.
The atom/adios and custom/adios dump styles are part of the ADIOS package. They are only enabled if LAMMPS
was built with that package. See the Build package page for more info.

16.37.5 Related commands

dump, dump_modify, undump

16.38 dump cfg/uef command

16.38.1 Syntax

dump ID group-ID cfg/uef N file mass type xs ys zs args

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be dumped
• N = dump every this many timesteps
• file = name of file to write dump info to
args = same as args for dump custom

16.38. dump cfg/uef command 693

LAMMPS Documentation, Release stable 29Sep2021

16.38.2 Examples

dump 1 all cfg/uef 10 dump.*.cfg mass type xs ys zs

dump 2 all cfg/uef 100 dump.*.cfg mass type xs ys zs id c_stress

16.38.3 Description

This command is used to dump atomic coordinates in the reference frame of the applied flow field when fix nvt/uef or
fix npt/uef or is used. Only the atomic coordinates and frame-invariant scalar quantities will be in the flow frame. If
velocities are selected as output, for example, they will not be in the same reference frame as the atomic positions.

16.38.4 Restrictions

This fix is part of the UEF package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
This command can only be used when fix nvt/uef or fix npt/uef is active.

16.38.5 Related commands

dump, fix nvt/uef

16.38.6 Default

none

16.39 dump h5md command

16.39.1 Syntax

dump ID group-ID h5md N file.h5 args

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be imaged
• h5md = style of dump command (other styles atom or cfg or dcd or xtc or xyz or local or custom are discussed
on the dump doc page)
• N = dump every this many timesteps
• file.h5 = name of file to write to
args = list of data elements to dump, with their dump "sub-intervals"
position options
image
velocity options
force options
species options
file_from ID: do not open a new file, re-use the already opened file from dump ID

694 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

box value = yes or no

create_group value = yes or no
author value = quoted string
Note that at least one element must be specified and image may only be present if position is specified first.
For the elements position, velocity, force and species, a sub-interval may be specified to write the data only every
N_element iterations of the dump (i.e. every N*N_element time steps). This is specified by this option directly follow-
ing the element declaration:

every N_element

16.39.2 Examples

dump h5md1 all h5md 100 dump_h5md.h5 position image

dump h5md1 all h5md 100 dump_h5md.h5 position velocity every 10
dump h5md1 all h5md 100 dump_h5md.h5 velocity author "John Doe"

16.39.3 Description

Dump a snapshot of atom coordinates every N timesteps in the HDF5 based H5MD file format (de Buyl). HDF5 files
are binary, portable and self-describing. This dump style will write only one file, on the root node.
Several dumps may write to the same file, by using file_from and referring to a previously defined dump. Several
groups may also be stored within the same file by defining several dumps. A dump that refers (via file_from) to an
already open dump ID and that concerns another particle group must specify create_group yes.
Each data element is written every N*N_element steps. For image, no sub-interval is needed as it must be present
at the same interval as position. image must be given after position in any case. The box information (edges in each
dimension) is stored at the same interval than the position element, if present. Else it is stored every N steps.

Note: Because periodic boundary conditions are enforced only on timesteps when neighbor lists are rebuilt, the
coordinates of an atom written to a dump file may be slightly outside the simulation box.

Use from write_dump:

It is possible to use this dump style with the write_dump command. In this case, the sub-intervals must not be set at
all. The write_dump command can be used either to create a new file or to add current data to an existing dump file by
using the file_from keyword.
Typically, the species data is fixed. The following two commands store the position data every 100 timesteps, with the
image data, and store once the species data in the same file.

dump h5md1 all h5md 100 dump.h5 position image

write_dump all h5md dump.h5 file_from h5md1 species

16.39. dump h5md command 695

LAMMPS Documentation, Release stable 29Sep2021

16.39.4 Restrictions

The number of atoms per snapshot cannot change with the h5md style. The position data is stored wrapped (box
boundaries not enforced, see note above). Only orthogonal domains are currently supported. This is a limitation of the
present dump h5md command and not of H5MD itself.
The h5md dump style is part of the H5MD package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info. It also requires (i) building the ch5md library provided with LAMMPS (See
the Build package page for more info.) and (ii) having the HDF5 library installed (C bindings are sufficient) on your
system. The library ch5md is compiled with the h5cc wrapper provided by the HDF5 library.

16.39.5 Related commands

dump, dump_modify, undump

(de Buyl) de Buyl, Colberg and Hofling, H5MD: A structured, efficient, and portable file format for molecular data,
Comp. Phys. Comm. 185(6), 1546-1553 (2014) - [arXiv:1308.6382].

16.40 dump image command

16.41 dump movie command

16.41.1 Syntax

dump ID group-ID style N file color diameter keyword value ...

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be imaged
• style = image or movie = style of dump command (other styles atom or cfg or dcd or xtc or xyz or local or custom
are discussed on the dump doc page)
• N = dump every this many timesteps
• file = name of file to write image to
• color = atom attribute that determines color of each atom
• diameter = atom attribute that determines size of each atom
• zero or more keyword/value pairs may be appended
• keyword = atom or adiam or bond or line or tri or body or fix or size or view or center or up or zoom or box or
axes or subbox or shiny or ssao
atom = yes/no = do or do not draw atoms
adiam size = numeric value for atom diameter (distance units)
bond values = color width = color and width of bonds
color = atom or type or none
width = number or atom or type or none
number = numeric value for bond width (distance units)

696 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

line = color width

color = type
width = numeric value for line width (distance units)
tri = color tflag width
color = type
tflag = 1 for just triangle, 2 for just tri edges, 3 for both
width = numeric value for tringle edge width (distance units)
body = color bflag1 bflag2
color = type
bflag1,bflag2 = 2 numeric flags to affect how bodies are drawn
fix = fixID color fflag1 fflag2
fixID = ID of fix that generates objects to dray
color = type
fflag1,fflag2 = 2 numeric flags to affect how fix objects are drawn
size values = width height = size of images
width = width of image in # of pixels
height = height of image in # of pixels
view values = theta phi = view of simulation box
theta = view angle from +z axis (degrees)
phi = azimuthal view angle (degrees)
theta or phi can be a variable (see below)
center values = flag Cx Cy Cz = center point of image
flag = "s" for static, "d" for dynamic
Cx,Cy,Cz = center point of image as fraction of box dimension (0.5 = center of␣
,→box)

Cx,Cy,Cz can be variables (see below)

up values = Ux Uy Uz = direction that is "up" in image
Ux,Uy,Uz = components of up vector
Ux,Uy,Uz can be variables (see below)
zoom value = zfactor = size that simulation box appears in image
zfactor = scale image size by factor > 1 to enlarge, factor < 1 to shrink
zfactor can be a variable (see below)
box values = yes/no diam = draw outline of simulation box
yes/no = do or do not draw simulation box lines
diam = diameter of box lines as fraction of shortest box length
axes values = yes/no length diam = draw xyz axes
yes/no = do or do not draw xyz axes lines next to simulation box
length = length of axes lines as fraction of respective box lengths
diam = diameter of axes lines as fraction of shortest box length
subbox values = yes/no diam = draw outline of processor sub-domains
yes/no = do or do not draw sub-domain lines
diam = diameter of sub-domain lines as fraction of shortest box length
shiny value = sfactor = shinyness of spheres and cylinders
sfactor = shinyness of spheres and cylinders from 0.0 to 1.0
ssao value = yes/no seed dfactor = SSAO depth shading
yes/no = turn depth shading on/off
seed = random # seed (positive integer)
dfactor = strength of shading from 0.0 to 1.0

16.41. dump movie command 697

LAMMPS Documentation, Release stable 29Sep2021

16.41.2 Examples

dump d0 all image 100 dump.*.jpg type type

dump d1 mobile image 500 snap.*.png element element ssao yes 4539 0.6
dump d2 all image 200 img-*.ppm type type zoom 2.5 adiam 1.5 size 1280 720
dump m0 all movie 1000 movie.mpg type type size 640 480
dump m1 all movie 1000 movie.avi type type size 640 480
dump m2 all movie 100 movie.m4v type type zoom 1.8 adiam v_value size 1280 720

16.41.3 Description

Dump a high-quality rendered image of the atom configuration every N timesteps and save the images either as a
sequence of JPEG or PNG or PPM files, or as a single movie file. The options for this command as well as the
dump_modify command control what is included in the image or movie and how it appears. A series of such images
can easily be manually converted into an animated movie of your simulation or the process can be automated without
writing the intermediate files using the dump movie style; see further details below. Other dump styles store snapshots
of numerical data associated with atoms in various formats, as discussed on the dump doc page.
Note that a set of images or a movie can be made after a simulation has been run, using the rerun command to read
snapshots from an existing dump file, and using these dump commands in the rerun script to generate the images/movie.
Here are two sample images, rendered as 1024x1024 JPEG files.

Only atoms in the specified group are rendered in the image. The dump_modify region and thresh commands can also
alter what atoms are included in the image. The filename suffix determines whether a JPEG, PNG, or PPM file is
created with the image dump style. If the suffix is “.jpg” or “.jpeg”, then a JPEG format file is created, if the suffix is
“.png”, then a PNG format is created, else a PPM (aka NETPBM) format file is created. The JPEG and PNG files are
binary; PPM has a text mode header followed by binary data. JPEG images have lossy compression, PNG has lossless
compression, and PPM files are uncompressed but can be compressed with gzip, if LAMMPS has been compiled with
-DLAMMPS_GZIP and a “.gz” suffix is used.
Similarly, the format of the resulting movie is chosen with the movie dump style. This is handled by the underlying
FFmpeg converter and thus details have to be looked up in the FFmpeg documentation. Typical examples are: .avi,
.mpg, .m4v, .mp4, .mkv, .flv, .mov, .gif Additional settings of the movie compression like bitrate and framerate can be
set using the dump_modify command.

698 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

To write out JPEG and PNG format files, you must build LAMMPS with support for the corresponding JPEG or PNG
library. To convert images into movies, LAMMPS has to be compiled with the -DLAMMPS_FFMPEG flag. See the
Build settings page for details.

Note: Because periodic boundary conditions are enforced only on timesteps when neighbor lists are rebuilt, the
coordinates of an atom in the image may be slightly outside the simulation box.

Dumps are performed on timesteps that are a multiple of N (including timestep 0) and on the last timestep of a min-
imization if the minimization converges. Note that this means a dump will not be performed on the initial timestep
after the dump command is invoked, if the current timestep is not a multiple of N. This behavior can be changed via
the dump_modify first command, which can be useful if the dump command is invoked after a minimization ended on
an arbitrary timestep. N can be changed between runs by using the dump_modify every command.
Dump image filenames must contain a wildcard character “*”, so that one image file per snapshot is written.
The “*” character is replaced with the timestep value. For example, tmp.dump.*.jpg becomes tmp.dump.0.jpg,
tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc. Note that the dump_modify pad command can be used to insure all
timestep numbers are the same length (e.g. 00010), which can make it easier to convert a series of images into a movie
in the correct ordering.
Dump movie filenames on the other hand, must not have any wildcard character since only one file combining all images
into a single movie will be written by the movie encoder.

The color and diameter settings determine the color and size of atoms rendered in the image. They can be any atom
attribute defined for the dump custom command, including type and element. This includes per-atom quantities cal-
culated by a compute, fix, or variable, which are prefixed by “c_”, “f_”, or “v_” respectively. Note that the diameter
setting can be overridden with a numeric value applied to all atoms by the optional adiam keyword.
If type is specified for the color setting, then the color of each atom is determined by its atom type. By default the
mapping of types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. This mapping can be changed by the dump_modify acolor command.
If type is specified for the diameter setting then the diameter of each atom is determined by its atom type. By default
all types have diameter 1.0. This mapping can be changed by the dump_modify adiam command.
If element is specified for the color and/or diameter setting, then the color and/or diameter of each atom is determined
by which element it is, which in turn is specified by the element-to-type mapping specified by the “dump_modify
element” command. By default every atom type is C (carbon). Every element has a color and diameter associated with
it, which is the same as the colors and sizes used by the AtomEye visualization package.
If other atom attributes are used for the color or diameter settings, they are interpreted in the following way.
If “vx”, for example, is used as the color setting, then the color of the atom will depend on the x-component of its
velocity. The association of a per-atom value with a specific color is determined by a “color map”, which can be
specified via the dump_modify command. The basic idea is that the atom-attribute will be within a range of values, and

16.41. dump movie command 699

LAMMPS Documentation, Release stable 29Sep2021

every value within the range is mapped to a specific color. Depending on how the color map is defined, that mapping
can take place via interpolation so that a value of -3.2 is halfway between “red” and “blue”, or discretely so that the
value of -3.2 is “orange”.
If “vx”, for example, is used as the diameter setting, then the atom will be rendered using the x-component of its
velocity as the diameter. If the per-atom value <= 0.0, them the atom will not be drawn. Note that finite-size spherical
particles, as defined by atom_style sphere define a per-particle radius or diameter, which can be used as the diameter
setting.

The various keywords listed above control how the image is rendered. As listed below, all of the keywords have defaults,
most of which you will likely not need to change. The dump modify also has options specific to the dump image style,
particularly for assigning colors to atoms, bonds, and other image features.

The atom keyword allow you to turn off the drawing of all atoms, if the specified value is no. Note that this will not
turn off the drawing of particles that are represented as lines, triangles, or bodies, as discussed below. These particles
can be drawn separately if the line, tri, or body keywords are used.
The adiam keyword allows you to override the diameter setting to set a single numeric size. All atoms will be drawn
with that diameter, e.g. 1.5, which is in whatever distance units the input script defines, e.g. Angstroms.

The bond keyword allows to you to alter how bonds are drawn. A bond is only drawn if both atoms in the bond are
being drawn due to being in the specified group and due to other selection criteria (e.g. region, threshold settings of the
dump_modify command). By default, bonds are drawn if they are defined in the input data file as read by the read_data
command. Using none for both the bond color and width value will turn off the drawing of all bonds.
If atom is specified for the bond color value, then each bond is drawn in 2 halves, with the color of each half being the
color of the atom at that end of the bond.
If type is specified for the color value, then the color of each bond is determined by its bond type. By default the
mapping of bond types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for bond types > 6. This mapping can be changed by the dump_modify bcolor command.
The bond width value can be a numeric value or atom or type (or none as indicated above).
If a numeric value is specified, then all bonds will be drawn as cylinders with that diameter, e.g. 1.0, which is in
whatever distance units the input script defines, e.g. Angstroms.
If atom is specified for the width value, then each bond will be drawn with a width corresponding to the minimum
diameter of the 2 atoms in the bond.
If type is specified for the width value then the diameter of each bond is determined by its bond type. By default all
types have diameter 0.5. This mapping can be changed by the dump_modify bdiam command.

700 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The line keyword can be used when atom_style line is used to define particles as line segments, and will draw them as
lines. If this keyword is not used, such particles will be drawn as spheres, the same as if they were regular atoms. The
only setting currently allowed for the color value is type, which will color the lines according to the atom type of the
particle. By default the mapping of types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.
The line width can only be a numeric value, which specifies that all lines will be drawn as cylinders with that diameter,
e.g. 1.0, which is in whatever distance units the input script defines, e.g. Angstroms.

The tri keyword can be used when atom_style tri is used to define particles as triangles, and will draw them as triangles
or edges (3 lines) or both, depending on the setting for tflag. If edges are drawn, the width setting determines the
diameters of the line segments. If this keyword is not used, triangle particles will be drawn as spheres, the same as if
they were regular atoms. The only setting currently allowed for the color value is type, which will color the triangles
according to the atom type of the particle. By default the mapping of types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.

The body keyword can be used when atom_style body is used to define body particles with internal state (e.g. sub-
particles), and will drawn them in a manner specific to the body style. If this keyword is not used, such particles will
be drawn as spheres, the same as if they were regular atoms.
The Howto body page describes the body styles LAMMPS currently supports, and provides more details as to the
kind of body particles they represent and how they are drawn by this dump image command. For all the body styles,
individual atoms can be either a body particle or a usual point (non-body) particle. Non-body particles will be drawn
the same way they would be as a regular atom. The bflag1 and bflag2 settings are numerical values which are passed
to the body style to affect how the drawing of a body particle is done. See the Howto body page for a description of
what these parameters mean for each body style.
The only setting currently allowed for the color value is type, which will color the body particles according to the atom
type of the particle. By default the mapping of types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue

16.41. dump movie command 701

LAMMPS Documentation, Release stable 29Sep2021

• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.

The fix keyword can be used with a fix that produces objects to be drawn.
The fflag1 and fflag2 settings are numerical values which are passed to the fix to affect how the drawing of its objects
is done. See the individual fix page for a description of what these parameters mean for a particular fix.
The only setting currently allowed for the color value is type, which will color the fix objects according to their type.
By default the mapping of types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.

The size keyword sets the width and height of the created images, i.e. the number of pixels in each direction.

The view, center, up, and zoom values determine how 3d simulation space is mapped to the 2d plane of the image.
Basically they control how the simulation box appears in the image.
All of the view, center, up, and zoom values can be specified as numeric quantities, whose meaning is explained below.
Any of them can also be specified as an equal-style variable, by using v_name as the value, where “name” is the variable
name. In this case the variable will be evaluated on the timestep each image is created to create a new value. If the
equal-style variable is time-dependent, this is a means of changing the way the simulation box appears from image to
image, effectively doing a pan or fly-by view of your simulation.
The view keyword determines the viewpoint from which the simulation box is viewed, looking towards the center point.
The theta value is the vertical angle from the +z axis, and must be an angle from 0 to 180 degrees. The phi value is an
azimuthal angle around the z axis and can be positive or negative. A value of 0.0 is a view along the +x axis, towards
the center point. If theta or phi are specified via variables, then the variable values should be in degrees.
The center keyword determines the point in simulation space that will be at the center of the image. Cx, Cy, and Cz
are specified as fractions of the box dimensions, so that (0.5,0.5,0.5) is the center of the simulation box. These values
do not have to be between 0.0 and 1.0, if you want the simulation box to be offset from the center of the image. Note,
however, that if you choose strange values for Cx, Cy, or Cz you may get a blank image. Internally, Cx, Cy, and Cz are
converted into a point in simulation space. If flag is set to “s” for static, then this conversion is done once, at the time
the dump command is issued. If flag is set to “d” for dynamic then the conversion is performed every time a new image
is created. If the box size or shape is changing, this will adjust the center point in simulation space.
The up keyword determines what direction in simulation space will be “up” in the image. Internally it is stored as
a vector that is in the plane perpendicular to the view vector implied by the theta and pni values, and which is also
in the plane defined by the view vector and user-specified up vector. Thus this internal vector is computed from the
user-specified up vector as

702 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

up_internal = view cross (up cross view)

This means the only restriction on the specified up vector is that it cannot be parallel to the view vector, implied by the
theta and phi values.
The zoom keyword scales the size of the simulation box as it appears in the image. The default zfactor value of 1 should
display an image mostly filled by the atoms in the simulation box. A zfactor > 1 will make the simulation box larger; a
zfactor < 1 will make it smaller. Zfactor must be a value > 0.0.

The box keyword determines if and how the simulation box boundaries are rendered as thin cylinders in the image. If
no is set, then the box boundaries are not drawn and the diam setting is ignored. If yes is set, the 12 edges of the box
are drawn, with a diameter that is a fraction of the shortest box length in x,y,z (for 3d) or x,y (for 2d). The color of the
box boundaries can be set with the dump_modify boxcolor command.
The axes keyword determines if and how the coordinate axes are rendered as thin cylinders in the image. If no is set,
then the axes are not drawn and the length and diam settings are ignored. If yes is set, 3 thin cylinders are drawn to
represent the x,y,z axes in colors red,green,blue. The origin of these cylinders will be offset from the lower left corner
of the box by 10%. The length setting determines how long the cylinders will be as a fraction of the respective box
lengths. The diam setting determines their thickness as a fraction of the shortest box length in x,y,z (for 3d) or x,y (for
2d).
The subbox keyword determines if and how processor sub-domain boundaries are rendered as thin cylinders in the
image. If no is set (default), then the sub-domain boundaries are not drawn and the diam setting is ignored. If yes is
set, the 12 edges of each processor sub-domain are drawn, with a diameter that is a fraction of the shortest box length
in x,y,z (for 3d) or x,y (for 2d). The color of the sub-domain boundaries can be set with the dump_modify boxcolor
command.

The shiny keyword determines how shiny the objects rendered in the image will appear. The sfactor value must be a
value 0.0 <= sfactor <= 1.0, where sfactor = 1 is a highly reflective surface and sfactor = 0 is a rough non-shiny surface.
The ssao keyword turns on/off a screen space ambient occlusion (SSAO) model for depth shading. If yes is set, then
atoms further away from the viewer are darkened via a randomized process, which is perceived as depth. The calculation
of this effect can increase the cost of computing the image by roughly 2x. The strength of the effect can be scaled by
the dfactor parameter. If no is set, no depth shading is performed.

A series of JPEG, PNG, or PPM images can be converted into a movie file and then played as a movie using commonly
available tools. Using dump style movie automates this step and avoids the intermediate step of writing (many) image
snapshot file. But LAMMPS has to be compiled with -DLAMMPS_FFMPEG and an FFmpeg executable have to be
installed.
To manually convert JPEG, PNG or PPM files into an animated GIF or MPEG or other movie file you can use:
• a) Use the ImageMagick convert program.

% convert *.jpg foo.gif

% convert -loop 1 *.ppm foo.mpg

Animated GIF files from ImageMagick are not optimized. You can use a program like gifsicle to optimize and
thus massively shrink them. MPEG files created by ImageMagick are in MPEG-1 format with a rather inefficient
compression and low quality compared to more modern compression styles like MPEG-4, H.264, VP8, VP9,
H.265 and so on.

16.41. dump movie command 703

LAMMPS Documentation, Release stable 29Sep2021

• b) Use QuickTime.
Select “Open Image Sequence” under the File menu Load the images into QuickTime to animate them Select
“Export” under the File menu Save the movie as a QuickTime movie (*.mov) or in another format. QuickTime
can generate very high quality and efficiently compressed movie files. Some of the supported formats require to
buy a license and some are not readable on all platforms until specific runtime libraries are installed.
• c) Use FFmpeg
FFmpeg is a command line tool that is available on many platforms and allows extremely flexible encoding and
decoding of movies.

cat snap.*.jpg | ffmpeg -y -f image2pipe -c:v mjpeg -i - -b:v 2000k movie.m4v

cat snap.*.ppm | ffmpeg -y -f image2pipe -c:v ppm -i - -b:v 2400k movie.avi

Front ends for FFmpeg exist for multiple platforms. For more information see the FFmpeg homepage

Play the movie:

• a) Use your browser to view an animated GIF movie.
Select “Open File” under the File menu Load the animated GIF file
• b) Use the freely available mplayer or ffplay tool to view a movie. Both are available for multiple OSes and
support a large variety of file formats and decoders.

% mplayer foo.mpg
% ffplay bar.avi

• c) Use the Pizza.py animate tool, which works directly on a series of image files.

a = animate("foo*.jpg")

• d) QuickTime and other Windows- or MacOS-based media players can obviously play movie files directly. Sim-
ilarly for corresponding tools bundled with Linux desktop environments. However, due to licensing issues with
some file formats, the formats may require installing additional libraries, purchasing a license, or may not be
supported.

See the Modify page for information on how to add new compute and fix styles to LAMMPS to calculate per-atom
quantities which could then be output into dump files.

16.41.4 Restrictions

To write JPEG images, you must use the -DLAMMPS_JPEG switch when building LAMMPS and link with a JPEG
library. To write PNG images, you must use the -DLAMMPS_PNG switch when building LAMMPS and link with a
PNG library.
To write movie dumps, you must use the -DLAMMPS_FFMPEG switch when building LAMMPS and have the FFmpeg
executable available on the machine where LAMMPS is being run. Typically it’s name is lowercase, i.e. ffmpeg.
See the Build settings page for details.
Note that since FFmpeg is run as an external program via a pipe, LAMMPS has limited control over its execution and
no knowledge about errors and warnings printed by it. Those warnings and error messages will be printed to the screen
only. Due to the way image data is communicated to FFmpeg, it will often print the message

704 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

pipe:: Input/output error

which can be safely ignored. Other warnings and errors have to be addressed according to the FFmpeg documentation.
One known issue is that certain movie file formats (e.g. MPEG level 1 and 2 format streams) have video bandwidth
limits that can be crossed when rendering too large of image sizes. Typical warnings look like this:

[mpeg @ 0x98b5e0] packet too large, ignoring buffer limits to mux it

[mpeg @ 0x98b5e0] buffer underflow st=0 bufi=281407 size=285018
[mpeg @ 0x98b5e0] buffer underflow st=0 bufi=283448 size=285018

In this case it is recommended to either reduce the size of the image or encode in a different format that is also supported
by your copy of FFmpeg, and which does not have this limitation (e.g. .avi, .mkv, mp4).

16.41.5 Related commands

dump, dump_modify, undump

16.41.6 Default

The defaults for the keywords are as follows:

• adiam = not specified (use diameter setting)
• atom = yes
• bond = none none (if no bonds in system)
• bond = atom 0.5 (if bonds in system)
• size = 512 512
• view = 60 30 (for 3d)
• view = 0 0 (for 2d)
• center = s 0.5 0.5 0.5
• up = 0 0 1 (for 3d)
• up = 0 1 0 (for 2d)
• zoom = 1.0
• box = yes 0.02
• axes = no 0.0 0.0
• subbox no 0.0
• shiny = 1.0
• ssao = no

16.41. dump movie command 705

LAMMPS Documentation, Release stable 29Sep2021

16.42 dump_modify command

16.42.1 Syntax

dump_modify dump-ID keyword values ...

• dump-ID = ID of dump to modify

• one or more keyword/value pairs may be appended
• these keywords apply to various dump styles
• keyword = append or at or buffer or delay or element or every or fileper or first or flush or format or image or
label or maxfiles or nfile or pad or pbc or precision or region or refresh or scale or sfactor or sort or tfactor or
thermo or thresh or time or units or unwrap
append arg = yes or no
at arg = N
N = index of frame written upon first dump
buffer arg = yes or no
delay arg = Dstep
Dstep = delay output until this timestep
element args = E1 E2 ... EN, where N = # of atom types
E1,...,EN = element name, e.g. C or Fe or Ga
every arg = N
N = dump every this many timesteps
N can be a variable (see below)
fileper arg = Np
Np = write one file for every this many processors
first arg = yes or no
flush arg = yes or no
format args = line string, int string, float string, M string, or none
string = C-style format string
M = integer from 1 to N, where N = # of per-atom quantities being output
image arg = yes or no
label arg = string
string = character string (e.g. BONDS) to use in header of dump local file
maxfiles arg = Fmax
Fmax = keep only the most recent Fmax snapshots (one snapshot per file)
nfile arg = Nf
Nf = write this many files, one from each of Nf processors
pad arg = Nchar = # of characters to convert timestep to
pbc arg = yes or no = remap atoms via periodic boundary conditions
precision arg = power-of-10 value from 10 to 1000000
region arg = region-ID or "none"
refresh arg = c_ID = compute ID that supports a refresh operation
scale arg = yes or no
sfactor arg = coordinate scaling factor (> 0.0)
sort arg = off or id or N or -N
off = no sorting of per-atom lines within a snapshot
id = sort per-atom lines by atom ID
N = sort per-atom lines in ascending order by the Nth column
-N = sort per-atom lines in descending order by the Nth column
tfactor arg = time scaling factor (> 0.0)
thermo arg = yes or no

706 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

time arg = yes or no

thresh args = attribute operator value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "|^"
value = numeric value to compare to, or LAST
these 3 args can be replaced by the word "none" to turn off thresholding
units arg = yes or no
unwrap arg = yes or no
• these keywords apply only to the image and movie styles
• keyword = acolor or adiam or amap or backcolor or bcolor or bdiam or boxcolor or color or bitrate or framerate
or header
acolor args = type color
type = atom type or range of types (see below)
color = name of color or color1/color2/...
adiam args = type diam
type = atom type or range of types (see below)
diam = diameter of atoms of that type (distance units)
amap args = lo hi style delta N entry1 entry2 ... entryN
lo = number or min = lower bound of range of color map
hi = number or max = upper bound of range of color map
style = 2 letters = "c" or "d" or "s" plus "a" or "f"
"c" for continuous
"d" for discrete
"s" for sequential
"a" for absolute
"f" for fractional
delta = binsize (only used for style "s", otherwise ignored)
binsize = range is divided into bins of this width
N = # of subsequent entries
entry = value color (for continuous style)
value = number or min or max = single value within range
color = name of color used for that value
entry = lo hi color (for discrete style)
lo/hi = number or min or max = lower/upper bound of subset of range
color = name of color used for that subset of values
entry = color (for sequential style)
color = name of color used for a bin of values
backcolor arg = color
color = name of color for background
bcolor args = type color
type = bond type or range of types (see below)
color = name of color or color1/color2/...
bdiam args = type diam
type = bond type or range of types (see below)
diam = diameter of bonds of that type (distance units)
boxcolor arg = color
color = name of color for simulation box lines and processor sub-domain lines
color args = name R G B
name = name of color
R,G,B = red/green/blue numeric values from 0.0 to 1.0
bitrate arg = rate
rate = target bitrate for movie in kbps

16.42. dump_modify command 707

LAMMPS Documentation, Release stable 29Sep2021

framerate arg = fps

fps = frames per second for movie
header arg = yes or no
yes to write the header
no to not write the header
• these keywords apply only to the /gz and /zstd dump styles
• keyword = compression_level
compression_level args = level
level = integer specifying the compression level that should be used (see below␣
,→for supported levels)

• these keywords apply only to the /zstd dump styles

• keyword = compression_level
checksum args = yes or no (add checksum at end of zst file)

16.42.2 Examples

dump_modify 1 format line "%d %d %20.15g %g %g" scale yes

dump_modify 1 format float %20.15g scale yes
dump_modify myDump image yes scale no flush yes
dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2
dump_modify xtcdump precision 10000 sfactor 0.1
dump_modify 1 every 1000 nfile 20
dump_modify 1 every v_myVar
dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red

16.42.3 Description

Modify the parameters of a previously defined dump command. Not all parameters are relevant to all dump styles.
As explained on the dump doc page, the atom/mpiio, custom/mpiio, and xyz/mpiio dump styles are identical in command
syntax and in the format of the dump files they create, to the corresponding styles without “mpiio”, except the single
dump file they produce is written in parallel via the MPI-IO library. Thus if a dump_modify option below is valid for
the atom style, it is also valid for the atom/mpiio style, and similarly for the other styles which allow for use of MPI-IO.

These keywords apply to various dump styles, including the dump image and dump movie styles. The description gives
details.

The append keyword applies to all dump styles except cfg and xtc and dcd. It also applies only to text output files,
not to binary or gzipped or image/movie files. If specified as yes, then dump snapshots are appended to the end of an
existing dump file. If specified as no, then a new dump file will be created which will overwrite an existing file with
the same name.

The at keyword only applies to the netcdf dump style. It can only be used if the append yes keyword is also used. The
N argument is the index of which frame to append to. A negative value can be specified for N, which means a frame
counted from the end of the file. The at keyword can only be used if the dump_modify command is before the first

708 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

command that causes dump snapshots to be output, e.g. a run or minimize command. Once the dump file has been
opened, this keyword has no further effect.

The buffer keyword applies only to dump styles atom, cfg, custom, local, and xyz. It also applies only to text output
files, not to binary or gzipped files. If specified as yes, which is the default, then each processor writes its output into an
internal text buffer, which is then sent to the processor(s) which perform file writes, and written by those processors(s)
as one large chunk of text. If specified as no, each processor sends its per-atom data in binary format to the processor(s)
which perform file wirtes, and those processor(s) format and write it line by line into the output file.
The buffering mode is typically faster since each processor does the relatively expensive task of formatting the output
for its own atoms. However it requires about twice the memory (per processor) for the extra buffering.

The delay keyword applies to all dump styles. No snapshots will be output until the specified Dstep timestep or later.
Specifying Dstep < 0 is the same as turning off the delay setting. This is a way to turn off unwanted output early in a
simulation, for example, during an equilibration phase.

The element keyword applies only to the dump cfg, xyz, and image styles. It associates element names (e.g. H, C, Fe)
with LAMMPS atom types. See the list of element names at the bottom of this page.
In the case of dump cfg, this allows the AtomEye visualization package to read the dump file and render atoms with
the appropriate size and color.
In the case of dump image, the output images will follow the same AtomEye convention. An element name is specified
for each atom type (1 to Ntype) in the simulation. The same element name can be given to multiple atom types.
In the case of xyz format dumps, there are no restrictions to what label can be used as an element name. Any white-space
separated text will be accepted.

The every keyword changes the dump frequency originally specified by the dump command to a new value. The every
keyword can be specified in one of two ways. It can be a numeric value in which case it must be > 0. Or it can be an
equal-style variable, which should be specified as v_name, where name is the variable name.
In this case, the variable is evaluated at the beginning of a run to determine the next timestep at which a dump snapshot
will be written out. On that timestep the variable will be evaluated again to determine the next timestep, etc. Thus
the variable should return timestep values. See the stagger() and logfreq() and stride() math functions for equal-style
variables, as examples of useful functions to use in this context. Other similar math functions could easily be added
as options for equal-style variables. Also see the next() function, which allows use of a file-style variable which reads
successive values from a file, each time the variable is evaluated. Used with the every keyword, if the file contains a
list of ascending timesteps, you can output snapshots whenever you wish.
Note that when using the variable option with the every keyword, you need to use the first option if you want an initial
snapshot written to the dump file. The every keyword cannot be used with the dump dcd style.
For example, the following commands will write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:

variable s equal logfreq(10,3,10)

dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s first yes

The following commands would write snapshots at the timesteps listed in file tmp.times:

16.42. dump_modify command 709

LAMMPS Documentation, Release stable 29Sep2021

variable f file tmp.times

variable s equal next(f)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s

Note: When using a file-style variable with the every keyword, the file of timesteps must list a first timestep that is
beyond the current timestep (e.g. it cannot be 0). And it must list one or more timesteps beyond the length of the run
you perform. This is because the dump command will generate an error if the next timestep it reads from the file is not
a value greater than the current timestep. Thus if you wanted output on steps 0,15,100 of a 100-timestep run, the file
should contain the values 15,100,101 and you should also use the dump_modify first command. Any final value > 100
could be used in place of 101.

The first keyword determines whether a dump snapshot is written on the very first timestep after the dump command is
invoked. This will always occur if the current timestep is a multiple of N, the frequency specified in the dump command,
including timestep 0. But if this is not the case, a dump snapshot will only be written if the setting of this keyword is
yes. If it is no, which is the default, then it will not be written.

The flush keyword determines whether a flush operation is invoked after a dump snapshot is written to the dump file.
A flush insures the output in that file is current (no buffering by the OS), even if LAMMPS halts before the simulation
completes. Flushes cannot be performed with dump style xtc.

The format keyword can be used to change the default numeric format output by the text-based dump styles: atom,
local, custom, cfg, and xyz styles, and their MPIIO variants. Only the line or none options can be used with the atom
and xyz styles.
All the specified format strings are C-style formats, e.g. as used by the C/C++ printf() command. The line keyword
takes a single argument which is the format string for an entire line of output for each atom (do not include a trailing
“n”), with N fields, which you must enclose in quotes if it is more than one field. The int and float keywords take a
single format argument and are applied to all integer or floating-point quantities output. The setting for M string also
takes a single format argument which is used for the Mth value output in each line, e.g. the fifth column is output in
high precision for “format 5 %20.15g”.

Note: When using the line keyword for the cfg style, the first two fields (atom ID and type) are not actually written
into the CFG file, however you must include formats for them in the format string.

The format keyword can be used multiple times. The precedence is that for each value in a line of output, the M format
(if specified) is used, else the int or float setting (if specified) is used, else the line setting (if specified) for that value is
used, else the default setting is used. A setting of none clears all previous settings, reverting all values to their default
format.

Note: Atom and molecule IDs are stored internally as 4-byte or 8-byte signed integers, depending on how LAMMPS
was compiled. When specifying the format int option you can use a “%d”-style format identifier in the format string
and LAMMPS will convert this to the corresponding 8-byte form if it is needed when outputting those values. However,
when specifying the line option or format M string option for those values, you should specify a format string appro-
priate for an 8-byte signed integer, e.g. one with “%ld”, if LAMMPS was compiled with the -DLAMMPS_BIGBIG
option for 8-byte IDs.

710 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Note: Any value written to a text-based dump file that is a per-atom quantity calculated by a compute or fix is stored
internally as a floating-point value. If the value is actually an integer and you wish it to appear in the text dump file as
a (large) integer, then you need to use an appropriate format. For example, these commands:

compute 1 all property/local batom1 batom2

dump 1 all local 100 tmp.bonds index c_1[1] c_1[2]
dump_modify 1 format line "%d %0.0f %0.0f"

will output the two atom IDs for atoms in each bond as integers. If the dump_modify command were omitted, they
would appear as floating-point values, assuming they were large integers (more than 6 digits). The “index” keyword
should use the “%d” format since it is not generated by a compute or fix, and is stored internally as an integer.

The fileper keyword is documented below with the nfile keyword.

The image keyword applies only to the dump atom style. If the image value is yes, 3 flags are appended to each atom’s
coords which are the absolute box image of the atom in each dimension. For example, an x image flag of -2 with a
normalized coord of 0.5 means the atom is in the center of the box, but has passed through the box boundary 2 times
and is really 2 box lengths to the left of its current coordinate. Note that for dump style custom these various values
can be printed in the dump file by using the appropriate atom attributes in the dump command itself.

The label keyword applies only to the dump local style. When it writes local information, such as bond or angle
topology to a dump file, it will use the specified label to format the header. By default this includes 2 lines:

ITEM: NUMBER OF ENTRIES

ITEM: ENTRIES ...

The word “ENTRIES” will be replaced with the string specified, e.g. BONDS or ANGLES.

The maxfiles keyword can only be used when a ‘*’ wildcard is included in the dump file name, i.e. when writing a new
file(s) for each snapshot. The specified Fmax is how many snapshots will be kept. Once this number is reached, the
file(s) containing the oldest snapshot is deleted before a new dump file is written. If the specified Fmax <= 0, then all
files are retained.
This can be useful for debugging, especially if you don’t know on what timestep something bad will happen, e.g. when
LAMMPS will exit with an error. You can dump every timestep, and limit the number of dump files produced, even if
you run for 1000s of steps.

The nfile or fileper keywords can be used in conjunction with the “%” wildcard character in the specified dump file
name, for all dump styles except the dcd, image, movie, xtc, and xyz styles (for which “%” is not allowed). As explained
on the dump command doc page, the “%” character causes the dump file to be written in pieces, one piece for each of
P processors. By default P = the number of processors the simulation is running on. The nfile or fileper keyword can
be used to set P to a smaller value, which can be more efficient when running on a large number of processors.
The nfile keyword sets P to the specified Nf value. For example, if Nf = 4, and the simulation is running on 100
processors, 4 files will be written, by processors 0,25,50,75. Each will collect information from itself and the next 24
processors and write it to a dump file.

16.42. dump_modify command 711

LAMMPS Documentation, Release stable 29Sep2021

For the fileper keyword, the specified value of Np means write one file for every Np processors. For example, if Np =
4, every fourth processor (0,4,8,12,etc) will collect information from itself and the next 3 processors and write it to a
dump file.

The pad keyword only applies when the dump filename is specified with a wildcard “*” character which becomes the
timestep. If pad is 0, which is the default, the timestep is converted into a string of unpadded length, e.g. 100 or
12000 or 2000000. When pad is specified with Nchar > 0, the string is padded with leading zeroes so they are all
the same length = Nchar. For example, pad 7 would yield 0000100, 0012000, 2000000. This can be useful so that
post-processing programs can easily read the files in ascending timestep order.

The pbc keyword applies to all the dump styles. As explained on the dump doc page, atom coordinates in a dump file
may be slightly outside the simulation box. This is because periodic boundary conditions are enforced only on timesteps
when neighbor lists are rebuilt, which will not typically coincide with the timesteps dump snapshots are written. If the
setting of this keyword is set to yes, then all atoms will be remapped to the periodic box before the snapshot is written,
then restored to their original position. If it is set to no they will not be. The no setting is the default because it requires
no extra computation.

The precision keyword only applies to the dump xtc style. A specified value of N means that coordinates are stored to
1/N nanometer accuracy, e.g. for N = 1000, the coordinates are written to 1/1000 nanometer accuracy.

The refresh keyword only applies to the dump custom, cfg, image, and movie styles. It allows an “incremental” dump
file to be written, by refreshing a compute that is used as a threshold for determining which atoms are included in a
dump snapshot. The specified c_ID gives the ID of the compute. It is prefixed by “c_” to indicate a compute, which is
the only current option. At some point, other options may be added, e.g. fixes or variables.

Note: This keyword can only be specified once for a dump. Refreshes of multiple computes cannot yet be performed.

The definition and motivation of an incremental dump file is as follows. Instead of outputting all atoms at each snapshot
(with some associated values), you may only wish to output the subset of atoms with a value that has changed in some
way compared to the value the last time that atom was output. In some scenarios this can result in a dramatically
smaller dump file. If desired, by post-processing the sequence of snapshots, the values for all atoms at all timesteps
can be inferred.
A concrete example is a simulation of atom diffusion in a solid, represented as atoms on a lattice. Diffusive hops are
rare. Imagine that when a hop occurs an atom moves more than a distance Dhop. For any snapshot we only want
to output atoms that have hopped since the last snapshot. This can be accomplished with something the following
commands:

variable Dhop equal 0.6

variable check atom "c_dsp[4] > v_Dhop"
compute dsp all displace/atom refresh check
dump 1 all custom 20 tmp.dump id type x y z
dump_modify 1 append yes thresh c_dsp[4] > ${Dhop} refresh c_dsp

The compute displace/atom command calculates the displacement of each atom from its reference position. The “4”
index is the scalar displacement; 1,2,3 are the xyz components of the displacement. The dump_modify thresh command
will cause only atoms that have displaced more than 0.6 Angstroms to be output on a given snapshot (assuming metal
units). However, note that when an atom is output, we also need to update the reference position for that atom to its
new coordinates. So that it will not be output in every snapshot thereafter. That reference position is stored by compute

712 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

displace/atom. So the dump_modify refresh option triggers a call to compute displace/atom at the end of every dump
to perform that update. The refresh check option shown as part of the compute displace/atom command enables the
compute to respond to the call from the dump command, and update the appropriate reference positions. This is done
be defining an atom-style variable, check in this example, which calculates a Boolean value (0 or 1) for each atom,
based on the same criterion used by dump_modify thresh.
See the compute displace/atom command for more details, including an example of how to produce output that includes
an initial snapshot with the reference position of all atoms.
Note that only computes with a refresh option will work with dump_modify refresh. See individual compute doc pages
for details. Currently, only compute displace/atom supports this option. Others may be added at some point. If you use
a compute that does not support refresh operations, LAMMPS will not complain; dump_modify refresh will simply do
nothing.

The region keyword only applies to the dump custom, cfg, image, and movie styles. If specified, only atoms in the
region will be written to the dump file or included in the image/movie. Only one region can be applied as a filter (the
last one specified). See the region command for more details. Note that a region can be defined as the “inside” or
“outside” of a geometric shape, and it can be the “union” or “intersection” of a series of simpler regions.

The scale keyword applies only to the dump atom style. A scale value of yes means atom coords are written in normal-
ized units from 0.0 to 1.0 in each box dimension. If the simulation box is triclinic (tilted), then all atom coords will still
be between 0.0 and 1.0. A value of no means they are written in absolute distance units (e.g. Angstroms or sigma).

The sfactor and tfactor keywords only apply to the dump xtc style. They allow customization of the unit conversion
factors used when writing to XTC files. By default they are initialized for whatever units style is being used, to write
out coordinates in nanometers and time in picoseconds. I.e. for real units, LAMMPS defines sfactor = 0.1 and tfactor
= 0.001, since the Angstroms and fs used by real units are 0.1 nm and 0.001 ps respectively. If you are using a units
system with distance and time units far from nm and ps, you may wish to write XTC files with different units, since
the compression algorithm used in XTC files is most effective when the typical magnitude of position data is between
10.0 and 0.1.

The sort keyword determines whether lines of per-atom output in a snapshot are sorted or not. A sort value of off
means they will typically be written in indeterminate order, either in serial or parallel. This is the case even in serial
if the atom_modify sort option is turned on, which it is by default, to improve performance. A sort value of id means
sort the output by atom ID. A sort value of N or -N means sort the output by the value in the Nth column of per-atom
info in either ascending or descending order.
The dump local style cannot be sorted by atom ID, since there are typically multiple lines of output per atom. Some
dump styles, such as dcd and xtc, require sorting by atom ID to format the output file correctly. If multiple processors
are writing the dump file, via the “%” wildcard in the dump filename, then sorting cannot be performed.

Note: Unless it is required by the dump style, sorting dump file output requires extra overhead in terms of CPU and
communication cost, as well as memory, versus unsorted output.

The thermo keyword only applies the dump netcdf style. It triggers writing of thermo information to the dump file
alongside per-atom data. The values included in the dump file are identical to the values specified by thermo_style.

16.42. dump_modify command 713

LAMMPS Documentation, Release stable 29Sep2021

The thresh keyword only applies to the dump custom, cfg, image, and movie styles. Multiple thresholds can be specified.
Specifying none turns off all threshold criteria. If thresholds are specified, only atoms whose attributes meet all the
threshold criteria are written to the dump file or included in the image. The possible attributes that can be tested for are
the same as those that can be specified in the dump custom command, with the exception of the element attribute, since
it is not a numeric value. Note that a different attributes can be used than those output by the dump custom command.
E.g. you can output the coordinates and stress of atoms whose energy is above some threshold.
If an atom-style variable is used as the attribute, then it can produce continuous numeric values or effective Boolean
0/1 values which may be useful for the comparison operator. Boolean values can be generated by variable formulas
that use comparison or Boolean math operators or special functions like gmask() and rmask() and grmask(). See the
variable command page for details.
The specified value must be a simple numeric value or the word LAST. If LAST is used, it refers to the value of the
attribute the last time the dump command was invoked to produce a snapshot. This is a way to only dump atoms whose
attribute has changed (or not changed). Three examples follow.

dump_modify ... thresh ix != LAST

This will dump atoms which have crossed the periodic x boundary of the simulation box since the last dump. (Note
that atoms that crossed once and then crossed back between the two dump timesteps would not be included.)

region foo sphere 10 20 10 15

variable inregion atom rmask(foo)
dump_modify ... thresh v_inregion |^ LAST

This will dump atoms which crossed the boundary of the spherical region since the last dump.

variable charge atom "(q > 0.5) || (q < -0.5)"

dump_modify ... thresh v_charge |^ LAST

This will dump atoms whose charge has changed from an absolute value less than 1/2 to greater than 1/2 (or vice versa)
since the last dump. E.g. due to reactions and subsequent charge equilibration in a reactive force field.
The choice of operators listed above are the usual comparison operators. The XOR operation (exclusive or) is also
included as “|^”. In this context, XOR means that if either the attribute or value is 0.0 and the other is non-zero, then
the result is “true” and the threshold criterion is met. Otherwise it is not met.

The time keyword only applies to the dump atom, custom, and local styles (and their COMPRESS package ver-
sions atom/gz, custom/gz and local/gz). If set to yes, each frame will will contain two extra lines before the “ITEM:
TIMESTEP” entry:
ITEM: TIME
<elapsed time>
This will output the current elapsed simulation time in current time units equivalent to the thermo keyword time. This
is to simplify post-processing of trajectories using a variable time step, e.g. when using fix dt/reset. The default setting
is no.

The units keyword only applies to the dump atom, custom, and local styles (and their COMPRESS package versions
atom/gz, custom/gz and local/gz). If set to yes, each individual dump file will contain two extra lines at the very
beginning with:
ITEM: UNITS
<units style>

714 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

This will output the current selected units style to the dump file and thus allows visualization and post-processing tools
to determine the choice of units of the data in the dump file. The default setting is no.

The unwrap keyword only applies to the dump dcd and xtc styles. If set to yes, coordinates will be written “unwrapped”
by the image flags for each atom. Unwrapped means that if the atom has passed through a periodic boundary one or
more times, the value is printed for what the coordinate would be if it had not been wrapped back into the periodic box.
Note that these coordinates may thus be far outside the box size stored with the snapshot.

These keywords apply only to the dump image and dump movie styles. Any keyword that affects an image, also affects
a movie, since the movie is simply a collection of images. Some of the keywords only affect the dump movie style. The
descriptions give details.

The acolor keyword can be used with the dump image command, when its atom color setting is type, to set the color
that atoms of each type will be drawn in the image.
The specified type should be an integer from 1 to Ntypes = the number of atom types. A wildcard asterisk can be used
in place of or in conjunction with the type argument to specify a range of atom types. This takes the form “*” or “*n” or
“n*” or “m*n”. If N = the number of atom types, then an asterisk with no numeric values means all types from 1 to N.
A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive).
A middle asterisk means all types from m to n (inclusive).
The specified color can be a single color which is any of the 140 pre-defined colors (see below) or a color name defined
by the dump_modify color option. Or it can be two or more colors separated by a “/” character, e.g. red/green/blue. In
the former case, that color is assigned to all the specified atom types. In the latter case, the list of colors are assigned
in a round-robin fashion to each of the specified atom types.

The adiam keyword can be used with the dump image command, when its atom diameter setting is type, to set the size
that atoms of each type will be drawn in the image. The specified type should be an integer from 1 to Ntypes. As with
the acolor keyword, a wildcard asterisk can be used as part of the type argument to specify a range of atom types. The
specified diam is the size in whatever distance units the input script is using, e.g. Angstroms.

The amap keyword can be used with the dump image command, with its atom keyword, when its atom setting is an
atom-attribute, to setup a color map. The color map is used to assign a specific RGB (red/green/blue) color value to
an individual atom when it is drawn, based on the atom’s attribute, which is a numeric value, e.g. its x-component of
velocity if the atom-attribute “vx” was specified.
The basic idea of a color map is that the atom-attribute will be within a range of values, and that range is associated
with a series of colors (e.g. red, blue, green). An atom’s specific value (vx = -3.2) can then mapped to the series of
colors (e.g. halfway between red and blue), and a specific color is determined via an interpolation procedure.
There are many possible options for the color map, enabled by the amap keyword. Here are the details.
The lo and hi settings determine the range of values allowed for the atom attribute. If numeric values are used for lo
and/or hi, then values that are lower/higher than that value are set to the value. I.e. the range is static. If lo is specified
as min or hi as max then the range is dynamic, and the lower and/or upper bound will be calculated each time an image
is drawn, based on the set of atoms being visualized.
The style setting is two letters, such as “ca”. The first letter is either “c” for continuous, “d” for discrete, or “s” for
sequential. The second letter is either “a” for absolute, or “f” for fractional.

16.42. dump_modify command 715

LAMMPS Documentation, Release stable 29Sep2021

A continuous color map is one in which the color changes continuously from value to value within the range. A discrete
color map is one in which discrete colors are assigned to sub-ranges of values within the range. A sequential color map
is one in which discrete colors are assigned to a sequence of sub-ranges of values covering the entire range.
An absolute color map is one in which the values to which colors are assigned are specified explicitly as values within
the range. A fractional color map is one in which the values to which colors are assigned are specified as a fractional
portion of the range. For example if the range is from -10.0 to 10.0, and the color red is to be assigned to atoms with a
value of 5.0, then for an absolute color map the number 5.0 would be used. But for a fractional map, the number 0.75
would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
The delta setting must be specified for all styles, but is only used for the sequential style; otherwise the value is ignored.
It specifies the bin size to use within the range for assigning consecutive colors to. For example, if the range is from
-10.0 to 10.0 and a delta of 1.0 is used, then 20 colors will be assigned to the range. The first will be from -10.0 <=
color1 < -9.0, then second from -9.0 <= color2 < -8.0, etc.
The N setting is how many entries follow. The format of the entries depends on whether the color map style is con-
tinuous, discrete or sequential. In all cases the color setting can be any of the 140 pre-defined colors (see below) or a
color name defined by the dump_modify color option.
For continuous color maps, each entry has a value and a color. The value is either a number within the range of values
or min or max. The value of the first entry must be min and the value of the last entry must be max. Any entries
in between must have increasing values. Note that numeric values can be specified either as absolute numbers or as
fractions (0.0 to 1.0) of the range, depending on the “a” or “f” in the style setting for the color map.
Here is how the entries are used to determine the color of an individual atom, given the value X of its atom attribute.
X will fall between 2 of the entry values. The color of the atom is linearly interpolated (in each of the RGB values)
between the 2 colors associated with those entries. For example, if X = -5.0 and the 2 surrounding entries are “red” at
-10.0 and “blue” at 0.0, then the atom’s color will be halfway between “red” and “blue”, which happens to be “purple”.
For discrete color maps, each entry has a lo and hi value and a color. The lo and hi settings are either numbers within
the range of values or lo can be min or hi can be max. The lo and hi settings of the last entry must be min and max.
Other entries can have any lo and hi values and the sub-ranges of different values can overlap. Note that numeric lo
and hi values can be specified either as absolute numbers or as fractions (0.0 to 1.0) of the range, depending on the “a”
or “f” in the style setting for the color map.
Here is how the entries are used to determine the color of an individual atom, given the value X of its atom attribute.
The entries are scanned from first to last. The first time that lo <= X <= hi, X is assigned the color associated with that
entry. You can think of the last entry as assigning a default color (since it will always be matched by X), and the earlier
entries as colors that override the default. Also note that no interpolation of a color RGB is done. All atoms will be
drawn with one of the colors in the list of entries.
For sequential color maps, each entry has only a color. Here is how the entries are used to determine the color of an
individual atom, given the value X of its atom attribute. The range is partitioned into N bins of width binsize. Thus
X will fall in a specific bin from 1 to N, say the Mth bin. If it falls on a boundary between 2 bins, it is considered to
be in the higher of the 2 bins. Each bin is assigned a color from the E entries. If E < N, then the colors are repeated.
For example if 2 entries with colors red and green are specified, then the odd numbered bins will be red and the even
bins green. The color of the atom is the color of its bin. Note that the sequential color map is really a shorthand way
of defining a discrete color map without having to specify where all the bin boundaries are.
Here is an example of using a sequential color map to color all the atoms in individual molecules with a different color.
See the examples/pour/in.pour.2d.molecule input script for an example of how this is used.

variable colors string &

"red green blue yellow white &
purple pink orange lime gray"
variable mol atom mol%10
dump 1 all image 250 image.*.jpg v_mol type &
(continues on next page)

716 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

zoom 1.6 adiam 1.5
dump_modify 1 pad 5 amap 0 10 sa 1 10 ${colors}

In this case, 10 colors are defined, and molecule IDs are mapped to one of the colors, even if there are 1000s of
molecules.

The backcolor sets the background color of the images. The color name can be any of the 140 pre-defined colors (see
below) or a color name defined by the dump_modify color option.

The bcolor keyword can be used with the dump image command, with its bond keyword, when its color setting is type,
to set the color that bonds of each type will be drawn in the image.
The specified type should be an integer from 1 to Nbondtypes = the number of bond types. A wildcard asterisk can
be used in place of or in conjunction with the type argument to specify a range of bond types. This takes the form “*”
or “*n” or “n*” or “m*n”. If N = the number of bond types, then an asterisk with no numeric values means all types
from 1 to N. A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n (inclusive).
The specified color can be a single color which is any of the 140 pre-defined colors (see below) or a color name defined
by the dump_modify color option. Or it can be two or more colors separated by a “/” character, e.g. red/green/blue. In
the former case, that color is assigned to all the specified bond types. In the latter case, the list of colors are assigned
in a round-robin fashion to each of the specified bond types.

The bdiam keyword can be used with the dump image command, with its bond keyword, when its diam setting is type,
to set the diameter that bonds of each type will be drawn in the image. The specified type should be an integer from 1
to Nbondtypes. As with the bcolor keyword, a wildcard asterisk can be used as part of the type argument to specify a
range of bond types. The specified diam is the size in whatever distance units you are using, e.g. Angstroms.

The bitrate keyword can be used with the dump movie command to define the size of the resulting movie file and its
quality via setting how many kbits per second are to be used for the movie file. Higher bitrates require less compression
and will result in higher quality movies. The quality is also determined by the compression format and encoder. The
default setting is 2000 kbit/s, which will result in average quality with older compression formats.

Note: Not all movie file formats supported by dump movie allow the bitrate to be set. If not, the setting is silently
ignored.

The boxcolor keyword sets the color of the simulation box drawn around the atoms in each image as well as the color
of processor sub-domain boundaries. See the “dump image box” command for how to specify that a box be drawn
via the box keyword, and the sub-domain boundaries via the subbox keyword. The color name can be any of the 140
pre-defined colors (see below) or a color name defined by the dump_modify color option.

The color keyword allows definition of a new color name, in addition to the 140-predefined colors (see below), and asso-
ciates 3 red/green/blue RGB values with that color name. The color name can then be used with any other dump_modify
keyword that takes a color name as a value. The RGB values should each be floating point values between 0.0 and 1.0
inclusive.

16.42. dump_modify command 717

LAMMPS Documentation, Release stable 29Sep2021

When a color name is converted to RGB values, the user-defined color names are searched first, then the 140 pre-defined
color names. This means you can also use the color keyword to overwrite one of the pre-defined color names with new
RBG values.

The framerate keyword can be used with the dump movie command to define the duration of the resulting movie file.
Movie files written by the dump movie command have a default frame rate of 24 frames per second and the images
generated will be converted at that rate. Thus a sequence of 1000 dump images will result in a movie of about 42
seconds. To make a movie run longer you can either generate images more frequently or lower the frame rate. To speed
a movie up, you can do the inverse. Using a frame rate higher than 24 is not recommended, as it will result in simply
dropping the rendered images. It is more efficient to dump images less frequently.

The header keyword toggles whether the dump file will include a header. Excluding a header will reduce the size of
the dump file for fixes such as fix pair/tracker which do not require the information typically written to the header.

The COMPRESS package offers both GZ and Zstd compression variants of styles atom, custom, local, cfg, and xyz.
When using these styles the compression level can be controlled by the compression_level parameter. File names
with these styles have to end in either .gz or .zst.
GZ supports compression levels from -1 (default), 0 (no compression), and 1 to 9. 9 being the best compression. The
COMPRESS /gz styles use 9 as default compression level.
Zstd offers a wider range of compression levels, including negative levels that sacrifice compression for performance.
0 is the default, positive levels are 1 to 22, with 22 being the most expensive compression. Zstd promises higher
compression/decompression speeds for similar compression ratios. For more details see http://facebook.github.io/zstd/.
In addition, Zstd compressed files can have a checksum of the entire contents. The Zstd enabled dump styles enable
this feature by default and it can be disabled with the checksum parameter.

16.42.4 Restrictions

none

16.42.5 Related commands

dump, dump image, undump

16.42.6 Default

The option defaults are

• append = no
• buffer = yes for dump styles atom, custom, loca, and xyz
• element = “C” for every atom type
• every = whatever it was set to via the dump command
• fileper = # of processors
• first = no

718 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• flush = yes
• format = %d and %g for each integer or floating point value
• image = no
• label = ENTRIES
• maxfiles = -1
• nfile = 1
• pad = 0
• pbc = no
• precision = 1000
• region = none
• scale = yes
• sort = off for dump styles atom, custom, cfg, and local
• sort = id for dump styles dcd, xtc, and xyz
• thresh = none
• units = no
• unwrap = no
• acolor = * red/green/blue/yellow/aqua/cyan
• adiam = * 1.0
• amap = min max cf 0.0 2 min blue max red
• backcolor = black
• bcolor = * red/green/blue/yellow/aqua/cyan
• bdiam = * 0.5
• bitrate = 2000
• boxcolor = yellow
• color = 140 color names are pre-defined as listed below
• framerate = 24
• compression_level = 9 (gz variants)
• compression_level = 0 (zstd variants)
• checksum = yes (zstd variants)

These are the standard 109 element names that LAMMPS pre-defines for use with the dump image and dump_modify
commands.
• 1-10 = “H”, “He”, “Li”, “Be”, “B”, “C”, “N”, “O”, “F”, “Ne”
• 11-20 = “Na”, “Mg”, “Al”, “Si”, “P”, “S”, “Cl”, “Ar”, “K”, “Ca”
• 21-30 = “Sc”, “Ti”, “V”, “Cr”, “Mn”, “Fe”, “Co”, “Ni”, “Cu”, “Zn”
• 31-40 = “Ga”, “Ge”, “As”, “Se”, “Br”, “Kr”, “Rb”, “Sr”, “Y”, “Zr”

16.42. dump_modify command 719

LAMMPS Documentation, Release stable 29Sep2021

• 41-50 = “Nb”, “Mo”, “Tc”, “Ru”, “Rh”, “Pd”, “Ag”, “Cd”, “In”, “Sn”
• 51-60 = “Sb”, “Te”, “I”, “Xe”, “Cs”, “Ba”, “La”, “Ce”, “Pr”, “Nd”
• 61-70 = “Pm”, “Sm”, “Eu”, “Gd”, “Tb”, “Dy”, “Ho”, “Er”, “Tm”, “Yb”
• 71-80 = “Lu”, “Hf”, “Ta”, “W”, “Re”, “Os”, “Ir”, “Pt”, “Au”, “Hg”
• 81-90 = “Tl”, “Pb”, “Bi”, “Po”, “At”, “Rn”, “Fr”, “Ra”, “Ac”, “Th”
• 91-100 = “Pa”, “U”, “Np”, “Pu”, “Am”, “Cm”, “Bk”, “Cf”, “Es”, “Fm”
• 101-109 = “Md”, “No”, “Lr”, “Rf”, “Db”, “Sg”, “Bh”, “Hs”, “Mt”

These are the 140 colors that LAMMPS pre-defines for use with the dump image and dump_modify commands. Addi-
tional colors can be defined with the dump_modify color command. The 3 numbers listed for each name are the RGB
(red/green/blue) values. Divide each value by 255 to get the equivalent 0.0 to 1.0 value.

720 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

aliceblue = 240, antiquewhite = 250, aqua = 0, 255, 255 aquamarine = 127, azure = 240, 255,
248, 255 235, 215 255, 212 255
beige = 245, 245, bisque = 255, 228, 196 black = 0, 0, 0 blanchedalmond = blue = 0, 0, 255
220 255, 255, 205
blueviolet = 138, brown = 165, 42, 42 burlywood = 222, cadetblue = 95, 158, chartreuse = 127,
43, 226 184, 135 160 255, 0
chocolate = 210, coral = 255, 127, 80 cornflowerblue = cornsilk = 255, 248, crimson = 220, 20,
105, 30 100, 149, 237 220 60
cyan = 0, 255, 255 darkblue = 0, 0, 139 darkcyan = 0, 139, darkgoldenrod = darkgray = 169,
139 184, 134, 11 169, 169
darkgreen = 0, 100, darkkhaki = 189, 183, darkmagenta = 139, darkolivegreen = darkorange = 255,
0 107 0, 139 85, 107, 47 140, 0
darkorchid = 153, darkred = 139, 0, 0 darksalmon = 233, darkseagreen = darkslateblue = 72,
50, 204 150, 122 143, 188, 143 61, 139
darkslategray = 47, darkturquoise = 0, 206, darkviolet = 148, 0, deeppink = 255, 20, deepskyblue = 0,
79, 79 209 211 147 191, 255
dimgray = 105, dodgerblue = 30, 144, firebrick = 178, 34, floralwhite = 255, forestgreen = 34,
105, 105 255 34 250, 240 139, 34
fuchsia = 255, 0, gainsboro = 220, 220, ghostwhite = 248, gold = 255, 215, 0 goldenrod = 218,
255 220 248, 255 165, 32
gray = 128, 128, green = 0, 128, 0 greenyellow = 173, honeydew = 240, hotpink = 255, 105,
128 255, 47 255, 240 180
indianred = 205, indigo = 75, 0, 130 ivory = 255, 240, khaki = 240, 230, lavender = 230,
92, 92 240 140 230, 250
lavenderblush = lawngreen = 124, 252, lemonchiffon = 255, lightblue = 173, lightcoral = 240,
255, 240, 245 0 250, 205 216, 230 128, 128
lightcyan = 224, lightgoldenrodyellow lightgreen = 144, lightgrey = 211, lightpink = 255,
255, 255 = 250, 250, 210 238, 144 211, 211 182, 193
lightsalmon = 255, lightseagreen = 32, lightskyblue = 135, lightslategray = lightsteelblue =
160, 122 178, 170 206, 250 119, 136, 153 176, 196, 222
lightyellow = 255, lime = 0, 255, 0 limegreen = 50, 205, linen = 250, 240, magenta = 255, 0,
255, 224 50 230 255
maroon = 128, 0, 0 mediumaquamarine = mediumblue = 0, 0, mediumorchid = mediumpurple =
102, 205, 170 205 186, 85, 211 147, 112, 219
mediumseagreen = mediumslateblue = mediumspringgreen mediumturquoise = mediumvioletred =
60, 179, 113 123, 104, 238 = 0, 250, 154 72, 209, 204 199, 21, 133
midnightblue = 25, mintcream = 245, 255, mistyrose = 255, moccasin = 255, navajowhite = 255,
25, 112 250 228, 225 228, 181 222, 173
navy = 0, 0, 128 oldlace = 253, 245, olive = 128, 128, 0 olivedrab = 107, orange = 255, 165,
230 142, 35 0
orangered = 255, orchid = 218, 112, 214 palegoldenrod = palegreen = 152, paleturquoise =
69, 0 238, 232, 170 251, 152 175, 238, 238
palevioletred = papayawhip = 255, peachpuff = 255, peru = 205, 133, 63 pink = 255, 192,
219, 112, 147 239, 213 239, 213 203
plum = 221, 160, powderblue = 176, purple = 128, 0, 128 red = 255, 0, 0 rosybrown = 188,
221 224, 230 143, 143
royalblue = 65, saddlebrown = 139, salmon = 250, 128, sandybrown = 244, seagreen = 46, 139,
105, 225 69, 19 114 164, 96 87
seashell = 255, 245, sienna = 160, 82, 45 silver = 192, 192, skyblue = 135, 206, slateblue = 106, 90,
238 192 235 205
slategray = 112, snow = 255, 250, 250 springgreen = 0, steelblue = 70, 130, tan = 210, 180, 140
128, 144 255, 127 180
teal = 0, 128, 128 thistle = 216, 191, 216 tomato = 253, 99, 71 turquoise = 64, 224, violet = 238, 130,
208 238
wheat dump_modify
16.42. = 245, 222, white = 255, 255, 255
command whitesmoke = 245, yellow = 255, 255, 0 yellowgreen = 154,
721
179 245, 245 205, 50
LAMMPS Documentation, Release stable 29Sep2021

16.43 dump molfile command

16.43.1 Syntax

dump ID group-ID molfile N file format path

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be imaged
• molfile = style of dump command (other styles atom or cfg or dcd or xtc or xyz or local or custom are discussed
on the dump doc page)
• N = dump every this many timesteps
• file = name of file to write to
• format = file format to be used
• path = file path with plugins (optional)

16.43.2 Examples

dump mf1 all molfile 10 melt1.xml hoomd

dump mf2 all molfile 10 melt2-*.pdb pdb .
dump mf3 all molfile 50 melt3.xyz xyz .:/home/akohlmey/vmd/plugins/LINUX/molfile

16.43.3 Description

Dump a snapshot of atom coordinates and selected additional quantities to one or more files every N timesteps in one
of several formats. Only information for atoms in the specified group is dumped. This specific dump style uses molfile
plugins that are bundled with the VMD molecular visualization and analysis program.
Unless the filename contains a * character, the output will be written to one single file with the specified format.
Otherwise there will be one file per snapshot and the * will be replaced by the time step number when the snapshot is
written.

Note: Because periodic boundary conditions are enforced only on timesteps when neighbor lists are rebuilt, the
coordinates of an atom written to a dump file may be slightly outside the simulation box.

The molfile plugin API has a few restrictions that have to be honored by this dump style: the number of atoms must
not change, the atoms must be sorted, outside of the coordinates no change in atom properties (like type, mass, charge)
will be recorded.

The format keyword determines what format is used to write out the dump. For this to work, LAMMPS must be able
to find and load a compatible molfile plugin that supports this format. Settings made via the dump_modify command
can alter per atom properties like element names.
The path keyword determines which in directories. This is a “path” like other search paths, i.e. it can contain multiple
directories separated by a colon (or semi-colon on windows). This keyword is optional and default to “.”, the current
directory.

722 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The unwrap option of the dump_modify command allows coordinates to be written “unwrapped” by the image flags for
each atom. Unwrapped means that if the atom has passed through a periodic boundary one or more times, the value
is printed for what the coordinate would be if it had not been wrapped back into the periodic box. Note that these
coordinates may thus be far outside the box size stored with the snapshot.

Dumps are performed on timesteps that are a multiple of N (including timestep 0) and on the last timestep of a min-
imization if the minimization converges. Note that this means a dump will not be performed on the initial timestep
after the dump command is invoked, if the current timestep is not a multiple of N. This behavior can be changed via
the dump_modify first command, which can be useful if the dump command is invoked after a minimization ended on
an arbitrary timestep. N can be changed between runs by using the dump_modify every command. The dump_modify
every command also allows a variable to be used to determine the sequence of timesteps on which dump files are
written.

16.43.4 Restrictions

The molfile dump style is part of the MOLFILE package. It is only enabled if LAMMPS was built with that package.
See the Build package page for more info.
Molfile plugins provide a consistent programming interface to read and write file formats commonly used in molec-
ular simulations. The MOLFILE package only provides the interface code, not the plugins. These can be ob-
tained from a VMD installation which has to match the platform that you are using to compile LAMMPS for. By
adding plugins to VMD, support for new file formats can be added to LAMMPS (or VMD or other programs that
use them) without having to re-compile the application itself. The plugins are installed in the directory: <VMD-
HOME>/plugins/<VMDARCH>/molfile

Note: while the programming interface (API) to the plugins is backward compatible, the binary interface (ABI) has
been changing over time, so it is necessary to compile this package with the plugin header files from VMD that match
the binary plugins. These header files in the directory: <VMDHOME>/plugins/include For convenience, the package
ships with a set of header files that are compatible with VMD 1.9 and 1.9.1 (June 2012)

16.43.5 Related commands

dump, dump_modify, undump

16.43.6 Default

The default path is “.”. All other properties have to be specified.

16.43. dump molfile command 723

LAMMPS Documentation, Release stable 29Sep2021

16.44 dump netcdf command

16.45 dump netcdf/mpiio command

16.45.1 Syntax

dump ID group-ID netcdf N file args

dump ID group-ID netcdf/mpiio N file args

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be imaged
• netcdf or netcdf/mpiio = style of dump command (other styles atom or cfg or dcd or xtc or xyz or local or custom
are discussed on the dump doc page)
• N = dump every this many timesteps
• file = name of file to write dump info to
• args = list of atom attributes, same as for dump_style custom

16.45.2 Examples

dump 1 all netcdf 100 traj.nc type x y z vx vy vz

dump_modify 1 append yes at -1 thermo yes
dump 1 all netcdf/mpiio 1000 traj.nc id type x y z
dump 1 all netcdf 1000 traj.*.nc id type x y z

16.45.3 Description

Dump a snapshot of atom coordinates every N timesteps in Amber-style NetCDF file format. NetCDF files are binary,
portable and self-describing. This dump style will write only one file on the root node. The dump style netcdf uses
the standard NetCDF library. All data is collected on one processor and then written to the dump file. Dump style
netcdf/mpiio uses the parallel NetCDF library and MPI-IO to write to the dump file in parallel; it has better performance
on a larger number of processors. Note that style netcdf outputs all atoms sorted by atom tag while style netcdf/mpiio
outputs atoms in order of their MPI rank.
NetCDF files can be directly visualized via the following tools:
Ovito (http://www.ovito.org/). Ovito supports the AMBER convention and all extensions of this dump style.
• VMD (http://www.ks.uiuc.edu/Research/vmd/).
• AtomEye (http://www.libatoms.org/). The libAtoms version of AtomEye contains a NetCDF reader that is not
present in the standard distribution of AtomEye.
In addition to per-atom data, thermo data can be included in the dump file. The data included in the dump file is
identical to the data specified by thermo_style.

724 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.45.4 Restrictions

The netcdf and netcdf/mpiio dump styles are part of the NETCDF package. They are only enabled if LAMMPS was
built with that package. See the Build package page for more info.
The netcdf and netcdf/mpiio dump styles currently cannot dump string properties or properties from variables.

16.45.5 Related commands

dump, dump_modify, undump

16.46 dump vtk command

16.46.1 Syntax

dump ID group-ID vtk N file args

• ID = user-assigned name for the dump

• group-ID = ID of the group of atoms to be dumped
• vtk = style of dump command (other styles atom or cfg or dcd or xtc or xyz or local or custom are discussed on
the dump doc page)
• N = dump every this many timesteps
• file = name of file to write dump info to
• args = same as arguments for dump_style custom

16.46.2 Examples

dump dmpvtk all vtk 100 dump*.myforce.vtk id type vx fx

dump dmpvtp flow vtk 100 dump*.%.displace.vtp id type c_myD[1] c_myD[2] c_myD[3] v_ke

16.46.3 Description

Dump a snapshot of atom quantities to one or more files every N timesteps in a format readable by the VTK visualization
toolkit or other visualization tools that use it, e.g. ParaView. The timesteps on which dump output is written can also
be controlled by a variable; see the dump_modify every command for details.
This dump style is similar to dump_style custom but uses the VTK library to write data to VTK simple legacy or XML
format depending on the filename extension specified for the dump file. This can be either *.vtk for the legacy format
or *.vtp and *.vtu, respectively, for XML format; see the VTK homepage for a detailed description of these formats.
Since this naming convention conflicts with the way binary output is usually specified (see below), the dump_modify
binary command allows setting of a binary option for this dump style explicitly.
Only information for atoms in the specified group is dumped. The dump_modify thresh and region commands can also
alter what atoms are included; see details below.
As described below, special characters (“*”, “%”) in the filename determine the kind of output.

16.46. dump vtk command 725

LAMMPS Documentation, Release stable 29Sep2021

Warning: Because periodic boundary conditions are enforced only on timesteps when neighbor lists are rebuilt,
the coordinates of an atom written to a dump file may be slightly outside the simulation box.

Warning: Unless the dump_modify sort option is invoked, the lines of atom information written to dump files
will be in an indeterminate order for each snapshot. This is even true when running on a single processor, if
the atom_modify sort option is on, which it is by default. In this case atoms are re-ordered periodically during a
simulation, due to spatial sorting. It is also true when running in parallel, because data for a single snapshot is
collected from multiple processors, each of which owns a subset of the atoms.

For the vtk style, sorting is off by default. See the dump_modify page for details.

The dimensions of the simulation box are written to a separate file for each snapshot (either in legacy VTK or XML
format depending on the format of the main dump file) with the suffix _boundingBox appended to the given dump
filename.
For an orthogonal simulation box this information is saved as a rectilinear grid (legacy .vtk or .vtr XML format).
Triclinic simulation boxes (non-orthogonal) are saved as hexahedrons in either legacy .vtk or .vtu XML format.
Style vtk allows you to specify a list of atom attributes to be written to the dump file for each atom. The list of possible
attributes is the same as for the dump_style custom command; see its page for a listing and an explanation of each
attribute.

Note: Since position data is required to write VTK files the atom attributes “x y z” do not have to be specified explicitly;
they will be included in the dump file regardless. Also, in contrast to the custom style, the specified vtk attributes are
rearranged to ensure correct ordering of vector components (except for computes and fixes - these have to be given in
the right order) and duplicate entries are removed.

The VTK format uses a single snapshot of the system per file, thus a wildcard “*” must be included in the filename, as
discussed below. Otherwise the dump files will get overwritten with the new snapshot each time.

Dumps are performed on timesteps that are a multiple of N (including timestep 0) and on the last timestep of a mini-
mization if the minimization converges. Note that this means a dump will not be performed on the initial timestep after
the dump command is invoked, if the current timestep is not a multiple of N. This behavior can be changed via the
dump_modify first command, which can also be useful if the dump command is invoked after a minimization ended on
an arbitrary timestep. N can be changed between runs by using the dump_modify every command. The dump_modify
every command also allows a variable to be used to determine the sequence of timesteps on which dump files are writ-
ten. In this mode a dump on the first timestep of a run will also not be written unless the dump_modify first command
is used.
Dump filenames can contain two wildcard characters. If a “*” character appears in the filename, then one file per
snapshot is written and the “*” character is replaced with the timestep value. For example, tmp.dump*.vtk becomes
tmp.dump0.vtk, tmp.dump10000.vtk, tmp.dump20000.vtk, etc. Note that the dump_modify pad command can be used
to insure all timestep numbers are the same length (e.g. 00010), which can make it easier to read a series of dump files
in order with some post-processing tools.
If a “%” character appears in the filename, then each of P processors writes a portion of the dump file, and the “%” char-
acter is replaced with the processor ID from 0 to P-1 preceded by an underscore character. For example, tmp.dump%.vtp
becomes tmp.dump_0.vtp, tmp.dump_1.vtp, . . . tmp.dump_P-1.vtp, etc. This creates smaller files and can be a fast
mode of output on parallel machines that support parallel I/O for output.

726 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

By default, P = the number of processors meaning one file per processor, but P can be set to a smaller value via the nfile
or fileper keywords of the dump_modify command. These options can be the most efficient way of writing out dump
files when running on large numbers of processors.
For the legacy VTK format “%” is ignored and P = 1, i.e., only processor 0 does write files.
Note that using the “*” and “%” characters together can produce a large number of small dump files!
If dump_modify binary is used, the dump file (or files, if “*” or “%” is also used) is written in binary format. A binary
dump file will be about the same size as a text version, but will typically write out much faster.

16.46.4 Restrictions

The vtk style does not support writing of gzipped dump files.
The vtk dump style is part of the VTK package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.
To use this dump style, you also must link to the VTK library. See the info in lib/vtk/README and insure the Make-
file.lammps file in that directory is appropriate for your machine.
The vtk dump style supports neither buffering or custom format strings.

16.46.5 Related commands

dump, dump image, dump_modify, undump

16.46.6 Default

By default, files are written in ASCII format. If the file extension is not one of .vtk, .vtp or .vtu, the legacy VTK file
format is used.

16.47 dynamical_matrix command

16.47.1 Syntax

dynamical_matrix group-ID style gamma args keyword value ...

• group-ID = ID of group of atoms to displace

• style = regular or eskm
• gamma = finite different displacement length (distance units)
• one or more keyword/arg pairs may be appended
keyword = file or binary
file name = name of output file for the dynamical matrix
binary arg = yes or no or gzip

16.47. dynamical_matrix command 727

LAMMPS Documentation, Release stable 29Sep2021

16.47.2 Examples

dynamical_matrix 1 regular 0.000001

dynamical_matrix 1 eskm 0.000001
dynamical_matrix 3 regular 0.00004 file dynmat.dat
dynamical_matrix 5 eskm 0.00000001 file dynamical.dat binary yes

16.47.3 Description

Calculate the dynamical matrix by finite difference of the selected group,

Φαβ
ij
D= p
Mi Mj

where D is the dynamical matrix and Φ is the force constant matrix defined by

∂2U
Φαβ
ij =
∂xi,α ∂xj,β

The output for the dynamical matrix is printed three elements at a time. The three elements are the three β elements
for a respective i/α/j combination. Each line is printed in order of j increasing first, α second, and i last.
If the style eskm is selected, the dynamical matrix will be in units of inverse squared femtoseconds. These units will
then conveniently leave frequencies in THz.

16.47.4 Restrictions

The command collects an array of nine times the number of atoms in a group on every single MPI rank, so the memory
requirements can be very significant for large systems.
This command is part of the PHONON package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.

16.47.5 Related commands

fix phonon, fix numdiff ,

compute hma uses an analytic formulation of the Hessian provided by a pair_style’s Pair::single_hessian() function, if
implemented.

16.47.6 Default

The default settings are file = “dynmat.dyn”, binary = no

728 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.48 echo command

16.48.1 Syntax

echo style

• style = none or screen or log or both

16.48.2 Examples

echo both
echo log

16.48.3 Description

This command determines whether LAMMPS echoes each input script command to the screen and/or log file as it is
read and processed. If an input script has errors, it can be useful to look at echoed output to see the last command
processed.
The command-line switch -echo can be used in place of this command.

16.48.4 Restrictions

none

16.48.5 Related commands

none

16.48.6 Default

echo log

16.49 fix command

16.49.1 Syntax

fix ID group-ID style args

• ID = user-assigned name for the fix

• group-ID = ID of the group of atoms to apply the fix to
• style = one of a long list of possible style names (see below)
• args = arguments used by a particular style

16.48. echo command 729

LAMMPS Documentation, Release stable 29Sep2021

16.49.2 Examples

fix 1 all nve

fix 3 all nvt temp 300.0 300.0 0.01
fix mine top setforce 0.0 NULL 0.0

16.49.3 Description

Set a fix that will be applied to a group of atoms. In LAMMPS, a “fix” is any operation that is applied to the system dur-
ing timestepping or minimization. Examples include updating of atom positions and velocities due to time integration,
controlling temperature, applying constraint forces to atoms, enforcing boundary conditions, computing diagnostics,
etc. There are hundreds of fixes defined in LAMMPS and new ones can be added; see the Modify page for details.
Fixes perform their operations at different stages of the timestep. If 2 or more fixes operate at the same stage of the
timestep, they are invoked in the order they were specified in the input script.
The ID of a fix can only contain alphanumeric characters and underscores.
Fixes can be deleted with the unfix command.

Note: The unfix command is the only way to turn off a fix; simply specifying a new fix with a similar style will not
turn off the first one. This is especially important to realize for integration fixes. For example, using a fix nve command
for a second run after using a fix nvt command for the first run, will not cancel out the NVT time integration invoked
by the “fix nvt” command. Thus two time integrators would be in place!

If you specify a new fix with the same ID and style as an existing fix, the old fix is deleted and the new one is created
(presumably with new settings). This is the same as if an “unfix” command were first performed on the old fix, except
that the new fix is kept in the same order relative to the existing fixes as the old one originally was. Note that this
operation also wipes out any additional changes made to the old fix via the fix_modify command.
The fix modify command allows settings for some fixes to be reset. See the page for individual fixes for details.
Some fixes store an internal “state” which is written to binary restart files via the restart or write_restart commands.
This allows the fix to continue on with its calculations in a restarted simulation. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file. See the doc pages for individual fixes for info on
which ones can be restarted.

Some fixes calculate one of three styles of quantities: global, per-atom, or local, which can be used by other commands
or output as described below. A global quantity is one or more system-wide values, e.g. the energy of a wall interacting
with particles. A per-atom quantity is one or more values per atom, e.g. the displacement vector for each atom since
time 0. Per-atom values are set to 0.0 for atoms not in the specified fix group. Local quantities are calculated by each
processor based on the atoms it owns, but there may be zero or more per atoms.
Note that a single fix can produce either global or per-atom or local quantities (or none at all), but not both global and
per-atom. It can produce local quantities in tandem with global or per-atom quantities. The fix page will explain.
Global, per-atom, and local quantities each come in three kinds: a single scalar value, a vector of values, or a 2d array
of values. The doc page for each fix describes the style and kind of values it produces, e.g. a per-atom vector. Some
fixes produce more than one kind of a single style, e.g. a global scalar and a global vector.
When a fix quantity is accessed, as in many of the output commands discussed below, it can be referenced via the
following bracket notation, where ID is the ID of the fix:

730 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

f_ID | entire scalar, vector, or array

f_ID[I] | one element of vector, one column of array
f_ID[I][J] | one element of array

In other words, using one bracket reduces the dimension of the quantity once (vector -> scalar, array -> vector). Using
two brackets reduces the dimension twice (array -> scalar). Thus a command that uses scalar fix values as input can
also process elements of a vector or array.
Note that commands and variables which use fix quantities typically do not allow for all kinds, e.g. a command may
require a vector of values, not a scalar. This means there is no ambiguity about referring to a fix quantity as f_ID even
if it produces, for example, both a scalar and vector. The doc pages for various commands explain the details.

In LAMMPS, the values generated by a fix can be used in several ways:

• Global values can be output via the thermo_style custom or fix ave/time command. Or the values can be referenced
in a variable equal or variable atom command.
• Per-atom values can be output via the dump custom command. Or they can be time-averaged via the fix ave/atom
command or reduced by the compute reduce command. Or the per-atom values can be referenced in an atom-style
variable.
• Local values can be reduced by the compute reduce command, or histogrammed by the fix ave/histo command.
See the Howto output page for a summary of various LAMMPS output options, many of which involve fixes.
The results of fixes that calculate global quantities can be either “intensive” or “extensive” values. Intensive means
the value is independent of the number of atoms in the simulation, e.g. temperature. Extensive means the value scales
with the number of atoms in the simulation, e.g. total rotational kinetic energy. Thermodynamic output will normalize
extensive values by the number of atoms in the system, depending on the “thermo_modify norm” setting. It will not
normalize intensive values. If a fix value is accessed in another way, e.g. by a variable, you may want to know whether
it is an intensive or extensive value. See the page for individual fixes for further info.

Each fix style has its own page which describes its arguments and what it does, as listed below. Here is an alphabetic
list of fix styles available in LAMMPS. They are also listed in more compact form on the Commands fix doc page.
There are also additional accelerated fix styles included in the LAMMPS distribution for faster performance on CPUs,
GPUs, and KNLs. The individual style names on the Commands fix doc page are followed by one or more of (g,i,k,o,t)
to indicate which accelerated styles exist.
• accelerate/cos - apply cosine-shaped acceleration to atoms
• adapt - change a simulation parameter over time
• adapt/fep - enhanced version of fix adapt
• addforce - add a force to each atom
• addtorque - add a torque to a group of atoms
• append/atoms - append atoms to a running simulation
• atc - initiates a coupled MD/FE simulation
• atom/swap - Monte Carlo atom type swapping
• ave/atom - compute per-atom time-averaged quantities
• ave/chunk - compute per-chunk time-averaged quantities
• ave/correlate - compute/output time correlations

16.49. fix command 731

LAMMPS Documentation, Release stable 29Sep2021

• ave/correlate/long -
• ave/histo - compute/output time-averaged histograms
• ave/histo/weight - weighted version of fix ave/histo
• ave/time - compute/output global time-averaged quantities
• aveforce - add an averaged force to each atom
• balance - perform dynamic load-balancing
• brownian - overdamped translational brownian motion
• brownian/asphere - overdamped translational and rotational brownian motion for ellipsoids
• brownian/sphere - overdamped translational and rotational brownian motion for spheres
• bocs - NPT style time integration with pressure correction
• bond/break - break bonds on the fly
• bond/create - create bonds on the fly
• bond/create/angle - create bonds on the fly with angle constraints
• bond/react - apply topology changes to model reactions
• bond/swap - Monte Carlo bond swapping
• box/relax - relax box size during energy minimization
• charge/regulation - Monte Carlo sampling of charge regulation
• client/md - MD client for client/server simulations
• cmap - enables CMAP cross-terms of the CHARMM force field
• colvars - interface to the collective variables “Colvars” library
• controller - apply control loop feedback mechanism
• deform - change the simulation box size/shape
• deposit - add new atoms above a surface
• dpd/energy - constant energy dissipative particle dynamics
• drag - drag atoms towards a defined coordinate
• drude - part of Drude oscillator polarization model
• drude/transform/direct - part of Drude oscillator polarization model
• drude/transform/inverse - part of Drude oscillator polarization model
• dt/reset - reset the timestep based on velocity, forces
• edpd/source - add heat source to eDPD simulations
• efield - impose electric field on system
• ehex - enhanced heat exchange algorithm
• electron/stopping - electronic stopping power as a friction force
• electron/stopping/fit - electronic stopping power as a friction force
• enforce2d - zero out z-dimension velocity and force
• eos/cv -

732 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• eos/table -
• eos/table/rx -
• evaporate - remove atoms from simulation periodically
• external - callback to an external driver program
• ffl - apply a Fast-Forward Langevin equation thermostat
• filter/corotate - implement corotation filter to allow larger timesteps with r-RESPA
• flow/gauss - Gaussian dynamics for constant mass flux
• freeze - freeze atoms in a granular simulation
• gcmc - grand canonical insertions/deletions
• gld - generalized Langevin dynamics integrator
• gle - generalized Langevin equation thermostat
• gravity - add gravity to atoms in a granular simulation
• grem - implements the generalized replica exchange method
• halt - terminate a dynamics run or minimization
• heat - add/subtract momentum-conserving heat
• hyper/global - global hyperdynamics
• hyper/local - local hyperdynamics
• imd - implements the “Interactive MD” (IMD) protocol
• indent - impose force due to an indenter
• ipi - enable LAMMPS to run as a client for i-PI path-integral simulations
• langevin - Langevin temperature control
• langevin/drude - Langevin temperature control of Drude oscillators
• langevin/eff - Langevin temperature control for the electron force field model
• langevin/spin - Langevin temperature control for a spin or spin-lattice system
• latte - wrapper on LATTE density-functional tight-binding code
• lb/fluid -
• lb/momentum -
• lb/pc -
• lb/rigid/pc/sphere -
• lb/viscous -
• lineforce - constrain atoms to move in a line
• manifoldforce - restrain atoms to a manifold during minimization
• mdi/engine - connect LAMMPS to external programs via the MolSSI Driver Interface (MDI)
• meso/move - move mesoscopic SPH/SDPD particles in a prescribed fashion
• momentum - zero the linear and/or angular momentum of a group of atoms
• momentum/chunk - zero the linear and/or angular momentum of a chunk of atoms

16.49. fix command 733

LAMMPS Documentation, Release stable 29Sep2021

• move - move atoms in a prescribed fashion

• mscg - apply MSCG method for force-matching to generate coarse grain models
• msst - multi-scale shock technique (MSST) integration
• mvv/dpd - DPD using the modified velocity-Verlet integration algorithm
• mvv/edpd - constant energy DPD using the modified velocity-Verlet algorithm
• mvv/tdpd - constant temperature DPD using the modified velocity-Verlet algorithm
• neb - nudged elastic band (NEB) spring forces
• neb/spin - nudged elastic band (NEB) spring forces for spins
• nph - constant NPH time integration via Nose/Hoover
• nph/asphere - NPH for aspherical particles
• nph/body - NPH for body particles
• nph/eff - NPH for nuclei and electrons in the electron force field model
• nph/sphere - NPH for spherical particles
• nphug - constant-stress Hugoniostat integration
• npt - constant NPT time integration via Nose/Hoover
• npt/asphere - NPT for aspherical particles
• npt/body - NPT for body particles
• npt/cauchy - NPT with Cauchy stress
• npt/eff - NPT for nuclei and electrons in the electron force field model
• npt/sphere - NPT for spherical particles
• npt/uef - NPT style time integration with diagonal flow
• numdiff - compute derivatives of per-atom data from finite differences
• nve - constant NVE time integration
• nve/asphere - NVE for aspherical particles
• nve/asphere/noforce - NVE for aspherical particles without forces
• nve/awpmd - NVE for the Antisymmetrized Wave Packet Molecular Dynamics model
• nve/body - NVE for body particles
• nve/dot - rigid body constant energy time integrator for coarse grain models
• nve/dotc/langevin - Langevin style rigid body time integrator for coarse grain models
• nve/eff - NVE for nuclei and electrons in the electron force field model
• nve/limit - NVE with limited step length
• nve/line - NVE for line segments
• nve/manifold/rattle -
• nve/noforce - NVE without forces (v only)
• nve/sphere - NVE for spherical particles
• nve/spin - NVE for a spin or spin-lattice system

734 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• nve/tri - NVE for triangles

• nvk - constant kinetic energy time integration
• nvt - NVT time integration via Nose/Hoover
• nvt/asphere - NVT for aspherical particles
• nvt/body - NVT for body particles
• nvt/eff - NVE for nuclei and electrons in the electron force field model
• nvt/manifold/rattle -
• nvt/sllod - NVT for NEMD with SLLOD equations
• nvt/sllod/eff - NVT for NEMD with SLLOD equations for the electron force field model
• nvt/sphere - NVT for spherical particles
• nvt/uef - NVT style time integration with diagonal flow
• oneway - constrain particles on move in one direction
• orient/bcc - add grain boundary migration force for BCC
• orient/fcc - add grain boundary migration force for FCC
• orient/eco - add generalized grain boundary migration force
• pafi - constrained force averages on hyper-planes to compute free energies (PAFI)
• pair/tracker - track properties of pairwise interactions
• phonon - calculate dynamical matrix from MD simulations
• pimd - Feynman path integral molecular dynamics
• planeforce - constrain atoms to move in a plane
• plumed - wrapper on PLUMED free energy library
• poems - constrain clusters of atoms to move as coupled rigid bodies
• polarize/bem/gmres -
• polarize/bem/icc -
• polarize/functional -
• pour - pour new atoms/molecules into a granular simulation domain
• precession/spin -
• press/berendsen - pressure control by Berendsen barostat
• print - print text and variables during a simulation
• propel/self - model self-propelled particles
• property/atom - add customized per-atom values
• python/invoke - call a Python function during a simulation
• python/move - call a Python function during a simulation run
• qbmsst - quantum bath multi-scale shock technique time integrator
• qeq/comb - charge equilibration for COMB potential
• qeq/dynamic - charge equilibration via dynamic method

16.49. fix command 735

LAMMPS Documentation, Release stable 29Sep2021

• qeq/fire - charge equilibration via FIRE minimizer

• qeq/point - charge equilibration via point method
• qeq/reaxff - charge equilibration for ReaxFF potential
• qeq/shielded - charge equilibration via shielded method
• qeq/slater - charge equilibration via Slater method
• qmmm - functionality to enable a quantum mechanics/molecular mechanics coupling
• qtb - implement quantum thermal bath scheme
• rattle - RATTLE constraints on bonds and/or angles
• reaxff/bonds - write out ReaxFF bond information
• reaxff/species - write out ReaxFF molecule information
• recenter - constrain the center-of-mass position of a group of atoms
• restrain - constrain a bond, angle, dihedral
• rhok - add bias potential for long-range ordered systems
• rigid - constrain one or more clusters of atoms to move as a rigid body with NVE integration
• rigid/meso - constrain clusters of mesoscopic SPH/SDPD particles to move as a rigid body
• rigid/nph - constrain one or more clusters of atoms to move as a rigid body with NPH integration
• rigid/nph/small - constrain many small clusters of atoms to move as a rigid body with NPH integration
• rigid/npt - constrain one or more clusters of atoms to move as a rigid body with NPT integration
• rigid/npt/small - constrain many small clusters of atoms to move as a rigid body with NPT integration
• rigid/nve - constrain one or more clusters of atoms to move as a rigid body with alternate NVE integration
• rigid/nve/small - constrain many small clusters of atoms to move as a rigid body with alternate NVE integration
• rigid/nvt - constrain one or more clusters of atoms to move as a rigid body with NVT integration
• rigid/nvt/small - constrain many small clusters of atoms to move as a rigid body with NVT integration
• rigid/small - constrain many small clusters of atoms to move as a rigid body with NVE integration
• rx -
• saed/vtk -
• setforce - set the force on each atom
• setforce/spin - set magnetic precession vectors on each atom
• shake - SHAKE constraints on bonds and/or angles
• shardlow - integration of DPD equations of motion using the Shardlow splitting
• smd - applied a steered MD force to a group
• smd/adjust_dt -
• smd/integrate_tlsph -
• smd/integrate_ulsph -
• smd/move_tri_surf -
• smd/setvel -

736 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• smd/wall_surface -
• sph - time integration for SPH/DPDE particles
• sph/stationary -
• spring - apply harmonic spring force to group of atoms
• spring/chunk - apply harmonic spring force to each chunk of atoms
• spring/rg - spring on radius of gyration of group of atoms
• spring/self - spring from each atom to its origin
• srd - stochastic rotation dynamics (SRD)
• store/force - store force on each atom
• store/state - store attributes for each atom
• tdpd/source -
• temp/berendsen - temperature control by Berendsen thermostat
• temp/csld - canonical sampling thermostat with Langevin dynamics
• temp/csvr - canonical sampling thermostat with Hamiltonian dynamics
• temp/rescale - temperature control by velocity rescaling
• temp/rescale/eff - temperature control by velocity rescaling in the electron force field model
• tfmc - perform force-bias Monte Carlo with time-stamped method
• tgnvt/drude - NVT time integration for Drude polarizable model via temperature-grouped Nose-Hoover
• tgnpt/drude - NPT time integration for Drude polarizable model via temperature-grouped Nose-Hoover
• thermal/conductivity - Muller-Plathe kinetic energy exchange for thermal conductivity calculation
• ti/spring -
• tmd - guide a group of atoms to a new configuration
• ttm - two-temperature model for electronic/atomic coupling (replicated grid)
• ttm/grid - two-temperature model for electronic/atomic coupling (distributed grid)
• ttm/mod - enhanced two-temperature model with additional options
• tune/kspace - auto-tune KSpace parameters
• vector - accumulate a global vector every N timesteps
• viscosity - Muller-Plathe momentum exchange for viscosity calculation
• viscous - viscous damping for granular simulations
• wall/body/polygon -
• wall/body/polyhedron -
• wall/colloid - Lennard-Jones wall interacting with finite-size particles
• wall/ees - wall for ellipsoidal particles
• wall/gran - frictional wall(s) for granular simulations
• wall/gran/region -
• wall/harmonic - harmonic spring wall

16.49. fix command 737

LAMMPS Documentation, Release stable 29Sep2021

• wall/lj1043 - Lennard-Jones 10-4-3 wall

• wall/lj126 - Lennard-Jones 12-6 wall
• wall/lj93 - Lennard-Jones 9-3 wall
• wall/morse - Morse potential wall
• wall/piston - moving reflective piston wall
• wall/reflect - reflecting wall(s)
• wall/reflect/stochastic - reflecting wall(s) with finite temperature
• wall/region - use region surface as wall
• wall/region/ees - use region surface as wall for ellipsoidal particles
• wall/srd - slip/no-slip wall for SRD particles
• widom - Widom insertions of atoms or molecules

16.49.4 Restrictions

Some fix styles are part of specific packages. They are only enabled if LAMMPS was built with that package. See the
Build package page for more info. The doc pages for individual fixes tell if it is part of a package.

16.49.5 Related commands

unfix, fix_modify

16.49.6 Default

none

16.50 fix_modify command

16.50.1 Syntax

fix_modify fix-ID keyword value ...

• fix-ID = ID of the fix to modify

• one or more keyword/value pairs may be appended
• keyword = temp or press or energy or virial or respa or dynamic/dof or bodyforces
temp value = compute ID that calculates a temperature
press value = compute ID that calculates a pressure
energy value = yes or no
virial value = yes or no
respa value = 1 to max respa level or 0 (for outermost level)
dynamic/dof value = yes or no
yes/no = do or do not re-compute the number of degrees of freedom (DOF)␣
,→contributing to the temperature

bodyforces value = early or late

738 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

early/late = compute rigid-body forces/torques early or late in the timestep

16.50.2 Examples

fix_modify 3 temp myTemp press myPress

fix_modify 1 energy yes
fix_modify tether respa 2

16.50.3 Description

Modify one or more parameters of a previously defined fix. Only specific fix styles support specific parameters. See
the doc pages for individual fix commands for info on which ones support which fix_modify parameters.
The temp keyword is used to determine how a fix computes temperature. The specified compute ID must have been
previously defined by the user via the compute command and it must be a style of compute that calculates a temperature.
All fixes that compute temperatures define their own compute by default, as described in their documentation. Thus
this option allows the user to override the default method for computing T.
The press keyword is used to determine how a fix computes pressure. The specified compute ID must have been
previously defined by the user via the compute command and it must be a style of compute that calculates a pressure.
All fixes that compute pressures define their own compute by default, as described in their documentation. Thus this
option allows the user to override the default method for computing P.
The energy keyword can be used with fixes that support it, which is explained at the bottom of their doc page. Energy
yes will add a contribution to the potential energy of the system. More specifically, the fix’s global or per-atom energy
is included in the calculation performed by the compute pe or compute pe/atom commands. The former is what is used
the thermo_style command for output of any quantity that includes the global potential energy of the system. Note that
the compute pe and compute pe/atom commands also have an option to include or exclude the contribution from fixes.
For fixes that tally a global energy, it can also be printed with thermodynamic output by using the keyword f_ID in the
thermo_style custom command, where ID is the fix-ID of the appropriate fix.

Note: If you are performing an energy minimization with one of these fixes and want the energy and forces it produces
to be part of the optimization criteria, you must specify the energy yes setting.

Note: For most fixes that support the energy keyword, the default setting is no. For a few it is yes, when a user would
expect that to be the case. The page of each fix gives the default.

The virial keyword can be used with fixes that support it, which is explained at the bottom of their doc page. Virial
yes will add a contribution to the virial of the system. More specifically, the fix’s global or per-atom virial is included
in the calculation performed by the compute pressure or compute stress/atom commands. The former is what is used
the thermo_style command for output of any quantity that includes the global pressure of the system. Note that the
compute pressure and compute stress/atom commands also have an option to include or exclude the contribution from
fixes.

Note: If you are performing an energy minimization with box relaxation and one of these fixes and want the virial
contribution of the fix to be part of the optimization criteria, you must specify the virial yes setting.

16.50. fix_modify command 739

LAMMPS Documentation, Release stable 29Sep2021

Note: For most fixes that support the virial keyword, the default setting is no. For a few it is yes, when a user would
expect that to be the case. The page of each fix gives the default.

For fixes that set or modify forces, it may be possible to select at which r-RESPA level the fix operates via the respa
keyword. The RESPA level at which the fix is active can be selected. This is a number ranging from 1 to the number
of levels. If the RESPA level is larger than the current maximum, the outermost level will be used, which is also the
default setting. This default can be restored using a value of 0 for the RESPA level. The affected fix has to be enabled to
support this feature; if not, fix_modify will report an error. Active fixes with a custom RESPA level setting are reported
with their specified level at the beginning of a r-RESPA run.
The dynamic/dof keyword determines whether the number of atoms N in the fix group and their associated degrees
of freedom are re-computed each time a temperature is computed. Only fix styles that calculate their own internal
temperature use this option. Currently this is only the fix rigid/nvt/small and fix rigid/npt/small commands for the
purpose of thermostatting rigid body translation and rotation. By default, N and their DOF are assumed to be constant.
If you are adding atoms or molecules to the system (see the fix pour, fix deposit, and fix gcmc commands) or expect
atoms or molecules to be lost (e.g. due to exiting the simulation box or via fix evaporate), then this option should be
used to insure the temperature is correctly normalized.

Note: Other thermostatting fixes, such as fix nvt, do not use the dynamic/dof keyword because they use a temperature
compute to calculate temperature. See the compute_modify dynamic/dof command for a similar way to insure correct
temperature normalization for those thermostats.

The bodyforces keyword determines whether the forces and torques acting on rigid bodies are computed early at the
post-force stage of each timestep (right after per-atom forces have been computed and communicated among proces-
sors), or late at the final-integrate stage of each timestep (after any other fixes have finished their post-force tasks). Only
the rigid-body integration fixes use this option, which includes fix rigid and fix rigid/small, and their variants, and also
fix poems.
The default is late. If there are other fixes that add forces to individual atoms, then the rigid-body constraints will
include these forces when time-integrating the rigid bodies. If early is specified, then new fixes can be written that use
or modify the per-body force and torque, before time-integration of the rigid bodies occurs. Note however this has the
side effect, that fixes such as fix addforce, fix setforce, fix spring, which add forces to individual atoms will have no
effect on the motion of the rigid bodies if they are specified in the input script after the fix rigid command. LAMMPS
will give a warning if that is the case.

16.50.4 Restrictions

none

16.50.5 Related commands

fix, compute temp, compute pressure, thermo_style

740 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.50.6 Default

The option defaults are temp = ID defined by fix, press = ID defined by fix, energy = no, virial = different for each fix
style, respa = 0, bodyforce = late.

16.51 group command

16.51.1 Syntax

group ID style args

• ID = user-defined name of the group

• style = delete or clear or empty or region or type or id or molecule or variable or include or subtract or union or
intersect or dynamic or static
delete = no args
clear = no args
empty = no args
region args = region-ID
type or id or molecule
args = list of one or more atom types, atom IDs, or molecule IDs
any entry in list can be a sequence formatted as A:B or A:B:C where
A = starting index, B = ending index,
C = increment between indices, 1 if not specified
args = logical value
logical = "<" or "<=" or ">" or ">=" or "==" or "!="
value = an atom type or atom ID or molecule ID (depending on style)
args = logical value1 value2
logical = "<>"
value1,value2 = atom types or atom IDs or molecule IDs (depending on style)
variable args = variable-name
include args = molecule
molecule = add atoms to group with same molecule ID as atoms already in group
subtract args = two or more group IDs
union args = one or more group IDs
intersect args = two or more group IDs
dynamic args = parent-ID keyword value ...
one or more keyword/value pairs may be appended
keyword = region or var or property or every
region value = region-ID
var value = name of variable
property value = name of custom integer or floating point vector
every value = N = update group every this many timesteps
static = no args

16.51. group command 741

LAMMPS Documentation, Release stable 29Sep2021

16.51.2 Examples

group edge region regstrip

group water type 3 4
group sub id 10 25 50
group sub id 10 25 50 500:1000
group sub id 100:10000:10
group sub id <= 150
group polyA molecule <> 50 250
group hienergy variable eng
group hienergy include molecule
group boundary subtract all a2 a3
group boundary union lower upper
group boundary intersect upper flow
group boundary delete
group mine dynamic all region myRegion every 100

16.51.3 Description

Identify a collection of atoms as belonging to a group. The group ID can then be used in other commands such as fix,
compute, dump, or velocity to act on those atoms together.
If the group ID already exists, the group command adds the specified atoms to the group.

Note: By default groups are static, meaning the atoms are permanently assigned to the group. For example, if the
region style is used to assign atoms to a group, the atoms will remain in the group even if they later move out of the
region. As explained below, the dynamic style can be used to make a group dynamic so that a periodic determination
is made as to which atoms are in the group. Since many LAMMPS commands operate on groups of atoms, you should
think carefully about whether making a group dynamic makes sense for your model.

A group with the ID all is predefined. All atoms belong to this group. This group cannot be deleted, or made dynamic.
The delete style removes the named group and un-assigns all atoms that were assigned to that group. Since there is a
restriction (see below) that no more than 32 groups can be defined at any time, the delete style allows you to remove
groups that are no longer needed, so that more can be specified. You cannot delete a group if it has been used to define
a current fix or compute or dump.
The clear style un-assigns all atoms that were assigned to that group. This may be dangerous to do during a simulation
run, e.g. using the run every command if a fix or compute or other operation expects the atoms in the group to remain
constant, but LAMMPS does not check for this.
The empty style creates an empty group, which is useful for commands like fix gcmc or with complex scripts that add
atoms to a group.
The region style puts all atoms in the region volume into the group. Note that this is a static one-time assignment. The
atoms remain assigned (or not assigned) to the group even in they later move out of the region volume.
The type, id, and molecule styles put all atoms with the specified atom types, atom IDs, or molecule IDs into the group.
These 3 styles can use arguments specified in one of two formats.
The first format is a list of values (types or IDs). For example, the second command in the examples above puts all
atoms of type 3 or 4 into the group named water. Each entry in the list can be a colon-separated sequence A:B or
A:B:C, as in two of the examples above. A “sequence” generates a sequence of values (types or IDs), with an optional
increment. The first example with 500:1000 has the default increment of 1 and would add all atom IDs from 500 to
1000 (inclusive) to the group sub, along with 10,25,50 since they also appear in the list of values. The second example

742 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

with 100:10000:10 uses an increment of 10 and would thus would add atoms IDs 100,110,120, . . . 9990,10000 to
the group sub.
The second format is a logical followed by one or two values (type or ID). The 7 valid logicals are listed above. All
the logicals except <> take a single argument. The third example above adds all atoms with IDs from 1 to 150 to the
group named sub. The logical <> means “between” and takes 2 arguments. The fourth example above adds all atoms
belonging to molecules with IDs from 50 to 250 (inclusive) to the group named polyA.
The variable style evaluates a variable to determine which atoms to add to the group. It must be an atom-style variable
previously defined in the input script. If the variable evaluates to a non-zero value for a particular atom, then that atom
is added to the specified group.
Atom-style variables can specify formulas that include thermodynamic quantities, per-atom values such as atom coor-
dinates, or per-atom quantities calculated by computes, fixes, or other variables. They can also include Boolean logic
where 2 numeric values are compared to yield a 1 or 0 (effectively a true or false). Thus using the variable style, is a
general way to flag specific atoms to include or exclude from a group.
For example, these lines define a variable “eatom” that calculates the potential energy of each atom and includes it in
the group if its potential energy is above the threshold value -3.0.

compute 1 all pe/atom

compute 2 all reduce sum c_1
thermo_style custom step temp pe c_2
run 0

variable eatom atom "c_1 > -3.0"

group hienergy variable eatom

Note that these lines

compute 2 all reduce sum c_1

thermo_style custom step temp pe c_2
run 0

are necessary to insure that the “eatom” variable is current when the group command invokes it. Because the eatom
variable computes the per-atom energy via the pe/atom compute, it will only be current if a run has been performed
which evaluated pairwise energies, and the pe/atom compute was actually invoked during the run. Printing the ther-
modynamic info for compute 2 insures that this is the case, since it sums the pe/atom compute values (in the reduce
compute) to output them to the screen. See the “Variable Accuracy” section of the variable page for more details on
insuring that variables are current when they are evaluated between runs.
The include style with its arg molecule adds atoms to a group that have the same molecule ID as atoms already in the
group. The molecule ID = 0 is ignored in this operation, since it is assumed to flag isolated atoms that are not part of
molecules. An example of where this operation is useful is if the region style has been used previously to add atoms
to a group that are within a geometric region. If molecules straddle the region boundary, then atoms outside the region
that are part of molecules with atoms inside the region will not be in the group. Using the group command a second
time with include molecule will add those atoms that are outside the region to the group.

Note: The include molecule operation is relatively expensive in a parallel sense. This is because it requires communi-
cation of relevant molecule IDs between all the processors and each processor to loop over its atoms once per processor,
to compare its atoms to the list of molecule IDs from every other processor. Hence it scales as N, rather than N/P as
most of the group operations do, where N is the number of atoms, and P is the number of processors.

The subtract style takes a list of two or more existing group names as arguments. All atoms that belong to the first
group, but not to any of the other groups are added to the specified group.

16.51. group command 743

LAMMPS Documentation, Release stable 29Sep2021

The union style takes a list of one or more existing group names as arguments. All atoms that belong to any of the listed
groups are added to the specified group.
The intersect style takes a list of two or more existing group names as arguments. Atoms that belong to every one of
the listed groups are added to the specified group.

The dynamic style flags an existing or new group as dynamic. This means atoms will be (re)assigned to the group
periodically as a simulation runs. This is in contrast to static groups where atoms are permanently assigned to the
group. The way the assignment occurs is as follows. Only atoms in the group specified as the parent group via the
parent-ID are assigned to the dynamic group before the following conditions are applied.
If the region keyword is used, atoms not in the specified region are removed from the dynamic group.
If the var keyword is used, the variable name must be an atom-style or atomfile-style variable. The variable is evaluated
and atoms whose per-atom values are 0.0, are removed from the dynamic group.
If the property keyword is used, the name refers to a custom integer or floating point per-atom vector defined via the
fix property/atom command. This means the values in the vector can be read as part of a data file with the read_data
command or specified with the set command. Or accessed and changed via the library interface to LAMMPS, or by
styles you add to LAMMPS (pair, fix, compute, etc) which access the custom vector and modify its values. Which
means the values can be modified between or during simulations. Atoms whose values in the custom vector are zero
are removed from the dynamic group. Note that the name of the custom per-atom vector is specified just as name, not as
i_name or d_name as it is for other commands that use different kinds of custom atom vectors or arrays as arguments.
The assignment of atoms to a dynamic group is done at the beginning of each run and on every timestep that is a
multiple of N, which is the argument for the every keyword (N = 1 is the default). For an energy minimization, via the
minimize command, an assignment is made at the beginning of the minimization, but not during the iterations of the
minimizer.
The point in the timestep at which atoms are assigned to a dynamic group is after the initial stage of velocity Verlet time
integration has been performed, and before neighbor lists or forces are computed. This is the point in the timestep where
atom positions have just changed due to the time integration, so the region criterion should be accurate, if applied.

Note: If the region keyword is used to determine what atoms are in the dynamic group, atoms can move outside of the
simulation box between reneighboring events. Thus if you want to include all atoms on the left side of the simulation
box, you probably want to set the left boundary of the region to be outside the simulation box by some reasonable
amount (e.g. up to the cutoff of the potential), else they may be excluded from the dynamic region.

Here is an example of using a dynamic group to shrink the set of atoms being integrated by using a spherical region
with a variable radius (shrinking from 18 to 5 over the course of the run). This could be used to model a quench of the
system, freezing atoms outside the shrinking sphere, then converting the remaining atoms to a static group and running
further.

variable nsteps equal 5000

variable rad equal 18-(step/v_nsteps)*(18-5)
region ss sphere 20 20 0 v_rad
group mobile dynamic all region ss
fix 1 mobile nve
run ${nsteps}
group mobile static
run ${nsteps}

Note: All fixes and computes take a group ID as an argument, but they do not all allow for use of a dynamic group.
If you get an error message that this is not allowed, but feel that it should be for the fix or compute in question, then

744 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

please post your reasoning to the LAMMPS mail list and we can change it.

The static style removes the setting for a dynamic group, converting it to a static group (the default). The atoms in the
static group are those currently in the dynamic group.

16.51.4 Restrictions

There can be no more than 32 groups defined at one time, including “all”.
The parent group of a dynamic group cannot itself be a dynamic group.

16.51.5 Related commands

dump, fix, region, velocity

16.51.6 Default

All atoms belong to the “all” group.

16.52 group2ndx command

16.53 ndx2group command

16.53.1 Syntax

group2ndx file group-ID ...

ndx2group file group-ID ...

• file = name of index file to write out or read in

• zero or more group IDs may be appended

16.53.2 Examples

group2ndx allindex.ndx
group2ndx someindex.ndx upper lower mobile
ndx2group someindex.ndx
ndx2group someindex.ndx mobile

16.52. group2ndx command 745

LAMMPS Documentation, Release stable 29Sep2021

16.53.3 Description

Write or read a Gromacs style index file in text format that associates atom IDs with the corresponding group definitions.
This index file can be used with in combination with Gromacs analysis tools or to import group definitions into the fix
colvars input file. It can also be used to save and restore group definitions for static groups.
The group2ndx command will write group definitions to an index file. Without specifying any group IDs, all groups
will be written to the index file. When specifying group IDs, only those groups will be written to the index file. In
order to follow the Gromacs conventions, the group all will be renamed to System in the index file.
The ndx2group command will create of update group definitions from those stored in an index file. Without specifying
any group IDs, all groups except System will be read from the index file and the corresponding groups recreated. If a
group of the same name already exists, it will be completely reset. When specifying group IDs, those groups, if present,
will be read from the index file and restored.

16.53.4 Restrictions

This command requires that atoms have atom IDs, since this is the information that is written to the index file.
These commands are part of the COLVARS package. They are only enabled if LAMMPS was built with that package.
See the Build package page for more info.

16.53.5 Related commands

group, dump, fix colvars

16.53.6 Default

none

16.54 hyper command

16.54.1 Syntax

hyper N Nevent fix-ID compute-ID keyword values ...

• N = # of timesteps to run
• Nevent = check for events every this many steps
• fix-ID = ID of a fix that applies a global or local bias potential, can be NULL
• compute-ID = ID of a compute that identifies when an event has occurred
• zero or more keyword/value pairs may be appended
• keyword = min or dump or rebond
min values = etol ftol maxiter maxeval
etol = stopping tolerance for energy, used in quenching
ftol = stopping tolerance for force, used in quenching
maxiter = max iterations of minimize, used in quenching

746 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

maxeval = max number of force/energy evaluations, used in quenching

dump value = dump-ID
dump-ID = ID of dump to trigger whenever an event takes place
rebond value = Nrebond
Nrebond = frequency at which to reset bonds, even if no event has occurred

16.54.2 Examples

compute event all event/displace 1.0

fix HG mobile hyper/global 3.0 0.3 0.4 800.0
hyper 5000 100 HG event min 1.0e-6 1.0e-6 100 100 dump 1 dump 5

16.54.3 Description

Run a bond-boost hyperdynamics (HD) simulation where time is accelerated by application of a bias potential to one
or more pairs of nearby atoms in the system. This command can be used to run both global and local hyperdynamics.
In global HD a single bond within the system is biased on each timestep. In local HD multiple bonds (separated by a
sufficient distance) can be biased simultaneously at each timestep. In the bond-boost hyperdynamics context, a “bond”
is not a covalent bond between a pair of atoms in a molecule. Rather it is simply a pair of nearby atoms as discussed
below.
Both global and local HD are described in (Voter2013) by Art Voter and collaborators. Similar to parallel replica dy-
namics (PRD), global and local HD are methods for performing accelerated dynamics that are suitable for infrequent-
event systems that obey first-order kinetics. A good overview of accelerated dynamics methods (AMD) for such systems
in given in (Voter2002) from the same group. To quote from the review paper: “The dynamical evolution is charac-
terized by vibrational excursions within a potential basin, punctuated by occasional transitions between basins. The
transition probability is characterized by p(t) = k*exp(-kt) where k is the rate constant.”
Both HD and PRD produce a time-accurate trajectory that effectively extends the timescale over which a system can
be simulated, but they do it differently. HD uses a single replica of the system and accelerates time by biasing the
interaction potential in a manner such that each timestep is effectively longer. PRD creates Nr replicas of the system
and runs dynamics on each independently with a normal unbiased potential until an event occurs in one of the replicas.
The time between events is reduced by a factor of Nr replicas. For both methods, per CPU second, more physical time
elapses and more events occur. See the prd page for more info about PRD.
An HD run has several stages, which are repeated each time an event occurs, as explained below. The logic for an HD
run is as follows:

quench
create initial list of bonds

while (time remains):

run dynamics for Nevent steps
quench
check for an event
if event occurred: reset list of bonds
restore pre-quench state

The list of bonds is the list of atom pairs of atoms that are within a short cutoff distance of each other after the system
energy is minimized (quenched). This list is created and reset by a fix hyper/global or fix hyper/local command specified
as fix-ID. At every dynamics timestep, the same fix selects one of more bonds to apply a bias potential to.

16.54. hyper command 747

LAMMPS Documentation, Release stable 29Sep2021

Note: The style of fix associated with the specified fix-ID determines whether you are running the global versus local
hyperdynamics algorithm.

Dynamics (with the bias potential) is run continuously, stopping every Nevent steps to check if a transition event has
occurred. The specified N for total steps must be a multiple of Nevent. check is performed by quenching the system
and comparing the resulting atom coordinates to the coordinates from the previous basin.
A quench is an energy minimization and is performed by whichever algorithm has been defined by the min_style
command. Minimization parameters may be set via the min_modify command and by the min keyword of the hyper
command. The latter are the settings that would be used with the minimize command. Note that typically, you do
not need to perform a highly-converged minimization to detect a transition event, though you may need to in order to
prevent a set of atoms in the system from relaxing to a saddle point.
The event check is performed by a compute with the specified compute-ID. Currently there is only one compute that
works with the hyper command, which is the compute event/displace command. Other event-checking computes may
be added. Compute event/displace checks whether any atom in the compute group has moved further than a specified
threshold distance. If so, an event has occurred.
If this happens, the list of bonds is reset, since some bond pairs are likely now too far apart, and new pairs are likely
close enough to be considered a bond. The pre-quenched state of the system (coordinates and velocities) is restored,
and dynamics continue.
At the end of the hyper run, a variety of statistics are output to the screen and logfile. These include info relevant to
both global and local hyperdynamics, such as the number of events and the elapsed hyper time (accelerated time), And
it includes info specific to one or the other, depending on which style of fix was specified by fix-ID.

The optional keywords operate as follows.

As explained above, the min keyword can be used to specify parameters for the quench. Their meaning is the same as
for the minimize command
The dump keyword can be used to trigger a specific dump command with the specified dump-ID to output a snapshot
each time an event is detected. It can be specified multiple times with different dump-ID values, as in the example
above. These snapshots will be for the quenched state of the system on a timestep that is a multiple of Nevent, i.e. a
timestep after the event has occurred. Note that any dump command in the input script will also output snapshots at
whatever timestep interval it defines via its N argument; see the dump command for details. This means if you only
want a particular dump to output snapshots when events are detected, you should specify its N as a value larger than
the length of the hyperdynamics run.
As in the code logic above, the bond list is normally only reset when an event occurs. The rebond keyword will force
a reset of the bond list every Nrebond steps, even if an event has not occurred. Nrebond must be a multiple of Nevent.
This can be useful to check if more frequent resets alter event statistics, perhaps because the parameters chosen for
defining what is a bond and what is an event are producing bad dynamics in the presence of the bias potential.

748 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.54.4 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package doc page
for more info.

16.54.5 Related commands

fix hyper/global, fix hyper/local, compute event/displace, prd

16.54.6 Default

The option defaults are min = 0.1 0.1 40 50 and time = steps.

(Voter2013) S. Y. Kim, D. Perez, A. F. Voter, J Chem Phys, 139, 144110 (2013).

(Voter2002) Voter, Montalenti, Germann, Annual Review of Materials Research 32, 321 (2002).

16.55 if command

16.55.1 Syntax

if boolean then t1 t2 ... elif boolean f1 f2 ... elif boolean f1 f2 ... else e1 e2 ...

• boolean = a Boolean expression evaluated as TRUE or FALSE (see below)

• then = required word
• t1,t2,. . . ,tN = one or more LAMMPS commands to execute if condition is met, each enclosed in quotes
• elif = optional word, can appear multiple times
• f1,f2,. . . ,fN = one or more LAMMPS commands to execute if elif condition is met, each enclosed in quotes
(optional arguments)
• else = optional argument
• e1,e2,. . . ,eN = one or more LAMMPS commands to execute if no condition is met, each enclosed in quotes
(optional arguments)

16.55.2 Examples

if "${steps} > 1000" then quit

if "${myString} == a10" then quit
if "$x <= $y" then "print X is smaller = $x" else "print Y is smaller = $y"
if "(${eng} > 0.0) || ($n < 1000)" then &
"timestep 0.005" &
elif $n<10000 &
"timestep 0.01" &
else &
"timestep 0.02" &
(continues on next page)

16.55. if command 749

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

"print 'Max step reached'"
if "${eng} > ${eng_previous}" then "jump file1" else "jump file2"

16.55.3 Description

This command provides an if-then-else capability within an input script. A Boolean expression is evaluated and the
result is TRUE or FALSE. Note that as in the examples above, the expression can contain variables, as defined by the
variable command, which will be evaluated as part of the expression. Thus a user-defined formula that reflects the
current state of the simulation can be used to issue one or more new commands.
If the result of the Boolean expression is TRUE, then one or more commands (t1, t2, . . . , tN) are executed. If it is FALSE,
then Boolean expressions associated with successive elif keywords are evaluated until one is found to be true, in which
case its commands (f1, f2, . . . , fN) are executed. If no Boolean expression is TRUE, then the commands associated with
the else keyword, namely (e1, e2, . . . , eN), are executed. The elif and else keywords and their associated commands
are optional. If they are not specified and the initial Boolean expression is FALSE, then no commands are executed.
The syntax for Boolean expressions is described below.
Each command (t1, f1, e1, etc) can be any valid LAMMPS input script command. If the command is more than one
word, it must enclosed in quotes, so it will be treated as a single argument, as in the examples above.

Note: If a command itself requires a quoted argument (e.g. a print command), then double and single quotes can be
used and nested in the usual manner, as in the examples above and below. The Commands parse page has more details
on using quotes in arguments. Only one of level of nesting is allowed, but that should be sufficient for most use cases.

Note that by using the line continuation character “&”, the if command can be spread across many lines, though it is
still a single command:

if "$a < $b" then &

"print 'Minimum value = $a'" &
"run 1000" &
else &
'print "Minimum value = $b"' &
"minimize 0.001 0.001 1000 10000"

Note that if one of the commands to execute is quit, as in the first example above, then executing the command will
cause LAMMPS to halt.
Note that by jumping to a label in the same input script, the if command can be used to break out of a loop. See the
variable delete command for info on how to delete the associated loop variable, so that it can be re-used later in the
input script.
Here is an example of a loop which checks every 1000 steps if the system temperature has reached a certain value, and
if so, breaks out of the loop to finish the run. Note that any variable could be checked, so long as it is current on the
timestep when the run completes. As explained on the variable doc page, this can be insured by including the variable
in thermodynamic output.

variable myTemp equal temp

label loop
variable a loop 1000
run 1000
if "${myTemp} < 300.0" then "jump SELF break"
(continues on next page)

750 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

next a
jump SELF loop
label break
print "ALL DONE"

Here is an example of a double loop which uses the if and jump commands to break out of the inner loop when a
condition is met, then continues iterating through the outer loop.

label loopa
variable a loop 5
label loopb
variable b loop 5
print "A,B = $a,$b"
run 10000
if "$b > 2" then "jump SELF break"
next b
jump in.script loopb
label break
variable b delete
next a
jump SELF loopa

The Boolean expressions for the if and elif keywords have a C-like syntax. Note that each expression is a single argument
within the if command. Thus if you want to include spaces in the expression for clarity, you must enclose the entire
expression in quotes.
An expression is built out of numbers (which start with a digit or period or minus sign) or strings (which start with a
letter and can contain alphanumeric characters, underscores, or forward slashes):

0.2, 100, 1.0e20, -15.4, ...

InP, myString, a123, ab_23_cd, lj/cut, ...

and Boolean operators:

A == B, A != B, A < B, A <= B, A > B, A >= B, A && B, A || B, A |^ B, !A
Each A and B is a number or string or a variable reference like $a or ${abc}, or A or B can be another Boolean
expression.
If a variable is used it can produce a number when evaluated, like an equal-style variable. Or it can produce a string,
like an index-style variable. For an individual Boolean operator, A and B must both be numbers or must both be strings.
You cannot compare a number to a string.
Expressions are evaluated left to right and have the usual C-style precedence: the unary logical NOT operator “!” has the
highest precedence, the 4 relational operators “<”, “<=”, “>”, and “>=” are next; the two remaining relational operators
“==” and “!=” are next; then the logical AND operator “&&”; and finally the logical OR operator “||” and logical XOR
(exclusive or) operator “|^” have the lowest precedence. Parenthesis can be used to group one or more portions of an
expression and/or enforce a different order of evaluation than what would occur with the default precedence.
When the 6 relational operators (first 6 in list above) compare 2 numbers, they return either a 1.0 or 0.0 depending on
whether the relationship between A and B is TRUE or FALSE. When the 6 relational operators compare 2 strings, they
also return a 1.0 or 0.0 for TRUE or FALSE, but the comparison is done by the C function strcmp().
When the 3 logical operators (last 3 in list above) compare 2 numbers, they also return either a 1.0 or 0.0 depending on
whether the relationship between A and B is TRUE or FALSE (or just A). The logical AND operator will return 1.0 if

16.55. if command 751

LAMMPS Documentation, Release stable 29Sep2021

both its arguments are non-zero, else it returns 0.0. The logical OR operator will return 1.0 if either of its arguments
is non-zero, else it returns 0.0. The logical XOR operator will return 1.0 if one of its arguments is zero and the other
non-zero, else it returns 0.0. The logical NOT operator returns 1.0 if its argument is 0.0, else it returns 0.0. The 3
logical operators can only be used to operate on numbers, not on strings.
The overall Boolean expression produces a TRUE result if the result is non-zero. If the result is zero, the expression
result is FALSE.

16.55.4 Restrictions

none

16.55.5 Related commands

variable, print

16.55.6 Default

none

16.56 improper_coeff command

16.56.1 Syntax

improper_coeff N args

• N = improper type (see asterisk form below)

• args = coefficients for one or more improper types

16.56.2 Examples

improper_coeff 1 300.0 0.0

improper_coeff * 80.2 -1 2
improper_coeff *4 80.2 -1 2

16.56.3 Description

Specify the improper force field coefficients for one or more improper types. The number and meaning of the coef-
ficients depends on the improper style. Improper coefficients can also be set in the data file read by the read_data
command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can be used, as in the first example above. Or a
wild-card asterisk can be used to set the coefficients for multiple improper types. This takes the form “*” or “*n” or
“n*” or “m*n”. If N = the number of improper types, then an asterisk with no numeric values means all types from 1 to
N. A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive).
A middle asterisk means all types from m to n (inclusive).

752 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Note that using an improper_coeff command can override a previous setting for the same improper type. For example,
these commands set the coeffs for all improper types, then overwrite the coeffs for just improper type 2:

improper_coeff * 300.0 0.0

improper_coeff 2 50.0 0.0

A line in a data file that specifies improper coefficients uses the exact same format as the arguments of the im-
proper_coeff command in an input script, except that wild-card asterisks should not be used since coefficients for
all N types must be listed in the file. For example, under the “Improper Coeffs” section of a data file, the line that
corresponds to the first example above would be listed as

1 300.0 0.0

The improper_style class2 is an exception to this rule, in that an additional argument is used in the input script to allow
specification of the cross-term coefficients. See its doc page for details.

The list of all improper styles defined in LAMMPS is given on the improper_style doc page. They are also listed in
more compact form on the Commands improper doc page.
On either of those pages, click on the style to display the formula it computes and its coefficients as specified by the
associated improper_coeff command.

16.56.4 Restrictions

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.
An improper style must be defined before any improper coefficients are set, either in the input script or in a data file.

16.56.5 Related commands

improper_style

16.56.6 Default

none

16.57 improper_style command

16.57.1 Syntax

improper_style style

• style = none or hybrid or class2 or cvff or harmonic

16.57. improper_style command 753

LAMMPS Documentation, Release stable 29Sep2021

16.57.2 Examples

improper_style harmonic
improper_style cvff
improper_style hybrid cvff harmonic

16.57.3 Description

Set the formula(s) LAMMPS uses to compute improper interactions between quadruplets of atoms, which remain in
force for the duration of the simulation. The list of improper quadruplets is read in by a read_data or read_restart
command from a data or restart file. Note that the ordering of the 4 atoms in an improper quadruplet determines the
definition of the improper angle used in the formula for each style. See the doc pages of individual styles for details.
Hybrid models where impropers are computed using different improper potentials can be setup using the hybrid im-
proper style.
The coefficients associated with an improper style can be specified in a data or restart file or via the improper_coeff
command.
All improper potentials store their coefficient data in binary restart files which means improper_style and im-
proper_coeff commands do not need to be re-specified in an input script that restarts a simulation. See the read_restart
command for details on how to do this. The one exception is that improper_style hybrid only stores the list of sub-styles
in the restart file; improper coefficients need to be re-specified.

Note: When both an improper and pair style is defined, the special_bonds command often needs to be used to turn off
(or weight) the pairwise interaction that would otherwise exist between a group of 4 bonded atoms.

Here is an alphabetic list of improper styles defined in LAMMPS. Click on the style to display the formula it computes
and coefficients specified by the associated improper_coeff command.
Click on the style to display the formula it computes, any additional arguments specified in the improper_style com-
mand, and coefficients specified by the associated improper_coeff command.
There are also additional accelerated pair styles included in the LAMMPS distribution for faster performance on CPUs,
GPUs, and KNLs. The individual style names on the Commands improper page are followed by one or more of
(g,i,k,o,t) to indicate which accelerated styles exist.
• none - turn off improper interactions
• zero - topology but no interactions
• hybrid - define multiple styles of improper interactions
• class2 - COMPASS (class 2) improper
• cossq - improper with a cosine squared term
• cvff - CVFF improper
• distance - improper based on distance between atom planes
• distharm - improper that is harmonic in the out-of-plane distance
• fourier - improper with multiple cosine terms
• harmonic - harmonic improper
• inversion/harmonic - harmonic improper with Wilson-Decius out-of-plane definition

754 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• ring - improper which prevents planar conformations

• umbrella - DREIDING improper
sqdistharm - improper that is harmonic in the square of the out-of-plane distance

16.57.4 Restrictions

Improper styles can only be set for atom_style choices that allow impropers to be defined.
Most improper styles are part of the MOLECULE package. They are only enabled if LAMMPS was built with that
package. See the Build package page for more info. The doc pages for individual improper potentials tell if it is part of
a package.

16.57.5 Related commands

improper_coeff

16.57.6 Default

improper_style none

16.58 include command

16.58.1 Syntax

include file

• file = filename of new input script to switch to

16.58.2 Examples

include newfile
include in.run2

16.58.3 Description

This command opens a new input script file and begins reading LAMMPS commands from that file. When the new file
is finished, the original file is returned to. Include files can be nested as deeply as desired. If input script A includes
script B, and B includes A, then LAMMPS could run for a long time.
If the filename is a variable (see the variable command), different processor partitions can run different input scripts.

16.58. include command 755

LAMMPS Documentation, Release stable 29Sep2021

16.58.4 Restrictions

none

16.58.5 Related commands

variable, jump

16.58.6 Default

none

16.59 info command

16.59.1 Syntax

info args

• args = one or more of the following keywords: out, all, system, memory, communication, computes, dumps, fixes,
groups, regions, variables, coeffs, styles, time, accelerator, or configuration
• out values = screen, log, append filename, overwrite filename
• styles values = all, angle, atom, bond, compute, command, dump, dihedral, fix, improper, integrate, kspace,
minimize, pair, region

16.59.2 Examples

info system
info groups computes variables
info all out log
info all out append info.txt
info styles all
info styles atom

16.59.3 Description

Print out information about the current internal state of the running LAMMPS process. This can be helpful when
debugging or validating complex input scripts. Several output categories are available and one or more output category
may be requested.
The out flag controls where the output is sent. It can only be sent to one target. By default this is the screen, if it is
active. The log argument selects the log file instead. With the append and overwrite option, followed by a filename,
the output is written to that file, which is either appended to or overwritten, respectively.
The all flag activates printing all categories listed below.
The configuration category prints some information about the LAMMPS version as well as architecture and OS it is
run on.

756 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The memory category prints some information about the current memory allocation of MPI rank 0 (this the amount of
dynamically allocated memory reported by LAMMPS classes). Where supported, also some OS specific information
about the size of the reserved memory pool size (this is where malloc() and the new operator request memory from)
and the maximum resident set size is reported (this is the maximum amount of physical memory occupied so far).
The system category prints a general system overview listing. This includes the unit style, atom style, number of atoms,
bonds, angles, dihedrals, and impropers and the number of the respective types, box dimensions and properties, force
computing styles and more.
The communication category prints a variety of information about communication and parallelization: the MPI library
version level, the number of MPI ranks and OpenMP threads, the communication style and layout, the processor grid
dimensions, ghost atom communication mode, cutoff, and related settings.
The computes category prints a list of all currently defined computes, their IDs and styles and groups they operate on.
The dumps category prints a list of all currently active dumps, their IDs, styles, filenames, groups, and dump frequen-
cies.
The fixes category prints a list of all currently defined fixes, their IDs and styles and groups they operate on.
The groups category prints a list of all currently defined groups.
The regions category prints a list of all currently defined regions, their IDs and styles and whether “inside” or “outside”
atoms are selected.
The variables category prints a list of all currently defined variables, their names, styles, definition and last computed
value, if available.
The coeffs category prints a list for each defined force style (pair, bond, angle, dihedral, improper) indicating which of
the corresponding coefficients have been set. This can be very helpful to debug error messages like “All pair coeffs are
not set”.
The accelerator category prints out information about compile time settings of included accelerator support for the
GPU, KOKKOS, INTEL, and OPENMP packages.
The styles category prints the list of styles available in the current LAMMPS binary. It supports one of the following
options to control which category of styles is printed out:
• all
• angle
• atom
• bond
• compute
• command
• dump
• dihedral
• fix
• improper
• integrate
• kspace
• minimize
• pair
• region

16.59. info command 757

LAMMPS Documentation, Release stable 29Sep2021

The time category prints the accumulated CPU and wall time for the process that writes output (usually MPI rank 0).

16.59.4 Restrictions

none

16.59.5 Related commands

print

16.59.6 Default

The out option has the default screen.

The styles option has the default all.

16.60 jump command

16.60.1 Syntax

jump file label

• file = filename of new input script to switch to

• label = optional label within file to jump to

16.60.2 Examples

jump newfile
jump in.run2 runloop
jump SELF runloop

16.60.3 Description

This command closes the current input script file, opens the file with the specified name, and begins reading LAMMPS
commands from that file. Unlike the include command, the original file is not returned to, although by using multiple
jump commands it is possible to chain from file to file or back to the original file.
If the word “SELF” is used for the filename, then the current input script is re-opened and read again.

Note: The SELF option is not guaranteed to work when the current input script is being read through stdin (standard
input), e.g.

lmp_g++ < in.script

since the SELF option invokes the C-library rewind() call, which may not be supported for stdin on some systems or
by some MPI implementations. This can be worked around by using the -in command-line switch, e.g.

758 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

lmp_g++ -in in.script

or by using the -var command-line switch to pass the script name as a variable to the input script. In the latter case, a
variable called “fname” could be used in place of SELF, e.g.
lmp_g++ -var fname in.script < in.script

The second argument to the jump command is optional. If specified, it is treated as a label and the new file is scanned
(without executing commands) until the label is found, and commands are executed from that point forward. This can
be used to loop over a portion of the input script, as in this example. These commands perform 10 runs, each of 10000
steps, and create 10 dump files named file.1, file.2, etc. The next command is used to exit the loop after 10 iterations.
When the “a” variable has been incremented for the tenth time, it will cause the next jump command to be skipped.

variable a loop 10
label loop
dump 1 all atom 100 file.$a
run 10000
undump 1
next a
jump in.lj loop

If the jump file argument is a variable, the jump command can be used to cause different processor partitions to run
different input scripts. In this example, LAMMPS is run on 40 processors, with 4 partitions of 10 procs each. An in.file
containing the example variable and jump command will cause each partition to run a different simulation.

mpirun -np 40 lmp_ibm -partition 4x10 -in in.file

variable f world script.1 script.2 script.3 script.4

jump $f

Here is an example of a loop which checks every 1000 steps if the system temperature has reached a certain value, and
if so, breaks out of the loop to finish the run. Note that any variable could be checked, so long as it is current on the
timestep when the run completes. As explained on the variable doc page, this can be insured by including the variable
in thermodynamic output.

variable myTemp equal temp

label loop
variable a loop 1000
run 1000
if "${myTemp} < 300.0" then "jump SELF break"
next a
jump SELF loop
label break
print "ALL DONE"

Here is an example of a double loop which uses the if and jump commands to break out of the inner loop when a
condition is met, then continues iterating through the outer loop.
label loopa
variable a loop 5
label loopb
variable b loop 5
print "A,B = $a,$b"
run 10000
(continues on next page)

16.60. jump command 759

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

if "$b > 2" then "jump SELF break"
next b
jump in.script loopb
label break
variable b delete
next a
jump SELF loopa

16.60.4 Restrictions

If you jump to a file and it does not contain the specified label, LAMMPS will come to the end of the file and exit.

16.60.5 Related commands

variable, include, label, next

16.60.6 Default

none

16.61 kim command

16.61.1 Syntax

kim sub-command args

• sub-command = init or interactions or query or param or property

• args = arguments used by a particular sub-command

16.61.2 Examples

kim init args

kim interactions args
kim query args
kim param args
kim property args

760 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.61.3 Description

The kim command includes a set of sub-commands that allow LAMMPS users to use interatomic models (IM) (po-
tentials and force fields) and their predictions for various physical properties archived in the Open Knowledgebase of
Interatomic Models (OpenKIM) repository.
Using OpenKIM provides LAMMPS users with immediate access to a large number of verified IMs and their predic-
tions. OpenKIM IMs have multiple benefits including reliability, reproducibility and convenience.
There are two types of IMs archived in OpenKIM:
1. The first type is called a KIM Portable Model (PM). A KIM PM is an independent computer implementation of
an IM written in one of the languages supported by KIM (C, C++, Fortran) that conforms to the KIM Application
Programming Interface (KIM API) Portable Model Interface (PMI) standard. A KIM PM will work seamlessly
with any simulation code that supports the KIM API/PMI standard (including LAMMPS; see complete list of
supported codes).
2. The second type is called a KIM Simulator Model (SM). A KIM SM is an IM that is implemented natively
within a simulation code (simulator) that supports the KIM API Simulator Model Interface (SMI); in this case
LAMMPS. A separate SM package is archived in OpenKIM for each parameterization of the IM, which includes
all of the necessary parameter files, LAMMPS commands, and metadata (supported species, units, etc.) needed
to run the IM in LAMMPS.
With these two IM types, OpenKIM can archive and test almost all IMs that can be used by LAMMPS. (It is easy to
contribute new IMs to OpenKIM, see the upload instructions.)
OpenKIM IMs are uniquely identified by a KIM ID. The extended KIM ID consists of a human-readable prefix identi-
fying the type of IM, authors, publication year, and supported species, separated by two underscores from the KIM ID
itself, which begins with an IM code (MO for a KIM Portable Model, and SM for a KIM Simulator Model) followed by
a unique 12-digit code and a 3-digit version identifier. By convention SM prefixes begin with Sim_ to readily identify
them.

SW_StillingerWeber_1985_Si__MO_405512056662_005
Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_001

Each OpenKIM IM has a dedicated “Model Page” on OpenKIM providing all the information on the IM including
a title, description, authorship and citation information, test and verification check results, visualizations of results, a
wiki with documentation and user comments, and access to raw files, and other information. The URL for the Model
Page is constructed from the extended KIM ID of the IM:

https://openkim.org/id/extended_KIM_ID

For example, for the Stillinger-Weber potential listed above the Model Page is located at:
https://openkim.org/id/SW_StillingerWeber_1985_Si__MO_405512056662_005
See the current list of KIM PMs and SMs archived in OpenKIM. This list is sorted by species and can be filtered to
display only IMs for certain species combinations.
See Obtaining KIM Models to learn how to install a pre-built binary of the OpenKIM Repository of Models.

Note: It is also possible to locally install IMs not archived in OpenKIM, in which case their names do not have to
conform to the KIM ID format.

16.61. kim command 761

LAMMPS Documentation, Release stable 29Sep2021

16.61.4 Using OpenKIM IMs with LAMMPS (kim init, kim interactions)

Two sub-commands are employed when using OpenKIM IMs in LAMMPS, one to select the IM and perform necessary
initialization (kim init), and the second to set up the IM for use by executing any necessary LAMMPS commands (kim
interactions). Both are required.

Syntax

kim init model user_units unitarg

kim interactions typeargs

• model = name of the KIM interatomic model (the KIM ID for models archived in OpenKIM)
• user_units = the LAMMPS units style assumed in the LAMMPS input script
• unitarg = unit_conversion_mode (optional)
• typeargs = atom type to species mapping (one entry per atom type) or fixed_types for models with a preset fixed
mapping

Examples

kim init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal

kim interactions Si

kim init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_001 real

kim init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_001␣
,→metal unit_conversion_mode

kim interactions C H O

kim init Sim_LAMMPS_IFF_PCFF_HeinzMishraLinEmami_2015Ver1v5_

,→FccmetalsMineralsSolventsPolymers__SM_039297821658_000 real

kim interactions fixed_types

See the examples/kim directory for example input scripts that use KIM PMs and KIM SMs.

OpenKIM IM Initialization (kim init)

The kim command followed by init sub-command must be issued before the simulation box is created (normally at the
top of the file). This command sets the OpenKIM IM that will be used and may issue additional commands changing
LAMMPS default settings that are required for using the selected IM (such as units or atom_style). If needed, those
settings can be overridden, however, typically a script containing a kim init command would not include units and
atom_style commands.
The required arguments of kim init are the model name of the IM to be used in the simulation (for an IM archived in
OpenKIM this is its extended KIM ID, and the user_units, which are the LAMMPS units style used in the input script.
(Any dimensioned numerical values in the input script and values read in from files are expected to be in the user_units
system.)
The selected IM can be either a KIM PM or a KIM SM. For a KIM SM, the kim init command verifies that the SM
is designed to work with LAMMPS (and not another simulation code). In addition, the LAMMPS version used for
defining the SM and the LAMMPS version being currently run are printed to help diagnose any incompatible changes
to input script or command syntax between the two LAMMPS versions.

762 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Based on the selected model kim init may modify the atom_style. Some SMs have requirements for this setting. If
this is the case, then atom_style will be set to the required style. Otherwise, the value is left unchanged (which in the
absence of an atom_style command in the input script is the default atom_style value).
Regarding units, the kim init behaves in different ways depending on whether or not unit conversion mode is activated
as indicated by the optional unitarg argument. If unit conversion mode is not active, then user_units must either match
the required units of the IM or the IM must be able to adjust its units to match. (The latter is only possible with some
KIM PMs; SMs can never adjust their units.) If a match is possible, the LAMMPS units command is called to set
the units to user_units. If the match fails, the simulation is terminated with an error. The kim init command also sets
the default value for the skin (extra distance beyond force cutoff) as 2.0 Angstroms and sets the default value for the
timestep size as 1.0 femtosecond.
Here is an example of a LAMMPS script to compute the cohesive energy of a face-centered cubic (fcc) lattice for the
MEAM potential by Pascuet and Fernandez (2015) for Al.

kim init Sim_LAMMPS_MEAM_PascuetFernandez_2015_Al__SM_811588957187_000 metal

boundary p p p
lattice fcc 4.049
region simbox block 0 1 0 1 0 1 units lattice
create_box 1 simbox
create_atoms 1 box
mass 1 26.981539
kim interactions Al
run 0
variable Ec equal (pe/count(all))
print "Cohesive Energy = ${Ec} eV"

The above script will end with an error in the kim init line if the IM is changed to another potential for Al that does not
work with metal units. To address this, kim init offers the unit_conversion_mode as shown below.
If unit conversion mode is active, then kim init calls the LAMMPS units command to set the units to the IM’s required
or preferred units. Conversion factors between the IM’s units and the user_units are defined for all physical quantities
(mass, distance, etc.). (Note that converting to or from the “lj” unit style is not supported.) These factors are stored as
internal style variables with the following standard names:

_u_mass
_u_distance
_u_time
_u_energy
_u_velocity
_u_force
_u_torque
_u_temperature
_u_pressure
_u_viscosity
_u_charge
_u_dipole
_u_efield
_u_density

If desired, the input script can be designed to work with these conversion factors so that the script will work without
change with any OpenKIM IM. (This approach is used in the OpenKIM Testing Framework.)
For example, the script given above for the cohesive energy of fcc Al can be rewritten to work with any IM regardless
of units. The following script constructs an fcc lattice with a lattice parameter defined in meters, computes the total
energy, and prints the cohesive energy in Joules regardless of the units of the IM.

16.61. kim command 763

LAMMPS Documentation, Release stable 29Sep2021

kim init Sim_LAMMPS_MEAM_PascuetFernandez_2015_Al__SM_811588957187_000 si unit_

,→conversion_mode

boundary p p p
lattice fcc $(4.049e-10*v__u_distance)
region simbox block 0 1 0 1 0 1 units lattice
create_box 1 simbox
create_atoms 1 box
mass 1 $(4.480134e-26*v__u_mass)
kim interactions Al
neighbor $(2e-10*v__u_distance) bin
run 0
variable Ec_in_J equal (pe/count(all))/v__u_energy
print "Cohesive Energy = ${Ec_in_J} J"

Note the multiplication by v__u_distance and v__u_mass to convert from SI units (specified in the kim init command)
to whatever units the IM uses (metal in this case), and the division by v__u_energy to convert from the IM’s energy
units to SI units (Joule). This script will work correctly for any IM for Al (KIM PM or SM) selected by the kim init
command.
Care must be taken to apply unit conversion to dimensional variables read in from a file. For example, if a configuration
of atoms is read in from a dump file using the read_dump command, the following can be done to convert the box and
all atomic positions to the correct units:

change_box all x scale ${_u_distance} &

y scale ${_u_distance} &
z scale ${_u_distance} &
xy final $(xy*v__u_distance) &
xz final $(xz*v__u_distance) &
yz final $(yz*v__u_distance) &
remap

Note: Unit conversion will only work if the conversion factors are placed in all appropriate places in the input script.
It is up to the user to do this correctly.

OpenKIM IM Execution (kim interactions)

The second and final step in using an OpenKIM IM is to execute the kim interactions command. This command must
be preceded by a kim init command and a command that defines the number of atom types N (such as create_box).
The kim interactions command has one argument typeargs. This argument contains either a list of N chemical species,
which defines a mapping between atom types in LAMMPS to the available species in the OpenKIM IM, or the key-
word fixed_types for models that have a preset fixed mapping (i.e. the mapping between LAMMPS atom types and
chemical species is defined by the model and cannot be changed). In the latter case, the user must consult the model
documentation to see how many atom types there are and how they map to the chemical species.
For example, consider an OpenKIM IM that supports Si and C species. If the LAMMPS simulation has four atom
types, where the first three are Si, and the fourth is C, the following kim interactions command would be used:

kim interactions Si Si Si C

Alternatively, for a model with a fixed mapping the command would be:

764 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

kim interactions fixed_types

The kim interactions command performs all the necessary steps to set up the OpenKIM IM selected in the kim init
command. The specific actions depend on whether the IM is a KIM PM or a KIM SM. For a KIM PM, a pair_style
kim command is executed followed by the appropriate pair_coeff command. For example, for the Ercolessi and Adams
(1994) KIM PM for Al set by the following commands:

kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal

...
... box specification lines skipped
...
kim interactions Al

the kim interactions command executes the following LAMMPS input commands:

pair_style kim EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005

pair_coeff * * Al

For a KIM SM, the generated input commands may be more complex and require that LAMMPS is built with the
required packages included for the type of potential being used. The set of commands to be executed is defined in the
SM specification file, which is part of the SM package. For example, for the Strachan et al. (2003) ReaxFF SM set by
the following commands:

kim init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 real

...
... box specification lines skipped
...
kim interactions C H N O

the kim interactions command executes the following LAMMPS input commands:

pair_style reaxff lmp_control safezone 2.0 mincap 100

pair_coeff * * ffield.reax.rdx C H N O
fix reaxqeq all qeq/reaxff 1 0.0 10.0 1.0e-6 param.qeq

Note: The files lmp_control, ffield.reax.rdx and param.qeq are specific to the Strachan et al. (2003) ReaxFF parame-
terization and are archived as part of the SM package in OpenKIM.

Note: Parameters like cutoff radii and charge tolerances, which have an effect on IM predictions, are also included in
the SM definition ensuring reproducibility.

Note: When using kim init and kim interactions to select and set up an OpenKIM IM, other LAMMPS commands for
the same functions (such as pair_style, pair_coeff, bond_style, bond_coeff, fixes related to charge equilibration, etc.)
should normally not appear in the input script.

Note: kim interactions must be called each time after the change_box command to provide the correct settings (it should
be called with the same typeargs as the first call.) The reason is that changing a periodic boundary to a non-periodic
one, or in general, using the change_box command after the interactions are set via kim interactions or pair_coeff
commands might affect some of the settings. For example, SM models containing Coulombic terms in the interactions

16.61. kim command 765

LAMMPS Documentation, Release stable 29Sep2021

require different settings if a periodic boundary changes to a non-periodic one. In other cases, the second call to kim
interactions does not affect any other settings.

16.61.5 Using OpenKIM Web Queries in LAMMPS (kim query)

The kim query command performs a web query to retrieve the predictions of an IM set by kim init for material properties
archived in OpenKIM.

Syntax

kim query variable formatarg query_function queryargs

• variable(s) = single name or list of names of (string style) LAMMPS variable(s) where a query result or parameter
get result is stored. Variables that do not exist will be created by the command
• formatarg = list, split, or index (optional):
list = returns a single string with a list of space separated values
(e.g. "1.0 2.0 3.0"), which is placed in a LAMMPS variable as
defined by the variable argument. [default]
split = returns the values separately in new variables with names based
on the prefix specified in variable and a number appended to
indicate which element in the list of values is in the variable
index = returns a variable style index that can be incremented via the
next command. This enables the construction of simple loops
• query_function = name of the OpenKIM web API query function to be used
• queryargs = a series of keyword=value pairs that represent the web query; supported keywords depend on the
query function

Examples

kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom]

kim query model index get_available_models species=[Al] potential_type=[eam]

The result of the query is stored in one or more string style variables as determined by the optional formatarg argument.
For the “list” setting of formatarg (or if formatarg is not specified), the result is returned as a space-separated list of
values in variable. The formatarg keyword “split” separates the result values into individual variables of the form
prefix_I, where prefix is set to the kim query variable argument and I ranges from 1 to the number of returned values.
The number and order of the returned values is determined by the type of query performed. The formatarg keyword
“index” returns a variable style index that can be incremented via the next command. This enables the construction of
simple loops over the returned values by the type of query performed.

Note: kim query only supports queries that return a single result or an array of values. More complex queries that
return a JSON structure are not currently supported. An attempt to use kim query in such cases will generate an error.

The second required argument query_function is the name of the query function to be called (e.g.
get_lattice_constant_cubic). All following arguments are parameters handed over to the web query in the format key-
word=value, where value is always an array of one or more comma-separated items in brackets. The list of supported

766 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

keywords and the type and format of their values depend on the query function used. The current list of query functions
is available on the OpenKIM webpage at https://openkim.org/doc/usage/kim-query.

Note: All query functions, except get_available_models, require the model keyword, which identifies the IM whose
predictions are being queried. kim query automatically generates the model keyword based on the IM set in by kim
init, and it can be overwritten if specified as an argument to the kim query. Where kim init is not specified, the model
keyword must be provided as an argument to the kim query.

Note: Each query_function is associated with a default method (implemented as a KIM Test) used to compute this
property. In cases where there are multiple methods in OpenKIM for computing a property, a method keyword can be
provided to select the method of choice. See the query documentation to see which methods are available for a given
query_function.

kim query Usage Examples and Further Clarifications

The data obtained by kim query commands can be used as part of the setup or analysis phases of LAMMPS simulations.
Some examples are given below.
Define an equilibrium fcc crystal

kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal

boundary p p p
kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom]
lattice fcc ${a0}
...

units metal
kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom]␣
,→model=[EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005]

lattice fcc ${a0}

...

The kim query command retrieves from OpenKIM the equilibrium lattice constant predicted by the Ercolessi and Adams
(1994) potential for the fcc structure and places it in variable a0. This variable is then used on the next line to set up the
crystal. By using kim query, the user is saved the trouble and possible error of tracking this value down, or of having
to perform an energy minimization to find the equilibrium lattice constant.

Note: In unit_conversion_mode the results obtained from a kim query would need to be converted to the appropri-
ate units system. For example, in the above script, the lattice command would need to be changed to: “lattice fcc
$(v_a0*v__u_distance)”.

Define an equilibrium hcp crystal

kim init EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000 metal

boundary p p p
kim query latconst split get_lattice_constant_hexagonal crystal=[hcp] species=[Zr]␣
,→units=[angstrom]

lattice custom ${latconst_1} a1 0.5 -0.866025 0 a2 0.5 0.866025 0 a3 0 0 $(latconst_2/

,→latconst_1) &

(continues on next page)

16.61. kim command 767

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

basis 0.333333 0.666666 0.25 basis 0.666666 0.333333 0.75
...

In this case the kim query returns two arguments (since the hexagonal close packed (hcp) structure has two independent
lattice constants). The formatarg keyword “split” places the two values into the variables latconst_1 and latconst_2.
(These variables are created if they do not already exist.)
Define a crystal at finite temperature accounting for thermal expansion

kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal

boundary p p p
kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom]
kim query alpha get_linear_thermal_expansion_coefficient_cubic crystal=[fcc]␣
,→species=[Al] units=[1/K] temperature=[293.15] temperature_units=[K]

variable DeltaT equal 300

lattice fcc $(v_a0*v_alpha*v_DeltaT)
...

As in the previous example, the equilibrium lattice constant is obtained for the Ercolessi and Adams (1994) potential.
However, in this case the crystal is scaled to the appropriate lattice constant at room temperature (293.15 K) by using
the linear thermal expansion constant predicted by the potential.

Note: When passing numerical values as arguments (as in the case of the temperature in the above example) it is also
possible to pass a tolerance indicating how close to the value is considered a match. If no tolerance is passed a default
value is used. If multiple results are returned (indicating that the tolerance is too large), kim query will return an error.
See the query documentation to see which numerical arguments and tolerances are available for a given query_function.

Compute defect formation energy

kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal

...
... Build fcc crystal containing some defect and compute the total energy
... which is stored in the variable *Etot*
...
kim query Ec get_cohesive_energy_cubic crystal=[fcc] species=[Al] units=[eV]
variable Eform equal ${Etot} - count(all)*${Ec}
...

The defect formation energy Eform is computed by subtracting the ideal fcc cohesive energy of the atoms in the system
from Etot. The ideal fcc cohesive energy of the atoms is obtained from OpenKIM for the Ercolessi and Adams (1994)
potential.
Retrieve equilibrium fcc crystal of all EAM potentials that support a specific species

kim query model index get_available_models species=[Al] potential_type=[eam]

label model_loop
kim query latconst get_lattice_constant_cubic crystal=[fcc] species=[Al]␣
,→units=[angstrom] model=[${model}]

print "FCC lattice constant (${model} potential) = ${latconst}"

...
... do something with current value of latconst
...
(continues on next page)

768 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

next model
jump SELF model_loop

In this example, the index mode of formatarg is used. The first kim query returns the list of all available EAM potentials
that support the Al species and archived in OpenKIM. The result of the query operation is stored in the LAMMPS
variable model as an index variable. This variable is used later to access the values one at a time within a loop as
shown in the example. The second kim query command retrieves from OpenKIM the equilibrium lattice constant
predicted by each potential for the fcc structure and places it in variable latconst.

Note: kim query commands return results archived in OpenKIM. These results are obtained using programs for
computing material properties (KIM Tests and KIM Test Drivers) that were contributed to OpenKIM. In order to give
credit to Test developers, the number of times results from these programs are queried is tracked. No other information
about the nature of the query or its source is recorded.

16.61.6 Accessing KIM Model Parameters from LAMMPS (kim param)

All IMs are functional forms containing a set of parameters. These parameters’ values are typically selected to best
reproduce a training set of quantum mechanical calculations or available experimental data. For example, a Lennard-
Jones potential intended to model argon might have the values of its two parameters, epsilon, and sigma, fit to the dimer
dissociation energy or thermodynamic properties at a critical point of the phase diagram.
Normally a user employing an IM should not modify its parameters since, as noted above, these are selected to re-
produce material properties. However, there are cases where accessing and modifying IM parameters is desired, such
as for assessing uncertainty, fitting an IM, or working with an ensemble of IMs. As explained above, IMs archived
in OpenKIM are either Portable Models (PMs) or Simulator Models (SMs). KIM PMs are complete independent
implementations of an IM, whereas KIM SMs are wrappers to an IM implemented within LAMMPS. Two different
mechanisms are provided for accessing IM parameters in these two cases:
• For a KIM PM, the kim param command can be used to get and set the values of the PM’s parameters as explained
below.
• For a KIM SM, the user should consult the documentation page for the specific IM and follow instructions there
for how to modify its parameters (if possible).
The kim param get and kim param set commands provide an interface to access and change the parameters of a KIM
PM that “publishes” its parameters and makes them publicly available (see the KIM API documentation for details).

Note: The kim param set/get command must be preceded by a kim interactions command (or alternatively by a
pair_style kim and pair_coeff commands). The kim param set command may be used wherever a pair_coeff command
may occur.

16.61. kim command 769

LAMMPS Documentation, Release stable 29Sep2021

Syntax

kim param get param_name index_range variable formatarg

kim param set param_name index_range values

• param_name = name of a KIM portable model parameter (which is published by the PM and available for access).
The specific string used to identify a parameter is defined by the PM. For example, for the Stillinger-Weber (SW)
potential in OpenKIM, the parameter names are A, B, p, q, sigma, gamma, cutoff, lambda, costheta0
• index_range = KIM portable model parameter index range (an integer for a single element, or pair of integers
separated by a colon for a range of elements)
• variable(s) = single name or list of names of (string style) LAMMPS variable(s) where a query result or parameter
get result is stored. Variables that do not exist will be created by the command
• formatarg = list, split, or explicit (optional): .. parsed-literal:

*list* = returns a single string with a list of space separated values

(e.g. "1.0 2.0 3.0"), which is placed in a LAMMPS variable as
defined by the *variable* argument.
*split* = returns the values separately in new variables with names based
on the prefix specified in *variable* and a number appended to
indicate which element in the list of values is in the variable
*explicit* = returns the values separately in one more more variable names
provided as arguments that precede *formatarg*\ . [default]

• values = new value(s) to replace the current value(s) of a KIM portable model parameter

Note: The list of all the parameters that a PM exposes for access/mutation are automatically written to the lammps
log file when kim init is called.

Each published parameter of a KIM PM takes the form of an array of numerical values. The array can contain one
element for a single-valued parameter, or a set of values. For example, the multispecies SW potential for the Zn-Cd-Hg-
S-Se-Te system has the same parameter names as the single-species SW potential, but each parameter array contains
21 entries that correspond to the parameter values used for each pairwise combination of the model’s six supported
species (this model does not have parameters specific to individual ternary combinations of its supported species).
The index_range argument may either be an integer referring to a specific element within the array associated with the
parameter specified by param_name, or a pair of integers separated by a colon that refer to a slice of this array. In both
cases, one-based indexing is used to refer to the entries of the array.
The result of a get operation for a specific index_range is stored in one or more LAMMPS string style variables as de-
termined by the optional formatarg argument documented above. If not specified, the default for formatarg is “explicit”
for the kim param command.
For the case where the result is an array with multiple values (i.e. index_range contains a range), the optional “split”
or “explicit” formatarg keywords can be used to separate the results into multiple variables; see the examples below.
Multiple parameters can be retrieved with a single call to kim param get by repeating the argument list following get.
For a set operation, the values argument contains the new value(s) for the element(s) of the parameter specified by
index_range. For the case where multiple values are being set, values contains a set of values separated by spaces.
Multiple parameters can be set with a single call to kim param set by repeating the argument list following set.

770 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

kim param Usage Examples and Further Clarifications

Examples of getting and setting KIM PM parameters with further clarifications are provided below.
Getting a scalar parameter
kim init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal
...
kim interactions Si
kim param get A 1 VARA

or
...
pair_style kim SW_StillingerWeber_1985_Si__MO_405512056662_005
pair_coeff * * Si
kim param get A 1 VARA

In these cases, the value of the SW A parameter is retrieved and placed in the LAMMPS variable VARA. The variable
VARA can be used in the remainder of the input script in the same manner as any other LAMMPS variable.
Getting multiple scalar parameters with a single call

...
kim interactions Si
kim param get A 1 VARA B 1 VARB

In this example, it is shown how to retrieve the A and B parameters of the SW potential and store them in the LAMMPS
variables VARA and VARB.
Getting a range of values from a parameter
There are several options when getting a range of values from a parameter determined by the formatarg argument.

kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal

...
kim interactions Te Zn Se
kim param get lambda 7:9 LAM_TeTe LAM_TeZn LAM_TeSe

In this case, formatarg is not specified and therefore the default “explicit” mode is used. (The behavior would be the
same if the word explicit were added after LAM_TeSe.) Elements 7, 8 and 9 of parameter lambda retrieved by the get
operation are placed in the LAMMPS variables LAM_TeTe, LAM_TeZn and LAM_TeSe, respectively.

Note: In the above example, elements 7-9 of the lambda parameter correspond to Te-Te, Te-Zm and Te-Se interactions.
This can be determined by visiting the model page for the specified potential and looking at its parameter file linked
to at the bottom of the page (file with .param ending) and consulting the README documentation provided with the
driver for the PM being used. A link to the driver is provided at the top of the model page.

...
kim interactions Te Zn Se
kim param get lambda 15:17 LAMS list
variable LAM_VALUE index ${LAMS}
label loop_on_lambda
...
... do something with the current value of lambda
(continues on next page)

16.61. kim command 771

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

...
next LAM_VALUE
jump SELF loop_on_lambda

In this case, the “list” mode of formatarg is used. The result of the get operation is stored in the LAMMPS variable
LAMS as a string containing the three retrieved values separated by spaces, e.g “1.0 2.0 3.0”. This can be used in
LAMMPS with an index variable to access the values one at a time within a loop as shown in the example. At each
iteration of the loop LAM_VALUE contains the current value of lambda.

...
kim interactions Te Zn Se
kim param get lambda 15:17 LAM split

In this case, the “split” mode of formatarg is used. The three values retrieved by the get operation are stored in the three
LAMMPS variables LAM_15, LAM_16 and LAM_17. The provided name “LAM” is used as prefix and the location
in the lambda array is appended to create the variable names.
Setting a scalar parameter

kim init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal

...
kim interactions Si
kim param set gamma 1 2.6

Here, the SW potential’s gamma parameter is set to 2.6. Note that the get and set commands work together, so that a
get following a set operation will return the new value that was set. For example,

...
kim interactions Si
kim param get gamma 1 ORIG_GAMMA
kim param set gamma 1 2.6
kim param get gamma 1 NEW_GAMMA
...
print "original gamma = ${ORIG_GAMMA}, new gamma = ${NEW_GAMMA}"

Here, ORIG_GAMMA will contain the original gamma value for the SW potential, while NEW_GAMMA will contain
the value 2.6.
Setting multiple scalar parameters with a single call

kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal

...
kim interactions Cd Te
variable VARG equal 2.6
variable VARS equal 2.0951
kim param set gamma 1 ${VARG} sigma 3 ${VARS}

In this case, the first element of the gamma parameter and third element of the sigma parameter are set to 2.6 and
2.0951, respectively. This example also shows how LAMMPS variables can be used when setting parameters.
Setting a range of values of a parameter

kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal

...
(continues on next page)

772 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

kim interactions Cd Te Zn Se Hg S
kim param set sigma 2:6 2.35214 2.23869 2.04516 2.43269 1.80415

In this case, elements 2 through 6 of the parameter sigma are set to the values 2.35214, 2.23869, 2.04516, 2.43269 and
1.80415 in order.

16.61.7 Writing material properties in standard KIM Property Instance format (kim
property)

The OpenKIM system includes a collection of Tests (material property calculation codes), Models (interatomic po-
tentials), Predictions, and Reference Data (DFT or experiments). Specifically, a KIM Test is a computation that when
coupled with a KIM Model generates the prediction of that model for a specific material property rigorously defined by
a KIM Property Definition (see the KIM Properties Framework for further details). A prediction of a material property
for a given model is a specific numerical realization of a property definition, referred to as a “Property Instance.” The
objective of the kim property command is to make it easy to output material properties in a standardized, machine
readable, format that can be easily ingested by other programs. Additionally, it aims to make it as easy as possible to
convert a LAMMPS script that computes a material property into a KIM Test that can then be uploaded to openkim.org
A developer interested in creating a KIM Test using a LAMMPS script should first determine whether a property
definition that applies to their calculation already exists in OpenKIM by searching the properties page. If none exists,
it is possible to use a locally defined property definition contained in a file until it can be uploaded to the official
repository (see below). Once one or more applicable property definitions have been identified, the kim property create,
kim property modify, kim property remove, and kim property destroy, commands provide an interface to create, set,
modify, remove, and destroy instances of them within a LAMMPS script.

Syntax

kim property create instance_id property_id

kim property modify instance_id key key_name key_name_key key_name_value
kim property remove instance_id key key_name
kim property destroy instance_id
kim property dump file

• instance_id = a positive integer identifying the KIM property instance; (note that the results file can contain
multiple property instances)
• property_id = identifier of a KIM Property Definition, which can be (1) a property short name, (2) the full unique
ID of the property (including the contributor and date), (3) a file name corresponding to a local property definition
file
• key_name = one of the keys belonging to the specified KIM property definition
• key_name_key = a key belonging to a key-value pair (standardized in the KIM Properties Framework)
• key_name_value = value to be associated with a key_name_key in a key-value pair
• file = name of a file to write the currently defined set of KIM property instances to
Examples of each of the three property_id cases are shown below,

kim property create 1 atomic-mass

kim property create 2 cohesive-energy-relation-cubic-crystal

16.61. kim command 773

LAMMPS Documentation, Release stable 29Sep2021

kim property create 1 tag:[email protected],2016-05-11:property/atomic-mass

kim property create 2 tag:[email protected],2014-04-15:property/cohesive-energy-
,→relation-cubic-crystal

kim property create 1 new-property.edn

kim property create 2 /home/mary/marys-kim-properties/dissociation-energy.edn

In the last example, “new-property.edn” and “/home/mary/marys-kim-properties/dissociation-energy.edn” are the

names of files that contain user-defined (local) property definitions.
A KIM property instance takes the form of a “map,” i.e. a set of key-value pairs akin to Perl’s hash, Python’s dictionary,
or Java’s Hashtable. It consists of a set of property key names, each of which is referred to here by the key_name
argument, that are defined as part of the relevant KIM Property Definition and include only lowercase alphanumeric
characters and dashes. The value paired with each property key is itself a map whose possible keys are defined as part
of the KIM Properties Framework; these keys are referred to by the key_name_key argument and their associated values
by the key_name_value argument. These values may either be scalars or arrays, as stipulated in the property definition.

Note: Each map assigned to a key_name must contain the key_name_key “source-value” and an associated
key_name_value of the appropriate type (as defined in the relevant KIM Property Definition). For keys that are de-
fined as having physical units, the “source-unit” key_name_key must also be given a string value recognized by GNU
units.

Once a kim property create command has been given to instantiate a property instance, maps associated with the
property’s keys can be edited using the kim property modify command. In using this command, the special keyword
“key” should be given, followed by the property key name and the key-value pair in the map associated with the key
that is to be set. For example, the atomic-mass property definition consists of two property keys named “mass” and
“species.” An instance of this property could be created like so:

kim property create 1 atomic-mass

kim property modify 1 key species source-value Al
kim property modify 1 key mass source-value 26.98154
kim property modify 1 key mass source-unit amu

or, equivalently,

kim property create 1 atomic-mass

kim property modify 1 key species source-value Al &
key mass source-value 26.98154 &
source-unit amu

kim property Usage Examples and Further Clarifications

Create

kim property create instance_id property_id

The kim property create command takes as input a property instance ID and the property definition name, and creates
an initial empty property instance data structure. For example,

kim property create 1 atomic-mass

kim property create 2 cohesive-energy-relation-cubic-crystal

774 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

creates an empty property instance of the “atomic-mass” property definition with instance ID 1 and an empty instance of
the “cohesive-energy-relation-cubic-crystal” property with ID 2. A list of published property definitions in OpenKIM
can be found on the properties page.
One can also provide the name of a file in the current working directory or the path of a file containing a valid property
definition. For example,

kim property create 1 new-property.edn

where “new-property.edn” refers to a file name containing a new property definition that does not exist in OpenKIM.
If the property_id given cannot be found in OpenKIM and no file of this name containing a valid property definition
can be found, this command will produce an error with an appropriate message. Calling kim property create with the
same instance ID multiple times will also produce an error.
Modify

kim property modify instance_id key key_name key_name_key key_name_value

The kim property modify command incrementally builds the property instance by receiving property definition keys
along with associated arguments. Each key_name is associated with a map containing one or more key-value pairs (in
the form of key_name_key-key_name_value pairs). For example,

kim property modify 1 key species source-value Al

kim property modify 1 key mass source-value 26.98154
kim property modify 1 key mass source-unit amu

where the special keyword “key” is followed by a key_name (“species” or “mass” in the above) and one or more key-
value pairs. These key-value pairs may continue until either another “key” keyword is given or the end of the command
line is reached. Thus, the above could equivalently be written as

kim property modify 1 key species source-value Al &

key mass source-value 26.98154 &
key mass source-unit amu

As an example of modifying multiple key-value pairs belonging to the map of a single property key, the following
command modifies the map of the “cohesive-potential-energy” property key to contain the key “source-unit” which is
assigned a value of “eV” and the key “digits” which is assigned a value of 5,

kim property modify 2 key cohesive-potential-energy source-unit eV digits 5

Note: The relevant data types of the values in the map are handled automatically based on the specification of the key
in the KIM Property Definition. In the example above, this means that the value “eV” will automatically be interpreted
as a string while the value 5 will be interpreted as an integer.

The values contained in maps can either be scalars, as in all of the examples above, or arrays depending on which is
stipulated in the corresponding Property Definition. For one-dimensional arrays, a single one-based index must be
supplied that indicates which element of the array is to be modified. For multidimensional arrays, multiple indices
must be given depending on the dimensionality of the array.

Note: All array indexing used by kim property modify is one-based, i.e. the indices are enumerated 1, 2, 3, . . .

Note: The dimensionality of arrays are defined in the the corresponding Property Definition. The extent of each

16.61. kim command 775

LAMMPS Documentation, Release stable 29Sep2021

dimension of an array can either be a specific finite number or indefinite and determined at run time. If an array has a
fixed extent, attempting to modify an out-of-range index will fail with an error message.

For example, the “species” property key of the cohesive-energy-relation-cubic-crystal property is a one-dimensional
array that can contain any number of entries based on the number of atoms in the unit cell of a given cubic crystal. To
assign an array containing the string “Al” four times to the “source-value” key of the “species” property key, we can
do so by issuing:

kim property modify 2 key species source-value 1 Al

kim property modify 2 key species source-value 2 Al
kim property modify 2 key species source-value 3 Al
kim property modify 2 key species source-value 4 Al

Note: No declaration of the number of elements in this array was given; kim property modify will automatically handle
memory management to allow an arbitrary number of elements to be added to the array.

Note: In the event that kim property modify is used to set the value of an array index without having set the values of
all lesser indices, they will be assigned default values based on the data type associated with the key in the map:

Data type Default value

int 0
float 0.0
string ""
file ""

For example, doing the following:

kim property create 2 cohesive-energy-relation-cubic-crystal

kim property modify 2 key species source-value 4 Al

will result in the “source-value” key in the map for the property key “species” being assigned the array [“”, “”, “”,
“Al”].

For convenience, the index argument provided may refer to an inclusive range of indices by specifying two integers
separated by a colon (the first integer must be less than or equal to the second integer, and no whitespace should be
included). Thus, the snippet above could equivalently be written:

kim property modify 2 key species source-value 1:4 Al Al Al Al

Calling this command with a non-positive index, e.g. kim property modify 2 key species source-value 0
Al, or an incorrect number of input arguments, e.g. kim property modify 2 key species source-value 1:4
Al Al, will result in an error.
As an example of modifying multidimensional arrays, consider the “basis-atoms” key in the cohesive-energy-relation-
cubic-crystal property definition. This is a two-dimensional array containing the fractional coordinates of atoms in
the unit cell of the cubic crystal. In the case of, e.g. a conventional fcc unit cell, the “source-value” key in the map
associated with this key should be assigned the following value:

[[0.0, 0.0, 0.0],

[0.5, 0.5, 0.0],
(continues on next page)

776 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

[0.5, 0.0, 0.5],
[0.0, 0.5, 0.5]]

While each of the twelve components could be set individually, we can instead set each row at a time using colon
notation:

kim property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0
kim property modify 2 key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0
kim property modify 2 key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5
kim property modify 2 key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5

Where the first index given refers to a row and the second index refers to a column. We could, instead, choose to set
each column at a time like so:

kim property modify 2 key basis-atom-coordinates source-value 1:4 1 0.0 0.5 0.5 0.0 &
key basis-atom-coordinates source-value 1:4 2 0.0 0.5 0.0 0.5 &
key basis-atom-coordinates source-value 1:4 3 0.0 0.0 0.5 0.5

Note: Multiple calls of kim property modify made for the same instance ID can be combined into a single invocation,
meaning the following are both valid:

kim property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 &
key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0 &
key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5 &
key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5

kim property modify 2 key short-name source-value 1 fcc &

key species source-value 1:4 Al Al Al Al &
key a source-value 1:5 3.9149 4.0000 4.032 4.0817 4.1602 &
source-unit angstrom &
digits 5 &
key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 &
key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0 &
key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5 &
key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5

Note: For multidimensional arrays, only one colon-separated range is allowed in the index listing. Therefore,

kim property modify 2 key basis-atom-coordinates 1 1:3 0.0 0.0 0.0

is valid but

kim property modify 2 key basis-atom-coordinates 1:2 1:3 0.0 0.0 0.0 0.0 0.0 0.0

is not.

Note: After one sets a value in a map with the kim property modify command, additional calls will overwrite the
previous value.

16.61. kim command 777

LAMMPS Documentation, Release stable 29Sep2021

Remove

kim property remove instance_id key key_name

The kim property remove command can be used to remove a property key from a property instance. For example,

kim property remove 2 key basis-atom-coordinates

Destroy

kim property destroy instance_id

The kim property destroy command deletes a previously created property instance ID. For example,

kim property destroy 2

Note: If this command is called with an instance ID that does not exist, no error is raised.

Dump
The kim property dump command can be used to write the content of all currently defined property instances to a file:

kim property dump file

For example,

kim property dump results.edn

Note: Issuing the kim property dump command clears all existing property instances from memory.

16.61.8 Citation of OpenKIM IMs

When publishing results obtained using OpenKIM IMs researchers are requested to cite the OpenKIM project (Tadmor),
KIM API (Elliott), and the specific IM codes used in the simulations, in addition to the relevant scientific references
for the IM. The citation format for an IM is displayed on its page on OpenKIM along with the corresponding BibTex
file, and is automatically added to the LAMMPS citation reminder.
Citing the IM software (KIM infrastructure and specific PM or SM codes) used in the simulation gives credit to the
researchers who developed them and enables open source efforts like OpenKIM to function.

16.61.9 Restrictions

The kim command is part of the KIM package. It is only enabled if LAMMPS is built with that package. A requirement
for the KIM package, is the KIM API library that must be downloaded from the OpenKIM website and installed
before LAMMPS is compiled. When installing LAMMPS from binary, the kim-api package is a dependency that is
automatically downloaded and installed. The kim query command requires the libcurl library to be installed. The kim
property command requires Python 3.6 or later and the kim-property python package to be installed. See the KIM
section of the Packages details for details.
Furthermore, when using kim command to run KIM SMs, any packages required by the native potential being used or
other commands or fixes that it invokes must be installed.

778 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.61.10 Related commands

pair_style kim

(Tadmor) Tadmor, Elliott, Sethna, Miller and Becker, JOM, 63, 17 (2011). doi: https://doi.org/10.1007/
s11837-011-0102-6
(Elliott) Elliott, Tadmor and Bernstein, https://openkim.org/kim-api (2011) doi: https://doi.org/10.25950/FF8F563A

16.62 kspace_modify command

16.62.1 Syntax

kspace_modify keyword value ...

• one or more keyword/value pairs may be listed

• keyword = collective or compute or cutoff/adjust or diff or disp/auto or fftbench or force/disp/kspace or
force/disp/real or force or gewald/disp or gewald or kmax/ewald or mesh or minorder or mix/disp or order/disp
or order or overlap or scafacos or slab or splittol
collective value = yes or no
compute value = yes or no
cutoff/adjust value = yes or no
diff value = ad or ik = 2 or 4 FFTs for PPPM in smoothed or non-smoothed mode
disp/auto value = yes or no
fftbench value = yes or no
force/disp/real value = accuracy (force units)
force/disp/kspace value = accuracy (force units)
force value = accuracy (force units)
gewald value = rinv (1/distance units)
rinv = G-ewald parameter for Coulombics
gewald/disp value = rinv (1/distance units)
rinv = G-ewald parameter for dispersion
kmax/ewald value = kx ky kz
kx,ky,kz = number of Ewald sum kspace vectors in each dimension
mesh value = x y z
x,y,z = grid size in each dimension for long-range Coulombics
mesh/disp value = x y z
x,y,z = grid size in each dimension for 1/r^6 dispersion
minorder value = M
M = min allowed extent of Gaussian when auto-adjusting to minimize grid␣
,→communication

mix/disp value = pair or geom or none

order value = N
N = extent of Gaussian for PPPM or MSM mapping of charge to grid
order/disp value = N
N = extent of Gaussian for PPPM mapping of dispersion term to grid
overlap = yes or no = whether the grid stencil for PPPM is allowed to overlap into␣
,→more than the nearest-neighbor processor

pressure/scalar value = yes or no

scafacos values = option value1 value2 ...

16.62. kspace_modify command 779

LAMMPS Documentation, Release stable 29Sep2021

option = tolerance
value = energy or energy_rel or field or field_rel or potential or potential_rel
option = fmm_tuning
value = 0 or 1
slab value = volfactor or nozforce
volfactor = ratio of the total extended volume used in the
2d approximation compared with the volume of the simulation domain
nozforce turns off kspace forces in the z direction
splittol value = tol
tol = relative size of two eigenvalues (see discussion below)

16.62.2 Examples

kspace_modify mesh 24 24 30 order 6

kspace_modify slab 3.0
kspace_modify scafacos tolerance energy

16.62.3 Description

Set parameters used by the kspace solvers defined by the kspace_style command. Not all parameters are relevant to all
kspace styles.

The collective keyword applies only to PPPM. It is set to no by default, except on IBM BlueGene machines. If this
option is set to yes, LAMMPS will use MPI collective operations to remap data for 3d-FFT operations instead of the
default point-to-point communication. This is faster on IBM BlueGene machines, and may also be faster on other
machines if they have an efficient implementation of MPI collective operations and adequate hardware.

The compute keyword allows Kspace computations to be turned off, even though a kspace_style is defined. This is
not useful for running a real simulation, but can be useful for debugging purposes or for computing only partial forces
that do not include the Kspace contribution. You can also do this by simply not defining a kspace_style, but a Kspace-
compatible pair_style requires a kspace style to be defined. This keyword gives you that option.

The cutoff/adjust keyword applies only to MSM. If this option is turned on, the Coulombic cutoff will be automatically
adjusted at the beginning of the run to give the desired estimated error. Other cutoffs such as LJ will not be affected. If
the grid is not set using the mesh command, this command will also attempt to use the optimal grid that minimizes cost
using an estimate given by (Hardy). Note that this cost estimate is not exact, somewhat experimental, and still may not
yield the optimal parameters.

The diff keyword specifies the differentiation scheme used by the PPPM method to compute forces on particles given
electrostatic potentials on the PPPM mesh. The ik approach is the default for PPPM and is the original formulation
used in (Hockney). It performs differentiation in Kspace, and uses 3 FFTs to transfer each component of the computed
fields back to real space for total of 4 FFTs per timestep.
The analytic differentiation ad approach uses only 1 FFT to transfer information back to real space for a total of 2 FFTs
per timestep. It then performs analytic differentiation on the single quantity to generate the 3 components of the electric
field at each grid point. This is sometimes referred to as “smoothed” PPPM. This approach requires a somewhat larger

780 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

PPPM mesh to achieve the same accuracy as the ik method. Currently, only the ik method (default) can be used for a
triclinic simulation cell with PPPM. The ad method is always used for MSM.

Note: Currently, not all PPPM styles support the ad option. Support for those PPPM variants will be added later.

The disp/auto option controls whether the pppm/disp is allowed to generate PPPM parameters automatically. If set to
no, parameters have to be specified using the gewald/disp, mesh/disp, force/disp/real or force/disp/kspace keywords,
or the code will stop with an error message. When this option is set to yes, the error message will not appear and
the simulation will start. For a typical application, using the automatic parameter generation will provide simulations
that are either inaccurate or slow. Using this option is thus not recommended. For guidelines on how to obtain good
parameters, see the How-To discussion.

The fftbench keyword applies only to PPPM. It is off by default. If this option is turned on, LAMMPS will perform a
short FFT benchmark computation and report its timings, and will thus finish some seconds later than it would if this
option were off.

The force/disp/real and force/disp/kspace keywords set the force accuracy for the real and reciprocal space computations
for the dispersion part of pppm/disp. As shown in (Isele-Holder), optimal performance and accuracy in the results is
obtained when these values are different.

The force keyword overrides the relative accuracy parameter set by the kspace_style command with an absolute ac-
curacy. The accuracy determines the RMS error in per-atom forces calculated by the long-range solver and is thus
specified in force units. A negative value for the accuracy setting means to use the relative accuracy parameter. The
accuracy setting is used in conjunction with the pairwise cutoff to determine the number of K-space vectors for style
ewald, the FFT grid size for style pppm, or the real space grid size for style msm.

The gewald keyword sets the value of the Ewald or PPPM G-ewald parameter for charge as rinv in reciprocal distance
units. Without this setting, LAMMPS chooses the parameter automatically as a function of cutoff, precision, grid
spacing, etc. This means it can vary from one simulation to the next which may not be desirable for matching a KSpace
solver to a pre-tabulated pairwise potential. This setting can also be useful if Ewald or PPPM fails to choose a good grid
spacing and G-ewald parameter automatically. If the value is set to 0.0, LAMMPS will choose the G-ewald parameter
automatically. MSM does not use the gewald parameter.

The gewald/disp keyword sets the value of the Ewald or PPPM G-ewald parameter for dispersion as rinv in reciprocal
distance units. It has the same meaning as the gewald setting for Coulombics.

The kmax/ewald keyword sets the number of kspace vectors in each dimension for kspace style ewald. The three values
must be positive integers, or else (0,0,0), which unsets the option. When this option is not set, the Ewald sum scheme
chooses its own kspace vectors, consistent with the user-specified accuracy and pairwise cutoff. In any case, if kspace
style ewald is invoked, the values used are printed to the screen and the log file at the start of the run.

The mesh keyword sets the grid size for kspace style pppm or msm. In the case of PPPM, this is the FFT mesh, and
each dimension must be factorizable into powers of 2, 3, and 5. In the case of MSM, this is the finest scale real-space

16.62. kspace_modify command 781

LAMMPS Documentation, Release stable 29Sep2021

mesh, and each dimension must be factorizable into powers of 2. When this option is not set, the PPPM or MSM solver
chooses its own grid size, consistent with the user-specified accuracy and pairwise cutoff. Values for x,y,z of 0,0,0
unset the option.

The mesh/disp keyword sets the grid size for kspace style pppm/disp. This is the FFT mesh for long-range dispersion
and ach dimension must be factorizable into powers of 2, 3, and 5. When this option is not set, the PPPM solver chooses
its own grid size, consistent with the user-specified accuracy and pairwise cutoff. Values for x,y,z of 0,0,0 unset the
option.

The minorder keyword allows LAMMPS to reduce the order setting if necessary to keep the communication of ghost
grid point limited to exchanges between nearest-neighbor processors. See the discussion of the overlap keyword for
details. If the overlap keyword is set to yes, which is the default, this is never needed. If it set to no and overlap occurs,
then LAMMPS will reduce the order setting, one step at a time, until the ghost grid overlap only extends to nearest
neighbor processors. The minorder keyword limits how small the order setting can become. The minimum allowed
value for PPPM is 2, which is the default. If minorder is set to the same value as order then no reduction is allowed,
and LAMMPS will generate an error if the grid communication is non-nearest-neighbor and overlap is set to no. The
minorder keyword is not currently supported in MSM.

The mix/disp keyword selects the mixing rule for the dispersion coefficients. With pair, the dispersion coefficients of
unlike types are computed as indicated with pair_modify. With geom, geometric mixing is enforced on the dispersion
coefficients in the kspace coefficients. When using the arithmetic mixing rule, this will speed-up the simulations but
introduces some error in the force computations, as shown in (Wennberg). With none, it is assumed that no mixing rule
is applicable. Splitting of the dispersion coefficients will be performed as described in (Isele-Holder).
This splitting can be influenced with the splittol keywords. Only the eigenvalues that are larger than tol compared
to the largest eigenvalues are included. Using this keywords the original matrix of dispersion coefficients is approxi-
mated. This leads to faster computations, but the accuracy in the reciprocal space computations of the dispersion part
is decreased.

The order keyword determines how many grid spacings an atom’s charge extends when it is mapped to the grid in
kspace style pppm or msm. The default for this parameter is 5 for PPPM and 8 for MSM, which means each charge
spans 5 or 8 grid cells in each dimension, respectively. For the LAMMPS implementation of MSM, the order can
range from 4 to 10 and must be even. For PPPM, the minimum allowed setting is 2 and the maximum allowed setting
is 7. The larger the value of this parameter, the smaller that LAMMPS will set the grid size, to achieve the requested
accuracy. Conversely, the smaller the order value, the larger the grid size will be. Note that there is an inherent trade-off
involved: a small grid will lower the cost of FFTs or MSM direct sum, but a larger order parameter will increase the
cost of interpolating charge/fields to/from the grid.
The PPPM order parameter may be reset by LAMMPS when it sets up the FFT grid if the implied grid stencil extends
beyond the grid cells owned by neighboring processors. Typically this will only occur when small problems are run
on large numbers of processors. A warning will be generated indicating the order parameter is being reduced to allow
LAMMPS to run the problem. Automatic adjustment of the order parameter is not supported in MSM.

The order/disp keyword determines how many grid spacings an atom’s dispersion term extends when it is mapped to
the grid in kspace style pppm/disp. It has the same meaning as the order setting for Coulombics.

The overlap keyword can be used in conjunction with the minorder keyword with the PPPM styles to adjust the amount
of communication that occurs when values on the FFT grid are exchanged between processors. This communication is

782 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

distinct from the communication inherent in the parallel FFTs themselves, and is required because processors interpolate
charge and field values using grid point values owned by neighboring processors (i.e. ghost point communication). If
the overlap keyword is set to yes then this communication is allowed to extend beyond nearest-neighbor processors,
e.g. when using lots of processors on a small problem. If it is set to no then the communication will be limited to
nearest-neighbor processors and the order setting will be reduced if necessary, as explained by the minorder keyword
discussion. The overlap keyword is always set to yes in MSM.

The pressure/scalar keyword applies only to MSM. If this option is turned on, only the scalar pressure (i.e. (Pxx +
Pyy + Pzz)/3.0) will be computed, which can be used, for example, to run an isotropic barostat. Computing the full
pressure tensor with MSM is expensive, and this option provides a faster alternative. The scalar pressure is computed
using a relationship between the Coulombic energy and pressure (Hummer) instead of using the virial equation. This
option cannot be used to access individual components of the pressure tensor, to compute per-atom virial, or with suffix
kspace/pair styles of MSM, like OMP or GPU.

The scafacos keyword is used for settings that are passed to the ScaFaCoS library when using kspace_style scafacos.
The tolerance option affects how the accuracy specified with the kspace_style command is interpreted by ScaFaCoS.
The following values may be used:
• energy = absolute accuracy in total Coulombic energy
• energy_rel = relative accuracy in total Coulombic energy
• potential = absolute accuracy in total Coulombic potential
• potential_rel = relative accuracy in total Coulombic potential
• field = absolute accuracy in electric field
• field_rel = relative accuracy in electric field
The values with suffix _rel indicate the tolerance is a relative tolerance; the other values impose an absolute tolerance
on the given quantity. Absolute tolerance in this case means, that for a given quantity q and a given absolute tolerance
of t_a the result should be between q-t_a and q+t_a. For a relative tolerance t_r the relative error should not be greater
than t_r, i.e. abs(1 - (result/q)) < t_r. As a consequence of this, the tolerance type should be checked, when performing
computations with a high absolute field / energy. E.g. if the total energy in the system is 1000000.0 an absolute tolerance
of 1e-3 would mean that the result has to be between 999999.999 and 1000000.001, which would be equivalent to a
relative tolerance of 1e-9.
The energy and energy_rel values, set a tolerance based on the total Coulombic energy of the system. The potential
and potential_rel set a tolerance based on the per-atom Coulombic energy. The field and field_rel tolerance types set
a tolerance based on the electric field values computed by ScaFaCoS. Since per-atom forces are derived from the per-
atom electric field, this effectively sets a tolerance on the forces, similar to other LAMMPS KSpace styles, as explained
on the kspace_style doc page.
Note that not all ScaFaCoS solvers support all tolerance types. These are the allowed values for each method:
• fmm = energy and energy_rel
• p2nfft = field (1d-,2d-,3d-periodic systems) or potential (0d-periodic)
• p3m = field
• ewald = field
• direct = has no tolerance tuning

16.62. kspace_modify command 783

LAMMPS Documentation, Release stable 29Sep2021

If the tolerance type is not changed, the default values for the tolerance type are the first values in the above list, e.g.
energy is the default tolerance type for the fmm solver.
The fmm_tuning option is only relevant when using the FMM method. It activates (value=1) or deactivates (value=0)
an internal tuning mechanism for the FMM solver. The tuning operation runs sequentially and can be very time-
consuming. Usually it is not needed for systems with a homogeneous charge distribution. The default for this option is
therefore 0. The FMM internal tuning is performed once, when the solver is set up.

The slab keyword allows an Ewald or PPPM solver to be used for a systems that are periodic in x,y but non-periodic
in z - a boundary setting of “boundary p p f”. This is done by treating the system as if it were periodic in z, but
inserting empty volume between atom slabs and removing dipole inter-slab interactions so that slab-slab interactions
are effectively turned off. The volfactor value sets the ratio of the extended dimension in z divided by the actual
dimension in z. The recommended value is 3.0. A larger value is inefficient; a smaller value introduces unwanted
slab-slab interactions. The use of fixed boundaries in z means that the user must prevent particle migration beyond the
initial z-bounds, typically by providing a wall-style fix. The methodology behind the slab option is explained in the
paper by (Yeh). The slab option is also extended to non-neutral systems (Ballenegger).
An alternative slab option can be invoked with the nozforce keyword in lieu of the volfactor. This turns off all kspace
forces in the z direction. The nozforce option is not supported by MSM. For MSM, any combination of periodic, non-
periodic, or shrink-wrapped boundaries can be set using boundary (the slab approximation in not needed). The slab
keyword is not currently supported by Ewald or PPPM when using a triclinic simulation cell. The slab correction has
also been extended to point dipole interactions (Klapp) in kspace_style ewald/disp, ewald/dipole, and pppm/dipole.

Note: If you wish to apply an electric field in the Z-direction, in conjunction with the slab keyword, you should do it
by adding explicit charged particles to the +/- Z surfaces. If you do it via the fix efield command, it will not give the
correct dielectric constant due to the Yeh/Berkowitz (Yeh) correction not being compatible with how fix efield works.

The force/disp/real and force/disp/kspace keywords set the force accuracy for the real and reciprocal space computations
for the dispersion part of pppm/disp. As shown in (Isele-Holder), optimal performance and accuracy in the results is
obtained when these values are different.
The disp/auto option controls whether the pppm/disp is allowed to generate PPPM parameters automatically. If set to
no, parameters have to be specified using the gewald/disp, mesh/disp, force/disp/real or force/disp/kspace keywords,
or the code will stop with an error message. When this option is set to yes, the error message will not appear and
the simulation will start. For a typical application, using the automatic parameter generation will provide simulations
that are either inaccurate or slow. Using this option is thus not recommended. For guidelines on how to obtain good
parameters, see the Howto dispersion doc page.

16.62.4 Restrictions

none

784 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.62.5 Related commands

kspace_style, boundary

16.62.6 Default

The option defaults are mesh = mesh/disp = 0 0 0, order = order/disp = 5 (PPPM), order = 10 (MSM), minorder = 2, over-
lap = yes, force = -1.0, gewald = gewald/disp = 0.0, slab = 1.0, compute = yes, cutoff/adjust = yes (MSM), pressure/scalar
= yes (MSM), fftbench = no (PPPM), diff = ik (PPPM), mix/disp = pair, force/disp/real = -1.0, force/disp/kspace = -1.0,
split = 0, tol = 1.0e-6, and disp/auto = no. For pppm/intel, order = order/disp = 7. For scafacos settings, the scafacos
tolerance option depends on the method chosen, as documented above. The scafacos fmm_tuning default = 0.

(Hockney) Hockney and Eastwood, Computer Simulation Using Particles, Adam Hilger, NY (1989).
(Yeh) Yeh and Berkowitz, J Chem Phys, 111, 3155 (1999).
(Ballenegger) Ballenegger, Arnold, Cerda, J Chem Phys, 131, 094107 (2009).
(Klapp) Klapp, Schoen, J Chem Phys, 117, 8050 (2002).
(Hardy) David Hardy thesis: Multilevel Summation for the Fast Evaluation of Forces for the Simulation of
Biomolecules, University of Illinois at Urbana-Champaign, (2006).
(Hummer) Hummer, Gronbech-Jensen, Neumann, J Chem Phys, 109, 2791 (1998)
(Isele-Holder) Isele-Holder, Mitchell, Hammond, Kohlmeyer, Ismail, J Chem Theory Comput, 9, 5412 (2013).
(Wennberg) Wennberg, Murtola, Hess, Lindahl, J Chem Theory Comput, 9, 3527 (2013).

16.63 kspace_style command

16.63.1 Syntax

kspace_style style value

• style = none or ewald or ewald/dipole or ewald/dipole/spin or ewald/disp or ewald/disp/dipole or ewald/omp or

pppm or pppm/cg or pppm/disp or pppm/tip4p or pppm/stagger or pppm/disp/tip4p or pppm/gpu or pppm/intel
or pppm/disp/intel or pppm/kk or pppm/omp or pppm/cg/omp or pppm/disp/tip4p/omp or pppm/tip4p/omp or
pppm/dielectic or pppm/disp/dielectric or msm or msm/cg or msm/omp or msm/cg/omp or msm/dielectric or
scafacos
none value = none
ewald value = accuracy
accuracy = desired relative error in forces
ewald/dipole value = accuracy
accuracy = desired relative error in forces
ewald/dipole/spin value = accuracy
accuracy = desired relative error in forces
ewald/disp value = accuracy
accuracy = desired relative error in forces
ewald/disp/dipole value = accuracy
accuracy = desired relative error in forces
ewald/omp value = accuracy
accuracy = desired relative error in forces

16.63. kspace_style command 785

LAMMPS Documentation, Release stable 29Sep2021

pppm value = accuracy

accuracy = desired relative error in forces
pppm/cg values = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
pppm/dipole value = accuracy
accuracy = desired relative error in forces
pppm/dipole/spin value = accuracy
accuracy = desired relative error in forces
pppm/disp value = accuracy
accuracy = desired relative error in forces
pppm/tip4p value = accuracy
accuracy = desired relative error in forces
pppm/disp/tip4p value = accuracy
accuracy = desired relative error in forces
pppm/gpu value = accuracy
accuracy = desired relative error in forces
pppm/intel value = accuracy
accuracy = desired relative error in forces
pppm/disp/intel value = accuracy
accuracy = desired relative error in forces
pppm/kk value = accuracy
accuracy = desired relative error in forces
pppm/omp value = accuracy
accuracy = desired relative error in forces
pppm/cg/omp values = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
pppm/disp/omp value = accuracy
accuracy = desired relative error in forces
pppm/tip4p/omp value = accuracy
accuracy = desired relative error in forces
pppm/disp/tip4p/omp value = accuracy
accuracy = desired relative error in forces
pppm/stagger value = accuracy
accuracy = desired relative error in forces
pppm/dielectric value = accuracy
accuracy = desired relative error in forces
pppm/disp/dielectric value = accuracy
accuracy = desired relative error in forces
msm value = accuracy
accuracy = desired relative error in forces
msm/cg value = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
msm/omp value = accuracy
accuracy = desired relative error in forces
msm/cg/omp value = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
msm/dielectric value = accuracy
accuracy = desired relative error in forces
scafacos values = method accuracy
method = fmm or p2nfft or p3m or ewald or direct

786 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

accuracy = desired relative error in forces

16.63.2 Examples

kspace_style pppm 1.0e-4

kspace_style pppm/cg 1.0e-5 1.0e-6
kspace style msm 1.0e-4
kspace style scafacos fmm 1.0e-4
kspace_style none

Used in input scripts:

examples/peptide/in.peptide

16.63.3 Description

Define a long-range solver for LAMMPS to use each timestep to compute long-range Coulombic interactions or long-
range 1/r6 interactions. Most of the long-range solvers perform their computation in K-space, hence the name of this
command.
When such a solver is used in conjunction with an appropriate pair style, the cutoff for Coulombic or 1/rN interactions
is effectively infinite. If the Coulombic case, this means each charge in the system interacts with charges in an infinite
array of periodic images of the simulation domain.
Note that using a long-range solver requires use of a matching pair style to perform consistent short-range pairwise
calculations. This means that the name of the pair style contains a matching keyword to the name of the KSpace style,
as in this table:

Pair style KSpace style

coul/long ewald or pppm
coul/msm msm
lj/long or buck/long disp (for dispersion)
tip4p/long tip4p
dipole/long dipole

The ewald style performs a standard Ewald summation as described in any solid-state physics text.
The ewald/disp style adds a long-range dispersion sum option for 1/r6 potentials and is useful for simulation of inter-
faces (Veld). It also performs standard Coulombic Ewald summations, but in a more efficient manner than the ewald
style. The 1/r6 capability means that Lennard-Jones or Buckingham potentials can be used without a cutoff, i.e. they
become full long-range potentials.
The ewald/disp/dipole style can also be used with point-dipoles, see (Toukmaji).
The ewald/dipole style adds long-range standard Ewald summations for dipole-dipole interactions, see (Toukmaji).
The ewald/dipole/spin style adds long-range standard Ewald summations for magnetic dipole-dipole interactions be-
tween magnetic spins.

The pppm style invokes a particle-particle particle-mesh solver (Hockney) which maps atom charge to a 3d mesh, uses
3d FFTs to solve Poisson’s equation on the mesh, then interpolates electric fields on the mesh points back to the atoms.

16.63. kspace_style command 787

LAMMPS Documentation, Release stable 29Sep2021

It is closely related to the particle-mesh Ewald technique (PME) (Darden) used in AMBER and CHARMM. The cost
3
of traditional Ewald summation scales as N 2 where N is the number of atoms in the system. The PPPM solver scales
as N log N due to the FFTs, so it is almost always a faster choice (Pollock).
The pppm/cg style is identical to the pppm style except that it has an optimization for systems where most particles
are uncharged. Similarly the msm/cg style implements the same optimization for msm. The optional smallq argument
defines the cutoff for the absolute charge value which determines whether a particle is considered charged or not. Its
default value is 1.0e-5.
The pppm/dipole style invokes a particle-particle particle-mesh solver for dipole-dipole interactions, following the
method of (Cerda).
The pppm/dipole/spin style invokes a particle-particle particle-mesh solver for magnetic dipole-dipole interactions be-
tween magnetic spins.
The pppm/tip4p style is identical to the pppm style except that it adds a charge at the massless fourth site in each TIP4P
water molecule. It should be used with pair styles with a tip4p/long in their style name.
The pppm/stagger style performs calculations using two different meshes, one shifted slightly with respect to the other.
This can reduce force aliasing errors and increase the accuracy of the method for a given mesh size. Or a coarser mesh
can be used for the same target accuracy, which saves CPU time. However, there is a trade-off since FFTs on two meshes
are now performed which increases the computation required. See (Cerutti), (Neelov), and (Hockney) for details of the
method.
For high relative accuracy, using staggered PPPM allows the mesh size to be reduced by a factor of 2 in each dimension
as compared to regular PPPM (for the same target accuracy). This can give up to a 4x speedup in the KSpace time
(8x less mesh points, 2x more expensive). However, for low relative accuracy, the staggered PPPM mesh size may be
essentially the same as for regular PPPM, which means the method will be up to 2x slower in the KSpace time (simply
2x more expensive). For more details and timings, see the Speed tips doc page.

Note: Using pppm/stagger may not give the same increase in the accuracy of energy and pressure as it does in forces,
so some caution must be used if energy and/or pressure are quantities of interest, such as when using a barostat.

The pppm/disp and pppm/disp/tip4p styles add a mesh-based long-range dispersion sum option for 1/r^6 potentials
(Isele-Holder), similar to the ewald/disp style. The 1/r^6 capability means that Lennard-Jones or Buckingham poten-
tials can be used without a cutoff, i.e. they become full long-range potentials.
For these styles, you will possibly want to adjust the default choice of parameters by using the kspace_modify command.
This can be done by either choosing the Ewald and grid parameters, or by specifying separate accuracies for the real
and kspace calculations. When not making any settings, the simulation will stop with an error message. Further
information on the influence of the parameters and how to choose them is described in (Isele-Holder), (Isele-Holder2)
and the Howto dispersion doc page.

Note: All of the PPPM styles can be used with single-precision FFTs by using the compiler switch -DFFT_SINGLE
for the FFT_INC setting in your low-level Makefile. This setting also changes some of the PPPM operations (e.g.
mapping charge to mesh and interpolating electric fields to particles) to be performed in single precision. This option
can speed-up long-range calculations, particularly in parallel or on GPUs. The use of the -DFFT_SINGLE flag is
discussed on the Build settings doc page. MSM does not currently support the -DFFT_SINGLE compiler switch.

The msm style invokes a multi-level summation method MSM solver, (Hardy) or (Hardy2), which maps atom charge to
a 3d mesh, and uses a multi-level hierarchy of coarser and coarser meshes on which direct Coulomb solvers are done.

788 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

This method does not use FFTs and scales as N . It may therefore be faster than the other K-space solvers for relatively
large problems when running on large core counts. MSM can also be used for non-periodic boundary conditions and
for mixed periodic and non-periodic boundaries.
MSM is most competitive versus Ewald and PPPM when only relatively low accuracy forces, about 1e-4 relative error
or less accurate, are needed. Note that use of a larger Coulombic cutoff (i.e. 15 angstroms instead of 10 angstroms)
provides better MSM accuracy for both the real space and grid computed forces.
Currently calculation of the full pressure tensor in MSM is expensive. Using the kspace_modify pressure/scalar yes
command provides a less expensive way to compute the scalar pressure (Pxx + Pyy + Pzz)/3.0. The scalar pressure can
be used, for example, to run an isotropic barostat. If the full pressure tensor is needed, then calculating the pressure at
every timestep or using a fixed pressure simulation with MSM will cause the code to run slower.

The scafacos style is a wrapper on the ScaFaCoS Coulomb solver library which provides a variety of solver methods
which can be used with LAMMPS. The paper by (Sutman) gives an overview of ScaFaCoS.
ScaFaCoS was developed by a consortium of German research facilities with a BMBF (German Ministry of Science
and Education) funded project in 2009-2012. Participants of the consortium were the Universities of Bonn, Chemnitz,
Stuttgart, and Wuppertal as well as the Forschungszentrum Juelich.
The library is available for download at “http://scafacos.de” or can be cloned from the git-repository
“git://github.com/scafacos/scafacos.git”.
In order to use this KSpace style, you must download and build the ScaFaCoS library, then build LAMMPS with the
SCAFACOS package installed package which links LAMMPS to the ScaFaCoS library. See details on this page.

Note: Unlike other KSpace solvers in LAMMPS, ScaFaCoS computes all Coulombic interactions, both short- and
long-range. Thus you should NOT use a Coulombic pair style when using kspace_style scafacos. This also means the
total Coulombic energy (short- and long-range) will be tallied for thermodynamic output command as part of the elong
keyword; the ecoul keyword will be zero.

Note: See the current restriction below about use of ScaFaCoS in LAMMPS with molecular charged systems or the
TIP4P water model.

The specified method determines which ScaFaCoS algorithm is used. These are the ScaFaCoS methods currently
available from LAMMPS:
• fmm = Fast Multi-Pole method
• p2nfft = FFT-based Coulomb solver
• ewald = Ewald summation
• direct = direct O(N^2) summation
• p3m = PPPM
We plan to support additional ScaFaCoS solvers from LAMMPS in the future. For an overview of the included solvers,
refer to (Sutmann)
The specified accuracy is similar to the accuracy setting for other LAMMPS KSpace styles, but is passed to ScaFaCoS,
which can interpret it in different ways for different methods it supports. Within the ScaFaCoS library the accuracy
is treated as a tolerance level (either absolute or relative) for the chosen quantity, where the quantity can be either the
Columic field values, the per-atom Columic energy or the total Columic energy. To select from these options, see the
kspace_modify scafacos accuracy doc page.
The kspace_modify scafacos command also explains other ScaFaCoS options currently exposed to LAMMPS.

16.63. kspace_style command 789

LAMMPS Documentation, Release stable 29Sep2021

The specified accuracy determines the relative RMS error in per-atom forces calculated by the long-range solver. It is
set as a dimensionless number, relative to the force that two unit point charges (e.g. 2 monovalent ions) exert on each
other at a distance of 1 Angstrom. This reference value was chosen as representative of the magnitude of electrostatic
forces in atomic systems. Thus an accuracy value of 1.0e-4 means that the RMS error will be a factor of 10000 smaller
than the reference force.
The accuracy setting is used in conjunction with the pairwise cutoff to determine the number of K-space vectors for
style ewald or the grid size for style pppm or msm.
Note that style pppm only computes the grid size at the beginning of a simulation, so if the length or triclinic tilt of the
simulation cell increases dramatically during the course of the simulation, the accuracy of the simulation may degrade.
Likewise, if the kspace_modify slab option is used with shrink-wrap boundaries in the z-dimension, and the box size
changes dramatically in z. For example, for a triclinic system with all three tilt factors set to the maximum limit, the
PPPM grid should be increased roughly by a factor of 1.5 in the y direction and 2.0 in the z direction as compared to the
same system using a cubic orthogonal simulation cell. One way to handle this issue if you have a long simulation where
the box size changes dramatically, is to break it into shorter simulations (multiple run commands). This works because
the grid size is re-computed at the beginning of each run. Another way to ensure the described accuracy requirement
is met is to run a short simulation at the maximum expected tilt or length, note the required grid size, and then use the
kspace_modify mesh command to manually set the PPPM grid size to this value for the long run. The simulation then
will be “too accurate” for some portion of the run.
RMS force errors in real space for ewald and pppm are estimated using equation 18 of (Kolafa), which is also referenced
as equation 9 of (Petersen). RMS force errors in K-space for ewald are estimated using equation 11 of (Petersen),
which is similar to equation 32 of (Kolafa). RMS force errors in K-space for pppm are estimated using equation 38
of (Deserno). RMS force errors for msm are estimated using ideas from chapter 3 of (Hardy), with equation 3.197 of
particular note. When using msm with non-periodic boundary conditions, it is expected that the error estimation will
be too pessimistic. RMS force errors for dipoles when using ewald/disp or ewald/dipole are estimated using equations
33 and 46 of (Wang). The RMS force errors for pppm/dipole are estimated using the equations in (Cerda).
See the kspace_modify command for additional options of the K-space solvers that can be set, including a force option
for setting an absolute RMS error in forces, as opposed to a relative RMS error.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
More specifically, the pppm/gpu style performs charge assignment and force interpolation calculations on the GPU.
These processes are performed either in single or double precision, depending on whether the -DFFT_SINGLE setting
was specified in your low-level Makefile, as discussed above. The FFTs themselves are still calculated on the CPU. If
pppm/gpu is used with a GPU-enabled pair style, part of the PPPM calculation can be performed concurrently on the
GPU while other calculations for non-bonded and bonded force calculation are performed on the CPU.
The pppm/kk style performs charge assignment and force interpolation calculations, along with the FFTs themselves,
on the GPU or (optionally) threaded on the CPU when using OpenMP and FFTW3.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP, and OPT packages respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

790 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.63.4 Restrictions

Note that the long-range electrostatic solvers in LAMMPS assume conducting metal (tinfoil) boundary conditions for
both charge and dipole interactions. Vacuum boundary conditions are not currently supported.
The ewald/disp, ewald, pppm, and msm styles support non-orthogonal (triclinic symmetry) simulation boxes. However,
triclinic simulation cells may not yet be supported by all suffix versions of these styles.
Most of the base kspace styles are part of the KSPACE package. They are only enabled if LAMMPS was built with
that package. See the Build package page for more info.
The msm/dielectric and pppm/dielectric kspace styles are part of the DIELECTRIC package. They are only enabled if
LAMMPS was built with that package and the KSPACE package. See the Build package page for more info.
For MSM, a simulation must be 3d and one can use any combination of periodic, non-periodic, or shrink-wrapped
boundaries (specified using the boundary command).
For Ewald and PPPM, a simulation must be 3d and periodic in all dimensions. The only exception is if the slab option
is set with kspace_modify, in which case the xy dimensions must be periodic and the z dimension must be non-periodic.
The scafacos KSpace style will only be enabled if LAMMPS is built with the SCAFACOS package. See the Build
package doc page for more info.
The use of ScaFaCos in LAMMPS does not yet support molecular charged systems where the short-range Coulombic
interactions between atoms in the same bond/angle/dihedral are weighted by the special_bonds command. Likewise it
does not support the “TIP4P water style” where a fictitious charge site is introduced in each water molecule. Finally,
the methods p3m and ewald do not support computing the virial, so this contribution is not included.

16.63.5 Related commands

kspace_modify, pair_style lj/cut/coul/long, pair_style lj/charmm/coul/long, pair_style lj/long/coul/long, pair_style

buck/coul/long

16.63.6 Default

kspace_style none

(Darden) Darden, York, Pedersen, J Chem Phys, 98, 10089 (1993).

(Deserno) Deserno and Holm, J Chem Phys, 109, 7694 (1998).
(Hockney) Hockney and Eastwood, Computer Simulation Using Particles, Adam Hilger, NY (1989).
(Kolafa) Kolafa and Perram, Molecular Simulation, 9, 351 (1992).
(Petersen) Petersen, J Chem Phys, 103, 3668 (1995).
(Wang) Wang and Holm, J Chem Phys, 115, 6277 (2001).
(Pollock) Pollock and Glosli, Comp Phys Comm, 95, 93 (1996).
(Cerutti) Cerutti, Duke, Darden, Lybrand, Journal of Chemical Theory and Computation 5, 2322 (2009)
(Neelov) Neelov, Holm, J Chem Phys 132, 234103 (2010)
(Veld) In ‘t Veld, Ismail, Grest, J Chem Phys, 127, 144711 (2007).
(Toukmaji) Toukmaji, Sagui, Board, and Darden, J Chem Phys, 113, 10913 (2000).

16.63. kspace_style command 791

LAMMPS Documentation, Release stable 29Sep2021

(Isele-Holder) Isele-Holder, Mitchell, Ismail, J Chem Phys, 137, 174107 (2012).

(Isele-Holder2) Isele-Holder, Mitchell, Hammond, Kohlmeyer, Ismail, J Chem Theory Comput 9, 5412 (2013).
(Hardy) David Hardy thesis: Multilevel Summation for the Fast Evaluation of Forces for the Simulation of
Biomolecules, University of Illinois at Urbana-Champaign, (2006).
(Hardy2) Hardy, Stone, Schulten, Parallel Computing, 35, 164-177 (2009).
(Sutmann) Sutmann, Arnold, Fahrenberger, et. al., Physical review / E 88(6), 063308 (2013)
(Cerda) Cerda, Ballenegger, Lenz, Holm, J Chem Phys 129, 234104 (2008)
(Sutmann) G. Sutmann. ScaFaCoS - a Scalable library of Fast Coulomb Solvers for particle Systems. In Bajaj,
Zavattieri, Koslowski, Siegmund, Proceedings of the Society of Engineering Science 51st Annual Technical
Meeting. 2014.

16.64 label command

16.64.1 Syntax

label ID

• ID = string used as label name

16.64.2 Examples

label xyz
label loop

16.64.3 Description

Label this line of the input script with the chosen ID. Unless a jump command was used previously, this does nothing.
But if a jump command was used with a label argument to begin invoking this script file, then all command lines in
the script prior to this line will be ignored. I.e. execution of the script will begin at this line. This is useful for looping
over a section of the input script as discussed in the jump command.

16.64.4 Restrictions

none

16.64.5 Related commands

none

792 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.64.6 Default

none

16.65 lattice command

16.65.1 Syntax

lattice style scale keyword values ...

• style = none or sc or bcc or fcc or hcp or diamond or sq or sq2 or hex or custom

• scale = scale factor between lattice and simulation box
scale = reduced density rho* (for LJ units)
scale = lattice constant in distance units (for all other units)
• zero or more keyword/value pairs may be appended
• keyword = origin or orient or spacing or a1 or a2 or a3 or basis
origin values = x y z
x,y,z = fractions of a unit cell (0 <= x,y,z < 1)
orient values = dim i j k
dim = x or y or z
i,j,k = integer lattice directions
spacing values = dx dy dz
dx,dy,dz = lattice spacings in the x,y,z box directions
a1,a2,a3 values = x y z
x,y,z = primitive vector components that define unit cell
basis values = x y z
x,y,z = fractional coords of a basis atom (0 <= x,y,z < 1)

16.65.2 Examples

lattice fcc 3.52

lattice hex 0.85
lattice sq 0.8 origin 0.0 0.5 0.0 orient x 1 1 0 orient y -1 1 0
lattice custom 3.52 a1 1.0 0.0 0.0 a2 0.5 1.0 0.0 a3 0.0 0.0 0.5 &
basis 0.0 0.0 0.0 basis 0.5 0.5 0.5
lattice none 2.0

16.65.3 Description

Define a lattice for use by other commands. In LAMMPS, a lattice is simply a set of points in space, determined by a
unit cell with basis atoms, that is replicated infinitely in all dimensions. The arguments of the lattice command can be
used to define a wide variety of crystallographic lattices.
A lattice is used by LAMMPS in two ways. First, the create_atoms command creates atoms on the lattice points
inside the simulation box. Note that the create_atoms command allows different atom types to be assigned to different
basis atoms of the lattice. Second, the lattice spacing in the x,y,z dimensions implied by the lattice, can be used by

16.65. lattice command 793

LAMMPS Documentation, Release stable 29Sep2021

other commands as distance units (e.g. create_box, region and velocity), which are often convenient to use when the
underlying problem geometry is atoms on a lattice.
The lattice style must be consistent with the dimension of the simulation - see the dimension command. Styles sc or
bcc or fcc or hcp or diamond are for 3d problems. Styles sq or sq2 or hex are for 2d problems. Style custom can be
used for either 2d or 3d problems.
A lattice consists of a unit cell, a set of basis atoms within that cell, and a set of transformation parameters (scale, origin,
orient) that map the unit cell into the simulation box. The vectors a1,a2,a3 are the edge vectors of the unit cell. This
is the nomenclature for “primitive” vectors in solid-state crystallography, but in LAMMPS the unit cell they determine
does not have to be a “primitive cell” of minimum volume.
Note that the lattice command can be used multiple times in an input script. Each time it is invoked, the lattice attributes
are re-defined and are used for all subsequent commands (that use lattice attributes). For example, a sequence of lattice,
region, and create_atoms commands can be repeated multiple times to build a poly-crystalline model with different
geometric regions populated with atoms in different lattice orientations.

A lattice of style none does not define a unit cell and basis set, so it cannot be used with the create_atoms command.
However it does define a lattice spacing via the specified scale parameter. As explained above the lattice spacings in
x,y,z can be used by other commands as distance units. No additional keyword/value pairs can be specified for the none
style. By default, a “lattice none 1.0” is defined, which means the lattice spacing is the same as one distance unit, as
defined by the units command.
Lattices of style sc, fcc, bcc, and diamond are 3d lattices that define a cubic unit cell with edge length = 1.0. This means
a1 = 1 0 0, a2 = 0 1 0, and a3 = 0 0 1. Style hcp has a1 = 1 0 0, a2 = 0 sqrt(3) 0, and a3 = 0 0 sqrt(8/3). The placement
of the basis atoms within the unit cell are described in any solid-state physics text. A sc lattice has 1 basis atom at the
lower-left-bottom corner of the cube. A bcc lattice has 2 basis atoms, one at the corner and one at the center of the
cube. A fcc lattice has 4 basis atoms, one at the corner and 3 at the cube face centers. A hcp lattice has 4 basis atoms,
two in the z = 0 plane and 2 in the z = 0.5 plane. A diamond lattice has 8 basis atoms.
Lattices of style sq and sq2 are 2d lattices that define a square unit cell with edge length = 1.0. This means a1 = 1 0 0
and a2 = 0 1 0. A sq lattice has 1 basis atom at the lower-left corner of the square. A sq2 lattice has 2 basis atoms, one
at the corner and one at the center of the square. A hex style is also a 2d lattice, but the unit cell is rectangular, with a1
= 1 0 0 and a2 = 0 sqrt(3) 0. It has 2 basis atoms, one at the corner and one at the center of the rectangle.
A lattice of style custom allows you to specify a1, a2, a3, and a list of basis atoms to put in the unit cell. By default, a1
and a2 and a3 are 3 orthogonal unit vectors (edges of a unit cube). But you can specify them to be of any length and
non-orthogonal to each other, so that they describe a tilted parallelepiped. Via the basis keyword you add atoms, one
at a time, to the unit cell. Its arguments are fractional coordinates (0.0 <= x,y,z < 1.0). The position vector x of a basis
atom within the unit cell is thus a linear combination of the unit cell’s 3 edge vectors, i.e. x = bx a1 + by a2 + bz a3,
where bx,by,bz are the 3 values specified for the basis keyword.

This sub-section discusses the arguments that determine how the idealized unit cell is transformed into a lattice of
points within the simulation box.
The scale argument determines how the size of the unit cell will be scaled when mapping it into the simulation box.
I.e. it determines a multiplicative factor to apply to the unit cell, to convert it to a lattice of the desired size and distance
units in the simulation box. The meaning of the scale argument depends on the units being used in your simulation.
For all unit styles except lj, the scale argument is specified in the distance units defined by the unit style. For example,
in real or metal units, if the unit cell is a unit cube with edge length 1.0, specifying scale = 3.52 would create a cubic
lattice with a spacing of 3.52 Angstroms. In cgs units, the spacing would be 3.52 cm.
For unit style lj, the scale argument is the Lennard-Jones reduced density, typically written as rho*. LAMMPS converts
this value into the multiplicative factor via the formula “factor^dim = rho/rho*”, where rho = N/V with V = the volume
of the lattice unit cell and N = the number of basis atoms in the unit cell (described below), and dim = 2 or 3 for

794 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

the dimensionality of the simulation. Effectively, this means that if LJ particles of size sigma = 1.0 are used in the
simulation, the lattice of particles will be at the desired reduced density.
The origin option specifies how the unit cell will be shifted or translated when mapping it into the simulation box. The
x,y,z values are fractional values (0.0 <= x,y,z < 1.0) meaning shift the lattice by a fraction of the lattice spacing in each
dimension. The meaning of “lattice spacing” is discussed below.
The orient option specifies how the unit cell will be rotated when mapping it into the simulation box. The dim argument
is one of the 3 coordinate axes in the simulation box. The other 3 arguments are the crystallographic direction in the
lattice that you want to orient along that axis, specified as integers. E.g. “orient x 2 1 0” means the x-axis in the
simulation box will be the [210] lattice direction, and similarly for y and z. The 3 lattice directions you specify do not
have to be unit vectors, but they must be mutually orthogonal and obey the right-hand rule, i.e. (X cross Y) points in
the Z direction.

Note: The preceding paragraph describing lattice directions is only valid for orthogonal cubic unit cells (or square in
2d). If you are using a hcp or hex lattice or the more general lattice style custom with non-orthogonal a1,a2,a3 vectors,
then you should think of the 3 orient vectors as creating a 3x3 rotation matrix which is applied to a1,a2,a3 to rotate the
original unit cell to a new orientation in the simulation box.

Several LAMMPS commands have the option to use distance units that are inferred from “lattice spacings” in the x,y,z
box directions. E.g. the region command can create a block of size 10x20x20, where 10 means 10 lattice spacings in
the x direction.

Note: Though they are called lattice spacings, all the commands that have a “units lattice” option, simply use the 3
values as scale factors on the distance units defined by the units command. Thus if you do not like the lattice spacings
computed by LAMMPS (e.g. for a non-orthogonal or rotated unit cell), you can define the 3 values to be whatever you
wish, via the spacing option.

If the spacing option is not specified, the lattice spacings are computed by LAMMPS in the following way. A unit cell
of the lattice is mapped into the simulation box (scaled and rotated), so that it now has (perhaps) a modified size and
orientation. The lattice spacing in X is defined as the difference between the min/max extent of the x coordinates of the
8 corner points of the modified unit cell (4 in 2d). Similarly, the Y and Z lattice spacings are defined as the difference
in the min/max of the y and z coordinates.
Note that if the unit cell is orthogonal with axis-aligned edges (no rotation via the orient keyword), then the lattice
spacings in each dimension are simply the scale factor (described above) multiplied by the length of a1,a2,a3. Thus a
hex style lattice with a scale factor of 3.0 Angstroms, would have a lattice spacing of 3.0 in x and 3*sqrt(3.0) in y.

Note: For non-orthogonal unit cells and/or when a rotation is applied via the orient keyword, then the lattice spacings
computed by LAMMPS are typically less intuitive. In particular, in these cases, there is no guarantee that a particular
lattice spacing is an integer multiple of the periodicity of the lattice in that direction. Thus, if you create an orthogonal
periodic simulation box whose size in a dimension is a multiple of the lattice spacing, and then fill it with atoms via
the create_atoms command, you will NOT necessarily create a periodic system. I.e. atoms may overlap incorrectly at
the faces of the simulation box.

The spacing option sets the 3 lattice spacings directly. All must be non-zero (use 1.0 for dz in a 2d simulation). The
specified values are multiplied by the multiplicative factor described above that is associated with the scale factor. Thus
a spacing of 1.0 means one unit cell edge length independent of the scale factor. As mentioned above, this option can
be useful if the spacings LAMMPS computes are inconvenient to use in subsequent commands, which can be the case
for non-orthogonal or rotated lattices.

16.65. lattice command 795

LAMMPS Documentation, Release stable 29Sep2021

Note that whenever the lattice command is used, the values of the lattice spacings LAMMPS calculates are printed out.
Thus their effect in commands that use the spacings should be decipherable.

√
Example commands for generating a Wurtzite crystal. The lattice constants approximate those of CdSe. The 3 × 1
orthorhombic supercell is used with the x, y, and z directions oriented along [1̄2̄30], [101̄0], and [0001], respectively.

variable a equal 4.34

variable b equal $a*sqrt(3.0)
variable c equal $a*sqrt(8.0/3.0)

variable third equal 1.0/3.0

variable five6 equal 5.0/6.0

lattice custom 1.0 &

a1 $b 0.0 0.0 &
a2 0.0 $a 0.0 &
a3 0.0 0.0 $c &
basis 0.0 0.0 0.0 &
basis 0.5 0.5 0.0 &
basis ${third} 0.0 0.5 &
basis ${five6} 0.5 0.5 &
basis 0.0 0.0 0.625 &
basis 0.5 0.5 0.625 &
basis ${third} 0.0 0.125 &
basis ${five6} 0.5 0.125

region myreg block 0 1 0 1 0 1

create_box 2 myreg
create_atoms 1 box &
basis 5 2 &
basis 6 2 &
basis 7 2 &
basis 8 2

16.65.4 Restrictions

The a1,a2,a3,basis keywords can only be used with style custom.

16.65.5 Related commands

dimension, create_atoms, region

796 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.65.6 Default

lattice none 1.0

For other lattice styles, the option defaults are origin = 0.0 0.0 0.0, orient = x 1 0 0, orient = y 0 1 0, orient = z 0 0 1,
a1 = 1 0 0, a2 = 0 1 0, and a3 = 0 0 1.

16.66 log command

16.66.1 Syntax

log file keyword

• file = name of new logfile

• keyword = append if output should be appended to logfile (optional)

16.66.2 Examples

log log.equil
log log.equil append

16.66.3 Description

This command closes the current LAMMPS log file, opens a new file with the specified name, and begins logging
information to it. If the specified file name is none, then no new log file is opened. If the optional keyword append is
specified, then output will be appended to an existing log file, instead of overwriting it.
If multiple processor partitions are being used, the file name should be a variable, so that different processors do not
attempt to write to the same log file.
The file “log.lammps” is the default log file for a LAMMPS run. The name of the initial log file can also be set by the
-log command-line switch.

16.66.4 Restrictions

none

16.66.5 Related commands

none

16.66. log command 797

LAMMPS Documentation, Release stable 29Sep2021

16.66.6 Default

The default LAMMPS log file is named log.lammps

16.67 mass command

16.67.1 Syntax

mass I value

• I = atom type (see asterisk form below)

• value = mass

16.67.2 Examples

mass 1 1.0
mass * 62.5
mass 2* 62.5

16.67.3 Description

Set the mass for all atoms of one or more atom types. Per-type mass values can also be set in the read_data data file
using the “Masses” keyword. See the units command for what mass units to use.
The I index can be specified in one of two ways. An explicit numeric value can be used, as in the first example above.
Or a wild-card asterisk can be used to set the mass for multiple atom types. This takes the form “*” or “*n” or “n*”
or “m*n”. If N = the number of atom types, then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A
middle asterisk means all types from m to n (inclusive).
A line in a data file that follows the “Masses” keyword specifies mass using the same format as the arguments of the
mass command in an input script, except that no wild-card asterisk can be used. For example, under the “Masses”
section of a data file, the line that corresponds to the first example above would be listed as

1 1.0

Note that the mass command can only be used if the atom style requires per-type atom mass to be set. Currently, all
but the sphere and ellipsoid and peri styles do. They require mass to be set for individual particles, not types. Per-
atom masses are defined in the data file read by the read_data command, or set to default values by the create_atoms
command. Per-atom masses can also be set to new values by the set mass or set density commands.
Also note that pair_style eam and pair_style bop commands define the masses of atom types in their respective potential
files, in which case the mass command is normally not used.
If you define a hybrid atom style which includes one (or more) sub-styles which require per-type mass and one (or
more) sub-styles which require per-atom mass, then you must define both. However, in this case the per-type mass will
be ignored; only the per-atom mass will be used by LAMMPS.

798 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.67.4 Restrictions

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.
All masses must be defined before a simulation is run. They must also all be defined before a velocity or fix shake
command is used.
The mass assigned to any type or atom must be > 0.0.

16.67.5 Related commands

none

16.67.6 Default

none

16.68 mdi_engine command

16.68.1 Syntax

mdi_engine

16.68.2 Description

This command is used to have LAMMPS act as a server with another client code to effectively couple the two codes
together in client/server mode.
More specifically, this command causes LAMMPS to begin using the MDI Library to run as an MDI engine (server),
responding to commands made by an external MDI driver code (client). See the Howto mdi page for more information
about how LAMMPS can work as both an MDI driver or engine.
General information about launching codes that communicate using the MDI Library can be found in the corresponding
page of the MDI Library’s documentation.

This command should typically be used in an input script after LAMMPS has setup the system it is going to model
in collaboration with the driver code. Depending on how the driver code tells the LAMMPS engine to exit, other
commands can be executed after this command, but typically it should be used at the end of the LAMMPS input script.
To act as a MD-based MDI engine, this is the list of MDI commands from a driver code which LAMMPS currently
recognizes. See more details about these commands in the MDI library documentation .. NOTE: Taylor - is this the
best link for this info? Can we flesh this .. out with the full list of supported commands? Maybe the distinction .. of
what “node” the commands refer to is not needed in this table?

16.68. mdi_engine command 799

LAMMPS Documentation, Release stable 29Sep2021

Command name Action

>NATOMS Driver sends the number of atoms in the system
<NATOMS Driver requests the number of atoms in the system
<COORDS Driver requests 3*N double-precision atom coordinates
>FORCES Driver sends 3*N double-precision atom forces
<COORDS Driver requests 3*N double-precision atom forces
EXIT Driver tells the engine (LAMMPS) to exit engine mode

If these commands are not sufficient to support what a driver which you write needs, additional commands can be
defined by simply using a new command name not in this list. Code to support the new command needs to be added to
the MDI package within LAMMPS; see its src/MDI/mdi_engine.cpp and fix_mdi_engine.cpp files.

16.68.3 Restrictions

This command is part of the MDI package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

16.68.4 Related commands

fix mdi/engine

16.68.5 Default

None

16.69 message command

16.69.1 Syntax

message which protocol mode arg

• which = client or server or quit

• protocol = md or mc
• mode = file or zmq or mpi/one or mpi/two
file arg = filename
filename = file used for message exchanges
zmq arg = socket-ID
socket-ID for client = localhost:5555, see description below
socket-ID for server = *:5555, see description below
mpi/one arg = none
mpi/two arg = filename
filename = file used to establish communication between 2 MPI jobs

800 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.69.2 Examples

message client md file tmp.couple

message server md file tmp.couple

message client md zmq localhost:5555

message server md zmq *:5555

message client md mpi/one

message server md mpi/one

message client md mpi/two tmp.couple

message server md mpi/two tmp.couple

message quit

16.69.3 Description

Establish a messaging protocol between LAMMPS and another code for the purpose of client/server coupling.
The Howto client/server page gives an overview of client/server coupling of LAMMPS with another code where one
code is the “client” and sends request messages to a “server” code. The server responds to each request with a reply
message. This enables the two codes to work in tandem to perform a simulation.

The which argument defines LAMMPS to be the client or the server.

As explained below the quit option should be used when LAMMPS is finished as a client. It sends a message to the
server to tell it to shut down.

The protocol argument defines the format and content of messages that will be exchanged between the two codes. The
current options are:
• md = run dynamics with another code
• mc = perform Monte Carlo moves with another code
For protocol md, LAMMPS can be either a client or server. See the server md page for details on the protocol.
For protocol mc, LAMMPS can be the server. See the server mc page for details on the protocol.

The mode argument specifies how messages are exchanged between the client and server codes. Both codes must use
the same mode and use consistent parameters.
For mode file, the 2 codes communicate via binary files. They must use the same filename, which is actually a file
prefix. Several files with that prefix will be created and deleted as a simulation runs. The filename can include a path.
Both codes must be able to access the path/file in a common filesystem.
For mode zmq, the 2 codes communicate via a socket on the server code’s machine. Support for socket messaging
is provided by the open-source ZeroMQ library, which must be installed on your system. The client specifies an IP
address (IPv4 format) or the DNS name of the machine the server code is running on, followed by a 4 or 5 digit port
ID for the socket, separated by a colon. E.g.

16.69. message command 801

LAMMPS Documentation, Release stable 29Sep2021

localhost:5555 # client and server running on same machine

192.168.1.1:5555 # server is 192.168.1.1
deptbox.uni.edu:5555 # server is deptbox.uni.edu

The server specifies “*:5555” where “*” represents all available interfaces on the server’s machine, and the port ID
must match what the client specifies.

Note: On Linux or Unix machines port IDs below 1024 are reserved to the superuser and thus not available. Other
ports may already be in use and cannot be opened by a second process. On a Linux machine the commands “netstat
-t4an” or “ss -t4an” will list all locally used port IDs for IPv4 addresses.

Note: On many machines (and sometimes on local networks) also ports IDs may be blocked by default through
firewalls. In that case either access to the required port (or a desired range of ports) has to be selectively enabled to the
firewall disabled (the latter is usually not a good idea unless you are on a (small) local network that is already protected
from outside access.

Note: Additional explanation is needed here about how to use the zmq mode on a parallel machine, e.g. a cluster with
many nodes.

For mode mpi/one, the 2 codes communicate via MPI and are launched by the same mpirun command, e.g. with this
syntax for OpenMPI:

mpirun -np 2 lmp_mpi -mpicolor 0 -in in.client -log log.client : -np 4 othercode args #␣
,→LAMMPS is client

mpirun -np 2 othercode args : -np 4 lmp_mpi -mpicolor 1 -in in.server # LAMMPS is server

Note the use of the “-mpicolor color” command-line argument with LAMMPS. See the command-line args page for
further explanation.
For mode mpi/two, the 2 codes communicate via MPI, but are launched be 2 separate mpirun commands. The specified
filename argument is a file the 2 MPI processes will use to exchange info so that an MPI inter-communicator can be
established to enable the 2 codes to send MPI messages to each other. Both codes must be able to access the path/file
in a common filesystem.

Normally, the message client or message server command should be used at the top of a LAMMPS input script. It
performs an initial handshake with the other code to setup messaging and to verify that both codes are using the same
message protocol and mode. Assuming both codes are launched at (nearly) the same time, the other code should
perform the same kind of initialization.
If LAMMPS is the client code, it will begin sending messages when a LAMMPS client command begins its operation.
E.g. for the fix client/md command, it is when a run command is executed.
If LAMMPS is the server code, it will begin receiving messages when the server command is invoked.
If LAMMPS is being used as a client, the message quit command will terminate its messaging with the server. If you
do not use this command and just allow LAMMPS to exit, then the server will continue to wait for further messages.
This may not be a problem, but if both the client and server programs were launched in the same batch script, then if
the server runs indefinitely, it may consume the full allocation of computer time, even if the calculation finishes sooner.
Note that if LAMMPS is the client or server, it will continue processing the rest of its input script after client/server
communication terminates.

802 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

If both codes cooperate in this manner, a new round of client/server messaging can be initiated after termination by
re-using a second message command in your LAMMPS input script, followed by a new fix client or server command,
followed by another message quit command (if LAMMPS is the client). As an example, this can be performed in a loop
to use a quantum code as a server to compute quantum forces for multiple LAMMPS data files or periodic snapshots
while running dynamics.

16.69.4 Restrictions

This command is part of the MESSAGE package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.

16.69.5 Related commands

server, fix client/md

16.69.6 Default

none

16.70 min_modify command

16.70.1 Syntax

min_modify keyword values ...

• one or more keyword/value pairs may be listed

keyword = dmax or line or norm or alpha_damp or discrete_factor or integrator or␣
,→tmax

dmax value = max

max = maximum distance for line search to move (distance units)
line value = backtrack or quadratic or forcezero or spin_cubic or spin_none
backtrack,quadratic,forcezero,spin_cubic,spin_none = style of linesearch to use
norm value = two or inf or max
two = Euclidean two-norm (length of 3N vector)
inf = max force component across all 3-vectors
max = max force norm across all 3-vectors
alpha_damp value = damping
damping = fictitious Gilbert damping for spin minimization (adim)
discrete_factor value = factor
factor = discretization factor for adaptive spin timestep (adim)
integrator value = eulerimplicit or verlet
time integration scheme for fire minimization
tmax value = factor
factor = maximum adaptive timestep for fire minimization (adim)

16.70. min_modify command 803

LAMMPS Documentation, Release stable 29Sep2021

16.70.2 Examples

min_modify dmax 0.2

min_modify integrator verlet tmax 4

16.70.3 Description

This command sets parameters that affect the energy minimization algorithms selected by the min_style command. The
various settings may affect the convergence rate and overall number of force evaluations required by a minimization,
so users can experiment with these parameters to tune their minimizations.
The cg and sd minimization styles have an outer iteration and an inner iteration which is steps along a one-dimensional
line search in a particular search direction. The dmax parameter is how far any atom can move in a single line search
in any dimension (x, y, or z). For the quickmin and fire minimization styles, the dmax setting is how far any atom
can move in a single iteration (timestep). Thus a value of 0.1 in real units means no atom will move further than 0.1
Angstroms in a single outer iteration. This prevents highly overlapped atoms from being moved long distances (e.g.
through another atom) due to large forces.
The choice of line search algorithm for the cg and sd minimization styles can be selected via the line keyword. The
default quadratic line search algorithm starts out using the robust backtracking method described below. However,
once the system gets close to a local minimum and the linesearch steps get small, so that the energy is approximately
quadratic in the step length, it uses the estimated location of zero gradient as the linesearch step, provided the energy
change is downhill. This becomes more efficient than backtracking for highly-converged relaxations. The forcezero
line search algorithm is similar to quadratic. It may be more efficient than quadratic on some systems.
The backtracking search is robust and should always find a local energy minimum. However, it will “converge” when
it can no longer reduce the energy of the system. Individual atom forces may still be larger than desired at this point,
because the energy change is measured as the difference of two large values (energy before and energy after) and that
difference may be smaller than machine epsilon even if atoms could move in the gradient direction to reduce forces
further.
The choice of a norm can be modified for the min styles cg, sd, quickmin, fire, fire/old, spin, spin/cg and spin/lbfgs
using the norm keyword. The default two norm computes the 2-norm (Euclidean length) of the global force vector:
q
||F ||2 = F~12 + · · · + F~N2
~

The max norm computes the length of the 3-vector force for each atom (2-norm), and takes the maximum value of
those across all atoms
 
||F~ ||max = max ||F~1 ||, · · · , ||F~N ||

The inf norm takes the maximum component across the forces of all atoms in the system:

||F~ ||inf = max |F11 |, |F12 |, |F13 | · · · , |FN1 |, |FN2 |, |FN3 |

For the min styles spin, spin/cg and spin/lbfgs, the force norm is replaced by the spin-torque norm.
Keywords alpha_damp and discrete_factor only make sense when a min_spin command is declared. Keyword al-
pha_damp defines an analog of a magnetic Gilbert damping. It defines a relaxation rate toward an equilibrium for a
given magnetic system. Keyword discrete_factor defines a discretization factor for the adaptive timestep used in the
spin minimization. See min_spin for more information about those quantities.
The choice of a line search algorithm for the spin/cg and spin/lbfgs styles can be specified via the line keyword. The
spin_cubic and spin_none keywords only make sense when one of those two minimization styles is declared. The
spin_cubic performs the line search based on a cubic interpolation of the energy along the search direction. The

804 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

spin_none keyword deactivates the line search procedure. The spin_none is a default value for line keyword for both
spin/lbfgs and spin/cg. Convergence of spin/lbfgs can be more robust if spin_cubic line search is used.
The Newton integrator used for fire minimization can be selected to be either the symplectic Euler (eulerimplicit) or
velocity Verlet (verlet). tmax defines the maximum value for the adaptive timestep during a fire minimization. It is a
multiplication factor applied to the current timestep (not in time unit). For example, tmax = 4.0 with a timestep of 2fs,
means that the maximum value the timestep can reach during a fire minimization is 4fs. Note that parameter defaults
has been chosen to be reliable in most cases, but one should consider adjusting timestep and tmax to optimize the
minimization for large or complex systems. Other parameters of the fire minimization can be tuned (tmin, delaystep,
dtgrow, dtshrink, alpha0, and alphashrink). Please refer to the references describing the min_style fire. An additional
stopping criteria vdfmax is used by fire in order to avoid unnecessary looping when it is reasonable to think the system
will not be relaxed further. Note that in this case the system will NOT have reached your minimization criteria. This
could happen when the system comes to be stuck in a local basin of the phase space. vdfmax is the maximum number
of consecutive iterations with P(t) < 0.
The min_style fire is an optimized implementation of min_style fire/old. It can however behave similarly to the fire/old
style by using the following set of parameters:

min_modify integrator eulerexplicit tmax 10.0 tmin 0.0 delaystep 5 &

dtgrow 1.1 dtshrink 0.5 alpha0 0.1 alphashrink 0.99 &
vdfmax 100000 halfstepback no initialdelay no

16.70.4 Restrictions

For magnetic GNEB calculations, only spin_none value for line keyword can be used when minimization styles spin/cg
and spin/lbfgs are employed. See neb/spin for more explanation.

16.70.5 Related commands

min_style, minimize

16.70.6 Default

The option defaults are dmax = 0.1, line = quadratic and norm = two.
For the spin, spin/cg and spin/lbfgs styles, the option defaults are alpha_damp = 1.0, discrete_factor = 10.0, line =
spin_none, and norm = euclidean.
For the fire style, the option defaults are integrator = eulerimplicit, tmax = 10.0, tmin = 0.02, delaystep = 20, dtgrow =
1.1, dtshrink = 0.5, alpha0 = 0.25, alphashrink = 0.99, vdfmax = 2000, halfstepback = yes and initialdelay = yes.

16.70. min_modify command 805

LAMMPS Documentation, Release stable 29Sep2021

16.71 min_style spin command

16.72 min_style spin/cg command

16.73 min_style spin/lbfgs command

16.73.1 Syntax

min_style spin
min_style spin/cg
min_style spin/lbfgs

16.73.2 Examples

min_style spin/lbfgs
min_modify line spin_cubic discrete_factor 10.0

16.73.3 Description

Apply a minimization algorithm to use when a minimize command is performed.

Style spin defines a damped spin dynamics with an adaptive timestep, according to:

d~si
= λ ~si × (~
ωi × ~si )
dt
with λ a damping coefficient (similar to a Gilbert damping). λ can be defined by setting the alpha_damp keyword with
the min_modify command.
The minimization procedure solves this equation using an adaptive timestep. The value of this timestep is defined by
the largest precession frequency that has to be solved in the system:
2π
∆tmax =
κ |~
ωmax |

with |~
ωmax | the norm of the largest precession frequency in the system (across all processes, and across all replicas if
a spin/neb calculation is performed).
κ defines a discretization factor discrete_factor for the definition of this timestep. discrete_factor can be defined with
the min_modify command.
Style spin/cg defines an orthogonal spin optimization (OSO) combined to a conjugate gradient (CG) algorithm. The
min_modify command can be used to couple the spin/cg to a line search procedure, and to modify the discretization
factor discrete_factor. By default, style spin/cg does not employ the line search procedure and uses the adaptive time-
step technique in the same way as style spin.
Style spin/lbfgs defines an orthogonal spin optimization (OSO) combined to a limited-memory Broyden-Fletcher-
Goldfarb-Shanno (L-BFGS) algorithm. By default, style spin/lbfgs does not employ line search procedure. If the
line search procedure is not used then the discrete factor defines the maximum root mean squared rotation angle of
spins by equation pi/(5*Kappa). The default value for Kappa is 10. The spin_cubic line search option can improve the
convergence of the spin/lbfgs algorithm.

806 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The min_modify command can be used to activate the line search procedure, and to modify the discretization factor
discrete_factor.
For more information about styles spin/cg and spin/lbfgs, see their implementation reported in (Ivanov).

Note: All the spin styles replace the force tolerance by a torque tolerance. See minimize for more explanation.

Note: The spin/cg and spin/lbfgs styles can be used for magnetic NEB calculations only if the line search procedure
is deactivated. See neb/spin for more explanation.

16.73.4 Restrictions

This minimization procedure is only applied to spin degrees of freedom for a frozen lattice configuration.

16.73.5 Related commands

min_style, minimize, min_modify

16.73.6 Default

The option defaults are alpha_damp = 1.0, discrete_factor = 10.0, line = spin_none and norm = euclidean.

(Ivanov) Ivanov, Uzdin, Jonsson. arXiv preprint arXiv:1904.02669, (2019).

16.74 min_style command

16.74.1 Syntax

min_style style

• style = cg or hftn or sd or quickmin or fire or fire/old or spin or spin/cg or spin/lbfgs

16.74.2 Examples

min_style cg
min_style spin
min_style fire

16.74. min_style command 807

LAMMPS Documentation, Release stable 29Sep2021

16.74.3 Description

Choose a minimization algorithm to use when a minimize command is performed.

Style cg is the Polak-Ribiere version of the conjugate gradient (CG) algorithm. At each iteration the force gradient is
combined with the previous iteration information to compute a new search direction perpendicular (conjugate) to the
previous search direction. The PR variant affects how the direction is chosen and how the CG method is restarted when
it ceases to make progress. The PR variant is thought to be the most effective CG choice for most problems.
Style hftn is a Hessian-free truncated Newton algorithm. At each iteration a quadratic model of the energy potential is
solved by a conjugate gradient inner iteration. The Hessian (second derivatives) of the energy is not formed directly, but
approximated in each conjugate search direction by a finite difference directional derivative. When close to an energy
minimum, the algorithm behaves like a Newton method and exhibits a quadratic convergence rate to high accuracy. In
most cases the behavior of hftn is similar to cg, but it offers an alternative if cg seems to perform poorly. This style is
not affected by the min_modify command.
Style sd is a steepest descent algorithm. At each iteration, the search direction is set to the downhill direction corre-
sponding to the force vector (negative gradient of energy). Typically, steepest descent will not converge as quickly as
CG, but may be more robust in some situations.
Style quickmin is a damped dynamics method described in (Sheppard), where the damping parameter is related to the
projection of the velocity vector along the current force vector for each atom. The velocity of each atom is initialized
to 0.0 by this style, at the beginning of a minimization.
Style fire is a damped dynamics method described in (Bitzek), which is similar to quickmin but adds a variable timestep
and alters the projection operation to maintain components of the velocity non-parallel to the current force vector. The
velocity of each atom is initialized to 0.0 by this style, at the beginning of a minimization. This style correspond to an
optimized version described in (Guenole) that include different time integration schemes and defaults parameters. The
default parameters can be modified with the command min_modify.
Style fire/old is the original implementation of fire in Lammps, conserved for backward compatibility. The main differ-
ences regarding the current version fire are: time integration by Explicit Euler only, different sequence in maintaining
velocity components non-parallel to the current force vector and hard-coded minimization parameters. A complete
description of the differences between fire/old and fire can be found in (Guenole) (where the current fire in LAMMPS
is called fire2.0). By using an appropriate set of parameters, fire can behave similar to fire/old, as described in the
min_modify command.
Style spin is a damped spin dynamics with an adaptive timestep.
Style spin/cg uses an orthogonal spin optimization (OSO) combined to a conjugate gradient (CG) approach to minimize
spin configurations.
Style spin/lbfgs uses an orthogonal spin optimization (OSO) combined to a limited-memory Broyden-Fletcher-
Goldfarb-Shanno (LBFGS) approach to minimize spin configurations.
See the min/spin page for more information about the spin, spin/cg and spin/lbfgs styles.
Either the quickmin, fire and fire/old styles are useful in the context of nudged elastic band (NEB) calculations via the
neb command.
Either the spin, spin/cg and spin/lbfgs styles are useful in the context of magnetic geodesic nudged elastic band (GNEB)
calculations via the neb/spin command.

Note: The damped dynamic minimizers use whatever timestep you have defined via the timestep command. Often
they will converge more quickly if you use a timestep about 10x larger than you would normally use for dynamics
simulations. For fire, the default timestep is recommended to be equal to the one you would normally use for dynamics
simulations.

808 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Note: The quickmin, fire, fire/old, hftn, and cg/kk styles do not yet support the use of the fix box/relax command or
minimizations involving the electron radius in eFF models.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

16.74.4 Restrictions

none

16.74.5 Related commands

min_modify, minimize, neb

16.74.6 Default

min_style cg

(Sheppard) Sheppard, Terrell, Henkelman, J Chem Phys, 128, 134106 (2008). See ref 1 in this paper for original
reference to Qmin in Jonsson, Mills, Jacobsen.
(Bitzek) Bitzek, Koskinen, Gahler, Moseler, Gumbsch, Phys Rev Lett, 97, 170201 (2006).
(Guenole) Guenole, Noehring, Vaid, Houlle, Xie, Prakash, Bitzek, Comput Mater Sci, 175, 109584 (2020).

16.75 minimize command

16.76 minimize/kk command

16.76.1 Syntax

minimize etol ftol maxiter maxeval

• etol = stopping tolerance for energy (unitless)

16.75. minimize command 809

LAMMPS Documentation, Release stable 29Sep2021

• ftol = stopping tolerance for force (force units)

• maxiter = max iterations of minimizer
• maxeval = max number of force/energy evaluations

16.76.2 Examples

minimize 1.0e-4 1.0e-6 100 1000

minimize 0.0 1.0e-8 1000 100000

16.76.3 Description

Perform an energy minimization of the system, by iteratively adjusting atom coordinates. Iterations are terminated
when one of the stopping criteria is satisfied. At that point the configuration will hopefully be in local potential energy
minimum. More precisely, the configuration should approximate a critical point for the objective function (see below),
which may or may not be a local minimum.
The minimization algorithm used is set by the min_style command. Other options are set by the min_modify command.
Minimize commands can be interspersed with run commands to alternate between relaxation and dynamics. The
minimizers bound the distance atoms move in one iteration, so that you can relax systems with highly overlapped
atoms (large energies and forces) by pushing the atoms off of each other.
Alternate means of relaxing a system are to run dynamics with a small or limited timestep. Or dynamics can be run
using fix viscous to impose a damping force that slowly drains all kinetic energy from the system. The pair_style soft
potential can be used to un-overlap atoms while running dynamics. un-overlap atoms while running dynamics.
Note that you can minimize some atoms in the system while holding the coordinates of other atoms fixed by applying
fix setforce to the other atoms. See a fuller discussion of using fixes while minimizing below.
The minimization styles cg, sd, and hftn involves an outer iteration loop which sets the search direction along which
atom coordinates are changed. An inner iteration is then performed using a line search algorithm. The line search
typically evaluates forces and energies several times to set new coordinates. Currently, a backtracking algorithm is
used which may not be optimal in terms of the number of force evaluations performed, but appears to be more robust
than previous line searches we have tried. The backtracking method is described in Nocedal and Wright’s Numerical
Optimization (Procedure 3.1 on p 41).
The minimization styles quickmin, fire and fire/old perform damped dynamics using an Euler integration step. Thus
they require a timestep be defined.

Note: The damped dynamic minimizers use whatever timestep you have defined via the timestep command. Often
they will converge more quickly if you use a timestep about 10x larger than you would normally use for dynamics
simulations.

In all cases, the objective function being minimized is the total potential energy of the system as a function of the N
atom coordinates:
X X X
E(r1 , r2 , . . . , rN ) = Epair (ri , rj ) + Ebond (ri , rj ) + Eangle (ri , rj , rk )+
i,j ij ijk
X X X
Edihedral (ri , rj , rk , rl ) + Eimproper (ri , rj , rk , rl ) + Efix (ri )
ijkl ijkl i

810 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

where the first term is the sum of all non-bonded pairwise interactions including long-range Coulombic interactions,
the second through fifth terms are bond, angle, dihedral, and improper interactions respectively, and the last term is
energy due to fixes which can act as constraints or apply force to atoms, such as through interaction with a wall. See
the discussion below about how fix commands affect minimization.
The starting point for the minimization is the current configuration of the atoms.

The minimization procedure stops if any of several criteria are met:

• the change in energy between outer iterations is less than etol
• the 2-norm (length) of the global force vector is less than the ftol
• the line search fails because the step distance backtracks to 0.0
• the number of outer iterations or timesteps exceeds maxiter
• the number of total force evaluations exceeds maxeval

Note: the minimization style spin, spin/cg, and spin/lbfgs replace the force tolerance ftol by a torque tolerance. The
minimization procedure stops if the 2-norm (length) of the torque vector on atom (defined as the cross product between
the atomic spin and its precession vectors omega) is less than ftol, or if any of the other criteria are met. Torque have
the same units as the energy.

Note: You can also use the fix halt command to specify a general criterion for exiting a minimization, that is a
calculation performed on the state of the current system, as defined by an equal-style variable.

For the first criterion, the specified energy tolerance etol is unitless; it is met when the energy change between successive
iterations divided by the energy magnitude is less than or equal to the tolerance. For example, a setting of 1.0e-4 for
etol means an energy tolerance of one part in 10^4. For the damped dynamics minimizers this check is not performed
for a few steps after velocities are reset to 0, otherwise the minimizer would prematurely converge.
For the second criterion, the specified force tolerance ftol is in force units, since it is the length of the global force vector
for all atoms, e.g. a vector of size 3N for N atoms. Since many of the components will be near zero after minimization,
you can think of ftol as an upper bound on the final force on any component of any atom. For example, a setting of
1.0e-4 for ftol means no x, y, or z component of force on any atom will be larger than 1.0e-4 (in force units) after
minimization.
Either or both of the etol and ftol values can be set to 0.0, in which case some other criterion will terminate the
minimization.
During a minimization, the outer iteration count is treated as a timestep. Output is triggered by this timestep, e.g.
thermodynamic output or dump and restart files.
Using the thermo_style custom command with the fmax or fnorm keywords can be useful for monitoring the progress
of the minimization. Note that these outputs will be calculated only from forces on the atoms, and will not include any
extra degrees of freedom, such as from the fix box/relax command.
Following minimization, a statistical summary is printed that lists which convergence criterion caused the minimizer
to stop, as well as information about the energy, force, final line search, and iteration counts. An example is as follows:

Minimization stats:
Stopping criterion = max iterations
Energy initial, next-to-last, final =
-0.626828169302 -2.82642039062 -2.82643549739
(continues on next page)

16.76. minimize/kk command 811

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

Force two-norm initial, final = 2052.1 91.9642
Force max component initial, final = 346.048 9.78056
Final line search alpha, max atom move = 2.23899e-06 2.18986e-05
Iterations, force evaluations = 2000 12724

The 3 energy values are for before and after the minimization and on the next-to-last iteration. This is what the etol
parameter checks.
The two-norm force values are the length of the global force vector before and after minimization. This is what the ftol
parameter checks.
The max-component force values are the absolute value of the largest component (x,y,z) in the global force vector, i.e.
the infinity-norm of the force vector.
The alpha parameter for the line-search, when multiplied by the max force component (on the last iteration), gives the
max distance any atom moved during the last iteration. Alpha will be 0.0 if the line search could not reduce the energy.
Even if alpha is non-zero, if the “max atom move” distance is tiny compared to typical atom coordinates, then it is
possible the last iteration effectively caused no atom movement and thus the evaluated energy did not change and the
minimizer terminated. Said another way, even with non-zero forces, it’s possible the effect of those forces is to move
atoms a distance less than machine precision, so that the energy cannot be further reduced.
The iterations and force evaluation values are what is checked by the maxiter and maxeval parameters.

Note: There are several force fields in LAMMPS which have discontinuities or other approximations which may
prevent you from performing an energy minimization to high tolerances. For example, you should use a pair style that
goes to 0.0 at the cutoff distance when performing minimization (even if you later change it when running dynamics).
If you do not do this, the total energy of the system will have discontinuities when the relative distance between any pair
of atoms changes from cutoff+epsilon to cutoff-epsilon and the minimizer may behave poorly. Some of the many-body
potentials use splines and other internal cutoffs that inherently have this problem. The long-range Coulombic styles
(PPPM, Ewald) are approximate to within the user-specified tolerance, which means their energy and forces may not
agree to a higher precision than the Kspace-specified tolerance. In all these cases, the minimizer may give up and stop
before finding a minimum to the specified energy or force tolerance.

Note that a cutoff Lennard-Jones potential (and others) can be shifted so that its energy is 0.0 at the cutoff via the
pair_modify command. See the doc pages for individual pair styles for details. Note that Coulombic potentials al-
ways have a cutoff, unless versions with a long-range component are used (e.g. pair_style lj/cut/coul/long). The
CHARMM potentials go to 0.0 at the cutoff (e.g. pair_style lj/charmm/coul/charmm), as do the GROMACS potentials
(e.g. pair_style lj/gromacs).
If a soft potential (pair_style soft) is used the Astop value is used for the prefactor (no time dependence).
The fix box/relax command can be used to apply an external pressure to the simulation box and allow it to shrink/expand
during the minimization.
Only a few other fixes (typically those that add forces) are invoked during minimization. See the doc pages for individual
fix commands to see which ones are relevant. Current examples of fixes that can be used include:
• fix addforce
• fix addtorque
• fix efield
• fix enforce2d
• fix indent

812 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• fix lineforce
• fix planeforce
• fix setforce
• fix spring
• fix spring/self
• fix viscous
• fix wall
• fix wall/region

Note: Some fixes which are invoked during minimization have an associated potential energy. For that energy to be
included in the total potential energy of the system (the quantity being minimized), you MUST enable the fix_modify
energy option for that fix. The doc pages for individual fix commands specify if this should be done.

Note: The minimizers in LAMMPS do not allow for bonds (or angles, etc) to be held fixed while atom coordinates
are being relaxed, e.g. via fix shake or fix rigid. See more info in the Restrictions section below.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

16.76.4 Restrictions

Features that are not yet implemented are listed here, in case someone knows how they could be coded:
It is an error to use fix shake with minimization because it turns off bonds that should be included in the potential energy
of the system. The effect of a fix shake can be approximated during a minimization by using stiff spring constants for
the bonds and/or angles that would normally be constrained by the SHAKE algorithm.
Fix rigid is also not supported by minimization. It is not an error to have it defined, but the energy minimization will
not keep the defined body(s) rigid during the minimization. Note that if bonds, angles, etc internal to a rigid body have
been turned off (e.g. via neigh_modify exclude), they will not contribute to the potential energy which is probably not
what is desired.
Pair potentials that produce torque on a particle (e.g. granular potentials or the GayBerne potential for ellipsoidal
particles) are not relaxed by a minimization. More specifically, radial relaxations are induced, but no rotations are
induced by a minimization, so such a system will not fully relax.

16.76. minimize/kk command 813

LAMMPS Documentation, Release stable 29Sep2021

16.76.5 Related commands

min_modify, min_style, run_style

16.76.6 Default

none

16.77 molecule command

16.77.1 Syntax

molecule ID file1 keyword values ... file2 keyword values ... fileN ...

• ID = user-assigned name for the molecule template

• file1,file2,. . . = names of files containing molecule descriptions
• zero or more keyword/value pairs may be appended after each file
• keyword = offset or toff or boff or aoff or doff or ioff or scale
offset values = Toff Boff Aoff Doff Ioff
Toff = offset to add to atom types
Boff = offset to add to bond types
Aoff = offset to add to angle types
Doff = offset to add to dihedral types
Ioff = offset to add to improper types
toff value = Toff
Toff = offset to add to atom types
boff value = Boff
Boff = offset to add to bond types
aoff value = Aoff
Aoff = offset to add to angle types
doff value = Doff
Doff = offset to add to dihedral types
ioff value = Ioff
Ioff = offset to add to improper types
scale value = sfactor
sfactor = scale factor to apply to the size and mass of the molecule

16.77.2 Examples

molecule 1 mymol.txt
molecule 1 co2.txt h2o.txt
molecule CO2 co2.txt boff 3 aoff 2
molecule 1 mymol.txt offset 6 9 18 23 14
molecule objects file.1 scale 1.5 file.1 scale 2.0 file.2 scale 1.3

814 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.77.3 Description

Define a molecule template that can be used as part of other LAMMPS commands, typically to define a collection of
particles as a bonded molecule or a rigid body. Commands that currently use molecule templates include:
• fix deposit
• fix pour
• fix rigid/small
• fix shake
• fix gcmc
• fix bond/react
• create_atoms
• atom_style template
The ID of a molecule template can only contain alphanumeric characters and underscores.
A single template can contain multiple molecules, listed one per file. Some of the commands listed above currently
use only the first molecule in the template, and will issue a warning if the template contains multiple molecules. The
atom_style template command allows multiple-molecule templates to define a system with more than one templated
molecule.
Each filename can be followed by optional keywords which are applied only to the molecule in the file as used in this
template. This is to make it easy to use the same molecule file in different molecule templates or in different simulations.
You can specify the same file multiple times with different optional keywords.
The offset, toff, boff, aoff, doff, ioff keywords add the specified offset values to the atom types, bond types, angle types,
dihedral types, and/or improper types as they are read from the molecule file. E.g. if toff = 2, and the file uses atom
types 1,2,3, then each created molecule will have atom types 3,4,5. For the offset keyword, all five offset values must
be specified, but individual values will be ignored if the molecule template does not use that attribute (e.g. no bonds).
The scale keyword scales the size of the molecule. This can be useful for modeling polydisperse granular rigid bodies.
The scale factor is applied to each of these properties in the molecule file, if they are defined: the individual particle
coordinates (Coords section), the individual mass of each particle (Masses section), the individual diameters of each
particle (Diameters section), the total mass of the molecule (header keyword = mass), the center-of-mass of the molecule
(header keyword = com), and the moments of inertia of the molecule (header keyword = inertia).

Note: The molecule command can be used to define molecules with bonds, angles, dihedrals, impropers, or special
bond lists of neighbors within a molecular topology, so that you can later add the molecules to your simulation, via one
or more of the commands listed above. Since this topology-related information requires that suitable storage is reserved
when LAMMPS creates the simulation box (e.g. when using the create_box command or the read_data command)
suitable space has to be reserved so you do not overflow those pre-allocated data structures when adding molecules
later. Both the create_box command and the read_data command have “extra” options which insure space is allocated
for storing topology info for molecules that are added later.

The format of an individual molecule file is similar but (not identical) to the data file read by the read_data commands,
and is as follows.
A molecule file has a header and a body. The header appears first. The first line of the header is always skipped; it
typically contains a description of the file. Then lines are read one at a time. Lines can have a trailing comment starting
with ‘#’ that is ignored. If the line is blank (only white-space after comment is deleted), it is skipped. If the line contains
a header keyword, the corresponding value(s) is read from the line. If it does not contain a header keyword, the line
begins the body of the file.

16.77. molecule command 815

LAMMPS Documentation, Release stable 29Sep2021

The body of the file contains zero or more sections. The first line of a section has only a keyword. The next line is
skipped. The remaining lines of the section contain values. The number of lines depends on the section keyword as
described below. Zero or more blank lines can be used between sections. Sections can appear in any order, with a few
exceptions as noted below.
These are the recognized header keywords. Header lines can come in any order. The numeric value(s) are read from
the beginning of the line. The keyword should appear at the end of the line. All these settings have default values, as
explained below. A line need only appear if the value(s) are different than the default.
• N atoms = # of atoms N in molecule, default = 0
• Nb bonds = # of bonds Nb in molecule, default = 0
• Na angles = # of angles Na in molecule, default = 0
• Nd dihedrals = # of dihedrals Nd in molecule, default = 0
• Ni impropers = # of impropers Ni in molecule, default = 0
• Nf fragments = # of fragments in molecule, default = 0
• Mtotal mass = total mass of molecule
• Xc Yc Zc com = coordinates of center-of-mass of molecule
• Ixx Iyy Izz Ixy Ixz Iyz inertia = 6 components of inertia tensor of molecule
For mass, com, and inertia, the default is for LAMMPS to calculate this quantity itself if needed, assuming the molecules
consists of a set of point particles or finite-size particles (with a non-zero diameter) that do not overlap. If finite-size
particles in the molecule do overlap, LAMMPS will not account for the overlap effects when calculating any of these
3 quantities, so you should pre-compute them yourself and list the values in the file.
The mass and center-of-mass coordinates (Xc,Yc,Zc) are self-explanatory. The 6 moments of inertia
(ixx,iyy,izz,ixy,ixz,iyz) should be the values consistent with the current orientation of the rigid body around its center
of mass. The values are with respect to the simulation box XYZ axes, not with respect to the principal axes of the rigid
body itself. LAMMPS performs the latter calculation internally.
These are the allowed section keywords for the body of the file.
• Coords, Types, Molecules, Fragments, Charges, Diameters, Masses = atom-property sections
• Bonds, Angles, Dihedrals, Impropers = molecular topology sections
• Special Bond Counts, Special Bonds = special neighbor info
• Shake Flags, Shake Atoms, Shake Bond Types = SHAKE info
If a Bonds section is specified then the Special Bond Counts and Special Bonds sections can also be used, if desired,
to explicitly list the 1-2, 1-3, 1-4 neighbors within the molecule topology (see details below). This is optional since if
these sections are not included, LAMMPS will auto-generate this information. Note that LAMMPS uses this info to
properly exclude or weight bonded pairwise interactions between bonded atoms. See the special_bonds command for
more details. One reason to list the special bond info explicitly is for the thermalized Drude oscillator model which
treats the bonds between nuclear cores and Drude electrons in a different manner.

Note: Whether a section is required depends on how the molecule template is used by other LAMMPS commands.
For example, to add a molecule via the fix deposit command, the Coords and Types sections are required. To add a rigid
body via the fix pour command, the Bonds (Angles, etc) sections are not required, since the molecule will be treated as
a rigid body. Some sections are optional. For example, the fix pour command can be used to add “molecules” which
are clusters of finite-size granular particles. If the Diameters section is not specified, each particle in the molecule
will have a default diameter of 1.0. See the doc pages for LAMMPS commands that use molecule templates for more
details.

816 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Each section is listed below in alphabetic order. The format of each section is described including the number of lines
it must contain and rules (if any) for whether it can appear in the data file. For per- atom sections, entries should be
numbered from 1 to Natoms (where Natoms is the number of atoms in the template), indicating which atom (or bond,
etc) the entry applies to. Per-atom sections need to include a setting for every atom, but the atoms can be listed in any
order.

Coords section:
• one line per atom
• line syntax: ID x y z
• x,y,z = coordinate of atom

Types section:
• one line per atom
• line syntax: ID type
• type = atom type of atom

Molecules section:
• one line per atom
• line syntax: ID molecule-ID
• molecule-ID = molecule ID of atom

Fragments section:
• one line per fragment
• line syntax: ID a b c d . . .
• a,b,c,d,. . . = IDs of atoms in fragment
The ID of a fragment can only contain alphanumeric characters and underscores. The atom IDs should be values from
1 to Natoms, where Natoms = # of atoms in the molecule.

Charges section:
• one line per atom
• line syntax: ID q
• q = charge on atom
This section is only allowed for atom styles that support charge. If this section is not included, the default charge on
each atom in the molecule is 0.0.

Diameters section:
• one line per atom
• line syntax: ID diam

16.77. molecule command 817

LAMMPS Documentation, Release stable 29Sep2021

• diam = diameter of atom

This section is only allowed for atom styles that support finite-size spherical particles, e.g. atom_style sphere. If not
listed, the default diameter of each atom in the molecule is 1.0.

Masses section:
• one line per atom
• line syntax: ID mass
• mass = mass of atom
This section is only allowed for atom styles that support per-atom mass, as opposed to per-type mass. See the mass
command for details. If this section is not included, the default mass for each atom is derived from its volume (see
Diameters section) and a default density of 1.0, in units of mass/volume.

Bonds section:
• one line per bond
• line syntax: ID type atom1 atom2
• type = bond type (1-Nbondtype)
• atom1,atom2 = IDs of atoms in bond
The IDs for the two atoms in each bond should be values from 1 to Natoms, where Natoms = # of atoms in the molecule.

Angles section:
• one line per angle
• line syntax: ID type atom1 atom2 atom3
• type = angle type (1-Nangletype)
• atom1,atom2,atom3 = IDs of atoms in angle
The IDs for the three atoms in each angle should be values from 1 to Natoms, where Natoms = # of atoms in the molecule.
The 3 atoms are ordered linearly within the angle. Thus the central atom (around which the angle is computed) is the
atom2 in the list.

Dihedrals section:
• one line per dihedral
• line syntax: ID type atom1 atom2 atom3 atom4
• type = dihedral type (1-Ndihedraltype)
• atom1,atom2,atom3,atom4 = IDs of atoms in dihedral
The IDs for the four atoms in each dihedral should be values from 1 to Natoms, where Natoms = # of atoms in the
molecule. The 4 atoms are ordered linearly within the dihedral.

Impropers section:
• one line per improper

818 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• line syntax: ID type atom1 atom2 atom3 atom4

• type = improper type (1-Nimpropertype)
• atom1,atom2,atom3,atom4 = IDs of atoms in improper
The IDs for the four atoms in each improper should be values from 1 to Natoms, where Natoms = # of atoms in the
molecule. The ordering of the 4 atoms determines the definition of the improper angle used in the formula for the
defined improper style. See the doc pages for individual styles for details.

Special Bond Counts section:

• one line per atom
• line syntax: ID N1 N2 N3
• N1 = # of 1-2 bonds
• N2 = # of 1-3 bonds
• N3 = # of 1-4 bonds
N1, N2, N3 are the number of 1-2, 1-3, 1-4 neighbors respectively of this atom within the topology of the molecule.
See the special_bonds page for more discussion of 1-2, 1-3, 1-4 neighbors. If this section appears, the Special Bonds
section must also appear.
As explained above, LAMMPS will auto-generate this information if this section is not specified. If specified, this
section will override what would be auto-generated.

Special Bonds section:

• one line per atom
• line syntax: ID a b c d . . .
• a,b,c,d,. . . = IDs of atoms in N1+N2+N3 special bonds
A, b, c, d, etc are the IDs of the n1+n2+n3 atoms that are 1-2, 1-3, 1-4 neighbors of this atom. The IDs should be
values from 1 to Natoms, where Natoms = # of atoms in the molecule. The first N1 values should be the 1-2 neighbors,
the next N2 should be the 1-3 neighbors, the last N3 should be the 1-4 neighbors. No atom ID should appear more
than once. See the special_bonds doc page for more discussion of 1-2, 1-3, 1-4 neighbors. If this section appears, the
Special Bond Counts section must also appear.
As explained above, LAMMPS will auto-generate this information if this section is not specified. If specified, this
section will override what would be auto-generated.

Shake Flags section:

• one line per atom
• line syntax: ID flag
• flag = 0,1,2,3,4
This section is only needed when molecules created using the template will be constrained by SHAKE via the “fix
shake” command. The other two Shake sections must also appear in the file, following this one.
The meaning of the flag for each atom is as follows. See the fix shake page for a further description of SHAKE clusters.
• 0 = not part of a SHAKE cluster
• 1 = part of a SHAKE angle cluster (two bonds and the angle they form)

16.77. molecule command 819

LAMMPS Documentation, Release stable 29Sep2021

• 2 = part of a 2-atom SHAKE cluster with a single bond

• 3 = part of a 3-atom SHAKE cluster with two bonds
• 4 = part of a 4-atom SHAKE cluster with three bonds

Shake Atoms section:

• one line per atom
• line syntax: ID a b c d
• a,b,c,d = IDs of atoms in cluster
This section is only needed when molecules created using the template will be constrained by SHAKE via the “fix
shake” command. The other two Shake sections must also appear in the file.
The a,b,c,d values are atom IDs (from 1 to Natoms) for all the atoms in the SHAKE cluster that this atom belongs to.
The number of values that must appear is determined by the shake flag for the atom (see the Shake Flags section above).
All atoms in a particular cluster should list their a,b,c,d values identically.
If flag = 0, no a,b,c,d values are listed on the line, just the (ignored) ID.
If flag = 1, a,b,c are listed, where a = ID of central atom in the angle, and b,c the other two atoms in the angle.
If flag = 2, a,b are listed, where a = ID of atom in bond with the lowest ID, and b = ID of atom in bond with the highest
ID.
If flag = 3, a,b,c are listed, where a = ID of central atom, and b,c = IDs of other two atoms bonded to the central atom.
If flag = 4, a,b,c,d are listed, where a = ID of central atom, and b,c,d = IDs of other three atoms bonded to the central
atom.
See the fix shake page for a further description of SHAKE clusters.

Shake Bond Types section:

• one line per atom
• line syntax: ID a b c
• a,b,c = bond types (or angle type) of bonds (or angle) in cluster
This section is only needed when molecules created using the template will be constrained by SHAKE via the “fix
shake” command. The other two Shake sections must also appear in the file.
The a,b,c values are bond types (from 1 to Nbondtypes) for all bonds in the SHAKE cluster that this atom belongs
to. The number of values that must appear is determined by the shake flag for the atom (see the Shake Flags section
above). All atoms in a particular cluster should list their a,b,c values identically.
If flag = 0, no a,b,c values are listed on the line, just the (ignored) ID.
If flag = 1, a,b,c are listed, where a = bondtype of the bond between the central atom and the first non-central atom
(value b in the Shake Atoms section), b = bondtype of the bond between the central atom and the second non-central
atom (value c in the Shake Atoms section), and c = the angle type (1 to Nangletypes) of the angle between the 3 atoms.
If flag = 2, only a is listed, where a = bondtype of the bond between the 2 atoms in the cluster.
If flag = 3, a,b are listed, where a = bondtype of the bond between the central atom and the first non-central atom (value
b in the Shake Atoms section), and b = bondtype of the bond between the central atom and the second non-central atom
(value c in the Shake Atoms section).

820 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

If flag = 4, a,b,c are listed, where a = bondtype of the bond between the central atom and the first non-central atom (value
b in the Shake Atoms section), b = bondtype of the bond between the central atom and the second non-central atom
(value c in the Shake Atoms section), and c = bondtype of the bond between the central atom and the third non-central
atom (value d in the Shake Atoms section).
See the fix shake page for a further description of SHAKE clusters.

16.77.4 Restrictions

None

16.77.5 Related commands

fix deposit, fix pour, fix gcmc

16.77.6 Default

The default keywords values are offset 0 0 0 0 0 and scale = 1.0.

16.78 neb command

16.78.1 Syntax

neb etol ftol N1 N2 Nevery file-style arg keyword

• etol = stopping tolerance for energy (energy units)

• ftol = stopping tolerance for force (force units)
• N1 = max # of iterations (timesteps) to run initial NEB
• N2 = max # of iterations (timesteps) to run barrier-climbing NEB
• Nevery = print replica energies and reaction coordinates every this many timesteps
• file-style = final or each or none
final arg = filename
filename = file with initial coords for final replica
coords for intermediate replicas are linearly interpolated
between first and last replica
each arg = filename
filename = unique filename for each replica (except first)
with its initial coords
none arg = no argument all replicas assumed to already have
their initial coords
keyword = verbose

16.78. neb command 821

LAMMPS Documentation, Release stable 29Sep2021

16.78.2 Examples

neb 0.1 0.0 1000 500 50 final coords.final

neb 0.0 0.001 1000 500 50 each coords.initial.$i
neb 0.0 0.001 1000 500 50 none verbose

16.78.3 Description

Perform a nudged elastic band (NEB) calculation using multiple replicas of a system. Two or more replicas must be
used; the first and last are the end points of the transition path.
NEB is a method for finding both the atomic configurations and height of the energy barrier associated with a transition
state, e.g. for an atom to perform a diffusive hop from one energy basin to another in a coordinated fashion with its
neighbors. The implementation in LAMMPS follows the discussion in these 4 papers: (HenkelmanA), (HenkelmanB),
(Nakano) and (Maras).
Each replica runs on a partition of one or more processors. Processor partitions are defined at run-time using the -
partition command-line switch. Note that if you have MPI installed, you can run a multi-replica simulation with more
replicas (partitions) than you have physical processors, e.g you can run a 10-replica simulation on just one or two
processors. You will simply not get the performance speed-up you would see with one or more physical processors per
replica. See the Howto replica doc page for further discussion.

Note: As explained below, a NEB calculation performs a damped dynamics minimization across all the replicas. The
minimizer uses whatever timestep you have defined in your input script, via the timestep command. Often NEB will
converge more quickly if you use a timestep about 10x larger than you would normally use for dynamics simulations.

When a NEB calculation is performed, it is assumed that each replica is running the same system, though LAMMPS
does not check for this. I.e. the simulation domain, the number of atoms, the interaction potentials, and the starting
configuration when the neb command is issued should be the same for every replica.
In a NEB calculation each replica is connected to other replicas by inter-replica nudging forces. These forces are
imposed by the fix neb command, which must be used in conjunction with the neb command. The group used to define
the fix neb command defines the NEB atoms which are the only ones that inter-replica springs are applied to. If the group
does not include all atoms, then non-NEB atoms have no inter-replica springs and the forces they feel and their motion
is computed in the usual way due only to other atoms within their replica. Conceptually, the non-NEB atoms provide
a background force field for the NEB atoms. They can be allowed to move during the NEB minimization procedure
(which will typically induce different coordinates for non-NEB atoms in different replicas), or held fixed using other
LAMMPS commands such as fix setforce. Note that the partition command can be used to invoke a command on a
subset of the replicas, e.g. if you wish to hold NEB or non-NEB atoms fixed in only the end-point replicas.
The initial atomic configuration for each of the replicas can be specified in different manners via the file-style setting, as
discussed below. Only atoms whose initial coordinates should differ from the current configuration need be specified.
Conceptually, the initial and final configurations for the first replica should be states on either side of an energy barrier.
As explained below, the initial configurations of intermediate replicas can be atomic coordinates interpolated in a linear
fashion between the first and last replicas. This is often adequate for simple transitions. For more complex transitions,
it may lead to slow convergence or even bad results if the minimum energy path (MEP, see below) of states over the
barrier cannot be correctly converged to from such an initial path. In this case, you will want to generate initial states
for the intermediate replicas that are geometrically closer to the MEP and read them in.

For a file-style setting of final, a filename is specified which contains atomic coordinates for zero or more atoms, in
the format described below. For each atom that appears in the file, the new coordinates are assigned to that atom in

822 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

the final replica. Each intermediate replica also assigns a new position to that atom in an interpolated manner. This
is done by using the current position of the atom as the starting point and the read-in position as the final point. The
distance between them is calculated, and the new position is assigned to be a fraction of the distance. E.g. if there
are 10 replicas, the second replica will assign a position that is 10% of the distance along a line between the starting
and final point, and the 9th replica will assign a position that is 90% of the distance along the line. Note that for this
procedure to produce consistent coordinates across all the replicas, the current coordinates need to be the same in all
replicas. LAMMPS does not check for this, but invalid initial configurations will likely result if it is not the case.

Note: The “distance” between the starting and final point is calculated in a minimum-image sense for a periodic
simulation box. This means that if the two positions are on opposite sides of a box (periodic in that dimension), the
distance between them will be small, because the periodic image of one of the atoms is close to the other. Similarly,
even if the assigned position resulting from the interpolation is outside the periodic box, the atom will be wrapped back
into the box when the NEB calculation begins.

For a file-style setting of each, a filename is specified which is assumed to be unique to each replica. This can be done
by using a variable in the filename, e.g.

variable i equal part

neb 0.0 0.001 1000 500 50 each coords.initial.$i

which in this case will substitute the partition ID (0 to N-1) for the variable I, which is also effectively the replica ID.
See the variable command for other options, such as using world-, universe-, or uloop-style variables.
Each replica (except the first replica) will read its file, formatted as described below, and for any atom that appears in
the file, assign the specified coordinates to its atom. The various files do not need to contain the same set of atoms.
For a file-style setting of none, no filename is specified. Each replica is assumed to already be in its initial configuration
at the time the neb command is issued. This allows each replica to define its own configuration by reading a replica-
specific data or restart or dump file, via the read_data, read_restart, or read_dump commands. The replica-specific
names of these files can be specified as in the discussion above for the each file-style. Also see the section below for
how a NEB calculation can produce restart files, so that a long calculation can be restarted if needed.

Note: None of the file-style settings change the initial configuration of any atom in the first replica. The first replica
must thus be in the correct initial configuration at the time the neb command is issued.

A NEB calculation proceeds in two stages, each of which is a minimization procedure, performed via damped dynamics.
To enable this, you must first define a damped dynamics min_style, such as quickmin or fire. The cg, sd, and hftn styles
cannot be used, since they perform iterative line searches in their inner loop, which cannot be easily synchronized
across multiple replicas.
The minimizer tolerances for energy and force are set by etol and ftol, the same as for the minimize command.
A non-zero etol means that the NEB calculation will terminate if the energy criterion is met by every replica. The
energies being compared to etol do not include any contribution from the inter-replica nudging forces, since these are
non-conservative. A non-zero ftol means that the NEB calculation will terminate if the force criterion is met by every
replica. The forces being compared to ftol include the inter-replica nudging forces.
The maximum number of iterations in each stage is set by N1 and N2. These are effectively timestep counts since each
iteration of damped dynamics is like a single timestep in a dynamics run. During both stages, the potential energy of
each replica and its normalized distance along the reaction path (reaction coordinate RD) will be printed to the screen
and log file every Nevery timesteps. The RD is 0 and 1 for the first and last replica. For intermediate replicas, it is
the cumulative distance (normalized by the total cumulative distance) between adjacent replicas, where “distance” is
defined as the length of the 3N-vector of differences in atomic coordinates, where N is the number of NEB atoms

16.78. neb command 823

LAMMPS Documentation, Release stable 29Sep2021

involved in the transition. These outputs allow you to monitor NEB’s progress in finding a good energy barrier. N1
and N2 must both be multiples of Nevery.
In the first stage of NEB, the set of replicas should converge toward a minimum energy path (MEP) of conformational
states that transition over a barrier. The MEP for a transition is defined as a sequence of 3N-dimensional states, each
of which has a potential energy gradient parallel to the MEP itself. The configuration of highest energy along a MEP
corresponds to a saddle point. The replica states will also be roughly equally spaced along the MEP due to the inter-
replica nudging force added by the fix neb command.
In the second stage of NEB, the replica with the highest energy is selected and the inter-replica forces on it are converted
to a force that drives its atom coordinates to the top or saddle point of the barrier, via the barrier-climbing calculation
described in (HenkelmanB). As before, the other replicas rearrange themselves along the MEP so as to be roughly
equally spaced.
When both stages are complete, if the NEB calculation was successful, the configurations of the replicas should be
along (close to) the MEP and the replica with the highest energy should be an atomic configuration at (close to) the
saddle point of the transition. The potential energies for the set of replicas represents the energy profile of the transition
along the MEP.

A few other settings in your input script are required or advised to perform a NEB calculation. See the NOTE about
the choice of timestep at the beginning of this doc page.
An atom map must be defined which it is not by default for atom_style atomic problems. The atom_modify map
command can be used to do this.
The minimizers in LAMMPS operate on all atoms in your system, even non-NEB atoms, as defined above. To prevent
non-NEB atoms from moving during the minimization, you should use the fix setforce command to set the force on
each of those atoms to 0.0. This is not required, and may not even be desired in some cases, but if those atoms move too
far (e.g. because the initial state of your system was not well-minimized), it can cause problems for the NEB procedure.
The damped dynamics minimizers, such as quickmin and fire), adjust the position and velocity of the atoms via an Euler
integration step. Thus you must define an appropriate timestep to use with NEB. As mentioned above, NEB will often
converge more quickly if you use a timestep about 10x larger than you would normally use for dynamics simulations.

Each file read by the neb command containing atomic coordinates used to initialize one or more replicas must be
formatted as follows.
The file can be ASCII text or a gzipped text file (detected by a .gz suffix). The file can contain initial blank lines or
comment lines starting with “#” which are ignored. The first non-blank, non-comment line should list N = the number
of lines to follow. The N successive lines contain the following information:

ID1 x1 y1 z1
ID2 x2 y2 z2
...
IDN xN yN zN

The fields are the atom ID, followed by the x,y,z coordinates. The lines can be listed in any order. Additional trailing
information on the line is OK, such as a comment.
Note that for a typical NEB calculation you do not need to specify initial coordinates for very many atoms to produce
differing starting and final replicas whose intermediate replicas will converge to the energy barrier. Typically only new
coordinates for atoms geometrically near the barrier need be specified.
Also note there is no requirement that the atoms in the file correspond to the NEB atoms in the group defined by the
fix neb command. Not every NEB atom need be in the file, and non-NEB atoms can be listed in the file.

824 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Four kinds of output can be generated during a NEB calculation: energy barrier statistics, thermodynamic output by
each replica, dump files, and restart files.
When running with multiple partitions (each of which is a replica in this case), the print-out to the screen and master
log.lammps file contains a line of output, printed once every Nevery timesteps. It contains the timestep, the maximum
force per replica, the maximum force per atom (in any replica), potential gradients in the initial, final, and climbing
replicas, the forward and backward energy barriers, the total reaction coordinate (RDT), and the normalized reaction
coordinate and potential energy of each replica.
The “maximum force per replica” is the two-norm of the 3N-length force vector for the atoms in each replica, maximized
across replicas, which is what the ftol setting is checking against. In this case, N is all the atoms in each replica. The
“maximum force per atom” is the maximum force component of any atom in any replica. The potential gradients are
the two-norm of the 3N-length force vector solely due to the interaction potential i.e. without adding in inter-replica
forces.
The “reaction coordinate” (RD) for each replica is the two-norm of the 3N-length vector of distances between its atoms
and the preceding replica’s atoms, added to the RD of the preceding replica. The RD of the first replica RD1 = 0.0;
the RD of the final replica RDN = RDT, the total reaction coordinate. The normalized RDs are divided by RDT, so
that they form a monotonically increasing sequence from zero to one. When computing RD, N only includes the atoms
being operated on by the fix neb command.
The forward (reverse) energy barrier is the potential energy of the highest replica minus the energy of the first (last)
replica.
Supplementary information for all replicas can be printed out to the screen and master log.lammps file by adding the
verbose keyword. This information include the following. The “path angle” (pathangle) for the replica i which is the
angle between the 3N-length vectors (Ri-1 - Ri) and (Ri+1 - Ri) (where Ri is the atomic coordinates of replica i). A
“path angle” of 180 indicates that replicas i-1, i and i+1 are aligned. “angletangrad” is the angle between the 3N-length
tangent vector and the 3N-length force vector at image i. The tangent vector is calculated as in (HenkelmanA) for all
intermediate replicas and at R2 - R1 and RM - RM-1 for the first and last replica, respectively. “anglegrad” is the angle
between the 3N-length energy gradient vector of replica i and that of replica i+1. It is not defined for the final replica
and reads nan. gradV is the norm of the energy gradient of image i. ReplicaForce is the two-norm of the 3N-length
force vector (including nudging forces) for replica i. MaxAtomForce is the maximum force component of any atom in
replica i.
When a NEB calculation does not converge properly, the supplementary information can help understanding what is
going wrong. For instance when the path angle becomes acute, the definition of tangent used in the NEB calculation
is questionable and the NEB cannot may diverge (Maras).
When running on multiple partitions, LAMMPS produces additional log files for each partition, e.g. log.lammps.0,
log.lammps.1, etc. For a NEB calculation, these contain the thermodynamic output for each replica.
If dump commands in the input script define a filename that includes a universe or uloop style variable, then one dump
file (per dump command) will be created for each replica. At the end of the NEB calculation, the final snapshot in each
file will contain the sequence of snapshots that transition the system over the energy barrier. Earlier snapshots will
show the convergence of the replicas to the MEP.
Likewise, restart filenames can be specified with a universe or uloop style variable, to generate restart files for each
replica. These may be useful if the NEB calculation fails to converge properly to the MEP, and you wish to restart the
calculation from an intermediate point with altered parameters.
There are 2 Python scripts provided in the tools/python directory, neb_combine.py and neb_final.py, which are useful
in analyzing output from a NEB calculation. Assume a NEB simulation with M replicas, and the NEB atoms labeled
with a specific atom type.
The neb_combine.py script extracts atom coords for the NEB atoms from all M dump files and creates a single dump
file where each snapshot contains the NEB atoms from all the replicas and one copy of non-NEB atoms from the first
replica (presumed to be identical in other replicas). This can be visualized/animated to see how the NEB atoms relax
as the NEB calculation proceeds.

16.78. neb command 825

LAMMPS Documentation, Release stable 29Sep2021

The neb_final.py script extracts the final snapshot from each of the M dump files to create a single dump file with M
snapshots. This can be visualized to watch the system make its transition over the energy barrier.
To illustrate, here are images from the final snapshot produced by the neb_combine.py script run on the dump files
produced by the two example input scripts in examples/neb.

16.78.4 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package doc page
for more info.

16.78.5 Related commands

prd, temper, fix langevin, fix viscous

16.78.6 Default

none

(HenkelmanA) Henkelman and Jonsson, J Chem Phys, 113, 9978-9985 (2000).

(HenkelmanB) Henkelman, Uberuaga, Jonsson, J Chem Phys, 113, 9901-9904 (2000).
(Nakano) Nakano, Comp Phys Comm, 178, 280-289 (2008).
(Maras) Maras, Trushin, Stukowski, Ala-Nissila, Jonsson, Comp Phys Comm, 205, 13-21 (2016)

826 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.79 neb/spin command

16.79.1 Syntax

neb/spin etol ttol N1 N2 Nevery file-style arg keyword

• etol = stopping tolerance for energy (energy units)

• ttol = stopping tolerance for torque ( units)
• N1 = max # of iterations (timesteps) to run initial NEB
• N2 = max # of iterations (timesteps) to run barrier-climbing NEB
• Nevery = print replica energies and reaction coordinates every this many timesteps
• file-style = final or each or none
final arg = filename
filename = file with initial coords for final replica
coords for intermediate replicas are linearly interpolated
between first and last replica
each arg = filename
filename = unique filename for each replica (except first)
with its initial coords
none arg = no argument all replicas assumed to already have
their initial coords
• keyword = verbose
verbose = print supplemental information

16.79.2 Examples

neb/spin 0.1 0.0 1000 500 50 final coords.final

neb/spin 0.0 0.001 1000 500 50 each coords.initial.$i
neb/spin 0.0 0.001 1000 500 50 none verbose

16.79.3 Description

Perform a geodesic nudged elastic band (GNEB) calculation using multiple replicas of a system. Two or more replicas
must be used; the first and last are the end points of the transition path.
GNEB is a method for finding both the spin configurations and height of the energy barrier associated with a transition
state, e.g. spins to perform a collective rotation from one energy basin to another. The implementation in LAMMPS
follows the discussion in the following paper: (BessarabA).
Each replica runs on a partition of one or more processors. Processor partitions are defined at run-time using the -
partition command-line switch. Note that if you have MPI installed, you can run a multi-replica simulation with more
replicas (partitions) than you have physical processors, e.g you can run a 10-replica simulation on just one or two
processors. You will simply not get the performance speed-up you would see with one or more physical processors per
replica. See the Howto replica doc page for further discussion.

16.79. neb/spin command 827

LAMMPS Documentation, Release stable 29Sep2021

Note: As explained below, a GNEB calculation performs a minimization across all the replicas. One of the spin style
minimizers has to be defined in your input script.

When a GNEB calculation is performed, it is assumed that each replica is running the same system, though LAMMPS
does not check for this. I.e. the simulation domain, the number of magnetic atoms, the interaction potentials, and the
starting configuration when the neb command is issued should be the same for every replica.
In a GNEB calculation each replica is connected to other replicas by inter-replica nudging forces. These forces are
imposed by the fix neb/spin command, which must be used in conjunction with the neb command. The group used to
define the fix neb/spin command defines the GNEB magnetic atoms which are the only ones that inter-replica springs
are applied to. If the group does not include all magnetic atoms, then non-GNEB magnetic atoms have no inter-replica
springs and the torques they feel and their precession motion is computed in the usual way due only to other magnetic
atoms within their replica. Conceptually, the non-GNEB atoms provide a background force field for the GNEB atoms.
Their magnetic spins can be allowed to evolve during the GNEB minimization procedure.
The initial spin configuration for each of the replicas can be specified in different manners via the file-style setting, as
discussed below. Only atomic spins whose initial coordinates should differ from the current configuration need to be
specified.
Conceptually, the initial and final configurations for the first replica should be states on either side of an energy barrier.
As explained below, the initial configurations of intermediate replicas can be spin coordinates interpolated in a linear
fashion between the first and last replicas. This is often adequate for simple transitions. For more complex transitions,
it may lead to slow convergence or even bad results if the minimum energy path (MEP, see below) of states over the
barrier cannot be correctly converged to from such an initial path. In this case, you will want to generate initial states
for the intermediate replicas that are geometrically closer to the MEP and read them in.

For a file-style setting of final, a filename is specified which contains atomic and spin coordinates for zero or more
atoms, in the format described below. For each atom that appears in the file, the new coordinates are assigned to that
atom in the final replica. Each intermediate replica also assigns a new spin to that atom in an interpolated manner.
This is done by using the current direction of the spin at the starting point and the read-in direction as the final point.
The “angular distance” between them is calculated, and the new direction is assigned to be a fraction of the angular
distance.

Note: The “angular distance” between the starting and final point is evaluated in the geodesic sense, as described in
(BessarabA).

Note: The angular interpolation between the starting and final point is achieved using Rodrigues formula:

~ Ii cos(ωiν ) + (~ki × m
~ νi = m
m ~ Ii ) sin(ωiν ) + (1.0 − cos(ωiν ))~ki (~ki · m
~ Ii )

where m
~ Ii is the initial spin configuration for spin i, ωiν is a rotation angle defined as:
ωi
ωiν = (ν − 1)∆ωi and ∆ωi =
Q−1

with ν the image number, Q the total number of images, and ωi the total rotation between the initial and final spins. ~ki
defines a rotation axis such as:
~ Ii × m
~ki = m ~F
i 
~ Ii × m
m ~F
i


828 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

if the initial and final spins are not aligned. If the initial and final spins are aligned, then their cross product is null, and
the expression above does not apply. If they point toward the same direction, the intermediate images conserve the same
orientation. If the initial and final spins are aligned, but point toward opposite directions, an arbitrary rotation vector
belonging to the plane perpendicular to initial and final spins is chosen. In this case, a warning message is displayed.
For a file-style setting of each, a filename is specified which is assumed to be unique to each replica. See the neb
documentation page for more information about this option.
For a file-style setting of none, no filename is specified. Each replica is assumed to already be in its initial configuration
at the time the neb command is issued. This allows each replica to define its own configuration by reading a replica-
specific data or restart or dump file, via the read_data, read_restart, or read_dump commands. The replica-specific
names of these files can be specified as in the discussion above for the each file-style. Also see the section below for
how a NEB calculation can produce restart files, so that a long calculation can be restarted if needed.

Note: None of the file-style settings change the initial configuration of any atom in the first replica. The first replica
must thus be in the correct initial configuration at the time the neb command is issued.

A NEB calculation proceeds in two stages, each of which is a minimization procedure. To enable this, you must first
define a min_style, using either the spin, spin/cg, or spin/lbfgs style (see min_spin for more information). The other
styles cannot be used, since they relax the lattice degrees of freedom instead of the spins.
The minimizer tolerances for energy and force are set by etol and ttol, the same as for the minimize command.
A non-zero etol means that the GNEB calculation will terminate if the energy criterion is met by every replica. The
energies being compared to etol do not include any contribution from the inter-replica nudging forces, since these are
non-conservative. A non-zero ttol means that the GNEB calculation will terminate if the torque criterion is met by
every replica. The torques being compared to ttol include the inter-replica nudging forces.
The maximum number of iterations in each stage is set by N1 and N2. These are effectively timestep counts since each
iteration of damped dynamics is like a single timestep in a dynamics run. During both stages, the potential energy of
each replica and its normalized distance along the reaction path (reaction coordinate RD) will be printed to the screen
and log file every Nevery timesteps. The RD is 0 and 1 for the first and last replica. For intermediate replicas, it is the
cumulative angular distance (normalized by the total cumulative angular distance) between adjacent replicas, where
“distance” is defined as the length of the 3N-vector of the geodesic distances in spin coordinates, with N the number
of GNEB spins involved (see equation (13) in (BessarabA)). These outputs allow you to monitor NEB’s progress in
finding a good energy barrier. N1 and N2 must both be multiples of Nevery.
In the first stage of GNEB, the set of replicas should converge toward a minimum energy path (MEP) of conformational
states that transition over a barrier. The MEP for a transition is defined as a sequence of 3N-dimensional spin states,
each of which has a potential energy gradient parallel to the MEP itself. The configuration of highest energy along a
MEP corresponds to a saddle point. The replica states will also be roughly equally spaced along the MEP due to the
inter-replica nudging force added by the fix neb command.
In the second stage of GNEB, the replica with the highest energy is selected and the inter-replica forces on it are
converted to a force that drives its spin coordinates to the top or saddle point of the barrier, via the barrier-climbing
calculation described in (BessarabA). As before, the other replicas rearrange themselves along the MEP so as to be
roughly equally spaced.
When both stages are complete, if the GNEB calculation was successful, the configurations of the replicas should be
along (close to) the MEP and the replica with the highest energy should be a spin configuration at (close to) the saddle
point of the transition. The potential energies for the set of replicas represents the energy profile of the transition along
the MEP.

An atom map must be defined which it is not by default for atom_style atomic problems. The atom_modify map
command can be used to do this.

16.79. neb/spin command 829

LAMMPS Documentation, Release stable 29Sep2021

An initial value can be defined for the timestep. Although, the spin minimization algorithm is an adaptive timestep
methodology, so that this timestep is likely to evolve during the calculation.
The minimizers in LAMMPS operate on all spins in your system, even non-GNEB atoms, as defined above.

Each file read by the neb/spin command containing spin coordinates used to initialize one or more replicas must be
formatted as follows.
The file can be ASCII text or a gzipped text file (detected by a .gz suffix). The file can contain initial blank lines or
comment lines starting with “#” which are ignored. The first non-blank, non-comment line should list N = the number
of lines to follow. The N successive lines contain the following information:

ID1 g1 x1 y1 z1 sx1 sy1 sz1

ID2 g2 x2 y2 z2 sx2 sy2 sz2
...
IDN gN yN zN sxN syN szN

The fields are the atom ID, the norm of the associated magnetic spin, followed by the x,y,z coordinates and the sx,sy,sz
spin coordinates. The lines can be listed in any order. Additional trailing information on the line is OK, such as a
comment.
Note that for a typical GNEB calculation you do not need to specify initial spin coordinates for very many atoms to
produce differing starting and final replicas whose intermediate replicas will converge to the energy barrier. Typically
only new spin coordinates for atoms geometrically near the barrier need be specified.
Also note there is no requirement that the atoms in the file correspond to the GNEB atoms in the group defined by the
fix neb command. Not every GNEB atom need be in the file, and non-GNEB atoms can be listed in the file.

Four kinds of output can be generated during a GNEB calculation: energy barrier statistics, thermodynamic output by
each replica, dump files, and restart files.
When running with multiple partitions (each of which is a replica in this case), the print-out to the screen and master
log.lammps file contains a line of output, printed once every Nevery timesteps. It contains the timestep, the maximum
torque per replica, the maximum torque per atom (in any replica), potential gradients in the initial, final, and climbing
replicas, the forward and backward energy barriers, the total reaction coordinate (RDT), and the normalized reaction
coordinate and potential energy of each replica.
The “maximum torque per replica” is the two-norm of the 3N-length vector given by the cross product of a spin by its
precession vector omega, in each replica, maximized across replicas, which is what the ttol setting is checking against.
In this case, N is all the atoms in each replica. The “maximum torque per atom” is the maximum torque component
of any atom in any replica. The potential gradients are the two-norm of the 3N-length magnetic precession vector
solely due to the interaction potential i.e. without adding in inter-replica forces, and projected along the path tangent
(as detailed in Appendix D of (BessarabA)).
The “reaction coordinate” (RD) for each replica is the two-norm of the 3N-length vector of geodesic distances between
its spins and the preceding replica’s spins (see equation (13) of (BessarabA)), added to the RD of the preceding replica.
The RD of the first replica RD1 = 0.0; the RD of the final replica RDN = RDT, the total reaction coordinate. The
normalized RDs are divided by RDT, so that they form a monotonically increasing sequence from zero to one. When
computing RD, N only includes the spins being operated on by the fix neb/spin command.
The forward (reverse) energy barrier is the potential energy of the highest replica minus the energy of the first (last)
replica.
Supplementary information for all replicas can be printed out to the screen and master log.lammps file by adding the
verbose keyword. This information include the following. The “GradVidottan” are the projections of the potential
gradient for the replica i on its tangent vector (as detailed in Appendix D of (BessarabA)). The “DNi” are the non

830 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

normalized geodesic distances (see equation (13) of (BessarabA)), between a replica i and the next replica i+1. For the
last replica, this distance is not defined and a “NAN” value is the corresponding output.
When a NEB calculation does not converge properly, the supplementary information can help understanding what is
going wrong.
When running on multiple partitions, LAMMPS produces additional log files for each partition, e.g. log.lammps.0,
log.lammps.1, etc. For a GNEB calculation, these contain the thermodynamic output for each replica.
If dump commands in the input script define a filename that includes a universe or uloop style variable, then one dump
file (per dump command) will be created for each replica. At the end of the GNEB calculation, the final snapshot in
each file will contain the sequence of snapshots that transition the system over the energy barrier. Earlier snapshots
will show the convergence of the replicas to the MEP.
Likewise, restart filenames can be specified with a universe or uloop style variable, to generate restart files for each
replica. These may be useful if the GNEB calculation fails to converge properly to the MEP, and you wish to restart
the calculation from an intermediate point with altered parameters.
A c file script in provided in the tool/spin/interpolate_gneb directory, that interpolates the MEP given the information
provided by the verbose output option (as detailed in Appendix D of (BessarabA)).

16.79.4 Restrictions

This command can only be used if LAMMPS was built with the SPIN package. See the Build package doc page for
more info.
For magnetic GNEB calculations, only the spin_none value for the line keyword can be used when minimization styles
spin/cg and spin/lbfgs are employed.

16.79.5 Related commands

min/spin, fix neb/spin

16.79.6 Default

none

(BessarabA) Bessarab, Uzdin, Jonsson, Comp Phys Comm, 196, 335-347 (2015).

16.80 neigh_modify command

16.80.1 Syntax

neigh_modify keyword values ...

• one or more keyword/value pairs may be listed

16.80. neigh_modify command 831

LAMMPS Documentation, Release stable 29Sep2021

keyword = delay or every or check or once or cluster or include or exclude or page␣

,→or one or binsize or collection/type or collection/interval

delay value = N
N = delay building until this many steps since last build
every value = M
M = build neighbor list every this many steps
check value = yes or no
yes = only build if some atom has moved half the skin distance or more
no = always build on 1st step that every and delay are satisfied
once
yes = only build neighbor list once at start of run and never rebuild
no = rebuild neighbor list according to other settings
cluster
yes = check bond,angle,etc neighbor list for nearby clusters
no = do not check bond,angle,etc neighbor list for nearby clusters
include value = group-ID
group-ID = only build pair neighbor lists for atoms in this group
exclude values:
type M N
M,N = exclude if one atom in pair is type M, other is type N
group group1-ID group2-ID
group1-ID,group2-ID = exclude if one atom is in 1st group, other in 2nd
molecule/intra group-ID
group-ID = exclude if both atoms are in the same molecule and in group
molecule/inter group-ID
group-ID = exclude if both atoms are in different molecules and in group
none
delete all exclude settings
page value = N
N = number of pairs stored in a single neighbor page
one value = N
N = max number of neighbors of one atom
binsize value = size
size = bin size for neighbor list construction (distance units)
collection/type values = N arg1 ... argN
N = number of custom collections
arg = N separate lists of types (see below)
collection/interval values = N arg1 ... argN
N = number of custom collections
arg = N separate cutoffs for intervals (see below)

16.80.2 Examples

neigh_modify every 2 delay 10 check yes page 100000

neigh_modify exclude type 2 3
neigh_modify exclude group frozen frozen check no
neigh_modify exclude group residue1 chain3
neigh_modify exclude molecule/intra rigid
neigh_modify collection/type 2 1*2,5 3*4
neigh_modify collection/interval 2 1.0 10.0

832 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.80.3 Description

This command sets parameters that affect the building and use of pairwise neighbor lists. Depending on what pair
interactions and other commands are defined, a simulation may require one or more neighbor lists.
The every, delay, check, and once options affect how often lists are built as a simulation runs. The delay setting means
never build new lists until at least N steps after the previous build. The every setting means build lists every M steps
(after the delay has passed). If the check setting is no, the lists are built on the first step that satisfies the delay and
every settings. If the check setting is yes, then the every and delay settings determine when a build may possibly be
performed, but an actual build only occurs if some atom has moved more than half the skin distance (specified in the
neighbor command) since the last build.
If the once setting is yes, then the neighbor list is only built once at the beginning of each run, and never rebuilt, except
on steps when a restart file is written, or steps when a fix forces a rebuild to occur (e.g. fixes that create or delete atoms,
such as fix deposit or fix evaporate). This setting should only be made if you are certain atoms will not move far enough
that the neighbor list should be rebuilt, e.g. running a simulation of a cold crystal. Note that it is not that expensive to
check if neighbor lists should be rebuilt.
When the rRESPA integrator is used (see the run_style command), the every and delay parameters refer to the longest
(outermost) timestep.
The cluster option does a sanity test every time neighbor lists are built for bond, angle, dihedral, and improper inter-
actions, to check that each set of 2, 3, or 4 atoms is a cluster of nearby atoms. It does this by computing the distance
between pairs of atoms in the interaction and insuring they are not further apart than half the periodic box length. If
they are, an error is generated, since the interaction would be computed between far-away atoms instead of their nearby
periodic images. The only way this should happen is if the pairwise cutoff is so short that atoms that are part of the
same interaction are not communicated as ghost atoms. This is an unusual model (e.g. no pair interactions at all) and
the problem can be fixed by use of the comm_modify cutoff command. Note that to save time, the default cluster setting
is no, so that this check is not performed.
The include option limits the building of pairwise neighbor lists to atoms in the specified group. This can be useful for
models where a large portion of the simulation is particles that do not interact with other particles or with each other via
pairwise interactions. The group specified with this option must also be specified via the atom_modify first command.
Note that specifying “all” as the group-ID effectively turns off the include option.
The exclude option turns off pairwise interactions between certain pairs of atoms, by not including them in the neighbor
list. These are sample scenarios where this is useful:
• In crack simulations, pairwise interactions can be shut off between 2 slabs of atoms to effectively create a crack.
• When a large collection of atoms is treated as frozen, interactions between those atoms can be turned off to save
needless computation. E.g. Using the fix setforce command to freeze a wall or portion of a bio-molecule.
• When one or more rigid bodies are specified, interactions within each body can be turned off to save needless
computation. See the fix rigid command for more details.
The exclude type option turns off the pairwise interaction if one atom is of type M and the other of type N. M can
equal N. The exclude group option turns off the interaction if one atom is in the first group and the other is the second.
Group1-ID can equal group2-ID. The exclude molecule/intra option turns off the interaction if both atoms are in the
specified group and in the same molecule, as determined by their molecule ID. The exclude molecule/inter turns off
the interaction between pairs of atoms that have different molecule IDs and are both in the specified group.
Each of the exclude options can be specified multiple times. The exclude type option is the most efficient option to use;
it requires only a single check, no matter how many times it has been specified. The other exclude options are more
expensive if specified multiple times; they require one check for each time they have been specified.
Note that the exclude options only affect pairwise interactions; see the delete_bonds command for information on
turning off bond interactions.

16.80. neigh_modify command 833

LAMMPS Documentation, Release stable 29Sep2021

Note: Excluding pairwise interactions will not work correctly when also using a long-range solver via the kspace_style
command. LAMMPS will give a warning to this effect. This is because the short-range pairwise interaction needs to
subtract off a term from the total energy for pairs whose short-range interaction is excluded, to compensate for how the
long-range solver treats the interaction. This is done correctly for pairwise interactions that are excluded (or weighted)
via the special_bonds command. But it is not done for interactions that are excluded via these neigh_modify exclude
options.

The page and one options affect how memory is allocated for the neighbor lists. For most simulations the default
settings for these options are fine, but if a very large problem is being run or a very long cutoff is being used, these
parameters can be tuned. The indices of neighboring atoms are stored in “pages”, which are allocated one after another
as they fill up. The size of each page is set by the page value. A new page is allocated when the next atom’s neighbors
could potentially overflow the list. This threshold is set by the one value which tells LAMMPS the maximum number
of neighbor’s one atom can have.

Note: LAMMPS can crash without an error message if the number of neighbors for a single particle is larger than the
page setting, which means it is much, much larger than the one setting. This is because LAMMPS does not error check
these limits for every pairwise interaction (too costly), but only after all the particle’s neighbors have been found. This
problem usually means something is very wrong with the way you have setup your problem (particle spacing, cutoff
length, neighbor skin distance, etc). If you really expect that many neighbors per particle, then boost the one and page
settings accordingly.

The binsize option allows you to specify what size of bins will be used in neighbor list construction to sort and find
neighboring atoms. By default, for neighbor style bin, LAMMPS uses bins that are 1/2 the size of the maximum pair
cutoff. For neighbor style multi, the bins are 1/2 the size of the collection interaction cutoff. Typically these are good
values for minimizing the time for neighbor list construction. This setting overrides the default. If you make it too big,
there is little overhead due to looping over bins, but more atoms are checked. If you make it too small, the optimal
number of atoms is checked, but bin overhead goes up. If you set the binsize to 0.0, LAMMPS will use the default
binsize of 1/2 the cutoff.
The collection/type option allows you to define collections of atom types, used by the multi neighbor mode. By grouping
atom types with similar physical size or interaction cutoff lengths, one may be able to improve performance by reducing
overhead. You must first specify the number of collections N to be defined followed by N lists of types. Each list consists
of a series of type ranges separated by commas. The range can be specified as a single numeric value, or a wildcard
asterisk can be used to specify a range of values. This takes the form “*” or “*n” or “n*” or “m*n”. For example, if M
= the number of atom types, then an asterisk with no numeric values means all types from 1 to M. A leading asterisk
means all types from 1 to n (inclusive). A trailing asterisk means all types from n to M (inclusive). A middle asterisk
means all types from m to n (inclusive). Note that all atom types must be included in exactly one of the N collections.
The collection/interval option provides a similar capability. This command allows a user to define collections by
specifying a series of cutoff intervals. LAMMPS will automatically sort atoms into these intervals based on their type-
dependent cutoffs or their finite size. You must first specify the number of collections N to be defined followed by N
values representing the upper cutoff of each interval. This command is particularly useful for granular pair styles where
the interaction distance of particles depends on their radius and may not depend on their atom type.

834 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.80.4 Restrictions

If the “delay” setting is non-zero, then it must be a multiple of the “every” setting.
The molecule/intra and molecule/inter exclude options can only be used with atom styles that define molecule IDs.
The value of the page setting must be at least 10x larger than the one setting. This insures neighbor pages are not mostly
empty space.

16.80.5 Related commands

neighbor, delete_bonds

16.80.6 Default

The option defaults are delay = 10, every = 1, check = yes, once = no, cluster = no, include = all (same as no include
option defined), exclude = none, page = 100000, one = 2000, and binsize = 0.0.

16.81 neighbor command

16.81.1 Syntax

neighbor skin style

• skin = extra distance beyond force cutoff (distance units)

• style = bin or nsq or multi or multi/old

16.81.2 Examples

neighbor 0.3 bin

neighbor 2.0 nsq

16.81.3 Description

This command sets parameters that affect the building of pairwise neighbor lists. All atom pairs within a neighbor
cutoff distance equal to the their force cutoff plus the skin distance are stored in the list. Typically, the larger the skin
distance, the less often neighbor lists need to be built, but more pairs must be checked for possible force interactions
every timestep. The default value for skin depends on the choice of units for the simulation; see the default values
below.
The skin distance is also used to determine how often atoms migrate to new processors if the check option of the
neigh_modify command is set to yes. Atoms are migrated (communicated) to new processors on the same timestep that
neighbor lists are re-built.
The style value selects what algorithm is used to build the list. The bin style creates the list by binning which is an
operation that scales linearly with N/P, the number of atoms per processor where N = total number of atoms and P
= number of processors. It is almost always faster than the nsq style which scales as (N/P)^2. For unsolvated small
molecules in a non-periodic box, the nsq choice can sometimes be faster. Either style should give the same answers.

16.81. neighbor command 835

LAMMPS Documentation, Release stable 29Sep2021

The multi style is a modified binning algorithm that is useful for systems with a wide range of cutoff distances, e.g. due
to different size particles. For granular pair styles, cutoffs are set to the sum of the maximum atomic radii for each atom
type. For the bin style, the bin size is set to 1/2 of the largest cutoff distance between any pair of atom types and a single
set of bins is defined to search over for all atom types. This can be inefficient if one pair of types has a very long cutoff,
but other type pairs have a much shorter cutoff. The multi style uses different sized bins for collections of different
sized particles, where “size” may mean the physical size of the particle or its cutoff distance for interacting with other
particles. Different sets of bins are then used to construct the neighbor lists as as further described by Shire, Hanley, and
Stratford (Shire). This imposes some extra setup overhead, but the searches themselves may be much faster. By default,
each atom type defines a separate collection of particles. For systems where two or more atom types have the same
size (either physical size or cutoff distance), the definition of collections can be customized, which can result in less
overhead and faster performance. See the neigh_modify command for how to define custom collections. Whether the
collection definition is customized or not, also see the comm_modify mode multi command for communication options
that further improve performance in a manner consistent with neighbor style multi.
An alternate style, multi/old, sets the bin size to 1/2 of the shortest cutoff distance and multiple sets of bins are defined
to search over for different atom types. This algorithm used to be the default multi algorithm in LAMMPS but was
found to be significantly slower than the new approach. For now we are keeping the old option in case there are use
cases where multi/old outperforms the new multi style.
The neigh_modify command has additional options that control how often neighbor lists are built and which pairs are
stored in the list.
When a run is finished, counts of the number of neighbors stored in the pairwise list and the number of times neighbor
lists were built are printed to the screen and log file. See the Run output page for details.

16.81.4 Restrictions

none

16.81.5 Related commands

neigh_modify, units, comm_modify

16.81.6 Default

0.3 bin for units = lj, skin = 0.3 sigma

2.0 bin for units = real or metal, skin = 2.0 Angstroms
0.001 bin for units = si, skin = 0.001 meters = 1.0 mm
0.1 bin for units = cgs, skin = 0.1 cm = 1.0 mm

(Shire) Shire, Hanley and Stratford, Comp Part Mech, (2020).

836 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.82 newton command

16.82.1 Syntax

newton flag
newton flag1 flag2

• flag = on or off for both pairwise and bonded interactions

• flag1 = on or off for pairwise interactions
• flag2 = on or off for bonded interactions

16.82.2 Examples

newton off
newton on off

16.82.3 Description

This command turns Newton’s third law on or off for pairwise and bonded interactions. For most problems, setting
Newton’s third law to on means a modest savings in computation at the cost of two times more communication. Whether
this is faster depends on problem size, force cutoff lengths, a machine’s compute/communication ratio, and how many
processors are being used.
Setting the pairwise newton flag to off means that if two interacting atoms are on different processors, both processors
compute their interaction and the resulting force information is not communicated. Similarly, for bonded interactions,
newton off means that if a bond, angle, dihedral, or improper interaction contains atoms on 2 or more processors, the
interaction is computed by each processor.
LAMMPS should produce the same answers for any newton flag settings, except for round-off issues.
With run_style respa and only bonded interactions (bond, angle, etc) computed in the innermost timestep, it may be
faster to turn newton off for bonded interactions, to avoid extra communication in the innermost loop.

16.82.4 Restrictions

The newton bond setting cannot be changed after the simulation box is defined by a read_data or create_box command.

16.82.5 Related commands

run_style respa

16.82. newton command 837

LAMMPS Documentation, Release stable 29Sep2021

16.82.6 Default

newton on

16.83 next command

16.83.1 Syntax

next variables

• variables = one or more variable names

16.83.2 Examples

next x
next a t x myTemp

16.83.3 Description

This command is used with variables defined by the variable command. It assigns the next value to the variable from
the list of values defined for that variable by the variable command. Thus when that variable is subsequently substituted
for in an input script command, the new value is used.
See the variable command for info on how to define and use different kinds of variables in LAMMPS input scripts. If
a variable name is a single lower-case character from “a” to “z”, it can be used in an input script command as $a or $z.
If it is multiple letters, it can be used as ${myTemp}.
If multiple variables are used as arguments to the next command, then all must be of the same variable style: index,
loop, file, universe, or uloop. An exception is that universe- and uloop-style variables can be mixed in the same next
command.
All the variables specified with the next command are incremented by one value from their respective list of values.
A file-style variable reads the next line from its associated file. An atomfile-style variable reads the next set of lines
(one per atom) from its associated file. String- or atom- or equal- or world-style variables cannot be used with the next
command, since they only store a single value.
When any of the variables in the next command has no more values, a flag is set that causes the input script to skip the
next jump command encountered. This enables a loop containing a next command to exit. As explained in the variable
command, the variable that has exhausted its values is also deleted. This allows it to be used and re-defined later in the
input script. File-style and atomfile-style variables are exhausted when the end-of-file is reached.
When the next command is used with index- or loop-style variables, the next value is assigned to the variable for all
processors. When the next command is used with file-style variables, the next line is read from its file and the string
assigned to the variable. When the next command is used with atomfile-style variables, the next set of per-atom values
is read from its file and assigned to the variable.
When the next command is used with universe- or uloop-style variables, all universe- or uloop-style variables must be
listed in the next command. This is because of the manner in which the incrementing is done, using a single lock file
for all variables. The next value (for each variable) is assigned to whichever processor partition executes the command
first. All processors in the partition are assigned the same value(s). Running LAMMPS on multiple partitions of
processors via the -partition command-line switch. Universe- and uloop-style variables are incremented using the files

838 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

“tmp.lammps.variable” and “tmp.lammps.variable.lock” which you will see in your directory during and after such a
LAMMPS run.
Here is an example of running a series of simulations using the next command with an index-style variable. If this
input script is named in.polymer, 8 simulations would be run using data files from directories run1 through run8.

variable d index run1 run2 run3 run4 run5 run6 run7 run8
shell cd $d
read_data data.polymer
run 10000
shell cd ..
clear
next d
jump in.polymer

If the variable “d” were of style universe, and the same in.polymer input script were run on 3 partitions of processors,
then the first 3 simulations would begin, one on each set of processors. Whichever partition finished first, it would
assign variable “d” the fourth value and run another simulation, and so forth until all 8 simulations were finished.
Jump and next commands can also be nested to enable multi-level loops. For example, this script will run 15 simulations
in a double loop.

variable i loop 3
variable j loop 5
clear
...
read_data data.polymer.$i$j
print Running simulation $i.$j
run 10000
next j
jump in.script
next i
jump in.script

Here is an example of a double loop which uses the if and jump commands to break out of the inner loop when a
condition is met, then continues iterating through the outer loop.

label loopa
variable a loop 5
label loopb
variable b loop 5
print "A,B = $a,$b"
run 10000
if $b > 2 then "jump in.script break"
next b
jump in.script loopb
label break
variable b delete

next a
jump in.script loopa

16.83. next command 839

LAMMPS Documentation, Release stable 29Sep2021

16.83.4 Restrictions

As described above.

16.83.5 Related commands

jump, include, shell, variable,

16.83.6 Default

none

16.84 package command

16.84.1 Syntax

package style args

• style = gpu or intel or kokkos or omp

• args = arguments specific to the style
gpu args = Ngpu keyword value ...
Ngpu = # of GPUs per node
zero or more keyword/value pairs may be appended
keywords = neigh or newton or pair/only or binsize or split or gpuID or tpa or␣
,→blocksize or platform or device_type or ocl_args

neigh value = yes or no

yes = neighbor list build on GPU (default)
no = neighbor list build on CPU
newton = off or on
off = set Newton pairwise flag off (default and required)
on = set Newton pairwise flag on (currently not allowed)
pair/only = off or on
off = apply "gpu" suffix to all available styles in the GPU package (default)
on = apply "gpu" suffix only pair styles
binsize value = size
size = bin size for neighbor list construction (distance units)
split = fraction
fraction = fraction of atoms assigned to GPU (default = 1.0)
tpa value = Nlanes
Nlanes = # of GPU vector lanes (CUDA threads) used per atom
blocksize value = size
size = thread block size for pair force computation
omp value = Nthreads
Nthreads = number of OpenMP threads to use on CPU (default = 0)
platform value = id
id = For OpenCL, platform ID for the GPU or accelerator
gpuID values = id
id = ID of first GPU to be used on each node

840 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

device_type value = intelgpu or nvidiagpu or amdgpu or applegpu or generic or␣

,→ custom,val1,val2,...
val1,val2,... = custom OpenCL accelerator configuration parameters (see below␣
,→for details)

ocl_args value = args

args = List of additional OpenCL compiler arguments delimited by colons
intel args = NPhi keyword value ...
Nphi = # of co-processors per node
zero or more keyword/value pairs may be appended
keywords = mode or omp or lrt or balance or ghost or tpc or tptask or no_affinity
mode value = single or mixed or double
single = perform force calculations in single precision
mixed = perform force calculations in mixed precision
double = perform force calculations in double precision
omp value = Nthreads
Nthreads = number of OpenMP threads to use on CPU (default = 0)
lrt value = yes or no
yes = use additional thread dedicated for some PPPM calculations
no = do not dedicate an extra thread for some PPPM calculations
balance value = split
split = fraction of work to offload to co-processor, -1 for dynamic
ghost value = yes or no
yes = include ghost atoms for offload
no = do not include ghost atoms for offload
tpc value = Ntpc
Ntpc = max number of co-processor threads per co-processor core (default = 4)
tptask value = Ntptask
Ntptask = max number of co-processor threads per MPI task (default = 240)
no_affinity values = none
kokkos args = keyword value ...
zero or more keyword/value pairs may be appended
keywords = neigh or neigh/qeq or neigh/thread or newton or binsize or comm or␣
,→comm/exchange or comm/forward pair/comm/forward fix/comm/forward or comm/reverse␣

,→or gpu/aware or pair/only

neigh value = full or half

full = full neighbor list
half = half neighbor list built in thread-safe manner
neigh/qeq value = full or half
full = full neighbor list
half = half neighbor list built in thread-safe manner
neigh/thread value = off or on
off = thread only over atoms
on = thread over both atoms and neighbors
newton = off or on
off = set Newton pairwise and bonded flags off
on = set Newton pairwise and bonded flags on
binsize value = size
size = bin size for neighbor list construction (distance units)
comm value = no or host or device
use value for comm/exchange and comm/forward and pair/comm/forward and fix/
,→comm/forward and comm/reverse

comm/exchange value = no or host or device

comm/forward value = no or host or device
pair/comm/forward value = no or device

16.84. package command 841

LAMMPS Documentation, Release stable 29Sep2021

fix/comm/forward value = no or device

comm/reverse value = no or host or device
no = perform communication pack/unpack in non-KOKKOS mode
host = perform pack/unpack on host (e.g. with OpenMP threading)
device = perform pack/unpack on device (e.g. on GPU)
gpu/aware = off or on
off = do not use GPU-aware MPI
on = use GPU-aware MPI (default)
pair/only = off or on
off = use device acceleration (e.g. GPU) for all available styles in the␣
,→KOKKOS package (default)

on = use device acceleration only for pair styles (and host acceleration for␣
,→others)

omp args = Nthreads keyword value ...

Nthreads = # of OpenMP threads to associate with each MPI process
zero or more keyword/value pairs may be appended
keywords = neigh
neigh value = yes or no
yes = threaded neighbor list build (default)
no = non-threaded neighbor list build

16.84.2 Examples

package gpu 0
package gpu 1 split 0.75
package gpu 2 split -1.0
package gpu 0 omp 2 device_type intelgpu
package kokkos neigh half comm device
package omp 0 neigh no
package omp 4
package intel 1
package intel 2 omp 4 mode mixed balance 0.5

16.84.3 Description

This command invokes package-specific settings for the various accelerator packages available in LAMMPS. Currently
the following packages use settings from this command: GPU, INTEL, KOKKOS, and OPENMP.
If this command is specified in an input script, it must be near the top of the script, before the simulation box has been
defined. This is because it specifies settings that the accelerator packages use in their initialization, before a simulation
is defined.
This command can also be specified from the command-line when launching LAMMPS, using the “-pk” command-line
switch. The syntax is exactly the same as when used in an input script.
Note that all of the accelerator packages require the package command to be specified (except the OPT package), if the
package is to be used in a simulation (LAMMPS can be built with an accelerator package without using it in a particular
simulation). However, in all cases, a default version of the command is typically invoked by other accelerator settings.
The KOKKOS package requires a “-k on” command-line switch respectively, which invokes a “package kokkos” com-
mand with default settings.
For the GPU, INTEL, and OPENMP packages, if a “-sf gpu” or “-sf intel” or “-sf omp” command-line switch is used to
auto-append accelerator suffixes to various styles in the input script, then those switches also invoke a “package gpu”,

842 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

“package intel”, or “package omp” command with default settings.

Note: A package command for a particular style can be invoked multiple times when a simulation is setup, e.g. by the
-c on, -k on, -sf, and -pk command-line switches, and by using this command in an input script. Each time it is used all
of the style options are set, either to default values or to specified settings. I.e. settings from previous invocations do
not persist across multiple invocations.

See the Speed packages page for more details about using the various accelerator packages for speeding up LAMMPS
simulations.

The gpu style invokes settings associated with the use of the GPU package.
The Ngpu argument sets the number of GPUs per node. If Ngpu is 0 and no other keywords are specified, GPU or
accelerator devices are auto-selected. In this process, all platforms are searched for accelerator devices and GPUs
are chosen if available. The device with the highest number of compute cores is selected. The number of devices is
increased to be the number of matching accelerators with the same number of compute cores. If there are more devices
than MPI tasks, the additional devices will be unused. The auto-selection of GPUs/ accelerator devices and platforms
can be restricted by specifying a non-zero value for Ngpu and / or using the gpuID, platform, and device_type keywords
as described below. If there are more MPI tasks (per node) than GPUs, multiple MPI tasks will share each GPU.
Optional keyword/value pairs can also be specified. Each has a default value as listed below.
The neigh keyword specifies where neighbor lists for pair style computation will be built. If neigh is yes, which is the
default, neighbor list building is performed on the GPU. If neigh is no, neighbor list building is performed on the CPU.
GPU neighbor list building currently cannot be used with a triclinic box. GPU neighbor lists are not compatible with
commands that are not GPU-enabled. When a non-GPU enabled command requires a neighbor list, it will also be built
on the CPU. In these cases, it will typically be more efficient to only use CPU neighbor list builds.
The newton keyword sets the Newton flags for pairwise (not bonded) interactions to off or on, the same as the newton
command allows. Currently, only an off value is allowed, since all the GPU package pair styles require this setting. This
means more computation is done, but less communication. In the future a value of on may be allowed, so the newton
keyword is included as an option for compatibility with the package command for other accelerator styles. Note that
the newton setting for bonded interactions is not affected by this keyword.
The pair/only keyword can change how any “gpu” suffix is applied. By default a suffix is applied to all styles for which
an accelerated variant is available. However, that is not always the most effective way to use an accelerator. With
pair/only set to on the suffix will only by applied to supported pair styles, which tend to be the most effective in using
an accelerator and their operation can be overlapped with all other computations on the CPU.
The binsize keyword sets the size of bins used to bin atoms in neighbor list builds performed on the GPU, if neigh =
yes is set. If binsize is set to 0.0 (the default), then the binsize is set automatically using heuristics in the GPU package.
The split keyword can be used for load balancing force calculations between CPU and GPU cores in GPU-enabled pair
styles. If 0 < split < 1.0, a fixed fraction of particles is offloaded to the GPU while force calculation for the other particles
occurs simultaneously on the CPU. If split < 0.0, the optimal fraction (based on CPU and GPU timings) is calculated
every 25 timesteps, i.e. dynamic load-balancing across the CPU and GPU is performed. If split = 1.0, all force
calculations for GPU accelerated pair styles are performed on the GPU. In this case, other hybrid pair interactions, bond,
angle, dihedral, improper, and long-range calculations can be performed on the CPU while the GPU is performing
force calculations for the GPU-enabled pair style. If all CPU force computations complete before the GPU completes,
LAMMPS will block until the GPU has finished before continuing the timestep.
As an example, if you have two GPUs per node and 8 CPU cores per node, and would like to run on 4 nodes (32 cores)
with dynamic balancing of force calculation across CPU and GPU cores, you could specify

mpirun -np 32 -sf gpu -in in.script # launch command

package gpu 2 split -1 # input script command

16.84. package command 843

LAMMPS Documentation, Release stable 29Sep2021

In this case, all CPU cores and GPU devices on the nodes would be utilized. Each GPU device would be shared by 4
CPU cores. The CPU cores would perform force calculations for some fraction of the particles at the same time the
GPUs performed force calculation for the other particles.
The gpuID keyword is used to specify the first ID for the GPU or other accelerator that LAMMPS will use. For
example, if the ID is 1 and Ngpu is 3, GPUs 1-3 will be used. Device IDs should be determined from the output of
nvc_get_devices, ocl_get_devices, or hip_get_devices as provided in the lib/gpu directory. When using OpenCL with
accelerators that have main memory NUMA, the accelerators can be split into smaller virtual accelerators for more
efficient use with MPI.
The tpa keyword sets the number of GPU vector lanes per atom used to perform force calculations. With a default
value of 1, the number of lanes will be chosen based on the pair style, however, the value can be set explicitly with this
keyword to fine-tune performance. For large cutoffs or with a small number of particles per GPU, increasing the value
can improve performance. The number of lanes per atom must be a power of 2 and currently cannot be greater than
the SIMD width for the GPU / accelerator. In the case it exceeds the SIMD width, it will automatically be decreased
to meet the restriction.
The blocksize keyword allows you to tweak the number of threads used per thread block. This number should be a
multiple of 32 (for GPUs) and its maximum depends on the specific GPU hardware. Typical choices are 64, 128, or
256. A larger block size increases occupancy of individual GPU cores, but reduces the total number of thread blocks,
thus may lead to load imbalance. On modern hardware, the sensitivity to the blocksize is typically low.
The Nthreads value for the omp keyword sets the number of OpenMP threads allocated for each MPI task. This setting
controls OpenMP parallelism only for routines run on the CPUs. For more details on setting the number of OpenMP
threads, see the discussion of the Nthreads setting on this page for the “package omp” command. The meaning of
Nthreads is exactly the same for the GPU, INTEL, and GPU packages.
The platform keyword is only used with OpenCL to specify the ID for an OpenCL platform. See the output from
ocl_get_devices in the lib/gpu directory. In LAMMPS only one platform can be active at a time and by default (id=-1)
the platform is auto-selected to find the GPU with the most compute cores. When Ngpu or other keywords are specified,
the auto-selection is appropriately restricted. For example, if Ngpu is 3, only platforms with at least 3 accelerators are
considered. Similar restrictions can be enforced by the gpuID and device_type keywords.
The device_type keyword can be used for OpenCL to specify the type of GPU to use or specify a custom configuration
for an accelerator. In most cases this selection will be automatic and there is no need to use the keyword. The applegpu
type is not specific to a particular GPU vendor, but is separate due to the more restrictive Apple OpenCL implementa-
tion. For expert users, to specify a custom configuration, the custom keyword followed by the next parameters can be
specified:
CONFIG_ID, SIMD_SIZE, MEM_THREADS, SHUFFLE_AVAIL, FAST_MATH, THREADS_PER_ATOM,
THREADS_PER_CHARGE, THREADS_PER_THREE, BLOCK_PAIR, BLOCK_BIO_PAIR, BLOCK_ELLIPSE,
PPPM_BLOCK_1D, BLOCK_NBOR_BUILD, BLOCK_CELL_2D, BLOCK_CELL_ID, MAX_SHARED_TYPES,
MAX_BIO_SHARED_TYPES, PPPM_MAX_SPLINE.
CONFIG_ID can be 0. SHUFFLE_AVAIL in {0,1} indicates that inline-PTX (NVIDIA) or OpenCL extensions (In-
tel) should be used for horizontal vector operations. FAST_MATH in {0,1} indicates that OpenCL fast math op-
timizations are used during the build and hardware-accelerated transcendental functions are used when available.
THREADS_PER_* give the default tpa values for ellipsoidal models, styles using charge, and any other styles. The
BLOCK_* parameters specify the block sizes for various kernel calls and the MAX_*SHARED*_ parameters are used
to determine the amount of local shared memory to use for storing model parameters.
For OpenCL, the routines are compiled at runtime for the specified GPU or accelerator architecture. The ocl_args
keyword can be used to specify additional flags for the runtime build.

The intel style invokes settings associated with the use of the INTEL package. All of its settings, except the omp
and mode keywords, are ignored if LAMMPS was not built with Xeon Phi co-processor support. All of its settings,
including the omp and mode keyword are applicable if LAMMPS was built with co-processor support.

844 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The Nphi argument sets the number of co-processors per node. This can be set to any value, including 0, if LAMMPS
was not built with co-processor support.
Optional keyword/value pairs can also be specified. Each has a default value as listed below.
The Nthreads value for the omp keyword sets the number of OpenMP threads allocated for each MPI task. This setting
controls OpenMP parallelism only for routines run on the CPUs. For more details on setting the number of OpenMP
threads, see the discussion of the Nthreads setting on this page for the “package omp” command. The meaning of
Nthreads is exactly the same for the GPU, INTEL, and GPU packages.
The mode keyword determines the precision mode to use for computing pair style forces, either on the CPU or on the
co-processor, when using a INTEL supported pair style. It can take a value of single, mixed which is the default, or
double. Single means single precision is used for the entire force calculation. Mixed means forces between a pair of
atoms are computed in single precision, but accumulated and stored in double precision, including storage of forces,
torques, energies, and virial quantities. Double means double precision is used for the entire force calculation.
The lrt keyword can be used to enable “Long Range Thread (LRT)” mode. It can take a value of yes to enable
and no to disable. LRT mode generates an extra thread (in addition to any OpenMP threads specified with the
OMP_NUM_THREADS environment variable or the omp keyword). The extra thread is dedicated for performing
part of the PPPM solver computations and communications. This can improve parallel performance on processors
supporting Simultaneous Multithreading (SMT) such as Hyper-Threading (HT) on Intel processors. In this mode, one
additional thread is generated per MPI process. LAMMPS will generate a warning in the case that more threads are
used than available in SMT hardware on a node. If the PPPM solver from the INTEL package is not used, then the LRT
setting is ignored and no extra threads are generated. Enabling LRT will replace the run_style with the verlet/lrt/intel
style that is identical to the default verlet style aside from supporting the LRT feature. This feature requires setting the
pre-processor flag -DLMP_INTEL_USELRT in the makefile when compiling LAMMPS.
The balance keyword sets the fraction of pair style work offloaded to the co-processor for split values between 0.0
and 1.0 inclusive. While this fraction of work is running on the co-processor, other calculations will run on the host,
including neighbor and pair calculations that are not offloaded, as well as angle, bond, dihedral, kspace, and some MPI
communications. If split is set to -1, the fraction of work is dynamically adjusted automatically throughout the run.
This typically give performance within 5 to 10 percent of the optimal fixed fraction.
The ghost keyword determines whether or not ghost atoms, i.e. atoms at the boundaries of processor sub-domains,
are offloaded for neighbor and force calculations. When the value = “no”, ghost atoms are not offloaded. This option
can reduce the amount of data transfer with the co-processor and can also overlap MPI communication of forces with
computation on the co-processor when the newton pair setting is “on”. When the value = “yes”, ghost atoms are
offloaded. In some cases this can provide better performance, especially if the balance fraction is high.
The tpc keyword sets the max # of co-processor threads Ntpc that will run on each core of the co-processor. The default
value = 4, which is the number of hardware threads per core supported by the current generation Xeon Phi chips.
The tptask keyword sets the max # of co-processor threads (Ntptask* assigned to each MPI task. The default value =
240, which is the total # of threads an entire current generation Xeon Phi chip can run (240 = 60 cores * 4 threads/core).
This means each MPI task assigned to the Phi will enough threads for the chip to run the max allowed, even if only 1
MPI task is assigned. If 8 MPI tasks are assigned to the Phi, each will run with 30 threads. If you wish to limit the
number of threads per MPI task, set tptask to a smaller value. E.g. for tptask = 16, if 8 MPI tasks are assigned, each
will run with 16 threads, for a total of 128.
Note that the default settings for tpc and tptask are fine for most problems, regardless of how many MPI tasks you
assign to a Phi.
The no_affinity keyword will turn off automatic setting of core affinity for MPI tasks and OpenMP threads on the host
when using offload to a co-processor. Affinity settings are used when possible to prevent MPI tasks and OpenMP threads
from being on separate NUMA domains and to prevent offload threads from interfering with other processes/threads
used for LAMMPS.

The kokkos style invokes settings associated with the use of the KOKKOS package.

16.84. package command 845

LAMMPS Documentation, Release stable 29Sep2021

All of the settings are optional keyword/value pairs. Each has a default value as listed below.
The neigh keyword determines how neighbor lists are built. A value of half uses a thread-safe variant of half-neighbor
lists, the same as used by most pair styles in LAMMPS, which is the default when running on CPUs (i.e. the Kokkos
CUDA back end is not enabled).
A value of full uses a full neighbor lists and is the default when running on GPUs. This performs twice as much
computation as the half option, however that is often a win because it is thread-safe and does not require atomic
operations in the calculation of pair forces. For that reason, full is the default setting for GPUs. However, when
running on CPUs, a half neighbor list is the default because it are often faster, just as it is for non-accelerated pair
styles. Similarly, the neigh/qeq keyword determines how neighbor lists are built for fix qeq/reaxff/kk.
If the neigh/thread keyword is set to off, then the KOKKOS package threads only over atoms. However, for small
systems, this may not expose enough parallelism to keep a GPU busy. When this keyword is set to on, the KOKKOS
package threads over both atoms and neighbors of atoms. When using neigh/thread on, a full neighbor list must also be
used. Using neigh/thread on may be slower for large systems, so this this option is turned on by default only when there
are 16K atoms or less owned by an MPI rank and when using a full neighbor list. Not all KOKKOS-enabled potentials
support this keyword yet, and only thread over atoms. Many simple pair-wise potentials such as Lennard-Jones do
support threading over both atoms and neighbors.
The newton keyword sets the Newton flags for pairwise and bonded interactions to off or on, the same as the newton
command allows. The default for GPUs is off because this will almost always give better performance for the KOKKOS
package. This means more computation is done, but less communication. However, when running on CPUs a value of
on is the default since it can often be faster, just as it is for non-accelerated pair styles
The binsize keyword sets the size of bins used to bin atoms in neighbor list builds. The same value can be set by the
neigh_modify binsize command. Making it an option in the package kokkos command allows it to be set from the
command line. The default value for CPUs is 0.0, which means the LAMMPS default will be used, which is bins = 1/2
the size of the pairwise cutoff + neighbor skin distance. This is fine when neighbor lists are built on the CPU. For GPU
builds, a 2x larger binsize equal to the pairwise cutoff + neighbor skin is often faster, which is the default. Note that
if you use a longer-than-usual pairwise cutoff, e.g. to allow for a smaller fraction of KSpace work with a long-range
Coulombic solver because the GPU is faster at performing pairwise interactions, then this rule of thumb may give too
large a binsize and the default should be overridden with a smaller value.
The comm and comm/exchange and comm/forward and pair/comm/forward and fix/comm/forward and comm/reverse*
keywords determine whether the host or device performs the packing and unpacking of data when communicating
per-atom data between processors. “Exchange” communication happens only on timesteps that neighbor lists are re-
built. The data is only for atoms that migrate to new processors. “Forward” communication happens every timestep.
“Reverse” communication happens every timestep if the newton option is on. The data is for atom coordinates and
any other atom properties that needs to be updated for ghost atoms owned by each processor. “Pair/comm” controls
additional communication in pair styles, such as pair_style EAM. “Fix/comm” controls additional communication in
fixes, such as fix SHAKE.
The comm keyword is simply a short-cut to set the same value for all the comm keywords.
The value options for the keywords are no or host or device. A value of no means to use the standard non-KOKKOS
method of packing/unpacking data for the communication. A value of host means to use the host, typically a multi-
core CPU, and perform the packing/unpacking in parallel with threads. A value of device means to use the device,
typically a GPU, to perform the packing/unpacking operation. If a value of host is used for the pair/comm/forward or
fix/comm/forward keyword, it will be automatically be changed to no since these keywords don’t support host mode.
The optimal choice for these keywords depends on the input script and the hardware used. The no value is useful for
verifying that the Kokkos-based host and device values are working correctly. It is the default when running on CPUs
since it is usually the fastest.
When running on CPUs or Xeon Phi, the host and device values work identically. When using GPUs, the device
value is the default since it will typically be optimal if all of your styles used in your input script are supported by the
KOKKOS package. In this case data can stay on the GPU for many timesteps without being moved between the host
and GPU, if you use the device value. If your script uses styles (e.g. fixes) which are not yet supported by the KOKKOS

846 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

package, then data has to be moved between the host and device anyway, so it is typically faster to let the host handle
communication, by using the host value. Using host instead of no will enable use of multiple threads to pack/unpack
communicated data. When running small systems on a GPU, performing the exchange pack/unpack on the host CPU
can give speedup since it reduces the number of CUDA kernel launches.
The gpu/aware keyword chooses whether GPU-aware MPI will be used. When this keyword is set to on, buffers in
GPU memory are passed directly through MPI send/receive calls. This reduces overhead of first copying the data to the
host CPU. However GPU-aware MPI is not supported on all systems, which can lead to segmentation faults and would
require using a value of off. If LAMMPS can safely detect that GPU-aware MPI is not available (currently only possible
with OpenMPI v2.0.0 or later), then the gpu/aware keyword is automatically set to off by default. When the gpu/aware
keyword is set to off while any of the comm keywords are set to device, the value for these comm keywords will be
automatically changed to no. This setting has no effect if not running on GPUs or if using only one MPI rank. GPU-
aware MPI is available for OpenMPI 1.8 (or later versions), Mvapich2 1.9 (or later) when the “MV2_USE_CUDA”
environment variable is set to “1”, CrayMPI, and IBM Spectrum MPI when the “-gpu” flag is used.
The pair/only keyword can change how the KOKKOS suffix “kk” is applied when using an accelerator device. By
default device acceleration is always used for all available styles. With pair/only set to on the suffix setting will choose
device acceleration only for pair styles and run all other force computations on the host CPU. The comm flags will also
automatically be changed to no. This can result in better performance for certain configurations and system sizes.

The omp style invokes settings associated with the use of the OPENMP package.
The Nthreads argument sets the number of OpenMP threads allocated for each MPI task. For example, if your system
has nodes with dual quad-core processors, it has a total of 8 cores per node. You could use two MPI tasks per node
(e.g. using the -ppn option of the mpirun command in MPICH or -npernode in OpenMPI), and set Nthreads = 4. This
would use all 8 cores on each node. Note that the product of MPI tasks * threads/task should not exceed the physical
number of cores (on a node), otherwise performance will suffer.
Setting Nthreads = 0 instructs LAMMPS to use whatever value is the default for the given OpenMP environment.
This is usually determined via the OMP_NUM_THREADS environment variable or the compiler runtime. Note that
in most cases the default for OpenMP capable compilers is to use one thread for each available CPU core when
OMP_NUM_THREADS is not explicitly set, which can lead to poor performance.
Here are examples of how to set the environment variable when launching LAMMPS:

env OMP_NUM_THREADS=4 lmp_machine -sf omp -in in.script

env OMP_NUM_THREADS=2 mpirun -np 2 lmp_machine -sf omp -in in.script
mpirun -x OMP_NUM_THREADS=2 -np 2 lmp_machine -sf omp -in in.script

or you can set it permanently in your shell’s start-up script. All three of these examples use a total of 4 CPU cores.
Note that different MPI implementations have different ways of passing the OMP_NUM_THREADS environment
variable to all MPI processes. The second example line above is for MPICH; the third example line with -x is for
OpenMPI. Check your MPI documentation for additional details.
What combination of threads and MPI tasks gives the best performance is difficult to predict and can depend on many
components of your input. Not all features of LAMMPS support OpenMP threading via the OPENMP package and
the parallel efficiency can be very different, too.

Note: If you build LAMMPS with the GPU, INTEL, and / or OPENMP packages, be aware these packages all allow
setting of the Nthreads value via their package commands, but there is only a single global Nthreads value used by
OpenMP. Thus if multiple package commands are invoked, you should insure the values are consistent. If they are not,
the last one invoked will take precedence, for all packages. Also note that if the -sf hybrid intel omp command-line
switch is used, it invokes a “package intel” command, followed by a “package omp” command, both with a setting of
Nthreads = 0. Likewise for a hybrid suffix for gpu and omp. Note that KOKKOS also supports setting the number of
OpenMP threads from the command line using the “-k on” command-line switch. The default for KOKKOS is 1 thread

16.84. package command 847

LAMMPS Documentation, Release stable 29Sep2021

per MPI task, so any other number of threads should be explicitly set using the “-k on” command-line switch (and this
setting should be consistent with settings from any other packages used).

Optional keyword/value pairs can also be specified. Each has a default value as listed below.
The neigh keyword specifies whether neighbor list building will be multi-threaded in addition to force calculations. If
neigh is set to no then neighbor list calculation is performed only by MPI tasks with no OpenMP threading. If mode
is yes (the default), a multi-threaded neighbor list build is used. Using neigh = yes is almost always faster and should
produce identical neighbor lists at the expense of using more memory. Specifically, neighbor list pages are allocated
for all threads at the same time and each thread works within its own pages.

16.84.4 Restrictions

This command cannot be used after the simulation box is defined by a read_data or create_box command.
The gpu style of this command can only be invoked if LAMMPS was built with the GPU package. See the Build
package doc page for more info.
The intel style of this command can only be invoked if LAMMPS was built with the INTEL package. See the Build
package page for more info.
The kk style of this command can only be invoked if LAMMPS was built with the KOKKOS package. See the Build
package doc page for more info.
The omp style of this command can only be invoked if LAMMPS was built with the OPENMP package. See the Build
package doc page for more info.

16.84.5 Related commands

suffix, -pk command-line switch

16.84.6 Default

For the GPU package, the default is Ngpu = 0 and the option defaults are neigh = yes, newton = off, binsize = 0.0, split
= 1.0, gpuID = 0 to Ngpu-1, tpa = 1, omp = 0, and platform=-1. These settings are made automatically if the “-sf gpu”
command-line switch is used. If it is not used, you must invoke the package gpu command in your input script or via
the “-pk gpu” command-line switch.
For the INTEL package, the default is Nphi = 1 and the option defaults are omp = 0, mode = mixed, lrt = no, balance
= -1, tpc = 4, tptask = 240. The default ghost option is determined by the pair style being used. This value is output
to the screen in the offload report at the end of each run. Note that all of these settings, except “omp” and “mode”, are
ignored if LAMMPS was not built with Xeon Phi co-processor support. These settings are made automatically if the
“-sf intel” command-line switch is used. If it is not used, you must invoke the package intel command in your input
script or via the “-pk intel” command-line switch.
For the KOKKOS package, the option defaults for GPUs are neigh = full, neigh/qeq = full, newton = off, binsize for
GPUs = 2x LAMMPS default value, comm = device, gpu/aware = on. When LAMMPS can safely detect that GPU-
aware MPI is not available, the default value of gpu/aware becomes “off”. For CPUs or Xeon Phis, the option defaults
are neigh = half, neigh/qeq = half, newton = on, binsize = 0.0, and comm = no. The option neigh/thread = on when
there are 16K atoms or less on an MPI rank, otherwise it is “off”. These settings are made automatically by the required
“-k on” command-line switch. You can change them by using the package kokkos command in your input script or via
the -pk kokkos command-line switch.

848 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

For the OMP package, the default is Nthreads = 0 and the option defaults are neigh = yes. These settings are made
automatically if the “-sf omp” command-line switch is used. If it is not used, you must invoke the package omp command
in your input script or via the “-pk omp” command-line switch.

16.85 pair_coeff command

16.85.1 Syntax

pair_coeff I J args

• I,J = atom types (see asterisk form below)

• args = coefficients for one or more pairs of atom types

16.85.2 Examples

pair_coeff 1 2 1.0 1.0 2.5

pair_coeff 2 * 1.0 1.0
pair_coeff 3* 1*2 1.0 1.0 2.5
pair_coeff * * 1.0 1.0
pair_coeff * * nialhjea 1 1 2
pair_coeff * 3 morse.table ENTRY1
pair_coeff 1 2 lj/cut 1.0 1.0 2.5 (for pair_style hybrid)

16.85.3 Description

Specify the pairwise force field coefficients for one or more pairs of atom types. The number and meaning of the
coefficients depends on the pair style. Pair coefficients can also be set in the data file read by the read_data command
or in a restart file.
I and J can be specified in one of two ways. Explicit numeric values can be used for each, as in the first example above.
I <= J is required. LAMMPS sets the coefficients for the symmetric J,I interaction to the same values.
A wildcard asterisk can be used in place of or in conjunction with the I,J arguments to set the coefficients for multiple
pairs of atom types. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of atom types, then an
asterisk with no numeric values means all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive).
Note that only type pairs with I <= J are considered; if asterisks imply type pairs where J < I, they are ignored.
Note that a pair_coeff command can override a previous setting for the same I,J pair. For example, these commands
set the coeffs for all I,J pairs, then overwrite the coeffs for just the I,J = 2,3 pair:

pair_coeff * * 1.0 1.0 2.5

pair_coeff 2 3 2.0 1.0 1.12

A line in a data file that specifies pair coefficients uses the exact same format as the arguments of the pair_coeff command
in an input script, with the exception of the I,J type arguments. In each line of the “Pair Coeffs” section of a data file,
only a single type I is specified, which sets the coefficients for type I interacting with type I. This is because the section
has exactly N lines, where N = the number of atom types. For this reason, the wild-card asterisk should also not be
used as part of the I argument. Thus in a data file, the line corresponding to the first example above would be listed as

16.85. pair_coeff command 849

LAMMPS Documentation, Release stable 29Sep2021

2 1.0 1.0 2.5

For many potentials, if coefficients for type pairs with I != J are not set explicitly by a pair_coeff command, the values
are inferred from the I,I and J,J settings by mixing rules; see the pair_modify command for a discussion. Details on
this option as it pertains to individual potentials are described on the page for the potential.
Many pair styles, typically for many-body potentials, use tabulated potential files as input, when specifying the
pair_coeff command. Potential files provided with LAMMPS are in the potentials directory of the distribution. For
some potentials, such as EAM, other archives of suitable files can be found on the Web. They can be used with
LAMMPS so long as they are in the format LAMMPS expects, as discussed on the individual doc pages. The first line
of potential files may contain metadata with upper case tags followed their value. These may be parsed and used by
LAMMPS. Currently supported are the “DATE:” tag and the UNITS: tag. For pair styles that have been programmed to
support the metadata, the value of the “DATE:” tag is printed to the screen and logfile so that the version of a potential
file can be later identified. The UNITS: tag indicates the units setting required for this particular potential file. If the
potential file was created for a different sets of units, LAMMPS will terminate with an error. If the potential file does
not contain the tag, no check will be made and it is the responsibility of the user to determine that the unit style is
correct.
In some select cases and for specific combinations of unit styles, LAMMPS is capable of automatically converting
potential parameters from a file. In those cases, a warning message signaling that an automatic conversion has happened
is printed to the screen.
When a pair_coeff command using a potential file is specified, LAMMPS looks for the potential file in 2 places. First it
looks in the location specified. E.g. if the file is specified as “niu3.eam”, it is looked for in the current working directory.
If it is specified as “../potentials/niu3.eam”, then it is looked for in the potentials directory, assuming it is a sister
directory of the current working directory. If the file is not found, it is then looked for in one of the directories specified
by the LAMMPS_POTENTIALS environment variable. Thus if this is set to the potentials directory in the LAMMPS
distribution, then you can use those files from anywhere on your system, without copying them into your working
directory. Environment variables are set in different ways for different shells. Here are example settings for
csh, tcsh:

% setenv LAMMPS_POTENTIALS /path/to/lammps/potentials

bash:

% export LAMMPS_POTENTIALS=/path/to/lammps/potentials

Windows:
% set LAMMPS_POTENTIALS="C:\Path to LAMMPS\Potentials"
The LAMMPS_POTENTIALS environment variable may contain paths to multiple folders, if they are separated by “;” on
Windows and “:” on all other operating systems, just like the PATH and similar environment variables.

The alphabetic list of pair styles defined in LAMMPS is given on the pair_style doc page. They are also listed in more
compact form on the Commands pair doc page.
Click on the style to display the formula it computes and its coefficients as specified by the associated pair_coeff
command.

850 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.85.4 Restrictions

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.

16.85.5 Related commands

pair_style, pair_modify, read_data, read_restart, pair_write

16.85.6 Default

none

16.86 pair_modify command

16.86.1 Syntax

pair_modify keyword values ...

• one or more keyword/value pairs may be listed

• keyword = pair or shift or mix or table or table/disp or tabinner or tabinner/disp or tail or compute or nofdotr or
special or compute/tally
pair value = sub-style N
sub-style = sub-style of pair hybrid
N = which instance of sub-style (1 to M), only specify if sub-style is used␣
,→multiple times

mix value = geometric or arithmetic or sixthpower

shift value = yes or no
table value = N
2^N = # of values in table
table/disp value = N
2^N = # of values in table
tabinner value = cutoff
cutoff = inner cutoff at which to begin table (distance units)
tabinner/disp value = cutoff
cutoff = inner cutoff at which to begin table (distance units)
tail value = yes or no
compute value = yes or no
nofdotr value = none
special values = which wt1 wt2 wt3
which = lj/coul or lj or coul
w1,w2,w3 = 1-2, 1-3, 1-4 weights from 0.0 to 1.0 inclusive
compute/tally value = yes or no

16.86. pair_modify command 851

LAMMPS Documentation, Release stable 29Sep2021

16.86.2 Examples

pair_modify shift yes mix geometric

pair_modify tail yes
pair_modify table 12
pair_modify pair lj/cut compute no
pair_modify pair tersoff compute/tally no
pair_modify pair lj/cut/coul/long 1 special lj/coul 0.0 0.0 0.0
pair_modify pair lj/cut/coul/long special lj 0.0 0.0 0.5 special coul 0.0 0.0 0.8333333

16.86.3 Description

Modify the parameters of the currently defined pair style. If the pair style is hybrid or hybrid/overlay, then the specified
parameters are by default modified for all the hybrid sub-styles.

Note: The behavior for hybrid pair styles can be changed by using the pair keyword, which allows selection of a
specific sub-style to apply all remaining keywords to. The special and compute/tally keywords can only be used in
conjunction with the pair keyword. See further details about these 3 keywords below.

The mix keyword affects pair coefficients for interactions between atoms of type I and J, when I != J and the coefficients
are not explicitly set in the input script. Note that coefficients for I = J must be set explicitly, either in the input script
via the pair_coeff command or in the “Pair Coeffs” section of the data file. For some pair styles it is not necessary to
specify coefficients when I != J, since a “mixing” rule will create them from the I,I and J,J settings. The pair_modify
mix value determines what formulas are used to compute the mixed coefficients. In each case, the cutoff distance is
mixed the same way as sigma.
Note that not all pair styles support mixing and some mix options are not available for certain pair styles. Also, there
are additional restrictions when using pair style hybrid or hybrid/overlay. See the page for individual pair styles for
those restrictions. Note also that the pair_coeff command also can be used to directly set coefficients for a specific I
!= J pairing, in which case no mixing is performed.
• mix geometric
√
ij = i j
√
σij = σi σj

• mix arithmetic
√
ij = i j
1
σij = (σi + σj )
2

• mix sixthpower
√
2 i j σi3 σj3
ij =
σi6 + σj6
  61
1 6
σij = (σi + σj6 )
2

The shift keyword determines whether a Lennard-Jones potential is shifted at its cutoff to 0.0. If so, this adds an energy
term to each pairwise interaction which will be included in the thermodynamic output, but does not affect pair forces
or atom trajectories. See the doc page for individual pair styles to see which ones support this option.

852 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The table and table/disp keywords apply to pair styles with a long-range Coulombic term or long-range dispersion term
respectively; see the page for individual styles to see which potentials support these options. If N is non-zero, a table
of length 2^N is pre-computed for forces and energies, which can shrink their computational cost by up to a factor of
2. The table is indexed via a bit-mapping technique (Wolff) and a linear interpolation is performed between adjacent
table values. In our experiments with different table styles (lookup, linear, spline), this method typically gave the best
performance in terms of speed and accuracy.
The choice of table length is a tradeoff in accuracy versus speed. A larger N yields more accurate force computations,
but requires more memory which can slow down the computation due to cache misses. A reasonable value of N is
between 8 and 16. The default value of 12 (table of length 4096) gives approximately the same accuracy as the no-table
(N = 0) option. For N = 0, forces and energies are computed directly, using a polynomial fit for the needed erfc()
function evaluation, which is what earlier versions of LAMMPS did. Values greater than 16 typically slow down the
simulation and will not improve accuracy; values from 1 to 8 give unreliable results.
The tabinner and tabinner/disp keywords set an inner cutoff above which the pairwise computation is done by table
lookup (if tables are invoked), for the corresponding Coulombic and dispersion tables discussed with the table and
table/disp keywords. The smaller the cutoff is set, the less accurate the table becomes (for a given number of table
values), which can require use of larger tables. The default cutoff value is sqrt(2.0) distance units which means nearly
all pairwise interactions are computed via table lookup for simulations with “real” units, but some close pairs may be
computed directly (non-table) for simulations with “lj” units.
When the tail keyword is set to yes, certain pair styles will add a long-range VanderWaals tail “correction” to the
energy and pressure. These corrections are bookkeeping terms which do not affect dynamics, unless a constant-pressure
simulation is being performed. See the page for individual styles to see which support this option. These corrections
are included in the calculation and printing of thermodynamic quantities (see the thermo_style command). Their effect
will also be included in constant NPT or NPH simulations where the pressure influences the simulation box dimensions
(e.g. the fix npt and fix nph commands). The formulas used for the long-range corrections come from equation 5 of
(Sun).

Note: The tail correction terms are computed at the beginning of each run, using the current atom counts of each atom
type. If atoms are deleted (or lost) or created during a simulation, e.g. via the fix gcmc command, the correction factors
are not re-computed. If you expect the counts to change dramatically, you can break a run into a series of shorter runs
so that the correction factors are re-computed more frequently.

Several additional assumptions are inherent in using tail corrections, including the following:
• The simulated system is a 3d bulk homogeneous liquid. This option should not be used for systems that are
non-liquid, 2d, have a slab geometry (only 2d periodic), or inhomogeneous.
• G(r), the radial distribution function (rdf), is unity beyond the cutoff, so a fairly large cutoff should be used (i.e.
2.5 sigma for an LJ fluid), and it is probably a good idea to verify this assumption by checking the rdf. The rdf
is not exactly unity beyond the cutoff for each pair of interaction types, so the tail correction is necessarily an
approximation.
The tail corrections are computed at the beginning of each simulation run. If the number of atoms changes during
the run, e.g. due to atoms leaving the simulation domain, or use of the fix gcmc command, then the corrections
are not updated to reflect the changed atom count. If this is a large effect in your simulation, you should break
the long run into several short runs, so that the correction factors are re-computed multiple times.
• Thermophysical properties obtained from calculations with this option enabled will not be thermodynamically
consistent with the truncated force-field that was used. In other words, atoms do not feel any LJ pair interactions
beyond the cutoff, but the energy and pressure reported by the simulation include an estimated contribution from
those interactions.
The compute keyword allows pairwise computations to be turned off, even though a pair_style is defined. This is not
useful for running a real simulation, but can be useful for debugging purposes or for performing a rerun simulation,
when you only wish to compute partial forces that do not include the pairwise contribution.

16.86. pair_modify command 853

LAMMPS Documentation, Release stable 29Sep2021

Two examples are as follows. First, this option allows you to perform a simulation with pair_style hybrid with only a
subset of the hybrid sub-styles enabled. Second, this option allows you to perform a simulation with only long-range
interactions but no short-range pairwise interactions. Doing this by simply not defining a pair style will not work,
because the kspace_style command requires a Kspace-compatible pair style be defined.
The nofdotr keyword allows to disable an optimization that computes the global stress tensor from the total forces and
atom positions rather than from summing forces between individual pairs of atoms.

The pair keyword can only be used with the hybrid and hybrid/overlay pair styles. If used, it must appear first in the
list of keywords.
Its meaning is that all the following parameters will only be modified for the specified sub-style. If the sub-style is
defined multiple times, then an additional numeric argument N must also be specified, which is a number from 1 to M
where M is the number of times the sub-style was listed in the pair_style hybrid command. The extra number indicates
which instance of the sub-style the remaining keywords will be applied to.
The special and compute/tally keywords can only be used in conjunction with the pair keyword and they must directly
follow it. I.e. any other keyword, must appear after pair, special, and compute/tally.
The special keyword overrides the global special_bonds 1-2, 1-3, 1-4 exclusion settings (weights) for the sub-style
selected by the pair keyword.
Similar to the special_bonds command, it takes 4 arguments. The which argument can be lj to change only the non-
Coulomb weights (e.g. Lennard-Jones or Buckingham), coul to change only the Coulombic settings, or lj/coul to
change both to the same values. The wt1,wt2,wt3 values are numeric weights from 0.0 to 1.0 inclusive, for the 1-2, 1-3,
and 1-4 bond topology neighbors, respectively. The special keyword can be used multiple times, e.g. to set the lj and
coul settings to different values.

Note: The special keyword is not compatible with pair styles from the GPU or the INTEL package and attempting to
use it will cause an error.

Note: Weights of exactly 0.0 or 1.0 in the special_bonds command have implications on the neighbor list construction,
which means that they cannot be overridden by using the special keyword. One workaround for this restriction is to
use the special_bonds command with weights like 1.0e-10 or 0.999999999 instead of 0.0 or 1.0, respectively, which
enables to reset each them to any value between 0.0 and 1.0 inclusively. Otherwise you can set all global weights to an
arbitrary number between 0.0 or 1.0, like 0.5, and then you have to override all special settings for all sub-styles which
use the 1-2, 1-3, and 1-4 exclusion weights in their force/energy computation.

The compute/tally keyword disables or enables registering compute */tally computes for the sub-style specified by the
pair keyword. Use no to disable, or yes to enable.

Note: The “pair_modify pair compute/tally” command must be issued before the corresponding compute style is
defined.

854 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.86.4 Restrictions

You cannot use shift yes with tail yes, since those are conflicting options. You cannot use tail yes with 2d simulations.
You cannot use special with pair styles from the GPU or INTEL package.

16.86.5 Related commands

pair_style, pair_style hybrid, pair_coeff , thermo_style, compute */tally

16.86.6 Default

The option defaults are mix = geometric, shift = no, table = 12, tabinner = sqrt(2.0), tail = no, and compute = yes.
Note that some pair styles perform mixing, but only a certain style of mixing. See the doc pages for individual pair
styles for details.

(Wolff) Wolff and Rudd, Comp Phys Comm, 120, 200-32 (1999).
(Sun) Sun, J Phys Chem B, 102, 7338-7364 (1998).

16.87 pair_style command

16.87.1 Syntax

pair_style style args

• style = one of the styles from the list below

• args = arguments used by a particular style

16.87.2 Examples

pair_style lj/cut 2.5

pair_style eam/alloy
pair_style hybrid lj/charmm/coul/long 10.0 eam
pair_style table linear 1000
pair_style none

16.87.3 Description

Set the formula(s) LAMMPS uses to compute pairwise interactions. In LAMMPS, pair potentials are defined between
pairs of atoms that are within a cutoff distance and the set of active interactions typically changes over time. See
the bond_style command to define potentials between pairs of bonded atoms, which typically remain in place for the
duration of a simulation.
In LAMMPS, pairwise force fields encompass a variety of interactions, some of which include many-body effects, e.g.
EAM, Stillinger-Weber, Tersoff, REBO potentials. They are still classified as “pairwise” potentials because the set of

16.87. pair_style command 855

LAMMPS Documentation, Release stable 29Sep2021

interacting atoms changes with time (unlike molecular bonds) and thus a neighbor list is used to find nearby interacting
atoms.
Hybrid models where specified pairs of atom types interact via different pair potentials can be setup using the hybrid
pair style.
The coefficients associated with a pair style are typically set for each pair of atom types, and are specified by the
pair_coeff command or read from a file by the read_data or read_restart commands.
The pair_modify command sets options for mixing of type I-J interaction coefficients and adding energy offsets or tail
corrections to Lennard-Jones potentials. Details on these options as they pertain to individual potentials are described
on the doc page for the potential. Likewise, info on whether the potential information is stored in a restart file is listed
on the potential doc page.
In the formulas listed for each pair style, E is the energy of a pairwise interaction between two atoms separated by a
distance r. The force between the atoms is the negative derivative of this expression.
If the pair_style command has a cutoff argument, it sets global cutoffs for all pairs of atom types. The distance(s) can
be smaller or larger than the dimensions of the simulation box.
Typically, the global cutoff value can be overridden for a specific pair of atom types by the pair_coeff command. The
pair style settings (including global cutoffs) can be changed by a subsequent pair_style command using the same style.
This will reset the cutoffs for all atom type pairs, including those previously set explicitly by a pair_coeff command.
The exceptions to this are that pair_style table and hybrid settings cannot be reset. A new pair_style command for these
styles will wipe out all previously specified pair_coeff values.

Here is an alphabetic list of pair styles defined in LAMMPS. They are also listed in more compact form on the Com-
mands pair doc page.
Click on the style to display the formula it computes, any additional arguments specified in the pair_style command,
and coefficients specified by the associated pair_coeff command.
There are also additional accelerated pair styles included in the LAMMPS distribution for faster performance on CPUs,
GPUs, and KNLs. The individual style names on the Commands pair doc page are followed by one or more of (g,i,k,o,t)
to indicate which accelerated styles exist.
• none - turn off pairwise interactions
• hybrid - multiple styles of pairwise interactions
• hybrid/overlay - multiple styles of superposed pairwise interactions
• hybrid/scaled - multiple styles of scaled superposed pairwise interactions
• zero - neighbor list but no interactions
• adp - angular dependent potential (ADP) of Mishin
• agni - AGNI machine-learning potential
• airebo - AIREBO potential of Stuart
• airebo/morse - AIREBO with Morse instead of LJ
• atm - Axilrod-Teller-Muto potential
• awpmd/cut - Antisymmetrized Wave Packet MD potential for atoms and electrons
• beck - Beck potential
• body/nparticle - interactions between body particles
• body/rounded/polygon - granular-style 2d polygon potential

856 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• body/rounded/polyhedron - granular-style 3d polyhedron potential

• bop - BOP potential of Pettifor
• born - Born-Mayer-Huggins potential
• born/coul/dsf - Born with damped-shifted-force model
• born/coul/dsf/cs - Born with damped-shifted-force and core/shell model
• born/coul/long - Born with long-range Coulomb
• born/coul/long/cs - Born with long-range Coulomb and core/shell
• born/coul/msm - Born with long-range MSM Coulomb
• born/coul/wolf - Born with Wolf potential for Coulomb
• born/coul/wolf/cs - Born with Wolf potential for Coulomb and core/shell model
• brownian - Brownian potential for Fast Lubrication Dynamics
• brownian/poly - Brownian potential for Fast Lubrication Dynamics with polydispersity
• buck - Buckingham potential
• buck/coul/cut - Buckingham with cutoff Coulomb
• buck/coul/long - Buckingham with long-range Coulomb
• buck/coul/long/cs - Buckingham with long-range Coulomb and core/shell
• buck/coul/msm - Buckingham with long-range MSM Coulomb
• buck/long/coul/long - long-range Buckingham with long-range Coulomb
• buck/mdf - Buckingham with a taper function
• buck6d/coul/gauss/dsf - dispersion-damped Buckingham with damped-shift-force model
• buck6d/coul/gauss/long - dispersion-damped Buckingham with long-range Coulomb
• colloid - integrated colloidal potential
• comb - charge-optimized many-body (COMB) potential
• comb3 - charge-optimized many-body (COMB3) potential
• cosine/squared - Cooke-Kremer-Deserno membrane model potential
• coul/cut - cutoff Coulomb potential
• coul/cut/dielectric -
• coul/cut/global - cutoff Coulomb potential
• coul/cut/soft - Coulomb potential with a soft core
• coul/debye - cutoff Coulomb potential with Debye screening
• coul/diel - Coulomb potential with dielectric permittivity
• coul/dsf - Coulomb with damped-shifted-force model
• coul/exclude - subtract Coulomb potential for excluded pairs
• coul/long - long-range Coulomb potential
• coul/long/cs - long-range Coulomb potential and core/shell
• coul/long/dielectric -

16.87. pair_style command 857

LAMMPS Documentation, Release stable 29Sep2021

• coul/long/soft - long-range Coulomb potential with a soft core

• coul/msm - long-range MSM Coulomb
• coul/slater/cut - smeared out Coulomb
• coul/slater/long - long-range smeared out Coulomb
• coul/shield - Coulomb for boron nitride for use with ilp/graphene/hbn potential
• coul/streitz - Coulomb via Streitz/Mintmire Slater orbitals
• coul/tt - damped charge-dipole Coulomb for Drude dipoles
• coul/wolf - Coulomb via Wolf potential
• coul/wolf/cs - Coulomb via Wolf potential with core/shell adjustments
• dpd - dissipative particle dynamics (DPD)
• dpd/ext - generalized force field for DPD
• dpd/ext/tstat - pair-wise DPD thermostatting with generalized force field
• dpd/fdt - DPD for constant temperature and pressure
• dpd/fdt/energy - DPD for constant energy and enthalpy
• dpd/tstat - pair-wise DPD thermostatting
• dsmc - Direct Simulation Monte Carlo (DSMC)
• e3b - Explicit-three body (E3B) water model
• drip - Dihedral-angle-corrected registry-dependent interlayer potential (DRIP)
• eam - embedded atom method (EAM)
• eam/alloy - alloy EAM
• eam/cd - concentration-dependent EAM
• eam/cd/old - older two-site model for concentration-dependent EAM
• eam/fs - Finnis-Sinclair EAM
• eam/he - Finnis-Sinclair EAM modified for Helium in metals
• edip - three-body EDIP potential
• edip/multi - multi-element EDIP potential
• edpd - eDPD particle interactions
• eff/cut - electron force field with a cutoff
• eim - embedded ion method (EIM)
• exp6/rx - reactive DPD potential
• extep - extended Tersoff potential
• gauss - Gaussian potential
• gauss/cut - generalized Gaussian potential
• gayberne - Gay-Berne ellipsoidal potential
• granular - Generalized granular potential
• gran/hertz/history - granular potential with Hertzian interactions

858 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• gran/hooke - granular potential with history effects

• gran/hooke/history - granular potential without history effects
• gw - Gao-Weber potential
• gw/zbl - Gao-Weber potential with a repulsive ZBL core
• hbond/dreiding/lj - DREIDING hydrogen bonding LJ potential
• hbond/dreiding/morse - DREIDING hydrogen bonding Morse potential
• hdnnp - High-dimensional neural network potential
• ilp/graphene/hbn - registry-dependent interlayer potential (ILP)
• kim - interface to potentials provided by KIM project
• kolmogorov/crespi/full - Kolmogorov-Crespi (KC) potential with no simplifications
• kolmogorov/crespi/z - Kolmogorov-Crespi (KC) potential with normals along z-axis
• lcbop - long-range bond-order potential (LCBOP)
• lebedeva/z - Lebedeva interlayer potential for graphene with normals along z-axis
• lennard/mdf - LJ potential in A/B form with a taper function
• line/lj - LJ potential between line segments
• list - potential between pairs of atoms explicitly listed in an input file
• lj/charmm/coul/charmm - CHARMM potential with cutoff Coulomb
• lj/charmm/coul/charmm/implicit - CHARMM for implicit solvent
• lj/charmm/coul/long - CHARMM with long-range Coulomb
• lj/charmm/coul/long/soft - CHARMM with long-range Coulomb and a soft core
• lj/charmm/coul/msm - CHARMM with long-range MSM Coulomb
• lj/charmmfsw/coul/charmmfsh - CHARMM with force switching and shifting
• lj/charmmfsw/coul/long - CHARMM with force switching and long-rnage Coulomb
• lj/class2 - COMPASS (class 2) force field without Coulomb
• lj/class2/coul/cut - COMPASS with cutoff Coulomb
• lj/class2/coul/cut/soft - COMPASS with cutoff Coulomb with a soft core
• lj/class2/coul/long - COMPASS with long-range Coulomb
• lj/class2/coul/long/cs - COMPASS with long-range Coulomb with core/shell adjustments
• lj/class2/coul/long/soft - COMPASS with long-range Coulomb with a soft core
• lj/class2/soft - COMPASS (class 2) force field with no Coulomb with a soft core
• lj/cubic - LJ with cubic after inflection point
• lj/cut - cutoff Lennard-Jones potential without Coulomb
• lj/cut/coul/cut - LJ with cutoff Coulomb
• lj/cut/coul/cut/dielectric -
• lj/cut/coul/cut/soft - LJ with cutoff Coulomb with a soft core
• lj/cut/coul/debye - LJ with Debye screening added to Coulomb

16.87. pair_style command 859

LAMMPS Documentation, Release stable 29Sep2021

• lj/cut/coul/debye/dielectric -
• lj/cut/coul/dsf - LJ with Coulomb via damped shifted forces
• lj/cut/coul/long - LJ with long-range Coulomb
• lj/cut/coul/long/cs - LJ with long-range Coulomb with core/shell adjustments
• lj/cut/coul/long/dielectric -
• lj/cut/coul/long/soft - LJ with long-range Coulomb with a soft core
• lj/cut/coul/msm - LJ with long-range MSM Coulomb
• lj/cut/coul/msm/dielectric -
• lj/cut/coul/wolf - LJ with Coulomb via Wolf potential
• lj/cut/dipole/cut - point dipoles with cutoff
• lj/cut/dipole/long - point dipoles with long-range Ewald
• lj/cut/soft - LJ with a soft core
• lj/cut/thole/long - LJ with Coulomb with thole damping
• lj/cut/tip4p/cut - LJ with cutoff Coulomb for TIP4P water
• lj/cut/tip4p/long - LJ with long-range Coulomb for TIP4P water
• lj/cut/tip4p/long/soft - LJ with cutoff Coulomb for TIP4P water with a soft core
• lj/expand - Lennard-Jones for variable size particles
• lj/expand/coul/long - Lennard-Jones for variable size particles with long-range Coulomb
• lj/gromacs - GROMACS-style Lennard-Jones potential
• lj/gromacs/coul/gromacs - GROMACS-style LJ and Coulomb potential
• lj/long/coul/long - long-range LJ and long-range Coulomb
• lj/long/coul/long/dielectric -
• lj/long/dipole/long - long-range LJ and long-range point dipoles
• lj/long/tip4p/long - long-range LJ and long-range Coulomb for TIP4P water
• lj/mdf - LJ potential with a taper function
• lj/relres - LJ using multiscale Relative Resolution (RelRes) methodology (Chaimovich).
• lj/sdk - LJ for SDK coarse-graining
• lj/sdk/coul/long - LJ for SDK coarse-graining with long-range Coulomb
• lj/sdk/coul/msm - LJ for SDK coarse-graining with long-range Coulomb via MSM
• lj/sf/dipole/sf - LJ with dipole interaction with shifted forces
• lj/smooth - smoothed Lennard-Jones potential
• lj/smooth/linear - linear smoothed LJ potential
• lj/switch3/coulgauss/long - smoothed LJ vdW potential with Gaussian electrostatics
• lj96/cut - Lennard-Jones 9/6 potential
• local/density - generalized basic local density potential
• lubricate - hydrodynamic lubrication forces

860 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• lubricate/poly - hydrodynamic lubrication forces with polydispersity

• lubricateU - hydrodynamic lubrication forces for Fast Lubrication Dynamics
• lubricateU/poly - hydrodynamic lubrication forces for Fast Lubrication with polydispersity
• mdpd - mDPD particle interactions
• mdpd/rhosum - mDPD particle interactions for mass density
• meam - modified embedded atom method (MEAM) in C
• meam/spline - splined version of MEAM
• meam/sw/spline - splined version of MEAM with a Stillinger-Weber term
• mesocnt - mesoscale model for (carbon) nanotubes
• mgpt - simplified model generalized pseudopotential theory (MGPT) potential
• mesont/tpm - nanotubes mesoscopic force field
• mie/cut - Mie potential
• mm3/switch3/coulgauss/long - smoothed MM3 vdW potential with Gaussian electrostatics
• momb - Many-Body Metal-Organic (MOMB) force field
• morse - Morse potential
• morse/smooth/linear - linear smoothed Morse potential
• morse/soft - Morse potential with a soft core
• multi/lucy - DPD potential with density-dependent force
• multi/lucy/rx - reactive DPD potential with density-dependent force
• nb3b/harmonic - non-bonded 3-body harmonic potential
• nm/cut - N-M potential
• nm/cut/coul/cut - N-M potential with cutoff Coulomb
• nm/cut/coul/long - N-M potential with long-range Coulomb
• oxdna/coaxstk -
• oxdna/excv -
• oxdna/hbond -
• oxdna/stk -
• oxdna/xstk -
• oxdna2/coaxstk -
• oxdna2/dh -
• oxdna2/excv -
• oxdna2/hbond -
• oxdna2/stk -
• oxdna2/xstk -
• oxrna2/coaxstk -
• oxrna2/dh -

16.87. pair_style command 861

LAMMPS Documentation, Release stable 29Sep2021

• oxrna2/excv -
• oxrna2/hbond -
• oxrna2/stk -
• oxrna2/xstk -
• pace - Atomic Cluster Expansion (ACE) machine-learning potential
• peri/eps - peridynamic EPS potential
• peri/lps - peridynamic LPS potential
• peri/pmb - peridynamic PMB potential
• peri/ves - peridynamic VES potential
• polymorphic - polymorphic 3-body potential
• python -
• quip -
• rann -
• reaxff - ReaxFF potential
• rebo - second generation REBO potential of Brenner
• resquared - Everaers RE-Squared ellipsoidal potential
• sdpd/taitwater/isothermal - smoothed dissipative particle dynamics for water at isothermal conditions
• smd/hertz -
• smd/tlsph -
• smd/tri_surface -
• smd/ulsph -
• smtbq -
• mliap - Multiple styles of machine-learning potential
• snap - SNAP machine-learning potential
• soft - Soft (cosine) potential
• sph/heatconduction -
• sph/idealgas -
• sph/lj -
• sph/rhosum -
• sph/taitwater -
• sph/taitwater/morris -
• spin/dipole/cut -
• spin/dipole/long -
• spin/dmi -
• spin/exchange -
• spin/exchange/biquadratic -

862 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• spin/magelec -
• spin/neel -
• srp -
• sw - Stillinger-Weber 3-body potential
• table - tabulated pair potential
• table/rx -
• tdpd - tDPD particle interactions
• tersoff - Tersoff 3-body potential
• tersoff/mod - modified Tersoff 3-body potential
• tersoff/mod/c -
• tersoff/table -
• tersoff/zbl - Tersoff/ZBL 3-body potential
• thole - Coulomb interactions with thole damping
• tip4p/cut - Coulomb for TIP4P water w/out LJ
• tip4p/long - long-range Coulomb for TIP4P water w/out LJ
• tip4p/long/soft -
• tracker - monitor information about pairwise interactions
• tri/lj - LJ potential between triangles
• ufm -
• vashishta - Vashishta 2-body and 3-body potential
• vashishta/table -
• wf/cut - Wang-Frenkel Potential for short-ranged interactions
• yukawa - Yukawa potential
• yukawa/colloid - screened Yukawa potential for finite-size particles
• zbl - Ziegler-Biersack-Littmark potential

16.87.4 Restrictions

This command must be used before any coefficients are set by the pair_coeff , read_data, or read_restart commands.
Some pair styles are part of specific packages. They are only enabled if LAMMPS was built with that package. See
the Build package page for more info. The doc pages for individual pair potentials tell if it is part of a package.

16.87. pair_style command 863

LAMMPS Documentation, Release stable 29Sep2021

16.87.5 Related commands

pair_coeff , read_data, pair_modify, kspace_style, dielectric, pair_write

16.87.6 Default

pair_style none

16.88 pair_write command

16.88.1 Syntax

pair_write itype jtype N style inner outer file keyword Qi Qj

• itype,jtype = 2 atom types

• N = # of values
• style = r or rsq or bitmap
• inner,outer = inner and outer cutoff (distance units)
• file = name of file to write values to
• keyword = section name in file for this set of tabulated values
• Qi,Qj = 2 atom charges (charge units) (optional)

16.88.2 Examples

pair_write 1 3 500 r 1.0 10.0 table.txt LJ

pair_write 1 1 1000 rsq 2.0 8.0 table.txt Yukawa_1_1 -0.5 0.5

16.88.3 Description

Write energy and force values to a file as a function of distance for the currently defined pair potential. This is useful
for plotting the potential function or otherwise debugging its values. If the file already exists, the table of values is
appended to the end of the file to allow multiple tables of energy and force to be included in one file. In case a new
file is created, the first line will be a comment containing a “DATE:” and “UNITS:” tag with the current date and the
current units setting as argument. For subsequent invocations of the pair_write command, the current units setting is
compared against the entry in the file, if present, and pair_write will refuse to add a table if the units are not the same.
The energy and force values are computed at distances from inner to outer for 2 interacting atoms of type itype and
jtype, using the appropriate pair_coeff coefficients. If the style is r, then N distances are used, evenly spaced in r; if
the style is rsq, N distances are used, evenly spaced in r^2.
For example, for N = 7, style = r, inner = 1.0, and outer = 4.0, values are computed at r = 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0.
If the style is bitmap, then 2^N values are written to the file in a format and order consistent with how they are read in by
the pair_coeff command for pair style table. For reasonable accuracy in a bitmapped table, choose N >= 12, an inner
value that is smaller than the distance of closest approach of 2 atoms, and an outer value <= cutoff of the potential.

864 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

If the pair potential is computed between charged atoms, the charges of the pair of interacting atoms can optionally be
specified. If not specified, values of Qi = Qj = 1.0 are used.
The file is written in the format used as input for the pair_style table option with keyword as the section name. Each
line written to the file lists an index number (1-N), a distance (in distance units), an energy (in energy units), and a force
(in force units).

16.88.4 Restrictions

All force field coefficients for pair and other kinds of interactions must be set before this command can be invoked.
Due to how the pairwise force is computed, an inner value > 0.0 must be specified even if the potential has a finite value
at r = 0.0.
For EAM potentials, the pair_write command only tabulates the pairwise portion of the potential, not the embedding
portion.

16.88.5 Related commands

pair_style table, pair_style, pair_coeff

16.88.6 Default

none

16.89 partition command

16.89.1 Syntax

partition style N command ...

• style = yes or no
• N = partition number (see asterisk form below)
• command = any LAMMPS command

16.89.2 Examples

partition yes 1 processors 4 10 6

partition no 5 print "Active partition"
partition yes *5 fix all nve
partition yes 6* fix all nvt temp 1.0 1.0 0.1

16.89. partition command 865

LAMMPS Documentation, Release stable 29Sep2021

16.89.3 Description

This command invokes the specified command on a subset of the partitions of processors you have defined via the
-partition command-line switch.
Normally, every input script command in your script is invoked by every partition. This behavior can be modified by
defining world- or universe-style variables that have different values for each partition. This mechanism can be used
to cause your script to jump to different input script files on different partitions, if such a variable is used in a jump
command.
The “partition” command is another mechanism for having as input script operate differently on different partitions. It
is basically a prefix on any LAMMPS command. The command will only be invoked on the partition(s) specified by
the style and N arguments.
If the style is yes, the command will be invoked on any partition which matches the N argument. If the style is no the
command will be invoked on all the partitions which do not match the Np argument.
Partitions are numbered from 1 to Np, where Np is the number of partitions specified by the -partition command-line
switch.
N can be specified in one of two ways. An explicit numeric value can be used, as in the first example above. Or a
wild-card asterisk can be used to span a range of partition numbers. This takes the form “*” or “*n” or “n*” or “m*n”.
An asterisk with no numeric values means all partitions from 1 to Np. A leading asterisk means all partitions from 1 to
n (inclusive). A trailing asterisk means all partitions from n to Np (inclusive). A middle asterisk means all partitions
from m to n (inclusive).
This command can be useful for the “run_style verlet/split” command which imposed requirements on how the pro-
cessors command lays out a 3d grid of processors in each of 2 partitions.

16.89.4 Restrictions

none

16.89.5 Related commands

run_style verlet/split

16.89.6 Default

none

16.90 plugin command

16.90.1 Syntax

plugin command args

• command = load or unload or list or clear

• args = list of arguments for a particular plugin command

866 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

load file = load plugin(s) from shared object in file

unload style name = unload plugin name of style style
style = pair or bond or angle or dihedral or improper or compute or fix or␣
,→region or command

list = print a list of currently loaded plugins

clear = unload all currently loaded plugins

16.90.2 Examples

plugin load morse2plugin.so

plugin unload pair morse2/omp
plugin unload command hello
plugin list
plugin clear

16.90.3 Description

The plugin command allows to load (and unload) additional styles and commands into a LAMMPS binary from so-
called dynamic shared object (DSO) files. This enables to add new functionality to an existing LAMMPS binary
without having to recompile and link the entire executable.
The load command will load and initialize all plugins contained in the plugin DSO with the given filename. A message
with information the plugin style and name and more will be printed. Individual DSO files may contain multiple plugins.
More details about how to write and compile the plugin DSO is given in programmer’s guide part of the manual under
Writing plugins.
The unload command will remove the given style or the given name from the list of available styles. If the plugin style
is currently in use, that style instance will be deleted.
The list command will print a list of the loaded plugins and their styles and names.
The clear command will unload all currently loaded plugins.

16.90.4 Restrictions

The plugin command is part of the PLUGIN package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info. Plugins are not available on Windows.
For the loading of plugins to work the LAMMPS library must be compiled as a shared library. If plugins access
functions or classes from a package, LAMMPS must have been compiled with that package included.
Plugins are dependent on the LAMMPS binary interface (ABI) and particularly the MPI library used. So they are not
guaranteed to work when the plugin was compiled with a different MPI library or different compilation settings or a
different LAMMPS version. There are no checks, so if there is a mismatch the plugin object will either not load or data
corruption and crashes may happen.

16.90. plugin command 867

LAMMPS Documentation, Release stable 29Sep2021

16.90.5 Related commands

none

16.90.6 Default

none

16.91 prd command

16.91.1 Syntax

prd N t_event n_dephase t_dephase t_correlate compute-ID seed keyword value ...

• N = # of timesteps to run (not including dephasing/quenching)

• t_event = timestep interval between event checks
• n_dephase = number of velocity randomizations to perform in each dephase run
• t_dephase = number of timesteps to run dynamics after each velocity randomization during dephase
• t_correlate = number of timesteps within which 2 consecutive events are considered to be correlated
• compute-ID = ID of the compute used for event detection
• random_seed = random # seed (positive integer)
• zero or more keyword/value pairs may be appended
• keyword = min or temp or vel
min values = etol ftol maxiter maxeval
etol = stopping tolerance for energy, used in quenching
ftol = stopping tolerance for force, used in quenching
maxiter = max iterations of minimize, used in quenching
maxeval = max number of force/energy evaluations, used in quenching
temp value = Tdephase
Tdephase = target temperature for velocity randomization, used in dephasing
vel values = loop dist
loop = all or local or geom, used in dephasing
dist = uniform or gaussian, used in dephasing
time value = steps or clock
steps = simulation runs for N timesteps on each replica (default)
clock = simulation runs for N timesteps across all replicas

868 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.91.2 Examples

prd 5000 100 10 10 100 1 54982

prd 5000 100 10 10 100 1 54982 min 0.1 0.1 100 200

16.91.3 Description

Run a parallel replica dynamics (PRD) simulation using multiple replicas of a system. One or more replicas can be
used. The total number of steps N to run can be interpreted in one of two ways; see discussion of the time keyword
below.
PRD is described in (Voter1998) by Art Voter. Similar to global or local hyperdynamics (HD), PRD is a method for
performing accelerated dynamics that is suitable for infrequent-event systems that obey first-order kinetics. A good
overview of accelerated dynamics methods (AMD) for such systems in given in this review paper (Voter2002) from
Art’s group. To quote from the paper: “The dynamical evolution is characterized by vibrational excursions within a
potential basin, punctuated by occasional transitions between basins. The transition probability is characterized by p(t)
= k*exp(-kt) where k is the rate constant.”
Both PRD and HD produce a time-accurate trajectory that effectively extends the timescale over which a system can be
simulated, but they do it differently. PRD creates Nr replicas of the system and runs dynamics on each independently
with a normal unbiased potential until an event occurs in one of the replicas. The time between events is reduced by a
factor of Nr replicas. HD uses a single replica of the system and accelerates time by biasing the interaction potential in
a manner such that each timestep is effectively longer. For both methods, per CPU second, more physical time elapses
and more events occur. See the hyper page for more info about HD.
In PRD, each replica runs on a partition of one or more processors. Processor partitions are defined at run-time using the
-partition command-line switch. Note that if you have MPI installed, you can run a multi-replica simulation with more
replicas (partitions) than you have physical processors, e.g you can run a 10-replica simulation on one or two processors.
However for PRD, this makes little sense, since running a replica on virtual instead of physical processors,offers no
effective parallel speed-up in searching for infrequent events. See the Howto replica doc page for further discussion.
When a PRD simulation is performed, it is assumed that each replica is running the same model, though LAMMPS
does not check for this. I.e. the simulation domain, the number of atoms, the interaction potentials, etc should be the
same for every replica.
A PRD run has several stages, which are repeated each time an “event” occurs in one of the replicas, as explained
below. The logic for a PRD run is as follows:
while (time remains):
dephase for n_dephase*t_dephase steps
until (event occurs on some replica):
run dynamics for t_event steps
quench
check for uncorrelated event on any replica
until (no correlated event occurs):
run dynamics for t_correlate steps
quench
check for correlated event on this replica
event replica shares state with all replicas
Before this loop begins, the state of the system on replica 0 is shared with all replicas, so that all replicas begin from
the same initial state. The first potential energy basin is identified by quenching (an energy minimization, see below)
the initial state and storing the resulting coordinates for reference.
In the first stage, dephasing is performed by each replica independently to eliminate correlations between replicas.
This is done by choosing a random set of velocities, based on the random_seed that is specified, and running t_dephase

16.91. prd command 869

LAMMPS Documentation, Release stable 29Sep2021

timesteps of dynamics. This is repeated n_dephase times. At each of the n_dephase stages, if an event occurs during
the t_dephase steps of dynamics for a particular replica, the replica repeats the stage until no event occurs.
If the temp keyword is not specified, the target temperature for velocity randomization for each replica is the current
temperature of that replica. Otherwise, it is the specified Tdephase temperature. The style of velocity randomization
is controlled using the keyword vel with arguments that have the same meaning as their counterparts in the velocity
command.
In the second stage, each replica runs dynamics continuously, stopping every t_event steps to check if a transition event
has occurred. This check is performed by quenching the system and comparing the resulting atom coordinates to the
coordinates from the previous basin. The first time through the PRD loop, the “previous basin” is the set of quenched
coordinates from the initial state of the system.
A quench is an energy minimization and is performed by whichever algorithm has been defined by the min_style
command. Minimization parameters may be set via the min_modify command and by the min keyword of the PRD
command. The latter are the settings that would be used with the minimize command. Note that typically, you do
not need to perform a highly-converged minimization to detect a transition event, though you may need to in order to
prevent a set of atoms in the system from relaxing to a saddle point.
The event check is performed by a compute with the specified compute-ID. Currently there is only one compute that
works with the PRD command, which is the compute event/displace command. Other event-checking computes may
be added. Compute event/displace checks whether any atom in the compute group has moved further than a specified
threshold distance. If so, an “event” has occurred.
In the third stage, the replica on which the event occurred (event replica) continues to run dynamics to search for
correlated events. This is done by running dynamics for t_correlate steps, quenching every t_event steps, and checking
if another event has occurred.
The first time no correlated event occurs, the final state of the event replica is shared with all replicas, the new basin
reference coordinates are updated with the quenched state, and the outer loop begins again. While the replica event is
searching for correlated events, all the other replicas also run dynamics and event checking with the same schedule, but
the final states are always overwritten by the state of the event replica.
The outer loop of the pseudo-code above continues until N steps of dynamics have been performed. Note that N
only includes the dynamics of stages 2 and 3, not the steps taken during dephasing or the minimization iterations of
quenching. The specified N is interpreted in one of two ways, depending on the time keyword. If the time value is steps,
which is the default, then each replica runs for N timesteps. If the time value is clock, then the simulation runs until
N aggregate timesteps across all replicas have elapsed. This aggregate time is the “clock” time defined below, which
typically advances nearly M times faster than the timestepping on a single replica, where M is the number of replicas.

Four kinds of output can be generated during a PRD run: event statistics, thermodynamic output by each replica, dump
files, and restart files.
When running with multiple partitions (each of which is a replica in this case), the print-out to the screen and master
log.lammps file is limited to event statistics. Note that if a PRD run is performed on only a single replica then the event
statistics will be intermixed with the usual thermodynamic output discussed below.
The quantities printed each time an event occurs are the timestep, CPU time, clock, event number, a correlation flag,
the number of coincident events, and the replica number of the chosen event.
The timestep is the usual LAMMPS timestep, except that time does not advance during dephasing or quenches, but only
during dynamics. Note that are two kinds of dynamics in the PRD loop listed above that contribute to this timestepping.
The first is when all replicas are performing independent dynamics, waiting for an event to occur. The second is when
correlated events are being searched for, but only one replica is running dynamics.
The CPU time is the total elapsed time on each processor, since the start of the PRD run.
The clock is the same as the timestep except that it advances by M steps per timestep during the first kind of dynamics
when the M replicas are running independently. The clock advances by only 1 step per timestep during the second kind

870 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

of dynamics, when only a single replica is checking for a correlated event. Thus “clock” time represents the aggregate
time (in steps) that has effectively elapsed during a PRD simulation on M replicas. If most of the PRD run is spent in
the second stage of the loop above, searching for infrequent events, then the clock will advance nearly M times faster
than it would if a single replica was running. Note the clock time between successive events should be drawn from p(t).
The event number is a counter that increments with each event, whether it is uncorrelated or correlated.
The correlation flag will be 0 when an uncorrelated event occurs during the second stage of the loop listed above, i.e.
when all replicas are running independently. The correlation flag will be 1 when a correlated event occurs during the
third stage of the loop listed above, i.e. when only one replica is running dynamics.
When more than one replica detects an event at the end of the same event check (every t_event steps) during the second
stage, then one of them is chosen at random. The number of coincident events is the number of replicas that detected
an event. Normally, this value should be 1. If it is often greater than 1, then either the number of replicas is too large,
or t_event is too large.
The replica number is the ID of the replica (from 0 to M-1) in which the event occurred.

When running on multiple partitions, LAMMPS produces additional log files for each partition, e.g. log.lammps.0,
log.lammps.1, etc. For the PRD command, these contain the thermodynamic output for each replica. You will see short
runs and minimizations corresponding to the dynamics and quench operations of the loop listed above. The timestep
will be reset appropriately depending on whether the operation advances time or not.
After the PRD command completes, timing statistics for the PRD run are printed in each replica’s log file, giving a
breakdown of how much CPU time was spent in each stage (dephasing, dynamics, quenching, etc).

Any dump files defined in the input script, will be written to during a PRD run at timesteps corresponding to both
uncorrelated and correlated events. This means the requested dump frequency in the dump command is ignored. There
will be one dump file (per dump command) created for all partitions.
The atom coordinates of the dump snapshot are those of the minimum energy configuration resulting from quenching
following a transition event. The timesteps written into the dump files correspond to the timestep at which the event
occurred and NOT the clock. A dump snapshot corresponding to the initial minimum state used for event detection is
written to the dump file at the beginning of each PRD run.

If the restart command is used, a single restart file for all the partitions is generated, which allows a PRD run to be
continued by a new input script in the usual manner.
The restart file is generated at the end of the loop listed above. If no correlated events are found, this means it contains
a snapshot of the system at time T + t_correlate, where T is the time at which the uncorrelated event occurred. If
correlated events were found, then it contains a snapshot of the system at time T + t_correlate, where T is the time of
the last correlated event.
The restart frequency specified in the restart command is interpreted differently when performing a PRD run. It does
not mean the timestep interval between restart files. Instead it means an event interval for uncorrelated events. Thus
a frequency of 1 means write a restart file every time an uncorrelated event occurs. A frequency of 10 means write a
restart file every 10th uncorrelated event.
When an input script reads a restart file from a previous PRD run, the new script can be run on a different number
of replicas or processors. However, it is assumed that t_correlate in the new PRD command is the same as it was
previously. If not, the calculation of the “clock” value for the first event in the new run will be slightly off.

16.91. prd command 871

LAMMPS Documentation, Release stable 29Sep2021

16.91.4 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package doc page
for more info.
The N and t_correlate settings must be integer multiples of t_event.
Runs restarted from restart file written during a PRD run will not produce identical results due to changes in the random
numbers used for dephasing.
This command cannot be used when any fixes are defined that keep track of elapsed time to perform time-dependent
operations. Examples include the “ave” fixes such as fix ave/chunk. Also fix dt/reset and fix deposit.

16.91.5 Related commands

compute event/displace, min_modify, min_style, run_style, minimize, velocity, temper, neb, tad, hyper

16.91.6 Default

The option defaults are min = 0.1 0.1 40 50, no temp setting, vel = geom gaussian, and time = steps.

(Voter1998) Voter, Phys Rev B, 57, 13985 (1998).

(Voter2002) Voter, Montalenti, Germann, Annual Review of Materials Research 32, 321 (2002).

16.92 print command

16.92.1 Syntax

print string keyword value

• string = text string to print, which may contain variables

• zero or more keyword/value pairs may be appended
• keyword = file or append or screen or universe
file value = filename
append value = filename
screen value = yes or no
universe value = yes or no

16.92.2 Examples

print "Done with equilibration" file info.dat

print Vol=$v append info.dat screen no
print "The system volume is now $v"
print 'The system volume is now $v'
print "NEB calculation 1 complete" screen no universe yes
print """
(continues on next page)

872 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

System volume = $v
System temperature = $t
"""

16.92.3 Description

Print a text string to the screen and logfile. The text string must be a single argument, so if it is one line but more
than one word, it should be enclosed in single or double quotes. To generate multiple lines of output, the string can be
enclosed in triple quotes, as in the last example above. If the text string contains variables, they will be evaluated and
their current values printed.
If the file or append keyword is used, a filename is specified to which the output will be written. If file is used, then
the filename is overwritten if it already exists. If append is used, then the filename is appended to if it already exists,
or created if it does not exist.
If the screen keyword is used, output to the screen and logfile can be turned on or off as desired.
If the universe keyword is used, output to the global screen and logfile can be turned on or off as desired. In multi-
partition calculations, the screen option and the corresponding output only apply to the screen and logfile of the indi-
vidual partition.
If you want the print command to be executed multiple times (with changing variable values), there are 3 options. First,
consider using the fix print command, which will print a string periodically during a simulation. Second, the print
command can be used as an argument to the every option of the run command. Third, the print command could appear
in a section of the input script that is looped over (see the jump and next commands).
See the variable command for a description of equal style variables which are typically the most useful ones to use
with the print command. Equal-style variables can calculate formulas involving mathematical operations, atom prop-
erties, group properties, thermodynamic properties, global values calculated by a compute or fix, or references to other
variables.

16.92.4 Restrictions

none

16.92.5 Related commands

fix print, variable

16.92.6 Default

The option defaults are no file output, screen = yes, and universe = no.

16.92. print command 873

LAMMPS Documentation, Release stable 29Sep2021

16.93 processors command

16.93.1 Syntax

processors Px Py Pz keyword args ...

• Px,Py,Pz = # of processors in each dimension of 3d grid overlaying the simulation domain

• zero or more keyword/arg pairs may be appended
• keyword = grid or map or part or file
grid arg = gstyle params ...
gstyle = onelevel or twolevel or numa or custom
onelevel params = none
twolevel params = Nc Cx Cy Cz
Nc = number of cores per node
Cx,Cy,Cz = # of cores in each dimension of 3d sub-grid assigned to each node
numa params = none
custom params = infile
infile = file containing grid layout
map arg = cart or cart/reorder or xyz or xzy or yxz or yzx or zxy or zyx
cart = use MPI_Cart() methods to map processors to 3d grid with reorder = 0
cart/reorder = use MPI_Cart() methods to map processors to 3d grid with reorder␣
,→= 1

xyz,xzy,yxz,yzx,zxy,zyx = map processors to 3d grid in IJK ordering

numa arg = none
part args = Psend Precv cstyle
Psend = partition # (1 to Np) which will send its processor layout
Precv = partition # (1 to Np) which will recv the processor layout
cstyle = multiple
multiple = Psend grid will be multiple of Precv grid in each dimension
file arg = outfile
outfile = name of file to write 3d grid of processors to

16.93.2 Examples

processors * * 5
processors 2 4 4
processors * * 8 map xyz
processors * * * grid numa
processors * * * grid twolevel 4 * * 1
processors 4 8 16 grid custom myfile
processors * * * part 1 2 multiple

874 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.93.3 Description

Specify how processors are mapped as a regular 3d grid to the global simulation box. The mapping involves 2 steps.
First if there are P processors it means choosing a factorization P = Px by Py by Pz so that there are Px processors in
the x dimension, and similarly for the y and z dimensions. Second, the P processors are mapped to the regular 3d grid.
The arguments to this command control each of these 2 steps.
The Px, Py, Pz parameters affect the factorization. Any of the 3 parameters can be specified with an asterisk “*”, which
means LAMMPS will choose the number of processors in that dimension of the grid. It will do this based on the size
and shape of the global simulation box so as to minimize the surface-to-volume ratio of each processor’s sub-domain.
Choosing explicit values for Px or Py or Pz can be used to override the default manner in which LAMMPS will create
the regular 3d grid of processors, if it is known to be sub-optimal for a particular problem. E.g. a problem where the
extent of atoms will change dramatically in a particular dimension over the course of the simulation.
The product of Px, Py, Pz must equal P, the total # of processors LAMMPS is running on. For a 2d simulation, Pz must
equal 1.
Note that if you run on a prime number of processors P, then a grid such as 1 x P x 1 will be required, which may incur
extra communication costs due to the high surface area of each processor’s sub-domain.
Also note that if multiple partitions are being used then P is the number of processors in this partition; see the -
partition command-line switch page for details. Also note that you can prefix the processors command with the partition
command to easily specify different Px,Py,Pz values for different partitions.
You can use the partition command to specify different processor grids for different partitions, e.g.

partition yes 1 processors 4 4 4

partition yes 2 processors 2 3 2

Note: This command only affects the initial regular 3d grid created when the simulation box is first specified via a
create_box or read_data or read_restart command. Or if the simulation box is re-created via the replicate command.
The same regular grid is initially created, regardless of which comm_style command is in effect.

If load-balancing is never invoked via the balance or fix balance commands, then the initial regular grid will persist for
all simulations. If balancing is performed, some of the methods invoked by those commands retain the logical topology
of the initial 3d grid, and the mapping of processors to the grid specified by the processors command. However the grid
spacings in different dimensions may change, so that processors own sub-domains of different sizes. If the comm_style
tiled command is used, methods invoked by the balancing commands may discard the 3d grid of processors and tile
the simulation domain with sub-domains of different sizes and shapes which no longer have a logical 3d connectivity.
If that occurs, all the information specified by the processors command is ignored.

The grid keyword affects the factorization of P into Px,Py,Pz and it can also affect how the P processor IDs are mapped
to the 3d grid of processors.
The onelevel style creates a 3d grid that is compatible with the Px,Py,Pz settings, and which minimizes the surface-to-
volume ratio of each processor’s sub-domain, as described above. The mapping of processors to the grid is determined
by the map keyword setting.
The twolevel style can be used on machines with multicore nodes to minimize off-node communication. It insures that
contiguous sub-sections of the 3d grid are assigned to all the cores of a node. For example if Nc is 4, then 2x2x1 or
2x1x2 or 1x2x2 sub-sections of the 3d grid will correspond to the cores of each node. This affects both the factorization
and mapping steps.
The Cx, Cy, Cz settings are similar to the Px, Py, Pz settings, only their product should equal Nc. Any of the 3 parameters
can be specified with an asterisk “*”, which means LAMMPS will choose the number of cores in that dimension of

16.93. processors command 875

LAMMPS Documentation, Release stable 29Sep2021

the node’s sub-grid. As with Px,Py,Pz, it will do this based on the size and shape of the global simulation box so as to
minimize the surface-to-volume ratio of each processor’s sub-domain.

Note: For the twolevel style to work correctly, it assumes the MPI ranks of processors LAMMPS is running on are
ordered by core and then by node. E.g. if you are running on 2 quad-core nodes, for a total of 8 processors, then it
assumes processors 0,1,2,3 are on node 1, and processors 4,5,6,7 are on node 2. This is the default rank ordering for
most MPI implementations, but some MPIs provide options for this ordering, e.g. via environment variable settings.

The numa style operates similar to the twolevel keyword except that it auto-detects which cores are running on which
nodes. Currently, it does this in only 2 levels, but it may be extended in the future to account for socket topology and
other non-uniform memory access (NUMA) costs. It also uses a different algorithm than the twolevel keyword for
doing the two-level factorization of the simulation box into a 3d processor grid to minimize off-node communication,
and it does its own MPI-based mapping of nodes and cores to the regular 3d grid. Thus it may produce a different
layout of the processors than the twolevel options.
The numa style will give an error if the number of MPI processes is not divisible by the number of cores used per node,
or any of the Px or Py of Pz values is greater than 1.

Note: Unlike the twolevel style, the numa style does not require any particular ordering of MPI ranks i norder to work
correctly. This is because it auto-detects which processes are running on which nodes.

The custom style uses the file infile to define both the 3d factorization and the mapping of processors to the grid.
The file should have the following format. Any number of initial blank or comment lines (starting with a “#” character)
can be present. The first non-blank, non-comment line should have 3 values:

Px Py Py

These must be compatible with the total number of processors and the Px, Py, Pz settings of the processors command.
This line should be immediately followed by P = Px*Py*Pz lines of the form:

ID I J K

where ID is a processor ID (from 0 to P-1) and I,J,K are the processors location in the 3d grid. I must be a number
from 1 to Px (inclusive) and similarly for J and K. The P lines can be listed in any order, but no processor ID should
appear more than once.

The map keyword affects how the P processor IDs (from 0 to P-1) are mapped to the 3d grid of processors. It is only
used by the onelevel and twolevel grid settings.
The cart style uses the family of MPI Cartesian functions to perform the mapping, namely MPI_Cart_create(),
MPI_Cart_get(), MPI_Cart_shift(), and MPI_Cart_rank(). It invokes the MPI_Cart_create() function with its reorder
flag = 0, so that MPI is not free to reorder the processors.
The cart/reorder style does the same thing as the cart style except it sets the reorder flag to 1, so that MPI can reorder
processors if it desires.
The xyz, xzy, yxz, yzx, zxy, and zyx styles are all similar. If the style is IJK, then it maps the P processors to the grid
so that the processor ID in the I direction varies fastest, the processor ID in the J direction varies next fastest, and the
processor ID in the K direction varies slowest. For example, if you select style xyz and you have a 2x2x2 grid of 8
processors, the assignments of the 8 octants of the simulation domain will be:

876 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

proc 0 = lo x, lo y, lo z octant
proc 1 = hi x, lo y, lo z octant
proc 2 = lo x, hi y, lo z octant
proc 3 = hi x, hi y, lo z octant
proc 4 = lo x, lo y, hi z octant
proc 5 = hi x, lo y, hi z octant
proc 6 = lo x, hi y, hi z octant
proc 7 = hi x, hi y, hi z octant

Note that, in principle, an MPI implementation on a particular machine should be aware of both the machine’s network
topology and the specific subset of processors and nodes that were assigned to your simulation. Thus its MPI_Cart calls
can optimize the assignment of MPI processes to the 3d grid to minimize communication costs. In practice, however,
few if any MPI implementations actually do this. So it is likely that the cart and cart/reorder styles simply give the
same result as one of the IJK styles.
Also note, that for the twolevel grid style, the map setting is used to first map the nodes to the 3d grid, then again to the
cores within each node. For the latter step, the cart and cart/reorder styles are not supported, so an xyz style is used in
their place.

The part keyword affects the factorization of P into Px,Py,Pz.

It can be useful when running in multi-partition mode, e.g. with the run_style verlet/split command. It specifies a
dependency between a sending partition Psend and a receiving partition Precv which is enforced when each is setting
up their own mapping of their processors to the simulation box. Each of Psend and Precv must be integers from 1 to
Np, where Np is the number of partitions you have defined via the -partition command-line switch.
A “dependency” means that the sending partition will create its regular 3d grid as Px by Py by Pz and after it has done
this, it will send the Px,Py,Pz values to the receiving partition. The receiving partition will wait to receive these values
before creating its own regular 3d grid and will use the sender’s Px,Py,Pz values as a constraint. The nature of the
constraint is determined by the cstyle argument.
For a cstyle of multiple, each dimension of the sender’s processor grid is required to be an integer multiple of the
corresponding dimension in the receiver’s processor grid. This is a requirement of the run_style verlet/split command.
For example, assume the sending partition creates a 4x6x10 grid = 240 processor grid. If the receiving partition is
running on 80 processors, it could create a 4x2x10 grid, but it will not create a 2x4x10 grid, since in the y-dimension,
6 is not an integer multiple of 4.

Note: If you use the partition command to invoke different “processors” commands on different partitions, and you
also use the part keyword, then you must insure that both the sending and receiving partitions invoke the “proces-
sors” command that connects the 2 partitions via the part keyword. LAMMPS cannot easily check for this, but your
simulation will likely hang in its setup phase if this error has been made.

The file keyword writes the mapping of the factorization of P processors and their mapping to the 3d grid to the specified
file outfile. This is useful to check that you assigned physical processors in the manner you desired, which can be tricky
to figure out, especially when running on multiple partitions or on, a multicore machine or when the processor ranks
were reordered by use of the -reorder command-line switch or due to use of MPI-specific launch options such as a
config file.
If you have multiple partitions you should insure that each one writes to a different file, e.g. using a world-style variable
for the filename. The file has a self-explanatory header, followed by one-line per processor in this format:
world-ID universe-ID original-ID: I J K: name

16.93. processors command 877

LAMMPS Documentation, Release stable 29Sep2021

The IDs are the processor’s rank in this simulation (the world), the universe (of multiple simulations), and the original
MPI communicator used to instantiate LAMMPS, respectively. The world and universe IDs will only be different if
you are running on more than one partition; see the -partition command-line switch. The universe and original IDs will
only be different if you used the -reorder command-line switch to reorder the processors differently than their rank in
the original communicator LAMMPS was instantiated with.
I,J,K are the indices of the processor in the regular 3d grid, each from 1 to Nd, where Nd is the number of processors
in that dimension of the grid.
The name is what is returned by a call to MPI_Get_processor_name() and should represent an identifier relevant to
the physical processors in your machine. Note that depending on the MPI implementation, multiple cores can have the
same name.

16.93.4 Restrictions

This command cannot be used after the simulation box is defined by a read_data or create_box command. It can be
used before a restart file is read to change the 3d processor grid from what is specified in the restart file.
The grid numa keyword only currently works with the map cart option.
The part keyword (for the receiving partition) only works with the grid onelevel or grid twolevel options.

16.93.5 Related commands

partition, -reorder command-line switch

16.93.6 Default

The option defaults are Px Py Pz = * * *, grid = onelevel, and map = cart.

16.94 python command

16.94.1 Syntax

python func keyword args ...

• func = name of Python function

• one or more keyword/args pairs must be appended
keyword = invoke or input or return or format or length or file or here or exists␣
,→or source

invoke arg = none = invoke the previously defined Python function

input args = N i1 i2 ... iN
N = # of inputs to function
i1,...,iN = value, SELF, or LAMMPS variable name
value = integer number, floating point number, or string
SELF = reference to LAMMPS itself which can be accessed by Python function
variable = v_name, where name = name of LAMMPS variable, e.g. v_abc
return arg = varReturn

878 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

varReturn = v_name = LAMMPS variable name which return value of function will␣
,→be assigned to
format arg = fstring with M characters
M = N if no return value, where N = # of inputs
M = N+1 if there is a return value
fstring = each character (i,f,s,p) corresponds in order to an input or return␣
,→value

'i' = integer, 'f' = floating point, 's' = string, 'p' = SELF

length arg = Nlen
Nlen = max length of string returned from Python function
file arg = filename
filename = file of Python code, which defines func
here arg = inline
inline = one or more lines of Python code which defines func
must be a single argument, typically enclosed between triple quotes
exists arg = none = Python code has been loaded by previous python command
source arg = filename or inline
filename = file of Python code which will be executed immediately
inline = one or more lines of Python code which will be executed immediately
must be a single argument, typically enclosed between triple quotes

16.94.2 Examples

python pForce input 2 v_x 20.0 return v_f format fff file force.py
python pForce invoke

python factorial input 1 myN return v_fac format ii here """

def factorial(n):
if n == 1: return n
return n * factorial(n-1)
"""

python loop input 1 SELF return v_value format pf here """

def loop(lmpptr,N,cut0):
from lammps import lammps
lmp = lammps(ptr=lmpptr)

# loop N times, increasing cutoff each time

for i in range(N):
cut = cut0 + i*0.1
lmp.set_variable("cut",cut) # set a variable in LAMMPS
lmp.command("pair_style lj/cut ${cut}") # LAMMPS commands
lmp.command("pair_coeff * * 1.0 1.0")
lmp.command("run 100")
"""

16.94. python command 879

LAMMPS Documentation, Release stable 29Sep2021

16.94.3 Description

Define a Python function or execute a previously defined function or execute some arbitrary python code. Arguments,
including LAMMPS variables, can be passed to the function from the LAMMPS input script and a value returned by the
Python function to a LAMMPS variable. The Python code for the function can be included directly in the input script
or in a separate Python file. The function can be standard Python code or it can make “callbacks” to LAMMPS through
its library interface to query or set internal values within LAMMPS. This is a powerful mechanism for performing
complex operations in a LAMMPS input script that are not possible with the simple input script and variable syntax
which LAMMPS defines. Thus your input script can operate more like a true programming language.
Use of this command requires building LAMMPS with the PYTHON package which links to the Python library so that
the Python interpreter is embedded in LAMMPS. More details about this process are given below.
There are two ways to invoke a Python function once it has been defined. One is using the invoke keyword. The other is
to assign the function to a python-style variable defined in your input script. Whenever the variable is evaluated, it will
execute the Python function to assign a value to the variable. Note that variables can be evaluated in many different ways
within LAMMPS. They can be substituted for directly in an input script. Or they can be passed to various commands
as arguments, so that the variable is evaluated during a simulation run.
A broader overview of how Python can be used with LAMMPS is given on the Python doc page. There is an exam-
ples/python directory which illustrates use of the python command.

The func setting specifies the name of the Python function. The code for the function is defined using the file or here
keywords as explained below. In case of the source keyword, the name of the function is ignored.
If the invoke keyword is used, no other keywords can be used, and a previous python command must have defined the
Python function referenced by this command. This invokes the Python function with the previously defined arguments
and return value processed as explained below. You can invoke the function as many times as you wish in your input
script.
If the source keyword is used, no other keywords can be used. The argument can be a filename or a string with python
commands, either on a single line enclosed in quotes, or as multiple lines enclosed in triple quotes. These python
commands will be passed to the python interpreter and executed immediately without registering a python function for
future execution.
The input keyword defines how many arguments N the Python function expects. If it takes no arguments, then the input
keyword should not be used. Each argument can be specified directly as a value, e.g. 6 or 3.14159 or abc (a string
of characters). The type of each argument is specified by the format keyword as explained below, so that Python will
know how to interpret the value. If the word SELF is used for an argument it has a special meaning. A pointer is passed
to the Python function which it converts into a reference to LAMMPS itself. This enables the function to call back
to LAMMPS through its library interface as explained below. This allows the Python function to query or set values
internal to LAMMPS which can affect the subsequent execution of the input script. A LAMMPS variable can also be
used as an argument, specified as v_name, where “name” is the name of the variable. Any style of LAMMPS variable
can be used, as defined by the variable command. Each time the Python function is invoked, the LAMMPS variable is
evaluated and its value is passed to the Python function.
The return keyword is only needed if the Python function returns a value. The specified varReturn must be of the
form v_name, where “name” is the name of a python-style LAMMPS variable, defined by the variable command. The
Python function can return a numeric or string value, as specified by the format keyword.
As explained on the variable doc page, the definition of a python-style variable associates a Python function name
with the variable. This must match the func setting for this command. For example these two commands would be
self-consistent:

variable foo python myMultiply

python myMultiply return v_foo format f file funcs.py

880 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The two commands can appear in either order in the input script so long as both are specified before the Python function
is invoked for the first time.
The format keyword must be used if the input or return keyword is used. It defines an fstring with M characters, where
M = sum of number of inputs and outputs. The order of characters corresponds to the N inputs, followed by the return
value (if it exists). Each character must be one of the following: “i” for integer, “f” for floating point, “s” for string, or
“p” for SELF. Each character defines the type of the corresponding input or output value of the Python function and
affects the type conversion that is performed internally as data is passed back and forth between LAMMPS and Python.
Note that it is permissible to use a python-style variable in a LAMMPS command that allows for an equal-style variable
as an argument, but only if the output of the Python function is flagged as a numeric value (“i” or “f”) via the format
keyword.
If the return keyword is used and the format keyword specifies the output as a string, then the default maximum length
of that string is 63 characters (64-1 for the string terminator). If you want to return a longer string, the length keyword
can be specified with its Nlen value set to a larger number (the code allocates space for Nlen+1 to include the string
terminator). If the Python function generates a string longer than the default 63 or the specified Nlen, it will be truncated.

Either the file, here, or exists keyword must be used, but only one of them. These keywords specify what Python code
to load into the Python interpreter. The file keyword gives the name of a file, which should end with a “.py” suffix,
which contains Python code. The code will be immediately loaded into and run in the “main” module of the Python
interpreter. Note that Python code which contains a function definition does not “execute” the function when it is run;
it simply defines the function so that it can be invoked later.
The here keyword does the same thing, except that the Python code follows as a single argument to the here keyword.
This can be done using triple quotes as delimiters, as in the examples above. This allows Python code to be listed
verbatim in your input script, with proper indentation, blank lines, and comments, as desired. See the Commands parse
doc page, for an explanation of how triple quotes can be used as part of input script syntax.
The exists keyword takes no argument. It means that Python code containing the required Python function defined by
the func setting, is assumed to have been previously loaded by another python command.
Note that the Python code that is loaded and run must contain a function with the specified func name. To operate
properly when later invoked, the function code must match the input and return and format keywords specified by the
python command. Otherwise Python will generate an error.

This section describes how Python code can be written to work with LAMMPS.
Whether you load Python code from a file or directly from your input script, via the file and here keywords, the code
can be identical. It must be indented properly as Python requires. It can contain comments or blank lines. If the code is
in your input script, it cannot however contain triple-quoted Python strings, since that will conflict with the triple-quote
parsing that the LAMMPS input script performs.
All the Python code you specify via one or more python commands is loaded into the Python “main” module, i.e.
__main__. The code can define global variables or statements that are outside of function definitions. It can contain
multiple functions, only one of which matches the func setting in the python command. This means you can use the file
keyword once to load several functions, and the exists keyword thereafter in subsequent python commands to access
the other functions previously loaded.
A Python function you define (or more generally, the code you load) can import other Python modules or classes, it
can make calls to other system functions or functions you define, and it can access or modify global variables (in the
“main” module) which will persist between successive function calls. The latter can be useful, for example, to prevent
a function from being invoke multiple times per timestep by different commands in a LAMMPS input script that access
the returned python-style variable associated with the function. For example, consider this function loaded with two
global variables defined outside the function:

16.94. python command 881

LAMMPS Documentation, Release stable 29Sep2021

nsteplast = -1
nvaluelast = 0

def expensive(nstep):
global nsteplast,nvaluelast
if nstep == nsteplast: return nvaluelast
nsteplast = nstep
# perform complicated calculation
nvalue = ...
nvaluelast = nvalue
return nvalue

Nsteplast stores the previous timestep the function was invoked (passed as an argument to the function). Nvaluelast
stores the return value computed on the last function invocation. If the function is invoked again on the same timestep,
the previous value is simply returned, without re-computing it. The “global” statement inside the Python function
allows it to overwrite the global variables.
Note that if you load Python code multiple times (via multiple python commands), you can overwrite previously loaded
variables and functions if you are not careful. E.g. if the code above were loaded twice, the global variables would be
re-initialized, which might not be what you want. Likewise, if a function with the same name exists in two chunks of
Python code you load, the function loaded second will override the function loaded first.
It’s important to realize that if you are running LAMMPS in parallel, each MPI task will load the Python interpreter
and execute a local copy of the Python function(s) you define. There is no connection between the Python interpreters
running on different processors. This implies three important things.
First, if you put a print statement in your Python function, you will see P copies of the output, when running on P
processors. If the prints occur at (nearly) the same time, the P copies of the output may be mixed together. Welcome
to the world of parallel programming and debugging.
Second, if your Python code loads modules that are not pre-loaded by the Python library, then it will load the module
from disk. This may be a bottleneck if 1000s of processors try to load a module at the same time. On some large
supercomputers, loading of modules from disk by Python may be disabled. In this case you would need to pre-build a
Python library that has the required modules pre-loaded and link LAMMPS with that library.
Third, if your Python code calls back to LAMMPS (discussed in the next section) and causes LAMMPS to perform an
MPI operation requires global communication (e.g. via MPI_Allreduce), such as computing the global temperature of
the system, then you must insure all your Python functions (running independently on different processors) call back
to LAMMPS. Otherwise the code may hang.

Your Python function can “call back” to LAMMPS through its library interface, if you use the SELF input to pass
Python a pointer to LAMMPS. The mechanism for doing this in your Python function is as follows:

def foo(lmpptr,...):
from lammps import lammps
lmp = lammps(ptr=lmpptr)
lmp.command('print "Hello from inside Python"')
...

The function definition must include a variable (lmpptr in this case) which corresponds to SELF in the python command.
The first line of the function imports the “lammps” Python module. The second line creates a Python object lmp which
wraps the instance of LAMMPS that called the function. The “ptr=lmpptr” argument is what makes that happen. The
third line invokes the command() function in the LAMMPS library interface. It takes a single string argument which
is a LAMMPS input script command for LAMMPS to execute, the same as if it appeared in your input script. In this
case, LAMMPS should output

882 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Hello from inside Python

to the screen and log file. Note that since the LAMMPS print command itself takes a string in quotes as its argument,
the Python string must be delimited with a different style of quotes.
The Use Python with LAMMPS page describes the syntax for how Python wraps the various functions included in the
LAMMPS library interface.
A more interesting example is in the examples/python/in.python script which loads and runs the following function
from examples/python/funcs.py:

def loop(N,cut0,thresh,lmpptr):
print("LOOP ARGS", N, cut0, thresh, lmpptr)
from lammps import lammps
lmp = lammps(ptr=lmpptr)
natoms = lmp.get_natoms()

for i in range(N):
cut = cut0 + i*0.1

lmp.set_variable("cut",cut) # set a variable in LAMMPS

lmp.command("pair_style lj/cut ${cut}") # LAMMPS command
#lmp.command("pair_style lj/cut %d" % cut) # LAMMPS command option

lmp.command("pair_coeff * * 1.0 1.0") # ditto

lmp.command("run 10") # ditto
pe = lmp.extract_compute("thermo_pe",0,0) # extract total PE from LAMMPS
print("PE", pe/natoms, thresh)
if pe/natoms < thresh: return

with these input script commands:

python loop input 4 10 1.0 -4.0 SELF format iffp file funcs.py
python loop invoke

This has the effect of looping over a series of 10 short runs (10 timesteps each) where the pair style cutoff is increased
from a value of 1.0 in distance units, in increments of 0.1. The looping stops when the per-atom potential energy falls
below a threshold of -4.0 in energy units. More generally, Python can be used to implement a loop with complex logic,
much more so than can be created using the LAMMPS jump and if commands.
Several LAMMPS library functions are called from the loop function. Get_natoms() returns the number of atoms in
the simulation, so that it can be used to normalize the potential energy that is returned by extract_compute() for the
“thermo_pe” compute that is defined by default for LAMMPS thermodynamic output. Set_variable() sets the value of
a string variable defined in LAMMPS. This library function is a useful way for a Python function to return multiple
values to LAMMPS, more than the single value that can be passed back via a return statement. This cutoff value in the
“cut” variable is then substituted (by LAMMPS) in the pair_style command that is executed next. Alternatively, the
“LAMMPS command option” line could be used in place of the 2 preceding lines, to have Python insert the value into
the LAMMPS command string.

Note: When using the callback mechanism just described, recognize that there are some operations you should not
attempt because LAMMPS cannot execute them correctly. If the Python function is invoked between runs in the
LAMMPS input script, then it should be OK to invoke any LAMMPS input script command via the library interface
command() or file() functions, so long as the command would work if it were executed in the LAMMPS input script
directly at the same point.

16.94. python command 883

LAMMPS Documentation, Release stable 29Sep2021

However, a Python function can also be invoked during a run, whenever an associated LAMMPS variable it is assigned
to is evaluated. If the variable is an input argument to another LAMMPS command (e.g. fix setforce), then the Python
function will be invoked inside the class for that command, in one of its methods that is invoked in the middle of a
timestep. You cannot execute arbitrary input script commands from the Python function (again, via the command()
or file() functions) at that point in the run and expect it to work. Other library functions such as those that invoke
computes or other variables may have hidden side effects as well. In these cases, LAMMPS has no simple way to
check that something illogical is being attempted.
The same applies to Python functions called during a simulation run at each time step using fix python/invoke.

If you run Python code directly on your workstation, either interactively or by using Python to launch a Python script
stored in a file, and your code has an error, you will typically see informative error messages. That is not the case
when you run Python code from LAMMPS using an embedded Python interpreter. The code will typically fail silently.
LAMMPS will catch some errors but cannot tell you where in the Python code the problem occurred. For example, if
the Python code cannot be loaded and run because it has syntax or other logic errors, you may get an error from Python
pointing to the offending line, or you may get one of these generic errors from LAMMPS:

Could not process Python file

Could not process Python string

When the Python function is invoked, if it does not return properly, you will typically get this generic error from
LAMMPS:

Python function evaluation failed

Here are three suggestions for debugging your Python code while running it under LAMMPS.
First, don’t run it under LAMMPS, at least to start with! Debug it using plain Python. Load and invoke your function,
pass it arguments, check return values, etc.
Second, add Python print statements to the function to check how far it gets and intermediate values it calculates. See
the discussion above about printing from Python when running in parallel.
Third, use Python exception handling. For example, say this statement in your Python function is failing, because you
have not initialized the variable foo:

foo += 1

If you put one (or more) statements inside a “try” statement, like this:

import exceptions
print("Inside simple function")
try:
foo += 1 # one or more statements here
except Exception as e:
print("FOO error:", e)

then you will get this message printed to the screen:

FOO error: local variable 'foo' referenced before assignment

If there is no error in the try statements, then nothing is printed. Either way the function continues on (unless you put
a return or sys.exit() in the except clause).

884 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.94.4 Restrictions

This command is part of the PYTHON package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.
Building LAMMPS with the PYTHON package will link LAMMPS with the Python library on your system. Settings
to enable this are in the lib/python/Makefile.lammps file. See the lib/python/README file for information on those
settings.
If you use Python code which calls back to LAMMPS, via the SELF input argument explained above, there is an extra
step required when building LAMMPS. LAMMPS must also be built as a shared library and your Python function
must be able to load the “lammps” Python module that wraps the LAMMPS library interface. These are the same steps
required to use Python by itself to wrap LAMMPS. Details on these steps are explained on the Python doc page. Note
that it is important that the stand-alone LAMMPS executable and the LAMMPS shared library be consistent (built from
the same source code files) in order for this to work. If the two have been built at different times using different source
files, problems may occur.

16.94.5 Related commands

shell, variable, fix python/invoke

16.94.6 Default

none

16.95 quit command

16.95.1 Syntax

quit status

status = numerical exit status (optional)

16.95.2 Examples

quit
if "$n > 10000" then "quit 1"

16.95.3 Description

This command causes LAMMPS to exit, after shutting down all output cleanly.
It can be used as a debug statement in an input script, to terminate the script at some intermediate point.
It can also be used as an invoked command inside the “then” or “else” portion of an if command.
The optional status argument is an integer which signals the return status to a program calling LAMMPS. A return
status of 0 usually indicates success. A status != 0 is failure, where the specified value can be used to distinguish the
kind of error, e.g. where in the input script the quit was invoked. If not specified, a status of 0 is returned.

16.95. quit command 885

LAMMPS Documentation, Release stable 29Sep2021

16.95.4 Restrictions

none

16.95.5 Related commands

if

16.95.6 Default

none

16.96 read_data command

16.96.1 Syntax

read_data file keyword args ...

• file = name of data file to read in

• zero or more keyword/arg pairs may be appended
• keyword = add or offset or shift or extra/atom/types or extra/bond/types or extra/angle/types or
extra/dihedral/types or extra/improper/types or extra/bond/per/atom or extra/angle/per/atom or ex-
tra/dihedral/per/atom or extra/improper/per/atom or group or nocoeff or fix
add arg = append or IDoffset or IDoffset MOLoffset or merge
append = add new atoms with atom IDs appended to current IDs
IDoffset = add new atoms with atom IDs having IDoffset added
MOLoffset = add new atoms with molecule IDs having MOLoffset added (only when␣
,→molecule IDs are enabled)

merge = add new atoms with their atom IDs (and molecule IDs) unchanged
offset args = toff boff aoff doff ioff
toff = offset to add to atom types
boff = offset to add to bond types
aoff = offset to add to angle types
doff = offset to add to dihedral types
ioff = offset to add to improper types
shift args = Sx Sy Sz
Sx,Sy,Sz = distance to shift atoms when adding to system (distance units)
extra/atom/types arg = # of extra atom types
extra/bond/types arg = # of extra bond types
extra/angle/types arg = # of extra angle types
extra/dihedral/types arg = # of extra dihedral types
extra/improper/types arg = # of extra improper types
extra/bond/per/atom arg = leave space for this many new bonds per atom
extra/angle/per/atom arg = leave space for this many new angles per atom
extra/dihedral/per/atom arg = leave space for this many new dihedrals per atom
extra/improper/per/atom arg = leave space for this many new impropers per atom
extra/special/per/atom arg = leave space for extra 1-2,1-3,1-4 interactions per atom
group args = groupID

886 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

groupID = add atoms in data file to this group

nocoeff = ignore force field parameters
fix args = fix-ID header-string section-string
fix-ID = ID of fix to process header lines and sections of data file
header-string = header lines containing this string will be passed to fix
section-string = section names with this string will be passed to fix

16.96.2 Examples

read_data data.lj
read_data ../run7/data.polymer.gz
read_data data.protein fix mycmap crossterm CMAP
read_data data.water add append offset 3 1 1 1 1 shift 0.0 0.0 50.0
read_data data.water add merge 1 group solvent

16.96.3 Description

Read in a data file containing information LAMMPS needs to run a simulation. The file can be ASCII text or a gzipped
text file (detected by a .gz suffix). This is one of 3 ways to specify initial atom coordinates; see the read_restart and
create_atoms commands for alternative methods. Also see the explanation of the -restart command-line switch which
can convert a restart file to a data file.
This command can be used multiple times to add new atoms and their properties to an existing system by using the
add, offset, and shift keywords. See more details below, which includes the use case for the extra keywords.
The group keyword adds all the atoms in the data file to the specified group-ID. The group will be created if it does not
already exist. This is useful if you are reading multiple data files and wish to put sets of atoms into different groups
so they can be operated on later. E.g. a group of added atoms can be moved to new positions via the displace_atoms
command. Note that atoms read from the data file are also always added to the “all” group. The group command
discusses atom groups, as used in LAMMPS.
The nocoeff keyword tells read_data to ignore force field parameters. The various Coeff sections are still read and have
to have the correct number of lines, but they are not applied. This also allows to read a data file without having any
pair, bond, angle, dihedral or improper styles defined, or to read a data file for a different force field.
The use of the fix keyword is discussed below.

16.96.4 Reading multiple data files

The read_data command can be used multiple times with the same or different data files to build up a complex system
from components contained in individual data files. For example one data file could contain fluid in a confined domain;
a second could contain wall atoms, and the second file could be read a third time to create a wall on the other side of
the fluid. The third set of atoms could be rotated to an opposing direction using the displace_atoms command, after
the third read_data command is used.
The add, offset, shift, extra, and group keywords are useful in this context.
If a simulation box does not yet exist, the add keyword cannot be used; the read_data command is being used for the
first time. If a simulation box does exist, due to using the create_box command, or a previous read_data command,
then the add keyword must be used.

16.96. read_data command 887

LAMMPS Documentation, Release stable 29Sep2021

Note: The simulation box size (xlo to xhi, ylo to yhi, zlo to zhi) in the new data file will be merged with the existing
simulation box to create a large enough box in each dimension to contain both the existing and new atoms. Each box
dimension never shrinks due to this merge operation, it only stays the same or grows. Care must be used if you are
growing the existing simulation box in a periodic dimension. If there are existing atoms with bonds that straddle that
periodic boundary, then the atoms may become far apart if the box size grows. This will separate the atoms in the bond,
which can lead to “lost” bond atoms or bad dynamics.

The three choices for the add argument affect how the atom IDs and molecule IDs of atoms in the data file are treated. If
append is specified, atoms in the data file are added to the current system, with their atom IDs reset so that an atom-ID
= M in the data file becomes atom-ID = N+M, where N is the largest atom ID in the current system. This rule is applied
to all occurrences of atom IDs in the data file, e.g. in the Velocity or Bonds section. This is also done for molecule
IDs, if the atom style does support molecule IDs or they are enabled via fix property/atom. If IDoffset is specified, then
IDoffset is a numeric value is given, e.g. 1000, so that an atom-ID = M in the data file becomes atom-ID = 1000+M.
For systems with enabled molecule IDs, another numerical argument MOLoffset is required representing the equivalent
offset for molecule IDs. If merge is specified, the data file atoms are added to the current system without changing their
IDs. They are assumed to merge (without duplication) with the currently defined atoms. It is up to you to insure there
are no multiply defined atom IDs, as LAMMPS only performs an incomplete check that this is the case by insuring the
resulting max atom-ID >= the number of atoms. For molecule IDs, there is no check done at all.
The offset and shift keywords can only be used if the add keyword is also specified.
The offset keyword adds the specified offset values to the atom types, bond types, angle types, dihedral types, and
improper types as they are read from the data file. E.g. if toff = 2, and the file uses atom types 1,2,3, then the added
atoms will have atom types 3,4,5. These offsets apply to all occurrences of types in the data file, e.g. for the Atoms
or Masses or Pair Coeffs or Bond Coeffs sections. This makes it easy to use atoms and molecules and their attributes
from a data file in different simulations, where you want their types (atom, bond, angle, etc) to be different depending
on what other types already exist. All five offset values must be specified, but individual values will be ignored if the
data file does not use that attribute (e.g. no bonds).
The shift keyword can be used to specify an (Sx, Sy, Sz) displacement applied to the coordinates of each atom. Sz
must be 0.0 for a 2d simulation. This is a mechanism for adding structured collections of atoms at different locations
within the simulation box, to build up a complex geometry. It is up to you to insure atoms do not end up overlapping
unphysically which would lead to bad dynamics. Note that the displace_atoms command can be used to move a subset
of atoms after they have been read from a data file. Likewise, the delete_atoms command can be used to remove
overlapping atoms. Note that the shift values (Sx, Sy, Sz) are also added to the simulation box information (xlo, xhi,
ylo, yhi, zlo, zhi) in the data file to shift its boundaries. E.g. xlo_new = xlo + Sx, xhi_new = xhi + Sx.
The extra keywords can only be used the first time the read_data command is used. They are useful if you intend to add
new atom, bond, angle, etc types later with additional read_data commands. This is because the maximum number of
allowed atom, bond, angle, etc types is set by LAMMPS when the system is first initialized. If you do not use the extra
keywords, then the number of these types will be limited to what appears in the first data file you read. For example,
if the first data file is a solid substrate of Si, it will likely specify a single atom type. If you read a second data file
with a different material (water molecules) that sit on top of the substrate, you will want to use different atom types for
those atoms. You can only do this if you set the extra/atom/types keyword to a sufficiently large value when reading
the substrate data file. Note that use of the extra keywords also allows each data file to contain sections like Masses or
Pair Coeffs or Bond Coeffs which are sized appropriately for the number of types in that data file. If the offset keyword
is used appropriately when each data file is read, the values in those sections will be stored correctly in the larger data
structures allocated by the use of the extra keywords. E.g. the substrate file can list mass and pair coefficients for type 1
silicon atoms. The water file can list mass and pair coefficients for type 1 and type 2 hydrogen and oxygen atoms. Use
of the extra and offset keywords will store those mass and pair coefficient values appropriately in data structures that
allow for 3 atom types (Si, H, O). Of course, you would still need to specify coefficients for H/Si and O/Si interactions
in your input script to have a complete pairwise interaction model.
An alternative to using the extra keywords with the read_data command, is to use the create_box command to initialize
the simulation box and all the various type limits you need via its extra keywords. Then use the read_data command

888 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

one or more times to populate the system with atoms, bonds, angles, etc, using the offset keyword if desired to alter
types used in the various data files you read.

16.96.5 Format of a data file

The structure of the data file is important, though many settings and sections are optional or can come in any order.
See the examples directory for sample data files for different problems.
The file will be read line by line, but there is a limit of 254 characters per line and characters beyond that limit will be
ignored.
A data file has a header and a body. The header appears first. The first line of the header is always skipped; it typically
contains a description of the file. Then lines are read one at a time. Lines can have a trailing comment starting with
‘#’ that is ignored. If the line is blank (only white-space after comment is deleted), it is skipped. If the line contains
a header keyword, the corresponding value(s) is read from the line. If it does not contain a header keyword, the line
begins the body of the file.
The body of the file contains zero or more sections. The first line of a section has only a keyword. This line can have a
trailing comment starting with ‘#’ that is either ignored or can be used to check for a style match, as described below.
The next line is skipped. The remaining lines of the section contain values. The number of lines depends on the section
keyword as described below. Zero or more blank lines can be used between sections. Sections can appear in any order,
with a few exceptions as noted below.
The keyword fix can be used one or more times. Each usage specifies a fix that will be used to process a specific portion
of the data file. Any header line containing header-string and any section that is an exact match to section-string will
be passed to the specified fix. See the fix property/atom command for an example of a fix that operates in this manner.
The doc page for the fix defines the syntax of the header line(s) and section that it reads from the data file. Note that
the header-string can be specified as NULL, in which case no header lines are passed to the fix. This means the fix can
infer the length of its Section from standard header settings, such as the number of atoms.
The formatting of individual lines in the data file (indentation, spacing between words and numbers) is not important
except that header and section keywords (e.g. atoms, xlo xhi, Masses, Bond Coeffs) must be capitalized as shown and
cannot have extra white-space between their words - e.g. two spaces or a tab between the 2 words in “xlo xhi” or the 2
words in “Bond Coeffs”, is not valid.

16.96.6 Format of the header of a data file

These are the recognized header keywords. Header lines can come in any order. The value(s) are read from the
beginning of the line. Thus the keyword atoms should be in a line like “1000 atoms”; the keyword ylo yhi should be in
a line like “-10.0 10.0 ylo yhi”; the keyword xy xz yz should be in a line like “0.0 5.0 6.0 xy xz yz”. All these settings
have a default value of 0, except the lo/hi box size defaults are -0.5 and 0.5. A line need only appear if the value is
different than the default.
• atoms = # of atoms in system
• bonds = # of bonds in system
• angles = # of angles in system
• dihedrals = # of dihedrals in system
• impropers = # of impropers in system
• atom types = # of atom types in system

16.96. read_data command 889

LAMMPS Documentation, Release stable 29Sep2021

• bond types = # of bond types in system

• angle types = # of angle types in system
• dihedral types = # of dihedral types in system
• improper types = # of improper types in system
• extra bond per atom = leave space for this many new bonds per atom (deprecated, use extra/bond/per/atom
keyword)
• extra angle per atom = leave space for this many new angles per atom (deprecated, use extra/angle/per/atom
keyword)
• extra dihedral per atom = leave space for this many new dihedrals per atom (deprecated, use ex-
tra/dihedral/per/atom keyword)
• extra improper per atom = leave space for this many new impropers per atom (deprecated, use ex-
tra/improper/per/atom keyword)
• extra special per atom = leave space for this many new special bonds per atom (deprecated, use ex-
tra/special/per/atom keyword)
• ellipsoids = # of ellipsoids in system
• lines = # of line segments in system
• triangles = # of triangles in system
• bodies = # of bodies in system
• xlo xhi = simulation box boundaries in x dimension
• ylo yhi = simulation box boundaries in y dimension
• zlo zhi = simulation box boundaries in z dimension
• xy xz yz = simulation box tilt factors for triclinic system
The initial simulation box size is determined by the lo/hi settings. In any dimension, the system may be periodic or
non-periodic; see the boundary command. When the simulation box is created it is also partitioned into a regular 3d
grid of rectangular bricks, one per processor, based on the number of processors being used and the settings of the
processors command. The partitioning can later be changed by the balance or fix balance commands.
If the xy xz yz line does not appear, LAMMPS will set up an axis-aligned (orthogonal) simulation box. If the line does
appear, LAMMPS creates a non-orthogonal simulation domain shaped as a parallelepiped with triclinic symmetry. The
parallelepiped has its “origin” at (xlo,ylo,zlo) and is defined by 3 edge vectors starting from the origin given by A =
(xhi-xlo,0,0); B = (xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). Xy,xz,yz can be 0.0 or positive or negative values and are called
“tilt factors” because they are the amount of displacement applied to faces of an originally orthogonal box to transform
it into the parallelepiped.
By default, the tilt factors (xy,xz,yz) can not skew the box more than half the distance of the corresponding parallel
box length. For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between
-5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation,
since if the maximum tilt factor is 5 (as in this example), then configurations with tilt = . . . , -15, -5, 5, 15, 25, . . . are
all geometrically equivalent. If you wish to define a box with tilt factors that exceed these limits, you can use the box
tilt command, with a setting of large; a setting of small is the default.
See the Howto triclinic page for a geometric description of triclinic boxes, as defined by LAMMPS, and how to trans-
form these parameters to and from other commonly used triclinic representations.
When a triclinic system is used, the simulation domain should normally be periodic in the dimension that the tilt is
applied to, which is given by the second dimension of the tilt factor (e.g. y for xy tilt). This is so that pairs of atoms
interacting across that boundary will have one of them shifted by the tilt factor. Periodicity is set by the boundary

890 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

command. For example, if the xy tilt factor is non-zero, then the y dimension should be periodic. Similarly, the z
dimension should be periodic if xz or yz is non-zero. LAMMPS does not require this periodicity, but you may lose
atoms if this is not the case.
Also note that if your simulation will tilt the box, e.g. via the fix deform command, the simulation box must be setup
to be triclinic, even if the tilt factors are initially 0.0. You can also change an orthogonal box to a triclinic box or vice
versa by using the change box command with its ortho and triclinic options.
For 2d simulations, the zlo zhi values should be set to bound the z coords for atoms that appear in the file; the default
of -0.5 0.5 is valid if all z coords are 0.0. For 2d triclinic simulations, the xz and yz tilt factors must be 0.0.
If the system is periodic (in a dimension), then atom coordinates can be outside the bounds (in that dimension); they
will be remapped (in a periodic sense) back inside the box. Note that if the add option is being used to add atoms to a
simulation box that already exists, this periodic remapping will be performed using simulation box bounds that are the
union of the existing box and the box boundaries in the new data file.
If the system is non-periodic (in a dimension), then an image flag for that direction has no meaning, since there cannot
be periodic images without periodicity and the data file is therefore - technically speaking - invalid. This situation
would happen when a data file was written with periodic boundaries and then read back for non-periodic boundaries.
Accepting a non-zero image flag can lead to unexpected results for any operations and computations in LAMMPS
that internally use unwrapped coordinates (for example computing the center of mass of a group of atoms). Thus all
non-zero image flags for non-periodic dimensions will be be reset to zero on reading the data file and LAMMPS will
print a warning message, if that happens. This is equivalent to wrapping atoms individually back into the principal unit
cell in that direction. This operation is equivalent to the behavior of the change_box command when used to change
periodicity.
If those atoms with non-zero image flags are involved in bonded interactions, this reset can lead to undesired changes,
when the image flag values differ between the atoms, i.e. the bonded interaction straddles domain boundaries. For
example a bond can become stretched across the unit cell if one of its atoms is wrapped to one side of the cell and the
second atom to the other. In those cases the data file needs to be pre-processed externally to become valid again. This
can be done by first unwrapping coordinates and then wrapping entire molecules instead of individual atoms back into
the principal simulation cell and finally expanding the cell dimensions in the non-periodic direction as needed, so that
the image flag would be zero.

Note: If the system is non-periodic (in a dimension), then all atoms in the data file must have coordinates (in that
dimension) that are “greater than or equal to” the lo value and “less than or equal to” the hi value. If the non-periodic
dimension is of style “fixed” (see the boundary command), then the atom coords must be strictly “less than” the hi
value, due to the way LAMMPS assign atoms to processors. Note that you should not make the lo/hi values radically
smaller/larger than the extent of the atoms. For example, if your atoms extend from 0 to 50, you should not specify the
box bounds as -10000 and 10000 unless you also use the processors command. This is because LAMMPS uses the
specified box size to layout the 3d grid of processors. A huge (mostly empty) box will be sub-optimal for performance
when using “fixed” boundary conditions (see the boundary command). When using “shrink-wrap” boundary conditions
(see the boundary command), a huge (mostly empty) box may cause a parallel simulation to lose atoms when LAMMPS
shrink-wraps the box around the atoms. The read_data command will generate an error in this case.

The “extra bond per atom” setting (angle, dihedral, improper) is only needed if new bonds (angles, dihedrals, impropers)
will be added to the system when a simulation runs, e.g. by using the fix bond/create command. Using this header flag
is deprecated; please use the extra/bond/per/atom keyword (and correspondingly for angles, dihedrals and impropers)
in the read_data command instead. Either will pre-allocate space in LAMMPS data structures for storing the new bonds
(angles, dihedrals, impropers).
The “extra special per atom” setting is typically only needed if new bonds/angles/etc will be added to the system, e.g.
by using the fix bond/create command. Or if entire new molecules will be added to the system, e.g. by using the fix
deposit or fix pour commands, which will have more special 1-2,1-3,1-4 neighbors than any other molecules defined
in the data file. Using this header flag is deprecated; please use the extra/special/per/atom keyword instead. Using this

16.96. read_data command 891

LAMMPS Documentation, Release stable 29Sep2021

setting will pre-allocate space in the LAMMPS data structures for storing these neighbors. See the special_bonds and
molecule doc pages for more discussion of 1-2,1-3,1-4 neighbors.

Note: All of the “extra” settings are only applied in the first data file read and when no simulation box has yet been
created; as soon as the simulation box is created (and read_data implies that), these settings are locked and cannot be
changed anymore. Please see the description of the add keyword above for reading multiple data files. If they appear
in later data files, they are ignored.

The “ellipsoids” and “lines” and “triangles” and “bodies” settings are only used with atom_style ellipsoid or line or
tri or body and specify how many of the atoms are finite-size ellipsoids or lines or triangles or bodies; the remainder
are point particles. See the discussion of ellipsoidflag and the Ellipsoids section below. See the discussion of lineflag
and the Lines section below. See the discussion of triangleflag and the Triangles section below. See the discussion of
bodyflag and the Bodies section below.

Note: For atom_style template, the molecular topology (bonds,angles,etc) is contained in the molecule templates
read-in by the molecule command. This means you cannot set the bonds, angles, etc header keywords in the data file,
nor can you define Bonds, Angles, etc sections as discussed below. You can set the bond types, angle types, etc header
keywords, though it is not necessary. If specified, they must match the maximum values defined in any of the template
molecules.

16.96.7 Format of the body of a data file

These are the section keywords for the body of the file.
• Atoms, Velocities, Masses, Ellipsoids, Lines, Triangles, Bodies = atom-property sections
• Bonds, Angles, Dihedrals, Impropers = molecular topology sections
• Pair Coeffs, PairIJ Coeffs, Bond Coeffs, Angle Coeffs, Dihedral Coeffs, Improper Coeffs = force field sections
• BondBond Coeffs, BondAngle Coeffs, MiddleBondTorsion Coeffs, EndBondTorsion Coeffs, AngleTorsion Coeffs,
AngleAngleTorsion Coeffs, BondBond13 Coeffs, AngleAngle Coeffs = class 2 force field sections
These keywords will check an appended comment for a match with the currently defined style:
• Atoms, Pair Coeffs, PairIJ Coeffs, Bond Coeffs, Angle Coeffs, Dihedral Coeffs, Improper Coeffs
For example, these lines:

Atoms # sphere
Pair Coeffs # lj/cut

will check if the currently-defined atom_style is sphere, and the current pair_style is lj/cut. If not, LAMMPS will issue
a warning to indicate that the data file section likely does not contain the correct number or type of parameters expected
for the currently-defined style.
Each section is listed below in alphabetic order. The format of each section is described including the number of lines
it must contain and rules (if any) for where it can appear in the data file.
Any individual line in the various sections can have a trailing comment starting with “#” for annotation purposes. E.g.
in the Atoms section:

10 1 17 -1.0 10.0 5.0 6.0 # salt ion

892 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Angle Coeffs section:

• one line per angle type
• line syntax: ID coeffs

ID = angle type (1-N)

coeffs = list of coeffs

• example:

6 70 108.5 0 0

The number and meaning of the coefficients are specific to the defined angle style. See the angle_style and angle_coeff
commands for details. Coefficients can also be set via the angle_coeff command in the input script.

AngleAngle Coeffs section:

• one line per improper type
• line syntax: ID coeffs
ID = improper type (1-N)
coeffs = list of coeffs (see improper_coeff )

AngleAngleTorsion Coeffs section:

• one line per dihedral type
• line syntax: ID coeffs
ID = dihedral type (1-N)
coeffs = list of coeffs (see dihedral_coeff )

Angles section:
• one line per angle
• line syntax: ID type atom1 atom2 atom3

ID = number of angle (1-Nangles)

type = angle type (1-Nangletype)
atom1,atom2,atom3 = IDs of 1st,2nd,3rd atom in angle

example:

2 2 17 29 430

The 3 atoms are ordered linearly within the angle. Thus the central atom (around which the angle is computed) is the
atom2 in the list. E.g. H,O,H for a water molecule. The Angles section must appear after the Atoms section. All values
in this section must be integers (1, not 1.0).

AngleTorsion Coeffs section:

16.96. read_data command 893

LAMMPS Documentation, Release stable 29Sep2021

• one line per dihedral type

• line syntax: ID coeffs
ID = dihedral type (1-N)
coeffs = list of coeffs (see dihedral_coeff )

Atoms section:
• one line per atom
• line syntax: depends on atom style
An Atoms section must appear in the data file if natoms > 0 in the header section. The atoms can be listed in any
order. These are the line formats for each atom style in LAMMPS. As discussed below, each line can optionally have
3 flags (nx,ny,nz) appended to it, which indicate which image of a periodic simulation box the atom is in. These may
be important to include for some kinds of analysis.

angle atom-ID molecule-ID atom-type x y z

atomic atom-ID atom-type x y z
body atom-ID atom-type bodyflag mass x y z
bond atom-ID molecule-ID atom-type x y z
charge atom-ID atom-type q x y z
dipole atom-ID atom-type q x y z mux muy muz
dpd atom-ID atom-type theta x y z
edpd atom-ID atom-type edpd_temp edpd_cv x y z
electron atom-ID atom-type q spin eradius x y z
ellipsoid atom-ID atom-type ellipsoidflag density x y z
full atom-ID molecule-ID atom-type q x y z
line atom-ID molecule-ID atom-type lineflag density x y z
mdpd atom-ID atom-type rho x y z
mesont atom-ID molecule-ID atom-type bond_nt mass mradius mlength buckling x y z
molecular atom-ID molecule-ID atom-type x y z
peri atom-ID atom-type volume density x y z
smd atom-ID atom-type molecule volume mass kradius cradius x0 y0 z0 x y z
sph atom-ID atom-type rho esph cv x y z
sphere atom-ID atom-type diameter density x y z
spin atom-ID atom-type x y z spx spy spz sp
tdpd atom-ID atom-type x y z cc1 cc2 . . . ccNspecies
template atom-ID atom-type molecule-ID template-index template-atom x y z
tri atom-ID molecule-ID atom-type triangleflag density x y z
wavepacket atom-ID atom-type charge spin eradius etag cs_re cs_im x y z
hybrid atom-ID atom-type x y z sub-style1 sub-style2 . . .

The per-atom values have these meanings and units, listed alphabetically:
• atom-ID = integer ID of atom
• atom-type = type of atom (1-Ntype)
• bodyflag = 1 for body particles, 0 for point particles
• bond_nt = bond NT factor for MESONT particles (?? units)
• buckling = buckling factor for MESONT particles (?? units)
• ccN = chemical concentration for tDPD particles for each species (mole/volume units)

894 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• cradius = contact radius for SMD particles (distance units)

• cs_re,cs_im = real/imaginary parts of wave packet coefficients
• cv = heat capacity (need units) for SPH particles
• density = density of particle (mass/distance^3 or mass/distance^2 or mass/distance units, depending on dimen-
sionality of particle)
• diameter = diameter of spherical atom (distance units)
• esph = energy (need units) for SPH particles
• edpd_temp = temperature for eDPD particles (temperature units)
• edpd_cv = volumetric heat capacity for eDPD particles (energy/temperature/volume units)
• ellipsoidflag = 1 for ellipsoidal particles, 0 for point particles
• eradius = electron radius (or fixed-core radius)
• etag = integer ID of electron that each wave packet belongs to
• kradius = kernel radius for SMD particles (distance units)
• lineflag = 1 for line segment particles, 0 for point or spherical particles
• mass = mass of particle (mass units)
• mlength = ?? length for MESONT particles (distance units)
• molecule-ID = integer ID of molecule the atom belongs to
• mradius = ?? radius for MESONT particles (distance units)
• mux,muy,muz = components of dipole moment of atom (dipole units)
• q = charge on atom (charge units)
• rho = density (need units) for SPH particles
• spin = electron spin (+1/-1), 0 = nuclei, 2 = fixed-core, 3 = pseudo-cores (i.e. ECP)
• sp = magnitude of magnetic spin of atom (Bohr magnetons)
• spx,spy,spz = components of magnetic spin of atom (unit vector)
• template-atom = which atom within a template molecule the atom is
• template-index = which molecule within the molecule template the atom is part of
• theta = internal temperature of a DPD particle
• triangleflag = 1 for triangular particles, 0 for point or spherical particles
• volume = volume of Peridynamic particle (distance^3 units)
• x,y,z = coordinates of atom (distance units)
• x0,y0,z0 = original (strain-free) coordinates of atom (distance units)
The units for these quantities depend on the unit style; see the units command for details.
For 2d simulations specify z as 0.0, or a value within the zlo zhi setting in the data file header.
The atom-ID is used to identify the atom throughout the simulation and in dump files. Normally, it is a unique value
from 1 to Natoms for each atom. Unique values larger than Natoms can be used, but they will cause extra memory to
be allocated on each processor, if an atom map array is used, but not if an atom map hash is used; see the atom_modify
command for details. If an atom map is not used (e.g. an atomic system with no bonds), and you don’t care if unique
atom IDs appear in dump files, then the atom-IDs can all be set to 0.

16.96. read_data command 895

LAMMPS Documentation, Release stable 29Sep2021

The molecule ID is a second identifier attached to an atom. Normally, it is a number from 1 to N, identifying which
molecule the atom belongs to. It can be 0 if it is a non-bonded atom or if you don’t care to keep track of molecule
assignments.
The diameter specifies the size of a finite-size spherical particle. It can be set to 0.0, which means that atom is a point
particle.
The ellipsoidflag, lineflag, triangleflag, and bodyflag determine whether the particle is a finite-size ellipsoid or line or
triangle or body of finite size, or whether the particle is a point particle. Additional attributes must be defined for each
ellipsoid, line, triangle, or body in the corresponding Ellipsoids, Lines, Triangles, or Bodies section.
The template-index and template-atom are only defined used by atom_style template. In this case the molecule command
is used to define a molecule template which contains one or more molecules (as separate files). If an atom belongs to
one of those molecules, its template-index and template-atom are both set to positive integers; if not the values are both
0. The template-index is which molecule (1 to Nmols) the atom belongs to. The template-atom is which atom (1 to
Natoms) within the molecule the atom is.
Some pair styles and fixes and computes that operate on finite-size particles allow for a mixture of finite-size and point
particles. See the doc pages of individual commands for details.
For finite-size particles, the density is used in conjunction with the particle volume to set the mass of each particle as
mass = density * volume. In this context, volume can be a 3d quantity (for spheres or ellipsoids), a 2d quantity (for
triangles), or a 1d quantity (for line segments). If the volume is 0.0, meaning a point particle, then the density value
is used as the mass. One exception is for the body atom style, in which case the mass of each particle (body or point
particle) is specified explicitly. This is because the volume of the body is unknown.
Note that for 2d simulations of spheres, this command will treat them as spheres when converting density to mass.
However, they can also be modeled as 2d discs (circles) if the set density/disc command is used to reset their mass after
the read_data command is used. A disc keyword can also be used with time integration fixes, such as fix nve/sphere
and fix nvt/sphere to time integrate their motion as 2d discs (not 3d spheres), by changing their moment of inertia.
For atom_style hybrid, following the 5 initial values (ID,type,x,y,z), specific values for each sub-style must be listed.
The order of the sub-styles is the same as they were listed in the atom_style command. The specific values for each
sub-style are those that are not the 5 standard ones (ID,type,x,y,z). For example, for the “charge” sub-style, a “q” value
would appear. For the “full” sub-style, a “molecule-ID” and “q” would appear. These are listed in the same order they
appear as listed above. Thus if

atom_style hybrid charge sphere

were used in the input script, each atom line would have these fields:

atom-ID atom-type x y z q diameter density

Note that if a non-standard value is defined by multiple sub-styles, it only appears once in the atom line. E.g. the atom
line for atom_style hybrid dipole full would list “q” only once, with the dipole sub-style fields; “q” does not appear
with the full sub-style fields.

atom-ID atom-type x y z q mux muy myz molecule-ID

Atom lines specify the (x,y,z) coordinates of atoms. These can be inside or outside the simulation box. When the
data file is read, LAMMPS wraps coordinates outside the box back into the box for dimensions that are periodic. As
discussed above, if an atom is outside the box in a non-periodic dimension, it will be lost.
LAMMPS always stores atom coordinates as values which are inside the simulation box. It also stores 3 flags which
indicate which image of the simulation box (in each dimension) the atom would be in if its coordinates were unwrapped
across periodic boundaries. An image flag of 0 means the atom is still inside the box when unwrapped. A value of
2 means add 2 box lengths to get the unwrapped coordinate. A value of -1 means subtract 1 box length to get the
unwrapped coordinate. LAMMPS updates these flags as atoms cross periodic boundaries during the simulation. The
dump command can output atom coordinates in wrapped or unwrapped form, as well as the 3 image flags.

896 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

In the data file, atom lines (all lines or none of them) can optionally list 3 trailing integer values (nx,ny,nz), which are
used to initialize the atom’s image flags. If nx,ny,nz values are not listed in the data file, LAMMPS initializes them to
0. Note that the image flags are immediately updated if an atom’s coordinates need to wrapped back into the simulation
box.
It is only important to set image flags correctly in a data file if a simulation model relies on unwrapped coordinates
for some calculation; otherwise they can be left unspecified. Examples of LAMMPS commands that use unwrapped
coordinates internally are as follows:
• Atoms in a rigid body (see fix rigid, fix rigid/small) must have consistent image flags, so that when the atoms are
unwrapped, they are near each other, i.e. as a single body.
• If the replicate command is used to generate a larger system, image flags must be consistent for bonded atoms
when the bond crosses a periodic boundary. I.e. the values of the image flags should be different by 1 (in the
appropriate dimension) for the two atoms in such a bond.
• If you plan to dump image flags and perform post-analysis that will unwrap atom coordinates, it may be important
that a continued run (restarted from a data file) begins with image flags that are consistent with the previous run.

Note: If your system is an infinite periodic crystal with bonds then it is impossible to have fully consistent image flags.
This is because some bonds will cross periodic boundaries and connect two atoms with the same image flag.

Atom velocities and other atom quantities not defined above are set to 0.0 when the Atoms section is read. Velocities
can be set later by a Velocities section in the data file or by a velocity or set command in the input script.

Bodies section:
• one or more lines per body
• first line syntax: atom-ID Ninteger Ndouble

Ninteger = # of integer quantities for this particle

Ndouble = # of floating-point quantities for this particle

• 0 or more integer lines with total of Ninteger values

• 0 or more double lines with total of Ndouble values
• example:

12 3 6
2 3 2
1.0 2.0 3.0 1.0 2.0 4.0

• example:

12 0 14
1.0 2.0 3.0 1.0 2.0 4.0 1.0
2.0 3.0 1.0 2.0 4.0 4.0 2.0

The Bodies section must appear if atom_style body is used and any atoms listed in the Atoms section have a bodyflag
= 1. The number of bodies should be specified in the header section via the “bodies” keyword.
Each body can have a variable number of integer and/or floating-point values. The number and meaning of the values
is defined by the body style, as described in the Howto body doc page. The body style is given as an argument to the
atom_style body command.

16.96. read_data command 897

LAMMPS Documentation, Release stable 29Sep2021

The Ninteger and Ndouble values determine how many integer and floating-point values are specified for this particle.
Ninteger and Ndouble can be as large as needed and can be different for every body. Integer values are then listed
next on subsequent lines. Lines are read one at a time until Ninteger values are read. Floating-point values follow on
subsequent lines, Again lines are read one at a time until Ndouble values are read. Note that if there are no values of a
particular type, no lines appear for that type.
The Bodies section must appear after the Atoms section.

Bond Coeffs section:

• one line per bond type
• line syntax: ID coeffs

ID = bond type (1-N)

coeffs = list of coeffs

• example:

4 250 1.49

The number and meaning of the coefficients are specific to the defined bond style. See the bond_style and bond_coeff
commands for details. Coefficients can also be set via the bond_coeff command in the input script.

BondAngle Coeffs section:

• one line per angle type
• line syntax: ID coeffs
ID = angle type (1-N)
coeffs = list of coeffs (see class 2 section of angle_coeff )

BondBond Coeffs section:

• one line per angle type
• line syntax: ID coeffs
ID = angle type (1-N)
coeffs = list of coeffs (see class 2 section of angle_coeff )

BondBond13 Coeffs section:

• one line per dihedral type
• line syntax: ID coeffs
ID = dihedral type (1-N)
coeffs = list of coeffs (see class 2 section of dihedral_coeff )

Bonds section:
• one line per bond
• line syntax: ID type atom1 atom2

898 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

ID = bond number (1-Nbonds)

type = bond type (1-Nbondtype)
atom1,atom2 = IDs of 1st,2nd atom in bond

• example:

12 3 17 29

The Bonds section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).

Dihedral Coeffs section:

• one line per dihedral type
• line syntax: ID coeffs

ID = dihedral type (1-N)

coeffs = list of coeffs

• example:

3 0.6 1 0 1

The number and meaning of the coefficients are specific to the defined dihedral style. See the dihedral_style and
dihedral_coeff commands for details. Coefficients can also be set via the dihedral_coeff command in the input script.

Dihedrals section:
• one line per dihedral
• line syntax: ID type atom1 atom2 atom3 atom4

ID = number of dihedral (1-Ndihedrals)

type = dihedral type (1-Ndihedraltype)
atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atom in dihedral

• example:

12 4 17 29 30 21

The 4 atoms are ordered linearly within the dihedral. The Dihedrals section must appear after the Atoms section. All
values in this section must be integers (1, not 1.0).

Ellipsoids section:
• one line per ellipsoid
• line syntax: atom-ID shapex shapey shapez quatw quati quatj quatk

atom-ID = ID of atom which is an ellipsoid

shapex,shapey,shapez = 3 diameters of ellipsoid (distance units)
quatw,quati,quatj,quatk = quaternion components for orientation of atom

• example:

16.96. read_data command 899

LAMMPS Documentation, Release stable 29Sep2021

12 1 2 1 1 0 0 0

The Ellipsoids section must appear if atom_style ellipsoid is used and any atoms are listed in the Atoms section with
an ellipsoidflag = 1. The number of ellipsoids should be specified in the header section via the “ellipsoids” keyword.
The 3 shape values specify the 3 diameters or aspect ratios of a finite-size ellipsoidal particle, when it is oriented along
the 3 coordinate axes. They must all be non-zero values.
The values quatw, quati, quatj, and quatk set the orientation of the atom as a quaternion (4-vector). Note that the
shape attributes specify the aspect ratios of an ellipsoidal particle, which is oriented by default with its x-axis along
the simulation box’s x-axis, and similarly for y and z. If this body is rotated (via the right-hand rule) by an angle
theta around a unit vector (a,b,c), then the quaternion that represents its new orientation is given by (cos(theta/2),
a*sin(theta/2), b*sin(theta/2), c*sin(theta/2)). These 4 components are quatw, quati, quatj, and quatk as specified
above. LAMMPS normalizes each atom’s quaternion in case (a,b,c) is not specified as a unit vector.
The Ellipsoids section must appear after the Atoms section.

EndBondTorsion Coeffs section:

• one line per dihedral type
• line syntax: ID coeffs
ID = dihedral type (1-N)
coeffs = list of coeffs (see class 2 section of dihedral_coeff )

Improper Coeffs section:

• one line per improper type
• line syntax: ID coeffs

ID = improper type (1-N)

coeffs = list of coeffs

• example:

2 20 0.0548311

The number and meaning of the coefficients are specific to the defined improper style. See the improper_style and
improper_coeff commands for details. Coefficients can also be set via the improper_coeff command in the input
script.

Impropers section:
• one line per improper
• line syntax: ID type atom1 atom2 atom3 atom4

ID = number of improper (1-Nimpropers)

type = improper type (1-Nimpropertype)
atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atom in improper

• example:

900 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

12 3 17 29 13 100

The ordering of the 4 atoms determines the definition of the improper angle used in the formula for each improper
style. See the doc pages for individual styles for details.
The Impropers section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).

Lines section:
• one line per line segment
• line syntax: atom-ID x1 y1 x2 y2

atom-ID = ID of atom which is a line segment

x1,y1 = 1st end point
x2,y2 = 2nd end point

• example:

12 1.0 0.0 2.0 0.0

The Lines section must appear if atom_style line is used and any atoms are listed in the Atoms section with a lineflag =
1. The number of lines should be specified in the header section via the “lines” keyword.
The 2 end points are the end points of the line segment. The ordering of the 2 points should be such that using a
right-hand rule to cross the line segment with a unit vector in the +z direction, gives an “outward” normal vector
perpendicular to the line segment. I.e. normal = (c2-c1) x (0,0,1). This orientation may be important for defining some
interactions.
The Lines section must appear after the Atoms section.

Masses section:
• one line per atom type
• line syntax: ID mass

ID = atom type (1-N)

mass = mass value

• example:

3 1.01

This defines the mass of each atom type. This can also be set via the mass command in the input script. This section
cannot be used for atom styles that define a mass for individual atoms - e.g. atom_style sphere.

MiddleBondTorsion Coeffs section:

• one line per dihedral type
• line syntax: ID coeffs
ID = dihedral type (1-N)
coeffs = list of coeffs (see class 2 section of dihedral_coeff )

16.96. read_data command 901

LAMMPS Documentation, Release stable 29Sep2021

Pair Coeffs section:

• one line per atom type
• line syntax: ID coeffs

ID = atom type (1-N)

coeffs = list of coeffs

• example:

3 0.022 2.35197 0.022 2.35197

The number and meaning of the coefficients are specific to the defined pair style. See the pair_style and pair_coeff
commands for details. Since pair coefficients for types I != J are not specified, these will be generated automatically
by the pair style’s mixing rule. See the individual pair_style doc pages and the pair_modify mix command for details.
Pair coefficients can also be set via the pair_coeff command in the input script.

PairIJ Coeffs section:

• one line per pair of atom types for all I,J with I <= J
• line syntax: ID1 ID2 coeffs

ID1 = atom type I = 1-N

ID2 = atom type J = I-N, with I <= J
coeffs = list of coeffs

• examples:

3 3 0.022 2.35197 0.022 2.35197

3 5 0.022 2.35197 0.022 2.35197

This section must have N*(N+1)/2 lines where N = # of atom types. The number and meaning of the coefficients
are specific to the defined pair style. See the pair_style and pair_coeff commands for details. Since pair coefficients
for types I != J are all specified, these values will turn off the default mixing rule defined by the pair style. See the
individual pair_style doc pages and the pair_modify mix command for details. Pair coefficients can also be set via the
pair_coeff command in the input script.

Triangles section:
• one line per triangle
• line syntax: atom-ID x1 y1 z1 x2 y2 z2 x3 y3 z3

atom-ID = ID of atom which is a line segment

x1,y1,z1 = 1st corner point
x2,y2,z2 = 2nd corner point
x3,y3,z3 = 3rd corner point

• example:

902 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

12 0.0 0.0 0.0 2.0 0.0 1.0 0.0 2.0 1.0

The Triangles section must appear if atom_style tri is used and any atoms are listed in the Atoms section with a trian-
gleflag = 1. The number of lines should be specified in the header section via the “triangles” keyword.
The 3 corner points are the corner points of the triangle. The ordering of the 3 points should be such that using a
right-hand rule to go from point1 to point2 to point3 gives an “outward” normal vector to the face of the triangle. I.e.
normal = (c2-c1) x (c3-c1). This orientation may be important for defining some interactions.
The Triangles section must appear after the Atoms section.

Velocities section:
• one line per atom
• line syntax: depends on atom style

all styles except those listed atom-ID vx vy vz

electron atom-ID vx vy vz ervel
ellipsoid atom-ID vx vy vz lx ly lz
sphere atom-ID vx vy vz wx wy wz
hybrid atom-ID vx vy vz sub-style1 sub-style2 . . .

where the keywords have these meanings:

vx,vy,vz = translational velocity of atom lx,ly,lz = angular momentum of aspherical atom wx,wy,wz = angular velocity
of spherical atom ervel = electron radial velocity (0 for fixed-core):ul
The velocity lines can appear in any order. This section can only be used after an Atoms section. This is because the
Atoms section must have assigned a unique atom ID to each atom so that velocities can be assigned to them.
Vx, vy, vz, and ervel are in units of velocity. Lx, ly, lz are in units of angular momentum (distance-velocity-mass). Wx,
Wy, Wz are in units of angular velocity (radians/time).
For atom_style hybrid, following the 4 initial values (ID,vx,vy,vz), specific values for each sub-style must be listed.
The order of the sub-styles is the same as they were listed in the atom_style command. The sub-style specific values are
those that are not the 5 standard ones (ID,vx,vy,vz). For example, for the “sphere” sub-style, “wx”, “wy”, “wz” values
would appear. These are listed in the same order they appear as listed above. Thus if

atom_style hybrid electron sphere

were used in the input script, each velocity line would have these fields:

atom-ID vx vy vz ervel wx wy wz

Translational velocities can also be set by the velocity command in the input script.

16.96. read_data command 903

LAMMPS Documentation, Release stable 29Sep2021

16.96.8 Restrictions

To read gzipped data files, you must compile LAMMPS with the -DLAMMPS_GZIP option. See the Build settings
doc page for details.

16.96.9 Related commands

read_dump, read_restart, create_atoms, write_data

16.96.10 Default

The default for all the extra keywords is 0.

16.97 read_dump command

16.97.1 Syntax

read_dump file Nstep field1 field2 ... keyword values ...

• file = name of dump file to read

• Nstep = snapshot timestep to read from file
• one or more fields may be appended
field = x or y or z or vx or vy or vz or q or ix or iy or iz or fx or fy or fz
x,y,z = atom coordinates
vx,vy,vz = velocity components
q = charge
ix,iy,iz = image flags in each dimension
fx,fy,fz = force components
• zero or more keyword/value pairs may be appended
• keyword = nfile or box or replace or purge or trim or add or label or scaled or wrapped or format
nfile value = Nfiles = how many parallel dump files exist
box value = yes or no = replace simulation box with dump box
replace value = yes or no = overwrite atoms with dump atoms
purge value = yes or no = delete all atoms before adding dump atoms
trim value = yes or no = trim atoms not in dump snapshot
add value = yes or keep or no = add new dump atoms to system
label value = field column
field = one of the listed fields or id or type
column = label on corresponding column in dump file
scaled value = yes or no = coords in dump file are scaled/unscaled
wrapped value = yes or no = coords in dump file are wrapped/unwrapped
format values = format of dump file, must be last keyword if used
native = native LAMMPS dump file
xyz = XYZ file
adios [timeout value] = dump file written by the dump adios command
timeout = specify waiting time for the arrival of the timestep when running␣
,→concurrently.

904 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The value is a float number and is interpreted in seconds.

molfile style path = VMD molfile plugin interface
style = dcd or xyz or others supported by molfile plugins
path = optional path for location of molfile plugins

16.97.2 Examples

read_dump dump.file 5000 x y z

read_dump dump.xyz 5 x y z box no format xyz
read_dump dump.xyz 10 x y z box no format molfile xyz "../plugins"
read_dump dump.dcd 0 x y z box yes format molfile dcd
read_dump dump.file 1000 x y z vx vy vz box yes format molfile lammpstrj /usr/local/lib/
,→vmd/plugins/LINUXAMD64/plugins/molfile

read_dump dump.file 5000 x y vx vy trim yes

read_dump ../run7/dump.file.gz 10000 x y z box yes
read_dump dump.xyz 10 x y z box no format molfile xyz ../plugins
read_dump dump.dcd 0 x y z format molfile dcd
read_dump dump.file 1000 x y z vx vy vz format molfile lammpstrj /usr/local/lib/vmd/
,→plugins/LINUXAMD64/plugins/molfile

read_dump dump.bp 5000 x y z vx vy vz format adios

read_dump dump.bp 5000 x y z vx vy vz format adios timeout 60.0

16.97.3 Description

Read atom information from a dump file to overwrite the current atom coordinates, and optionally the atom velocities
and image flags and the simulation box dimensions. This is useful for restarting a run from a particular snapshot in
a dump file. See the read_restart and read_data commands for alternative methods to do this. Also see the rerun
command for a means of reading multiple snapshots from a dump file.
Note that a simulation box must already be defined before using the read_dump command. This can be done by the
create_box, read_data, or read_restart commands. The read_dump command can reset the simulation box dimensions,
as explained below.
Also note that reading per-atom information from a dump snapshot is limited to the atom coordinates, velocities and
image flags, as explained below. Other atom properties, which may be necessary to run a valid simulation, such as
atom charge, or bond topology information for a molecular system, are not read from (or even contained in) dump files.
Thus this auxiliary information should be defined in the usual way, e.g. in a data file read in by a read_data command,
before using the read_dump command, or by the set command, after the dump snapshot is read.

If the dump filename specified as file ends with “.gz”, the dump file is read in gzipped format. You cannot (yet) read a
dump file that was written in binary format with a “.bin” suffix.
You can read dump files that were written (in parallel) to multiple files via the “%” wild-card character in the dump
file name. If any specified dump file name contains a “%”, they must all contain it. See the dump command for details.
The “%” wild-card character is only supported by the native format for dump files, described next.
If reading parallel dump files, you must also use the nfile keyword to tell LAMMPS how many parallel files exist, via
its specified Nfiles value.
The format of the dump file is selected through the format keyword. If specified, it must be the last keyword used,
since all remaining arguments are passed on to the dump reader. The native format is for native LAMMPS dump files,
written with a dump atom or dump custom command. The xyz format is for generic XYZ formatted dump files. These
formats take no additional values.

16.97. read_dump command 905

LAMMPS Documentation, Release stable 29Sep2021

The molfile format supports reading data through using the VMD molfile plugin interface. This dump reader format is
only available, if the MOLFILE package has been installed when compiling LAMMPS.
The molfile format takes one or two additional values. The style value determines the file format to be used and can
be any format that the molfile plugins support, such as DCD or XYZ. Note that DCD dump files can be written by
LAMMPS via the dump dcd command. The path value specifies a list of directories which LAMMPS will search
for the molfile plugins appropriate to the specified style. The syntax of the path value is like other search paths: it
can contain multiple directories separated by a colon (or semi-colon on windows). The path keyword is optional and
defaults to “.”, i.e. the current directory.
The adios format supports reading data that was written by the dump adios command. The entire dump is read in parallel
across all the processes, dividing the atoms evenly among the processes. The number of writers that has written the
dump file does not matter. Using the adios style for dump and read_dump is a convenient way to dump all atoms from
N writers and read it back by M readers. If one is running two LAMMPS instances concurrently where one dumps
data and the other is reading it with the rerun command, the timeout option can be specified to wait on the reader side
for the arrival of the requested step.
Support for other dump format readers may be added in the future.

Global information is first read from the dump file, namely timestep and box information.
The dump file is scanned for a snapshot with a timestamp that matches the specified Nstep. This means the LAMMPS
timestep the dump file snapshot was written on for the native or adios formats.
The list of timestamps available in an adios .bp file is stored in the variable ntimestep:

$ bpls dump.bp -d ntimestep

uint64_t ntimestep 5*scalar
(0) 0 50 100 150 200

Note that the xyz and molfile formats do not store the timestep. For these formats, timesteps are numbered logically,
in a sequential manner, starting from 0. Thus to access the 10th snapshot in an xyz or mofile formatted dump file, use
Nstep = 9.
The dimensions of the simulation box for the selected snapshot are also read; see the box keyword discussion below. For
the native format, an error is generated if the snapshot is for a triclinic box and the current simulation box is orthogonal
or vice versa. A warning will be generated if the snapshot box boundary conditions (periodic, shrink-wrapped, etc)
do not match the current simulation boundary conditions, but the boundary condition information in the snapshot is
otherwise ignored. See the “boundary” command for more details. The adios reader does the same as the native format
reader.
For the xyz format, no information about the box is available, so you must set the box flag to no. See details below.
For the molfile format, reading simulation box information is typically supported, but the location of the simulation box
origin is lost and no explicit information about periodicity or orthogonal/triclinic box shape is available. The MOLFILE
package makes a best effort to guess based on heuristics, but this may not always work perfectly.

Per-atom information from the dump file snapshot is then read from the dump file snapshot. This corresponds to the
specified fields listed in the read_dump command. It is an error to specify a z-dimension field, namely z, vz, or iz, for
a 2d simulation.
For dump files in native format, each column of per-atom data has a text label listed in the file. A matching label for
each field must appear, e.g. the label “vy” for the field vy. For the x, y, z fields any of the following labels are considered
a match:
x, xs, xu, xsu for field x
y, ys, yu, ysu for field y
z, zs, zu, zsu for field z

906 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

The meaning of xs (scaled), xu (unwrapped), and xsu (scaled and unwrapped) is explained on the dump command doc
page. These labels are searched for in the list of column labels in the dump file, in order, until a match is found.
The dump file must also contain atom IDs, with a column label of “id”.
If the add keyword is specified with a value of yes or keep, as discussed below, the dump file must contain atom types,
with a column label of “type”.
If a column label you want to read from the dump file is not a match to a specified field, the label keyword can be used
to specify the specific column label from the dump file to associate with that field. An example is if a time-averaged
coordinate is written to the dump file via the fix ave/atom command. The column will then have a label corresponding
to the fix-ID rather than “x” or “xs”. The label keyword can also be used to specify new column labels for fields id and
type.
For dump files in xyz format, only the x, y, and z fields are supported. The dump file does not store atom IDs, so these
are assigned consecutively to the atoms as they appear in the dump file, starting from 1. Thus you should insure that
order of atoms is consistent from snapshot to snapshot in the XYZ dump file. See the dump_modify sort command if
the XYZ dump file was written by LAMMPS.
For dump files in molfile format, the x, y, z, vx, vy, and vz fields can be specified. However, not all molfile formats store
velocities, or their respective plugins may not support reading of velocities. The molfile dump files do not store atom
IDs, so these are assigned consecutively to the atoms as they appear in the dump file, starting from 1. Thus you should
insure that order of atoms are consistent from snapshot to snapshot in the molfile dump file. See the dump_modify sort
command if the dump file was written by LAMMPS.
The adios format supports all fields that the native format supports except for the q charge field. The list of fields stored
in an adios .bp file is recorded in the attributes columns (array of short strings) and columnstr (space-separated single
string).

$ bpls -la dump.bp column*

string columns attr = {"id", "type", "x", "y", "z", "vx", "vy", "vz"}
string columnstr attr = "id type x y z vx vy vz "

Information from the dump file snapshot is used to overwrite or replace properties of the current system. There are
various options for how this is done, determined by the specified fields and optional keywords.
The timestep of the snapshot becomes the current timestep for the simulation. See the reset_timestep command if you
wish to change this after the dump snapshot is read.
If the box keyword is specified with a yes value, then the current simulation box dimensions are replaced by the dump
snapshot box dimensions. If the box keyword is specified with a no value, the current simulation box is unchanged.
If the purge keyword is specified with a yes value, then all current atoms in the system are deleted before any of the
operations invoked by the replace, trim, or add keywords take place.
If the replace keyword is specified with a yes value, then atoms with IDs that are in both the current system and the
dump snapshot have their properties overwritten by field values. If the replace keyword is specified with a no value,
atoms with IDs that are in both the current system and the dump snapshot are not modified.
If the trim keyword is specified with a yes value, then atoms with IDs that are in the current system but not in the dump
snapshot are deleted. These atoms are unaffected if the trim keyword is specified with a no value.
If the add keyword is specified with a no value (default), then dump file atoms with IDs that are not in the current
system are not added to the system. They are simply ignored.
If a yes value is specified, the atoms with new IDs are added to the system but their atom IDs are not preserved. Instead,
after all the atoms are added, new IDs are assigned to them in the same manner as is described for the create_atoms
command. Basically the largest existing atom ID in the system is identified, and all the added atoms are assigned IDs
that consecutively follow the largest ID.

16.97. read_dump command 907

LAMMPS Documentation, Release stable 29Sep2021

If a keep value is specified, the atoms with new IDs are added to the system and their atom IDs are preserved. This
may lead to non-contiguous IDs for the combined system.
Note that atoms added via the add keyword will only have the attributes read from the dump file due to the field
arguments. For example, if x or y or z or q is not specified as a field, a value of 0.0 is used for added atoms. Added
atoms must have an atom type, so this value must appear in the dump file.
Any other attributes (e.g. charge or particle diameter for spherical particles) will be set to default values, the same as
if the create_atoms command were used.

Atom coordinates read from the dump file are first converted into unscaled coordinates, relative to the box dimensions
of the snapshot. These coordinates are then be assigned to an existing or new atom in the current simulation. The
coordinates will then be remapped to the simulation box, whether it is the original box or the dump snapshot box. If
periodic boundary conditions apply, this means the atom will be remapped back into the simulation box if necessary.
If shrink-wrap boundary conditions apply, the new coordinates may change the simulation box dimensions. If fixed
boundary conditions apply, the atom will be lost if it is outside the simulation box.
For native format dump files, the 3 xyz image flags for an atom in the dump file are set to the corresponding values
appearing in the dump file if the ix, iy, iz fields are specified. If not specified, the image flags for replaced atoms
are not changed and image flags for new atoms are set to default values. If coordinates read from the dump file are
in unwrapped format (e.g. xu) then the image flags for read-in atoms are also set to default values. The remapping
procedure described in the previous paragraph will then change images flags for all atoms (old and new) if periodic
boundary conditions are applied to remap an atom back into the simulation box.

Note: If you get a warning about inconsistent image flags after reading in a dump snapshot, it means one or more pairs
of bonded atoms now have inconsistent image flags. As discussed on the Errors common page this may or may not
cause problems for subsequent simulations. One way this can happen is if you read image flag fields from the dump
file but do not also use the dump file box parameters.

LAMMPS knows how to compute unscaled and remapped coordinates for the snapshot column labels discussed above,
e.g. x, xs, xu, xsu. If another column label is assigned to the x or y or z field via the label keyword, e.g. for coordinates
output by the fix ave/atom command, then LAMMPS needs to know whether the coordinate information in the dump
file is scaled and/or wrapped. This can be set via the scaled and wrapped keywords. Note that the value of the scaled
and wrapped keywords is ignored for fields x or y or z if the label keyword is not used to assign a column label to that
field.
The scaled/unscaled and wrapped/unwrapped setting must be identical for any of the x, y, z fields that are specified.
Thus you cannot read xs and yu from the dump file. Also, if the dump file coordinates are scaled and the simulation
box is triclinic, then all 3 of the x, y, z fields must be specified, since they are all needed to generate absolute, unscaled
coordinates.

16.97.4 Restrictions

The native dump file reader does not support binary .bin dump files.
To read gzipped dump files, you must compile LAMMPS with the -DLAMMPS_GZIP option. See the Build settings
doc page for details.
The molfile dump file formats are part of the MOLFILE package. They are only enabled if LAMMPS was built with
that packages. See the Build package page for more info.
To write and read adios .bp files, you must compile LAMMPS with the ADIOS package.

908 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.97.5 Related commands

dump, dump molfile, dump adios, read_data, read_restart, rerun

16.97.6 Default

The option defaults are box = yes, replace = yes, purge = no, trim = no, add = no, scaled = no, wrapped = yes, and
format = native.

16.98 read_restart command

16.98.1 Syntax

read_restart file flag

• file = name of binary restart file to read in

• flag = remap (optional)

16.98.2 Examples

read_restart save.10000
read_restart save.10000 remap
read_restart restart.*
read_restart restart.*.mpiio
read_restart poly.*.% remap

16.98.3 Description

Read in a previously saved system configuration from a restart file. This allows continuation of a previous run. Details
about what information is stored (and not stored) in a restart file is given below. Basically this operation will re-create
the simulation box with all its atoms and their attributes as well as some related global settings, at the point in time it
was written to the restart file by a previous simulation. The simulation box will be partitioned into a regular 3d grid of
rectangular bricks, one per processor, based on the number of processors in the current simulation and the settings of
the processors command. The partitioning can later be changed by the balance or fix balance commands.

Note: Normally, restart files are written by the restart or write_restart commands so that all atoms in the restart file
are inside the simulation box. If this is not the case, the read_restart command will print an error that atoms were “lost”
when the file is read. This error should be reported to the LAMMPS developers so the invalid writing of the restart
file can be fixed. If you still wish to use the restart file, the optional remap flag can be appended to the read_restart
command. This should avoid the error, by explicitly remapping each atom back into the simulation box, updating image
flags for the atom appropriately.

Restart files are saved in binary format to enable exact restarts, meaning that the trajectories of a restarted run will
precisely match those produced by the original run had it continued on.

16.98. read_restart command 909

LAMMPS Documentation, Release stable 29Sep2021

Several things can prevent exact restarts due to round-off effects, in which case the trajectories in the 2 runs will slowly
diverge. These include running on a different number of processors or changing certain settings such as those set by
the newton or processors commands. LAMMPS will issue a warning in these cases.
Certain fixes will not restart exactly, though they should provide statistically similar results. These include fix shake
and fix langevin.
Certain pair styles will not restart exactly, though they should provide statistically similar results. This is because the
forces they compute depend on atom velocities, which are used at half-step values every timestep when forces are
computed. When a run restarts, forces are initially evaluated with a full-step velocity, which is different than if the run
had continued. These pair styles include granular pair styles, pair dpd, and pair lubricate.
If a restarted run is immediately different than the run which produced the restart file, it could be a LAMMPS bug, so
consider reporting it if you think the behavior is a bug.
Because restart files are binary, they may not be portable to other machines. In this case, you can use the -restart
command-line switch to convert a restart file to a data file.
Similar to how restart files are written (see the write_restart and restart commands), the restart filename can contain
two wild-card characters. If a “*” appears in the filename, the directory is searched for all filenames that match the
pattern where “*” is replaced with a timestep value. The file with the largest timestep value is read in. Thus, this
effectively means, read the latest restart file. It’s useful if you want your script to continue a run from where it left off.
See the run command and its “upto” option for how to specify the run command so it does not need to be changed
either.
If a “%” character appears in the restart filename, LAMMPS expects a set of multiple files to exist. The restart and
write_restart commands explain how such sets are created. Read_restart will first read a filename where “%” is replaced
by “base”. This file tells LAMMPS how many processors created the set and how many files are in it. Read_restart then
reads the additional files. For example, if the restart file was specified as save.% when it was written, then read_restart
reads the files save.base, save.0, save.1, . . . save.P-1, where P is the number of processors that created the restart file.
Note that P could be the total number of processors in the previous simulation, or some subset of those processors, if
the fileper or nfile options were used when the restart file was written; see the restart and write_restart commands for
details. The processors in the current LAMMPS simulation share the work of reading these files; each reads a roughly
equal subset of the files. The number of processors which created the set can be different the number of processors in
the current LAMMPS simulation. This can be a fast mode of input on parallel machines that support parallel I/O.
A restart file can also be read in parallel as one large binary file via the MPI-IO library, assuming it was also written
with MPI-IO. MPI-IO is part of the MPI standard for versions 2.0 and above. Using MPI-IO requires two steps. First,
build LAMMPS with its MPIIO package installed, e.g.

make yes-mpiio # installs the MPIIO package

make mpi # build LAMMPS for your platform

Second, use a restart filename which contains “.mpiio”. Note that it does not have to end in “.mpiio”, just contain those
characters. Unlike MPI-IO dump files, a particular restart file must be both written and read using MPI-IO.

Here is the list of information included in a restart file, which means these quantities do not need to be re-specified in
the input script that reads the restart file, though you can redefine many of these settings after the restart file is read.
• units
• newton bond (see discussion of newton command below)
• atom style and atom_modify settings id, map, sort
• comm style and comm_modify settings mode, cutoff, vel
• timestep

910 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• simulation box size and shape and boundary settings

• atom group definitions
• per-type atom settings such as mass
• per-atom attributes including their group assignments and molecular topology attributes (bonds, angles, etc)
• force field styles (pair, bond, angle, etc)
• force field coefficients (pair, bond, angle, etc) in some cases (see below)
• pair_modify settings, except the compute option
• special_bonds settings
Here is a list of information not stored in a restart file, which means you must re-issue these commands in your input
script, after reading the restart file.
• newton pair (see discussion of newton command below)
• fix commands (see below)
• compute commands (see below)
• variable commands
• region commands
• neighbor list criteria including neigh_modify settings
• kspace_style and kspace_modify settings
• info for thermodynamic, dump, or restart output
The newton command has two settings, one for pairwise interactions, the other for bonded. Both settings are stored in
the restart file. For the bond setting, the value in the file will overwrite the current value (at the time the read_restart
command is issued) and warn if the two values are not the same and the current value is not the default. For the pair
setting, the value in the file will not overwrite the current value (so that you can override the previous run’s value), but
a warning is issued if the two values are not the same and the current value is not the default.
Note that some force field styles (pair, bond, angle, etc) do not store their coefficient info in restart files. Typically these
are many-body or tabulated potentials which read their parameters from separate files. In these cases you will need to
re-specify the pair_coeff , bond_coeff , etc commands in your restart input script. The doc pages for individual force
field styles mention if this is the case. This is also true of pair_style hybrid (bond hybrid, angle hybrid, etc) commands;
they do not store coefficient info.
As indicated in the above list, the fixes used for a simulation are not stored in the restart file. This means the new input
script should specify all fixes it will use. However, note that some fixes store an internal “state” which is written to the
restart file. This allows the fix to continue on with its calculations in a restarted simulation. To re-enable such a fix, the
fix command in the new input script must be of the same style and use the same fix-ID as was used in the input script
that wrote the restart file.
If a match is found, LAMMPS prints a message indicating that the fix is being re-enabled. If no match is found before
the first run or minimization is performed by the new script, the “state” information for the saved fix is discarded. At
the time the discard occurs, LAMMPS will also print a list of fixes for which the information is being discarded. See
the doc pages for individual fixes for info on which ones can be restarted in this manner. Note that fixes which are
created internally by other LAMMPS commands (computes, fixes, etc) will have style names which are all-capitalized,
and IDs which are generated internally.
Likewise, the computes used for a simulation are not stored in the restart file. This means the new input script should
specify all computes it will use. However, some computes create a fix internally to store “state” information that persists
from timestep to timestep. An example is the compute msd command which uses a fix to store a reference coordinate for
each atom, so that a displacement can be calculated at any later time. If the compute command in the new input script

16.98. read_restart command 911

LAMMPS Documentation, Release stable 29Sep2021

uses the same compute-ID and group-ID as was used in the input script that wrote the restart file, then it will create
the same fix in the restarted run. This means the re-created fix will be re-enabled with the stored state information as
described in the previous paragraph, so that the compute can continue its calculations in a consistent manner.

Note: There are a handful of commands which can be used before or between runs which may require a system
initialization. Examples include the “balance”, “displace_atoms”, “delete_atoms”, “set” (some options), and “velocity”
(some options) commands. This is because they can migrate atoms to new processors. Thus they will also discard
unused “state” information from fixes. You will know the discard has occurred because a list of discarded fixes will be
printed to the screen and log file, as explained above. This means that if you wish to retain that info in a restarted run,
you must re-specify the relevant fixes and computes (which create fixes) before those commands are used.

Some pair styles, like the granular pair styles, also use a fix to store “state” information that persists from timestep to
timestep. In the case of granular potentials, it is contact information between pairs of touching particles. This info will
also be re-enabled in the restart script, assuming you re-use the same granular pair style.
LAMMPS allows bond interactions (angle, etc) to be turned off or deleted in various ways, which can affect how their
info is stored in a restart file.
If bonds (angles, etc) have been turned off by the fix shake or delete_bonds command, their info will be written to a
restart file as if they are turned on. This means they will need to be turned off again in a new run after the restart file is
read.
Bonds that are broken (e.g. by a bond-breaking potential) are written to the restart file as broken bonds with a type of
0. Thus these bonds will still be broken when the restart file is read.
Bonds that have been broken by the fix bond/break command have disappeared from the system. No information about
these bonds is written to the restart file.

16.98.4 Restrictions

To write and read restart files in parallel with MPI-IO, the MPIIO package must be installed.

16.98.5 Related commands

read_data, read_dump, write_restart, restart

16.98.6 Default

none

16.99 region command

16.99.1 Syntax

region ID style args keyword arg ...

• ID = user-assigned name for the region

• style = delete or block or cone or cylinder or plane or prism or sphere or union or intersect

912 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

delete = no args
block args = xlo xhi ylo yhi zlo zhi
xlo,xhi,ylo,yhi,zlo,zhi = bounds of block in all dimensions (distance units)
cone args = dim c1 c2 radlo radhi lo hi
dim = x or y or z = axis of cone
c1,c2 = coords of cone axis in other 2 dimensions (distance units)
radlo,radhi = cone radii at lo and hi end (distance units)
lo,hi = bounds of cone in dim (distance units)
cylinder args = dim c1 c2 radius lo hi
dim = x or y or z = axis of cylinder
c1,c2 = coords of cylinder axis in other 2 dimensions (distance units)
radius = cylinder radius (distance units)
c1,c2, and radius can be a variable (see below)
lo,hi = bounds of cylinder in dim (distance units)
plane args = px py pz nx ny nz
px,py,pz = point on the plane (distance units)
nx,ny,nz = direction normal to plane (distance units)
prism args = xlo xhi ylo yhi zlo zhi xy xz yz
xlo,xhi,ylo,yhi,zlo,zhi = bounds of untilted prism (distance units)
xy = distance to tilt y in x direction (distance units)
xz = distance to tilt z in x direction (distance units)
yz = distance to tilt z in y direction (distance units)
sphere args = x y z radius
x,y,z = center of sphere (distance units)
radius = radius of sphere (distance units)
x,y,z, and radius can be a variable (see below)
union args = N reg-ID1 reg-ID2 ...
N = # of regions to follow, must be 2 or greater
reg-ID1,reg-ID2, ... = IDs of regions to join together
intersect args = N reg-ID1 reg-ID2 ...
N = # of regions to follow, must be 2 or greater
reg-ID1,reg-ID2, ... = IDs of regions to intersect
• zero or more keyword/arg pairs may be appended
• keyword = side or units or move or rotate or open
side value = in or out
in = the region is inside the specified geometry
out = the region is outside the specified geometry
units value = lattice or box
lattice = the geometry is defined in lattice units
box = the geometry is defined in simulation box units
move args = v_x v_y v_z
v_x,v_y,v_z = equal-style variables for x,y,z displacement of region over time
rotate args = v_theta Px Py Pz Rx Ry Rz
v_theta = equal-style variable for rotaton of region over time (in radians)
Px,Py,Pz = origin for axis of rotation (distance units)
Rx,Ry,Rz = axis of rotation vector
open value = integer from 1-6 corresponding to face index (see below)
• accelerated styles (with same args) = block/kk

16.99. region command 913

LAMMPS Documentation, Release stable 29Sep2021

16.99.2 Examples

region 1 block -3.0 5.0 INF 10.0 INF INF

region 2 sphere 0.0 0.0 0.0 5 side out
region void cylinder y 2 3 5 -5.0 EDGE units box
region 1 prism 0 10 0 10 0 10 2 0 0
region outside union 4 side1 side2 side3 side4
region 2 sphere 0.0 0.0 0.0 5 side out move v_left v_up NULL
region openbox block 0 10 0 10 0 10 open 5 open 6 units box
region funnel cone z 10 10 2 5 0 10 open 1 units box

16.99.3 Description

This command defines a geometric region of space. Various other commands use regions. For example, the region
can be filled with atoms via the create_atoms command. Or a bounding box around the region, can be used to define
the simulation box via the create_box command. Or the atoms in the region can be identified as a group via the group
command, or deleted via the delete_atoms command. Or the surface of the region can be used as a boundary wall via
the fix wall/region command.
Commands which use regions typically test whether an atom’s position is contained in the region or not. For this
purpose, coordinates exactly on the region boundary are considered to be interior to the region. This means, for example,
for a spherical region, an atom on the sphere surface would be part of the region if the sphere were defined with the
side in keyword, but would not be part of the region if it were defined using the side out keyword. See more details on
the side keyword below.
Normally, regions in LAMMPS are “static”, meaning their geometric extent does not change with time. If the move or
rotate keyword is used, as described below, the region becomes “dynamic”, meaning it’s location or orientation changes
with time. This may be useful, for example, when thermostatting a region, via the compute temp/region command, or
when the fix wall/region command uses a region surface as a bounding wall on particle motion, i.e. a rotating container.
The delete style removes the named region. Since there is little overhead to defining extra regions, there is normally no
need to do this, unless you are defining and discarding large numbers of regions in your input script.
The lo/hi values for block or cone or cylinder or prism styles can be specified as EDGE or INF. EDGE means they
extend all the way to the global simulation box boundary. Note that this is the current box boundary; if the box changes
size during a simulation, the region does not. INF means a large negative or positive number (1.0e20), so it should
encompass the simulation box even if it changes size. If a region is defined before the simulation box has been created
(via create_box or read_data or read_restart commands), then an EDGE or INF parameter cannot be used. For a
prism region, a non-zero tilt factor in any pair of dimensions cannot be used if both the lo/hi values in either of those
dimensions are INF. E.g. if the xy tilt is non-zero, then xlo and xhi cannot both be INF, nor can ylo and yhi.

Note: Regions in LAMMPS do not get wrapped across periodic boundaries, as specified by the boundary command.
For example, a spherical region that is defined so that it overlaps a periodic boundary is not treated as 2 half-spheres,
one on either side of the simulation box.

Note: Regions in LAMMPS are always 3d geometric objects, regardless of whether the dimension of a simulation is
2d or 3d. Thus when using regions in a 2d simulation, you should be careful to define the region so that its intersection
with the 2d x-y plane of the simulation has the 2d geometric extent you want.

For style cone, an axis-aligned cone is defined which is like a cylinder except that two different radii (one at each end)
can be defined. Either of the radii (but not both) can be 0.0.

914 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

For style cone and cylinder, the c1,c2 params are coordinates in the 2 other dimensions besides the cylinder axis
dimension. For dim = x, c1/c2 = y/z; for dim = y, c1/c2 = x/z; for dim = z, c1/c2 = x/y. Thus the third example above
specifies a cylinder with its axis in the y-direction located at x = 2.0 and z = 3.0, with a radius of 5.0, and extending in
the y-direction from -5.0 to the upper box boundary.
For style plane, a plane is defined which contain the point (px,py,pz) and has a normal vector (nx,ny,nz). The normal
vector does not have to be of unit length. The “inside” of the plane is the half-space in the direction of the normal
vector; see the discussion of the side option below.
For style prism, a parallelepiped is defined (it’s too hard to spell parallelepiped in an input script!). The parallelepiped
has its “origin” at (xlo,ylo,zlo) and is defined by 3 edge vectors starting from the origin given by A = (xhi-xlo,0,0);
B = (xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). Xy,xz,yz can be 0.0 or positive or negative values and are called “tilt factors”
because they are the amount of displacement applied to faces of an originally orthogonal box to transform it into the
parallelepiped.
A prism region that will be used with the create_box command to define a triclinic simulation box must have tilt factors
(xy,xz,yz) that do not skew the box more than half the distance of corresponding the parallel box length. For example,
if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz
and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor
is 5 (as in this example), then configurations with tilt = . . . , -15, -5, 5, 15, 25, . . . are all geometrically equivalent.
The radius value for style sphere and cylinder can be specified as an equal-style variable. If the value is a variable,
it should be specified as v_name, where name is the variable name. In this case, the variable will be evaluated each
timestep, and its value used to determine the radius of the region. For style sphere also the x-, y-, and z- coordinate of
the center of the sphere and for style cylinder the two center positions c1 and c2 for the location of the cylinder axes
can be a variable with the same kind of effect and requirements than for the radius.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
radius or have a time dependent position of the sphere or cylinder region.
See the Howto tricilinc page for a geometric description of triclinic boxes, as defined by LAMMPS, and how to trans-
form these parameters to and from other commonly used triclinic representations.
The union style creates a region consisting of the volume of all the listed regions combined. The intersect style creates
a region consisting of the volume that is common to all the listed regions.

Note: The union and intersect regions operate by invoking methods from their list of sub-regions. Thus you cannot
delete the sub-regions after defining a union or intersection region.

The side keyword determines whether the region is considered to be inside or outside of the specified geometry. Using
this keyword in conjunction with union and intersect regions, complex geometries can be built up. For example, if
the interior of two spheres were each defined as regions, and a union style with side = out was constructed listing the
region-IDs of the 2 spheres, the resulting region would be all the volume in the simulation box that was outside both
of the spheres.
The units keyword determines the meaning of the distance units used to define the region for any argument above listed
as having distance units. It also affects the scaling of the velocity vector specified with the vel keyword, the amplitude
vector specified with the wiggle keyword, and the rotation point specified with the rotate keyword, since they each
involve a distance metric.
A box value selects standard distance units as defined by the units command, e.g. Angstroms for units = real or metal.
A lattice value means the distance units are in lattice spacings. The lattice command must have been previously used
to define the lattice spacings which are used as follows:
• For style block, the lattice spacing in dimension x is applied to xlo and xhi, similarly the spacings in dimensions
y,z are applied to ylo/yhi and zlo/zhi.

16.99. region command 915

LAMMPS Documentation, Release stable 29Sep2021

• For style cone, the lattice spacing in argument dim is applied to lo and hi. The spacings in the two radial dimen-
sions are applied to c1 and c2. The two cone radii are scaled by the lattice spacing in the dimension corresponding
to c1.
• For style cylinder, the lattice spacing in argument dim is applied to lo and hi. The spacings in the two radial
dimensions are applied to c1 and c2. The cylinder radius is scaled by the lattice spacing in the dimension corre-
sponding to c1.
• For style plane, the lattice spacing in dimension x is applied to px and nx, similarly the spacings in dimensions
y,z are applied to py/ny and pz/nz.
• For style prism, the lattice spacing in dimension x is applied to xlo and xhi, similarly for ylo/yhi and zlo/zhi. The
lattice spacing in dimension x is applied to xy and xz, and the spacing in dimension y to yz.
• For style sphere, the lattice spacing in dimensions x,y,z are applied to the sphere center x,y,z. The spacing in
dimension x is applied to the sphere radius.

If the move or rotate keywords are used, the region is “dynamic”, meaning its location or orientation changes with time.
These keywords cannot be used with a union or intersect style region. Instead, the keywords should be used to make
the individual sub-regions of the union or intersect region dynamic. Normally, each sub-region should be “dynamic”
in the same manner (e.g. rotate around the same point), though this is not a requirement.
The move keyword allows one or more equal-style variables to be used to specify the x,y,z displacement of the region,
typically as a function of time. A variable is specified as v_name, where name is the variable name. Any of the three
variables can be specified as NULL, in which case no displacement is calculated in that dimension.
Note that equal-style variables can specify formulas with various mathematical functions, and include thermo_style
command keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a
region displacement that change as a function of time or spans consecutive runs in a continuous fashion. For the latter,
see the start and stop keywords of the run command and the elaplong keyword of thermo_style custom for details.
For example, these commands would displace a region from its initial position, in the positive x direction, effectively
at a constant velocity:

variable dx equal ramp(0,10)

region 2 sphere 10.0 10.0 0.0 5 move v_dx NULL NULL

Note that the initial displacement is 0.0, though that is not required.
Either of these variables would “wiggle” the region back and forth in the y direction:

variable dy equal swiggle(0,5,100)

variable dysame equal 5*sin(2*PI*elaplong*dt/100)
region 2 sphere 10.0 10.0 0.0 5 move NULL v_dy NULL

The rotate keyword rotates the region around a rotation axis R = (Rx,Ry,Rz) that goes through a point P = (Px,Py,Pz).
The rotation angle is calculated, presumably as a function of time, by a variable specified as v_theta, where theta is
the variable name. The variable should generate its result in radians. The direction of rotation for the region around
the rotation axis is consistent with the right-hand rule: if your right-hand thumb points along R, then your fingers wrap
around the axis in the direction of rotation.
The move and rotate keywords can be used together. In this case, the displacement specified by the move keyword is
applied to the P point of the rotate keyword.

The open keyword can be used (multiple times) to indicate that one or more faces of the region are ignored for
purposes of particle/wall interactions. This keyword is only relevant for regions used by the fix wall/region and fix
wall/gran/region commands. It can be used to create “open” containers where only some of the region faces are walls.

916 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

For example, a funnel can be created with a cone style region that has an open face at the smaller radius for particles
to flow out, or at the larger radius for pouring particles into the cone, or both.
Note that using the open keyword partly overrides the side keyword, since both exterior and interior surfaces of an
open region are tested for particle contacts. The exception to this is a union or intersect region which includes an open
sub-region. In that case the side keyword is still used to define the union/intersect region volume, and the open settings
are only applied to the individual sub-regions that use them.
The indices specified as part of the open keyword have the following meanings:
For style block, indices 1-6 correspond to the xlo, xhi, ylo, yhi, zlo, zhi surfaces of the block. I.e. 1 is the yz plane at x
= xlo, 2 is the yz-plane at x = xhi, 3 is the xz plane at y = ylo, 4 is the xz plane at y = yhi, 5 is the xy plane at z = zlo, 6
is the xy plane at z = zhi). In the second-to-last example above, the region is a box open at both xy planes.
For style prism, values 1-6 have the same mapping as for style block. I.e. in an untilted prism, open indices correspond
to the xlo, xhi, ylo, yhi, zlo, zhi surfaces.
For style cylinder, index 1 corresponds to the flat end cap at the low coordinate along the cylinder axis, index 2 cor-
responds to the high-coordinate flat end cap along the cylinder axis, and index 3 is the curved cylinder surface. For
example, a cylinder region with open 1 open 2 keywords will be open at both ends (e.g. a section of pipe), regardless
of the cylinder orientation.
For style cone, the mapping is the same as for style cylinder. Index 1 is the low-coordinate flat end cap, index 2 is the
high-coordinate flat end cap, and index 3 is the curved cone surface. In the last example above, a cone region is defined
along the z-axis that is open at the zlo value (e.g. for use as a funnel).
For all other styles, the open keyword is ignored. As indicated above, this includes the intersect and union regions,
though their sub-regions can be defined with the open keyword.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
The code using the region (such as a fix or compute) must also be supported by Kokkos or no acceleration will occur.
Currently, only block style regions are supported by Kokkos.
These accelerated styles are part of the Kokkos package. They are only enabled if LAMMPS was built with that
package. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

16.99.4 Restrictions

A prism cannot be of 0.0 thickness in any dimension; use a small z thickness for 2d simulations. For 2d simulations,
the xz and yz parameters must be 0.0.

16.99. region command 917

LAMMPS Documentation, Release stable 29Sep2021

16.99.5 Related commands

lattice, create_atoms, delete_atoms, group

16.99.6 Default

The option defaults are side = in, units = lattice, and no move or rotation.

16.100 replicate command

16.100.1 Syntax

replicate nx ny nz keyword
nx,ny,nz = replication factors in each dimension
• optional keyword = bbox
bbox = only check atoms in replicas that overlap with a processor's sub-domain

16.100.2 Examples

replicate 2 3 2

16.100.3 Description

Replicate the current simulation one or more times in each dimension. For example, replication factors of 2,2,2 will
create a simulation with 8x as many atoms by doubling the simulation domain in each dimension. A replication factor of
1 in a dimension leaves the simulation domain unchanged. When the new simulation box is created it is also partitioned
into a regular 3d grid of rectangular bricks, one per processor, based on the number of processors being used and the
settings of the processors command. The partitioning can later be changed by the balance or fix balance commands.
All properties of the atoms are replicated, including their velocities, which may or may not be desirable. New atom
IDs are assigned to new atoms, as are molecule IDs. Bonds and other topology interactions are created between pairs
of new atoms as well as between old and new atoms. This is done by using the image flag for each atom to “unwrap”
it out of the periodic box before replicating it.
This means that any molecular bond you specify in the original data file that crosses a periodic boundary should be
between two atoms with image flags that differ by 1. This will allow the bond to be unwrapped appropriately.
The optional keyword bbox uses a bounding box to only check atoms in replicas that overlap with a processor’s sub-
domain when assigning atoms to processors. It typically results in a substantial speedup when using the replicate
command on a large number of processors. It does require temporary use of more memory, specifically that each
processor can store all atoms in the entire system before it is replicated.

918 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.100.4 Restrictions

A 2d simulation cannot be replicated in the z dimension.

If a simulation is non-periodic in a dimension, care should be used when replicating it in that dimension, as it may put
atoms nearly on top of each other.

Note: You cannot use the replicate command on a system which has a molecule that spans the box and is bonded to
itself across a periodic boundary, so that the molecule is effectively a loop. A simple example would be a linear polymer
chain that spans the simulation box and bonds back to itself across the periodic boundary. More realistic examples would
be a CNT (meant to be an infinitely long CNT) or a graphene sheet or a bulk periodic crystal where there are explicit
bonds specified between near neighbors. (Note that this only applies to systems that have permanent bonds as specified
in the data file. A CNT that is just atoms modeled with the AIREBO potential has no such permanent bonds, so it can
be replicated.) The reason replication does not work with those systems is that the image flag settings described above
cannot be made consistent. I.e. it is not possible to define images flags so that when every pair of bonded atoms is
unwrapped (using the image flags), they will be close to each other. The only way the replicate command could work
in this scenario is for it to break a bond, insert more atoms, and re-connect the loop for the larger simulation box. But
it is not clever enough to do this. So you will have to construct a larger version of your molecule as a pre-processing
step and input a new data file to LAMMPS.

If the current simulation was read in from a restart file (before a run is performed), there must not be any fix information
stored in the file for individual atoms. Similarly, no fixes can be defined at the time the replicate command is used that
require vectors of atom information to be stored. This is because the replicate command does not know how to replicate
that information for new atoms it creates. To work around this restriction, restart files may be converted into data files
and fixes may be undefined via the unfix command before and redefined after the replicate command.

16.100.5 Related commands

none

16.100.6 Default

none

16.101 rerun command

16.101.1 Syntax

rerun file1 file2 ... keyword args ...

• file1,file2,. . . = dump file(s) to read

• one or more keywords may be appended, keyword dump must appear and be last
keyword = first or last or every or skip or start or stop or post or dump
first args = Nfirst
Nfirst = dump timestep to start on
last args = Nlast
Nlast = dumptimestep to stop on
every args = Nevery

16.101. rerun command 919

LAMMPS Documentation, Release stable 29Sep2021

Nevery = read snapshots matching every this many timesteps

skip args = Nskip
Nskip = read one out of every Nskip snapshots
start args = Nstart
Nstart = timestep on which pseudo run will start
stop args = Nstop
Nstop = timestep to which pseudo run will end
post value = yes or no
dump args = same as read_dump command starting with its field arguments

16.101.2 Examples

rerun dump.file dump x y z vx vy vz

rerun dump1.txt dump2.txt first 10000 every 1000 dump x y z
rerun dump.vels dump x y z vx vy vz box yes format molfile lammpstrj
rerun dump.dcd dump x y z box no format molfile dcd
rerun ../run7/dump.file.gz skip 2 dump x y z box yes
rerun dump.bp dump x y z box no format adios
rerun dump.bp dump x y z vx vy vz format adios timeout 10.0

16.101.3 Description

Perform a pseudo simulation run where atom information is read one snapshot at a time from a dump file(s), and
energies and forces are computed on the shapshot to produce thermodynamic or other output.
This can be useful in the following kinds of scenarios, after an initial simulation produced the dump file:
• Compute the energy and forces of snapshots using a different potential.
• Calculate one or more diagnostic quantities on the snapshots that were not computed in the initial run. These can
also be computed with settings not used in the initial run, e.g. computing an RDF via the compute rdf command
with a longer cutoff than was used initially.
• Calculate the portion of per-atom forces resulting from a subset of the potential. E.g. compute only Coulombic
forces. This can be done by only defining only a Coulombic pair style in the rerun script. Doing this in the
original script would result in different (bad) dynamics.
Conceptually, using the rerun command is like running an input script that has a loop in it (see the next and jump
commands). Each iteration of the loop reads one snapshot from the dump file via the read_dump command, sets the
timestep to the appropriate value, and then invokes a run command for zero timesteps to simply compute energy and
forces, and any other thermodynamic output or diagnostic info you have defined. This computation also invokes any
fixes you have defined that apply constraints to the system, such as fix shake or fix indent.
Note that a simulation box must already be defined before using the rerun command. This can be done by the create_box,
read_data, or read_restart commands.
Also note that reading per-atom information from dump snapshots is limited to the atom coordinates, velocities and
image flags as explained in the read_dump command. Other atom properties, which may be necessary to compute
energies and forces, such as atom charge, or bond topology information for a molecular system, are not read from (or
even contained in) dump files. Thus this auxiliary information should be defined in the usual way, e.g. in a data file
read in by a read_data command, before using the rerun command.
Also note that the frequency of thermodynamic or dump output from the rerun simulation will depend on settings made
in the rerun script, the same as for output from any LAMMPS simulation. See further info below as to what that means
if the timesteps for snapshots read from dump files do not match the specified output frequency.

920 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

If more than one dump file is specified, the dump files are read one after the other in the order specified. It is assumed
that snapshot timesteps will be in ascending order. If a snapshot is encountered that is not in ascending order, it will
skip the snapshot until it reads one that is. This allows skipping of a duplicate snapshot (same timestep), e.g. that
appeared at the end of one file and beginning of the next. However if you specify a series of dump files in an incorrect
order (with respect to the timesteps they contain), you may skip large numbers of snapshots.
Note that the dump files specified as part of the dump keyword can be parallel files, i.e. written as multiple files either
per processor and/or per snapshot. If that is the case they will also be read in parallel which can make the rerun
command operate dramatically faster for large systems. See the page for the read_dump and dump commands which
describe how to read and write parallel dump files.
The first, last, every, skip keywords determine which snapshots are read from the dump file(s). Snapshots are skipped
until they have a timestep >= Nfirst. When a snapshot with a timestep > Nlast is encountered, the rerun command
finishes. Note that the defaults for first and last are to read all snapshots. If the every keyword is set to a value > 0, then
only snapshots with timesteps that are a multiple of Nevery are read (the first snapshot is always read). If Nevery = 0,
then this criterion is ignored, i.e. every snapshot is read that meets the other criteria. If the skip keyword is used, then
after the first snapshot is read, every Nth snapshot is read, where N = Nskip. E.g. if Nskip = 3, then only 1 out of every
3 snapshots is read, assuming the snapshot timestep is also consistent with the other criteria.

Note: Not all dump formats contain the timestep and not all dump readers support reading it. In that case individual
snapshots are assigned consecutive timestep numbers starting at 1.

The start and stop keywords do not affect which snapshots are read from the dump file(s). Rather, they have the same
meaning that they do for the run command. They only need to be defined if (a) you are using a fix command that changes
some value over time, and (b) you want the reference point for elapsed time (from start to stop) to be different than the
first and last settings. See the page for individual fixes to see which ones can be used with the start/stop keywords.
Note that if you define neither of the start/stop or first/last keywords, then LAMMPS treats the pseudo run as going
from 0 to a huge value (effectively infinity). This means that any quantity that a fix scales as a fraction of elapsed time
in the run, will essentially remain at its initial value. Also note that an error will occur if you read a snapshot from the
dump file with a timestep value larger than the stop setting you have specified.
The post keyword can be used to minimize the output to the screen that happens after a rerun command, similar to the
post keyword of the run command. It is set to no by default.
The dump keyword is required and must be the last keyword specified. Its arguments are passed internally to the
read_dump command. The first argument following the dump keyword should be the field1 argument of the read_dump
command. See the read_dump page for details on the various options it allows for extracting information from the dump
file snapshots, and for using that information to alter the LAMMPS simulation.

In general, a LAMMPS input script that uses a rerun command can include and perform all the usual operations of an
input script that uses the run command. There are a few exceptions and points to consider, as discussed here.
Fixes that perform time integration, such as fix nve or fix npt are not invoked, since no time integration is performed.
Fixes that perturb or constrain the forces on atoms will be invoked, just as they would during a normal run. Examples
are fix indent and fix langevin. So you should think carefully as to whether that makes sense for the manner in which
you are reprocessing the dump snapshots.
If you only want the rerun script to perform an analysis that does not involve pair interactions, such as use compute
msd to calculated displacements over time, you do not need to define a pair style, which may also mean neighbor lists
will not need to be calculated which saves time. The comm_modify cutoff command can also be used to insure ghost
atoms are acquired from far enough away for operations like bond and angle evaluations, if no pair style is being used.

16.101. rerun command 921

LAMMPS Documentation, Release stable 29Sep2021

Every time a snapshot is read, the timestep for the simulation is reset, as if the reset_timestep command were used. This
command has some restrictions as to what fixes can be defined. See its page for details. For example, the fix deposit
and fix dt/reset fixes are in this category. They also make no sense to use with a rerun command.
If time-averaging fixes like fix ave/time are used, they are invoked on timesteps that are a function of their Nevery,
Nrepeat, and Nfreq settings. As an example, see the fix ave/time page for details. You must insure those settings are
consistent with the snapshot timestamps that are read from the dump file(s). If an averaging fix is not invoked on a
timestep it expects to be, LAMMPS will flag an error.
The various forms of LAMMPS output, as defined by the thermo_style, thermo, dump, and restart commands occur
with specified frequency, e.g. every N steps. If the timestep for a dump snapshot is not a multiple of N, then it will be
read and processed, but no output will be produced. If you want output for every dump snapshot, you can simply use
N=1 for an output frequency, e.g. for thermodynamic output or new dump file output.

16.101.4 Restrictions

The rerun command is subject to all restrictions of the read_dump command.

16.101.5 Related commands

read_dump

16.101.6 Default

The option defaults are first = 0, last = a huge value (effectively infinity), start = same as first, stop = same as last, every
= 0, skip = 1, post = no;

16.102 reset_atom_ids command

16.102.1 Syntax

reset_atom_ids keyword values ...

* zero or more keyword/value pairs may be appended

* keyword = *sort*

sort value = yes or no

16.102.2 Examples

reset_atom_ids
reset_atom_ids sort yes

922 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.102.3 Description

Reset atom IDs for the system, including all the global IDs stored for bond, angle, dihedral, improper topology data.
This will create a set of IDs that are numbered contiguously from 1 to N for a N atoms system.
This can be useful to do after performing a “delete_atoms” command for a molecular system. The delete_atoms com-
press yes option will not perform this operation due to the existence of bond topology. It can also be useful to do after
any simulation which has lost atoms, e.g. due to atoms moving outside a simulation box with fixed boundaries (see the
“boundary command”), or due to evaporation (see the “fix evaporate” command).
If the sort keyword is used with a setting of yes, then the assignment of new atom IDs will be the same no matter how
many processors LAMMPS is running on. This is done by first doing a spatial sort of all the atoms into bins and sorting
them within each bin. Because the set of bins is independent of the number of processors, this enables a consistent
assignment of new IDs to each atom.
This can be useful to do after using the “create_atoms” command and/or “replicate” command. In general those com-
mands do not guarantee assignment of the same atom ID to the same physical atom when LAMMPS is run on different
numbers of processors. Enforcing consistent IDs can be useful for debugging or comparing output from two different
runs.
Note that the spatial sort requires communication of atom IDs and coordinates between processors in an all-to-all
manner. This is done efficiently in LAMMPS, but it is more expensive than how atom IDs are reset without sorting.
Note that whether sorting or not, the resetting of IDs is not a compression, where gaps in atom IDs are removed by
decrementing atom IDs that are larger. Instead the IDs for all atoms are erased, and new IDs are assigned so that the
atoms owned by an individual processor have consecutive IDs, as the create_atoms command explains.

Note: If this command is used before a pair style is defined, an error about bond topology atom IDs not being found
may result. This is because the cutoff distance for ghost atom communication was not sufficient to find atoms in bonds,
angles, etc that are owned by other processors. The comm_modify cutoff command can be used to correct this issue.
Or you can define a pair style before using this command. If you do the former, you should unset the comm_modify
cutoff after using reset_atom_ids so that subsequent communication is not inefficient.

16.102.4 Restrictions

none

16.102.5 Related commands

delete_atoms

16.102.6 Default

By default, sort is no.

16.102. reset_atom_ids command 923

LAMMPS Documentation, Release stable 29Sep2021

16.103 reset_mol_ids command

16.103.1 Syntax

reset_mol_ids group-ID keyword value ...

• group-ID = ID of group of atoms whose molecule IDs will be reset

• zero or more keyword/value pairs may be appended
• keyword = compress or offset or single
compress value = yes or no
offset value = Noffset >= -1
single value = yes or no to treat single atoms (no bonds) as molecules

16.103.2 Examples

reset_mol_ids all
reset_mol_ids all offset 10 single yes
reset_mol_ids solvent compress yes offset 100
reset_mol_ids solvent compress no

16.103.3 Description

Reset molecule IDs for a group of atoms based on current bond connectivity. This will typically create a new set of
molecule IDs for atoms in the group. Only molecule IDs for atoms in the specified group are reset; molecule IDs for
atoms not in the group are not changed.
For purposes of this operation, molecules are identified by the current bond connectivity in the system, which may or
may not be consistent with the current molecule IDs. A molecule in this context is a set of atoms connected to each
other with explicit bonds. The specific algorithm used is the one of compute fragment/atom Once the molecules are
identified and a new molecule ID computed for each, this command will update the current molecule ID for all atoms in
the group with the new molecule ID. Note that if the group excludes atoms within molecules, one (physical) molecule
may become two or more (logical) molecules. For example if the group excludes atoms in the middle of a linear chain,
then each end of the chain is considered an independent molecule and will be assigned a different molecule ID.
This can be a useful operation to perform after running reactive molecular dynamics run with fix bond/react, fix
bond/create, or fix bond/break, all of which can change molecule topologies. It can also be useful after molecules
have been deleted with the delete_atoms command or after a simulation which has lost molecules, e.g. via the fix
evaporate command.
The compress keyword determines how new molecule IDs are computed. If the setting is yes (the default) and there
are N molecules in the group, the new molecule IDs will be a set of N contiguous values. See the offset keyword for
details on selecting the range of these values. If the setting is no, the molecule ID of every atom in the molecule will
be set to the smallest atom ID of any atom in the molecule.
The single keyword determines whether single atoms (not bonded to another atom) are treated as one-atom molecules
or not, based on the yes or no setting. If the setting is no (the default), their molecule IDs are set to 0. This setting can
be important if the new molecule IDs will be used as input to other commands such as compute chunk/atom molecule
or fix rigid molecule.
The offset keyword is only used if the compress setting is yes. Its default value is Noffset = -1. In that case, if the
specified group is all, then the new compressed molecule IDs will range from 1 to N. If the specified group is not all

924 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

and the largest molecule ID of atoms outside that group is M, then the new compressed molecule IDs will range from
M+1 to M+N, to avoid collision with existing molecule IDs. If an Noffset >= 0 is specified, then the new compressed
molecule IDs will range from Noffset+1 to Noffset+N. If the group is not all there may be collisions with the molecule
IDs of other atoms.

Note: The same as explained for the compute fragment/atom command, molecules are identified using the current
bond topology. This will not account for bonds broken by the bond_style quartic command because it does not perform
a full update of the bond topology data structures within LAMMPS.

16.103.4 Restrictions

none

16.103.5 Related commands

reset_atom_ids, fix bond/react, fix bond/create, fix bond/break, fix evaporate, delete_atoms, compute fragment/atom

16.103.6 Default

The default keyword settings are compress = yes, single = no, and offset = -1.

16.104 reset_timestep command

16.104.1 Syntax

reset_timestep N

• N = timestep number

16.104.2 Examples

reset_timestep 0
reset_timestep 4000000

16.104.3 Description

Set the timestep counter to the specified value. This command normally comes after the timestep has been set by
reading a restart file via the read_restart command, or a previous simulation advanced the timestep.
The read_data and create_box commands set the timestep to 0; the read_restart command sets the timestep to the
value it had when the restart file was written.

16.104. reset_timestep command 925

LAMMPS Documentation, Release stable 29Sep2021

16.104.4 Restrictions

none
This command cannot be used when any fixes are defined that keep track of elapsed time to perform certain kinds of
time-dependent operations. Examples are the fix deposit and fix dt/reset commands. The former adds atoms on specific
timesteps. The latter keeps track of accumulated time.
Various fixes use the current timestep to calculate related quantities. If the timestep is reset, this may produce unex-
pected behavior, but LAMMPS allows the fixes to be defined even if the timestep is reset. For example, commands
which thermostat the system, e.g. fix nvt, allow you to specify a target temperature which ramps from Tstart to Tstop
which may persist over several runs. If you change the timestep, you may induce an instantaneous change in the target
temperature.
Resetting the timestep clears flags for computes that may have calculated some quantity from a previous run. This
means these quantity cannot be accessed by a variable in between runs until a new run is performed. See the variable
command for more details.

16.104.5 Related commands

rerun

16.104.6 Default

none

16.105 restart command

16.105.1 Syntax

restart 0
restart N root keyword value ...
restart N file1 file2 keyword value ...

• N = write a restart file every this many timesteps

• N can be a variable (see below)
• root = filename to which timestep # is appended
• file1,file2 = two full filenames, toggle between them when writing file
• zero or more keyword/value pairs may be appended
• keyword = fileper or nfile
fileper arg = Np
Np = write one file for every this many processors
nfile arg = Nf
Nf = write this many files, one from each of Nf processors

926 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.105.2 Examples

restart 0
restart 1000 poly.restart
restart 1000 poly.restart.mpiio
restart 1000 restart.*.equil
restart 10000 poly.%.1 poly.%.2 nfile 10
restart v_mystep poly.restart

16.105.3 Description

Write out a binary restart file with the current state of the simulation every so many timesteps, in either or both of two
modes, as a run proceeds. A value of 0 means do not write out any restart files. The two modes are as follows. If one
filename is specified, a series of filenames will be created which include the timestep in the filename. If two filenames
are specified, only 2 restart files will be created, with those names. LAMMPS will toggle between the 2 names as it
writes successive restart files.
Note that you can specify the restart command twice, once with a single filename and once with two filenames. This
would allow you, for example, to write out archival restart files every 100000 steps using a single filename, and more
frequent temporary restart files every 1000 steps, using two filenames. Using restart 0 will turn off both modes of
output.
Similar to dump files, the restart filename(s) can contain two wild-card characters.
If a “*” appears in the single filename, it is replaced with the current timestep value. This is only recognized when
a single filename is used (not when toggling back and forth). Thus, the third example above creates restart files as
follows: restart.1000.equil, restart.2000.equil, etc. If a single filename is used with no “*”, then the timestep value is
appended. E.g. the second example above creates restart files as follows: poly.restart.1000, poly.restart.2000, etc.
If a “%” character appears in the restart filename(s), then one file is written for each processor and the “%” character
is replaced with the processor ID from 0 to P-1. An additional file with the “%” replaced by “base” is also writ-
ten, which contains global information. For example, the files written on step 1000 for filename restart.% would be
restart.base.1000, restart.0.1000, restart.1.1000, . . . , restart.P-1.1000. This creates smaller files and can be a fast mode
of output and subsequent input on parallel machines that support parallel I/O. The optional fileper and nfile keywords
discussed below can alter the number of files written.
The restart file can also be written in parallel as one large binary file via the MPI-IO library, which is part of the MPI
standard for versions 2.0 and above. Using MPI-IO requires two steps. First, build LAMMPS with its MPIIO package
installed, e.g.

make yes-mpiio # installs the MPIIO package

make mpi # build LAMMPS for your platform

Second, use a restart filename which contains “.mpiio”. Note that it does not have to end in “.mpiio”, just contain those
characters. Unlike MPI-IO dump files, a particular restart file must be both written and read using MPI-IO.
Restart files are written on timesteps that are a multiple of N but not on the first timestep of a run or minimization. You
can use the write_restart command to write a restart file before a run begins. A restart file is not written on the last
timestep of a run unless it is a multiple of N. A restart file is written on the last timestep of a minimization if N > 0 and
the minimization converges.
Instead of a numeric value, N can be specified as an equal-style variable, which should be specified as v_name, where
name is the variable name. In this case, the variable is evaluated at the beginning of a run to determine the next
timestep at which a restart file will be written out. On that timestep, the variable will be evaluated again to determine
the next timestep, etc. Thus the variable should return timestep values. See the stagger() and logfreq() and stride() math

16.105. restart command 927

LAMMPS Documentation, Release stable 29Sep2021

functions for equal-style variables, as examples of useful functions to use in this context. Other similar math functions
could easily be added as options for equal-style variables.
For example, the following commands will write restart files every step from 1100 to 1200, and could be useful for
debugging a simulation where something goes wrong at step 1163:

variable s equal stride(1100,1200,1)

restart v_s tmp.restart

See the read_restart command for information about what is stored in a restart file.
Restart files can be read by a read_restart command to restart a simulation from a particular state. Because the file is
binary (to enable exact restarts), it may not be readable on another machine. In this case, you can use the -r command-
line switch to convert a restart file to a data file.

Note: Although the purpose of restart files is to enable restarting a simulation from where it left off, not all information
about a simulation is stored in the file. For example, the list of fixes that were specified during the initial run is not
stored, which means the new input script must specify any fixes you want to use. Even when restart information is
stored in the file, as it is for some fixes, commands may need to be re-specified in the new input script, in order to re-use
that information. See the read_restart command for information about what is stored in a restart file.

The optional nfile or fileper keywords can be used in conjunction with the “%” wildcard character in the specified restart
file name(s). As explained above, the “%” character causes the restart file to be written in pieces, one piece for each of
P processors. By default P = the number of processors the simulation is running on. The nfile or fileper keyword can
be used to set P to a smaller value, which can be more efficient when running on a large number of processors.
The nfile keyword sets P to the specified Nf value. For example, if Nf = 4, and the simulation is running on 100
processors, 4 files will be written, by processors 0,25,50,75. Each will collect information from itself and the next 24
processors and write it to a restart file.
For the fileper keyword, the specified value of Np means write one file for every Np processors. For example, if Np =
4, every fourth processor (0,4,8,12,etc) will collect information from itself and the next 3 processors and write it to a
restart file.

16.105.4 Restrictions

To write and read restart files in parallel with MPI-IO, the MPIIO package must be installed.

16.105.5 Related commands

write_restart, read_restart

928 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.105.6 Default

restart 0

16.106 run command

16.106.1 Syntax

run N keyword values ...

• N = # of timesteps
• zero or more keyword/value pairs may be appended
• keyword = upto or start or stop or pre or post or every
upto value = none
start value = N1
N1 = timestep at which 1st run started
stop value = N2
N2 = timestep at which last run will end
pre value = no or yes
post value = no or yes
every values = M c1 c2 ...
M = break the run into M-timestep segments and invoke one or more commands␣
,→between each segment

c1,c2,...,cN = one or more LAMMPS commands, each enclosed in quotes

c1 = NULL means no command will be invoked

16.106.2 Examples

run 10000
run 1000000 upto
run 100 start 0 stop 1000
run 1000 pre no post yes
run 100000 start 0 stop 1000000 every 1000 "print 'Protein Rg = $r'"
run 100000 every 1000 NULL

16.106.3 Description

Run or continue dynamics for a specified number of timesteps.

When the run style is respa, N refers to outer loop (largest) timesteps.
A value of N = 0 is acceptable; only the thermodynamics of the system are computed and printed without taking a
timestep.
The upto keyword means to perform a run starting at the current timestep up to the specified timestep. E.g. if the
current timestep is 10,000 and “run 100000 upto” is used, then an additional 90,000 timesteps will be run. This can be
useful for very long runs on a machine that allocates chunks of time and terminate your job when time is exceeded. If

16.106. run command 929

LAMMPS Documentation, Release stable 29Sep2021

you need to restart your script multiple times (reading in the last restart file), you can keep restarting your script with
the same run command until the simulation finally completes.
The start or stop keywords can be used if multiple runs are being performed and you want a fix command that changes
some value over time (e.g. temperature) to make the change across the entire set of runs and not just a single run. See
the page for individual fixes to see which ones can be used with the start/stop keywords.
For example, consider this fix followed by 10 run commands:

fix 1 all nvt 200.0 300.0 1.0

run 1000 start 0 stop 10000
run 1000 start 0 stop 10000
...
run 1000 start 0 stop 10000

The NVT fix ramps the target temperature from 200.0 to 300.0 during a run. If the run commands did not have the
start/stop keywords (just “run 1000”), then the temperature would ramp from 200.0 to 300.0 during the 1000 steps of
each run. With the start/stop keywords, the ramping takes place over the 10000 steps of all runs together.
The pre and post keywords can be used to streamline the setup, clean-up, and associated output to the screen that
happens before and after a run. This can be useful if you wish to do many short runs in succession (e.g. LAMMPS is
being called as a library which is doing other computations between successive short LAMMPS runs).
By default (pre and post = yes), LAMMPS creates neighbor lists, computes forces, and imposes fix constraints before
every run. And after every run it gathers and prints timings statistics. If a run is just a continuation of a previous run
(i.e. no settings are changed), the initial computation is not necessary; the old neighbor list is still valid as are the forces.
So if pre is specified as “no” then the initial setup is skipped, except for printing thermodynamic info. Note that if pre
is set to “no” for the very first run LAMMPS performs, then it is overridden, since the initial setup computations must
be done.

Note: If your input script changes the system between 2 runs, then the initial setup must be performed to insure the
change is recognized by all parts of the code that are affected. Examples are adding a fix or dump or compute, changing
a neighbor list parameter, or writing restart file which can migrate atoms between processors. LAMMPS has no easy
way to check if this has happened, but it is an error to use the pre no option in this case.

If post is specified as “no”, the full timing summary is skipped; only a one-line summary timing is printed.
The every keyword provides a means of breaking a LAMMPS run into a series of shorter runs. Optionally, one or more
LAMMPS commands (c1, c2, . . . , cN) will be executed in between the short runs. If used, the every keyword must
be the last keyword, since it has a variable number of arguments. Each of the trailing arguments is a single LAMMPS
command, and each command should be enclosed in quotes, so that the entire command will be treated as a single
argument. This will also prevent any variables in the command from being evaluated until it is executed multiple times
during the run. Note that if a command itself needs one of its arguments quoted (e.g. the print command), then you
can use a combination of single and double quotes, as in the example above or below.
The every keyword is a means to avoid listing a long series of runs and interleaving commands in your input script. For
example, a print command could be invoked or a fix could be redefined, e.g. to reset a thermostat temperature. Or this
could be useful for invoking a command you have added to LAMMPS that wraps some other code (e.g. as a library) to
perform a computation periodically during a long LAMMPS run. See the Modify doc page for info about how to add
new commands to LAMMPS. See the Howto couple page for ideas about how to couple LAMMPS to other codes.
With the every option, N total steps are simulated, in shorter runs of M steps each. After each M-length run, the
specified commands are invoked. If only a single command is specified as NULL, then no command is invoked. Thus
these lines:

930 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

variable q equal x[100]

run 6000 every 2000 "print 'Coord = $q'"

are the equivalent of:

variable q equal x[100]

run 2000
print "Coord = $q"
run 2000
print "Coord = $q"
run 2000
print "Coord = $q"

which does 3 runs of 2000 steps and prints the x-coordinate of a particular atom between runs. Note that the variable
“$q” will be evaluated afresh each time the print command is executed.
Note that by using the line continuation character “&”, the run every command can be spread across many lines, though
it is still a single command:

run 100000 every 1000 &

"print 'Minimum value = $a'" &
"print 'Maximum value = $b'" &
"print 'Temp = $c'" &
"print 'Press = $d'"

If the pre and post options are set to “no” when used with the every keyword, then the first run will do the full setup
and the last run will print the full timing summary, but these operations will be skipped for intermediate runs.

Note: You might wish to specify a command that exits the run by jumping out of the loop, e.g.

variable t equal temp

run 10000 every 100 "if '$t < 300.0' then 'jump SELF afterrun'"

However, this will not work. The run command simply executes each command one at a time each time it pauses, then
continues the run.
Instead, you should use the fix halt command, which has additional options for how to exit the run.

16.106.4 Restrictions

When not using the upto keyword, the number of specified timesteps N must fit in a signed 32-bit integer, so you are
limited to slightly more than 2 billion steps (2^31) in a single run. When using upto, N can be larger than a signed
32-bit integer, however the difference between N and the current timestep must still be no larger than 2^31 steps.
However, with or without the upto keyword, you can perform successive runs to run a simulation for any number of
steps (ok, up to 2^63 total steps). I.e. the timestep counter within LAMMPS is a 64-bit signed integer.

16.106. run command 931

LAMMPS Documentation, Release stable 29Sep2021

16.106.5 Related commands

minimize, run_style, temper, fix halt

16.106.6 Default

The option defaults are start = the current timestep, stop = current timestep + N, pre = yes, and post = yes.

16.107 run_style command

16.107.1 Syntax

run_style style args

• style = verlet or verlet/split or respa or respa/omp

verlet args = none
verlet/split args = none
respa args = N n1 n2 ... keyword values ...
N = # of levels of rRESPA
n1, n2, ... = loop factors between rRESPA levels (N-1 values)
zero or more keyword/value pairings may be appended to the loop factors
keyword = bond or angle or dihedral or improper or
pair or inner or middle or outer or hybrid or kspace
bond value = M
M = which level (1-N) to compute bond forces in
angle value = M
M = which level (1-N) to compute angle forces in
dihedral value = M
M = which level (1-N) to compute dihedral forces in
improper value = M
M = which level (1-N) to compute improper forces in
pair value = M
M = which level (1-N) to compute pair forces in
inner values = M cut1 cut2
M = which level (1-N) to compute pair inner forces in
cut1 = inner cutoff between pair inner and
pair middle or outer (distance units)
cut2 = outer cutoff between pair inner and
pair middle or outer (distance units)
middle values = M cut1 cut2
M = which level (1-N) to compute pair middle forces in
cut1 = inner cutoff between pair middle and pair outer (distance units)
cut2 = outer cutoff between pair middle and pair outer (distance units)
outer value = M
M = which level (1-N) to compute pair outer forces in
hybrid values = M1 M2 ... (as many values as there are hybrid sub-styles
M1 = which level (1-N) to compute the first pair_style hybrid sub-style in
M2 = which level (1-N) to compute the second pair_style hybrid sub-style in
M3,etc
kspace value = M

932 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

M = which level (1-N) to compute kspace forces in

16.107.2 Examples

run_style verlet
run_style respa 4 2 2 2 bond 1 dihedral 2 pair 3 kspace 4
run_style respa 4 2 2 2 bond 1 dihedral 2 inner 3 5.0 6.0 outer 4 kspace 4
run_style respa 3 4 2 bond 1 hybrid 2 2 1 kspace 3

16.107.3 Description

Choose the style of time integrator used for molecular dynamics simulations performed by LAMMPS.
The verlet style is a standard velocity-Verlet integrator.

The verlet/split style is also a velocity-Verlet integrator, but it splits the force calculation within each timestep over
2 partitions of processors. See the -partition command-line switch for info on how to run LAMMPS with multiple
partitions.
Specifically, this style performs all computation except the kspace_style portion of the force field on the first parti-
tion. This include the pair style, bond style, neighbor list building, fixes including time integration, and output. The
kspace_style portion of the calculation is performed on the second partition.
This is most useful for the PPPM kspace_style when its performance on a large number of processors degrades due to
the cost of communication in its 3d FFTs. In this scenario, splitting your P total processors into 2 subsets of processors,
P1 in the first partition and P2 in the second partition, can enable your simulation to run faster. This is because the
long-range forces in PPPM can be calculated at the same time as pair-wise and bonded forces are being calculated, and
the FFTs can actually speed up when running on fewer processors.
To use this style, you must define 2 partitions where P1 is a multiple of P2. Typically having P1 be 3x larger than P2 is
a good choice. The 3d processor layouts in each partition must overlay in the following sense. If P1 is a Px1 by Py1 by
Pz1 grid, and P2 = Px2 by Py2 by Pz2, then Px1 must be an integer multiple of Px2, and similarly for Py1 a multiple
of Py2, and Pz1 a multiple of Pz2.
Typically the best way to do this is to let the first partition choose its onn optimal layout, then require the second
partition’s layout to match the integer multiple constraint. See the processors command with its part keyword for a
way to control this, e.g.

processors * * * part 1 2 multiple

You can also use the partition command to explicitly specify the processor layout on each partition. E.g. for 2 partitions
of 60 and 15 processors each:

partition yes 1 processors 3 4 5

partition yes 2 processors 3 1 5

When you run in 2-partition mode with the verlet/split style, the thermodynamic data for the entire simulation will be
output to the log and screen file of the first partition, which are log.lammps.0 and screen.0 by default; see the -plog
and -pscreen command-line switches to change this. The log and screen file for the second partition will not contain
thermodynamic output beyond the first timestep of the run.
See the Speed packages page for performance details of the speed-up offered by the verlet/split style. One important
performance consideration is the assignment of logical processors in the 2 partitions to the physical cores of a parallel
machine. The processors command has options to support this, and strategies are discussed in Section 5 of the manual.

16.107. run_style command 933

LAMMPS Documentation, Release stable 29Sep2021

The respa style implements the rRESPA multi-timescale integrator (Tuckerman) with N hierarchical levels, where
level 1 is the innermost loop (shortest timestep) and level N is the outermost loop (largest timestep). The loop factor
arguments specify what the looping factor is between levels. N1 specifies the number of iterations of level 1 for a single
iteration of level 2, N2 is the iterations of level 2 per iteration of level 3, etc. N-1 looping parameters must be specified.
Thus with a 4-level respa setting of “2 2 2” for the 3 loop factors, you could choose to have bond interactions computed
8x per large timestep, angle interactions computed 4x, pair interactions computed 2x, and long-range interactions once
per large timestep.
The timestep command sets the large timestep for the outermost rRESPA level. Thus if the 3 loop factors are “2 2 2” for
4-level rRESPA, and the outer timestep is set to 4.0 fs, then the inner timestep would be 8x smaller or 0.5 fs. All other
LAMMPS commands that specify number of timesteps (e.g. thermo for thermo output every N steps, neigh_modify
delay/every parameters, dump every N steps, etc) refer to the outermost timesteps.
The rRESPA keywords enable you to specify at what level of the hierarchy various forces will be computed. If not
specified, the defaults are that bond forces are computed at level 1 (innermost loop), angle forces are computed where
bond forces are, dihedral forces are computed where angle forces are, improper forces are computed where dihedral
forces are, pair forces are computed at the outermost level, and kspace forces are computed where pair forces are. The
inner, middle, outer forces have no defaults.
For fixes that support it, the rRESPA level at which a given fix is active, can be selected through the fix_modify command.
The inner and middle keywords take additional arguments for cutoffs that are used by the pairwise force computations.
If the 2 cutoffs for inner are 5.0 and 6.0, this means that all pairs up to 6.0 apart are computed by the inner force. Those
between 5.0 and 6.0 have their force go ramped to 0.0 so the overlap with the next regime (middle or outer) is smooth.
The next regime (middle or outer) will compute forces for all pairs from 5.0 outward, with those from 5.0 to 6.0 having
their value ramped in an inverse manner.
Note that you can use inner and outer without using middle to split the pairwise computations into two portions instead
of three. Unless you are using a very long pairwise cutoff, a 2-way split is often faster than a 3-way split, since it avoids
too much duplicate computation of pairwise interactions near the intermediate cutoffs.
Also note that only a few pair potentials support the use of the inner and middle and outer keywords. If not, only the
pair keyword can be used with that pair style, meaning all pairwise forces are computed at the same rRESPA level. See
the doc pages for individual pair styles for details.
Another option for using pair potentials with rRESPA is with the hybrid keyword, which requires the use of the
pair_style hybrid or hybrid/overlay command. In this scenario, different sub-styles of the hybrid pair style are evaluated
at different rRESPA levels. This can be useful, for example, to set different timesteps for hybrid coarse-grained/all-atom
models. The hybrid keyword requires as many level assignments as there are hybrid sub-styles, which assigns each
sub-style to a rRESPA level, following their order of definition in the pair_style command. Since the hybrid keyword
operates on pair style computations, it is mutually exclusive with either the pair or the inner/middle/outer keywords.
When using rRESPA (or for any MD simulation) care must be taken to choose a timestep size(s) that insures the
Hamiltonian for the chosen ensemble is conserved. For the constant NVE ensemble, total energy must be conserved.
Unfortunately, it is difficult to know a priori how well energy will be conserved, and a fairly long test simulation (~10
ps) is usually necessary in order to verify that no long-term drift in energy occurs with the trial set of parameters.
With that caveat, a few rules-of-thumb may be useful in selecting respa settings. The following applies mostly to
biomolecular simulations using the CHARMM or a similar all-atom force field, but the concepts are adaptable to other
problems. Without SHAKE, bonds involving hydrogen atoms exhibit high-frequency vibrations and require a timestep
on the order of 0.5 fs in order to conserve energy. The relatively inexpensive force computations for the bonds, angles,
impropers, and dihedrals can be computed on this innermost 0.5 fs step. The outermost timestep cannot be greater
than 4.0 fs without risking energy drift. Smooth switching of forces between the levels of the rRESPA hierarchy is also
necessary to avoid drift, and a 1-2 angstrom “healing distance” (the distance between the outer and inner cutoffs) works
reasonably well. We thus recommend the following settings for use of the respa style without SHAKE in biomolecular
simulations:

934 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

timestep 4.0
run_style respa 4 2 2 2 inner 2 4.5 6.0 middle 3 8.0 10.0 outer 4

With these settings, users can expect good energy conservation and roughly a 2.5 fold speedup over the verlet style
with a 0.5 fs timestep.
If SHAKE is used with the respa style, time reversibility is lost, but substantially longer time steps can be achieved.
For biomolecular simulations using the CHARMM or similar all-atom force field, bonds involving hydrogen atoms
exhibit high frequency vibrations and require a time step on the order of 0.5 fs in order to conserve energy. These
high frequency modes also limit the outer time step sizes since the modes are coupled. It is therefore desirable to use
SHAKE with respa in order to freeze out these high frequency motions and increase the size of the time steps in the
respa hierarchy. The following settings can be used for biomolecular simulations with SHAKE and rRESPA:

fix 2 all shake 0.000001 500 0 m 1.0 a 1

timestep 4.0
run_style respa 2 2 inner 1 4.0 5.0 outer 2

With these settings, users can expect good energy conservation and roughly a 1.5 fold speedup over the verlet style
with SHAKE and a 2.0 fs timestep.
For non-biomolecular simulations, the respa style can be advantageous if there is a clear separation of time scales - fast
and slow modes in the simulation. For example, a system of slowly-moving charged polymer chains could be setup as
follows:

timestep 4.0
run_style respa 2 8

This is two-level rRESPA with an 8x difference between the short and long timesteps. The bonds, angles, dihedrals will
be computed every 0.5 fs (assuming real units), while the pair and kspace interactions will be computed once every 4
fs. These are the default settings for each kind of interaction, so no additional keywords are necessary.
Even a LJ system can benefit from rRESPA if the interactions are divided by the inner, middle and outer keywords. A
2-fold or more speedup can be obtained while maintaining good energy conservation. In real units, for a pure LJ fluid
at liquid density, with a sigma of 3.0 angstroms, and epsilon of 0.1 Kcal/mol, the following settings seem to work well:

timestep 36.0
run_style respa 3 3 4 inner 1 3.0 4.0 middle 2 6.0 7.0 outer 3

The respa/omp style is a variant of respa adapted for use with pair, bond, angle, dihedral, improper, or kspace styles
with an omp suffix. It is functionally equivalent to respa but performs additional operations required for managing omp
styles. For more on omp styles see the Speed omp doc page. Accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
You can specify respa/omp explicitly in your input script, or you can use the -suffix command-line switch when you
invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

16.107. run_style command 935

LAMMPS Documentation, Release stable 29Sep2021

16.107.4 Restrictions

The verlet/split style can only be used if LAMMPS was built with the REPLICA package. Correspondingly the
respa/omp style is available only if the OPENMP package was included. See the Build package page for more info.
Whenever using rRESPA, the user should experiment with trade-offs in speed and accuracy for their system, and verify
that they are conserving energy to adequate precision.

16.107.5 Related commands

timestep, run

16.107.6 Default

run_style verlet

For run_style respa, the default assignment of interactions to rRESPA levels is as follows:
• bond forces = level 1 (innermost loop)
• angle forces = same level as bond forces
• dihedral forces = same level as angle forces
• improper forces = same level as dihedral forces
• pair forces = level N (outermost level)
• kspace forces = same level as pair forces
• inner, middle, outer forces = no default

(Tuckerman) Tuckerman, Berne and Martyna, J Chem Phys, 97, p 1990 (1992).

16.108 server command

16.108.1 Syntax

server protocol

• protocol = md or mc

16.108.2 Examples

server md

936 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.108.3 Description

This command starts LAMMPS running in “server” mode, where it receives messages from a separate “client” code
and responds by sending a reply message back to the client. The specified protocol determines the format and content
of messages LAMMPS expects to receive and how it responds.
The Howto client/server page gives an overview of client/server coupling of LAMMPS with another code where one
code is the “client” and sends request messages to a “server” code. The server responds to each request with a reply
message. This enables the two codes to work in tandem to perform a simulation.
When this command is invoked, LAMMPS will run in server mode in an endless loop, waiting for messages from the
client code. The client signals when it is done sending messages to LAMMPS, at which point the loop will exit, and
the remainder of the LAMMPS input script will be processed.
The protocol argument defines the format and content of messages that will be exchanged between the two codes. The
current options are:
• md = run dynamics with another code
• mc = perform Monte Carlo moves with another code
For protocol md, LAMMPS can be either a client (via the fix client/md command) or server. See the server md page
for details on the protocol.
For protocol mc, LAMMPS can be the server. See the server mc page for details on the protocol.

16.108.4 Restrictions

This command is part of the MESSAGE package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.
A script that uses this command must also use the message command to setup the messaging protocol with the other
client code.

16.108.5 Related commands

message, fix client/md

16.108.6 Default

none

16.109 server mc command

16.109.1 Syntax

server mc

mc = the protocol argument to the server command

16.109. server mc command 937

LAMMPS Documentation, Release stable 29Sep2021

16.109.2 Examples

server mc

16.109.3 Description

This command starts LAMMPS running in “server” mode, where it will expect messages from a separate “client” code
that match the mc protocol for format and content explained below. For each message LAMMPS receives it will send
a message back to the client.
The Howto client/server page gives an overview of client/server coupling of LAMMPS with another code where one
code is the “client” and sends request messages to a “server” code. The server responds to each request with a reply
message. This enables the two codes to work in tandem to perform a simulation.
When this command is invoked, LAMMPS will run in server mode in an endless loop, waiting for messages from the
client code. The client signals when it is done sending messages to LAMMPS, at which point the loop will exit, and
the remainder of the LAMMPS script will be processed.
The server page gives other options for using LAMMPS See an example of how this command is used in exam-
ples/COUPLE/lammps_mc/in.server.

When using this command, LAMMPS (as the server code) receives instructions from a Monte Carlo (MC) driver to
displace random atoms, compute the energy before and after displacement, and run dynamics to equilibrate the system.
The MC driver performs the random displacements on random atoms, accepts or rejects the move in an MC sense, and
orchestrates the MD runs.
The format and content of the exchanged messages are explained here in a conceptual sense. Python-style pseudo code
for the library calls to the CSlib is shown, which performs the actual message exchange between the two codes. See the
CSlib website doc pages for more details on the actual library syntax. The “cs” object in this pseudo code is a pointer
to an instance of the CSlib.
See the src/MESSAGE/server_mc.cpp file for details on how LAMMPS uses these messages. See the exam-
ples/COUPLE/lammps_mc/mc.cpp file for an example of how an MC driver code can use these messages.
Define NATOMS=1, EINIT=2, DISPLACE=3, ACCEPT=4, RUN=5.
Client sends one of these kinds of message:

cs->send(NATOMS,0) # msgID = 1 with no fields

cs->send(EINIT,0) # msgID = 2 with no fields

cs->send(DISPLACE,2) # msgID = 3 with 2 fields

cs->pack_int(1,ID) # 1st field = ID of atom to displace
cs->pack(2,3,xnew) # 2nd field = new xyz coords of displaced atom

cs->send(ACCEPT,1) # msgID = 4 with 1 field

cs->pack_int(1,flag) # 1st field = accept/reject flag

cs->send(RUN,1) # msgID = 5 with 1 field

cs->pack_int(1,nsteps) # 1st field = # of timesteps to run MD

Server replies:

938 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

cs->send(NATOMS,1) # msgID = 1 with 1 field

cs->pack_int(1,natoms) # 1st field = number of atoms

cs->send(EINIT,2) # msgID = 2 with 2 fields

cs->pack_double(1,poteng) # 1st field = potential energy of system
cs->pack(2,3*natoms,x) # 2nd field = 3N coords of Natoms

cs->send(DISPLACE,1) # msgID = 3 with 1 field

cs->pack_double(1,poteng) # 1st field = new potential energy of system

cs->send(ACCEPT,0) # msgID = 4 with no fields

cs->send(RUN,0) # msgID = 5 with no fields

16.109.4 Restrictions

This command is part of the MESSAGE package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.
A script that uses this command must also use the message command to setup the messaging protocol with the other
client code.

16.109.5 Related commands

message

16.109.6 Default

none

16.110 server md command

16.110.1 Syntax

server md

md = the protocol argument to the server command

16.110.2 Examples

server md

16.110. server md command 939

LAMMPS Documentation, Release stable 29Sep2021

16.110.3 Description

This command starts LAMMPS running in “server” mode, where it will expect messages from a separate “client” code
that match the md protocol for format and content explained below. For each message LAMMPS receives it will send
a message back to the client.
The Howto client/server page gives an overview of client/server coupling of LAMMPS with another code where one
code is the “client” and sends request messages to a “server” code. The server responds to each request with a reply
message. This enables the two codes to work in tandem to perform a simulation.
When this command is invoked, LAMMPS will run in server mode in an endless loop, waiting for messages from the
client code. The client signals when it is done sending messages to LAMMPS, at which point the loop will exit, and
the remainder of the LAMMPS script will be processed.
The server page gives other options for using LAMMPS in server mode. See an example of how this command is used
in examples/message/in.message.server.

When using this command, LAMMPS (as the server code) receives the current coordinates of all particles from the
client code each timestep, computes their interaction, and returns the energy, forces, and pressure for the interacting
particles to the client code, so it can complete the timestep. This command could also be used with a client code that
performs energy minimization, using the server to compute forces and energy each iteration of its minimizer.
When using the fix client/md command, LAMMPS (as the client code) does the timestepping and receives needed
energy, forces, and pressure values from the server code.
The format and content of the exchanged messages are explained here in a conceptual sense. Python-style pseudo code
for the library calls to the CSlib is shown, which performs the actual message exchange between the two codes. See the
CSlib website doc pages for more details on the actual library syntax. The “cs” object in this pseudo code is a pointer
to an instance of the CSlib.
See the src/MESSAGE/server_md.cpp and src/MESSAGE/fix_client_md.cpp files for details on how
LAMMPS uses these messages. See the examples/COUPLE/lammps_vasp/vasp_wrap.py or exam-
ples/COUPLE/lammps_nwchem/nwchem_wrap.py files for examples of how a quantum code (VASP or NWChem)
can use these messages.
The following pseudo-code uses these values, defined as enums.
Define:

SETUP=1, STEP=2
DIM=1, PERIODICITY=2, ORIGIN=3, BOX=4, NATOMS=5, NTYPES=6, TYPES=7, COORDS=8, UNITS-9,␣
,→CHARGE=10

FORCES=1, ENERGY=2, PRESSURE=3, ERROR=4

Client sends 2 kinds of messages:

# required fields: DIM, PERIODICTY, ORIGIN, BOX, NATOMS, NTYPES, TYPES, COORDS
# optional fields: UNITS, CHARGE

cs->send(SETUP,nfields) # msgID with nfields

cs->pack_int(DIM,dim) # dimension (2,3) of simulation

cs->pack(PERIODICITY,3,xyz) # periodicity flags in 3 dims
cs->pack(ORIGIN,3,origin) # lower-left corner of simulation box
cs->pack(BOX,9,box) # 3 edge vectors of simulation box
cs->pack_int(NATOMS,natoms) # total number of atoms
cs->pack_int(NTYPES,ntypes) # number of atom types

940 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

cs->pack(TYPES,natoms,type) # vector of per-atom types

cs->pack(COORDS,3*natoms,x) # vector of 3N atom coords
cs->pack_string(UNITS,units) # units = "lj", "real", "metal", etc
cs->pack(CHARGE,natoms,q) # vector of per-atom charge

# required fields: COORDS

# optional fields: ORIGIN, BOX

cs->send(STEP,nfields) # msgID with nfields

cs->pack(COORDS,3*natoms,x) # vector of 3N atom coords

cs->pack(ORIGIN,3,origin) # lower-left corner of simulation box
cs->pack(BOX,9,box) # 3 edge vectors of simulation box
Server replies to either kind of message:
# required fields: FORCES, ENERGY, PRESSURE
# optional fields: ERROR

cs->send(msgID,nfields) # msgID with nfields

cs->pack(FORCES,3*Natoms,f) # vector of 3N forces on atoms
cs->pack(ENERGY,1,poteng) # total potential energy of system
cs->pack(PRESSURE,6,press) # global pressure tensor (6-vector)
cs->pack_int(ERROR,flag) # server had an error (e.g. DFT non-convergence)

The units for various quantities that are sent and received iva messages are defined for atomic-scale simulations in the
table below. The client and server codes (including LAMMPS) can use internal units different than these (e.g. real
units in LAMMPS), so long as they convert to these units for messaging.
• COORDS, ORIGIN, BOX = Angstroms
• CHARGE = multiple of electron charge (1.0 is a proton)
• ENERGY = eV
• FORCES = eV/Angstrom
• PRESSURE = bars
Note that these are metal units in LAMMPS.
If you wish to run LAMMPS in another its non-atomic units, e.g. lj units, then the client and server should exchange a
UNITS message as indicated above, and both the client and server should agree on the units for the data they exchange.

16.110.4 Restrictions

This command is part of the MESSAGE package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.

16.110. server md command 941

LAMMPS Documentation, Release stable 29Sep2021

16.110.5 Related commands

message, fix client/md

16.110.6 Default

none

16.111 set command

16.111.1 Syntax

set style ID keyword values ...

• style = atom or type or mol or group or region

• ID = atom ID range or type range or mol ID range or group ID or region ID
• one or more keyword/value pairs may be appended
• keyword = type or type/fraction or type/ratio or type/subset or mol or x or y or z or charge or dipole or
dipole/random or quat or spin or spin/random or quat or quat/random or diameter or shape or length or tri
or theta or theta/random or angmom or omega or mass or density or density/disc or volume or image or bond
or angle or dihedral or improper or sph/e or sph/cv or sph/rho or smd/contact/radius or smd/mass/density or
dpd/theta or edpd/temp or edpd/cv or cc or i_name or d_name or i2_name or d2_name
type value = atom type
value can be an atom-style variable (see below)
type/fraction values = type fraction seed
type = new atom type
fraction = approximate fraction of selected atoms to set to new atom type
seed = random # seed (positive integer)
type/ratio values = type fraction seed
type = new atom type
fraction = exact fraction of selected atoms to set to new atom type
seed = random # seed (positive integer)
type/subset values = type Nsubset seed
type = new atom type
Nsubset = exact number of selected atoms to set to new atom type
seed = random # seed (positive integer)
mol value = molecule ID
value can be an atom-style variable (see below)
x,y,z value = atom coordinate (distance units)
value can be an atom-style variable (see below)
vx,vy,vz value = atom velocity (velocity units)
value can be an atom-style variable (see below)
charge value = atomic charge (charge units)
value can be an atom-style variable (see below)
dipole values = x y z
x,y,z = orientation of dipole moment vector
any of x,y,z can be an atom-style variable (see below)
dipole/random value = seed Dlen
seed = random # seed (positive integer) for dipole moment orientations

942 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Dlen = magnitude of dipole moment (dipole units)

spin values = g x y z
g = magnitude of magnetic spin vector (in Bohr magneton's unit)
x,y,z = orientation of magnetic spin vector
any of x,y,z can be an atom-style variable (see below)
spin/random value = seed Dlen
seed = random # seed (positive integer) for magnetic spin orientations
Dlen = magnitude of magnetic spin vector (in Bohr magneton's unit)
quat values = a b c theta
a,b,c = unit vector to rotate particle around via right-hand rule
theta = rotation angle (degrees)
any of a,b,c,theta can be an atom-style variable (see below)
quat/random value = seed
seed = random # seed (positive integer) for quaternion orientations
diameter value = diameter of spherical particle (distance units)
value can be an atom-style variable (see below)
shape value = Sx Sy Sz
Sx,Sy,Sz = 3 diameters of ellipsoid (distance units)
length value = len
len = length of line segment (distance units)
len can be an atom-style variable (see below)
tri value = side
side = side length of equilateral triangle (distance units)
side can be an atom-style variable (see below)
theta value = angle (degrees)
angle = orientation of line segment with respect to x-axis
angle can be an atom-style variable (see below)
theta/random value = seed
seed = random # seed (positive integer) for line segment orienations
angmom values = Lx Ly Lz
Lx,Ly,Lz = components of angular momentum vector (distance-mass-velocity units)
any of Lx,Ly,Lz can be an atom-style variable (see below)
omega values = Wx Wy Wz
Wx,Wy,Wz = components of angular velocity vector (radians/time units)
any of wx,wy,wz can be an atom-style variable (see below)
mass value = per-atom mass (mass units)
value can be an atom-style variable (see below)
density value = particle density for a sphere or ellipsoid (mass/distance^3 units),␣
,→or for a triangle (mass/distance^2 units) or line (mass/distance units) particle

value can be an atom-style variable (see below)

density/disc value = particle density for a 2d disc or ellipse (mass/distance^2␣
,→units)

value can be an atom-style variable (see below)

volume value = particle volume for Peridynamic particle (distance^3 units)
value can be an atom-style variable (see below)
image nx ny nz
nx,ny,nz = which periodic image of the simulation box the atom is in
any of nx,ny,nz can be an atom-style variable (see below)
bond value = bond type for all bonds between selected atoms
angle value = angle type for all angles between selected atoms
dihedral value = dihedral type for all dihedrals between selected atoms
improper value = improper type for all impropers between selected atoms
sph/e value = energy of SPH particles (need units)
value can be an atom-style variable (see below)

16.111. set command 943

LAMMPS Documentation, Release stable 29Sep2021

sph/cv value = heat capacity of SPH particles (need units)

value can be an atom-style variable (see below)
sph/rho value = density of SPH particles (need units)
value can be an atom-style variable (see below)
smd/contact/radius = radius for short range interactions, i.e. contact and friction
value can be an atom-style variable (see below)
smd/mass/density = set particle mass based on volume by providing a mass density
value can be an atom-style variable (see below)
dpd/theta value = internal temperature of DPD particles (temperature units)
value can be an atom-style variable (see below)
value can be NULL which sets internal temp of each particle to KE temp
edpd/temp value = temperature of eDPD particles (temperature units)
value can be an atom-style variable (see below)
edpd/cv value = volumetric heat capacity of eDPD particles (energy/temperature/
,→volume units)

value can be an atom-style variable (see below)

cc values = index cc
index = index of a chemical species (1 to Nspecies)
cc = chemical concentration of tDPD particles for a species (mole/volume units)
i_name value = custom integer vector with name
d_name value = custom floating-point vector with name
i2_name value = column of a custom integer array with name
column specified as i2_name[N] where N is 1 to Ncol
d2_name value = column of a custom floating-point array with name
column specified as d2_name[N] where N is 1 to Ncol

16.111.2 Examples

set group solvent type 2

set group solvent type/fraction 2 0.5 12393
set group edge bond 4
set region half charge 0.5
set type 3 charge 0.5
set type 1*3 charge 0.5
set atom * charge v_atomfile
set atom 100*200 x 0.5 y 1.0
set atom 100 vx 0.0 vy 0.0 vz -1.0
set atom 1492 type 3
set atom * i_myVal 5
set atom * d2_Sxyz[1] 6.4

16.111.3 Description

Set one or more properties of one or more atoms. Since atom properties are initially assigned by the read_data,
read_restart or create_atoms commands, this command changes those assignments. This can be useful for overriding
the default values assigned by the create_atoms command (e.g. charge = 0.0). It can be useful for altering pairwise and
molecular force interactions, since force-field coefficients are defined in terms of types. It can be used to change the
labeling of atoms by atom type or molecule ID when they are output in dump files. It can also be useful for debugging
purposes; i.e. positioning an atom at a precise location to compute subsequent forces or energy.
Note that the style and ID arguments determine which atoms have their properties reset. The remaining keywords
specify which properties to reset and what the new values are. Some strings like type or mol can be used as a style

944 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

and/or a keyword.

This section describes how to select which atoms to change the properties of, via the style and ID arguments.
The style atom selects all the atoms in a range of atom IDs. The style type selects all the atoms in a range of types. The
style mol selects all the atoms in a range of molecule IDs.
In each of the range cases, the range can be specified as a single numeric value, or a wildcard asterisk can be used to
specify a range of values. This takes the form “*” or “*n” or “n*” or “m*n”. For example, for the style type, if N = the
number of atom types, then an asterisk with no numeric values means all types from 1 to N. A leading asterisk means
all types from 1 to n (inclusive). A trailing asterisk means all types from n to N (inclusive). A middle asterisk means
all types from m to n (inclusive). For all the styles except mol, the lowest value for the wildcard is 1; for mol it is 0.
The style group selects all the atoms in the specified group. The style region selects all the atoms in the specified
geometric region. See the group and region commands for details of how to specify a group or region.

This section describes the keyword options for which properties to change, for the selected atoms.
Note that except where explicitly prohibited below, all of the keywords allow an atom-style or atomfile-style variable to
be used as the specified value(s). If the value is a variable, it should be specified as v_name, where name is the variable
name. In this case, the variable will be evaluated, and its resulting per-atom value used to determine the value assigned
to each selected atom. Note that the per-atom value from the variable will be ignored for atoms that are not selected via
the style and ID settings explained above. A simple way to use per-atom values from the variable to reset a property
for all atoms is to use style atom with ID = “*”; this selects all atom IDs.
Atom-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. They can also include per-atom values,
such as atom coordinates. Thus it is easy to specify a time-dependent or spatially-dependent set of per-atom values.
As explained on the variable doc page, atomfile-style variables can be used in place of atom-style variables, and thus
as arguments to the set command. Atomfile-style variables read their per-atoms values from a file.

Note: Atom-style and atomfile-style variables return floating point per-atom values. If the values are assigned to an
integer variable, such as the molecule ID, then the floating point value is truncated to its integer portion, e.g. a value
of 2.6 would become 2.

Keyword type sets the atom type for all selected atoms. The specified value must be from 1 to ntypes, where ntypes was
set by the create_box command or the atom types field in the header of the data file read by the read_data command.
Keyword type/fraction sets the atom type for a fraction of the selected atoms. The actual number of atoms changed
is not guaranteed to be exactly the specified fraction (0 <= fraction <= 1), but should be statistically close. Random
numbers are used in such a way that a particular atom is changed or not changed, regardless of how many processors
are being used. This keyword does not allow use of an atom-style variable.
Keywords type/ratio and type/subset also set the atom type for a fraction of the selected atoms. The actual number
of atoms changed will be exactly the requested number. For type/ratio the specified fraction (0 <= fraction <= 1)
determines the number. For type/subset, the specified Nsubset is the number. An iterative algorithm is used which
insures the correct number of atoms are selected, in a perfectly random fashion. Which atoms are selected will change
with the number of processors used. These keywords do not allow use of an atom-style variable.
Keyword mol sets the molecule ID for all selected atoms. The atom style being used must support the use of molecule
IDs.
Keywords x, y, z, and charge set the coordinates or charge of all selected atoms. For charge, the atom style being used
must support the use of atomic charge. Keywords vx, vy, and vz set the velocities of all selected atoms.

16.111. set command 945

LAMMPS Documentation, Release stable 29Sep2021

Keyword dipole uses the specified x,y,z values as components of a vector to set as the orientation of the dipole moment
vectors of the selected atoms. The magnitude of the dipole moment is set by the length of this orientation vector.
Keyword dipole/random randomizes the orientation of the dipole moment vectors for the selected atoms and sets the
magnitude of each to the specified Dlen value. For 2d systems, the z component of the orientation is set to 0.0. Random
numbers are used in such a way that the orientation of a particular atom is the same, regardless of how many processors
are being used. This keyword does not allow use of an atom-style variable.
Keyword spin uses the specified g value to set the magnitude of the magnetic spin vectors, and the x,y,z values as
components of a vector to set as the orientation of the magnetic spin vectors of the selected atoms.
Keyword spin/random randomizes the orientation of the magnetic spin vectors for the selected atoms and sets the
magnitude of each to the specified Dlen value.
Keyword quat uses the specified values to create a quaternion (4-vector) that represents the orientation of the selected
atoms. The particles must define a quaternion for their orientation (e.g. ellipsoids, triangles, body particles) as defined
by the atom_style command. Note that particles defined by atom_style ellipsoid have 3 shape parameters. The 3 values
must be non-zero for each particle set by this command. They are used to specify the aspect ratios of an ellipsoidal
particle, which is oriented by default with its x-axis along the simulation box’s x-axis, and similarly for y and z. If
this body is rotated (via the right-hand rule) by an angle theta around a unit rotation vector (a,b,c), then the quaternion
that represents its new orientation is given by (cos(theta/2), a*sin(theta/2), b*sin(theta/2), c*sin(theta/2)). The theta
and a,b,c values are the arguments to the quat keyword. LAMMPS normalizes the quaternion in case (a,b,c) was not
specified as a unit vector. For 2d systems, the a,b,c values are ignored, since a rotation vector of (0,0,1) is the only valid
choice.
Keyword quat/random randomizes the orientation of the quaternion for the selected atoms. The particles must define
a quaternion for their orientation (e.g. ellipsoids, triangles, body particles) as defined by the atom_style command.
Random numbers are used in such a way that the orientation of a particular atom is the same, regardless of how many
processors are being used. For 2d systems, only orientations in the xy plane are generated. As with keyword quat, for
ellipsoidal particles, the 3 shape values must be non-zero for each particle set by this command. This keyword does
not allow use of an atom-style variable.
Keyword diameter sets the size of the selected atoms. The particles must be finite-size spheres as defined by the
atom_style sphere command. The diameter of a particle can be set to 0.0, which means they will be treated as point
particles. Note that this command does not adjust the particle mass, even if it was defined with a density, e.g. via the
read_data command.
Keyword shape sets the size and shape of the selected atoms. The particles must be ellipsoids as defined by the
atom_style ellipsoid command. The Sx, Sy, Sz settings are the 3 diameters of the ellipsoid in each direction. All 3 can
be set to the same value, which means the ellipsoid is effectively a sphere. They can also all be set to 0.0 which means
the particle will be treated as a point particle. Note that this command does not adjust the particle mass, even if it was
defined with a density, e.g. via the read_data command.
Keyword length sets the length of selected atoms. The particles must be line segments as defined by the atom_style
line command. If the specified value is non-zero the line segment is (re)set to a length = the specified value, centered
around the particle position, with an orientation along the x-axis. If the specified value is 0.0, the particle will become
a point particle. Note that this command does not adjust the particle mass, even if it was defined with a density, e.g.
via the read_data command.
Keyword tri sets the size of selected atoms. The particles must be triangles as defined by the atom_style tri command.
If the specified value is non-zero the triangle is (re)set to be an equilateral triangle in the xy plane with side length =
the specified value, with a centroid at the particle position, with its base parallel to the x axis, and the y-axis running
from the center of the base to the top point of the triangle. If the specified value is 0.0, the particle will become a point
particle. Note that this command does not adjust the particle mass, even if it was defined with a density, e.g. via the
read_data command.
Keyword theta sets the orientation of selected atoms. The particles must be line segments as defined by the atom_style
line command. The specified value is used to set the orientation angle of the line segments with respect to the x axis.

946 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Keyword theta/random randomizes the orientation of theta for the selected atoms. The particles must be line segments
as defined by the atom_style line command. Random numbers are used in such a way that the orientation of a particular
atom is the same, regardless of how many processors are being used. This keyword does not allow use of an atom-style
variable.
Keyword angmom sets the angular momentum of selected atoms. The particles must be ellipsoids as defined by the
atom_style ellipsoid command or triangles as defined by the atom_style tri command. The angular momentum vector
of the particles is set to the 3 specified components.
Keyword omega sets the angular velocity of selected atoms. The particles must be spheres as defined by the atom_style
sphere command. The angular velocity vector of the particles is set to the 3 specified components.
Keyword mass sets the mass of all selected particles. The particles must have a per-atom mass attribute, as defined by
the atom_style command. See the “mass” command for how to set mass values on a per-type basis.
Keyword density or density/disc also sets the mass of all selected particles, but in a different way. The particles must
have a per-atom mass attribute, as defined by the atom_style command. If the atom has a radius attribute (see atom_style
sphere) and its radius is non-zero, its mass is set from the density and particle volume for 3d systems (the input density
is assumed to be in mass/distance^3 units). For 2d, the default is for LAMMPS to model particles with a radius attribute
as spheres. However, if the density/disc keyword is used, then they can be modeled as 2d discs (circles). Their mass is
set from the density and particle area (the input density is assumed to be in mass/distance^2 units).
If the atom has a shape attribute (see atom_style ellipsoid) and its 3 shape parameters are non-zero, then its mass is set
from the density and particle volume (the input density is assumed to be in mass/distance^3 units). The density/disc
keyword has no effect; it does not (yet) treat 3d ellipsoids as 2d ellipses.
If the atom has a length attribute (see atom_style line) and its length is non-zero, then its mass is set from the density
and line segment length (the input density is assumed to be in mass/distance units). If the atom has an area attribute
(see atom_style tri) and its area is non-zero, then its mass is set from the density and triangle area (the input density is
assumed to be in mass/distance^2 units).
If none of these cases are valid, then the mass is set to the density value directly (the input density is assumed to be in
mass units).
Keyword volume sets the volume of all selected particles. Currently, only the atom_style peri command defines particles
with a volume attribute. Note that this command does not adjust the particle mass.
Keyword image sets which image of the simulation box the atom is considered to be in. An image of 0 means it is inside
the box as defined. A value of 2 means add 2 box lengths to get the true value. A value of -1 means subtract 1 box length
to get the true value. LAMMPS updates these flags as atoms cross periodic boundaries during the simulation. The
flags can be output with atom snapshots via the dump command. If a value of NULL is specified for any of nx,ny,nz,
then the current image value for that dimension is unchanged. For non-periodic dimensions only a value of 0 can be
specified. This command can be useful after a system has been equilibrated and atoms have diffused one or more box
lengths in various directions. This command can then reset the image values for atoms so that they are effectively inside
the simulation box, e.g if a diffusion coefficient is about to be measured via the compute msd command. Care should
be taken not to reset the image flags of two atoms in a bond to the same value if the bond straddles a periodic boundary
(rather they should be different by +/- 1). This will not affect the dynamics of a simulation, but may mess up analysis
of the trajectories if a LAMMPS diagnostic or your own analysis relies on the image flags to unwrap a molecule which
straddles the periodic box.
Keywords bond, angle, dihedral, and improper, set the bond type (angle type, etc) of all bonds (angles, etc) of selected
atoms to the specified value from 1 to nbondtypes (nangletypes, etc). All atoms in a particular bond (angle, etc) must
be selected atoms in order for the change to be made. The value of nbondtype (nangletypes, etc) was set by the bond
types (angle types, etc) field in the header of the data file read by the read_data command. These keywords do not
allow use of an atom-style variable.
Keywords sph/e, sph/cv, and sph/rho set the energy, heat capacity, and density of smoothed particle hydrodynamics
(SPH) particles. See this PDF guide to using SPH in LAMMPS.

16.111. set command 947

LAMMPS Documentation, Release stable 29Sep2021

Keyword smd/mass/density sets the mass of all selected particles, but it is only applicable to the Smooth Mach Dynamics
package MACHDYN. It assumes that the particle volume has already been correctly set and calculates particle mass
from the provided mass density value.
Keyword smd/contact/radius only applies to simulations with the Smooth Mach Dynamics package MACHDYN. Itsets
an interaction radius for computing short-range interactions, e.g. repulsive forces to prevent different individual physical
bodies from penetrating each other. Note that the SPH smoothing kernel diameter used for computing long range,
nonlocal interactions, is set using the diameter keyword.
Keyword dpd/theta sets the internal temperature of a DPD particle as defined by the DPD-REACT package. If the
specified value is a number it must be >= 0.0. If the specified value is NULL, then the kinetic temperature Tkin of
each particle is computed as 3/2 k Tkin = KE = 1/2 m v^2 = 1/2 m (vx*vx+vy*vy+vz*vz). Each particle’s internal
temperature is set to Tkin. If the specified value is an atom-style variable, then the variable is evaluated for each particle.
If a value >= 0.0, the internal temperature is set to that value. If it is < 0.0, the computation of Tkin is performed and
the internal temperature is set to that value.
Keywords edpd/temp and edpd/cv set the temperature and volumetric heat capacity of an eDPD particle as defined by
the DPD-MESO package. Currently, only atom_style edpd defines particles with these attributes. The values for the
temperature and heat capacity must be positive.
Keyword cc sets the chemical concentration of a tDPD particle for a specified species as defined by the DPD-MESO
package. Currently, only atom_style tdpd defines particles with this attribute. An integer for “index” selects a chemical
species (1 to Nspecies) where Nspecies is set by the atom_style command. The value for the chemical concentration
must be >= 0.0.
Keywords i_name, d_name, i2_name, d2_name refer to custom per-atom integer and floating-point vectors or arrays
that have been added via the fix property/atom command. When that command is used specific names are given to each
attribute which are the “name” portion of these keywords. For arrays i2_name and d2_name, the column of the array
must also be included following the name in brackets: e.g. d2_xyz[2], i2_mySpin[3].

16.111.4 Restrictions

You cannot set an atom attribute (e.g. mol or q or volume) if the atom_style does not have that attribute.
This command requires inter-processor communication to coordinate the setting of bond types (angle types, etc). This
means that your system must be ready to perform a simulation before using one of these keywords (force fields set,
atom mass set, etc). This is not necessary for other keywords.
Using the region style with the bond (angle, etc) keywords can give unpredictable results if there are bonds (angles, etc)
that straddle periodic boundaries. This is because the region may only extend up to the boundary and partner atoms in
the bond (angle, etc) may have coordinates outside the simulation box if they are ghost atoms.

16.111.5 Related commands

create_box, create_atoms, read_data

948 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.111.6 Default

none

16.112 shell command

16.112.1 Syntax

shell command args

• command = cd or mkdir or mv or rm or rmdir or putenv or arbitrary command

cd arg = dir
dir = directory to change to
mkdir args = dir1 dir2 ...
dir1,dir2 = one or more directories to create
mv args = old new
old = old filename
new = new filename
rm args = file1 file2 ...
file1,file2 = one or more filenames to delete
rmdir args = dir1 dir2 ...
dir1,dir2 = one or more directories to delete
putenv args = var1=value1 var2=value2
var=value = one of more definitions of environment variables
anything else is passed as a command to the shell for direct execution

16.112.2 Examples

shell cd sub1
shell cd ..
shell mkdir tmp1 tmp2 tmp3
shell rmdir tmp1
shell mv log.lammps hold/log.1
shell rm TMP/file1 TMP/file2
shell putenv LAMMPS_POTENTIALS=../../potentials
shell my_setup file1 10 file2
shell my_post_process 100 dump.out

16.112.3 Description

Execute a shell command. A few simple file-based shell commands are supported directly, in Unix-style syntax. Any
command not listed above is passed as-is to the C-library system() call, which invokes the command in a shell.
This is means to invoke other commands from your input script. For example, you can move files around in preparation
for the next section of the input script. Or you can run a program that pre-processes data for input into LAMMPS. Or
you can run a program that post-processes LAMMPS output data.
With the exception of cd, all commands, including ones invoked via a system() call, are executed by only a single
processor, so that files/directories are not being manipulated by multiple processors.

16.112. shell command 949

LAMMPS Documentation, Release stable 29Sep2021

The cd command executes the Unix “cd” command to change the working directory. All subsequent LAMMPS com-
mands that read/write files will use the new directory. All processors execute this command.
The mkdir command executes the Unix “mkdir” command to create one or more directories.
The mv command executes the Unix “mv” command to rename a file and/or move it to a new directory.
The rm command executes the Unix “rm” command to remove one or more files.
The rmdir command executes the Unix “rmdir” command to remove one or more directories. A directory must be
empty to be successfully removed.
The putenv command defines or updates an environment variable directly. Since this command does not pass through
the shell, no shell variable expansion or globbing is performed, only the usual substitution for LAMMPS variables
defined with the variable command is performed. The resulting string is then used literally.
Any other command is passed as-is to the shell along with its arguments as one string, invoked by the C-library system()
call. For example, these lines in your input script:

variable n equal 10
variable foo string file2
shell my_setup file1 $n ${foo}

would be the same as invoking

% my_setup file1 10 file2

from a command-line prompt. The executable program “my_setup” is run with 3 arguments: file1 10 file2.

16.112.4 Restrictions

LAMMPS does not detect errors or print warnings when any of these commands execute. E.g. if the specified directory
does not exist, executing the cd command will silently do nothing.

16.112.5 Related commands

none

16.112.6 Default

none

16.113 special_bonds command

16.113.1 Syntax

special_bonds keyword values ...

• one or more keyword/value pairs may be appended

• keyword = amber or charmm or dreiding or fene or lj/coul or lj or coul or angle or dihedral

950 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

amber values = none

charmm values = none
dreiding values = none
fene values = none
lj/coul values = w1,w2,w3
w1,w2,w3 = weights (0.0 to 1.0) on pairwise Lennard-Jones and Coulombic␣
,→interactions

lj values = w1,w2,w3
w1,w2,w3 = weights (0.0 to 1.0) on pairwise Lennard-Jones interactions
coul values = w1,w2,w3
w1,w2,w3 = weights (0.0 to 1.0) on pairwise Coulombic interactions
angle value = yes or no
dihedral value = yes or no

16.113.2 Examples

special_bonds amber
special_bonds charmm
special_bonds fene dihedral no
special_bonds lj/coul 0.0 0.0 0.5 angle yes dihedral yes
special_bonds lj 0.0 0.0 0.5 coul 0.0 0.0 0.0 dihedral yes

16.113.3 Description

Set weighting coefficients for pairwise energy and force contributions between pairs of atoms that are also permanently
bonded to each other, either directly or via one or two intermediate bonds. These weighting factors are used by nearly
all pair styles in LAMMPS that compute simple pairwise interactions. Permanent bonds between atoms are specified
by defining the bond topology in the data file read by the read_data command. Typically a bond_style command is
also used to define a bond potential. The rationale for using these weighting factors is that the interaction between
a pair of bonded atoms is all (or mostly) specified by the bond, angle, dihedral potentials, and thus the non-bonded
Lennard-Jones or Coulombic interaction between the pair of atoms should be excluded (or reduced by a weighting
factor).

Note: These weighting factors are NOT used by pair styles that compute many-body interactions, since the “bonds” that
result from such interactions are not permanent, but are created and broken dynamically as atom conformations change.
Examples of pair styles in this category are EAM, MEAM, Stillinger-Weber, Tersoff, COMB, AIREBO, and ReaxFF. In
fact, it generally makes no sense to define permanent bonds between atoms that interact via these potentials, though such
bonds may exist elsewhere in your system, e.g. when using the pair_style hybrid command. Thus LAMMPS ignores
special_bonds settings when many-body potentials are calculated. Please note, that the existence of explicit bonds for
atoms that are described by a many-body potential will alter the neighbor list and thus can render the computation of
those interactions invalid, since those pairs are not only used to determine direct pairwise interactions but also neighbors
of neighbors and more. The recommended course of action is to remove such bonds, or - if that is not possible - use a
special bonds setting of 1.0 1.0 1.0.

Note: Unlike some commands in LAMMPS, you cannot use this command multiple times in an incremental fashion:
e.g. to first set the LJ settings and then the Coulombic ones. Each time you use this command it sets all the coefficients
to default values and only overrides the one you specify, so you should set all the options you need each time you use
it. See more details at the bottom of this page.

16.113. special_bonds command 951

LAMMPS Documentation, Release stable 29Sep2021

The Coulomb factors are applied to any Coulomb (charge interaction) term that the potential calculates. The LJ factors
are applied to the remaining terms that the potential calculates, whether they represent LJ interactions or not. The
weighting factors are a scaling pre-factor on the energy and force between the pair of atoms. A value of 1.0 means
include the full interaction; a value of 0.0 means exclude it completely.
The first of the 3 coefficients (LJ or Coulombic) is the weighting factor on 1-2 atom pairs, which are pairs of atoms
directly bonded to each other. The second coefficient is the weighting factor on 1-3 atom pairs which are those separated
by 2 bonds (e.g. the two H atoms in a water molecule). The third coefficient is the weighting factor on 1-4 atom pairs
which are those separated by 3 bonds (e.g. the first and fourth atoms in a dihedral interaction). Thus if the 1-2 coefficient
is set to 0.0, then the pairwise interaction is effectively turned off for all pairs of atoms bonded to each other. If it is set
to 1.0, then that interaction will be at full strength.

Note: For purposes of computing weighted pairwise interactions, 1-3 and 1-4 interactions are not defined from the list
of angles or dihedrals used by the simulation. Rather, they are inferred topologically from the set of bonds specified
when the simulation is defined from a data or restart file (see read_data or read_restart commands). Thus the set of
1-2,1-3,1-4 interactions that the weights apply to is the same whether angle and dihedral potentials are computed or
not, and remains the same even if bonds are constrained, or turned off, or removed during a simulation.

The two exceptions to this rule are (a) if the angle or dihedral keywords are set to yes (see below), or (b) if the
delete_bonds command is used with the special option that re-computes the 1-2,1-3,1-4 topologies after bonds are
deleted; see the delete_bonds command for more details.
The amber keyword sets the 3 coefficients to 0.0, 0.0, 0.5 for LJ interactions and to 0.0, 0.0, 0.8333 for Coulombic
interactions, which is the default for a commonly used version of the AMBER force field, where the last value is really
5/6. See (Cornell) for a description of the AMBER force field.
The charmm keyword sets the 3 coefficients to 0.0, 0.0, 0.0 for both LJ and Coulombic interactions, which is the
default for a commonly used version of the CHARMM force field. Note that in pair styles lj/charmm/coul/charmm and
lj/charmm/coul/long the 1-4 coefficients are defined explicitly, and these pairwise contributions are computed as part
of the charmm dihedral style - see the pair_coeff and dihedral_style commands for more information. See (MacKerell)
for a description of the CHARMM force field.
The dreiding keyword sets the 3 coefficients to 0.0, 0.0, 1.0 for both LJ and Coulombic interactions, which is the default
for the Dreiding force field, as discussed in (Mayo).
The fene keyword sets the 3 coefficients to 0.0, 1.0, 1.0 for both LJ and Coulombic interactions, which is consistent
with a coarse-grained polymer model with FENE bonds. See (Kremer) for a description of FENE bonds.
The lj/coul, lj, and coul keywords allow the 3 coefficients to be set explicitly. The lj/coul keyword sets both the LJ and
Coulombic coefficients to the same 3 values. The lj and coul keywords only set either the LJ or Coulombic coefficients.
Use both of them if you wish to set the LJ coefficients to different values than the Coulombic coefficients.
The angle keyword allows the 1-3 weighting factor to be ignored for individual atom pairs if they are not listed as the
first and last atoms in any angle defined in the simulation or as 1,3 or 2,4 atoms in any dihedral defined in the simulation.
For example, imagine the 1-3 weighting factor is set to 0.5 and you have a linear molecule with 4 atoms and bonds
as follows: 1-2-3-4. If your data file defines 1-2-3 as an angle, but does not define 2-3-4 as an angle or 1-2-3-4 as a
dihedral, then the pairwise interaction between atoms 1 and 3 will always be weighted by 0.5, but different force fields
use different rules for weighting the pairwise interaction between atoms 2 and 4. If the angle keyword is specified as
yes, then the pairwise interaction between atoms 2 and 4 will be unaffected (full weighting of 1.0). If the angle keyword
is specified as no which is the default, then the 2,4 interaction will also be weighted by 0.5.
The dihedral keyword allows the 1-4 weighting factor to be ignored for individual atom pairs if they are not listed as
the first and last atoms in any dihedral defined in the simulation. For example, imagine the 1-4 weighting factor is set to
0.5 and you have a linear molecule with 5 atoms and bonds as follows: 1-2-3-4-5. If your data file defines 1-2-3-4 as a
dihedral, but does not define 2-3-4-5 as a dihedral, then the pairwise interaction between atoms 1 and 4 will always be
weighted by 0.5, but different force fields use different rules for weighting the pairwise interaction between atoms 2 and
5. If the dihedral keyword is specified as yes, then the pairwise interaction between atoms 2 and 5 will be unaffected

952 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

(full weighting of 1.0). If the dihedral keyword is specified as no which is the default, then the 2,5 interaction will also
be weighted by 0.5.

Note: LAMMPS stores and maintains a data structure with a list of the first, second, and third neighbors of each atom
(within the bond topology of the system). If new bonds are created (or molecules added containing atoms with more
special neighbors), the size of this list needs to grow. Note that adding a single bond always adds a new first neighbor
but may also induce *many* new second and third neighbors, depending on the molecular topology of your system.
Using the extra/special/per/atom keyword to either read_data or create_box reserves empty space in the list for this
N additional first, second, or third neighbors to be added. If you do not do this, you may get an error when bonds (or
molecules) are added.

Note: If you reuse this command in an input script, you should set all the options you need each time. This command
cannot be used a second time incrementally. E.g. these two commands:

special_bonds lj 0.0 1.0 1.0

special_bonds coul 0.0 0.0 1.0

are not the same as

special_bonds lj 0.0 1.0 1.0 coul 0.0 0.0 1.0

In the first case you end up with (after the second command):

LJ: 0.0 0.0 0.0

Coul: 0.0 0.0 1.0

while only in the second case, you get the desired settings of:

LJ: 0.0 1.0 1.0

Coul: 0.0 0.0 1.0

This happens because the LJ (and Coul) settings are reset to their default values before modifying them, each time the
special_bonds command is issued.

16.113.4 Restrictions

none

16.113.5 Related commands

delete_bonds, fix bond/create

16.113. special_bonds command 953

LAMMPS Documentation, Release stable 29Sep2021

16.113.6 Default

All 3 Lennard-Jones and 3 Coulombic weighting coefficients = 0.0, angle = no, dihedral = no.

(Cornell) Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197
(1995).
(Kremer) Kremer, Grest, J Chem Phys, 92, 5057 (1990).
(MacKerell) MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al, J Phys Chem,
102, 3586 (1998).
(Mayo) Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909 (1990).

16.114 suffix command

16.114.1 Syntax

suffix style args

• style = off or on or gpu or intel or kk or omp or opt or hybrid

• args = for hybrid style, default suffix to be used and alternative suffix

16.114.2 Examples

suffix off
suffix on
suffix gpu
suffix intel
suffix hybrid intel omp
suffix kk

16.114.3 Description

This command allows you to use variants of various styles if they exist. In that respect it operates the same as the -suffix
command-line switch. It also has options to turn off or back on any suffix setting made via the command line.
The specified style can be gpu, intel, kk, omp, opt or hybrid. These refer to optional packages that LAMMPS can be
built with, as described on the Build package doc page. The “gpu” style corresponds to the GPU package, the “intel”
style to the INTEL package, the “kk” style to the KOKKOS package, the “omp” style to the OPENMP package, and
the “opt” style to the OPT package.
These are the variants these packages provide:
• GPU = a handful of pair styles and the PPPM kspace_style, optimized to run on one or more GPUs or multicore
CPU/GPU nodes
• INTEL = a collection of pair styles and neighbor routines optimized to run in single, mixed, or double precision
on CPUs and Intel(R) Xeon Phi(TM) co-processors.
• KOKKOS = a collection of atom, pair, and fix styles optimized to run using the Kokkos library on various kinds
of hardware, including GPUs via CUDA and many-core chips via OpenMP or threading.

954 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• OPENMP = a collection of pair, bond, angle, dihedral, improper, kspace, compute, and fix styles with support
for OpenMP multi-threading
• OPT = a handful of pair styles, cache-optimized for faster CPU performance
• HYBRID = a combination of two packages can be specified (see below)
As an example, all of the packages provide a pair_style lj/cut variant, with style names lj/cut/opt, lj/cut/omp, lj/cut/gpu,
lj/cut/intel, or lj/cut/kk. A variant styles can be specified explicitly in your input script, e.g. pair_style lj/cut/gpu. If the
suffix command is used with the appropriate style, you do not need to modify your input script. The specified suffix
(opt,omp,gpu,intel,kk) is automatically appended whenever your input script command creates a new atom, pair, bond,
angle, dihedral, improper, kspace, fix, compute, or run style. If the variant version does not exist, the standard version
is created.
For “hybrid”, two packages are specified. The first is used whenever available. If a style with the first suffix is not
available, the style with the suffix for the second package will be used if available. For example, “hybrid intel omp”
will use styles from the INTEL package as a first choice and styles from the OPENMP package as a second choice if
no INTEL variant is available.
If the specified style is off, then any previously specified suffix is temporarily disabled, whether it was specified by a
command-line switch or a previous suffix command. If the specified style is on, a disabled suffix is turned back on. The
use of these 2 commands lets your input script use a standard LAMMPS style (i.e. a non-accelerated variant), which
can be useful for testing or benchmarking purposes. Of course this is also possible by not using any suffix commands,
and explicitly appending or not appending the suffix to the relevant commands in your input script.

Note: The default run_style verlet is invoked prior to reading the input script and is therefore not affected by a suffix
command in the input script. The KOKKOS package requires “run_style verlet/kk”, so when using the KOKKOS
package it is necessary to either use the command line “-sf kk” command or add an explicit “run_style verlet” command
to the input script.

16.114.4 Restrictions

none

16.114.5 Related commands

-suffix command-line switch

16.114.6 Default

none

16.114. suffix command 955

LAMMPS Documentation, Release stable 29Sep2021

16.115 tad command

16.115.1 Syntax

tad N t_event T_lo T_hi delta tmax compute-ID keyword value ...

• N = # of timesteps to run (not including dephasing/quenching)

• t_event = timestep interval between event checks
• T_lo = temperature at which event times are desired
• T_hi = temperature at which MD simulation is performed
• delta = desired confidence level for stopping criterion
• tmax = reciprocal of lowest expected pre-exponential factor (time units)
• compute-ID = ID of the compute used for event detection
• zero or more keyword/value pairs may be appended
• keyword = min or neb or min_style or neb_style or neb_log
min values = etol ftol maxiter maxeval
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
maxiter = max iterations of minimize
maxeval = max number of force/energy evaluations
neb values = ftol N1 N2 Nevery
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
N1 = max # of iterations (timesteps) to run initial NEB
N2 = max # of iterations (timesteps) to run barrier-climbing NEB
Nevery = print NEB statistics every this many timesteps
neb_style value = quickmin or fire
neb_step value = dtneb
dtneb = timestep for NEB damped dynamics minimization
neb_log value = file where NEB statistics are printed

16.115.2 Examples

tad 2000 50 1800 2300 0.01 0.01 event

tad 2000 50 1800 2300 0.01 0.01 event &
min 1e-05 1e-05 100 100 &
neb 0.0 0.01 200 200 20 &
min_style cg &
neb_style fire &
neb_log log.neb

956 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.115.3 Description

Run a temperature accelerated dynamics (TAD) simulation. This method requires two or more partitions to perform
NEB transition state searches.
TAD is described in this paper by Art Voter. It is a method that uses accelerated dynamics at an elevated temperature to
generate results at a specified lower temperature. A good overview of accelerated dynamics methods (AMD) for such
systems is given in this review paper from the same group. To quote from the review paper: “The dynamical evolution
is characterized by vibrational excursions within a potential basin, punctuated by occasional transitions between basins.
The transition probability is characterized by p(t) = k*exp(-kt) where k is the rate constant.”
TAD is a suitable AMD method for infrequent-event systems, where in addition, the transition kinetics are well-
approximated by harmonic transition state theory (hTST). In hTST, the temperature dependence of transition rates
follows the Arrhenius relation. As a consequence a set of event times generated in a high-temperature simulation can
be mapped to a set of much longer estimated times in the low-temperature system. However, because this mapping in-
volves the energy barrier of the transition event, which is different for each event, the first event at the high temperature
may not be the earliest event at the low temperature. TAD handles this by first generating a set of possible events from
the current basin. After each event, the simulation is reflected backwards into the current basin. This is repeated until
the stopping criterion is satisfied, at which point the event with the earliest low-temperature occurrence time is selected.
The stopping criterion is that the confidence measure be greater than 1-delta. The confidence measure is the probability
that no earlier low-temperature event will occur at some later time in the high-temperature simulation. hTST provides
an lower bound for this probability, based on the user-specified minimum pre-exponential factor (reciprocal of tmax).
In order to estimate the energy barrier for each event, the TAD method invokes the NEB method. Each NEB replica
runs on a partition of processors. The current NEB implementation in LAMMPS restricts you to having exactly one
processor per replica. For more information, see the documentation for the neb command. In the current LAMMPS
implementation of TAD, all the non-NEB TAD operations are performed on the first partition, while the other partitions
remain idle. See the Howto replica doc page for further discussion of multi-replica simulations.
A TAD run has several stages, which are repeated each time an event is performed. The logic for a TAD run is as
follows:

while (time remains):

while (time < tstop):
until (event occurs):
run dynamics for t_event steps
quench
run neb calculation using all replicas
compute tlo from energy barrier
update earliest event
update tstop
reflect back into current basin
execute earliest event

Before this outer loop begins, the initial potential energy basin is identified by quenching (an energy minimization, see
below) the initial state and storing the resulting coordinates for reference.
Inside the inner loop, dynamics is run continuously according to whatever integrator has been specified by the user,
stopping every t_event steps to check if a transition event has occurred. This check is performed by quenching the
system and comparing the resulting atom coordinates to the coordinates from the previous basin.
A quench is an energy minimization and is performed by whichever algorithm has been defined by the min_style
command; its default is the CG minimizer. The tolerances and limits for each quench can be set by the min keyword.
Note that typically, you do not need to perform a highly-converged minimization to detect a transition event.
The event check is performed by a compute with the specified compute-ID. Currently there is only one compute that
works with the TAD command, which is the compute event/displace command. Other event-checking computes may

16.115. tad command 957

LAMMPS Documentation, Release stable 29Sep2021

be added. Compute event/displace checks whether any atom in the compute group has moved further than a specified
threshold distance. If so, an “event” has occurred.
The NEB calculation is similar to that invoked by the neb command, except that the final state is generated internally,
instead of being read in from a file. The style of minimization performed by NEB is determined by the neb_style
keyword and must be a damped dynamics minimizer. The tolerances and limits for each NEB calculation can be set by
the neb keyword. As discussed on the neb, it is often advantageous to use a larger timestep for NEB than for normal
dynamics. Since the size of the timestep set by the timestep command is used by TAD for performing dynamics, there
is a neb_step keyword which can be used to set a larger timestep for each NEB calculation if desired.

A key aspect of the TAD method is setting the stopping criterion appropriately. If this criterion is too conservative,
then many events must be generated before one is finally executed. Conversely, if this criterion is too aggressive, high-
entropy high-barrier events will be over-sampled, while low-entropy low-barrier events will be under-sampled. If the
lowest pre-exponential factor is known fairly accurately, then it can be used to estimate tmax, and the value of delta can
be set to the desired confidence level e.g. delta = 0.05 corresponds to 95% confidence. However, for systems where
the dynamics are not well characterized (the most common case), it will be necessary to experiment with the values of
delta and tmax to get a good trade-off between accuracy and performance.
A second key aspect is the choice of t_hi. A larger value greatly increases the rate at which new events are generated.
However, too large a value introduces errors due to anharmonicity (not accounted for within hTST). Once again, for
any given system, experimentation is necessary to determine the best value of t_hi.

Five kinds of output can be generated during a TAD run: event statistics, NEB statistics, thermodynamic output by
each replica, dump files, and restart files.
Event statistics are printed to the screen and master log.lammps file each time an event is executed. The quantities are
the timestep, CPU time, global event number N, local event number M, event status, energy barrier, time margin, t_lo
and delt_lo. The timestep is the usual LAMMPS timestep, which corresponds to the high-temperature time at which
the event was detected, in units of timestep. The CPU time is the total processor time since the start of the TAD run.
The global event number N is a counter that increments with each executed event. The local event number M is a
counter that resets to zero upon entering each new basin. The event status is E when an event is executed, and is D for
an event that is detected, while DF is for a detected event that is also the earliest (first) event at the low temperature.
The time margin is the ratio of the high temperature time in the current basin to the stopping time. This last number
can be used to judge whether the stopping time is too short or too long (see above).
t_lo is the low-temperature event time when the current basin was entered, in units of timestep. del*t_lo* is the time of
each detected event, measured relative to t_lo. delt_lo is equal to the high-temperature time since entering the current
basin, scaled by an exponential factor that depends on the hi/lo temperature ratio and the energy barrier for that event.
On lines for executed events, with status E, the global event number is incremented by one, the local event number
and time margin are reset to zero, while the global event number, energy barrier, and delt_lo match the last event with
status DF in the immediately preceding block of detected events. The low-temperature event time t_lo is incremented
by delt_lo.
NEB statistics are written to the file specified by the neb_log keyword. If the keyword value is “none”, then no NEB
statistics are printed out. The statistics are written every Nevery timesteps. See the neb command for a full description
of the NEB statistics. When invoked from TAD, NEB statistics are never printed to the screen.
Because the NEB calculation must run on multiple partitions, LAMMPS produces additional screen and log files for
each partition, e.g. log.lammps.0, log.lammps.1, etc. For the TAD command, these contain the thermodynamic output
of each NEB replica. In addition, the log file for the first partition, log.lammps.0, will contain thermodynamic output
from short runs and minimizations corresponding to the dynamics and quench operations, as well as a line for each
new detected event, as described above.
After the TAD command completes, timing statistics for the TAD run are printed in each replica’s log file, giving a
breakdown of how much CPU time was spent in each stage (NEB, dynamics, quenching, etc).

958 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Any dump files defined in the input script will be written to during a TAD run at timesteps when an event is executed.
This means the requested dump frequency in the dump command is ignored. There will be one dump file (per dump
command) created for all partitions. The atom coordinates of the dump snapshot are those of the minimum energy
configuration resulting from quenching following the executed event. The timesteps written into the dump files corre-
spond to the timestep at which the event occurred and NOT the clock. A dump snapshot corresponding to the initial
minimum state used for event detection is written to the dump file at the beginning of each TAD run.
If the restart command is used, a single restart file for all the partitions is generated, which allows a TAD run to be
continued by a new input script in the usual manner. The restart file is generated after an event is executed. The restart
file contains a snapshot of the system in the new quenched state, including the event number and the low-temperature
time. The restart frequency specified in the restart command is interpreted differently when performing a TAD run. It
does not mean the timestep interval between restart files. Instead it means an event interval for executed events. Thus
a frequency of 1 means write a restart file every time an event is executed. A frequency of 10 means write a restart file
every 10th executed event. When an input script reads a restart file from a previous TAD run, the new script can be run
on a different number of replicas or processors.
Note that within a single state, the dynamics will typically temporarily continue beyond the event that is ultimately
chosen, until the stopping criterion is satisfied. When the event is eventually executed, the timestep counter is reset to
the value when the event was detected. Similarly, after each quench and NEB minimization, the timestep counter is
reset to the value at the start of the minimization. This means that the timesteps listed in the replica log files do not
always increase monotonically. However, the timestep values printed to the master log file, dump files, and restart files
are always monotonically increasing.

16.115.4 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package doc page
for more info.
N setting must be integer multiple of t_event.
Runs restarted from restart files written during a TAD run will only produce identical results if the user-specified
integrator supports exact restarts. So fix nvt will produce an exact restart, but fix langevin will not.
This command cannot be used when any fixes are defined that keep track of elapsed time to perform time-dependent
operations. Examples include the “ave” fixes such as fix ave/chunk. Also fix dt/reset and fix deposit.

16.115.5 Related commands

compute event/displace, min_modify, min_style, run_style, minimize, temper, neb, prd

16.115.6 Default

The option defaults are min = 0.1 0.1 40 50, neb = 0.01 100 100 10, neb_style = quickmin, neb_step = the same timestep
set by the timestep command, and neb_log = “none”.

(Voter2000) Sorensen and Voter, J Chem Phys, 112, 9599 (2000)

(Voter2002) Voter, Montalenti, Germann, Annual Review of Materials Research 32, 321 (2002).

16.115. tad command 959

LAMMPS Documentation, Release stable 29Sep2021

16.116 temper command

16.116.1 Syntax

temper N M temp fix-ID seed1 seed2 index

• N = total # of timesteps to run

• M = attempt a tempering swap every this many steps
• temp = initial temperature for this ensemble
• fix-ID = ID of the fix that will control temperature during the run
• seed1 = random # seed used to decide on adjacent temperature to partner with
• seed2 = random # seed for Boltzmann factor in Metropolis swap
• index = which temperature (0 to N-1) I am simulating (optional)

16.116.2 Examples

temper 100000 100 $t tempfix 0 58728

temper 40000 100 $t tempfix 0 32285 $w

16.116.3 Description

Run a parallel tempering or replica exchange simulation using multiple replicas (ensembles) of a system. Two or more
replicas must be used.
Each replica runs on a partition of one or more processors. Processor partitions are defined at run-time using the -
partition command-line switch. Note that if you have MPI installed, you can run a multi-replica simulation with more
replicas (partitions) than you have physical processors, e.g you can run a 10-replica simulation on one or two processors.
You will simply not get the performance speed-up you would see with one or more physical processors per replica. See
the Howto replica doc page for further discussion.
Each replica’s temperature is controlled at a different value by a fix with fix-ID that controls temperature. Most ther-
mostat fix styles (with and without included time integration) are supported. The command will print an error message
and abort, if the chosen fix is unsupported. The desired temperature is specified by temp, which is typically a variable
previously set in the input script, so that each partition is assigned a different temperature. See the variable command
for more details. For example:

variable t world 300.0 310.0 320.0 330.0

fix myfix all nvt temp $t $t 100.0
temper 100000 100 $t myfix 3847 58382

would define 4 temperatures, and assign one of them to the thermostat used by each replica, and to the temper command.
As the tempering simulation runs for N timesteps, a temperature swap between adjacent ensembles will be attempted
every M timesteps. If seed1 is 0, then the swap attempts will alternate between odd and even pairings. If seed1 is non-
zero then it is used as a seed in a random number generator to randomly choose an odd or even pairing each time. Each
attempted swap of temperatures is either accepted or rejected based on a Boltzmann-weighted Metropolis criterion
which uses seed2 in the random number generator.

960 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

As a tempering run proceeds, multiple log files and screen output files are created, one per replica. By default these
files are named log.lammps.M and screen.M where M is the replica number from 0 to N-1, with N = # of replicas. See
the -log and -screen command-line swiches for info on how to change these names.
The main screen and log file (log.lammps) will list information about which temperature is assigned to each replica at
each thermodynamic output timestep. E.g. for a simulation with 16 replicas:

Running on 16 partitions of processors

Step T0 T1 T2 T3 T4 T5 T6 T7 T8 T9 T10 T11 T12 T13 T14 T15
0 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
500 1 0 3 2 5 4 6 7 8 9 10 11 12 13 14 15
1000 2 0 4 1 5 3 6 7 8 9 10 11 12 14 13 15
1500 2 1 4 0 5 3 6 7 9 8 10 11 12 14 13 15
2000 2 1 3 0 6 4 5 7 10 8 9 11 12 14 13 15
2500 2 1 3 0 6 4 5 7 11 8 9 10 12 14 13 15
...

The column headings T0 to TN-1 mean which temperature is currently assigned to the replica 0 to N-1. Thus the
columns represent replicas and the value in each column is its temperature (also numbered 0 to N-1). For example,
a 0 in the fourth column (column T3, step 2500) means that the fourth replica is assigned temperature 0, i.e. the
lowest temperature. You can verify this time sequence of temperature assignments for the Nth replica by comparing
the Nth column of screen output to the thermodynamic data in the corresponding log.lammps.N or screen.N files as
time proceeds.
You can have each replica create its own dump file in the following manner:

variable rep world 0 1 2 3 4 5 6 7

dump 1 all atom 1000 dump.temper.${rep}

Note: Each replica’s dump file will contain a continuous trajectory for its atoms where the temperature varies over
time as swaps take place involving that replica. If you want a series of dump files, each with snapshots (from all
replicas) that are all at a single temperature, then you will need to post-process the dump files using the information
from the log.lammps file. E.g. you could produce one dump file with snapshots at 300K (from all replicas), another
with snapshots at 310K, etc. Note that these new dump files will not contain “continuous trajectories” for individual
atoms, because two successive snapshots (in time) may be from different replicas. The reorder_remd_traj python script
can do the reordering for you (and additionally also calculated configurational log-weights of trajectory snapshots in
the canonical ensemble). The script can be found in the tools/replica directory while instructions on how to use it is
available in doc/Tools (in brief) and as a README file in tools/replica (in detail).

The last argument index in the temper command is optional and is used when restarting a tempering run from a set of
restart files (one for each replica) which had previously swapped to new temperatures. The index value (from 0 to N-1,
where N is the # of replicas) identifies which temperature the replica was simulating on the timestep the restart files
were written. Obviously, this argument must be a variable so that each partition has the correct value. Set the variable
to the N values listed in the log file for the previous run for the replica temperatures at that timestep. For example if
the log file listed the following for a simulation with 5 replicas:

500000 2 4 0 1 3

then a setting of

variable w world 2 4 0 1 3

would be used to restart the run with a tempering command like the example above with $w as the last argument.

16.116. temper command 961

LAMMPS Documentation, Release stable 29Sep2021

16.116.4 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package doc page
for more info.

16.116.5 Related commands

variable, prd, neb

16.116.6 Default

none

16.117 temper/grem command

16.117.1 Syntax

temper/grem N M lambda fix-ID thermostat-ID seed1 seed2 index

• N = total # of timesteps to run

• M = attempt a tempering swap every this many steps
• lambda = initial lambda for this ensemble
• fix-ID = ID of fix grem
• thermostat-ID = ID of the thermostat that controls kinetic temperature
• seed1 = random # seed used to decide on adjacent temperature to partner with
• seed2 = random # seed for Boltzmann factor in Metropolis swap
• index = which temperature (0 to N-1) I am simulating (optional)

16.117.2 Examples

temper/grem 100000 1000 ${lambda} fxgREM fxnvt 0 58728

temper/grem 40000 100 ${lambda} fxgREM fxnpt 0 32285 ${walkers}

16.117.3 Description

Run a parallel tempering or replica exchange simulation in LAMMPS partition mode using multiple generalized repli-
cas (ensembles) of a system defined by fix grem, which stands for the generalized replica exchange method (gREM)
originally developed by (Kim). It uses non-Boltzmann ensembles to sample over first order phase transitions. The is
done by defining replicas with an enthalpy dependent effective temperature
Two or more replicas must be used. See the temper command for an explanation of how to run replicas on multiple
partitions of one or more processors.
This command is a modification of the temper command and has the same dependencies, restraints, and input variables
which are discussed there in greater detail.

962 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Instead of temperature, this command performs replica exchanges in lambda as per the generalized ensemble enforced
by fix grem. The desired lambda is specified by lambda, which is typically a variable previously set in the input script,
so that each partition is assigned a different temperature. See the variable command for more details. For example:

variable lambda world 400 420 440 460

fix fxnvt all nvt temp 300.0 300.0 100.0
fix fxgREM all grem ${lambda} -0.05 -50000 fxnvt
temper/grem 100000 100 ${lambda} fxgREM fxnvt 3847 58382

would define 4 lambdas with constant kinetic temperature but unique generalized temperature, and assign one of them
to fix grem used by each replica, and to the grem command.
As the gREM simulation runs for N timesteps, a swap between adjacent ensembles will be attempted every M timesteps.
If seed1 is 0, then the swap attempts will alternate between odd and even pairings. If seed1 is non-zero then it is used
as a seed in a random number generator to randomly choose an odd or even pairing each time. Each attempted swap
of temperatures is either accepted or rejected based on a Metropolis criterion, derived for gREM by (Kim), which uses
seed2 in the random number generator.
File management works identical to the temper command. Dump files created by this fix contain continuous trajectories
and require post-processing to obtain per-replica information.
The last argument index in the grem command is optional and is used when restarting a run from a set of restart files
(one for each replica) which had previously swapped to new lambda. This is done using a variable. For example if the
log file listed the following for a simulation with 5 replicas:

500000 2 4 0 1 3

then a setting of

variable walkers world 2 4 0 1 3

would be used to restart the run with a grem command like the example above with ${walkers} as the last argument.
This functionality is identical to temper.

16.117.4 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package doc page
for more info.
This command must be used with fix grem.

16.117.5 Related commands

fix grem, temper, variable

16.117. temper/grem command 963

LAMMPS Documentation, Release stable 29Sep2021

16.117.6 Default

none
(Kim) Kim, Keyes, Straub, J Chem Phys, 132, 224107 (2010).

16.118 temper/npt command

16.118.1 Syntax

temper/npt N M temp fix-ID seed1 seed2 pressure index

• N = total # of timesteps to run

• M = attempt a tempering swap every this many steps
• temp = initial temperature for this ensemble
• fix-ID = ID of the fix that will control temperature and pressure during the run
• seed1 = random # seed used to decide on adjacent temperature to partner with
• seed2 = random # seed for Boltzmann factor in Metropolis swap
• pressure = setpoint pressure for the ensemble
• index = which temperature (0 to N-1) I am simulating (optional)

16.118.2 Examples

temper/npt 100000 100 $t nptfix 0 58728 1

temper/npt 2500000 1000 300 nptfix 0 32285 $p
temper/npt 5000000 2000 $t nptfix 0 12523 1 $w

16.118.3 Description

Run a parallel tempering or replica exchange simulation using multiple replicas (ensembles) of a system in the
isothermal-isobaric (NPT) ensemble. The command temper/npt works like temper but requires running replicas in
the NPT ensemble instead of the canonical (NVT) ensemble and allows for pressure to be set in the ensembles. These
multiple ensembles can run in parallel at different temperatures or different pressures. The acceptance criteria for
temper/npt is specific to the NPT ensemble and can be found in references (Okabe) and (Mori).
Apart from the difference in acceptance criteria and the specification of pressure, this command works much like the
temper command. See the documentation on temper for information on how the parallel tempering is handled in
general.

964 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.118.4 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package page for
more info.
This command should be used with a fix that maintains the isothermal-isobaric (NPT) ensemble.

16.118.5 Related commands

temper, variable, fix_npt

16.118.6 Default

none
(Okabe) T. Okabe, M. Kawata, Y. Okamoto, M. Masuhiro, Chem. Phys. Lett., 335, 435-439 (2001).
(Mori) Y. Mori, Y. Okamoto, J. Phys. Soc. Jpn., 7, 074003 (2010).

16.119 thermo command

16.119.1 Syntax

thermo N

• N = output thermodynamics every N timesteps

• N can be a variable (see below)

16.119.2 Examples

thermo 100

16.119.3 Description

Compute and print thermodynamic info (e.g. temperature, energy, pressure) on timesteps that are a multiple of N and
at the beginning and end of a simulation. A value of 0 will only print thermodynamics at the beginning and end.
The content and format of what is printed is controlled by the thermo_style and thermo_modify commands.
Instead of a numeric value, N can be specified as an equal-style variable, which should be specified as v_name, where
name is the variable name. In this case, the variable is evaluated at the beginning of a run to determine the next timestep
at which thermodynamic info will be written out. On that timestep, the variable will be evaluated again to determine
the next timestep, etc. Thus the variable should return timestep values. See the stagger() and logfreq() and stride() math
functions for equal-style variables, as examples of useful functions to use in this context. Other similar math functions
could easily be added as options for equal-style variables.
For example, the following commands will output thermodynamic info at timesteps
0,10,20,30,100,200,300,1000,2000,etc:

16.119. thermo command 965

LAMMPS Documentation, Release stable 29Sep2021

variable s equal logfreq(10,3,10)

thermo v_s

16.119.4 Restrictions

none

16.119.5 Related commands

thermo_style, thermo_modify

16.119.6 Default

thermo 0

16.120 thermo_modify command

16.120.1 Syntax

thermo_modify keyword value ...

• one or more keyword/value pairs may be listed

• keyword = lost or lost/bond or warn or norm or flush or line or format or temp or press
lost value = error or warn or ignore
lost/bond value = error or warn or ignore
warn value = ignore or reset or default or a number
norm value = yes or no
flush value = yes or no
line value = one or multi
format values = line string, int string, float string, M string, or none
string = C-style format string
M = integer from 1 to N, where N = # of quantities being output
temp value = compute ID that calculates a temperature
press value = compute ID that calculates a pressure

16.120.2 Examples

thermo_modify lost ignore flush yes

thermo_modify temp myTemp format 3 %15.8g
thermo_modify temp myTemp format line "%ld %g %g %15.8g"
thermo_modify line multi format float %g

966 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.120.3 Description

Set options for how thermodynamic information is computed and printed by LAMMPS.

Note: These options apply to the currently defined thermo style. When you specify a thermo_style command, all
thermodynamic settings are restored to their default values, including those previously reset by a thermo_modify com-
mand. Thus if your input script specifies a thermo_style command, you should use the thermo_modify command after
it.

The lost keyword determines whether LAMMPS checks for lost atoms each time it computes thermodynamics and
what it does if atoms are lost. An atom can be “lost” if it moves across a non-periodic simulation box boundary or if
it moves more than a box length outside the simulation domain (or more than a processor sub-domain length) before
reneighboring occurs. The latter case is typically due to bad dynamics, e.g. too large a timestep or huge forces and
velocities. If the value is ignore, LAMMPS does not check for lost atoms. If the value is error or warn, LAMMPS
checks and either issues an error or warning. The code will exit with an error and continue with a warning. A warning
will only be issued once, the first time an atom is lost. This can be a useful debugging option.
The lost/bond keyword determines whether LAMMPS throws an error or not if an atom in a bonded interaction (bond,
angle, etc) cannot be found when it creates bonded neighbor lists. By default this is a fatal error. However in some
scenarios it may be desirable to only issue a warning or ignore it and skip the computation of the missing bond, angle,
etc. An example would be when gas molecules in a vapor are drifting out of the box through a fixed boundary condition
(see the boundary command). In this case one atom may be deleted before the rest of the molecule is, on a later timestep.
The warn keyword allows you to control whether LAMMPS will print warning messages and how many of them.
Most warning messages are only printed by MPI rank 0. They are usually pointing out important issues that should be
investigated, but LAMMPS cannot determine for certain whether they are an indication of an error.
Some warning messages are printed during a run (or immediately before) each time a specific MPI rank encounters the
issue, e.g. bonds that are stretched too far or dihedrals in extreme configurations. These number of these can quickly
blow up the size of the log file and screen output. Thus a limit of 100 warning messages is applied by default. The
warning count is applied to the entire input unless reset with a thermo_modify warn reset command. If there
are more warnings than the limit, LAMMPS will print one final warning that it will not print any additional warning
messages.

Note: The warning limit is enforced on either the per-processor count or the total count across all processors. For
efficiency reasons, however, the total count is only updated at steps with thermodynamic output. Thus when running
on a large number of processors in parallel, the total number of warnings printed can be significantly larger than the
given limit.

Any number after the keyword warn will change the warning limit accordingly. With the value ignore all warnings will
be suppressed, with the value always no limit will be applied and warnings will always be printed, with the value reset
the internal warning counter will be reset to zero, and with the value default, the counter is reset and the limit set to
100. An example usage of either reset or default would be to re-enable warnings that were disabled or have reached the
limit during equilibration, where the warnings would be acceptable while the system is still adjusting, but then change
to all warnings for the production run, where they would indicate problems that would require a closer look at what is
causing them.
The norm keyword determines whether various thermodynamic output values are normalized by the number of atoms
or not, depending on whether it is set to yes or no. Different unit styles have different defaults for this setting (see
below). Even if norm is set to yes, a value is only normalized if it is an “extensive” quantity, meaning that it scales with
the number of atoms in the system. For the thermo keywords described by the page for the thermo_style command,
all energy-related keywords are extensive, such as pe or ebond or enthalpy. Other keywords such as temp or press
are “intensive” meaning their value is independent (in a statistical sense) of the number of atoms in the system and
thus are never normalized. For thermodynamic output values extracted from fixes and computes in a thermo_style

16.120. thermo_modify command 967

LAMMPS Documentation, Release stable 29Sep2021

custom command, the page for the individual fix or compute lists whether the value is “extensive” or “intensive” and
thus whether it is normalized. Thermodynamic output values calculated by a variable formula are assumed to be
“intensive” and thus are never normalized. You can always include a divide by the number of atoms in the variable
formula if this is not the case.
The flush keyword invokes a flush operation after thermodynamic info is written to the screen and log file. This insures
the output is updated and not buffered (by the application) even if LAMMPS halts before the simulation completes.
Please note that this does not affect buffering by the OS or devices, so you may still lose data in case the simulation
stops due to a hardware failure.
The line keyword determines whether thermodynamics will be output as a series of numeric values on one line or in a
multi-line format with 3 quantities with text strings per line and a dashed-line header containing the timestep and CPU
time. This modify option overrides the one and multi thermo_style settings.
The format keyword can be used to change the default numeric format of any of quantities the thermo_style command
outputs. All the specified format strings are C-style formats, e.g. as used by the C/C++ printf() command. The line
keyword takes a single argument which is the format string for the entire line of thermo output, with N fields, which
you must enclose in quotes if it is more than one field. The int and float keywords take a single format argument and are
applied to all integer or floating-point quantities output. The setting for M string also takes a single format argument
which is used for the Mth value output in each line, e.g. the fifth column is output in high precision for “format 5
%20.15g”.
The format keyword can be used multiple times. The precedence is that for each value in a line of output, the M format
(if specified) is used, else the int or float setting (if specified) is used, else the line setting (if specified) for that value is
used, else the default setting is used. A setting of none clears all previous settings, reverting all values to their default
format.

Note: The thermo output values step and atoms are stored internally as 8-byte signed integers, rather than the usual
4-byte signed integers. When specifying the format int option you can use a “%d”-style format identifier in the format
string and LAMMPS will convert this to the corresponding 8-byte form when it is applied to those keywords. However,
when specifying the line option or format M string option for step and natoms, you should specify a format string
appropriate for an 8-byte signed integer, e.g. one with “%ld”.

The temp keyword is used to determine how thermodynamic temperature is calculated, which is used by all thermo
quantities that require a temperature (“temp”, “press”, “ke”, “etotal”, “enthalpy”, “pxx”, etc). The specified compute ID
must have been previously defined by the user via the compute command and it must be a style of compute that calculates
a temperature. As described in the thermo_style command, thermo output uses a default compute for temperature with
ID = thermo_temp. This option allows the user to override the default.
The press keyword is used to determine how thermodynamic pressure is calculated, which is used by all thermo quan-
tities that require a pressure (“press”, “enthalpy”, “pxx”, etc). The specified compute ID must have been previously
defined by the user via the compute command and it must be a style of compute that calculates a pressure. As described
in the thermo_style command, thermo output uses a default compute for pressure with ID = thermo_press. This option
allows the user to override the default.

Note: If both the temp and press keywords are used in a single thermo_modify command (or in two separate com-
mands), then the order in which the keywords are specified is important. Note that a pressure compute defines its own
temperature compute as an argument when it is specified. The temp keyword will override this (for the pressure com-
pute being used by thermodynamics), but only if the temp keyword comes after the press keyword. If the temp keyword
comes before the press keyword, then the new pressure compute specified by the press keyword will be unaffected by
the temp setting.

968 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.120.4 Restrictions

none

16.120.5 Related commands

thermo, thermo_style

16.120.6 Default

The option defaults are lost = error, warn = 100, norm = yes for unit style of lj, norm = no for unit style of real and
metal, flush = no, and temp/press = compute IDs defined by thermo_style.
The defaults for the line and format options depend on the thermo style. For styles “one” and “custom”, the line and
format defaults are “one”, “%8d”, and “%12.8g”. For style “multi”, the line and format defaults are “multi”, “%8d”,
and “%14.4f”.

16.121 thermo_style command

16.121.1 Syntax

thermo_style style args

• style = one or multi or custom

• args = list of arguments for a particular style
one args = none
multi args = none
custom args = list of keywords
possible keywords = step, elapsed, elaplong, dt, time,
cpu, tpcpu, spcpu, cpuremain, part, timeremain,
atoms, temp, press, pe, ke, etotal,
evdwl, ecoul, epair, ebond, eangle, edihed, eimp,
emol, elong, etail,
enthalpy, ecouple, econserve,
vol, density, lx, ly, lz, xlo, xhi, ylo, yhi, zlo, zhi,
xy, xz, yz, xlat, ylat, zlat,
bonds, angles, dihedrals, impropers,
pxx, pyy, pzz, pxy, pxz, pyz,
fmax, fnorm, nbuild, ndanger,
cella, cellb, cellc, cellalpha, cellbeta, cellgamma,
c_ID, c_ID[I], c_ID[I][J],
f_ID, f_ID[I], f_ID[I][J],
v_name, v_name[I]
step = timestep
elapsed = timesteps since start of this run
elaplong = timesteps since start of initial run in a series of runs
dt = timestep size
time = simulation time
cpu = elapsed CPU time in seconds since start of this run

16.121. thermo_style command 969

LAMMPS Documentation, Release stable 29Sep2021

tpcpu = time per CPU second

spcpu = timesteps per CPU second
cpuremain = estimated CPU time remaining in run
part = which partition (0 to Npartition-1) this is
timeremain = remaining time in seconds on timer timeout.
atoms = # of atoms
temp = temperature
press = pressure
pe = total potential energy
ke = kinetic energy
etotal = total energy (pe + ke)
evdwl = van der Waals pairwise energy (includes etail)
ecoul = Coulombic pairwise energy
epair = pairwise energy (evdwl + ecoul + elong)
ebond = bond energy
eangle = angle energy
edihed = dihedral energy
eimp = improper energy
emol = molecular energy (ebond + eangle + edihed + eimp)
elong = long-range kspace energy
etail = van der Waals energy long-range tail correction
enthalpy = enthalpy (etotal + press*vol)
ecouple = cumulative energy change due to thermo/baro statting fixes
econserve = pe + ke + ecouple = etotal + ecouple
vol = volume
density = mass density of system
lx,ly,lz = box lengths in x,y,z
xlo,xhi,ylo,yhi,zlo,zhi = box boundaries
xy,xz,yz = box tilt for triclinic (non-orthogonal) simulation boxes
xlat,ylat,zlat = lattice spacings as calculated by lattice command
bonds,angles,dihedrals,impropers = # of these interactions defined
pxx,pyy,pzz,pxy,pxz,pyz = 6 components of pressure tensor
fmax = max component of force on any atom in any dimension
fnorm = length of force vector for all atoms
nbuild = # of neighbor list builds
ndanger = # of dangerous neighbor list builds
cella,cellb,cellc = periodic cell lattice constants a,b,c
cellalpha, cellbeta, cellgamma = periodic cell angles alpha,beta,gamma
c_ID = global scalar value calculated by a compute with ID
c_ID[I] = Ith component of global vector calculated by a compute with ID, I can␣
,→include wildcard (see below)

c_ID[I][J] = I,J component of global array calculated by a compute with ID

f_ID = global scalar value calculated by a fix with ID
f_ID[I] = Ith component of global vector calculated by a fix with ID, I can␣
,→include wildcard (see below)

f_ID[I][J] = I,J component of global array calculated by a fix with ID

v_name = value calculated by an equal-style variable with name
v_name[I] = value calculated by a vector-style variable with name

970 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.121.2 Examples

thermo_style multi
thermo_style custom step temp pe etotal press vol
thermo_style custom step temp etotal c_myTemp v_abc
thermo_style custom step temp etotal c_myTemp[*] v_abc

16.121.3 Description

Set the style and content for printing thermodynamic data to the screen and log file.
Style one prints a one-line summary of thermodynamic info that is the equivalent of “thermo_style custom step temp
epair emol etotal press”. The line contains only numeric values.
Style multi prints a multiple-line listing of thermodynamic info that is the equivalent of “thermo_style custom etotal ke
temp pe ebond eangle edihed eimp evdwl ecoul elong press”. The listing contains numeric values and a string ID for
each quantity.
Style custom is the most general setting and allows you to specify which of the keywords listed above you want printed
on each thermodynamic timestep. Note that the keywords c_ID, f_ID, v_name are references to computes, fixes, and
equal-style variables that have been defined elsewhere in the input script or can even be new styles which users have
added to LAMMPS. See the Modify page for details on the latter. Thus the custom style provides a flexible means of
outputting essentially any desired quantity as a simulation proceeds.
All styles except custom have vol appended to their list of outputs if the simulation box volume changes during the
simulation.
The values printed by the various keywords are instantaneous values, calculated on the current timestep. Time-averaged
quantities, which include values from previous timesteps, can be output by using the f_ID keyword and accessing a fix
that does time-averaging such as the fix ave/time command.
Options invoked by the thermo_modify command can be used to set the one- or multi-line format of the print-out, the
normalization of thermodynamic output (total values versus per-atom values for extensive quantities (ones which scale
with the number of atoms in the system), and the numeric precision of each printed value.

Note: When you use a “thermo_style” command, all thermodynamic settings are restored to their default values, in-
cluding those previously set by a thermo_modify command. Thus if your input script specifies a thermo_style command,
you should use the thermo_modify command after it.

Several of the thermodynamic quantities require a temperature to be computed: “temp”, “press”, “ke”, “etotal”, “en-
thalpy”, “pxx”, etc. By default this is done by using a temperature compute which is created when LAMMPS starts
up, as if this command had been issued:

compute thermo_temp all temp

See the compute temp command for details. Note that the ID of this compute is thermo_temp and the group is all.
You can change the attributes of this temperature (e.g. its degrees-of-freedom) via the compute_modify command.
Alternatively, you can directly assign a new compute (that calculates temperature) which you have defined, to be used
for calculating any thermodynamic quantity that requires a temperature. This is done via the thermo_modify command.
Several of the thermodynamic quantities require a pressure to be computed: “press”, “enthalpy”, “pxx”, etc. By default
this is done by using a pressure compute which is created when LAMMPS starts up, as if this command had been issued:

16.121. thermo_style command 971

LAMMPS Documentation, Release stable 29Sep2021

compute thermo_press all pressure thermo_temp

See the compute pressure command for details. Note that the ID of this compute is thermo_press and the group is
all. You can change the attributes of this pressure via the compute_modify command. Alternatively, you can directly
assign a new compute (that calculates pressure) which you have defined, to be used for calculating any thermodynamic
quantity that requires a pressure. This is done via the thermo_modify command.
Several of the thermodynamic quantities require a potential energy to be computed: “pe”, “etotal”, “ebond”, etc. This
is done by using a pe compute which is created when LAMMPS starts up, as if this command had been issued:

compute thermo_pe all pe

See the compute pe command for details. Note that the ID of this compute is thermo_pe and the group is all. You can
change the attributes of this potential energy via the compute_modify command.

The kinetic energy of the system ke is inferred from the temperature of the system with 12 kB T of energy for each
degree of freedom. Thus, using different compute commands for calculating temperature, via the thermo_modify temp
command, may yield different kinetic energies, since different computes that calculate temperature can subtract out
different non-thermal components of velocity and/or include different degrees of freedom (translational, rotational,
etc).
The potential energy of the system pe will include contributions from fixes if the fix_modify energy yes option is set
for a fix that calculates such a contribution. For example, the fix wall/lj93 fix calculates the energy of atoms interacting
with the wall. See the doc pages for “individual fixes” to see which ones contribute and whether their default fix_modify
energy setting is yes or no.
A long-range tail correction etail for the van der Waals pairwise energy will be non-zero only if the pair_modify tail
option is turned on. The etail contribution is included in evdwl, epair, pe, and etotal, and the corresponding tail
correction to the pressure is included in press and pxx, pyy, etc.

Here is more information on other keywords whose meaning may not be clear:
The step, elapsed, and elaplong keywords refer to timestep count. Step is the current timestep, or iteration count when a
minimization is being performed. Elapsed is the number of timesteps elapsed since the beginning of this run. Elaplong
is the number of timesteps elapsed since the beginning of an initial run in a series of runs. See the start and stop
keywords for the run for info on how to invoke a series of runs that keep track of an initial starting time. If these
keywords are not used, then elapsed and elaplong are the same value.
The dt keyword is the current timestep size in time units. The time keyword is the current elapsed simulation time,
also in time units, which is simply (step*dt) if the timestep size has not changed and the timestep has not been reset. If
the timestep has changed (e.g. via fix dt/reset) or the timestep has been reset (e.g. via the “reset_timestep” command),
then the simulation time is effectively a cumulative value up to the current point.
The cpu keyword is elapsed CPU seconds since the beginning of this run. The tpcpu and spcpu keywords are measures of
how fast your simulation is currently running. The tpcpu keyword is simulation time per CPU second, where simulation
time is in time units. E.g. for metal units, the tpcpu value would be picoseconds per CPU second. The spcpu keyword
is the number of timesteps per CPU second. Both quantities are on-the-fly metrics, measured relative to the last time
they were invoked. Thus if you are printing out thermodynamic output every 100 timesteps, the two keywords will
continually output the time and timestep rate for the last 100 steps. The tpcpu keyword does not attempt to track any
changes in timestep size, e.g. due to using the fix dt/reset command.
The cpuremain keyword estimates the CPU time remaining in the current run, based on the time elapsed thus far. It
will only be a good estimate if the CPU time/timestep for the rest of the run is similar to the preceding timesteps. On
the initial timestep the value will be 0.0 since there is no history to estimate from. For a minimization run performed

972 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

by the “minimize” command, the estimate is based on the maxiter parameter, assuming the minimization will proceed
for the maximum number of allowed iterations.
The part keyword is useful for multi-replica or multi-partition simulations to indicate which partition this output and
this file corresponds to, or for use in a variable to append to a filename for output specific to this partition. See discussion
of the -partition command-line switch for details on running in multi-partition mode.
The timeremain keyword is the seconds remaining when a timeout has been configured via the timer timeout command.
If the timeout timer is inactive, the value of this keyword is 0.0 and if the timer is expired, it is negative. This allows
for example to exit loops cleanly, if the timeout is expired with:

if "$(timeremain) < 0.0" then "quit 0"

The ecouple keyword is cumulative energy change in the system due to any thermostatting or barostatting fixes that are
being used. A positive value means that energy has been subtracted from the system (added to the coupling reservoir).
See the econserve keyword for an explanation of why this sign choice makes sense.
The econserve keyword is the sum of the potential and kinetic energy of the system as well as the energy that has been
transferred by thermostatting or barostatting to their coupling reservoirs. I.e. it is pe + ke + econserve. Ideally, for a
simulation in the NVE, NPH, or NPT ensembles, the econserve quantity should remain constant over time.
The fmax and fnorm keywords are useful for monitoring the progress of an energy minimization. The fmax keyword
calculates the maximum force in any dimension on any atom in the system, or the infinity-norm of the force vector for
the system. The fnorm keyword calculates the 2-norm or length of the force vector.
The nbuild and ndanger keywords are useful for monitoring neighbor list builds during a run. Note that both these
values are also printed with the end-of-run statistics. The nbuild keyword is the number of re-builds during the current
run. The ndanger keyword is the number of re-builds that LAMMPS considered potentially “dangerous”. If atom
movement triggered neighbor list rebuilding (see the neigh_modify command), then dangerous reneighborings are
those that were triggered on the first timestep atom movement was checked for. If this count is non-zero you may wish
to reduce the delay factor to insure no force interactions are missed by atoms moving beyond the neighbor skin distance
before a rebuild takes place.
The keywords cella, cellb, cellc, cellalpha, cellbeta, cellgamma, correspond to the usual crystallographic quantities that
define the periodic unit cell of a crystal. See the Howto triclinic page for a geometric description of triclinic periodic
cells, including a precise definition of these quantities in terms of the internal LAMMPS cell dimensions lx, ly, lz, yz,
xz, xy.

For output values from a compute or fix, the bracketed index I used to index a vector, as in c_ID[I] or f_ID[I], can
be specified using a wildcard asterisk with the index to effectively specify multiple values. This takes the form “*” or
“*n” or “n*” or “m*n”. If N = the size of the vector (for mode = scalar) or the number of columns in the array (for
mode = vector), then an asterisk with no numeric values means all indices from 1 to N. A leading asterisk means all
indices from 1 to n (inclusive). A trailing asterisk means all indices from n to N (inclusive). A middle asterisk means
all indices from m to n (inclusive).
Using a wildcard is the same as if the individual elements of the vector had been listed one by one. E.g. these 2
thermo_style commands are equivalent, since the compute temp command creates a global vector with 6 values.

compute myTemp all temp

thermo_style custom step temp etotal c_myTemp[*]
thermo_style custom step temp etotal &
c_myTemp[1] c_myTemp[2] c_myTemp[3] &
c_myTemp[4] c_myTemp[5] c_myTemp[6]

The c_ID and c_ID[I] and c_ID[I][J] keywords allow global values calculated by a compute to be output. As discussed
on the compute doc page, computes can calculate global, per-atom, or local values. Only global values can be referenced

16.121. thermo_style command 973

LAMMPS Documentation, Release stable 29Sep2021

by this command. However, per-atom compute values for an individual atom can be referenced in a variable and the
variable referenced by thermo_style custom, as discussed below. See the discussion above for how the I in c_ID[I] can
be specified with a wildcard asterisk to effectively specify multiple values from a global compute vector.
The ID in the keyword should be replaced by the actual ID of a compute that has been defined elsewhere in the input
script. See the compute command for details. If the compute calculates a global scalar, vector, or array, then the
keyword formats with 0, 1, or 2 brackets will reference a scalar value from the compute.
Note that some computes calculate “intensive” global quantities like temperature; others calculate “extensive” global
quantities like kinetic energy that are summed over all atoms in the compute group. Intensive quantities are printed
directly without normalization by thermo_style custom. Extensive quantities may be normalized by the total num-
ber of atoms in the simulation (NOT the number of atoms in the compute group) when output, depending on the
thermo_modify norm option being used.
The f_ID and f_ID[I] and f_ID[I][J] keywords allow global values calculated by a fix to be output. As discussed
on the fix doc page, fixes can calculate global, per-atom, or local values. Only global values can be referenced by
this command. However, per-atom fix values can be referenced for an individual atom in a variable and the variable
referenced by thermo_style custom, as discussed below. See the discussion above for how the I in f_ID[I] can be
specified with a wildcard asterisk to effectively specify multiple values from a global fix vector.
The ID in the keyword should be replaced by the actual ID of a fix that has been defined elsewhere in the input script.
See the fix command for details. If the fix calculates a global scalar, vector, or array, then the keyword formats with 0,
1, or 2 brackets will reference a scalar value from the fix.
Note that some fixes calculate “intensive” global quantities like timestep size; others calculate “extensive” global quan-
tities like energy that are summed over all atoms in the fix group. Intensive quantities are printed directly without
normalization by thermo_style custom. Extensive quantities may be normalized by the total number of atoms in the
simulation (NOT the number of atoms in the fix group) when output, depending on the thermo_modify norm option
being used.
The v_name keyword allow the current value of a variable to be output. The name in the keyword should be replaced
by the variable name that has been defined elsewhere in the input script. Only equal-style and vector-style variables can
be referenced; the latter requires a bracketed term to specify the Ith element of the vector calculated by the variable.
However, an atom-style variable can be referenced for an individual atom by an equal-style variable and that variable
referenced. See the variable command for details. Variables of style equal and vector and atom define a formula which
can reference per-atom properties or thermodynamic keywords, or they can invoke other computes, fixes, or variables
when evaluated, so this is a very general means of creating thermodynamic output.
Note that equal-style and vector-style variables are assumed to produce “intensive” global quantities, which are thus
printed as-is, without normalization by thermo_style custom. You can include a division by “natoms” in the variable
formula if this is not the case.

16.121.4 Restrictions

This command must come after the simulation box is defined by a read_data, read_restart, or create_box command.

974 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.121.5 Related commands

thermo, thermo_modify, fix_modify, compute temp, compute pressure

16.121.6 Default

thermo_style one

16.122 third_order command

16.122.1 Syntax

third_order group-ID style delta args keyword value ...

• group-ID = ID of group of atoms to displace

• style = regular or eskm
• delta = finite different displacement length (distance units)
• one or more keyword/arg pairs may be appended
keyword = file or binary
file name = name of output file for the third order tensor
binary arg = yes or no or gzip

16.122.2 Examples

third_order 1 regular 0.000001

third_order 1 eskm 0.000001
third_order 3 regular 0.00004 file third_order.dat
third_order 5 eskm 0.00000001 file third_order.dat binary yes

16.122.3 Description

Calculate the third order force constant tensor by finite difference of the selected group,

where Phi is the third order force constant tensor.

16.122. third_order command 975

LAMMPS Documentation, Release stable 29Sep2021

The output of the command is the tensor, three elements at a time. The three elements correspond to the three gamma
elements for a specific i/alpha/j/beta/k. The initial five numbers are i, alpha, j, beta, and k respectively.
If the style eskm is selected, the tensor will be using energy units of 10 J/mol. These units conform to eskm style from
the dynamical_matrix command, which will simplify operations using dynamical matrices with third order tensors.

16.122.4 Restrictions

The command collects a 9 times the number of atoms in the group on every single MPI rank, so the memory require-
ments can be very significant for large systems.
This command is part of the PHONON package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.

16.122.5 Related commands

fix phonon dynamical_matrix

16.122.6 Default

The default settings are file = “third_order.dat”, binary = no

16.123 timer command

16.123.1 Syntax

timer args

• args = one or more of off or loop or normal or full or sync or nosync or timeout or every
off = do not collect or print any timing information
loop = collect only the total time for the simulation loop
normal = collect timer information broken down by sections (default)
full = like normal but also include CPU and thread utilization
sync = explicitly synchronize MPI tasks between sections
nosync = do not synchronize MPI tasks between sections (default)
timeout elapse = set wall time limit to elapse
every Ncheck = perform timeout check every Ncheck steps

16.123.2 Examples

timer full sync

timer timeout 2:00:00 every 100
timer loop

976 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.123.3 Description

Select the level of detail at which LAMMPS performs its CPU timings. Multiple keywords can be specified with the
timer command. For keywords that are mutually exclusive, the last one specified takes precedence.
During a simulation run LAMMPS collects information about how much time is spent in different sections of the code
and thus can provide information for determining performance and load imbalance problems. This can be done at
different levels of detail and accuracy. For more information about the timing output, see the Run output doc page.
The off setting will turn all time measurements off. The loop setting will only measure the total time for a run and not
collect any detailed per section information. With the normal setting, timing information for portions of the timestep
(pairwise calculations, neighbor list construction, output, etc) are collected as well as information about load imbalances
for those sections across processors. The full setting adds information about CPU utilization and thread utilization,
when multi-threading is enabled.
With the sync setting, all MPI tasks are synchronized at each timer call which measures load imbalance for each section
more accurately, though it can also slow down the simulation by prohibiting overlapping independent computations on
different MPI ranks Using the nosync setting (which is the default) turns this synchronization off.
With the timeout keyword a wall time limit can be imposed, that affects the run and minimize commands. This can
be convenient when calculations have to comply with execution time limits, e.g. when running under a batch system
when you want to maximize the utilization of the batch time slot, especially for runs where the time per timestep varies
much and thus it becomes difficult to predict how many steps a simulation can perform for a given wall time limit.
This also applies for difficult to converge minimizations. The timeout elapse value should be somewhat smaller than
the maximum wall time requested from the batch system, as there is usually some overhead to launch jobs, and it is
advisable to write out a restart after terminating a run due to a timeout.
The timeout timer starts when the command is issued. When the time limit is reached, the run or energy minimization
will exit on the next step or iteration that is a multiple of the Ncheck value which can be set with the every keyword.
Default is checking every 10 steps. After the timer timeout has expired all subsequent run or minimize commands in the
input script will be skipped. The remaining time or timer status can be accessed with the thermo variable timeremain,
which will be zero, if the timeout is inactive (default setting), it will be negative, if the timeout time is expired and
positive if there is time remaining and in this case the value of the variable are the number of seconds remaining.
When the timeout key word is used a second time, the timer is restarted with a new time limit. The timeout elapse
value can be specified as off or unlimited to impose a no timeout condition (which is the default). The elapse setting
can be specified as a single number for seconds, two numbers separated by a colon (MM:SS) for minutes and seconds,
or as three numbers separated by colons for hours, minutes, and seconds (H:MM:SS).
The every keyword sets how frequently during a run or energy minimization the wall clock will be checked. This check
count applies to the outer iterations or time steps during minimizations or r-RESPA runs, respectively. Checking for
timeout too often, can slow a calculation down. Checking too infrequently can make the timeout measurement less
accurate, with the run being stopped later than desired.

Note: Using the full and sync options provides the most detailed and accurate timing information, but can also have
a negative performance impact due to the overhead of the many required system calls. It is thus recommended to use
these settings only when testing tests to identify performance bottlenecks. For calculations with few atoms or a very
large number of processors, even the normal setting can have a measurable negative performance impact. In those
cases you can just use the loop or off setting.

16.123. timer command 977

LAMMPS Documentation, Release stable 29Sep2021

16.123.4 Restrictions

none

16.123.5 Related commands

run post no, kspace_modify fftbench

16.123.6 Default

timer normal nosync

timer timeout off
timer every 10

16.124 timestep command

16.124.1 Syntax

timestep dt

• dt = timestep size (time units)

16.124.2 Examples

timestep 2.0
timestep 0.003

16.124.3 Description

Set the timestep size for subsequent molecular dynamics simulations. See the units command for the time units asso-
ciated with each choice of units that LAMMPS supports.
The default value for the timestep size also depends on the choice of units for the simulation; see the default values
below.
When the run style is respa, dt is the timestep for the outer loop (largest) timestep.

16.124.4 Restrictions

none

978 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.124.5 Related commands

fix dt/reset, run, run_style respa, units

16.124.6 Default

choice of units time units default timestep size

lj τ 0.005 τ
real fs 1.0 fs
metal ps 0.001 ps
si s 1.0e-8 s (10 ns)
cgs s 1.0e-8 s (10 ns)
electron fs 0.001 fs
micro µs 2.0 µs
nano ns 0.00045 ns

16.125 uncompute command

16.125.1 Syntax

uncompute compute-ID

• compute-ID = ID of a previously defined compute

16.125.2 Examples

uncompute 2
uncompute lower-boundary

16.125.3 Description

Delete a compute that was previously defined with a compute command. This also wipes out any additional changes
made to the compute via the compute_modify command.

16.125.4 Restrictions

none

16.125. uncompute command 979

LAMMPS Documentation, Release stable 29Sep2021

16.125.5 Related commands

compute

16.125.6 Default

none

16.126 undump command

16.126.1 Syntax

undump dump-ID

• dump-ID = ID of previously defined dump

16.126.2 Examples

undump mine
undump 2

16.126.3 Description

Turn off a previously defined dump so that it is no longer active. This closes the file associated with the dump.

16.126.4 Restrictions

none

16.126.5 Related commands

dump

16.126.6 Default

none

980 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.127 unfix command

16.127.1 Syntax

unfix fix-ID

• fix-ID = ID of a previously defined fix

16.127.2 Examples

unfix 2
unfix lower-boundary

16.127.3 Description

Delete a fix that was previously defined with a fix command. This also wipes out any additional changes made to the
fix via the fix_modify command.

16.127.4 Restrictions

none

16.127.5 Related commands

fix

16.127.6 Default

none

16.128 units command

16.128.1 Syntax

units style

• style = lj or real or metal or si or cgs or electron or micro or nano

16.127. unfix command 981

LAMMPS Documentation, Release stable 29Sep2021

16.128.2 Examples

units metal
units lj

16.128.3 Description

This command sets the style of units used for a simulation. It determines the units of all quantities specified in the input
script and data file, as well as quantities output to the screen, log file, and dump files. Typically, this command is used
at the very beginning of an input script.
For all units except lj, LAMMPS uses physical constants from www.physics.nist.gov. For the definition of Kcal in real
units, LAMMPS uses the thermochemical calorie = 4.184 J.
The choice you make for units simply sets some internal conversion factors within LAMMPS. This means that any
simulation you perform for one choice of units can be duplicated with any other unit setting LAMMPS supports. In
this context “duplicate” means the particles will have identical trajectories and all output generated by the simulation
will be identical. This will be the case for some number of timesteps until round-off effects accumulate, since the
conversion factors for two different unit systems are not identical to infinite precision.
To perform the same simulation in a different set of units you must change all the unit-based input parameters in your
input script and other input files (data file, potential files, etc) correctly to the new units. And you must correctly convert
all output from the new units to the old units when comparing to the original results. That is often not simple to do.
Potential or table files may have a UNITS: tag included in the first line indicating the unit style those files were created
for. If the tag exists, its value will be compared to the chosen unit style and LAMMPS will stop with an error message
if there is a mismatch. In some select cases and for specific combinations of unit styles, LAMMPS is capable of
automatically converting potential parameters from a file. In those cases, a warning message signaling that an automatic
conversion has happened is printed to the screen.

For style lj, all quantities are unitless. Without loss of generality, LAMMPS sets the fundamental quantities mass, σ, ,
and the Boltzmann constant kB = 1. The masses, distances, energies you specify are multiples of these fundamental
values. The formulas relating the reduced or unitless quantity (with an asterisk) to the same quantity with units is also
given. Thus you can use the mass, σ, and  values for a specific material and convert the results from a unitless LJ
simulation into physical quantities. Please note that using these three properties as base, your unit of time has to conform
2 kg·m2
to the relation  = mσ τ 2 since energy is a derived unit (in SI units you equivalently have the relation 1J = 1 s2 ).

• mass = mass or m, where M ∗ = M

m

• distance = σ, where x∗ = σx
• time = τ , where τ ∗ = τ mσ
p 
2

• energy = , where E ∗ = E


• velocity = στ , where v ∗ = v στ
• force = σ , where f ∗ = f σ
• torque = , where t∗ = t


• temperature = reduced LJ temperature, where T ∗ = T kB


3
• pressure = reduced LJ pressure, where p∗ = p σ
3
• dynamic viscosity = reduced LJ viscosity, where η ∗ = η στ
• charge = reduced LJ charge, where q ∗ = q √4πε
1
0 σ

982 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• dipole = reduced LJ dipole, moment where µ∗ = µ √4πε1 3

0σ
√
• electric field = force/charge, where E ∗ = E 4πε0 σσ

dim
• density = mass/volume, where ρ∗ = ρ σ m
Note that for LJ units, the default mode of thermodynamic output via the thermo_style command is to normalize all
extensive quantities by the number of atoms. E.g. potential energy is extensive because it is summed over atoms, so
it is output as energy/atom. Temperature is intensive since it is already normalized by the number of atoms, so it is
output as-is. This behavior can be changed via the thermo_modify norm command.
For style real, these are the units:
• mass = grams/mole
• distance = Angstroms
• time = femtoseconds
• energy = Kcal/mole
• velocity = Angstroms/femtosecond
• force = Kcal/mole-Angstrom
• torque = Kcal/mole
• temperature = Kelvin
• pressure = atmospheres
• dynamic viscosity = Poise
• charge = multiple of electron charge (1.0 is a proton)
• dipole = charge*Angstroms
• electric field = volts/Angstrom
• density = gram/cm^dim
For style metal, these are the units:
• mass = grams/mole
• distance = Angstroms
• time = picoseconds
• energy = eV
• velocity = Angstroms/picosecond
• force = eV/Angstrom
• torque = eV
• temperature = Kelvin
• pressure = bars
• dynamic viscosity = Poise
• charge = multiple of electron charge (1.0 is a proton)
• dipole = charge*Angstroms
• electric field = volts/Angstrom
• density = gram/cm^dim

16.128. units command 983

LAMMPS Documentation, Release stable 29Sep2021

For style si, these are the units:

• mass = kilograms
• distance = meters
• time = seconds
• energy = Joules
• velocity = meters/second
• force = Newtons
• torque = Newton-meters
• temperature = Kelvin
• pressure = Pascals
• dynamic viscosity = Pascal*second
• charge = Coulombs (1.6021765e-19 is a proton)
• dipole = Coulombs*meters
• electric field = volts/meter
• density = kilograms/meter^dim
For style cgs, these are the units:
• mass = grams
• distance = centimeters
• time = seconds
• energy = ergs
• velocity = centimeters/second
• force = dynes
• torque = dyne-centimeters
• temperature = Kelvin
• pressure = dyne/cm^2 or barye = 1.0e-6 bars
• dynamic viscosity = Poise
• charge = statcoulombs or esu (4.8032044e-10 is a proton)
• dipole = statcoul-cm = 10^18 debye
• electric field = statvolt/cm or dyne/esu
• density = grams/cm^dim
For style electron, these are the units:
• mass = atomic mass units
• distance = Bohr
• time = femtoseconds
• energy = Hartrees
• velocity = Bohr/atomic time units [1.03275e-15 seconds]

984 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

• force = Hartrees/Bohr
• temperature = Kelvin
• pressure = Pascals
• charge = multiple of electron charge (1.0 is a proton)
• dipole moment = Debye
• electric field = volts/cm
For style micro, these are the units:
• mass = picograms
• distance = micrometers
• time = microseconds
• energy = picogram-micrometer^2/microsecond^2
• velocity = micrometers/microsecond
• force = picogram-micrometer/microsecond^2
• torque = picogram-micrometer^2/microsecond^2
• temperature = Kelvin
• pressure = picogram/(micrometer-microsecond^2)
• dynamic viscosity = picogram/(micrometer-microsecond)
• charge = picocoulombs (1.6021765e-7 is a proton)
• dipole = picocoulomb-micrometer
• electric field = volt/micrometer
• density = picograms/micrometer^dim
For style nano, these are the units:
• mass = attograms
• distance = nanometers
• time = nanoseconds
• energy = attogram-nanometer^2/nanosecond^2
• velocity = nanometers/nanosecond
• force = attogram-nanometer/nanosecond^2
• torque = attogram-nanometer^2/nanosecond^2
• temperature = Kelvin
• pressure = attogram/(nanometer-nanosecond^2)
• dynamic viscosity = attogram/(nanometer-nanosecond)
• charge = multiple of electron charge (1.0 is a proton)
• dipole = charge-nanometer
• electric field = volt/nanometer
• density = attograms/nanometer^dim

16.128. units command 985

LAMMPS Documentation, Release stable 29Sep2021

The units command also sets the timestep size and neighbor skin distance to default values for each style:
• For style lj these are dt = 0.005 τ and skin = 0.3 σ.
• For style real these are dt = 1.0 femtoseconds and skin = 2.0 Angstroms.
• For style metal these are dt = 0.001 picoseconds and skin = 2.0 Angstroms.
• For style si these are dt = 1.0e-8 seconds and skin = 0.001 meters.
• For style cgs these are dt = 1.0e-8 seconds and skin = 0.1 centimeters.
• For style electron these are dt = 0.001 femtoseconds and skin = 2.0 Bohr.
• For style micro these are dt = 2.0 microseconds and skin = 0.1 micrometers.
• For style nano these are dt = 0.00045 nanoseconds and skin = 0.1 nanometers.

16.128.4 Restrictions

This command cannot be used after the simulation box is defined by a read_data or create_box command.

16.128.5 Related commands

none

16.128.6 Default

units lj

16.129 variable command

16.129.1 Syntax

variable name style args ...

• name = name of variable to define

• style = delete or index or loop or world or universe or uloop or string or format or getenv or file or atomfile or
python or internal or equal or vector or atom
delete = no args
index args = one or more strings
loop args = N
N = integer size of loop, loop from 1 to N inclusive
loop args = N pad
N = integer size of loop, loop from 1 to N inclusive
pad = all values will be same length, e.g. 001, 002, ..., 100
loop args = N1 N2
N1,N2 = loop from N1 to N2 inclusive
loop args = N1 N2 pad
N1,N2 = loop from N1 to N2 inclusive
pad = all values will be same length, e.g. 050, 051, ..., 100

986 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

world args = one string for each partition of processors

universe args = one or more strings
uloop args = N
N = integer size of loop
uloop args = N pad
N = integer size of loop
pad = all values will be same length, e.g. 001, 002, ..., 100
string arg = one string
format args = vname fstr
vname = name of equal-style variable to evaluate
fstr = C-style format string
getenv arg = one string
file arg = filename
atomfile arg = filename
python arg = function
internal arg = numeric value
equal or vector or atom args = one formula containing numbers, thermo keywords,␣
,→math operations, group functions, atom values and vectors, compute/fix/variable␣

,→references

numbers = 0.0, 100, -5.4, 2.8e-4, etc

constants = PI, version, on, off, true, false, yes, no
thermo keywords = vol, ke, press, etc from thermo_style
math operators = (), -x, x+y, x-y, x*y, x/y, x^y, x%y,
x == y, x != y, x < y, x <= y, x > y, x >= y, x && y, x || y, x␣
,→|^ y, !x

math functions = sqrt(x), exp(x), ln(x), log(x), abs(x),

sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x),
random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x)
ramp(x,y), stagger(x,y), logfreq(x,y,z), logfreq2(x,y,z),
logfreq3(x,y,z), stride(x,y,z), stride2(x,y,z,a,b,c),
vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z)
group functions = count(group), mass(group), charge(group),
xcm(group,dim), vcm(group,dim), fcm(group,dim),
bound(group,dir), gyration(group), ke(group),
angmom(group,dim), torque(group,dim),
inertia(group,dimdim), omega(group,dim)
region functions = count(group,region), mass(group,region), charge(group,region),
xcm(group,dim,region), vcm(group,dim,region), fcm(group,dim,
,→region),

bound(group,dir,region), gyration(group,region), ke(group,

,→reigon),

angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x),␣
,→rmask(x), grmask(x,y), next(x), is_file(name)

feature functions = is_available(category,feature), is_active(category,feature),␣

,→is_defined(category,id)

atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i],␣
,→vz[i], fx[i], fy[i], fz[i], q[i]

atom vector = id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q
compute references = c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i]
fix references = f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i]
variable references = v_name, v_name[i]

16.129. variable command 987

LAMMPS Documentation, Release stable 29Sep2021

16.129.2 Examples

variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop $n
variable beta equal temp/3.0
variable b1 equal x[234]+0.5*vol
variable b1 equal "x[234] + 0.5*vol"
variable b equal xcm(mol1,x)/2.0
variable b equal c_myTemp
variable b atom x*y/vol
variable foo string myfile
variable foo internal 3.5
variable myPy python increase
variable f file values.txt
variable temp world 300.0 310.0 320.0 ${Tfinal}
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15 pad
variable str format x %.6g
variable x delete

16.129.3 Description

This command assigns one or more strings to a variable name for evaluation later in the input script or during a simu-
lation.
Variables can thus be useful in several contexts. A variable can be defined and then referenced elsewhere in an input
script to become part of a new input command. For variable styles that store multiple strings, the next command can
be used to increment which string is assigned to the variable. Variables of style equal store a formula which when
evaluated produces a single numeric value which can be output either directly (see the print, fix print, and run every
commands) or as part of thermodynamic output (see the thermo_style command), or used as input to an averaging fix
(see the fix ave/time command). Variables of style vector store a formula which produces a vector of such values which
can be used as input to various averaging fixes, or elements of which can be part of thermodynamic output. Variables
of style atom store a formula which when evaluated produces one numeric value per atom which can be output to a
dump file (see the dump custom command) or used as input to an averaging fix (see the fix ave/chunk and fix ave/atom
commands). Variables of style atomfile can be used anywhere in an input script that atom-style variables are used; they
get their per-atom values from a file rather than from a formula. Variables of style python can be hooked to Python
functions using code you provide, so that the variable gets its value from the evaluation of the Python code. Variables
of style internal are used by a few commands which set their value directly.

Note: As discussed on the Commands parse doc page, an input script can use “immediate” variables, specified as
$(formula) with parenthesis, where the formula has the same syntax as equal-style variables described on this page.
This is a convenient way to evaluate a formula immediately without using the variable command to define a named
variable and then evaluate that variable. See below for a more detailed discussion of this feature.

In the discussion that follows, the “name” of the variable is the arbitrary string that is the first argument in the variable
command. This name can only contain alphanumeric characters and underscores. The “string” is one or more of the
subsequent arguments. The “string” can be simple text as in the first example above, it can contain other variables as in
the second example, or it can be a formula as in the third example. The “value” is the numeric quantity resulting from
evaluation of the string. Note that the same string can generate different values when it is evaluated at different times
during a simulation.

988 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Note: When an input script line is encountered that defines a variable of style equal or vector or atom or python that
contains a formula or Python code, the formula is NOT immediately evaluated. It will be evaluated every time when
the variable is used instead. If you simply want to evaluate a formula in place you can use as so-called. See the section
below about “Immediate Evaluation of Variables” for more details on the topic. This is also true of a format style
variable since it evaluates another variable when it is invoked.

Variables of style equal and vector and atom can be used as inputs to various other commands which evaluate their
formulas as needed, e.g. at different timesteps during a run.
Variables of style internal can be used in place of an equal-style variable, except by commands that set the value stored
by the internal-style variable. Thus any command that states it can use an equal-style variable as an argument, can
also use an internal-style variable. This means that when the command evaluates the variable, it will use the value set
(internally) by another command.
Variables of style python can be used in place of an equal-style variable so long as the associated Python function,
as defined by the python command, returns a numeric value. Thus any command that states it can use an equal-style
variable as an argument, can also use such a python-style variable. This means that when the LAMMPS command
evaluates the variable, the Python function will be executed.

Note: When a variable command is encountered in the input script and the variable name has already been specified,
the command is ignored. This means variables can NOT be re-defined in an input script (with two exceptions, read
further). This is to allow an input script to be processed multiple times without resetting the variables; see the jump or
include commands. It also means that using the command-line switch -var will override a corresponding index variable
setting in the input script.

There are two exceptions to this rule. First, variables of style string, getenv, internal, equal, vector, atom, and python
ARE redefined each time the command is encountered. This allows these style of variables to be redefined multiple
times in an input script. In a loop, this means the formula associated with an equal or atom style variable can change
if it contains a substitution for another variable, e.g. $x or v_x.
Second, as described below, if a variable is iterated on to the end of its list of strings via the next command, it is removed
from the list of active variables, and is thus available to be re-defined in a subsequent variable command. The delete
style does the same thing.

The Commands parse page explains how occurrences of a variable name in an input script line are replaced by the
variable’s string. The variable name can be referenced as $x if the name “x” is a single character, or as ${LoopVar} if
the name “LoopVar” is one or more characters.
As described below, for variable styles index, loop, file, universe, and uloop, which string is assigned to a variable can
be incremented via the next command. When there are no more strings to assign, the variable is exhausted and a flag
is set that causes the next jump command encountered in the input script to be skipped. This enables the construction
of simple loops in the input script that are iterated over and then exited from.
As explained above, an exhausted variable can be re-used in an input script. The delete style also removes the variable,
the same as if it were exhausted, allowing it to be redefined later in the input script or when the input script is looped
over. This can be useful when breaking out of a loop via the if and jump commands before the variable would become
exhausted. For example,

label loop
variable a loop 5
print "A = $a"
if "$a > 2" then "jump in.script break"
(continues on next page)

16.129. variable command 989

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

next a
jump in.script loop
label break
variable a delete

This section describes how all the various variable styles are defined and what they store. Except for the equal and
vector and atom styles, which are explained in the next section.
Many of the styles store one or more strings. Note that a single string can contain spaces (multiple words), if it is
enclosed in quotes in the variable command. When the variable is substituted for in another input script command, its
returned string will then be interpreted as multiple arguments in the expanded command.
For the index style, one or more strings are specified. Initially, the first string is assigned to the variable. Each time a
next command is used with the variable name, the next string is assigned. All processors assign the same string to the
variable.
Index style variables with a single string value can also be set by using the command-line switch -var.
The loop style is identical to the index style except that the strings are the integers from 1 to N inclusive, if only one
argument N is specified. This allows generation of a long list of runs (e.g. 1000) without having to list N strings in the
input script. Initially, the string “1” is assigned to the variable. Each time a next command is used with the variable
name, the next string (“2”, “3”, etc) is assigned. All processors assign the same string to the variable. The loop style
can also be specified with two arguments N1 and N2. In this case the loop runs from N1 to N2 inclusive, and the string
N1 is initially assigned to the variable. N1 <= N2 and N2 >= 0 is required.
For the world style, one or more strings are specified. There must be one string for each processor partition or “world”.
LAMMPS can be run with multiple partitions via the -partition command-line switch. This variable command assigns
one string to each world. All processors in the world are assigned the same string. The next command cannot be used
with equal style variables, since there is only one value per world. This style of variable is useful when you wish to
run different simulations on different partitions, or when performing a parallel tempering simulation (see the temper
command), to assign different temperatures to different partitions.
For the universe style, one or more strings are specified. There must be at least as many strings as there are processor
partitions or “worlds”. LAMMPS can be run with multiple partitions via the -partition command-line switch. This
variable command initially assigns one string to each world. When a next command is encountered using this variable,
the first processor partition to encounter it, is assigned the next available string. This continues until all the variable
strings are consumed. Thus, this command can be used to run 50 simulations on 8 processor partitions. The simulations
will be run one after the other on whatever partition becomes available, until they are all finished. Universe style
variables are incremented using the files “tmp.lammps.variable” and “tmp.lammps.variable.lock” which you will see
in your directory during such a LAMMPS run.
The uloop style is identical to the universe style except that the strings are the integers from 1 to N. This allows generation
of long list of runs (e.g. 1000) without having to list N strings in the input script.
For the string style, a single string is assigned to the variable. Two differences between this style and using the index
style exist: a variable with string style can be redefined, e.g. by another command later in the input script, or if the script
is read again in a loop. The other difference is that string performs variable substitution even if the string parameter is
quoted.
For the format style, an equal-style variable is specified along with a C-style format string, e.g. “%f” or “%.10g”,
which must be appropriate for formatting a double-precision floating-point value. The default format is “%.15g”. This
variable style allows an equal-style variable to be formatted precisely when it is evaluated.
If you simply wish to print a variable value with desired precision to the screen or logfile via the print or fix print
commands, you can also do this by specifying an “immediate” variable with a trailing colon and format string, as part
of the string argument of those commands. This is explained on the Commands parse doc page.

990 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

For the getenv style, a single string is assigned to the variable which should be the name of an environment variable.
When the variable is evaluated, it returns the value of the environment variable, or an empty string if it not defined.
This style of variable can be used to adapt the behavior of LAMMPS input scripts via environment variable settings, or
to retrieve information that has been previously stored with the shell putenv command. Note that because environment
variable settings are stored by the operating systems, they persist beyond a clear command.
For the file style, a filename is provided which contains a list of strings to assign to the variable, one per line. The strings
can be numeric values if desired. See the discussion of the next() function below for equal-style variables, which will
convert the string of a file-style variable into a numeric value in a formula.
When a file-style variable is defined, the file is opened and the string on the first line is read and stored with the variable.
This means the variable can then be evaluated as many times as desired and will return that string. There are two ways
to cause the next string from the file to be read: use the next command or the next() function in an equal- or atom-style
variable, as discussed below.
The rules for formatting the file are as follows. A comment character “#” can be used anywhere on a line; text starting
with the comment character is stripped. Blank lines are skipped. The first “word” of a non-blank line, delimited by
white-space, is the “string” assigned to the variable.
For the atomfile style, a filename is provided which contains one or more sets of values, to assign on a per-atom basis
to the variable. The format of the file is described below.
When an atomfile-style variable is defined, the file is opened and the first set of per-atom values are read and stored
with the variable. This means the variable can then be evaluated as many times as desired and will return those values.
There are two ways to cause the next set of per-atom values from the file to be read: use the next command or the next()
function in an atom-style variable, as discussed below.
The rules for formatting the file are as follows. Each time a set of per-atom values is read, a non-blank line is searched
for in the file. The file is read line by line but only up to 254 characters are used. The rest are ignored. A comment
character “#” can be used anywhere on a line and all text following and the “#” character are ignored; text starting
with the comment character is stripped. Blank lines are skipped. The first “word” of a non-blank line, delimited by
white-space, is read as the count N of per-atom lines to immediately follow. N can be the total number of atoms in the
system, or only a subset. The next N lines have the following format

ID value

where ID is an atom ID and value is the per-atom numeric value that will be assigned to that atom. IDs can be listed in
any order.

Note: Every time a set of per-atom lines is read, the value for all atoms is first set to 0.0. Thus values for atoms whose
ID does not appear in the set, will remain 0.0.

For the python style a Python function name is provided. This needs to match a function name specified in a python
command which returns a value to this variable as defined by its return keyword. For example these two commands
would be self-consistent:

variable foo python myMultiply

python myMultiply return v_foo format f file funcs.py

The two commands can appear in either order so long as both are specified before the Python function is invoked for
the first time.
Each time the variable is evaluated, the associated Python function is invoked, and the value it returns is also returned
by the variable. Since the Python function can use other LAMMPS variables as input, or query interal LAMMPS
quantities to perform its computation, this means the variable can return a different value each time it is evaluated.

16.129. variable command 991

LAMMPS Documentation, Release stable 29Sep2021

The type of value stored in the variable is determined by the format keyword of the python command. It can be an
integer (i), floating point (f), or string (s) value. As mentioned above, if it is a numeric value (integer or floating point),
then the python-style variable can be used in place of an equal-style variable anywhere in an input script, e.g. as an
argument to another command that allows for equal-style variables.
For the internal style a numeric value is provided. This value will be assigned to the variable until a LAMMPS
command sets it to a new value. There are currently only two LAMMPS commands that require internal variables as
inputs, because they reset them: create_atoms and fix controller. As mentioned above, an internal-style variable can
be used in place of an equal-style variable anywhere else in an input script, e.g. as an argument to another command
that allows for equal-style variables.

For the equal and vector and atom styles, a single string is specified which represents a formula that will be evaluated
afresh each time the variable is used. If you want spaces in the string, enclose it in double quotes so the parser will treat
it as a single argument. For equal-style variables the formula computes a scalar quantity, which becomes the value of
the variable whenever it is evaluated. For vector-style variables the formula must compute a vector of quantities, which
becomes the value of the variable whenever it is evaluated. The calculated vector can be of length one, but it cannot
be a simple scalar value like that produced by an equal-style compute. I.e. the formula for a vector-style variable must
have at least one quantity in it that refers to a global vector produced by a compute, fix, or other vector-style variable.
For atom-style variables the formula computes one quantity for each atom whenever it is evaluated.
Note that equal, vector, and atom variables can produce different values at different stages of the input script or at
different times during a run. For example, if an equal variable is used in a fix print command, different values could be
printed each timestep it was invoked. If you want a variable to be evaluated immediately, so that the result is stored by
the variable instead of the string, see the section below on “Immediate Evaluation of Variables”.
The next command cannot be used with equal or vector or atom style variables, since there is only one string.
The formula for an equal, vector, or atom variable can contain a variety of quantities. The syntax for each kind of
quantity is simple, but multiple quantities can be nested and combined in various ways to build up formulas of arbitrary
complexity. For example, this is a valid (though strange) variable formula:

variable x equal "pe + c_MyTemp / vol^(1/3)"

Specifically, a formula can contain numbers, constants, thermo keywords, math operators, math functions, group func-
tions, region functions, atom values, atom vectors, compute references, fix references, and references to other variables.

992 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Num- 0.2, 100, 1.0e20, -15.4, etc

ber
Con- PI, version, on, off, true, false, yes, no
stant
Thermo vol, pe, ebond, etc
key-
words
Math (), -x, x+y, x-y, x*y, x/y, x^y, x%y, x == y, x != y, x < y, x <= y, x > y, x >= y, x && y, x || y, x |^ y, !x
opera-
tors
Math sqrt(x), exp(x), ln(x), log(x), abs(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x),
func- random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z),
tions logfreq2(x,y,z), logfreq3(x,y,z), stride(x,y,z), stride2(x,y,z,a,b,c), vdisplace(x,y), swiggle(x,y,z), cwig-
gle(x,y,z)
Group count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID),
func- ke(ID), angmom(ID,dim), torque(ID,dim), inertia(ID,dimdim), omega(ID,dim)
tions
Re- count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR),
gion bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), iner-
func- tia(ID,dimdim,IDR), omega(ID,dim,IDR)
tions
Spe- sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x)
cial
func-
tions
Atom id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i]
values
Atom id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q
vec-
tors
Com- c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i]
pute
refer-
ences
Fix f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i]
refer-
ences
Other v_name, v_name[i]
vari-
ables

Most of the formula elements produce a scalar value. Some produce a global or per-atom vector of values. Global
vectors can be produced by computes or fixes or by other vector-style variables. Per-atom vectors are produced by
atom vectors, compute references that represent a per-atom vector, fix references that represent a per-atom vector, and
variables that are atom-style variables. Math functions that operate on scalar values produce a scalar value; math
function that operate on global or per-atom vectors do so element-by-element and produce a global or per-atom vector.
A formula for equal-style variables cannot use any formula element that produces a global or per-atom vector. A
formula for a vector-style variable can use formula elements that produce either a scalar value or a global vector value,
but cannot use a formula element that produces a per-atom vector. A formula for an atom-style variable can use formula
elements that produce either a scalar value or a per-atom vector, but not one that produces a global vector. Atom-style
variables are evaluated by other commands that define a group on which they operate, e.g. a dump or compute or fix
command. When they invoke the atom-style variable, only atoms in the group are included in the formula evaluation.

16.129. variable command 993

LAMMPS Documentation, Release stable 29Sep2021

The variable evaluates to 0.0 for atoms not in the group.

Numbers, constants, and thermo keywords

Numbers can contain digits, scientific notation (3.0e20,3.0e-20,3.0E20,3.0E-20), and leading minus signs.
Constants are set at compile time and cannot be changed. PI will return the number 3.14159265358979323846; on,
true or yes will return 1.0; off, false or no will return 0.0; version will return a numeric version code of the current
LAMMPS version (e.g. version 2 Sep 2015 will return the number 20150902). The corresponding value for newer
versions of LAMMPS will be larger, for older versions of LAMMPS will be smaller. This can be used to have input
scripts adapt automatically to LAMMPS versions, when non-backwards compatible syntax changes are introduced.
Here is an illustrative example (which will not work, since the version has been introduced more recently):

if $(version<20140513) then "communicate vel yes" else "comm_modify vel yes"

The thermo keywords allowed in a formula are those defined by the thermo_style custom command. Thermo keywords
that require a compute to calculate their values such as “temp” or “press”, use computes stored and invoked by the
thermo_style command. This means that you can only use those keywords in a variable if the style you are using
with the thermo_style command (and the thermo keywords associated with that style) also define and use the needed
compute. Note that some thermo keywords use a compute indirectly to calculate their value (e.g. the enthalpy keyword
uses temp, pe, and pressure). If a variable is evaluated directly in an input script (not during a run), then the values
accessed by the thermo keyword must be current. See the discussion below about “Variable Accuracy”.

Math Operators

Math operators are written in the usual way, where the “x” and “y” in the examples can themselves be arbitrarily
complex formulas, as in the examples above. In this syntax, “x” and “y” can be scalar values or per-atom vectors. For
example, “ke/natoms” is the division of two scalars, where “vy+vz” is the element-by-element sum of two per-atom
vectors of y and z velocities.
Operators are evaluated left to right and have the usual C-style precedence: unary minus and unary logical NOT operator
“!” have the highest precedence, exponentiation “^” is next; multiplication and division and the modulo operator “%”
are next; addition and subtraction are next; the 4 relational operators “<”, “<=”, “>”, and “>=” are next; the two
remaining relational operators “==” and “!=” are next; then the logical AND operator “&&”; and finally the logical
OR operator “||” and logical XOR (exclusive or) operator “|^” have the lowest precedence. Parenthesis can be used to
group one or more portions of a formula and/or enforce a different order of evaluation than what would occur with the
default precedence.

Note: Because a unary minus is higher precedence than exponentiation, the formula “-2^2” will evaluate to 4, not -4.
This convention is compatible with some programming languages, but not others. As mentioned, this behavior can be
easily overridden with parenthesis; the formula “-(2^2)” will evaluate to -4.

The 6 relational operators return either a 1.0 or 0.0 depending on whether the relationship between x and y is TRUE
or FALSE. For example the expression x<10.0 in an atom-style variable formula will return 1.0 for all atoms whose
x-coordinate is less than 10.0, and 0.0 for the others. The logical AND operator will return 1.0 if both its arguments
are non-zero, else it returns 0.0. The logical OR operator will return 1.0 if either of its arguments is non-zero, else
it returns 0.0. The logical XOR operator will return 1.0 if one of its arguments is zero and the other non-zero, else it
returns 0.0. The logical NOT operator returns 1.0 if its argument is 0.0, else it returns 0.0.

994 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

These relational and logical operators can be used as a masking or selection operation in a formula. For example, the
number of atoms whose properties satisfy one or more criteria could be calculated by taking the returned per-atom
vector of ones and zeroes and passing it to the compute reduce command.

Math Functions

Math functions are specified as keywords followed by one or more parenthesized arguments “x”, “y”, “z”, each of
which can themselves be arbitrarily complex formulas. In this syntax, the arguments can represent scalar values or
global vectors or per-atom vectors. In the latter case, the math operation is performed on each element of the vector.
For example, “sqrt(natoms)” is the sqrt() of a scalar, where “sqrt(y*z)” yields a per-atom vector with each element
being the sqrt() of the product of one atom’s y and z coordinates.
Most of the math functions perform obvious operations. The ln() is the natural log; log() is the base 10 log.
The random(x,y,z) function takes 3 arguments: x = lo, y = hi, and z = seed. It generates a uniform random number
between lo and hi. The normal(x,y,z) function also takes 3 arguments: x = mu, y = sigma, and z = seed. It generates
a Gaussian variate centered on mu with variance sigma^2. In both cases the seed is used the first time the internal
random number generator is invoked, to initialize it. For equal-style and vector-style variables, every processor uses
the same seed so that they each generate the same sequence of random numbers. For atom-style variables, a unique
seed is created for each processor, based on the specified seed. This effectively generates a different random number
for each atom being looped over in the atom-style variable.

Note: Internally, there is just one random number generator for all equal-style and vector-style variables and another
one for all atom-style variables. If you define multiple variables (of each style) which use the random() or normal()
math functions, then the internal random number generators will only be initialized once, which means only one of the
specified seeds will determine the sequence of generated random numbers.

The ceil(), floor(), and round() functions are those in the C math library. Ceil() is the smallest integer not less than its
argument. Floor() if the largest integer not greater than its argument. Round() is the nearest integer to its argument.
The ramp(x,y) function uses the current timestep to generate a value linearly interpolated between the specified x,y
values over the course of a run, according to this formula:
value = x + (y-x) * (timestep-startstep) / (stopstep-startstep)
The run begins on startstep and ends on stopstep. Startstep and stopstep can span multiple runs, using the start and
stop keywords of the run command. See the run command for details of how to do this.
The stagger(x,y) function uses the current timestep to generate a new timestep. X,y > 0 and x > y are required. The gen-
erated timesteps increase in a staggered fashion, as the sequence x,x+y,2x,2x+y,3x,3x+y,etc. For any current timestep,
the next timestep in the sequence is returned. Thus if stagger(1000,100) is used in a variable by the dump_modify every
command, it will generate the sequence of output timesteps:

100,1000,1100,2000,2100,3000,etc

The logfreq(x,y,z) function uses the current timestep to generate a new timestep. X,y,z > 0 and y < z are re-
quired. The generated timesteps are on a base-z logarithmic scale, starting with x, and the y value is how many
of the z-1 possible timesteps within one logarithmic interval are generated. I.e. the timesteps follow the sequence
x,2x,3x,. . . y*x,x*z,2x*z,3x*z,. . . y*x*z,x*z^2,2x*z^2,etc. For any current timestep, the next timestep in the sequence
is returned. Thus if logfreq(100,4,10) is used in a variable by the dump_modify every command, it will generate this
sequence of output timesteps:

100,200,300,400,1000,2000,3000,4000,10000,20000,etc

16.129. variable command 995

LAMMPS Documentation, Release stable 29Sep2021

The logfreq2(x,y,z) function is similar to logfreq, except a single logarithmic interval is divided into y equally-spaced
timesteps and all of them are output. Y < z is not required. Thus, if logfreq2(100,18,10) is used in a variable by the
dump_modify every command, then the interval between 100 and 1000 is divided as 900/18 = 50 steps, and it will
generate the sequence of output timesteps:

100,150,200,...950,1000,1500,2000,...9500,10000,15000,etc

The logfreq3(x,y,z) function generates y points between x and z (inclusive), that are separated by a multiplicative ratio:
(z/x)^(1/(y-1)). Constraints are: x,z > 0, y > 1, z-x >= y-1. For eg., if logfreq3(10,25,1000) is used in a variable by the
fix print command, then the interval between 10 and 1000 is divided into 24 parts with a multiplicative separation of
~1.21, and it will generate the following sequence of output timesteps:

10, 13, 15, 18, 22, 27, 32,...384, 465, 563, 682, 826, 1000

The stride(x,y,z) function uses the current timestep to generate a new timestep. X,y >= 0 and z > 0 and x <= y are re-
quired. The generated timesteps increase in increments of z, from x to y, i.e. it generates the sequence x,x+z,x+2z,. . . ,y.
If y-x is not a multiple of z, then similar to the way a for loop operates, the last value will be one that does not exceed
y. For any current timestep, the next timestep in the sequence is returned. Thus if stride(1000,2000,100) is used in a
variable by the dump_modify every command, it will generate the sequence of output timesteps:

1000,1100,1200, ... ,1900,2000

The stride2(x,y,z,a,b,c) function is similar to the stride() function except it generates two sets of strided timesteps, one
at a coarser level and one at a finer level. Thus it is useful for debugging, e.g. to produce output every timestep at the
point in simulation when a problem occurs. X,y >= 0 and z > 0 and x <= y are required, as are a,b >= 0 and c > 0 and a
< b. Also, a >= x and b <= y are required so that the second stride is inside the first. The generated timesteps increase
in increments of z, starting at x, until a is reached. At that point the timestep increases in increments of c, from a to b,
then after b, increments by z are resumed until y is reached. For any current timestep, the next timestep in the sequence
is returned. Thus if stride2(1000,2000,100,1350,1360,1) is used in a variable by the dump_modify every command, it
will generate the sequence of output timesteps:

1000,1100,1200,1300,1350,1351,1352, ... 1359,1360,1400,1500, ... ,2000

The vdisplace(x,y) function takes 2 arguments: x = value0 and y = velocity, and uses the elapsed time to change the
value by a linear displacement due to the applied velocity over the course of a run, according to this formula:
value = value0 + velocity*(timestep-startstep)*dt
where dt = the timestep size.
The run begins on startstep. Startstep can span multiple runs, using the start keyword of the run command. See the
run command for details of how to do this. Note that the thermo_style keyword elaplong = timestep-startstep.
The swiggle(x,y,z) and cwiggle(x,y,z) functions each take 3 arguments: x = value0, y = amplitude, z = period. They
use the elapsed time to oscillate the value by a sin() or cos() function over the course of a run, according to one of these
formulas, where omega = 2 PI / period:
value = value0 + Amplitude * sin(omega*(timestep-startstep)*dt)
value = value0 + Amplitude * (1 - cos(omega*(timestep-startstep)*dt))
where dt = the timestep size.
The run begins on startstep. Startstep can span multiple runs, using the start keyword of the run command. See the
run command for details of how to do this. Note that the thermo_style keyword elaplong = timestep-startstep.

996 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Group and Region Functions

Group functions are specified as keywords followed by one or two parenthesized arguments. The first argument ID is
the group-ID. The dim argument, if it exists, is x or y or z. The dir argument, if it exists, is xmin, xmax, ymin, ymax,
zmin, or zmax. The dimdim argument, if it exists, is xx or yy or zz or xy or yz or xz.
The group function count() is the number of atoms in the group. The group functions mass() and charge() are the total
mass and charge of the group. Xcm() and vcm() return components of the position and velocity of the center of mass
of the group. Fcm() returns a component of the total force on the group of atoms. Bound() returns the min/max of
a particular coordinate for all atoms in the group. Gyration() computes the radius-of-gyration of the group of atoms.
See the compute gyration command for a definition of the formula. Angmom() returns components of the angular
momentum of the group of atoms around its center of mass. Torque() returns components of the torque on the group
of atoms around its center of mass, based on current forces on the atoms. Inertia() returns one of 6 components of the
symmetric inertia tensor of the group of atoms around its center of mass, ordered as Ixx,Iyy,Izz,Ixy,Iyz,Ixz. Omega()
returns components of the angular velocity of the group of atoms around its center of mass.
Region functions are specified exactly the same way as group functions except they take an extra final argument IDR
which is the region ID. The function is computed for all atoms that are in both the group and the region. If the group
is “all”, then the only criteria for atom inclusion is that it be in the region.

Special Functions

Special functions take specific kinds of arguments, meaning their arguments cannot be formulas themselves.
The is_file(x) function is a test whether ‘x’ is a (readable) file and returns 1 in this case, otherwise it returns 0. For that
‘x’ is taken as a literal string and must not have any blanks in it.
The sum(x), min(x), max(x), ave(x), trap(x), and slope(x) functions each take 1 argument which is of the form “c_ID”
or “c_ID[N]” or “f_ID” or “f_ID[N]” or “v_name”. The first two are computes and the second two are fixes; the ID in
the reference should be replaced by the ID of a compute or fix defined elsewhere in the input script. The compute or fix
must produce either a global vector or array. If it produces a global vector, then the notation without “[N]” should be
used. If it produces a global array, then the notation with “[N]” should be used, when N is an integer, to specify which
column of the global array is being referenced. The last form of argument “v_name” is for a vector-style variable where
“name” is replaced by the name of the variable.
These functions operate on a global vector of inputs and reduce it to a single scalar value. This is analogous to the
operation of the compute reduce command, which performs similar operations on per-atom and local vectors.
The sum() function calculates the sum of all the vector elements. The min() and max() functions find the minimum and
maximum element respectively. The ave() function is the same as sum() except that it divides the result by the length
of the vector.
The trap() function is the same as sum() except the first and last elements are multiplied by a weighting factor of 1/2
when performing the sum. This effectively implements an integration via the trapezoidal rule on the global vector of
data. I.e. consider a set of points, equally spaced by 1 in their x coordinate: (1,V1), (2,V2), . . . , (N,VN), where the Vi
are the values in the global vector of length N. The integral from 1 to N of these points is trap(). When appropriately
normalized by the timestep size, this function is useful for calculating integrals of time-series data, like that generated
by the fix ave/correlate command.
The slope() function uses linear regression to fit a line to the set of points, equally spaced by 1 in their x coordinate:
(1,V1), (2,V2), . . . , (N,VN), where the Vi are the values in the global vector of length N. The returned value is the slope
of the line. If the line has a single point or is vertical, it returns 1.0e20.
The gmask(x) function takes 1 argument which is a group ID. It can only be used in atom-style variables. It returns a
1 for atoms that are in the group, and a 0 for atoms that are not.

16.129. variable command 997

LAMMPS Documentation, Release stable 29Sep2021

The rmask(x) function takes 1 argument which is a region ID. It can only be used in atom-style variables. It returns a
1 for atoms that are in the geometric region, and a 0 for atoms that are not.
The grmask(x,y) function takes 2 arguments. The first is a group ID, and the second is a region ID. It can only be used
in atom-style variables. It returns a 1 for atoms that are in both the group and region, and a 0 for atoms that are not in
both.
The next(x) function takes 1 argument which is a variable ID (not “v_foo”, just “foo”). It must be for a file-style or
atomfile-style variable. Each time the next() function is invoked (i.e. each time the equal-style or atom-style variable
is evaluated), the following steps occur.
For file-style variables, the current string value stored by the file-style variable is converted to a numeric value and
returned by the function. And the next string value in the file is read and stored. Note that if the line previously read
from the file was not a numeric string, then it will typically evaluate to 0.0, which is likely not what you want.
For atomfile-style variables, the current per-atom values stored by the atomfile-style variable are returned by the func-
tion. And the next set of per-atom values in the file is read and stored.
Since file-style and atomfile-style variables read and store the first line of the file or first set of per-atoms values when
they are defined in the input script, these are the value(s) that will be returned the first time the next() function is invoked.
If next() is invoked more times than there are lines or sets of lines in the file, the variable is deleted, similar to how the
next command operates.

Feature Functions

Feature functions allow to probe the running LAMMPS executable for whether specific features are either active,
defined, or available. The functions take two arguments, a category and a corresponding argument. The arguments
are strings thus cannot be formulas themselves (only $-style immediate variable expansion is possible). Return value
is either 1.0 or 0.0 depending on whether the function evaluates to true or false, respectively.
The is_active() function allows to query for active settings which are grouped by categories. Currently supported
categories and arguments are:
• package (argument = gpu or intel or kokkos or omp)
• newton (argument = pair or bond or any)
• pair (argument = single or respa or manybody or tail or shift)
• comm_style (argument = brick or tiled)
• min_style (argument = any of the compiled in minimizer styles)
• run_style (argument = any of the compiled in run styles)
• atom_style (argument = any of the compiled in atom styles)
• pair_style (argument = any of the compiled in pair styles)
• bond_style (argument = any of the compiled in bond styles)
• angle_style (argument = any of the compiled in angle styles)
• dihedral_style (argument = any of the compiled in dihedral styles)
• improper_style (argument = any of the compiled in improper styles)
• kspace_style (argument = any of the compiled in kspace styles)

998 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

Most of the settings are self-explanatory, the single argument in the pair category allows to check whether a pair style
supports a Pair::single() function as needed by compute group/group and others features or LAMMPS, respa allows to
check whether the inner/middle/outer mode of r-RESPA is supported. In the various style categories, the checking is
also done using suffix flags, if available and enabled.
Example 1: disable use of suffix for pppm when using GPU package (i.e. run it on the CPU concurrently to running
the pair style on the GPU), but do use the suffix otherwise (e.g. with OPENMP).

pair_style lj/cut/coul/long 14.0

if $(is_active(package,gpu)) then "suffix off"
kspace_style pppm

Example 2: use r-RESPA with inner/outer cutoff, if supported by pair style, otherwise fall back to using pair and
reducing the outer time step

timestep $(2.0*(1.0+2.0*is_active(pair,respa))
if $(is_active(pair,respa)) then "run_style respa 4 3 2 2 improper 1 inner 2 5.5 7.0␣
,→outer 3 kspace 4" else "run_style respa 3 3 2 improper 1 pair 2 kspace 3"

The is_defined() function allows to query categories like compute, dump, fix, group, region, and variable whether an
entry with the provided name or id is defined.
The is_available(category,name) function allows to query whether a specific optional feature is available, i.e. compiled
in. This currently works for the following categories: command, compute, fix, pair_style and feature. For all categories
except command and feature also appending active suffixes is tried before reporting failure.
The feature category is used to check the availability of compiled in features such as GZIP support, PNG support, JPEG
support, FFMPEG support, and C++ exceptions for error handling. Corresponding values for name are gzip, png, jpeg,
ffmpeg and exceptions.
This enables writing input scripts which only dump using a given format if the compiled binary supports it.

if "$(is_available(feature,png))" then "print 'PNG supported'" else "print 'PNG not␣

,→supported'"

if "$(is_available(feature,ffmpeg)" then "dump 3 all movie 25 movie.mp4 type type zoom 1.

,→6 adiam 1.0"

Atom Values and Vectors

Atom values take an integer argument I from 1 to N, where I is the atom-ID, e.g. x[243], which means use the x
coordinate of the atom with ID = 243. Or they can take a variable name, specified as v_name, where name is the name
of the variable, like x[v_myIndex]. The variable can be of any style except vector or atom or atomfile variables. The
variable is evaluated and the result is expected to be numeric and is cast to an integer (i.e. 3.4 becomes 3), to use an
index, which must be a value from 1 to N. Note that a “formula” cannot be used as the argument between the brackets,
e.g. x[243+10] or x[v_myIndex+1] are not allowed. To do this a single variable can be defined that contains the needed
formula.
Note that the 0 < atom-ID <= N, where N is the largest atom ID in the system. If an ID is specified for an atom that
does not currently exist, then the generated value is 0.0.
Atom vectors generate one value per atom, so that a reference like “vx” means the x-component of each atom’s velocity
will be used when evaluating the variable.
The meaning of the different atom values and vectors is mostly self-explanatory. Mol refers to the molecule ID of an
atom, and is only defined if an atom_style is being used that defines molecule IDs.

16.129. variable command 999

LAMMPS Documentation, Release stable 29Sep2021

Note that many other atom attributes can be used as inputs to a variable by using the compute property/atom command
and then specifying a quantity from that compute.

Compute References

Compute references access quantities calculated by a compute. The ID in the reference should be replaced by the ID
of a compute defined elsewhere in the input script. As discussed in the page for the compute command, computes can
produce global, per-atom, or local values. Only global and per-atom values can be used in a variable. Computes can
also produce a scalar, vector, or array.
An equal-style variable can only use scalar values, which means a global scalar, or an element of a global or per-atom
vector or array. A vector-style variable can use scalar values or a global vector of values, or a column of a global array
of values. Atom-style variables can use global scalar values. They can also use per-atom vector values, or a column of
a per-atom array. See the doc pages for individual computes to see what kind of values they produce.
Examples of different kinds of compute references are as follows. There is typically no ambiguity (see exception below)
as to what a reference means, since computes only produce either global or per-atom quantities, never both.

c_ID | global scalar, or per-atom vector

c_ID[I] | Ith element of global vector, or atom I’s value in per-atom vector, or Ith column from per-atom array
c_ID[I][J] | I,J element of global array, or atom I’s Jth value in per-atom array

For I and J indices, integers can be specified or a variable name, specified as v_name, where name is the name of the
variable. The rules for this syntax are the same as for the “Atom Values and Vectors” discussion above.
One source of ambiguity for compute references is when a vector-style variable refers to a compute that produces both
a global scalar and a global vector. Consider a compute with ID “foo” that does this, referenced as follows by variable
“a”, where “myVec” is another vector-style variable:

variable a vector c_foo*v_myVec

The reference “c_foo” could refer to either the global scalar or global vector produced by compute “foo”. In this case,
“c_foo” will always refer to the global scalar, and “C_foo” can be used to reference the global vector. Similarly if the
compute produces both a global vector and global array, then “c_foo[I]” will always refer to an element of the global
vector, and “C_foo[I]” can be used to reference the Ith column of the global array.
Note that if a variable containing a compute is evaluated directly in an input script (not during a run), then the values
accessed by the compute must be current. See the discussion below about “Variable Accuracy”.

Fix References

Fix references access quantities calculated by a fix. The ID in the reference should be replaced by the ID of a fix defined
elsewhere in the input script. As discussed in the page for the fix command, fixes can produce global, per-atom, or local
values. Only global and per-atom values can be used in a variable. Fixes can also produce a scalar, vector, or array.
An equal-style variable can only use scalar values, which means a global scalar, or an element of a global or per-atom
vector or array. Atom-style variables can use the same scalar values. They can also use per-atom vector values. A
vector value can be a per-atom vector itself, or a column of an per-atom array. See the doc pages for individual fixes to
see what kind of values they produce.
The different kinds of fix references are exactly the same as the compute references listed in the above table, where
“c_” is replaced by “f_”. Again, there is typically no ambiguity (see exception below) as to what a reference means,
since fixes only produce either global or per-atom quantities, never both.

1000 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

f_ID | global scalar, or per-atom vector

f_ID[I] | Ith element of global vector, or atom I’s value in per-atom vector, or Ith column from per-atom array
f_ID[I][J] | I,J element of global array, or atom I’s Jth value in per-atom array

For I and J indices, integers can be specified or a variable name, specified as v_name, where name is the name of the
variable. The rules for this syntax are the same as for the “Atom Values and Vectors” discussion above.
One source of ambiguity for fix references is the same ambiguity discussed for compute references above. Namely
when a vector-style variable refers to a fix that produces both a global scalar and a global vector. The solution is the
same as for compute references. For a fix with ID “foo”, “f_foo” will always refer to the global scalar, and “F_foo”
can be used to reference the global vector. And similarly for distinguishing between a fix’s global vector versus global
array with “f_foo[I]” versus “F_foo[I]”.
Note that if a variable containing a fix is evaluated directly in an input script (not during a run), then the values accessed
by the fix should be current. See the discussion below about “Variable Accuracy”.
Note that some fixes only generate quantities on certain timesteps. If a variable attempts to access the fix on non-allowed
timesteps, an error is generated. For example, the fix ave/time command may only generate averaged quantities every
100 steps. See the doc pages for individual fix commands for details.

Variable References

Variable references access quantities stored or calculated by other variables, which will cause those variables to be
evaluated. The name in the reference should be replaced by the name of a variable defined elsewhere in the input
script.
As discussed on this doc page, equal-style variables generate a single global numeric value, vector-style variables
generate a vector of global numeric values, and atom-style and atomfile-style variables generate a per-atom vector of
numeric values. All other variables store one or more strings.
The formula for an equal-style variable can use any style of variable including a vector_style or atom-style or atomfile-
style. For these 3 styles, a subscript must be used to access a single value from the vector-, atom-, or atomfile-style
variable. If a string-storing variable is used, the string is converted to a numeric value. Note that this will typically
produce a 0.0 if the string is not a numeric string, which is likely not what you want.
The formula for a vector-style variable can use any style of variable, including atom-style or atomfile-style variables.
For these 2 styles, a subscript must be used to access a single value from the atom-, or atomfile-style variable.
The formula for an atom-style variable can use any style of variable, including other atom-style or atomfile-style vari-
ables. If it uses a vector-style variable, a subscript must be used to access a single value from the vector-style variable.
Examples of different kinds of variable references are as follows. There is no ambiguity as to what a reference means,
since variables produce only a global scalar or global vector or per-atom vector.

v_name | global scalar from equal-style variable

v_name | global vector from vector-style variable
v_name | per-atom vector from atom-style or atomfile-style variable
v_name[I] | Ith element of a global vector from vector-style variable
v_name[I] | value of atom with ID = I from atom-style or atomfile-style variable

For the I index, an integer can be specified or a variable name, specified as v_name, where name is the name of the
variable. The rules for this syntax are the same as for the “Atom Values and Vectors” discussion above.

16.129. variable command 1001

LAMMPS Documentation, Release stable 29Sep2021

16.129.4 Immediate Evaluation of Variables

If you want an equal-style variable to be evaluated immediately, it may be the case that you do not need to define a
variable at all. See the Commands parse page for info on how to use “immediate” variables in an input script, specified
as $(formula) with parenthesis, where the formula has the same syntax as equal-style variables described on this page.
This effectively evaluates a formula immediately without using the variable command to define a named variable.
More generally, there is a difference between referencing a variable with a leading $ sign (e.g. $x or ${abc}) versus with
a leading “v_” (e.g. v_x or v_abc). The former can be used in any input script command, including a variable command.
The input script parser evaluates the reference variable immediately and substitutes its value into the command. As
explained on the Commands parse doc page, you can also use un-named “immediate” variables for this purpose. For
example, a string like this $((xlo+xhi)/2+sqrt(v_area)) in an input script command evaluates the string between the
parenthesis as an equal-style variable formula.
Referencing a variable with a leading “v_” is an optional or required kind of argument for some commands (e.g. the
fix ave/chunk or dump custom or thermo_style commands) if you wish it to evaluate a variable periodically during a
run. It can also be used in a variable formula if you wish to reference a second variable. The second variable will be
evaluated whenever the first variable is evaluated.
As an example, suppose you use this command in your input script to define the variable “v” as

variable v equal vol

before a run where the simulation box size changes. You might think this will assign the initial volume to the variable
“v”. That is not the case. Rather it assigns a formula which evaluates the volume (using the thermo_style keyword
“vol”) to the variable “v”. If you use the variable “v” in some other command like fix ave/time then the current volume
of the box will be evaluated continuously during the run.
If you want to store the initial volume of the system, you can do it this way:

variable v equal vol

variable v0 equal $v

The second command will force “v” to be evaluated (yielding the initial volume) and assign that value to the variable
“v0”. Thus the command

thermo_style custom step v_v v_v0

would print out both the current and initial volume periodically during the run.
Note that it is a mistake to enclose a variable formula in double quotes if it contains variables preceded by $ signs. For
example,

variable vratio equal "${vfinal}/${v0}"

This is because the quotes prevent variable substitution (explained on the Commands parse doc page), and thus an error
will occur when the formula for “vratio” is evaluated later.

1002 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.129.5 Variable Accuracy

Obviously, LAMMPS attempts to evaluate variables containing formulas (equal and atom style variables) accurately
whenever the evaluation is performed. Depending on what is included in the formula, this may require invoking a
compute, either directly or indirectly via a thermo keyword, or accessing a value previously calculated by a compute,
or accessing a value calculated and stored by a fix. If the compute is one that calculates the pressure or energy of the
system, then these quantities need to be tallied during the evaluation of the interatomic potentials (pair, bond, etc) on
timesteps that the variable will need the values.
LAMMPS keeps track of all of this during a run or energy minimization. An error will be generated if you attempt
to evaluate a variable on timesteps when it cannot produce accurate values. For example, if a thermo_style custom
command prints a variable which accesses values stored by a fix ave/time command and the timesteps on which thermo
output is generated are not multiples of the averaging frequency used in the fix command, then an error will occur.
An input script can also request variables be evaluated before or after or in between runs, e.g. by including them in
a print command. In this case, if a compute is needed to evaluate a variable (either directly or indirectly), LAMMPS
will not invoke the compute, but it will use a value previously calculated by the compute, and can do this only if it was
invoked on the current timestep. Fixes will always provide a quantity needed by a variable, but the quantity may or
may not be current. This leads to one of three kinds of behavior:
(1) The variable may be evaluated accurately. If it contains references to a compute or fix, and these values were
calculated on the last timestep of a preceding run, then they will be accessed and used by the variable and the result
will be accurate.
(2) LAMMPS may not be able to evaluate the variable and will generate an error message stating so. For example,
if the variable requires a quantity from a compute that has not been invoked on the current timestep, LAMMPS will
generate an error. This means, for example, that such a variable cannot be evaluated before the first run has occurred.
Likewise, in between runs, a variable containing a compute cannot be evaluated unless the compute was invoked on
the last timestep of the preceding run, e.g. by thermodynamic output.
One way to get around this problem is to perform a 0-timestep run before using the variable. For example, these
commands

variable t equal temp

print "Initial temperature = $t"
run 1000

will generate an error if the run is the first run specified in the input script, because generating a value for the “t” variable
requires a compute for calculating the temperature to be invoked.
However, this sequence of commands would be fine:

run 0
variable t equal temp
print "Initial temperature = $t"
run 1000

The 0-timestep run initializes and invokes various computes, including the one for temperature, so that the value it
stores is current and can be accessed by the variable “t” after the run has completed. Note that a 0-timestep run does
not alter the state of the system, so it does not change the input state for the 1000-timestep run that follows. Also note
that the 0-timestep run must actually use and invoke the compute in question (e.g. via thermo or dump output) in order
for it to enable the compute to be used in a variable after the run. Thus if you are trying to print a variable that uses
a compute you have defined, you can insure it is invoked on the last timestep of the preceding run by including it in
thermodynamic output.
Unlike computes, fixes will never generate an error if their values are accessed by a variable in between runs. They
always return some value to the variable. However, the value may not be what you expect if the fix has not yet calculated
the quantity of interest or it is not current. For example, the fix indent command stores the force on the indenter. But

16.129. variable command 1003

LAMMPS Documentation, Release stable 29Sep2021

this is not computed until a run is performed. Thus if a variable attempts to print this value before the first run, zeroes
will be output. Again, performing a 0-timestep run before printing the variable has the desired effect.
(3) The variable may be evaluated incorrectly and LAMMPS may have no way to detect this has occurred. Consider
the following sequence of commands:

pair_coeff 1 1 1.0 1.0

run 1000
pair_coeff 1 1 1.5 1.0
variable e equal pe
print "Final potential energy = $e"

The first run is performed using one setting for the pairwise potential defined by the pair_style and pair_coeff com-
mands. The potential energy is evaluated on the final timestep and stored by the compute pe compute (this is done by
the thermo_style command). Then a pair coefficient is changed, altering the potential energy of the system. When the
potential energy is printed via the “e” variable, LAMMPS will use the potential energy value stored by the compute
pe compute, thinking it is current. There are many other commands which could alter the state of the system between
runs, causing a variable to evaluate incorrectly.
The solution to this issue is the same as for case (2) above, namely perform a 0-timestep run before the variable is
evaluated to insure the system is up-to-date. For example, this sequence of commands would print a potential energy
that reflected the changed pairwise coefficient:

pair_coeff 1 1 1.0 1.0

run 1000
pair_coeff 1 1 1.5 1.0
run 0
variable e equal pe
print "Final potential energy = $e"

16.129.6 Restrictions

Indexing any formula element by global atom ID, such as an atom value, requires the atom style to use a global mapping
in order to look up the vector indices. By default, only atom styles with molecular information create global maps. The
atom_modify map command can override the default, e.g. for atomic-style atom styles.
All universe- and uloop-style variables defined in an input script must have the same number of values.

16.129.7 Related commands

next, jump, include, temper, fix print, print

16.129.8 Default

none

1004 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.130 velocity command

16.130.1 Syntax

velocity group-ID style args keyword value ...

• group-ID = ID of group of atoms whose velocity will be changed

• style = create or set or scale or ramp or zero
create args = temp seed
temp = temperature value (temperature units)
seed = random # seed (positive integer)
set args = vx vy vz
vx,vy,vz = velocity value or NULL (velocity units)
any of vx,vy,vz van be a variable (see below)
scale arg = temp
temp = temperature value (temperature units)
ramp args = vdim vlo vhi dim clo chi
vdim = vx or vy or vz
vlo,vhi = lower and upper velocity value (velocity units)
dim = x or y or z
clo,chi = lower and upper coordinate bound (distance units)
zero arg = linear or angular
linear = zero the linear momentum
angular = zero the angular momentum
• zero or more keyword/value pairs may be appended
• keyword = dist or sum or mom or rot or temp or bias or loop or units
dist value = uniform or gaussian
sum value = no or yes
mom value = no or yes
rot value = no or yes
temp value = temperature compute ID
bias value = no or yes
loop value = all or local or geom
rigid value = fix-ID
fix-ID = ID of rigid body fix
units value = box or lattice

16.130.2 Examples

velocity all create 300.0 4928459 rot yes dist gaussian

velocity border set NULL 4.0 v_vz sum yes units box
velocity flow scale 300.0
velocity flow ramp vx 0.0 5.0 y 5 25 temp mytemp
velocity all zero linear

16.130. velocity command 1005

LAMMPS Documentation, Release stable 29Sep2021

16.130.3 Description

Set or change the velocities of a group of atoms in one of several styles. For each style, there are required arguments
and optional keyword/value parameters. Not all options are used by each style. Each option has a default as listed
below.
The create style generates an ensemble of velocities using a random number generator with the specified seed at the
specified temperature.
The set style sets the velocities of all atoms in the group to the specified values. If any component is specified as NULL,
then it is not set. Any of the vx,vy,vz velocity components can be specified as an equal-style or atom-style variable. If
the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable
will be evaluated, and its value used to determine the velocity component. Note that if a variable is used, the velocity
it calculates must be in box units, not lattice units; see the discussion of the units keyword below.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters or other parameters.
Atom-style variables can specify the same formulas as equal-style variables but can also include per-atom values, such
as atom coordinates. Thus it is easy to specify a spatially-dependent velocity field.
The scale style computes the current temperature of the group of atoms and then rescales the velocities to the specified
temperature.
The ramp style is similar to that used by the compute temp/ramp command. Velocities ramped uniformly from vlo to
vhi are applied to dimension vx, or vy, or vz. The value assigned to a particular atom depends on its relative coordinate
value (in dim) from clo to chi. For the example above, an atom with y-coordinate of 10 (1/4 of the way from 5 to 25),
would be assigned a x-velocity of 1.25 (1/4 of the way from 0.0 to 5.0). Atoms outside the coordinate bounds (less
than 5 or greater than 25 in this case), are assigned velocities equal to vlo or vhi (0.0 or 5.0 in this case).
The zero style adjusts the velocities of the group of atoms so that the aggregate linear or angular momentum is zero.
No other changes are made to the velocities of the atoms. If the rigid option is specified (see below), then the zeroing
is performed on individual rigid bodies, as defined by the fix rigid or fix rigid/small commands. In other words, zero
linear will set the linear momentum of each rigid body to zero, and zero angular will set the angular momentum of each
rigid body to zero. This is done by adjusting the velocities of the atoms in each rigid body.
All temperatures specified in the velocity command are in temperature units; see the units command. The units of
velocities and coordinates depend on whether the units keyword is set to box or lattice, as discussed below.
For all styles, no atoms are assigned z-component velocities if the simulation is 2d; see the dimension command.

The keyword/value options are used in the following ways by the various styles.
The dist keyword is used by create. The ensemble of generated velocities can be a uniform distribution from some
minimum to maximum value, scaled to produce the requested temperature. Or it can be a gaussian distribution with a
mean of 0.0 and a sigma scaled to produce the requested temperature.
The sum keyword is used by all styles, except zero. The new velocities will be added to the existing ones if sum = yes,
or will replace them if sum = no.
The mom and rot keywords are used by create. If mom = yes, the linear momentum of the newly created ensemble of
velocities is zeroed; if rot = yes, the angular momentum is zeroed.

If specified, the temp keyword is used by create and scale to specify a compute that calculates temperature in a desired
way, e.g. by first subtracting out a velocity bias, as discussed on the Howto thermostat doc page. If this keyword is not
specified, create and scale calculate temperature using a compute that is defined internally as follows:

1006 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

compute velocity_temp group-ID temp

where group-ID is the same ID used in the velocity command. i.e. the group of atoms whose velocity is being altered.
This compute is deleted when the velocity command is finished. See the compute temp command for details. If the
calculated temperature should have degrees-of-freedom removed due to fix constraints (e.g. SHAKE or rigid-body
constraints), then the appropriate fix command must be specified before the velocity command is issued.
The bias keyword with a yes setting is used by create and scale, but only if the temp keyword is also used to specify
a compute that calculates temperature in a desired way. If the temperature compute also calculates a velocity bias, the
bias is subtracted from atom velocities before the create and scale operations are performed. After the operations, the
bias is added back to the atom velocities. See the Howto thermostat page for more discussion of temperature computes
with biases. Note that the velocity bias is only applied to atoms in the temperature compute specified with the temp
keyword.
As an example, assume atoms are currently streaming in a flow direction (which could be separately initialized with the
ramp style), and you wish to initialize their thermal velocity to a desired temperature. In this context thermal velocity
means the per-particle velocity that remains when the streaming velocity is subtracted. This can be done using the
create style with the temp keyword specifying the ID of a compute temp/ramp or compute temp/profile command, and
the bias keyword set to a yes value.

The loop keyword is used by create in the following ways.

If loop = all, then each processor loops over all atoms in the simulation to create velocities, but only stores velocities for
atoms it owns. This can be a slow loop for a large simulation. If atoms were read from a data file, the velocity assigned
to a particular atom will be the same, independent of how many processors are being used. This will not be the case if
atoms were created using the create_atoms command, since atom IDs will likely be assigned to atoms differently.
If loop = local, then each processor loops over only its atoms to produce velocities. The random number seed is adjusted
to give a different set of velocities on each processor. This is a fast loop, but the velocity assigned to a particular atom
will depend on which processor owns it. Thus the results will always be different when a simulation is run on a different
number of processors.
If loop = geom, then each processor loops over only its atoms. For each atom a unique random number seed is created,
based on the atom’s xyz coordinates. A velocity is generated using that seed. This is a fast loop and the velocity
assigned to a particular atom will be the same, independent of how many processors are used. However, the set of
generated velocities may be more correlated than if the all or local keywords are used.
Note that the loop geom keyword will not necessarily assign identical velocities for two simulations run on different
machines. This is because the computations based on xyz coordinates are sensitive to tiny differences in the double-
precision value for a coordinate as stored on a particular machine.

The rigid keyword only has meaning when used with the zero style. It allows specification of a fix-ID for one of the
rigid-body fix variants which defines a set of rigid bodies. The zeroing of linear or angular momentum is then performed
for each rigid body defined by the fix, as described above.
The units keyword is used by set and ramp. If units = box, the velocities and coordinates specified in the velocity
command are in the standard units described by the units command (e.g. Angstroms/fs for real units). If units = lattice,
velocities are in units of lattice spacings per time (e.g. spacings/fs) and coordinates are in lattice spacings. The lattice
command must have been previously used to define the lattice spacing.

16.130. velocity command 1007

LAMMPS Documentation, Release stable 29Sep2021

16.130.4 Restrictions

Assigning a temperature via the create style to a system with rigid bodies or SHAKE constraints may not have the
desired outcome for two reasons. First, the velocity command can be invoked before all of the relevant fixes are created
and initialized and the number of adjusted degrees of freedom (DOFs) is known. Thus it is not possible to compute
the target temperature correctly. Second, the assigned velocities may be partially canceled when constraints are first
enforced, leading to a different temperature than desired. A workaround for this is to perform a run 0 command, which
insures all DOFs are accounted for properly, and then rescale the temperature to the desired value before performing a
simulation. For example:

velocity all create 300.0 12345

run 0 # temperature may not be 300K
velocity all scale 300.0 # now it should be

16.130.5 Related commands

fix rigid, fix shake, lattice

16.130.6 Default

The keyword defaults are dist = uniform, sum = no, mom = yes, rot = no, bias = no, loop = all, and units = lattice. The
temp and rigid keywords are not defined by default.

16.131 write_coeff command

16.131.1 Syntax

write_coeff file

• file = name of data file to write out

16.131.2 Examples

write_coeff polymer.coeff

16.131.3 Description

Write a text format file with the currently defined force field coefficients in a way, that it can be read by LAMMPS
with the include command. In combination with the nocoeff option of write_data this can be used to move the Coeffs
sections from a data file into a separate file.

Note: The write_coeff command is not yet fully implemented as some pair styles do not output their coefficient
information. This means you will need to add/copy this information manually.

1008 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.131.4 Restrictions

none

16.131.5 Related commands

read_data, write_restart, write_data

16.132 write_data command

16.132.1 Syntax

write_data file keyword value ...

• file = name of data file to write out

• zero or more keyword/value pairs may be appended
• keyword = pair or nocoeff
nocoeff = do not write out force field info
nofix = do not write out extra sections read by fixes
pair value = ii or ij
ii = write one line of pair coefficient info per atom type
ij = write one line of pair coefficient info per IJ atom type pair

16.132.2 Examples

write_data data.polymer
write_data data.*

16.132.3 Description

Write a data file in text format of the current state of the simulation. Data files can be read by the read data command
to begin a simulation. The read_data command also describes their format.
Similar to dump files, the data filename can contain a “*” wild-card character. The “*” is replaced with the current
timestep value.

Data in Coeff sections

The write_data command may not always write all coefficient settings to the corresponding Coeff sections of the data
file. This can have one of multiple reasons. 1) A few styles may be missing the code that would write those sections (if
you come across one, please notify the LAMMPS developers). 2) Some pair styles require a single pair_coeff statement
and those are not compatible with data files. 3) The default for write_data is to write a PairCoeff section, which has only
entries for atom types i == j. The remaining coefficients would be inferred through the currently selected mixing rule.
If there has been a pair_coeff command with i != j, this setting would be lost. LAMMPS will detect this and print a
warning message unless pair ij is appended to the write_data command. This will request writing a PairIJCoeff section

16.132. write_data command 1009

LAMMPS Documentation, Release stable 29Sep2021

which has information for all pairs of atom types. In cases where the coefficient data in the data file is incomplete, you
will need to re-specify that information in your input script that reads the data file.

Because a data file is in text format, if you use a data file written out by this command to restart a simulation, the initial
state of the new run will be slightly different than the final state of the old run (when the file was written) which was
represented internally by LAMMPS in binary format. A new simulation which reads the data file will thus typically
diverge from a simulation that continued in the original input script.
If you want to do more exact restarts, using binary files, see the restart, write_restart, and read_restart commands.
You can also convert binary restart files to text data files, after a simulation has run, using the -r command-line switch.

Note: Only limited information about a simulation is stored in a data file. For example, no information about atom
groups and fixes are stored. Binary restart files store more information.

Bond interactions (angle, etc) that have been turned off by the fix shake or delete_bonds command will be written to a
data file as if they are turned on. This means they will need to be turned off again in a new run after the data file is read.
Bonds that are broken (e.g. by a bond-breaking potential) are not written to the data file. Thus these bonds will not
exist when the data file is read.

The nocoeff keyword requests that no force field parameters should be written to the data file. This can be very helpful,
if one wants to make significant changes to the force field or if the parameters are read in separately anyway, e.g. from
an include file.
The nofix keyword requests that no extra sections read by fixes should be written to the data file (see the fix option of
the read_data command for details). For example, this option excludes sections for user-created per-atom properties
from fix property/atom.
The pair keyword lets you specify in what format the pair coefficient information is written into the data file. If the
value is specified as ii, then one line per atom type is written, to specify the coefficients for each of the I=J interactions.
This means that no cross-interactions for I != J will be specified in the data file and the pair style will apply its mixing
rule, as documented on individual pair_style doc pages. Of course this behavior can be overridden in the input script
after reading the data file, by specifying additional pair_coeff commands for any desired I,J pairs.
If the value is specified as ij, then one line of coefficients is written for all I,J pairs where I <= J. These coefficients will
include any specific settings made in the input script up to that point. The presence of these I != J coefficients in the
data file will effectively turn off the default mixing rule for the pair style. Again, the coefficient values in the data file
can be overridden in the input script after reading the data file, by specifying additional pair_coeff commands for any
desired I,J pairs.

16.132.4 Restrictions

This command requires inter-processor communication to migrate atoms before the data file is written. This means
that your system must be ready to perform a simulation before using this command (force fields setup, atom masses
initialized, etc).

1010 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

16.132.5 Related commands

read_data, write_restart

16.132.6 Default

The option defaults are pair = ii.

16.133 write_dump command

16.133.1 Syntax

write_dump group-ID style file dump-args modify dump_modify-args

• group-ID = ID of the group of atoms to be dumped

• style = any of the supported dump styles
• file = name of file to write dump info to
• dump-args = any additional args needed for a particular dump style
• modify = all args after this keyword are passed to dump_modify (optional)
• dump-modify-args = args for dump_modify (optional)

16.133.2 Examples

write_dump all atom dump.atom

write_dump subgroup atom dump.run.bin
write_dump all custom dump.myforce.* id type x y vx fx
write_dump flow custom dump.%.myforce id type c_myF[3] v_ke modify sort id
write_dump all xyz system.xyz modify sort id element O H
write_dump all image snap*.jpg type type size 960 960 modify backcolor white
write_dump all image snap*.jpg element element &
bond atom 0.3 shiny 0.1 ssao yes 6345 0.2 size 1600 1600 &
modify backcolor white element C C O H N C C C O H H S O H
write_dump all atom/gz dump.atom.gz modify compression_level 9
write_dump flow custom/zstd dump.%.myforce.zst &
id type c_myF[3] v_ke &
modify sort id &
compression_level 15

16.133. write_dump command 1011

LAMMPS Documentation, Release stable 29Sep2021

16.133.3 Description

Dump a single snapshot of atom quantities to one or more files for the current state of the system. This is a one-time
immediate operation, in contrast to the dump command which will will set up a dump style to write out snapshots
periodically during a running simulation.
The syntax for this command is mostly identical to that of the dump and dump_modify commands as if they were
concatenated together, with the following exceptions: There is no need for a dump ID or dump frequency and the
keyword modify is added. The latter is so that the full range of dump_modify options can be specified for the single
snapshot, just as they can be for multiple snapshots. The modify keyword separates the arguments that would normally
be passed to the dump command from those that would be given the dump_modify. Both support optional arguments
and thus LAMMPS needs to be able to cleanly separate the two sets of args.
Note that if the specified filename uses wildcard characters “*” or “%”, as supported by the dump command, they will
operate in the same fashion to create the new filename(s). Normally, dump image files require a filename with a “*”
character for the timestep. That is not the case for the write_dump command; no wildcard “*” character is necessary.

16.133.4 Restrictions

All restrictions for the dump and dump_modify commands apply to this command as well, with the exception of the
dump image filename not requiring a wildcard “*” character, as noted above.
Since dumps are normally written during a run or energy minimization, the simulation has to be ready to run before this
command can be used. Similarly, if the dump requires information from a compute, fix, or variable, the information
needs to have been calculated for the current timestep (e.g. by a prior run), else LAMMPS will generate an error
message.
For example, it is not possible to dump per-atom energy with this command before a run has been performed, since
no energies and forces have yet been calculated. See the variable doc page section on Variable Accuracy for more
information on this topic.

16.133.5 Related commands

dump, dump image, dump_modify

16.133.6 Default

The defaults are listed on the doc pages for the dump and dump image and dump_modify commands.

16.134 write_restart command

16.134.1 Syntax

write_restart file keyword value ...

• file = name of file to write restart information to

• zero or more keyword/value pairs may be appended
• keyword = fileper or nfile

1012 Chapter 16. Commands

 LAMMPS Documentation, Release stable 29Sep2021

fileper arg = Np
Np = write one file for every this many processors
nfile arg = Nf
Nf = write this many files, one from each of Nf processors

16.134.2 Examples

write_restart restart.equil
write_restart restart.equil.mpiio
write_restart poly.%.* nfile 10

16.134.3 Description

Write a binary restart file of the current state of the simulation.

During a long simulation, the restart command is typically used to output restart files periodically. The write_restart
command is useful after a minimization or whenever you wish to write out a single current restart file.
Similar to dump files, the restart filename can contain two wild-card characters. If a “*” appears in the filename, it
is replaced with the current timestep value. If a “%” character appears in the filename, then one file is written by
each processor and the “%” character is replaced with the processor ID from 0 to P-1. An additional file with the
“%” replaced by “base” is also written, which contains global information. For example, the files written for filename
restart.% would be restart.base, restart.0, restart.1, . . . restart.P-1. This creates smaller files and can be a fast mode
of output and subsequent input on parallel machines that support parallel I/O. The optional fileper and nfile keywords
discussed below can alter the number of files written.
The restart file can also be written in parallel as one large binary file via the MPI-IO library, which is part of the MPI
standard for versions 2.0 and above. Using MPI-IO requires two steps. First, build LAMMPS with its MPIIO package
installed, e.g.

CMake build

cmake . -DPKG_MPIIO=on # enables the MPIIO package in the build folder

cmake --build . # recompiles LAMMPS with the package code included

Traditional make

make yes-mpiio # installs the MPIIO package

make mpi # build LAMMPS for your platform

Second, use a restart filename which contains “.mpiio”. Note that it does not have to end in “.mpiio”, just contain those
characters. Unlike MPI-IO dump files, a particular restart file must be both written and read using MPI-IO.
Restart files can be read by a read_restart command to restart a simulation from a particular state. Because the file is
binary (to enable exact restarts), it may not be readable on another machine. In this case, you can use the -r command-
line switch to convert a restart file to a data file.

Note: Although the purpose of restart files is to enable restarting a simulation from where it left off, not all information
about a simulation is stored in the file. For example, the list of fixes that were specified during the initial run is not
stored, which means the new input script must specify any fixes you want to use. Even when restart information is

16.134. write_restart command 1013

LAMMPS Documentation, Release stable 29Sep2021

stored in the file, as it is for some fixes, commands may need to be re-specified in the new input script, in order to re-use
that information. Details are usually given in the documentation of the respective command. Also, see the read_restart
command for general information about what is stored in a restart file.

The optional nfile or fileper keywords can be used in conjunction with the “%” wildcard character in the specified restart
file name. As explained above, the “%” character causes the restart file to be written in pieces, one piece for each of P
processors. By default P = the number of processors the simulation is running on. The nfile or fileper keyword can be
used to set P to a smaller value, which can be more efficient when running on a large number of processors.
The nfile keyword sets P to the specified Nf value. For example, if Nf = 4, and the simulation is running on 100
processors, 4 files will be written, by processors 0,25,50,75. Each will collect information from itself and the next 24
processors and write it to a restart file.
For the fileper keyword, the specified value of Np means write one file for every Np processors. For example, if Np =
4, every fourth processor (0,4,8,12,etc) will collect information from itself and the next 3 processors and write it to a
restart file.

16.134.4 Restrictions

This command requires inter-processor communication to migrate atoms before the restart file is written. This means
that your system must be ready to perform a simulation before using this command (force fields setup, atom masses
initialized, etc).
To write and read restart files in parallel with MPI-IO, the MPIIO package must be installed.

16.134.5 Related commands

restart, read_restart, write_data

16.134.6 Default

none

1014 Chapter 16. Commands

 CHAPTER

SEVENTEEN

FIXES

17.1 fix accelerate/cos command

17.1.1 Syntax

fix ID group-ID accelerate value

• ID, group-ID are documented in fix command

• accelerate/cos = style name of this fix command
• value = amplitude of acceleration (in unit of force/mass)

17.1.2 Examples

fix 1 all accelerate/cos 0.02e-5

17.1.3 Description

Give each atom a acceleration in x-direction based on its z coordinate. The acceleration is a periodic function along
the z-direction:
 
2πz
ax (z) = A cos
lz

where A is the acceleration amplitude, lz is the z-length of the simulation box. At steady state, the acceleration generates
a velocity profile:
 
2πz
vx (z) = V cos
lz

The generated velocity amplitude V is related to the shear viscosity η by:

 2
Aρ lz
V =
η 2π

and it can be obtained from ensemble average of the velocity profile:

 
P 2πzi
i 2m i v i,x cos lz
V = P
i m i

1015
LAMMPS Documentation, Release stable 29Sep2021

where mi , vi,x and zi are the mass, x-component velocity and z coordinate of a particle.
The velocity amplitude V can be calculated with compute viscosity/cos, which enables viscosity calculation with pe-
riodic perturbation method, as described by Hess. Because the applied acceleration drives the system away from
equilibration, the calculated shear viscosity is lower than the intrinsic viscosity due to the shear-thinning effect. Ex-
trapolation to zero acceleration should generally be performed to predict the zero-shear viscosity. As the shear stress
decreases, the signal-noise ratio decreases rapidly, the simulation time must be extended accordingly to get converged
result.
In order to get meaningful result, the group ID of this fix should be all.

17.1.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.1.5 Restrictions

This command is only available when LAMMPS was built with the MISC package. Since this fix depends on the
z-coordinate of atoms, it cannot be used in 2d simulations.

17.1.6 Related commands

compute viscosity/cos

17.1.7 Default

none

(Hess) Hess, B. The Journal of Chemical Physics 2002, 116 (1), 209-217.

17.2 fix adapt command

17.2.1 Syntax

fix ID group-ID adapt N attribute args ... keyword value ...

• ID, group-ID are documented in fix command

• adapt = style name of this fix command
• N = adapt simulation settings every this many timesteps
• one or more attribute/arg pairs may be appended
• attribute = pair or bond or kspace or atom

1016 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

pair args = pstyle pparam I J v_name

pstyle = pair style name, e.g. lj/cut
pparam = parameter to adapt over time
I,J = type pair(s) to set parameter for
v_name = variable with name that calculates value of pparam
bond args = bstyle bparam I v_name
bstyle = bond style name, e.g. harmonic
bparam = parameter to adapt over time
I = type bond to set parameter for
v_name = variable with name that calculates value of bparam
kspace arg = v_name
v_name = variable with name that calculates scale factor on K-space terms
atom args = aparam v_name
aparam = parameter to adapt over time
v_name = variable with name that calculates value of aparam
• zero or more keyword/value pairs may be appended
• keyword = scale or reset or mass
scale value = no or yes
no = the variable value is the new setting
yes = the variable value multiplies the original setting
reset value = no or yes
no = values will remain altered at the end of a run
yes = reset altered values to their original values at the end of a run
mass value = no or yes
no = mass is not altered by changes in diameter
yes = mass is altered by changes in diameter

17.2.2 Examples

fix 1 all adapt 1 pair soft a 1 1 v_prefactor

fix 1 all adapt 1 pair soft a 2* 3 v_prefactor
fix 1 all adapt 1 pair lj/cut epsilon * * v_scale1 pair coul/cut scale 3 3 v_scale2␣
,→scale yes reset yes

fix 1 all adapt 10 atom diameter v_size

variable ramp_up equal "ramp(0.01,0.5)"

fix stretch all adapt 1 bond harmonic r0 1 v_ramp_up

17.2.3 Description

Change or adapt one or more specific simulation attributes or settings over time as a simulation runs. Pair potential
and K-space and atom attributes which can be varied by this fix are discussed below. Many other fixes can also be
used to time-vary simulation parameters, e.g. the “fix deform” command will change the simulation box size/shape
and the “fix move” command will change atom positions and velocities in a prescribed manner. Also note that many
commands allow variables as arguments for specific parameters, if described in that manner on their doc pages. An
equal-style variable can calculate a time-dependent quantity, so this is another way to vary a simulation parameter over
time.
If N is specified as 0, the specified attributes are only changed once, before the simulation begins. This is all that is
needed if the associated variables are not time-dependent. If N > 0, then changes are made every N steps during the
simulation, presumably with a variable that is time-dependent.

17.2. fix adapt command 1017

LAMMPS Documentation, Release stable 29Sep2021

Depending on the value of the reset keyword, attributes changed by this fix will or will not be reset back to their original
values at the end of a simulation. Even if reset is specified as yes, a restart file written during a simulation will contain
the modified settings.
If the scale keyword is set to no, which is the default, then the value of the altered parameter will be whatever the
variable generates. If the scale keyword is set to yes, then the value of the altered parameter will be the initial value
of that parameter multiplied by whatever the variable generates. I.e. the variable is now a “scale factor” applied in
(presumably) a time-varying fashion to the parameter.
Note that whether scale is no or yes, internally, the parameters themselves are actually altered by this fix. Make sure
you use the reset yes option if you want the parameters to be restored to their initial values after the run.

The pair keyword enables various parameters of potentials defined by the pair_style command to be changed, if the
pair style supports it. Note that the pair_style and pair_coeff commands must be used in the usual manner to specify
these parameters initially; the fix adapt command simply overrides the parameters.
The pstyle argument is the name of the pair style. If pair_style hybrid or hybrid/overlay is used, pstyle should be a
sub-style name. If there are multiple sub-styles using the same pair style, then pstyle should be specified as “style:N”
where N is which instance of the pair style you wish to adapt, e.g. the first, second, etc. For example, pstyle could
be specified as “soft” or “lubricate” or “lj/cut:1” or “lj/cut:2”. The pparam argument is the name of the parameter
to change. This is the current list of pair styles and parameters that can be varied by this fix. See the doc pages for
individual pair styles and their energy formulas for the meaning of these parameters:

born a,b,c type pairs

born/coul/long, born/coul/msm coulombic_cutoff type global
buck, buck/coul/cut a,c type pairs
buck/coul/long, buck/coul/msm a,c,coulombic_cutoff type pairs
buck/mdf a,c type pairs
coul/cut scale type pairs
coul/cut/soft lambda type pairs
coul/debye scale type pairs
coul/dsf coulombic_cutoff type global
coul/long, coul/msm coulombic_cutoff, scale type pairs
coul/long/soft scale, lambda, coulombic_cutoff type pairs
eam, eam/alloy, eam/fs scale type pairs
gauss a type pairs
lennard/mdf A,B type pairs
lj/class2 epsilon,sigma type pairs
lj/class2/coul/cut, lj/class2/coul/long epsilon,sigma,coulombic_cutoff type pairs
lj/cut epsilon,sigma type pairs
lj/cut/coul/cut, lj/cut/coul/long, lj/cut/coul/msm epsilon,sigma,coulombic_cutoff type pairs
lj/cut/coul/cut/soft, lj/cut/coul/long/soft epsilon,sigma,lambda,coulombic_cutoff type pairs
lj/cut/coul/dsf cutoff type global
lj/cut/tip4p/cut epsilon,sigma,coulombic_cutoff type pairs
lj/cut/soft epsilon,sigma,lambda type pairs
lj/expand epsilon,sigma,delta type pairs
lj/mdf epsilon,sigma type pairs
lj/sf/dipole/sf epsilon,sigma,scale type pairs
lubricate mu global
mie/cut epsilon,sigma,gamma_repulsive,gamma_attractive type pairs
morse, morse/smooth/linear D0,R0,alpha type pairs
morse/soft D0,R0,alpha,lambda type pairs
continues on next page

1018 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Table 1 – continued from previous page

nm/cut E0,R0,m,n type pairs
nm/cut/coul/cut, nm/cut/coul/long E0,R0,m,n,coulombic_cutoff type pairs
reaxff chi, eta, gamma type global
snap scale type pairs
spin/dmi coulombic_cutoff type global
spin/exchange coulombic_cutoff type global
spin/magelec coulombic_cutoff type global
spin/neel coulombic_cutoff type global
table table_cutoff type pairs
ufm epsilon,sigma type pairs
soft a type pairs

Note: It is easy to add new pairwise potentials and their parameters to this list. All it typically takes is adding an
extract() method to the pair_*.cpp file associated with the potential.

Some parameters are global settings for the pair style, e.g. the viscosity setting “mu” for pair_style lubricate. Other
parameters apply to atom type pairs within the pair style, e.g. the prefactor “a” for pair_style soft.
Note that for many of the potentials, the parameter that can be varied is effectively a prefactor on the entire energy
expression for the potential, e.g. the lj/cut epsilon. The parameters listed as “scale” are exactly that, since the energy
expression for the coul/cut potential (for example) has no labeled prefactor in its formula. To apply an effective prefactor
to some potentials, multiple parameters need to be altered. For example, the Buckingham potential needs both the A
and C terms altered together. To scale the Buckingham potential, you should thus list the pair style twice, once for A
and once for C.
If a type pair parameter is specified, the I and J settings should be specified to indicate which type pairs to apply it to.
If a global parameter is specified, the I and J settings still need to be specified, but are ignored.
Similar to the pair_coeff command, I and J can be specified in one of two ways. Explicit numeric values can be used for
each, as in the first example above. I <= J is required. LAMMPS sets the coefficients for the symmetric J,I interaction
to the same values.
A wild-card asterisk can be used in place of or in conjunction with the I,J arguments to set the coefficients for multiple
pairs of atom types. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of atom types, then an
asterisk with no numeric values means all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive).
Note that only type pairs with I <= J are considered; if asterisks imply type pairs where J < I, they are ignored.
IMPROTANT NOTE: If pair_style hybrid or hybrid/overlay is being used, then the pstyle will be a sub-style name. You
must specify I,J arguments that correspond to type pair values defined (via the pair_coeff command) for that sub-style.
The v_name argument for keyword pair is the name of an equal-style variable which will be evaluated each time this
fix is invoked to set the parameter to a new value. It should be specified as v_name, where name is the variable name.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify parameters that
change as a function of time or span consecutive runs in a continuous fashion. For the latter, see the start and stop
keywords of the run command and the elaplong keyword of thermo_style custom for details.
For example, these commands would change the prefactor coefficient of the pair_style soft potential from 10.0 to 30.0
in a linear fashion over the course of a simulation:

variable prefactor equal ramp(10,30)

fix 1 all adapt 1 pair soft a * * v_prefactor

17.2. fix adapt command 1019

LAMMPS Documentation, Release stable 29Sep2021

The bond keyword uses the specified variable to change the value of a bond coefficient over time, very similar to how
the pair keyword operates. The only difference is that now a bond coefficient for a given bond type is adapted.
A wild-card asterisk can be used in place of or in conjunction with the bond type argument to set the coefficients for
multiple bond types. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of atom types, then an
asterisk with no numeric values means all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive).
Currently bond does not support bond_style hybrid nor bond_style hybrid/overlay as bond styles. The only bonds that
currently are working with fix_adapt are

class2 r0 type bonds

fene k, r0 type bonds
gromos k, r0 type bonds
harmonic k,r0 type bonds
morse r0 type bonds
nonlinear r0 type bonds

The kspace keyword used the specified variable as a scale factor on the energy, forces, virial calculated by whatever
K-Space solver is defined by the kspace_style command. If the variable has a value of 1.0, then the solver is unaltered.
The kspace keyword works this way whether the scale keyword is set to no or yes.

The atom keyword enables various atom properties to be changed. The aparam argument is the name of the parameter
to change. This is the current list of atom parameters that can be varied by this fix:
• charge = charge on particle
• diameter or diameter/disc = diameter of particle
The v_name argument of the atom keyword is the name of an equal-style variable which will be evaluated each time
this fix is invoked to set, or scale the parameter to a new value. It should be specified as v_name, where name is the
variable name. See the discussion above describing the formulas associated with equal-style variables. The new value
is assigned to the corresponding attribute for all atoms in the fix group.
If the atom parameter is diameter and per-atom density and per-atom mass are defined for particles (e.g. atom_style
granular), then the mass of each particle is, by default, also changed when the diameter changes. The mass is set from
the particle volume for 3d systems (density is assumed to stay constant). For 2d, the default is for LAMMPS to model
particles with a radius attribute as spheres. However, if the atom parameter is diameter/disc, then the mass is set from
the particle area (the density is assumed to be in mass/distance^2 units). The mass of the particle may also be kept
constant if the mass keyword is set to no. This can be useful to account for diameter changes that do not involve mass
changes, e.g., thermal expansion.
For example, these commands would shrink the diameter of all granular particles in the “center” group from 1.0 to 0.1
in a linear fashion over the course of a 1000-step simulation:

variable size equal ramp(1.0,0.1)

fix 1 center adapt 10 atom diameter v_size

This fix can be used in long simulations which are restarted one or more times to continuously adapt simulation pa-
rameters, but it must be done carefully. There are two issues to consider. The first is how to adapt the parameters in
a continuous manner from one simulation to the next. The second is how, if desired, to reset the parameters to their
original values at the end of the last restarted run.

1020 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Note that all the parameters changed by this fix are written into a restart file in their current changed state. A new
restarted simulation does not know their original time=0 values, unless the input script explicitly resets the parameters
(after the restart file is read), to their original values.
Also note, that the time-dependent variable(s) used in the restart script should typically be written as a function of time
elapsed since the original simulation began.
With this in mind, if the scale keyword is set to no (the default) in a restarted simulation, original parameters are not
needed. The adapted parameters should seamlessly continue their variation relative to the preceding simulation.
If the scale keyword is set to yes, then the input script should typically reset the parameters being adapted to their
original values, so that the scaling formula specified by the variable will operate correctly. An exception is if the atom
keyword is being used with scale yes. In this case, information is added to the restart file so that per-atom properties in
the new run will automatically be scaled relative to their original values. This will only work if the fix adapt command
specified in the restart script has the same ID as the one used in the original script.
In a restarted run, if the reset keyword is set to yes, and the run ends in this script (as opposed to just writing more
restart files, parameters will be restored to the values they were at the beginning of the run command in the restart
script. Which as explained above, may or may not be the original values of the parameters. Again, an exception is if
the atom keyword is being used with reset yes (in all the runs). In that case, the original per-atom parameters are stored
in the restart file, and will be restored when the restarted run finally completes.

17.2.4 Restart, fix_modify, output, run start/stop, minimize info

If the atom keyword is used and the scale or reset keyword is set to yes, then this fix writes information to a restart
file so that in a restarted run scaling can continue in a seamless manner and/or the per-atom values can be restored, as
explained above.
None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access
by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.
For rRESPA time integration, this fix changes parameters on the outermost rRESPA level.

17.2.5 Restrictions

none

17.2.6 Related commands

compute ti

17.2.7 Default

The option defaults are scale = no, reset = no, mass = yes.

17.2. fix adapt command 1021

LAMMPS Documentation, Release stable 29Sep2021

17.3 fix adapt/fep command

17.3.1 Syntax

fix ID group-ID adapt/fep N attribute args ... keyword value ...

• ID, group-ID are documented in fix command

• adapt/fep = style name of this fix command
• N = adapt simulation settings every this many timesteps
• one or more attribute/arg pairs may be appended
• attribute = pair or kspace or atom
pair args = pstyle pparam I J v_name
pstyle = pair style name, e.g. lj/cut
pparam = parameter to adapt over time
I,J = type pair(s) to set parameter for
v_name = variable with name that calculates value of pparam
kspace arg = v_name
v_name = variable with name that calculates scale factor on K-space terms
atom args = aparam v_name
aparam = parameter to adapt over time
I = type(s) to set parameter for
v_name = variable with name that calculates value of aparam
• zero or more keyword/value pairs may be appended
• keyword = scale or reset or after
scale value = no or yes
no = the variable value is the new setting
yes = the variable value multiplies the original setting
reset value = no or yes
no = values will remain altered at the end of a run
yes = reset altered values to their original values at the end
of a run
after value = no or yes
no = parameters are adapted at timestep N
yes = parameters are adapted one timestep after N

17.3.2 Examples

fix 1 all adapt/fep 1 pair soft a 1 1 v_prefactor

fix 1 all adapt/fep 1 pair soft a 2* 3 v_prefactor
fix 1 all adapt/fep 1 pair lj/cut epsilon * * v_scale1 coul/cut scale 3 3 v_scale2 scale␣
,→yes reset yes
fix 1 all adapt/fep 10 atom diameter 1 v_size

Example input scripts available: examples/PACKAGES/fep

1022 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.3.3 Description

Change or adapt one or more specific simulation attributes or settings over time as a simulation runs.
This is an enhanced version of the fix adapt command with two differences,
• It is possible to modify the charges of chosen atom types only, instead of scaling all the charges in the system.
• There is a new option after for better compatibility with “fix ave/time”.
This version is suited for free energy calculations using compute ti or compute fep.
If N is specified as 0, the specified attributes are only changed once, before the simulation begins. This is all that is
needed if the associated variables are not time-dependent. If N > 0, then changes are made every N steps during the
simulation, presumably with a variable that is time-dependent.
Depending on the value of the reset keyword, attributes changed by this fix will or will not be reset back to their original
values at the end of a simulation. Even if reset is specified as yes, a restart file written during a simulation will contain
the modified settings.
If the scale keyword is set to no, then the value the parameter is set to will be whatever the variable generates. If the
scale keyword is set to yes, then the value of the altered parameter will be the initial value of that parameter multiplied
by whatever the variable generates. I.e. the variable is now a “scale factor” applied in (presumably) a time-varying
fashion to the parameter. Internally, the parameters themselves are actually altered; make sure you use the reset yes
option if you want the parameters to be restored to their initial values after the run.
If the after keyword is set to yes, then the parameters are changed one timestep after the multiple of N. In this manner,
if a fix such as “fix ave/time” is used to calculate averages at every N timesteps, all the contributions to the average will
be obtained with the same values of the parameters.

The pair keyword enables various parameters of potentials defined by the pair_style command to be changed, if the
pair style supports it. Note that the pair_style and pair_coeff commands must be used in the usual manner to specify
these parameters initially; the fix adapt command simply overrides the parameters.
The pstyle argument is the name of the pair style. If pair_style hybrid or hybrid/overlay is used, pstyle should be a
sub-style name. For example, pstyle could be specified as “soft” or “lubricate”. The pparam argument is the name of
the parameter to change. This is the current list of pair styles and parameters that can be varied by this fix. See the doc
pages for individual pair styles and their energy formulas for the meaning of these parameters:

17.3. fix adapt/fep command 1023

LAMMPS Documentation, Release stable 29Sep2021

born a,b,c type pairs

buck, buck/coul/cut, buck/coul/long, buck/coul/msm a,c type pairs
buck/mdf a,c type pairs
coul/cut scale type pairs
coul/cut/soft lambda type pairs
coul/long, coul/msm scale type pairs
coul/long/soft scale, lambda type pairs
eam scale type pairs
gauss a type pairs
lennard/mdf a,b type pairs
lj/class2 epsilon,sigma type pairs
lj/class2/coul/cut, lj/class2/coul/long epsilon,sigma type pairs
lj/cut epsilon,sigma type pairs
lj/cut/soft epsilon,sigma,lambda type pairs
lj/cut/coul/cut, lj/cut/coul/long, lj/cut/coul/msm epsilon,sigma type pairs
lj/cut/coul/cut/soft, lj/cut/coul/long/soft epsilon,sigma,lambda type pairs
lj/cut/tip4p/cut, lj/cut/tip4p/long epsilon,sigma type pairs
lj/cut/tip4p/long/soft epsilon,sigma,lambda type pairs
lj/expand epsilon,sigma,delta type pairs
lj/mdf epsilon,sigma type pairs
lj/sf/dipole/sf epsilon,sigma,scale type pairs
mie/cut epsilon,sigma,gamR,gamA type pairs
morse, morse/smooth/linear d0,r0,alpha type pairs
morse/soft d0,r0,alpha,lambda type pairs
nm/cut e0,r0,nn,mm type pairs
nm/cut/coul/cut, nm/cut/coul/long e0,r0,nn,mm type pairs
snap scale type pairs
soft a type pairs
ufm epsilon,sigma,scale type pairs

Note: It is easy to add new potentials and their parameters to this list. All it typically takes is adding an extract()
method to the pair_*.cpp file associated with the potential.

Note that for many of the potentials, the parameter that can be varied is effectively a prefactor on the entire energy
expression for the potential, e.g. the lj/cut epsilon. The parameters listed as “scale” are exactly that, since the energy
expression for the coul/cut potential (for example) has no labeled prefactor in its formula. To apply an effective prefactor
to some potentials, multiple parameters need to be altered. For example, the Buckingham potential needs both the A
and C terms altered together. To scale the Buckingham potential, you should thus list the pair style twice, once for A
and once for C.
If a type pair parameter is specified, the I and J settings should be specified to indicate which type pairs to apply it to.
If a global parameter is specified, the I and J settings still need to be specified, but are ignored.
Similar to the pair_coeff command, I and J can be specified in one of two ways. Explicit numeric values can be used for
each, as in the first example above. I <= J is required. LAMMPS sets the coefficients for the symmetric J,I interaction
to the same values.
A wild-card asterisk can be used in place of or in conjunction with the I,J arguments to set the coefficients for multiple
pairs of atom types. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of atom types, then an
asterisk with no numeric values means all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to N (inclusive). A middle asterisk means all types from m to n (inclusive).
Note that only type pairs with I <= J are considered; if asterisks imply type pairs where J < I, they are ignored.

1024 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

IMPROTANT NOTE: If pair_style hybrid or hybrid/overlay is being used, then the pstyle will be a sub-style name. You
must specify I,J arguments that correspond to type pair values defined (via the pair_coeff command) for that sub-style.
The v_name argument for keyword pair is the name of an equal-style variable which will be evaluated each time this
fix is invoked to set the parameter to a new value. It should be specified as v_name, where name is the variable name.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify parameters that
change as a function of time or span consecutive runs in a continuous fashion. For the latter, see the start and stop
keywords of the run command and the elaplong keyword of thermo_style custom for details.
For example, these commands would change the prefactor coefficient of the pair_style soft potential from 10.0 to 30.0
in a linear fashion over the course of a simulation:

variable prefactor equal ramp(10,30)

fix 1 all adapt 1 pair soft a * * v_prefactor

The kspace keyword used the specified variable as a scale factor on the energy, forces, virial calculated by whatever
K-Space solver is defined by the kspace_style command. If the variable has a value of 1.0, then the solver is unaltered.
The kspace keyword works this way whether the scale keyword is set to no or yes.

The atom keyword enables various atom properties to be changed. The aparam argument is the name of the parameter
to change. This is the current list of atom parameters that can be varied by this fix:
• charge = charge on particle
• diameter = diameter of particle
The I argument indicates which atom types are affected. A wild-card asterisk can be used in place of or in conjunction
with the I argument to set the coefficients for multiple atom types.
The v_name argument of the atom keyword is the name of an equal-style variable which will be evaluated each time this
fix is invoked to set the parameter to a new value. It should be specified as v_name, where name is the variable name.
See the discussion above describing the formulas associated with equal-style variables. The new value is assigned to
the corresponding attribute for all atoms in the fix group.
If the atom parameter is diameter and per-atom density and per-atom mass are defined for particles (e.g. atom_style
granular), then the mass of each particle is also changed when the diameter changes (density is assumed to stay con-
stant).
For example, these commands would shrink the diameter of all granular particles in the “center” group from 1.0 to 0.1
in a linear fashion over the course of a 1000-step simulation:

variable size equal ramp(1.0,0.1)

fix 1 center adapt 10 atom diameter * v_size

For rRESPA time integration, this fix changes parameters on the outermost rRESPA level.

17.3. fix adapt/fep command 1025

LAMMPS Documentation, Release stable 29Sep2021

17.3.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.3.5 Restrictions

none

17.3.6 Related commands

compute fep, fix adapt, compute ti, pair_style */soft

17.3.7 Default

The option defaults are scale = no, reset = no, after = no.

17.4 fix addforce command

17.4.1 Syntax

fix ID group-ID addforce fx fy fz keyword value ...

• ID, group-ID are documented in fix command

• addforce = style name of this fix command
• fx,fy,fz = force component values (force units)

any of fx,fy,fz can be a variable (see below)

• zero or more keyword/value pairs may be appended to args

• keyword = every or region or energy
every value = Nevery
Nevery = add force every this many timesteps
region value = region-ID
region-ID = ID of region atoms must be in to have added force
energy value = v_name
v_name = variable with name that calculates the potential energy of each atom in␣
,→the added force field

1026 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.4.2 Examples

fix kick flow addforce 1.0 0.0 0.0

fix kick flow addforce 1.0 0.0 v_oscillate
fix ff boundary addforce 0.0 0.0 v_push energy v_espace

17.4.3 Description

Add fx,fy,fz to the corresponding component of force for each atom in the group. This command can be used to give
an additional push to atoms in a simulation, such as for a simulation of Poiseuille flow in a channel.
Any of the 3 quantities defining the force components can be specified as an equal-style or atom-style variable, namely
fx, fy, fz. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the
variable will be evaluated each timestep, and its value(s) used to determine the force component.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
force field.
Atom-style variables can specify the same formulas as equal-style variables but can also include per-atom values, such
as atom coordinates. Thus it is easy to specify a spatially-dependent force field with optional time-dependence as well.
If the every keyword is used, the Nevery setting determines how often the forces are applied. The default value is 1, for
every timestep.
If the region keyword is used, the atom must also be in the specified geometric region in order to have force added to
it.

Adding a force to atoms implies a change in their potential energy as they move due to the applied force field. For
dynamics via the “run” command, this energy can be optionally added to the system’s potential energy for thermody-
namic output (see below). For energy minimization via the “minimize” command, this energy must be added to the
system’s potential energy to formulate a self-consistent minimization problem (see below).
The energy keyword is not allowed if the added force is a constant vector F = (fx,fy,fz), with all components defined as
numeric constants and not as variables. This is because LAMMPS can compute the energy for each atom directly as E
= -x dot F = -(x*fx + y*fy + z*fz), so that -Grad(E) = F.
The energy keyword is optional if the added force is defined with one or more variables, and if you are performing
dynamics via the run command. If the keyword is not used, LAMMPS will set the energy to 0.0, which is typically
fine for dynamics.
The energy keyword is required if the added force is defined with one or more variables, and you are performing energy
minimization via the “minimize” command. The keyword specifies the name of an atom-style variable which is used
to compute the energy of each atom as function of its position. Like variables used for fx, fy, fz, the energy variable is
specified as v_name, where name is the variable name.
Note that when the energy keyword is used during an energy minimization, you must insure that the formula defined
for the atom-style variable is consistent with the force variable formulas, i.e. that -Grad(E) = F. For example, if the
force were a spring-like F = kx, then the energy formula should be E = -0.5kx^2. If you don’t do this correctly, the
minimization will not converge properly.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.

17.4. fix addforce command 1027

LAMMPS Documentation, Release stable 29Sep2021

These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.4.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy inferred by the added force to the
global potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify
energy no. Note that this energy is a fictitious quantity but is needed so that the minimize command can include the
forces added by this fix in a consistent manner. I.e. there is a decrease in potential energy when atoms move in the
direction of the added force.
The fix_modify virial option is supported by this fix to add the contribution due to the added forces on atoms to both
the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands.
The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial no.
The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.
This fix computes a global scalar and a global 3-vector of forces, which can be accessed by various output commands.
The scalar is the potential energy discussed above. The vector is the total force on the group of atoms before the forces
on individual atoms are changed by the fix. The scalar and vector values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command. You should
not specify force components with a variable that has time-dependence for use with a minimizer, since the minimizer
increments the timestep as the iteration count during the minimization.

Note: If you want the fictitious potential energy associated with the added forces to be included in the total potential
energy of the system (the quantity being minimized), you MUST enable the fix_modify energy option for this fix.

17.4.5 Restrictions

none

17.4.6 Related commands

fix setforce, fix aveforce

1028 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.4.7 Default

The option default for the every keyword is every = 1.

17.5 fix addtorque command

17.5.1 Syntax

fix ID group-ID addtorque Tx Ty Tz

• ID, group-ID are documented in fix command

• addtorque = style name of this fix command
• Tx,Ty,Tz = torque component values (torque units)
• any of Tx,Ty,Tz can be a variable (see below)

17.5.2 Examples

fix kick bead addtorque 2.0 3.0 5.0

fix kick bead addtorque 0.0 0.0 v_oscillate

17.5.3 Description

Add a set of forces to each atom in the group such that:

• the components of the total torque applied on the group (around its center of mass) are Tx,Ty,Tz
• the group would move as a rigid body in the absence of other forces.
This command can be used to drive a group of atoms into rotation.
Any of the 3 quantities defining the torque components can be specified as an equal-style variable, namely Tx, Ty, Tz.
If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable
will be evaluated each timestep, and its value used to determine the torque component.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
torque.

17.5.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential “energy” inferred by the added torques to the
global potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify
energy no. Note that this is a fictitious quantity but is needed so that the minimize command can include the forces
added by this fix in a consistent manner. I.e. there is a decrease in potential energy when atoms move in the direction
of the added forces.

17.5. fix addtorque command 1029

LAMMPS Documentation, Release stable 29Sep2021

The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its torque. Default is the outermost level.
This fix computes a global scalar and a global 3-vector, which can be accessed by various output commands. The
scalar is the potential energy discussed above. The vector is the total torque on the group of atoms before the forces on
individual atoms are changed by the fix. The scalar and vector values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command.

Note: If you want the fictitious potential energy associated with the added forces to be included in the total potential
energy of the system (the quantity being minimized), you MUST enable the fix_modify energy option for this fix.

Note: You should not specify force components with a variable that has time-dependence for use with a minimizer,
since the minimizer increments the timestep as the iteration count during the minimization.

17.5.5 Restrictions

This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.

17.5.6 Related commands

fix addforce

17.5.7 Default

none

17.6 fix append/atoms command

17.6.1 Syntax

fix ID group-ID append/atoms face ... keyword value ...

• ID, group-ID are documented in fix command

• append/atoms = style name of this fix command
• face = zhi
• zero or more keyword/value pairs may be appended
• keyword = basis or size or freq or temp or random or units
basis values = M itype
M = which basis atom
itype = atom type (1-N) to assign to this basis atom
size args = Lz

1030 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Lz = z size of lattice region appended in a single event(distance units)

freq args = freq
freq = the number of timesteps between append events
temp args = target damp seed extent
target = target temperature for the region between zhi-extent and zhi␣
,→(temperature units)

damp = damping parameter (time units)

seed = random number seed for langevin kicks
extent = extent of thermostatted region (distance units)
random args = xmax ymax zmax seed
xmax, ymax, zmax = maximum displacement in particular direction (distance units)
seed = random number seed for random displacement
units value = lattice or box
lattice = the wall position is defined in lattice units
box = the wall position is defined in simulation box units

17.6.2 Examples

fix 1 all append/atoms zhi size 5.0 freq 295 units lattice
fix 4 all append/atoms zhi size 15.0 freq 5 units box
fix A all append/atoms zhi size 1.0 freq 1000 units lattice

17.6.3 Description

This fix creates atoms on a lattice, appended on the zhi edge of the system box. This can be useful when a shock or wave
is propagating from zlo. This allows the system to grow with time to accommodate an expanding wave. A simulation
box must already exist, which is typically created via the create_box command. Before using this command, a lattice
must also be defined using the lattice command.
This fix will automatically freeze atoms on the zhi edge of the system, so that overlaps are avoided when new atoms
are appended.
The basis keyword specifies an atom type that will be assigned to specific basis atoms as they are created. See the
lattice command for specifics on how basis atoms are defined for the unit cell of the lattice. By default, all created
atoms are assigned type = 1 unless this keyword specifies differently.
The size keyword defines the size in z of the chunk of material to be added.
The random keyword will give the atoms random displacements around their lattice points to simulate some initial
temperature.
The temp keyword will cause a region to be thermostatted with a Langevin thermostat on the zhi boundary. The size
of the region is measured from zhi and is set with the extent argument.
The units keyword determines the meaning of the distance units used to define a wall position, but only when a numeric
constant is used. A box value selects standard distance units as defined by the units command, e.g. Angstroms for units
= real or metal. A lattice value means the distance units are in lattice spacings. The lattice command must have been
previously used to define the lattice spacings.

17.6. fix append/atoms command 1031

LAMMPS Documentation, Release stable 29Sep2021

17.6.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.6.5 Restrictions

This fix style is part of the SHOCK package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
The boundary on which atoms are added with append/atoms must be shrink/minimum. The opposite boundary may be
any boundary type other than periodic.

17.6.6 Related commands

fix wall/piston command

17.6.7 Default

The keyword defaults are size = 0.0, freq = 0, units = lattice. All added atoms are of type 1 unless the basis keyword is
used.

17.7 fix atc command

17.7.1 Syntax

fix <fixID> <group> atc <type> <parameter_file>

• fixID = name of fix

• group = name of group fix is to be applied
• type = thermal or two_temperature or hardy or field
thermal = thermal coupling with fields: temperature
two_temperature = electron-phonon coupling with field: temperature and electron_
,→temperature

hardy = on-the-fly post-processing using kernel localization functions

field = on-the-fly post-processing using mesh-based localization functions
• parameter_file = name of the file with material parameters. Note: Neither hardy nor field requires a parameter
file

1032 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.7.2 Examples

fix AtC internal atc thermal Ar_thermal.dat

fix AtC internal atc two_temperature Ar_ttm.mat
fix AtC internal atc hardy
fix AtC internal atc field

17.7.3 Description

This fix is the beginning to creating a coupled FE/MD simulation and/or an on-the-fly estimation of continuum fields.
The coupled versions of this fix do Verlet integration and the post-processing does not. After instantiating this fix,
several other fix_modify commands will be needed to set up the problem, e.g. define the finite element mesh and
prescribe initial and boundary conditions.

The following coupling example is typical, but non-exhaustive:

# ... commands to create and initialize the MD system

# initial fix to designate coupling type and group to apply it to

# tag group physics material_file
fix AtC internal atc thermal Ar_thermal.mat

# create a uniform 12 x 2 x 2 mesh that covers region contain the group

# nx ny nz region periodicity
fix_modify AtC mesh create 12 2 2 mdRegion f p p

# specify the control method for the type of coupling

# physics control_type
fix_modify AtC thermal control flux

# specify the initial values for the empirical field "temperature"

# field node_group value
fix_modify AtC initial temperature all 30

(continues on next page)

17.7. fix atc command 1033

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

# create an output stream for nodal fields
# filename output_frequency
fix_modify AtC output atc_fe_output 100

run 1000

likewise for this post-processing example:

# ... commands to create and initialize the MD system

# initial fix to designate post-processing and the group to apply it to

# no material file is allowed nor required
fix AtC internal atc hardy

# for hardy fix, specific kernel function (function type and range) to # be used as a␣
,→localization function

fix AtC kernel quartic_sphere 10.0

# create a uniform 1 x 1 x 1 mesh that covers region contain the group

# with periodicity this effectively creates a system average
fix_modify AtC mesh create 1 1 1 box p p p

# change from default lagrangian map to eulerian

# refreshed every 100 steps
fix_modify AtC atom_element_map eulerian 100

# start with no field defined

# add mass density, potential energy density, stress and temperature
fix_modify AtC fields add density energy stress temperature

# create an output stream for nodal fields

# filename output_frequency
fix_modify AtC output nvtFE 100 text

run 1000

the mesh’s linear interpolation functions can be used as the localization function by using the field option:

fix AtC internal atc field

fix_modify AtC mesh create 1 1 1 box p p p
...

Note coupling and post-processing can be combined in the same simulations using separate fixes.

1034 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.7.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is not supported by this fix, but this fix does add the kinetic energy imparted to atoms by
the momentum coupling mode of the AtC package to the global potential energy of the system as part of thermodynamic
output.
Additional fix_modify options relevant to this fix are listed below.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the energy discussed
in the previous paragraph. The scalar value is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.7.5 Restrictions

Thermal and two_temperature (coupling) types use a Verlet time-integration algorithm. The hardy type does not contain
its own time-integrator and must be used with a separate fix that does contain one, e.g. nve, nvt, etc. In addition,
currently:
• the coupling is restricted to thermal physics
• the FE computations are done in serial on each processor.

17.7.6 Related commands

After specifying this fix in your input script, several fix_modify AtC commands are used to setup the problem, e.g.
define the finite element mesh and prescribe initial and boundary conditions. Each of these options has its own doc
page.
fix_modify commands for setup:
• fix_modify AtC mesh create
• fix_modify AtC mesh quadrature
• fix_modify AtC mesh read
• fix_modify AtC mesh write
• fix_modify AtC mesh create_nodeset
• fix_modify AtC mesh add_to_nodeset
• fix_modify AtC mesh create_faceset box
• fix_modify AtC mesh create_faceset plane
• fix_modify AtC mesh create_elementset
• fix_modify AtC mesh delete_elements
• fix_modify AtC mesh nodeset_to_elementset
• fix_modify AtC boundary type
• fix_modify AtC internal_quadrature
• fix_modify AtC time_integration
• fix_modify AtC extrinsic electron_integration

17.7. fix atc command 1035

LAMMPS Documentation, Release stable 29Sep2021

• fix_modify AtC internal_element_set

• fix_modify AtC decomposition
fix_modify commands for boundary and initial conditions:
• fix_modify AtC initial
• fix_modify AtC fix
• fix_modify AtC unfix
• fix_modify AtC fix_flux
• fix_modify AtC unfix_flux
• fix_modify AtC source
• fix_modify AtC remove_source
fix_modify commands for control and filtering:
• fix_modify AtC control thermal
• fix_modify AtC control momentum
• fix_modify AtC control localized_lambda
• fix_modify AtC control lumped_lambda_solve
• fix_modify AtC control mask_direction
• fix_modify AtC filter
• fix_modify AtC filter scale
• fix_modify AtC filter type
• fix_modify AtC equilibrium_start
• fix_modify AtC extrinsic exchange
• fix_modify AtC poisson_solver
fix_modify commands for output:
• fix_modify AtC output
• fix_modify AtC output nodeset
• fix_modify AtC output volume_integral
• fix_modify AtC output boundary_integral
• fix_modify AtC output contour_integral
• fix_modify AtC mesh output
• fix_modify AtC write_restart
• fix_modify AtC read_restart
fix_modify commands for post-processing:
• fix_modify AtC kernel
• fix_modify AtC fields
• fix_modify AtC gradients
• fix_modify AtC rates

1036 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• fix_modify AtC computes

• fix_modify AtC on_the_fly
• fix_modify AtC pair/bond_interactions
• fix_modify AtC sample_frequency
• fix_modify AtC set
miscellaneous fix_modify commands:
• fix_modify AtC atom_element_map
• fix_modify AtC atom_weight
• fix_modify AtC write_atom_weights
• fix_modify AtC kernel_bandwidth
• fix_modify AtC reset_time
• fix_modify AtC reset_atomic_reference_positions
• fix_modify AtC fe_md_boundary
• fix_modify AtC boundary_faceset
• fix_modify AtC consistent_fe_initialization
• fix_modify AtC mass_matrix
• fix_modify AtC material
• fix_modify AtC atomic_charge
• fix_modify AtC source_integration
• fix_modify AtC temperature_definition
• fix_modify AtC track_displacement
• fix_modify AtC boundary_dynamics
• fix_modify AtC add_species
• fix_modify AtC add_molecule
• fix_modify AtC remove_species
• fix_modify AtC remove_molecule
Note: a set of example input files with the attendant material files are included in the examples/PACKAGES/atc
folders.

17.7.7 Default

None

For detailed exposition of the theory and algorithms please see:

(Wagner) Wagner, GJ; Jones, RE; Templeton, JA; Parks, MA, “An atomistic-to-continuum coupling method for
heat transfer in solids.” Special Issue of Computer Methods and Applied Mechanics (2008) 197:3351.

17.7. fix atc command 1037

LAMMPS Documentation, Release stable 29Sep2021

(Zimmerman2004) Zimmerman, JA; Webb, EB; Hoyt, JJ;. Jones, RE; Klein, PA; Bammann, DJ, “Calculation of
stress in atomistic simulation.” Special Issue of Modelling and Simulation in Materials Science and Engineering
(2004), 12:S319.
(Zimmerman2010) Zimmerman, JA; Jones, RE; Templeton, JA, “A material frame approach for evaluating con-
tinuum variables in atomistic simulations.” Journal of Computational Physics (2010), 229:2364.
(Templeton2010) Templeton, JA; Jones, RE; Wagner, GJ, “Application of a field-based method to spatially vary-
ing thermal transport problems in molecular dynamics.” Modelling and Simulation in Materials Science and
Engineering (2010), 18:085007.
(Jones) Jones, RE; Templeton, JA; Wagner, GJ; Olmsted, D; Modine, JA, “Electron transport enhanced molecu-
lar dynamics for metals and semi-metals.” International Journal for Numerical Methods in Engineering (2010),
83:940.
(Templeton2011) Templeton, JA; Jones, RE; Lee, JW; Zimmerman, JA; Wong, BM, “A long-range electric field
solver for molecular dynamics based on atomistic-to-continuum modeling.” Journal of Chemical Theory and
Computation (2011), 7:1736.
(Mandadapu) Mandadapu, KK; Templeton, JA; Lee, JW, “Polarization as a field variable from molecular dy-
namics simulations.” Journal of Chemical Physics (2013), 139:054115.
Please refer to the standard finite element (FE) texts, e.g. T.J.R Hughes ” The finite element method “, Dover 2003, for
the basics of FE simulation.

17.8 fix atom/swap command

17.8.1 Syntax

fix ID group-ID atom/swap N X seed T keyword values ...

• ID, group-ID are documented in fix command

• atom/swap = style name of this fix command
• N = invoke this fix every N steps
• X = number of swaps to attempt every N steps
• seed = random # seed (positive integer)
• T = scaling temperature of the MC swaps (temperature units)
• one or more keyword/value pairs may be appended to args
• keyword = types or mu or ke or semi-grand or region
types values = two or more atom types
mu values = chemical potential of swap types (energy units)
ke value = no or yes
no = no conservation of kinetic energy after atom swaps
yes = kinetic energy is conserved after atom swaps
semi-grand value = no or yes
no = particle type counts and fractions conserved
yes = semi-grand canonical ensemble, particle fractions not conserved
region value = region-ID
region-ID = ID of region to use as an exchange/move volume

1038 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.8.2 Examples

fix 2 all atom/swap 1 1 29494 300.0 ke no types 1 2

fix myFix all atom/swap 100 1 12345 298.0 region my_swap_region types 5 6
fix SGMC all atom/swap 1 100 345 1.0 semi-grand yes types 1 2 3 mu 0.0 4.3 -5.0

17.8.3 Description

This fix performs Monte Carlo swaps of atoms of one given atom type with atoms of the other given atom types. The
specified T is used in the Metropolis criterion dictating swap probabilities.
Perform X swaps of atoms of one type with atoms of another type according to a Monte Carlo probability. Swap
candidates must be in the fix group, must be in the region (if specified), and must be of one of the listed types. Swaps
are attempted between candidates that are chosen randomly with equal probability among the candidate atoms. Swaps
are not attempted between atoms of the same type since nothing would happen.
All atoms in the simulation domain can be moved using regular time integration displacements, e.g. via fix nvt, resulting
in a hybrid MC+MD simulation. A smaller-than-usual timestep size may be needed when running such a hybrid
simulation, especially if the swapped atoms are not well equilibrated.
The types keyword is required. At least two atom types must be specified.
The ke keyword can be set to no to turn off kinetic energy conservation for swaps. The default is yes, which means that
swapped atoms have their velocities scaled by the ratio of the masses of the swapped atom types. This ensures that the
kinetic energy of each atom is the same after the swap as it was before the swap, even though the atom masses have
changed.
The semi-grand keyword can be set to yes to switch to the semi-grand canonical ensemble as discussed in (Sadigh).
This means that the total number of each particle type does not need to be conserved. The default is no, which means
that the only kind of swap allowed exchanges an atom of one type with an atom of a different given type. In other words,
the relative mole fractions of the swapped atoms remains constant. Whereas in the semi-grand canonical ensemble,
the composition of the system can change. Note that when using semi-grand, atoms in the fix group whose type is
not listed in the types keyword are ineligible for attempted conversion. An attempt is made to switch the selected
atom (if eligible) to one of the other listed types with equal probability. Acceptance of each attempt depends upon the
Metropolis criterion.
The mu keyword allows users to specify chemical potentials. This is required and allowed only when using semi-grand.
All chemical potentials are absolute, so there is one for each swap type listed following the types keyword. In semi-
grand canonical ensemble simulations the chemical composition of the system is controlled by the difference in these
values. So shifting all values by a constant amount will have no effect on the simulation.
This command may optionally use the region keyword to define swap volume. The specified region must have been
previously defined with a region command. It must be defined with side = in. Swap attempts occur only between atoms
that are both within the specified region. Swaps are not otherwise attempted.
You should ensure you do not swap atoms belonging to a molecule, or LAMMPS will soon generate an error when it
tries to find those atoms. LAMMPS will warn you if any of the atoms eligible for swapping have a non-zero molecule
ID, but does not check for this at the time of swapping.
If not using semi-grand this fix checks to ensure all atoms of the given types have the same atomic charge. LAMMPS
does not enforce this in general, but it is needed for this fix to simplify the swapping procedure. Successful swaps will
swap the atom type and charge of the swapped atoms. Conversely, when using semi-grand, it is assumed that all the
atom types involved in switches have the same charge. Otherwise, charge would not be conserved. As a consequence,
no checks on atomic charges are performed, and successful switches update the atom type but not the atom charge.
While it is possible to use semi-grand with groups of atoms that have different charges, these charges will not be
changed when the atom types change.

17.8. fix atom/swap command 1039

LAMMPS Documentation, Release stable 29Sep2021

Since this fix computes total potential energies before and after proposed swaps, so even complicated potential energy
calculations are OK, including the following:
• long-range electrostatics (kspace)
• many body pair styles
• hybrid pair styles
• eam pair styles
• triclinic systems
• need to include potential energy contributions from other fixes
Some fixes have an associated potential energy. Examples of such fixes include: efield, gravity, addforce, langevin,
restrain, temp/berendsen, temp/rescale, and wall fixes. For that energy to be included in the total potential energy of
the system (the quantity used when performing GCMC moves), you MUST enable the fix_modify energy option for
that fix. The doc pages for individual fix commands specify if this should be done.

17.8.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the fix to binary restart files. This includes information about the random number generator
seed, the next timestep for MC exchanges, the number of exchange attempts and successes etc. See the read_restart
command for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix
continues in an uninterrupted fashion.

Note: For this to work correctly, the timestep must not be changed after reading the restart with reset_timestep. The
fix will try to detect it and stop with an error.

None of the fix_modify options are relevant to this fix.

This fix computes a global vector of length 2, which can be accessed by various output commands. The vector values
are the following global cumulative quantities:
• 1 = swap attempts
• 2 = swap successes
The vector values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.8.5 Restrictions

This fix is part of the MC package. It is only enabled if LAMMPS was built with that package. See the Build package
doc page for more info.

1040 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.8.6 Related commands

fix nvt, neighbor, fix deposit, fix evaporate, delete_atoms, fix gcmc

17.8.7 Default

The option defaults are ke = yes, semi-grand = no, mu = 0.0 for all atom types.

(Sadigh) B Sadigh, P Erhart, A Stukowski, A Caro, E Martinez, and L Zepeda-Ruiz, Phys. Rev. B, 85, 184203 (2012).

17.9 fix ave/atom command

17.9.1 Syntax

fix ID group-ID ave/atom Nevery Nrepeat Nfreq value1 value2 ...

• ID, group-ID are documented in fix command

• ave/atom = style name of this fix command
• Nevery = use input values every this many timesteps
• Nrepeat = # of times to use input values for calculating averages
• Nfreq = calculate averages every this many timesteps one or more input values can be listed
• value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[i], f_ID, f_ID[i], v_name

x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component)

c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can␣
,→include wildcard (see below)

f_ID = per-atom vector calculated by a fix with ID

f_ID[I] = Ith column of per-atom array calculated by a fix with ID, I can include␣
,→wildcard (see below)

v_name = per-atom vector calculated by an atom-style variable with name

17.9.2 Examples

fix 1 all ave/atom 1 100 100 vx vy vz

fix 1 all ave/atom 10 20 1000 c_my_stress[1]
fix 1 all ave/atom 10 20 1000 c_my_stress[*]

17.9. fix ave/atom command 1041

LAMMPS Documentation, Release stable 29Sep2021

17.9.3 Description

Use one or more per-atom vectors as inputs every few timesteps, and average them atom by atom over longer timescales.
The resulting per-atom averages can be used by other output commands such as the fix ave/chunk or dump custom
commands.
The group specified with the command means only atoms within the group have their averages computed. Results are
set to 0.0 for atoms not in the group.
Each input value can be an atom attribute (position, velocity, force component) or can be the result of a compute or fix
or the evaluation of an atom-style variable. In the latter cases, the compute, fix, or variable must produce a per-atom
vector, not a global quantity or local quantity. If you wish to time-average global quantities from a compute, fix, or
variable, then see the fix ave/time command.
Each per-atom value of each input vector is averaged independently.
Computes that produce per-atom vectors or arrays are those which have the word atom in their style name. See the doc
pages for individual fixes to determine which ones produce per-atom vectors or arrays. Variables of style atom are the
only ones that can be used with this fix since they produce per-atom vectors.
Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the
index to effectively specify multiple values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the size of the
vector (for mode = scalar) or the number of columns in the array (for mode = vector), then an asterisk with no numeric
values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk
means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual columns of the array had been listed one by one. E.g. these 2 fix
ave/atom commands are equivalent, since the compute stress/atom command creates a per-atom array with 6 columns:

compute my_stress all stress/atom NULL

fix 1 all ave/atom 10 20 1000 c_my_stress[*]
fix 1 all ave/atom 10 20 1000 c_my_stress[1] c_my_stress[2] &
c_my_stress[3] c_my_stress[4] &
c_my_stress[5] c_my_stress[6]

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be used in order to contribute
to the average. The final averaged quantities are generated on timesteps that are a multiple of Nfreq. The average is
over Nrepeat quantities, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a
multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the average
value cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on timesteps 90,92,94,96,98,100 will be used to
compute the final average on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc.

The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are self-explanatory. Note that other atom attributes can be used as
inputs to this fix by using the compute property/atom command and then specifying an input value from that compute.

Note: The x,y,z attributes are values that are re-wrapped inside the periodic box whenever an atom crosses a periodic
boundary. Thus if you time average an atom that spends half its time on either side of the periodic box, you will get a
value in the middle of the box. If this is not what you want, consider averaging unwrapped coordinates, which can be
provided by the compute property/atom command via its xu,yu,zu attributes.

If a value begins with “c_”, a compute ID must follow which has been previously defined in the input script. If no
bracketed term is appended, the per-atom vector calculated by the compute is used. If a bracketed term containing an

1042 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

index I is appended, the Ith column of the per-atom array calculated by the compute is used. Users can also write code
for their own compute styles and add them to LAMMPS. See the discussion above for how I can be specified with a
wildcard asterisk to effectively specify multiple values.
If a value begins with “f_”, a fix ID must follow which has been previously defined in the input script. If no bracketed
term is appended, the per-atom vector calculated by the fix is used. If a bracketed term containing an index I is appended,
the Ith column of the per-atom array calculated by the fix is used. Note that some fixes only produce their values on
certain timesteps, which must be compatible with Nevery, else an error will result. Users can also write code for their
own fix styles and add them to LAMMPS. See the discussion above for how I can be specified with a wildcard asterisk
to effectively specify multiple values.
If a value begins with “v_”, a variable name must follow which has been previously defined in the input script as an
atom-style variable Variables of style atom can reference thermodynamic keywords, or invoke other computes, fixes,
or variables when they are evaluated, so this is a very general means of generating per-atom quantities to time average.

17.9.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global scalar or vector quantities are stored by this fix for access by various output commands.
This fix produces a per-atom vector or array which can be accessed by various output commands. A vector is produced if
only a single quantity is averaged by this fix. If two or more quantities are averaged, then an array of values is produced.
The per-atom values can only be accessed on timesteps that are multiples of Nfreq since that is when averaging is
performed.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.9.5 Restrictions

none

17.9.6 Related commands

compute, fix ave/histo, fix ave/chunk, fix ave/time, variable,

17.9.7 Default

none

17.10 fix ave/chunk command

17.10.1 Syntax

fix ID group-ID ave/chunk Nevery Nrepeat Nfreq chunkID value1 value2 ... keyword args ...

• ID, group-ID are documented in fix command

• ave/chunk = style name of this fix command

17.10. fix ave/chunk command 1043

LAMMPS Documentation, Release stable 29Sep2021

• Nevery = use input values every this many timesteps

• Nrepeat = # of times to use input values for calculating averages
• Nfreq = calculate averages every this many timesteps
• chunkID = ID of compute chunk/atom command
• one or more input values can be listed
• value = vx, vy, vz, fx, fy, fz, density/mass, density/number, temp, c_ID, c_ID[I], f_ID, f_ID[I], v_name

vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)

density/number, density/mass = number or mass density
temp = temperature
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can␣
,→include wildcard (see below)

f_ID = per-atom vector calculated by a fix with ID

f_ID[I] = Ith column of per-atom array calculated by a fix with ID, I can include␣
,→wildcard (see below)

v_name = per-atom vector calculated by an atom-style variable with name

• zero or more keyword/arg pairs may be appended

• keyword = norm or ave or bias or adof or cdof or file or overwrite or title1 or title2 or title3
norm arg = all or sample or none = how output on Nfreq steps is normalized
all = output is sum of atoms across all Nrepeat samples, divided by atom count
sample = output is sum of Nrepeat sample averages, divided by Nrepeat
none = output is sum of Nrepeat sample sums, divided by Nrepeat
ave args = one or running or window M
one = output new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
bias arg = bias-ID
bias-ID = ID of a temperature compute that removes a velocity bias for␣
,→temperature calculation

adof value = dof_per_atom

dof_per_atom = define this many degrees-of-freedom per atom for temperature␣
,→calculation

cdof value = dof_per_chunk

dof_per_chunk = define this many degrees-of-freedom per chunk for temperature␣
,→calculation

file arg = filename

filename = file to write results to
overwrite arg = none = overwrite output file with only latest output
format arg = string
string = C-style format string
title1 arg = string
string = text to print as 1st line of output file
title2 arg = string
string = text to print as 2nd line of output file
title3 arg = string
string = text to print as 3rd line of output file

1044 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.10.2 Examples

fix 1 all ave/chunk 10000 1 10000 binchunk c_myCentro title1 "My output values"
fix 1 flow ave/chunk 100 10 1000 molchunk vx vz norm sample file vel.profile
fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running
fix 1 flow ave/chunk 100 5 1000 binchunk density/mass ave running

NOTE:
If you are trying to replace a deprecated fix ave/spatial command with the newer, more flexible fix ave/chunk and
compute chunk/atom commands, you simply need to split the fix ave/spatial arguments across the two new commands.
For example, this command:

fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile

could be replaced by:

compute cc1 flow chunk/atom bin/1d y 0.0 1.0

fix 1 flow ave/chunk 100 10 1000 cc1 vx vz norm sample file vel.profile

17.10.3 Description

Use one or more per-atom vectors as inputs every few timesteps, sum the values over the atoms in each chunk at each
timestep, then average the per-chunk values over longer timescales. The resulting chunk averages can be used by other
output commands such as thermo_style custom, and can also be written to a file.
In LAMMPS, chunks are collections of atoms defined by a compute chunk/atom command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified as chunkID. For example, a single chunk could
be the atoms in a molecule or atoms in a spatial bin. See the compute chunk/atom page and the Howto chunk page for
details of how chunks can be defined and examples of how they can be used to measure properties of a system.
Note that only atoms in the specified group contribute to the summing and averaging calculations. The compute
chunk/atom command defines its own group as well as an optional region. Atoms will have a chunk ID = 0, meaning
they belong to no chunk, if they are not in that group or region. Thus you can specify the “all” group for this command
if you simply want to use the chunk definitions provided by chunkID.
Each specified per-atom value can be an atom attribute (position, velocity, force component), a mass or number density,
or the result of a compute or fix or the evaluation of an atom-style variable. In the latter cases, the compute, fix, or
variable must produce a per-atom quantity, not a global quantity. Note that the compute property/atom command
provides access to any attribute defined and stored by atoms. If you wish to time-average global quantities from a
compute, fix, or variable, then see the fix ave/time command.
The per-atom values of each input vector are summed and averaged independently of the per-atom values in other input
vectors.
Computes that produce per-atom quantities are those which have the word atom in their style name. See the doc pages
for individual fixes to determine which ones produce per-atom quantities. Variables of style atom are the only ones that
can be used with this fix since all other styles of variable produce global quantities.
Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the
index to effectively specify multiple values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the size of the
vector (for mode = scalar) or the number of columns in the array (for mode = vector), then an asterisk with no numeric
values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk
means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive).

17.10. fix ave/chunk command 1045

LAMMPS Documentation, Release stable 29Sep2021

Using a wildcard is the same as if the individual columns of the array had been listed one by one. E.g. these 2 fix
ave/chunk commands are equivalent, since the compute property/atom command creates, in this case, a per-atom array
with 3 columns:

compute myAng all property/atom angmomx angmomy angmomz

fix 1 all ave/chunk 100 1 100 cc1 c_myAng[*] file tmp.angmom
fix 2 all ave/chunk 100 1 100 cc1 c_myAng[1] c_myAng[2] c_myAng[3] file tmp.angmom

Note: This fix works by creating an array of size Nchunk by Nvalues on each processor. Nchunk is the number of
chunks which is defined by the compute chunk/atom command. Nvalues is the number of input values specified. Each
processor loops over its atoms, tallying its values to the appropriate chunk. Then the entire array is summed across all
processors. This means that using a large number of chunks will incur an overhead in memory and computational cost
(summing across processors), so be careful to define a reasonable number of chunks.

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be accessed and contribute
to the average. The final averaged quantities are generated on timesteps that are a multiples of Nfreq. The average is
over Nrepeat quantities, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a
multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the average
value cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on timesteps 90,92,94,96,98,100 will be used to
compute the final average on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc. If
Nrepeat=1 and Nfreq = 100, then no time averaging is done; values are simply generated on timesteps 100,200,etc.
Each input value can also be averaged over the atoms in each chunk. The way the averaging is done across the Nrepeat
timesteps to produce output on the Nfreq timesteps, and across multiple Nfreq outputs, is determined by the norm and
ave keyword settings, as discussed below.

Note: To perform per-chunk averaging within a Nfreq time window, the number of chunks Nchunk defined by the
compute chunk/atom command must remain constant. If the ave keyword is set to running or window then Nchunk
must remain constant for the duration of the simulation. This fix forces the chunk/atom compute specified by chunkID
to hold Nchunk constant for the appropriate time windows, by not allowing it to re-calculate Nchunk, which can also
affect how it assigns chunk IDs to atoms. This is particularly important to understand if the chunks defined by the
compute chunk/atom command are spatial bins. If its units keyword is set to box or lattice, then the number of bins
Nchunk and size of each bin will be fixed over the Nfreq time window, which can affect which atoms are discarded if
the simulation box size changes. If its units keyword is set to reduced, then the number of bins Nchunk will still be
fixed, but the size of each bin can vary at each timestep if the simulation box size changes, e.g. for an NPT simulation.

The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory. As noted above, any other atom attributes can be
used as input values to this fix by using the compute property/atom command and then specifying an input value from
that compute.
The density/number value means the number density is computed for each chunk, i.e. number/volume. The den-
sity/mass value means the mass density is computed for each chunk, i.e. total-mass/volume. The output values are in
units of 1/volume or density (mass/volume). See the units command page for the definition of density for each choice
of units, e.g. gram/cm^3. If the chunks defined by the compute chunk/atom command are spatial bins, the volume is
the bin volume. Otherwise it is the volume of the entire simulation box.
The temp value means the temperature is computed for each chunk, by the formula KE = DOF/2 k T, where KE = total
kinetic energy of the chunk of atoms (sum of 1/2 m v^2), DOF = the total number of degrees of freedom for all atoms
in the chunk, k = Boltzmann constant, and T = temperature.

1046 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The DOF is calculated as N*adof + cdof, where N = number of atoms in the chunk, adof = degrees of freedom per
atom, and cdof = degrees of freedom per chunk. By default adof = 2 or 3 = dimensionality of system, as set via the
dimension command, and cdof = 0.0. This gives the usual formula for temperature.
Note that currently this temperature only includes translational degrees of freedom for each atom. No rotational degrees
of freedom are included for finite-size particles. Also no degrees of freedom are subtracted for any velocity bias or
constraints that are applied, such as compute temp/partial, or fix shake or fix rigid. This is because those degrees of
freedom (e.g. a constrained bond) could apply to sets of atoms that are both included and excluded from a specific
chunk, and hence the concept is somewhat ill-defined. In some cases, you can use the adof and cdof keywords to
adjust the calculated degrees of freedom appropriately, as explained below.
Also note that a bias can be subtracted from atom velocities before they are used in the above formula for KE, by using
the bias keyword. This allows, for example, a thermal temperature to be computed after removal of a flow velocity
profile.
Note that the per-chunk temperature calculated by this fix and the compute temp/chunk command can be different. The
compute calculates the temperature for each chunk for a single snapshot. This fix can do that but can also time average
those values over many snapshots, or it can compute a temperature as if the atoms in the chunk on different timesteps
were collected together as one set of atoms to calculate their temperature. The compute allows the center-of-mass
velocity of each chunk to be subtracted before calculating the temperature; this fix does not.
If a value begins with “c_”, a compute ID must follow which has been previously defined in the input script. If no
bracketed integer is appended, the per-atom vector calculated by the compute is used. If a bracketed integer is appended,
the Ith column of the per-atom array calculated by the compute is used. Users can also write code for their own compute
styles and add them to LAMMPS. See the discussion above for how I can be specified with a wildcard asterisk to
effectively specify multiple values.
If a value begins with “f_”, a fix ID must follow which has been previously defined in the input script. If no bracketed
integer is appended, the per-atom vector calculated by the fix is used. If a bracketed integer is appended, the Ith column
of the per-atom array calculated by the fix is used. Note that some fixes only produce their values on certain timesteps,
which must be compatible with Nevery, else an error results. Users can also write code for their own fix styles and add
them to LAMMPS. See the discussion above for how I can be specified with a wildcard asterisk to effectively specify
multiple values.
If a value begins with “v_”, a variable name must follow which has been previously defined in the input script. Variables
of style atom can reference thermodynamic keywords and various per-atom attributes, or invoke other computes, fixes,
or variables when they are evaluated, so this is a very general means of generating per-atom quantities to average within
chunks.

Additional optional keywords also affect the operation of this fix and its outputs.
The norm keyword affects how averaging is done for the per-chunk values that are output every Nfreq timesteps.
It the norm setting is all, which is the default, a chunk value is summed over all atoms in all Nrepeat samples, as is the
count of atoms in the chunk. The averaged output value for the chunk on the Nfreq timesteps is Total-sum / Total-count.
In other words it is an average over atoms across the entire Nfreq timescale. For the density/number and density/mass
values, the volume (bin volume or system volume) used in the final normalization will be the volume at the final Nfreq
timestep. For the temp values, degrees of freedom and kinetic energy are summed separately across the entire Nfreq
timescale, and the output value is calculated by dividing those two sums.
If the norm setting is sample, the chunk value is summed over atoms for each sample, as is the count, and an “average
sample value” is computed for each sample, i.e. Sample-sum / Sample-count. The output value for the chunk on the
Nfreq timesteps is the average of the Nrepeat “average sample values”, i.e. the sum of Nrepeat “average sample values”
divided by Nrepeat. In other words it is an average of an average. For the density/number and density/mass values,
the volume (bin volume or system volume) used in the per-sample normalization will be the current volume at each
sampling step.

17.10. fix ave/chunk command 1047

LAMMPS Documentation, Release stable 29Sep2021

If the norm setting is none, a similar computation as for the sample setting is done, except the individual “average
sample values” are “summed sample values”. A summed sample value is simply the chunk value summed over atoms
in the sample, without dividing by the number of atoms in the sample. The output value for the chunk on the Nfreq
timesteps is the average of the Nrepeat “summed sample values”, i.e. the sum of Nrepeat “summed sample values”
divided by Nrepeat. For the density/number and density/mass values, the volume (bin volume or system volume) used
in the per-sample sum normalization will be the current volume at each sampling step.
The ave keyword determines how the per-chunk values produced every Nfreq steps are averaged with values produced
on previous steps that were multiples of Nfreq, before they are accessed by another output command or written to a file.
If the ave setting is one, which is the default, then the chunk values produced on timesteps that are multiples of Nfreq
are independent of each other; they are output as-is without further averaging.
If the ave setting is running, then the chunk values produced on timesteps that are multiples of Nfreq are summed and
averaged in a cumulative sense before being output. Each output chunk value is thus the average of the chunk value
produced on that timestep with all preceding values for the same chunk. This running average begins when the fix is
defined; it can only be restarted by deleting the fix via the unfix command, or re-defining the fix by re-specifying it.
If the ave setting is window, then the chunk values produced on timesteps that are multiples of Nfreq are summed and
averaged within a moving “window” of time, so that the last M values for the same chunk are used to produce the
output. E.g. if M = 3 and Nfreq = 1000, then the output on step 10000 will be the average of the individual chunk
values on steps 8000,9000,10000. Outputs on early steps will average over less than M values if they are not available.
The bias keyword specifies the ID of a temperature compute that removes a “bias” velocity from each atom, specified as
bias-ID. It is only used when the temp value is calculated, to compute the thermal temperature of each chunk after the
translational kinetic energy components have been altered in a prescribed way, e.g. to remove a flow velocity profile.
See the doc pages for individual computes that calculate a temperature to see which ones implement a bias.
The adof and cdof keywords define the values used in the degree of freedom (DOF) formula described above for
temperature calculation for each chunk. They are only used when the temp value is calculated. They can be used to
calculate a more appropriate temperature for some kinds of chunks. Here are 3 examples:
If spatially binned chunks contain some number of water molecules and fix shake is used to make each molecule rigid,
then you could calculate a temperature with 6 degrees of freedom (DOF) (3 translational, 3 rotational) per molecule by
setting adof to 2.0.
If compute temp/partial is used with the bias keyword to only allow the x component of velocity to contribute to the
temperature, then adof = 1.0 would be appropriate.
If each chunk consists of a large molecule, with some number of its bonds constrained by fix shake or the entire molecule
by fix rigid/small, adof = 0.0 and cdof could be set to the remaining degrees of freedom for the entire molecule (entire
chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid molecule.
The file keyword allows a filename to be specified. Every Nfreq timesteps, a section of chunk info will be written to a
text file in the following format. A line with the timestep and number of chunks is written. Then one line per chunk is
written, containing the chunk ID (1-Nchunk), an optional original ID value, optional coordinate values for chunks that
represent spatial bins, the number of atoms in the chunk, and one or more calculated values. More explanation of the
optional values is given below. The number of values in each line corresponds to the number of values specified in the
fix ave/chunk command. The number of atoms and the value(s) are summed or average quantities, as explained above.
The overwrite keyword will continuously overwrite the output file with the latest output, so that it only contains one
timestep worth of output. This option can only be used with the ave running setting.
The format keyword sets the numeric format of each value when it is printed to a file via the file keyword. Note that
all values are floating point quantities. The default format is %g. You can specify a higher precision if desired, e.g.
%20.16g.
The title1 and title2 and title3 keywords allow specification of the strings that will be printed as the first 3 lines of the
output file, assuming the file keyword was used. LAMMPS uses default values for each of these, so they do not need
to be specified.

1048 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

By default, these header lines are as follows:

# Chunk-averaged data for fix ID and group name

# Timestep Number-of-chunks
# Chunk (OrigID) (Coord1) (Coord2) (Coord3) Ncount value1 value2 ...

In the first line, ID and name are replaced with the fix-ID and group name. The second line describes the two values
that are printed at the first of each section of output. In the third line the values are replaced with the appropriate value
names, e.g. fx or c_myCompute[2].
The words in parenthesis only appear with corresponding columns if the chunk style specified for the compute
chunk/atom command supports them. The OrigID column is only used if the compress keyword was set to yes for
the compute chunk/atom command. This means that the original chunk IDs (e.g. molecule IDs) will have been com-
pressed to remove chunk IDs with no atoms assigned to them. Thus a compressed chunk ID of 3 may correspond to an
original chunk ID or molecule ID of 415. The OrigID column will list 415 for the third chunk.
The CoordN columns only appear if a binning style was used in the compute chunk/atom command. For bin/1d, bin/2d,
and bin/3d styles the column values are the center point of the bin in the corresponding dimension. Just Coord1 is
used for bin/1d, Coord2 is added for bin/2d, Coord3 is added for bin/3d. For bin/sphere, just Coord1 is used, and it is
the radial coordinate. For bin/cylinder, Coord1 and Coord2 are used. Coord1 is the radial coordinate (away from the
cylinder axis), and coord2 is the coordinate along the cylinder axis.
Note that if the value of the units keyword used in the compute chunk/atom command is box or lattice, the coordinate
values will be in distance units. If the value of the units keyword is reduced, the coordinate values will be in unitless
reduced units (0-1). This is not true for the Coord1 value of style bin/sphere or bin/cylinder which both represent radial
dimensions. Those values are always in distance units.

17.10.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global array of values which can be accessed by various output commands. The values can only be
accessed on timesteps that are multiples of Nfreq since that is when averaging is performed. The global array has # of
rows = the number of chunks Nchunk as calculated by the specified compute chunk/atom command. The # of columns
= M+1+Nvalues, where M = 1 to 4, depending on whether the optional columns for OrigID and CoordN are used, as
explained above. Following the optional columns, the next column contains the count of atoms in the chunk, and the
remaining columns are the Nvalue quantities. When the array is accessed with a row I that exceeds the current number
of chunks, than a 0.0 is returned by the fix instead of an error, since the number of chunks can vary as a simulation runs
depending on how that value is computed by the compute chunk/atom command.
The array values calculated by this fix are treated as “intensive”, since they are typically already normalized by the
count of atoms in each chunk.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.10. fix ave/chunk command 1049

LAMMPS Documentation, Release stable 29Sep2021

17.10.5 Restrictions

none

17.10.6 Related commands

compute, fix ave/atom, fix ave/histo, fix ave/time, variable, fix ave/correlate

17.10.7 Default

The option defaults are norm = all, ave = one, bias = none, no file output, and title 1,2,3 = strings as described above.

17.11 fix ave/correlate command

17.11.1 Syntax

fix ID group-ID ave/correlate Nevery Nrepeat Nfreq value1 value2 ... keyword args ...

• ID, group-ID are documented in fix command

• ave/correlate = style name of this fix command
• Nevery = use input values every this many timesteps
• Nrepeat = # of correlation time windows to accumulate
• Nfreq = calculate time window averages every this many timesteps
• one or more input values can be listed
• value = c_ID, c_ID[N], f_ID, f_ID[N], v_name

c_ID = global scalar calculated by a compute with ID

c_ID[I] = Ith component of global vector calculated by a compute with ID, I can␣
,→include wildcard (see below)

f_ID = global scalar calculated by a fix with ID

f_ID[I] = Ith component of global vector calculated by a fix with ID, I can include␣
,→wildcard (see below)

v_name = global value calculated by an equal-style variable with name

v_name[I] = Ith component of a vector-style variable with name

• zero or more keyword/arg pairs may be appended

• keyword = type or ave or start or prefactor or file or overwrite or title1 or title2 or title3
type arg = auto or upper or lower or auto/upper or auto/lower or full
auto = correlate each value with itself
upper = correlate each value with each succeeding value
lower = correlate each value with each preceding value
auto/upper = auto + upper
auto/lower = auto + lower
full = correlate each value with every other value, including itself = auto +␣
,→upper + lower

ave args = one or running

1050 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

one = zero the correlation accumulation every Nfreq steps

running = accumulate correlations continuously
start args = Nstart
Nstart = start accumulating correlations on this timestep
prefactor args = value
value = prefactor to scale all the correlation data by
file arg = filename
filename = name of file to output correlation data to
overwrite arg = none = overwrite output file with only latest output
title1 arg = string
string = text to print as 1st line of output file
title2 arg = string
string = text to print as 2nd line of output file
title3 arg = string
string = text to print as 3rd line of output file

17.11.2 Examples

fix 1 all ave/correlate 5 100 1000 c_myTemp file temp.correlate

fix 1 all ave/correlate 1 50 10000 &
c_thermo_press[1] c_thermo_press[2] c_thermo_press[3] &
type upper ave running title1 "My correlation data"

fix 1 all ave/correlate 1 50 10000 c_thermo_press[*]

17.11.3 Description

Use one or more global scalar values as inputs every few timesteps, calculate time correlations between them at varying
time intervals, and average the correlation data over longer timescales. The resulting correlation values can be time
integrated by variables or used by other output commands such as thermo_style custom, and can also be written to a
file. See the fix ave/correlate/long command for an alternate method for computing correlation functions efficiently
over very long time windows.
The group specified with this command is ignored. However, note that specified values may represent calculations
performed by computes and fixes which store their own “group” definitions.
Each listed value can be the result of a compute or fix or the evaluation of an equal-style or vector-style variable. In
each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to
spatial- or time-average or histogram per-atom quantities from a compute, fix, or variable, then see the fix ave/chunk,
fix ave/atom, or fix ave/histo commands. If you wish to convert a per-atom quantity into a single global value, see the
compute reduce command.
The input values must be all scalars. What kinds of correlations between input values are calculated is determined by
the type keyword as discussed below.
Computes that produce global quantities are those which do not have the word atom in their style name. Only a few
fixes produce global quantities. See the doc pages for individual fixes for info on which ones produce such values.
Variables of style equal and vector are the only ones that can be used with this fix. Variables of style atom cannot be
used, since they produce per-atom values.
Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the
index to effectively specify multiple values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the size of the
vector (for mode = scalar) or the number of columns in the array (for mode = vector), then an asterisk with no numeric

17.11. fix ave/correlate command 1051

LAMMPS Documentation, Release stable 29Sep2021

values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk
means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual elements of the vector had been listed one by one. E.g. these 2 fix
ave/correlate commands are equivalent, since the compute pressure command creates a global vector with 6 values.

compute myPress all pressure NULL

fix 1 all ave/correlate 1 50 10000 c_myPress[*]
fix 1 all ave/correlate 1 50 10000 &
c_myPress[1] c_myPress[2] c_myPress[3] &
c_myPress[4] c_myPress[5] c_myPress[6]

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be used to calculate corre-
lation data. The input values are sampled every Nevery timesteps. The correlation data for the preceding samples is
computed on timesteps that are a multiple of Nfreq. Consider a set of samples from some initial time up to an output
timestep. The initial time could be the beginning of the simulation or the last output time; see the ave keyword for
options. For the set of samples, the correlation value Cij is calculated as:
Cij(delta) = ave(Vi(t)*Vj(t+delta))
which is the correlation value between input values Vi and Vj, separated by time delta. Note that the second value Vj
in the pair is always the one sampled at the later time. The ave() represents an average over every pair of samples in
the set that are separated by time delta. The maximum delta used is of size (Nrepeat-1)*Nevery. Thus the correlation
between a pair of input values yields Nrepeat correlation datums:
Cij(0), Cij(Nevery), Cij(2*Nevery), ..., Cij((Nrepeat-1)*Nevery)
For example, if Nevery=5, Nrepeat=6, and Nfreq=100, then values on timesteps 0,5,10,15,. . . ,100 will be used to
compute the final averages on timestep 100. Six averages will be computed: Cij(0), Cij(5), Cij(10), Cij(15), Cij(20),
and Cij(25). Cij(10) on timestep 100 will be the average of 19 samples, namely Vi(0)*Vj(10), Vi(5)*Vj(15), Vi(10)*V
j20), Vi(15)*Vj(25), . . . , Vi(85)*Vj(95), Vi(90)*Vj(100).
Nfreq must be a multiple of Nevery; Nevery and Nrepeat must be non-zero. Also, if the ave keyword is set to one which
is the default, then Nfreq >= (Nrepeat-1)*Nevery is required.

If a value begins with “c_”, a compute ID must follow which has been previously defined in the input script. If no
bracketed term is appended, the global scalar calculated by the compute is used. If a bracketed term is appended, the
Ith element of the global vector calculated by the compute is used. See the discussion above for how I can be specified
with a wildcard asterisk to effectively specify multiple values.
Note that there is a compute reduce command which can sum per-atom quantities into a global scalar or vector which
can thus be accessed by fix ave/correlate. Or it can be a compute defined not in your input script, but by thermodynamic
output or other fixes such as fix nvt or fix temp/rescale. See the doc pages for these commands which give the IDs of
these computes. Users can also write code for their own compute styles and add them to LAMMPS.
If a value begins with “f_”, a fix ID must follow which has been previously defined in the input script. If no bracketed
term is appended, the global scalar calculated by the fix is used. If a bracketed term is appended, the Ith element of the
global vector calculated by the fix is used. See the discussion above for how I can be specified with a wildcard asterisk
to effectively specify multiple values.
Note that some fixes only produce their values on certain timesteps, which must be compatible with Nevery, else an
error will result. Users can also write code for their own fix styles and add them to LAMMPS.
If a value begins with “v_”, a variable name must follow which has been previously defined in the input script. Only
equal-style or vector-style variables can be referenced; the latter requires a bracketed term to specify the Ith element of
the vector calculated by the variable. See the variable command for details. Note that variables of style equal or vector
define a formula which can reference individual atom properties or thermodynamic keywords, or they can invoke other

1052 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

computes, fixes, or variables when they are evaluated, so this is a very general means of specifying quantities to time
correlate.

Additional optional keywords also affect the operation of this fix.

The type keyword determines which pairs of input values are correlated with each other. For N input values Vi, for i
= 1 to N, let the number of pairs = Npair. Note that the second value in the pair Vi(t)*Vj(t+delta) is always the one
sampled at the later time.
• If type is set to auto then each input value is correlated with itself. I.e. Cii = Vi*Vi, for i = 1 to N, so Npair = N.
• If type is set to upper then each input value is correlated with every succeeding value. I.e. Cij = Vi*Vj, for i < j,
so Npair = N*(N-1)/2.
• If type is set to lower then each input value is correlated with every preceding value. I.e. Cij = Vi*Vj, for i > j,
so Npair = N*(N-1)/2.
• If type is set to auto/upper then each input value is correlated with itself and every succeeding value. I.e. Cij =
Vi*Vj, for i >= j, so Npair = N*(N+1)/2.
• If type is set to auto/lower then each input value is correlated with itself and every preceding value. I.e. Cij =
Vi*Vj, for i <= j, so Npair = N*(N+1)/2.
• If type is set to full then each input value is correlated with itself and every other value. I.e. Cij = Vi*Vj, for i,j
= 1,N so Npair = N^2.
The ave keyword determines what happens to the accumulation of correlation samples every Nfreq timesteps. If the
ave setting is one, then the accumulation is restarted or zeroed every Nfreq timesteps. Thus the outputs on successive
Nfreq timesteps are essentially independent of each other. The exception is that the Cij(0) = Vi(T)*Vj(T) value at a
timestep T, where T is a multiple of Nfreq, contributes to the correlation output both at time T and at time T+Nfreq.
If the ave setting is running, then the accumulation is never zeroed. Thus the output of correlation data at any timestep is
the average over samples accumulated every Nevery steps since the fix was defined. it can only be restarted by deleting
the fix via the unfix command, or by re-defining the fix by re-specifying it.
The start keyword specifies what timestep the accumulation of correlation samples will begin on. The default is step
0. Setting it to a larger value can avoid adding non-equilibrated data to the correlation averages.
The prefactor keyword specifies a constant which will be used as a multiplier on the correlation data after it is averaged.
It is effectively a scale factor on Vi*Vj, which can be used to account for the size of the time window or other unit
conversions.
The file keyword allows a filename to be specified. Every Nfreq steps, an array of correlation data is written to the file.
The number of rows is Nrepeat, as described above. The number of columns is the Npair+2, also as described above.
Thus the file ends up to be a series of these array sections.
The overwrite keyword will continuously overwrite the output file with the latest output, so that it only contains one
timestep worth of output. This option can only be used with the ave running setting.
The title1 and title2 and title3 keywords allow specification of the strings that will be printed as the first 3 lines of the
output file, assuming the file keyword was used. LAMMPS uses default values for each of these, so they do not need
to be specified.
By default, these header lines are as follows:
# Time-correlated data for fix ID
# TimeStep Number-of-time-windows
# Index TimeDelta Ncount valueI*valueJ valueI*valueJ ...
In the first line, ID is replaced with the fix-ID. The second line describes the two values that are printed at the first of
each section of output. In the third line the value pairs are replaced with the appropriate fields from the fix ave/correlate
command.

17.11. fix ave/correlate command 1053

LAMMPS Documentation, Release stable 29Sep2021

Let Sij = a set of time correlation data for input values I and J, namely the Nrepeat values:
Sij = Cij(0), Cij(Nevery), Cij(2*Nevery), ..., Cij(*Nrepeat-1)*Nevery)
As explained below, these datums are output as one column of a global array, which is effectively the correlation matrix.
The trap function defined for equal-style variables can be used to perform a time integration of this vector of datums,
using a trapezoidal rule. This is useful for calculating various quantities which can be derived from time correlation
data. If a normalization factor is needed for the time integration, it can be included in the variable formula or via the
prefactor keyword.

17.11.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global array of values which can be accessed by various output commands. The values can only
be accessed on timesteps that are multiples of Nfreq since that is when averaging is performed. The global array has
# of rows = Nrepeat and # of columns = Npair+2. The first column has the time delta (in timesteps) between the pairs
of input values used to calculate the correlation, as described above. The second column has the number of samples
contributing to the correlation average, as described above. The remaining Npair columns are for I,J pairs of the N
input values, as determined by the type keyword, as described above.
• For type = auto, the Npair = N columns are ordered: C11, C22, . . . , CNN.
• For type = upper, the Npair = N*(N-1)/2 columns are ordered: C12, C13, . . . , C1N, C23, . . . , C2N, C34, . . . ,
CN-1N.
• For type = lower, the Npair = N*(N-1)/2 columns are ordered: C21, C31, C32, C41, C42, C43, . . . , CN1, CN2,
. . . , CNN-1.
• For type = auto/upper, the Npair = N*(N+1)/2 columns are ordered: C11, C12, C13, . . . , C1N, C22, C23, . . . ,
C2N, C33, C34, . . . , CN-1N, CNN.
• For type = auto/lower, the Npair = N*(N+1)/2 columns are ordered: C11, C21, C22, C31, C32, C33, C41, . . . ,
C44, CN1, CN2, . . . , CNN-1, CNN.
• For type = full, the Npair = N^2 columns are ordered: C11, C12, . . . , C1N, C21, C22, . . . , C2N, C31, . . . , C3N,
. . . , CN1, . . . , CNN-1, CNN.
The array values calculated by this fix are treated as intensive. If you need to divide them by the number of atoms, you
must do this in a later processing step, e.g. when using them in a variable.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.11.5 Restrictions

none

1054 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.11.6 Related commands

fix ave/correlate/long, compute, fix ave/time, fix ave/atom, fix ave/chunk, fix ave/histo, variable

17.11.7 Default

none
The option defaults are ave = one, type = auto, start = 0, no file output, title 1,2,3 = strings as described above, and
prefactor = 1.0.

17.12 fix ave/correlate/long command

17.12.1 Syntax

fix ID group-ID ave/correlate/long Nevery Nfreq value1 value2 ... keyword args ...

• ID, group-ID are documented in fix command

• ave/correlate/long = style name of this fix command
• Nevery = use input values every this many timesteps
• Nfreq = save state of the time correlation functions every this many timesteps
• one or more input values can be listed
• value = c_ID, c_ID[N], f_ID, f_ID[N], v_name

c_ID = global scalar calculated by a compute with ID

c_ID[I] = Ith component of global vector calculated by a compute with ID
f_ID = global scalar calculated by a fix with ID
f_ID[I] = Ith component of global vector calculated by a fix with ID
v_name = global value calculated by an equal-style variable with name

• zero or more keyword/arg pairs may be appended

• keyword = type or start or file or overwrite or title1 or title2 or ncorr or nlen or ncount
type arg = auto or upper or lower or auto/upper or auto/lower or full
auto = correlate each value with itself
upper = correlate each value with each succeeding value
lower = correlate each value with each preceding value
auto/upper = auto + upper
auto/lower = auto + lower
full = correlate each value with every other value, including itself = auto +␣
,→upper + lower

start args = Nstart

Nstart = start accumulating correlations on this timestep
file arg = filename
filename = name of file to output correlation data to
overwrite arg = none = overwrite output file with only latest output
title1 arg = string
string = text to print as 1st line of output file
title2 arg = string

17.12. fix ave/correlate/long command 1055

LAMMPS Documentation, Release stable 29Sep2021

string = text to print as 2nd line of output file

ncorr arg = Ncorrelators
Ncorrelators = number of correlators to store
nlen args = Nlen
Nlen = length of each correlator
ncount args = Ncount
Ncount = number of values over which successive correlators are averaged

17.12.2 Examples

fix 1 all ave/correlate/long 5 1000 c_myTemp file temp.correlate

fix 1 all ave/correlate/long 1 10000 &
c_thermo_press[1] c_thermo_press[2] c_thermo_press[3] &
type upper title1 "My correlation data" nlen 15 ncount 3

17.12.3 Description

This fix is similar in spirit and syntax to the fix ave/correlate. However, this fix allows the efficient calculation of
time correlation functions on-the-fly over extremely long time windows with little additional CPU overhead, using a
multiple-tau method (Ramirez) that decreases the resolution of the stored correlation function with time. It is not a full
drop-in replacement.
The group specified with this command is ignored. However, note that specified values may represent calculations
performed by computes and fixes which store their own “group” definitions.
Each listed value can be the result of a compute or fix or the evaluation of an equal-style variable. See the fix
ave/correlate page for details.
The Nevery and Nfreq arguments specify on what timesteps the input values will be used to calculate correlation data,
and the frequency with which the time correlation functions will be output to a file. Note that there is no Nrepeat
argument, unlike the fix ave/correlate command.
The optional keywords ncorr, nlen, and ncount are unique to this command and determine the number of correlation
points calculated and the memory and CPU overhead used by this calculation. Nlen and ncount determine the amount
of averaging done at longer correlation times. The default values nlen=16, ncount=2 ensure that the systematic error
of the multiple-tau correlator is always below the level of the statistical error of a typical simulation (which depends
on the ensemble size and the simulation length).
The maximum correlation time (in time steps) that can be reached is given by the formula (nlen-1) * ncount^(ncorr-
1). Longer correlation times are discarded and not calculated. With the default values of the parameters (ncorr=20,
nlen=16 and ncount=2), this corresponds to 7864320 time steps. If longer correlation times are needed, the value of
ncorr should be increased. Using nlen=16 and ncount=2, with ncorr=30, the maximum number of steps that can be
correlated is 80530636808. If ncorr=40, correlation times in excess of 8e12 time steps can be calculated.
The total memory needed for each correlation pair is roughly 4*ncorr*nlen*8 bytes. With the default values of the
parameters, this corresponds to about 10 KB.
For the meaning of the additional optional keywords, see the fix ave/correlate doc page.

1056 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.12.4 Restart, fix_modify, output, run start/stop, minimize info

Contrary to fix ave/correlate this fix does not provide access to its internal data to various output options. Since this fix
in intended for the calculation of time correlation functions over very long MD simulations, the information about this
fix is written automatically to binary restart files, so that the time correlation calculation can continue in subsequent
simulations. None of the fix_modify options are relevant to this fix.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.12.5 Restrictions

This compute is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.

17.12.6 Related commands

fix ave/correlate

17.12.7 Default

none
The option defaults for keywords that are also keywords for the fix ave/correlate command are as follows: type = auto,
start = 0, no file output, title 1,2 = strings as described on the fix ave/correlate doc page.
The option defaults for keywords unique to this command are as follows: ncorr=20, nlen=16, ncount=2.

(Ramirez) J. Ramirez, S.K. Sukumaran, B. Vorselaars and A.E. Likhtman, J. Chem. Phys. 133, 154103 (2010).

17.13 fix ave/histo command

17.14 fix ave/histo/weight command

17.14.1 Syntax

fix ID group-ID style Nevery Nrepeat Nfreq lo hi Nbin value1 value2 ... keyword args ...

• ID, group-ID are documented in fix command

• style = ave/histo or ave/histo/weight = style name of this fix command
• Nevery = use input values every this many timesteps
• Nrepeat = # of times to use input values for calculating histogram
• Nfreq = calculate histogram every this many timesteps
• lo,hi = lo/hi bounds within which to histogram
• Nbin = # of histogram bins

17.13. fix ave/histo command 1057

LAMMPS Documentation, Release stable 29Sep2021

• one or more input values can be listed

• value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID[N], f_ID, f_ID[N], v_name

x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component)

c_ID = scalar or vector calculated by a compute with ID
c_ID[I] = Ith component of vector or Ith column of array calculated by a compute␣
,→with ID, I can include wildcard (see below)

f_ID = scalar or vector calculated by a fix with ID

f_ID[I] = Ith component of vector or Ith column of array calculated by a fix with␣
,→ID, I can include wildcard (see below)

v_name = value(s) calculated by an equal-style or vector-style or atom-style␣

,→variable with name

v_name[I] = value calculated by a vector-style variable with name

• zero or more keyword/arg pairs may be appended

• keyword = mode or file or ave or start or beyond or overwrite or title1 or title2 or title3
mode arg = scalar or vector
scalar = all input values are scalars
vector = all input values are vectors
kind arg = global or peratom or local
file arg = filename
filename = name of file to output histogram(s) to
ave args = one or running or window
one = output a new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
start args = Nstart
Nstart = start averaging on this timestep
beyond arg = ignore or end or extra
ignore = ignore values outside histogram lo/hi bounds
end = count values outside histogram lo/hi bounds in end bins
extra = create 2 extra bins for value outside histogram lo/hi bounds
overwrite arg = none = overwrite output file with only latest output
title1 arg = string
string = text to print as 1st line of output file
title2 arg = string
string = text to print as 2nd line of output file
title3 arg = string
string = text to print as 3rd line of output file, only for vector mode

17.14.2 Examples

fix 1 all ave/histo 100 5 1000 0.5 1.5 50 c_myTemp file temp.histo ave running
fix 1 all ave/histo 100 5 1000 -5 5 100 c_thermo_press[2] c_thermo_press[3] title1 "My␣
,→output values"

fix 1 all ave/histo 100 5 1000 -5 5 100 c_thermo_press[*]

fix 1 all ave/histo 1 100 1000 -2.0 2.0 18 vx vy vz mode vector ave running beyond extra
fix 1 all ave/histo/weight 1 1 1 10 100 2000 c_XRD[1] c_XRD[2]

1058 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.14.3 Description

Use one or more values as inputs every few timesteps to create a single histogram. The histogram can then be averaged
over longer timescales. The resulting histogram can be used by other output commands, and can also be written to
a file. The fix ave/histo/weight command has identical syntax to fix ave/histo, except that exactly two values must be
specified. See details below.
The group specified with this command is ignored for global and local input values. For per-atom input values, only
atoms in the group contribute to the histogram. Note that regardless of the specified group, specified values may
represent calculations performed by computes and fixes which store their own “group” definition.
A histogram is simply a count of the number of values that fall within a histogram bin. Nbins are defined, with even
spacing between lo and hi. Values that fall outside the lo/hi bounds can be treated in different ways; see the discussion
of the beyond keyword below.
Each input value can be an atom attribute (position, velocity, force component) or can be the result of a compute or fix or
the evaluation of an equal-style or vector-style or atom-style variable. The set of input values can be either all global, all
per-atom, or all local quantities. Inputs of different kinds (e.g. global and per-atom) cannot be mixed. Atom attributes
are per-atom vector values. See the page for individual “compute” and “fix” commands to see what kinds of quantities
they generate. See the optional kind keyword below for how to force the fix ave/histo command to disambiguate if
necessary.
Note that the output of this command is a single histogram for all input values combined together, not one histogram
per input value. See below for details on the format of the output of this fix.
The input values must either be all scalars or all vectors (or arrays), depending on the setting of the mode keyword.
If mode = scalar, then the input values must be scalars, or vectors with a bracketed term appended, indicating the Ith
value of the vector is used.
If mode = vector, then the input values must be vectors, or arrays with a bracketed term appended, indicating the Ith
column of the array is used.
Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the
index to effectively specify multiple values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the size of the
vector (for mode = scalar) or the number of columns in the array (for mode = vector), then an asterisk with no numeric
values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk
means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual elements of the vector or columns of the array had been listed one by
one. E.g. these 2 fix ave/histo commands are equivalent, since the compute com/chunk command creates a global array
with 3 columns:

compute myCOM all com/chunk

fix 1 all ave/histo 100 1 100 -10.0 10.0 100 c_myCOM[*] file tmp1.com mode vector
fix 2 all ave/histo 100 1 100 -10.0 10.0 100 c_myCOM[1] c_myCOM[2] c_myCOM[3] file tmp2.
,→com mode vector

If the fix ave/histo/weight command is used, exactly two values must be specified. If the values are vectors, they must
be the same length. The first value (a scalar or vector) is what is histogrammed into bins, in the same manner the fix
ave/histo command operates. The second value (a scalar or vector) is used as a “weight”. This means that instead of
each value tallying a “1” to its bin, the corresponding weight is tallied. E.g. The Nth entry (weight) in the second vector
is tallied to the bin corresponding to the Nth entry in the first vector.

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be used in order to contribute
to the histogram. The final histogram is generated on timesteps that are multiple of Nfreq. It is averaged over Nrepeat
histograms, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a multiple

17.14. fix ave/histo/weight command 1059

LAMMPS Documentation, Release stable 29Sep2021

of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the histogram value
cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then input values on timesteps 90,92,94,96,98,100 will be used
to compute the final histogram on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc.
If Nrepeat=1 and Nfreq = 100, then no time averaging of the histogram is done; a histogram is simply generated on
timesteps 100,200,etc.

The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are self-explanatory. Note that other atom attributes can be used as
inputs to this fix by using the compute property/atom command and then specifying an input value from that compute.
If a value begins with “c_”, a compute ID must follow which has been previously defined in the input script. If mode
= scalar, then if no bracketed term is appended, the global scalar calculated by the compute is used. If a bracketed
term is appended, the Ith element of the global vector calculated by the compute is used. If mode = vector, then if no
bracketed term is appended, the global or per-atom or local vector calculated by the compute is used. If a bracketed
term is appended, the Ith column of the global or per-atom or local array calculated by the compute is used. See the
discussion above for how I can be specified with a wildcard asterisk to effectively specify multiple values.
Note that there is a compute reduce command which can sum per-atom quantities into a global scalar or vector which
can thus be accessed by fix ave/histo. Or it can be a compute defined not in your input script, but by thermodynamic
output or other fixes such as fix nvt or fix temp/rescale. See the doc pages for these commands which give the IDs of
these computes. Users can also write code for their own compute styles and add them to LAMMPS.
If a value begins with “f_”, a fix ID must follow which has been previously defined in the input script. If mode = scalar,
then if no bracketed term is appended, the global scalar calculated by the fix is used. If a bracketed term is appended,
the Ith element of the global vector calculated by the fix is used. If mode = vector, then if no bracketed term is appended,
the global or per-atom or local vector calculated by the fix is used. If a bracketed term is appended, the Ith column of
the global or per-atom or local array calculated by the fix is used. See the discussion above for how I can be specified
with a wildcard asterisk to effectively specify multiple values.
Note that some fixes only produce their values on certain timesteps, which must be compatible with Nevery, else an
error will result. Users can also write code for their own fix styles and add them to LAMMPS.
If a value begins with “v_”, a variable name must follow which has been previously defined in the input script. If mode
= scalar, then only equal-style or vector-style variables can be used, which both produce global values. In this mode,
a vector-style variable requires a bracketed term to specify the Ith element of the vector calculated by the variable. If
mode = vector, then only vector-style or atom-style variables can be used, which produce a global or per-atom vector
respectively. The vector-style variable must be used without a bracketed term. See the variable command for details.
Note that variables of style equal, vector, and atom define a formula which can reference individual atom properties or
thermodynamic keywords, or they can invoke other computes, fixes, or variables when they are evaluated, so this is a
very general means of specifying quantities to histogram.

Additional optional keywords also affect the operation of this fix.

If the mode keyword is set to scalar, then all input values must be global scalars, or elements of global vectors. If the
mode keyword is set to vector, then all input values must be global or per-atom or local vectors, or columns of global
or per-atom or local arrays.
The kind keyword only needs to be set if a compute or fix produces more than one kind of output (global, per-atom,
local). If this is not the case, then LAMMPS will determine what kind of input is provided and whether all the input
arguments are consistent. If a compute or fix produces more than one kind of output, the kind keyword should be used
to specify which output will be used. The remaining input arguments must still be consistent.
The beyond keyword determines how input values that fall outside the lo to hi bounds are treated. Values such that lo
<= value <= hi are assigned to one bin. Values on a bin boundary are assigned to the lower of the 2 bins. If beyond is
set to ignore then values < lo and values > hi are ignored, i.e. they are not binned. If beyond is set to end then values <

1060 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

lo are counted in the first bin and values > hi are counted in the last bin. If beyond is set to extend then two extra bins
are created, so that there are Nbins+2 total bins. Values < lo are counted in the first bin and values > hi are counted in
the last bin (Nbins+2). Values between lo and hi (inclusive) are counted in bins 2 through Nbins+1. The “coordinate”
stored and printed for these two extra bins is lo and hi.
The ave keyword determines how the histogram produced every Nfreq steps are averaged with histograms produced on
previous steps that were multiples of Nfreq, before they are accessed by another output command or written to a file.
If the ave setting is one, then the histograms produced on timesteps that are multiples of Nfreq are independent of each
other; they are output as-is without further averaging.
If the ave setting is running, then the histograms produced on timesteps that are multiples of Nfreq are summed and
averaged in a cumulative sense before being output. Each bin value in the histogram is thus the average of the bin
value produced on that timestep with all preceding values for the same bin. This running average begins when the fix
is defined; it can only be restarted by deleting the fix via the unfix command, or by re-defining the fix by re-specifying
it.
If the ave setting is window, then the histograms produced on timesteps that are multiples of Nfreq are summed within a
moving “window” of time, so that the last M histograms are used to produce the output. E.g. if M = 3 and Nfreq = 1000,
then the output on step 10000 will be the combined histogram of the individual histograms on steps 8000,9000,10000.
Outputs on early steps will be sums over less than M histograms if they are not available.
The start keyword specifies what timestep histogramming will begin on. The default is step 0. Often input values can
be 0.0 at time 0, so setting start to a larger value can avoid including a 0.0 in a running or windowed histogram.
The file keyword allows a filename to be specified. Every Nfreq steps, one histogram is written to the file. This includes a
leading line that contains the timestep, number of bins, the total count of values contributing to the histogram, the count
of values that were not histogrammed (see the beyond keyword), the minimum value encountered, and the maximum
value encountered. The min/max values include values that were not histogrammed. Following the leading line, one
line per bin is written into the file. Each line contains the bin #, the coordinate for the center of the bin (between lo and
hi), the count of values in the bin, and the normalized count. The normalized count is the bin count divided by the total
count (not including values not histogrammed), so that the normalized values sum to 1.0 across all bins.
The overwrite keyword will continuously overwrite the output file with the latest output, so that it only contains one
timestep worth of output. This option can only be used with the ave running setting.
The title1 and title2 and title3 keywords allow specification of the strings that will be printed as the first 3 lines of the
output file, assuming the file keyword was used. LAMMPS uses default values for each of these, so they do not need
to be specified.
By default, these header lines are as follows:

# Histogram for fix ID

# TimeStep Number-of-bins Total-counts Missing-counts Min-value Max-value
# Bin Coord Count Count/Total

In the first line, ID is replaced with the fix-ID. The second line describes the six values that are printed at the first of
each section of output. The third describes the 4 values printed for each bin in the histogram.

17.14. fix ave/histo/weight command 1061

LAMMPS Documentation, Release stable 29Sep2021

17.14.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix produces a global vector and global array which can be accessed by various output commands. The values can
only be accessed on timesteps that are multiples of Nfreq since that is when a histogram is generated. The global vector
has 4 values:
• 1 = total counts in the histogram
• 2 = values that were not histogrammed (see beyond keyword)
• 3 = min value of all input values, including ones not histogrammed
• 4 = max value of all input values, including ones not histogrammed
The global array has # of rows = Nbins and # of columns = 3. The first column has the bin coordinate, the second
column has the count of values in that histogram bin, and the third column has the bin count divided by the total count
(not including missing counts), so that the values in the third column sum to 1.0.
The vector and array values calculated by this fix are all treated as intensive. If this is not the case, e.g. due to
histogramming per-atom input values, then you will need to account for that when interpreting the values produced by
this fix.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.14.5 Restrictions

none

17.14.6 Related commands

compute, fix ave/atom, fix ave/chunk, fix ave/time, variable, fix ave/correlate,

17.14.7 Default

none
The option defaults are mode = scalar, kind = figured out from input arguments, ave = one, start = 0, no file output,
beyond = ignore, and title 1,2,3 = strings as described above.

17.15 fix ave/time command

17.15.1 Syntax

fix ID group-ID ave/time Nevery Nrepeat Nfreq value1 value2 ... keyword args ...

• ID, group-ID are documented in fix command

• ave/time = style name of this fix command
• Nevery = use input values every this many timesteps
• Nrepeat = # of times to use input values for calculating averages

1062 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• Nfreq = calculate averages every this many timesteps

• one or more input values can be listed
• value = c_ID, c_ID[N], f_ID, f_ID[N], v_name

c_ID = global scalar or vector calculated by a compute with ID

c_ID[I] = Ith component of global vector or Ith column of global array calculated␣
,→by a compute with ID, I can include wildcard (see below)

f_ID = global scalar or vector calculated by a fix with ID

f_ID[I] = Ith component of global vector or Ith column of global array calculated␣
,→by a fix with ID, I can include wildcard (see below)

v_name = value(s) calculated by an equal-style or vector-style variable with name

v_name[I] = value calculated by a vector-style variable with name

• zero or more keyword/arg pairs may be appended

• keyword = mode or file or ave or start or off or overwrite or title1 or title2 or title3
mode arg = scalar or vector
scalar = all input values are global scalars
vector = all input values are global vectors or global arrays
ave args = one or running or window M
one = output a new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
start args = Nstart
Nstart = start averaging on this timestep
off arg = M = do not average this value
M = value # from 1 to Nvalues
file arg = filename
filename = name of file to output time averages to
overwrite arg = none = overwrite output file with only latest output
format arg = string
string = C-style format string
title1 arg = string
string = text to print as 1st line of output file
title2 arg = string
string = text to print as 2nd line of output file
title3 arg = string
string = text to print as 3rd line of output file, only for vector mode

17.15.2 Examples

fix 1 all ave/time 100 5 1000 c_myTemp c_thermo_temp file temp.profile

fix 1 all ave/time 100 5 1000 c_thermo_press[2] ave window 20 &
title1 "My output values"
fix 1 all ave/time 100 5 1000 c_thermo_press[*]
fix 1 all ave/time 1 100 1000 f_indent f_indent[1] file temp.indent off 1

17.15. fix ave/time command 1063

LAMMPS Documentation, Release stable 29Sep2021

17.15.3 Description

Use one or more global values as inputs every few timesteps, and average them over longer timescales. The resulting
averages can be used by other output commands such as thermo_style custom, and can also be written to a file. Note
that if no time averaging is done, this command can be used as a convenient way to simply output one or more global
values to a file.
The group specified with this command is ignored. However, note that specified values may represent calculations
performed by computes and fixes which store their own “group” definitions.
Each listed value can be the result of a compute or fix or the evaluation of an equal-style or vector-style variable. In
each case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity. If you wish to
spatial- or time-average or histogram per-atom quantities from a compute, fix, or variable, then see the fix ave/chunk,
fix ave/atom, or fix ave/histo commands. If you wish to sum a per-atom quantity into a single global quantity, see the
compute reduce command.
Computes that produce global quantities are those which do not have the word atom in their style name. Only a few
fixes produce global quantities. See the doc pages for individual fixes for info on which ones produce such values.
Variables of style equal and vector are the only ones that can be used with this fix. Variables of style atom cannot be
used, since they produce per-atom values.
The input values must either be all scalars or all vectors depending on the setting of the mode keyword. In both cases,
the averaging is performed independently on each input value. I.e. each input scalar is averaged independently or each
element of each input vector is averaged independently.
If mode = scalar, then the input values must be scalars, or vectors with a bracketed term appended, indicating the Ith
value of the vector is used.
If mode = vector, then the input values must be vectors, or arrays with a bracketed term appended, indicating the Ith
column of the array is used. All vectors must be the same length, which is the length of the vector or number of rows
in the array.
Note that for values from a compute or fix, the bracketed index I can be specified using a wildcard asterisk with the
index to effectively specify multiple values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the size of the
vector (for mode = scalar) or the number of columns in the array (for mode = vector), then an asterisk with no numeric
values means all indices from 1 to N. A leading asterisk means all indices from 1 to n (inclusive). A trailing asterisk
means all indices from n to N (inclusive). A middle asterisk means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual elements of the vector or columns of the array had been listed one by
one. E.g. these 2 fix ave/time commands are equivalent, since the compute rdf command creates, in this case, a global
array with 3 columns, each of length 50:

compute myRDF all rdf 50 1 2

fix 1 all ave/time 100 1 100 c_myRDF[*] file tmp1.rdf mode vector
fix 2 all ave/time 100 1 100 c_myRDF[1] c_myRDF[2] c_myRDF[3] file tmp2.rdf mode vector

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be used in order to contribute
to the average. The final averaged quantities are generated on timesteps that are a multiple of Nfreq. The average is
over Nrepeat quantities, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a
multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the average
value cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on timesteps 90,92,94,96,98,100 will be used to
compute the final average on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc. If
Nrepeat=1 and Nfreq = 100, then no time averaging is done; values are simply generated on timesteps 100,200,etc.

1064 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

If a value begins with “c_”, a compute ID must follow which has been previously defined in the input script. If mode
= scalar, then if no bracketed term is appended, the global scalar calculated by the compute is used. If a bracketed
term is appended, the Ith element of the global vector calculated by the compute is used. If mode = vector, then if no
bracketed term is appended, the global vector calculated by the compute is used. If a bracketed term is appended, the
Ith column of the global array calculated by the compute is used. See the discussion above for how I can be specified
with a wildcard asterisk to effectively specify multiple values.
Note that there is a compute reduce command which can sum per-atom quantities into a global scalar or vector which
can thus be accessed by fix ave/time. Or it can be a compute defined not in your input script, but by thermodynamic
output or other fixes such as fix nvt or fix temp/rescale. See the doc pages for these commands which give the IDs of
these computes. Users can also write code for their own compute styles and add them to LAMMPS.
If a value begins with “f_”, a fix ID must follow which has been previously defined in the input script. If mode =
scalar, then if no bracketed term is appended, the global scalar calculated by the fix is used. If a bracketed term is
appended, the Ith element of the global vector calculated by the fix is used. If mode = vector, then if no bracketed term
is appended, the global vector calculated by the fix is used. If a bracketed term is appended, the Ith column of the
global array calculated by the fix is used. See the discussion above for how I can be specified with a wildcard asterisk
to effectively specify multiple values.
Note that some fixes only produce their values on certain timesteps, which must be compatible with Nevery, else an
error will result. Users can also write code for their own fix styles and add them to LAMMPS.
If a value begins with “v_”, a variable name must follow which has been previously defined in the input script. If mode
= scalar, then only equal-style or vector-style variables can be used, which both produce global values. In this mode,
a vector-style variable requires a bracketed term to specify the Ith element of the vector calculated by the variable. If
mode = vector, then only a vector-style variable can be used, without a bracketed term. See the variable command for
details.
Note that variables of style equal and vector define a formula which can reference individual atom properties or ther-
modynamic keywords, or they can invoke other computes, fixes, or variables when they are evaluated, so this is a very
general means of specifying quantities to time average.

Additional optional keywords also affect the operation of this fix.

If the mode keyword is set to scalar, then all input values must be global scalars, or elements of global vectors. If the
mode keyword is set to vector, then all input values must be global vectors, or columns of global arrays. They can also
be global arrays, which are converted into a series of global vectors (one per column), as explained above.
The ave keyword determines how the values produced every Nfreq steps are averaged with values produced on previous
steps that were multiples of Nfreq, before they are accessed by another output command or written to a file.
If the ave setting is one, then the values produced on timesteps that are multiples of Nfreq are independent of each
other; they are output as-is without further averaging.
If the ave setting is running, then the values produced on timesteps that are multiples of Nfreq are summed and averaged
in a cumulative sense before being output. Each output value is thus the average of the value produced on that timestep
with all preceding values. This running average begins when the fix is defined; it can only be restarted by deleting the
fix via the unfix command, or by re-defining the fix by re-specifying it.
If the ave setting is window, then the values produced on timesteps that are multiples of Nfreq are summed and averaged
within a moving “window” of time, so that the last M values are used to produce the output. E.g. if M = 3 and Nfreq
= 1000, then the output on step 10000 will be the average of the individual values on steps 8000,9000,10000. Outputs
on early steps will average over less than M values if they are not available.
The start keyword specifies what timestep averaging will begin on. The default is step 0. Often input values can be 0.0
at time 0, so setting start to a larger value can avoid including a 0.0 in a running or windowed average.
The off keyword can be used to flag any of the input values. If a value is flagged, it will not be time averaged. Instead
the most recent input value will always be stored and output. This is useful if one of more of the inputs produced by

17.15. fix ave/time command 1065

LAMMPS Documentation, Release stable 29Sep2021

a compute or fix or variable are effectively constant or are simply current values. E.g. they are being written to a file
with other time-averaged values for purposes of creating well-formatted output.
The file keyword allows a filename to be specified. Every Nfreq steps, one quantity or vector of quantities is written
to the file for each input value specified in the fix ave/time command. For mode = scalar, this means a single line is
written each time output is performed. Thus the file ends up to be a series of lines, i.e. one column of numbers for each
input value. For mode = vector, an array of numbers is written each time output is performed. The number of rows is
the length of the input vectors, and the number of columns is the number of values. Thus the file ends up to be a series
of these array sections.
The overwrite keyword will continuously overwrite the output file with the latest output, so that it only contains one
timestep worth of output. This option can only be used with the ave running setting.
The format keyword sets the numeric format of each value when it is printed to a file via the file keyword. Note that
all values are floating point quantities. The default format is %g. You can specify a higher precision if desired, e.g.
%20.16g.
The title1 and title2 and title3 keywords allow specification of the strings that will be printed as the first 2 or 3 lines
of the output file, assuming the file keyword was used. LAMMPS uses default values for each of these, so they do not
need to be specified.
By default, these header lines are as follows for mode = scalar:

# Time-averaged data for fix ID

# TimeStep value1 value2 ...

In the first line, ID is replaced with the fix-ID. In the second line the values are replaced with the appropriate fields
from the fix ave/time command. There is no third line in the header of the file, so the title3 setting is ignored when
mode = scalar.
By default, these header lines are as follows for mode = vector:

# Time-averaged data for fix ID

# TimeStep Number-of-rows
# Row value1 value2 ...

In the first line, ID is replaced with the fix-ID. The second line describes the two values that are printed at the first
of each section of output. In the third line the values are replaced with the appropriate fields from the fix ave/time
command.

17.15.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix produces a global scalar or global vector or global array which can be accessed by various output commands.
The values can only be accessed on timesteps that are multiples of Nfreq since that is when averaging is performed.
A scalar is produced if only a single input value is averaged and mode = scalar. A vector is produced if multiple input
values are averaged for mode = scalar, or a single input value for mode = vector. In the first case, the length of the vector
is the number of inputs. In the second case, the length of the vector is the same as the length of the input vector. An
array is produced if multiple input values are averaged and mode = vector. The global array has # of rows = length of
the input vectors and # of columns = number of inputs.
If the fix produces a scalar or vector, then the scalar and each element of the vector can be either “intensive” or “exten-
sive”, depending on whether the values contributing to the scalar or vector element are “intensive” or “extensive”. If the
fix produces an array, then all elements in the array must be the same, either “intensive” or “extensive”. If a compute

1066 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

or fix provides the value being time averaged, then the compute or fix determines whether the value is intensive or
extensive; see the page for that compute or fix for further info. Values produced by a variable are treated as intensive.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.15.5 Restrictions

none

17.15.6 Related commands

compute, fix ave/atom, fix ave/chunk, fix ave/histo, variable, fix ave/correlate,

17.15.7 Default

The option defaults are mode = scalar, ave = one, start = 0, no file output, format = %g, title 1,2,3 = strings as described
above, and no off settings for any input values.

17.16 fix aveforce command

17.16.1 Syntax

fix ID group-ID aveforce fx fy fz keyword value ...

• ID, group-ID are documented in fix command

• aveforce = style name of this fix command
• fx,fy,fz = force component values (force units)

any of fx,fy,fz can be a variable (see below)

• zero or more keyword/value pairs may be appended to args

• keyword = region
region value = region-ID
region-ID = ID of region atoms must be in to have added force

17.16.2 Examples

fix pressdown topwall aveforce 0.0 -1.0 0.0

fix 2 bottomwall aveforce NULL -1.0 0.0 region top
fix 2 bottomwall aveforce NULL -1.0 v_oscillate region top

17.16. fix aveforce command 1067

LAMMPS Documentation, Release stable 29Sep2021

17.16.3 Description

Apply an additional external force to a group of atoms in such a way that every atom experiences the same force. This
is useful for pushing on wall or boundary atoms so that the structure of the wall does not change over time.
The existing force is averaged for the group of atoms, component by component. The actual force on each atom is then
set to the average value plus the component specified in this command. This means each atom in the group receives
the same force.
Any of the fx,fy,fz values can be specified as NULL which means the force in that dimension is not changed. Note that
this is not the same as specifying a 0.0 value, since that sets all forces to the same average value without adding in any
additional force.
Any of the 3 quantities defining the force components can be specified as an equal-style variable, namely fx, fy, fz. If
the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable
will be evaluated each timestep, and its value used to determine the average force.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
average force.
If the region keyword is used, the atom must also be in the specified geometric region in order to have force added to
it.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.16.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.
This fix computes a global 3-vector of forces, which can be accessed by various output commands. This is the total
force on the group of atoms before the forces on individual atoms are changed by the fix. The vector values calculated
by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command. You should
not specify force components with a variable that has time-dependence for use with a minimizer, since the minimizer
increments the timestep as the iteration count during the minimization.

1068 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.16.5 Restrictions

none

17.16.6 Related commands

fix setforce, fix addforce

17.16.7 Default

none

17.17 fix balance command

17.17.1 Syntax

fix ID group-ID balance Nfreq thresh style args keyword args ...

• ID, group-ID are documented in fix command

• balance = style name of this fix command
• Nfreq = perform dynamic load balancing every this many steps
• thresh = imbalance threshold that must be exceeded to perform a re-balance
• style = shift or rcb
shift args = dimstr Niter stopthresh
dimstr = sequence of letters containing "x" or "y" or "z", each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshold is reached
rcb args = none
• zero or more keyword/arg pairs may be appended
• keyword = weight or out
weight style args = use weighted particle counts for the balancing
style = group or neigh or time or var or store
group args = Ngroup group1 weight1 group2 weight2 ...
Ngroup = number of groups with assigned weights
group1, group2, ... = group IDs
weight1, weight2, ... = corresponding weight factors
neigh factor = compute weight based on number of neighbors
factor = scaling factor (> 0)
time factor = compute weight based on time spend computing
factor = scaling factor (> 0)
var name = take weight from atom-style variable
name = name of the atom-style variable
store name = store weight in custom atom property defined by fix property/atom␣
,→command

name = atom property name (without d_ prefix)

out arg = filename

17.17. fix balance command 1069

LAMMPS Documentation, Release stable 29Sep2021

filename = write each processor's sub-domain to a file, at each re-balancing

17.17.2 Examples

fix 2 all balance 1000 1.05 shift x 10 1.05

fix 2 all balance 100 0.9 shift xy 20 1.1 out tmp.balance
fix 2 all balance 100 0.9 shift xy 20 1.1 weight group 3 substrate 3.0 solvent 1.0␣
,→solute 0.8 out tmp.balance

fix 2 all balance 100 1.0 shift x 10 1.1 weight time 0.8
fix 2 all balance 100 1.0 shift xy 5 1.1 weight var myweight weight neigh 0.6 weight␣
,→store allweight

fix 2 all balance 1000 1.1 rcb

17.17.3 Description

This command adjusts the size and shape of processor sub-domains within the simulation box, to attempt to balance the
number of particles and thus the computational cost (load) evenly across processors. The load balancing is “dynamic”
in the sense that re-balancing is performed periodically during the simulation. To perform “static” balancing, before or
between runs, see the balance command.
Load-balancing is typically most useful if the particles in the simulation box have a spatially-varying density distribution
or where the computational cost varies significantly between different atoms. E.g. a model of a vapor/liquid interface,
or a solid with an irregular-shaped geometry containing void regions, or hybrid pair style simulations which combine
pair styles with different computational cost. In these cases, the LAMMPS default of dividing the simulation box
volume into a regular-spaced grid of 3d bricks, with one equal-volume sub-domain per processor, may assign numbers
of particles per processor in a way that the computational effort varies significantly. This can lead to poor performance
when the simulation is run in parallel.
The balancing can be performed with or without per-particle weighting. With no weighting, the balancing attempts
to assign an equal number of particles to each processor. With weighting, the balancing attempts to assign an equal
aggregate computational weight to each processor, which typically induces a different number of atoms assigned to
each processor.

Note: The weighting options listed above are documented with the balance command in this section of the balance
command doc page. That section describes the various weighting options and gives a few examples of how they can
be used. The weighting options are the same for both the fix balance and balance commands.

Note that the processors command allows some control over how the box volume is split across processors. Specifically,
for a Px by Py by Pz grid of processors, it allows choice of Px, Py, and Pz, subject to the constraint that Px * Py * Pz =
P, the total number of processors. This is sufficient to achieve good load-balance for some problems on some processor
counts. However, all the processor sub-domains will still have the same shape and same volume.
On a particular timestep, a load-balancing operation is only performed if the current “imbalance factor” in particles
owned by each processor exceeds the specified thresh parameter. The imbalance factor is defined as the maximum
number of particles (or weight) owned by any processor, divided by the average number of particles (or weight) per
processor. Thus an imbalance factor of 1.0 is perfect balance.
As an example, for 10000 particles running on 10 processors, if the most heavily loaded processor has 1200 particles,
then the factor is 1.2, meaning there is a 20% imbalance. Note that re-balances can be forced even if the current balance
is perfect (1.0) be specifying a thresh < 1.0.

Note: This command attempts to minimize the imbalance factor, as defined above. But depending on the method a

1070 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

perfect balance (1.0) may not be achieved. For example, “grid” methods (defined below) that create a logical 3d grid
cannot achieve perfect balance for many irregular distributions of particles. Likewise, if a portion of the system is a
perfect lattice, e.g. the initial system is generated by the create_atoms command, then “grid” methods may be unable
to achieve exact balance. This is because entire lattice planes will be owned or not owned by a single processor.

Note: The imbalance factor is also an estimate of the maximum speed-up you can hope to achieve by running a
perfectly balanced simulation versus an imbalanced one. In the example above, the 10000 particle simulation could
run up to 20% faster if it were perfectly balanced, versus when imbalanced. However, computational cost is not strictly
proportional to particle count, and changing the relative size and shape of processor sub-domains may lead to additional
computational and communication overheads, e.g. in the PPPM solver used via the kspace_style command. Thus you
should benchmark the run times of a simulation before and after balancing.

The method used to perform a load balance is specified by one of the listed styles, which are described in detail below.
There are 2 kinds of styles.
The shift style is a “grid” method which produces a logical 3d grid of processors. It operates by changing the cutting
planes (or lines) between processors in 3d (or 2d), to adjust the volume (area in 2d) assigned to each processor, as in
the following 2d diagram where processor sub-domains are shown and atoms are colored by the processor that owns
them.

The leftmost diagram is the default partitioning of the simulation box across processors (one sub-box for each of 16
processors); the middle diagram is after a “grid” method has been applied. The rcb style is a “tiling” method which
does not produce a logical 3d grid of processors. Rather it tiles the simulation domain with rectangular sub-boxes of
varying size and shape in an irregular fashion so as to have equal numbers of particles (or weight) in each sub-box, as
in the rightmost diagram above.
The “grid” methods can be used with either of the comm_style command options, brick or tiled. The “tiling” methods
can only be used with comm_style tiled.
When a “grid” method is specified, the current domain partitioning can be either a logical 3d grid or a tiled partitioning.
In the former case, the current logical 3d grid is used as a starting point and changes are made to improve the imbalance
factor. In the latter case, the tiled partitioning is discarded and a logical 3d grid is created with uniform spacing in all
dimensions. This is the starting point for the balancing operation.
When a “tiling” method is specified, the current domain partitioning (“grid” or “tiled”) is ignored, and a new partition-
ing is computed from scratch.

The group-ID is ignored. However the impact of balancing on different groups of atoms can be affected by using the
group weight style as described below.

17.17. fix balance command 1071

LAMMPS Documentation, Release stable 29Sep2021

The Nfreq setting determines how often a re-balance is performed. If Nfreq > 0, then re-balancing will occur every
Nfreq steps. Each time a re-balance occurs, a reneighboring is triggered, so Nfreq should not be too small. If Nfreq
= 0, then re-balancing will be done every time reneighboring normally occurs, as determined by the the neighbor and
neigh_modify command settings.
On re-balance steps, re-balancing will only be attempted if the current imbalance factor, as defined above, exceeds the
thresh setting.

The shift style invokes a “grid” method for balancing, as described above. It changes the positions of cutting planes
between processors in an iterative fashion, seeking to reduce the imbalance factor.
The dimstr argument is a string of characters, each of which must be an “x” or “y” or “z”. Each character can appear
zero or one time, since there is no advantage to balancing on a dimension more than once. You should normally only
list dimensions where you expect there to be a density variation in the particles.
Balancing proceeds by adjusting the cutting planes in each of the dimensions listed in dimstr, one dimension at a time.
For a single dimension, the balancing operation (described below) is iterated on up to Niter times. After each dimension
finishes, the imbalance factor is re-computed, and the balancing operation halts if the stopthresh criterion is met.
A re-balance operation in a single dimension is performed using a density-dependent recursive multisectioning algo-
rithm, where the position of each cutting plane (line in 2d) in the dimension is adjusted independently. This is similar
to a recursive bisectioning for a single value, except that the bounds used for each bisectioning take advantage of infor-
mation from neighboring cuts if possible, as well as counts of particles at the bounds on either side of each cuts, which
themselves were cuts in previous iterations. The latter is used to infer a density of particles near each of the current
cuts. At each iteration, the count of particles on either side of each plane is tallied. If the counts do not match the target
value for the plane, the position of the cut is adjusted based on the local density. The low and high bounds are adjusted
on each iteration, using new count information, so that they become closer together over time. Thus as the recursion
progresses, the count of particles on either side of the plane gets closer to the target value.
The density-dependent part of this algorithm is often an advantage when you re-balance a system that is already nearly
balanced. It typically converges more quickly than the geometric bisectioning algorithm used by the balance command.
However, if can be a disadvantage if you attempt to re-balance a system that is far from balanced, and converge more
slowly. In this case you probably want to use the balance command before starting a run, so that you begin the run with
a balanced system.
Once the re-balancing is complete and final processor sub-domains assigned, particles migrate to their new owning
processor as part of the normal reneighboring procedure.

Note: At each re-balance operation, the bisectioning for each cutting plane (line in 2d) typically starts with low and
high bounds separated by the extent of a processor’s sub-domain in one dimension. The size of this bracketing region
shrinks based on the local density, as described above, which should typically be 1/2 or more every iteration. Thus if
Niter is specified as 10, the cutting plane will typically be positioned to better than 1 part in 1000 accuracy (relative to
the perfect target position). For Niter = 20, it will be accurate to better than 1 part in a million. Thus there is no need
to set Niter to a large value. This is especially true if you are re-balancing often enough that each time you expect only
an incremental adjustment in the cutting planes is necessary. LAMMPS will check if the threshold accuracy is reached
(in a dimension) is less iterations than Niter and exit early.

The rcb style invokes a “tiled” method for balancing, as described above. It performs a recursive coordinate bisectioning
(RCB) of the simulation domain. The basic idea is as follows.
The simulation domain is cut into 2 boxes by an axis-aligned cut in the longest dimension, leaving one new box on
either side of the cut. All the processors are also partitioned into 2 groups, half assigned to the box on the lower side of
the cut, and half to the box on the upper side. (If the processor count is odd, one side gets an extra processor.) The cut
is positioned so that the number of atoms in the lower box is exactly the number that the processors assigned to that box

1072 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

should own for load balance to be perfect. This also makes load balance for the upper box perfect. The positioning is
done iteratively, by a bisectioning method. Note that counting atoms on either side of the cut requires communication
between all processors at each iteration.
That is the procedure for the first cut. Subsequent cuts are made recursively, in exactly the same manner. The subset
of processors assigned to each box make a new cut in the longest dimension of that box, splitting the box, the subset of
processors, and the atoms in the box in two. The recursion continues until every processor is assigned a sub-box of the
entire simulation domain, and owns the atoms in that sub-box.

The out keyword writes text to the specified filename with the results of each re-balancing operation. The file contains
the bounds of the sub-domain for each processor after the balancing operation completes. The format of the file is
compatible with the Pizza.py mdump tool which has support for manipulating and visualizing mesh files. An example
is shown here for a balancing by 4 processors for a 2d problem:

ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
16
ITEM: BOX BOUNDS
0 10
0 10
0 10
ITEM: NODES
1 1 0 0 0
2 1 5 0 0
3 1 5 5 0
4 1 0 5 0
5 1 5 0 0
6 1 10 0 0
7 1 10 5 0
8 1 5 5 0
9 1 0 5 0
10 1 5 5 0
11 1 5 10 0
12 1 10 5 0
13 1 5 5 0
14 1 10 5 0
15 1 10 10 0
16 1 5 10 0
ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
4
ITEM: SQUARES
1 1 1 2 3 4
2 1 5 6 7 8
3 1 9 10 11 12
4 1 13 14 15 16

The coordinates of all the vertices are listed in the NODES section, 5 per processor. Note that the 4 sub-domains share
vertices, so there will be duplicate nodes in the list.
The “SQUARES” section lists the node IDs of the 4 vertices in a rectangle for each processor (1 to 4).

17.17. fix balance command 1073

LAMMPS Documentation, Release stable 29Sep2021

For a 3d problem, the syntax is similar with 8 vertices listed for each processor, instead of 4, and “SQUARES” replaced
by “CUBES”.

17.17.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global scalar which is the imbalance factor after the most recent re-balance and a global vector of
length 3 with additional information about the most recent re-balancing. The 3 values in the vector are as follows:
• 1 = max # of particles per processor
• 2 = total # iterations performed in last re-balance
• 3 = imbalance factor right before the last re-balance was performed
As explained above, the imbalance factor is the ratio of the maximum number of particles (or total weight) on any
processor to the average number of particles (or total weight) per processor.
These quantities can be accessed by various output commands. The scalar and vector values calculated by this fix are
“intensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.17.5 Restrictions

For 2d simulations, the z style cannot be used. Nor can a “z” appear in dimstr for the shift style.
Balancing through recursive bisectioning (rcb style) requires comm_style tiled

17.17.6 Related commands

group, processors, balance, comm_style

17.17.7 Default

none

17.18 fix bocs command

17.18.1 Syntax

fix ID group-ID bocs keyword values ...

keyword = temp or cgiso or analytic or linear_spline or cubic_spline

temp values = Tstart Tstop Tdamp
cgiso values = Pstart Pstop Pdamp
basis set

1074 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

analytic values = V_avg N_particles N_coeff Coeff_1 Coeff_2 ... Coeff_N

linear_spline values = input_filename
cubic_spline values = input_filename

17.18.2 Examples

fix 1 all bocs temp 300.0 300.0 100.0 cgiso 0.986 0.986 1000.0 analytic 66476.015 968 2␣
,→245030.10 8962.20

fix 1 all bocs temp 300.0 300.0 100.0 cgiso 0.986 0.986 1000.0 cubic_spline input_Fv.dat

thermo_modify press 1_press

17.18.3 Description

These commands incorporate a pressure correction as described by Dunn and Noid in (Dunn1) to the standard MTTK
barostat by Martyna et. al. in (Martyna) . The first half of the command mimics a standard fix npt command:

fix 1 all bocs temp Tstart Tstop Tcoupl cgiso Pstart Pstop Pdamp

The two differences are replacing npt with bocs, and replacing iso/aniso/etc with cgiso. The rest of the command
details what form you would like to use for the pressure correction equation. The choices are: analytic, linear_spline,
or cubic_spline.
With either spline method, the only argument that needs to follow it is the name of a file that contains the desired
pressure correction as a function of volume. The file must be formatted so each line has:

Volume_i, PressureCorrection_i

Note both the COMMA and the SPACE separating the volume’s value and its corresponding pressure correction. The
volumes in the file must be uniformly spaced. Both the volumes and the pressure corrections should be provided in the
proper units, e.g. if you are using units real, the volumes should all be in cubic angstroms, and the pressure corrections
should all be in atmospheres. Furthermore, the table should start/end at a volume considerably smaller/larger than you
expect your system to sample during the simulation. If the system ever reaches a volume outside of the range provided,
the simulation will stop.
With the analytic option, the arguments are as follows:

... analytic V_avg N_particles N_coeff Coeff_1 Coeff_2 ... Coeff_N

Note that V_avg and Coeff_i should all be in the proper units, e.g. if you are using units real, V_avg should be in cubic
angstroms, and the coefficients should all be in atmospheres * cubic angstroms.

17.18. fix bocs command 1075

LAMMPS Documentation, Release stable 29Sep2021

17.18.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the cumulative global energy change to binary restart files. See the read_restart command for info on
how to re-specify a fix in an input script that reads a restart file, so that the fix continues in an uninterrupted fashion.
The fix_modify temp option is supported by this fix. You can use it to assign a temperature compute you have defined
to this fix which will be used in its thermostatting procedure, as described above. For consistency, the group used by
this fix and by the compute should be the same.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.18.5 Restrictions

As this is computing a (modified) pressure, group-ID should be all.

The pressure correction has only been tested for use with an isotropic pressure coupling in 3 dimensions.
By default, LAMMPS will still report the normal value for the pressure if the pressure is printed via a thermo command,
or if the pressures are written to a file every so often. In order to have LAMMPS report the modified pressure, you must
include the thermo_modify command given in the examples. For the last argument in the command, you should put
XXXX_press, where XXXX is the ID given to the fix bocs command (in the example, the ID of the fix bocs command
is 1 ).
This fix is part of the BOCS package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.

17.18.6 Further information

For more details about the pressure correction and the entire BOCS software package, visit the BOCS package on
GitHub and read the release paper by Dunn et. al. (Dunn2) .

(Dunn1) Dunn and Noid, J Chem Phys, 143, 243148 (2015).

(Martyna) Martyna, Tobias, and Klein, J Chem Phys, 101, 4177 (1994).
(Dunn2) Dunn, Lebold, DeLyser, Rudzinski, and Noid, J. Phys. Chem. B, 122, 3363 (2018).

1076 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.19 fix bond/break command

17.19.1 Syntax

fix ID group-ID bond/break Nevery bondtype Rmax keyword values ...

• ID, group-ID are documented in fix command

• bond/break = style name of this fix command
• Nevery = attempt bond breaking every this many steps
• bondtype = type of bonds to break
• Rmax = bond longer than Rmax can break (distance units)
• zero or more keyword/value pairs may be appended to args
• keyword = prob
prob values = fraction seed
fraction = break a bond with this probability if otherwise eligible
seed = random number seed (positive integer)

17.19.2 Examples

fix 5 all bond/break 10 2 1.2

fix 5 polymer bond/break 1 1 2.0 prob 0.5 49829

17.19.3 Description

Break bonds between pairs of atoms as a simulation runs according to specified criteria. This can be used to model the
dissolution of a polymer network due to stretching of the simulation box or other deformations. In this context, a bond
means an interaction between a pair of atoms computed by the bond_style command. Once the bond is broken it will
be permanently deleted, as will all angle, dihedral, and improper interactions that bond is part of.
This is different than a pairwise bond-order potential such as Tersoff or AIREBO which infers bonds and many-body
interactions based on the current geometry of a small cluster of atoms and effectively creates and destroys bonds and
higher-order many-body interactions from timestep to timestep as atoms move.
A check for possible bond breakage is performed every Nevery timesteps. If two bonded atoms I,J are further than a
distance Rmax of each other, if the bond is of type bondtype, and if both I and J are in the specified fix group, then I,J
is labeled as a “possible” bond to break.
If several bonds involving an atom are stretched, it may have multiple possible bonds to break. Every atom checks its
list of possible bonds to break and labels the longest such bond as its “sole” bond to break. After this is done, if atom
I is bonded to atom J in its sole bond, and atom J is bonded to atom I in its sole bond, then the I,J bond is “eligible” to
be broken.
Note that these rules mean an atom will only be part of at most one broken bond on a given timestep. It also means
that if atom I chooses atom J as its sole partner, but atom J chooses atom K is its sole partner (due to Rjk > Rij), then
this means atom I will not be part of a broken bond on this timestep, even if it has other possible bond partners.
The prob keyword can effect whether an eligible bond is actually broken. The fraction setting must be a value between
0.0 and 1.0. A uniform random number between 0.0 and 1.0 is generated and the eligible bond is only broken if the
random number < fraction.

17.19. fix bond/break command 1077

LAMMPS Documentation, Release stable 29Sep2021

When a bond is broken, data structures within LAMMPS that store bond topology are updated to reflect the breakage.
Likewise, if the bond is part of a 3-body (angle) or 4-body (dihedral, improper) interaction, that interaction is removed
as well. These changes typically affect pairwise interactions between atoms that used to be part of bonds, angles, etc.

Note: One data structure that is not updated when a bond breaks are the molecule IDs stored by each atom. Even
though one molecule becomes two molecules due to the broken bond, all atoms in both new molecules retain their
original molecule IDs.

Computationally, each timestep this fix operates, it loops over all the bonds in the system and computes distances
between pairs of bonded atoms. It also communicates between neighboring processors to coordinate which bonds
are broken. Moreover, if any bonds are broken, neighbor lists must be immediately updated on the same timestep.
This is to insure that any pairwise interactions that should be turned “on” due to a bond breaking, because they are
no longer excluded by the presence of the bond and the settings of the special_bonds command, will be immediately
recognized. All of these operations increase the cost of a timestep. Thus you should be cautious about invoking this
fix too frequently.
You can dump out snapshots of the current bond topology via the dump local command.

Note: Breaking a bond typically alters the energy of a system. You should be careful not to choose bond breaking
criteria that induce a dramatic change in energy. For example, if you define a very stiff harmonic bond and break it
when 2 atoms are separated by a distance far from the equilibrium bond length, then the 2 atoms will be dramatically
released when the bond is broken. More generally, you may need to thermostat your system to compensate for energy
changes resulting from broken bonds (and angles, dihedrals, impropers).

17.19.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes two statistics which it stores in a global vector of length 2, which can be accessed by various output
commands. The vector values calculated by this fix are “intensive”.
These are the 2 quantities:
• (1) # of bonds broken on the most recent breakage timestep
• (2) cumulative # of bonds broken
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.19.5 Restrictions

This fix is part of the MC package. It is only enabled if LAMMPS was built with that package. See the Build package
doc page for more info.

1078 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.19.6 Related commands

fix bond/create, fix bond/react, fix bond/swap, dump local, special_bonds

17.19.7 Default

The option defaults are prob = 1.0.

17.20 fix bond/create command

17.21 fix bond/create/angle command

17.21.1 Syntax

fix ID group-ID bond/create Nevery itype jtype Rmin bondtype keyword values ...

• ID, group-ID are documented in fix command

• bond/create = style name of this fix command
• Nevery = attempt bond creation every this many steps
• itype,jtype = atoms of itype can bond to atoms of jtype
• Rmin = 2 atoms separated by less than Rmin can bond (distance units)
• bondtype = type of created bonds
• zero or more keyword/value pairs may be appended to args
• keyword = iparam or jparam or prob or atype or dtype or itype or aconstrain
iparam values = maxbond, newtype
maxbond = max # of bonds of bondtype the itype atom can have
newtype = change the itype atom to this type when maxbonds exist
jparam values = maxbond, newtype
maxbond = max # of bonds of bondtype the jtype atom can have
newtype = change the jtype atom to this type when maxbonds exist
prob values = fraction seed
fraction = create a bond with this probability if otherwise eligible
seed = random number seed (positive integer)
atype value = angletype
angletype = type of created angles
dtype value = dihedraltype
dihedraltype = type of created dihedrals
itype value = impropertype
impropertype = type of created impropers
aconstrain value = amin amax
amin = minimal angle at which new bonds can be created
amax = maximal angle at which new bonds can be created

17.20. fix bond/create command 1079

LAMMPS Documentation, Release stable 29Sep2021

17.21.2 Examples

fix 5 all bond/create 10 1 2 0.8 1

fix 5 all bond/create 1 3 3 0.8 1 prob 0.5 85784 iparam 2 3
fix 5 all bond/create 1 3 3 0.8 1 prob 0.5 85784 iparam 2 3 atype 1 dtype 2
fix 5 all bond/create/angle 10 1 2 1.122 1 aconstrain 120 180 prob 1 4928459 iparam 2 1␣
,→jparam 2 2

17.21.3 Description

Create bonds between pairs of atoms as a simulation runs according to specified criteria. This can be used to model
cross-linking of polymers, the formation of a percolation network, etc. In this context, a bond means an interaction
between a pair of atoms computed by the bond_style command. Once the bond is created it will be permanently in
place. Optionally, the creation of a bond can also create angle, dihedral, and improper interactions that bond is part of.
See the discussion of the atype, dtype, and itype keywords below.
This is different than a pairwise bond-order potential such as Tersoff or AIREBO which infers bonds and many-body
interactions based on the current geometry of a small cluster of atoms and effectively creates and destroys bonds and
higher-order many-body interactions from timestep to timestep as atoms move.
A check for possible new bonds is performed every Nevery timesteps. If two atoms I,J are within a distance Rmin of
each other, if I is of atom type itype, if J is of atom type jtype, if both I and J are in the specified fix group, if a bond does
not already exist between I and J, and if both I and J meet their respective maxbond requirement (explained below),
then I,J is labeled as a “possible” bond pair.
If several atoms are close to an atom, it may have multiple possible bond partners. Every atom checks its list of possible
bond partners and labels the closest such partner as its “sole” bond partner. After this is done, if atom I has atom J as
its sole partner, and atom J has atom I as its sole partner, then the I,J bond is “eligible” to be formed.
Note that these rules mean an atom will only be part of at most one created bond on a given timestep. It also means
that if atom I chooses atom J as its sole partner, but atom J chooses atom K is its sole partner (due to Rjk < Rij), then
this means atom I will not form a bond on this timestep, even if it has other possible bond partners.
It is permissible to have itype = jtype. Rmin must be <= the pairwise cutoff distance between itype and jtype atoms, as
defined by the pair_style command.
The iparam and jparam keywords can be used to limit the bonding functionality of the participating atoms. Each atom
keeps track of how many bonds of bondtype it already has. If atom I of itype already has maxbond bonds (as set by the
iparam keyword), then it will not form any more. Likewise for atom J. If maxbond is set to 0, then there is no limit on
the number of bonds that can be formed with that atom.
The newtype value for iparam and jparam can be used to change the atom type of atom I or J when it reaches maxbond
number of bonds of type bondtype. This means it can now interact in a pairwise fashion with other atoms in a different
way by specifying different pair_coeff coefficients. If you do not wish the atom type to change, simply specify newtype
as itype or jtype.
The prob keyword can also effect whether an eligible bond is actually created. The fraction setting must be a value
between 0.0 and 1.0. A uniform random number between 0.0 and 1.0 is generated and the eligible bond is only created
if the random number < fraction.
The aconstrain keyword is only available with the fix bond/create/angle command. It allows to specify a minimal and
maximal angle amin and amax between the two prospective bonding partners and a third particle that is already bonded
to one of the two partners. Such a criterion can be important when new angles are defined together with the formation
of a new bond. Without a restriction on the permissible angle, and for stiffer angle potentials, very large energies can
arise and lead to uncontrolled behavior.
Any bond that is created is assigned a bond type of bondtype.

1080 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

When a bond is created, data structures within LAMMPS that store bond topology are updated to reflect the creation.
If the bond is part of new 3-body (angle) or 4-body (dihedral, improper) interactions, you can choose to create new
angles, dihedrals, impropers as well, using the atype, dtype, and itype keywords. All of these changes typically affect
pairwise interactions between atoms that are now part of new bonds, angles, etc.

Note: One data structure that is not updated when a bond breaks are the molecule IDs stored by each atom. Even
though two molecules become one molecule due to the created bond, all atoms in the new molecule retain their original
molecule IDs.

If the atype keyword is used and if an angle potential is defined via the angle_style command, then any new 3-body
interactions inferred by the creation of a bond will create new angles of type angletype, with parameters assigned by the
corresponding angle_coeff command. Likewise, the dtype and itype keywords will create new dihedrals and impropers
of type dihedraltype and impropertype.

Note: To create a new bond, the internal LAMMPS data structures that store this information must have space for
it. When LAMMPS is initialized from a data file, the list of bonds is scanned and the maximum number of bonds per
atom is tallied. If some atom will acquire more bonds than this limit as this fix operates, then the “extra bond per atom”
parameter must be set to allow for it. Ditto for “extra angle per atom”, “extra dihedral per atom”, and “extra improper
per atom” if angles, dihedrals, or impropers are being added when bonds are created. See the read_data or create_box
command for more details. Note that a data file with no atoms can be used if you wish to add non-bonded atoms via
the create atoms command, e.g. for a percolation simulation.

Note: LAMMPS stores and maintains a data structure with a list of the first, second, and third neighbors of each atom
(within the bond topology of the system) for use in weighting pairwise interactions for bonded atoms. Note that adding
a single bond always adds a new first neighbor but may also induce *many* new second and third neighbors, depending
on the molecular topology of your system. The “extra special per atom” parameter must typically be set to allow for
the new maximum total size (first + second + third neighbors) of this per-atom list. There are 2 ways to do this. See
the read_data or create_box commands for details.

Note: Even if you do not use the atype, dtype, or itype keywords, the list of topological neighbors is updated for atoms
affected by the new bond. This in turn affects which neighbors are considered for pairwise interactions, using the
weighting rules set by the special_bonds command. Consider a new bond created between atoms I,J. If J has a bonded
neighbor K, then K becomes a second neighbor of I. Even if the atype keyword is not used to create angle I-J-K, the
pairwise interaction between I and K will be potentially turned off or weighted by the 1-3 weighting specified by the
special_bonds command. This is the case even if the “angle yes” option was used with that command. The same is true
for third neighbors (1-4 interactions), the dtype keyword, and the “dihedral yes” option used with the special_bonds
command.

Note that even if your simulation starts with no bonds, you must define a bond_style and use the bond_coeff command
to specify coefficients for the bondtype. Similarly, if new atom types are specified by the iparam or jparam keywords,
they must be within the range of atom types allowed by the simulation and pairwise coefficients must be specified for
the new types.
Computationally, each timestep this fix operates, it loops over neighbor lists and computes distances between pairs
of atoms in the list. It also communicates between neighboring processors to coordinate which bonds are created.
Moreover, if any bonds are created, neighbor lists must be immediately updated on the same timestep. This is to insure
that any pairwise interactions that should be turned “off” due to a bond creation, because they are now excluded by the
presence of the bond and the settings of the special_bonds command, will be immediately recognized. All of these
operations increase the cost of a timestep. Thus you should be cautious about invoking this fix too frequently.

17.21. fix bond/create/angle command 1081

LAMMPS Documentation, Release stable 29Sep2021

You can dump out snapshots of the current bond topology via the dump local command.

Note: Creating a bond typically alters the energy of a system. You should be careful not to choose bond creation criteria
that induce a dramatic change in energy. For example, if you define a very stiff harmonic bond and create it when 2
atoms are separated by a distance far from the equilibrium bond length, then the 2 atoms will oscillate dramatically
when the bond is formed. More generally, you may need to thermostat your system to compensate for energy changes
resulting from created bonds (and angles, dihedrals, impropers).

17.21.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes two statistics which it stores in a global vector of length 2, which can be accessed by various output
commands. The vector values calculated by this fix are “intensive”.
These are the 2 quantities:
• (1) # of bonds created on the most recent creation timestep
• (2) cumulative # of bonds created
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.21.5 Restrictions

This fix is part of the MC package. It is only enabled if LAMMPS was built with that package. See the Build package
doc page for more info.

17.21.6 Related commands

fix bond/break, fix bond/react, fix bond/swap, dump local, special_bonds

17.21.7 Default

The option defaults are iparam = (0,itype), jparam = (0,jtype), and prob = 1.0.

17.22 fix bond/react command

17.22.1 Syntax

fix ID group-ID bond/react common_keyword values ...

react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-
,→ID(post-reacted) map_file individual_keyword values ...

react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-

,→ID(post-reacted) map_file individual_keyword values ...

(continues on next page)

1082 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-
,→ID(post-reacted) map_file individual_keyword values ...

...

• ID, group-ID are documented in fix command.

• bond/react = style name of this fix command
• the common keyword/values may be appended directly after ‘bond/react’
• common keywords apply to all reaction specifications
• common_keyword = stabilization or reset_mol_ids
stabilization values = no or yes group-ID xmax
no = no reaction site stabilization (default)
yes = perform reaction site stabilization
group-ID = user-assigned prefix for the dynamic group of atoms not currently␣
,→involved in a reaction

xmax = xmax value that is used by an internally-created nve/limit integrator

reset_mol_ids values = yes or no
yes = update molecule IDs based on new global topology (default)
no = do not update molecule IDs
• react = mandatory argument indicating new reaction specification
• react-ID = user-assigned name for the reaction
• react-group-ID = only atoms in this group are considered for the reaction
• Nevery = attempt reaction every this many steps
• Rmin = initiator atoms must be separated by more than Rmin to initiate reaction (distance units)
• Rmax = initiator atoms must be separated by less than Rmax to initiate reaction (distance units)
• template-ID(pre-reacted) = ID of a molecule template containing pre-reaction topology
• template-ID(post-reacted) = ID of a molecule template containing post-reaction topology
• map_file = name of file specifying corresponding atom-IDs in the pre- and post-reacted templates
• zero or more individual keyword/value pairs may be appended to each react argument
• individual_keyword = prob or max_rxn or stabilize_steps or custom_charges or molecule or modify_create
prob values = fraction seed
fraction = initiate reaction with this probability if otherwise eligible
seed = random number seed (positive integer)
max_rxn value = N
N = maximum number of reactions allowed to occur
stabilize_steps value = timesteps
timesteps = number of timesteps to apply the internally-created nve/limit fix to␣
,→reacting atoms

custom_charges value = no or fragmentID

no = update all atomic charges (default)
fragmentID = ID of molecule fragment whose charges are updated
molecule value = off or inter or intra
off = allow both inter- and intramolecular reactions (default)
inter = search for reactions between molecules with different IDs
intra = search for reactions within the same molecule

17.22. fix bond/react command 1083

LAMMPS Documentation, Release stable 29Sep2021

modify_create keyword values

fit value = all or fragmentID
all = use all eligible atoms for create-atoms fit (default)
fragmentID = ID of molecule fragment used for create-atoms fit
overlap value = R
R = only insert atom/molecule if further than R from existing particles␣
,→(distance units)

17.22.2 Examples

For unabridged example scripts and files, see examples/PACKAGES/reaction.

molecule mol1 pre_reacted_topology.txt
molecule mol2 post_reacted_topology.txt
fix 5 all bond/react react myrxn1 all 1 0 3.25 mol1 mol2 map_file.txt

molecule mol1 pre_reacted_rxn1.txt

molecule mol2 post_reacted_rxn1.txt
molecule mol3 pre_reacted_rxn2.txt
molecule mol4 post_reacted_rxn2.txt
fix 5 all bond/react stabilization yes nvt_grp .03 &
react myrxn1 all 1 0 3.25 mol1 mol2 map_file_rxn1.txt prob 0.50 12345 &
react myrxn2 all 1 0 2.75 mol3 mol4 map_file_rxn2.txt prob 0.25 12345
fix 6 nvt_grp_REACT nvt temp 300 300 100 # set thermostat after bond/react

17.22.3 Description

Initiate complex covalent bonding (topology) changes. These topology changes will be referred to as ‘reactions’
throughout this documentation. Topology changes are defined in pre- and post-reaction molecule templates and can
include creation and deletion of bonds, angles, dihedrals, impropers, bond types, angle types, dihedral types, atom
types, or atomic charges. In addition, reaction by-products or other molecules can be identified and deleted. Finally,
atoms can be created and inserted at specific positions relative to the reaction site.
Fix bond/react does not use quantum mechanical (eg. fix qmmm) or pairwise bond-order potential (eg. Tersoff or
AIREBO) methods to determine bonding changes a priori. Rather, it uses a distance-based probabilistic criteria to
effect predetermined topology changes in simulations using standard force fields.
This fix was created to facilitate the dynamic creation of polymeric, amorphous or highly cross-linked systems. A
suggested workflow for using this fix is: 1) identify a reaction to be simulated 2) build a molecule template of the
reaction site before the reaction has occurred 3) build a molecule template of the reaction site after the reaction has
occurred 4) create a map that relates the template-atom-IDs of each atom between pre- and post-reaction molecule
templates 5) fill a simulation box with molecules and run a simulation with fix bond/react.
Only one ‘fix bond/react’ command can be used at a time. Multiple reactions can be simultaneously applied by speci-
fying multiple react arguments to a single ‘fix bond/react’ command. This syntax is necessary because the ‘common
keywords’ are applied to all reactions.
The stabilization keyword enables reaction site stabilization. Reaction site stabilization is performed by including
reacting atoms in an internally-created fix nve/limit time integrator for a set number of timesteps given by the stabi-
lize_steps keyword. While reacting atoms are being time integrated by the internal nve/limit, they are prevented from
being involved in any new reactions. The xmax value keyword should typically be set to the maximum distance that
non-reacting atoms move during the simulation.
Fix bond/react creates and maintains two important dynamic groups of atoms when using the stabilization keyword.
The first group contains all atoms currently involved in a reaction; this group is automatically thermostatted by an

1084 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

internally-created nve/limit integrator. The second group contains all atoms currently not involved in a reaction. This
group should be used by a thermostat in order to time integrate the system. The name of this group of non-reacting
atoms is created by appending ‘_REACT’ to the group-ID argument of the stabilization keyword, as shown in the
second example above.

Note: When using reaction stabilization, you should generally not have a separate thermostat which acts on the ‘all’
group.

The group-ID set using the stabilization keyword can be an existing static group or a previously-unused group-ID.
It cannot be specified as ‘all’. If the group-ID is previously unused, the fix bond/react command creates a dynamic
group that is initialized to include all atoms. If the group-ID is that of an existing static group, the group is used as the
parent group of new, internally-created dynamic group. In both cases, this new dynamic group is named by appending
‘_REACT’ to the group-ID, e.g. nvt_grp_REACT. By specifying an existing group, you may thermostat constant-
topology parts of your system separately. The dynamic group contains only atoms not involved in a reaction at a given
timestep, and therefore should be used by a subsequent system-wide time integrator such as nvt, npt, or nve, as shown
in the second example above (full examples can be found at examples/PACKAGES/reaction). The time integration
command should be placed after the fix bond/react command due to the internal dynamic grouping performed by fix
bond/react.

Note: If the group-ID is an existing static group, react-group-IDs should also be specified as this static group, or a
subset.

The reset_mol_ids keyword invokes the reset_mol_ids command after a reaction occurs, to ensure that molecule IDs
are consistent with the new bond topology. The group-ID used for reset_mol_ids is the group-ID for this fix. Resetting
molecule IDs is necessarily a global operation, and so can be slow for very large systems.
The following comments pertain to each react argument (in other words, can be customized for each reaction, or
reaction step):
A check for possible new reaction sites is performed every Nevery timesteps. Nevery can be specified with an equal-style
variable, whose value is rounded up to the nearest integer.
Three physical conditions must be met for a reaction to occur. First, an initiator atom pair must be identified within
the reaction distance cutoffs. Second, the topology surrounding the initiator atom pair must match the topology of the
pre-reaction template. Only atom types and bond connectivity are used to identify a valid reaction site (not bond types,
etc.). Finally, any reaction constraints listed in the map file (see below) must be satisfied. If all of these conditions are
met, the reaction site is eligible to be modified to match the post-reaction template.
An initiator atom pair will be identified if several conditions are met. First, a pair of atoms I,J within the specified
react-group-ID of type itype and jtype must be separated by a distance between Rmin and Rmax. Rmin and Rmax can
be specified with equal-style variables. For example, these reaction cutoffs can be a function of the reaction conversion
using the following commands:

variable rmax equal 0 # initialize variable before bond/react

fix myrxn all bond/react react myrxn1 all 1 0 v_rmax mol1 mol2 map_file.txt
variable rmax equal 3+f_myrxn[1]/100 # arbitrary function of reaction count

The following criteria are used if multiple candidate initiator atom pairs are identified within the cutoff distance: 1)
If the initiator atoms in the pre-reaction template are not 1-2 neighbors (i.e. not directly bonded) the closest potential
partner is chosen. 2) Otherwise, if the initiator atoms in the pre-reaction template are 1-2 neighbors (i.e. directly
bonded) the farthest potential partner is chosen. 3) Then, if both an atom I and atom J have each other as their initiator
partners, these two atoms are identified as the initiator atom pair of the reaction site. Note that it can be helpful to
select unique atom types for the initiator atoms: if an initiator atom pair is identified, as described in the previous steps,
but does not correspond to the same pair specified in the pre-reaction template, an otherwise eligible reaction could

17.22. fix bond/react command 1085

LAMMPS Documentation, Release stable 29Sep2021

be prevented from occurring. Once this unique initiator atom pair is identified for each reaction, there could be two or
more reactions that involve the same atom on the same timestep. If this is the case, only one such reaction is permitted
to occur. This reaction is chosen randomly from all potential reactions involving the overlapping atom. This capability
allows e.g. for different reaction pathways to proceed from identical reaction sites with user-specified probabilities.
The pre-reacted molecule template is specified by a molecule command. This molecule template file contains a sample
reaction site and its surrounding topology. As described below, the initiator atom pairs of the pre-reacted template are
specified by atom ID in the map file. The pre-reacted molecule template should contain as few atoms as possible while
still completely describing the topology of all atoms affected by the reaction (which includes all atoms that change
atom type or connectivity, and all bonds that change bond type). For example, if the force field contains dihedrals, the
pre-reacted template should contain any atom within three bonds of reacting atoms.
Some atoms in the pre-reacted template that are not reacting may have missing topology with respect to the simulation.
For example, the pre-reacted template may contain an atom that, in the simulation, is currently connected to the rest
of a long polymer chain. These are referred to as edge atoms, and are also specified in the map file. All pre-reaction
template atoms should be linked to an initiator atom, via at least one path that does not involve edge atoms. When the
pre-reaction template contains edge atoms, not all atoms, bonds, charges, etc. specified in the reaction templates will
be updated. Specifically, topology that involves only atoms that are ‘too near’ to template edges will not be updated.
The definition of ‘too near the edge’ depends on which interactions are defined in the simulation. If the simulation has
defined dihedrals, atoms within two bonds of edge atoms are considered ‘too near the edge.’ If the simulation defines
angles, but not dihedrals, atoms within one bond of edge atoms are considered ‘too near the edge.’ If just bonds are
defined, only edge atoms are considered ‘too near the edge.’

Note: Small molecules, i.e. ones that have all their atoms contained within the reaction templates, never have edge
atoms.

Note that some care must be taken when a building a molecule template for a given simulation. All atom types in the
pre-reacted template must be the same as those of a potential reaction site in the simulation. A detailed discussion of
matching molecule template atom types with the simulation is provided on the molecule command page.
The post-reacted molecule template contains a sample of the reaction site and its surrounding topology after the reaction
has occurred. It must contain the same number of atoms as the pre-reacted template (unless there are created atoms).
A one-to-one correspondence between the atom IDs in the pre- and post-reacted templates is specified in the map file
as described below. Note that during a reaction, an atom, bond, etc. type may change to one that was previously not
present in the simulation. These new types must also be defined during the setup of a given simulation. A discussion
of correctly handling this is also provided on the molecule command page.

Note: When a reaction occurs, it is possible that the resulting topology/atom (e.g. special bonds, dihedrals, etc.)
exceeds that of the existing system and reaction templates. As when inserting molecules, enough space for this increased
topology/atom must be reserved by using the relevant “extra” keywords to the read_data or create_box commands.

The map file is a text document with the following format:

A map file has a header and a body. The header of map file the contains one mandatory keyword and five optional
keywords. The mandatory keyword is ‘equivalences’:
N equivalences = # of atoms N in the reaction molecule templates
The optional keywords are ‘edgeIDs’, ‘deleteIDs’, ‘chiralIDs’ and ‘constraints’:
N edgeIDs = # of edge atoms N in the pre-reacted molecule template
N deleteIDs = # of atoms N that are deleted
N createIDs = # of atoms N that are created
N chiralIDs = # of chiral centers N
N constraints = # of reaction constraints N

1086 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The body of the map file contains two mandatory sections and five optional sections. The first mandatory section
begins with the keyword ‘InitiatorIDs’ and lists the two atom IDs of the initiator atom pair in the pre-reacted molecule
template. The second mandatory section begins with the keyword ‘Equivalences’ and lists a one-to-one correspondence
between atom IDs of the pre- and post-reacted templates. The first column is an atom ID of the pre-reacted molecule
template, and the second column is the corresponding atom ID of the post-reacted molecule template. The first optional
section begins with the keyword ‘EdgeIDs’ and lists the atom IDs of edge atoms in the pre-reacted molecule template.
The second optional section begins with the keyword ‘DeleteIDs’ and lists the atom IDs of pre-reaction template atoms
to delete. The third optional section begins with the keyword ‘CreateIDs’ and lists the atom IDs of the post-reaction
template atoms to create. The fourth optional section begins with the keyword ‘ChiralIDs’ lists the atom IDs of chiral
atoms whose handedness should be enforced. The fifth optional section begins with the keyword ‘Constraints’ and lists
additional criteria that must be satisfied in order for the reaction to occur. Currently, there are six types of constraints
available, as discussed below: ‘distance’, ‘angle’, ‘dihedral’, ‘arrhenius’, ‘rmsd’, and ‘custom’.
A sample map file is given below:

# this is a map file

7 equivalences
2 edgeIDs

InitiatorIDs

3
5

EdgeIDs

1
7

Equivalences

1 1
2 2
3 3
4 4
5 5
6 6
7 7

A user-specified set of atoms can be deleted by listing their pre-reaction template IDs in the DeleteIDs section. A
deleted atom must still be included in the post-reaction molecule template, in which it cannot be bonded to an atom
that is not deleted. In addition to deleting unwanted reaction by-products, this feature can be used to remove specific
topologies, such as small rings, that may be otherwise indistinguishable.
Atoms can be created by listing their post-reaction template IDs in the CreateIDs section. A created atom should not
be included in the pre-reaction template. The inserted positions of created atoms are determined by the coordinates of
the post-reaction template, after optimal translation and rotation of the post-reaction template to the reaction site (using
a fit with atoms that are neither created nor deleted). The modify_create keyword can be used to modify the default
behavior when creating atoms. The modify_create keyword has two sub-keywords, fit and overlap. One or more of
the sub-keywords may be used after the modify_create keyword. The fit sub-keyword can be used to specify which
post-reaction atoms are used for the optimal translation and rotation of the post-reaction template. The fragmentID

17.22. fix bond/react command 1087

LAMMPS Documentation, Release stable 29Sep2021

value of the fit sub-keyword must be the name of a molecule fragment defined in the post-reaction molecule template,
and only atoms in this fragment are used for the fit. Atoms are created only if no current atom in the simulation is
within a distance R of any created atom, including the effect of periodic boundary conditions if applicable. R is defined
by the overlap sub-keyword. Note that the default value for R is 0.0, which will allow atoms to strongly overlap if you
are inserting where other atoms are present. The velocity of each created atom is initialized in a random direction with
a magnitude calculated from the instantaneous temperature of the reaction site.
The handedness of atoms that are chiral centers can be enforced by listing their IDs in the ChiralIDs section. A chiral
atom must be bonded to four atoms with mutually different atom types. This feature uses the coordinates and types of
the involved atoms in the pre-reaction template to determine handedness. Three atoms bonded to the chiral center are
arbitrarily chosen, to define an oriented plane, and the relative position of the fourth bonded atom determines the chiral
center’s handedness.
Any number of additional constraints may be specified in the Constraints section of the map file. The constraint of type
‘distance’ has syntax as follows:
distance ID1 ID2 rmin rmax
where ‘distance’ is the required keyword, ID1 and ID2 are pre-reaction atom IDs (or molecule-fragment IDs, see below),
and these two atoms must be separated by a distance between rmin and rmax for the reaction to occur.
The constraint of type ‘angle’ has the following syntax:
angle ID1 ID2 ID3 amin amax
where ‘angle’ is the required keyword, ID1, ID2 and ID3 are pre-reaction atom IDs (or molecule-fragment IDs, see
below), and these three atoms must form an angle between amin and amax for the reaction to occur (where ID2 is the
central atom). Angles must be specified in degrees. This constraint can be used to enforce a certain orientation between
reacting molecules.
The constraint of type ‘dihedral’ has the following syntax:
dihedral ID1 ID2 ID3 ID4 amin amax amin2 amax2
where ‘dihedral’ is the required keyword, and ID1, ID2, ID3 and ID4 are pre-reaction atom IDs (or molecule-fragment
IDs, see below). Dihedral angles are calculated in the interval (-180,180]. Refer to the dihedral style documentation
for further details on convention. If amin is less than amax, these four atoms must form a dihedral angle greater than
amin and less than amax for the reaction to occur. If amin is greater than amax, these four atoms must form a dihedral
angle greater than amin or less than amax for the reaction to occur. Angles must be specified in degrees. Optionally, a
second range of permissible angles amin2-amax2 can be specified.
For the ‘distance’, ‘angle’, and ‘dihedral’ constraints (explained above), atom IDs can be replaced by pre-reaction
molecule-fragment IDs. The molecule-fragment ID must begin with a letter. The location of the ID is the geometric
center of all atom positions in the fragment. The molecule fragment must have been defined in the molecule command
for the pre-reaction template.
The constraint of type ‘arrhenius’ imposes an additional reaction probability according to the temperature-dependent
Arrhenius equation:
−Ea
k = AT n e kB T

The Arrhenius constraint has the following syntax:

arrhenius A n E_a seed
where ‘arrhenius’ is the required keyword, A is the pre-exponential factor, n is the exponent of the temperature depen-
dence, Ea is the activation energy (units of energy), and seed is a random number seed. The temperature is defined as
the instantaneous temperature averaged over all atoms in the reaction site, and is calculated in the same manner as for
example compute temp/chunk. Currently, there are no options for additional temperature averaging or velocity-biased
temperature calculations. A uniform random number between 0 and 1 is generated using seed; if this number is less
than the result of the Arrhenius equation above, the reaction is permitted to occur.

1088 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The constraint of type ‘rmsd’ has the following syntax:

rmsd RMSDmax molfragment
where ‘rmsd’ is the required keyword, and RMSDmax is the maximum root-mean-square deviation between atom
positions of the pre-reaction template and the local reaction site (distance units), after optimal translation and rotation
of the pre-reaction template. Optionally, the name of a molecule fragment (of the pre-reaction template) can be specified
by molfragment. If a molecule fragment is specified, only atoms that are part of this molecule fragment are used to
determine the RMSD. A molecule fragment must have been defined in the molecule command for the pre-reaction
template. For example, the molecule fragment could consist of only the backbone atoms of a polymer chain. This
constraint can be used to enforce a specific relative position and orientation between reacting molecules.
The constraint of type ‘custom’ has the following syntax:
custom varstring
where ‘custom’ is the required keyword, and varstring is a variable expression. The expression must be a valid equal-
style variable formula that can be read by the variable command, after any special reaction functions are evaluated. If
the resulting expression is zero, the reaction is prevented from occurring; otherwise, it is permitted to occur. There
are two special reaction functions available, ‘rxnsum’ and ‘rxnave’. These functions operate over the atoms in a given
reaction site, and have one mandatory argument and one optional argument. The mandatory argument is the identifier
for an atom-style variable. The second, optional argument is the name of a molecule fragment in the pre-reaction
template, and can be used to operate over a subset of atoms in the reaction site. The ‘rxnsum’ function sums the atom-
style variable over the reaction site, while the ‘rxnave’ returns the average value. For example, a constraint on the total
potential energy of atoms involved in the reaction can be imposed as follows:

compute 1 all pe/atom # in LAMMPS input script

variable my_pe atom c_1 # in LAMMPS input script

custom "rxnsum(v_my_pe) > 100" # in Constraints section of map file

The above example prevents the reaction from occurring unless the total potential energy of the reaction site is above
100. The variable expression can be interpreted as the probability of the reaction occurring by using an inequality and
the ‘random(x,y,z)’ function available as an equal-style variable input, similar to the ‘arrhenius’ constraint above.
By default, all constraints must be satisfied for the reaction to occur. In other words, constraints are evaluated as a series
of logical values using the logical AND operator “&&”. More complex logic can be achieved by explicitly adding the
logical AND operator “&&” or the logical OR operator “||” after a given constraint command. If a logical operator
is specified after a constraint, it must be placed after all constraint parameters, on the same line as the constraint (one
per line). Similarly, parentheses can be used to group constraints. The expression that results from concatenating
all constraints should be a valid logical expression that can be read by the variable command after converting each
constraint to a logical value. Because exactly one constraint is allowed per line, having a valid logical expression
implies that left parentheses “(” should only appear before a constraint, and right parentheses “)” should only appear
after a constraint and before any logical operator.
Once a reaction site has been successfully identified, data structures within LAMMPS that store bond topology are
updated to reflect the post-reacted molecule template. All force fields with fixed bonds, angles, dihedrals or impropers
are supported.
A few capabilities to note: 1) You may specify as many react arguments as desired. For example, you could break
down a complicated reaction mechanism into several reaction steps, each defined by its own react argument. 2) While
typically a bond is formed or removed between the initiator atoms specified in the pre-reacted molecule template, this
is not required. 3) By reversing the order of the pre- and post- reacted molecule templates in another react argument,
you can allow for the possibility of one or more reverse reactions.
The optional keywords deal with the probability of a given reaction occurring as well as the stable equilibration of each
reaction site as it occurs:

17.22. fix bond/react command 1089

LAMMPS Documentation, Release stable 29Sep2021

The prob keyword can affect whether or not an eligible reaction actually occurs. The fraction setting must be a value
between 0.0 and 1.0, and can be specified with an equal-style variable. A uniform random number between 0.0 and
1.0 is generated and the eligible reaction only occurs if the random number is less than the fraction. Up to N reactions
are permitted to occur, as optionally specified by the max_rxn keyword.
The stabilize_steps keyword allows for the specification of how many timesteps a reaction site is stabilized before being
returned to the overall system thermostat. In order to produce the most physical behavior, this ‘reaction site equilibration
time’ should be tuned to be as small as possible while retaining stability for a given system or reaction step. After a
limited number of case studies, this number has been set to a default of 60 timesteps. Ideally, it should be individually
tuned for each fix reaction step. Note that in some situations, decreasing rather than increasing this parameter will
result in an increase in stability.
The custom_charges keyword can be used to specify which atoms’ atomic charges are updated. When the value is set
to ‘no’, all atomic charges are updated to those specified by the post-reaction template (default). Otherwise, the value
should be the name of a molecule fragment defined in the pre-reaction molecule template. In this case, only the atomic
charges of atoms in the molecule fragment are updated.
The molecule keyword can be used to force the reaction to be intermolecular, intramolecular or either. When the value
is set to ‘off’, molecule IDs are not considered when searching for reactions (default). When the value is set to ‘inter’,
the initiator atoms must have different molecule IDs in order to be considered for the reaction. When the value is set
to ‘intra’, only initiator atoms with the same molecule ID are considered for the reaction.
A few other considerations:
Optionally, you can enforce additional behaviors on reacting atoms. For example, it may be beneficial to force re-
acting atoms to remain at a certain temperature. For this, you can use the internally-created dynamic group named
“bond_react_MASTER_group”, which consists of all atoms currently involved in a reaction. For example, adding the
following command would add an additional thermostat to the group of all currently-reacting atoms:

fix 1 bond_react_MASTER_group temp/rescale 1 300 300 10 1

Note: This command must be added after the fix bond/react command, and will apply to all reactions.

Computationally, each timestep this fix operates, it loops over neighbor lists (for bond-forming reactions) and computes
distances between pairs of atoms in the list. It also communicates between neighboring processors to coordinate which
bonds are created and/or removed. All of these operations increase the cost of a timestep. Thus you should be cautious
about invoking this fix too frequently.
You can dump out snapshots of the current bond topology via the dump local command.

17.22.4 Restart, fix_modify, output, run start/stop, minimize info

Cumulative reaction counts for each reaction are written to binary restart files. These values are associated with the
reaction name (react-ID). Additionally, internally-created per-atom properties are stored to allow for smooth restarts.
None of the fix_modify options are relevant to this fix.
This fix computes one statistic for each react argument that it stores in a global vector, of length ‘number of react
arguments’, that can be accessed by various output commands. The vector values calculated by this fix are “intensive”.
These is 1 quantity for each react argument:
• (1) cumulative # of reactions occurred
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

1090 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

When fix bond/react is ‘unfixed’, all internally-created groups are deleted. Therefore, fix bond/react can only be unfixed
after unfixing all other fixes that use any group created by fix bond/react.

17.22.5 Restrictions

This fix is part of the REACTION package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.22.6 Related commands

fix bond/create, fix bond/break, fix bond/swap, dump local, special_bonds

17.22.7 Default

The option defaults are stabilization = no, prob = 1.0, stabilize_steps = 60, reset_mol_ids = yes, custom_charges = no,
molecule = off, modify_create = no

(Gissinger2017) Gissinger, Jensen and Wise, Polymer, 128, 211-217 (2017).

(Gissinger2020) Gissinger, Jensen and Wise, Macromolecules, 53, 22, 9953-9961 (2020).

17.23 fix bond/swap command

17.23.1 Syntax

fix ID group-ID bond/swap Nevery fraction cutoff seed

• ID, group-ID are documented in fix command

• bond/swap = style name of this fix command
• Nevery = attempt bond swapping every this many steps
• fraction = fraction of group atoms to consider for swapping
• cutoff = distance at which swapping will be considered (distance units)
• seed = random # seed (positive integer)

17.23.2 Examples

fix 1 all bond/swap 50 0.5 1.3 598934

17.23. fix bond/swap command 1091

LAMMPS Documentation, Release stable 29Sep2021

17.23.3 Description

In a simulation of polymer chains this command attempts to swap a pair of bonds, as illustrated below. This is done
via Monte Carlo rules using the Boltzmann acceptance criterion, typically with the goal of equilibrating the polymer
system more quickly. This fix is designed for use with idealized bead-spring polymer chains where each polymer is a
linear chain of monomers, but LAMMPS does not check that is the case for your system.
Here are two use cases for this fix.
The first use case is for swapping bonds on two different chains, effectively grafting the end of one chain onto the other
chain and vice versa. The purpose is to equilibrate the polymer chain conformations more rapidly than dynamics alone
would do it, by enabling instantaneous large conformational changes in a dense polymer melt. The polymer chains
should thus more rapidly converge to the proper end-to-end distances and radii of gyration.
A schematic of the kinds of bond swaps that can occur in this use case is shown here:

On the left, the red and blue chains have two monomers A1 and B1 close to each other, which are currently bonded to
monomers A2 and B2 respectively within their own chains. The bond swap operation will attempt to delete the A1-A2
and B1-B2 bonds and replace them with A1-B2 and B1-A2 bonds. If the swap is energetically favorable, the two chains
on the right are the result and each polymer chain has undergone a dramatic conformational change. This reference,
(Sides) provides more details on the algorithm’s effectiveness for this use case.
The second use case is a collection of polymer chains with some fraction of their sites identified as “sticker” sites.
Initially each polymer chain is isolated from the others in a topological sense, and there is an intra-chain bond between
every pair of sticker sites on the same chain. Over time, bonds swap so that inter-molecular sticker bonds are created.
This models a vitrification-style process whereby the polymer chains all become interconnected. For this use case, if
angles are defined they should not include bonds between sticker sites.

The bond swapping operation is invoked once every Nevery timesteps. If any bond in the entire system is swapped, a
re-build of the neighbor lists is triggered, since a swap alters the list of which neighbors are considered for pairwise
interaction. At each invocation, each processor considers a random specified fraction of its atoms as potential swapping
monomers for this timestep. Choosing a small fraction value can reduce the likelihood of a reverse swap occurring
soon after an initial swap.
For each monomer A1, its neighbors are looped over as B1 monomers. For each A1,B1 an additional double loop of
bond partners A2 of A1, and bond partners B2 of B1 a is performed. For each pair of A1-A2 and B1-B2 bonds to be
eligible for swapping, the following 4 criteria must be met:
1. All 4 monomers must be in the fix group.
2. All 4 monomers must be owned by the processor (not ghost atoms). This insures that another processor does not
attempt to swap bonds involving the same atoms on the same timestep. Note that this also means that bond pairs
which straddle processor boundaries are not eligible for swapping on this step.
3. The distances between 4 pairs of atoms – (A1,A2), (B1,B2), (A1,B2), (B1,A2) – must all be less than the specified
cutoff.
4. The molecule IDs of A1 and B1 must be the same (see below).

1092 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

If an eligible B1 partner is found, the energy change due to swapping the 2 bonds is computed. This includes changes in
pairwise, bond, and angle energies due to the altered connectivity of the 2 chains. Dihedral and improper interactions
are not allowed to be defined when this fix is used.
If the energy decreases due to the swap operation, the bond swap is accepted. If the energy increases it is accepted
with probability exp(-delta/kT) where delta is the increase in energy, k is the Boltzmann constant, and T is the current
temperature of the system.

Note: IMPORTANT: Whether the swap is accepted or rejected, no other swaps are attempted by this processor on
this timestep. No other eligible 4-tuples of atoms are considered. This means that each processor will perform either
a single swap or none on timesteps this fix is invoked.

The criterion for matching molecule IDs is how the first use case described above can be simulated while conserving
chain lengths. This is done by setting up the molecule IDs for the polymer chains in a specific way, typically in the data
file, read by the read_data command.
Consider a system of 6-mer chains. You have 2 choices. If the molecule IDs for monomers on each chain are set to
1,2,3,4,5,6 then swaps will conserve chain length. For a particular monomer there will be only one other monomer on
another chain which is a potential swap partner. If the molecule IDs for monomers on each chain are set to 1,2,3,3,2,1
then swaps will conserve chain length but swaps will be able to occur at either end of a chain. Thus for a particular
monomer there will be 2 possible swap partners on another chain. In this scenario, swaps can also occur within a single
chain, i.e. the two ends of a chain swap with each other.

Note: If your simulation uses molecule IDs in the usual way, where all monomers on a single chain are assigned the
same ID (different for each chain), then swaps will only occur within the same chain. If you assign the same molecule
ID to all monomers in all chains then inter-chain swaps will occur, but they will not conserve chain length. Neither of
these scenarios is probably what you want for this fix.

Note: When a bond swap occurs the image flags of monomers in the new polymer chains can become inconsistent.
See the dump command for a discussion of image flags. This is not an issue for running dynamics, but can affect
calculation of some diagnostic quantities or the printing of unwrapped coordinates to a dump file.

For the second use case described above, the molecule IDs for all sticker sites should be the same.

This fix computes a temperature each time it is invoked for use by the Boltzmann criterion. To do this, the fix creates
its own compute of style temp, as if this command had been issued:

compute fix-ID_temp all temp

See the compute temp command for details. Note that the ID of the new compute is the fix-ID with underscore + “temp”
appended and the group for the new compute is “all”, so that the temperature of the entire system is used.
Note that this is NOT the compute used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp. This means you can change the attributes of this fix’s temperature (e.g. its degrees-of-freedom) via
the compute_modify command or print this temperature during thermodynamic output via the thermo_style custom
command using the appropriate compute-ID. It also means that changing attributes of thermo_temp will have no effect
on this fix.

17.23. fix bond/swap command 1093

LAMMPS Documentation, Release stable 29Sep2021

17.23.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. Because the state of the random number generator is
not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation continues on the
same as if no restart had taken place. However, in a statistical sense, a restarted simulation should produce the same
behavior. Also note that each processor generates possible swaps independently of other processors. Thus if you repeat
the same simulation on a different number of processors, the specific swaps performed will be different.
The fix_modify temp option is supported by this fix. You can use it to assign a compute you have defined to this fix
which will be used to compute the temperature for the Boltzmann criterion.
This fix computes two statistical quantities as a global 2-vector of output, which can be accessed by various output
commands. The first component of the vector is the cumulative number of swaps performed by all processors. The
second component of the vector is the cumulative number of swaps attempted (whether accepted or rejected). Note
that a swap “attempt” only occurs when swap partners meeting the criteria described above are found on a particular
timestep. The vector values calculated by this fix are “intensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.23.5 Restrictions

This fix is part of the MC package. It is only enabled if LAMMPS was built with that package. See the Build package
doc page for more info.
The settings of the “special_bond” command must be 0,1,1 in order to use this fix, which is typical of bead-spring
chains with FENE or harmonic bonds. This means that pairwise interactions between bonded atoms are turned off, but
are turned on between atoms two or three hops away along the chain backbone.
Currently, energy changes in dihedral and improper interactions due to a bond swap are not considered. Thus a simu-
lation that uses this fix cannot use a dihedral or improper potential.

17.23.6 Related commands

fix atom/swap

17.23.7 Default

none

(Sides) Sides, Grest, Stevens, Plimpton, J Polymer Science B, 42, 199-208 (2004).

17.24 fix box/relax command

17.24.1 Syntax

fix ID group-ID box/relax keyword value ...

• ID, group-ID are documented in fix command

• box/relax = style name of this fix command

1094 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

one or more keyword value pairs may be appended

keyword = iso or aniso or tri or x or y or z or xy or yz or xz or couple or nreset␣
,→or vmax or dilate or scaleyz or scalexz or scalexy or fixedpoint

iso or aniso or tri value = Ptarget = desired pressure (pressure units)

x or y or z or xy or yz or xz value = Ptarget = desired pressure (pressure units)
couple = none or xyz or xy or yz or xz
nreset value = reset reference cell every this many minimizer iterations
vmax value = fraction = max allowed volume change in one iteration
dilate value = all or partial
scaleyz value = yes or no = scale yz with lz
scalexz value = yes or no = scale xz with lz
scalexy value = yes or no = scale xy with ly
fixedpoint values = x y z
x,y,z = perform relaxation dilation/contraction around this point (distance␣
,→units)

17.24.2 Examples

fix 1 all box/relax iso 0.0 vmax 0.001

fix 2 water box/relax aniso 0.0 dilate partial
fix 2 ice box/relax tri 0.0 couple xy nreset 100

17.24.3 Description

Apply an external pressure or stress tensor to the simulation box during an energy minimization. This allows the box
size and shape to vary during the iterations of the minimizer so that the final configuration will be both an energy
minimum for the potential energy of the atoms, and the system pressure tensor will be close to the specified external
tensor. Conceptually, specifying a positive pressure is like squeezing on the simulation box; a negative pressure typically
allows the box to expand.

The external pressure tensor is specified using one or more of the iso, aniso, tri, x, y, z, xy, xz, yz, and couple keywords.
These keywords give you the ability to specify all 6 components of an external stress tensor, and to couple various of
these components together so that the dimensions they represent are varied together during the minimization.
Orthogonal simulation boxes have 3 adjustable dimensions (x,y,z). Triclinic (non-orthogonal) simulation boxes have
6 adjustable dimensions (x,y,z,xy,xz,yz). The create_box, read data, and read_restart commands specify whether the
simulation box is orthogonal or non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz tilt factors.
The target pressures Ptarget for each of the 6 components of the stress tensor can be specified independently via the x,
y, z, xy, xz, yz keywords, which correspond to the 6 simulation box dimensions. For example, if the y keyword is used,
the y-box length will change during the minimization. If the xy keyword is used, the xy tilt factor will change. A box
dimension will not change if that component is not specified.
Note that in order to use the xy, xz, or yz keywords, the simulation box must be triclinic, even if its initial tilt factors are
0.0.
When the size of the simulation box changes, all atoms are re-scaled to new positions, unless the keyword dilate is
specified with a value of partial, in which case only the atoms in the fix group are re-scaled. This can be useful for
leaving the coordinates of atoms in a solid substrate unchanged and controlling the pressure of a surrounding fluid.
The scaleyz, scalexz, and scalexy keywords control whether or not the corresponding tilt factors are scaled with the
associated box dimensions when relaxing triclinic periodic cells. The default values yes will turn on scaling, which
corresponds to adjusting the linear dimensions of the cell while preserving its shape. Choosing no ensures that the tilt

17.24. fix box/relax command 1095

LAMMPS Documentation, Release stable 29Sep2021

factors are not scaled with the box dimensions. See below for restrictions and default values in different situations. In
older versions of LAMMPS, scaling of tilt factors was not performed. The old behavior can be recovered by setting all
three scale keywords to no.
The fixedpoint keyword specifies the fixed point for cell relaxation. By default, it is the center of the box. Whatever point
is chosen will not move during the simulation. For example, if the lower periodic boundaries pass through (0,0,0), and
this point is provided to fixedpoint, then the lower periodic boundaries will remain at (0,0,0), while the upper periodic
boundaries will move twice as far. In all cases, the particle positions at each iteration are unaffected by the chosen
value, except that all particles are displaced by the same amount, different on each iteration.

Note: Applying an external pressure to tilt dimensions xy, xz, yz can sometimes result in arbitrarily large values of the
tilt factors, i.e. a dramatically deformed simulation box. This typically indicates that there is something badly wrong
with how the simulation was constructed. The two most common sources of this error are applying a shear stress to a
liquid system or specifying an external shear stress tensor that exceeds the yield stress of the solid. In either case the
minimization may converge to a bogus conformation or not converge at all. Also note that if the box shape tilts to an
extreme shape, LAMMPS will run less efficiently, due to the large volume of communication needed to acquire ghost
atoms around a processor’s irregular-shaped sub-domain. For extreme values of tilt, LAMMPS may also lose atoms
and generate an error.

Note: Performing a minimization with this fix is not a mathematically well-defined minimization problem. This
is because the objective function being minimized changes if the box size/shape changes. In practice this means the
minimizer can get “stuck” before you have reached the desired tolerance. The solution to this is to restart the minimizer
from the new adjusted box size/shape, since that creates a new objective function valid for the new box size/shape.
Repeat as necessary until the box size/shape has reached its new equilibrium.

The couple keyword allows two or three of the diagonal components of the pressure tensor to be “coupled” together. The
value specified with the keyword determines which are coupled. For example, xz means the Pxx and Pzz components
of the stress tensor are coupled. Xyz means all 3 diagonal components are coupled. Coupling means two things: the
instantaneous stress will be computed as an average of the corresponding diagonal components, and the coupled box
dimensions will be changed together in lockstep, meaning coupled dimensions will be dilated or contracted by the same
percentage every timestep. The Ptarget values for any coupled dimensions must be identical. Couple xyz can be used
for a 2d simulation; the z dimension is simply ignored.

The iso, aniso, and tri keywords are simply shortcuts that are equivalent to specifying several other keywords together.
The keyword iso means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure),
and dilate/contract the dimensions together. Using “iso Ptarget” is the same as specifying these 4 keywords:

x Ptarget
y Ptarget
z Ptarget
couple xyz

The keyword aniso means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components
of the stress tensor as the driving forces, and the specified scalar external pressure. Using “aniso Ptarget” is the same
as specifying these 4 keywords:

x Ptarget
y Ptarget
z Ptarget
couple none

1096 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The keyword tri means x, y, z, xy, xz, and yz dimensions are controlled independently using their individual stress
components as the driving forces, and the specified scalar pressure as the external normal stress. Using “tri Ptarget” is
the same as specifying these 7 keywords:

x Ptarget
y Ptarget
z Ptarget
xy 0.0
yz 0.0
xz 0.0
couple none

The vmax keyword can be used to limit the fractional change in the volume of the simulation box that can occur in one
iteration of the minimizer. If the pressure is not settling down during the minimization this can be because the volume
is fluctuating too much. The specified fraction must be greater than 0.0 and should be << 1.0. A value of 0.001 means
the volume cannot change by more than 1/10 of a percent in one iteration when couple xyz has been specified. For any
other case it means no linear dimension of the simulation box can change by more than 1/10 of a percent.

With this fix, the potential energy used by the minimizer is augmented by an additional energy provided by the fix. The
overall objective function then is:

E = U + Pt (V − V0 ) + Estrain

where U is the system potential energy, Pt is the desired hydrostatic pressure, V and V0 are the system and reference
volumes, respectively. Estrain is the strain energy expression proposed by Parrinello and Rahman (Parrinello1981).
Taking derivatives of E w.r.t. the box dimensions, and setting these to zero, we find that at the minimum of the objective
function, the global system stress tensor P will satisfy the relation:

t
P = Pt I + St h−1
0 h0d

where I is the identity matrix, h0 is the box dimension tensor of the reference cell, and :h0d is the diagonal part of
h0 . St is a symmetric stress tensor that is chosen by LAMMPS so that the upper-triangular components of P equal the
stress tensor specified by the user.
This equation only applies when the box dimensions are equal to those of the reference dimensions. If this is not
the case, then the converged stress tensor will not equal that specified by the user. We can resolve this problem by
periodically resetting the reference dimensions. The keyword nreset controls how often this is done. If this keyword
is not used, or is given a value of zero, then the reference dimensions are set to those of the initial simulation domain
and are never changed. A value of nstep means that every nstep minimization steps, the reference dimensions are set
to those of the current simulation domain. Note that resetting the reference dimensions changes the objective function
and gradients, which sometimes causes the minimization to fail. This can be resolved by changing the value of nreset,
or simply continuing the minimization from a restart file.

Note: As normally computed, pressure includes a kinetic- energy or temperature-dependent component; see the
compute pressure command. However, atom velocities are ignored during a minimization, and the applied pressure(s)
specified with this command are assumed to only be the virial component of the pressure (the non-kinetic portion).
Thus if atoms have a non-zero temperature and you print the usual thermodynamic pressure, it may not appear the
system is converging to your specified pressure. The solution for this is to either (a) zero the velocities of all atoms
before performing the minimization, or (b) make sure you are monitoring the pressure without its kinetic component.
The latter can be done by outputting the pressure from the pressure compute this command creates (see below) or a
pressure compute you define yourself.

17.24. fix box/relax command 1097

LAMMPS Documentation, Release stable 29Sep2021

Note: Because pressure is often a very sensitive function of volume, it can be difficult for the minimizer to equilibrate
the system the desired pressure with high precision, particularly for solids. Some techniques that seem to help are
(a) use the “min_modify line quadratic” option when minimizing with box relaxations, (b) minimize several times in
succession if need be, to drive the pressure closer to the target pressure, (c) relax the atom positions before relaxing
the box, and (d) relax the box to the target hydrostatic pressure before relaxing to a target shear stress state. Also note
that some systems (e.g. liquids) will not sustain a non-hydrostatic applied pressure, which means the minimizer will
not converge.

This fix computes a temperature and pressure each timestep. The temperature is used to compute the kinetic contribu-
tion to the pressure, even though this is subsequently ignored by default. To do this, the fix creates its own computes
of style “temp” and “pressure”, as if these commands had been issued:

compute fix-ID_temp group-ID temp

compute fix-ID_press group-ID pressure fix-ID_temp virial

See the compute temp and compute pressure commands for details. Note that the IDs of the new computes are the
fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is the same as the
fix group. Also note that the pressure compute does not include a kinetic component.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.

17.24.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its temperature and pressure calculation, as described above. Note that as
described above, if you assign a pressure compute to this fix that includes a kinetic energy component it will affect the
minimization, most likely in an undesirable way.

Note: If both the temp and press keywords are used in a single thermo_modify command (or in two separate com-
mands), then the order in which the keywords are specified is important. Note that a pressure compute defines its own
temperature compute as an argument when it is specified. The temp keyword will override this (for the pressure com-
pute being used by fix box/relax), but only if the temp keyword comes after the press keyword. If the temp keyword
comes before the press keyword, then the new pressure compute specified by the press keyword will be unaffected by
the temp setting.

This fix computes a global scalar which can be accessed by various output commands. The scalar is the pressure-volume
energy, plus the strain energy, if it exists, as described above. The energy values reported at the end of a minimization
run under “Minimization stats” include this energy, and so differ from what LAMMPS normally reports as potential
energy. This fix does not support the fix_modify energy option, because that would result in double-counting of the fix
energy in the minimization energy. Instead, the fix energy can be explicitly added to the potential energy using one of
these two variants:

1098 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

variable emin equal pe+f_1

variable emin equal pe+f_1/atoms

No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is invoked during energy minimization, but not for the purpose of adding a contribution to the energy or forces
being minimized. Instead it alters the simulation box geometry as described above.

17.24.5 Restrictions

Only dimensions that are available can be adjusted by this fix. Non-periodic dimensions are not available. z, xz, and yz,
are not available for 2D simulations. xy, xz, and yz are only available if the simulation domain is non-orthogonal. The
create_box, read data, and read_restart commands specify whether the simulation box is orthogonal or non-orthogonal
(triclinic) and explain the meaning of the xy,xz,yz tilt factors.
The scaleyz yes and scalexz yes keyword/value pairs can not be used for 2D simulations. scaleyz yes, scalexz yes, and
scalexy yes options can only be used if the second dimension in the keyword is periodic, and if the tilt factor is not
coupled to the barostat via keywords tri, yz, xz, and xy.

17.24.6 Related commands

fix npt, minimize

17.24.7 Default

The keyword defaults are dilate = all, vmax = 0.0001, nreset = 0.

(Parrinello1981) Parrinello and Rahman, J Appl Phys, 52, 7182 (1981).

17.25 fix brownian command

17.26 fix brownian/sphere command

17.27 fix brownian/asphere command

17.27.1 Syntax

fix ID group-ID style_name temp seed keyword args

• ID, group-ID are documented in fix command

• style_name = brownian or brownian/sphere or brownian/asphere
• temp = temperature
• seed = random number generator seed
• one or more keyword/value pairs may be appended

17.25. fix brownian command 1099

LAMMPS Documentation, Release stable 29Sep2021

• keyword = rng or dipole or gamma_r_eigen or gamma_t_eigen or gamma_r or gamma_t

rng value = uniform or gaussian or none
uniform = use uniform random number generator
gaussian = use gaussian random number generator
none = turn off noise
dipole value = mux and muy and muz for brownian/asphere
mux, muy, and muz = update orientation of dipole having direction (mux,*muy*,
,→*muz*) in body frame of rigid body

gamma_r_eigen values = gr1 and gr2 and gr3 for brownian/asphere

gr1, gr2, and gr3 = diagonal entries of body frame rotational friction tensor
gamma_r values = gr for brownian/sphere
gr = magnitude of the (isotropic) rotational friction tensor
gamma_t_eigen values = gt1 and gt2 and gt3 for brownian/asphere
gt1, gt2, and gt3 = diagonal entries of body frame translational friction tensor
gamma_t values = gt for brownian and brownian/sphere
gt = magnitude of the (isotropic) translational friction tensor

17.27.2 Examples

fix 1 all brownian 1.0 12908410 gamma_t 1.0

fix 1 all brownian 1.0 12908410 gamma_t 3.0 rng gaussian
fix 1 all brownian/sphere 1.0 1294019 gamma_t 3.0 gamma_r 1.0
fix 1 all brownian/sphere 1.0 19581092 gamma_t 1.0 gamma_r 0.3 rng none
fix 1 all brownian/asphere 1.0 1294019 gamma_t_eigen 1.0 2.0 3.0 gamma_r_eigen 4.0 7.0 8.
,→0 rng gaussian
fix 1 all brownian/asphere 1.0 1294019 gamma_t_eigen 1.0 2.0 3.0 gamma_r_eigen 4.0 7.0 8.
,→0 dipole 1.0 0.0 0.0

17.27.3 Description

Perform Brownian Dynamics time integration to update position, velocity, dipole orientation (for spheres) and quater-
nion orientation (for ellipsoids, with optional dipole update as well) of all particles in the fix group in each timestep.
Brownian Dynamics uses Newton’s laws of motion in the limit that inertial forces are negligible compared to viscous
forces. The stochastic equation of motion for the center of mass positions is
−1/2
p
dr = γt−1 Fdt + 2kB T γt dWt ,

in the lab-frame (i.e. γt is not diagonal, but only depends on orientation and so the noise is still additive).
The rotational motion for the spherical and ellipsoidal particles is not as simple an expression, but is chosen to replicate
the Boltzmann distribution for the case of conservative torques (see (Ilie) or (Delong)).
For the style brownian, only the positions of the particles are updated. This is therefore suitable for point particle
simulations.
For the style brownian/sphere, the positions of the particles are updated, and a dipole slaved to the spherical orientation
is also updated. This style therefore requires the hybrid atom style atom_style dipole and atom_style sphere.
For the style brownian/asphere, the center of mass positions and the quaternions of ellipsoidal particles are updated.
This fix style is suitable for equations of motion where the rotational and translational friction tensors can be diagonal-
ized in a certain (body) reference frame.

1100 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Note: This integrator does not by default assume a relationship between the rotational and translational friction
tensors, though such a relationship should exist in the case of no-slip boundary conditions between the particles and
the surrounding (implicit) solvent. E.g. in the case of spherical particles, the condition γt = 3γr /σ 2 must be explicitly
accounted for by setting gamma_t to 3x and gamma_r to x (where σ is the spherical diameter). A similar (though more
complex) relationship holds for ellipsoids and rod-like particles.

Note: Temperature computation using the compute temp will not correctly compute temperature of these overdamped
dynamics since we are explicitly neglecting inertial effects. Furthermore, this time integrator does not add the stochastic
terms or viscous terms to the force and/or torques. Rather, they are just added in to the equations of motion to update
the degrees of freedom.

If the rng keyword is used with the uniform value, then the noise is generated from a uniform distribution (see (Dunweg)
for why this works). This is the same method of noise generation as used in fix_langevin.
If the rng keyword is used with the gaussian value, then the noise is generated from a gaussian distribution. Typically
this added complexity is unnecessary, and one should be fine using the uniform value for reasons argued in (Dunweg).
If the rng keyword is used with the none value, then the noise terms are set to zero.
The gamma_t keyword sets the (isotropic) translational viscous damping. Required for (and only compatible with)
brownian and brownian/sphere. The units of gamma_t are mass/time.
The gamma_r keyword sets the (isotropic) rotational viscous damping. Required for (and only compatible with) brow-
nian/sphere. The units of gamma_r are mass*length**2/time.
The gamma_r_eigen, and gamma_t_eigen keywords are the eigenvalues of the rotational and viscous damping tensors
(having the same units as their isotropic counterparts). Required for (and only compatible with) brownian/asphere.
For a 2D system, the first two values of gamma_r_eigen must be inf (only rotation in xy plane), and the third value of
gamma_t_eigen must be inf (only diffusion in xy plane).
If the dipole keyword is used, then the dipole moments of the particles are updated as described above. Only compatible
with brownian/asphere (as brownian/sphere updates dipoles automatically).

Note: For style brownian/asphere, the components gamma_t_eigen =(x,x,x) and gamma_r_eigen = (y,y,y), the dy-
namics will replicate those of the brownian/sphere style with gamma_t = x and gamma_r = y.

17.27.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. No global or per-atom quantities are stored by this fix
for access by various output commands.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.27. fix brownian/asphere command 1101

LAMMPS Documentation, Release stable 29Sep2021

17.27.5 Restrictions

The style brownian/sphere fix requires that atoms store torque and angular velocity (omega) as defined by the atom_style
sphere command. The style brownian/asphere fix requires that atoms store torque and quaternions as defined by the
atom_style ellipsoid command. If the dipole keyword is used, they must also store a dipole moment as defined by the
atom_style dipole command.
This fix is part of the BROWNIAN package. It is only enabled if LAMMPS was built with that package. See the Build
package doc page for more info.

17.27.6 Related commands

fix propel/self , fix langevin, fix nve/sphere,

17.27.7 Default

The default for rng is uniform. The default for the rotational and translational friction tensors are the identity tensor.

(Ilie) Ilie, Briels, den Otter, Journal of Chemical Physics, 142, 114103 (2015).
(Delong) Delong, Usabiaga, Donev, Journal of Chemical Physics. 143, 144107 (2015)
(Dunweg) Dunweg and Paul, Int J of Modern Physics C, 2, 817-27 (1991).

17.28 fix charge/regulation command

17.28.1 Syntax

fix ID group-ID charge/regulation cation_type anion_type keyword value(s)

• ID, group-ID are documented in fix command

• charge/regulation = style name of this fix command
• cation_type = atom type of free cations
• anion_type = atom type of free anions
• zero or more keyword/value pairs may be appended
keyword = pH, pKa, pKb, pIp, pIm, pKs, acid_type, base_type, lunit_nm, temp,␣
,→tempfixid, nevery, nmc, xrd, seed, tag, group, onlysalt, pmcmoves

pH value = pH of the solution (can be specified as an equal-style variable)

pKa value = acid dissociation constant
pKb value = base dissociation constant
pIp value = chemical potential of free cations
pIm value = chemical potential of free anions
pKs value = solution self-dissociation constant
acid_type = atom type of acid groups
base_type = atom type of base groups
lunit_nm value = unit length used by LAMMPS (# in the units of nanometers)
temp value = temperature
tempfixid value = fix ID of temperature thermostat

1102 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

nevery value = invoke this fix every nevery steps

nmc value = number of charge regulation MC moves to attempt every nevery steps
xrd value = cutoff distance for acid/base reaction
seed value = random # seed (positive integer)
tag value = yes or no (yes: The code assign unique tags to inserted ions; no: The␣
,→tag of all inserted ions is "0")

group value = group-ID, inserted ions are assigned to group group-ID. Can be used␣
,→multiple times to assign inserted ions to multiple groups.

onlysalt values = flag charge_cation charge_anion.

flag = yes or no (yes: the fix performs only ion insertion/deletion, no: perform␣
,→acid/base dissociation and ion insertion/deletion)

charge_cation, charge_anion = value of cation/anion charge, must be an integer␣

,→(only specify if flag = yes)

pmcmoves values = pmcA pmcB pmcI - MC move fractions for acid ionization (pmcA),␣
,→base ionization (pmcB) and free ion exchange (pmcI)

17.28.2 Examples

fix chareg all charge/regulation 1 2 acid_type 3 base_type 4 pKa 5 pKb 7 lb 1.0 nevery␣
,→200 nexchange 200 seed 123 tempfixid fT

fix chareg all charge/regulation 1 2 pIp 3 pIm 3 onlysalt yes 2 -1 seed 123 tag yes temp␣
,→1.0

17.28.3 Description

This fix performs Monte Carlo (MC) sampling of charge regulation and exchange of ions with a reservoir as discussed
in (Curk1) and (Curk2). The implemented method is largely analogous to the grand-reaction ensemble method in
(Landsgesell). The implementation is parallelized, compatible with existing LAMMPS functionalities, and applicable
to any system utilizing discrete, ionizable groups or surface sites.
Specifically, the fix implements the following three types of MC moves, which discretely change the charge state of
+ −
individual particles and insert ions into the systems: A
A− +X+ , B
B+ +X− , and ∅
Z − XZ +Z + X−Z . In
the former two types of reactions, Monte Carlo moves alter the charge value of specific atoms (A, B) and simultaneously
insert a counterion to preserve the charge neutrality of the system, modeling the dissociation/association process. The
last type of reaction performs grand canonical MC exchange of ion pairs with a (fictitious) reservoir.
In our implementation “acid” refers to particles that can attain charge q = {0, −1} and “base” to particles with q =
{0, 1}, whereas the MC exchange of free ions allows any integer charge values of Z + and Z − .
Here we provide several practical examples for modeling charge regulation effects in solvated systems. An acid ioniza-
tion reaction (A
A− + H+ ) can be defined via a single line in the input file

fix acid_reaction all charge/regulation 2 3 acid_type 1 pH 7.0 pKa 5.0 pIp 7.0 pIm 7.0

where the fix attempts to charge A (discharge A− ) to A− (A) and insert (delete) a proton (atom type 2). Besides, the fix
implements self-ionization reaction of water ∅
H+ + OH− . However, this approach is highly inefficient at pH ≈ 7
when the concentration of both protons and hydroxyl ions is low, resulting in a relatively low acceptance rate of MC
moves.
A more efficient way is to allow salt ions to participate in ionization reactions, which can be easily achieved via

fix acid_reaction all charge/regulation 4 5 acid_type 1 pH 7.0 pKa 5.0 pIp 2.0 pIm 2.0

17.28. fix charge/regulation command 1103

LAMMPS Documentation, Release stable 29Sep2021

where particles of atom type 4 and 5 are the salt cations and anions, both at chemical potential pI=2.0, see (Curk1) and
(Landsgesell) for more details.
Similarly, we could have simultaneously added a base ionization reaction (B
B+ + OH− )

fix base_reaction all charge/regulation 2 3 base_type 6 pH 7.0 pKb 6.0 pIp 7.0 pIm 7.0

where the fix will attempt to charge B (discharge B+ ) to B+ (B) and insert (delete) a hydroxyl ion OH− of atom type
3. If neither the acid or the base type is specified, for example,

fix salt_reaction all charge/regulation 4 5 pIp 2.0 pIm 2.0

the fix simply inserts or deletes an ion pair of a free cation (atom type 4) and a free anion (atom type 5) as done in a
conventional grand-canonical MC simulation.
The fix is compatible with LAMMPS sub-packages such as molecule or rigid. That said, the acid and base particles
can be part of larger molecules or rigid bodies. Free ions that are inserted to or deleted from the system must be defined
as single particles (no bonded interactions allowed) and cannot be part of larger molecules or rigid bodies. If molecule
package is used, all inserted ions have a molecule ID equal to zero.
Note that LAMMPS implicitly assumes a constant number of particles (degrees of freedom). Since using this fix alters
the total number of particles during the simulation, any thermostat used by LAMMPS, such as NVT or Langevin, must
use a dynamic calculation of system temperature. This can be achieved by specifying a dynamic temperature compute
(e.g. dtemp) and using it with the desired thermostat, e.g. a Langevin thermostat:

compute dtemp all temp

compute_modify dtemp dynamic yes
fix fT all langevin 1.0 1.0 1.0 123
fix_modify fT temp dtemp

The chemical potential units (e.g. pH) are in the standard log10 representation assuming reference concentration ρ0 =
mol/l. Therefore, to perform the internal unit conversion, the length (in nanometers) of the LAMMPS unit length must
be specified via lunit_nm (default is set to the Bjerrum length in water at room temperature lunit_nm = 0.71nm). For
example, in the dilute ideal solution limit, the concentration of free ions will be cI = 10−pIp mol/l.
The temperature used in MC acceptance probability is set by temp. This temperature should be the same as the temper-
ature set by the molecular dynamics thermostat. For most purposes, it is probably best to use tempfixid keyword which
dynamically sets the temperature equal to the chosen MD thermostat temperature, in the example above we assumed
the thermostat fix-ID is fT. The inserted particles attain a random velocity corresponding to the specified temperature.
Using tempfixid overrides any fixed temperature set by temp.
The xrd keyword can be used to restrict the inserted/deleted counterions to a specific radial distance from an acid or
base particle that is currently participating in a reaction. This can be used to simulate more realist reaction dynamics.
If xrd = 0 or xrd > L / 2, where L is the smallest box dimension, the radial restriction is automatically turned off and
free ion can be inserted or deleted anywhere in the simulation box.
If the tag yes is used, every inserted atom gets a unique tag ID, otherwise, the tag of every inserted atom is set to 0.
tag yes might cause an integer overflow in very long simulations since the tags are unique to every particle and thus
increase with every successful particle insertion.
The pmcmoves keyword sets the relative probability of attempting the three types of MC moves (reactions): acid charg-
ing, base charging, and ion pair exchange. The fix only attempts to perform particle charging MC moves if acid_type or
base_type is defined. Otherwise fix only performs free ion insertion/deletion. For example, if acid_type is not defined,
pmcA is automatically set to 0. The vector pmcmoves is automatically normalized, for example, if set to pmcmoves 0
0.33 0.33, the vector would be normalized to [0,0.5,0.5].
The only_salt option can be used to perform multivalent grand-canonical ion-exchange moves. If only_salt yes is used,
no charge exchange is performed, only ion insertion/deletion (pmcmoves is set to [0,0,1]), but ions can be multivalent.

1104 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

In the example above, an MC move would consist of three ion insertion/deletion to preserve the charge neutrality of
the system.
The group keyword can be used to add inserted particles to a specific group-ID. All inserted particles are automatically
added to group all.

17.28.4 Output

This fix computes a global vector of length 8, which can be accessed by various output commands. The vector values
are the following global quantities:
• 1 = cumulative MC attempts
• 2 = cumulative MC successes
• 3 = current # of neutral acid atoms
• 4 = current # of -1 charged acid atoms
• 5 = current # of neutral base atoms
• 6 = current # of +1 charged base atoms
• 7 = current # of free cations
• 8 = current # of free anions

17.28.5 Restrictions

This fix is part of the MC package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
The atom_style, used must contain the charge property, for example, the style could be charge or full. Only usable for
3D simulations. Atoms specified as free ions cannot be part of rigid bodies or molecules and cannot have bonding
interactions. The scheme is limited to integer charges, any atoms with non-integer charges will not be considered by
the fix.
All interaction potentials used must be continuous, otherwise the MD integration and the particle exchange MC moves
do not correspond to the same equilibrium ensemble. For example, if an lj/cut pair style is used, the LJ potential must
be shifted so that it vanishes at the cutoff. This can be easily achieved using the pair_modify command, i.e., by using:
pair_modify shift yes.

Note: Region restrictions are not yet implemented.

17.28.6 Related commands

fix gcmc, fix atom/swap

17.28. fix charge/regulation command 1105

LAMMPS Documentation, Release stable 29Sep2021

17.28.7 Default

pH = 7.0; pKa = 100.0; pKb = 100.0; pIp = 5.0; pIm = 5.0; pKs = 14.0; acid_type = -1; base_type = -1; lunit_nm =
0.71; temp = 1.0; nevery = 100; nmc = 100; xrd = 0; seed = 0; tag = no; onlysalt = no, pmcmoves = [1/3, 1/3, 1/3],
group-ID = all

(Curk1) T. Curk, J. Yuan, and E. Luijten, “Coarse-grained simulation of charge regulation using LAMMPS”, preprint
(2021).
(Curk2) T. Curk and E. Luijten, “Charge-regulation effects in nanoparticle self-assembly”, PRL (2021)
(Landsgesell) J. Landsgesell, P. Hebbeker, O. Rud, R. Lunkad, P. Kosovan, and C. Holm, “Grand-reaction method for
simulations of ionization equilibria coupled to ion partitioning”, Macromolecules 53, 3007-3020 (2020).

17.29 fix client/md command

17.29.1 Syntax

fix ID group-ID client/md

• ID, group-ID are documented in fix command

• client/md = style name of this fix command

17.29.2 Examples

fix 1 all client/md

17.29.3 Description

This fix style enables LAMMPS to run as a “client” code and communicate each timestep with a separate “server” code
to perform an MD simulation together.
The Howto client/server page gives an overview of client/server coupling of LAMMPS with another code where one
code is the “client” and sends request messages to a “server” code. The server responds to each request with a reply
message. This enables the two codes to work in tandem to perform a simulation.
When using this fix, LAMMPS (as the client code) passes the current coordinates of all particles to the server code
each timestep, which computes their interaction, and returns the energy, forces, and virial for the interacting particles
to LAMMPS, so it can complete the timestep.
Note that the server code can be a quantum code, or another classical MD code which encodes a force field (pair_style
in LAMMPS lingo) which LAMMPS does not have. In the quantum case, this fix is a mechanism for running ab initio
MD with quantum forces.
The group associated with this fix is ignored.
The protocol and units for message format and content that LAMMPS exchanges with the server code is defined on the
server md doc page.
Note that when using LAMMPS as an MD client, your LAMMPS input script should not normally contain force field
commands, like a pair_style, bond_style, or kspace_style command. However it is possible for a server code to only

1106 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

compute a portion of the full force-field, while LAMMPS computes the remaining part. Your LAMMPS script can also
specify boundary conditions or force constraints in the usual way, which will be added to the per-atom forces returned
by the server code.
See the examples/message directory for example scripts where LAMMPS is both the “client” and/or “server” code for
this kind of client/server MD simulation. The examples/message/README file explains how to launch LAMMPS and
another code in tandem to perform a coupled simulation.

17.29.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy set by the server application to the
global potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify
energy yes.
The fix_modify virial option is supported by this fix to add the contribution computed by the server application to the
global pressure of the system via the compute pressure command. This can be accessed by thermodynamic output. The
default setting for this fix is fix_modify virial yes.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the potential energy
discussed above. The scalar value calculated by this fix is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.29.5 Restrictions

This fix is part of the MESSAGE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
A script that uses this command must also use the message command to setup and shut down the messaging protocol
with the server code.

17.29.6 Related commands

message, server

17.29.7 Default

none

17.29. fix client/md command 1107

LAMMPS Documentation, Release stable 29Sep2021

17.30 fix cmap command

17.30.1 Syntax

fix ID group-ID cmap filename

• ID, group-ID are documented in fix command

• cmap = style name of this fix command
• filename = force-field file with CMAP coefficients

17.30.2 Examples

fix myCMAP all cmap ../potentials/cmap36.data

read_data proteinX.data fix myCMAP crossterm CMAP
fix_modify myCMAP energy yes

17.30.3 Description

This command enables CMAP cross-terms to be added to simulations which use the CHARMM force field. These are
relevant for any CHARMM model of a peptide or protein sequences that is 3 or more amino-acid residues long; see
(Buck) and (Brooks) for details, including the analytic energy expressions for CMAP interactions. The CMAP cross-
terms add additional potential energy contributions to pairs of overlapping phi-psi dihedrals of amino-acids, which are
important to properly represent their conformational behavior.
The examples/cmap directory has a sample input script and data file for a small peptide, that illustrates use of the fix
cmap command.
As in the example above, this fix should be used before reading a data file that contains a listing of CMAP interactions.
The filename specified should contain the CMAP parameters for a particular version of the CHARMM force field. Two
such files are including in the lammps/potentials directory: charmm22.cmap and charmm36.cmap.
The data file read by the “read_data” must contain the topology of all the CMAP interactions, similar to the topology
data for bonds, angles, dihedrals, etc. Specially it should have a line like this in its header section:

N crossterms

where N is the number of CMAP cross-terms. It should also have a section in the body of the data file like this with N
lines:

CMAP

1 1 8 10 12 18 20
2 5 18 20 22 25 27
[...]
N 3 314 315 317 318 330

The first column is an index from 1 to N to enumerate the CMAP terms; it is ignored by LAMMPS. The second column
is the “type” of the interaction; it is an index into the CMAP force field file. The remaining 5 columns are the atom IDs
of the atoms in the two 4-atom dihedrals that overlap to create the CMAP 5-body interaction. Note that the “crossterm”
and “CMAP” keywords for the header and body sections match those specified in the read_data command following
the data file name; see the read_data page for more details.

1108 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

A data file containing CMAP cross-terms can be generated from a PDB file using the charmm2lammps.pl script in the
tools/ch2lmp directory of the LAMMPS distribution. The script must be invoked with the optional “-cmap” flag to do
this; see the tools/ch2lmp/README file for more information.
The potential energy associated with CMAP interactions can be output as described below. It can also be included in
the total potential energy of the system, as output by the thermo_style command, if the fix_modify energy command is
used, as in the example above. See the note below about how to include the CMAP energy when performing an energy
minimization.

17.30.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the list of CMAP cross-terms to binary restart files. See the read_restart command for info on how to
re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an uninterrupted
fashion.
The fix_modify energy option is supported by this fix to add the potential energy of the CMAP interactions to both the
global potential energy and peratom potential energies of the system as part of thermodynamic output or output by the
compute pe/atom command. The default setting for this fix is fix_modify energy yes.
The fix_modify virial option is supported by this fix to add the contribution due to the CMAP interactions to both the
global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands. The
former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial yes.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the potential energy
discussed above. The scalar value calculated by this fix is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command.
The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.

Note: If you want the potential energy associated with the CMAP terms forces to be included in the total potential
energy of the system (the quantity being minimized), you MUST not disable the fix_modify energy option for this fix.

17.30.5 Restrictions

To function as expected this fix command must be issued before a read_data command but after a read_restart com-
mand.
This fix can only be used if LAMMPS was built with the MOLECULE package. See the Build package page for more
info.

17.30. fix cmap command 1109

LAMMPS Documentation, Release stable 29Sep2021

17.30.6 Related commands

fix_modify, read_data

17.30.7 Default

none

(Buck) Buck, Bouguet-Bonnet, Pastor, MacKerell Jr., Biophys J, 90, L36 (2006).
(Brooks) Brooks, Brooks, MacKerell Jr., J Comput Chem, 30, 1545 (2009).

17.31 fix colvars command

17.31.1 Syntax

fix ID group-ID colvars configfile keyword values ...

• ID, group-ID are documented in fix command

• colvars = style name of this fix command
• configfile = the configuration file for the colvars module
• keyword = input or output or seed or tstat
input arg = colvars.state file name or prefix or NULL (default: NULL)
output arg = output filename prefix (default: out)
seed arg = seed for random number generator (default: 1966)
unwrap arg = yes or no
use unwrapped coordinates in collective variables (default: yes)
tstat arg = fix id of a thermostat or NULL (default: NULL)

17.31.2 Examples

fix mtd all colvars peptide.colvars.inp seed 2122 input peptide.colvars.state output␣
,→peptide

fix abf all colvars colvars.inp tstat 1

17.31.3 Description

This fix interfaces LAMMPS to the collective variables (Colvars) library, which allows to calculate potentials of mean
force (PMFs) for any set of colvars, using different sampling methods: currently implemented are the Adaptive Biasing
Force (ABF) method, metadynamics, Steered Molecular Dynamics (SMD) and Umbrella Sampling (US) via a flexible
harmonic restraint bias.
This documentation describes only the fix colvars command itself and LAMMPS specific parts of the code. The full
documentation of the colvars library is available as this supplementary PDF document
The Colvars library is developed at https://github.com/colvars/colvars A detailed discussion of its implementation is
in (Fiorin).

1110 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

There are some example scripts for using this package with LAMMPS in the examples/PACKAGES/colvars directory.

The only mandatory argument to the fix is the filename to the colvars input file that contains the input that is independent
from the MD program in which the colvars library has been integrated.
The group-ID entry is ignored. The collective variable module will always apply to the entire system and there can only
be one instance of the colvars fix at a time. The colvars fix will only communicate the minimum information necessary
and the colvars library supports multiple, completely independent collective variables, so there is no restriction to
functionality by limiting the number of colvars fixes.
The input keyword allows to specify a state file that would contain the restart information required in order to continue
a calculation from a prerecorded state. Fix colvars records it state in binary restart files, so when using the read_restart
command, this is usually not needed.
The output keyword allows to specify the output prefix. All output files generated will use this prefix followed by the
“.colvars.” and a word like “state” or “traj”.
The seed keyword contains the seed for the random number generator that will be used in the colvars module.
The unwrap keyword controls whether wrapped or unwrapped coordinates are passed to the colvars library for calcu-
lation of the collective variables and the resulting forces. The default is yes, i.e. to use the image flags to reconstruct
the absolute atom positions. Setting this to no will use the current local coordinates that are wrapped back into the
simulation cell at each re-neighboring instead.
The tstat keyword can be either NULL or the label of a thermostatting fix that thermostats all atoms in the fix colvars
group. This will be used to provide the colvars module with the current thermostat target temperature.

17.31.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the current status of the colvars module into binary restart files. This is in addition to the text mode
status file that is written by the colvars module itself and the kind of information in both files is identical.
The fix_modify energy option is supported by this fix to add the energy change from the biasing force added by Colvars
to the global potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify
energy no.
The fix_modify configfile <config file> option allows to add settings from an additional config file to the colvars module.
This option can only be used, after the system has been initialized with a run command.
The fix_modify config <quoted string> option allows to add settings from inline strings. Those have to fit on a single
line when enclosed in a pair of double quotes (“), or can span multiple lines when bracketed by a pair of triple double
quotes (“””, like python embedded documentation).
This fix computes a global scalar which can be accessed by various output commands. The scalar is the Colvars energy
mentioned above. The scalar value calculated by this fix is “extensive”.

17.31.5 Restrictions

This fix is part of the COLVARS package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
There can only be one colvars fix active at a time. Since the interface communicates only the minimum amount of
information and colvars module itself can handle an arbitrary number of collective variables, this is not a limitation of
functionality.

17.31. fix colvars command 1111

LAMMPS Documentation, Release stable 29Sep2021

17.31.6 Related commands

fix smd, fix spring, fix plumed

17.31.7 Default

The default options are input = NULL, output = out, seed = 1966, unwrap yes, and tstat = NULL.

(Fiorin) Fiorin, Klein, Henin, Mol. Phys., DOI:10.1080/00268976.2013.813594

17.32 fix controller command

17.32.1 Syntax

fix ID group-ID controller Nevery alpha Kp Ki Kd pvar setpoint cvar

• ID, group-ID are documented in fix command

• controller = style name of this fix command
• Nevery = invoke controller every this many timesteps
• alpha = coupling constant for PID equation (see units discussion below)
• Kp = proportional gain in PID equation (unitless)
• Ki = integral gain in PID equation (unitless)
• Kd = derivative gain in PID equation (unitless)
• pvar = process variable of form c_ID, c_ID[I], f_ID, f_ID[I], or v_name

c_ID = global scalar calculated by a compute with ID

c_ID[I] = Ith component of global vector calculated by a compute with ID
f_ID = global scalar calculated by a fix with ID
f_ID[I] = Ith component of global vector calculated by a fix with ID
v_name = value calculated by an equal-style variable with name

• setpoint = desired value of process variable (same units as process variable)

• cvar = name of control variable

17.32.2 Examples

fix 1 all controller 100 1.0 0.5 0.0 0.0 c_thermo_temp 1.5 tcontrol
fix 1 all controller 100 0.2 0.5 0 100.0 v_pxxwall 1.01325 xwall
fix 1 all controller 10000 0.2 0.5 0 2000 v_avpe -3.785 tcontrol

1112 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.32.3 Description

This fix enables control of a LAMMPS simulation using a control loop feedback mechanism known as a proportional-
integral-derivative (PID) controller. The basic idea is to define a “process variable” which is a quantity that can be
monitored during a running simulation. A desired target value is chosen for the process variable. A “control variable”
is also defined which is an adjustable attribute of the running simulation, which the process variable will respond to.
The PID controller continuously adjusts the control variable based on the difference between the process variable and
the target.
Here are examples of ways in which this fix can be used. The examples/pid directory contains a script that implements
the simple thermostat.

Goal process variable control variable

Simple thermostat instantaneous T thermostat target T
Find melting temperature average PE per atom thermostat target T
Control pressure in non-periodic system force on wall position of wall

Note: For this fix to work, the control variable must actually induce a change in a running LAMMPS simulation.
Typically this will only occur if there is some other command (e.g. a thermostat fix) which uses the control variable as
an input parameter. This could be done directly or indirectly, e.g. the other command uses a variable as input whose
formula uses the control variable. The other command should alter its behavior dynamically as the variable changes.

Note: If there is a command you think could be used in this fashion, but does not currently allow a variable as an input
parameter, please notify the LAMMPS developers. It is often not difficult to enable a command to use a variable as an
input parameter.

The group specified with this command is ignored. However, note that the process variable may be defined by calcu-
lations performed by computes and fixes which store their own “group” definitions.
The PID controller is invoked once each Nevery timesteps.
The PID controller is implemented as a discretized version of the following dynamic equation:
Z t
dc de
= Ê − α(Kp e + Ki e dt + Kd )
dt 0 dt

where c is the continuous time analog of the control variable, e =pvar-setpoint is the error in the process variable, and
α, Kp , Ki , and Kd are constants set by the corresponding keywords described above. The discretized version of this
equation is:
n
!
X
cn = Êcn−1 − α Kp τ en + Ki τ 2 ei + Kd (en − en−1 )
i=1

where τ = Nevery · timestep is the time interval between updates, and the subscripted variables indicate the values
of c and e at successive updates.
From the first equation, it is clear that if the three gain values Kp , Ki , Kd are dimensionless constants, then α must
have units of [unit cvar]/[unit pvar]/[unit time] e.g. [ eV/K/ps ]. The advantage of this unit scheme is that the value of
the constants should be invariant under a change of either the MD timestep size or the value of Nevery. Similarly, if
the LAMMPS unit style is changed, it should only be necessary to change the value of α to reflect this, while leaving
Kp , Ki , and Kd unaltered.

17.32. fix controller command 1113

LAMMPS Documentation, Release stable 29Sep2021

When choosing the values of the four constants, it is best to first pick a value and sign for α that is consistent with the
magnitudes and signs of pvar and cvar. The magnitude of Kp should then be tested over a large positive range keeping
Ki = Kd = 0. A good value for Kp will produce a fast response in pvar, without overshooting the setpoint. For many
applications, proportional feedback is sufficient, and so Ki = K_d =0` can be used. In cases where there is a substantial
lag time in the response of pvar to a change in cvar, this can be counteracted by increasing Kd . In situations where
pvar plateaus without reaching setpoint, this can be counteracted by increasing Ki . In the language of Charles Dickens,
Kp represents the error of the present, Ki the error of the past, and Kd the error yet to come.
Because this fix updates cvar, but does not initialize its value, the initial value is that assigned by the user in the input
script via the internal-style variable command. This value is used (by the other LAMMPS command that used the
variable) until this fix performs its first update of cvar after Nevery timesteps. On the first update, the value of the
derivative term is set to zero, because the value of en − 1 is not yet defined.

The process variable pvar can be specified as the output of a compute or fix or the evaluation of a variable. In each
case, the compute, fix, or variable must produce a global quantity, not a per-atom or local quantity.
If pvar begins with “c_”, a compute ID must follow which has been previously defined in the input script and which
generates a global scalar or vector. See the individual compute doc page for details. If no bracketed integer is appended,
the scalar calculated by the compute is used. If a bracketed integer is appended, the Ith value of the vector calculated
by the compute is used. Users can also write code for their own compute styles and add them to LAMMPS.
If pvar begins with “f_”, a fix ID must follow which has been previously defined in the input script and which generates
a global scalar or vector. See the individual fix page for details. Note that some fixes only produce their values on
certain timesteps, which must be compatible with when fix controller references the values, or else an error results.
If no bracketed integer is appended, the scalar calculated by the fix is used. If a bracketed integer is appended, the
Ith value of the vector calculated by the fix is used. Users can also write code for their own fix style and add them to
LAMMPS.
If pvar begins with “v_”, a variable name must follow which has been previously defined in the input script. Only
equal-style variables can be referenced. See the variable command for details. Note that variables of style equal
define a formula which can reference individual atom properties or thermodynamic keywords, or they can invoke other
computes, fixes, or variables when they are evaluated, so this is a very general means of specifying the process variable.
The target value setpoint for the process variable must be a numeric value, in whatever units pvar is defined for.
The control variable cvar must be the name of an internal-style variable previously defined in the input script. Note
that it is not specified with a “v_” prefix, just the name of the variable. It must be an internal-style variable, because
this fix updates its value directly. Note that other commands can use an equal-style versus internal-style variable
interchangeably.

17.32.4 Restart, fix_modify, output, run start/stop, minimize info

Currently, no information about this fix is written to binary restart files. None of the fix_modify options are relevant to
this fix.
This fix produces a global vector with 3 values which can be accessed by various output commands. The values can be
accessed on any timestep, though they are only updated on timesteps that are a multiple of Nevery.
The three values are the most recent updates made to the control variable by each of the 3 terms in the PID equation
above. The first value is the proportional term, the second is the integral term, the third is the derivative term.
The units of the vector values will be whatever units the control variable is in. The vector values calculated by this fix
are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

1114 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.32.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.32.6 Related commands

fix adapt

17.32.7 Default

none

17.33 fix deform command

Accelerator Variants: deform/kk

17.33.1 Syntax

fix ID group-ID deform N parameter args ... keyword value ...

• ID, group-ID are documented in fix command

• deform = style name of this fix command
• N = perform box deformation every this many timesteps
• one or more parameter/arg pairs may be appended
parameter = x or y or z or xy or xz or yz
x, y, z args = style value(s)
style = final or delta or scale or vel or erate or trate or volume or wiggle or␣
,→variable

final values = lo hi
lo hi = box boundaries at end of run (distance units)
delta values = dlo dhi
dlo dhi = change in box boundaries at end of run (distance units)
scale values = factor
factor = multiplicative factor for change in box length at end of run
vel value = V
V = change box length at this velocity (distance/time units),
effectively an engineering strain rate
erate value = R
R = engineering strain rate (1/time units)
trate value = R
R = true strain rate (1/time units)
volume value = none = adjust this dim to preserve volume of system
wiggle values = A Tp
A = amplitude of oscillation (distance units)
Tp = period of oscillation (time units)
variable values = v_name1 v_name2

17.33. fix deform command 1115

LAMMPS Documentation, Release stable 29Sep2021

v_name1 = variable with name1 for box length change as function of time
v_name2 = variable with name2 for change rate as function of time
xy, xz, yz args = style value
style = final or delta or vel or erate or trate or wiggle
final value = tilt
tilt = tilt factor at end of run (distance units)
delta value = dtilt
dtilt = change in tilt factor at end of run (distance units)
vel value = V
V = change tilt factor at this velocity (distance/time units),
effectively an engineering shear strain rate
erate value = R
R = engineering shear strain rate (1/time units)
trate value = R
R = true shear strain rate (1/time units)
wiggle values = A Tp
A = amplitude of oscillation (distance units)
Tp = period of oscillation (time units)
variable values = v_name1 v_name2
v_name1 = variable with name1 for tilt change as function of time
v_name2 = variable with name2 for change rate as function of time
• zero or more keyword/value pairs may be appended
• keyword = remap or flip or units
remap value = x or v or none
x = remap coords of atoms in group into deforming box
v = remap velocities of all atoms when they cross periodic boundaries
none = no remapping of x or v
flip value = yes or no
allow or disallow box flips when it becomes highly skewed
units value = lattice or box
lattice = distances are defined in lattice units
box = distances are defined in simulation box units

17.33.2 Examples

fix 1 all deform 1 x final 0.0 9.0 z final 0.0 5.0 units box
fix 1 all deform 1 x trate 0.1 y volume z volume
fix 1 all deform 1 xy erate 0.001 remap v
fix 1 all deform 10 y delta -0.5 0.5 xz vel 1.0

17.33.3 Description

Change the volume and/or shape of the simulation box during a dynamics run. Orthogonal simulation boxes have 3 ad-
justable parameters (x,y,z). Triclinic (non-orthogonal) simulation boxes have 6 adjustable parameters (x,y,z,xy,xz,yz).
Any or all of them can be adjusted independently and simultaneously by this command.
This fix can be used to perform non-equilibrium MD (NEMD) simulations of a continuously strained system. See the
fix nvt/sllod and compute temp/deform commands for more details. Note that simulation of a continuously extended
system (extensional flow) can be modeled using the UEF package and its fix commands.

1116 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

For the x, y, z parameters, the associated dimension cannot be shrink-wrapped. For the xy, yz, xz parameters, the
associated second dimension cannot be shrink-wrapped. Dimensions not varied by this command can be periodic
or non-periodic. Dimensions corresponding to unspecified parameters can also be controlled by a fix npt or fix nph
command.
The size and shape of the simulation box at the beginning of the simulation run were either specified by the create_box or
read_data or read_restart command used to setup the simulation initially if it is the first run, or they are the values from
the end of the previous run. The create_box, read data, and read_restart commands specify whether the simulation box
is orthogonal or non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz tilt factors. If fix deform changes
the xy,xz,yz tilt factors, then the simulation box must be triclinic, even if its initial tilt factors are 0.0.
As described below, the desired simulation box size and shape at the end of the run are determined by the parameters
of the fix deform command. Every Nth timestep during the run, the simulation box is expanded, contracted, or tilted
to ramped values between the initial and final values.

For the x, y, and z parameters, this is the meaning of their styles and values.
The final, delta, scale, vel, and erate styles all change the specified dimension of the box via “constant displacement”
which is effectively a “constant engineering strain rate”. This means the box dimension changes linearly with time
from its initial to final value.
For style final, the final lo and hi box boundaries of a dimension are specified. The values can be in lattice or box
distance units. See the discussion of the units keyword below.
For style delta, plus or minus changes in the lo/hi box boundaries of a dimension are specified. The values can be in
lattice or box distance units. See the discussion of the units keyword below.
For style scale, a multiplicative factor to apply to the box length of a dimension is specified. For example, if the initial
box length is 10, and the factor is 1.1, then the final box length will be 11. A factor less than 1.0 means compression.
For style vel, a velocity at which the box length changes is specified in units of distance/time. This is effectively a
“constant engineering strain rate”, where rate = V/L0 and L0 is the initial box length. The distance can be in lattice
or box distance units. See the discussion of the units keyword below. For example, if the initial box length is 100
Angstroms, and V is 10 Angstroms/ps, then after 10 ps, the box length will have doubled. After 20 ps, it will have
tripled.
The erate style changes a dimension of the box at a “constant engineering strain rate”. The units of the specified strain
rate are 1/time. See the units command for the time units associated with different choices of simulation units, e.g.
picoseconds for “metal” units). Tensile strain is unitless and is defined as delta/L0, where L0 is the original box length
and delta is the change relative to the original length. The box length L as a function of time will change as
L(t) = L0 (1 + erate*dt)
where dt is the elapsed time (in time units). Thus if erate R is specified as 0.1 and time units are picoseconds, this
means the box length will increase by 10% of its original length every picosecond. I.e. strain after 1 ps = 0.1, strain
after 2 ps = 0.2, etc. R = -0.01 means the box length will shrink by 1% of its original length every picosecond. Note
that for an “engineering” rate the change is based on the original box length, so running with R = 1 for 10 picoseconds
expands the box length by a factor of 11 (strain of 10), which is different that what the trate style would induce.
The trate style changes a dimension of the box at a “constant true strain rate”. Note that this is not an “engineering strain
rate”, as the other styles are. Rather, for a “true” rate, the rate of change is constant, which means the box dimension
changes non-linearly with time from its initial to final value. The units of the specified strain rate are 1/time. See the
units command for the time units associated with different choices of simulation units, e.g. picoseconds for “metal”
units). Tensile strain is unitless and is defined as delta/L0, where L0 is the original box length and delta is the change
relative to the original length.
The box length L as a function of time will change as
L(t) = L0 exp(trate*dt)

17.33. fix deform command 1117

LAMMPS Documentation, Release stable 29Sep2021

where dt is the elapsed time (in time units). Thus if trate R is specified as ln(1.1) and time units are picoseconds, this
means the box length will increase by 10% of its current (not original) length every picosecond. I.e. strain after 1 ps =
0.1, strain after 2 ps = 0.21, etc. R = ln(2) or ln(3) means the box length will double or triple every picosecond. R =
ln(0.99) means the box length will shrink by 1% of its current length every picosecond. Note that for a “true” rate the
change is continuous and based on the current length, so running with R = ln(2) for 10 picoseconds does not expand
the box length by a factor of 11 as it would with erate, but by a factor of 1024 since the box length will double every
picosecond.
Note that to change the volume (or cross-sectional area) of the simulation box at a constant rate, you can change multiple
dimensions via erate or trate. E.g. to double the box volume in a picosecond picosecond, you could set “x erate M”,
“y erate M”, “z erate M”, with M = pow(2,1/3) - 1 = 0.26, since if each box dimension grows by 26%, the box volume
doubles. Or you could set “x trate M”, “y trate M”, “z trate M”, with M = ln(1.26) = 0.231, and the box volume would
double every picosecond.
The volume style changes the specified dimension in such a way that the box volume remains constant while other box
dimensions are changed explicitly via the styles discussed above. For example, “x scale 1.1 y scale 1.1 z volume” will
shrink the z box length as the x,y box lengths increase, to keep the volume constant (product of x,y,z lengths). If “x
scale 1.1 z volume” is specified and parameter y is unspecified, then the z box length will shrink as x increases to keep
the product of x,z lengths constant. If “x scale 1.1 y volume z volume” is specified, then both the y,z box lengths will
shrink as x increases to keep the volume constant (product of x,y,z lengths). In this case, the y,z box lengths shrink so
as to keep their relative aspect ratio constant.
For solids or liquids, note that when one dimension of the box is expanded via fix deform (i.e. tensile strain), it may be
physically undesirable to hold the other 2 box lengths constant (unspecified by fix deform) since that implies a density
change. Using the volume style for those 2 dimensions to keep the box volume constant may make more physical sense,
but may also not be correct for materials and potentials whose Poisson ratio is not 0.5. An alternative is to use fix npt
aniso with zero applied pressure on those 2 dimensions, so that they respond to the tensile strain dynamically.
The wiggle style oscillates the specified box length dimension sinusoidally with the specified amplitude and period.
I.e. the box length L as a function of time is given by
L(t) = L0 + A sin(2*pi t/Tp)
where L0 is its initial length. If the amplitude A is a positive number the box initially expands, then contracts, etc. If
A is negative then the box initially contracts, then expands, etc. The amplitude can be in lattice or box distance units.
See the discussion of the units keyword below.
The variable style changes the specified box length dimension by evaluating a variable, which presumably is a function
of time. The variable with name1 must be an equal-style variable and should calculate a change in box length in units
of distance. Note that this distance is in box units, not lattice units; see the discussion of the units keyword below. The
formula associated with variable name1 can reference the current timestep. Note that it should return the “change” in
box length, not the absolute box length. This means it should evaluate to 0.0 when invoked on the initial timestep of
the run following the definition of fix deform. It should evaluate to a value > 0.0 to dilate the box at future times, or a
value < 0.0 to compress the box.
The variable name2 must also be an equal-style variable and should calculate the rate of box length change, in units
of distance/time, i.e. the time-derivative of the name1 variable. This quantity is used internally by LAMMPS to reset
atom velocities when they cross periodic boundaries. It is computed internally for the other styles, but you must provide
it when using an arbitrary variable.
Here is an example of using the variable style to perform the same box deformation as the wiggle style formula listed
above, where we assume that the current timestep = 0.

variable A equal 5.0

variable Tp equal 10.0
variable displace equal "v_A * sin(2*PI * step*dt/v_Tp)"
variable rate equal "2*PI*v_A/v_Tp * cos(2*PI * step*dt/v_Tp)"
fix 2 all deform 1 x variable v_displace v_rate remap v

1118 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

For the scale, vel, erate, trate, volume, wiggle, and variable styles, the box length is expanded or compressed around
its mid point.

For the xy, xz, and yz parameters, this is the meaning of their styles and values. Note that changing the tilt factors of a
triclinic box does not change its volume.
The final, delta, vel, and erate styles all change the shear strain at a “constant engineering shear strain rate”. This means
the tilt factor changes linearly with time from its initial to final value.
For style final, the final tilt factor is specified. The value can be in lattice or box distance units. See the discussion of
the units keyword below.
For style delta, a plus or minus change in the tilt factor is specified. The value can be in lattice or box distance units.
See the discussion of the units keyword below.
For style vel, a velocity at which the tilt factor changes is specified in units of distance/time. This is effectively an
“engineering shear strain rate”, where rate = V/L0 and L0 is the initial box length perpendicular to the direction of
shear. The distance can be in lattice or box distance units. See the discussion of the units keyword below. For example,
if the initial tilt factor is 5 Angstroms, and the V is 10 Angstroms/ps, then after 1 ps, the tilt factor will be 15 Angstroms.
After 2 ps, it will be 25 Angstroms.
The erate style changes a tilt factor at a “constant engineering shear strain rate”. The units of the specified shear strain
rate are 1/time. See the units command for the time units associated with different choices of simulation units, e.g.
picoseconds for “metal” units). Shear strain is unitless and is defined as offset/length, where length is the box length
perpendicular to the shear direction (e.g. y box length for xy deformation) and offset is the displacement distance in
the shear direction (e.g. x direction for xy deformation) from the unstrained orientation.
The tilt factor T as a function of time will change as
T(t) = T0 + L0*erate*dt
where T0 is the initial tilt factor, L0 is the original length of the box perpendicular to the shear direction (e.g. y box
length for xy deformation), and dt is the elapsed time (in time units). Thus if erate R is specified as 0.1 and time
units are picoseconds, this means the shear strain will increase by 0.1 every picosecond. I.e. if the xy shear strain was
initially 0.0, then strain after 1 ps = 0.1, strain after 2 ps = 0.2, etc. Thus the tilt factor would be 0.0 at time 0, 0.1*ybox
at 1 ps, 0.2*ybox at 2 ps, etc, where ybox is the original y box length. R = 1 or 2 means the tilt factor will increase by
1 or 2 every picosecond. R = -0.01 means a decrease in shear strain by 0.01 every picosecond.
The trate style changes a tilt factor at a “constant true shear strain rate”. Note that this is not an “engineering shear
strain rate”, as the other styles are. Rather, for a “true” rate, the rate of change is constant, which means the tilt factor
changes non-linearly with time from its initial to final value. The units of the specified shear strain rate are 1/time. See
the units command for the time units associated with different choices of simulation units, e.g. picoseconds for “metal”
units). Shear strain is unitless and is defined as offset/length, where length is the box length perpendicular to the shear
direction (e.g. y box length for xy deformation) and offset is the displacement distance in the shear direction (e.g. x
direction for xy deformation) from the unstrained orientation.
The tilt factor T as a function of time will change as
T(t) = T0 exp(trate*dt)
where T0 is the initial tilt factor and dt is the elapsed time (in time units). Thus if trate R is specified as ln(1.1) and
time units are picoseconds, this means the shear strain or tilt factor will increase by 10% every picosecond. I.e. if the
xy shear strain was initially 0.1, then strain after 1 ps = 0.11, strain after 2 ps = 0.121, etc. R = ln(2) or ln(3) means the
tilt factor will double or triple every picosecond. R = ln(0.99) means the tilt factor will shrink by 1% every picosecond.
Note that the change is continuous, so running with R = ln(2) for 10 picoseconds does not change the tilt factor by a
factor of 10, but by a factor of 1024 since it doubles every picosecond. Note that the initial tilt factor must be non-zero
to use the trate option.

17.33. fix deform command 1119

LAMMPS Documentation, Release stable 29Sep2021

Note that shear strain is defined as the tilt factor divided by the perpendicular box length. The erate and trate styles
control the tilt factor, but assume the perpendicular box length remains constant. If this is not the case (e.g. it changes
due to another fix deform parameter), then this effect on the shear strain is ignored.
The wiggle style oscillates the specified tilt factor sinusoidally with the specified amplitude and period. I.e. the tilt
factor T as a function of time is given by
T(t) = T0 + A sin(2*pi t/Tp)
where T0 is its initial value. If the amplitude A is a positive number the tilt factor initially becomes more positive, then
more negative, etc. If A is negative then the tilt factor initially becomes more negative, then more positive, etc. The
amplitude can be in lattice or box distance units. See the discussion of the units keyword below.
The variable style changes the specified tilt factor by evaluating a variable, which presumably is a function of time. The
variable with name1 must be an equal-style variable and should calculate a change in tilt in units of distance. Note that
this distance is in box units, not lattice units; see the discussion of the units keyword below. The formula associated
with variable name1 can reference the current timestep. Note that it should return the “change” in tilt factor, not the
absolute tilt factor. This means it should evaluate to 0.0 when invoked on the initial timestep of the run following the
definition of fix deform.
The variable name2 must also be an equal-style variable and should calculate the rate of tilt change, in units of dis-
tance/time, i.e. the time-derivative of the name1 variable. This quantity is used internally by LAMMPS to reset atom
velocities when they cross periodic boundaries. It is computed internally for the other styles, but you must provide it
when using an arbitrary variable.
Here is an example of using the variable style to perform the same box deformation as the wiggle style formula listed
above, where we assume that the current timestep = 0.

variable A equal 5.0

variable Tp equal 10.0
variable displace equal "v_A * sin(2*PI * step*dt/v_Tp)"
variable rate equal "2*PI*v_A/v_Tp * cos(2*PI * step*dt/v_Tp)"
fix 2 all deform 1 xy variable v_displace v_rate remap v

All of the tilt styles change the xy, xz, yz tilt factors during a simulation. In LAMMPS, tilt factors (xy,xz,yz) for triclinic
boxes are normally bounded by half the distance of the parallel box length. See the discussion of the flip keyword below,
to allow this bound to be exceeded, if desired.
For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5.
Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the
maximum tilt factor is 5 (as in this example), then configurations with tilt = . . . , -15, -5, 5, 15, 25, . . . are all equivalent.
To obey this constraint and allow for large shear deformations to be applied via the xy, xz, or yz parameters, the following
algorithm is used. If prd is the associated parallel box length (10 in the example above), then if the tilt factor exceeds
the accepted range of -5 to 5 during the simulation, then the box is flipped to the other limit (an equivalent box) and
the simulation continues. Thus for this example, if the initial xy tilt factor was 0.0 and “xy final 100.0” was specified,
then during the simulation the xy tilt factor would increase from 0.0 to 5.0, the box would be flipped so that the tilt
factor becomes -5.0, the tilt factor would increase from -5.0 to 5.0, the box would be flipped again, etc. The flip occurs
10 times and the final tilt factor at the end of the simulation would be 0.0. During each flip event, atoms are remapped
into the new box in the appropriate manner.
The one exception to this rule is if the first dimension in the tilt factor (x for xy) is non-periodic. In that case, the limits
on the tilt factor are not enforced, since flipping the box in that dimension does not change the atom positions due to
non-periodicity. In this mode, if you tilt the system to extreme angles, the simulation will simply become inefficient
due to the highly skewed simulation box.

1120 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Each time the box size or shape is changed, the remap keyword determines whether atom positions are remapped to
the new box. If remap is set to x (the default), atoms in the fix group are remapped; otherwise they are not. Note that
their velocities are not changed, just their positions are altered. If remap is set to v, then any atom in the fix group that
crosses a periodic boundary will have a delta added to its velocity equal to the difference in velocities between the lo
and hi boundaries. Note that this velocity difference can include tilt components, e.g. a delta in the x velocity when an
atom crosses the y periodic boundary. If remap is set to none, then neither of these remappings take place.
Conceptually, setting remap to x forces the atoms to deform via an affine transformation that exactly matches the box
deformation. This setting is typically appropriate for solids. Note that though the atoms are effectively “moving” with
the box over time, it is not due to their having a velocity that tracks the box change, but only due to the remapping.
By contrast, setting remap to v is typically appropriate for fluids, where you want the atoms to respond to the change
in box size/shape on their own and acquire a velocity that matches the box change, so that their motion will naturally
track the box without explicit remapping of their coordinates.

Note: When non-equilibrium MD (NEMD) simulations are performed using this fix, the option “remap v” should
normally be used. This is because fix nvt/sllod adjusts the atom positions and velocities to induce a velocity profile that
matches the changing box size/shape. Thus atom coordinates should NOT be remapped by fix deform, but velocities
SHOULD be when atoms cross periodic boundaries, since that is consistent with maintaining the velocity profile
already created by fix nvt/sllod. LAMMPS will warn you if the remap setting is not consistent with fix nvt/sllod.

Note: For non-equilibrium MD (NEMD) simulations using “remap v” it is usually desirable that the fluid (or flowing
material, e.g. granular particles) stream with a velocity profile consistent with the deforming box. As mentioned above,
using a thermostat such as fix nvt/sllod or fix lavgevin (with a bias provided by compute temp/deform), will typically
accomplish that. If you do not use a thermostat, then there is no driving force pushing the atoms to flow in a manner
consistent with the deforming box. E.g. for a shearing system the box deformation velocity may vary from 0 at the
bottom to 10 at the top of the box. But the stream velocity profile of the atoms may vary from -5 at the bottom to
+5 at the top. You can monitor these effects using the fix ave/chunk, compute temp/deform, and compute temp/profile
commands. One way to induce atoms to stream consistent with the box deformation is to give them an initial velocity
profile, via the velocity ramp command, that matches the box deformation rate. This also typically helps the system
come to equilibrium more quickly, even if a thermostat is used.

Note: If a fix rigid is defined for rigid bodies, and remap is set to x, then the center-of-mass coordinates of rigid bodies
will be remapped to the changing simulation box. This will be done regardless of whether atoms in the rigid bodies are
in the fix deform group or not. The velocity of the centers of mass are not remapped even if remap is set to v, since fix
nvt/sllod does not currently do anything special for rigid particles. If you wish to perform a NEMD simulation of rigid
particles, you can either thermostat them independently or include a background fluid and thermostat the fluid via fix
nvt/sllod.

The flip keyword allows the tilt factors for a triclinic box to exceed half the distance of the parallel box length, as
discussed above. If the flip value is set to yes, the bound is enforced by flipping the box when it is exceeded. If the
flip value is set to no, the tilt will continue to change without flipping. Note that if you apply large deformations, this
means the box shape can tilt dramatically LAMMPS will run less efficiently, due to the large volume of communication
needed to acquire ghost atoms around a processor’s irregular-shaped sub-domain. For extreme values of tilt, LAMMPS
may also lose atoms and generate an error.
The units keyword determines the meaning of the distance units used to define various arguments. A box value selects
standard distance units as defined by the units command, e.g. Angstroms for units = real or metal. A lattice value
means the distance units are in lattice spacings. The lattice command must have been previously used to define the
lattice spacing. Note that the units choice also affects the vel style parameters since it is defined in terms of distance/time.
Also note that the units keyword does not affect the variable style. You should use the xlat, ylat, zlat keywords of the
thermo_style command if you want to include lattice spacings in a variable formula.

17.33. fix deform command 1121

LAMMPS Documentation, Release stable 29Sep2021

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.33.4 Restart, fix_modify, output, run start/stop, minimize info

This fix will restore the initial box settings from binary restart files, which allows the fix to be properly continue
deformation, when using the start/stop options of the run command. None of the fix_modify options are relevant to this
fix. No global or per-atom quantities are stored by this fix for access by various output commands.
This fix can perform deformation over multiple runs, using the start and stop keywords of the run command. See the
run command for details of how to do this.
This fix is not invoked during energy minimization.

17.33.5 Restrictions

You cannot apply x, y, or z deformations to a dimension that is shrink-wrapped via the boundary command.
You cannot apply xy, yz, or xz deformations to a second dimension (y in xy) that is shrink-wrapped via the boundary
command.

17.33.6 Related commands

change_box

17.33.7 Default

The option defaults are remap = x, flip = yes, and units = lattice.

17.34 fix deposit command

17.34.1 Syntax

fix ID group-ID deposit N type M seed keyword values ...

• ID, group-ID are documented in fix command

• deposit = style name of this fix command
• N = # of atoms or molecules to insert

1122 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• type = atom type to assign to inserted atoms (offset for molecule insertion)
• M = insert a single atom or molecule every M steps
• seed = random # seed (positive integer)
• one or more keyword/value pairs may be appended to args
• keyword = region or id or global or local or near or gaussian or attempt or rate or vx or vy or vz or mol or rigid
or shake or units
region value = region-ID
region-ID = ID of region to use as insertion volume
id value = max or next
max = atom ID for new atom(s) is max ID of all current atoms plus one
next = atom ID for new atom(s) increments by one for every deposition
global values = lo hi
lo,hi = put new atom/molecule a distance lo-hi above all other atoms (distance␣
,→units)

local values = lo hi delta

lo,hi = put new atom/molecule a distance lo-hi above any nearby atom beneath it␣
,→(distance units)

delta = lateral distance within which a neighbor is considered "nearby" (distance␣

,→units)

near value = R
R = only insert atom/molecule if further than R from existing particles (distance␣
,→units)

gaussian values = xmid ymid zmid sigma

xmid,ymid,zmid = center of the gaussian distribution (distance units)
sigma = width of gaussian distribution (distance units)
attempt value = Q
Q = attempt a single insertion up to Q times
rate value = V
V = z velocity (y in 2d) at which insertion volume moves (velocity units)
vx values = vxlo vxhi
vxlo,vxhi = range of x velocities for inserted atom/molecule (velocity units)
vy values = vylo vyhi
vylo,vyhi = range of y velocities for inserted atom/molecule (velocity units)
vz values = vzlo vzhi
vzlo,vzhi = range of z velocities for inserted atom/molecule (velocity units)
target values = tx ty tz
tx,ty,tz = location of target point (distance units)
mol value = template-ID
template-ID = ID of molecule template specified in a separate molecule command
molfrac values = f1 f2 ... fN
f1 to fN = relative probability of creating each of N molecules in template-ID
rigid value = fix-ID
fix-ID = ID of fix rigid/small command
shake value = fix-ID
fix-ID = ID of fix shake command
orient values = rx ry rz
rx,ry,rz = vector to randomly rotate an inserted molecule around
units value = lattice or box
lattice = the geometry is defined in lattice units
box = the geometry is defined in simulation box units

17.34. fix deposit command 1123

LAMMPS Documentation, Release stable 29Sep2021

17.34.2 Examples

fix 3 all deposit 1000 2 100 29494 region myblock local 1.0 1.0 1.0 units box
fix 2 newatoms deposit 10000 1 500 12345 region disk near 2.0 vz -1.0 -0.8
fix 4 sputter deposit 1000 2 500 12235 region sphere vz -1.0 -1.0 target 5.0 5.0 0.0␣
,→units lattice

fix 5 insert deposit 200 2 100 777 region disk gaussian 5.0 5.0 9.0 1.0 units box

17.34.3 Description

Insert a single atom or molecule into the simulation domain every M timesteps until N atoms or molecules have been
inserted. This is useful for simulating deposition onto a surface. For the remainder of this doc page, a single inserted
atom or molecule is referred to as a “particle”.
If inserted particles are individual atoms, they are assigned the specified atom type. If they are molecules, the type of
each atom in the inserted molecule is specified in the file read by the molecule command, and those values are added
to the specified atom type. E.g. if the file specifies atom types 1,2,3, and those are the atom types you want for inserted
molecules, then specify type = 0. If you specify type = 2, the in the inserted molecule will have atom types 3,4,5.
All atoms in the inserted particle are assigned to two groups: the default group “all” and the group specified in the fix
deposit command (which can also be “all”).
If you are computing temperature values which include inserted particles, you will want to use the compute_modify
dynamic option, which insures the current number of atoms is used as a normalizing factor each time the temperature
is computed.
Care must be taken that inserted particles are not too near existing atoms, using the options described below. When
inserting particles above a surface in a non-periodic box (see the boundary command), the possibility of a particle
escaping the surface and flying upward should be considered, since the particle may be lost or the box size may grow
infinitely large. A fix wall/reflect command can be used to prevent this behavior. Note that if a shrink-wrap boundary
is used, it is OK to insert the new particle outside the box, however the box will immediately be expanded to include
the new particle. When simulating a sputtering experiment it is probably more realistic to ignore those atoms using the
thermo_modify command with the lost ignore option and a fixed boundary.
The fix deposit command must use the region keyword to define an insertion volume. The specified region must have
been previously defined with a region command. It must be defined with side = in.

Note: LAMMPS checks that the specified region is wholly inside the simulation box. It can do this correctly for
orthonormal simulation boxes. However for triclinic boxes, it only tests against the larger orthonormal box that bounds
the tilted simulation box. If the specified region includes volume outside the tilted box, then an insertion will likely
fail, leading to a “lost atoms” error. Thus for triclinic boxes you should insure the specified region is wholly inside the
simulation box.

The locations of inserted particles are taken from uniform distributed random numbers, unless the gaussian key-
word is used. Then the individual coordinates are taken from a gaussian distribution of width sigma centered on
xmid,ymid,zmid.
Individual atoms are inserted, unless the mol keyword is used. It specifies a template-ID previously defined using the
molecule command, which reads files that define one or more molecules. The coordinates, atom types, charges, etc, as
well as any bond/angle/etc and special neighbor information for the molecule can be specified in the molecule file. See
the molecule command for details. The only settings required to be in each file are the coordinates and types of atoms
in the molecule.
If the molecule template contains more than one molecule, the relative probability of depositing each molecule can be
specified by the molfrac keyword. N relative probabilities, each from 0.0 to 1.0, are specified, where N is the number

1124 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

of molecules in the template. Each time a molecule is deposited, a random number is used to sample from the list of
relative probabilities. The N values must sum to 1.0.
If you wish to insert molecules via the mol keyword, that will be treated as rigid bodies, use the rigid keyword, speci-
fying as its value the ID of a separate fix rigid/small command which also appears in your input script.

Note: If you wish the new rigid molecules (and other rigid molecules) to be thermostatted correctly via fix
rigid/small/nvt or fix rigid/small/npt, then you need to use the “fix_modify dynamic/dof yes” command for the rigid
fix. This is to inform that fix that the molecule count will vary dynamically.

If you wish to insert molecules via the mol keyword, that will have their bonds or angles constrained via SHAKE, use
the shake keyword, specifying as its value the ID of a separate fix shake command which also appears in your input
script.
Each timestep a particle is inserted, the coordinates for its atoms are chosen as follows. For insertion of individual
atoms, the “position” referred to in the following description is the coordinate of the atom. For insertion of molecule,
the “position” is the geometric center of the molecule; see the molecule doc page for details. A random rotation of the
molecule around its center point is performed, which determines the coordinates all the individual atoms.
A random position within the region insertion volume is generated. If neither the global or local keyword is used, the
random position is the trial position. If the global keyword is used, the random x,y values are used, but the z position
of the new particle is set above the highest current atom in the simulation by a distance randomly chosen between lo/hi.
(For a 2d simulation, this is done for the y position.) If the local keyword is used, the z position is set a distance between
lo/hi above the highest current atom in the simulation that is “nearby” the chosen x,y position. In this context, “nearby”
means the lateral distance (in x,y) between the new and old particles is less than the delta setting.
Once a trial x,y,z position has been selected, the insertion is only performed if no current atom in the simulation is
within a distance R of any atom in the new particle, including the effect of periodic boundary conditions if applicable.
R is defined by the near keyword. Note that the default value for R is 0.0, which will allow atoms to strongly overlap
if you are inserting where other atoms are present. This distance test is performed independently for each atom in
an inserted molecule, based on the randomly rotated configuration of the molecule. If this test fails, a new random
position within the insertion volume is chosen and another trial is made. Up to Q attempts are made. If the particle is
not successfully inserted, LAMMPS prints a warning message.

Note: If you are inserting finite size particles or a molecule or rigid body consisting of finite-size particles, then
you should typically set R larger than the distance at which any inserted particle may overlap with either a previously
inserted particle or an existing particle. LAMMPS will issue a warning if R is smaller than this value, based on the
radii of existing and inserted particles.

The rate option moves the insertion volume in the z direction (3d) or y direction (2d). This enables particles to be
inserted from a successively higher height over time. Note that this parameter is ignored if the global or local keywords
are used, since those options choose a z-coordinate for insertion independently.
The vx, vy, and vz components of velocity for the inserted particle are set using the values specified for the vx, vy,
and vz keywords. Note that normally, new particles should be a assigned a negative vertical velocity so that they move
towards the surface. For molecules, the same velocity is given to every particle (no rotation or bond vibration).
If the target option is used, the velocity vector of the inserted particle is changed so that it points from the insertion
position towards the specified target point. The magnitude of the velocity is unchanged. This can be useful, for example,
for simulating a sputtering process. E.g. the target point can be far away, so that all incident particles strike the surface
as if they are in an incident beam of particles at a prescribed angle.
The orient keyword is only used when molecules are deposited. By default, each molecule is inserted at a random
orientation. If this keyword is specified, then (rx,ry,rz) is used as an orientation vector, and each inserted molecule is

17.34. fix deposit command 1125

LAMMPS Documentation, Release stable 29Sep2021

rotated around that vector with a random value from zero to 2*PI. For a 2d simulation, rx = ry = 0.0 is required, since
rotations can only be performed around the z axis.
The id keyword determines how atom IDs and molecule IDs are assigned to newly deposited particles. Molecule IDs
are only assigned if molecules are being inserted. For the max setting, the atom and molecule IDs of all current atoms
are checked. Atoms in the new particle are assigned IDs starting with the current maximum plus one. If a molecule is
inserted it is assigned an ID = current maximum plus one. This means that if particles leave the system, the new IDs
may replace the lost ones. For the next setting, the maximum ID of any atom and molecule is stored at the time the fix
is defined. Each time a new particle is added, this value is incremented to assign IDs to the new atom(s) or molecule.
Thus atom and molecule IDs for deposited particles will be consecutive even if particles leave the system over time.
The units keyword determines the meaning of the distance units used for the other deposition parameters. A box value
selects standard distance units as defined by the units command, e.g. Angstroms for units = real or metal. A lattice
value means the distance units are in lattice spacings. The lattice command must have been previously used to define
the lattice spacing. Note that the units choice affects all the keyword values that have units of distance or velocity.

Note: If you are monitoring the temperature of a system where the atom count is changing due to adding particles,
you typically should use the compute_modify dynamic yes command for the temperature compute you are using.

17.34.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the deposition to binary restart files. This includes information about how many particles
have been deposited, the random number generator seed, the next timestep for deposition, etc. See the read_restart
command for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix
continues in an uninterrupted fashion.

Note: For this to work correctly, the timestep must not be changed after reading the restart with reset_timestep. The
fix will try to detect it and stop with an error.

None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access
by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.34.5 Restrictions

The specified insertion region cannot be a “dynamic” region, as defined by the region command.

17.34.6 Related commands

fix pour, region

1126 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.34.7 Default

Insertions are performed for individual atoms, i.e. no mol setting is defined. If the mol keyword is used, the default for
molfrac is an equal probabilities for all molecules in the template. Additional option defaults are id = max, delta = 0.0,
near = 0.0, attempt = 10, rate = 0.0, vx = 0.0 0.0, vy = 0.0 0.0, vz = 0.0 0.0, and units = lattice.

17.35 fix dpd/energy command

Accelerator Variants: dpd/energy/kk

17.35.1 Syntax

fix ID group-ID dpd/energy

• ID, group-ID are documented in fix command

• dpd/energy = style name of this fix command

17.35.2 Examples

fix 1 all dpd/energy

17.35.3 Description

Perform constant energy dissipative particle dynamics (DPD-E) integration. This fix updates the internal energies for
particles in the group at each timestep. It must be used in conjunction with a deterministic integrator (e.g. fix nve) that
updates the particle positions and velocities.
For fix dpd/energy, the particle internal temperature is related to the particle internal energy through a mesoparticle
equation of state. An additional fix must be specified that defines the equation of state for each particle, e.g. fix eos/cv.
This fix must be used with the pair_style dpd/fdt/energy command.
Note that numerous variants of DPD can be specified by choosing an appropriate combination of the integrator and
pair_style dpd/fdt/energy command. DPD under isoenergetic conditions can be specified by using fix dpd/energy, fix
nve and pair_style dpd/fdt/energy. DPD under isoenthalpic conditions can be specified by using fix dpd/energy, fix
nph and pair_style dpd/fdt/energy. Examples of each DPD variant are provided in the examples/PACKAGES/dpd-react
directory.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.35. fix dpd/energy command 1127

LAMMPS Documentation, Release stable 29Sep2021

17.35.4 Restrictions

This command is part of the DPD-REACT package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info.
This fix must be used with an additional fix that specifies time integration, e.g. fix nve.
The fix dpd/energy requires the dpd atom_style to be used in order to properly account for the particle internal energies
and temperature.
The fix dpd/energy must be used with an additional fix that specifies the mesoparticle equation of state for each particle.

17.35.5 Related commands

fix nve fix eos/cv

17.35.6 Default

none

(Lisal) M. Lisal, J.K. Brennan, J. Bonet Avalos, “Dissipative particle dynamics at isothermal, isobaric, isoenergetic,
and isoenthalpic conditions using Shardlow-like splitting algorithms.”, J. Chem. Phys., 135, 204105 (2011).
(Larentzos) J.P. Larentzos, J.K. Brennan, J.D. Moore, and W.D. Mattson, “LAMMPS Implementation of Constant
Energy Dissipative Particle Dynamics (DPD-E)”, ARL-TR-6863, U.S. Army Research Laboratory, Aberdeen Proving
Ground, MD (2014).

17.36 fix edpd/source command

17.37 fix tdpd/source command

17.37.1 Syntax

fix ID group-ID edpd/source keyword values ...

fix ID group-ID tdpd/source cc_index keyword values ...

• ID, group-ID are documented in fix command

• edpd/source or tdpd/source = style name of this fix command
• index (only specified for tdpd/source) = index of chemical species (1 to Nspecies)
• keyword = sphere or cuboid
sphere values = cx,cy,cz,radius,source
cx,cy,cz = x,y,z center of spherical domain (distance units)
radius = radius of a spherical domain (distance units)
source = heat source or concentration source (flux units, see below)
cuboid values = cx,cy,cz,dLx,dLy,dLz,source

1128 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

cx,cy,cz = x,y,z lower left corner of a cuboid domain (distance units)

dLx,dLy,dLz = x,y,z side length of a cuboid domain (distance units)
source = heat source or concentration source (flux units, see below)

17.37.2 Examples

fix 1 all edpd/source sphere 0.0 0.0 0.0 5.0 0.01

fix 1 all edpd/source cuboid 0.0 0.0 0.0 20.0 10.0 10.0 -0.01
fix 1 all tdpd/source 1 sphere 5.0 0.0 0.0 5.0 0.01
fix 1 all tdpd/source 2 cuboid 0.0 0.0 0.0 20.0 10.0 10.0 0.01

17.37.3 Description

Fix edpd/source adds a heat source as an external heat flux to each atom in a spherical or cuboid domain, where
the source is in units of energy/time. Fix tdpd/source adds an external concentration source of the chemical species
specified by index as an external concentration flux for each atom in a spherical or cuboid domain, where the source is
in units of mole/volume/time.
This command can be used to give an additional heat/concentration source term to atoms in a simulation, such as for a
simulation of a heat conduction with a source term (see Fig.12 in (Li2014)) or diffusion with a source term (see Fig.1
in (Li2015)), as an analog of a periodic Poiseuille flow problem.
If the sphere keyword is used, the cx,cy,cz,radius defines a spherical domain to apply the source flux to.
If the cuboid keyword is used, the cx,cy,cz,dLx,dLy,dLz defines a cuboid domain to apply the source flux to.

17.37.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.37.5 Restrictions

This fix is part of the DPD-MESO package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
Fix edpd/source must be used with the pair_style edpd command. Fix tdpd/source must be used with the pair_style
tdpd command.

17.37.6 Related commands

pair_style edpd, pair_style tdpd, compute edpd/temp/atom, compute tdpd/cc/atom

17.37. fix tdpd/source command 1129

LAMMPS Documentation, Release stable 29Sep2021

17.37.7 Default

none

(Li2014) Z. Li, Y.-H. Tang, H. Lei, B. Caswell and G.E. Karniadakis, “Energy-conserving dissipative particle dynamics
with temperature-dependent properties”, J. Comput. Phys., 265: 113-127 (2014). DOI: 10.1016/j.jcp.2014.02.003
(Li2015) Z. Li, A. Yazdani, A. Tartakovsky and G.E. Karniadakis, “Transport dissipative particle dynamics model for
mesoscopic advection-diffusion-reaction problems”, J. Chem. Phys., 143: 014101 (2015). DOI: 10.1063/1.4923254

17.38 fix drag command

17.38.1 Syntax

fix ID group-ID drag x y z fmag delta

• ID, group-ID are documented in fix command

• drag = style name of this fix command
• x,y,z = coord to drag atoms towards
• fmag = magnitude of force to apply to each atom (force units)
• delta = cutoff distance inside of which force is not applied (distance units)

17.38.2 Examples

fix center small-molecule drag 0.0 10.0 0.0 5.0 2.0

17.38.3 Description

Apply a force to each atom in a group to drag it towards the point (x,y,z). The magnitude of the force is specified by
fmag. If an atom is closer than a distance delta to the point, then the force is not applied.
Any of the x,y,z values can be specified as NULL which means do not include that dimension in the distance calculation
or force application.
This command can be used to steer one or more atoms to a new location in the simulation.

17.38.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.
This fix computes a global 3-vector of forces, which can be accessed by various output commands. This is the total
force on the group of atoms by the drag force. The vector values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

1130 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.38.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.38.6 Related commands

fix spring, fix spring/self , fix spring/rg, fix smd

17.38.7 Default

none

17.39 fix drude command

17.39.1 Syntax

fix ID group-ID drude flag1 flag2 ... flagN

• ID, group-ID are documented in fix command

• drude = style name of this fix command
• flag1 flag2 . . . flagN = Drude flag for each atom type (1 to N) in the system

17.39.2 Examples

fix 1 all drude 1 1 0 1 0 2 2 2

fix 1 all drude C C N C N D D D

Example input scripts available: examples/PACKAGES/drude

17.39.3 Description

Assign each atom type in the system to be one of 3 kinds of atoms within the Drude polarization model. This fix is
designed to be used with the thermalized Drude oscillator model. Polarizable models in LAMMPS are described on
the Howto polarizable doc page.
The three possible types can be designated with an integer (0,1,2) or capital letter (N,C,D):
• 0 or N = non-polarizable atom (not part of Drude model)
• 1 or C = Drude core
• 2 or D = Drude electron

17.39. fix drude command 1131

LAMMPS Documentation, Release stable 29Sep2021

17.39.4 Restrictions

This fix should be invoked before any other commands that implement the Drude oscillator model, such as fix
langevin/drude, fix tgnvt/drude, fix drude/transform, compute temp/drude, pair_style thole.

17.39.5 Related commands

fix langevin/drude, fix tgnvt/drude, fix drude/transform, compute temp/drude, pair_style thole

17.39.6 Default

none

17.40 fix drude/transform/direct command

17.41 fix drude/transform/inverse command

17.41.1 Syntax

fix ID group-ID style keyword value ...

• ID, group-ID are documented in fix command

• style = drude/transform/direct or drude/transform/inverse

17.41.2 Examples

fix 3 all drude/transform/direct

fix 1 all drude/transform/inverse

Example input scripts available: examples/PACKAGES/drude

17.41.3 Description

Transform the coordinates of Drude oscillators from real to reduced and back for thermalizing the Drude oscillators as
described in (Lamoureux) using a Nose-Hoover thermostat. This fix is designed to be used with the thermalized Drude
oscillator model. Polarizable models in LAMMPS are described on the Howto polarizable doc page.
Drude oscillators are a pair of atoms representing a single polarizable atom. Ideally, the mass of Drude particles would
vanish and their positions would be determined self-consistently by iterative minimization of the energy, the cores’
positions being fixed. It is however more efficient and it yields comparable results, if the Drude oscillators (the motion
of the Drude particle relative to the core) are thermalized at a low temperature. In that case, the Drude particles need
a small mass.
The thermostats act on the reduced degrees of freedom, which are defined by the following equations. Note that in
these equations upper case denotes atomic or center of mass values and lower case denotes Drude particle or dipole
values. Primes denote the transformed (reduced) values, while bare letters denote the original values.

1132 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Masses:

M0 = M + m

Mm
m0 =
M0
Positions:
M X + mx
X0 =
M0
x0 = x − X
Velocities:
M V + mv
V0 =
M0
v0 = v − V
Forces:

F0 = F + f

M f − mF
f0 =
M0
This transform conserves the total kinetic energy
1 1
(M V 2 + m v 2 ) = (M 0 V 02 + m0 v 02 )
2 2
and the virial defined with absolute positions

X F + x f = X 0 F 0 + x0 f 0

This fix requires each atom know whether it is a Drude particle or not. You must therefore use the fix drude command
to specify the Drude status of each atom type.

Note: only the Drude core atoms need to be in the group specified for this fix. A Drude electron will be transformed
together with its core even if it is not itself in the group. It is safe to include Drude electrons or non-polarizable atoms
in the group. The non-polarizable atoms will simply not be transformed.

This fix does NOT perform time integration. It only transform masses, coordinates, velocities and forces. Thus you
must use separate time integration fixes, like fix nve or fix npt to actually update the velocities and positions of atoms.
In order to thermalize the reduced degrees of freedom at different temperatures, two Nose-Hoover thermostats must be
defined, acting on two distinct groups.

Note: The fix drude/transform/direct command must appear before any Nose-Hoover thermostatting fixes. The fix
drude/transform/inverse command must appear after any Nose-Hoover thermostatting fixes.

Example:

17.41. fix drude/transform/inverse command 1133

LAMMPS Documentation, Release stable 29Sep2021

fix fDIRECT all drude/transform/direct

fix fNVT gCORES nvt temp 300.0 300.0 100
fix fNVT gDRUDES nvt temp 1.0 1.0 100
fix fINVERSE all drude/transform/inverse
compute TDRUDE all temp/drude
thermo_style custom step cpu etotal ke pe ebond ecoul elong press vol temp c_TDRUDE[1] c_
,→TDRUDE[2]

In this example, gCORES is the group of the atom cores and gDRUDES is the group of the Drude particles (electrons).
The centers of mass of the Drude oscillators will be thermostatted at 300.0 and the internal degrees of freedom will
be thermostatted at 1.0. The temperatures of cores and Drude particles, in center-of-mass and relative coordinates, are
calculated using compute temp/drude
In addition, if you want to use a barostat to simulate a system at constant pressure, only one of the Nose-Hoover fixes
must be npt, the other one should be nvt. You must add a compute temp/com and a fix_modify command so that the
temperature of the npt fix be just that of its group (the Drude cores) but the pressure be the overall pressure thermo_press.
Example:

compute cTEMP_CORE gCORES temp/com

fix fDIRECT all drude/transform/direct
fix fNPT gCORES npt temp 298.0 298.0 100 iso 1.0 1.0 500
fix_modify fNPT temp cTEMP_CORE press thermo_press
fix fNVT gDRUDES nvt temp 5.0 5.0 100
fix fINVERSE all drude/transform/inverse

In this example, gCORES is the group of the atom cores and gDRUDES is the group of the Drude particles. The centers
of mass of the Drude oscillators will be thermostatted at 298.0 and the internal degrees of freedom will be thermostatted
at 5.0. The whole system will be barostatted at 1.0.
In order to avoid the flying ice cube problem (irreversible transfer of linear momentum to the center of mass of the
system), you may need to add a fix momentum command:

fix fMOMENTUM all momentum 100 linear 1 1 1

17.41.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

17.41.5 Restrictions

none

1134 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.41.6 Related commands

fix drude, fix langevin/drude, compute temp/drude, pair_style thole

17.41.7 Default

none

(Lamoureux) Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003).

17.42 fix dt/reset command

17.42.1 Syntax

fix ID group-ID dt/reset N Tmin Tmax Xmax keyword values ...

• ID, group-ID are documented in fix command

• dt/reset = style name of this fix command
• N = re-compute dt every N timesteps
• Tmin = minimum dt allowed which can be NULL (time units)
• Tmax = maximum dt allowed which can be NULL (time units)
• Xmax = maximum distance for an atom to move in one timestep (distance units)
• zero or more keyword/value pairs may be appended
• keyword = emax or units
emax value = Emax
Emax = maximum kinetic energy change for an atom in one timestep (energy units)
units value = lattice or box
lattice = Xmax is defined in lattice units
box = Xmax is defined in simulation box units

17.42.2 Examples

fix 5 all dt/reset 10 1.0e-5 0.01 0.1

fix 5 all dt/reset 10 0.01 2.0 0.2 units box
fix 5 all dt/reset 5 NULL 0.001 0.5 emax 30 units box

17.42. fix dt/reset command 1135

LAMMPS Documentation, Release stable 29Sep2021

17.42.3 Description

Reset the timestep size every N steps during a run, so that no atom moves further than the specified Xmax distance,
based on current atom velocities and forces. Optionally an additional criterion is imposed by the emax keyword, so
that no atom’s kinetic energy changes by more than the specified Emax.
This can be useful when starting from a configuration with overlapping atoms, where forces will be large. Or it can be
useful when running an impact simulation where one or more high-energy atoms collide with a solid, causing a damage
cascade.
This fix overrides the timestep size setting made by the timestep command. The new timestep size dt is computed in
the following manner.
For each atom, the timestep is computed that would cause it to displace Xmax on the next integration step, as a function
of its current velocity and force. Since performing this calculation exactly would require the solution to a quartic
equation, a cheaper estimate is generated. The estimate is conservative in that the atom’s displacement is guaranteed
not to exceed Xmax, though it may be smaller.
In addition if the emax keyword is used, the specified Emax value is enforced as a limit on how much an atom’s kinetic
energy can change. If the timestep required is even smaller than for the Xmax displacement, then the smaller timestep
is used.
Given this putative timestep for each atom, the minimum timestep value across all atoms is computed. Then the Tmin
and Tmax bounds are applied, if specified. If one (or both) is specified as NULL, it is not applied.
When the run style is respa, this fix resets the outer loop (largest) timestep, which is the same timestep that the timestep
command sets.
Note that the cumulative simulation time (in time units), which accounts for changes in the timestep size as a simulation
proceeds, can be accessed by the thermo_style time keyword.

17.42.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global scalar which can be accessed by various output commands. The scalar stores the last timestep
on which the timestep was reset to a new value.
The scalar value calculated by this fix is “intensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.42.5 Restrictions

none

1136 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.42.6 Related commands

timestep

17.42.7 Default

The option defaults are units = lattice, and no emax kinetic energy limit.

17.43 fix efield command

17.43.1 Syntax

fix ID group-ID efield ex ey ez keyword value ...

• ID, group-ID are documented in fix command

• efield = style name of this fix command
• ex,ey,ez = E-field component values (electric field units)
• any of ex,ey,ez can be a variable (see below)
• zero or more keyword/value pairs may be appended to args
• keyword = region or energy
region value = region-ID
region-ID = ID of region atoms must be in to have added force
energy value = v_name
v_name = variable with name that calculates the potential energy of each atom in␣
,→the added E-field

17.43.2 Examples

fix kick external-field efield 1.0 0.0 0.0

fix kick external-field efield 0.0 0.0 v_oscillate

17.43.3 Description

Add a force F = qE to each charged atom in the group due to an external electric field being applied to the system. If
the system contains point-dipoles, also add a torque on the dipoles due to the external electric field.
For charges, any of the 3 quantities defining the E-field components can be specified as an equal-style or atom-style
variable, namely ex, ey, ez. If the value is a variable, it should be specified as v_name, where name is the variable
name. In this case, the variable will be evaluated each timestep, and its value used to determine the E-field component.
For point-dipoles, equal-style variables can be used, but atom-style variables are not currently supported, since they
imply a spatial gradient in the electric field which means additional terms with gradients of the field are required for
the force and torque on dipoles.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
E-field.

17.43. fix efield command 1137

LAMMPS Documentation, Release stable 29Sep2021

Atom-style variables can specify the same formulas as equal-style variables but can also include per-atom values, such
as atom coordinates. Thus it is easy to specify a spatially-dependent E-field with optional time-dependence as well.
If the region keyword is used, the atom must also be in the specified geometric region in order to have force added to
it.

Adding a force or torque to atoms implies a change in their potential energy as they move or rotate due to the applied
E-field.
For dynamics via the “run” command, this energy can be optionally added to the system’s potential energy for thermo-
dynamic output (see below). For energy minimization via the “minimize” command, this energy must be added to the
system’s potential energy to formulate a self-consistent minimization problem (see below).
The energy keyword is not allowed if the added field is a constant vector (ex,ey,ez), with all components defined as
numeric constants and not as variables. This is because LAMMPS can compute the energy for each charged particle
directly as E = -x dot qE = -q (x*ex + y*ey + z*ez), so that -Grad(E) = F. Similarly for point-dipole particles the energy
can be computed as E = -mu dot E = -(mux*ex + muy*ey + muz*ez).
The energy keyword is optional if the added force is defined with one or more variables, and if you are performing
dynamics via the run command. If the keyword is not used, LAMMPS will set the energy to 0.0, which is typically
fine for dynamics.
The energy keyword is required if the added force is defined with one or more variables, and you are performing energy
minimization via the “minimize” command for charged particles. It is not required for point-dipoles, but a warning is
issued since the minimizer in LAMMPS does not rotate dipoles, so you should not expect to be able to minimize the
orientation of dipoles in an applied electric field.
The energy keyword specifies the name of an atom-style variable which is used to compute the energy of each atom as
function of its position. Like variables used for ex, ey, ez, the energy variable is specified as v_name, where name is
the variable name.
Note that when the energy keyword is used during an energy minimization, you must insure that the formula defined
for the atom-style variable is consistent with the force variable formulas, i.e. that -Grad(E) = F. For example, if the
force due to the electric field were a spring-like F = kx, then the energy formula should be E = -0.5kx^2. If you don’t
do this correctly, the minimization will not converge properly.

17.43.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy inferred by the added force due to the
electric field to the global potential energy of the system as part of thermodynamic output. The default setting for this
fix is fix_modify energy no. Note that this energy is a fictitious quantity but is needed so that the minimize command
can include the forces added by this fix in a consistent manner. I.e. there is a decrease in potential energy when atoms
move in the direction of the added force due to the electric field.
The fix_modify virial option is supported by this fix to add the contribution due to the added forces on atoms to both
the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands.
The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial no.
The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
adding its forces. Default is the outermost level.
This fix computes a global scalar and a global 3-vector of forces, which can be accessed by various output commands.
The scalar is the potential energy discussed above. The vector is the total force added to the group of atoms. The scalar
and vector values calculated by this fix are “extensive”.

1138 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command. You should
not specify force components with a variable that has time-dependence for use with a minimizer, since the minimizer
increments the timestep as the iteration count during the minimization.

Note: If you want the fictitious potential energy associated with the added forces to be included in the total potential
energy of the system (the quantity being minimized), you MUST enable the fix_modify energy option for this fix.

17.43.5 Restrictions

None

17.43.6 Related commands

fix addforce

17.43.7 Default

none

17.44 fix ehex command

17.44.1 Syntax

fix ID group-ID ehex nevery F keyword value

• ID, group-ID are documented in fix command

• ehex = style name of this fix command
• nevery = add/subtract heat every this many timesteps
• F = energy flux into the reservoir (energy/time units)
• zero or more keyword/value pairs may be appended to args
• keyword = region or constrain or com or hex
region value = region-ID
region-ID = ID of region (reservoir) atoms must be in for added thermostatting␣
,→force

constrain value = none

apply the constraint algorithm (SHAKE or RATTLE) again at the end of the timestep
com value = none
rescale all sites of a constrained cluster of atom if its COM is in the reservoir
hex value = none
omit the coordinate correction to recover the HEX algorithm

17.44. fix ehex command 1139

LAMMPS Documentation, Release stable 29Sep2021

17.44.2 Examples

# Lennard-Jones, from examples/in.ehex.lj

fix fnve all nve

# specify regions rhot and rcold
...
fix fhot all ehex 1 0.15 region rhot
fix fcold all ehex 1 -0.15 region rcold

# SPC/E water, from examples/in.ehex.spce

fix fnve all nve
# specify regions rhot and rcold
...
fix fhot all ehex 1 0.075 region rhot constrain com
fix fcold all ehex 1 -0.075 region rcold constrain com
fix frattle all rattle 1e-10 400 0 b 1 a 1

17.44.3 Description

This fix implements the asymmetric version of the enhanced heat exchange algorithm (Wirnsberger). The eHEX algo-
rithm is an extension of the heat exchange algorithm (Ikeshoji) and adds an additional coordinate integration to account
for higher-order truncation terms in the operator splitting. The original HEX algorithm (implemented as fix heat) is
known to exhibit a slight energy drift limiting the accessible simulation times to a few nanoseconds. This issue is
greatly improved by the new algorithm decreasing the energy drift by at least a factor of a hundred (LJ and SPC/E
water) with little computational overhead.
In both algorithms (non-translational) kinetic energy is constantly swapped between regions (reservoirs) to impose a
heat flux onto the system. The equations of motion are therefore modified if a particle i is located inside a reservoir Γk
where k > 0. We use Γ0 to label those parts of the simulation box which are not thermostatted.) The input parameter
region-ID of this fix corresponds to k. The energy swap is modelled by introducing an additional thermostatting force to
the equations of motion, such that the time evolution of coordinates and momenta of particle i becomes (Wirnsberger)

ṙi = vi ,
fi gi
v̇i = + .
mi mi
The thermostatting force is given by

 mi FΓk(ri ) v − v
 
2 KΓk(r ) i Γk(ri )
k(ri ) > 0 (inside a reservoir),
gi = i
0 otherwise,

where mi is the mass and k(ri ) maps the particle position to the respective reservoir. The quantity FΓk(ri ) corresponds
to the input parameter F, which is the energy flux into the reservoir. Furthermore, KΓk(ri ) and vΓk(ri ) denote the
non-translational kinetic energy and the center of mass velocity of that reservoir. The thermostatting force does not
affect the center of mass velocities of the individual reservoirs and the entire simulation box. A derivation of the
equations and details on the numerical implementation with velocity Verlet in LAMMPS can be found in reference
“(Wirnsberger)”#_Wirnsberger.

Note: This fix only integrates the thermostatting force and must be combined with another integrator, such as fix nve,
to solve the full equations of motion.

1140 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

This fix is different from a thermostat such as fix nvt or fix temp/rescale in that energy is added/subtracted continu-
ally. Thus if there is not another mechanism in place to counterbalance this effect, the entire system will heat or cool
continuously.

Note: If heat is subtracted from the system too aggressively so that the group’s kinetic energy would go to zero, then
LAMMPS will halt with an error message. Increasing the value of nevery means that heat is added/subtracted less
frequently but in larger portions. The resulting temperature profile will therefore be the same.

This fix will default to fix_heat (HEX algorithm) if the keyword hex is specified.

Compatibility with SHAKE and RATTLE (rigid molecules):

This fix is compatible with fix shake and fix rattle. If either of these constraining algorithms is specified in the input
script and the keyword constrain is set, the bond distances will be corrected a second time at the end of the integration
step. It is recommended to specify the keyword com in addition to the keyword constrain. With this option all sites of
a constrained cluster are rescaled, if its center of mass is located inside the region. Rescaling all sites of a cluster by
the same factor does not introduce any velocity components along fixed bonds. No rescaling takes place if the center
of mass lies outside the region.

Note: You can only use the keyword com along with constrain.

To achieve the highest accuracy it is recommended to use fix rattle with the keywords constrain and com as shown in
the second example. Only if RATTLE is employed, the velocity constraints will be satisfied.

Note: Even if RATTLE is used and the keywords com and constrain are both set, the coordinate constraints will
not necessarily be satisfied up to the target precision. The velocity constraints are satisfied as long as all sites of a
cluster are rescaled (keyword com) and the cluster does not span adjacent reservoirs. The current implementation of
the eHEX algorithm introduces a small error in the bond distances, which goes to zero with order three in the timestep.
For example, in a simulation of SPC/E water with a timestep of 2 fs the maximum relative error in the bond distances
was found to be on the order of 10−7 for relatively large temperature gradients. A higher precision can be achieved by
decreasing the timestep.

17.44.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.44. fix ehex command 1141

LAMMPS Documentation, Release stable 29Sep2021

17.44.5 Restrictions

This fix is part of the RIGID package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.44.6 Related commands

fix heat, fix thermal/conductivity, compute temp, compute temp/region

17.44.7 Default

none

(Ikeshoji) Ikeshoji and Hafskjold, Molecular Physics, 81, 251-261 (1994).

(Wirnsberger) Wirnsberger, Frenkel, and Dellago, J Chem Phys, 143, 124104 (2015).

17.45 fix electron/stopping command

17.46 fix electron/stopping/fit command

17.46.1 Syntax

fix ID group-ID style args

• ID, group-ID are documented in fix command

• style = electron/stopping or electron/stopping/fit
electron/stopping args = Ecut file keyword value ...
Ecut = minimum kinetic energy for electronic stopping (energy units)
file = name of the file containing the electronic stopping power table

electron/stopping/fit args = Ecut c1 c2 ...

Ecut = minimum kinetic energy for electronic stopping (energy units)
c1 c2 = linear and quadratic coefficients for the fitted quadratic polynomial
• zero or more keyword/value pairs may be appended to args for style = electron/stopping
keyword = region or minneigh
region value = region-ID
region-ID = region whose atoms will be affected by this fix
minneigh value = minneigh
minneigh = minimum number of neighbors an atom to have stopping applied

1142 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.46.2 Examples

fix el all electron/stopping 10.0 elstop-table.txt

fix el all electron/stopping 10.0 elstop-table.txt minneigh 3
fix el mygroup electron/stopping 1.0 elstop-table.txt region bulk
fix 1 all electron/stopping/fit 4.63 3.3e-3 4.0e-8
fix 1 all electron/stopping/fit 3.49 1.8e-3 9.0e-8 7.57 4.2e-3 5.0e-8

17.46.3 Description

This fix implements inelastic energy loss for fast projectiles in solids. It applies a friction force to fast moving atoms to
slow them down due to electronic stopping (energy lost via electronic collisions per unit of distance). This fix should
be used for simulation of irradiation damage or ion implantation, where the ions can lose noticeable amounts of energy
from electron excitations. If the electronic stopping power is not considered, the simulated range of the ions can be
severely overestimated (Nordlund98, Nordlund95).
The electronic stopping is implemented by applying a friction force to each atom as:
~vi
F~i = F~i0 − · Se
k~vi k

where F~i is the resulting total force on the atom. F~i0 is the original force applied to the atom, ~vi is its velocity and Se
is the stopping power of the ion.

Note: In addition to electronic stopping, atomic cascades and irradiation simulations require the use of an adaptive
timestep (see fix dt/reset) and the repulsive ZBL potential (see ZBL potential) or similar. Without these settings the
interaction between the ion and the target atoms will be faulty. It is also common to use in such simulations a thermostat
(fix_nvt) in the borders of the simulation cell.

Note: This fix removes energy from fast projectiles without depositing it as a heat to the simulation cell. Such
implementation might lead to the unphysical results when the amount of energy deposited to the electronic system is
large, e.g. simulations of Swift Heavy Ions (energy per nucleon of 100 keV/amu or higher) or multiple projectiles. You
could compensate energy loss by coupling bulk atoms with some thermostat or control heat transfer between electronic
and atomic subsystems with the two-temperature model (fix_ttm).

At low velocities the electronic stopping is negligible. The electronic friction is not applied to atoms whose kinetic
energy is smaller than Ecut, or smaller than the lowest energy value given in the table in file. Electronic stopping should
be applied only when a projectile reaches bulk material. This fix scans neighbor list and excludes atoms with fewer
than minneigh neighbors (by default one). If the pair potential cutoff is large, minneigh should be increased, though not
above the number of nearest neighbors in bulk material. An alternative is to disable the check for neighbors by setting
minneigh to zero and using the region keyword. This is necessary when running simulations of cluster bombardment.
If the region keyword is used, the atom must also be in the specified geometric region in order to have electronic
stopping applied to it. This is useful if the position of the bulk material is fixed. By default the electronic stopping is
applied everywhere in the simulation cell.

The energy ranges and stopping powers are read from the file file. Lines starting with # and empty lines are ignored.
Otherwise each line must contain exactly N+1 numbers, where N is the number of atom types in the simulation.
The first column is the energy for which the stopping powers on that line apply. The energies must be sorted from the
smallest to the largest. The other columns are the stopping powers Se for each atom type, in ascending order, in force

17.46. fix electron/stopping/fit command 1143

LAMMPS Documentation, Release stable 29Sep2021

units. The stopping powers for intermediate energy values are calculated with linear interpolation between 2 nearest
points.
For example:

# This is a comment
# atom-1 atom-2
# eV eV/Ang eV/Ang # units metal
10 0 0
250 60 80
750 100 150

If an atom which would have electronic stopping applied to it has a kinetic energy higher than the largest energy given
in file, LAMMPS will exit with an error message.
The stopping power depends on the energy of the ion and the target material. The electronic stopping table can be
obtained from scientific publications, experimental databases or by using SRIM software. Other programs such as
CasP or PASS can calculate the energy deposited as a function of the impact parameter of the ion; these results can be
used to derive the stopping power.

Style electron/stopping/fit calculates the electronic stopping power and cumulative energy lost to the electron gas via
a quadratic functional and applies a drag force to the classical equations-of-motion for all atoms moving above some
minimum cutoff velocity (i.e., kinetic energy). These coefficients can be determined by fitting a quadratic polynomial
to electronic stopping data predicted by, for example, SRIM or TD-DFT. Multiple ‘Ecut c1 c2’ values can be provided
for multi-species simulations in the order of the atom types. There is an examples/PACKAGES/electron_stopping/
directory, which illustrates uses of this command. Details of this implementation are further described in Stewart2018
and Lee2020.

17.46.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify options are not supported.
This fix computes a global scalar, which can be accessed by various output commands. The scalar is the total energy
loss from electronic stopping applied by this fix since the start of the latest run. It is considered “intensive”.
The start/stop keywords of the run command have no effect on this fix.

17.46.5 Restrictions

This pair style is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the
Build package doc page for more info.

1144 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.46.6 Default

The default is no limitation by region, and minneigh = 1.

(electronic stopping) Wikipedia - Electronic Stopping Power: https://en.wikipedia.org/wiki/Stopping_power_

%28particle_radiation%29
(Nordlund98) Nordlund, Kai, et al. Physical Review B 57.13 (1998): 7556.
(Nordlund95) Nordlund, Kai. Computational materials science 3.4 (1995): 448-456.
(SRIM) SRIM webpage: http://www.srim.org/
(CasP) CasP webpage: https://www.helmholtz-berlin.de/people/gregor-schiwietz/casp_en.html
(PASS) PASS webpage: https://www.sdu.dk/en/DPASS
(Stewart2018) J.A. Stewart, et al. (2018) Journal of Applied Physics, 123(16), 165902.
(Lee2020) C.W. Lee, et al. (2020) Physical Review B, 102(2), 024107.

17.47 fix enforce2d command

Accelerator Variants: enforce2d/kk

17.47.1 Syntax

fix ID group-ID enforce2d

• ID, group-ID are documented in fix command

• enforce2d = style name of this fix command

17.47.2 Examples

fix 5 all enforce2d

17.47.3 Description

Zero out the z-dimension velocity and force on each atom in the group. This is useful when running a 2d simulation to
insure that atoms do not move from their initial z coordinate.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.

17.47. fix enforce2d command 1145

LAMMPS Documentation, Release stable 29Sep2021

See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.47.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command.

17.47.5 Restrictions

none

17.47.6 Related commands

none

17.47.7 Default

none

17.48 fix eos/cv command

17.48.1 Syntax

fix ID group-ID eos/cv cv

• ID, group-ID are documented in fix command

• eos/cv = style name of this fix command
• cv = constant-volume heat capacity (energy/temperature units)

17.48.2 Examples

fix 1 all eos/cv 0.01

1146 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.48.3 Description

Fix eos/cv applies a mesoparticle equation of state to relate the particle internal energy (ui ) to the particle internal
temperature (θi ). The eos/cv mesoparticle equation of state requires the constant-volume heat capacity, and is defined
as follows:

ui = umech
i + ucond
i = C V θi

where CV is the constant-volume heat capacity, ucond is the internal conductive energy, and umech is the internal
mechanical energy. Note that alternative definitions of the mesoparticle equation of state are possible.

17.48.4 Restrictions

This command is part of the DPD-REACT package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info.
This command also requires use of the atom_style dpd command.

17.48.5 Related commands

fix shardlow, pair dpd/fdt

17.48.6 Default

none

(Larentzos) J.P. Larentzos, J.K. Brennan, J.D. Moore, and W.D. Mattson, “LAMMPS Implementation of Constant
Energy Dissipative Particle Dynamics (DPD-E)”, ARL-TR-6863, U.S. Army Research Laboratory, Aberdeen Proving
Ground, MD (2014).

17.49 fix eos/table command

17.49.1 Syntax

fix ID group-ID eos/table style file N keyword

• ID, group-ID are documented in fix command

• eos/table = style name of this fix command
• style = linear = method of interpolation
• file = filename containing the tabulated equation of state
• N = use N values in linear tables
• keyword = name of table keyword corresponding to table file

17.49. fix eos/table command 1147

LAMMPS Documentation, Release stable 29Sep2021

17.49.2 Examples

fix 1 all eos/table linear eos.table 100000 KEYWORD

17.49.3 Description

Fix eos/table applies a tabulated mesoparticle equation of state to relate the particle internal energy (u_i) to the particle
internal temperature (dpdTheta_i).
Fix eos/table creates interpolation tables of length N from internal energy values listed in a file as a function of internal
temperature.
The interpolation tables are created by fitting cubic splines to the file values and interpolating energy values at each
of N internal temperatures, and vice versa. During a simulation, these tables are used to interpolate internal energy or
temperature values as needed. The interpolation is done with the linear style.
For the linear style, the internal temperature is used to find 2 surrounding table values from which an internal energy
is computed by linear interpolation, and vice versa.
The filename specifies a file containing tabulated internal temperature and internal energy values. The keyword specifies
a section of the file. The format of this file is described below.

The format of a tabulated file is as follows (without the parenthesized comments):

# EOS TABLE (one or more comment or blank lines)

KEYWORD (keyword is first text on line)

N 500 (N parameter)
(blank)
1 1.00 0.000 (index, internal temperature, internal energy)
2 1.02 0.001
...
500 10.0 0.500

A section begins with a non-blank line whose first character is not a “#”; blank lines or lines starting with “#” can be
used as comments between sections. The first line begins with a keyword which identifies the section. The line can
contain additional text, but the initial text must match the argument specified in the fix command.
The next line lists the number of table entries. The parameter “N” is required and its value is the number of table entries
that follow. Note that this may be different than the N specified in the fix eos/table command. Let Ntable = N in the
fix command, and Nfile = “N” in the tabulated file. What LAMMPS does is a preliminary interpolation by creating
splines using the Nfile tabulated values as nodal points. It uses these to interpolate as needed to generate energy and
temperature values at Ntable different points. The resulting tables of length Ntable are then used as described above,
when computing energy and temperature relationships. This means that if you want the interpolation tables of length
Ntable to match exactly what is in the tabulated file (with effectively no preliminary interpolation), you should set
Ntable = Nfile.
Following a blank line, the next N lines list the tabulated values. On each line, the first value is the index from 1 to
N, the second value is the internal temperature (in temperature units), the third value is the internal energy (in energy
units).
Note that the internal temperature and internal energy values must increase from one line to the next.
Note that one file can contain many sections, each with a tabulated potential. LAMMPS reads the file section by section
until it finds one that matches the specified keyword.

1148 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.49.4 Restrictions

This command is part of the DPD-REACT package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info.
This command also requires use of the atom_style dpd command.
The equation of state must be a monotonically increasing function.
An error will occur if the internal temperature or internal energies are not within the table cutoffs.

17.49.5 Related commands

fix shardlow, pair dpd/fdt

17.49.6 Default

none

17.50 fix eos/table/rx command

Accelerator Variants: eos/table/rx/kk

17.50.1 Syntax

fix ID group-ID eos/table/rx style file1 N keyword ...

• ID, group-ID are documented in fix command

• eos/table/rx = style name of this fix command
• style = linear = method of interpolation
• file1 = filename containing the tabulated equation of state
• N = use N values in linear tables
• keyword = name of table keyword corresponding to table file
• file2 = filename containing the heats of formation of each species (optional)
• deltaHf = heat of formation for a single species in energy units (optional)
• energyCorr = energy correction in energy units (optional)
• tempCorrCoeff = temperature correction coefficient (optional)

17.50. fix eos/table/rx command 1149

LAMMPS Documentation, Release stable 29Sep2021

17.50.2 Examples

fix 1 all eos/table/rx linear eos.table 10000 KEYWORD thermo.table

fix 1 all eos/table/rx linear eos.table 10000 KEYWORD 1.5
fix 1 all eos/table/rx linear eos.table 10000 KEYWORD 1.5 0.025 0.0

17.50.3 Description

Fix eos/table/rx applies a tabulated mesoparticle equation of state to relate the concentration-dependent particle internal
energy (ui ) to the particle internal temperature (θi ).
The concentration-dependent particle internal energy (ui ) is computed according to the following relation:
m
X 3kb T
Ui = ci,j (uj + ∆Hf,j ) + + N kb T
j=1
2

where m is the number of species, ci,j is the concentration of species j in particle i, uj is the internal energy of
species j, ∆Hf,j istheheatof f ormationof species ∗ j∗, N isthenumberof moleculesrepresentedbythecoarse −
grainedparticle, : math : is the Boltzmann constant, and T is the temperature of the system. Additionally, it is possible
to modify the concentration-dependent particle internal energy relation by adding an energy correction, temperature-
dependent correction, and/or a molecule-dependent correction. An energy correction can be specified as a constant
(in energy units). A temperature correction can be specified by multiplying a temperature correction coefficient by the
internal temperature. A molecular correction can be specified by by multiplying a molecule correction coefficient by
the average number of product gas particles in the coarse-grain particle.
Fix eos/table/rx creates interpolation tables of length N from m internal energy values of each species uj listed in
a file as a function of internal temperature. During a simulation, these tables are used to interpolate internal energy
or temperature values as needed. The interpolation is done with the linear style. For the linear style, the internal
temperature is used to find 2 surrounding table values from which an internal energy is computed by linear interpolation.
A secant solver is used to determine the internal temperature from the internal energy.
The first filename specifies a file containing tabulated internal temperature and m internal energy values for each species
uj . The keyword specifies a section of the file. The format of this file is described below.
The second filename specifies a file containing heat of formation ∆Hf,j for each species.
In cases where the coarse-grain particle represents a single molecular species (i.e., no reactions occur and fix rx is not
present in the input file), fix eos/table/rx can be applied in a similar manner to fix eos/table within a non-reactive DPD
simulation. In this case, the heat of formation filename is replaced with the heat of formation value for the single species.
Additionally, the energy correction and temperature correction coefficients may also be specified as fix arguments.

The format of a tabulated file is as follows (without the parenthesized comments):

# EOS TABLE (one or more comment or blank lines)

KEYWORD (keyword is first text on line)

N 500 h2 no2 n2 ... no (N parameter species1 species2 ... speciesN)
(blank)
1 1.00 0.000 ... 0.0000 (index, internal temperature, internal energy of species 1, ..
,→., internal energy of species m)

2 1.02 0.001 ... 0.0002

...
500 10.0 0.500 ... 1.0000

1150 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

A section begins with a non-blank line whose first character is not a “#”; blank lines or lines starting with “#” can be
used as comments between sections. The first line begins with a keyword which identifies the section. The line can
contain additional text, but the initial text must match the argument specified in the fix command.
The next line lists the number of table entries and the species names that correspond with all the species listed in
the reaction equations through the fix rx command. The parameter “N” is required and its value is the number of table
entries that follow. Let Nfile = “N” in the tabulated file. What LAMMPS does is a preliminary interpolation by creating
splines using the Nfile tabulated values as nodal points.
Following a blank line, the next N lines list the tabulated values. On each line, the first value is the index from 1 to N,
the second value is the internal temperature (in temperature units), the third value until the m+3 value are the internal
energies of the m species (in energy units).
Note that all internal temperature and internal energy values must increase from one line to the next.
Note that one file can contain many sections, each with a tabulated potential. LAMMPS reads the file section by section
until it finds one that matches the specified keyword.

The format of a heat of formation file is as follows (without the parenthesized comments):

# HEAT OF FORMATION TABLE (one or more comment or blank lines)

(blank)
h2 0.00 (species name, heat of formation)
no2 0.34
n2 0.00
...
no 0.93

Note that the species can be listed in any order. The tag that is used as the species name must correspond with the tags
used to define the reactions with the fix rx command.
Alternatively, corrections to the EOS can be included by specifying three additional columns that correspond to the
energy correction, the temperature correction coefficient and molecule correction coefficient. In this case, the format
of the file is as follows:

# HEAT OF FORMATION TABLE (one or more comment or blank lines)

(blank)
h2 0.00 1.23 0.025 0.0 (species name, heat of formation, energy correction,␣
,→temperature correction coefficient, molecule correction coefficient)

no2 0.34 0.00 0.000 -1.76

n2 0.00 0.00 0.000 -1.76
...
no 0.93 0.00 0.000 -1.76

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.

17.50. fix eos/table/rx command 1151

LAMMPS Documentation, Release stable 29Sep2021

See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.50.4 Restrictions

This command is part of the DPD-REACT package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info.
This command also requires use of the atom_style dpd command.
The equation of state must be a monotonically increasing function.
An error will occur if the internal temperature or internal energies are not within the table cutoffs.

17.50.5 Related commands

fix rx, pair dpd/fdt

17.50.6 Default

none

17.51 fix evaporate command

17.51.1 Syntax

fix ID group-ID evaporate N M region-ID seed

• ID, group-ID are documented in fix command

• evaporate = style name of this fix command
• N = delete atoms every this many timesteps
• M = number of atoms to delete each time
• region-ID = ID of region within which to perform deletions
• seed = random number seed to use for choosing atoms to delete
• zero or more keyword/value pairs may be appended
keyword = molecule
molecule value = no or yes

1152 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.51.2 Examples

fix 1 solvent evaporate 1000 10 surface 49892

fix 1 solvent evaporate 1000 10 surface 38277 molecule yes

17.51.3 Description

Remove M atoms from the simulation every N steps. This can be used, for example, to model evaporation of solvent
particles or molecules (i.e. drying) of a system. Every N steps, the number of atoms in the fix group and within the
specified region are counted. M of these are chosen at random and deleted. If there are less than M eligible particles,
then all of them are deleted.
If the setting for the molecule keyword is no, then only single atoms are deleted. In this case, you should insure you
do not delete only a portion of a molecule (only some of its atoms), or LAMMPS will soon generate an error when it
tries to find those atoms. LAMMPS will warn you if any of the atoms eligible for deletion have a non-zero molecule
ID, but does not check for this at the time of deletion.
If the setting for the molecule keyword is yes, then when an atom is chosen for deletion, the entire molecule it is part
of is deleted. The count of deleted atoms is incremented by the number of atoms in the molecule, which may make it
exceed M. If the molecule ID of the chosen atom is 0, then it is assumed to not be part of a molecule, and just the single
atom is deleted.
As an example, if you wish to delete 10 water molecules every N steps, you should set M to 30. If only the water’s
oxygen atoms were in the fix group, then two hydrogen atoms would be deleted when an oxygen atom is selected for
deletion, whether the hydrogen atoms are inside the evaporation region or not.
Note that neighbor lists are re-built on timesteps that atoms are removed. Thus you should not remove atoms too
frequently or you will incur overhead due to the cost of building neighbor lists.

Note: If you are monitoring the temperature of a system where the atom count is changing due to evaporation, you
typically should use the compute_modify dynamic yes command for the temperature compute you are using.

17.51.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global scalar, which can be accessed by various output commands. The scalar is the cumulative
number of deleted atoms. The scalar value calculated by this fix is “intensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.51.5 Restrictions

None

17.51. fix evaporate command 1153

LAMMPS Documentation, Release stable 29Sep2021

17.51.6 Related commands

fix deposit

17.51.7 Default

The option defaults are molecule = no.

17.52 fix external command

17.52.1 Syntax

fix ID group-ID external mode args

• ID, group-ID are documented in fix command

• external = style name of this fix command
• mode = pf/callback or pf/array
pf/callback args = Ncall Napply
Ncall = make callback every Ncall steps
Napply = apply callback forces every Napply steps
pf/array args = Napply
Napply = apply array forces every Napply steps

17.52.2 Examples

fix 1 all external pf/callback 1 1

fix 1 all external pf/callback 100 1
fix 1 all external pf/array 10

17.52.3 Description

This fix allows external programs that are running LAMMPS through its library interface to modify certain LAMMPS
properties on specific timesteps, similar to the way other fixes do. The external driver can be a C/C++ or Fortran
program or a Python script.

If mode is pf/callback then the fix will make a callback every Ncall timesteps or minimization iterations to the external
program. The external program computes forces on atoms by setting values in an array owned by the fix. The fix then
adds these forces to each atom in the group, once every Napply steps, similar to the way the fix addforce command
works. Note that if Ncall > Napply, the force values produced by one callback will persist, and be used multiple times
to update atom forces.
The callback function “foo” is invoked by the fix as:

foo(void *ptr, bigint timestep, int nlocal, tagint *ids, double **x, double **fexternal);

The arguments are as follows:

1154 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• ptr = pointer provided by and simply passed back to external driver

• timestep = current LAMMPS timestep
• nlocal = # of atoms on this processor
• ids = list of atom IDs on this processor
• x = coordinates of atoms on this processor
• fexternal = forces to add to atoms on this processor
Note that timestep is a “bigint” which is defined in src/lmptype.h, typically as a 64-bit integer. And ids is a pointer to
type “tagint” which is typically a 32-bit integer unless LAMMPS is compiled with -DLAMMPS_BIGBIG. For more
info please see the build settings section of the manual. Finally, fexternal are the forces returned by the driver program.
The fix has a set_callback() method which the external driver can call to pass a pointer to its foo() function. See the
couple/lammps_quest/lmpqst.cpp file in the LAMMPS distribution for an example of how this is done. This sample
application performs classical MD using quantum forces computed by a density functional code Quest.

If mode is pf/array then the fix simply stores force values in an array. The fix adds these forces to each atom in the
group, once every Napply steps, similar to the way the fix addforce command works.
The name of the public force array provided by the FixExternal class is

double **fexternal;

It is allocated by the FixExternal class as an (N,3) array where N is the number of atoms owned by a processor. The 3
corresponds to the fx, fy, fz components of force.
It is up to the external program to set the values in this array to the desired quantities, as often as desired. For example,
the driver program might perform an MD run in stages of 1000 timesteps each. In between calls to the LAMMPS run
command, it could retrieve atom coordinates from LAMMPS, compute forces, set values in fexternal, etc.

To use this fix during energy minimization, the energy corresponding to the added forces must also be set so as to be
consistent with the added forces. Otherwise the minimization will not converge correctly. Correspondingly, the global
virial needs to be updated to be use this fix with variable cell calculations (e.g. fix box/relax or fix npt).
This can be done from the external driver by calling these public methods of the FixExternal class:

void set_energy_global(double eng);

void set_virial_global(double *virial);

where eng is the potential energy, and virial an array of the 6 stress tensor components. Eng is an extensive quantity,
meaning it should be the sum over per-atom energies of all affected atoms. It should also be provided in energy units
consistent with the simulation. See the details below for how to insure this energy setting is used appropriately in a
minimization.
Additional public methods that the caller can use to update system properties are:

void set_energy_peratom(double *eng);

void set_virial_peratom(double **virial);
void set_vector_length(int n);
void set_vector(int idx, double val);

These allow to set per-atom energy contributions, per-atom stress contributions, the length and individual values of a
global vector of properties that the caller code may want to communicate to LAMMPS (e.g. for use in fix ave/time or
in equal-style variables or for custom thermo output.

17.52. fix external command 1155

LAMMPS Documentation, Release stable 29Sep2021

17.52.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy set by the external driver to both the
global potential energy and peratom potential energies of the system as part of thermodynamic output or output by the
compute pe/atom command. The default setting for this fix is fix_modify energy yes. Note that this energy may be a
fictitious quantity but it is needed so that the minimize command can include the forces added by this fix in a consistent
manner. I.e. there is a decrease in potential energy when atoms move in the direction of the added force.
The fix_modify virial option is supported by this fix to add the contribution computed by the external program to both
the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands.
The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial yes.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the potential energy
discussed above. The scalar stored by this fix is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command.

Note: If you want the fictitious potential energy associated with the added forces to be included in the total potential
energy of the system (the quantity being minimized), you MUST not disable the fix_modify energy option for this fix.

17.52.5 Restrictions

none

17.52.6 Related commands

none

17.52.7 Default

none

17.53 fix ffl command

17.53.1 Syntax

fix ID id-group ffl tau Tstart Tstop seed [flip-type]

• ID, group-ID are documented in fix command

• ffl = style name of this fix command
• tau = thermostat parameter (positive real)

1156 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• Tstart, Tstop = temperature ramp during the run

• seed = random number seed to use for generating noise (positive integer)
• one more value may be appended

flip-type = determines the flipping type, can be chosen between rescale - no_flip -
,→ hard - soft, if no flip type is given, rescale will be chosen by default

17.53.2 Examples

fix 3 boundary ffl 10 300 300 31415

fix 1 all ffl 100 500 500 9265 soft

17.53.3 Description

Apply a Fast-Forward Langevin Equation (FFL) thermostat as described in (Hijazi). Contrary to fix langevin, this fix
performs both thermostatting and evolution of the Hamiltonian equations of motion, so it should not be used together
with fix nve – at least not on the same atom groups.
The time-evolution of a single particle undergoing Langevin dynamics is described by the equations

dq p
= ,
dt m
dp
= −γp + W + F,
dt
where F is the physical force, γ is the friction coefficient, and W is a Gaussian random force.
The friction coefficient is the inverse of the thermostat parameter : γ = 1/τ , with τ the thermostat parameter tau. The
thermostat parameter is given in the time units, γ is in inverse time units.
Equilibrium sampling a temperature T is obtained by specifying the target value as the Tstart and Tstop arguments, so
that the internal constants depending on the temperature are computed automatically.
The random number seed must be a positive integer. A Marsaglia random number generator is used. Each processor
uses the input seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the
system will not be identical on two runs on different numbers of processors.
The flipping type flip-type can be chosen between 4 types described in (Hijazi). The flipping operation occurs during
the thermostatting step and it flips the momenta of the atoms. If no_flip is chosen, no flip will be executed and the
integration will be the same as a standard Langevin thermostat (Bussi). The other flipping types are : rescale - hard -
soft.

17.53.4 Restart, fix_modify, output, run start/stop, minimize info

The instantaneous values of the extended variables are written to binary restart files. Because the state of the random
number generator is not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation
continues on the same as if no restart had taken place. However, in a statistical sense, a restarted simulation should
produce the same behavior. Note however that you should use a different seed each time you restart, otherwise the
same sequence of random numbers will be used each time, which might lead to stochastic synchronization and subtle
artifacts in the sampling.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.

17.53. fix ffl command 1157

LAMMPS Documentation, Release stable 29Sep2021

This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.53.5 Restrictions

In order to perform constant-pressure simulations please use fix press/berendsen, rather than fix npt, to avoid duplicate
integration of the equations of motion.
This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.53.6 Related commands

fix nvt, fix temp/rescale, fix viscous, fix nvt, pair_style dpd/tstat, fix gld, fix gle

(Hijazi) M. Hijazi, D. M. Wilkins, M. Ceriotti, J. Chem. Phys. 148, 184109 (2018)

(Bussi) G. Bussi, M. Parrinello, Phs. Rev. E 75, 056707 (2007)

17.54 fix filter/corotate command

17.54.1 Syntax

fix ID group-ID filter/corotate keyword value ...

• ID, group-ID are documented in fix command

• one or more constraint/value pairs are appended
• constraint = b or a or t or m
b values = one or more bond types
a values = one or more angle types
t values = one or more atom types
m value = one or more mass values

17.54.2 Examples

timestep 8
run_style respa 3 2 8 bond 1 pair 2 kspace 3
fix cor all filter/corotate m 1.0

fix cor all filter/corotate b 4 19 a 3 5 2

1158 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.54.3 Description

This fix implements a corotational filter for a mollified impulse method. In biomolecular simulations, it allows the
usage of larger timesteps for long-range electrostatic interactions. For details, see (Fath).
When using run_style respa for a biomolecular simulation with high-frequency covalent bonds, the outer time-step
is restricted to below ~ 4fs due to resonance problems. This fix filters the outer stage of the respa and thus a larger
(outer) time-step can be used. Since in large biomolecular simulations the computation of the long-range electrostatic
contributions poses a major bottleneck, this can significantly accelerate the simulation.
The filter computes a cluster decomposition of the molecular structure following the criteria indicated by the options
a, b, t and m. This process is similar to the approach in fix shake, however, the clusters are not kept constrained.
Instead, the position is slightly modified only for the computation of long-range forces. A good cluster decomposition
constitutes in building clusters which contain the fastest covalent bonds inside clusters.
If the clusters are chosen suitably, the run_style respa is stable for outer timesteps of at least 8fs.

17.54.4 Restart, fix_modify, output, run start/stop, minimize info

No information about these fixes is written to binary restart files. None of the fix_modify options are relevant to these
fixes. No global or per-atom quantities are stored by these fixes for access by various output commands. No parameter
of these fixes can be used with the start/stop keywords of the run command. These fixes are not invoked during energy
minimization.

17.54.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
Currently, it does not support molecule templates.

17.54.6 Related commands

17.54.7 Default

none

(Fath) Fath, Hochbruck, Singh, J Comp Phys, 333, 180-198 (2017).

17.55 fix flow/gauss command

17.55.1 Syntax

fix ID group-ID flow/gauss xflag yflag zflag keyword

• ID, group-ID are documented in fix command

• flow/gauss = style name of this fix command

17.55. fix flow/gauss command 1159

LAMMPS Documentation, Release stable 29Sep2021

• xflag,yflag,zflag = 0 or 1

0 = do not conserve current in this dimension

1 = conserve current in this dimension

• zero or more keyword/value pairs may be appended

• keyword = energy
energy value = no or yes
no = do not compute work done by this fix
yes = compute work done by this fix

17.55.2 Examples

fix GD fluid flow/gauss 1 0 0

fix GD fluid flow/gauss 1 1 1 energy yes

17.55.3 Description

This fix implements the Gaussian dynamics (GD) method to simulate a system at constant mass flux (Strong). GD is a
nonequilibrium molecular dynamics simulation method that can be used to study fluid flows through pores, pipes, and
channels. In its original implementation GD was used to compute the pressure required to achieve a fixed mass flux
through an opening. The flux can be conserved in any combination of the directions, x, y, or z, using xflag,yflag,zflag.
This fix does not initialize a net flux through a system, it only conserves the center-of-mass momentum that is present
when the fix is declared in the input script. Use the velocity command to generate an initial center-of-mass momentum.
GD applies an external fluctuating gravitational field that acts as a driving force to keep the system away from equilib-
rium. To maintain steady state, a profile-unbiased thermostat must be implemented to dissipate the heat that is added
by the driving force. Compute temp/profile can be used to implement a profile-unbiased thermostat.
A common use of this fix is to compute a pressure drop across a pipe, pore, or membrane. The pressure profile can
be computed in LAMMPS with compute stress/atom and fix ave/chunk, or with the hardy method in fix atc. Note that
the simple compute stress/atom method is only accurate away from inhomogeneities in the fluid, such as fixed wall
atoms. Further, the computed pressure profile must be corrected for the acceleration applied by GD before computing
a pressure drop or comparing it to other methods, such as the pump method (Zhu). The pressure correction is discussed
and described in (Strong).
For a complete example including the considerations discussed above, see the examples/PACKAGES/flow_gauss di-
rectory.

Note: Only the flux of the atoms in group-ID will be conserved. If the velocities of the group-ID atoms are coupled
to the velocities of other atoms in the simulation, the flux will not be conserved. For example, in a simulation with
fluid atoms and harmonically constrained wall atoms, if a single thermostat is applied to group all, the fluid atom
velocities will be coupled to the wall atom velocities, and the flux will not be conserved. This issue can be avoided by
thermostatting the fluid and wall groups separately.

Adding an acceleration to atoms does work on the system. This added energy can be optionally subtracted from the
potential energy for the thermodynamic output (see below) to check that the timestep is small enough to conserve
energy. Since the applied acceleration is fluctuating in time, the work cannot be computed from a potential. As a
result, computing the work is slightly more computationally expensive than usual, so it is not performed by default. To
invoke the work calculation, use the energy keyword. The fix_modify energy option also invokes the work calculation,

1160 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

and overrides an energy no setting here. If neither energy yes or fix_modify energy yes are set, the global scalar computed
by the fix will return zero.

Note: In order to check energy conservation, any other fixes that do work on the system must have fix_modify energy
yes set as well. This includes thermostat fixes and any constraints that hold the positions of wall atoms fixed, such as
fix spring/self .

If this fix is used in a simulation with the rRESPA integrator, the applied acceleration must be computed and applied
at the same rRESPA level as the interactions between the flowing fluid and the obstacle. The rRESPA level at which
the acceleration is applied can be changed using the fix_modify respa option discussed below. If the flowing fluid and
the obstacle interact through multiple interactions that are computed at different rRESPA levels, then there must be
a separate flow/gauss fix for each level. For example, if the flowing fluid and obstacle interact through pairwise and
long-range Coulomb interactions, which are computed at rRESPA levels 3 and 4, respectively, then there must be two
separate flow/gauss fixes, one that specifies fix_modify respa 3 and one with fix_modify respa 4.

17.55.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy added by the fix to the global potential
energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify energy no.
The fix_modify respa option is supported by this fix. This allows the user to set at which level of the rRESPA integrator
the fix computes and adds the external acceleration. Default is the outermost level.
This fix computes a global scalar and a global 3-vector of forces, which can be accessed by various output commands.
The scalar is the negative of the work done on the system, see the discussion above. It is only calculated if the energy
keyword is enabled or fix_modify energy yes is set.
The vector is the total force that this fix applied to the group of atoms on the current timestep. The scalar and vector
values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.55.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.55.6 Related commands

fix addforce, compute temp/profile, velocity

17.55. fix flow/gauss command 1161

LAMMPS Documentation, Release stable 29Sep2021

17.55.7 Default

The option default for the energy keyword is energy = no.

(Strong) Strong and Eaves, J. Phys. Chem. B 121, 189 (2017).

(Evans) Evans and Morriss, Phys. Rev. Lett. 56, 2172 (1986).
(Zhu) Zhu, Tajkhorshid, and Schulten, Biophys. J. 83, 154 (2002).

17.56 fix freeze command

Accelerator Variants: freeze/kk

17.56.1 Syntax

fix ID group-ID freeze

• ID, group-ID are documented in fix command

• freeze = style name of this fix command

17.56.2 Examples

fix 2 bottom freeze

17.56.3 Description

Zero out the force and torque on a granular particle. This is useful for preventing certain particles from moving in a
simulation. The granular pair styles also detect if this fix has been defined and compute interactions between frozen
and non-frozen particles appropriately, as if the frozen particle has infinite mass. A similar functionality for normal
(point) particles can be obtained using fix setforce.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

1162 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.56.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global 3-vector of forces, which can be accessed by various output commands. This is the total
force on the group of atoms before the forces on individual atoms are changed by the fix. The vector values calculated
by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.56.5 Restrictions

This fix is part of the GRANULAR package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
There can only be a single freeze fix defined. This is because other the granular pair styles treat frozen particles
differently and need to be able to reference a single group to which this fix is applied.

17.56.6 Related commands

atom_style sphere, fix setforce

17.56.7 Default

none

17.57 fix gcmc command

17.57.1 Syntax

fix ID group-ID gcmc N X M type seed T mu displace keyword values ...

• ID, group-ID are documented in fix command

• gcmc = style name of this fix command
• N = invoke this fix every N steps
• X = average number of GCMC exchanges to attempt every N steps
• M = average number of MC moves to attempt every N steps
• type = atom type for inserted atoms (must be 0 if mol keyword used)
• seed = random # seed (positive integer)
• T = temperature of the ideal gas reservoir (temperature units)
• mu = chemical potential of the ideal gas reservoir (energy units)
• displace = maximum Monte Carlo translation distance (length units)
• zero or more keyword/value pairs may be appended to args

17.57. fix gcmc command 1163

LAMMPS Documentation, Release stable 29Sep2021

keyword = mol, region, maxangle, pressure, fugacity_coeff , full_energy, charge,␣

,→group, grouptype, intra_energy, tfac_insert, or overlap_cutoff

mol value = template-ID

template-ID = ID of molecule template specified in a separate molecule command
mcmoves values = Patomtrans Pmoltrans Pmolrotate
Patomtrans = proportion of atom translation MC moves
Pmoltrans = proportion of molecule translation MC moves
Pmolrotate = proportion of molecule rotation MC moves
rigid value = fix-ID
fix-ID = ID of fix rigid/small command
shake value = fix-ID
fix-ID = ID of fix shake command
region value = region-ID
region-ID = ID of region where GCMC exchanges and MC moves are allowed
maxangle value = maximum molecular rotation angle (degrees)
pressure value = pressure of the gas reservoir (pressure units)
fugacity_coeff value = fugacity coefficient of the gas reservoir (unitless)
full_energy = compute the entire system energy when performing GCMC exchanges and␣
,→MC moves

charge value = charge of inserted atoms (charge units)

group value = group-ID
group-ID = group-ID for inserted atoms (string)
grouptype values = type group-ID
type = atom type (int)
group-ID = group-ID for inserted atoms (string)
intra_energy value = intramolecular energy (energy units)
tfac_insert value = scale up/down temperature of inserted atoms (unitless)
overlap_cutoff value = maximum pair distance for overlap rejection (distance␣
,→units)

max value = Maximum number of molecules allowed in the system

min value = Minimum number of molecules allowed in the system

17.57.2 Examples

fix 2 gas gcmc 10 1000 1000 2 29494 298.0 -0.5 0.01

fix 3 water gcmc 10 100 100 0 3456543 3.0 -2.5 0.1 mol my_one_water maxangle 180 full_
,→energy

fix 4 my_gas gcmc 1 10 10 1 123456543 300.0 -12.5 1.0 region disk

17.57.3 Description

This fix performs grand canonical Monte Carlo (GCMC) exchanges of atoms or molecules with an imaginary ideal
gas reservoir at the specified T and chemical potential (mu) as discussed in (Frenkel). It also attempts Monte Carlo
(MC) moves (translations and molecule rotations) within the simulation cell or region. If used with the fix nvt com-
mand, simulations in the grand canonical ensemble (muVT, constant chemical potential, constant volume, and constant
temperature) can be performed. Specific uses include computing isotherms in microporous materials, or computing
vapor-liquid coexistence curves.
Every N timesteps the fix attempts both GCMC exchanges (insertions or deletions) and MC moves of gas atoms or
molecules. On those timesteps, the average number of attempted GCMC exchanges is X, while the average number of
attempted MC moves is M. For GCMC exchanges of either molecular or atomic gasses, these exchanges can be either
deletions or insertions, with equal probability.

1164 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The possible choices for MC moves are translation of an atom, translation of a molecule, and rotation of a molecule.
The relative amounts of each are determined by the optional mcmoves keyword (see below). The default behavior is
as follows. If the mol keyword is used, only molecule translations and molecule rotations are performed with equal
probability. Conversely, if the mol keyword is not used, only atom translations are performed. M should typically
be chosen to be approximately equal to the expected number of gas atoms or molecules of the given type within the
simulation cell or region, which will result in roughly one MC move per atom or molecule per MC cycle.
All inserted particles are always added to two groups: the default group “all” and the fix group specified in the fix
command. In addition, particles are also added to any groups specified by the group and grouptype keywords. If inserted
particles are individual atoms, they are assigned the atom type given by the type argument. If they are molecules, the
type argument has no effect and must be set to zero. Instead, the type of each atom in the inserted molecule is specified
in the file read by the molecule command.

Note: Care should be taken to apply fix gcmc only to a group that contains only those atoms and molecules that you
wish to manipulate using Monte Carlo. Hence it is generally not a good idea to specify the default group “all” in the
fix command, although it is allowed.

This fix cannot be used to perform GCMC insertions of gas atoms or molecules other than the exchanged type, but
GCMC deletions, and MC translations, and rotations can be performed on any atom/molecule in the fix group. All
atoms in the simulation cell can be moved using regular time integration translations, e.g. via fix nvt, resulting in
a hybrid GCMC+MD simulation. A smaller-than-usual timestep size may be needed when running such a hybrid
simulation, especially if the inserted molecules are not well equilibrated.
This command may optionally use the region keyword to define an exchange and move volume. The specified region
must have been previously defined with a region command. It must be defined with side = in. Insertion attempts occur
only within the specified region. For non-rectangular regions, random trial points are generated within the rectangular
bounding box until a point is found that lies inside the region. If no valid point is generated after 1000 trials, no insertion
is performed, but it is counted as an attempted insertion. Move and deletion attempt candidates are selected from gas
atoms or molecules within the region. If there are no candidates, no move or deletion is performed, but it is counted
as an attempt move or deletion. If an attempted move places the atom or molecule center-of-mass outside the specified
region, a new attempted move is generated. This process is repeated until the atom or molecule center-of-mass is inside
the specified region.
If used with fix nvt, the temperature of the imaginary reservoir, T, should be set to be equivalent to the target temperature
used in fix nvt. Otherwise, the imaginary reservoir will not be in thermal equilibrium with the simulation cell. Also, it
is important that the temperature used by fix nvt be dynamic/dof, which can be achieved as follows:

compute mdtemp mdatoms temp

compute_modify mdtemp dynamic/dof yes
fix mdnvt mdatoms nvt temp 300.0 300.0 10.0
fix_modify mdnvt temp mdtemp

Note that neighbor lists are re-built every timestep that this fix is invoked, so you should not set N to be too small.
However, periodic rebuilds are necessary in order to avoid dangerous rebuilds and missed interactions. Specifically,
avoid performing so many MC translations per timestep that atoms can move beyond the neighbor list skin distance.
See the neighbor command for details.
When an atom or molecule is to be inserted, its coordinates are chosen at a random position within the current simulation
cell or region, and new atom velocities are randomly chosen from the specified temperature distribution given by T.
The effective temperature for new atom velocities can be increased or decreased using the optional keyword tfac_insert
(see below). Relative coordinates for atoms in a molecule are taken from the template molecule provided by the user.
The center of mass of the molecule is placed at the insertion point. The orientation of the molecule is chosen at random
by rotating about this point.
Individual atoms are inserted, unless the mol keyword is used. It specifies a template-ID previously defined using the
molecule command, which reads a file that defines the molecule. The coordinates, atom types, charges, etc., as well as

17.57. fix gcmc command 1165

LAMMPS Documentation, Release stable 29Sep2021

any bonding and special neighbor information for the molecule can be specified in the molecule file. See the molecule
command for details. The only settings required to be in this file are the coordinates and types of atoms in the molecule.
When not using the mol keyword, you should ensure you do not delete atoms that are bonded to other atoms, or
LAMMPS will soon generate an error when it tries to find bonded neighbors. LAMMPS will warn you if any of the
atoms eligible for deletion have a non-zero molecule ID, but does not check for this at the time of deletion.
If you wish to insert molecules using the mol keyword that will be treated as rigid bodies, use the rigid keyword,
specifying as its value the ID of a separate fix rigid/small command which also appears in your input script.

Note: If you wish the new rigid molecules (and other rigid molecules) to be thermostatted correctly via fix
rigid/small/nvt or fix rigid/small/npt, then you need to use the “fix_modify dynamic/dof yes” command for the rigid
fix. This is to inform that fix that the molecule count will vary dynamically.

If you wish to insert molecules via the mol keyword, that will have their bonds or angles constrained via SHAKE, use
the shake keyword, specifying as its value the ID of a separate fix shake command which also appears in your input
script.
Optionally, users may specify the relative amounts of different MC moves using the mcmoves keyword. The values
Patomtrans, Pmoltrans, Pmolrotate specify the average proportion of atom translations, molecule translations, and
molecule rotations, respectively. The values must be non-negative integers or real numbers, with at least one non-
zero value. For example, (10,30,0) would result in 25% of the MC moves being atomic translations, 75% molecular
translations, and no molecular rotations.
Optionally, users may specify the maximum rotation angle for molecular rotations using the maxangle keyword and
specifying the angle in degrees. Rotations are performed by generating a random point on the unit sphere and a random
rotation angle on the range [0,maxangle). The molecule is then rotated by that angle about an axis passing through
the molecule center of mass. The axis is parallel to the unit vector defined by the point on the unit sphere. The same
procedure is used for randomly rotating molecules when they are inserted, except that the maximum angle is 360
degrees.
Note that fix gcmc does not use configurational bias MC or any other kind of sampling of intramolecular degrees of free-
dom. Inserted molecules can have different orientations, but they will all have the same intramolecular configuration,
which was specified in the molecule command input.
For atomic gasses, inserted atoms have the specified atom type, but deleted atoms are any atoms that have been inserted
or that already belong to the fix group. For molecular gasses, exchanged molecules use the same atom types as in the
template molecule supplied by the user. In both cases, exchanged atoms/molecules are assigned to two groups: the
default group “all” and the fix group (which can also be “all”).
The chemical potential is a user-specified input parameter defined as:

µ = µid + µex

The second term mu_ex is the excess chemical potential due to energetic interactions and is formally zero for the
fictitious gas reservoir but is non-zero for interacting systems. So, while the chemical potential of the reservoir and the
simulation cell are equal, mu_ex is not, and as a result, the densities of the two are generally quite different. The first
term mu_id is the ideal gas contribution to the chemical potential. mu_id can be related to the density or pressure of
the fictitious gas reservoir by:

µid =kT ln ρΛ3

φP Λ3
=kT ln
kT
where k is Boltzman’s constant, T is the user-specified temperature, ρ is the number density, P is the pressure, and φ is
the fugacity coefficient. The constant Λ is required for dimensional consistency. For all unit styles except lj it is defined

1166 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

as the thermal de Broglie wavelength

r
h2
Λ=
2πmkT
where h is Planck’s constant, and m is the mass of the exchanged atom or molecule. For unit style lj, Λ is simply set to
unity. Note that prior to March 2017, Λ for unit style lj was calculated using the above formula with h set to the rather
specific value of 0.18292026. Chemical potential under the old definition can be converted to an equivalent value under
the new definition by subtracting 3kT ln(Λold ).
As an alternative to specifying mu directly, the ideal gas reservoir can be defined by its pressure P using the pres-
sure keyword, in which case the user-specified chemical potential is ignored. The user may also specify the fugacity
coefficient φ using the fugacity_coeff keyword, which defaults to unity.
The full_energy option means that the fix calculates the total potential energy of the entire simulated system, instead
of just the energy of the part that is changed. The total system energy before and after the proposed GCMC exchange
or MC move is then used in the Metropolis criterion to determine whether or not to accept the proposed change. By
default, this option is off, in which case only partial energies are computed to determine the energy difference due to
the proposed change.
The full_energy option is needed for systems with complicated potential energy calculations, including the following:
• long-range electrostatics (kspace)
• many-body pair styles
• hybrid pair styles
• eam pair styles
• tail corrections
• need to include potential energy contributions from other fixes
In these cases, LAMMPS will automatically apply the full_energy keyword and issue a warning message.
When the mol keyword is used, the full_energy option also includes the intramolecular energy of inserted and deleted
molecules, whereas this energy is not included when full_energy is not used. If this is not desired, the intra_energy
keyword can be used to define an amount of energy that is subtracted from the final energy when a molecule is inserted,
and subtracted from the initial energy when a molecule is deleted. For molecules that have a non-zero intramolecular
energy, this will ensure roughly the same behavior whether or not the full_energy option is used.
Inserted atoms and molecules are assigned random velocities based on the specified temperature T. Because the relative
velocity of all atoms in the molecule is zero, this may result in inserted molecules that are systematically too cold. In
addition, the intramolecular potential energy of the inserted molecule may cause the kinetic energy of the molecule
to quickly increase or decrease after insertion. The tfac_insert keyword allows the user to counteract these effects by
changing the temperature used to assign velocities to inserted atoms and molecules by a constant factor. For a particular
application, some experimentation may be required to find a value of tfac_insert that results in inserted molecules that
equilibrate quickly to the correct temperature.
Some fixes have an associated potential energy. Examples of such fixes include: efield, gravity, addforce, langevin,
restrain, temp/berendsen, temp/rescale, and wall fixes. For that energy to be included in the total potential energy of
the system (the quantity used when performing GCMC exchange and MC moves), you MUST enable the fix_modify
energy option for that fix. The doc pages for individual fix commands specify if this should be done.
Use the charge option to insert atoms with a user-specified point charge. Note that doing so will cause the system
to become non-neutral. LAMMPS issues a warning when using long-range electrostatics (kspace) with non-neutral
systems. See the compute group/group documentation for more details about simulating non-neutral systems with
kspace on.
Use of this fix typically will cause the number of atoms to fluctuate, therefore, you will want to use the compute_modify
dynamic/dof command to insure that the current number of atoms is used as a normalizing factor each time temperature
is computed. A simple example of this is:

17.57. fix gcmc command 1167

LAMMPS Documentation, Release stable 29Sep2021

compute_modify thermo_temp dynamic yes

A more complicated example is listed earlier on this page in the context of NVT dynamics.

Note: If the density of the cell is initially very small or zero, and increases to a much larger density after a period
of equilibration, then certain quantities that are only calculated once at the start (kspace parameters) may no longer be
accurate. The solution is to start a new simulation after the equilibrium density has been reached.

With some pair_styles, such as Buckingham, Born-Mayer-Huggins and ReaxFF, two atoms placed close to each other
may have an arbitrary large, negative potential energy due to the functional form of the potential. While these unphys-
ical configurations are inaccessible to typical dynamical trajectories, they can be generated by Monte Carlo moves.
The overlap_cutoff keyword suppresses these moves by effectively assigning an infinite positive energy to all new
configurations that place any pair of atoms closer than the specified overlap cutoff distance.
The max and min keywords allow for the restriction of the number of atoms in the simulation. They automatically
reject all insertion or deletion moves that would take the system beyond the set boundaries. Should the system already
be beyond the boundary, only moves that bring the system closer to the bounds may be accepted.
The group keyword adds all inserted atoms to the group of the group-ID value. The grouptype keyword adds all inserted
atoms of the specified type to the group of the group-ID value.

17.57.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the fix to binary restart files. This includes information about the random number generator
seed, the next timestep for MC exchanges, the number of MC step attempts and successes etc. See the read_restart
command for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix
continues in an uninterrupted fashion.

Note: For this to work correctly, the timestep must not be changed after reading the restart with reset_timestep. The
fix will try to detect it and stop with an error.

None of the fix_modify options are relevant to this fix.

This fix computes a global vector of length 8, which can be accessed by various output commands. The vector values
are the following global cumulative quantities:
• 1 = translation attempts
• 2 = translation successes
• 3 = insertion attempts
• 4 = insertion successes
• 5 = deletion attempts
• 6 = deletion successes
• 7 = rotation attempts
• 8 = rotation successes
The vector values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

1168 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.57.5 Restrictions

This fix is part of the MC package. It is only enabled if LAMMPS was built with that package. See the Build package
doc page for more info.
Do not set “neigh_modify once yes” or else this fix will never be called. Reneighboring is required.
Can be run in parallel, but aspects of the GCMC part will not scale well in parallel. Only usable for 3D simulations.
When using fix gcmc in combination with fix shake or fix rigid, only GCMC exchange moves are supported, so the
argument M must be zero.
When using fix gcmc in combination with fix rigid, deletion of the last remaining molecule is not allowed for technical
reasons, and so the molecule count will never drop below 1, regardless of the specified chemical potential.
Note that very lengthy simulations involving insertions/deletions of billions of gas molecules may run out of atom or
molecule IDs and trigger an error, so it is better to run multiple shorter-duration simulations. Likewise, very large
molecules have not been tested and may turn out to be problematic.
Use of multiple fix gcmc commands in the same input script can be problematic if using a template molecule. The
issue is that the user-referenced template molecule in the second fix gcmc command may no longer exist since it might
have been deleted by the first fix gcmc command. An existing template molecule will need to be referenced by the user
for each subsequent fix gcmc command.

17.57.6 Related commands

fix atom/swap, fix nvt, neighbor, fix deposit, fix evaporate, delete_atoms

17.57.7 Default

The option defaults are mol = no, maxangle = 10, overlap_cutoff = 0.0, fugacity_coeff = 1.0, intra_energy = 0.0,
tfac_insert = 1.0. (Patomtrans, Pmoltrans, Pmolrotate) = (1, 0, 0) for mol = no and (0, 1, 1) for mol = yes. full_energy
= no, except for the situations where full_energy is required, as listed above.

(Frenkel) Frenkel and Smit, Understanding Molecular Simulation, Academic Press, London, 2002.

17.58 fix gld command

17.58.1 Syntax

fix ID group-ID gld Tstart Tstop N_k seed series c_1 tau_1 ... c_N_k tau_N_k keyword␣
,→values ...

• ID, group-ID are documented in fix command

• gld = style name of this fix command
• Tstart,Tstop = desired temperature at start/end of run (temperature units)
• N_k = number of terms in the Prony series representation of the memory kernel
• seed = random number seed to use for white noise (positive integer)
• series = pprony is presently the only available option

17.58. fix gld command 1169

LAMMPS Documentation, Release stable 29Sep2021

• c_k = the weight of the kth term in the Prony series (mass per time units)
• tau_k = the time constant of the kth term in the Prony series (time units)
• zero or more keyword/value pairs may be appended
keyword = frozen or zero
frozen value = no or yes
no = initialize extended variables using values drawn from equilibrium␣
,→distribution at Tstart

yes = initialize extended variables to zero (i.e., from equilibrium␣

,→distribution at zero temperature)

zero value = no or yes

no = do not set total random force to zero
yes = set total random force to zero

17.58.2 Examples

fix 1 all gld 1.0 1.0 2 82885 pprony 0.5 1.0 1.0 2.0 frozen yes zero yes
fix 3 rouse gld 7.355 7.355 4 48823 pprony 107.1 0.02415 186.0 0.04294 428.6 0.09661␣
,→1714 0.38643

17.58.3 Description

Applies Generalized Langevin Dynamics to a group of atoms, as described in (Baczewski). This is intended to model
the effect of an implicit solvent with a temporally non-local dissipative force and a colored Gaussian random force,
consistent with the Fluctuation-Dissipation Theorem. The functional form of the memory kernel associated with the
temporally non-local force is constrained to be a Prony series.

Note: While this fix bears many similarities to fix langevin, it has one significant difference. Namely, fix gld performs
time integration, whereas fix langevin does NOT. To this end, the specification of another fix to perform time integration,
such as fix nve, is NOT necessary.

With this fix active, the force on the jth atom is given as
Zt
Fj (t) =FC
j (t) − Γj (t − s)vj (s) ds + FR
j (t)
0
Nk
X ck
Γj (t − s) = e−(t−s)/τk
τk
k=1

j (t), Fj (s)i =kB T Γj (t − s)

hFR R

Here, the first term is representative of all conservative (pairwise, bonded, etc) forces external to this fix, the second is
the temporally non-local dissipative force given as a Prony series, and the third is the colored Gaussian random force.
The Prony series form of the memory kernel is chosen to enable an extended variable formalism, with a number of
exemplary mathematical features discussed in (Baczewski). In particular, 3Nk extended variables are added to each
atom, which effect the action of the memory kernel without having to explicitly evaluate the integral over time in the
second term of the force. This also has the benefit of requiring the generation of uncorrelated random forces, rather
than correlated random forces as specified in the third term of the force.
Presently, the Prony series coefficients are limited to being greater than or equal to zero, and the time constants are
limited to being greater than zero. To this end, the value of series MUST be set to pprony, for now. Future updates will

1170 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

allow for negative coefficients and other representations of the memory kernel. It is with these updates in mind that the
series option was included.
The units of the Prony series coefficients are chosen to be mass per time to ensure that the numerical integration scheme
stably approaches the Newtonian and Langevin limits. Details of these limits, and the associated numerical concerns
are discussed in (Baczewski).
The desired temperature at each timestep is ramped from Tstart to Tstop over the course of the next run.
The random # seed must be a positive integer. A Marsaglia random number generator is used. Each processor uses the
input seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the system
will not be identical on two runs on different numbers of processors.

The keyword/value option pairs are used in the following ways.

The keyword frozen can be used to specify how the extended variables associated with the GLD memory kernel are
initialized. Specifying no (the default), the initial values are drawn at random from an equilibrium distribution at Tstart,
consistent with the Fluctuation-Dissipation Theorem. Specifying yes, initializes the extended variables to zero.
The keyword zero can be used to eliminate drift due to the thermostat. Because the random forces on different atoms are
independent, they do not sum exactly to zero. As a result, this fix applies a small random force to the entire system, and
the center-of-mass of the system undergoes a slow random walk. If the keyword zero is set to yes, the total random force
is set exactly to zero by subtracting off an equal part of it from each atom in the group. As a result, the center-of-mass
of a system with zero initial momentum will not drift over time.

17.58.4 Restart, fix_modify, output, run start/stop, minimize info

The instantaneous values of the extended variables are written to binary restart files. Because the state of the random
number generator is not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation
continues on the same as if no restart had taken place. However, in a statistical sense, a restarted simulation should
produce the same behavior.
None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access
by various output commands.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.58.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.58. fix gld command 1171

LAMMPS Documentation, Release stable 29Sep2021

17.58.6 Related commands

fix langevin, fix viscous, pair_style dpd/tstat

17.58.7 Default

The option defaults are frozen = no, zero = no.

(Baczewski) A.D. Baczewski and S.D. Bond, J. Chem. Phys. 139, 044107 (2013).

17.59 fix gle command

17.59.1 Syntax

fix ID id-group gle Ns Tstart Tstop seed Amatrix [noneq Cmatrix] [every stride]

• ID, group-ID are documented in fix command

• gle = style name of this fix command
• Ns = number of additional fictitious momenta
• Tstart, Tstop = temperature ramp during the run
• Amatrix = file to read the drift matrix A from
• seed = random number seed to use for generating noise (positive integer)
• zero or more keyword/value pairs may be appended
keyword = noneq or every
noneq Cmatrix = file to read the non-equilibrium covariance matrix from
every stride = apply the GLE once every time steps. Reduces the accuracy
of the integration of the GLE, but has *no effect* on the accuracy of␣
,→equilibrium

sampling. It might change sampling properties when used together with noneq.

17.59.2 Examples

fix 3 boundary gle 6 300 300 31415 smart.A

fix 1 all gle 6 300 300 31415 qt-300k.A noneq qt-300k.C

1172 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.59.3 Description

Apply a Generalized Langevin Equation (GLE) thermostat as described in (Ceriotti). The formalism allows one to
obtain a number of different effects ranging from efficient sampling of all vibrational modes in the system to inexpensive
(approximate) modelling of nuclear quantum effects. Contrary to fix langevin, this fix performs both thermostatting
and evolution of the Hamiltonian equations of motion, so it should not be used together with fix nve – at least not on
the same atom groups.
Each degree of freedom in the thermostatted group is supplemented with Ns additional degrees of freedom s, and the
equations of motion become

dq/dt=p/m
d(p,s)/dt=(F,0) - A(p,s) + B dW/dt

where F is the physical force, A is the drift matrix (that generalizes the friction in Langevin dynamics), B is the diffusion
term and dW/dt un-correlated Gaussian random forces. The A matrix couples the physical (q,p) dynamics with that
of the additional degrees of freedom, and makes it possible to obtain effectively a history-dependent noise and friction
kernel.
The drift matrix should be given as an external file Afile, as a (Ns+1 x Ns+1) matrix in inverse time units. Matrices
that are optimal for a given application and the system of choice can be obtained from (GLE4MD).
Equilibrium sampling a temperature T is obtained by specifying the target value as the Tstart and Tstop arguments, so
that the diffusion matrix that gives canonical sampling for a given A is computed automatically. However, the GLE
framework also allow for non-equilibrium sampling, that can be used for instance to model inexpensively zero-point
energy effects (Ceriotti2). This is achieved specifying the noneq keyword followed by the name of the file that contains
the static covariance matrix for the non-equilibrium dynamics. Please note, that the covariance matrix is expected to
be given in temperature units.
Since integrating GLE dynamics can be costly when used together with simple potentials, one can use the every optional
keyword to apply the Langevin terms only once every several MD steps, in a multiple time-step fashion. This should be
used with care when doing non-equilibrium sampling, but should have no effect on equilibrium averages when using
canonical sampling.
The random number seed must be a positive integer. A Marsaglia random number generator is used. Each processor
uses the input seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the
system will not be identical on two runs on different numbers of processors.
Note also that the Generalized Langevin Dynamics scheme that is implemented by the fix gld scheme is closely related
to the present one. In fact, it should be always possible to cast the Prony series form of the memory kernel used by
GLD into an appropriate input matrix for fix gle. While the GLE scheme is more general, the form used by fix gld can
be more directly related to the representation of an implicit solvent environment.

17.59.4 Restart, fix_modify, output, run start/stop, minimize info

The instantaneous values of the extended variables are written to binary restart files. Because the state of the random
number generator is not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation
continues on the same as if no restart had taken place. However, in a statistical sense, a restarted simulation should
produce the same behavior. Note however that you should use a different seed each time you restart, otherwise the
same sequence of random numbers will be used each time, which might lead to stochastic synchronization and subtle
artifacts in the sampling.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.

17.59. fix gle command 1173

LAMMPS Documentation, Release stable 29Sep2021

This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.59.5 Restrictions

The GLE thermostat in its current implementation should not be used with rigid bodies, SHAKE or RATTLE. It is
expected that all the thermostatted degrees of freedom are fully flexible, and the sampled ensemble will not be correct
otherwise.
In order to perform constant-pressure simulations please use fix press/berendsen, rather than fix npt, to avoid duplicate
integration of the equations of motion.
This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.59.6 Related commands

fix nvt, fix temp/rescale, fix viscous, fix nvt, pair_style dpd/tstat, fix gld

(Ceriotti) Ceriotti, Bussi and Parrinello, J Chem Theory Comput 6, 1170-80 (2010)
(GLE4MD) http://gle4md.org/
(Ceriotti2) Ceriotti, Bussi and Parrinello, Phys Rev Lett 103, 030603 (2009)

17.60 fix gravity command

Accelerator Variants: gravity/omp, gravity/kk

17.60.1 Syntax

fix ID group gravity magnitude style args

• ID, group are documented in fix command

• gravity = style name of this fix command
• magnitude = size of acceleration (force/mass units)
• magnitude can be a variable (see below)
• style = chute or spherical or gradient or vector
chute args = angle
angle = angle in +x away from -z or -y axis in 3d/2d (in degrees)
angle can be a variable (see below)
spherical args = phi theta
phi = azimuthal angle from +x axis (in degrees)
theta = angle from +z or +y axis in 3d/2d (in degrees)
phi or theta can be a variable (see below)
vector args = x y z

1174 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

x y z = vector direction to apply the acceleration

x or y or z can be a variable (see below)

17.60.2 Examples

fix 1 all gravity 1.0 chute 24.0

fix 1 all gravity v_increase chute 24.0
fix 1 all gravity 1.0 spherical 0.0 -180.0
fix 1 all gravity 10.0 spherical v_phi v_theta
fix 1 all gravity 100.0 vector 1 1 0

17.60.3 Description

Impose an additional acceleration on each particle in the group. This fix is typically used with granular systems to
include a “gravity” term acting on the macroscopic particles. More generally, it can represent any kind of driving field,
e.g. a pressure gradient inducing a Poiseuille flow in a fluid. Note that this fix operates differently than the fix addforce
command. The addforce fix adds the same force to each atom, independent of its mass. This command imparts the
same acceleration to each atom (force/mass).
The magnitude of the acceleration is specified in force/mass units. For granular systems (LJ units) this is typically 1.0.
See the units command for details.
Style chute is typically used for simulations of chute flow where the specified angle is the chute angle, with flow
occurring in the +x direction. For 3d systems, the tilt is away from the z axis; for 2d systems, the tilt is away from the
y axis.
Style spherical allows an arbitrary 3d direction to be specified for the acceleration vector. Phi and theta are defined
in the usual spherical coordinates. Thus for acceleration acting in the -z direction, theta would be 180.0 (or -180.0).
Theta = 90.0 and phi = -90.0 would mean acceleration acts in the -y direction. For 2d systems, phi is ignored and theta
is an angle in the xy plane where theta = 0.0 is the y-axis.
Style vector imposes an acceleration in the vector direction given by (x,y,z). Only the direction of the vector is impor-
tant; it’s length is ignored. For 2d systems, the z component is ignored.
Any of the quantities magnitude, angle, phi, theta, x, y, z which define the gravitational magnitude and direction, can
be specified as an equal-style variable. If the value is a variable, it should be specified as v_name, where name is the
variable name. In this case, the variable will be evaluated each timestep, and its value used to determine the quantity.
You should insure that the variable calculates a result in the appropriate units, e.g. force/mass or degrees.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
gravitational field.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.60. fix gravity command 1175

LAMMPS Documentation, Release stable 29Sep2021

17.60.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the gravitational potential energy of the system to the global
potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify energy no.
The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.
This fix computes a global scalar which can be accessed by various output commands. This scalar is the gravitational
potential energy of the particles in the defined field, namely mass * (g dot x) for each particles, where x and mass are
the particles position and mass, and g is the gravitational field. The scalar value calculated by this fix is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.60.5 Restrictions

none

17.60.6 Related commands

atom_style sphere, fix addforce

17.60.7 Default

none

17.61 fix grem command

17.61.1 Syntax

fix ID group-ID grem lambda eta H0 thermostat-ID

• ID, group-ID are documented in fix command

• grem = style name of this fix command
• lambda = intercept parameter of linear effective temperature function
• eta = slope parameter of linear effective temperature function
• H0 = shift parameter of linear effective temperature function
• thermostat-ID = ID of Nose-Hoover thermostat or barostat used in simulation

1176 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.61.2 Examples

fix fxgREM all grem 400 -0.01 -30000 fxnpt

thermo_modify press fxgREM_press

fix fxgREM all grem 502 -0.15 -80000 fxnvt

17.61.3 Description

This fix implements the molecular dynamics version of the generalized replica exchange method (gREM) originally
developed by (Kim), which uses non-Boltzmann ensembles to sample over first order phase transitions. The is done by
defining replicas with an enthalpy dependent effective temperature

Tef f = λ + η(H − H0 )

with η negative and steep enough to only intersect the characteristic microcanonical temperature (Ts) of the system
once, ensuring a unimodal enthalpy distribution in that replica. λ is the intercept and effects the generalized ensemble
similar to how temperature effects a Boltzmann ensemble. H0 is a reference enthalpy, and is typically set as the lowest
desired sampled enthalpy. Further explanation can be found in our recent papers (Malolepsza).
This fix requires a Nose-Hoover thermostat fix reference passed to the grem as thermostat-ID. Two distinct temperatures
exist in this generalized ensemble, the effective temperature defined above, and a kinetic temperature that controls the
velocity distribution of particles as usual. Either constant volume or constant pressure algorithms can be used.
The fix enforces a generalized ensemble in a single replica only. Typically, this ideology is combined with replica
exchange with replicas differing by λ only for simplicity, but this is not required. A multi-replica simulation can
be run within the LAMMPS environment using the temper/grem command. This utilizes LAMMPS partition mode
and requires the number of available processors be on the order of the number of desired replicas. A 100-replica
simulation would require at least 100 processors (1 per world at minimum). If many replicas are needed on a small
number of processors, multi-replica runs can be run outside of LAMMPS. An example of this can be found in exam-
ples/PACKAGES/grem and has no limit on the number of replicas per processor. However, this is very inefficient and
error prone and should be avoided if possible.
In general, defining the generalized ensembles is unique for every system. When starting a many-replica simulation
without any knowledge of the underlying microcanonical temperature, there are several tricks we have utilized to opti-
mize the process. Choosing a less-steep η yields broader distributions, requiring fewer replicas to map the microcanon-
ical temperature. While this likely struggles from the same sampling problems gREM was built to avoid, it provides
quick insight to Ts. Initially using an evenly-spaced λ distribution identifies regions where small changes in enthalpy
lead to large temperature changes. Replicas are easily added where needed.

17.61.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The thermo_modify press option is supported by this fix to add the rescaled kinetic pressure as part of thermodynamic
output.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the effective
temperature Tef f . The scalar value calculated by this fix is “intensive”.

17.61. fix grem command 1177

LAMMPS Documentation, Release stable 29Sep2021

17.61.5 Restrictions

This fix is part of the REPLICA package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.61.6 Related commands

temper/grem, fix nvt, fix npt, thermo_modify

17.61.7 Default

none

(Kim) Kim, Keyes, Straub, J Chem. Phys, 132, 224107 (2010).

(Malolepsza) Malolepsza, Secor, Keyes, J Phys Chem B 119 (42), 13379-13384 (2015).

17.62 fix halt command

17.62.1 Syntax

fix ID group-ID halt N attribute operator avalue keyword value ...

• ID, group-ID are documented in fix command

• halt = style name of this fix command
• N = check halt condition every N steps
• attribute = bondmax or tlimit or v_name
bondmax = length of longest bond in the system (in length units)
tlimit = elapsed CPU time (in seconds)
diskfree = free disk space (in MBytes)
v_name = name of equal-style variable
• operator = “<” or “<=” or “>” or “>=” or “==” or “!=” or “|^”
• avalue = numeric value to compare attribute to
• zero or more keyword/value pairs may be appended
• keyword = error or message or path
error value = hard or soft or continue
message value = yes or no
path value = path to check for free space (may be in quotes)

1178 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.62.2 Examples

fix 10 all halt 1 bondmax > 1.5

fix 10 all halt 10 v_myCheck != 0 error soft
fix 10 all halt 100 diskfree < 100000.0 path "dump storage/."

17.62.3 Description

Check a condition every N steps during a simulation run. N must be >=1. If the condition is met, exit the run. In this
context a “run” can be dynamics or minimization iterations, as specified by the run or minimize command.
The specified group-ID is ignored by this fix.
The specified attribute can be one of the options listed above, namely bondmax, tlimit, diskfree, or an equal-style
variable referenced as v_name, where “name” is the name of a variable that has been defined previously in the input
script.
The bondmax attribute will loop over all bonds in the system, compute their current lengths, and set attribute to the
longest bond distance.
The tlimit attribute queries the elapsed CPU time (in seconds) since the current run began, and sets attribute to that
value. This is an alternative way to limit the length of a simulation run, similar to the timer timeout command. There are
two differences in using this method versus the timer command option. The first is that the clock starts at the beginning
of the current run (not when the timer or fix command is specified), so that any setup time for the run is not included
in the elapsed time. The second is that the timer invocation and syncing across all processors (via MPI_Allreduce)
is not performed once every N steps by this command. Instead it is performed (typically) only a small number of
times and the elapsed times are used to predict when the end-of-the-run will be. Both of these attributes can be useful
when performing benchmark calculations for a desired length of time with minimal overhead. For example, if a run is
performing 1000s of timesteps/sec, the overhead for syncing the timer frequently across a large number of processors
may be non-negligible.
The diskfree attribute will check for available disk space (in MBytes) on supported operating systems. By default it
will check the file system of the current working directory. This can be changed with the optional path keyword, which
will take the path to a file or folder on the file system to be checked as argument. This path must be given with single
or double quotes, if it contains blanks or other special characters (like $).
Equal-style variables evaluate to a numeric value. See the variable command for a description. They calculate formu-
las which can involve mathematical operations, atom properties, group properties, thermodynamic properties, global
values calculated by a compute or fix, or references to other variables. Thus they are a very general means of computing
some attribute of the current system. For example, the following “bondmax” variable will calculate the same quantity
as the hstyle = bondmax option.

compute bdist all bond/local dist

compute bmax all reduce max c_bdist
variable bondmax equal c_bmax

Thus these two versions of a fix halt command will do the same thing:

fix 10 all halt 1 bondmax > 1.5

fix 10 all halt 1 v_bondmax > 1.5

The version with “bondmax” will just run somewhat faster, due to less overhead in computing bond lengths and not
storing them in a separate compute.
A variable can be used to implement a large variety of conditions, including to stop when a specific file exists. Example:

17.62. fix halt command 1179

LAMMPS Documentation, Release stable 29Sep2021

variable exit equal is_file(EXIT)

fix 10 all halt 100 v_exit != 0 error soft

Will stop the current run command when a file EXIT is created in the current working directory. The condition can be
cleared by removing the file through the shell command.
The choice of operators listed above are the usual comparison operators. The XOR operation (exclusive or) is also
included as “|^”. In this context, XOR means that if either the attribute or avalue is 0.0 and the other is non-zero, then
the result is “true”. Otherwise it is “false”.
The specified avalue must be a numeric value.

The optional error keyword determines how the current run is halted. If its value is hard, then LAMMPS will stop
with an error message.
If its value is soft, LAMMPS will exit the current run, but continue to execute subsequent commands in the input script.
However, additional run or minimize commands will be skipped. For example, this allows a script to output the current
state of the system, e.g. via a write_dump or write_restart command.
If its value is continue, the behavior is the same as for soft, except subsequent run or minimize commands are executed.
This allows your script to remedy the condition that triggered the halt, if necessary. Note that you may wish use the
unfix command on the fix halt ID, so that the same condition is not immediately triggered in a subsequent run.
The optional message keyword determines whether a message is printed to the screen and logfile when the halt condition
is triggered. If message is set to yes, a one line message with the values that triggered the halt is printed. If message is
set to no, no message is printed; the run simply exits. The latter may be desirable for post-processing tools that extract
thermodynamic information from log files.

17.62.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command.

17.62.5 Restrictions

The diskfree attribute is currently only supported on Linux, MacOSX, and BSD.

17.62.6 Related commands

variable

17.62.7 Default

The option defaults are error = hard, message = yes, and path = “.”.

1180 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.63 fix heat command

17.63.1 Syntax

fix ID group-ID heat N eflux

• ID, group-ID are documented in fix command

• heat = style name of this fix command
• N = add/subtract heat every this many timesteps
• eflux = rate of heat addition or subtraction (energy/time units)
• eflux can be a variable (see below)
• zero or more keyword/value pairs may be appended to args
• keyword = region
region value = region-ID
region-ID = ID of region atoms must be in to have added force

17.63.2 Examples

fix 3 qin heat 1 1.0

fix 3 qin heat 10 v_flux
fix 4 qout heat 1 -1.0 region top

17.63.3 Description

Add non-translational kinetic energy (heat) to a group of atoms in a manner that conserves their aggregate momentum.
Two of these fixes can be used to establish a temperature gradient across a simulation domain by adding heat (energy)
to one group of atoms (hot reservoir) and subtracting heat from another (cold reservoir). E.g. a simulation sampling
from the McDLT ensemble.
If the region keyword is used, the atom must be in both the group and the specified geometric region in order to have
energy added or subtracted to it. If not specified, then the atoms in the group are affected wherever they may move to.
Heat addition/subtraction is performed every N timesteps.
The eflux parameter can be specified as a numeric constant or as an equal- or atom-style variable. If the value is a
variable, it should be specified as v_name, where name is the variable name. In this case, the variable will be evaluated
each timestep, and its current value(s) used to determine the flux.
If eflux is a numeric constant or equal-style variable which evaluates to a scalar value, then eflux determines the change
in aggregate energy of the entire group of atoms per unit time, e.g. in eV/ps for metal units. In this case it is an
“extensive” quantity, meaning its magnitude should be scaled with the number of atoms in the group. Note that since
eflux also has per-time units (i.e. it is a flux), this means that a larger value of N will add/subtract a larger amount of
energy each time the fix is invoked.

Note: The heat-exchange (HEX) algorithm implemented by this fix is known to exhibit a pronounced energy drift.
An improved algorithm (eHEX) is available as a fix ehex command and might be preferable if energy conservation is
important.

17.63. fix heat command 1181

LAMMPS Documentation, Release stable 29Sep2021

If eflux is specified as an atom-style variable (see below), then the variable computes one value per atom. In this case,
each value is the energy flux for a single atom, again in units of energy per unit time. In this case, each value is an
“intensive” quantity, which need not be scaled with the number of atoms in the group.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
flux.
Atom-style variables can specify the same formulas as equal-style variables but can also include per-atom values, such
as atom coordinates. Thus it is easy to specify a spatially-dependent flux with optional time-dependence as well.

Note: If heat is subtracted from the system too aggressively so that the group’s kinetic energy would go to zero, or any
individual atom’s kinetic energy would go to zero for the case where eflux is an atom-style variable, then LAMMPS
will halt with an error message.

Fix heat is different from a thermostat such as fix nvt or fix temp/rescale in that energy is added/subtracted continually.
Thus if there is not another mechanism in place to counterbalance this effect, the entire system will heat or cool con-
tinuously. You can use multiple heat fixes so that the net energy change is 0.0 or use fix viscous to drain energy from
the system.
This fix does not change the coordinates of its atoms; it only scales their velocities. Thus you must still use an integration
fix (e.g. fix nve) on the affected atoms. This fix should not normally be used on atoms that have their temperature
controlled by another fix - e.g. fix nvt or fix langevin fix.

17.63.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global scalar which can be accessed by various output commands. This scalar is the most recent
value by which velocities were scaled. The scalar value calculated by this fix is “intensive”. If eflux is specified as an
atom-style variable, this fix computes the average value by which the velocities were scaled for all of the atoms that
had their velocities scaled.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.63.5 Restrictions

none

17.63.6 Related commands

fix ehex, compute temp, compute temp/region

1182 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.63.7 Default

none

17.64 fix hyper/global command

17.64.1 Syntax

fix ID group-ID hyper/global cutbond qfactor Vmax Tequil

• ID, group-ID are documented in fix command

• hyper/global = style name of this fix command
• cutbond = max distance at which a pair of atoms is considered bonded (distance units)
• qfactor = max strain at which bias potential goes to 0.0 (unitless)
• Vmax = height of bias potential (energy units)
• Tequil = equilibration temperature (temperature units)

17.64.2 Examples

fix 1 all hyper/global 1.0 0.3 0.8 300.0

17.64.3 Description

This fix is meant to be used with the hyper command to perform a bond-boost global hyperdynamics (GHD) simulation.
The role of this fix is to a select a single pair of atoms in the system at each timestep to add a global bias potential to,
which will alter the dynamics of the system in a manner that effectively accelerates time. This is in contrast to the fix
hyper/local command, which can be user to perform a local hyperdynamics (LHD) simulation, by adding a local bias
potential to multiple pairs of atoms at each timestep. GHD can time accelerate a small simulation with up to a few 100
atoms. For larger systems, LHD is needed to achieve good time acceleration.
For a system that undergoes rare transition events, where one or more atoms move over an energy barrier to a new
potential energy basin, the effect of the bias potential is to induce more rapid transitions. This can lead to a dramatic
speed-up in the rate at which events occurs, without altering their relative frequencies, thus leading to an overall increase
in the elapsed real time of the simulation as compared to running for the same number of timesteps with normal MD.
See the hyper page for a more general discussion of hyperdynamics and citations that explain both GHD and LHD.
The equations and logic used by this fix and described here to perform GHD follow the description given in (Voter2013).
The bond-boost form of a bias potential for HD is due to Miron and Fichthorn as described in (Miron). In LAMMPS
we use a simplified version of bond-boost GHD where a single bond in the system is biased at any one timestep.
Bonds are defined between each pair of atoms ij, whose Rij 0
distance is less than cutbond, when the system is in a
quenched state (minimum) energy. Note that these are not “bonds” in a covalent sense. A bond is simply any pair of
atoms that meet the distance criterion. Cutbond is an argument to this fix; it is discussed below. A bond is only formed
if one or both of the ij atoms are in the specified group.
The current strain of bond ij (when running dynamics) is defined as
0
Rij − Rij
Eij = 0
Rij

17.64. fix hyper/global command 1183

LAMMPS Documentation, Release stable 29Sep2021

where Rij is the current distance between atoms i and j, and Rij
0
is the equilibrium distance in the quenched state.
The bias energy Vij of any bond between atoms i and j is defined as
 2 !
Eij
Vij = V max
· 1− for |Eij | < qf actor or 0 otherwise
q

where the prefactor V max and the cutoff qfactor are arguments to this fix; they are discussed below. This functional
form is an inverse parabola centered at 0.0 with height V max and which goes to 0.0 at +/- qfactor.
Let E max be the maximum of |Eij | for all ij bonds in the system on a given timestep. On that step, Vij is added as a
bias potential to only the single bond with strain E max , call it Vijmax . Note that Vijmax will be 0.0 if E max >= qfactor
on that timestep. Also note that Vijmax is added to the normal interatomic potential that is computed between all atoms
in the system at every step.
The derivative of Vijmax with respect to the position of each atom in the E max bond gives a bias force Fijmax acting on
the bond as
dVijmax 2V max E − ij
Fijmax = − = for |Eij | < qfactor or 0 otherwise
dEij qfactor2

which can be decomposed into an equal and opposite force acting on only the two ij atoms in the E max bond.
The time boost factor for the system is given each timestep I by
max
Bi = eβVij

where β = kTequil ,
1
and Tequil is the temperature of the system and an argument to this fix. Note that Bi >= 1 at every
step.

Note: To run a GHD simulation, the input script must also use the fix langevin command to thermostat the atoms at the
same Tequil as specified by this fix, so that the system is running constant-temperature (NVT) dynamics. LAMMPS
does not check that this is done.

The elapsed time thyper for a GHD simulation running for N timesteps is simply
X
thyper = B − i · dt
i=1,N

where dt is the timestep size defined by the timestep command. The effective time acceleration due to GHD is thus
t_hyper / N*dt, where N*dt is elapsed time for a normal MD run of N timesteps.
Note that in GHD, the boost factor varies from timestep to timestep. Likewise, which bond has E max strain and thus
which pair of atoms the bias potential is added to, will also vary from timestep to timestep. This is in contrast to local
hyperdynamics (LHD) where the boost factor is an input parameter; see the fix hyper/local page for details.

Here is additional information on the input parameters for GHD.

The cutbond argument is the cutoff distance for defining bonds between pairs of nearby atoms. A pair of ij atoms in
their equilibrium, minimum-energy configuration, which are separated by a distance Rij < cutbond, are flagged as a
bonded pair. Setting cubond to be ~25% larger than the nearest-neighbor distance in a crystalline lattice is a typical
choice for solids, so that bonds exist only between nearest neighbor pairs.
The qfactor argument is the limiting strain at which the bias potential goes to 0.0. It is dimensionless, so a value of 0.3
means a bond distance can be up to 30% larger or 30% smaller than the equilibrium (quenched) R0ij distance and the
two atoms in the bond could still experience a non-zero bias force.

1184 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

If qfactor is set too large, then transitions from one energy basin to another are affected because the bias potential is
non-zero at the transition state (e.g. saddle point). If qfactor is set too small than little boost is achieved because the Eij
strain of some bond in the system will (nearly) always exceed qfactor. A value of 0.3 for qfactor is typically reasonable.
The Vmax argument is the prefactor on the bias potential. Ideally, tt should be set to a value slightly less than the
smallest barrier height for an event to occur. Otherwise the applied bias potential may be large enough (when added to
the interatomic potential) to produce a local energy basin with a maxima in the center. This can produce artificial energy
minima in the same basin that trap an atom. Or if Vmax is even larger, it may induce an atom(s) to rapidly transition
to another energy basin. Both cases are “bad dynamics” which violate the assumptions of GHD that guarantee an
accelerated time-accurate trajectory of the system.
Note that if Vmax is set too small, the GHD simulation will run correctly. There will just be fewer events because the
hyper time (t_hyper equation above) will be shorter.

Note: If you have no physical intuition as to the smallest barrier height in your system, a reasonable strategy to
determine the largest Vmax you can use for a GHD model, is to run a sequence of simulations with smaller and smaller
Vmax values, until the event rate does not change (as a function of hyper time).

The Tequil argument is the temperature at which the system is simulated; see the comment above about the fix langevin
thermostatting. It is also part of the beta term in the exponential factor that determines how much boost is achieved as
a function of the bias potential.
In general, the lower the value of Tequil and the higher the value of Vmax, the more time boost will be achievable by
the GHD algorithm.

17.64.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the energy of the bias potential to the global potential
energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify energy no.
This fix computes a global scalar and global vector of length 12, which can be accessed by various output commands.
The scalar is the magnitude of the bias potential (energy units) applied on the current timestep. The vector stores the
following quantities:
• 1 = boost factor on this step (unitless)
• 2 = max strain Eij of any bond on this step (absolute value, unitless)
• 3 = ID of first atom in the max-strain bond
• 4 = ID of second atom in the max-strain bond
• 5 = average # of bonds/atom on this step
• 6 = fraction of timesteps where the biased bond has bias = 0.0 during this run
• 7 = fraction of timesteps where the biased bond has negative strain during this run
• 8 = max drift distance of any atom during this run (distance units)
• 9 = max bond length during this run (distance units)
• 10 = cumulative hyper time since fix was defined (time units)
• 11 = cumulative count of event timesteps since fix was defined
• 12 = cumulative count of atoms in events since fix was defined

17.64. fix hyper/global command 1185

LAMMPS Documentation, Release stable 29Sep2021

The first 5 quantities are for the current timestep. Quantities 6-9 are for the current hyper run. They are reset each time
a new hyper run is performed. Quantities 19-12 are cumulative across multiple runs (since the point in the input script
the fix was defined).
For value 8, drift is the distance an atom moves between two quenched states when the second quench determines an
event has occurred. Atoms involved in an event will typically move the greatest distance since others typically remain
near their original quenched position.
For value 11, events are checked for by the hyper command once every Nevent timesteps. This value is the count of
those timesteps on which one (or more) events was detected. It is NOT the number of distinct events, since more than
one event may occur in the same Nevent time window.
For value 12, each time the hyper command checks for an event, it invokes a compute to flag zero or more atoms as
participating in one or more events. E.g. atoms that have displaced more than some distance from the previous quench
state. Value 11 is the cumulative count of the number of atoms participating in any of the events that were found.
The scalar and vector values calculated by this fix are all “intensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.64.5 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package page for
more info.

17.64.6 Related commands

hyper, fix hyper/local

17.64.7 Default

none

(Voter2013) S. Y. Kim, D. Perez, A. F. Voter, J Chem Phys, 139, 144110 (2013).

(Miron) R. A. Miron and K. A. Fichthorn, J Chem Phys, 119, 6210 (2003).

17.65 fix hyper/local command

17.65.1 Syntax

fix ID group-ID hyper/local cutbond qfactor Vmax Tequil Dcut alpha Btarget

• ID, group-ID are documented in fix command

• hyper/local = style name of this fix command
• cutbond = max distance at which a pair of atoms is considered bonded (distance units)
• qfactor = max strain at which bias potential goes to 0.0 (unitless)
• Vmax = estimated height of bias potential (energy units)

1186 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• Tequil = equilibration temperature (temperature units)

• Dcut = minimum distance between boosted bonds (distance units)
• alpha = boostostat relaxation time (time units)
• Btarget = desired time boost factor (unitless)
• zero or more keyword/value pairs may be appended
• keyword = bound or reset or check/ghost or check/bias
bound value = Bfrac
Bfrac = -1 or a value >= 0.0
reset value = Rfreq
Rfreq = -1 or 0 or timestep value > 0
check/ghost values = none
check/bias values = Nevery error/warn/ignore

17.65.2 Examples

fix 1 all hyper/local 1.0 0.3 0.8 300.0

fix 1 all hyper/local 1.0 0.3 0.8 300.0 bound 0.1 reset 0

17.65.3 Description

This fix is meant to be used with the hyper command to perform a bond-boost local hyperdynamics (LHD) simulation.
The role of this fix is to a select multiple pairs of atoms in the system at each timestep to add a local bias potential to,
which will alter the dynamics of the system in a manner that effectively accelerates time. This is in contrast to the fix
hyper/global command, which can be user to perform a global hyperdynamics (GHD) simulation, by adding a global
bias potential to a single pair of atoms at each timestep. GHD can time accelerate a small simulation with up to a few
100 atoms. For larger systems, LHD is needed to achieve good time acceleration.
For a system that undergoes rare transition events, where one or more atoms move over an energy barrier to a new
potential energy basin, the effect of the bias potential is to induce more rapid transitions. This can lead to a dramatic
speed-up in the rate at which events occurs, without altering their relative frequencies, thus leading to an overall increase
in the elapsed real time of the simulation as compared to running for the same number of timesteps with normal MD.
See the hyper page for a more general discussion of hyperdynamics and citations that explain both GHD and LHD.
The equations and logic used by this fix and described here to perform LHD follow the description given in (Voter2013).
The bond-boost form of a bias potential for HD is due to Miron and Fichthorn as described in (Miron).
To understand this description, you should first read the description of the GHD algorithm on the fix hyper/global doc
page. This description of LHD builds on the GHD description.
The definition of bonds and Eij are the same for GHD and LHD. The formulas for Vijmax and Fijmax are also the same
except for a pre-factor Cij , explained below.
The bias energy Vij applied to a bond ij with maximum strain is
 2 !
Eij
max
Vij = Cij · V max
· 1− for |Eij | < qf actor or 0 otherwise
q

The derivative of Vijmax with respect to the position of each atom in the ij bond gives a bias force Fijmax acting on the
bond as
dVijmax Eij
Fijmax = − = 2Cij V max for |Eij | < qf actor or 0 otherwise
dEij qf actor2

17.65. fix hyper/local command 1187

LAMMPS Documentation, Release stable 29Sep2021

which can be decomposed into an equal and opposite force acting on only the two atoms i and j in the ij bond.
The key difference is that in GHD a bias energy and force is added (on a particular timestep) to only one bond (pair of
atoms) in the system, which is the bond with maximum strain E max .
In LHD, a bias energy and force can be added to multiple bonds separated by the specified Dcut distance or more.
A bond ij is biased if it is the maximum strain bond within its local “neighborhood”, which is defined as the bond ij
plus any neighbor bonds within a distance Dcut from ij. The “distance” between bond ij and bond kl is the minimum
distance between any of the ik, il, jk, and jl pairs of atoms.
For a large system, multiple bonds will typically meet this requirement, and thus a bias potential Vijmax will be applied
to many bonds on the same timestep.
In LHD, all bonds store a Cij prefactor which appears in the Vijmax and Fijmax equationsabove.N otethatthe : math :
factor scales the strength of the bias energy and forces whenever bond ij is the maximum strain bond in its neighborhood.
Cij is initialized to 1.0 when a bond between the ij atoms is first defined. The specified Btarget factor is then used to
adjust the Cij prefactors for each bond every timestep in the following manner.
An instantaneous boost factor Bij is computed each timestep for each bond, as
max
Bij = eβVkl

where Vklmax is the bias energy of the maxstrain bond kl within bond ij‘s neighborhood, β = kTequil ,
1
and Tequil is the
temperature of the system and an argument to this fix.

Note: To run an LHD simulation, the input script must also use the fix langevin command to thermostat the atoms at
the same Tequil as specified by this fix, so that the system is running constant-temperature (NVT) dynamics. LAMMPS
does not check that this is done.

Note that if ij== kl, then bond ij is a biased bond on that timestep, otherwise it is not. But regardless, the boost factor
Bij can be thought of an estimate of time boost currently being applied within a local region centered on bond ij. For
LHD, we want this to be the specified Btarget value everywhere in the simulation domain.
To accomplish this, if Bij < Btarget , the Cij prefactor for bond ij is incremented on the current timestep by an amount
proportional to the inverse of the specified α and the difference (Bij − Btarget ). Conversely if Bij > Btarget , Cij
is decremented by the same amount. This procedure is termed “boostostatting” in (Voter2013). It drives all of the
individual Cij to values such that when Vijmax is applied as a bias to bond ij, the resulting boost factor Bij will be close
to Btarget on average. Thus the LHD time acceleration factor for the overall system is effectively Btarget.
Note that in LHD, the boost factor Btarget is specified by the user. This is in contrast to global hyperdynamics (GHD)
where the boost factor varies each timestep and is computed as a function of Vmax , Emax , and Tequil ; see the fix
hyper/global page for details.

Here is additional information on the input parameters for LHD.

Note that the cutbond, qfactor, and Tequil arguments have the same meaning as for GHD. The Vmax argument is slightly
different. The Dcut, alpha, and Btarget parameters are unique to LHD.
The cutbond argument is the cutoff distance for defining bonds between pairs of nearby atoms. A pair of I,J atoms in
their equilibrium, minimum-energy configuration, which are separated by a distance Rij < cutbond, are flagged as a
bonded pair. Setting cubond to be ~25% larger than the nearest-neighbor distance in a crystalline lattice is a typical
choice for solids, so that bonds exist only between nearest neighbor pairs.
The qfactor argument is the limiting strain at which the bias potential goes to 0.0. It is dimensionless, so a value of 0.3
means a bond distance can be up to 30% larger or 30% smaller than the equilibrium (quenched) Rij 0
distance and the
two atoms in the bond could still experience a non-zero bias force.

1188 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

If qfactor is set too large, then transitions from one energy basin to another are affected because the bias potential is
non-zero at the transition state (e.g. saddle point). If qfactor is set too small than little boost can be achieved because
the Eij strain of some bond in the system will (nearly) always exceed qfactor. A value of 0.3 for qfactor is typically a
reasonable value.
The Vmax argument is a fixed prefactor on the bias potential. There is a also a dynamic prefactor Cij , driven by the
choice of Btarget as discussed above. The product of these should be a value less than the smallest barrier height for an
event to occur. Otherwise the applied bias potential may be large enough (when added to the interatomic potential) to
produce a local energy basin with a maxima in the center. This can produce artificial energy minima in the same basin
that trap an atom. Or if Cij · V max is even larger, it may induce an atom(s) to rapidly transition to another energy basin.
Both cases are “bad dynamics” which violate the assumptions of LHD that guarantee an accelerated time-accurate
trajectory of the system.

Note: It may seem that V max can be set to any value, and Cij will compensate to reduce the overall prefactor if
necessary. However the Cij are initialized to 1.0 and the boostostatting procedure typically operates slowly enough
that there can be a time period of bad dynamics if V max is set too large. A better strategy is to set V max to the slightly
smaller than the lowest barrier height for an event (the same as for GHD), so that the Cij remain near unity.

The Tequil argument is the temperature at which the system is simulated; see the comment above about the fix langevin
thermostatting. It is also part of the beta term in the exponential factor that determines how much boost is achieved as
a function of the bias potential. See the discussion of the Btarget argument below.
As discussed above, the Dcut argument is the distance required between two locally maxstrain bonds for them to both
be selected as biased bonds on the same timestep. Computationally, the larger Dcut is, the more work (computation and
communication) must be done each timestep within the LHD algorithm. And the fewer bonds can be simultaneously
biased, which may mean the specified Btarget time acceleration cannot be achieved.
Physically Dcut should be a long enough distance that biasing two pairs of atoms that close together will not influence
the dynamics of each pair. E.g. something like 2x the cutoff of the interatomic potential. In practice a Dcut value of
~10 Angstroms seems to work well for many solid-state systems.

Note: You should insure that ghost atom communication is performed for a distance of at least Dcut + cutevent =
the distance one or more atoms move (between quenched states) to be considered an “event”. It is an argument to the
“compute event/displace” command used to detect events. By default the ghost communication distance is set by the
pair_style cutoff, which will typically be < Dcut. The comm_modify cutoff command should be used to override the
ghost cutoff explicitly, e.g.

comm_modify cutoff 12.0

Note that this fix does not know the cutevent parameter, but uses half the cutbond parameter as an estimate to warn if
the ghost cutoff is not long enough.
As described above the alpha argument is a pre-factor in the boostostat update equation for each bond’s Cij prefactor.
Alpha is specified in time units, similar to other thermostat or barostat damping parameters. It is roughly the physical
time it will take the boostostat to adjust a Cij value from a too high (or too low) value to a correct one. An alpha
setting of a few ps is typically good for solid-state systems. Note that the alpha argument here is the inverse of the
alpha parameter discussed in (Voter2013).
The Btarget argument is the desired time boost factor (a value > 1) that all the atoms in the system will experience. The
elapsed time t_hyper for an LHD simulation running for N timesteps is simply

thyper = Btarget · N · dt

where dt is the timestep size defined by the timestep command. The effective time acceleration due to LHD is thus
thyper
N ·dt = Btarget , where N · dt is the elapsed time for a normal MD run of N timesteps.

17.65. fix hyper/local command 1189

LAMMPS Documentation, Release stable 29Sep2021

You cannot choose an arbitrarily large setting for Btarget. The maximum value you should choose is

Btarget = eβVsmall

where Vsmall is the smallest event barrier height in your system, β = kTequil ,
1
and Tequil is the specified temperature
of the system (both by this fix and the Langevin thermostat).
Note that if Btarget is set smaller than this, the LHD simulation will run correctly. There will just be fewer events
because the hyper time (t_hyper equation above) will be shorter.

Note: If you have no physical intuition as to the smallest barrier height in your system, a reasonable strategy to
determine the largest Btarget you can use for an LHD model, is to run a sequence of simulations with smaller and
smaller Btarget values, until the event rate does not change (as a function of hyper time).

Here is additional information on the optional keywords for this fix.

The bound keyword turns on min/max bounds for bias coefficients Cij for all bonds. Cij is a prefactor for each bond
on the bias potential of maximum strength V max . Depending on the choice of alpha and Btarget and Vmax, the
boostostatting can cause individual Cij values to fluctuate. If the fluctuations are too large Cij · V max can exceed low
barrier heights and induce bad event dynamics. Bounding the Cij values is a way to prevent this. If Bfrac is set to -1
or any negative value (the default) then no bounds are enforced on Cij values (except they must always be >= 0.0). A
Bfrac setting >= 0.0 sets a lower bound of 1.0 - Bfrac and upper bound of 1.0 + Bfrac on each Cij value. Note that all
Cij values are initialized to 1.0 when a bond is created for the first time. Thus Bfrac limits the bias potential height to
Vmax +/- Bfrac*Vmax.
The reset keyword allow Vmax to be adjusted dynamically depending on the average value of all Cij prefactors. This
can be useful if you are unsure what value of Vmax will match the Btarget boost for the system. The Cij values will
then adjust in aggregate (up or down) so that Cij · V max produces a boost of Btarget, but this may conflict with the
bound keyword settings. By using bound and reset together, V max itself can be reset, and desired bounds still applied
to the Cij values.
A setting for Rfreq of -1 (the default) means Vmax never changes. A setting of 0 means V max is adjusted every time
an event occurs and bond pairs are recalculated. A setting of N > 0 timesteps means V max is adjusted on the first
time an event occurs on a timestep >= N steps after the previous adjustment. The adjustment to V max is computed as
follows. The current average of all Cij · V max values is computed and the V max is reset to that value. All Cij values
are changed to new prefactors such the new Cij · V max is the same as it was previously. If the bound keyword was
used, those bounds are enforced on the new Cij values. Henceforth, new bonds are assigned a Cij = 1.0, which means
their bias potential magnitude is the new V max .
The check/ghost keyword turns on extra computation each timestep to compute statistics about ghost atoms used to
determine which bonds to bias. The output of these stats are the vector values 14 and 15, described below. If this
keyword is not enabled, the output of the stats will be zero.
The check/bias keyword turns on extra computation and communication to check if any biased bonds are closer than
Dcut to each other, which should not be the case if LHD is operating correctly. Thus it is a debugging check. The
Nevery setting determines how often the check is made. The error, warn, or ignore setting determines what is done if
the count of too-close bonds is not zero. Either the code will exit, or issue a warning, or silently tally the count. The
count can be output as vector value 17, as described below. If this keyword is not enabled, the output of that statistic
will be 0.
Note that both of these computations are costly, hence they are only enabled by these keywords.

1190 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.65.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the energy of the bias potential to the global potential
energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify energy no.
This fix computes a global scalar and global vector of length 28, which can be accessed by various output commands.
The scalar is the magnitude of the bias potential (energy units) applied on the current timestep, summed over all biased
bonds. The vector stores the following quantities:
• 1 = average boost for all bonds on this step (unitless)
• 2 = # of biased bonds on this step
• 3 = max strain Eij of any bond on this step (absolute value, unitless)
• 4 = value of V max on this step (energy units)
• 5 = average bias coeff for all bonds on this step (unitless)
• 6 = min bias coeff for all bonds on this step (unitless)
• 7 = max bias coeff for all bonds on this step (unitless)
• 8 = average # of bonds/atom on this step
• 9 = average neighbor bonds/bond on this step within Dcut
• 10 = average boost for all bonds during this run (unitless)
• 11 = average # of biased bonds/step during this run
• 12 = fraction of biased bonds with no bias during this run
• 13 = fraction of biased bonds with negative strain during this run
• 14 = max bond length during this run (distance units)
• 15 = average bias coeff for all bonds during this run (unitless)
• 16 = min bias coeff for any bond during this run (unitless)
• 17 = max bias coeff for any bond during this run (unitless)
• 18 = max drift distance of any bond atom during this run (distance units)
• 19 = max distance from proc subbox of any ghost atom with maxstrain < qfactor during this run (distance units)
• 20 = max distance outside my box of any ghost atom with any maxstrain during this run (distance units)
• 21 = count of ghost atoms that could not be found on reneighbor steps during this run
• 22 = count of bias overlaps (< Dcut) found during this run
• 23 = cumulative hyper time since fix created (time units)
• 24 = cumulative count of event timesteps since fix created
• 25 = cumulative count of atoms in events since fix created
• 26 = cumulative # of new bonds formed since fix created
27 = average boost for biased bonds on this step (unitless) 28 = # of bonds with absolute strain >= q on this step
The first quantities 1-9 are for the current timestep. Quantities 10-22 are for the current hyper run. They are reset each
time a new hyper run is performed. Quantities 23-26 are cumulative across multiple runs (since the point in the input
script the fix was defined).

17.65. fix hyper/local command 1191

LAMMPS Documentation, Release stable 29Sep2021

For value 10, each bond instantaneous boost factor is given by the equation for Bij above. The total system boost
(average across all bonds) fluctuates, but should average to a value close to the specified Btarget .
For value 12, the numerator is a count of all biased bonds on each timestep whose bias energy = 0.0 due to Eij >=
qf actor. The denominator is the count of all biased bonds on all timesteps.
For value 13, the numerator is a count of all biased bonds on each timestep with negative strain. The denominator is
the count of all biased bonds on all timesteps.
Values 18-22 are mostly useful for debugging and diagnostic purposes.
For value 18, drift is the distance an atom moves between two quenched states when the second quench determines an
event has occurred. Atoms involved in an event will typically move the greatest distance since others typically remain
near their original quenched position.
For values 19-21, neighbor atoms in the full neighbor list with cutoff Dcut may be ghost atoms outside a processor’s
sub-box. Before the next event occurs they may move further than Dcut away from the sub-box boundary. Value 19
is the furthest (from the sub-box) any ghost atom in the neighbor list with maxstrain < qfactor was accessed during
the run. Value 20 is the same except that the ghost atom’s maxstrain may be >= qfactor, which may mean it is about
to participate in an event. Value 21 is a count of how many ghost atoms could not be found on reneighbor steps,
presumably because they moved too far away due to their participation in an event (which will likely be detected at the
next quench).
Typical values for 19 and 20 should be slightly larger than Dcut, which accounts for ghost atoms initially at a Dcut
distance moving thermally before the next event takes place.
Note that for values 19 and 20 to be computed, the optional keyword check/ghost must be specified. Otherwise these
values will be zero. This is because computing them incurs overhead, so the values are only computed if requested.
Value 21 should be zero or small. As explained above a small count likely means some ghost atoms were participating
in their own events and moved a longer distance. If the value is large, it likely means the communication cutoff for
ghosts is too close to Dcut leading to many not-found ghost atoms before the next event. This may lead to a reduced
number of bonds being selected for biasing, since the code assumes those atoms are part of highly strained bonds. As
explained above, the comm_modify cutoff command can be used to set a longer cutoff.
For value 22, no two bonds should be biased if they are within a Dcut distance of each other. This value should be zero,
indicating that no pair of biased bonds are closer than Dcut from each other.
Note that for value 22 to be computed, the optional keyword check/bias must be specified and it determines how
often this check is performed. This is because performing the check incurs overhead, so if only computed as often as
requested.
The result at the end of the run is the cumulative total from every timestep the check was made. Note that the value
is a count of atoms in bonds which found other atoms in bonds too close, so it is almost always an over-count of the
number of too-close bonds.
Value 23 is simply the specified boost factor times the number of timesteps times the timestep size.
For value 24, events are checked for by the hyper command once every Nevent timesteps. This value is the count of
those timesteps on which one (or more) events was detected. It is NOT the number of distinct events, since more than
one event may occur in the same Nevent time window.
For value 25, each time the hyper command checks for an event, it invokes a compute to flag zero or more atoms as
participating in one or more events. E.g. atoms that have displaced more than some distance from the previous quench
state. Value 25 is the cumulative count of the number of atoms participating in any of the events that were found.
Value 26 tallies the number of new bonds created by the bond reset operation. Bonds between a specific I,J pair of
atoms may persist for the entire hyperdynamics simulation if neither I or J are involved in an event.
Value 27 computes the average boost for biased bonds only on this step.
Value 28 is the count of bonds with an absolute value of strain >= q on this step.

1192 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The scalar value is an “extensive” quantity since it grows with the system size; the vector values are all “intensive”.
This fix also computes a local vector of length the number of bonds currently in the system. The value for each bond
is its Cij prefactor (bias coefficient). These values can be can be accessed by various output commands. A particularly
useful one is the fix ave/histo command which can be used to histogram the Cij values to see if they are distributed
reasonably close to 1.0, which indicates a good choice of V max .
The local values calculated by this fix are unitless.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.65.5 Restrictions

This fix is part of the REPLICA package. It is only enabled if LAMMPS was built with that package. See the Build
package doc page for more info.

17.65.6 Related commands

hyper, fix hyper/global

17.65.7 Default

The default settings for optimal keywords are bounds = -1 and reset = -1. The check/ghost and check/bias keywords
are not enabled by default.

(Voter2013) S. Y. Kim, D. Perez, A. F. Voter, J Chem Phys, 139, 144110 (2013).

(Miron) R. A. Miron and K. A. Fichthorn, J Chem Phys, 119, 6210 (2003).

17.66 fix imd command

17.66.1 Syntax

fix ID group-ID imd trate port keyword values ...

• ID, group-ID are documented in fix command

• imd = style name of this fix command
• port = port number on which the fix listens for an IMD client
• keyword = unwrap or fscale or trate
unwrap arg = on or off
off = coordinates are wrapped back into the principal unit cell (default)
on = "unwrapped" coordinates using the image flags used
fscale arg = factor
factor = floating point number to scale IMD forces (default: 1.0)
trate arg = transmission rate of coordinate data sets (default: 1)
nowait arg = on or off
off = LAMMPS waits to be connected to an IMD client before continuing (default)
on = LAMMPS listens for an IMD client, but continues with the run

17.66. fix imd command 1193

LAMMPS Documentation, Release stable 29Sep2021

17.66.2 Examples

fix vmd all imd 5678

fix comm all imd 8888 trate 5 unwrap on fscale 10.0

17.66.3 Description

This fix implements the “Interactive MD” (IMD) protocol which allows realtime visualization and manipulation of MD
simulations through the IMD protocol, as initially implemented in VMD and NAMD. Specifically it allows LAMMPS
to connect an IMD client, for example the VMD visualization program, so that it can monitor the progress of the
simulation and interactively apply forces to selected atoms.
If LAMMPS is compiled with the pre-processor flag -DLAMMPS_ASYNC_IMD then fix imd will use POSIX threads
to spawn a IMD communication thread on MPI rank 0 in order to offload data reading and writing from the main
execution thread and potentially lower the inferred latencies for slow communication links. This feature has only been
tested under linux.
There are example scripts for using this package with LAMMPS in examples/PACKAGES/imd. Additional examples
and a driver for use with the Novint Falcon game controller as haptic device can be found at: http://sites.google.com/
site/akohlmey/software/vrpn-icms.
The source code for this fix includes code developed by the Theoretical and Computational Biophysics Group in the
Beckman Institute for Advanced Science and Technology at the University of Illinois at Urbana-Champaign. We thank
them for providing a software interface that allows codes like LAMMPS to hook to VMD.
Upon initialization of the fix, it will open a communication port on the node with MPI task 0 and wait for an incoming
connection. As soon as an IMD client is connected, the simulation will continue and the fix will send the current
coordinates of the fix’s group to the IMD client at every trate MD step. When using r-RESPA, trate applies to the steps
of the outmost RESPA level. During a run with an active IMD connection also the IMD client can request to apply
forces to selected atoms of the fix group.
The port number selected must be an available network port number. On many machines, port numbers < 1024 are
reserved for accounts with system manager privilege and specific applications. If multiple imd fixes would be active at
the same time, each needs to use a different port number.
The nowait keyword controls the behavior of the fix when no IMD client is connected. With the default setting of off,
LAMMPS will wait until a connection is made before continuing with the execution. Setting nowait to on will have
the LAMMPS code be ready to connect to a client, but continue with the simulation. This can for example be used to
monitor the progress of an ongoing calculation without the need to be permanently connected or having to download
a trajectory file.
The trate keyword allows to select how often the coordinate data is sent to the IMD client. It can also be changed
on request of the IMD client through an IMD protocol message. The unwrap keyword allows to send “unwrapped”
coordinates to the IMD client that undo the wrapping back of coordinates into the principle unit cell, as done by default
in LAMMPS. The fscale keyword allows to apply a scaling factor to forces transmitted by the IMD client. The IMD
protocols stipulates that forces are transferred in kcal/mol/angstrom under the assumption that coordinates are given in
angstrom. For LAMMPS runs with different units or as a measure to tweak the forces generated by the manipulation
of the IMD client, this option allows to make adjustments.
To connect VMD to a listening LAMMPS simulation on the same machine with fix imd enabled, one needs to start
VMD and load a coordinate or topology file that matches the fix group. When the VMD command prompts appears,
one types the command line:

imd connect localhost 5678

This assumes that fix imd was started with 5678 as a port number for the IMD protocol.

1194 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The steps to do interactive manipulation of a running simulation in VMD are the following:
In the Mouse menu of the VMD Main window, select “Mouse -> Force -> Atom”. You may alternately select “Residue”,
or “Fragment” to apply forces to whole residues or fragments. Your mouse can now be used to apply forces to your
simulation. Click on an atom, residue, or fragment and drag to apply a force. Click quickly without moving the mouse
to turn the force off. You can also use a variety of 3D position trackers to apply forces to your simulation. Game
controllers or haptic devices with force-feedback such as the Novint Falcon or Sensable PHANTOM allow you to feel
the resistance due to inertia or interactions with neighbors that the atoms experience you are trying to move, as if they
were real objects. See the VMD IMD Homepage and the VRPN-ICMS Homepage for more details.
If IMD control messages are received, a line of text describing the message and its effect will be printed to the LAMMPS
output screen, if screen output is active.

17.66.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global scalar or vector or per-atom quantities are stored by this fix for access by various output commands. No
parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.66.5 Restrictions

This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
When used in combination with VMD, a topology or coordinate file has to be loaded, which matches (in number and
ordering of atoms) the group the fix is applied to. The fix internally sorts atom IDs by ascending integer value; in VMD
(and thus the IMD protocol) those will be assigned 0-based consecutive index numbers.
When using multiple active IMD connections at the same time, each needs to use a different port number.

17.66.6 Related commands

none

17.66.7 Default

none

17.67 fix indent command

17.67.1 Syntax

fix ID group-ID indent K keyword values ...

• ID, group-ID are documented in fix command

• indent = style name of this fix command
• K = force constant for indenter surface (force/distance^2 units)
• one or more keyword/value pairs may be appended

17.67. fix indent command 1195

LAMMPS Documentation, Release stable 29Sep2021

• keyword = sphere or cylinder or plane or side or units

sphere args = x y z R
x,y,z = initial position of center of indenter (distance units)
R = sphere radius of indenter (distance units)
any of x,y,z,R can be a variable (see below)
cylinder args = dim c1 c2 R
dim = x or y or z = axis of cylinder
c1,c2 = coords of cylinder axis in other 2 dimensions (distance units)
R = cylinder radius of indenter (distance units)
any of c1,c2,R can be a variable (see below)
plane args = dim pos side
dim = x or y or z = plane perpendicular to this dimension
pos = position of plane in dimension x, y, or z (distance units)
pos can be a variable (see below)
side = lo or hi
side value = in or out
in = the indenter acts on particles inside the sphere or cylinder
out = the indenter acts on particles outside the sphere or cylinder
units value = lattice or box
lattice = the geometry is defined in lattice units
box = the geometry is defined in simulation box units

17.67.2 Examples

fix 1 all indent 10.0 sphere 0.0 0.0 15.0 3.0

fix 1 all indent 10.0 sphere v_x v_y 0.0 v_radius side in
fix 2 flow indent 10.0 cylinder z 0.0 0.0 10.0 units box

17.67.3 Description

Insert an indenter within a simulation box. The indenter repels all atoms in the group that touch it, so it can be used to
push into a material or as an obstacle in a flow. Or it can be used as a constraining wall around a simulation; see the
discussion of the side keyword below.
The indenter can either be spherical or cylindrical or planar. You must set one of those 3 keywords.
A spherical indenter exerts a force of magnitude
2
F (r) = −K (r − R)

on each atom where K is the specified force constant, r is the distance from the atom to the center of the indenter, and
R is the radius of the indenter. The force is repulsive and F(r) = 0 for r > R.
A cylindrical indenter exerts the same force, except that r is the distance from the atom to the center axis of the cylinder.
The cylinder extends infinitely along its axis.
Spherical and cylindrical indenters account for periodic boundaries in two ways. First, the center point of a spherical
indenter (x,y,z) or axis of a cylindrical indenter (c1,c2) is remapped back into the simulation box, if the box is periodic
in a particular dimension. This occurs every timestep if the indenter geometry is specified with a variable (see below),
e.g. it is moving over time. Second, the calculation of distance to the indenter center or axis accounts for periodic
boundaries. Both of these mean that an indenter can effectively move through and straddle one or more periodic
boundaries.

1196 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

A planar indenter is really an axis-aligned infinite-extent wall exerting the same force on atoms in the system, where
R is the position of the plane and r-R is the distance from the plane. If the side parameter of the plane is specified as
lo then it will indent from the lo end of the simulation box, meaning that atoms with a coordinate less than the plane’s
current position will be pushed towards the hi end of the box and atoms with a coordinate higher than the plane’s current
position will feel no force. Vice versa if side is specified as hi.
Any of the 4 quantities defining a spherical indenter’s geometry can be specified as an equal-style variable, namely x,
y, z, or R. Similarly, for a cylindrical indenter, any of c1, c2, or R, can be a variable. For a planar indenter, pos can be
a variable. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case,
the variable will be evaluated each timestep, and its value used to define the indenter geometry.
Note that equal-style variables can specify formulas with various mathematical functions, and include thermo_style
command keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify indenter
properties that change as a function of time or span consecutive runs in a continuous fashion. For the latter, see the
start and stop keywords of the run command and the elaplong keyword of thermo_style custom for details.
For example, if a spherical indenter’s x-position is specified as v_x, then this variable definition will keep it’s center at
a relative position in the simulation box, 1/4 of the way from the left edge to the right edge, even if the box size changes:

variable x equal "xlo + 0.25*lx"

Similarly, either of these variable definitions will move the indenter from an initial position at 2.5 at a constant velocity
of 5:

variable x equal "2.5 + 5*elaplong*dt"

variable x equal vdisplace(2.5,5)

If a spherical indenter’s radius is specified as v_r, then these variable definitions will grow the size of the indenter at a
specified rate.

variable r0 equal 0.0

variable rate equal 1.0
variable r equal "v_r0 + step*dt*v_rate"

If the side keyword is specified as out, which is the default, then particles outside the indenter are pushed away from its
outer surface, as described above. This only applies to spherical or cylindrical indenters. If the side keyword is specified
as in, the action of the indenter is reversed. Particles inside the indenter are pushed away from its inner surface. In
other words, the indenter is now a containing wall that traps the particles inside it. If the radius shrinks over time, it
will squeeze the particles.
The units keyword determines the meaning of the distance units used to define the indenter geometry. A box value
selects standard distance units as defined by the units command, e.g. Angstroms for units = real or metal. A lattice
value means the distance units are in lattice spacings. The lattice command must have been previously used to define
the lattice spacing. The (x,y,z) coords of the indenter position are scaled by the x,y,z lattice spacings respectively. The
radius of a spherical or cylindrical indenter is scaled by the x lattice spacing.
Note that the units keyword only affects indenter geometry parameters specified directly with numbers, not those spec-
ified as variables. In the latter case, you should use the xlat, ylat, zlat keywords of the thermo_style command if you
want to include lattice spacings in a variable formula.
The force constant K is not affected by the units keyword. It is always in force/distance^2 units where force and distance
are defined by the units command. If you wish K to be scaled by the lattice spacing, you can define K with a variable
whose formula contains xlat, ylat, zlat keywords of the thermo_style command, e.g.

variable k equal 100.0/xlat/xlat

fix 1 all indent $k sphere ...

17.67. fix indent command 1197

LAMMPS Documentation, Release stable 29Sep2021

17.67.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the energy of interaction between atoms and the indenter to
the global potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify
energy no. The energy of each particle interacting with the indenter is K/3 (r - R)^3.
The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.
This fix computes a global scalar energy and a global 3-vector of forces (on the indenter), which can be accessed by
various output commands. The scalar and vector values calculated by this fix are “extensive”.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command. Note that if
you define the indenter geometry with a variable using a time-dependent formula, LAMMPS uses the iteration count
in the minimizer as the timestep. But it is almost certainly a bad idea to have the indenter change its position or size
during a minimization. LAMMPS does not check if you have done this.

Note: If you want the atom/indenter interaction energy to be included in the total potential energy of the system (the
quantity being minimized), you must enable the fix_modify energy option for this fix.

17.67.5 Restrictions

none

17.67.6 Related commands

none

17.67.7 Default

The option defaults are side = out and units = lattice.

17.68 fix ipi command

17.68.1 Syntax

fix ID group-ID ipi address port [unix] [reset]

• ID, group-ID are documented in fix command

• ipi = style name of this fix command
• address = internet address (FQDN or IP), or UNIX socket name
• port = port number (ignored for UNIX sockets)
• optional keyword = unix, if present uses a unix socket
• optional keyword = reset, if present reset electrostatics at each call

1198 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.68.2 Examples

fix 1 all ipi my.server.com 12345

fix 1 all ipi mysocket 666 unix reset

17.68.3 Description

This fix enables LAMMPS to be run as a client for the i-PI Python wrapper (IPI) for performing a path integral molecular
dynamics (PIMD) simulation. The philosophy behind i-PI is described in the following publication (IPI-CPC).
A version of the i-PI package, containing only files needed for use with LAMMPS, is provided in the tools/i-pi directory.
See the tools/i-pi/manual.pdf for an introduction to i-PI. The examples/PACKAGES/i-pi directory contains example
scripts for using i-PI with LAMMPS.
In brief, the path integral molecular dynamics is performed by the Python wrapper, while the client (LAMMPS in this
case) simply computes forces and energy for each configuration. The communication between the two components
takes place using sockets, and is reduced to the bare minimum. All the parameters of the dynamics are specified in
the input of i-PI, and all the parameters of the force field must be specified as LAMMPS inputs, preceding the fix ipi
command.
The server address must be specified by the address argument, and can be either the IP address, the fully-qualified name
of the server, or the name of a UNIX socket for local, faster communication. In the case of internet sockets, the port
argument specifies the port number on which i-PI is listening, while the unix optional switch specifies that the socket
is a UNIX socket.
Note that there is no check of data integrity, or that the atomic configurations make sense. It is assumed that the species
in the i-PI input are listed in the same order as in the data file of LAMMPS. The initial configuration is ignored, as it
will be substituted with the coordinates received from i-PI before forces are ever evaluated.
A note of caution when using potentials that contain long-range electrostatics, or that contain parameters that depend
on box size: all of these options will be initialized based on the cell size in the LAMMPS-side initial configuration and
kept constant during the run. This is required to e.g. obtain reproducible and conserved forces. If the cell varies too
wildly, it may be advisable to re-initialize these interactions at each call. This behavior can be requested by setting the
reset switch.

17.68.4 Restart, fix_modify, output, run start/stop, minimize info

There is no restart information associated with this fix, since all the dynamical parameters are dealt with by i-PI.

17.68.5 Restrictions

Using this fix on anything other than all atoms requires particular care, since i-PI will know nothing on atoms that are
not those whose coordinates are transferred. However, one could use this strategy to define an external potential acting
on the atoms that are moved by i-PI.
This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info. Because of the use of UNIX domain sockets, this fix will only work in a UNIX environment.

17.68. fix ipi command 1199

LAMMPS Documentation, Release stable 29Sep2021

17.68.6 Related commands

fix nve

(IPI-CPC) Ceriotti, More and Manolopoulos, Comp Phys Comm, 185, 1019-1026 (2014).
(IPI) http://epfl-cosmo.github.io/gle4md/index.html?page=ipi

17.69 fix langevin command

Accelerator Variants: langevin/kk

17.69.1 Syntax

fix ID group-ID langevin Tstart Tstop damp seed keyword values ...

• ID, group-ID are documented in fix command

• langevin = style name of this fix command
• Tstart,Tstop = desired temperature at start/end of run (temperature units)
• Tstart can be a variable (see below)
• damp = damping parameter (time units)
• seed = random number seed to use for white noise (positive integer)
• zero or more keyword/value pairs may be appended
• keyword = angmom or omega or scale or tally or zero
angmom value = no or factor
no = do not thermostat rotational degrees of freedom via the angular momentum
factor = do thermostat rotational degrees of freedom via the angular momentum and␣
,→apply numeric scale factor as discussed below

gjf value = no or vfull or vhalf

no = use standard formulation
vfull = use Gronbech-Jensen/Farago formulation
vhalf = use 2GJ formulation
omega value = no or yes
no = do not thermostat rotational degrees of freedom via the angular velocity
yes = do thermostat rotational degrees of freedom via the angular velocity
scale values = type ratio
type = atom type (1-N)
ratio = factor by which to scale the damping coefficient
tally value = no or yes
no = do not tally the energy added/subtracted to atoms
yes = do tally the energy added/subtracted to atoms
zero value = no or yes
no = do not set total random force to zero
yes = set total random force to zero

1200 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.69.2 Examples

fix 3 boundary langevin 1.0 1.0 1000.0 699483

fix 1 all langevin 1.0 1.1 100.0 48279 scale 3 1.5
fix 1 all langevin 1.0 1.1 100.0 48279 angmom 3.333

17.69.3 Description

Apply a Langevin thermostat as described in (Schneider) to a group of atoms which models an interaction with a
background implicit solvent. Used with fix nve, this command performs Brownian dynamics (BD), since the total force
on each atom will have the form:
F =Fc + Ff + Fr
m
Ff = − v
damp
s
kB T m
Fr ∝
dt damp

Fc is the conservative force computed via the usual inter-particle interactions (pair_style, bond_style, etc). The Ff and
Fr terms are added by this fix on a per-particle basis. See the pair_style dpd/tstat command for a thermostatting option
that adds similar terms on a pairwise basis to pairs of interacting particles.
Ff is a frictional drag or viscous damping term proportional to the particle’s velocity. The proportionality constant for
each atom is computed as damp m
, where m is the mass of the particle and damp is the damping factor specified by the
user.
Fr is a force due to solvent atoms at a temperature T randomly bumping intoq
the particle. As derived from the fluc-
tuation/dissipation theorem, its magnitude as shown above is proportional to dtkBdamp Tm
, where kB is the Boltzmann
constant, T is the desired temperature, m is the mass of the particle, dt is the timestep size, and damp is the damping
factor. Random numbers are used to randomize the direction and magnitude of this force as described in (Dunweg),
where a uniform random number is used (instead of a Gaussian random number) for speed.
Note that unless you use the omega or angmom keywords, the thermostat effect of this fix is applied to only the trans-
lational degrees of freedom for the particles, which is an important consideration for finite-size particles, which have
rotational degrees of freedom, are being thermostatted. The translational degrees of freedom can also have a bias
velocity removed from them before thermostatting takes place; see the description below.

Note: Unlike the fix nvt command which performs Nose/Hoover thermostatting AND time integration, this fix does
NOT perform time integration. It only modifies forces to effect thermostatting. Thus you must use a separate time
integration fix, like fix nve to actually update the velocities and positions of atoms using the modified forces. Likewise,
this fix should not normally be used on atoms that also have their temperature controlled by another fix - e.g. by fix nvt
or fix temp/rescale commands.

See the Howto thermostat page for a discussion of different ways to compute temperature and perform thermostatting.
The desired temperature at each timestep is a ramped value during the run from Tstart to Tstop.
Tstart can be specified as an equal-style or atom-style variable. In this case, the Tstop setting is ignored. If the value
is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable will be
evaluated each timestep, and its value used to determine the target temperature.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
temperature.

17.69. fix langevin command 1201

LAMMPS Documentation, Release stable 29Sep2021

Atom-style variables can specify the same formulas as equal-style variables but can also include per-atom values, such
as atom coordinates. Thus it is easy to specify a spatially-dependent temperature with optional time-dependence as
well.
Like other fixes that perform thermostatting, this fix can be used with compute commands that remove a “bias” from
the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or removing the x-component
of velocity from the calculation. This is not done by default, but only if the fix_modify command is used to assign a
temperature compute to this fix that includes such a bias term. See the doc pages for individual compute commands to
determine which ones include a bias. In this case, the thermostat works in the following manner: bias is removed from
each atom, thermostatting is performed on the remaining thermal degrees of freedom, and the bias is added back in.
The damp parameter is specified in time units and determines how rapidly the temperature is relaxed. For example, a
value of 100.0 means to relax the temperature in a timespan of (roughly) 100 time units (τ or fs or ps - see the units
command). The damp factor can be thought of as inversely related to the viscosity of the solvent. I.e. a small relaxation
time implies a high-viscosity solvent and vice versa. See the discussion about γ and viscosity in the documentation for
the fix viscous command for more details.
The random # seed must be a positive integer. A Marsaglia random number generator is used. Each processor uses the
input seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the system
will not be identical on two runs on different numbers of processors.

The keyword/value option pairs are used in the following ways.

The keyword angmom and omega keywords enable thermostatting of rotational degrees of freedom in addition to the
usual translational degrees of freedom. This can only be done for finite-size particles.
A simulation using atom_style sphere defines an omega for finite-size spheres. A simulation using atom_style ellip-
soid defines a finite size and shape for aspherical particles and an angular momentum. The Langevin formulas for
thermostatting the rotational degrees of freedom are the same as those above, where force is replaced by torque, m is
replaced by the moment of inertia I, and v is replaced by omega (which is derived from the angular momentum in the
case of aspherical particles).
The rotational temperature of the particles can be monitored by the compute temp/sphere and compute temp/asphere
commands with their rotate options.
For the omega keyword there is also a scale factor of 10.0
3.0 that is applied as a multiplier on the Ff (damping) term in
q
the equation above and of 3.0 as a multiplier on the Fr term. This does not affect the thermostatting behavior of the
10.0

Langevin formalism but insures that the randomized rotational diffusivity of spherical particles is correct.
For the angmom keyword a similar scale factor is needed which is 10.0 3.0 for spherical particles, but is anisotropic for
aspherical particles (e.g. ellipsoids). Currently LAMMPS only applies an isotropic scale factor, and you can choose
its magnitude as the specified value of the angmom keyword. If your aspherical particles are (nearly) spherical than a
value of 10.0
3.0 = 3.3 is a good choice. If they are highly aspherical, a value of 1.0 is as good a choice as any, since the
effects on rotational diffusivity of the particles will be incorrect regardless. Note that for any reasonable scale factor,
the thermostatting effect of the angmom keyword on the rotational temperature of the aspherical particles should still
be valid.
The keyword scale allows the damp factor to be scaled up or down by the specified factor for atoms of that type. This
can be useful when different atom types have different sizes or masses. It can be used multiple times to adjust damp for
several atom types. Note that specifying a ratio of 2 increases the relaxation time which is equivalent to the solvent’s
viscosity acting on particles with 12 the diameter. This is the opposite effect of scale factors used by the fix viscous
command, since the damp factor in fix langevin is inversely related to the γ factor in fix viscous. Also note that the
damping factor in fix langevin includes the particle mass in Ff, unlike fix viscous. Thus the mass and size of different
atom types should be accounted for in the choice of ratio values.
The keyword tally enables the calculation of the cumulative energy added/subtracted to the atoms as they are ther-
mostatted. Effectively it is the energy exchanged between the infinite thermal reservoir and the particles. As described
below, this energy can then be printed out or added to the potential energy of the system to monitor energy conservation.

1202 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Note: This accumulated energy does NOT include kinetic energy removed by the zero flag. LAMMPS will print a
warning when both options are active.

The keyword zero can be used to eliminate drift due to the thermostat. Because the random forces on different atoms are
independent, they do not sum exactly to zero. As a result, this fix applies a small random force to the entire system, and
the center-of-mass of the system undergoes a slow random walk. If the keyword zero is set to yes, the total random force
is set exactly to zero by subtracting off an equal part of it from each atom in the group. As a result, the center-of-mass
of a system with zero initial momentum will not drift over time.
The keyword gjf can be used to run the Gronbech-Jensen/Farago time-discretization of the Langevin model. As
described in the papers cited below, the purpose of this method is to enable longer timesteps to be used (up to the
numerical stability limit of the integrator), while still producing the correct Boltzmann distribution of atom positions.
The current implementation provides the user with the option to output the velocity in one of two forms: vfull or
vhalf, which replaces the outdated option yes. The gjf option vfull outputs the on-site velocity given in Gronbech-
Jensen/Farago; this velocity is shown to be systematically lower than the target temperature by a small amount, which
grows quadratically with the timestep. The gjf option vhalf outputs the 2GJ half-step velocity given in Gronbech
Jensen/Gronbech-Jensen; for linear systems, this velocity is shown to not have any statistical errors for any stable time
step. An overview of statistically correct Boltzmann and Maxwell-Boltzmann sampling of true on-site and true half-step
velocities is given in Gronbech-Jensen. Regardless of the choice of output velocity, the sampling of the configurational
distribution of atom positions is the same, and linearly consistent with the target temperature.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.69.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. Because the state of the random number generator is
not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation continues on the
same as if no restart had taken place. However, in a statistical sense, a restarted simulation should produce the same
behavior.
The fix_modify temp option is supported by this fix. You can use it to assign a temperature compute you have defined
to this fix which will be used in its thermostatting procedure, as described above. For consistency, the group used by
this fix and by the compute should be the same.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve, but only if the tally keyword to set to yes. See the thermo_style page for details.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
Note that calculation of this quantity also requires setting the tally keyword to yes.

17.69. fix langevin command 1203

LAMMPS Documentation, Release stable 29Sep2021

This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.69.5 Restrictions

For gjf do not choose damp=dt/2. gjf is not compatible with run_style respa.

17.69.6 Related commands

fix nvt, fix temp/rescale, fix viscous, fix nvt, pair_style dpd/tstat

17.69.7 Default

The option defaults are angmom = no, omega = no, scale = 1.0 for all types, tally = no, zero = no, gjf = no.

(Dunweg) Dunweg and Paul, Int J of Modern Physics C, 2, 817-27 (1991).

(Schneider) Schneider and Stoll, Phys Rev B, 17, 1302 (1978).
(Gronbech-Jensen) Gronbech-Jensen and Farago, Mol Phys, 111, 983 (2013); Gronbech-Jensen, Hayre, and Farago,
Comp Phys Comm, 185, 524 (2014)
(Gronbech-Jensen) Gronbech Jensen and Gronbech-Jensen, Mol Phys, 117, 2511 (2019)
(Gronbech-Jensen) Gronbech-Jensen, Mol Phys (2019); https://doi.org/10.1080/00268976.2019.1662506

17.70 fix langevin/drude command

17.70.1 Syntax

fix ID group-ID langevin/drude Tcom damp_com seed_com Tdrude damp_drude seed_drude␣

,→keyword values ...

• ID, group-ID are documented in fix command

• langevin/drude = style name of this fix command
• Tcom = desired temperature of the centers of mass (temperature units)
• damp_com = damping parameter for the thermostat on centers of mass (time units)
• seed_com = random number seed to use for white noise of the thermostat on centers of mass (positive integer)
• Tdrude = desired temperature of the Drude oscillators (temperature units)
• damp_drude = damping parameter for the thermostat on Drude oscillators (time units)
• seed_drude = random number seed to use for white noise of the thermostat on Drude oscillators (positive integer)
• zero or more keyword/value pairs may be appended
• keyword = zero

1204 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

zero value = no or yes

no = do not set total random force on centers of mass to zero
yes = set total random force on centers of mass to zero

17.70.2 Examples

fix 3 all langevin/drude 300.0 100.0 19377 1.0 20.0 83451

fix 1 all langevin/drude 298.15 100.0 19377 5.0 10.0 83451 zero yes

Example input scripts available: examples/PACKAGES/drude

17.70.3 Description

Apply two Langevin thermostats as described in (Jiang) for thermalizing the reduced degrees of freedom of Drude
oscillators. This link describes how to use the thermalized Drude oscillator model in LAMMPS and polarizable models
in LAMMPS are discussed on the Howto polarizable doc page.
Drude oscillators are a way to simulate polarizables atoms, by splitting them into a core and a Drude particle bound
by a harmonic bond. The thermalization works by transforming the particles degrees of freedom by these equations.
In these equations upper case denotes atomic or center of mass values and lower case denotes Drude particle or dipole
values. Primes denote the transformed (reduced) values, while bare letters denote the original values.
Velocities:
M V + mv
V0 =
M0
v0 = v − V
Masses:

M0 = M + m

Mm
m0 =
M0
The Langevin forces are computed as
M0
F0 = − V 0 + Fr0
dampc om
m0
f0 = − v 0 + fr0
dampd rude
q q
kB Tcom m0 2 kB Tdrude m0
Fr0 is a random force proportional to 2dt dampc om . fr is a random force proportional to
0
dt dampd rude . Then the real
forces acting on the particles are computed from the inverse transform:
M 0
F = F − f0
M0
m
f = 0 F0 + f0
M
This fix also thermostats non-polarizable atoms in the group at temperature Tcom, as if they had a massless Drude
partner. The Drude particles themselves need not be in the group. The center of mass and the dipole are thermostatted
iff the core atom is in the group.
Note that the thermostat effect of this fix is applied to only the translational degrees of freedom of the particles, which is
an important consideration if finite-size particles, which have rotational degrees of freedom, are being thermostatted.

17.70. fix langevin/drude command 1205

LAMMPS Documentation, Release stable 29Sep2021

The translational degrees of freedom can also have a bias velocity removed from them before thermostatting takes
place; see the description below.

Note: Like the fix langevin command, this fix does NOT perform time integration. It only modifies forces to effect
thermostatting. Thus you must use a separate time integration fix, like fix nve or fix nph to actually update the velocities
and positions of atoms using the modified forces. Likewise, this fix should not normally be used on atoms that also
have their temperature controlled by another fix - e.g. by fix nvt or fix temp/rescale commands.

See the Howto thermostat page for a discussion of different ways to compute temperature and perform thermostatting.

This fix requires each atom know whether it is a Drude particle or not. You must therefore use the fix drude command
to specify the Drude status of each atom type.

Note: only the Drude core atoms need to be in the group specified for this fix. A Drude electron will be transformed
together with its cores even if it is not itself in the group. It is safe to include Drude electrons or non-polarizable
atoms in the group. The non-polarizable atoms will simply be thermostatted as if they had a massless Drude partner
(electron).

Note: Ghost atoms need to know their velocity for this fix to act correctly. You must use the comm_modify command
to enable this, e.g.

comm_modify vel yes

Tcom is the target temperature of the centers of mass, which would be used to thermostat the non-polarizable atoms.
Tdrude is the (normally low) target temperature of the core-Drude particle pairs (dipoles). Tcom and Tdrude can be
specified as an equal-style variable. If the value is a variable, it should be specified as v_name, where name is the
variable name. In this case, the variable will be evaluated each timestep, and its value used to determine the target
temperature.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
temperature.
Like other fixes that perform thermostatting, this fix can be used with compute commands that remove a “bias” from
the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms. This is not done by default, but
only if the fix_modify command is used to assign a temperature compute to this fix that includes such a bias term. See
the doc pages for individual compute commands to determine which ones include a bias. In this case, the thermostat
works in the following manner: bias is removed from each atom, thermostatting is performed on the remaining thermal
degrees of freedom, and the bias is added back in. NOTE: this feature has not been tested.
Note: The temperature thermostatting the core-Drude particle pairs should be chosen low enough, so as to mimic as
closely as possible the self-consistent minimization. It must however be high enough, so that the dipoles can follow the
local electric field exerted by the neighboring atoms. The optimal value probably depends on the temperature of the
centers of mass and on the mass of the Drude particles.
damp_com is the characteristic time for reaching thermal equilibrium of the centers of mass. For example, a value of
100.0 means to relax the temperature of the centers of mass in a timespan of (roughly) 100 time units (tau or fs or ps
- see the units command). damp_drude is the characteristic time for reaching thermal equilibrium of the dipoles. It is
typically a few timesteps.

1206 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The number seed_com and seed_drude are positive integers. They set the seeds of the Marsaglia random number
generators used for generating the random forces on centers of mass and on the dipoles. Each processor uses the input
seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the system will not
be identical on two runs on different numbers of processors.
The keyword zero can be used to eliminate drift due to the thermostat on centers of mass. Because the random forces on
different centers of mass are independent, they do not sum exactly to zero. As a result, this fix applies a small random
force to the entire system, and the momentum of the total center of mass of the system undergoes a slow random walk.
If the keyword zero is set to yes, the total random force on the centers of mass is set exactly to zero by subtracting off
an equal part of it from each center of mass in the group. As a result, the total center of mass of a system with zero
initial momentum will not drift over time.
The actual temperatures of cores and Drude particles, in center-of-mass and relative coordinates, respectively, can be
calculated using the compute temp/drude command.

Usage example for rigid bodies in the NPT ensemble:

comm_modify vel yes

fix TEMP all langevin/drude 300. 100. 1256 1. 20. 13977 zero yes
fix NPH ATOMS rigid/nph/small molecule iso 1. 1. 500.
fix NVE DRUDES nve
compute TDRUDE all temp/drude
thermo_style custom step cpu etotal ke pe ebond ecoul elong press vol temp c_TDRUDE[1] c_
,→TDRUDE[2]

Comments:
• Drude particles should not be in the rigid group, otherwise the Drude oscillators will be frozen and the system
will lose its polarizability.
• zero yes avoids a drift of the center of mass of the system, but is a bit slower.
• Use two different random seeds to avoid unphysical correlations.
• Temperature is controlled by the fix langevin/drude, so the time-integration fixes do not thermostat. Don’t forget
to time-integrate both cores and Drude particles.
• Pressure is time-integrated only once by using nve for Drude particles and nph for atoms/cores (or vice versa).
Do not use nph for both.
• The temperatures of cores and Drude particles are calculated by compute temp/drude
• Contrary to the alternative thermostatting using Nose-Hoover thermostat fix npt and fix drude/transform, the
fix_modify command is not required here, because the fix nph computes the global pressure even if its group is
ATOMS. This is what we want. If we thermostatted ATOMS using npt, the pressure should be the global one, but
the temperature should be only that of the cores. That’s why the command fix_modify should be called in that
case.

17.70. fix langevin/drude command 1207

LAMMPS Documentation, Release stable 29Sep2021

17.70.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. Because the state of the random number generator is
not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation continues on the
same as if no restart had taken place. However, in a statistical sense, a restarted simulation should produce the same
behavior.
The fix_modify temp option is supported by this fix. You can use it to assign a temperature compute you have defined
to this fix which will be used in its thermostatting procedure, as described above. For consistency, the group used by
the compute should include the group of this fix and the Drude particles.
This fix is not invoked during energy minimization.

17.70.5 Restrictions

none

17.70.6 Related commands

fix langevin, fix drude, fix drude/transform, compute temp/drude, pair_style thole

17.70.7 Default

The option defaults are zero = no.

(Jiang) Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux, J Phys Chem Lett, 2, 87-92 (2011).

17.71 fix langevin/eff command

17.71.1 Syntax

fix ID group-ID langevin/eff Tstart Tstop damp seed keyword values ...

• ID, group-ID are documented in fix command

• langevin/eff = style name of this fix command
• Tstart,Tstop = desired temperature at start/end of run (temperature units)
• damp = damping parameter (time units)
• seed = random number seed to use for white noise (positive integer)
• zero or more keyword/value pairs may be appended
keyword = scale or tally or zero
scale values = type ratio
type = atom type (1-N)
ratio = factor by which to scale the damping coefficient
tally values = no or yes
no = do not tally the energy added/subtracted to atoms
yes = do tally the energy added/subtracted to atoms

1208 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

zero value = no or yes

no = do not set total random force to zero
yes = set total random force to zero

17.71.2 Examples

fix 3 boundary langevin/eff 1.0 1.0 10.0 699483

fix 1 all langevin/eff 1.0 1.1 10.0 48279 scale 3 1.5

17.71.3 Description

Apply a Langevin thermostat as described in (Schneider) to a group of nuclei and electrons in the electron force field
model. Used with fix nve/eff , this command performs Brownian dynamics (BD), since the total force on each atom will
have the form:
F =Fc + Ff + Fr
m
Ff = − v
damp
s
kB T m
Fr ∝
dt damp

Fc is the conservative force computed via the usual inter-particle interactions (pair_style). The Ff and Fr terms are
added by this fix on a per-particle basis.
The operation of this fix is exactly like that described by the fix langevin command, except that the thermostatting is
also applied to the radial electron velocity for electron particles.

17.71.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. Because the state of the random number generator is
not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation continues on the
same as if no restart had taken place. However, in a statistical sense, a restarted simulation should produce the same
behavior.
The fix_modify temp option is supported by this fix. You can use it to assign a temperature compute you have defined
to this fix which will be used in its thermostatting procedure, as described above. For consistency, the group used by
this fix and by the compute should be the same.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve, but only if the tally keyword to set to yes. See the thermo_style page for details.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
Note that calculation of this quantity also requires setting the tally keyword to yes.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.71. fix langevin/eff command 1209

LAMMPS Documentation, Release stable 29Sep2021

17.71.5 Restrictions

none
This fix is part of the EFF package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.

17.71.6 Related commands

fix langevin

17.71.7 Default

The option defaults are scale = 1.0 for all types and tally = no.

(Dunweg) Dunweg and Paul, Int J of Modern Physics C, 2, 817-27 (1991).

(Schneider) Schneider and Stoll, Phys Rev B, 17, 1302 (1978).

17.72 fix langevin/spin command

17.72.1 Syntax

fix ID group-ID langevin/spin T Tdamp seed

• ID, group-ID are documented in fix command

• langevin/spin = style name of this fix command
• T = desired temperature of the bath (temperature units, K in metal units)
• Tdamp = transverse magnetic damping parameter (adim)
• seed = random number seed to use for white noise (positive integer)

17.72.2 Examples

fix 2 all langevin/spin 300.0 0.01 21

17.72.3 Description

Apply a Langevin thermostat as described in (Mayergoyz) to the magnetic spins associated to the atoms. Used with fix
nve/spin, this command performs Brownian dynamics (BD). A random torque and a transverse dissipation are applied
to each spin i according to the following stochastic differential equation:

d~si 1
= ωi + ~η ) × ~si + λ ~si × (~
((~ ωi × ~si ))
dt (1 + λ2 )

with λ the transverse damping, and η a random vector. This equation is referred to as the stochastic Landau-Lifshitz-
Gilbert (sLLG) equation.

1210 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The components of η are drawn from a Gaussian probability law. Their amplitude is defined as a proportion of the
temperature of the external thermostat T (in K in metal units).
More details about this implementation are reported in (Tranchida).
Note: due to the form of the sLLG equation, this fix has to be defined just before the nve/spin fix (and after all other
magnetic fixes). As an example:

fix 1 all precession/spin zeeman 0.01 0.0 0.0 1.0

fix 2 all langevin/spin 300.0 0.01 21
fix 3 all nve/spin lattice moving

is correct, but defining a force/spin command after the langevin/spin command would give an error message.
Note: The random # seed must be a positive integer. A Marsaglia random number generator is used. Each processor
uses the input seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the
system will not be identical on two runs on different numbers of processors.

17.72.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. Because the state of the random number generator is
not saved in restart files, this means you cannot do “exact” restarts with this fix, where the simulation continues on the
same as if no restart had taken place. However, in a statistical sense, a restarted simulation should produce the same
behavior.
This fix is not invoked during energy minimization.

17.72.5 Restrictions

The langevin/spin fix is part of the SPIN package. This style is only enabled if LAMMPS was built with this package.
See the Build package page for more info.
The numerical integration has to be performed with fix nve/spin when fix langevin/spin is enabled.
This fix has to be the last defined magnetic fix before the time integration fix (e.g. fix nve/spin).

17.72.6 Related commands

fix nve/spin, fix precession/spin

17.72.7 Default

none

(Mayergoyz) I.D. Mayergoyz, G. Bertotti, C. Serpico (2009). Elsevier (2009)

(Tranchida) Tranchida, Plimpton, Thibaudeau and Thompson, Journal of Computational Physics, 372, 406-425,
(2018).

17.72. fix langevin/spin command 1211

LAMMPS Documentation, Release stable 29Sep2021

17.73 fix latte command

17.73.1 Syntax

fix ID group-ID latte peID

• ID, group-ID are documented in fix command

• latte = style name of this fix command
• peID = NULL or ID of compute used to calculate per-atom energy

17.73.2 Examples

fix dftb all latte NULL

17.73.3 Description

This fix style is a wrapper on the self-consistent charge transfer density functional based tight binding (DFTB) code
LATTE. If you download and build LATTE, it can be called as a library by LAMMPS via this fix to run dynamics or
perform energy minimization using DFTB forces and energies computed by LATTE.
LATTE is principally developed and supported by Marc Cawkwell and co-workers at Los Alamos National Laboratory
(LANL). See the full list of contributors in the src/LATTE/README file.
To use this fix, the LATTE program needs to be compiled as a library and linked with LAMMPS. LATTE can be
downloaded (or cloned) from https://github.com/lanl/LATTE. Instructions on how to download and build LATTE on
your system can be found in the lib/latte/README. Note that you can also use the “make lib-latte” command from the
LAMMPS src directory to automate this process.
Once LAMMPS is built with the LATTE package, you can run the example input scripts for molecular dynamics or
energy minimization that are found in examples/latte.
A step-by-step tutorial can be followed at: LAMMPS-LATTE tutorial
The peID argument is not yet supported by fix latte, so it must be specified as NULL. Eventually it will be used to
enable LAMMPS to calculate a Coulomb potential as an alternative to LATTE performing the calculation.

LATTE is a code for performing self-consistent charge transfer tight-binding (SC-TB) calculations of total energies
and the forces acting on atoms in molecules and solids. This tight-binding method is becoming more and more popular
and widely used in chemistry, biochemistry, material science, etc.
The SC-TB formalism is derived from an expansion of the Kohn-Sham density functional to second order in charge
fluctuations about a reference charge of overlapping atom-centered densities and bond integrals are parameterized
using a Slater-Koster tight-binding approach. This procedure, which usually is referred to as the DFTB method has
been described in detail by (Elstner) and (Finnis) and coworkers.
The work of the LATTE developers follows that of Elstner closely with respect to the physical model. However,
the development of LATTE is geared principally toward large-scale, long duration, microcanonical quantum-based
Born-Oppenheimer molecular dynamics (QMD) simulations. One of the main bottlenecks of an electronic structure
calculation is the solution of the generalized eigenvalue problem which scales with the cube of the system size O(N^3).
The Theoretical and Computer sciences divisions at Los Alamos National Laboratory have accumulated large experi-
ence addressing this issue by calculating the density matrix directly instead of using diagonalization. We typically use

1212 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

a recursive sparse Fermi-operator expansion using second-order spectral projection functions (SP2-algorithm), which
was introduced by Niklasson in 2002 (Niklasson2002), (Rubensson), (Mniszewski). When the matrices involved in
the recursive expansion are sufficiently sparse, the calculation of the density matrix scales linearly as a function of the
system size O(N).
Another important feature is the extended Lagrangian framework for Born-Oppenheimer molecular dynamics (XL-
BOMD) (Niklasson2008) (Niklasson2014), (Niklasson2017) that allows for a drastic reduction or even a complete
removal of the iterative self-consistent field optimization. Often only a single density matrix calculation per molecular
dynamics time step is required, yet total energy stability is well maintained. The SP2 and XL-BOMD techniques enables
stable linear scaling MD simulations with a very small computational overhead. This opens a number of opportunities
in many different areas of chemistry and materials science, as we now can simulate larger system sizes and longer time
scales (Cawkwell2012), (Negre2016).

17.73.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy computed by LATTE to the global
potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify energy
yes.
The fix_modify virial option is supported by this fix to add the contribution compute by LATTE to the global pressure
of the system via the compute pressure command. This can be accessed by thermodynamic output. The default setting
for this fix is fix_modify virial yes.
The fix_modify virial option is supported by this fix to add the contribution computed by LATTE to the global pressure
of the system as part of thermodynamic output. The default setting for this fix is fix_modify virial yes.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the potential energy
discussed above. The scalar value calculated by this fix is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
The DFTB forces computed by LATTE via this fix are imposed during an energy minimization, invoked by the minimize
command.

Note: If you want the potential energy associated with the DFTB forces to be included in the total potential energy of
the system (the quantity being minimized), you MUST not disable the fix_modify energy option for this fix.

17.73.5 Restrictions

This fix is part of the LATTE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
You must use metal units, as set by the units command to use this fix.
LATTE does not currently compute per-atom energy or per-atom virial contributions. So they will not show up as part
of the calculations performed by the compute pe/atom or compute stress/atom commands.
Currently, LAMMPS must be run in serial or as a single MPI task, to use this fix. This is typically not a bottleneck,
since LATTE will be doing 99% or more of the work to compute quantum-accurate forces.

17.73. fix latte command 1213

LAMMPS Documentation, Release stable 29Sep2021

Note: NEB calculations can be done using this fix using multiple replicas and running LAMMPS in parallel. However,
each replica must be run on a single MPI task. For details, see the neb command page and the -partition command-line
switch

17.73.6 Related commands

none

17.73.7 Default

none

(Elstner) M. Elstner, D. Poresag, G. Jungnickel, J. Elsner, M. Haugk, T. Frauenheim, S. Suhai, and G. Seifert, Phys.
Rev. B, 58, 7260 (1998).
(Elstner) M. Elstner, D. Poresag, G. Jungnickel, J. Elsner, M. Haugk, T. Frauenheim, S. Suhai, and G. Seifert, Phys.
Rev. B, 58, 7260 (1998).
(Finnis) M. W. Finnis, A. T. Paxton, M. Methfessel, and M. van Schilfgarde, Phys. Rev. Lett., 81, 5149 (1998).
(Mniszewski) S. M. Mniszewski, M. J. Cawkwell, M. E. Wall, J. Mohd-Yusof, N. Bock, T. C. Germann, and A. M. N.
Niklasson, J. Chem. Theory Comput., 11, 4644 (2015).
(Niklasson2002) A. M. N. Niklasson, Phys. Rev. B, 66, 155115 (2002).
(Rubensson) E. H. Rubensson, A. M. N. Niklasson, SIAM J. Sci. Comput. 36 (2), 147-170, (2014).
(Niklasson2008) A. M. N. Niklasson, Phys. Rev. Lett., 100, 123004 (2008).
(Niklasson2014) A. M. N. Niklasson and M. Cawkwell, J. Chem. Phys., 141, 164123, (2014).
(Niklasson2017) A. M. N. Niklasson, J. Chem. Phys., 147, 054103 (2017).
(Cawkwell2012) A. M. N. Niklasson, M. J. Cawkwell, Phys. Rev. B, 86 (17), 174308 (2012).
(Negre2016) C. F. A. Negre, S. M. Mniszewski, M. J. Cawkwell, N. Bock, M. E. Wall, and A. M. N. Niklasson, J.
Chem. Theory Comp., 12, 3063 (2016).

17.74 fix lb/fluid command

17.74.1 Syntax

fix ID group-ID lb/fluid nevery LBtype viscosity density keyword values ...

• ID, group-ID are documented in fix command

• lb/fluid = style name of this fix command
• nevery = update the lattice-Boltzmann fluid every this many timesteps
• LBtype = 1 to use the standard finite difference LB integrator, 2 to use the LB integrator of Ollila et al.
• viscosity = the fluid viscosity (units of mass/(time*length)).

1214 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• density = the fluid density.

• zero or more keyword/value pairs may be appended
• keyword = setArea or setGamma or scaleGamma or dx or dm or a0 or noise or calcforce or trilinear or D3Q19
or read_restart or write_restart or zwall_velocity or bodyforce or printfluid
setArea values = type node_area
type = atom type (1-N)
node_area = portion of the surface area of the composite object associated␣
,→with the particular atom type (used when the force coupling constant is set by␣

,→default).

setGamma values = gamma

gamma = user set value for the force coupling constant.
scaleGamma values = type gammaFactor
type = atom type (1-N)
gammaFactor = factor to scale the setGamma gamma value by, for the specified␣
,→atom type.

dx values = dx_LB = the lattice spacing.

dm values = dm_LB = the lattice-Boltzmann mass unit.
a0 values = a_0_real = the square of the speed of sound in the fluid.
noise values = Temperature seed
Temperature = fluid temperature.
seed = random number generator seed (positive integer)
calcforce values = N forcegroup-ID
N = output the force and torque every N timesteps
forcegroup-ID = ID of the particle group to calculate the force and torque of
trilinear values = none (used to switch from the default Peskin interpolation␣
,→stencil to the trilinear stencil).

D3Q19 values = none (used to switch from the default D3Q15, 15 velocity lattice, to␣
,→the D3Q19, 19 velocity lattice).

read_restart values = restart file = name of the restart file to use to restart a␣
,→fluid run.

write_restart values = N = write a restart file every N MD timesteps.

zwall_velocity values = velocity_bottom velocity_top = velocities along the␣
,→y-direction of the bottom and top walls (located at z=zmin and z=zmax).

bodyforce values = bodyforcex bodyforcey bodyforcez = the x,y and z components of a␣

,→constant body force added to the fluid.

printfluid values = N = print the fluid density and velocity at each grid point␣
,→every N timesteps.

17.74. fix lb/fluid command 1215

LAMMPS Documentation, Release stable 29Sep2021

17.74.2 Examples

fix 1 all lb/fluid 1 2 1.0 1.0 setGamma 13.0 dx 4.0 dm 10.0 calcforce sphere1
fix 1 all lb/fluid 1 1 1.0 0.0009982071 setArea 1 1.144592082 dx 2.0 dm 0.3 trilinear␣
,→noise 300.0 8979873

17.74.3 Description

Implement a lattice-Boltzmann fluid on a uniform mesh covering the LAMMPS simulation domain. The MD particles
described by group-ID apply a velocity dependent force to the fluid.
The lattice-Boltzmann algorithm solves for the fluid motion governed by the Navier Stokes equations,

∂t ρ + ∂β (ρuβ ) =0
∂t (ρuα ) + ∂β (ρuα uβ ) =∂β σαβ + Fα + ∂β (ηαβγν ∂γ uν )

with,
 
2
ηαβγν = η δαγ δβν + δαν δβγ − δαβ δγν + Λδαβ δγν
3
where ρ is the fluid density, u is the local fluid velocity, σ is the stress tensor, F is a local external force, and η and Λ
are the shear and bulk viscosities respectively. Here, we have implemented

σαβ = −Pαβ = −ρa0 δαβ

1 dx 2
with a0 set to 3 dt by default.
The algorithm involves tracking the time evolution of a set of partial distribution functions which evolve according to
a velocity discretized version of the Boltzmann equation,
1
(∂t + eiα ∂α ) fi = − (fi − fieq ) + Wi
τ
where the first term on the right hand side represents a single time relaxation towards the equilibrium distribution
function, and τ is a parameter physically related to the viscosity. On a technical note, we have implemented a 15
velocity model (D3Q15) as default; however, the user can switch to a 19 velocity model (D3Q19) through the use of
the D3Q19 keyword. This fix provides the user with the choice of two algorithms to solve this equation, through the
specification of the keyword LBtype. If LBtype is set equal to 1, the standard finite difference LB integrator is used. If
LBtype is set equal to 2, the algorithm of Ollila et al. is used.
Physical variables are then defined in terms of moments of the distribution functions,
X
ρ= fi
i
X
ρuα = fi eiα
i

Full details of the lattice-Boltzmann algorithm used can be found in Mackay et al..
The fluid is coupled to the MD particles described by group-ID through a velocity dependent force. The contribution
to the fluid force on a given lattice mesh site j due to MD particle α is calculated as:

Fjα = γ (vn − uf ) ζjα

where vn is the velocity of the MD particle, uf is the fluid velocity interpolated to the particle location, and γ is the
force coupling constant. ζ is a weight assigned to the grid point, obtained by distributing the particle to the nearest

1216 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

lattice sites. For this, the user has the choice between a trilinear stencil, which provides a support of 8 lattice sites, or
the immersed boundary method Peskin stencil, which provides a support of 64 lattice sites. While the Peskin stencil
is seen to provide more stable results, the trilinear stencil may be better suited for simulation of objects close to walls,
due to its smaller support. Therefore, by default, the Peskin stencil is used; however the user may switch to the trilinear
stencil by specifying the keyword, trilinear.
By default, the force coupling constant, γ, is calculated according to
 
2mu mv 1
γ=
mu + mv ∆tcollision

Here, mv is the mass of the MD particle, mu is a representative fluid mass at the particle location, and ∆tcollision is a
collision time, chosen such that Δtcollision
τ
= 1 (see Mackay and Denniston for full details). In order to calculate mu ,
the fluid density is interpolated to the MD particle location, and multiplied by a volume, node_area * dxLB , where
node_area represents the portion of the surface area of the composite object associated with a given MD particle. By
default, node_area is set equal to dx2LB ; however specific values for given atom types can be set using the setArea
keyword.
The user also has the option of specifying their own value for the force coupling constant, for all the MD particles
associated with the fix, through the use of the setGamma keyword. This may be useful when modelling porous particles.
See Mackay et al. for a detailed description of the method by which the user can choose an appropriate γ value.

Note: while this fix applies the force of the particles on the fluid, it does not apply the force of the fluid to the particles.
When the force coupling constant is set using the default method, there is only one option to include this hydrodynamic
force on the particles, and that is through the use of the lb/viscous fix. This fix adds the hydrodynamic force to the
total force acting on the particles, after which any of the built-in LAMMPS integrators can be used to integrate the
particle motion. However, if the user specifies their own value for the force coupling constant, as mentioned in Mackay
et al., the built-in LAMMPS integrators may prove to be unstable. Therefore, we have included our own integrators fix
lb/rigid/pc/sphere, and fix lb/pc, to solve for the particle motion in these cases. These integrators should not be used
with the lb/viscous fix, as they add hydrodynamic forces to the particles directly. In addition, they can not be used if
the force coupling constant has been set the default way.

Note: if the force coupling constant is set using the default method, and the lb/viscous fix is NOT used to add the
hydrodynamic force to the total force acting on the particles, this physically corresponds to a situation in which an
infinitely massive particle is moving through the fluid (since collisions between the particle and the fluid do not act to
change the particle’s velocity). Therefore, the user should set the mass of the particle to be significantly larger than the
mass of the fluid at the particle location, in order to approximate an infinitely massive particle (see the dragforce test
run for an example).

Inside the fix, parameters are scaled by the lattice-Boltzmann timestep, dtLB , grid spacing, dxLB , and mass unit,
dmLB . dtLB is set equal to nevery · dtM D , where dtM D is the MD timestep. By default, dmLB is set equal to 1.0,
and dxLB is chosen so that dt
τ
2 is approximately equal to 1. However, the user has the option of specifying their
3ηdt
= ρdx
own values for dmLB , and dxLB , by using the optional keywords dm, and dx respectively.

Note: Care must be taken when choosing both a value for dxLB , and a simulation domain size. This fix uses the
same subdivision of the simulation domain among processors as the main LAMMPS program. In order to uniformly
cover the simulation domain with lattice sites, the lengths of the individual LAMMPS sub-domains must all be evenly
divisible by dxLB . If the simulation domain size is cubic, with equal lengths in all dimensions, and the default value
for dxLB is used, this will automatically be satisfied.

17.74. fix lb/fluid command 1217

LAMMPS Documentation, Release stable 29Sep2021

Physical parameters describing the fluid are specified through viscosity, density, and a0. If the force coupling constant
is set the default way, the surface area associated with the MD particles is specified using the setArea keyword. If
the user chooses to specify a value for the force coupling constant, this is set using the setGamma keyword. These
parameters should all be given in terms of the mass, distance, and time units chosen for the main LAMMPS run, as
they are scaled by the LB timestep, lattice spacing, and mass unit, inside the fix.

The setArea keyword allows the user to associate a surface area with a given atom type. For example if a spherical
composite object of radius R is represented as a spherical shell of N evenly distributed MD particles, all of the same
2
type, the surface area per particle associated with that atom type should be set equal to 4πR
N . This keyword should
only be used if the force coupling constant, γ, is set the default way.
The setGamma keyword allows the user to specify their own value for the force coupling constant, γ, instead of using
the default value.
The scaleGamma keyword should be used in conjunction with the setGamma keyword, when the user wishes to specify
different γ values for different atom types. This keyword allows the user to scale the setGamma γ value by a factor,
gammaFactor, for a given atom type.
The dx keyword allows the user to specify a value for the LB grid spacing.
The dm keyword allows the user to specify the LB mass unit.
If the a0 keyword is used, the value specified is used for the square of the speed of sound in the fluid. If this keyword is
 2
not present, the speed of sound squared is set equal to 13 dx LB
dtLB . Setting a0 > ( dx
dtLB ) is not allowed, as this may
LB 2

lead to instabilities.
If the noise keyword is used, followed by a positive temperature value, and a positive integer random number seed, a
thermal lattice-Boltzmann algorithm is used. If LBtype is set equal to 1 (i.e. the standard LB integrator is chosen), the
thermal LB algorithm of Adhikari et al. is used; however if LBtype is set equal to 2 both the LB integrator, and thermal
LB algorithm described in Ollila et al. are used.
If the calcforce keyword is used, both the fluid force and torque acting on the specified particle group are printed to the
screen every N timesteps.
If the keyword trilinear is used, the trilinear stencil is used to interpolate the particle nodes onto the fluid mesh. By
default, the immersed boundary method, Peskin stencil is used. Both of these interpolation methods are described in
Mackay et al..
If the keyword D3Q19 is used, the 19 velocity (D3Q19) lattice is used by the lattice-Boltzmann algorithm. By default,
the 15 velocity (D3Q15) lattice is used.
If the keyword write_restart is used, followed by a positive integer, N, a binary restart file is printed every N LB
timesteps. This restart file only contains information about the fluid. Therefore, a LAMMPS restart file should also be
written in order to print out full details of the simulation.

Note: When a large number of lattice grid points are used, the restart files may become quite large.

In order to restart the fluid portion of the simulation, the keyword read_restart is specified, followed by the name of
the binary lb_fluid restart file to be used.
If the zwall_velocity keyword is used y-velocities are assigned to the lower and upper walls. This keyword requires
the presence of walls in the z-direction. This is set by assigning fixed boundary conditions in the z-direction. If fixed
boundary conditions are present in the z-direction, and this keyword is not used, the walls are assumed to be stationary.
If the bodyforce keyword is used, a constant body force is added to the fluid, defined by it’s x, y and z components.
If the printfluid keyword is used, followed by a positive integer, N, the fluid densities and velocities at each lattice site
are printed to the screen every N timesteps.

1218 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

For further details, as well as descriptions and results of several test runs, see Mackay et al.. Please include a citation
to this paper if the lb_fluid fix is used in work contributing to published research.

17.74.4 Restart, fix_modify, output, run start/stop, minimize info

Due to the large size of the fluid data, this fix writes it’s own binary restart files, if requested, independent of the main
LAMMPS binary restart files; no information about lb_fluid is written to the main LAMMPS binary restart files.
None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access
by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.74.5 Restrictions

This fix is part of the LATBOLTZ package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix can only be used with an orthogonal simulation domain.
Walls have only been implemented in the z-direction. Therefore, the boundary conditions, as specified via the main
LAMMPS boundary command must be periodic for x and y, and either fixed or periodic for z. Shrink-wrapped boundary
conditions are not permitted with this fix.
This fix must be used before any of fix lb/viscous, fix lb/momentum, fix lb/rigid/pc/sphere, and/ or fix lb/pc , as the
fluid needs to be initialized before any of these routines try to access its properties. In addition, in order for the
hydrodynamic forces to be added to the particles, this fix must be used in conjunction with the lb/viscous fix if the force
coupling constant is set by default, or either the lb/viscous fix or one of the lb/rigid/pc/sphere or lb/pc integrators, if
the user chooses to specify their own value for the force coupling constant.

17.74.6 Related commands

fix lb/viscous, fix lb/momentum, fix lb/rigid/pc/sphere, fix lb/pc

17.74.7 Default

By default, the force coupling constant is set according to

 
2mu mv 1
γ=
mu + mv ∆tcollision

and an area of dx2LB per node, used to calculate the fluid mass at the particle node location, is assumed.
 2
dx is chosen such that dtτLB = 3ηdt LB
ρdx2LB
is approximately equal to 1. dm is set equal to 1.0. a0 is set equal to 1 dxLB
3 dtLB .
The Peskin stencil is used as the default interpolation method. The D3Q15 lattice is used for the lattice-Boltzmann
algorithm. If walls are present, they are assumed to be stationary.

(Ollila et al.) Ollila, S.T.T., Denniston, C., Karttunen, M., and Ala-Nissila, T., Fluctuating lattice-Boltzmann model
for complex fluids, J. Chem. Phys. 134 (2011) 064902.

17.74. fix lb/fluid command 1219

LAMMPS Documentation, Release stable 29Sep2021

(Mackay et al.) Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS
through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031.
(Mackay and Denniston) Mackay, F. E., and Denniston, C., Coupling MD particles to a lattice-Boltzmann fluid
through the use of conservative forces, J. Comput. Phys. 237 (2013) 289-298.
(Adhikari et al.) Adhikari, R., Stratford, K., Cates, M. E., and Wagner, A. J., Fluctuating lattice Boltzmann, Europhys.
Lett. 71 (2005) 473-479.

17.75 fix lb/momentum command

17.75.1 Syntax

fix ID group-ID lb/momentum nevery keyword values ...

• ID, group-ID are documented in the fix command

• lb/momentum = style name of this fix command
• nevery = adjust the momentum every this many timesteps
• zero or more keyword/value pairs may be appended
• keyword = linear
linear values = xflag yflag zflag
xflag,yflag,zflag = 0/1 to exclude/include each dimension.

17.75.2 Examples

fix 1 sphere lb/momentum

fix 1 all lb/momentum linear 1 1 0

17.75.3 Description

This fix is based on the fix momentum command, and was created to be used in place of that command, when a lattice-
Boltzmann fluid is present.
Zero the total linear momentum of the system, including both the atoms specified by group-ID and the lattice-Boltzmann
fluid every nevery timesteps. This is accomplished by adjusting the particle velocities and the fluid velocities at each
lattice site.

Note: This fix only considers the linear momentum of the system.

By default, the subtraction is performed for each dimension. This can be changed by specifying the keyword linear,
along with a set of three flags set to 0/1 in order to exclude/ include the corresponding dimension.

1220 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.75.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.75.5 Restrictions

Can only be used if a lattice-Boltzmann fluid has been created via the fix lb/fluid command, and must come after this
command.
This fix is part of the LATBOLTZ package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.75.6 Related commands

fix momentum, fix lb/fluid

17.75.7 Default

Zeros the total system linear momentum in each dimension.

17.76 fix lb/pc command

17.76.1 Syntax

fix ID group-ID lb/pc

• ID, group-ID are documented in the fix command

• lb/pc = style name of this fix command

17.76.2 Examples

fix 1 all lb/pc

17.76.3 Description

Update the positions and velocities of the individual particles described by group-ID, experiencing velocity-dependent
hydrodynamic forces, using the integration algorithm described in Mackay et al.. This integration algorithm should
only be used if a user-specified value for the force-coupling constant used in fix lb/fluid has been set; do not use this
integration algorithm if the force coupling constant has been set by default.

17.76. fix lb/pc command 1221

LAMMPS Documentation, Release stable 29Sep2021

17.76.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.76.5 Restrictions

This fix is part of the LATBOLTZ package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
Can only be used if a lattice-Boltzmann fluid has been created via the fix lb/fluid command, and must come after this
command.

17.76.6 Related commands

fix lb/fluid fix lb/rigid/pc/sphere

17.76.7 Default

none.

(Mackay et al.) Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS
through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031.

17.77 fix lb/rigid/pc/sphere command

17.77.1 Syntax

fix ID group-ID lb/rigid/pc/sphere bodystyle args keyword values ...

• ID, group-ID are documented in fix command

• lb/rigid/pc/sphere = style name of this fix command
• bodystyle = single or molecule or group
single args = none
molecule args = none
group args = N groupID1 groupID2 ...
N = # of groups
• zero or more keyword/value pairs may be appended
• keyword = force or torque or innerNodes
force values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass force is active
torque values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass torque is active

1222 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

innerNodes values = innergroup-ID

innergroup-ID = ID of the atom group which does not experience a hydrodynamic␣
,→force from the lattice-Boltzmann fluid

17.77.2 Examples

fix 1 spheres lb/rigid/pc/sphere

fix 1 all lb/rigid/pc/sphere force 1 0 0 innerNodes ForceAtoms

17.77.3 Description

This fix is based on the fix rigid command, and was created to be used in place of that fix, to integrate the equations
of motion of spherical rigid bodies when a lattice-Boltzmann fluid is present with a user-specified value of the force-
coupling constant. The fix uses the integration algorithm described in Mackay et al. to update the positions, velocities,
and orientations of a set of spherical rigid bodies experiencing velocity dependent hydrodynamic forces. The spherical
bodies are assumed to rotate as solid, uniform density spheres, with moments of inertia calculated using the combined
sum of the masses of all the constituent particles (which are assumed to be point particles).

By default, all of the atoms that this fix acts on experience a hydrodynamic force due to the presence of the lattice-
Boltzmann fluid. However, the innerNodes keyword allows the user to specify atoms belonging to a rigid object which
do not interact with the lattice-Boltzmann fluid (i.e. these atoms do not feel a hydrodynamic force from the lattice-
Boltzmann fluid). This can be used to distinguish between atoms on the surface of a non-porous object, and those on
the inside.
This feature can be used, for example, when implementing a hard sphere interaction between two spherical objects.
Instead of interactions occurring between the particles on the surfaces of the two spheres, it is desirable simply to place
an atom at the center of each sphere, which does not contribute to the hydrodynamic force, and have these central atoms
interact with one another.

Apart from the features described above, this fix is very similar to the rigid fix (although it includes fewer optional
arguments, and assumes the constituent atoms are point particles); see fix rigid for a complete documentation.

17.77.4 Restart, fix_modify, output, run start/stop, minimize info

No information about the rigid and rigid/nve fixes are written to binary restart files.
The fix_modify virial option is supported by this fix to add the contribution due to the added forces on atoms to both
the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands.
The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial yes.
Similar to the fix rigid command: The rigid fix computes a global scalar which can be accessed by various output
commands. The scalar value calculated by these fixes is “intensive”. The scalar is the current temperature of the
collection of rigid bodies. This is averaged over all rigid bodies and their translational and rotational degrees of freedom.
The translational energy of a rigid body is 1/2 m v^2, where m = total mass of the body and v = the velocity of its
center of mass. The rotational energy of a rigid body is 1/2 I w^2, where I = the moment of inertia tensor of the body
and w = its angular velocity. Degrees of freedom constrained by the force and torque keywords are removed from this
calculation.
All of these fixes compute a global array of values which can be accessed by various output commands. The number
of rows in the array is equal to the number of rigid bodies. The number of columns is 15. Thus for each rigid body,

17.77. fix lb/rigid/pc/sphere command 1223

LAMMPS Documentation, Release stable 29Sep2021

15 values are stored: the xyz coords of the center of mass (COM), the xyz components of the COM velocity, the xyz
components of the force acting on the COM, the xyz components of the torque acting on the COM, and the xyz image
flags of the COM, which have the same meaning as image flags for atom positions (see the “dump” command). The
force and torque values in the array are not affected by the force and torque keywords in the fix rigid command; they
reflect values before any changes are made by those keywords.
The ordering of the rigid bodies (by row in the array) is as follows. For the single keyword there is just one rigid body.
For the molecule keyword, the bodies are ordered by ascending molecule ID. For the group keyword, the list of group
IDs determines the ordering of bodies.
The array values calculated by these fixes are “intensive”, meaning they are independent of the number of atoms in the
simulation.
No parameter of these fixes can be used with the start/stop keywords of the run command. These fixes are not invoked
during energy minimization.

17.77.5 Restrictions

This fix is part of the LATBOLTZ package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
Can only be used if a lattice-Boltzmann fluid has been created via the fix lb/fluid command, and must come after this
command. Should only be used if the force coupling constant used in fix lb/fluid has been set by the user; this integration
fix cannot be used if the force coupling constant is set by default.

17.77.6 Related commands

fix lb/fluid, fix lb/pc

17.77.7 Default

The defaults are force * on on on, and torque * on on on.

(Mackay et al.) Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS
through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031.

17.78 fix lb/viscous command

17.78.1 Syntax

fix ID group-ID lb/viscous

• ID, group-ID are documented in fix command

• lb/viscous = style name of this fix command

1224 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.78.2 Examples

fix 1 flow lb/viscous

17.78.3 Description

This fix is similar to the fix viscous command, and is to be used in place of that command when a lattice-Boltzmann
fluid is present, and the user wishes to integrate the particle motion using one of the built in LAMMPS integrators.
This fix adds a force, F = - Gamma*(velocity-fluid_velocity), to each atom, where Gamma is the force coupling constant
described in the fix lb/fluid command (which applies an equal and opposite force to the fluid).

Note: This fix should only be used in conjunction with one of the built in LAMMPS integrators; it should not be used
with the fix lb/pc or fix lb/rigid/pc/sphere integrators, which already include the hydrodynamic forces. These latter fixes
should only be used if the force coupling constant has been set by the user (instead of using the default value); if the
default force coupling value is used, then this fix provides the only method for adding the hydrodynamic forces to the
particles.

For further details, as well as descriptions and results of several test runs, see Mackay et al.. Please include a citation
to this paper if this fix is used in work contributing to published research.

17.78.4 Restart, fix_modify, output, run start/stop, minimize info

As described in the fix viscous documentation:

“No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command. This fix
should only be used with damped dynamics minimizers that allow for non-conservative forces. See the min_style
command for details.”

17.78.5 Restrictions

This fix is part of the LATBOLTZ package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
Can only be used if a lattice-Boltzmann fluid has been created via the fix lb/fluid command, and must come after this
command.
This fix should not be used if either the fix lb/pc or fix lb/rigid/pc/sphere integrator is used.

17.78. fix lb/viscous command 1225

LAMMPS Documentation, Release stable 29Sep2021

17.78.6 Related commands

fix lb/fluid, fix lb/pc, fix lb/rigid/pc/sphere

17.78.7 Default

none

(Mackay et al.) Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS
through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031.

17.79 fix lineforce command

17.79.1 Syntax

fix ID group-ID lineforce x y z

• ID, group-ID are documented in fix command

• lineforce = style name of this fix command
• x y z = direction of line as a 3-vector

17.79.2 Examples

fix hold boundary lineforce 0.0 1.0 1.0

17.79.3 Description

Adjust the forces on each atom in the group so that only the component of force along the linear direction specified by
the vector (x,y,z) remains. This is done by subtracting out components of force in the plane perpendicular to the line.
If the initial velocity of the atom is 0.0 (or along the line), then it should continue to move along the line thereafter.

17.79.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command.

1226 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.79.5 Restrictions

none

17.79.6 Related commands

fix planeforce

17.79.7 Default

none

17.80 fix manifoldforce command

17.80.1 Syntax

fix ID group-ID manifoldforce manifold manifold-args ...

• ID, group-ID are documented in fix command

• manifold = name of the manifold
• manifold-args = parameters for the manifold

17.80.2 Examples

fix constrain all manifoldforce sphere 5.0

17.80.3 Description

This fix subtracts each time step from the force the component along the normal of the specified manifold. This can
be used in combination with minimize to remove overlap between particles while keeping them (roughly) constrained
to the given manifold, e.g. to set up a run with fix nve/manifold/rattle. I have found that only hftn and quickmin with a
very small time step perform adequately though.

17.80.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is invoked during energy minimization.

17.80. fix manifoldforce command 1227

LAMMPS Documentation, Release stable 29Sep2021

17.80.5 Restrictions

This fix is part of the MANIFOLD package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
Only use this with min_style hftn or min_style quickmin. If not, the constraints will not be satisfied very well at all. A
warning is generated if the min_style is incompatible but no error.

17.80.6 Related commands

fix nve/manifold/rattle, fix nvt/manifold/rattle

17.81 fix mdi/engine command

17.81.1 Syntax

fix ID group-ID mdi/engine

• ID, group-ID are documented in fix command

• mdi/engine = style name of this fix command

17.81.2 Examples

fix 1 all mdi/engine

17.81.3 Description

This fix is used along with the mdi/engine command to enable LAMMPS to use the MDI Library to run as an MDI
engine. The fix provides hooks that enable MDI driver codes to communicate with LAMMPS at various points within
a LAMMPS timestep.
It is not generally necessary to add this fix to a LAMMPS input file, even when using the mdi/engine command. If the
mdi/engine command is executed and this fix is not present, it will automatically be added and applied as a new fix for
all atoms for the duration of the command. Thus it is only necessary to add this fix to an input file when you want to
modify the group-ID or the ordering of this fix relative to other fixes in the input script.
For more information about running LAMMPS as an MDI engine, see the mdi/engine command and the Howto mdi
doc page.

1228 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.81.4 Restrictions

This command is part of the MDI package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.81.5 Related commands

mdi/engine

17.81.6 Default

none

17.82 fix meso/move command

17.82.1 Syntax

fix ID group-ID meso/move style args keyword values ...

• ID, group-ID are documented in fix command

• meso/move = style name of this fix command
• style = linear or wiggle or rotate or variable
linear args = Vx Vy Vz
Vx,Vy,Vz = components of velocity vector (velocity units), any component can be␣
,→specified as NULL

wiggle args = Ax Ay Az period

Ax,Ay,Az = components of amplitude vector (distance units), any component can be␣
,→specified as NULL

period = period of oscillation (time units)

rotate args = Px Py Pz Rx Ry Rz period
Px,Py,Pz = origin point of axis of rotation (distance units)
Rx,Ry,Rz = axis of rotation vector
period = period of rotation (time units)
variable args = v_dx v_dy v_dz v_vx v_vy v_vz
v_dx,v_dy,v_dz = 3 variable names that calculate x,y,z displacement as function␣
,→of time, any component can be specified as NULL

v_vx,v_vy,v_vz = 3 variable names that calculate x,y,z velocity as function of␣

,→time, any component can be specified as NULL

• zero or more keyword/value pairs may be appended

• keyword = units
units value = box or lattice

17.82. fix meso/move command 1229

LAMMPS Documentation, Release stable 29Sep2021

17.82.2 Examples

fix 1 boundary meso/move wiggle 3.0 0.0 0.0 1.0 units box
fix 2 boundary meso/move rotate 0.0 0.0 0.0 0.0 0.0 1.0 5.0
fix 2 boundary meso/move variable v_myx v_myy NULL v_VX v_VY NULL

17.82.3 Description

Perform updates of position, velocity, internal energy and local density for mesoscopic particles in the group each
timestep using the specified settings or formulas, without regard to forces on the particles. This can be useful for
boundary, solid bodies or other particles, whose movement can influence nearby particles.
The operation of this fix is exactly like that described by the fix move command, except that particles’ density, internal
energy and extrapolated velocity are also updated.

Note: The particles affected by this fix should not be time integrated by other fixes (e.g. fix sph, fix sph/stationary),
since that will change their positions and velocities twice.

Note: As particles move due to this fix, they will pass through periodic boundaries and be remapped to the other side
of the simulation box, just as they would during normal time integration (e.g. via the fix sph command). It is up to you
to decide whether periodic boundaries are appropriate with the kind of particle motion you are prescribing with this
fix.

Note: As discussed below, particles are moved relative to their initial position at the time the fix is specified. These
initial coordinates are stored by the fix in “unwrapped” form, by using the image flags associated with each particle.
See the dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the read_data
command for a discussion of image flags and how they are set for each particle. You can reset the image flags (e.g. to
0) before invoking this fix by using the set image command.

The linear style moves particles at a constant velocity, so that their position X = (x,y,z) as a function of time is given
in vector notation as
X(t) = X0 + V * delta
where X0 = (x0,y0,z0) is their position at the time the fix is specified, V is the specified velocity vector with components
(Vx,Vy,Vz), and delta is the time elapsed since the fix was specified. This style also sets the velocity of each particle to V
= (Vx,Vy,Vz). If any of the velocity components is specified as NULL, then the position and velocity of that component
is time integrated the same as the fix sph command would perform, using the corresponding force component on the
particle.
Note that the linear style is identical to using the variable style with an equal-style variable that uses the vdisplace()
function. E.g.

variable V equal 10.0

variable x equal vdisplace(0.0,$V)
fix 1 boundary move variable v_x NULL NULL v_V NULL NULL

The wiggle style moves particles in an oscillatory fashion, so that their position X = (x,y,z) as a function of time is given
in vector notation as

1230 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

X(t) = X0 + A sin(omega*delta)
where X0 = (x0,y0,z0) is their position at the time the fix is specified, A is the specified amplitude vector with compo-
nents (Ax,Ay,Az), omega is 2 PI / period, and delta is the time elapsed since the fix was specified. This style also sets
the velocity of each particle to the time derivative of this expression. If any of the amplitude components is specified
as NULL, then the position and velocity of that component is time integrated the same as the fix sph command would
perform, using the corresponding force component on the particle.
Note that the wiggle style is identical to using the variable style with equal-style variables that use the swiggle() and
cwiggle() functions. E.g.

variable A equal 10.0

variable T equal 5.0
variable omega equal 2.0*PI/$T
variable x equal swiggle(0.0,$A,$T)
variable v equal v_omega*($A-cwiggle(0.0,$A,$T))
fix 1 boundary move variable v_x NULL NULL v_v NULL NULL

The rotate style rotates particles around a rotation axis R = (Rx,Ry,Rz) that goes through a point P = (Px,Py,Pz). The
period of the rotation is also specified. The direction of rotation for the particles around the rotation axis is consistent
with the right-hand rule: if your right-hand thumb points along R, then your fingers wrap around the axis in the direction
of rotation.
This style also sets the velocity of each particle to (omega cross Rperp) where omega is its angular velocity around the
rotation axis and Rperp is a perpendicular vector from the rotation axis to the particle.
The variable style allows the position and velocity components of each particle to be set by formulas specified via the
variable command. Each of the 6 variables is specified as an argument to the fix as v_name, where name is the variable
name that is defined elsewhere in the input script.
Each variable must be of either the equal or atom style. Equal-style variables compute a single numeric quantity, that
can be a function of the timestep as well as of other simulation values. Atom-style variables compute a numeric quantity
for each particle, that can be a function per-atom quantities, such as the particle’s position, as well as of the timestep
and other simulation values. Note that this fix stores the original coordinates of each particle (see note below) so that
per-atom quantity can be used in an atom-style variable formula. See the variable command for details.
The first 3 variables (v_dx,v_dy,v_dz) specified for the variable style are used to calculate a displacement from the
particle’s original position at the time the fix was specified. The second 3 variables (v_vx,v_vy,v_vz) specified are
used to compute a velocity for each particle.
Any of the 6 variables can be specified as NULL. If both the displacement and velocity variables for a particular x,y,z
component are specified as NULL, then the position and velocity of that component is time integrated the same as
the fix sph command would perform, using the corresponding force component on the particle. If only the velocity
variable for a component is specified as NULL, then the displacement variable will be used to set the position of the
particle, and its velocity component will not be changed. If only the displacement variable for a component is specified
as NULL, then the velocity variable will be used to set the velocity of the particle, and the position of the particle will
be time integrated using that velocity.
The units keyword determines the meaning of the distance units used to define the linear velocity and wiggle amplitude
and rotate origin. This setting is ignored for the variable style. A box value selects standard units as defined by the
units command, e.g. velocity in Angstroms/fs and amplitude and position in Angstroms for units = real. A lattice
value means the velocity units are in lattice spacings per time and the amplitude and position are in lattice spacings.
The lattice command must have been previously used to define the lattice spacing. Each of these 3 quantities may be
dependent on the x,y,z dimension, since the lattice spacings can be different in x,y,z.

17.82. fix meso/move command 1231

LAMMPS Documentation, Release stable 29Sep2021

17.82.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the original coordinates of moving particles to binary restart files, as well as the initial timestep, so that
the motion can be continuous in a restarted simulation. See the read_restart command for info on how to re-specify a
fix in an input script that reads a restart file, so that the operation of the fix continues in an uninterrupted fashion.

Note: Because the move positions are a function of the current timestep and the initial timestep, you cannot reset the
timestep to a different value after reading a restart file, if you expect a fix move command to work in an uninterrupted
fashion.

None of the fix_modify options are relevant to this fix.

This fix produces a per-atom array which can be accessed by various output commands. The number of columns for
each atom is 3, and the columns store the original unwrapped x,y,z coords of each particle. The per-atom values can
be accessed on any timestep.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.82.5 Restrictions

This fix is part of the DPD-SMOOTH package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.
This fix requires that atoms store density and internal energy as defined by the atom_style sph command.
All particles in the group must be mesoscopic SPH/SDPD particles.

17.82.6 Related commands

fix move, fix sph, displace_atoms

17.82.7 Default

The option default is units = lattice.

17.83 fix_modify AtC commands

17.83.1 fix_modify AtC add_molecule command

Syntax

fix_modify <AtC fixID> add_molecule <small|large> <tag> <group-ID>

• AtC fixID = ID of fix atc instance

• add_molecule = name of the AtC sub-command
• small or large = can be small if molecule size < cutoff radius, must be large otherwise
• tag = tag for tracking a molecule

1232 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• group-ID = LAMMPS defined group-ID

Examples

group WATERGROUP type 1 2

fix_modify AtC add_molecule small water WATERGROUP

Description

Associates a tag with all molecules corresponding to a specified group.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC add_species
• fix_modify AtC remove_species
• fix_modify AtC remove_molecule

Default

None.

17.83.2 fix_modify AtC add_species command

Syntax

fix_modify <AtC fixID> add_species <tag> <group|type> <ID>

• AtC fixID = ID of fix atc instance

• add_species = name of the AtC sub-command
• tag = tag for tracking a species
• group or type = LAMMPS defined group or type of atoms
• ID = name of group or type number

17.83. fix_modify AtC commands 1233

LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC add_species gold type 1

group GOLDGROUP type 1
fix_modify AtC add_species gold group GOLDGROUP

Description

Associates a tag with all atoms of a specified type or within a specified group.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC add_molecule
• fix_modify AtC remove_species
• fix_modify AtC remove_molecule

Default

None.

17.83.3 fix_modify AtC atom_element_map command

Syntax

fix_modify <AtC fixID> atom_element_map <eulerian|lagrangian> [<frequency>]

• AtC fixID = ID of fix atc instance

• atom_element_map = name of the AtC sub-command
• eulerian or lagrangian = frame of reference
• frequency = frequency of updating atom-to-continuum maps based on the current configuration - (only for eule-
rian)

1234 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC atom_element_map eulerian 100

Description

Changes frame of reference from eulerian to lagrangian or vice versa and sets the frequency for which the map from
atoms to elements is reformed and all the attendant data is recalculated.

Restrictions

Cannot change map type after initialization.

Related AtC commands

• fix_modify AtC command overview

Default

lagrangian

17.83.4 fix_modify AtC atom_weight command

Syntax

fix_modify <AtC fixID> atom_weight <method> <args>

• AtC fixID = ID of fix atc instance

• atom_weight = name of the AtC sub-command
• method = constant or lattice or element or region or group or read_in
– constant <group-ID> <value>: atoms in specified group are assigned the constant value given
– lattice: volume per atom for specified lattice type (e.g. fcc) and parameter
– element: element volume divided among atoms within element
– region: volume per atom determined based on the atom count in the MD regions and their volumes. Note:
meaningful only if atoms completely fill all the regions.
– group: volume per atom determined based on the atom count in a group and its volume
– node: (undocumented)
– node_element: (undocumented)
– read_in<filename>: list of values for atoms are read-in from specified file

17.83. fix_modify AtC commands 1235

LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC atom_weight constant myatoms 11.8

fix_modify AtC atom_weight lattice
fix_modify AtC atom_weight read-in atm_wt_file.txt

Description

Command for assigning the value of atomic weights used for atomic integration in atom-continuum coupled simula-
tions.

Restrictions

The use of the lattice option requires a lattice type and parameter is already specified.

Related AtC commands

• fix_modify AtC command overview

Default

lattice

17.83.5 fix_modify AtC atomic_charge command

Syntax

fix_modify <AtC fixID> <include|omit> atomic_charge

• AtC fixID = ID of fix atc instance

• include or omit = switch to activate/deactivate inclusion of intrinsic atomic charge in ATC
• atomic_charge = name of the AtC sub-command

Examples

fix_modify AtC include atomic_charge

1236 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Description

Determines whether AtC tracks the total charge as a finite element field.

Restrictions

Required for: electrostatics

Related AtC commands

• fix_modify AtC command overview

Default

If the atom charge is defined, default is on, otherwise default is off.

17.83.6 fix_modify AtC boundary_dynamics command

Syntax

fix_modify <AtC fixID> boundary_dynamics <on|damped_harmonic|prescribed|coupled|none>

• AtC fixID = ID of fix atc instance

• boundary_dynamics = name of the AtC sub-command
• on or damped_harmonic prescribed coupled none

Description

Sets different schemes for controlling boundary atoms. on will integrate the boundary atoms using the velocity-verlet
algorithm. damped_harmonic uses a mass/spring/dashpot for the boundary atoms with added arguments of the damping
and spring constants followed by the ratio of the boundary type mass to the desired mass. prescribed forces the boundary
atoms to follow the finite element displacement. coupled does the same.

Restrictions

Boundary atoms must be specified. When using swaps between internal and boundary atoms, the initial configuration
must have already correctly partitioned the two.

17.83. fix_modify AtC commands 1237

LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

Default

prescribed on

17.83.7 fix_modify AtC boundary_faceset command

Syntax

fix_modify <AtC fixID> boundary_faceset <is|add> <faceset_name>

• AtC fixID = ID of fix atc instance

• boundary_faceset = name of the AtC sub-command
• is or add = select whether to select or add a faceset
• faceset_name = name of the faceset

Examples

fix_modify AtC boundary_faceset is obndy

Description

This command species the faceset name when using a faceset to compute the MD/FE boundary fluxes. The faceset
must already exist.

Restrictions

This is only valid when fe_md_boundary is set to faceset.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC fe_md_boundary
• fix_modify AtC mesh create_faceset box
• fix_modify AtC mesh create_faceset plane

1238 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Default

None.

17.83.8 fix_modify AtC boundary type command

Syntax

fix_modify <AtC fixID> boundary type <atom-type-id>

• AtC fixID = ID of fix atc instance

• boundary type = name of the AtC sub-command
• atom-type-id = type id for atoms that represent a fictitious boundary internal to the FE mesh

Examples

fix_modify AtC boundary type ghost_atoms

Description

Command to define the atoms that represent the fictitious boundary internal to the FE mesh. For fully overlapped
MD/FE domains with periodic boundary conditions no boundary atoms should be defined.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83.9 fix_modify AtC consistent_fe_initialization command

Syntax

fix_modify <AtC fixID> consistent_fe_initialization <on|off>

• AtC fixID = ID of fix atc instance

• consistent_fe_initialization = name of the AtC sub-command
• on or off = switch to activate/deactivate the initial setting of the FE intrinsic field to match the projected MD
field

17.83. fix_modify AtC commands 1239

LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC consistent_fe_initialization on

Description

Determines whether AtC initializes FE intrinsic fields (e.g., temperature) to match the projected MD values. This is
particularly useful for fully overlapping simulations.

Restrictions

Can be used with: thermal, two_temperature. Cannot be used with time filtering on. Does not include boundary nodes.

Related AtC commands

• fix_modify AtC command overview

Default

Default is off

17.83.10 fix_modify AtC control localized_lambda command

Syntax

fix_modify <AtC fixID> control localized_lambda <on|off>

• AtC fixID = ID of fix atc instance

• control localized_lambda = name of the AtC sub-command
• on or off = Toggles state of localization algorithm

Examples

fix_modify AtC control localized_lambda on

Description

Turns the localization algorithms on or off for control algorithms to restrict the influence of FE coupling or boundary
conditions to a region near the boundary of the MD region. Control algorithms will not affect atoms in elements not
possessing faces on the boundary of the region. Flux-based control is localized via row-sum lumping while quantity
control is done by solving a truncated matrix equation.

1240 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

off

17.83.11 fix_modify AtC control momentum command

Syntax

fix_modify <AtC fixID> control <physics_type> <solution_parameter> <value>

fix_modify AtC control momentum none
fix_modify AtC control momentum rescale <frequency>
fix_modify AtC control momentum glc_displacement
fix_modify AtC control momentum glc_velocity
fix_modify AtC control momentum hoover
fix_modify AtC control momentum flux [faceset face_set_id, interpolate]

• AtC fixID = ID of fix atc instance

• control = name of the AtC sub-command
• physics_type = thermal or momentum
• solution_parameter = max_iterations or tolerance
• value = solution_parameter value
• momentum option = none or rescale or glc_displacement or glc_velocity hoover or flux
• frequency = time step frequency for applying displacement and velocity rescaling
• faceset_id = id of boundary face set (optional, only for faceset)

Examples

fix_modify AtC control momentum none

fix_modify AtC control momentum flux faceset bndy_faces
fix_modify AtC control momentum glc_velocity

17.83. fix_modify AtC commands 1241

LAMMPS Documentation, Release stable 29Sep2021

Description

The general version of control sets the numerical parameters for the matrix solvers used in the specified control algo-
rithm. Many solution approaches require iterative solvers, and these methods enable users to provide the maximum
number of iterations and the relative tolerance.
The control momentum version sets the momentum exchange mechanism from the finite elements to the atoms, managed
through a control algorithm. rescale computes a scale factor for each atom to match the finite element temperature.
hoover is a Gaussian least-constraint isokinetic thermostat enforces that the nodal restricted atomic temperature matches
the finite element temperature. flux is a similar mode, but rather adds energy to the atoms based on conservation of
energy.
correction_max_iterations sets the maximum number of iterations to compute the second order in time correction term
for lambda with the fractional step method. The method uses the same tolerance as the controller’s matrix solver.

Restrictions

Only for be used with the specific controllers thermal or momentum. They are ignored if a lumped solution is requested.
control momentum is only for be used with specific transfers: elastic rescale not valid with time filtering activated

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC control thermal

Default

• max_iterations is the number of rows in the matrix.

• tolerance is 1.0e-10.

17.83.12 fix_modify AtC control thermal command

Syntax

fix_modify <AtC fixID> control <physics_type> <solution_parameter> <value>

fix_modify <AtC fixID> control thermal <control_type> <optional_args>
fix_modify <AtC fixID> control thermal rescale <frequency>
fix_modify <AtC fixID> control thermal flux <boundary_integration_type> <faceset_id>
fix_modify <AtC fixID> control thermal correction_max_iterations <max_iterations>

• AtC fixID = ID of fix atc instance

• control = name of the AtC sub-command
• physics_type = thermal or momentum
• solution_parameter = max_iterations or tolerance
• value = solution_parameter value
• thermal control_type = none or rescale or hoover or flux
• frequency = time step frequency for applying velocity rescaling

1242 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• boundary_integration_type = faceset or interpolate (optional)

• faceset_id = id of boundary face set (optional, only for faceset)
• correction_max_iterations = maximum number of iterations that will be used by iterative matrix solvers for
thermal physics type

Examples

fix_modify AtC control thermal none

fix_modify AtC control thermal rescale 10
fix_modify AtC control thermal hoover
fix_modify AtC control thermal flux
fix_modify AtC control thermal flux faceset bndy_faces
fix_modify AtC control thermal correction_max_iterations 10

Description

The general version of control sets the numerical parameters for the matrix solvers used in the specified control algo-
rithm. Many solution approaches require iterative solvers, and these methods enable users to provide the maximum
number of iterations and the relative tolerance.
The control thermal version sets the energy exchange mechanism from the finite elements to the atoms, managed
through a control algorithm. rescale computes a scale factor for each atom to match the finite element temperature.
hoover is a Gaussian least-constraint isokinetic thermostat enforces that the nodal restricted atomic temperature matches
the finite element temperature. flux is a similar mode, but rather adds energy to the atoms based on conservation of
energy. hoover and flux allow the prescription of sources or fixed temperatures on the atoms.
correction_max_iterations sets the maximum number of iterations to compute the second order in time correction term
for lambda with the fractional step method. The method uses the same tolerance as the controller’s matrix solver.

Restrictions

Only for be used with the specific controllers thermal or momentum. They are ignored if a lumped solution is requested.
control thermal is only for be used with specific transfers: thermal (rescale, hoover, flux), two_temperature (flux).
rescale not valid with time filtering activated
correction_max_iterations is only for use with thermal physics using the fractional step method.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC control momentum

17.83. fix_modify AtC commands 1243

LAMMPS Documentation, Release stable 29Sep2021

Default

• max_iterations is the number of rows in the matrix.

• tolerance is 1.0e-10.
• rescale frequency is 1
• flux boundary_integration_type is interpolate
• correction_max_iterations is 20

17.83.13 fix_modify AtC decomposition command

Syntax

fix_modify <AtC fixID> decomposition <type>

• AtC fixID = ID of fix atc instance

• decomposition = name of the AtC sub-command
• type = replicated_memory or distributed_memory

Examples

fix_modify AtC decomposition distributed_memory

Description

Command for assigning the distribution of work and memory for parallel runs. With replicated_memory the nodal
information is replicated on each processor, and with distributed_memory only the owned nodal information kept on
each processor. The replicated_memory option is most appropriate for simulations were the number of nodes is much
smaller than the number of atoms.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

1244 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Default

replicated_memory

17.83.14 fix_modify AtC extrinsic electron_integration command

Syntax

fix_modify <AtC fixID> extrinsic electron_integration <integration_type> [<num_subcycle_

,→steps>]

• AtC fixID = ID of fix atc instance

• extrinsic electron_integration = name of the AtC sub-command
• integration_type = explicit or implicit or steady
• num_subcycle_steps = number of subcycle steps for the electron time integration (optional)

Examples

fix_modify AtC extrinsic electron_integration implicit

fix_modify AtC extrinsic electron_integration explicit 100

Description

Switches between integration schemes for the electron temperature. The number of subcycling steps used to integrate
the electron temperature for one LAMMPS timestep can be manually adjusted to capture fast electron dynamics.

Restrictions

For use only with the two_temperature type of the AtC fix (see fix atc command)

Related AtC commands

• fix_modify AtC command overview

Default

implicit and subcycle_steps = 1

17.83. fix_modify AtC commands 1245

LAMMPS Documentation, Release stable 29Sep2021

17.83.15 fix_modify AtC equilibrium_start command

Syntax

fix_modify <AtC fixID> equilibrium_start <on|off>

• AtC fixID = ID of fix atc instance

• equilibrium_start = name of the AtC sub-command
• exponential or step or no_filter = select type of filter

Examples

fix_modify AtC equilibrium_start on

Description

Starts filtered calculations assuming they start in equilibrium, i.e. perfect finite element force balance.

Restrictions

Only for use with these specific transfers: thermal, two_temperature

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC filter
• fix_modify AtC filter scale

Default

None.

17.83.16 fix_modify AtC extrinsic exchange command

Syntax

fix_modify <AtC fixID> extrinsic exchange <on|off>

• AtC fixID = ID of fix atc instance

• extrinsic exchange = name of the AtC sub-command
• on or off = set state of energy exchange

1246 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC extrinsic exchange on

Description

Switches energy exchange between the MD system and the electron system on or off

Restrictions

For use only with the two_temperature type of the AtC fix (see fix atc command)

Related AtC commands

• fix_modify AtC command overview

Default

on

17.83.17 fix_modify AtC fe_md_boundary command

Syntax

fix_modify <AtC fixID> fe_md_boundary <faceset|interpolate|no_boundary>

• AtC fixID = ID of fix atc instance

• fe_md_boundary = name of the AtC sub-command
• faceset or interpolate or no_boundary

Examples

fix_modify AtC fe_md_boundary interpolate

Description

Specifies different methods for computing fluxes between between the MD and FE integration regions. Faceset defines
a faceset separating the MD and FE regions and uses finite element face quadrature to compute the flux. Interpolate
uses a reconstruction scheme to approximate the flux, which is more robust but less accurate if the MD/FE boundary
does correspond to a faceset. No boundary results in no fluxes between the systems being computed.

17.83. fix_modify AtC commands 1247

LAMMPS Documentation, Release stable 29Sep2021

Restrictions

If faceset is used, all the AtC non-boundary atoms must lie within and completely fill the domain enclosed by the
faceset.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create_faceset box
• fix_modify AtC mesh create_faceset plane

Default

interpolate

17.83.18 fix_modify AtC filter scale command

Syntax

fix_modify <AtC fixID> filter scale <scale>

• AtC fixID = ID of fix atc instance

• filter scale = name of the AtC sub-command
• scale = characteristic times scale of the filter

Examples

fix_modify AtC filter scale 10.0

Description

Sets the time scale for MD dynamics filter to construct a more appropriate continuous field.

Restrictions

Only for use with these specific transfers: thermal, two_temperature

1248 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC filter
• fix_modify AtC filter type

Default

0.0

17.83.19 fix_modify AtC filter type command

Syntax

fix_modify <AtC fixID> filter type <exponential|step|no_filter>

• AtC fixID = ID of fix atc instance

• filter type = name of the AtC sub-command
• exponential or step or no_filter = select type of filter

Examples

fix_modify AtC filter type exponential

Description

Specifies the type of time filter used.

Restrictions

Only for use with these specific transfers: thermal, two_temperature

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC filter
• fix_modify AtC filter scale

17.83. fix_modify AtC commands 1249

LAMMPS Documentation, Release stable 29Sep2021

Default

None.

17.83.20 fix_modify AtC fix command

Syntax

fix_modify <AtC fixID> fix <field> <nodeset> <constant|function>

• AtC fixID = ID of fix atc instance

• fix = name of the AtC sub-command
• field = field kind name valid for type of physics: temperature or electron_temperature
• nodeset = name of set of nodes to apply boundary condition
• constant or function = value or name of function followed by its parameters

Examples

fix_modify AtC fix temperature groupNAME 10.

fix_modify AtC fix temperature groupNAME 0 0 0 10.0 0 0 1.0

Description

Creates a constraint on the values of the specified field at specified nodes.

Restrictions

The keyword all is reserved and thus not available as nodeset name.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC unfix

Default

None.

1250 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.83.21 fix_modify AtC fix_flux command

Syntax

fix_modify <AtC fixID> fix_flux <field> <face_set> <value|function>

• AtC fixID = ID of fix atc instance

• fix_flux = name of the AtC sub-command
• field = field kind name valid for type of physics: temperature or electron_temperature
• face_set = name of set of element faces
• value or function = value or name of function followed by its parameters

Examples

fix_modify AtC fix_flux temperature faceSet 10.0

Description

Command for fixing normal fluxes e.g. heat_flux. This command only prescribes the normal component of the physical
flux, e.g. heat (energy) flux. The units are in AtC units, i.e. derived from the LAMMPS length, time, and mass scales.

Restrictions

Only normal fluxes (Neumann data) can be prescribed.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC unfix_flux

Default

None.

17.83.22 fix_modify AtC computes command

Syntax

fix_modify <AtC fixID> computes <add|delete> <per-atom compute-ID> <volume|number>

• AtC fixID = ID of fix atc instance

• computes = name of the AtC sub-command
• add or delete = add or delete the calculation of an equivalent continuum field for the specified per-atom compute
as volume or number density quantity

17.83. fix_modify AtC commands 1251

LAMMPS Documentation, Release stable 29Sep2021

• per-atom compute-ID = ID of a per-atom compute; fields can be calculated for all per-atom computes available
in LAMMPS
• volume or number = select whether the created field is a per-unit-volume quantity or a per-atom quantity as
weighted by kernel functions

Examples

compute virial all stress/atom

fix_modify AtC computes add virial volume
fix_modify AtC computes delete virial

compute centrosymmetry all centro/atom

fix_modify AtC computes add centrosymmetry number

Description

Calculates continuum fields corresponding to specified per-atom computes created by LAMMPS.

Restrictions

Must be used with fix atc hardy. The per-atom compute must be specified before the corresponding continuum field
can be requested.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC fields
• compute

Default

None.

17.83.23 fix_modify AtC fields command

Syntax

fix_modify <AtC fixID> fields <all|none>

fix_modify <AtC fixID> fields <add|delete> <list_of_fields>

• AtC fixID = ID of fix atc instance

• fields = name of the AtC sub-command
• all or none = output all or no fields
• add or delete = add or delete the listed output fields
• list_of_fields = one or more of the fields listed below:

1252 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

– density : mass per unit volume

– displacement : displacement vector
– momentum : momentum per unit volume
– velocity : defined by momentum divided by density
– projected_velocity : simple kernel estimation of atomic velocities
– temperature : temperature derived from the relative atomic kinetic energy
– kinetic_temperature : temperature derived from the full kinetic energy
– number_density : simple kernel estimation of number of atoms per unit volume
– stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or first Piola-Kirchhoff stress tensor
for lagrangian analysis
– transformed_stress : first Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or
Cauchy stress tensor for lagrangian analysis
– heat_flux : spatial heat flux vector for eulerian, or referential heat flux vector for lagrangian
– potential_energy : potential energy per unit volume
– kinetic_energy : kinetic energy per unit volume
– thermal_energy : thermal energy (kinetic energy - continuum kinetic energy) per unit volume
– internal_energy : total internal energy (potential + thermal) per unit volume
– energy : total energy (potential + kinetic) per unit volume
– number_density : number of atoms per unit volume
– eshelby_stress : configurational stress (energy-momentum) tensor defined by [Eshelby]
– vacancy_concentration : volume fraction of vacancy content
– type_concentration : volume fraction of a specific atom type

Examples

fix_modify AtC fields add velocity temperature

Description

Allows modification of the fields calculated and output by the AtC transfer class. The commands are cumulative, e.g.:

fix_modify AtC fields none

fix_modify AtC fields add velocity temperature

will only output the velocity and temperature fields.

17.83. fix_modify AtC commands 1253

LAMMPS Documentation, Release stable 29Sep2021

Restrictions

Must be used with fix atc hardy. Currently, the stress and heat flux formulas are only correct for central force potentials,
e.g. Lennard-Jones and EAM but not Stillinger-Weber.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC gradients
• fix_modify AtC rates
• fix_modify AtC computes

Default

By default, no fields are output.

References

17.83.24 fix_modify AtC gradients command

Syntax

fix_modify <AtC fixID> gradients <add|delete> <list_of_fields>

• AtC fixID = ID of fix atc instance

• gradients = name of the AtC sub-command
• add or delete = select whether to add or delete calculation of gradients for the listed output fields
• list_of_fields = one or more of the fields listed below:
– density : mass per unit volume
– displacement : displacement vector
– momentum : momentum per unit volume
– velocity : defined by momentum divided by density
– projected_velocity : simple kernel estimation of atomic velocities
– temperature : temperature derived from the relative atomic kinetic energy
– kinetic_temperature : temperature derived from the full kinetic energy
– number_density : simple kernel estimation of number of atoms per unit volume
– stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or first Piola-Kirchhoff stress tensor
for lagrangian analysis
– transformed_stress : first Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or
Cauchy stress tensor for lagrangian analysis
– heat_flux : spatial heat flux vector for eulerian, or referential heat flux vector for lagrangian
– potential_energy : potential energy per unit volume

1254 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

– kinetic_energy : kinetic energy per unit volume

– thermal_energy : thermal energy (kinetic energy - continuum kinetic energy) per unit volume
– internal_energy : total internal energy (potential + thermal) per unit volume
– energy : total energy (potential + kinetic) per unit volume
– number_density : number of atoms per unit volume
– eshelby_stress : configurational stress (energy-momentum) tensor defined by [Eshelby]
– vacancy_concentration : volume fraction of vacancy content
– type_concentration : volume fraction of a specific atom type

Examples

fix_modify AtC gradients add temperature velocity stress

fix_modify AtC gradients delete velocity

Description

Requests calculation and output of gradients of the fields from the AtC transfer class. These gradients will be with
regard to spatial or material coordinate for Eulerian or Lagrangian analysis, respectively, as specified by fix_modify
AtC atom_element_map

Restrictions

Must be used with fix atc hardy.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC atom_element_map
• fix_modify AtC fields
• fix_modify AtC rates

Default

None.

17.83. fix_modify AtC commands 1255

LAMMPS Documentation, Release stable 29Sep2021

17.83.25 fix_modify AtC kernel command

Syntax

fix_modify <AtC fixID> kernel <type> <parameters>

• AtC fixID = ID of fix atc instance

• kernel = name of the AtC sub-command
• type = step or cell or cubic_bar or cubic_cylinder or cubic_sphere or quartic_bar or quartic_cylinder or quar-
tic_sphere
• the following parameter(s) are required for each kernel:
– step : <radius>
– cell : <hx> <hy> <hz> or <h>
– cubic_bar : <half_width>
– cubic_cylinder : <radius>
– cubic_sphere : <radius>
– quartic_bar : <half_width>
– quartic_cylinder : <radius>
– quartic_sphere : <radius>

Examples

fix_modify AtC kernel cell 1.0 1.0 1.0

fix_modify AtC kernel quartic_sphere 10.0

Description

Sets the localization kernel type and parameters for fix atc hardy.

Restrictions

Must be used with fix atc hardy. For bar kernel types, half-width oriented along x-direction. For cylinder kernel types,
cylindrical axis is assumed to be in z-direction.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC fields
• fix_modify AtC gradients
• fix_modify AtC rates
• fix_modify AtC computes

1256 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Default

None.

17.83.26 fix_modify AtC on_the_fly command

Syntax

fix_modify <AtC fixID> on_the_fly <bond|kernel> <on|off>

• AtC fixID = ID of fix atc instance

• on_the_fly = name of the AtC sub-command
• bond or kernel = specifies on-the-fly calculation of bond or kernel matrix elements
• on or off = activate or discontinue on-the-fly mode

Examples

fix_modify AtC on_the_fly bond on

fix_modify AtC on_the_fly kernel
fix_modify AtC on_the_fly kernel off

Description

Overrides normal mode of pre-calculating and storing bond pair-to-node a nd kernel atom-to-node matrices. If acti-
vated, it will calculate elements of these matrices during repeated calls of field computations (i.e. “on-the-fly”) and
not store them for future use. The on flag is optional - if omitted, on_the_fly will be activated for the specified matrix.
Can be deactivated using the off flag.

Restrictions

Must be used with fix atc hardy.

Related AtC commands

• fix_modify AtC command overview

Default

By default, on-the-fly calculation is not active (i.e. off). However, THE code does a memory allocation check to
determine if it can store all needed bond and kernel matrix elements. If this allocation fails, on-the-fly will be activated.

17.83. fix_modify AtC commands 1257

LAMMPS Documentation, Release stable 29Sep2021

17.83.27 fix_modify AtC rates command

Syntax

fix_modify <AtC fixID> rates <add|delete> <list_of_fields>

• AtC fixID = ID of fix atc instance

• rates = name of the AtC sub-command
• add or delete = select whether to add or delete calculation of rates for the listed output fields
• list_of_fields = one or more of the fields listed below:
– density : mass per unit volume
– displacement : displacement vector
– momentum : momentum per unit volume
– velocity : defined by momentum divided by density
– projected_velocity : simple kernel estimation of atomic velocities
– temperature : temperature derived from the relative atomic kinetic energy
– kinetic_temperature : temperature derived from the full kinetic energy
– number_density : simple kernel estimation of number of atoms per unit volume
– stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or first Piola-Kirchhoff stress tensor
for lagrangian analysis
– transformed_stress : first Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or
Cauchy stress tensor for lagrangian analysis
– heat_flux : spatial heat flux vector for eulerian, or referential heat flux vector for lagrangian
– potential_energy : potential energy per unit volume
– kinetic_energy : kinetic energy per unit volume
– thermal_energy : thermal energy (kinetic energy - continuum kinetic energy) per unit volume
– internal_energy : total internal energy (potential + thermal) per unit volume
– energy : total energy (potential + kinetic) per unit volume
– number_density : number of atoms per unit volume
– eshelby_stress : configurational stress (energy-momentum) tensor defined by [Eshelby]
– vacancy_concentration : volume fraction of vacancy content
– type_concentration : volume fraction of a specific atom type

1258 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC rates add temperature velocity stress

fix_modify AtC rates delete stress

Description

Requests calculation and output of rates (time derivatives) of the fields from the AtC transfer class. For Eulerian
analysis (see fix_modify AtC atom_element_map) these rates are the partial time derivatives of the nodal fields, not the
full (material) time derivatives.

Restrictions

Must be used with fix atc hardy.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC atom_element_map
• fix_modify AtC fields
• fix_modify AtC fields

Default

None.

17.83.28 fix_modify AtC initial command

Syntax

fix_modify <AtC fixID> initial <field> <nodeset> <constant|function>

• AtC fixID = ID of fix atc instance

• initial = name of the AtC sub-command
• field = field kind name valid for type of physics: temperature or electron_temperature
• nodeset = name of set of nodes to apply initial condition
• constant or function = value or name of function followed by its parameters

17.83. fix_modify AtC commands 1259

LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC initial temperature groupNAME 10.

Description

Sets the initial values for the specified field at the specified nodes.

Restrictions

The keyword all is reserved and thus not available as nodeset name.

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83.29 fix_modify AtC internal_element_set command

Syntax

fix_modify <AtC fixID> internal_element_set <element_set_name>

• AtC fixID = ID of fix atc instance

• internal_element_set = name of the AtC sub-command
• element_set_name = name of element set defining internal region, or off

Examples

fix_modify AtC internal_element_set myElementSet

fix_modify AtC internal_element_set off

Description

Enables AtC to base the region for internal atoms to be an element set. If no ghost atoms are used, all the AtC atoms
must be constrained to remain in this element set by the user, e.g., with walls. If boundary atoms are used in conjunction
with Eulerian atom maps AtC will partition all atoms of a boundary or internal type to be of type internal if they are in
the internal region or to be of type boundary otherwise.

1260 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Restrictions

If boundary atoms are used in conjunction with Eulerian atom maps, the Eulerian reset frequency must be an integer
multiple of the Lammps reneighbor frequency.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC atom_element_map
• fix_modify AtC boundary type

Default

off

17.83.30 fix_modify AtC internal_quadrature command

Syntax

fix_modify <AtC fixID> internal_quadrature <on|off> [region]

• AtC fixID = ID of fix atc instance

• internal_quadrature = name of the AtC sub-command
• on or off = select whether internal quadrature is enabled or not
• region = treat finite elements as within MD region (optional)

Examples

fix_modify AtC internal_quadrature off

Description

Command to use or not use atomic quadrature on internal elements fully filled with atoms. By turning the internal
quadrature off these elements do not contribute to the governing PDE and the fields at the internal nodes follow the
weighted averages of the atomic data.
Optional region tag specifies which finite element nodes will be treated as being within the MD region. This option is
only valid with internal_quadrature off.

17.83. fix_modify AtC commands 1261

LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

Default

on.

17.83.31 fix_modify AtC kernel_bandwidth command

Syntax

fix_modify <AtC fixID> kernel_bandwidth <value>

• AtC fixID = ID of fix atc instance

• kernel_bandwidth = name of the AtC sub-command
• value = new bandwidth value

Examples

fix_modify AtC kernel_bandwidth 8

Description

Sets a maximum parallel bandwidth for the kernel functions during parallel communication. If the command is not
issued, the default will be to assume the bandwidth of the kernel matrix corresponds to the number of sampling loca-
tions.

Restrictions

Only is used if kernel functions are being used.

Related AtC commands

• fix_modify AtC command overview

Default

Number of sample locations.

1262 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.83.32 fix_modify AtC control lumped_lambda_solve command

Syntax

fix_modify <AtC fixID> control lumped_lambda_solve <on|off>

• AtC fixID = ID of fix atc instance

• control lumped_lambda_solve = name of the AtC sub-command
• on or off = Toggles state of lumped matrix

Examples

fix_modify AtC control lumped_lambda_solve on

Description

Command select whether to use or not use lumped matrix for lambda solve.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

off

17.83.33 fix_modify AtC control mask_direction command

Syntax

fix_modify <AtC fixID> control mask_direction <direction> <on|off>

• AtC fixID = ID of fix atc instance

• control mask_direction = name of the AtC sub-command
• direction = select direction
• on or off = Toggles state

17.83. fix_modify AtC commands 1263

LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC control mask_direction 0 on

Description

Command to mask out certain dimensions from the atomic regulator

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

17.83.34 fix_modify AtC mass_matrix command

Syntax

fix_modify <AtC fixID> mass_matrix <fe|md_fe>

• AtC fixID = ID of fix atc instance

• mass_matrix = name of the AtC sub-command
• fe or md_fe = activate/deactivate using the FE mass matrix in the MD region

Examples

fix_modify AtC mass_matrix fe

Description

Determines whether AtC uses the FE mass matrix based on Gaussian quadrature or based on atomic quadrature in the
MD region. This is useful for fully overlapping simulations to improve efficiency.

Restrictions

Should not be used unless the FE region is contained within the MD region, otherwise the method will be unstable and
inaccurate.

1264 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

Default

md_fe

17.83.35 fix_modify AtC material command

Syntax

fix_modify <AtC fixID> material <elementset_name> <material_id>

• AtC fixID = ID of fix atc instance

• material = name of the AtC sub-command
• elementset_name = name of the elementset
• material_id = ID of the material

Examples

fix_modify AtC material gap_region 1

Description

Sets the material model in elementset_name to be of type material_id.

Restrictions

The element set must already be created and the material must be specified in the material file given the the atc fix on
construction

Related AtC commands

• fix_modify AtC command overview

Default

All elements default to the first material in the material file.

17.83. fix_modify AtC commands 1265

LAMMPS Documentation, Release stable 29Sep2021

17.83.36 fix_modify AtC mesh add_to_nodeset command

Syntax

fix_modify <AtC fixID> mesh add_to_nodeset <id> <xmin> <xmax> <ymin> <ymax> <zmin> <zmax>

• AtC fixID = ID of fix atc instance

• mesh create_nodeset = name of the AtC sub-command
• id = id to assign to the collection of FE nodes
• <xmin> <xmax> <ymin> <ymax> <zmin> <zmax> = coordinates of the bounding box that contains the desired
nodes to be added

Examples

fix_modify AtC mesh add_to_nodeset lbc -12.1 -11.9 -12 12 -12 12

Description

Command to add nodes to an already existing FE nodeset.

Restrictions

None

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create_nodeset

Default

Coordinates are assumed to be in lattice units.

17.83.37 fix_modify AtC mesh create command

Syntax

fix_modify <AtC fixID> mesh create <nx> <ny> <nz> <region-ID> <f|p> <f|p> <f|p>

• AtC fixID = ID of fix atc instance

• mesh create = name of the AtC sub-command
• nx ny nz = number of elements in x-, y-, and z-direction
• region-ID = ID of region that is to be meshed
• f or p = periodicity flags for x-, y-, and z-direction

1266 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC mesh create 10 1 1 feRegion p p p

Description

Creates a uniform mesh in a rectangular region.

Restrictions

Creates only uniform rectangular grids in a rectangular region

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh quadrature

Default

When created, the mesh defaults to gauss2 (2-point Gaussian) quadrature. Use the fix_modify AtC mesh quadrature
command to change the quadrature style.

17.83.38 fix_modify AtC mesh create_elementset command

Syntax

fix_modify <AtC fixID> mesh create_elementset <id> <xmin> <xmax> <ymin> <ymax> <zmin>
,→<zmax>

• AtC fixID = ID of fix atc instance

• mesh create_elementset = name of the AtC sub-command
• id = id to assign to the collection of FE nodes
• <xmin> <xmax> <ymin> <ymax> <zmin> <zmax> = coordinates of the bounding box that contains only the
desired elements

Examples

fix_modify AtC mesh create_elementset middle -4.1 4.1 -100 100 -100 1100

17.83. fix_modify AtC commands 1267

LAMMPS Documentation, Release stable 29Sep2021

Description

Command to assign an id to a set of FE elements to be used subsequently in defining material and mesh-based opera-
tions.

Restrictions

Only viable for rectangular grids.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh delete_elements
• fix_modify AtC mesh nodeset_to_elementset

Default

Coordinates are assumed to be in lattice units.

17.83.39 fix_modify AtC mesh create_faceset box command

Syntax

fix_modify <AtC fixID> mesh create_faceset <id> box <xmin> <xmax> <ymin> <ymax> <zmin>
,→<zmax> <in|out> [units]

• AtC fixID = ID of fix atc instance

• mesh create_faceset = name of the AtC sub-command
• id = id to assign to the collection of FE faces
• box = use bounding box to define FE faces
• <xmin> <xmax> <ymin> <ymax> <zmin> <zmax> = coordinates of the bounding box that is coincident with
the desired FE faces
• <in|out> = “in” gives inner faces to the box, “out” gives the outer faces to the box
• units = option to specify real as opposed to lattice units

Examples

fix_modify AtC mesh create_faceset obndy box -4.0 4.0 -12 12 -12 12 out

1268 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Description

Command to assign an id to a set of FE faces.

Restrictions

Only viable for rectangular grids.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create_faceset plane

Default

The default options are units = lattice and the use of outer faces.

17.83.40 fix_modify AtC mesh create_faceset plane command

Syntax

fix_modify <AtC fixID> mesh create_faceset <id> plane <x|y|z> <val1> <x|y|z> <lval2>
,→<uval2> [units]

• AtC fixID = ID of fix atc instance

• mesh create_faceset = name of the AtC sub-command
• id = id to assign to the collection of FE faces
• plane = use plane to define faceset
• <val1>,<lval2>,<uval2> = plane is specified as the x|y|z=val1 plane bounded by the segments x|y|z = [lval2,uval2]
• units = option to specify real as opposed to lattice units

Examples

fix_modify AtC mesh create_faceset xyplane plane y 0 x -4 0

Description

Command to assign an id to a set of FE faces.

17.83. fix_modify AtC commands 1269

LAMMPS Documentation, Release stable 29Sep2021

Restrictions

Only viable for rectangular grids.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create_faceset box

Default

The default options are units = lattice.

17.83.41 fix_modify AtC mesh create_nodeset command

Syntax

fix_modify <AtC fixID> mesh create_nodeset <id> <xmin> <xmax> <ymin> <ymax> <zmin> <zmax>

• AtC fixID = ID of fix atc instance

• mesh create_nodeset = name of the AtC sub-command
• id = id to assign to the collection of FE nodes
• <xmin> <xmax> <ymin> <ymax> <zmin> <zmax> = coordinates of the bounding box that contains only the
desired nodes

Examples

fix_modify AtC mesh create_nodeset lbc -12.1 -11.9 -12 12 -12 12

Description

Command to assign an id to a set of FE nodes to be used subsequently in defining boundary conditions.

Restrictions

None

1270 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh add_to_nodeset

Default

Coordinates are assumed to be in lattice units.

17.83.42 fix_modify AtC mesh delete_elements command

Syntax

fix_modify <AtC fixID> mesh delete_elements <id>

• AtC fixID = ID of fix atc instance

• mesh create_elementset = name of the AtC sub-command
• id = id of the element set

Examples

fix_modify AtC mesh delete_elements gap

Description

Deletes a group of elements from the mesh.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create_elementset
• fix_modify AtC mesh nodeset_to_elementset

17.83. fix_modify AtC commands 1271

LAMMPS Documentation, Release stable 29Sep2021

Default

None.

17.83.43 fix_modify AtC mesh nodeset_to_elementset command

Syntax

fix_modify <AtC fixID> mesh nodeset_to_elementset <nodeset_id> <elementset_id> <max/min>

• AtC fixID = ID of fix atc instance

• mesh nodeset_to_elementset = name of the AtC sub-command
• nodeset_id = id of desired nodeset from which to create the elementset
• elementset_id = id to assign to the collection of FE elements
• <max/min> = flag to choose either the maximal or minimal elementset

Examples

fix_modify AtC mesh nodeset_to_elementset myNodeset myElementset min

Description

Command to create an elementset from an existing nodeset. Either the minimal element set of elements with all nodes
in the set, or maximal element set with all elements with at least one node in the set, can be created.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create_elementset
• fix_modify AtC mesh delete_elements

Default

Unless specified, the maximal element set is created.

1272 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.83.44 fix_modify AtC mesh output command

Syntax

fix_modify <AtC fixID> mesh output <file_prefix>

• AtC fixID = ID of fix atc instance

• mesh output = name of the AtC sub-command
• file_prefix = prefix of various generated output files

Examples

fix_modify AtC mesh output meshData

Description

Command to output mesh and associated data: nodesets, facesets, and elementsets. This data is only output once upon
initialization since currently the mesh is static. Creates binary (EnSight, “gold” format) output of mesh data.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83.45 fix_modify AtC mesh quadrature command

Syntax

fix_modify <AtC fixID> mesh quatrature <quad>

• AtC fixID = ID of fix atc instance

• mesh quadrature = name of the AtC sub-command
• quad = nodal or gauss1 or gauss2 or gauss3 or face

17.83. fix_modify AtC commands 1273

LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC mesh quadrature face

Description

(Re-)assigns the quadrature style for an existing mesh. When a mesh is created its quadrature method defaults to gauss2.
Use this call to change it after the fact.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create

Default

None.

17.83.46 fix_modify AtC mesh read command

Syntax

fix_modify <AtC fixID> mesh read <f|p> <f|p> <f|p>

• AtC fixID = ID of fix atc instance

• mesh read = name of the AtC sub-command
• filename = name of the file containing the mesh to be read
• f or p = periodicity flags for x-, y-, and z-direction (optional)

Examples

fix_modify AtC mesh read myComponent.mesh p p p

fix_modify AtC mesh read myOtherComponent.exo

1274 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Description

Reads a mesh from a text or exodus file, and assigns periodic boundary conditions if needed.

Restrictions

None

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create
• fix_modify AtC mesh write

Default

Periodicity flags are set to false (f) by default.

17.83.47 fix_modify AtC mesh write command

Syntax

fix_modify <AtC fixID> mesh write <f|p> <f|p> <f|p>

• AtC fixID = ID of fix atc instance

• mesh write = name of the AtC sub-command
• filename = name of the file containing the mesh to be write

Examples

fix_modify AtC mesh write myMesh.mesh

Description

Writes a mesh to a text file.

Restrictions

None

17.83. fix_modify AtC commands 1275

LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC mesh create
• fix_modify AtC mesh read

Default

None.

17.83.48 fix_modify AtC output command

Syntax

fix_modify <AtC fixID> output <filename_prefix> <frequency> [text|full_

,→text|binary|vector_components|tensor_components]

fix_modify <AtC fixID> output index [step|time]

• AtC fixID = ID of fix atc instance

• output or output index = name of the AtC sub-command
• filename_prefix = prefix for data files (for output)
• frequency = frequency of output in timesteps (for output)
• optional keywords for output:
– text = creates text output of index, step and nodal variable values for unique nodes
– full_text = creates text output index, nodal id, step, nodal coordinates and nodal variable values for unique
and image nodes
– binary = creates binary EnSight output
– vector_components = outputs vectors as scalar components
– tensor_components = outputs tensor as scalar components (for use with ParaView)
• step or time = index output by step or by time (for output index)

Examples

fix_modify AtC output heatFE 100

fix_modify AtC output hardyFE 1 text tensor_components
fix_modify AtC output hardyFE 10 text binary tensor_components
fix_modify AtC output index step

1276 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Description

Creates text and/or binary (EnSight, “gold” format) output of nodal/mesh data which is transfer/physics specific. Output
indexing by step or time is possible.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix atc command

Default

No default format. Output indexed by time.

17.83.49 fix_modify AtC output boundary_integral command

Syntax

fix_modify <AtC fixID> output boundary_integral <fieldname> faceset [name]

• AtC fixID = ID of fix atc instance

• output boundary_integral = name of the AtC sub-command
• fieldname = name of hardy field
• faceset = required keyword
• name= name of faceset

Examples

fix_modify AtC output boundary_integral stress faceset loop1

Description

Calculates a surface integral of the given field dotted with the outward normal of the faces and puts output in the
“GLOBALS” file.

17.83. fix_modify AtC commands 1277

LAMMPS Documentation, Release stable 29Sep2021

Restrictions

Must be used with the hardy/field type of fix atc

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83.50 fix_modify AtC output contour_integral command

Syntax

fix_modify <AtC fixID> output contour_integral <fieldname> faceset <name> [axis [x|y|z]]

• AtC fixID = ID of fix atc instance

• output contour_integral = name of the AtC sub-command
• fieldname = name of hardy field
• faceset = required keyword
• name = name of faceset
• axis x or axis y or axis z = (optional)

Examples

fix_modify AtC output contour_integral stress faceset loop1

Description

Calculates a surface integral of the given field dotted with the outward normal of the faces and puts output in the
“GLOBALS” file.

Restrictions

Must be used with the hardy/field type of fix atc

1278 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83.51 fix_modify AtC output nodeset command

Syntax

fix_modify <AtC fixID> output nodeset <nodeset_name> <operation>

• AtC fixID = ID of fix atc instance

• output nodeset = name of the AtC sub-command
• nodeset_name= name of nodeset to be operated on
• operation = sum
– sum = creates nodal sum over nodes in specified nodeset

Examples

fix_modify AtC output nodeset nset1 sum

Description

Performs operation over the nodes belonging to specified nodeset and outputs resulting variable values to GLOBALS
file.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix atc command

17.83. fix_modify AtC commands 1279

LAMMPS Documentation, Release stable 29Sep2021

Default

None.

17.83.52 fix_modify AtC output volume_integral command

Syntax

fix_modify <AtC fixID> output volume_integral <elementset_name> <field>

• AtC fixID = ID of fix atc instance

• output volume_integral = name of the AtC sub-command
• elementset_name= name of elementset to be integrated over
• fieldname = name of field to integrate

Examples

fix_modify AtC output volume_integral eset1 mass_density

Description

Performs volume integration of specified field over elementset and outputs resulting variable values to GLOBALS file.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix atc command

Default

None.

17.83.53 fix_modify AtC pair_interactions command

17.83.54 fix_modify AtC bond_interactions command

Syntax

fix_modify <AtC fixID> pair_interactions <on|off>

fix_modify <AtC fixID> bond_interactions <on|off>

1280 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• AtC fixID = ID of fix atc instance

• pair_interactions or bond_interactions = name of the AtC sub-command
• on or off = activate or deactivate

Examples

fix_modify AtC pair_interactions off

fix_modify AtC bond_interactions on

Description

Include bonds and/or pairs in stress and heat flux computations.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

pair_interactions: on, bond_interactions: off

17.83.55 fix_modify AtC poisson_solver command

Syntax

fix_modify <AtC fixID> poisson_solver mesh create <nx> <ny> <nz> <region-ID> <f|p> <f|p>
,→<f|p>

• AtC fixID = ID of fix atc instance

• poisson_solver = name of the AtC sub-command
• nx ny nz = number of elements in x, y, and z
• region-id = id of region to be meshed
• f or p = periodicity flags for x, y, and z

17.83. fix_modify AtC commands 1281

LAMMPS Documentation, Release stable 29Sep2021

Examples

fix_modify AtC poisson_solver mesh create 10 1 1 feRegion p p p

Description

Creates a uniform mesh in a rectangular region.

Restrictions

Creates only uniform rectangular grids in rectangular regions.

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83.56 fix_modify AtC read_restart command

Syntax

fix_modify <AtC fixID> read_restart <file_name>

• AtC fixID = ID of fix atc instance

• read_restart = name of the AtC sub-command
• file_name = name of AtC restart file

Examples

fix_modify AtC read_restart restart.mydata.AtC

Description

Reads the current state of the AtC fields from a named text-based restart file.

1282 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Restrictions

The restart file only contains fields and their time derivatives. The reference positions of the atoms and the commands
that initialize the fix are not saved e.g. an identical mesh containing the same atoms will have to be recreated.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC write_restart

Default

None.

17.83.57 fix_modify AtC remove_molecule command

Syntax

fix_modify <AtC fixID> remove_molecule <tag>

• AtC fixID = ID of fix atc instance

• remove_molecule = name of the AtC sub-command
• tag = tag for tracking a molecule

Examples

fix_modify AtC remove_molecule water

Description

Removes tag designated for tracking a specified set of molecules.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC add_species
• fix_modify AtC add_molecule
• fix_modify AtC remove_species

17.83. fix_modify AtC commands 1283

LAMMPS Documentation, Release stable 29Sep2021

Default

None.

17.83.58 fix_modify AtC remove_source command

Syntax

fix_modify <AtC fixID> remove_source <field> <element_set>

• AtC fixID = ID of fix atc instance

• remove_source = name of the AtC sub-command
• field = field kind name valid for type of physics: temperature or electron_temperature
• element_set = name of set of elements

Examples

fix_modify AtC remove_source temperature groupNAME

Description

Remove a domain source.

Restrictions

The keyword all is reserved and thus not available as element_set name.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC source

Default

None.

17.83.59 fix_modify AtC remove_species command

Syntax

fix_modify <AtC fixID> remove_species <tag>

• AtC fixID = ID of fix atc instance

• remove_species = name of the AtC sub-command

1284 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• tag = tag for tracking a species

Examples

fix_modify AtC remove_species gold

Description

Removes tag designated for tracking a specified species.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC add_species
• fix_modify AtC add_molecule
• fix_modify AtC remove_molecule

Default

None.

17.83.60 fix_modify AtC reset_atomic_reference_positions command

Syntax

fix_modify <AtC fixID> reset_atomic_reference_positions

• AtC fixID = ID of fix atc instance

• reset_atomic_reference_positions = name of the AtC sub-command

Examples

fix_modify AtC reset_atomic_reference_positions

17.83. fix_modify AtC commands 1285

LAMMPS Documentation, Release stable 29Sep2021

Description

Resets the atomic positions ATC uses to perform point to field operations. In can be used to use perfect lattice sites in
ATC but a thermalized or deformed lattice in LAMMPS.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

None

17.83.61 fix_modify AtC reset_time command

Syntax

fix_modify <AtC fixID> reset_time <value>

• AtC fixID = ID of fix atc instance

• reset_time = name of the AtC sub-command
• value = new time value

Examples

fix_modify AtC reset_time 0.0

Description

Resets the simulation time counter.

Restrictions

None.

1286 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

Default

None

17.83.62 fix_modify AtC sample_frequency command

Syntax

fix_modify <AtC fixID> sample_frequency <freq>

• AtC fixID = ID of fix atc instance

• sample_frequency = name of the AtC sub-command
• freq = frequency to sample fields in number of steps

Examples

fix_modify AtC sample_frequency 10

Description

Specifies a frequency at which fields are computed for the case where time filters are being applied.

Restrictions

Must be used with fix atc hardy and is only relevant when time filters are being used.

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83. fix_modify AtC commands 1287

LAMMPS Documentation, Release stable 29Sep2021

17.83.63 fix_modify AtC set reference_potential_energy command

Syntax

fix_modify <AtC fixID> set reference_potential_energy [<value|filename>]

• AtC fixID = ID of fix atc instance

• set reference_potential_energy = name of the AtC sub-command
• value = optional user specified zero point for PE in native LAMMPS energy units
• filename = optional user specified string for file of nodal PE values to be read-in

Examples

fix_modify AtC set reference_potential_energy

fix_modify AtC set reference_potential_energy -0.05
fix_modify AtC set reference_potential_energy myPEvalues

Description

Used to set various quantities for the post-processing algorithms. It sets the zero point for the potential energy density
using the value provided for all nodes, or from the current configuration of the lattice if no value is provided, or values
provided within the specified filename.

Restrictions

Must be used with fix atc hardy or fix atc field.

Related AtC commands

• fix_modify AtC command overview

Default

Defaults to the LAMMPS zero point i.e. isolated atoms.

17.83.64 fix_modify AtC source command

Syntax

fix_modify <AtC fixID> source <field> <element_set> <value|function>

• AtC fixID = ID of fix atc instance

• source = name of the AtC sub-command
• field = field kind name valid for type of physics: temperature or electron_temperature
• element_set = name of set of elements

1288 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• value or function = value or name of function followed by its parameters

Examples

fix_modify AtC source temperature middle temporal_ramp 10.0 0.0

Description

Add domain sources to the mesh. The units are consistent with LAMMPS’s units for mass, length and time and are
defined by the PDE being solved, e.g. for thermal transfer the balance equation is for energy and source is energy per
time.

Restrictions

The keyword all is reserved and thus not available as element_set name.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC remove_source

Default

None.

17.83.65 fix_modify AtC source_integration command

Syntax

fix_modify <AtC fixID> source_integration <fe|atom>

• AtC fixID = ID of fix atc instance

• source_integration = name of the AtC sub-command
• fe or atom = (undocumented)

Examples

fix_modify AtC source_integration atom

17.83. fix_modify AtC commands 1289

LAMMPS Documentation, Release stable 29Sep2021

Description

(undocumented)

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

Default is fe

17.83.66 fix_modify AtC temperature_definition command

Syntax

fix_modify <AtC fixID> temperature_definition <kinetic|total>

• AtC fixID = ID of fix atc instance

• temperature_definition = name of the AtC sub-command
• kinetic or total = (undocumented)

Examples

fix_modify AtC temperature_definition kinetic

Description

Change the definition for the atomic temperature used to create the finite element temperature. The kinetic option is
based only on the kinetic energy of the atoms while the total option uses the total energy (kinetic + potential) of an
atom.

Restrictions

This command is only valid when using thermal coupling. Also, while not a formal restriction, the user should ensure
that associating a potential energy with each atom makes physical sense for the total option to be meaningful.

1290 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

Default

kinetic

17.83.67 fix_modify AtC filter command

Syntax

fix_modify <AtC fixID> filter <on|off|equilibrate>

• AtC fixID = ID of fix atc instance

• filter = name of the AtC sub-command
• on or off or equilibrate = Select state of filter

Examples

fix_modify AtC filter on

Description

Filters the MD dynamics to construct a more appropriate continuous field. Equilibrating first filters the time derivatives
without changing the dynamics to provide a better initial condition to the filtered dynamics.

Restrictions

Only for use with these specific transfers: thermal, two_temperature

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC filter scale
• fix_modify AtC equilibrium_start

17.83. fix_modify AtC commands 1291

LAMMPS Documentation, Release stable 29Sep2021

Default

off

17.83.68 fix_modify AtC time_integration command

Syntax

fix_modify <AtC fixID> time_integration <descriptor>

• AtC fixID = ID of fix atc instance

• time_integration = name of the AtC sub-command
• descriptor = gear or fractional_step or verlet

Examples

fix_modify AtC time_integration fractional_step

Description

Command to select the thermal or momentum time integration.

Options for thermal time integration:

gear atomic velocity update with second order Verlet, nodal temperature update with third or fourth order Gear, ther-
mostats based on controlling power
fractional_step atomic velocity update with second order Verlet, mixed nodal temperature update, 3/4 Gear for con-
tinuum and 2 Verlet for atomic contributions, thermostats based on controlling discrete energy changes

Options for momentum time integration:

verlet atomic velocity update with second order Verlet, nodal temperature update with second order Verlet, kinetostats
based on controlling force
fractional_step atomic velocity update with second order Verlet, mixed nodal momentum update, second order Verlet
for continuum and exact second order Verlet for atomic contributions, kinetostats based on controlling discrete
momentum changes
gear atomic velocity update with second order Verlet, nodal temperature update with third or fourth order Gear, kine-
tostats based on controlling power.

1292 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

None.

17.83.69 fix_modify AtC track_displacement command

Syntax

fix_modify <AtC fixID> track_displacement <on|off>

• AtC fixID = ID of fix atc instance

• track_displacement = name of the AtC sub-command
• on or off = (undocumented)

Examples

fix_modify AtC track_displacement on

Description

Determines whether displacement is tracked or not. For solids problems this is a useful quantity, but for fluids it is not
relevant.

Restrictions

Some constitutive models require the displacement field.

Related AtC commands

• fix_modify AtC command overview

17.83. fix_modify AtC commands 1293

LAMMPS Documentation, Release stable 29Sep2021

Default

on

17.83.70 fix_modify AtC unfix command

Syntax

fix_modify <AtC fixID> unfix <field> <nodeset>

• AtC fixID = ID of fix atc instance

• unfix = name of the AtC sub-command
• field = field kind name valid for type of physics: temperature or electron_temperature
• nodeset = name of set of nodes to apply boundary condition

Examples

fix_modify AtC unfix temperature groupNAME

Description

Removes constraint on field values for specified nodes.

Restrictions

The keyword all is reserved and thus not available as nodeset name.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC fix

Default

None.

17.83.71 fix_modify AtC unfix_flux command

Syntax

fix_modify <AtC fixID> unfix_flux <field> <face_set> <value|function>

• AtC fixID = ID of fix atc instance

• unfix_flux = name of the AtC sub-command

1294 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• field = field kind name valid for type of physics: temperature or electron_temperature
• face_set = name of set of element faces

Examples

fix_modify AtC unfix_flux temperature faceSet

Description

Command for removing prescribed normal fluxes e.g. heat_flux, stress.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC fix_flux

Default

None.

17.83.72 fix_modify AtC write_atom_weights command

Syntax

fix_modify <AtC fixID> write_atom_weights <filename> <frequency>

• AtC fixID = ID of fix atc instance

• write_atom_weights = name of the AtC sub-command
• filename = name of file that atomic weights are written to
• frequency = how often writes will occur

Examples

fix_modify AtC write_atom_weights atm_wt_file.txt 10

17.83. fix_modify AtC commands 1295

LAMMPS Documentation, Release stable 29Sep2021

Description

Command for writing the values of atomic weights to a specified file.

Restrictions

None.

Related AtC commands

• fix_modify AtC command overview

Default

None

17.83.73 fix_modify AtC write_restart command

Syntax

fix_modify <AtC fixID> write_restart <file_name>

• AtC fixID = ID of fix atc instance

• write_restart = name of the AtC sub-command
• file_name = name of AtC restart file

Examples

fix_modify AtC write_restart restart.mydata.AtC

Description

Dumps the current state of the fields to a named text-based restart file. This done when the command is invoked and
not repeated, unlike the otherwise similar LAMMPS command.

Restrictions

None.

1296 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Related AtC commands

• fix_modify AtC command overview

• fix_modify AtC read_restart

Default

None.

17.84 fix momentum command

Accelerator Variants: momentum/kk

17.85 fix momentum/chunk command

17.85.1 Syntax

fix ID group-ID momentum N keyword values ...

• ID, group-ID are documented in fix command

• momentum = style name of this fix command
• N = adjust the momentum every this many timesteps one or more keyword/value pairs may be appended
• keyword = linear or angular or rescale
fix ID group-ID momentum/chunk N chunkID keyword values . . .
• ID, group-ID are documented in fix command
• momentum/chunk = style name of this fix command
• N = adjust the momentum per chunk every this many timesteps
• chunkID = ID of compute chunk/atom command
one or more keyword/value pairs may be appended
• keyword = linear or angular or rescale
linear values = xflag yflag zflag
xflag,yflag,zflag = 0/1 to exclude/include each dimension
angular values = none
rescale values = none

17.84. fix momentum command 1297

LAMMPS Documentation, Release stable 29Sep2021

17.85.2 Examples

fix 1 all momentum 1 linear 1 1 0

fix 1 all momentum 1 linear 1 1 1 rescale
fix 1 all momentum 100 linear 1 1 1 angular
fix 1 all momentum/chunk 100 molchunk linear 1 1 1 angular

17.85.3 Description

Fix momentum zeroes the linear and/or angular momentum of the group of atoms every N timesteps by adjusting the
velocities of the atoms. Fix momentum/chunk works equivalently, but operates on a per-chunk basis.
One (or both) of the linear or angular keywords must be specified.
If the linear keyword is used, the linear momentum is zeroed by subtracting the center-of-mass velocity of the group
or chunk from each atom. This does not change the relative velocity of any pair of atoms. One or more dimensions can
be excluded from this operation by setting the corresponding flag to 0.
If the angular keyword is used, the angular momentum is zeroed by subtracting a rotational component from each
atom.
This command can be used to insure the entire collection of atoms (or a subset of them) does not drift or rotate during
the simulation due to random perturbations (e.g. fix langevin thermostatting).
The rescale keyword enables conserving the kinetic energy of the group or chunk of atoms by rescaling the velocities
after the momentum was removed.
Note that the velocity command can be used to create initial velocities with zero aggregate linear and/or angular mo-
mentum.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.85.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

1298 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.85.5 Restrictions

Fix momentum/chunk is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package.
See the Build package page for more info.

17.85.6 Related commands

fix recenter, velocity

17.85.7 Default

none

17.86 fix move command

17.86.1 Syntax

fix ID group-ID move style args keyword values ...

• ID, group-ID are documented in fix command

• move = style name of this fix command
• style = linear or wiggle or rotate or variable
linear args = Vx Vy Vz
Vx,Vy,Vz = components of velocity vector (velocity units), any component can be␣
,→specified as NULL

wiggle args = Ax Ay Az period

Ax,Ay,Az = components of amplitude vector (distance units), any component can be␣
,→specified as NULL

period = period of oscillation (time units)

rotate args = Px Py Pz Rx Ry Rz period
Px,Py,Pz = origin point of axis of rotation (distance units)
Rx,Ry,Rz = axis of rotation vector
period = period of rotation (time units)
variable args = v_dx v_dy v_dz v_vx v_vy v_vz
v_dx,v_dy,v_dz = 3 variable names that calculate x,y,z displacement as function␣
,→of time, any component can be specified as NULL

v_vx,v_vy,v_vz = 3 variable names that calculate x,y,z velocity as function of␣

,→time, any component can be specified as NULL

• zero or more keyword/value pairs may be appended

• keyword = units
units value = box or lattice

17.86. fix move command 1299

LAMMPS Documentation, Release stable 29Sep2021

17.86.2 Examples

fix 1 boundary move wiggle 3.0 0.0 0.0 1.0 units box
fix 2 boundary move rotate 0.0 0.0 0.0 0.0 0.0 1.0 5.0
fix 2 boundary move variable v_myx v_myy NULL v_VX v_VY NULL

17.86.3 Description

Perform updates of position and velocity for atoms in the group each timestep using the specified settings or formulas,
without regard to forces on the atoms. This can be useful for boundary or other atoms, whose movement can influence
nearby atoms.

Note: The atoms affected by this fix should not normally be time integrated by other fixes (e.g. fix nve, fix nvt), since
that will change their positions and velocities twice.

Note: As atoms move due to this fix, they will pass through periodic boundaries and be remapped to the other side of
the simulation box, just as they would during normal time integration (e.g. via the fix nve command). It is up to you to
decide whether periodic boundaries are appropriate with the kind of atom motion you are prescribing with this fix.

Note: As discussed below, atoms are moved relative to their initial position at the time the fix is specified. These
initial coordinates are stored by the fix in “unwrapped” form, by using the image flags associated with each atom. See
the dump custom command for a discussion of “unwrapped” coordinates. See the Atoms section of the read_data
command for a discussion of image flags and how they are set for each atom. You can reset the image flags (e.g. to 0)
before invoking this fix by using the set image command.

The linear style moves atoms at a constant velocity, so that their position X = (x,y,z) as a function of time is given in
vector notation as
X(t) = X0 + V * delta
where X0 = (x0,y0,z0) is their position at the time the fix is specified, V is the specified velocity vector with components
(Vx,Vy,Vz), and delta is the time elapsed since the fix was specified. This style also sets the velocity of each atom to V
= (Vx,Vy,Vz). If any of the velocity components is specified as NULL, then the position and velocity of that component
is time integrated the same as the fix nve command would perform, using the corresponding force component on the
atom.
Note that the linear style is identical to using the variable style with an equal-style variable that uses the vdisplace()
function. E.g.

variable V equal 10.0

variable x equal vdisplace(0.0,$V)
fix 1 boundary move variable v_x NULL NULL v_V NULL NULL

The wiggle style moves atoms in an oscillatory fashion, so that their position X = (x,y,z) as a function of time is given
in vector notation as
X(t) = X0 + A sin(omega*delta)

1300 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

where X0 = (x0,y0,z0) is their position at the time the fix is specified, A is the specified amplitude vector with com-
ponents (Ax,Ay,Az), omega is 2 PI / period, and delta is the time elapsed since the fix was specified. This style also
sets the velocity of each atom to the time derivative of this expression. If any of the amplitude components is specified
as NULL, then the position and velocity of that component is time integrated the same as the fix nve command would
perform, using the corresponding force component on the atom.
Note that the wiggle style is identical to using the variable style with equal-style variables that use the swiggle() and
cwiggle() functions. E.g.

variable A equal 10.0

variable T equal 5.0
variable omega equal 2.0*PI/$T
variable x equal swiggle(0.0,$A,$T)
variable v equal v_omega*($A-cwiggle(0.0,$A,$T))
fix 1 boundary move variable v_x NULL NULL v_v NULL NULL

The rotate style rotates atoms around a rotation axis R = (Rx,Ry,Rz) that goes through a point P = (Px,Py,Pz). The
period of the rotation is also specified. The direction of rotation for the atoms around the rotation axis is consistent with
the right-hand rule: if your right-hand thumb points along R, then your fingers wrap around the axis in the direction of
rotation.
This style also sets the velocity of each atom to (omega cross Rperp) where omega is its angular velocity around the
rotation axis and Rperp is a perpendicular vector from the rotation axis to the atom. If the defined atom_style assigns
an angular velocity or angular momentum or orientation to each atom (atom styles sphere, ellipsoid, line, tri, body),
then those properties are also updated appropriately to correspond to the atom’s motion and rotation over time.
The variable style allows the position and velocity components of each atom to be set by formulas specified via the
variable command. Each of the 6 variables is specified as an argument to the fix as v_name, where name is the variable
name that is defined elsewhere in the input script.
Each variable must be of either the equal or atom style. Equal-style variables compute a single numeric quantity, that
can be a function of the timestep as well as of other simulation values. Atom-style variables compute a numeric quantity
for each atom, that can be a function per-atom quantities, such as the atom’s position, as well as of the timestep and
other simulation values. Note that this fix stores the original coordinates of each atom (see note below) so that per-atom
quantity can be used in an atom-style variable formula. See the variable command for details.
The first 3 variables (v_dx,v_dy,v_dz) specified for the variable style are used to calculate a displacement from the
atom’s original position at the time the fix was specified. The second 3 variables (v_vx,v_vy,v_vz) specified are used
to compute a velocity for each atom.
Any of the 6 variables can be specified as NULL. If both the displacement and velocity variables for a particular x,y,z
component are specified as NULL, then the position and velocity of that component is time integrated the same as the
fix nve command would perform, using the corresponding force component on the atom. If only the velocity variable
for a component is specified as NULL, then the displacement variable will be used to set the position of the atom, and
its velocity component will not be changed. If only the displacement variable for a component is specified as NULL,
then the velocity variable will be used to set the velocity of the atom, and the position of the atom will be time integrated
using that velocity.
The units keyword determines the meaning of the distance units used to define the linear velocity and wiggle amplitude
and rotate origin. This setting is ignored for the variable style. A box value selects standard units as defined by the
units command, e.g. velocity in Angstroms/fs and amplitude and position in Angstroms for units = real. A lattice
value means the velocity units are in lattice spacings per time and the amplitude and position are in lattice spacings.
The lattice command must have been previously used to define the lattice spacing. Each of these 3 quantities may be
dependent on the x,y,z dimension, since the lattice spacings can be different in x,y,z.

17.86. fix move command 1301

LAMMPS Documentation, Release stable 29Sep2021

17.86.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the original coordinates of moving atoms to binary restart files, as well as the initial timestep, so that
the motion can be continuous in a restarted simulation. See the read_restart command for info on how to re-specify a
fix in an input script that reads a restart file, so that the operation of the fix continues in an uninterrupted fashion.

Note: Because the move positions are a function of the current timestep and the initial timestep, you cannot reset the
timestep to a different value after reading a restart file, if you expect a fix move command to work in an uninterrupted
fashion.

None of the fix_modify options are relevant to this fix.

This fix produces a per-atom array which can be accessed by various output commands. The number of columns for
each atom is 3, and the columns store the original unwrapped x,y,z coords of each atom. The per-atom values can be
accessed on any timestep.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.
For rRESPA time integration, this fix adjusts the position and velocity of atoms on the outermost rRESPA level.

17.86.5 Restrictions

none

17.86.6 Related commands

fix nve, displace_atoms

17.86.7 Default

none
The option default is units = lattice.

17.87 fix mscg command

17.87.1 Syntax

fix ID group-ID mscg N keyword args ...

• ID, group-ID are documented in fix command

• mscg = style name of this fix command
• N = envoke this fix every this many timesteps
• zero or more keyword/value pairs may be appended
• keyword = range or name or max

1302 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

range arg = on or off

on = range finding functionality is performed
off = force matching functionality is performed
name args = name1 ... nameN
name1,...,nameN = string names for each atom type (1-Ntype)
max args = maxb maxa maxd
maxb,maxa,maxd = maximum bonds/angles/dihedrals per atom

17.87.2 Examples

fix 1 all mscg 1

fix 1 all mscg 1 range name A B
fix 1 all mscg 1 max 4 8 20

17.87.3 Description

This fix applies the Multi-Scale Coarse-Graining (MSCG) method to snapshots from a dump file to generate potentials
for coarse-grained simulations from all-atom simulations, using a force-matching technique (Izvekov, Noid).
It makes use of the MS-CG library, written and maintained by Greg Voth’s group at the University of Chicago, which
is freely available on their MS-CG GitHub site. See instructions on obtaining and installing the MS-CG library in
the src/MSCG/README file, which must be done before you build LAMMPS with this fix command and use the
command in a LAMMPS input script.
An example script using this fix is provided the examples/mscg directory.
The general workflow for using LAMMPS in conjunction with the MS-CG library to create a coarse-grained model
and run coarse-grained simulations is as follows:
1. Perform all-atom simulations on the system to be coarse grained.
2. Generate a trajectory mapped to the coarse-grained model.
3. Create input files for the MS-CG library.
4. Run the range finder functionality of the MS-CG library.
5. Run the force matching functionality of the MS-CG library.
6. Check the results of the force matching.
7. Run coarse-grained simulations using the new coarse-grained potentials.
This fix can perform the range finding and force matching steps 4 and 5 of the above workflow when used in conjunction
with the rerun command. It does not perform steps 1-3 and 6-7.
Step 2 can be performed using a Python script (what is the name?) provided with the MS-CG library which defines the
coarse-grained model and converts a standard LAMMPS dump file for an all-atom simulation (step 1) into a LAMMPS
dump file which has the positions of and forces on the coarse-grained beads.
In step 3, an input file named “control.in” is needed by the MS-CG library which sets parameters for the range finding
and force matching functionalities. See the examples/mscg/control.in file as an example. And see the documentation
provided with the MS-CG library for more info on this file.
When this fix is used to perform steps 4 and 5, the MS-CG library also produces additional output files. The range finder
functionality (step 4) outputs files defining pair and bonded interaction ranges. The force matching functionality (step
5) outputs tabulated force files for every interaction in the system. Other diagnostic files can also be output depending

17.87. fix mscg command 1303

LAMMPS Documentation, Release stable 29Sep2021

on the parameters in the MS-CG library input script. Again, see the documentation provided with the MS-CG library
for more info.

The range keyword specifies which MS-CG library functionality should be invoked. If on, the step 4 range finder
functionality is invoked. off, the step 5 force matching functionality is invoked.
If the name keyword is used, string names are defined to associate with the integer atom types in LAMMPS. Ntype
names must be provided, one for each atom type (1-Ntype).
The max keyword specifies the maximum number of bonds, angles, and dihedrals a bead can have in the coarse-grained
model.

17.87.4 Restrictions

This fix is part of the MSCG package. It is only enabled if LAMMPS was built with that package. See the Build
package doc page for more info.
The MS-CG library uses C++11, which may not be supported by older compilers. The MS-CG library also has some
additional numeric library dependencies, which are described in its documentation.
Currently, the MS-CG library is not setup to run in parallel with MPI, so this fix can only be used in a serial LAMMPS
build and run on a single processor.

17.87.5 Related commands

none

17.87.6 Default

The default keyword settings are range off, max 4 12 36.

(Izvekov) Izvekov, Voth, J Chem Phys 123, 134105 (2005).

(Noid) Noid, Chu, Ayton, Krishna, Izvekov, Voth, Das, Andersen, J Chem Phys 128, 134105 (2008).

17.88 fix msst command

17.88.1 Syntax

fix ID group-ID msst dir shockvel keyword value ...

• ID, group-ID are documented in fix command

• msst = style name of this fix
• dir = x or y or z
• shockvel = shock velocity (strictly positive, distance/time units)
• zero or more keyword value pairs may be appended
• keyword = q or mu or p0 or v0 or e0 or tscale or beta or dftb

1304 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

q value = cell mass-like parameter (mass^2/distance^4 units)

mu value = artificial viscosity (mass/length/time units)
p0 value = initial pressure in the shock equations (pressure units)
v0 value = initial simulation cell volume in the shock equations (distance^3 units)
e0 value = initial total energy (energy units)
tscale value = reduction in initial temperature (unitless fraction between 0.0 and␣
,→1.0)

dftb value = yes or no for whether using MSST in conjunction with DFTB+
beta value = scale factor for improved energy conservation

17.88.2 Examples

fix 1 all msst y 100.0 q 1.0e5 mu 1.0e5

fix 2 all msst z 50.0 q 1.0e4 mu 1.0e4 v0 4.3419e+03 p0 3.7797e+03 e0 -9.72360e+02␣
,→tscale 0.01

fix 1 all msst y 100.0 q 1.0e5 mu 1.0e5 dftb yes beta 0.5

17.88.3 Description

This command performs the Multi-Scale Shock Technique (MSST) integration to update positions and velocities each
timestep to mimic a compressive shock wave passing over the system. See (Reed) for a detailed description of this
method. The MSST varies the cell volume and temperature in such a way as to restrain the system to the shock
Hugoniot and the Rayleigh line. These restraints correspond to the macroscopic conservation laws dictated by a shock
front. shockvel determines the steady shock velocity that will be simulated.
To perform a simulation, choose a value of q that provides volume compression on the timescale of 100 fs to 1 ps. If
the volume is not compressing, either the shock speed is chosen to be below the material sound speed or p0 has been
chosen inaccurately. Volume compression at the start can be sped up by using a non-zero value of tscale. Use the
smallest value of tscale that results in compression.
Under some special high-symmetry conditions, the pressure (volume) and/or temperature of the system may oscillate
for many cycles even with an appropriate choice of mass-like parameter q. Such oscillations have physical significance
in some cases. The optional mu keyword adds an artificial viscosity that helps break the system symmetry to equilibrate
to the shock Hugoniot and Rayleigh line more rapidly in such cases.
The keyword tscale is a factor between 0 and 1 that determines what fraction of thermal kinetic energy is converted to
compressive strain kinetic energy at the start of the simulation. Setting this parameter to a non-zero value may assist
in compression at the start of simulations where it is slow to occur.
If keywords e0, p0,or v0 are not supplied, these quantities will be calculated on the first step, after the energy specified
by tscale is removed. The value of e0 is not used in the dynamical equations, but is used in calculating the deviation
from the Hugoniot.
The keyword beta is a scaling term that can be added to the MSST ionic equations of motion to account for drift in the
conserved quantity during long timescale simulations, similar to a Berendsen thermostat. See (Reed) and (Goldman)
for more details. The value of beta must be between 0.0 and 1.0 inclusive. A value of 0.0 means no contribution, a
value of 1.0 means a full contribution.
Values of shockvel less than a critical value determined by the material response will not have compressive solutions.
This will be reflected in lack of significant change of the volume in the MSST.
For all pressure styles, the simulation box stays orthogonal in shape. Parrinello-Rahman boundary conditions (tilted
box) are supported by LAMMPS, but are not implemented for MSST.
This fix computes a temperature and pressure and potential energy each timestep. To do this, the fix creates its own
computes of style “temp” “pressure”, and “pe”, as if these commands had been issued:

17.88. fix msst command 1305

LAMMPS Documentation, Release stable 29Sep2021

compute fix-ID_MSST_temp all temp

compute fix-ID_MSST_press all pressure fix-ID_MSST_temp

compute fix-ID_MSST_pe all pe

See the compute temp and compute pressure commands for details. Note that the IDs of the new computes are the
fix-ID + “_MSST_temp” or “MSST_press” or “_MSST_pe”. The group for the new computes is “all”.

The dftb keyword is to allow this fix to be used when LAMMPS is being driven by DFTB+, a density-functional tight-
binding code. If the keyword dftb is used with a value of yes, then the MSST equations are altered to account for the
electron entropy contribution to the Hugonio relations and total energy. See (Reed2) and (Goldman) for details on this
contribution. In this case, you must define a fix external command in your input script, which is used to callback to
DFTB+ during the LAMMPS timestepping. DFTB+ will communicate its info to LAMMPS via that fix.

17.88.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of all internal variables to binary restart files. See the read_restart command for info on how
to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an uninterrupted
fashion.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
The progress of the MSST can be monitored by printing the global scalar and global vector quantities computed by the
fix.
As mentioned above, the scalar is the cumulative energy change due to the fix. By monitoring the thermodynamic
econserve output, this can be used to test if the MD timestep is sufficiently small for accurate integration of the dynamic
equations.
The global vector contains four values in the following order. The vector values output by this fix are “intensive”.
[dhugoniot, drayleigh, lagrangian_speed, lagrangian_position]
1. dhugoniot is the departure from the Hugoniot (temperature units).
2. drayleigh is the departure from the Rayleigh line (pressure units).
3. lagrangian_speed is the laboratory-frame Lagrangian speed (particle velocity) of the computational cell (velocity
units).
4. lagrangian_position is the computational cell position in the reference frame moving at the shock speed. This is
usually a good estimate of distance of the computational cell behind the shock front.
To print these quantities to the log file with descriptive column headers, the following LAMMPS commands are sug-
gested:

fix msst all msst z

variable dhug equal f_msst[1]
variable dray equal f_msst[2]
variable lgr_vel equal f_msst[3]
(continues on next page)

1306 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

variable lgr_pos equal f_msst[4]
thermo_style custom step temp ke pe lz pzz econserve v_dhug v_dray v_lgr_vel v_lgr_
,→pos f_msst

17.88.5 Restrictions

This fix style is part of the SHOCK package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
All cell dimensions must be periodic. This fix can not be used with a triclinic cell. The MSST fix has been tested only
for the group-ID all.

17.88.6 Related commands

fix nphug, fix deform

17.88.7 Default

The keyword defaults are q = 10, mu = 0, tscale = 0.01, dftb = no, beta = 0.0. Note that p0, v0, and e0 are calculated
on the first timestep.

(Reed) Reed, Fried, and Joannopoulos, Phys. Rev. Lett., 90, 235503 (2003).
(Reed2) Reed, J. Phys. Chem. C, 116, 2205 (2012).
(Goldman) Goldman, Srinivasan, Hamel, Fried, Gaus, and Elstner, J. Phys. Chem. C, 117, 7885 (2013).

17.89 fix mvv/dpd command

17.90 fix mvv/edpd command

17.91 fix mvv/tdpd command

17.91.1 Syntax

fix ID group-ID mvv/dpd lambda

fix ID group-ID mvv/edpd lambda

fix ID group-ID mvv/tdpd lambda

• ID, group-ID are documented in fix command

• mvv/dpd, mvv/edpd, mvv/tdpd = style name of this fix command
• lambda = (optional) relaxation parameter (unitless)

17.89. fix mvv/dpd command 1307

LAMMPS Documentation, Release stable 29Sep2021

17.91.2 Examples

fix 1 all mvv/dpd

fix 1 all mvv/dpd 0.5
fix 1 all mvv/edpd
fix 1 all mvv/edpd 0.5
fix 1 all mvv/tdpd
fix 1 all mvv/tdpd 0.5

17.91.3 Description

Perform time integration using the modified velocity-Verlet (MVV) algorithm to update position and velocity (fix
mvv/dpd), or position, velocity and temperature (fix mvv/edpd), or position, velocity and concentration (fix mvv/tdpd)
for particles in the group each timestep.
The modified velocity-Verlet (MVV) algorithm aims to improve the stability of the time integrator by using an extrap-
olated version of the velocity for the force evaluation:

∆t ∆t
v(t + ) =v(t) + · a(t)
2 2
∆t
r(t + ∆t) =r(t) + ∆t · v(t + )
2
1
a(t + ∆t) = · F [r(t + ∆t), v(t) + λ · ∆t · a(t)]
m
∆t ∆t
v(t + ∆t) =v(t + )+ · a(t + ∆t)
2 2
where the parameter λ depends on the specific choice of DPD parameters, and needs to be tuned on a case-by-case
basis. Specification of a lambda value is optional. If specified, the setting must be from 0.0 to 1.0. If not specified, a
default value of 0.5 is used, which effectively reproduces the standard velocity-Verlet (VV) scheme. For more details,
see Groot.
Fix mvv/dpd updates the position and velocity of each atom. It can be used with the pair_style mdpd command or other
pair styles such as pair dpd.
Fix mvv/edpd updates the per-atom temperature, in addition to position and velocity, and must be used with the
pair_style edpd command.
Fix mvv/tdpd updates the per-atom chemical concentration, in addition to position and velocity, and must be used with
the pair_style tdpd command.

17.91.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

1308 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.91.5 Restrictions

This fix is part of the DPD-MESO package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.91.6 Related commands

pair_style mdpd, pair_style edpd, pair_style tdpd

17.91.7 Default

The default value for the optional lambda parameter is 0.5.

(Groot) Groot and Warren, J Chem Phys, 107: 4423-4435 (1997). DOI: 10.1063/1.474784

17.92 fix neb command

17.92.1 Syntax

fix ID group-ID neb Kspring keyword value

• ID, group-ID are documented in fix command

• neb = style name of this fix command
• Kspring = spring constant for parallel nudging force (force/distance units or force units, see parallel keyword)
• zero or more keyword/value pairs may be appended
• keyword = parallel or perp or end
parallel value = neigh or ideal
neigh = parallel nudging force based on distance to neighbor replicas (Kspring = force/
,→distance units)

ideal = parallel nudging force based on interpolated ideal position (Kspring = force␣
,→units)

perp value = Kspring2

Kspring2 = spring constant for perpendicular nudging force (force/distance units)
end values = estyle Kspring3
estyle = first or last or last/efirst or last/efirst/middle
first = apply force to first replica
last = apply force to last replica
last/efirst = apply force to last replica and set its target energy to that of first␣
,→replica

last/efirst/middle = same as last/efirst plus prevent middle replicas having lower␣

,→energy than first replica

Kspring3 = spring constant for target energy term (1/distance units)

17.92. fix neb command 1309

LAMMPS Documentation, Release stable 29Sep2021

17.92.2 Examples

fix 1 active neb 10.0

fix 2 all neb 1.0 perp 1.0 end last
fix 2 all neb 1.0 perp 1.0 end first 1.0 end last 1.0
fix 1 all neb 1.0 parallel ideal end last/efirst 1

17.92.3 Description

Add nudging forces to atoms in the group for a multi-replica simulation run via the neb command to perform a nudged
elastic band (NEB) calculation for finding the transition state. Hi-level explanations of NEB are given with the neb
command and on the Howto replica doc page. The fix neb command must be used with the “neb” command and defines
how inter-replica nudging forces are computed. A NEB calculation is divided in two stages. In the first stage n replicas
are relaxed toward a MEP until convergence. In the second stage, the climbing image scheme (see (Henkelman2)) is
enabled, so that the replica having the highest energy relaxes toward the saddle point (i.e. the point of highest energy
along the MEP), and a second relaxation is performed.
A key purpose of the nudging forces is to keep the replicas equally spaced. During the NEB calculation, the 3N-length
vector of interatomic force Fi = -Grad(V) for each replica I is altered. For all intermediate replicas (i.e. for 1 < I < N,
except the climbing replica) the force vector becomes:

Fi = -Grad(V) + (Grad(V) dot T') T' + Fnudge_parallel + Fnudge_perp

T’ is the unit “tangent” vector for replica I and is a function of Ri, Ri-1, Ri+1, and the potential energy of the 3 replicas;
it points roughly in the direction of (Ri+i - Ri-1); see the (Henkelman1) paper for details. Ri are the atomic coordinates
of replica I; Ri-1 and Ri+1 are the coordinates of its neighbor replicas. The term (Grad(V) dot T’) is used to remove
the component of the gradient parallel to the path which would tend to distribute the replica unevenly along the path.
Fnudge_parallel is an artificial nudging force which is applied only in the tangent direction and which maintains the
equal spacing between replicas (see below for more information). Fnudge_perp is an optional artificial spring which
is applied in a direction perpendicular to the tangent direction and which prevent the paths from forming acute kinks
(see below for more information).
In the second stage of the NEB calculation, the interatomic force Fi for the climbing replica (the replica of highest
energy after the first stage) is changed to:

Fi = -Grad(V) + 2 (Grad(V) dot T') T' + Fnudge_perp

and the relaxation procedure is continued to a new converged MEP.

The keyword parallel specifies how the parallel nudging force is computed. With a value of neigh, the parallel nudging
force is computed as in (Henkelman1) by connecting each intermediate replica with the previous and the next image:
Fnudge_parallel = Kspring * (|Ri+1 - Ri| - |Ri - Ri-1|)
Note that in this case the specified Kspring is in force/distance units.
With a value of ideal, the spring force is computed as suggested in ref`(WeinanE) <WeinanE>`
Fnudge_parallel = -Kspring * (RD-RDideal) / (2 * meanDist)
where RD is the “reaction coordinate” see neb section, and RDideal is the ideal RD for which all the images are equally
spaced. I.e. RDideal = (I-1)*meanDist when the climbing replica is off, where I is the replica number). The meanDist
is the average distance between replicas. Note that in this case the specified Kspring is in force units.
Note that the ideal form of nudging can often be more effective at keeping the replicas equally spaced.

1310 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The keyword perp specifies if and how a perpendicular nudging force is computed. It adds a spring force perpendicular
to the path in order to prevent the path from becoming too strongly kinked. It can significantly improve the convergence
of the NEB calculation when the resolution is poor. I.e. when few replicas are used; see (Maras) for details.
The perpendicular spring force is given by
Fnudge_perp = Kspring2 * F(Ri-1,Ri,Ri+1) (Ri+1 + Ri-1 - 2 Ri)
where Kspring2 is the specified value. F(Ri-1 Ri R+1) is a smooth scalar function of the angle Ri-1 Ri Ri+1. It is equal
to 0.0 when the path is straight and is equal to 1 when the angle Ri-1 Ri Ri+1 is acute. F(Ri-1 Ri R+1) is defined in
(Jonsson).
If Kspring2 is set to 0.0 (the default) then no perpendicular spring force is added.

By default, no additional forces act on the first and last replicas during the NEB relaxation, so these replicas simply relax
toward their respective local minima. By using the key word end, additional forces can be applied to the first and/or
last replicas, to enable them to relax toward a MEP while constraining their energy E to the target energy ETarget.
If ETarget>E, the interatomic force Fi for the specified replica becomes:
Fi = -Grad(V) + (Grad(V) dot T' + (E-ETarget)*Kspring3) T', when Grad(V) dot T' < 0
Fi = -Grad(V) + (Grad(V) dot T' + (ETarget- E)*Kspring3) T', when Grad(V) dot T' > 0
The “spring” constant on the difference in energies is the specified Kspring3 value.
When estyle is specified as first, the force is applied to the first replica. When estyle is specified as last, the force is
applied to the last replica. Note that the end keyword can be used twice to add forces to both the first and last replicas.
For both these estyle settings, the target energy ETarget is set to the initial energy of the replica (at the start of the NEB
calculation).
If the estyle is specified as last/efirst or last/efirst/middle, force is applied to the last replica, but the target energy ETarget
is continuously set to the energy of the first replica, as it evolves during the NEB relaxation.
The difference between these two estyle options is as follows. When estyle is specified as last/efirst, no change is made
to the inter-replica force applied to the intermediate replicas (neither first or last). If the initial path is too far from
the MEP, an intermediate replica may relax “faster” and reach a lower energy than the last replica. In this case the
intermediate replica will be relaxing toward its own local minima. This behavior can be prevented by specifying estyle
as last/efirst/middle which will alter the inter-replica force applied to intermediate replicas by removing the contribution
of the gradient to the inter-replica force. This will only be done if a particular intermediate replica has a lower energy
than the first replica. This should effectively prevent the intermediate replicas from over-relaxing.
After converging a NEB calculation using an estyle of last/efirst/middle, you should check that all intermediate replicas
have a larger energy than the first replica. If this is not the case, the path is probably not a MEP.
Finally, note that the last replica may never reach the target energy if it is stuck in a local minima which has a larger
energy than the target energy.

17.92. fix neb command 1311

LAMMPS Documentation, Release stable 29Sep2021

17.92.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, as invoked by the minimize command via the
neb command.

17.92.5 Restrictions

This command can only be used if LAMMPS was built with the REPLICA package. See the Build package doc page
for more info.

17.92.6 Related commands

neb

17.92.7 Default

The option defaults are parallel = neigh, perp = 0.0, ends is not specified (no inter-replica force on the end replicas).

(Henkelman1) Henkelman and Jonsson, J Chem Phys, 113, 9978-9985 (2000).

(Henkelman2) Henkelman, Uberuaga, Jonsson, J Chem Phys, 113, 9901-9904 (2000).
(WeinanE) E, Ren, Vanden-Eijnden, Phys Rev B, 66, 052301 (2002).
(Jonsson) Jonsson, Mills and Jacobsen, in Classical and Quantum Dynamics in Condensed Phase Simulations, edited
by Berne, Ciccotti, and Coker World Scientific, Singapore, 1998, p 385.
(Maras) Maras, Trushin, Stukowski, Ala-Nissila, Jonsson, Comp Phys Comm, 205, 13-21 (2016).

17.93 fix neb/spin command

17.93.1 Syntax

fix ID group-ID neb/spin Kspring

• ID, group-ID are documented in fix command

• neb/spin = style name of this fix command

Kspring = spring constant for parallel nudging force

(force/distance units or force units, see parallel keyword)

1312 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.93.2 Examples

fix 1 active neb/spin 1.0

17.93.3 Description

Add nudging forces to spins in the group for a multi-replica simulation run via the neb/spin command to perform a
geodesic nudged elastic band (GNEB) calculation for finding the transition state. Hi-level explanations of GNEB are
given with the neb/spin command and on the Howto replica doc page. The fix neb/spin command must be used with
the “neb/spin” command and defines how inter-replica nudging forces are computed. A GNEB calculation is divided
in two stages. In the first stage n replicas are relaxed toward a MEP until convergence. In the second stage, the climbing
image scheme is enabled, so that the replica having the highest energy relaxes toward the saddle point (i.e. the point of
highest energy along the MEP), and a second relaxation is performed.
The nudging forces are calculated as explained in (BessarabB)). See this reference for more explanation about their
expression.

17.93.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, as invoked by the minimize command via the
neb/spin command.

17.93.5 Restrictions

This command can only be used if LAMMPS was built with the SPIN package. See the Build package doc page for
more info.

17.93.6 Related commands

neb_spin

17.93.7 Default

none

(BessarabB) Bessarab, Uzdin, Jonsson, Comp Phys Comm, 196, 335-347 (2015).

17.93. fix neb/spin command 1313

LAMMPS Documentation, Release stable 29Sep2021

17.94 fix nvt command

Accelerator Variants: nvt/gpu, nvt/intel, nvt/kk, nvt/omp

17.95 fix npt command

Accelerator Variants: npt/gpu, npt/intel, npt/kk, npt/omp

17.96 fix nph command

Accelerator Variants: nph/kk, nph/omp

17.96.1 Syntax

fix ID group-ID style_name keyword value ...

• ID, group-ID are documented in fix command

• style_name = nvt or npt or nph
• one or more keyword/value pairs may be appended
keyword = temp or iso or aniso or tri or x or y or z or xy or yz or xz or couple or␣
,→tchain or pchain or mtk or tloop or ploop or nreset or drag or ptemp or dilate␣

,→or scalexy or scaleyz or scalexz or flip or fixedpoint or update

temp values = Tstart Tstop Tdamp

Tstart,Tstop = external temperature at start/end of run
Tdamp = temperature damping parameter (time units)
iso or aniso or tri values = Pstart Pstop Pdamp
Pstart,Pstop = scalar external pressure at start/end of run (pressure units)
Pdamp = pressure damping parameter (time units)
x or y or z or xy or yz or xz values = Pstart Pstop Pdamp
Pstart,Pstop = external stress tensor component at start/end of run (pressure␣
,→units)

Pdamp = stress damping parameter (time units)

couple = none or xyz or xy or yz or xz
tchain value = N
N = length of thermostat chain (1 = single thermostat)
pchain value = N
N length of thermostat chain on barostat (0 = no thermostat)
mtk value = yes or no = add in MTK adjustment term or not
tloop value = M
M = number of sub-cycles to perform on thermostat
ploop value = M
M = number of sub-cycles to perform on barostat thermostat
nreset value = reset reference cell every this many timesteps
drag value = Df
Df = drag factor added to barostat/thermostat (0.0 = no drag)
ptemp value = Ttarget
Ttarget = target temperature for barostat

1314 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

dilate value = dilate-group-ID

dilate-group-ID = only dilate atoms in this group due to barostat volume changes
scalexy value = yes or no = scale xy with ly
scaleyz value = yes or no = scale yz with lz
scalexz value = yes or no = scale xz with lz
flip value = yes or no = allow or disallow box flips when it becomes highly skewed
fixedpoint values = x y z
x,y,z = perform barostat dilation/contraction around this point (distance units)
update value = dipole or dipole/dlm
dipole = update dipole orientation (only for sphere variants)
dipole/dlm = use DLM integrator to update dipole orientation (only for sphere␣
,→variants)

17.96.2 Examples

fix 1 all nvt temp 300.0 300.0 100.0

fix 1 water npt temp 300.0 300.0 100.0 iso 0.0 0.0 1000.0
fix 2 jello npt temp 300.0 300.0 100.0 tri 5.0 5.0 1000.0
fix 2 ice nph x 1.0 1.0 0.5 y 2.0 2.0 0.5 z 3.0 3.0 0.5 yz 0.1 0.1 0.5 xz 0.2 0.2 0.5 xy␣
,→0.3 0.3 0.5 nreset 1000

17.96.3 Description

These commands perform time integration on Nose-Hoover style non-Hamiltonian equations of motion which are de-
signed to generate positions and velocities sampled from the canonical (nvt), isothermal-isobaric (npt), and isenthalpic
(nph) ensembles. This updates the position and velocity for atoms in the group each timestep.
The thermostatting and barostatting is achieved by adding some dynamic variables which are coupled to the particle
velocities (thermostatting) and simulation domain dimensions (barostatting). In addition to basic thermostatting and
barostatting, these fixes can also create a chain of thermostats coupled to the particle thermostat, and another chain of
thermostats coupled to the barostat variables. The barostat can be coupled to the overall box volume, or to individual
dimensions, including the xy, xz and yz tilt dimensions. The external pressure of the barostat can be specified as either
a scalar pressure (isobaric ensemble) or as components of a symmetric stress tensor (constant stress ensemble). When
used correctly, the time-averaged temperature and stress tensor of the particles will match the target values specified
by Tstart/Tstop and Pstart/Pstop.
The equations of motion used are those of Shinoda et al in (Shinoda), which combine the hydrostatic equations of
Martyna, Tobias and Klein in (Martyna) with the strain energy proposed by Parrinello and Rahman in (Parrinello).
The time integration schemes closely follow the time-reversible measure-preserving Verlet and rRESPA integrators
derived by Tuckerman et al in (Tuckerman).

The thermostat parameters for fix styles nvt and npt are specified using the temp keyword. Other thermostat-related
keywords are tchain, tloop and drag, which are discussed below.
The thermostat is applied to only the translational degrees of freedom for the particles. The translational degrees of
freedom can also have a bias velocity removed before thermostatting takes place; see the description below. The desired
temperature at each timestep is a ramped value during the run from Tstart to Tstop. The Tdamp parameter is specified
in time units and determines how rapidly the temperature is relaxed. For example, a value of 10.0 means to relax the
temperature in a timespan of (roughly) 10 time units (e.g. τ or fs or ps - see the units command). The atoms in the
fix group are the only ones whose velocities and positions are updated by the velocity/position update portion of the
integration.

17.96. fix nph command 1315

LAMMPS Documentation, Release stable 29Sep2021

Note: A Nose-Hoover thermostat will not work well for arbitrary values of Tdamp. If Tdamp is too small, the
temperature can fluctuate wildly; if it is too large, the temperature will take a very long time to equilibrate. A good
choice for many models is a Tdamp of around 100 timesteps. Note that this is NOT the same as 100 time units for
most units settings. A simple way to ensure this, is via using an immediate variable expression accessing the thermo
property ‘dt’, which is the length of the time step. Example:

fix 1 all nvt temp 300.0 300.0 $(100.0*dt)

The barostat parameters for fix styles npt and nph is specified using one or more of the iso, aniso, tri, x, y, z, xy, xz,
yz, and couple keywords. These keywords give you the ability to specify all 6 components of an external stress tensor,
and to couple various of these components together so that the dimensions they represent are varied together during a
constant-pressure simulation.
Other barostat-related keywords are pchain, mtk, ploop, nreset, drag, and dilate, which are discussed below.
Orthogonal simulation boxes have 3 adjustable dimensions (x,y,z). Triclinic (non-orthogonal) simulation boxes have
6 adjustable dimensions (x,y,z,xy,xz,yz). The create_box, read data, and read_restart commands specify whether the
simulation box is orthogonal or non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz tilt factors.
The target pressures for each of the 6 components of the stress tensor can be specified independently via the x, y, z,
xy, xz, yz keywords, which correspond to the 6 simulation box dimensions. For each component, the external pressure
or tensor component at each timestep is a ramped value during the run from Pstart to Pstop. If a target pressure is
specified for a component, then the corresponding box dimension will change during a simulation. For example, if
the y keyword is used, the y-box length will change. If the xy keyword is used, the xy tilt factor will change. A box
dimension will not change if that component is not specified, although you have the option to change that dimension
via the fix deform command.
Note that in order to use the xy, xz, or yz keywords, the simulation box must be triclinic, even if its initial tilt factors are
0.0.
For all barostat keywords, the Pdamp parameter operates like the Tdamp parameter, determining the time scale on
which pressure is relaxed. For example, a value of 10.0 means to relax the pressure in a timespan of (roughly) 10 time
units (e.g. τ or fs or ps - see the units command).

Note: A Nose-Hoover barostat will not work well for arbitrary values of Pdamp. If Pdamp is too small, the pressure
and volume can fluctuate wildly; if it is too large, the pressure will take a very long time to equilibrate. A good choice
for many models is a Pdamp of around 1000 timesteps. However, note that Pdamp is specified in time units, and that
timesteps are NOT the same as time units for most units settings.

The relaxation rate of the barostat is set by its inertia W :

2
W = (N + 1)kTtarget Pdamp

where N is the number of atoms, k is the Boltzmann constant, and Ttarget is the target temperature of the barostat
(Martyna). If a thermostat is defined, Ttarget is the target temperature of the thermostat. If a thermostat is not defined,
Ttarget is set to the current temperature of the system when the barostat is initialized. If this temperature is too low the
simulation will quit with an error. Note: in previous versions of LAMMPS, Ttarget would default to a value of 1.0 for
lj units and 300.0 otherwise if the system had a temperature of exactly zero.
If a thermostat is not specified by this fix, Ttarget can be manually specified using the Ptemp parameter. This may be
useful if the barostat is initialized when the current temperature does not reflect the steady state temperature of the
system. This keyword may also be useful in athermal simulations where the temperature is not well defined.

1316 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Regardless of what atoms are in the fix group (the only atoms which are time integrated), a global pressure or stress
tensor is computed for all atoms. Similarly, when the size of the simulation box is changed, all atoms are re-scaled to
new positions, unless the keyword dilate is specified with a dilate-group-ID for a group that represents a subset of the
atoms. This can be useful, for example, to leave the coordinates of atoms in a solid substrate unchanged and controlling
the pressure of a surrounding fluid. This option should be used with care, since it can be unphysical to dilate some
atoms and not others, because it can introduce large, instantaneous displacements between a pair of atoms (one dilated,
one not) that are far from the dilation origin. Also note that for atoms not in the fix group, a separate time integration
fix like fix nve or fix nvt can be used on them, independent of whether they are dilated or not.

The couple keyword allows two or three of the diagonal components of the pressure tensor to be “coupled” together. The
value specified with the keyword determines which are coupled. For example, xz means the Pxx and Pzz components
of the stress tensor are coupled. Xyz means all 3 diagonal components are coupled. Coupling means two things: the
instantaneous stress will be computed as an average of the corresponding diagonal components, and the coupled box
dimensions will be changed together in lockstep, meaning coupled dimensions will be dilated or contracted by the
same percentage every timestep. The Pstart, Pstop, Pdamp parameters for any coupled dimensions must be identical.
Couple xyz can be used for a 2d simulation; the z dimension is simply ignored.

The iso, aniso, and tri keywords are simply shortcuts that are equivalent to specifying several other keywords together.
The keyword iso means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure),
and dilate/contract the dimensions together. Using “iso Pstart Pstop Pdamp” is the same as specifying these 4 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
couple xyz

The keyword aniso means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components
of the stress tensor as the driving forces, and the specified scalar external pressure. Using “aniso Pstart Pstop Pdamp”
is the same as specifying these 4 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
couple none

The keyword tri means x, y, z, xy, xz, and yz dimensions are controlled independently using their individual stress
components as the driving forces, and the specified scalar pressure as the external normal stress. Using “tri Pstart
Pstop Pdamp” is the same as specifying these 7 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
xy 0.0 0.0 Pdamp
yz 0.0 0.0 Pdamp
xz 0.0 0.0 Pdamp
couple none

In some cases (e.g. for solids) the pressure (volume) and/or temperature of the system can oscillate undesirably when
a Nose/Hoover barostat and thermostat is applied. The optional drag keyword will damp these oscillations, although
it alters the Nose/Hoover equations. A value of 0.0 (no drag) leaves the Nose/Hoover formalism unchanged. A non-
zero value adds a drag term; the larger the value specified, the greater the damping effect. Performing a short run and

17.96. fix nph command 1317

LAMMPS Documentation, Release stable 29Sep2021

monitoring the pressure and temperature is the best way to determine if the drag term is working. Typically a value
between 0.2 to 2.0 is sufficient to damp oscillations after a few periods. Note that use of the drag keyword will interfere
with energy conservation and will also change the distribution of positions and velocities so that they do not correspond
to the nominal NVT, NPT, or NPH ensembles.
An alternative way to control initial oscillations is to use chain thermostats. The keyword tchain determines the number
of thermostats in the particle thermostat. A value of 1 corresponds to the original Nose-Hoover thermostat. The
keyword pchain specifies the number of thermostats in the chain thermostatting the barostat degrees of freedom. A
value of 0 corresponds to no thermostatting of the barostat variables.
The mtk keyword controls whether or not the correction terms due to Martyna, Tuckerman, and Klein are included in
the equations of motion (Martyna). Specifying no reproduces the original Hoover barostat, whose volume probability
distribution function differs from the true NPT and NPH ensembles by a factor of 1/V. Hence using yes is more correct,
but in many cases the difference is negligible.
The keyword tloop can be used to improve the accuracy of integration scheme at little extra cost. The initial and final
updates of the thermostat variables are broken up into tloop sub-steps, each of length dt/tloop. This corresponds to using
a first-order Suzuki-Yoshida scheme (Tuckerman). The keyword ploop does the same thing for the barostat thermostat.
The keyword nreset controls how often the reference dimensions used to define the strain energy are reset. If this
keyword is not used, or is given a value of zero, then the reference dimensions are set to those of the initial simulation
domain and are never changed. If the simulation domain changes significantly during the simulation, then the final
average pressure tensor will differ significantly from the specified values of the external stress tensor. A value of nstep
means that every nstep timesteps, the reference dimensions are set to those of the current simulation domain.
The scaleyz, scalexz, and scalexy keywords control whether or not the corresponding tilt factors are scaled with the
associated box dimensions when barostatting triclinic periodic cells. The default values yes will turn on scaling, which
corresponds to adjusting the linear dimensions of the cell while preserving its shape. Choosing no ensures that the tilt
factors are not scaled with the box dimensions. See below for restrictions and default values in different situations. In
older versions of LAMMPS, scaling of tilt factors was not performed. The old behavior can be recovered by setting all
three scale keywords to no.
The flip keyword allows the tilt factors for a triclinic box to exceed half the distance of the parallel box length, as
discussed below. If the flip value is set to yes, the bound is enforced by flipping the box when it is exceeded. If the flip
value is set to no, the tilt will continue to change without flipping. Note that if applied stress induces large deformations
(e.g. in a liquid), this means the box shape can tilt dramatically and LAMMPS will run less efficiently, due to the
large volume of communication needed to acquire ghost atoms around a processor’s irregular-shaped sub-domain. For
extreme values of tilt, LAMMPS may also lose atoms and generate an error.
The fixedpoint keyword specifies the fixed point for barostat volume changes. By default, it is the center of the box.
Whatever point is chosen will not move during the simulation. For example, if the lower periodic boundaries pass
through (0,0,0), and this point is provided to fixedpoint, then the lower periodic boundaries will remain at (0,0,0), while
the upper periodic boundaries will move twice as far. In all cases, the particle trajectories are unaffected by the chosen
value, except for a time-dependent constant translation of positions.
If the update keyword is used with the dipole value, then the orientation of the dipole moment of each particle is also
updated during the time integration. This option should be used for models where a dipole moment is assigned to
finite-size particles, e.g. spheroids via use of the atom_style hybrid sphere dipole command.
The default dipole orientation integrator can be changed to the Dullweber-Leimkuhler-McLachlan integration scheme
(Dullweber) when using update with the value dipole/dlm. This integrator is symplectic and time-reversible, giving
better energy conservation and allows slightly longer timesteps at only a small additional computational cost.

Note: Using a barostat coupled to tilt dimensions xy, xz, yz can sometimes result in arbitrarily large values of the
tilt dimensions, i.e. a dramatically deformed simulation box. LAMMPS allows the tilt factors to grow a small amount

1318 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

beyond the normal limit of half the box length (0.6 times the box length), and then performs a box “flip” to an equivalent
periodic cell. See the discussion of the flip keyword above, to allow this bound to be exceeded, if desired.

The flip operation is described in more detail in the page for fix deform. Both the barostat dynamics and the atom
trajectories are unaffected by this operation. However, if a tilt factor is incremented by a large amount (1.5 times the
box length) on a single timestep, LAMMPS can not accommodate this event and will terminate the simulation with an
error. This error typically indicates that there is something badly wrong with how the simulation was constructed, such
as specifying values of Pstart that are too far from the current stress value, or specifying a timestep that is too large.
Triclinic barostatting should be used with care. This also is true for other barostat styles, although they tend to be more
forgiving of insults. In particular, it is important to recognize that equilibrium liquids can not support a shear stress
and that equilibrium solids can not support shear stresses that exceed the yield stress.
One exception to this rule is if the first dimension in the tilt factor (x for xy) is non-periodic. In that case, the limits
on the tilt factor are not enforced, since flipping the box in that dimension does not change the atom positions due to
non-periodicity. In this mode, if you tilt the system to extreme angles, the simulation will simply become inefficient
due to the highly skewed simulation box.

Note: Unlike the fix temp/berendsen command which performs thermostatting but NO time integration, these fixes
perform thermostatting/barostatting AND time integration. Thus you should not use any other time integration fix,
such as fix nve on atoms to which this fix is applied. Likewise, fix nvt and fix npt should not normally be used on atoms
that also have their temperature controlled by another fix - e.g. by fix langevin or fix temp/rescale commands.

See the Howto thermostat and Howto barostat doc pages for a discussion of different ways to compute temperature and
perform thermostatting and barostatting.

These fixes compute a temperature and pressure each timestep. To do this, the thermostat and barostat fixes create their
own computes of style “temp” and “pressure”, as if one of these sets of commands had been issued:
For fix nvt:

compute fix-ID_temp group-ID temp

For fix npt and fix nph:

compute fix-ID_temp all temp

compute fix-ID_press all pressure fix-ID_temp

For fix nvt, the group for the new temperature compute is the same as the fix group. For fix npt and fix nph, the group
for both the new temperature and pressure compute is “all” since pressure is computed for the entire system. In the
case of fix nph, the temperature compute is not used for thermostatting, but just for a kinetic-energy contribution to the
pressure. See the compute temp and compute pressure commands for details. Note that the IDs of the new computes
are the fix-ID + underscore + “temp” or fix_ID + underscore + “press”.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of these fix’s temperature or pressure
via the compute_modify command. Or you can print this temperature or pressure during thermodynamic output
via the thermo_style custom command using the appropriate compute-ID. It also means that changing attributes of
thermo_temp or thermo_press will have no effect on this fix.
Like other fixes that perform thermostatting, fix nvt and fix npt can be used with compute commands that calculate a
temperature after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group
of atoms or only calculating temperature on the x-component of velocity or only calculating temperature for atoms in
a geometric region. This is not done by default, but only if the fix_modify command is used to assign a temperature
compute to this fix that includes such a bias term. See the doc pages for individual compute commands to determine

17.96. fix nph command 1319

LAMMPS Documentation, Release stable 29Sep2021

which ones include a bias. In this case, the thermostat works in the following manner: the current temperature is
calculated taking the bias into account, bias is removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.

These fixes can be used with either the verlet or respa integrators. When using one of the barostat fixes with respa,
LAMMPS uses an integrator constructed according to the following factorization of the Liouville propagator (for two
rRESPA levels):
       
∆t ∆t ∆t (2) ∆t
exp (iL∆t) =Ê exp iLT-baro exp iLT-part exp iL,2 exp iL2
2 2 2 2
          n
(1) ∆t ∆t ∆t ∆t (1) ∆t
× exp iL2 exp iL,1 exp iL1 exp iL,1 exp iL2
2n 2n n 2n 2n
       
(2) ∆t ∆t ∆t ∆t
× exp iL2 exp iL,2 exp iLT-part exp iLT-baro
2 2 2 2
3


+ O ∆t

This factorization differs somewhat from that of Tuckerman et al, in that the barostat is only updated at the outermost
rRESPA level, whereas Tuckerman’s factorization requires splitting the pressure into pieces corresponding to the forces
computed at each rRESPA level. In theory, the latter method will exhibit better numerical stability. In practice, because
Pdamp is normally chosen to be a large multiple of the outermost rRESPA timestep, the barostat dynamics are not the
limiting factor for numerical stability. Both factorizations are time-reversible and can be shown to preserve the phase
space measure of the underlying non-Hamiltonian equations of motion.

Note: This implementation has been shown to conserve linear momentum up to machine precision under NVT dy-
namics. Under NPT dynamics, for a system with zero initial total linear momentum, the total momentum fluctuates
close to zero. It may occasionally undergo brief excursions to non-negligible values, before returning close to zero.
Over long simulations, this has the effect of causing the center-of-mass to undergo a slow random walk. This can be
mitigated by resetting the momentum at infrequent intervals using the fix momentum command.

The fix npt and fix nph commands can be used with rigid bodies or mixtures of rigid bodies and non-rigid particles
(e.g. solvent). But there are also fix rigid/npt and fix rigid/nph commands, which are typically a more natural choice.
See the page for those commands for more discussion of the various ways to do this.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

1320 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.96.4 Restart, fix_modify, output, run start/stop, minimize info

These fixes writes the state of all the thermostat and barostat variables to binary restart files. See the read_restart
command for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix
continues in an uninterrupted fashion.
The fix_modify temp and press options are supported by these fixes. You can use them to assign a compute you have
defined to this fix which will be used in its thermostatting or barostatting procedure, as described above. If you do this,
note that the kinetic energy derived from the compute temperature should be consistent with the virial term computed
using all atoms for the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.

Note: If both the temp and press keywords are used in a single thermo_modify command (or in two separate com-
mands), then the order in which the keywords are specified is important. Note that a pressure compute defines its own
temperature compute as an argument when it is specified. The temp keyword will override this (for the pressure com-
pute being used by fix npt), but only if the temp keyword comes after the press keyword. If the temp keyword comes
before the press keyword, then the new pressure compute specified by the press keyword will be unaffected by the temp
setting.

The cumulative energy change in the system imposed by these fixes, via either thermostatting and/or barostatting, is
included in the thermodynamic output keywords ecouple and econserve. See the thermo_style page for details.
These fixes compute a global scalar which can be accessed by various output commands. The scalar is the same
cumulative energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is
“extensive”.
These fixes compute also compute a global vector of quantities, which can be accessed by various output commands.
The vector values are “intensive”.
The vector stores internal Nose/Hoover thermostat and barostat variables. The number and meaning of the vector values
depends on which fix is used and the settings for keywords tchain and pchain, which specify the number of Nose/Hoover
chains for the thermostat and barostat. If no thermostatting is done, then tchain is 0. If no barostatting is done, then
pchain is 0. In the following list, “ndof” is 0, 1, 3, or 6, and is the number of degrees of freedom in the barostat. Its
value is 0 if no barostat is used, else its value is 6 if any off-diagonal stress tensor component is barostatted, else its
value is 1 if couple xyz is used or couple xy for a 2d simulation, otherwise its value is 3.
The order of values in the global vector and their meaning is as follows. The notation means there are tchain values for
eta, followed by tchain for eta_dot, followed by ndof for omega, etc:
• eta[tchain] = particle thermostat displacements (unitless)
• eta_dot[tchain] = particle thermostat velocities (1/time units)
• omega[ndof] = barostat displacements (unitless)
• omega_dot[ndof] = barostat velocities (1/time units)
• etap[pchain] = barostat thermostat displacements (unitless)
• etap_dot[pchain] = barostat thermostat velocities (1/time units)
• PE_eta[tchain] = potential energy of each particle thermostat displacement (energy units)
• KE_eta_dot[tchain] = kinetic energy of each particle thermostat velocity (energy units)
• PE_omega[ndof] = potential energy of each barostat displacement (energy units)
• KE_omega_dot[ndof] = kinetic energy of each barostat velocity (energy units)
• PE_etap[pchain] = potential energy of each barostat thermostat displacement (energy units)
• KE_etap_dot[pchain] = kinetic energy of each barostat thermostat velocity (energy units)

17.96. fix nph command 1321

LAMMPS Documentation, Release stable 29Sep2021

• PE_strain[1] = scalar strain energy (energy units)

These fixes can ramp their external temperature and pressure over multiple runs, using the start and stop keywords of
the run command. See the run command for details of how to do this.
These fixes are not invoked during energy minimization.

17.96.5 Restrictions

X, y, z cannot be barostatted if the associated dimension is not periodic. Xy, xz, and yz can only be barostatted if the
simulation domain is triclinic and the second dimension in the keyword (y dimension in xy) is periodic. Z, xz, and yz,
cannot be barostatted for 2D simulations. The create_box, read data, and read_restart commands specify whether the
simulation box is orthogonal or non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz tilt factors.
For the temp keyword, the final Tstop cannot be 0.0 since it would make the external T = 0.0 at some timestep during
the simulation which is not allowed in the Nose/Hoover formulation.
The scaleyz yes and scalexz yes keyword/value pairs can not be used for 2D simulations. scaleyz yes, scalexz yes, and
scalexy yes options can only be used if the second dimension in the keyword is periodic, and if the tilt factor is not
coupled to the barostat via keywords tri, yz, xz, and xy.
These fixes can be used with dynamic groups as defined by the group command. Likewise they can be used with groups
to which atoms are added or deleted over time, e.g. a deposition simulation. However, the conservation properties of
the thermostat and barostat are defined for systems with a static set of atoms. You may observe odd behavior if the
atoms in a group vary dramatically over time or the atom count becomes very small.

17.96.6 Related commands

fix nve, fix_modify, run_style

17.96.7 Default

The keyword defaults are tchain = 3, pchain = 3, mtk = yes, tloop = 1, ploop = 1, nreset = 0, drag = 0.0, dilate = all,
couple = none, flip = yes, scaleyz = scalexz = scalexy = yes if periodic in second dimension and not coupled to barostat,
otherwise no.

(Martyna) Martyna, Tobias and Klein, J Chem Phys, 101, 4177 (1994).
(Parrinello) Parrinello and Rahman, J Appl Phys, 52, 7182 (1981).
(Tuckerman) Tuckerman, Alejandre, Lopez-Rendon, Jochim, and Martyna, J Phys A: Math Gen, 39, 5629 (2006).
(Shinoda) Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).
(Dullweber) Dullweber, Leimkuhler and McLachlan, J Chem Phys, 107, 5840 (1997).

1322 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.97 fix nvt/eff command

17.98 fix npt/eff command

17.99 fix nph/eff command

17.99.1 Syntax

fix ID group-ID style_name keyword value ...

• ID, group-ID are documented in fix command

• style_name = nvt/eff or npt/eff or nph/eff
one or more keyword value pairs may be appended
keyword = temp or iso or aniso or tri or x or y or z or xy or yz or xz or couple or␣
,→tchain or pchain or mtk or tloop or ploop or nreset or drag or dilate

temp values = Tstart Tstop Tdamp

Tstart,Tstop = external temperature at start/end of run
Tdamp = temperature damping parameter (time units)
iso or aniso or tri values = Pstart Pstop Pdamp
Pstart,Pstop = scalar external pressure at start/end of run (pressure units)
Pdamp = pressure damping parameter (time units)
x or y or z or xy or yz or xz values = Pstart Pstop Pdamp
Pstart,Pstop = external stress tensor component at start/end of run (pressure␣
,→units)

Pdamp = stress damping parameter (time units)

couple = none or xyz or xy or yz or xz
tchain value = length of thermostat chain (1 = single thermostat)
pchain values = length of thermostat chain on barostat (0 = no thermostat)
mtk value = yes or no = add in MTK adjustment term or not
tloop value = number of sub-cycles to perform on thermostat
ploop value = number of sub-cycles to perform on barostat thermostat
nreset value = reset reference cell every this many timesteps
drag value = drag factor added to barostat/thermostat (0.0 = no drag)
dilate value = all or partial

17.99.2 Examples

fix 1 all nvt/eff temp 300.0 300.0 0.1

fix 1 part npt/eff temp 300.0 300.0 0.1 iso 0.0 0.0 1.0
fix 2 part npt/eff temp 300.0 300.0 0.1 tri 5.0 5.0 1.0
fix 2 ice nph/eff x 1.0 1.0 0.5 y 2.0 2.0 0.5 z 3.0 3.0 0.5 yz 0.1 0.1 0.5 xz 0.2 0.2 0.
,→5 xy 0.3 0.3 0.5 nreset 1000

17.97. fix nvt/eff command 1323

LAMMPS Documentation, Release stable 29Sep2021

17.99.3 Description

These commands perform time integration on Nose-Hoover style non-Hamiltonian equations of motion for nuclei and
electrons in the group for the electron force field model. The fixes are designed to generate positions and velocities
sampled from the canonical (nvt), isothermal-isobaric (npt), and isenthalpic (nph) ensembles. This is achieved by
adding some dynamic variables which are coupled to the particle velocities (thermostatting) and simulation domain
dimensions (barostatting). In addition to basic thermostatting and barostatting, these fixes can also create a chain
of thermostats coupled to the particle thermostat, and another chain of thermostats coupled to the barostat variables.
The barostat can be coupled to the overall box volume, or to individual dimensions, including the xy, xz and yz tilt
dimensions. The external pressure of the barostat can be specified as either a scalar pressure (isobaric ensemble)
or as components of a symmetric stress tensor (constant stress ensemble). When used correctly, the time-averaged
temperature and stress tensor of the particles will match the target values specified by Tstart/Tstop and Pstart/Pstop.
The operation of these fixes is exactly like that described by the fix nvt, npt, and nph commands, except that the radius
and radial velocity of electrons are also updated. Likewise the temperature and pressure calculated by the fix, using the
computes it creates (as discussed in the fix nvt, npt, and nph doc page), are performed with computes that include the
eFF contribution to the temperature or kinetic energy from the electron radial velocity.

Note: there are two different pressures that can be reported for eFF when defining the pair_style (see pair eff/cut
to understand these settings), one (default) that considers electrons do not contribute radial virial components (i.e.
electrons treated as incompressible ‘rigid’ spheres) and one that does. The radial electronic contributions to the virials
are only tallied if the flexible pressure option is set, and this will affect both global and per-atom quantities. In principle,
the true pressure of a system is somewhere in between the rigid and the flexible eFF pressures, but, for most cases, the
difference between these two pressures will not be significant over long-term averaged runs (i.e. even though the energy
partitioning changes, the total energy remains similar).

Note: currently, there is no available option for the user to set or create temperature distributions that include the radial
electronic degrees of freedom with the velocity command, so the the user must allow for these degrees of freedom to
equilibrate (i.e. equi-partitioning of energy) through time integration.

17.99.4 Restart, fix_modify, output, run start/stop, minimize info

See the page for the fix nvt, npt, and nph commands for details.

17.99.5 Restrictions

This fix is part of the EFF package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
Other restriction discussed on the page for the fix nvt, npt, and nph commands also apply.

Note: The temperature for systems (regions or groups) with only electrons and no nuclei is 0.0 (i.e. not defined)
in the current temperature calculations, a practical example would be a uniform electron gas or a very hot plasma,
where electrons remain delocalized from the nuclei. This is because, even though electron virials are included in the
temperature calculation, these are averaged over the nuclear degrees of freedom only. In such cases a corrective term
must be added to the pressure to get the correct kinetic contribution.

1324 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.99.6 Related commands

fix nvt, fix nph, fix npt, fix_modify, run_style

17.99.7 Default

The keyword defaults are tchain = 3, pchain = 3, mtk = yes, tloop = ploop = 1, nreset = 0, drag = 0.0, dilate = all, and
couple = none.

(Martyna) Martyna, Tobias and Klein, J Chem Phys, 101, 4177 (1994).
(Parrinello) Parrinello and Rahman, J Appl Phys, 52, 7182 (1981).
(Tuckerman) Tuckerman, Alejandre, Lopez-Rendon, Jochim, and Martyna, J Phys A: Math Gen, 39, 5629 (2006).
(Shinoda) Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).

17.100 fix nvt/uef command

17.101 fix npt/uef command

17.101.1 Syntax

fix ID group-ID style_name erate edot_x edot_y temp Tstart Tstop Tdamp keyword value ...

• ID, group-ID are documented in fix command

• style_name = nvt/uef or npt/uef
• Tstart, Tstop, and Tdamp are documented in the fix npt command
• edot_x and edot_y are the strain rates in the x and y directions (1/(time units))
• one or more keyword/value pairs may be appended
keyword = ext or strain or iso or x or y or z or tchain or pchain or tloop or␣
,→ploop or mtk

ext value = x or y or z or xy or yz or xz = external dimensions

sets the external dimensions used to calculate the scalar pressure
strain values = e_x e_y = initial strain
usually not needed, but may be needed to resume a run with a data file.
iso, x, y, z, tchain, pchain, tloop, ploop, mtk keywords
documented by the fix npt command

17.100. fix nvt/uef command 1325

LAMMPS Documentation, Release stable 29Sep2021

17.101.2 Examples

fix uniax_nvt all nvt/uef temp 400 400 100 erate 0.00001 -0.000005
fix biax_nvt all nvt/uef temp 400 400 100 erate 0.000005 0.000005
fix uniax_npt all npt/uef temp 400 400 300 iso 1 1 3000 erate 0.00001 -0.000005 ext yz
fix biax_npt all npt/uef temp 400 400 100 erate -0.00001 0.000005 x 1 1 3000

17.101.3 Description

This fix can be used to simulate non-equilibrium molecular dynamics (NEMD) under diagonal flow fields, including
uniaxial and bi-axial flow. Simulations under continuous extensional flow may be carried out for an indefinite amount
of time. It is an implementation of the boundary conditions from (Dobson), and also uses numerical lattice reduction
as was proposed by (Hunt). The lattice reduction algorithm is from (Semaev). The fix is intended for simulations of
homogeneous flows, and integrates the SLLOD equations of motion, originally proposed by Hoover and Ladd (see
(Evans and Morriss)). Additional detail about this implementation can be found in (Nicholson and Rutledge).
Note that NEMD simulations of a continuously strained system can be performed using the fix deform, fix nvt/sllod,
and compute temp/deform commands.
The applied flow field is set by the eps keyword. The values edot_x and edot_y correspond to the strain rates in the xx
and yy directions. It is implicitly assumed that the flow field is traceless, and therefore the strain rate in the zz direction
is eqal to -(edot_x + edot_y).

Note: Due to an instability in the SLLOD equations under extension, fix momentum should be used to regularly reset
the linear momentum.

The boundary conditions require a simulation box that does not have a consistent alignment relative to the applied flow
field. Since LAMMPS utilizes an upper-triangular simulation box, it is not possible to express the evolving simulation
box in the same coordinate system as the flow field. This fix keeps track of two coordinate systems: the flow frame, and
the upper triangular LAMMPS frame. The coordinate systems are related to each other through the QR decomposition,
as is illustrated in the image below.

1326 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

During most molecular dynamics operations, the system is represented in the LAMMPS frame. Only when the posi-
tions and velocities are updated is the system rotated to the flow frame, and it is rotated back to the LAMMPS frame
immediately afterwards. For this reason, all vector-valued quantities (except for the tensors from compute pressure/uef
and compute temp/uef ) will be computed in the LAMMPS frame. Rotationally invariant scalar quantities like the tem-
perature and hydrostatic pressure are frame-invariant and will be computed correctly. Additionally, the system is in the
LAMMPS frame during all of the output steps, and therefore trajectory files made using the dump command will be in
the LAMMPS frame unless the dump cfg/uef command is used.

Temperature control is achieved with the default Nose-Hoover style thermostat documented in fix npt. When this fix is
active, only the peculiar velocity of each atom is stored, defined as the velocity relative to the streaming velocity. This
is in contrast to fix nvt/sllod, which uses a lab-frame velocity, and removes the contribution from the streaming velocity
in order to compute the temperature.
Pressure control is achieved using the default Nose-Hoover barostat documented in fix npt. There are two ways to
control the pressure using this fix. The first method involves using the ext keyword along with the iso pressure style.
With this method, the pressure is controlled by scaling the simulation box isotropically to achieve the average pressure
only in the directions specified by ext. For example, if the ext value is set to xy, the average pressure (Pxx+Pyy)/2 will
be controlled.
This example command will control the total hydrostatic pressure under uniaxial tension:

fix f1 all npt/uef temp 0.7 0.7 0.5 iso 1 1 5 erate -0.5 -0.5 ext xyz

This example command will control the average stress in compression directions, which would typically correspond to
free surfaces under drawing with uniaxial tension:

fix f2 all npt/uef temp 0.7 0.7 0.5 iso 1 1 5 erate -0.5 -0.5 ext xy

The second method for pressure control involves setting the normal stresses using the x, y, and/or z keywords. When
using this method, the same pressure must be specified via Pstart and Pstop for all dimensions controlled. Any choice
of pressure conditions that would cause LAMMPS to compute a deviatoric stress are not permissible and will result in
an error. Additionally, all dimensions with controlled stress must have the same applied strain rate. The ext keyword
must be set to the default value (xyz) when using this method.
For example, the following commands will work:

fix f3 all npt/uef temp 0.7 0.7 0.5 x 1 1 5 y 1 1 5 erate -0.5 -0.5
fix f4 all npt/uef temp 0.7 0.7 0.5 z 1 1 5 erate 0.5 0.5

The following commands will not work:

fix f5 all npt/uef temp 0.7 0.7 0.5 x 1 1 5 z 1 1 5 erate -0.5 -0.5
fix f6 all npt/uef temp 0.7 0.7 0.5 x 1 1 5 z 2 2 5 erate 0.5 0.5

These fix computes a temperature and pressure each timestep. To do this, it creates its own computes of style “temp/uef”
and “pressure/uef”, as if one of these two sets of commands had been issued:

compute fix-ID_temp group-ID temp/uef

compute fix-ID_press group-ID pressure/uef fix-ID_temp

compute fix-ID_temp all temp/uef

compute fix-ID_press all pressure/uef fix-ID_temp

See the compute temp/uef and compute pressure/uef commands for details. Note that the IDs of the new computes are
the fix-ID + underscore + “temp” or fix_ID + underscore + “press”.

17.101. fix npt/uef command 1327

LAMMPS Documentation, Release stable 29Sep2021

17.101.4 Restart, fix_modify, output, run start/stop, minimize info

The fix writes the state of all the thermostat and barostat variables, as well as the cumulative strain applied, to binary
restart files. See the read_restart command for info on how to re-specify a fix in an input script that reads a restart file,
so that the operation of the fix continues in an uninterrupted fashion.

Note: It is not necessary to set the strain keyword when resuming a run from a restart file. Only for resuming from
data files, which do not contain the cumulative applied strain, will this keyword be necessary.

This fix can be used with the fix_modify temp and press options. The temperature and pressure computes used must be
of type temp/uef and pressure/uef.
This fix computes the same global scalar and vector quantities as fix npt.
The fix is not invoked during energy minimization.

17.101.5 Restrictions

This fix is part of the UEF package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
Due to requirements of the boundary conditions, when the strain keyword is set to zero (or unset), the initial simulation
box must be cubic and have style triclinic. If the box is initially of type ortho, use change_box before invoking the fix.

Note: When resuming from restart files, you may need to use box tilt large since lammps has internal criteria from
lattice reduction that are not the same as the criteria in the numerical lattice reduction algorithm.

17.101.6 Related commands

fix nvt, fix nvt/sllod, compute temp/uef , compute pressure/uef , dump cfg/uef

17.101.7 Default

The default keyword values specific to this fix are exy = xyz, strain = 0 0. The remaining defaults are the same as for
fix npt except tchain = 1. The reason for this change is given in fix nvt/sllod.

(Dobson) Dobson, J Chem Phys, 141, 184103 (2014).

(Hunt) Hunt, Mol Simul, 42, 347 (2016).
(Semaev) Semaev, Cryptography and Lattices, 181 (2001).
(Evans and Morriss) Evans and Morriss, Phys Rev A, 30, 1528 (1984).
(Nicholson and Rutledge) Nicholson and Rutledge, J Chem Phys, 145, 244903 (2016).

1328 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.102 fix nph/asphere command

Accelerator Variants: nph/asphere/omp

17.102.1 Syntax

fix ID group-ID nph/asphere args keyword value ...

• ID, group-ID are documented in fix command

• nph/asphere = style name of this fix command
• additional barostat related keyword/value pairs from the fix nph command can be appended

17.102.2 Examples

fix 1 all nph/asphere iso 0.0 0.0 1000.0

fix 2 all nph/asphere x 5.0 5.0 1000.0
fix 2 all nph/asphere x 5.0 5.0 1000.0 drag 0.2
fix 2 water nph/asphere aniso 0.0 0.0 1000.0 dilate partial

17.102.3 Description

Perform constant NPH integration to update position, velocity, orientation, and angular velocity each timestep for
aspherical or ellipsoidal particles in the group using a Nose/Hoover pressure barostat. P is pressure; H is enthalpy.
This creates a system trajectory consistent with the isenthalpic ensemble.
This fix differs from the fix nph command, which assumes point particles and only updates their position and velocity.
Additional parameters affecting the barostat are specified by keywords and values documented with the fix nph com-
mand. See, for example, discussion of the aniso, and dilate keywords.
The particles in the fix group are the only ones whose velocities and positions are updated by the velocity/position
update portion of the NPH integration.
Regardless of what particles are in the fix group, a global pressure is computed for all particles. Similarly, when the
size of the simulation box is changed, all particles are re-scaled to new positions, unless the keyword dilate is specified
with a value of partial, in which case only the particles in the fix group are re-scaled. The latter can be useful for
leaving the coordinates of particles in a solid substrate unchanged and controlling the pressure of a surrounding fluid.

This fix computes a temperature and pressure each timestep. To do this, the fix creates its own computes of style
“temp/asphere” and “pressure”, as if these commands had been issued:

compute fix-ID_temp all temp/asphere

compute fix-ID_press all pressure fix-ID_temp

See the compute temp/asphere and compute pressure commands for details. Note that the IDs of the new computes are
the fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is “all” since
pressure is computed for the entire system.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the

17.102. fix nph/asphere command 1329

LAMMPS Documentation, Release stable 29Sep2021

compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.102.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover barostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its thermostatting or barostatting procedure. If you do this, note that the kinetic
energy derived from the compute temperature should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nph command.
This fix can ramp its target pressure over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.102.5 Restrictions

This fix is part of the ASPHERE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style ellipsoid
command.
All particles in the group must be finite-size. They cannot be point particles, but they can be aspherical or spherical as
defined by their shape attribute.

1330 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.102.6 Related commands

fix nph, fix nve_asphere, fix nvt_asphere, fix npt_asphere, fix_modify

17.102.7 Default

none

17.103 fix nph/body command

17.103.1 Syntax

fix ID group-ID nph/body args keyword value ...

• ID, group-ID are documented in fix command

• nph/body = style name of this fix command
• additional barostat related keyword/value pairs from the fix nph command can be appended

17.103.2 Examples

fix 1 all nph/body iso 0.0 0.0 1000.0

fix 2 all nph/body x 5.0 5.0 1000.0
fix 2 all nph/body x 5.0 5.0 1000.0 drag 0.2
fix 2 water nph/body aniso 0.0 0.0 1000.0 dilate partial

17.103.3 Description

Perform constant NPH integration to update position, velocity, orientation, and angular velocity each timestep for body
particles in the group using a Nose/Hoover pressure barostat. P is pressure; H is enthalpy. This creates a system
trajectory consistent with the isenthalpic ensemble.
This fix differs from the fix nph command, which assumes point particles and only updates their position and velocity.
Additional parameters affecting the barostat are specified by keywords and values documented with the fix nph com-
mand. See, for example, discussion of the aniso, and dilate keywords.
The particles in the fix group are the only ones whose velocities and positions are updated by the velocity/position
update portion of the NPH integration.
Regardless of what particles are in the fix group, a global pressure is computed for all particles. Similarly, when the
size of the simulation box is changed, all particles are re-scaled to new positions, unless the keyword dilate is specified
with a value of partial, in which case only the particles in the fix group are re-scaled. The latter can be useful for
leaving the coordinates of particles in a solid substrate unchanged and controlling the pressure of a surrounding fluid.

This fix computes a temperature and pressure each timestep. To do this, the fix creates its own computes of style
“temp/body” and “pressure”, as if these commands had been issued:

17.103. fix nph/body command 1331

LAMMPS Documentation, Release stable 29Sep2021

compute fix-ID_temp all temp/body

compute fix-ID_press all pressure fix-ID_temp

See the compute temp/body and compute pressure commands for details. Note that the IDs of the new computes are
the fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is “all” since
pressure is computed for the entire system.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.103.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover barostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its thermostatting or barostatting procedure. If you do this, note that the kinetic
energy derived from the compute temperature should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nph command.
This fix can ramp its target pressure over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

1332 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.103.5 Restrictions

This fix is part of the BODY package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style body
command.

17.103.6 Related commands

fix nph, fix nve_body, fix nvt_body, fix npt_body, fix_modify

17.103.7 Default

none

17.104 fix nph/sphere command

Accelerator Variants: nph/sphere/omp

17.104.1 Syntax

fix ID group-ID nph/sphere args keyword value ...

• ID, group-ID are documented in fix command

• nph/sphere = style name of this fix command
• keyword = disc
disc value = none = treat particles as 2d discs, not spheres
• additional barostat related keyword/value pairs from the fix nph command can be appended

17.104.2 Examples

fix 1 all nph/sphere iso 0.0 0.0 1000.0

fix 2 all nph/sphere x 5.0 5.0 1000.0
fix 2 all nph/sphere x 5.0 5.0 1000.0 disc
fix 2 all nph/sphere x 5.0 5.0 1000.0 drag 0.2
fix 2 water nph/sphere aniso 0.0 0.0 1000.0 dilate partial

17.104. fix nph/sphere command 1333

LAMMPS Documentation, Release stable 29Sep2021

17.104.3 Description

Perform constant NPH integration to update position, velocity, and angular velocity each timestep for finite-size spher-
ical particles in the group using a Nose/Hoover pressure barostat. P is pressure; H is enthalpy. This creates a system
trajectory consistent with the isenthalpic ensemble.
This fix differs from the fix nph command, which assumes point particles and only updates their position and velocity.
If the disc keyword is used, then each particle is treated as a 2d disc (circle) instead of as a sphere. This is only possible
for 2d simulations, as defined by the dimension keyword. The only difference between discs and spheres in this context
is their moment of inertia, as used in the time integration.
Additional parameters affecting the barostat are specified by keywords and values documented with the fix nph com-
mand. See, for example, discussion of the aniso, and dilate keywords.
The particles in the fix group are the only ones whose velocities and positions are updated by the velocity/position
update portion of the NPH integration.
Regardless of what particles are in the fix group, a global pressure is computed for all particles. Similarly, when the
size of the simulation box is changed, all particles are re-scaled to new positions, unless the keyword dilate is specified
with a value of partial, in which case only the particles in the fix group are re-scaled. The latter can be useful for
leaving the coordinates of particles in a solid substrate unchanged and controlling the pressure of a surrounding fluid.

This fix computes a temperature and pressure each timestep. To do this, the fix creates its own computes of style
“temp/sphere” and “pressure”, as if these commands had been issued:

compute fix-ID_temp all temp/sphere

compute fix-ID_press all pressure fix-ID_temp

See the compute temp/sphere and compute pressure commands for details. Note that the IDs of the new computes are
the fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is “all” since
pressure is computed for the entire system.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

1334 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.104.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover barostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its thermostatting or barostatting procedure. If you do this, note that the kinetic
energy derived from the compute temperature should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nph command.
This fix can ramp its target pressure over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.104.5 Restrictions

This fix requires that atoms store torque and angular velocity (omega) and a radius as defined by the atom_style sphere
command.
All particles in the group must be finite-size spheres. They cannot be point particles.
Use of the disc keyword is only allowed for 2d simulations, as defined by the dimension keyword.

17.104.6 Related commands

fix nph, fix nve_sphere, fix nvt_sphere, fix npt_sphere, fix_modify

17.104.7 Default

none

17.105 fix nphug command

Accelerator Variants: nphug/omp

17.105.1 Syntax

fix ID group-ID nphug keyword value ...

• ID, group-ID are documented in fix command

one or more keyword value pairs may be appended
keyword = temp or iso or aniso or tri or x or y or z or couple or tchain or pchain␣
,→or mtk or tloop or ploop or nreset or drag or dilate or scaleyz or scalexz or␣

,→scalexy

17.105. fix nphug command 1335

LAMMPS Documentation, Release stable 29Sep2021

temp values = Value1 Value2 Tdamp

Value1, Value2 = Nose-Hoover target temperatures, ignored by Hugoniostat
Tdamp = temperature damping parameter (time units)
iso or aniso or tri values = Pstart Pstop Pdamp
Pstart,Pstop = scalar external pressures, must be equal (pressure units)
Pdamp = pressure damping parameter (time units)
x or y or z or xy or yz or xz values = Pstart Pstop Pdamp
Pstart,Pstop = external stress tensor components, must be equal (pressure units)
Pdamp = stress damping parameter (time units)
couple = none or xyz or xy or yz or xz
tchain value = length of thermostat chain (1 = single thermostat)
pchain values = length of thermostat chain on barostat (0 = no thermostat)
mtk value = yes or no = add in MTK adjustment term or not
tloop value = number of sub-cycles to perform on thermostat
ploop value = number of sub-cycles to perform on barostat thermostat
nreset value = reset reference cell every this many timesteps
drag value = drag factor added to barostat/thermostat (0.0 = no drag)
dilate value = all or partial
scaleyz value = yes or no = scale yz with lz
scalexz value = yes or no = scale xz with lz
scalexy value = yes or no = scale xy with ly

17.105.2 Examples

fix myhug all nphug temp 1.0 1.0 10.0 z 40.0 40.0 70.0
fix myhug all nphug temp 1.0 1.0 10.0 iso 40.0 40.0 70.0 drag 200.0 tchain 1 pchain 0

17.105.3 Description

This command is a variant of the Nose-Hoover fix npt fix style. It performs time integration of the Hugoniostat equations
of motion developed by Ravelo et al. (Ravelo). These equations compress the system to a state with average axial stress
or pressure equal to the specified target value and that satisfies the Rankine-Hugoniot (RH) jump conditions for steady
shocks.
The compression can be performed either hydrostatically (using keyword iso, aniso, or tri) or uniaxially (using keywords
x, y, or z). In the hydrostatic case, the cell dimensions change dynamically so that the average axial stress in all
three directions converges towards the specified target value. In the uniaxial case, the chosen cell dimension changes
dynamically so that the average axial stress in that direction converges towards the target value. The other two cell
dimensions are kept fixed (zero lateral strain).
This leads to the following additional restrictions on the keywords:
• One and only one of the following keywords should be used: iso, aniso, tri, x, y, z
• The specified initial and final target pressures must be the same.
• The keywords xy, xz, yz may not be used.
• The only admissible value for the couple keyword is xyz, which has the same effect as keyword iso
• The temp keyword must be used to specify the time constant for kinetic energy relaxation, but initial and final
target temperature values are ignored.

1336 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Essentially, a Hugoniostat simulation is an NPT simulation in which the user-specified target temperature is replaced
with a time-dependent target temperature Tt obtained from the following equation:
1


2 (P + P0 ) (V0 − V ) + E0 − E
Tt − T = =∆
Ndof kB
where T and Tt are the instantaneous and target temperatures, P and P0 are the instantaneous and reference pressures
or axial stresses, depending on whether hydrostatic or uniaxial compression is being performed, V and V0 are the
instantaneous and reference volumes, E and E0 are the instantaneous and reference internal energy (potential plus
kinetic), Ndof is the number of degrees of freedom used in the definition of temperature, and kB is the Boltzmann
constant. ∆ is the negative deviation of the instantaneous temperature from the target temperature. When the system
reaches a stable equilibrium, the value of ∆ should fluctuate about zero.
The values of E0 , V0 , and P0 are the instantaneous values at the start of the simulation. These can be overridden using
the fix_modify keywords e0, v0, and p0 described below.

Note: Unlike the fix temp/berendsen command which performs thermostatting but NO time integration, this fix per-
forms thermostatting/barostatting AND time integration. Thus you should not use any other time integration fix, such
as fix nve on atoms to which this fix is applied. Likewise, this fix should not be used on atoms that have their temperature
controlled by another fix - e.g. by fix langevin or fix temp/rescale commands.

This fix computes a temperature and pressure at each timestep. To do this, the fix creates its own computes of style
“temp” and “pressure”, as if one of these two sets of commands had been issued:

compute fix-ID_temp group-ID temp

compute fix-ID_press group-ID pressure fix-ID_temp

compute fix-ID_temp all temp

compute fix-ID_press all pressure fix-ID_temp

See the compute temp and compute pressure commands for details. Note that the IDs of the new computes are the
fix-ID + underscore + “temp” or fix_ID + underscore + “press”. The group for the new computes is “all” since pressure
is computed for the entire system.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.105. fix nphug command 1337

LAMMPS Documentation, Release stable 29Sep2021

17.105.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the values of E0 , V0 , and P0 , as well as the state of all the thermostat and barostat variables to binary
restart files. See the read_restart command for info on how to re-specify a fix in an input script that reads a restart file,
so that the operation of the fix continues in an uninterrupted fashion.
The fix_modify e0, v0 and p0 keywords can be used to define the values of E0 , V0 , and P0 . Note the the values for
e0 and v0 are extensive, and so must correspond to the total energy and volume of the entire system, not energy and
volume per atom. If any of these quantities are not specified, then the instantaneous value in the system at the start of
the simulation is used.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have defined
to this fix which will be used in its thermostatting or barostatting procedure, as described above. If you do this, note
that the kinetic energy derived from the compute temperature should be consistent with the virial term computed using
all atoms for the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details. Note that this energy is *not* included in the
definition of internal energy E when calculating the value of Delta in the above equation.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
This fix also computes a global vector of quantities, which can be accessed by various output commands. The scalar
The vector values are “intensive”.
The vector stores three quantities unique to this fix (∆, Us, and up), followed by all the internal Nose/Hoover thermostat
and barostat variables defined for fix npt. Delta is the deviation of the temperature from the target temperature, given
by the above equation. Us and up are the shock and particle velocity corresponding to a steady shock calculated from
the RH conditions. They have units of distance/time.

17.105.5 Restrictions

This fix style is part of the SHOCK package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
All the usual restrictions for fix npt apply, plus the additional ones mentioned above.

17.105.6 Related commands

fix msst, fix npt, fix_modify

17.105.7 Default

The keyword defaults are the same as those for fix npt

(Ravelo) Ravelo, Holian, Germann and Lomdahl, Phys Rev B, 70, 014103 (2004).

1338 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.106 fix npt/asphere command

Accelerator Variants: npt/asphere/omp

17.106.1 Syntax

fix ID group-ID npt/asphere keyword value ...

• ID, group-ID are documented in fix command

• npt/asphere = style name of this fix command
• additional thermostat and barostat related keyword/value pairs from the fix npt command can be appended

17.106.2 Examples

fix 1 all npt/asphere temp 300.0 300.0 100.0 iso 0.0 0.0 1000.0
fix 2 all npt/asphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0
fix 2 all npt/asphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 drag 0.2
fix 2 water npt/asphere temp 300.0 300.0 100.0 aniso 0.0 0.0 1000.0 dilate partial

17.106.3 Description

Perform constant NPT integration to update position, velocity, orientation, and angular velocity each timestep for
aspherical or ellipsoidal particles in the group using a Nose/Hoover temperature thermostat and Nose/Hoover pressure
barostat. P is pressure; T is temperature. This creates a system trajectory consistent with the isothermal-isobaric
ensemble.
This fix differs from the fix npt command, which assumes point particles and only updates their position and velocity.
The thermostat is applied to both the translational and rotational degrees of freedom for the aspherical particles, assum-
ing a compute is used which calculates a temperature that includes the rotational degrees of freedom (see below). The
translational degrees of freedom can also have a bias velocity removed from them before thermostatting takes place;
see the description below.
Additional parameters affecting the thermostat and barostat are specified by keywords and values documented with the
fix npt command. See, for example, discussion of the temp, iso, aniso, and dilate keywords.
The particles in the fix group are the only ones whose velocities and positions are updated by the velocity/position
update portion of the NPT integration.
Regardless of what particles are in the fix group, a global pressure is computed for all particles. Similarly, when the
size of the simulation box is changed, all particles are re-scaled to new positions, unless the keyword dilate is specified
with a value of partial, in which case only the particles in the fix group are re-scaled. The latter can be useful for
leaving the coordinates of particles in a solid substrate unchanged and controlling the pressure of a surrounding fluid.

This fix computes a temperature and pressure each timestep. To do this, the fix creates its own computes of style
“temp/asphere” and “pressure”, as if these commands had been issued:

compute fix-ID_temp all temp/asphere

compute fix-ID_press all pressure fix-ID_temp

17.106. fix npt/asphere command 1339

LAMMPS Documentation, Release stable 29Sep2021

See the compute temp/asphere and compute pressure commands for details. Note that the IDs of the new computes are
the fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is “all” since
pressure is computed for the entire system.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used with compute commands that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only calculating temperature for atoms in a geometric
region. This is not done by default, but only if the fix_modify command is used to assign a temperature compute to
this fix that includes such a bias term. See the doc pages for individual compute commands to determine which ones
include a bias. In this case, the thermostat works in the following manner: the current temperature is calculated taking
the bias into account, bias is removed from each atom, thermostatting is performed on the remaining thermal degrees
of freedom, and the bias is added back in.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.106.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat and barostat to binary restart files. See the read_restart com-
mand for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues
in an uninterrupted fashion.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its thermostatting or barostatting procedure. If you do this, note that the kinetic
energy derived from the compute temperature should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix npt command.
This fix can ramp its target temperature and pressure over multiple runs, using the start and stop keywords of the run
command. See the run command for details of how to do this.
This fix is not invoked during energy minimization.

1340 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.106.5 Restrictions

This fix is part of the ASPHERE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style ellipsoid
command.
All particles in the group must be finite-size. They cannot be point particles, but they can be aspherical or spherical as
defined by their shape attribute.

17.106.6 Related commands

fix npt, fix nve_asphere, fix nvt_asphere, fix_modify

17.106.7 Default

none

17.107 fix npt/body command

17.107.1 Syntax

fix ID group-ID npt/body keyword value ...

• ID, group-ID are documented in fix command

• npt/body = style name of this fix command
• additional thermostat and barostat related keyword/value pairs from the fix npt command can be appended

17.107.2 Examples

fix 1 all npt/body temp 300.0 300.0 100.0 iso 0.0 0.0 1000.0
fix 2 all npt/body temp 300.0 300.0 100.0 x 5.0 5.0 1000.0
fix 2 all npt/body temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 drag 0.2
fix 2 water npt/body temp 300.0 300.0 100.0 aniso 0.0 0.0 1000.0 dilate partial

17.107.3 Description

Perform constant NPT integration to update position, velocity, orientation, and angular velocity each timestep for body
particles in the group using a Nose/Hoover temperature thermostat and Nose/Hoover pressure barostat. P is pressure;
T is temperature. This creates a system trajectory consistent with the isothermal-isobaric ensemble.
This fix differs from the fix npt command, which assumes point particles and only updates their position and velocity.
The thermostat is applied to both the translational and rotational degrees of freedom for the body particles, assuming
a compute is used which calculates a temperature that includes the rotational degrees of freedom (see below). The
translational degrees of freedom can also have a bias velocity removed from them before thermostatting takes place;
see the description below.

17.107. fix npt/body command 1341

LAMMPS Documentation, Release stable 29Sep2021

Additional parameters affecting the thermostat and barostat are specified by keywords and values documented with the
fix npt command. See, for example, discussion of the temp, iso, aniso, and dilate keywords.
The particles in the fix group are the only ones whose velocities and positions are updated by the velocity/position
update portion of the NPT integration.
Regardless of what particles are in the fix group, a global pressure is computed for all particles. Similarly, when the
size of the simulation box is changed, all particles are re-scaled to new positions, unless the keyword dilate is specified
with a value of partial, in which case only the particles in the fix group are re-scaled. The latter can be useful for
leaving the coordinates of particles in a solid substrate unchanged and controlling the pressure of a surrounding fluid.

This fix computes a temperature and pressure each timestep. To do this, the fix creates its own computes of style
“temp/body” and “pressure”, as if these commands had been issued:

compute fix-ID_temp all temp/body

compute fix-ID_press all pressure fix-ID_temp

See the compute temp/body and compute pressure commands for details. Note that the IDs of the new computes are
the fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is “all” since
pressure is computed for the entire system.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used with compute commands that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only calculating temperature for atoms in a geometric
region. This is not done by default, but only if the fix_modify command is used to assign a temperature compute to
this fix that includes such a bias term. See the doc pages for individual compute commands to determine which ones
include a bias. In this case, the thermostat works in the following manner: the current temperature is calculated taking
the bias into account, bias is removed from each atom, thermostatting is performed on the remaining thermal degrees
of freedom, and the bias is added back in.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

1342 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.107.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat and barostat to binary restart files. See the read_restart com-
mand for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues
in an uninterrupted fashion.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its thermostatting or barostatting procedure. If you do this, note that the kinetic
energy derived from the compute temperature should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix npt command.
This fix can ramp its target temperature and pressure over multiple runs, using the start and stop keywords of the run
command. See the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.107.5 Restrictions

This fix is part of the BODY package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style body
command.

17.107.6 Related commands

fix npt, fix nve_body, fix nvt_body, fix_modify

17.107.7 Default

none

17.108 fix npt/cauchy command

17.108.1 Syntax

fix ID group-ID style_name keyword value ...

• ID, group-ID are documented in fix command

• style_name = npt/cauchy
• one or more keyword/value pairs may be appended
• keyword = temp or iso or aniso or tri or x or y or z or xy or yz or xz or couple or tchain or pchain or mtk or tloop
or ploop or nreset or drag or dilate or scalexy or scaleyz or scalexz or flip or fixedpoint

17.108. fix npt/cauchy command 1343

LAMMPS Documentation, Release stable 29Sep2021

temp values = Tstart Tstop Tdamp

Tstart,Tstop = external temperature at start/end of run
Tdamp = temperature damping parameter (time units)
iso or aniso or tri values = Pstart Pstop Pdamp
Pstart,Pstop = scalar external pressure at start/end of run (pressure units)
Pdamp = pressure damping parameter (time units)
x or y or z or xy or yz or xz values = Pstart Pstop Pdamp
Pstart,Pstop = external stress tensor component at start/end of run (pressure␣
,→units)

Pdamp = stress damping parameter (time units)

couple = none or xyz or xy or yz or xz
tchain value = N
N = length of thermostat chain (1 = single thermostat)
pchain values = N
N length of thermostat chain on barostat (0 = no thermostat)
mtk value = yes or no = add in MTK adjustment term or not
tloop value = M
M = number of sub-cycles to perform on thermostat
ploop value = M
M = number of sub-cycles to perform on barostat thermostat
nreset value = reset reference cell every this many timesteps
drag value = Df
Df = drag factor added to barostat/thermostat (0.0 = no drag)
dilate value = dilate-group-ID
dilate-group-ID = only dilate atoms in this group due to barostat volume changes
scalexy value = yes or no = scale xy with ly
scaleyz value = yes or no = scale yz with lz
scalexz value = yes or no = scale xz with lz
flip value = yes or no = allow or disallow box flips when it becomes highly skewed
alpha value = strength of Cauchy stress control parameter
continue value = yes or no = whether of not to continue from a previous run
fixedpoint values = x y z
x,y,z = perform barostat dilation/contraction around this point (distance units)

17.108.2 Examples

fix 1 water npt/cauchy temp 300.0 300.0 100.0 iso 0.0 0.0 1000.0 alpha 0.001

17.108.3 Description

This command performs time integration on Nose-Hoover style non-Hamiltonian equations of motion which are de-
signed to generate positions and velocities sampled from the isothermal-isobaric (npt) ensembles. This updates the
position and velocity for atoms in the group each timestep and the box dimensions.
The thermostatting and barostatting is achieved by adding some dynamic variables which are coupled to the particle
velocities (thermostatting) and simulation domain dimensions (barostatting). In addition to basic thermostatting and
barostatting, this fix can also create a chain of thermostats coupled to the particle thermostat, and another chain of
thermostats coupled to the barostat variables. The barostat can be coupled to the overall box volume, or to individual
dimensions, including the xy, xz and yz tilt dimensions. The external pressure of the barostat can be specified as either
a scalar pressure (isobaric ensemble) or as components of a symmetric stress tensor (constant stress ensemble). When
used correctly, the time-averaged temperature and stress tensor of the particles will match the target values specified
by Tstart/Tstop and Pstart/Pstop.

1344 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The equations of motion used are those of Shinoda et al in (Shinoda), which combine the hydrostatic equations of
Martyna, Tobias and Klein in (Martyna) with the strain energy proposed by Parrinello and Rahman in (Parrinello).
The time integration schemes closely follow the time-reversible measure-preserving Verlet and rRESPA integrators
derived by Tuckerman et al in (Tuckerman).

The thermostat parameters are specified using the temp keyword. Other thermostat-related keywords are tchain, tloop
and drag, which are discussed below.
The thermostat is applied to only the translational degrees of freedom for the particles. The translational degrees of
freedom can also have a bias velocity removed before thermostatting takes place; see the description below. The desired
temperature at each timestep is a ramped value during the run from Tstart to Tstop. The Tdamp parameter is specified
in time units and determines how rapidly the temperature is relaxed. For example, a value of 10.0 means to relax the
temperature in a timespan of (roughly) 10 time units (e.g. τ or fs or ps - see the units command). The atoms in the
fix group are the only ones whose velocities and positions are updated by the velocity/position update portion of the
integration.

Note: A Nose-Hoover thermostat will not work well for arbitrary values of Tdamp. If Tdamp is too small, the
temperature can fluctuate wildly; if it is too large, the temperature will take a very long time to equilibrate. A good
choice for many models is a Tdamp of around 100 timesteps. Note that this is NOT the same as 100 time units for most
units settings.

The barostat parameters are specified using one or more of the iso, aniso, tri, x, y, z, xy, xz, yz, and couple keywords.
These keywords give you the ability to specify all 6 components of an external stress tensor, and to couple various
of these components together so that the dimensions they represent are varied together during a constant-pressure
simulation.
Other barostat-related keywords are pchain, mtk, ploop, nreset, drag, and dilate, which are discussed below.
Orthogonal simulation boxes have 3 adjustable dimensions (x,y,z). Triclinic (non-orthogonal) simulation boxes have
6 adjustable dimensions (x,y,z,xy,xz,yz). The create_box, read data, and read_restart commands specify whether the
simulation box is orthogonal or non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz tilt factors.
The target pressures for each of the 6 components of the stress tensor can be specified independently via the x, y, z,
xy, xz, yz keywords, which correspond to the 6 simulation box dimensions. For each component, the external pressure
or tensor component at each timestep is a ramped value during the run from Pstart to Pstop. If a target pressure is
specified for a component, then the corresponding box dimension will change during a simulation. For example, if
the y keyword is used, the y-box length will change. If the xy keyword is used, the xy tilt factor will change. A box
dimension will not change if that component is not specified, although you have the option to change that dimension
via the fix deform command.
Note that in order to use the xy, xz, or yz keywords, the simulation box must be triclinic, even if its initial tilt factors are
0.0.
For all barostat keywords, the Pdamp parameter operates like the Tdamp parameter, determining the time scale on
which pressure is relaxed. For example, a value of 10.0 means to relax the pressure in a timespan of (roughly) 10 time
units (e.g. τ or fs or ps - see the units command).

Note: A Nose-Hoover barostat will not work well for arbitrary values of Pdamp. If Pdamp is too small, the pressure
and volume can fluctuate wildly; if it is too large, the pressure will take a very long time to equilibrate. A good choice
for many models is a Pdamp of around 1000 timesteps. However, note that Pdamp is specified in time units, and that
timesteps are NOT the same as time units for most units settings.

17.108. fix npt/cauchy command 1345

LAMMPS Documentation, Release stable 29Sep2021

Regardless of what atoms are in the fix group (the only atoms which are time integrated), a global pressure or stress
tensor is computed for all atoms. Similarly, when the size of the simulation box is changed, all atoms are re-scaled to
new positions, unless the keyword dilate is specified with a dilate-group-ID for a group that represents a subset of the
atoms. This can be useful, for example, to leave the coordinates of atoms in a solid substrate unchanged and controlling
the pressure of a surrounding fluid. This option should be used with care, since it can be unphysical to dilate some
atoms and not others, because it can introduce large, instantaneous displacements between a pair of atoms (one dilated,
one not) that are far from the dilation origin. Also note that for atoms not in the fix group, a separate time integration
fix like fix nve or fix nvt can be used on them, independent of whether they are dilated or not.

The couple keyword allows two or three of the diagonal components of the pressure tensor to be “coupled” together. The
value specified with the keyword determines which are coupled. For example, xz means the Pxx and Pzz components
of the stress tensor are coupled. Xyz means all 3 diagonal components are coupled. Coupling means two things: the
instantaneous stress will be computed as an average of the corresponding diagonal components, and the coupled box
dimensions will be changed together in lockstep, meaning coupled dimensions will be dilated or contracted by the
same percentage every timestep. The Pstart, Pstop, Pdamp parameters for any coupled dimensions must be identical.
Couple xyz can be used for a 2d simulation; the z dimension is simply ignored.

The iso, aniso, and tri keywords are simply shortcuts that are equivalent to specifying several other keywords together.
The keyword iso means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure),
and dilate/contract the dimensions together. Using “iso Pstart Pstop Pdamp” is the same as specifying these 4 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
couple xyz

The keyword aniso means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components
of the stress tensor as the driving forces, and the specified scalar external pressure. Using “aniso Pstart Pstop Pdamp”
is the same as specifying these 4 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
couple none

The keyword tri means x, y, z, xy, xz, and yz dimensions are controlled independently using their individual stress
components as the driving forces, and the specified scalar pressure as the external normal stress. Using “tri Pstart
Pstop Pdamp” is the same as specifying these 7 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
xy 0.0 0.0 Pdamp
yz 0.0 0.0 Pdamp
xz 0.0 0.0 Pdamp
couple none

In some cases (e.g. for solids) the pressure (volume) and/or temperature of the system can oscillate undesirably when
a Nose/Hoover barostat and thermostat is applied. The optional drag keyword will damp these oscillations, although
it alters the Nose/Hoover equations. A value of 0.0 (no drag) leaves the Nose/Hoover formalism unchanged. A non-
zero value adds a drag term; the larger the value specified, the greater the damping effect. Performing a short run and

1346 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

monitoring the pressure and temperature is the best way to determine if the drag term is working. Typically a value
between 0.2 to 2.0 is sufficient to damp oscillations after a few periods. Note that use of the drag keyword will interfere
with energy conservation and will also change the distribution of positions and velocities so that they do not correspond
to the nominal NVT, NPT, or NPH ensembles.
An alternative way to control initial oscillations is to use chain thermostats. The keyword tchain determines the number
of thermostats in the particle thermostat. A value of 1 corresponds to the original Nose-Hoover thermostat. The
keyword pchain specifies the number of thermostats in the chain thermostatting the barostat degrees of freedom. A
value of 0 corresponds to no thermostatting of the barostat variables.
The mtk keyword controls whether or not the correction terms due to Martyna, Tuckerman, and Klein are included in
the equations of motion (Martyna). Specifying no reproduces the original Hoover barostat, whose volume probability
distribution function differs from the true NPT and NPH ensembles by a factor of 1/V. Hence using yes is more correct,
but in many cases the difference is negligible.
The keyword tloop can be used to improve the accuracy of integration scheme at little extra cost. The initial and final
updates of the thermostat variables are broken up into tloop sub-steps, each of length dt/tloop. This corresponds to using
a first-order Suzuki-Yoshida scheme (Tuckerman). The keyword ploop does the same thing for the barostat thermostat.
The keyword nreset controls how often the reference dimensions used to define the strain energy are reset. If this
keyword is not used, or is given a value of zero, then the reference dimensions are set to those of the initial simulation
domain and are never changed. If the simulation domain changes significantly during the simulation, then the final
average pressure tensor will differ significantly from the specified values of the external stress tensor. A value of nstep
means that every nstep timesteps, the reference dimensions are set to those of the current simulation domain.
The scaleyz, scalexz, and scalexy keywords control whether or not the corresponding tilt factors are scaled with the
associated box dimensions when barostatting triclinic periodic cells. The default values yes will turn on scaling, which
corresponds to adjusting the linear dimensions of the cell while preserving its shape. Choosing no ensures that the tilt
factors are not scaled with the box dimensions. See below for restrictions and default values in different situations. In
older versions of LAMMPS, scaling of tilt factors was not performed. The old behavior can be recovered by setting all
three scale keywords to no.
The flip keyword allows the tilt factors for a triclinic box to exceed half the distance of the parallel box length, as
discussed below. If the flip value is set to yes, the bound is enforced by flipping the box when it is exceeded. If the flip
value is set to no, the tilt will continue to change without flipping. Note that if applied stress induces large deformations
(e.g. in a liquid), this means the box shape can tilt dramatically and LAMMPS will run less efficiently, due to the
large volume of communication needed to acquire ghost atoms around a processor’s irregular-shaped sub-domain. For
extreme values of tilt, LAMMPS may also lose atoms and generate an error.
The fixedpoint keyword specifies the fixed point for barostat volume changes. By default, it is the center of the box.
Whatever point is chosen will not move during the simulation. For example, if the lower periodic boundaries pass
through (0,0,0), and this point is provided to fixedpoint, then the lower periodic boundaries will remain at (0,0,0), while
the upper periodic boundaries will move twice as far. In all cases, the particle trajectories are unaffected by the chosen
value, except for a time-dependent constant translation of positions.

Note: Using a barostat coupled to tilt dimensions xy, xz, yz can sometimes result in arbitrarily large values of the
tilt dimensions, i.e. a dramatically deformed simulation box. LAMMPS allows the tilt factors to grow a small amount
beyond the normal limit of half the box length (0.6 times the box length), and then performs a box “flip” to an equivalent
periodic cell. See the discussion of the flip keyword above, to allow this bound to be exceeded, if desired.

The flip operation is described in more detail in the page for fix deform. Both the barostat dynamics and the atom
trajectories are unaffected by this operation. However, if a tilt factor is incremented by a large amount (1.5 times the
box length) on a single timestep, LAMMPS can not accommodate this event and will terminate the simulation with an
error. This error typically indicates that there is something badly wrong with how the simulation was constructed, such
as specifying values of Pstart that are too far from the current stress value, or specifying a timestep that is too large.

17.108. fix npt/cauchy command 1347

LAMMPS Documentation, Release stable 29Sep2021

Triclinic barostatting should be used with care. This also is true for other barostat styles, although they tend to be more
forgiving of insults. In particular, it is important to recognize that equilibrium liquids can not support a shear stress
and that equilibrium solids can not support shear stresses that exceed the yield stress.
One exception to this rule is if the first dimension in the tilt factor (x for xy) is non-periodic. In that case, the limits
on the tilt factor are not enforced, since flipping the box in that dimension does not change the atom positions due to
non-periodicity. In this mode, if you tilt the system to extreme angles, the simulation will simply become inefficient
due to the highly skewed simulation box.

Note: Unlike the fix temp/berendsen command which performs thermostatting but NO time integration, this fix per-
forms thermostatting/barostatting AND time integration. Thus you should not use any other time integration fix, such
as fix nve on atoms to which this fix is applied. Likewise, fix npt/cauchy should not normally be used on atoms that
also have their temperature controlled by another fix - e.g. by fix langevin or fix temp/rescale commands.

See the Howto thermostat and Howto barostat doc pages for a discussion of different ways to compute temperature and
perform thermostatting and barostatting.

This fix compute a temperature and pressure each timestep. To do this, the fix creates its own computes of style “temp”
and “pressure”, as if one of these sets of commands had been issued:

compute fix-ID_temp all temp

compute fix-ID_press all pressure fix-ID_temp

The group for both the new temperature and pressure compute is “all” since pressure is computed for the entire system.
See the compute temp and compute pressure commands for details. Note that the IDs of the new computes are the
fix-ID + underscore + “temp” or fix_ID + underscore + “press”.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of these fix’s temperature or pressure
via the compute_modify command. Or you can print this temperature or pressure during thermodynamic output
via the thermo_style custom command using the appropriate compute-ID. It also means that changing attributes of
thermo_temp or thermo_press will have no effect on this fix.
Like other fixes that perform thermostatting, fix npt/cauchy can be used with compute commands that calculate a
temperature after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group
of atoms or only calculating temperature on the x-component of velocity or only calculating temperature for atoms in
a geometric region. This is not done by default, but only if the fix_modify command is used to assign a temperature
compute to this fix that includes such a bias term. See the doc pages for individual compute commands to determine
which ones include a bias. In this case, the thermostat works in the following manner: the current temperature is
calculated taking the bias into account, bias is removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.

This fix can be used with either the verlet or respa integrators. When using this fix with respa, LAMMPS uses an
integrator constructed according to the following factorization of the Liouville propagator (for two rRESPA levels):
       
∆t ∆t ∆t (2) ∆t
exp (iL∆t) =Ê exp iLT-baro exp iLT-part exp iL,2 exp iL2
2 2 2 2
          n
(1) ∆t ∆t ∆t ∆t (1) ∆t
× exp iL2 exp iL,1 exp iL1 exp iL,1 exp iL2
2n 2n n 2n 2n
       
(2) ∆t ∆t ∆t ∆t
× exp iL2 exp iL,2 exp iLT-part exp iLT-baro
2 2 2 2
3


+ O ∆t

1348 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

This factorization differs somewhat from that of Tuckerman et al, in that the barostat is only updated at the outermost
rRESPA level, whereas Tuckerman’s factorization requires splitting the pressure into pieces corresponding to the forces
computed at each rRESPA level. In theory, the latter method will exhibit better numerical stability. In practice, because
Pdamp is normally chosen to be a large multiple of the outermost rRESPA timestep, the barostat dynamics are not the
limiting factor for numerical stability. Both factorizations are time-reversible and can be shown to preserve the phase
space measure of the underlying non-Hamiltonian equations of motion.

Note: Under NPT dynamics, for a system with zero initial total linear momentum, the total momentum fluctuates
close to zero. It may occasionally undergo brief excursions to non-negligible values, before returning close to zero.
Over long simulations, this has the effect of causing the center-of-mass to undergo a slow random walk. This can be
mitigated by resetting the momentum at infrequent intervals using the fix momentum command.

17.108.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of all the thermostat and barostat variables to binary restart files. See the read_restart command
for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in
an uninterrupted fashion.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have defined
to this fix which will be used in its thermostatting or barostatting procedure, as described above. If you do this, note
that the kinetic energy derived from the compute temperature should be consistent with the virial term computed using
all atoms for the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.

Note: If both the temp and press keywords are used in a single thermo_modify command (or in two separate com-
mands), then the order in which the keywords are specified is important. Note that a pressure compute defines its own
temperature compute as an argument when it is specified. The temp keyword will override this (for the pressure com-
pute being used by fix npt), but only if the temp keyword comes after the press keyword. If the temp keyword comes
before the press keyword, then the new pressure compute specified by the press keyword will be unaffected by the temp
setting.

The cumulative energy change in the system imposed by this fix, due to thermostatting and/or barostatting, is included
in the thermodynamic output keywords ecouple and econserve. See the thermo_style page for details.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
This fix also computes a global vector of quantities, which can be accessed by various output commands. Rhe vector
values are “intensive”.
The vector stores internal Nose/Hoover thermostat and barostat variables. The number and meaning of the vector values
depends on which fix is used and the settings for keywords tchain and pchain, which specify the number of Nose/Hoover
chains for the thermostat and barostat. If no thermostatting is done, then tchain is 0. If no barostatting is done, then
pchain is 0. In the following list, “ndof” is 0, 1, 3, or 6, and is the number of degrees of freedom in the barostat. Its
value is 0 if no barostat is used, else its value is 6 if any off-diagonal stress tensor component is barostatted, else its
value is 1 if couple xyz is used or couple xy for a 2d simulation, otherwise its value is 3.
The order of values in the global vector and their meaning is as follows. The notation means there are tchain values for
eta, followed by tchain for eta_dot, followed by ndof for omega, etc:
• eta[tchain] = particle thermostat displacements (unitless)
• eta_dot[tchain] = particle thermostat velocities (1/time units)

17.108. fix npt/cauchy command 1349

LAMMPS Documentation, Release stable 29Sep2021

• omega[ndof] = barostat displacements (unitless)

• omega_dot[ndof] = barostat velocities (1/time units)
• etap[pchain] = barostat thermostat displacements (unitless)
• etap_dot[pchain] = barostat thermostat velocities (1/time units)
• PE_eta[tchain] = potential energy of each particle thermostat displacement (energy units)
• KE_eta_dot[tchain] = kinetic energy of each particle thermostat velocity (energy units)
• PE_omega[ndof] = potential energy of each barostat displacement (energy units)
• KE_omega_dot[ndof] = kinetic energy of each barostat velocity (energy units)
• PE_etap[pchain] = potential energy of each barostat thermostat displacement (energy units)
• KE_etap_dot[pchain] = kinetic energy of each barostat thermostat velocity (energy units)
• PE_strain[1] = scalar strain energy (energy units)
This fix can ramp its external temperature and pressure over multiple runs, using the start and stop keywords of the run
command. See the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.108.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
X, y, z cannot be barostatted if the associated dimension is not periodic. Xy, xz, and yz can only be barostatted if the
simulation domain is triclinic and the second dimension in the keyword (y dimension in xy) is periodic. Z, xz, and yz,
cannot be barostatted for 2D simulations. The create_box, read data, and read_restart commands specify whether the
simulation box is orthogonal or non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz tilt factors.
For the temp keyword, the final Tstop cannot be 0.0 since it would make the external T = 0.0 at some timestep during
the simulation which is not allowed in the Nose/Hoover formulation.
The scaleyz yes and scalexz yes keyword/value pairs can not be used for 2D simulations. scaleyz yes, scalexz yes, and
scalexy yes options can only be used if the second dimension in the keyword is periodic, and if the tilt factor is not
coupled to the barostat via keywords tri, yz, xz, and xy.
The alpha keyword modifies the barostat as per Miller et al. (Miller)_”#nc-Miller” so that the Cauchy stress is con-
trolled. alpha is the non-dimensional parameter, typically set to 0.001 or 0.01 that determines how aggressively the
algorithm drives the system towards the set Cauchy stresses. Larger values of alpha will modify the system more
quickly, but can lead to instabilities. Smaller values will lead to longer convergence time. Since alpha also influences
how much the stress fluctuations deviate from the equilibrium fluctuations, it should be set as small as possible.
A continue value of yes indicates that the fix is subsequent to a previous run with the npt/cauchy fix, and the intention
is to continue from the converged stress state at the end of the previous run. This may be required, for example, when
implementing a multi-step loading/unloading sequence over several fixes.
Setting alpha to zero is not permitted. To “turn off” the cauchystat control and thus restore the equilibrium stress
fluctuations, two subsequent fixes should be used. In the first, fix npt/cauchy is used and the simulation box equilibrates
to the correct shape for the desired stresses. In the second, fix npt is used instead which uses the original Parrinello-
Rahman algorithm, but now with the corrected simulation box shape from using fix npt/cauchy.
This fix can be used with dynamic groups as defined by the group command. Likewise it can be used with groups to
which atoms are added or deleted over time, e.g. a deposition simulation. However, the conservation properties of the

1350 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

thermostat and barostat are defined for systems with a static set of atoms. You may observe odd behavior if the atoms
in a group vary dramatically over time or the atom count becomes very small.

17.108.6 Related commands

fix nve, fix_modify, run_style

17.108.7 Default

The keyword defaults are tchain = 3, pchain = 3, mtk = yes, tloop = ploop = 1, nreset = 0, drag = 0.0, dilate = all, couple
= none, cauchystat = no, scaleyz = scalexz = scalexy = yes if periodic in second dimension and not coupled to barostat,
otherwise no.

(Martyna) Martyna, Tobias and Klein, J Chem Phys, 101, 4177 (1994).
(Parrinello) Parrinello and Rahman, J Appl Phys, 52, 7182 (1981).
(Tuckerman) Tuckerman, Alejandre, Lopez-Rendon, Jochim, and Martyna, J Phys A: Math Gen, 39, 5629 (2006).
(Shinoda) Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).
(Miller) Miller, Tadmor, Gibson, Bernstein and Pavia, J Chem Phys, 144, 184107 (2016).

17.109 fix npt/sphere command

Accelerator Variants: npt/sphere/omp

17.109.1 Syntax

fix ID group-ID npt/sphere keyword value ...

• ID, group-ID are documented in fix command npt/sphere = style name of this fix command zero or more key-
word/value pairs may be appended
• keyword = disc
disc value = none = treat particles as 2d discs, not spheres
• additional thermostat and barostat related keyword/value pairs from the fix npt command can be appended

17.109.2 Examples

fix 1 all npt/sphere temp 300.0 300.0 100.0 iso 0.0 0.0 1000.0
fix 2 all npt/sphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0
fix 2 all npt/sphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 disc
fix 2 all npt/sphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 drag 0.2
fix 2 water npt/sphere temp 300.0 300.0 100.0 aniso 0.0 0.0 1000.0 dilate partial

17.109. fix npt/sphere command 1351

LAMMPS Documentation, Release stable 29Sep2021

17.109.3 Description

Perform constant NPT integration to update position, velocity, and angular velocity each timestep for finite-sizex spheri-
cal particles in the group using a Nose/Hoover temperature thermostat and Nose/Hoover pressure barostat. P is pressure;
T is temperature. This creates a system trajectory consistent with the isothermal-isobaric ensemble.
This fix differs from the fix npt command, which assumes point particles and only updates their position and velocity.
The thermostat is applied to both the translational and rotational degrees of freedom for the spherical particles, assuming
a compute is used which calculates a temperature that includes the rotational degrees of freedom (see below). The
translational degrees of freedom can also have a bias velocity removed from them before thermostatting takes place;
see the description below.
If the disc keyword is used, then each particle is treated as a 2d disc (circle) instead of as a sphere. This is only possible
for 2d simulations, as defined by the dimension keyword. The only difference between discs and spheres in this context
is their moment of inertia, as used in the time integration.
Additional parameters affecting the thermostat and barostat are specified by keywords and values documented with the
fix npt command. See, for example, discussion of the temp, iso, aniso, and dilate keywords.
The particles in the fix group are the only ones whose velocities and positions are updated by the velocity/position
update portion of the NPT integration.
Regardless of what particles are in the fix group, a global pressure is computed for all particles. Similarly, when the
size of the simulation box is changed, all particles are re-scaled to new positions, unless the keyword dilate is specified
with a value of partial, in which case only the particles in the fix group are re-scaled. The latter can be useful for
leaving the coordinates of particles in a solid substrate unchanged and controlling the pressure of a surrounding fluid.

This fix computes a temperature and pressure each timestep. To do this, the fix creates its own computes of style
“temp/sphere” and “pressure”, as if these commands had been issued:

compute fix-ID_temp all temp/sphere

compute fix-ID_press all pressure fix-ID_temp

See the compute temp/sphere and compute pressure commands for details. Note that the IDs of the new computes are
the fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is “all” since
pressure is computed for the entire system.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used with compute commands that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only calculating temperature for atoms in a geometric
region. This is not done by default, but only if the fix_modify command is used to assign a temperature compute to
this fix that includes such a bias term. See the doc pages for individual compute commands to determine which ones
include a bias. In this case, the thermostat works in the following manner: the current temperature is calculated taking
the bias into account, bias is removed from each atom, thermostatting is performed on the remaining thermal degrees
of freedom, and the bias is added back in.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc

1352 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.109.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat and barostat to binary restart files. See the read_restart com-
mand for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues
in an uninterrupted fashion.
The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its thermostatting or barostatting procedure. If you do this, note that the kinetic
energy derived from the compute temperature should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix npt command.
This fix can ramp its target temperature and pressure over multiple runs, using the start and stop keywords of the run
command. See the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.109.5 Restrictions

This fix requires that atoms store torque and angular velocity (omega) and a radius as defined by the atom_style sphere
command.
All particles in the group must be finite-size spheres. They cannot be point particles.
Use of the disc keyword is only allowed for 2d simulations, as defined by the dimension keyword.

17.109.6 Related commands

fix npt, fix nve_sphere, fix nvt_sphere, fix npt_asphere, fix_modify

17.109.7 Default

none

17.109. fix npt/sphere command 1353

LAMMPS Documentation, Release stable 29Sep2021

17.110 fix numdiff command

17.110.1 Syntax

fix ID group-ID numdiff Nevery delta

• ID, group-ID are documented in fix command

• numdiff = style name of this fix command
• Nevery = calculate force by finite difference every this many timesteps
• delta = finite difference displacement length (distance units)

17.110.2 Examples

fix 1 all numdiff 1 0.0001

fix 1 all numdiff 10 1e-6
fix 1 all numdiff 100 0.01

17.110.3 Description

Calculate forces through finite difference calculations of energy versus position. These forces can be compared to
analytic forces computed by pair styles, bond styles, etc. This can be useful for debugging or other purposes.
The group specified with the command means only atoms within the group have their averages computed. Results are
set to 0.0 for atoms not in the group.
This fix performs a loop over all atoms in the group. For each atom and each component of force it adds delta to the
position, and computes the new energy of the entire system. It then subtracts delta from the original position and again
computes the new energy of the system. It then restores the original position. That component of force is calculated as
the difference in energy divided by two times delta.

Note: It is important to choose a suitable value for delta, the magnitude of atom displacements that are used to generate
finite difference approximations to the exact forces. For typical systems, a value in the range of 1 part in 1e4 to 1e5
of the typical separation distance between atoms in the liquid or solid state will be sufficient. However, the best value
will depend on a multitude of factors including the stiffness of the interatomic potential, the thermodynamic state of
the material being probed, and so on. The only way to be sure that you have made a good choice is to do a sensitivity
study on a representative atomic configuration, sweeping over a wide range of values of delta. If delta is too small,
the output forces will vary erratically due to truncation effects. If delta is increased beyond a certain point, the output
forces will start to vary smoothly with delta, due to growing contributions from higher order derivatives. In between
these two limits, the numerical force values should be largely independent of delta.

Note: The cost of each energy evaluation is essentially the cost of an MD timestep. Thus invoking this fix once for
a 3d system has a cost of 6N timesteps, where N is the total number of atoms in the system (assuming all atoms are
included in the group). So this fix can be very expensive to use for large systems.

The Nevery argument specifies on what timesteps the force will be used calculated by finite difference.

1354 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The delta argument specifies the positional displacement each atom will undergo.

17.110.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix produces a per-atom array which can be accessed by various output commands, which stores the components
of the force on each atom as calculated by finite difference. The per-atom values can only be accessed on timesteps that
are multiples of Nevery since that is when the finite difference forces are calculated.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is invoked during
energy minimization.

17.110.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.110.6 Related commands

dynamical_matrix,

17.110.7 Default

none

17.111 fix nve command

Accelerator Variants: nve/gpu, nve/intel, nve/kk, nve/omp

17.111.1 Syntax

fix ID group-ID nve

• ID, group-ID are documented in fix command

• nve = style name of this fix command

17.111. fix nve command 1355

LAMMPS Documentation, Release stable 29Sep2021

17.111.2 Examples

fix 1 all nve

17.111.3 Description

Perform plain time integration to update position and velocity for atoms in the group each timestep. This creates
a system trajectory consistent with the microcanonical ensemble (NVE) provided there are (full) periodic boundary
conditions and no other “manipulations” of the system (e.g. fixes that modify forces or velocities).

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.111.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.111.5 Restrictions

none

17.111.6 Related commands

fix nvt, fix npt

17.111.7 Default

none

1356 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.112 fix nve/asphere command

Accelerator Variants: nve/asphere/gpu, nve/asphere/intel

17.112.1 Syntax

fix ID group-ID nve/asphere

• ID, group-ID are documented in fix command

• nve/asphere = style name of this fix command

17.112.2 Examples

fix 1 all nve/asphere

17.112.3 Description

Perform constant NVE integration to update position, velocity, orientation, and angular velocity for aspherical particles
in the group each timestep. V is volume; E is energy. This creates a system trajectory consistent with the microcanonical
ensemble.
This fix differs from the fix nve command, which assumes point particles and only updates their position and velocity.

17.112.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.112. fix nve/asphere command 1357

LAMMPS Documentation, Release stable 29Sep2021

17.112.5 Restrictions

This fix is part of the ASPHERE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style ellipsoid
command.
All particles in the group must be finite-size. They cannot be point particles, but they can be aspherical or spherical as
defined by their shape attribute.

17.112.6 Related commands

fix nve, fix nve/sphere

17.112.7 Default

none

17.113 fix nve/asphere/noforce command

17.113.1 Syntax

fix ID group-ID nve/asphere/noforce

• ID, group-ID are documented in fix command

• nve/asphere/noforce = style name of this fix command

17.113.2 Examples

fix 1 all nve/asphere/noforce

17.113.3 Description

Perform updates of position and orientation, but not velocity or angular momentum for atoms in the group each timestep.
In other words, the force and torque on the atoms is ignored and their velocity and angular momentum are not updated.
The atom velocities and angular momenta are used to update their positions and orientation.
This is useful as an implicit time integrator for Fast Lubrication Dynamics, since the velocity and angular momentum
are updated by the pair_style lubricuteU command.

1358 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.113.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.113.5 Restrictions

This fix is part of the ASPHERE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style ellipsoid
command.
All particles in the group must be finite-size. They cannot be point particles, but they can be aspherical or spherical as
defined by their shape attribute.

17.113.6 Related commands

fix nve/noforce, fix nve/asphere

17.113.7 Default

none

17.114 fix nve/awpmd command

17.114.1 Syntax

fix ID group-ID nve/awpmd

• ID, group-ID are documented in fix command

• nve/awpmd = style name of this fix command

17.114.2 Examples

fix 1 all nve/awpmd

17.114. fix nve/awpmd command 1359

LAMMPS Documentation, Release stable 29Sep2021

17.114.3 Description

Perform constant NVE integration to update position and velocity for nuclei and electrons in the group for the An-
tisymmetrized Wave Packet Molecular Dynamics model. V is volume; E is energy. This creates a system trajectory
consistent with the microcanonical ensemble.
The operation of this fix is exactly like that described by the fix nve command, except that the width and width-velocity
of the electron wave functions are also updated.

17.114.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.114.5 Restrictions

This fix is part of the AWPMD package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.114.6 Related commands

fix nve

17.114.7 Default

none

17.115 fix nve/body command

17.115.1 Syntax

fix ID group-ID nve/body

• ID, group-ID are documented in fix command

• nve/body = style name of this fix command

1360 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.115.2 Examples

fix 1 all nve/body

17.115.3 Description

Perform constant NVE integration to update position, velocity, orientation, and angular velocity for body particles in
the group each timestep. V is volume; E is energy. This creates a system trajectory consistent with the microcanonical
ensemble. See the Howto body page for more details on using body particles.
This fix differs from the fix nve command, which assumes point particles and only updates their position and velocity.

17.115.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.115.5 Restrictions

This fix is part of the BODY package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style body
command.
All particles in the group must be body particles. They cannot be point particles.

17.115.6 Related commands

fix nve, fix nve/sphere, fix nve/asphere

17.115.7 Default

none

17.116 fix nve/dot command

17.116.1 Syntax

fix ID group-ID nve/dot

• ID, group-ID are documented in fix command

• nve/dot = style name of this fix command

17.116. fix nve/dot command 1361

LAMMPS Documentation, Release stable 29Sep2021

17.116.2 Examples

fix 1 all nve/dot

17.116.3 Description

Apply a rigid-body integrator as described in (Davidchack) to a group of atoms, but without Langevin dynamics. This
command performs Molecular dynamics (MD) via a velocity-Verlet algorithm and an evolution operator that rotates
the quaternion degrees of freedom, similar to the scheme outlined in (Miller).
This command is the equivalent of the fix nve/dotc/langevin without damping and noise and can be used to determine the
stability range in a NVE ensemble prior to using the Langevin-type DOTC-integrator (see also fix nve/dotc/langevin).
The command is equivalent to the fix nve. The particles are always considered to have a finite size.
An example input file can be found in /examples/PACKAGES/cgdna/examples/duplex1/. Further details of the imple-
mentation and stability of the integrator are contained in (Henrich). The preprint version of the article can be found
here.

17.116.4 Restrictions

These pair styles can only be used if LAMMPS was built with the CG-DNA package and the MOLECULE and AS-
PHERE package. See the Build package page for more info.

17.116.5 Related commands

fix nve/dotc/langevin, fix nve

17.116.6 Default

none

(Davidchack) R.L Davidchack, T.E. Ouldridge, and M.V. Tretyakov. J. Chem. Phys. 142, 144114 (2015).
(Miller) T. F. Miller III, M. Eleftheriou, P. Pattnaik, A. Ndirango, G. J. Martyna, J. Chem. Phys., 116, 8649-8659
(2002).
(Henrich) O. Henrich, Y. A. Gutierrez-Fosado, T. Curk, T. E. Ouldridge, Eur. Phys. J. E 41, 57 (2018).

17.117 fix nve/dotc/langevin command

17.117.1 Syntax

fix ID group-ID nve/dotc/langevin Tstart Tstop damp seed keyword value

• ID, group-ID are documented in fix command

• nve/dotc/langevin = style name of this fix command

1362 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• Tstart,Tstop = desired temperature at start/end of run (temperature units)

• damp = damping parameter (time units)
• seed = random number seed to use for white noise (positive integer)
• keyword = angmom
angmom value = factor
factor = do thermostat rotational degrees of freedom via the angular momentum and␣
,→apply numeric scale factor as discussed below

17.117.2 Examples

fix 1 all nve/dotc/langevin 1.0 1.0 0.03 457145 angmom 10

fix 1 all nve/dotc/langevin 0.1 0.1 78.9375 457145 angmom 10

17.117.3 Description

Apply a rigid-body Langevin-type integrator of the kind “Langevin C” as described in (Davidchack) to a group of atoms,
which models an interaction with an implicit background solvent. This command performs Brownian dynamics (BD)
via a technique that splits the integration into a deterministic Hamiltonian part and the Ornstein-Uhlenbeck process for
noise and damping. The quaternion degrees of freedom are updated though an evolution operator which performs a
rotation in quaternion space, preserves the quaternion norm and is akin to (Miller).
In terms of syntax this command has been closely modelled on the fix langevin and its angmom option. But it combines
the fix nve and the fix langevin in one single command. The main feature is improved stability over the standard
integrator, permitting slightly larger timestep sizes.

Note: Unlike the fix langevin this command performs also time integration of the translational and quaternion degrees
of freedom.

The total force on each atom will have the form:

F =Fc + Ff + Fr
m
Ff = − v
damp
s
kB T m
Fr ∝
dt damp

Fc is the conservative force computed via the usual inter-particle interactions (pair_style, bond_style, etc). The Ff and
Fr terms are implicitly taken into account by this fix on a per-particle basis.
Ff is a frictional drag or viscous damping term proportional to the particle’s velocity. The proportionality constant for
each atom is computed as damp m
, where m is the mass of the particle and damp is the damping factor specified by the
user.
Fr is a force due to solvent atoms at a temperature T randomly bumping intoq
the particle. As derived from the fluc-
tuation/dissipation theorem, its magnitude as shown above is proportional to dtkBdamp Tm
, where kB is the Boltzmann
constant, T is the desired temperature, m is the mass of the particle, dt is the timestep size, and damp is the damping
factor. Random numbers are used to randomize the direction and magnitude of this force as described in (Dunweg),
where a uniform random number is used (instead of a Gaussian random number) for speed.

17.117. fix nve/dotc/langevin command 1363

LAMMPS Documentation, Release stable 29Sep2021

Tstart and Tstop have to be constant values, i.e. they cannot be variables. If used together with the oxDNA force field
for coarse-grained simulation of DNA please note that T = 0.1 in oxDNA units corresponds to T = 300 K.
The damp parameter is specified in time units and determines how rapidly the temperature is relaxed. For example, a
value of 0.03 means to relax the temperature in a timespan of (roughly) 0.03 time units τ (see the units command). The
damp factor can be thought of as inversely related to the viscosity of the solvent, i.e. a small relaxation time implies a
high-viscosity solvent and vice versa. See the discussion about gamma and viscosity in the documentation for the fix
viscous command for more details. Note that the value 78.9375 in the second example above corresponds to a diffusion
constant, which is about an order of magnitude larger than realistic ones. This has been used to sample configurations
faster in Brownian dynamics simulations.
The random # seed must be a positive integer. A Marsaglia random number generator is used. Each processor uses the
input seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the system
will not be identical on two runs on different numbers of processors.
The keyword/value option has to be used in the following way:
This fix has to be used together with the angmom keyword. The particles are always considered to have a finite size.
The keyword angmom enables thermostatting of the rotational degrees of freedom in addition to the usual translational
degrees of freedom.
The scale factor after the angmom keyword gives the ratio of the rotational to the translational friction coefficient.
An example input file can be found in examples/PACKAGES/cgdna/examples/duplex2/. Further details of the imple-
mentation and stability of the integrators are contained in (Henrich). The preprint version of the article can be found
here.

17.117.4 Restrictions

These pair styles can only be used if LAMMPS was built with the CG-DNA package and the MOLECULE and AS-
PHERE package. See the Build package page for more info.

17.117.5 Related commands

fix nve, fix langevin, fix nve/dot, bond_style oxdna/fene, bond_style oxdna2/fene, pair_style oxdna/excv, pair_style
oxdna2/excv

17.117.6 Default

none

(Davidchack) R.L Davidchack, T.E. Ouldridge, M.V. Tretyakov. J. Chem. Phys. 142, 144114 (2015).
(Miller) T. F. Miller III, M. Eleftheriou, P. Pattnaik, A. Ndirango, G. J. Martyna, J. Chem. Phys., 116, 8649-8659
(2002).
(Dunweg) B. Dunweg, W. Paul, Int. J. Mod. Phys. C, 2, 817-27 (1991).
(Henrich) O. Henrich, Y. A. Gutierrez-Fosado, T. Curk, T. E. Ouldridge, Eur. Phys. J. E 41, 57 (2018).

1364 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.118 fix nve/eff command

17.118.1 Syntax

fix ID group-ID nve/eff

• ID, group-ID are documented in fix command

• nve/eff = style name of this fix command

17.118.2 Examples

fix 1 all nve/eff

17.118.3 Description

Perform constant NVE integration to update position and velocity for nuclei and electrons in the group for the electron
force field model. V is volume; E is energy. This creates a system trajectory consistent with the microcanonical
ensemble.
The operation of this fix is exactly like that described by the fix nve command, except that the radius and radial velocity
of electrons are also updated.

17.118.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.118.5 Restrictions

This fix is part of the EFF package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.

17.118.6 Related commands

fix nve, fix nvt/eff , fix npt/eff

17.118.7 Default

none

17.118. fix nve/eff command 1365

LAMMPS Documentation, Release stable 29Sep2021

17.119 fix nve/limit command

17.119.1 Syntax

fix ID group-ID nve/limit xmax

• ID, group-ID are documented in fix command

• nve = style name of this fix command
• xmax = maximum distance an atom can move in one timestep (distance units)

17.119.2 Examples

fix 1 all nve/limit 0.1

17.119.3 Description

Perform constant NVE updates of position and velocity for atoms in the group each timestep. A limit is imposed on the
maximum distance an atom can move in one timestep. This is useful when starting a simulation with a configuration
containing highly overlapped atoms. Normally this would generate huge forces which would blow atoms out of the
simulation box, causing LAMMPS to stop with an error.
Using this fix can overcome that problem. Forces on atoms must still be computable (which typically means 2 atoms
must have a separation distance > 0.0). But large velocities generated by large forces are reset to a value that corresponds
to a displacement of length xmax in a single timestep. Xmax is specified in distance units; see the units command for
details. The value of xmax should be consistent with the neighbor skin distance and the frequency of neighbor list
re-building, so that pairwise interactions are not missed on successive timesteps as atoms move. See the neighbor and
neigh_modify commands for details.
Note that if a velocity reset occurs the integrator will not conserve energy. On steps where no velocity resets occur,
this integrator is exactly like the fix nve command. Since forces are unaltered, pressures computed by thermodynamic
output will still be very large for overlapped configurations.

Note: You should not use fix shake in conjunction with this fix. That is because fix shake applies constraint forces
based on the predicted positions of atoms after the next timestep. It has no way of knowing the timestep may change due
to this fix, which will cause the constraint forces to be invalid. A better strategy is to turn off fix shake when performing
initial dynamics that need this fix, then turn fix shake on when doing normal dynamics with a fixed-size timestep.

17.119.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the count of how
many updates of atom’s velocity/position were limited by the maximum distance criterion. This should be roughly the
number of atoms so affected, except that updates occur at both the beginning and end of a timestep in a velocity Verlet
timestepping algorithm. This is a cumulative quantity for the current run, but is re-initialized to zero each time a run
is performed. The scalar value calculated by this fix is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

1366 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.119.5 Restrictions

none

17.119.6 Related commands

fix nve, fix nve/noforce, pair_style soft

17.119.7 Default

none

17.120 fix nve/line command

17.120.1 Syntax

fix ID group-ID nve/line

• ID, group-ID are documented in fix command

• nve/line = style name of this fix command

17.120.2 Examples

fix 1 all nve/line

17.120.3 Description

Perform constant NVE integration to update position, velocity, orientation, and angular velocity for line segment par-
ticles in the group each timestep. V is volume; E is energy. This creates a system trajectory consistent with the
microcanonical ensemble. See Howto spherical page for an overview of using line segment particles.
This fix differs from the fix nve command, which assumes point particles and only updates their position and velocity.

17.120.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.120. fix nve/line command 1367

LAMMPS Documentation, Release stable 29Sep2021

17.120.5 Restrictions

This fix is part of the ASPHERE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires that particles be line segments as defined by the atom_style line command.

17.120.6 Related commands

fix nve, fix nve/asphere

17.120.7 Default

none

17.121 fix nve/manifold/rattle command

17.121.1 Syntax

fix ID group-ID nve/manifold/rattle tol maxit manifold manifold-args keyword value ...

• ID, group-ID are documented in fix command

• nve/manifold/rattle = style name of this fix command
• tol = tolerance to which Newton iteration must converge
• maxit = maximum number of iterations to perform
• manifold = name of the manifold
• manifold-args = parameters for the manifold
• one or more keyword/value pairs may be appended
keyword = every
every values = N
N = print info about iteration every N steps. N = 0 means no output

17.121.2 Examples

fix 1 all nve/manifold/rattle 1e-4 10 sphere 5.0

fix step all nve/manifold/rattle 1e-8 100 ellipsoid 2.5 2.5 5.0 every 25

1368 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.121.3 Description

Perform constant NVE integration to update position and velocity for atoms constrained to a curved surface (manifold)
in the group each timestep. The constraint is handled by RATTLE (Andersen) written out for the special case of single-
particle constraints as explained in (Paquay). V is volume; E is energy. This way, the dynamics of particles constrained
to curved surfaces can be studied. If combined with fix langevin, this generates Brownian motion of particles constrained
to a curved surface. For a list of currently supported manifolds and their parameters, see the Howto manifold doc page.
Note that the particles must initially be close to the manifold in question. If not, RATTLE will not be able to iterate
until the constraint is satisfied, and an error is generated. For simple manifolds this can be achieved with region and
create_atoms commands, but for more complex surfaces it might be more useful to write a script.
The manifold args may be equal-style variables, like so:

variable R equal "ramp(5.0,3.0)"

fix shrink_sphere all nve/manifold/rattle 1e-4 10 sphere v_R

In this case, the manifold parameter will change in time according to the variable. This is not a problem for the time
integrator as long as the change of the manifold is slow with respect to the dynamics of the particles. Note that if the
manifold has to exert work on the particles because of these changes, the total energy might not be conserved.

17.121.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.121.5 Restrictions

This fix is part of the MANIFOLD package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.121.6 Related commands

fix nvt/manifold/rattle, fix manifoldforce

17.121.7 Default

every = 0, tchain = 3

(Andersen) Andersen, J. Comp. Phys. 52, 24, (1983).

(Paquay) Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at arXiv:1411.3019.

17.121. fix nve/manifold/rattle command 1369

LAMMPS Documentation, Release stable 29Sep2021

17.122 fix nve/noforce command

17.122.1 Syntax

fix ID group-ID nve

• ID, group-ID are documented in fix command

• nve/noforce = style name of this fix command

17.122.2 Examples

fix 3 wall nve/noforce

17.122.3 Description

Perform updates of position, but not velocity for atoms in the group each timestep. In other words, the force on the
atoms is ignored and their velocity is not updated. The atom velocities are used to update their positions.
This can be useful for wall atoms, when you set their velocities, and want the wall to move (or stay stationary) in a
prescribed fashion.
This can also be accomplished via the fix setforce command, but with fix nve/noforce, the forces on the wall atoms are
unchanged, and can thus be printed by the dump command or queried with an equal-style variable that uses the fcm()
group function to compute the total force on the group of atoms.

17.122.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.122.5 Restrictions

none

17.122.6 Related commands

fix nve

1370 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.122.7 Default

none

17.123 fix nve/sphere command

Accelerator Variants: nve/sphere/omp, nve/sphere/kk

17.123.1 Syntax

fix ID group-ID nve/sphere

• ID, group-ID are documented in fix command

• nve/sphere = style name of this fix command
• zero or more keyword/value pairs may be appended
• keyword = update or disc
update value = dipole or dipole/dlm
dipole = update orientation of dipole moment during integration
dipole/dlm = use DLM integrator to update dipole orientation
disc value = none = treat particles as 2d discs, not spheres

17.123.2 Examples

fix 1 all nve/sphere

fix 1 all nve/sphere update dipole
fix 1 all nve/sphere disc
fix 1 all nve/sphere update dipole/dlm

17.123.3 Description

Perform constant NVE integration to update position, velocity, and angular velocity for finite-size spherical particles in
the group each timestep. V is volume; E is energy. This creates a system trajectory consistent with the microcanonical
ensemble.
This fix differs from the fix nve command, which assumes point particles and only updates their position and velocity.
If the update keyword is used with the dipole value, then the orientation of the dipole moment of each particle is also
updated during the time integration. This option should be used for models where a dipole moment is assigned to
finite-size particles, e.g. spheroids via use of the atom_style hybrid sphere dipole command.
The default dipole orientation integrator can be changed to the Dullweber-Leimkuhler-McLachlan integration scheme
(Dullweber) when using update with the value dipole/dlm. This integrator is symplectic and time-reversible, giving
better energy conservation and allows slightly longer timesteps at only a small additional computational cost.
If the disc keyword is used, then each particle is treated as a 2d disc (circle) instead of as a sphere. This is only possible
for 2d simulations, as defined by the dimension keyword. The only difference between discs and spheres in this context
is their moment of inertia, as used in the time integration.

17.123. fix nve/sphere command 1371

LAMMPS Documentation, Release stable 29Sep2021

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.123.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.123.5 Restrictions

This fix requires that atoms store torque and angular velocity (omega) and a radius as defined by the atom_style sphere
command. If the dipole keyword is used, then they must also store a dipole moment as defined by the atom_style dipole
command.
All particles in the group must be finite-size spheres. They cannot be point particles.
Use of the disc keyword is only allowed for 2d simulations, as defined by the dimension keyword.

17.123.6 Related commands

fix nve, fix nve/asphere

17.123.7 Default

none

(Dullweber) Dullweber, Leimkuhler and McLachlan, J Chem Phys, 107, 5840 (1997).

17.124 fix nve/spin command

17.124.1 Syntax

fix ID group-ID nve/spin keyword values

• ID, group-ID are documented in fix command

• nve/spin = style name of this fix command

1372 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• keyword = lattice
lattice value = moving or frozen
moving = integrate both spin and atomic degress of freedom
frozen = integrate spins on a fixed lattice

17.124.2 Examples

fix 3 all nve/spin lattice moving

fix 1 all nve/spin lattice frozen

17.124.3 Description

Perform a symplectic integration for the spin or spin-lattice system.

The lattice keyword defines if the spins are integrated on a lattice of fixed atoms (lattice = frozen), or if atoms are
moving (lattice = moving). The first case corresponds to a spin dynamics calculation, and the second to a spin-lattice
calculation. By default a spin-lattice integration is performed (lattice = moving).
The nve/spin fix applies a Suzuki-Trotter decomposition to the equations of motion of the spin lattice system, following
the scheme:

according to the implementation reported in (Omelyan).

A sectoring method enables this scheme for parallel calculations. The implementation of this sectoring algorithm is
reported in (Tranchida).

17.124. fix nve/spin command 1373

LAMMPS Documentation, Release stable 29Sep2021

17.124.4 Restrictions

This fix style can only be used if LAMMPS was built with the SPIN package. See the Build package page for more
info.
To use the spin algorithm, it is necessary to define a map with the atom_modify command. Typically, by adding the
command:

atom_modify map array

before you create the simulation box. Note that the keyword “hash” instead of “array” is also valid.

17.124.5 Related commands

atom_style spin, fix nve

17.124.6 Default

The option default is lattice = moving.

(Omelyan) Omelyan, Mryglod, and Folk. Phys. Rev. Lett. 86(5), 898. (2001).
(Tranchida) Tranchida, Plimpton, Thibaudeau and Thompson, Journal of Computational Physics, 372, 406-425,
(2018).

17.125 fix nve/tri command

17.125.1 Syntax

fix ID group-ID nve/tri

• ID, group-ID are documented in fix command

• nve/tri = style name of this fix command

17.125.2 Examples

fix 1 all nve/tri

17.125.3 Description

Perform constant NVE integration to update position, velocity, orientation, and angular momentum for triangular par-
ticles in the group each timestep. V is volume; E is energy. This creates a system trajectory consistent with the
microcanonical ensemble. See the Howto spherical page for an overview of using triangular particles.
This fix differs from the fix nve command, which assumes point particles and only updates their position and velocity.

1374 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.125.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.125.5 Restrictions

This fix is part of the ASPHERE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires that particles be triangles as defined by the atom_style tri command.

17.125.6 Related commands

fix nve, fix nve/asphere

17.125.7 Default

none

17.126 fix nvk command

17.126.1 Syntax

fix ID group-ID nvk

• ID, group-ID are documented in fix command

• nvk = style name of this fix command

17.126.2 Examples

fix 1 all nvk

17.126.3 Description

Perform constant kinetic energy integration using the Gaussian thermostat to update position and velocity for atoms in
the group each timestep. V is volume; K is kinetic energy. This creates a system trajectory consistent with the isokinetic
ensemble.
The equations of motion used are those of Minary et al in (Minary), a variant of those initially given by Zhang in
(Zhang).
The kinetic energy will be held constant at its value given when fix nvk is initiated. If a different kinetic energy is
desired, the velocity command should be used to change the kinetic energy prior to this fix.

17.126. fix nvk command 1375

LAMMPS Documentation, Release stable 29Sep2021

17.126.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.126.5 Restrictions

The Gaussian thermostat only works when it is applied to all atoms in the simulation box. Therefore, the group must
be set to all.
This fix has not yet been implemented to work with the RESPA integrator.
This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.126.6 Related commands

none

17.126.7 Default

none

(Minary) Minary, Martyna, and Tuckerman, J Chem Phys, 18, 2510 (2003).
(Zhang) Zhang, J Chem Phys, 106, 6102 (1997).

17.127 fix nvt/asphere command

Accelerator Variants: nvt/asphere/omp

17.127.1 Syntax

fix ID group-ID nvt/asphere keyword value ...

• ID, group-ID are documented in fix command

• nvt/asphere = style name of this fix command
• additional thermostat related keyword/value pairs from the fix nvt command can be appended

1376 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.127.2 Examples

fix 1 all nvt/asphere temp 300.0 300.0 100.0

fix 1 all nvt/asphere temp 300.0 300.0 100.0 drag 0.2

17.127.3 Description

Perform constant NVT integration to update position, velocity, orientation, and angular velocity each timestep for
aspherical or ellipsoidal particles in the group using a Nose/Hoover temperature thermostat. V is volume; T is temper-
ature. This creates a system trajectory consistent with the canonical ensemble.
This fix differs from the fix nvt command, which assumes point particles and only updates their position and velocity.
The thermostat is applied to both the translational and rotational degrees of freedom for the aspherical particles, assum-
ing a compute is used which calculates a temperature that includes the rotational degrees of freedom (see below). The
translational degrees of freedom can also have a bias velocity removed from them before thermostatting takes place;
see the description below.
Additional parameters affecting the thermostat are specified by keywords and values documented with the fix nvt com-
mand. See, for example, discussion of the temp and drag keywords.
This fix computes a temperature each timestep. To do this, the fix creates its own compute of style “temp/asphere”, as
if this command had been issued:

compute fix-ID_temp group-ID temp/asphere

See the compute temp/asphere command for details. Note that the ID of the new compute is the fix-ID + underscore +
“temp”, and the group for the new compute is the same as the fix group.
Note that this is NOT the compute used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp. This means you can change the attributes of this fix’s temperature (e.g. its degrees-of-freedom) via
the compute_modify command or print this temperature during thermodynamic output via the thermo_style custom
command using the appropriate compute-ID. It also means that changing attributes of thermo_temp will have no effect
on this fix.
Like other fixes that perform thermostatting, this fix can be used with compute commands that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only calculating temperature for atoms in a geometric
region. This is not done by default, but only if the fix_modify command is used to assign a temperature compute to
this fix that includes such a bias term. See the doc pages for individual compute commands to determine which ones
include a bias. In this case, the thermostat works in the following manner: the current temperature is calculated taking
the bias into account, bias is removed from each atom, thermostatting is performed on the remaining thermal degrees
of freedom, and the bias is added back in.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.127. fix nvt/asphere command 1377

LAMMPS Documentation, Release stable 29Sep2021

17.127.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp option is supported by this fix. You can use it to assign a compute you have defined to this fix
which will be used in its thermostatting procedure.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nvt command.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.127.5 Restrictions

This fix is part of the ASPHERE package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style ellipsoid
command.
All particles in the group must be finite-size. They cannot be point particles, but they can be aspherical or spherical as
defined by their shape attribute.

17.127.6 Related commands

fix nvt, fix nve_asphere, fix npt_asphere, fix_modify

17.127.7 Default

none

17.128 fix nvt/body command

17.128.1 Syntax

fix ID group-ID nvt/body keyword value ...

• ID, group-ID are documented in fix command

• nvt/body = style name of this fix command
• additional thermostat related keyword/value pairs from the fix nvt command can be appended

1378 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.128.2 Examples

fix 1 all nvt/body temp 300.0 300.0 100.0

fix 1 all nvt/body temp 300.0 300.0 100.0 drag 0.2

17.128.3 Description

Perform constant NVT integration to update position, velocity, orientation, and angular velocity each timestep for body
particles in the group using a Nose/Hoover temperature thermostat. V is volume; T is temperature. This creates a
system trajectory consistent with the canonical ensemble.
This fix differs from the fix nvt command, which assumes point particles and only updates their position and velocity.
The thermostat is applied to both the translational and rotational degrees of freedom for the body particles, assuming
a compute is used which calculates a temperature that includes the rotational degrees of freedom (see below). The
translational degrees of freedom can also have a bias velocity removed from them before thermostatting takes place;
see the description below.
Additional parameters affecting the thermostat are specified by keywords and values documented with the fix nvt com-
mand. See, for example, discussion of the temp and drag keywords.
This fix computes a temperature each timestep. To do this, the fix creates its own compute of style “temp/body”, as if
this command had been issued:

compute fix-ID_temp group-ID temp/body

See the compute temp/body command for details. Note that the ID of the new compute is the fix-ID + underscore +
“temp”, and the group for the new compute is the same as the fix group.
Note that this is NOT the compute used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp. This means you can change the attributes of this fix’s temperature (e.g. its degrees-of-freedom) via
the compute_modify command or print this temperature during thermodynamic output via the thermo_style custom
command using the appropriate compute-ID. It also means that changing attributes of thermo_temp will have no effect
on this fix.
Like other fixes that perform thermostatting, this fix can be used with compute commands that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only calculating temperature for atoms in a geometric
region. This is not done by default, but only if the fix_modify command is used to assign a temperature compute to
this fix that includes such a bias term. See the doc pages for individual compute commands to determine which ones
include a bias. In this case, the thermostat works in the following manner: the current temperature is calculated taking
the bias into account, bias is removed from each atom, thermostatting is performed on the remaining thermal degrees
of freedom, and the bias is added back in.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.128. fix nvt/body command 1379

LAMMPS Documentation, Release stable 29Sep2021

17.128.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp option is supported by this fix. You can use it to assign a compute you have defined to this fix
which will be used in its thermostatting procedure.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nvt command.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.128.5 Restrictions

This fix is part of the BODY package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
This fix requires that atoms store torque and angular momentum and a quaternion as defined by the atom_style body
command.

17.128.6 Related commands

fix nvt, fix nve_body, fix npt_body, fix_modify

17.128.7 Default

none

17.129 fix nvt/manifold/rattle command

17.129.1 Syntax

fix ID group-ID nvt/manifold/rattle tol maxit manifold manifold-args keyword value ...

• ID, group-ID are documented in fix command

• nvt/manifold/rattle = style name of this fix command
• tol = tolerance to which Newton iteration must converge
• maxit = maximum number of iterations to perform
• manifold = name of the manifold
• manifold-args = parameters for the manifold
• one or more keyword/value pairs may be appended

1380 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

keyword = temp or tchain or every

temp values = Tstart Tstop Tdamp
Tstart, Tstop = external temperature at start/end of run
Tdamp = temperature damping parameter (time units)
tchain value = N
N = length of thermostat chain (1 = single thermostat)
every value = N
N = print info about iteration every N steps. N = 0 means no output

17.129.2 Examples

fix 1 all nvt/manifold/rattle 1e-4 10 cylinder 3.0 temp 1.0 1.0 10.0

17.129.3 Description

This fix combines the RATTLE-based (Andersen) time integrator of fix nve/manifold/rattle (Paquay) with a Nose-
Hoover-chain thermostat to sample the canonical ensemble of particles constrained to a curved surface (manifold).
This sampling does suffer from discretization bias of O(dt). For a list of currently supported manifolds and their
parameters, see the Howto manifold doc page.

17.129.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.129.5 Restrictions

This fix is part of the MANIFOLD package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.129.6 Related commands

fix nve/manifold/rattle, fix manifoldforce Default: every = 0

(Andersen) Andersen, J. Comp. Phys. 52, 24, (1983).

(Paquay) Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at arXiv:1411.3019.

17.129. fix nvt/manifold/rattle command 1381

LAMMPS Documentation, Release stable 29Sep2021

17.130 fix nvt/sllod command

Accelerator Variants: nvt/sllod/intel, nvt/sllod/omp, nvt/sllod/kk

17.130.1 Syntax

fix ID group-ID nvt/sllod keyword value ...

• ID, group-ID are documented in fix command

• nvt/sllod = style name of this fix command
• additional thermostat related keyword/value pairs from the fix nvt command can be appended

17.130.2 Examples

fix 1 all nvt/sllod temp 300.0 300.0 100.0

fix 1 all nvt/sllod temp 300.0 300.0 100.0 drag 0.2

17.130.3 Description

Perform constant NVT integration to update positions and velocities each timestep for atoms in the group using a
Nose/Hoover temperature thermostat. V is volume; T is temperature. This creates a system trajectory consistent with
the canonical ensemble.
This thermostat is used for a simulation box that is changing size and/or shape, for example in a non-equilibrium
MD (NEMD) simulation. The size/shape change is induced by use of the fix deform command, so each point in the
simulation box can be thought of as having a “streaming” velocity. This position-dependent streaming velocity is
subtracted from each atom’s actual velocity to yield a thermal velocity which is used for temperature computation and
thermostatting. For example, if the box is being sheared in x, relative to y, then points at the bottom of the box (low
y) have a small x velocity, while points at the top of the box (hi y) have a large x velocity. These velocities do not
contribute to the thermal “temperature” of the atom.

Note: Fix deform has an option for remapping either atom coordinates or velocities to the changing simulation box.
To use fix nvt/sllod, fix deform should NOT remap atom positions, because fix nvt/sllod adjusts the atom positions
and velocities to create a velocity profile that matches the changing box size/shape. Fix deform SHOULD remap atom
velocities when atoms cross periodic boundaries since that is consistent with maintaining the velocity profile created
by fix nvt/sllod. LAMMPS will give an error if this setting is not consistent.

The SLLOD equations of motion, originally proposed by Hoover and Ladd (see (Evans and Morriss)), were proven
to be equivalent to Newton’s equations of motion for shear flow by (Evans and Morriss). They were later shown to
generate the desired velocity gradient and the correct production of work by stresses for all forms of homogeneous flow
by (Daivis and Todd). As implemented in LAMMPS, they are coupled to a Nose/Hoover chain thermostat in a velocity
Verlet formulation, closely following the implementation used for the fix nvt command.

Note: A recent (2017) book by (Daivis and Todd) discusses use of the SLLOD method and non-equilibrium MD
(NEMD) thermostatting generally, for both simple and complex fluids, e.g. molecular systems. The latter can be tricky
to do correctly.

1382 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Additional parameters affecting the thermostat are specified by keywords and values documented with the fix nvt com-
mand. See, for example, discussion of the temp and drag keywords.
This fix computes a temperature each timestep. To do this, the fix creates its own compute of style “temp/deform”, as
if this command had been issued:

compute fix-ID_temp group-ID temp/deform

See the compute temp/deform command for details. Note that the ID of the new compute is the fix-ID + underscore +
“temp”, and the group for the new compute is the same as the fix group.
Note that this is NOT the compute used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp. This means you can change the attributes of this fix’s temperature (e.g. its degrees-of-freedom) via
the compute_modify command or print this temperature during thermodynamic output via the thermo_style custom
command using the appropriate compute-ID. It also means that changing attributes of thermo_temp will have no effect
on this fix.
Like other fixes that perform thermostatting, this fix can be used with compute commands that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only calculating temperature for atoms in a geometric
region. This is not done by default, but only if the fix_modify command is used to assign a temperature compute to
this fix that includes such a bias term. See the doc pages for individual compute commands to determine which ones
include a bias. In this case, the thermostat works in the following manner: the current temperature is calculated taking
the bias into account, bias is removed from each atom, thermostatting is performed on the remaining thermal degrees
of freedom, and the bias is added back in.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.130.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp option is supported by this fix. You can use it to assign a compute you have defined to this fix
which will be used in its thermostatting procedure.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nvt command.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.130. fix nvt/sllod command 1383

LAMMPS Documentation, Release stable 29Sep2021

17.130.5 Restrictions

This fix works best without Nose-Hoover chain thermostats, i.e. using tchain = 1. Setting tchain to larger values can
result in poor equilibration.

17.130.6 Related commands

fix nve, fix nvt, fix temp/rescale, fix langevin, fix_modify, compute temp/deform

17.130.7 Default

Same as fix nvt, except tchain = 1.

(Evans and Morriss) Evans and Morriss, Phys Rev A, 30, 1528 (1984).
(Daivis and Todd) Daivis and Todd, J Chem Phys, 124, 194103 (2006).
(Daivis and Todd) Daivis and Todd, Nonequilibrium Molecular Dynamics (book), Cambridge University Press, https:
//doi.org/10.1017/9781139017848, (2017).

17.131 fix nvt/sllod/eff command

17.131.1 Syntax

fix ID group-ID nvt/sllod/eff keyword value ...

• ID, group-ID are documented in fix command

• nvt/sllod/eff = style name of this fix command
• additional thermostat related keyword/value pairs from the fix nvt/eff command can be appended

17.131.2 Examples

fix 1 all nvt/sllod/eff temp 300.0 300.0 0.1

fix 1 all nvt/sllod/eff temp 300.0 300.0 0.1 drag 0.2

17.131.3 Description

Perform constant NVT integration to update positions and velocities each timestep for nuclei and electrons in the group
for the electron force field model, using a Nose/Hoover temperature thermostat. V is volume; T is temperature. This
creates a system trajectory consistent with the canonical ensemble.
The operation of this fix is exactly like that described by the fix nvt/sllod command, except that the radius and radial
velocity of electrons are also updated and thermostatted. Likewise the temperature calculated by the fix, using the
compute it creates (as discussed in the fix nvt, npt, and nph doc page), is performed with a compute temp/deform/eff
command that includes the eFF contribution to the temperature from the electron radial velocity.

1384 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.131.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp option is supported by this fix. You can use it to assign a compute you have defined to this fix
which will be used in its thermostatting procedure.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nvt/eff command.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.131.5 Restrictions

This fix is part of the EFF package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.
This fix works best without Nose-Hoover chain thermostats, i.e. using tchain = 1. Setting tchain to larger values can
result in poor equilibration.

17.131.6 Related commands

fix nve/eff , fix nvt/eff , fix langevin/eff , fix nvt/sllod, fix_modify, compute temp/deform/eff

17.131.7 Default

Same as fix nvt/eff , except tchain = 1.

(Tuckerman) Tuckerman, Mundy, Balasubramanian, Klein, J Chem Phys, 106, 5615 (1997).

17.132 fix nvt/sphere command

Accelerator Variants: nvt/sphere/omp

17.132.1 Syntax

fix ID group-ID nvt/sphere keyword value ...

• ID, group-ID are documented in fix command

• nvt/sphere = style name of this fix command
• zero or more keyword/value pairs may be appended
• keyword = disc

17.132. fix nvt/sphere command 1385

LAMMPS Documentation, Release stable 29Sep2021

disc value = none = treat particles as 2d discs, not spheres

• additional thermostat related keyword/value pairs from the fix nvt command can be appended

17.132.2 Examples

fix 1 all nvt/sphere temp 300.0 300.0 100.0

fix 1 all nvt/sphere temp 300.0 300.0 100.0 disc
fix 1 all nvt/sphere temp 300.0 300.0 100.0 drag 0.2

17.132.3 Description

Perform constant NVT integration to update position, velocity, and angular velocity each timestep for finite-size spher-
ical particles in the group using a Nose/Hoover temperature thermostat. V is volume; T is temperature. This creates a
system trajectory consistent with the canonical ensemble.
This fix differs from the fix nvt command, which assumes point particles and only updates their position and velocity.
The thermostat is applied to both the translational and rotational degrees of freedom for the spherical particles, assuming
a compute is used which calculates a temperature that includes the rotational degrees of freedom (see below). The
translational degrees of freedom can also have a bias velocity removed from them before thermostatting takes place;
see the description below.
If the disc keyword is used, then each particle is treated as a 2d disc (circle) instead of as a sphere. This is only possible
for 2d simulations, as defined by the dimension keyword. The only difference between discs and spheres in this context
is their moment of inertia, as used in the time integration.
Additional parameters affecting the thermostat are specified by keywords and values documented with the fix nvt com-
mand. See, for example, discussion of the temp and drag keywords.
This fix computes a temperature each timestep. To do this, the fix creates its own compute of style “temp/sphere”, as
if this command had been issued:

compute fix-ID_temp group-ID temp/sphere

See the compute temp/sphere command for details. Note that the ID of the new compute is the fix-ID + underscore +
“temp”, and the group for the new compute is the same as the fix group.
Note that this is NOT the compute used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp. This means you can change the attributes of this fix’s temperature (e.g. its degrees-of-freedom) via
the compute_modify command or print this temperature during thermodynamic output via the thermo_style custom
command using the appropriate compute-ID. It also means that changing attributes of thermo_temp will have no effect
on this fix.
Like other fixes that perform thermostatting, this fix can be used with compute commands that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only calculating temperature for atoms in a geometric
region. This is not done by default, but only if the fix_modify command is used to assign a temperature compute to
this fix that includes such a bias term. See the doc pages for individual compute commands to determine which ones
include a bias. In this case, the thermostat works in the following manner: the current temperature is calculated taking
the bias into account, bias is removed from each atom, thermostatting is performed on the remaining thermal degrees
of freedom, and the bias is added back in.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc

1386 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.132.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the state of the Nose/Hoover thermostat to binary restart files. See the read_restart command for info
on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
The fix_modify temp option is supported by this fix. You can use it to assign a compute you have defined to this fix
which will be used in its thermostatting procedure.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes the same global scalar and global vector of quantities as does the fix nvt command.
This fix can ramp its target temperature over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.132.5 Restrictions

This fix requires that atoms store torque and angular velocity (omega) and a radius as defined by the atom_style sphere
command.
All particles in the group must be finite-size spheres. They cannot be point particles.
Use of the disc keyword is only allowed for 2d simulations, as defined by the dimension keyword.

17.132.6 Related commands

fix nvt, fix nve_sphere, fix nvt_asphere, fix npt_sphere, fix_modify

17.132.7 Default

none

17.132. fix nvt/sphere command 1387

LAMMPS Documentation, Release stable 29Sep2021

17.133 fix oneway command

17.133.1 Syntax

fix ID group-ID oneway N region-ID direction

• ID, group-ID are documented in fix command

• oneway = style name of this fix command
• N = apply this fix every this many timesteps
• region-ID = ID of region where fix is active
• direction = x or -x or y or -y or z or -z = coordinate and direction of the oneway constraint

17.133.2 Examples

fix ions oneway 10 semi -x

fix all oneway 1 left -z
fix all oneway 1 right z

17.133.3 Description

Enforce that particles in the group and in a given region can only move in one direction. This is done by reversing a
particle’s velocity component, if it has the wrong sign in the specified dimension. The effect is that the particle moves
in one direction only.
This can be used, for example, as a simple model of a semi-permeable membrane, or as an implementation of Maxwell’s
demon.

17.133.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.133.5 Restrictions

This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.

1388 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.133.6 Related commands

fix wall/reflect command

17.133.7 Default

none

17.134 fix orient/fcc command

17.135 fix orient/bcc command

17.135.1 Syntax

fix ID group-ID orient/fcc nstats dir alat dE cutlo cuthi file0 file1
fix ID group-ID orient/bcc nstats dir alat dE cutlo cuthi file0 file1

• ID, group-ID are documented in fix command

• nstats = print stats every this many steps, 0 = never
• dir = 0/1 for which crystal is used as reference
• alat = fcc/bcc cubic lattice constant (distance units)
• dE = energy added to each atom (energy units)
• cutlo,cuthi = values between 0.0 and 1.0, cutlo < cuthi
• file0,file1 = files that specify orientation of each grain

17.135.2 Examples

fix gb all orient/fcc 0 1 4.032008 0.001 0.25 0.75 xi.vec chi.vec

fix gb all orient/bcc 0 1 2.882 0.001 0.25 0.75 ngb.left ngb.right

17.135.3 Description

The fix applies an orientation-dependent force to atoms near a planar grain boundary which can be used to induce grain
boundary migration (in the direction perpendicular to the grain boundary plane). The motivation and explanation of
this force and its application are described in (Janssens). The adaptation to bcc crystals is described in (Wicaksono1).
The computed force is only applied to atoms in the fix group.
The basic idea is that atoms in one grain (on one side of the boundary) have a potential energy dE added to them.
Atoms in the other grain have 0.0 potential energy added. Atoms near the boundary (whose neighbor environment is
intermediate between the two grain orientations) have an energy between 0.0 and dE added. This creates an effective
driving force to reduce the potential energy of atoms near the boundary by pushing them towards one of the grain
orientations. For dir = 1 and dE > 0, the boundary will thus move so that the grain described by file0 grows and the
grain described by file1 shrinks. Thus this fix is designed for simulations of two-grain systems, either with one grain
boundary and free surfaces parallel to the boundary, or a system with periodic boundary conditions and two equal and

17.134. fix orient/fcc command 1389

LAMMPS Documentation, Release stable 29Sep2021

opposite grain boundaries. In either case, the entire system can displace during the simulation, and such motion should
be accounted for in measuring the grain boundary velocity.
The potential energy added to atom I is given by these formulas
12
X
rj − rIj 
 
ξi = (1)
j=1

12
X  J
rj − rIj 

ξIJ = (2)
j=1

ξlow =cutlo ξIJ (3)

ξhigh =cuthi ξIJ (4)

π ξi − ξlow
ωi = (5)
2 ξhigh − ξlow

ui =0 for ξi < ξlow

1 − cos(2ωi )
=dE for ξlow < ξi < ξhigh (6)
2
=dE for ξhigh < ξi

which are fully explained in (Janssens). For fcc crystals this order parameter Xi for atom I in equation (1) is a sum
over the 12 nearest neighbors of atom I. For bcc crystals it is the corresponding sum of the 8 nearest neighbors. Rj
is the vector from atom I to its neighbor J, and RIj is a vector in the reference (perfect) crystal. That is, if dir = 0/1,
then RIj is a vector to an atom coord from file 0/1. Equation (2) gives the expected value of the order parameter XiIJ
in the other grain. Hi and lo cutoffs are defined in equations (3) and (4), using the input parameters cutlo and cuthi as
thresholds to avoid adding grain boundary energy when the deviation in the order parameter from 0 or 1 is small (e.g.
due to thermal fluctuations in a perfect crystal). The added potential energy Ui for atom I is given in equation (6) where
it is interpolated between 0 and dE using the two threshold Xi values and the Wi value of equation (5).
The derivative of this energy expression gives the force on each atom which thus depends on the orientation of its
neighbors relative to the 2 grain orientations. Only atoms near the grain boundary feel a net force which tends to drive
them to one of the two grain orientations.
In equation (1), the reference vector used for each neighbor is the reference vector closest to the actual neighbor position.
This means it is possible two different neighbors will use the same reference vector. In such cases, the atom in question
is far from a perfect orientation and will likely receive the full dE addition, so the effect of duplicate reference vector
usage is small.
The dir parameter determines which grain wants to grow at the expense of the other. A value of 0 means the first grain
will shrink; a value of 1 means it will grow. This assumes that dE is positive. The reverse will be true if dE is negative.
The alat parameter is the cubic lattice constant for the fcc or bcc material and is only used to compute a cutoff distance
of 1.57 * alat / sqrt(2) for finding the 12 or 8 nearest neighbors of each atom (which should be valid for an fcc or bcc
crystal). A longer/shorter cutoff can be imposed by adjusting alat. If a particular atom has less than 12 or 8 neighbors
within the cutoff, the order parameter of equation (1) is effectively multiplied by 12 or 8 divided by the actual number
of neighbors within the cutoff.
The dE parameter is the maximum amount of additional energy added to each atom in the grain which wants to shrink.
The cutlo and cuthi parameters are used to reduce the force added to bulk atoms in each grain far away from the
boundary. An atom in the bulk surrounded by neighbors at the ideal grain orientation would compute an order parameter
of 0 or 1 and have no force added. However, thermal vibrations in the solid will cause the order parameters to be greater

1390 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

than 0 or less than 1. The cutoff parameters mask this effect, allowing forces to only be added to atoms with order-
parameters between the cutoff values.
File0 and file1 are filenames for the two grains which each contain 6 vectors (6 lines with 3 values per line) which
specify the grain orientations. Each vector is a displacement from a central atom (0,0,0) to a nearest neighbor atom in
an fcc lattice at the proper orientation. The vector lengths should all be identical since an fcc lattice has a coordination
number of 12. Only 6 are listed due to symmetry, so the list must include one from each pair of equal-and-opposite
neighbors. A pair of orientation files for a Sigma=5 tilt boundary are shown below. A tutorial that can help for writing
the orientation files is given in (Wicaksono2)

17.135.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy of atom interactions with the grain
boundary driving force to the global potential energy of the system as part of thermodynamic output. The default
setting for this fix is fix_modify energy no.
The fix_modify respa option is supported by these fixes. This allows to set at which level of the r-RESPA integrator a
fix is adding its forces. Default is the outermost level.
This fix calculates a global scalar which can be accessed by various output commands. The scalar is the potential
energy change due to this fix. The scalar value calculated by this fix is “extensive”.
This fix also calculates a per-atom array which can be accessed by various output commands. The array stores the
order parameter Xi and normalized order parameter (0 to 1) for each atom. The per-atom values can be accessed on
any timestep.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.135.5 Restrictions

These fixes are part of the ORIENT package. They are only enabled if LAMMPS was built with that package. See the
Build package page for more info.
These fixes should only be used with fcc or bcc lattices.

17.135.6 Related commands

fix_modify

17.135.7 Default

none

(Janssens) Janssens, Olmsted, Holm, Foiles, Plimpton, Derlet, Nature Materials, 5, 124-127 (2006).
(Wicaksono1) Wicaksono, Sinclair, Militzer, Computational Materials Science, 117, 397-405 (2016).
(Wicaksono2) Wicaksono, figshare, https://doi.org/10.6084/m9.figshare.1488628.v1 (2015).

17.135. fix orient/bcc command 1391

LAMMPS Documentation, Release stable 29Sep2021

For illustration purposes, here are example files that specify a Sigma=5 <100> tilt boundary. This is for a lattice constant
of 3.5706 Angs.
file0:

0.798410432046075 1.785300000000000 1.596820864092150

-0.798410432046075 1.785300000000000 -1.596820864092150
2.395231296138225 0.000000000000000 0.798410432046075
0.798410432046075 0.000000000000000 -2.395231296138225
1.596820864092150 1.785300000000000 -0.798410432046075
1.596820864092150 -1.785300000000000 -0.798410432046075

file1:

-0.798410432046075 1.785300000000000 1.596820864092150

0.798410432046075 1.785300000000000 -1.596820864092150
0.798410432046075 0.000000000000000 2.395231296138225
2.395231296138225 0.000000000000000 -0.798410432046075
1.596820864092150 1.785300000000000 0.798410432046075
1.596820864092150 -1.785300000000000 0.798410432046075

17.136 fix orient/eco command

fix ID group-ID orient/eco u0 eta cutoff orientationsFile

• ID, group-ID are documented in fix command

• u0 = energy added to each atom (energy units)
• eta = cutoff value (usually 0.25)
• cutoff = cutoff radius for orientation parameter calculation
• orientationsFile = file that specifies orientation of each grain

17.136.1 Examples

fix gb all orient/eco 0.08 0.25 3.524 sigma5.ori

17.136.2 Description

The fix applies a synthetic driving force to a grain boundary which can be used for the investigation of grain bound-
ary motion. The affiliation of atoms to either of the two grains forming the grain boundary is determined from an
orientation-dependent order parameter as described in (Ulomek). The potential energy of atoms is either increased
by an amount of 0.5*u0 or -0.5*u0 according to the orientation of the surrounding crystal. This creates a potential
energy gradient which pushes atoms near the grain boundary to orient according to the energetically favorable grain
orientation. This fix is designed for applications in bicrystal system with one grain boundary and open ends, or two
opposite grain boundaries in a periodic system. In either case, the entire system can experience a displacement dur-
ing the simulation which needs to be accounted for in the evaluation of the grain boundary velocity. While the basic
method is described in (Ulomek), the implementation follows the efficient implementation from (Schratt & Mohles).

1392 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The synthetic potential energy added to an atom j is given by the following formulas
(
rjk |4
|~ r |2
|~
4 − 2 rjk 2 + 1, |~rjk | < rcut
w(|~rjk |) = wjk = r cut cut
0, |~rjk | ≥ rcut
3
1 X  Ih 2  2 i
χj = ψl (~rj ) − ψlII (~rj )
N
l=1
X
X
wjk exp i~rjk · ~qlX


ψl (~rj ) =
k∈Γj

 1,  χj ≥ η
u0  πχj

u(χj ) = sin 2η , −η < χj < η
2 
−1, χj ≤ −η


which are fully explained in (Ulomek) and (Schratt & Mohles).

The force on each atom is the negative gradient of the synthetic potential energy. It depends on the surrounding of
this atom. An atom far from the grain boundary does not experience a synthetic force as its surrounding is that of an
oriented single crystal and thermal fluctuations are masked by the parameter eta. Near the grain boundary however, the
gradient is nonzero and synthetic force terms are computed. The orientationsFile specifies the perfect oriented crystal
basis vectors for the two adjoining crystals. The first three lines (line=row vector) for the energetically penalized and
the last three lines for the energetically favored grain assuming u0 is positive. For negative u0, this is reversed. With the
cutoff parameter, the size of the region around each atom which is used in the order parameter computation is defined.
The cutoff must be smaller than the interaction range of the MD potential. It should at least include the nearest neighbor
shell. For high temperatures or low angle grain boundaries, it might be beneficial to increase the cutoff in order to get
a more precise identification of the atoms surrounding. However, computation time will increase as more atoms are
considered in the order parameter and force computation. It is also worth noting that the cutoff radius must not exceed
the communication distance for ghost atoms in LAMMPS. With orientationsFile, the 6 oriented crystal basis vectors is
specified. Each line of the input file contains the three components of a primitive lattice vector oriented according to
the grain orientation in the simulation box. The first (last) three lines correspond to the primitive lattice vectors of the
first (second) grain. An example for a Σh001i mis-orientation is given at the end.
If no synthetic energy difference between the grains is created, u0 = 0, the force computation is omitted. In this
case, still, the order parameter of the driving force is computed and can be used to track the grain boundary motion
throughout the simulation.

17.136.3 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to :doc: binary restart files <restart>.
The fix_modify energy option is supported by this fix to add the potential energy of atom interactions with the grain
boundary driving force to the global potential energy of the system as part of thermodynamic output. The default
setting for this fix is fix_modify energy no.
This fix calculates a per-atom array with 2 columns, which can be accessed by indices 1-1 by any command that uses
per-atom values from a fix as input. See the Howto output doc page for an overview of LAMMPS output options.
The first column is the order parameter for each atom; the second is the thermal masking value for each atom. Both are
described above.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.136. fix orient/eco command 1393

LAMMPS Documentation, Release stable 29Sep2021

17.136.4 Restrictions

This fix is part of the ORIENT package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.136.5 Related commands

fix_modify
fix_orient

17.136.6 Default

none

(Ulomek) Ulomek, Brien, Foiles, Mohles, Modelling Simul. Mater. Sci. Eng. 23 (2015) 025007
(Schratt & Mohles) Schratt, Mohles. Comp. Mat. Sci. 182 (2020) 109774

For illustration purposes, here is an example file that specifies a Σ = 5h001i tilt grain boundary. This is for a lattice
constant of 3.52 Angstrom:

sigma5.ori:

1.671685 0.557228 1.76212

0.557228 -1.671685 1.76212
2.228913 -1.114456 0.00000
0.557228 1.671685 1.76212
1.671685 -0.557228 1.76212
2.228913 1.114456 0.00000

17.137 fix pafi command

17.137.1 Syntax

fix ID group-ID pafi compute-ID Temp Tdamp seed keyword values...

• ID, group-ID are documented in fix command

• pafi = style name of this fix command
• compute-ID = ID of a compute property/atom that holds data used by this fix
• Temp = desired temperature (temperature units)
• Tdamp = damping parameter (time units)
• seed = random number seed to use for white noise (positive integer)
• keyword = overdamped or com

1394 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

overdamped value = yes or no or 1 or 0

yes or 1 = Brownian (overdamped) integration in hyperplane
no or 0 = Langevin integration in hyperplane
com value = yes or no or 1 or 0
yes or 1 = zero linear momentum, fixing center or mass (recommended)
no or 0 = do not zero linear momentum, allowing center of mass drift

17.137.2 Examples

compute pa all property/atom d_nx d_ny d_nz d_dnx d_dny d_dnz d_ddnx d_ddny d_ddnz
run 0 post no
fix hp all pafi pa 500.0 0.01 434 overdamped yes

17.137.3 Description

Perform Brownian or Langevin integration whilst constraining the system to lie in some hyperplane, which is expected
to be the tangent plane to some reference pathway in a solid state system. The instantaneous value of a modified force
projection is also calculated, whose time integral can be shown to be equal to the true free energy gradient along the
minimum free energy path local to the reference pathway. A detailed discussion of the projection technique can be
found in (Swinburne).
This fix can be used with LAMMPS as demonstrated in examples/PACKAGES/pafi, though it is primarily intended to
be coupled with the PAFI C++ code, developed at https://github.com/tomswinburne/pafi, which distributes multiple
LAMMPS workers in parallel to compute and collate hyperplane-constrained averages, allowing the calculation of free
energy barriers and pathways.
A compute property/atom must be provided with 9 fields per atom coordinate, which in order are the x,y,z coordinates
of a configuration on the reference path, the x,y,z coordinates of the path tangent (derivative of path position with path
coordinate) and the x,y,z coordinates of the change in tangent (derivative of path tangent with path coordinate).
A 4-element vector is also calculated by this fix. The 4 components are the modified projected force, its square, the
expected projection of the minimum free energy path tangent on the reference path tangent and the minimum image
distance between the current configuration and the reference configuration, projected along the path tangent. This latter
value should be essentially zero.

Note: When com=yes/1, which is recommended, the provided tangent vector must also have zero center of mass. This
can be achieved by subtracting from each coordinate of the path tangent the average x,y,z value. The PAFI C++ code
(see above) can generate these paths for use in LAMMPS.

Note: When overdamped=yes/1, the Tdamp parameter should be around 5-10 times smaller than that used in typical
Langevin integration. See fix langevin for typical values.

17.137. fix pafi command 1395

LAMMPS Documentation, Release stable 29Sep2021

17.137.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix produces a global vector each timestep which can be accessed by various output commands.

17.137.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.137.6 Default

The option defaults are com = yes, overdamped = no

(Swinburne) Swinburne and Marinica, Physical Review Letters, 120, 1 (2018)

17.138 fix pair/tracker command

17.138.1 Syntax

fix ID group-ID pair/tracker N attribute1 attribute2 ... keyword values ...

• ID, group-ID are documented in fix command

• pair/tracker = style name of this fix command
• N = prepare data for output every this many timesteps
• one or more attributes may be appended

possible attributes = id1 id2 time/created time/broken time/total

rmin rave x y z

id1, id2 = IDs of the 2 atoms in each pair interaction

time/created = the time that the 2 atoms began interacting
time/broken = the time that the 2 atoms stopped interacting
time/total = the total time the 2 atoms interacted
r/min = the minimum radial distance between the 2 atoms during the interaction
r/ave = the average radial distance between the 2 atoms during the interaction
x, y, z = the center of mass position of the 2 atoms when they stopped interacting

• zero or more keyword/value pairs may be appended

• keyword = time/min or type/include
time/min value = T
T = minimum interaction time
type/include value = arg1 arg2
arg = separate lists of types (see below)

1396 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.138.2 Examples

fix 1 all pair/tracker 1000 id1 id2 time/min 100

fix 1 all pair/tracker 1000 time/created time/broken type/include 1 * type/include 2 3,4

17.138.3 Description

Tracks properties of pairwise interactions between two atoms and records data whenever the atoms move beyond the
interaction cutoff. Must be used in conjunction with pair tracker. Data is accumulated over a span of N timesteps
before being deleted. The number of datums generated, aggregated across all processors, equals the number of broken
interactions. Interactions are only included if both atoms are included in the specified fix group. Additional filters can
be applied using the time/min or type/include keywords described below.

Note: For extremely long-lived interactions, the calculation of r/ave may not be correct due to double overflow.

The time/min keyword sets a minimum amount of time that an interaction must persist to be included. This setting can
be used to censor short-lived interactions. The type/include keyword filters interactions based on the types of the two
atoms. Data is only saved for interactions between atoms with types in the two lists. Each list consists of a series of
type ranges separated by commas. The range can be specified as a single numeric value, or a wildcard asterisk can be
used to specify a range of values. This takes the form “*” or “*n” or “n*” or “m*n”. For example, if M = the number
of atom types, then an asterisk with no numeric values means all types from 1 to M. A leading asterisk means all types
from 1 to n (inclusive). A trailing asterisk means all types from n to M (inclusive). A middle asterisk means all types
from m to n (inclusive). Multiple type/include keywords may be added.

17.138.4 Restart, fix_modify, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No parameter of this fix can be used with the start/stop keywords of the run command.

17.138.5 Output info

This compute calculates a local vector or local array depending on the number of input values. The length of the vector
or number of rows in the array is the number of recorded, lost interactions. If a single input is specified, a local vector
is produced. If two or more inputs are specified, a local array is produced where the number of columns = the number
of inputs. The vector or array can be accessed by any command that uses local values from a compute as input. See
the Howto output page for an overview of LAMMPS output options.
The vector or array values will be doubles that correspond to the specified attribute.

17.138. fix pair/tracker command 1397

LAMMPS Documentation, Release stable 29Sep2021

17.138.6 Restrictions

Must be used in conjunction with pair style tracker.

This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.

17.138.7 Related commands

pair tracker

17.138.8 Default

none

17.139 fix phonon command

17.139.1 Syntax

fix ID group-ID phonon N Noutput Nwait map_file prefix keyword values ...

• ID, group-ID are documented in fix command

• phonon = style name of this fix command
• N = measure the Green’s function every this many timesteps
• Noutput = output the dynamical matrix every this many measurements
• Nwait = wait this many timesteps before measuring
• map_file = file or GAMMA
file is the file that contains the mapping info between atom ID and the lattice␣
,→indices.

GAMMA flags to treate the whole simulation box as a unit cell, so that the mapping
info can be generated internally. In this case, dynamical matrix at only the␣
,→gamma-point

will/can be evaluated.
• prefix = prefix for output files
• one or none keyword/value pairs may be appended
• keyword = sysdim or nasr
sysdim value = d
d = dimension of the system, usually the same as the MD model dimension
nasr value = n
n = number of iterations to enforce the acoustic sum rule

1398 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.139.2 Examples

fix 1 all phonon 20 5000 200000 map.in LJ1D sysdim 1

fix 1 all phonon 20 5000 200000 map.in EAM3D
fix 1 all phonon 10 5000 500000 GAMMA EAM0D nasr 100

17.139.3 Description

Calculate the dynamical matrix from molecular dynamics simulations based on fluctuation-dissipation theory for a
group of atoms.
Consider a crystal with N unit cells in three dimensions labeled l = (l1 , l2 , l3 ) where li are integers. Each unit cell is
defined by three linearly independent vectors a1 , a2 , a3 forming a parallelepiped, containing K basis atoms labeled k.
Based on fluctuation-dissipation theory, the force constant coefficients of the system in reciprocal space are given by
(Campana , Kong)

Φkα,k0 β (q) = kB T G−1

kα,k0 β (q)

where G is the Green’s functions coefficients given by

Gkα,k0 β (q) = ukα (q) • u∗k0 β (q)



where h. . .i denotes the ensemble average, and

X
ukα (q) = ulkα exp (iqrl )
l

is the α component of the atomic displacement for the k th atom in the unit cell in reciprocal space at q. In practice,
the Green’s functions coefficients can also be measured according to the following formula,
∗
Gkα,k0 β (q) = Rkα (q) • R∗k0 β (q) − hRikα (q) • hRik0 β (q)



where R is the instantaneous positions of atoms, and hRi is the averaged atomic positions. It gives essentially the same
results as the displacement method and is easier to implement in an MD code.
Once the force constant matrix is known, the dynamical matrix D can then be obtained by
1
Dkα,k0 β (q) = (mk mk0 )− 2 Φkα,k0 β (q)

whose eigenvalues are exactly the phonon frequencies at q.

This fix uses positions of atoms in the specified group and calculates two-point correlations. To achieve this. the
positions of the atoms are examined every Nevery steps and are Fourier-transformed into reciprocal space, where the
averaging process and correlation computation is then done. After every Noutput measurements, the matrix G(q) is
calculated and inverted to obtain the elastic stiffness coefficients. The dynamical matrices are then constructed and
written to prefix.bin.timestep files in binary format and to the file prefix.log for each wave-vector q.
A detailed description of this method can be found in (Kong2011).
The sysdim keyword is optional. If specified with a value smaller than the dimensionality of the LAMMPS simulation,
its value is used for the dynamical matrix calculation. For example, using LAMMPS to model a 2D or 3D system, the
phonon dispersion of a 1D atomic chain can be computed using sysdim = 1.
The nasr keyword is optional. An iterative procedure is employed to enforce the acoustic sum rule on Φ at Γ, and the
number provided by keyword nasr gives the total number of iterations. For a system whose unit cell has only one atom,
nasr = 1 is sufficient; for other systems, nasr = 10 is typically sufficient.

17.139. fix phonon command 1399

LAMMPS Documentation, Release stable 29Sep2021

The map_file contains the mapping information between the lattice indices and the atom IDs, which tells the code which
atom sits at which lattice point; the lattice indices start from 0. An auxiliary code, latgen, can be employed to generate
the compatible map file for various crystals.
In case one simulates a non-periodic system, where the whole simulation box is treated as a unit cell, one can set
map_file as GAMMA, so that the mapping info will be generated internally and a file is not needed. In this case, the
dynamical matrix at only the gamma-point will/can be evaluated. Please keep in mind that fix-phonon is designed for
cyrstals, it will be inefficient and even degrade the performance of lammps in case the unit cell is too large.
The calculated dynamical matrix elements are written out in energy/distance^2/mass units. The coordinates for q points
in the log file is in the units of the basis vectors of the corresponding reciprocal lattice.

17.139.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify temp option is supported by this fix. You can use it to change the temperature compute from
thermo_temp to the one that reflects the true temperature of atoms in the group.
No global scalar or vector or per-atom quantities are stored by this fix for access by various output commands.
Instead, this fix outputs its initialization information (including mapping information) and the calculated dynamical ma-
trices to the file prefix.log, with the specified prefix. The dynamical matrices are also written to files prefix.bin.timestep
in binary format. These can be read by the post-processing tool in tools/phonon to compute the phonon density of states
and/or phonon dispersion curves.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.139.5 Restrictions

This fix assumes a crystalline system with periodical lattice. The temperature of the system should not exceed the
melting temperature to keep the system in its solid state.
This fix is part of the PHONON package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix requires LAMMPS be built with an FFT library. See the Build settings page for details.

17.139.6 Related commands

compute msd, dynamical_matrix

17.139.7 Default

The option defaults are sysdim = the same dimension as specified by the dimension command, and nasr = 20.

(Campana) C. Campana and M. H. Muser, Practical Green’s function approach to the simulation of elastic semi-infinite
solids, Phys. Rev. B [74], 075420 (2006)
(Kong) L.T. Kong, G. Bartels, C. Campana, C. Denniston, and Martin H. Muser, Implementation of Green’s function
molecular dynamics: An extension to LAMMPS, Computer Physics Communications [180](6):1004-1010 (2009).

1400 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

L.T. Kong, C. Denniston, and Martin H. Muser, An improved version of the Green’s function molecular dynamics
method, Computer Physics Communications [182](2):540-541 (2011).
(Kong2011) L.T. Kong, Phonon dispersion measured directly from molecular dynamics simulations, Computer Physics
Communications [182](10):2201-2207, (2011).

17.140 fix pimd command

17.140.1 Syntax

fix ID group-ID pimd keyword value ...

• ID, group-ID are documented in fix command

• pimd = style name of this fix command
• zero or more keyword/value pairs may be appended
• keyword = method or fmass or sp or temp or nhc
method value = pimd or nmpimd or cmd
fmass value = scaling factor on mass
sp value = scaling factor on Planck constant
temp value = temperature (temperarate units)
nhc value = Nc = number of chains in Nose-Hoover thermostat

17.140.2 Examples

fix 1 all pimd method nmpimd fmass 1.0 sp 2.0 temp 300.0 nhc 4

17.140.3 Description

This command performs quantum molecular dynamics simulations based on the Feynman path integral to include ef-
fects of tunneling and zero-point motion. In this formalism, the isomorphism of a quantum partition function for the
original system to a classical partition function for a ring-polymer system is exploited, to efficiently sample configu-
rations from the canonical ensemble (Feynman). The classical partition function and its components are given by the
following equations:
Z
Z = dqdp · exp[−βHef f ]
P
p2i
X 
Hef f = + Vef f
i=1
2mi
P  
X mP 2 1
Vef f = (qi − q i+1 ) + V (qi )
i=1
2β 2 ~2 P

The interested user is referred to any of the numerous references on this methodology, but briefly, each quantum particle
in a path integral simulation is represented by a ring-polymer of P quasi-beads, labeled from 1 to P. During the simula-
tion, each quasi-bead interacts with beads on the other ring-polymers with the same imaginary time index (the second
term in the effective potential above). The quasi-beads also interact with the two neighboring quasi-beads through the
spring potential in imaginary-time space (first term in effective potential). To sample the canonical ensemble, a Nose-
Hoover massive chain thermostat is applied (Tuckerman). With the massive chain algorithm, a chain of NH thermostats

17.140. fix pimd command 1401

LAMMPS Documentation, Release stable 29Sep2021

is coupled to each degree of freedom for each quasi-bead. The keyword temp sets the target temperature for the system
and the keyword nhc sets the number Nc of thermostats in each chain. For example, for a simulation of N particles with
P beads in each ring-polymer, the total number of NH thermostats would be 3 x N x P x Nc.

Note: This fix implements a complete velocity-verlet integrator combined with NH massive chain thermostat, so no
other time integration fix should be used.

The method keyword determines what style of PIMD is performed. A value of pimd is standard PIMD. A value of
nmpimd is for normal-mode PIMD. A value of cmd is for centroid molecular dynamics (CMD). The difference between
the styles is as follows.
In standard PIMD, the value used for a bead’s fictitious mass is arbitrary. A common choice is to use Mi = m/P, which
results in the mass of the entire ring-polymer being equal to the real quantum particle. But it can be difficult to efficiently
integrate the equations of motion for the stiff harmonic interactions in the ring polymers.
A useful way to resolve this issue is to integrate the equations of motion in a normal mode representation, using Normal
Mode Path-Integral Molecular Dynamics (NMPIMD) (Cao1). In NMPIMD, the NH chains are attached to each normal
mode of the ring-polymer and the fictitious mass of each mode is chosen as Mk = the eigenvalue of the Kth normal
mode for k > 0. The k = 0 mode, referred to as the zero-frequency mode or centroid, corresponds to overall translation
of the ring-polymer and is assigned the mass of the real particle.
Motion of the centroid can be effectively uncoupled from the other normal modes by scaling the fictitious masses to
achieve a partial adiabatic separation. This is called a Centroid Molecular Dynamics (CMD) approximation (Cao2).
The time-evolution (and resulting dynamics) of the quantum particles can be used to obtain centroid time correlation
functions, which can be further used to obtain the true quantum correlation function for the original system. The CMD
method also uses normal modes to evolve the system, except only the k > 0 modes are thermostatted, not the centroid
degrees of freedom.
The keyword fmass sets a further scaling factor for the fictitious masses of beads, which can be used for the Partial
Adiabatic CMD (Hone), or to be set as P, which results in the fictitious masses to be equal to the real particle masses.
The keyword sp is a scaling factor on Planck’s constant, which can be useful for debugging or other purposes. The
default value of 1.0 is appropriate for most situations.
The PIMD algorithm in LAMMPS is implemented as a hyper-parallel scheme as described in (Calhoun). In LAMMPS
this is done by using multi-replica feature in LAMMPS, where each quasi-particle system is stored and simulated on
a separate partition of processors. The following diagram illustrates this approach. The original system with 2 ring
polymers is shown in red. Since each ring has 4 quasi-beads (imaginary time slices), there are 4 replicas of the system,
each running on one of the 4 partitions of processors. Each replica (shown in green) owns one quasi-bead in each ring.

1402 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

To run a PIMD simulation with M quasi-beads in each ring polymer using N MPI tasks for each partition’s domain-
decomposition, you would use P = MxN processors (cores) and run the simulation as follows:

mpirun -np P lmp_mpi -partition MxN -in script

Note that in the LAMMPS input script for a multi-partition simulation, it is often very useful to define a uloop-style
variable such as

variable ibead uloop M pad

where M is the number of quasi-beads (partitions) used in the calculation. The uloop variable can then be used to
manage I/O related tasks for each of the partitions, e.g.

dump dcd all dcd 10 system_${ibead}.dcd

restart 1000 system_${ibead}.restart1 system_${ibead}.restart2
read_restart system_${ibead}.restart2

17.140. fix pimd command 1403

LAMMPS Documentation, Release stable 29Sep2021

17.140.4 Restrictions

This fix is part of the REPLICA package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
A PIMD simulation can be initialized with a single data file read via the read_data command. However, this means
all quasi-beads in a ring polymer will have identical positions and velocities, resulting in identical trajectories for all
quasi-beads. To avoid this, users can simply initialize velocities with different random number seeds assigned to each
partition, as defined by the uloop variable, e.g.

velocity all create 300.0 1234${ibead} rot yes dist gaussian

17.140.5 Default

The keyword defaults are method = pimd, fmass = 1.0, sp = 1.0, temp = 300.0, and nhc = 2.

(Feynman) R. Feynman and A. Hibbs, Chapter 7, Quantum Mechanics and Path Integrals, McGraw-Hill, New York
(1965).
(Tuckerman) M. Tuckerman and B. Berne, J Chem Phys, 99, 2796 (1993).
(Cao1) J. Cao and B. Berne, J Chem Phys, 99, 2902 (1993).
(Cao2) J. Cao and G. Voth, J Chem Phys, 100, 5093 (1994).
(Hone) T. Hone, P. Rossky, G. Voth, J Chem Phys, 124, 154103 (2006).
(Calhoun) A. Calhoun, M. Pavese, G. Voth, Chem Phys Letters, 262, 415 (1996).

17.141 fix planeforce command

17.141.1 Syntax

fix ID group-ID planeforce x y z

• ID, group-ID are documented in fix command

• planeforce = style name of this fix command
• x y z = 3-vector that is normal to the plane

17.141.2 Examples

fix hold boundary planeforce 1.0 0.0 0.0

1404 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.141.3 Description

Adjust the forces on each atom in the group so that only the components of force in the plane specified by the normal
vector (x,y,z) remain. This is done by subtracting out the component of force perpendicular to the plane.
If the initial velocity of the atom is 0.0 (or in the plane), then it should continue to move in the plane thereafter.

17.141.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command.

17.141.5 Restrictions

none

17.141.6 Related commands

fix lineforce

17.141.7 Default

none

17.142 fix plumed command

17.142.1 Syntax

fix ID group-ID plumed keyword value ...

• ID, group-ID are documented in fix command

• plumed = style name of this fix command
• keyword = plumedfile or outfile
plumedfile arg = name of PLUMED input file to use (default: NULL)
outfile arg = name of file on which to write the PLUMED log (default: NULL)

17.142. fix plumed command 1405

LAMMPS Documentation, Release stable 29Sep2021

17.142.2 Examples

fix pl all plumed all plumed plumedfile plumed.dat outfile p.log

17.142.3 Description

This fix instructs LAMMPS to call the PLUMED library, which allows one to perform various forms of trajectory
analysis on the fly and to also use methods such as umbrella sampling and metadynamics to enhance the sampling of
phase space.
The documentation included here only describes the fix plumed command itself. This command is LAMMPS specific,
whereas most of the functionality implemented in PLUMED will work with a range of MD codes, and when PLUMED
is used as a stand alone code for analysis. The full documentation for PLUMED is available online and included in
the PLUMED source code. The PLUMED library development is hosted at https://github.com/plumed/plumed2 A
detailed discussion of the code can be found in (Tribello).
There is an example input for using this package with LAMMPS in the examples/PACKAGES/plumed directory.

The command to make LAMMPS call PLUMED during a run requires two keyword value pairs pointing to the
PLUMED input file and an output file for the PLUMED log. The user must specify these arguments every time
PLUMED is to be used. Furthermore, the fix plumed command should appear in the LAMMPS input file after relevant
input parameters (e.g. the timestep) have been set.
The group-ID entry is ignored. LAMMPS will always pass all the atoms to PLUMED and there can only be one
instance of the plumed fix at a time. The way the plumed fix is implemented ensures that the minimum amount of
information required is communicated. Furthermore, PLUMED supports multiple, completely independent collective
variables, multiple independent biases and multiple independent forms of analysis. There is thus really no restriction
in functionality by only allowing only one plumed fix in the LAMMPS input.
The plumedfile keyword allows the user to specify the name of the PLUMED input file. Instructions as to what should
be included in a plumed input file can be found in the documentation for PLUMED
The outfile keyword allows the user to specify the name of a file in which to output the PLUMED log. This log file
normally just repeats the information that is contained in the input file to confirm it was correctly read and parsed. The
names of the files in which the results are stored from the various analysis options performed by PLUMED will be
specified by the user in the PLUMED input file.

17.142.4 Restart, fix_modify, output, run start/stop, minimize info

When performing a restart of a calculation that involves PLUMED you must include a RESTART command in the
PLUMED input file as detailed in the PLUMED documentation. When the restart command is found in the PLUMED
input PLUMED will append to the files that were generated in the run that was performed previously. No part of the
PLUMED restart data is included in the LAMMPS restart files. Furthermore, any history dependent bias potentials that
were accumulated in previous calculations will be read in when the RESTART command is included in the PLUMED
input.
The fix_modify energy option is supported by this fix to add the energy change from the biasing force added by PLUMED
to the global potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify
energy yes.
The fix_modify virial option is supported by this fix to add the contribution from the biasing force to the global pressure
of the system via the compute pressure command. This can be accessed by thermodynamic output. The default setting
for this fix is fix_modify virial yes.

1406 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

This fix computes a global scalar which can be accessed by various output commands. The scalar is the PLUMED
energy mentioned above. The scalar value calculated by this fix is “extensive”.
Note that other quantities of interest can be output by commands that are native to PLUMED.

17.142.5 Restrictions

This fix is part of the PLUMED package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
There can only be one fix plumed command active at a time.

17.142.6 Related commands

fix smd fix colvars

17.142.7 Default

The default options are plumedfile = NULL and outfile = NULL

(Tribello) G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni and G. Bussi, Comp. Phys. Comm 185, 604 (2014)

17.143 fix poems command

17.143.1 Syntax

fix ID group-ID poems keyword values

• ID, group-ID are documented in fix command

• poems = style name of this fix command
• keyword = group or file or molecule
group values = list of group IDs
molecule values = none
file values = filename

17.143.2 Examples

fix 3 fluid poems group clump1 clump2 clump3

fix 3 fluid poems file cluster.list

17.143. fix poems command 1407

LAMMPS Documentation, Release stable 29Sep2021

17.143.3 Description

Treats one or more sets of atoms as coupled rigid bodies. This means that each timestep the total force and torque on
each rigid body is computed and the coordinates and velocities of the atoms are updated so that the collection of bodies
move as a coupled set. This can be useful for treating a large biomolecule as a collection of connected, coarse-grained
particles.
The coupling, associated motion constraints, and time integration is performed by the software package Parallelizable
Open source Efficient Multibody Software (POEMS) which computes the constrained rigid-body motion of articulated
(jointed) multibody systems (Anderson). POEMS was written and is distributed by Prof Kurt Anderson, his graduate
student Rudranarayan Mukherjee, and other members of his group at Rensselaer Polytechnic Institute (RPI). Rudra-
narayan developed the LAMMPS/POEMS interface. For copyright information on POEMS and other details, please
refer to the documents in the poems directory distributed with LAMMPS.
This fix updates the positions and velocities of the rigid atoms with a constant-energy time integration, so you should
not update the same atoms via other fixes (e.g. nve, nvt, npt, temp/rescale, langevin).
Each body must have a non-degenerate inertia tensor, which means if must contain at least 3 non-collinear atoms.
Which atoms are in which bodies can be defined via several options.
For option group, each of the listed groups is treated as a rigid body. Note that only atoms that are also in the fix group
are included in each rigid body.
For option molecule, each set of atoms in the group with a different molecule ID is treated as a rigid body.
For option file, sets of atoms are read from the specified file and each set is treated as a rigid body. Each line of the file
specifies a rigid body in the following format:
ID type atom1-ID atom2-ID atom3-ID . . .
ID as an integer from 1 to M (the number of rigid bodies). Type is any integer; it is not used by the fix poems command.
The remaining arguments are IDs of atoms in the rigid body, each typically from 1 to N (the number of atoms in the
system). Only atoms that are also in the fix group are included in each rigid body. Blank lines and lines that begin with
‘#’ are skipped.
A connection between a pair of rigid bodies is inferred if one atom is common to both bodies. The POEMS solver
treats that atom as a spherical joint with 3 degrees of freedom. Currently, a collection of bodies can only be connected
by joints as a linear chain. The entire collection of rigid bodies can represent one or more chains. Other connection
topologies (tree, ring) are not allowed, but will be added later. Note that if no joints exist, it is more efficient to use the
fix rigid command to simulate the system.
When the poems fix is defined, it will print out statistics on the total # of clusters, bodies, joints, atoms involved. A
cluster in this context means a set of rigid bodies connected by joints.
For computational efficiency, you should turn off pairwise and bond interactions within each rigid body, as they no
longer contribute to the motion. The “neigh_modify exclude” and “delete_bonds” commands can be used to do this if
each rigid body is a group.
For computational efficiency, you should only define one fix poems which includes all the desired rigid bodies.
LAMMPS will allow multiple poems fixes to be defined, but it is more expensive.
The degrees-of-freedom removed by coupled rigid bodies are accounted for in temperature and pressure computations.
Similarly, the rigid body contribution to the pressure virial is also accounted for. The latter is only correct if forces
within the bodies have been turned off, and there is only a single fix poems defined.

1408 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.143.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify virial option is supported by this fix to add the contribution due to the added forces and torques on
atoms to both the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom
commands. The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial
yes.
The fix_modify bodyforces option is supported by this fix style to set whether per-body forces and torques are computed
early or late in a timestep, i.e. at the post-force stage or at the final-integrate stage, respectively.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.143.5 Restrictions

This fix is part of the POEMS package. It is only enabled if LAMMPS was built with that package, which also requires
the POEMS library be built and linked with LAMMPS. See the Build package page for more info.

17.143.6 Related commands

fix rigid, delete_bonds, neigh_modify exclude

17.143.7 Default

none

(Anderson) Anderson, Mukherjee, Critchley, Ziegler, and Lipton “POEMS: Parallelizable Open-source Efficient
Multibody Software “, Engineering With Computers (2006). (link to paper)

17.144 fix polarize/bem/gmres command

17.145 fix polarize/bem/icc command

17.146 fix polarize/functional command

17.146.1 Syntax

fix ID group-ID style nevery tolerance ...

• ID, group-ID are documented in fix command

• style = polarize/bem/gmres or polarize/bem/icc or polarize/functional
• Nevery = this fixed is invoked every this many timesteps
• tolerance = the tolerance for the iterative solver to stop

17.144. fix polarize/bem/gmres command 1409

LAMMPS Documentation, Release stable 29Sep2021

17.146.2 Examples

fix 2 interface polarize/bem/gmres 5 0.0001

fix 1 interface polarize/bem/icc 1 0.0001
fix 3 interface polarize/functional 1 0.001

Used in input scripts:

examples/PACKAGES/dielectric/in.confined
examples/PACKAGES/dielectric/in.nopbc

17.146.3 Description

These fixes compute induced charges at the interface between two impermeable media with different dielectric con-
stants.
There are some example scripts for using this fix with LAMMPS in the examples/PACKAGES/dielectric directory.

For fix polarize/bem/gmres and fix polarize/bem/icc the induced charges of the atoms in the specified group, which are
the vertices on the interface, are computed using the equation:
..math:

\sigma_b(\mathbf{s}) = \dfrac{1 - \bar{\epsilon}}{\bar{\epsilon}}

\sigma_f(\mathbf{s}) - \epsilon_0 \dfrac{\Delta \epsilon}{\bar{\epsilon}}
\mathbf{E}(\mathbf{s}) \cdot \mathbf{n}(\mathbf{s})

• σb is the induced charge density at the interface vertex s.

• ¯ is the mean dielectric constant at the interface vertex: ¯ = (1 + 2 )/2.
• ∆ is the dielectric constant difference at the interface vertex: ∆ = 1 − 2
• σf is the free charge density at the interface vertex
• E(s) is the electrical field at the vertex
• n(s) is the unit normal vector at the vertex pointing from medium with 2 to that with 1
Fix polarize/bem/gmres employs the Generalized Minimum Residual (GMRES) as described in (Barros) to solve σb .
Fix polarize/bem/icc employs the successive over-relaxation algorithm as described in (Tyagi) to solve σb .
Fix polarize/functional . . .

17.146.4 Restart, fix_modify, output, run start/stop, minimize info

...

1410 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.146.5 Restrictions

These fixes are part of the DIELECTRIC package. It is only enabled if LAMMPS was built with that package, which
requires that also the KSPACE package is installed. See the Build package page for more info.

17.146.6 Related commands

compute efield/atom

17.146.7 Default

None.

(Barros) Barros, Sinkovits, Luijten, J. Chem. Phys, 140, 064903 (2014)

(Tyagi) Tyagi, Suzen, Sega, Barbosa, Kantorovich, Holm, J Chem Phys, 132, 154112 (2010)
(Jadhao) Jadhao, Solis, Olvera de la Cruz, J Chem Phys, 138, 054119 (2013)
(NguyenTD) Nguyen, Li, Bagchi, Solis, Olvera de la Cruz, Comput Phys Commun 241, 80-19 (2019)

17.147 fix pour command

17.147.1 Syntax

fix ID group-ID pour N type seed keyword values ...

• ID, group-ID are documented in fix command

• pour = style name of this fix command
• N = # of particles to insert
• type = atom type to assign to inserted particles (offset for molecule insertion)
• seed = random # seed (positive integer)
• one or more keyword/value pairs may be appended to args
• keyword = region or diam or vol or rate or dens or vel or mol or rigid or shake or ignore
region value = region-ID
region-ID = ID of region to use as insertion volume
diam values = dstyle args
dstyle = one or range or poly
one args = D
D = single diameter for inserted particles (distance units)
range args = Dlo Dhi
Dlo,Dhi = range of diameters for inserted particles (distance units)
poly args = Npoly D1 P1 D2 P2 ...
Npoly = # of (D,P) pairs
D1,D2,... = diameter for subset of inserted particles (distance units)
P1,P2,... = percentage of inserted particles with this diameter (0-1)
id values = idflag

17.147. fix pour command 1411

LAMMPS Documentation, Release stable 29Sep2021

idflag = max or next = how to choose IDs for inserted particles and molecules
vol values = fraction Nattempt
fraction = desired volume fraction for filling insertion volume
Nattempt = max # of insertion attempts per particle
rate value = V
V = z velocity (3d) or y velocity (2d) at which
insertion volume moves (velocity units)
dens values = Rholo Rhohi
Rholo,Rhohi = range of densities for inserted particles (mass/volume units)
vel values (3d) = vxlo vxhi vylo vyhi vz
vel values (2d) = vxlo vxhi vy
vxlo,vxhi = range of x velocities for inserted particles (velocity units)
vylo,vyhi = range of y velocities for inserted particles (velocity units)
vz = z velocity (3d) assigned to inserted particles (velocity units)
vy = y velocity (2d) assigned to inserted particles (velocity units)
mol value = template-ID
template-ID = ID of molecule template specified in a separate molecule command
molfrac values = f1 f2 ... fN
f1 to fN = relative probability of creating each of N molecules in template-ID
rigid value = fix-ID
fix-ID = ID of fix rigid/small command
shake value = fix-ID
fix-ID = ID of fix shake command
ignore value = none
skip any line or triangle particles when detecting possible
overlaps with inserted particles

17.147.2 Examples

fix 3 all pour 1000 2 29494 region myblock

fix 2 all pour 10000 1 19985583 region disk vol 0.33 100 rate 1.0 diam range 0.9 1.1
fix 2 all pour 10000 1 19985583 region disk diam poly 2 0.7 0.4 1.5 0.6
fix ins all pour 500 1 4767548 vol 0.8 10 region slab mol object rigid myRigid

17.147.3 Description

Insert finite-size particles or molecules into the simulation box every few timesteps within a specified region until N
particles or molecules have been inserted. This is typically used to model the pouring of granular particles into a
container under the influence of gravity. For the remainder of this doc page, a single inserted atom or molecule is
referred to as a “particle”.
If inserted particles are individual atoms, they are assigned the specified atom type. If they are molecules, the type of
each atom in the inserted molecule is specified in the file read by the molecule command, and those values are added
to the specified atom type. E.g. if the file specifies atom types 1,2,3, and those are the atom types you want for inserted
molecules, then specify type = 0. If you specify type = 2, the in the inserted molecule will have atom types 3,4,5.
All atoms in the inserted particle are assigned to two groups: the default group “all” and the group specified in the fix
pour command (which can also be “all”).
This command must use the region keyword to define an insertion volume. The specified region must have been
previously defined with a region command. It must be of type block or a z-axis cylinder and must be defined with side
= in. The cylinder style of region can only be used with 3d simulations.

1412 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Individual atoms are inserted, unless the mol keyword is used. It specifies a template-ID previously defined using the
molecule command, which reads a file that defines the molecule. The coordinates, atom types, center-of-mass, moments
of inertia, etc, as well as any bond/angle/etc and special neighbor information for the molecule can be specified in the
molecule file. See the molecule command for details. The only settings required to be in this file are the coordinates
and types of atoms in the molecule.
If the molecule template contains more than one molecule, the relative probability of depositing each molecule can be
specified by the molfrac keyword. N relative probabilities, each from 0.0 to 1.0, are specified, where N is the number
of molecules in the template. Each time a molecule is inserted, a random number is used to sample from the list of
relative probabilities. The N values must sum to 1.0.
If you wish to insert molecules via the mol keyword, that will be treated as rigid bodies, use the rigid keyword, speci-
fying as its value the ID of a separate fix rigid/small command which also appears in your input script.

Note: If you wish the new rigid molecules (and other rigid molecules) to be thermostatted correctly via fix
rigid/small/nvt or fix rigid/small/npt, then you need to use the “fix_modify dynamic/dof yes” command for the rigid
fix. This is to inform that fix that the molecule count will vary dynamically.

If you wish to insert molecules via the mol keyword, that will have their bonds or angles constrained via SHAKE, use
the shake keyword, specifying as its value the ID of a separate fix shake command which also appears in your input
script.
Each timestep particles are inserted, they are placed randomly inside the insertion volume so as to mimic a stream of
poured particles. If they are molecules they are also oriented randomly. Each atom in the particle is tested for overlaps
with existing particles, including effects due to periodic boundary conditions if applicable. If an overlap is detected,
another random insertion attempt is made; see the vol keyword discussion below. The larger the volume of the insertion
region, the more particles that can be inserted at any one timestep. Particles are inserted again after enough time has
elapsed that the previously inserted particles fall out of the insertion volume under the influence of gravity. Insertions
continue every so many timesteps until the desired # of particles has been inserted.

Note: If you are monitoring the temperature of a system where the particle count is changing due to adding particles,
you typically should use the compute_modify dynamic yes command for the temperature compute you are using.

All other keywords are optional with defaults as shown below.

The diam option is only used when inserting atoms and specifies the diameters of inserted particles. There are 3 styles:
one, range, or poly. For one, all particles will have diameter D. For range, the diameter of each particle will be chosen
randomly and uniformly between the specified Dlo and Dhi bounds. For poly, a series of Npoly diameters is specified.
For each diameter a percentage value from 0.0 to 1.0 is also specified. The Npoly percentages must sum to 1.0. For the
example shown above with “diam 2 0.7 0.4 1.5 0.6”, all inserted particles will have a diameter of 0.7 or 1.5. 40% of
the particles will be small; 60% will be large.
Note that for molecule insertion, the diameters of individual atoms in the molecule can be specified in the file read by
the molecule command. If not specified, the diameter of each atom in the molecule has a default diameter of 1.0.
The id option has two settings which are used to determine the atom or molecule IDs to assign to inserted parti-
cles/molecules. In both cases a check is done of the current system to find the maximum current atom and molecule
ID of any existing particle. Newly inserted particles and molecules are assigned IDs that increment those max values.
For the max setting, which is the default, this check is done at every insertion step, which allows for particles to leave
the system, and their IDs to potentially be re-used. For the next setting this check is done only once when the fix is
specified, which can be more efficient if you are sure particles will not be added in some other way.
The vol option specifies what volume fraction of the insertion volume will be filled with particles. For particles with
a size specified by the diam range keyword, they are assumed to all be of maximum diameter Dhi for purposes of

17.147. fix pour command 1413

LAMMPS Documentation, Release stable 29Sep2021

computing their contribution to the volume fraction.

The higher the volume fraction value, the more particles are inserted each timestep. Since inserted particles can-
not overlap, the maximum volume fraction should be no higher than about 0.6. Each timestep particles are inserted,
LAMMPS will make up to a total of M tries to insert the new particles without overlaps, where M = # of inserted
particles * Nattempt. If LAMMPS is unsuccessful at completing all insertions, it prints a warning.
The dens and vel options enable inserted particles to have a range of densities or xy velocities. The specific values
for a particular inserted particle will be chosen randomly and uniformly between the specified bounds. Internally, the
density value for a particle is converted to a mass, based on the radius (volume) of the particle. The vz or vy value for
option vel assigns a z-velocity (3d) or y-velocity (2d) to each inserted particle.
The rate option moves the insertion volume in the z direction (3d) or y direction (2d). This enables pouring particles
from a successively higher height over time.
The ignore option is useful when running a simulation that used line segment (2d) or triangle (3d) particles, typically
to define boundaries for spherical granular particles to interact with. See the atom_style line or tri command for details.
Lines and triangles store their size, and if the size is large it may overlap (in a spherical sense) with the insertion region,
even if the line/triangle is oriented such that there is no actual overlap. This can prevent particles from being inserted.
The ignore keyword causes the overlap check to skip any line or triangle particles. Obviously you should only use it if
there is in fact no overlap of the line or triangle particles with the insertion region.

17.147.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. This means you must be careful when restarting a pouring
simulation, when the restart file was written in the middle of the pouring operation. Specifically, you should use a new
fix pour command in the input script for the restarted simulation that continues the operation. You will need to adjust
the arguments of the original fix pour command to do this.
Also note that because the state of the random number generator is not saved in restart files, you cannot do “exact”
restarts with this fix, where the simulation continues on the same as if no restart had taken place. However, in a statistical
sense, a restarted simulation should produce the same behavior if you adjust the fix pour parameters appropriately.
None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access
by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.147.5 Restrictions

This fix is part of the GRANULAR package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
For 3d simulations, a gravity fix in the -z direction must be defined for use in conjunction with this fix. For 2d simula-
tions, gravity must be defined in the -y direction.
The specified insertion region cannot be a “dynamic” region, as defined by the region command.

1414 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.147.6 Related commands

fix deposit, fix gravity, region

17.147.7 Default

Insertions are performed for individual particles, i.e. no mol setting is defined. If the mol keyword is used, the default
for molfrac is an equal probabilities for all molecules in the template. Additional option defaults are diam = one 1.0,
dens = 1.0 1.0, vol = 0.25 50, rate = 0.0, vel = 0.0 0.0 0.0 0.0 0.0 (for 3d), vel = 0.0 0.0 0.0 (for 2d), and id = max.

17.148 fix precession/spin command

17.148.1 Syntax

fix ID group precession/spin style args

• ID, group are documented in fix command

• precession/spin = style name of this fix command
• style = zeeman or anisotropy or cubic or stt
zeeman args = H x y z
H = intensity of the magnetic field (in Tesla)
x y z = vector direction of the field
anisotropy args = K x y z
K = intensity of the magnetic anisotropy (in eV)
x y z = vector direction of the anisotropy
cubic args = K1 K2c n1x n1y n1x n2x n2y n2z n3x n3y n3z
K1 and K2c = intensity of the magnetic anisotropy (in eV)
n1x to n3z = three direction vectors of the cubic anisotropy
stt args = J x y z
J = intensity of the spin-transfer torque field
x y z = vector direction of the field

17.148.2 Examples

fix 1 all precession/spin zeeman 0.1 0.0 0.0 1.0

fix 1 3 precession/spin anisotropy 0.001 0.0 0.0 1.0
fix 1 iron precession/spin cubic 0.001 0.0005 1.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 1.0
fix 1 all precession/spin zeeman 0.1 0.0 0.0 1.0 anisotropy 0.001 0.0 0.0 1.0

17.148. fix precession/spin command 1415

LAMMPS Documentation, Release stable 29Sep2021

17.148.3 Description

This fix applies a precession torque to each magnetic spin in the group.
Style zeeman is used for the simulation of the interaction between the magnetic spins in the defined group and an
external magnetic field:
N
X
HZeeman = −g ~ ext
µi ~si · B
i=0

with:
• B
~ ext the external magnetic field (in T)

• g the Lande factor (hard-coded as g = 2.0)

• ~si the unitary vector describing the orientation of spin i
• µi the atomic moment of spin i given as a multiple of the Bohr magneton µB (for example, µi ≈ 2.2 in bulk
iron).
The field value in Tesla is multiplied by the gyromagnetic ratio, g · µB /~, converting it into a precession frequency in
rad.THz (in metal units and with µB = 5.788 · 10−5 eV/T).
As a comparison, the figure below displays the simulation of a single spin (of norm µi = 1.0) submitted to an external
magnetic field of |Bext | = 10.0 Tesla (and oriented along the z axis). The upper plot shows the average magnetization
along the external magnetic field axis and the lower plot the Zeeman energy, both as a function of temperature. The
reference result is provided by the plot of the Langevin function for the same parameters.

The temperature effects are accounted for by connecting the spin i to a thermal bath using a Langevin thermostat (see
fix langevin/spin for the definition of this thermostat).

1416 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Style anisotropy is used to simulate an easy axis or an easy plane for the magnetic spins in the defined group:
N
X 2
Haniso = − Kan (ri ) (~si · ~ni )
i=1

with n defining the direction of the anisotropy, and K (in eV) its intensity. If K > 0, an easy axis is defined, and if
K < 0, an easy plane is defined.
Style cubic is used to simulate a cubic anisotropy, with three possible easy axis for the magnetic spins in the defined
group:
N h i
(c)
X 2 2 2 2 2 2 2 2 2
Hcubic = − K1 (~si · n~1 ) (~si · n~2 ) + (~si · n~2 ) (~si · n~3 ) + (~si · n~1 ) (~si · n~3 ) + K2 (~si · n~1 ) (~si · n~2 ) (~si · n~3 )
i=1

with K1 and K2c (in eV) the intensity coefficients and ~n1 , ~n2 and ~n3 defining the three anisotropic directions defined
by the command (from n1x to n3z). For ~n1 = (100), ~n2 = (010), and ~n3 = (001), K1 < 0 defines an iron type
anisotropy (easy axis along the (001)-type cube edges), and K1 > 0 defines a nickel type anisotropy (easy axis along
the (111)-type cube diagonals). K2c > 0 also defines easy axis along the (111)-type cube diagonals. See chapter 2 of
(Skomski) for more details on cubic anisotropies.
Style stt is used to simulate the interaction between the spins and a spin-transfer torque. See equation (7) of (Chirac)
for more details about the implemented spin-transfer torque term.
In all cases, the choice of (xyz) only imposes the vector directions for the forces. Only the direction of the vector is
important; its length is ignored (the entered vectors are normalized).
Those styles can be combined within one single command line.

Note: The norm of all vectors defined with the precession/spin command have to be non-zero. For example, defining
“fix 1 all precession/spin zeeman 0.1 0.0 0.0 0.0” would result in an error message. Since those vector components are
used to compute the inverse of the field (or anisotropy) vector norm, setting a zero-vector would result in a division by
zero.

17.148.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the energy associated with the spin precession torque to
the global potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify
energy no.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the potential energy
(in energy units) discussed in the previous paragraph. The scalar value is an “extensive” quantity.
No information about this fix is written to binary restart files.

17.148. fix precession/spin command 1417

LAMMPS Documentation, Release stable 29Sep2021

17.148.5 Restrictions

The precession/spin style is part of the SPIN package. This style is only enabled if LAMMPS was built with this
package, and if the atom_style “spin” was declared. See the Build package page for more info.

17.148.6 Related commands

atom_style spin

17.148.7 Default

none

(Skomski) Skomski, R. (2008). Simple models of magnetism. Oxford University Press.

(Chirac) Chirac, Theophile, et al. Ultrafast antiferromagnetic switching in NiO induced by spin transfer torques.
Physical Review B 102.13 (2020): 134415.

17.149 fix press/berendsen command

17.149.1 Syntax

fix ID group-ID press/berendsen keyword value ...

• ID, group-ID are documented in fix command

• press/berendsen = style name of this fix command
one or more keyword value pairs may be appended
keyword = iso or aniso or x or y or z or couple or dilate or modulus
iso or aniso values = Pstart Pstop Pdamp
Pstart,Pstop = scalar external pressure at start/end of run (pressure units)
Pdamp = pressure damping parameter (time units)
x or y or z values = Pstart Pstop Pdamp
Pstart,Pstop = external stress tensor component at start/end of run (pressure␣
,→units)

Pdamp = stress damping parameter (time units)

couple = none or xyz or xy or yz or xz
modulus value = bulk modulus of system (pressure units)
dilate value = all or partial

1418 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.149.2 Examples

fix 1 all press/berendsen iso 0.0 0.0 1000.0

fix 2 all press/berendsen aniso 0.0 0.0 1000.0 dilate partial

17.149.3 Description

Reset the pressure of the system by using a Berendsen barostat (Berendsen), which rescales the system volume and
(optionally) the atoms coordinates within the simulation box every timestep.
Regardless of what atoms are in the fix group, a global pressure is computed for all atoms. Similarly, when the size
of the simulation box is changed, all atoms are re-scaled to new positions, unless the keyword dilate is specified with
a value of partial, in which case only the atoms in the fix group are re-scaled. The latter can be useful for leaving the
coordinates of atoms in a solid substrate unchanged and controlling the pressure of a surrounding fluid.

Note: Unlike the fix npt or fix nph commands which perform Nose/Hoover barostatting AND time integration, this fix
does NOT perform time integration. It only modifies the box size and atom coordinates to effect barostatting. Thus you
must use a separate time integration fix, like fix nve or fix nvt to actually update the positions and velocities of atoms.
This fix can be used in conjunction with thermostatting fixes to control the temperature, such as fix nvt or fix langevin
or fix temp/berendsen.

See the Howto baroostat page for a discussion of different ways to perform barostatting.

The barostat is specified using one or more of the iso, aniso, x, y, z, and couple keywords. These keywords give you
the ability to specify the 3 diagonal components of an external stress tensor, and to couple various of these components
together so that the dimensions they represent are varied together during a constant-pressure simulation. Unlike the
fix npt and fix nph commands, this fix cannot be used with triclinic (non-orthogonal) simulation boxes to control all 6
components of the general pressure tensor.
The target pressures for each of the 3 diagonal components of the stress tensor can be specified independently via the
x, y, z, keywords, which correspond to the 3 simulation box dimensions. For each component, the external pressure
or tensor component at each timestep is a ramped value during the run from Pstart to Pstop. If a target pressure is
specified for a component, then the corresponding box dimension will change during a simulation. For example, if the
y keyword is used, the y-box length will change. A box dimension will not change if that component is not specified,
although you have the option to change that dimension via the fix deform command.
For all barostat keywords, the Pdamp parameter determines the time scale on which pressure is relaxed. For example,
a value of 10.0 means to relax the pressure in a timespan of (roughly) 10 time units (tau or fs or ps - see the units
command).

Note: A Berendsen barostat will not work well for arbitrary values of Pdamp. If Pdamp is too small, the pressure
and volume can fluctuate wildly; if it is too large, the pressure will take a very long time to equilibrate. A good choice
for many models is a Pdamp of around 1000 timesteps. However, note that Pdamp is specified in time units, and that
timesteps are NOT the same as time units for most units settings.

Note: The relaxation time is actually also a function of the bulk modulus of the system (inverse of isothermal com-
pressibility). The bulk modulus has units of pressure and is the amount of pressure that would need to be applied
(isotropically) to reduce the volume of the system by a factor of 2 (assuming the bulk modulus was a constant, inde-
pendent of density, which it’s not). The bulk modulus can be set via the keyword modulus. The Pdamp parameter
is effectively multiplied by the bulk modulus, so if the pressure is relaxing faster than expected or desired, increasing

17.149. fix press/berendsen command 1419

LAMMPS Documentation, Release stable 29Sep2021

the bulk modulus has the same effect as increasing Pdamp. The converse is also true. LAMMPS does not attempt to
guess a correct value of the bulk modulus; it just uses 10.0 as a default value which gives reasonable relaxation for a
Lennard-Jones liquid, but will be way off for other materials and way too small for solids. Thus you should experiment
to find appropriate values of Pdamp and/or the modulus when using this fix.

The couple keyword allows two or three of the diagonal components of the pressure tensor to be “coupled” together. The
value specified with the keyword determines which are coupled. For example, xz means the Pxx and Pzz components
of the stress tensor are coupled. Xyz means all 3 diagonal components are coupled. Coupling means two things: the
instantaneous stress will be computed as an average of the corresponding diagonal components, and the coupled box
dimensions will be changed together in lockstep, meaning coupled dimensions will be dilated or contracted by the
same percentage every timestep. The Pstart, Pstop, Pdamp parameters for any coupled dimensions must be identical.
Couple xyz can be used for a 2d simulation; the z dimension is simply ignored.

The iso and aniso keywords are simply shortcuts that are equivalent to specifying several other keywords together.
The keyword iso means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure),
and dilate/contract the dimensions together. Using “iso Pstart Pstop Pdamp” is the same as specifying these 4 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
couple xyz

The keyword aniso means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components
of the stress tensor as the driving forces, and the specified scalar external pressure. Using “aniso Pstart Pstop Pdamp”
is the same as specifying these 4 keywords:

x Pstart Pstop Pdamp

y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
couple none

This fix computes a temperature and pressure each timestep. To do this, the fix creates its own computes of style “temp”
and “pressure”, as if these commands had been issued:

compute fix-ID_temp group-ID temp

compute fix-ID_press group-ID pressure fix-ID_temp

See the compute temp and compute pressure commands for details. Note that the IDs of the new computes are the
fix-ID + underscore + “temp” or fix_ID + underscore + “press”, and the group for the new computes is the same as the
fix group.
Note that these are NOT the computes used by thermodynamic output (see the thermo_style command) with ID =
thermo_temp and thermo_press. This means you can change the attributes of this fix’s temperature or pressure via the
compute_modify command or print this temperature or pressure during thermodynamic output via the thermo_style
custom command using the appropriate compute-ID. It also means that changing attributes of thermo_temp or
thermo_press will have no effect on this fix.

1420 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.149.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify temp and press options are supported by this fix. You can use them to assign a compute you have
defined to this fix which will be used in its temperature and pressure calculations. If you do this, note that the kinetic
energy derived from the compute temperature should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute temperature on a subset of atoms.
No global or per-atom quantities are stored by this fix for access by various output commands.
This fix can ramp its target pressure over multiple runs, using the start and stop keywords of the run command. See
the run command for details of how to do this.
This fix is not invoked during energy minimization.

17.149.5 Restrictions

Any dimension being adjusted by this fix must be periodic.

17.149.6 Related commands

fix nve, fix nph, fix npt, fix temp/berendsen, fix_modify

17.149.7 Default

The keyword defaults are dilate = all, modulus = 10.0 in units of pressure for whatever units are defined.

(Berendsen) Berendsen, Postma, van Gunsteren, DiNola, Haak, J Chem Phys, 81, 3684 (1984).

17.150 fix print command

17.150.1 Syntax

fix ID group-ID print N string keyword value ...

• ID, group-ID are documented in fix command

• print = style name of this fix command
• N = print every N steps; N can be a variable (see below)
• string = text string to print with optional variable names
• zero or more keyword/value pairs may be appended
• keyword = file or append or screen or title
file value = filename
append value = filename
screen value = yes or no
title value = string
string = text to print as 1st line of output file

17.150. fix print command 1421

LAMMPS Documentation, Release stable 29Sep2021

17.150.2 Examples

fix extra all print 100 "Coords of marker atom = $x $y $z"

fix extra all print 100 "Coords of marker atom = $x $y $z" file coord.txt

17.150.3 Description

Print a text string every N steps during a simulation run. This can be used for diagnostic purposes or as a debugging
tool to monitor some quantity during a run. The text string must be a single argument, so it should be enclosed in
double quotes if it is more than one word. If it contains variables it must be enclosed in double quotes to insure they
are not evaluated when the input script line is read, but will instead be evaluated each time the string is printed.
Instead of a numeric value, N can be specified as an equal-style variable, which should be specified as v_name, where
name is the variable name. In this case, the variable is evaluated at the beginning of a run to determine the next
timestep at which the string will be written out. On that timestep, the variable will be evaluated again to determine the
next timestep, etc. Thus the variable should return timestep values. See the stagger() and logfreq() and stride() math
functions for equal-style variables, as examples of useful functions to use in this context. For example, the following
commands will print output at timesteps 10,20,30,100,200,300,1000,2000,etc:

variable s equal logfreq(10,3,10)

fix extra all print v_s "Coords of marker atom = $x $y $z"

The specified group-ID is ignored by this fix.

See the variable command for a description of equal style variables which are the most useful ones to use with the
fix print command, since they are evaluated afresh each timestep that the fix print line is output. Equal-style variables
calculate formulas involving mathematical operations, atom properties, group properties, thermodynamic properties,
global values calculated by a compute or fix, or references to other variables.
If the file or append keyword is used, a filename is specified to which the output generated by this fix will be written.
If file is used, then the filename is overwritten if it already exists. If append is used, then the filename is appended to
if it already exists, or created if it does not exist.
If the screen keyword is used, output by this fix to the screen and logfile can be turned on or off as desired.
The title keyword allow specification of the string that will be printed as the first line of the output file, assuming the
file keyword was used. By default, the title line is as follows:

# Fix print output for fix ID

where ID is replaced with the fix-ID.

17.150.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

1422 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.150.5 Restrictions

none

17.150.6 Related commands

variable, print

17.150.7 Default

The option defaults are no file output, screen = yes, and title string as described above.

17.151 fix propel/self command

17.151.1 Syntax

fix ID group-ID propel/self mode magnitude keyword values

• ID, group-ID are documented in fix command

• propel/self = style name of this fix command
• mode = dipole or velocity or quat
• magnitude = magnitude of self-propulsion force
• zero or one keyword/value pairs may be appended
• keyword = qvector
qvector value = direction of force in ellipsoid frame
sx, sy, sz = components of qvector

17.151.2 Examples

fix active all propel/self dipole 40.0

fix active all propel/self velocity 10.0
fix active all propel/self quat 15.7 qvector 1.0 0.0 0.0

17.151.3 Description

Add a force to each atom in the group due to a self-propulsion force. The force is given by

Fi = fP ei

where i is the particle the force is being applied to, fP is the magnitude of the force, and ei is the vector direction of
the force. The specification of ei is based on which of the three keywords (dipole or velocity or quat) one selects.
For mode dipole, ei is just equal to the dipole vectors of the atoms in the group. Therefore, if the dipoles are not unit
vectors, the ei will not be unit vectors.

17.151. fix propel/self command 1423

LAMMPS Documentation, Release stable 29Sep2021

Note: If another command changes the magnitude of the dipole, this force will change accordingly (since |ei | will
change, which is physically equivalent to re-scaling fP while keeping |ei | constant), and no warning will be provided
by LAMMPS. This is almost never what you want, so ensure you are not changing dipole magnitudes with another
LAMMPS fix or pair style. Furthermore, self-propulsion forces (almost) always set ei to be a unit vector for all times,
so it’s best to set all the dipole magnitudes to 1.0 unless you have a good reason not to (see the set command on how to
do this).

For mode velocity, ei points in the direction of the current velocity (a unit-vector). This can be interpreted as a velocity-
dependent friction, as proposed by e.g. (Erdmann).
For mode quat, ei points in the direction of a unit vector, oriented in the coordinate frame of the ellipsoidal particles,
which defaults to point along the x-direction. This default behavior can be changed by via the quatvec keyword.
The optional quatvec keyword specifies the direction of self-propulsion via a unit vector (sx,sy,sz). The arguments sx,
sy, and sz, are defined within the coordinate frame of the atom’s ellipsoid. For instance, for an ellipsoid with long axis
along its x-direction, if one wanted the self-propulsion force to also be along this axis, set sx equal to 1 and sy, sz both
equal to zero. This keyword may only be specified for mode quat.

Note: In using keyword quatvec, the three arguments sx, sy, and sz will be automatically normalized to components
of a unit vector internally to avoid users having to explicitly do so themselves. Therefore, in mode quat, the vectors ei
will always be of unit length.

Along
P with adding a force contribution, this fix can also contribute to the virial (pressure) of the system, defined as
fP i < ei .ri > /(dV ), where ri is the unwrapped coordinate of particle i in the case of periodic boundary conditions.
See (Winkler) for a discussion of this active pressure contribution.
For modes dipole and quat, this fix is by default included in pressure computations.
For mode velocity, this fix is by default not included in pressure computations.

Note: In contrast to equilibrium systems, pressure of active systems in general depends on the geometry of the con-
tainer. The active pressure contribution as calculated in this fix is only valid for certain boundary conditions (spherical
walls, rectangular walls, or periodic boundary conditions). For other geometries, the pressure must be measured via
explicit calculation of the force per unit area on a wall, and so one must not calculate it using this fix. (Use fix_modify
as described below to turn off the virial contribution of this fix). Again, see (Winkler) for discussion of why this is the
case.
Furthermore, when dealing with active systems, the temperature is no longer well defined. Therefore, one should ensure
that the virial flag is used in the compute pressure command (turning off temperature contributions).

17.151.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify virial option is supported by this fix to add the contribution due to the added forces on atoms to the
system’s virial as part of thermodynamic output. The default is virial yes for keywords dipole and quat. The default is
virial no for keyword velocity.
No parameter of this fix can be used with the start/stop keywords of the run command.

1424 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.151.5 Restrictions

With keyword dipole, this fix only works when the DIPOLE package is enabled. See the Build package page for more
info.
This fix is part of the BROWNIAN package. It is only enabled if LAMMPS was built with that package. See the Build
package doc page for more info.

17.151.6 Related commands

fix efield , fix setforce, fix addforce

17.151.7 Default

none

(Erdmann) U. Erdmann , W. Ebeling, L. Schimansky-Geier, and F. Schweitzer, Eur. Phys. J. B 15, 105-113, 2000.
(Winkler) Winkler, Wysocki, and Gompper, Soft Matter, 11, 6680 (2015).

17.152 fix property/atom command

Accelerator Variants: property/atom/kk

17.152.1 Syntax

fix ID group-ID property/atom name1 name2 ... keyword value ...

• ID, group-ID are documented in fix command

• property/atom = style name of this fix command
• name1,name2,. . . = mol or q or rmass or i_name or d_name or i2_name or d2_name
mol = molecule IDs
q = charge
rmass = per-atom mass
i_name = new integer vector referenced by name
d_name = new floating-point vector referenced by name
i2_name = new integer array referenced by name
i2_name arg = N = number of columns in the array
d2_name = new floating-point array referenced by name
d2_name arg = N = number of columns in the array
• zero of more keyword/value pairs may be appended
• keyword = ghost
ghost value = no or yes for whether ghost atom info in communicated

17.152. fix property/atom command 1425

LAMMPS Documentation, Release stable 29Sep2021

17.152.2 Examples

fix 1 all property/atom mol

fix 1 all property/atom i_myflag1 i_myflag2
fix 1 all property/atom d2_sxyz 3 ghost yes

17.152.3 Description

Create one or more additional per-atom vectors or arrays to store information about atoms and to use during a simulation.
The specified group-ID is ignored by this fix.
The atom style used for a simulation defines a set of per-atom properties, as explained on the atom_style and read_data
doc pages. The latter command defines these properties for each atom in the system when a data file is read. This fix
augments the set of per-atom properties with new custom ones. This can be useful in several scenarios.
If the atom style does not define molecule IDs, per-atom charge, or per-atom mass, they can be added using the mol, q
or rmass keywords. This could be useful to define “molecules” to use as rigid bodies with the fix rigid command, or
to carry around an extra flag with atoms (stored as a molecule ID) that can be used by various commands like compute
chunk/atom to group atoms without having to use the group command (which is limited to a total of 32 groups including
all).
Another application is to use the rmass flag in order to have per-atom masses instead of per-type masses. This could
be used to study isotope effects with partial isotope substitution. See below for an example of simulating a mixture of
light and heavy water with the TIP4P water potential.
An alternative to using fix property/atom for these examples is to use an atom style that does define molecule IDs
or charge or per-atom mass (indirectly via diameter and density) or to use a hybrid atom style that combines two or
more atom styles to provide the union of all their atom properties. However, this has two practical drawbacks: first,
it typically necessitates changing the format of the Atoms section in the data file and second, it may define additional
properties that are not needed such as bond lists, which incurs some overhead when there are no bonds.
In the future, we may add additional existing per-atom properties to fix property/atom, similar to mol, q or rmass, which
“turn-on” specific properties defined by some atom styles, so they can be easily used by atom styles that do not define
them.
More generally, the i_name and d_name options allow one or more new custom per-atom vectors to be defined. Likewise
the i2_name and d2_name options allow one or more custom per-atom arrays to be defined. The i2_name and d2_name
options take an argument N which specifies the number of columns in the per-atom array, i.e. the number of attributes
associated with each atom. N >= 1 is required.
Each name must be unique and can use alphanumeric or underscore characters. These vectors and arrays can store
whatever values you decide are useful in your simulation. As explained below there are several ways to initialize,
access, and output these values, via input script commands, data files, and in new code you add to LAMMPS.
This is effectively a simple way to add per-atom properties to a model without needing to write code for a new atom
style that defines the properties. Note however that implementing a new atom style allows new atom properties to be
more tightly and seamlessly integrated with the rest of the code.
The new atom properties encode values that migrate with atoms to new processors and are written to restart files. If
you want the new properties to also be defined for ghost atoms, then use the ghost keyword with a value of yes. This
will invoke extra communication when ghost atoms are created (at every re-neighboring) to insure the new properties
are also defined for the ghost atoms.

Properties on ghost atoms

If you use the mol, q or rmass names, you most likely want to set ghost yes, since these properties are stored with ghost
atoms if you use an atom_style that defines them. Many LAMMPS operations that use molecule IDs or charge, such

1426 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

as neighbor lists and pair styles, will expect ghost atoms to have these values. LAMMPS will issue a warning it you
define those vectors but do not set ghost yes.

Limitations on ghost atom properties

The specified properties for ghost atoms are not updated every timestep, but only once every few steps when neighbor
lists are re-built. Thus the ghost keyword is suitable for static properties, like molecule IDs, but not for dynamic
properties that change every step. For the latter, the code you add to LAMMPS to change the properties will also need
to communicate their new values to/from ghost atoms, an operation that can be invoked from within a pair style or fix
or compute that you write.

This fix is one of a small number that can be defined in an input script before the simulation box is created or atoms
are defined. This is so it can be used with the read_data command as described next.
Per-atom properties that are defined by the atom style are initialized when atoms are created, e.g. by the read_data or
create_atoms commands. The per-atom properties defined by this fix are not. So you need to initialize them explicitly.
One way to do this is read_data command, using its fix keyword and passing it the fix-ID of this fix.
Thus these commands:

fix prop all property/atom mol d_flag

read_data data.txt fix prop NULL Molecules

would allow a data file to have a section like this:

Molecules

1 4 1.5
2 4 3.0
3 10 1.0
4 10 1.0
5 10 1.0
...
N 763 4.5

where N is the number of atoms, the first field on each line is the atom-ID, the next two are a molecule-ID and a floating
point value that will be stored in a new property called “flag”. If a per-atom array was specified in the fix property/atom
command then the N values for that array must be specified consecutively for that property on each line. Note that the
order of values on each line corresponds to the order of custom names in the fix property/atom command.
Note that the the lines of per-atom properties can be listed in any order. Also note that all the per-atom properties
specified by the fix ID (prop in this case) must be included on each line in the specified data file section (Molecules in
this case).
Another way of initializing the new properties is via the set command. For example, if you wanted molecules defined
for every set of 10 atoms, based on their atom-IDs, these commands could be used:

fix prop all property/atom mol

variable cluster atom ((id-1)/10)+1
set atom * mol v_cluster

The atom-style variable will create values for atoms with IDs 31,32,33,. . . 40 that are 4.0,4.1,4.2,. . . ,4.9. When the set
commands assigns them to the molecule ID for each atom, they will be truncated to an integer value, so atoms 31-40
will all be assigned a molecule ID of 4.

17.152. fix property/atom command 1427

LAMMPS Documentation, Release stable 29Sep2021

Note that atomfile-style variables can also be used in place of atom-style variables, which means in this case that the
molecule IDs could be read-in from a separate file and assigned by the set command. This allows you to initialize new
per-atom properties in a completely general fashion.

For new atom properties specified as i_name, d_name, i2_name, or d2_name, the dump custom and compute prop-
erty/atom commands can access their values. This means that the values can be used accessed by fixes like fix ave/atom,
accessed by other computes like compute reduce, or used in atom-style variables.
For example, these commands will output both the instantaneous and time-averaged values of two new properties to a
custom dump file:

fix myprops all property/atom i_flag1 d_flag2

compute 1 all property/atom i_flag1 d_flag2
fix 1 all ave/atom 10 10 100 c_1[1] c_1[2]
dump 1 all custom 100 tmp.dump id x y z i_flag1 d_flag2 f_1[1] f_1[2]

If you wish to add new pair styles, fixes, or computes that use the per-atom properties defined by this fix, see the Modify
atom doc page which has details on how the custom properties of this fix can be accessed from added classes.

Here is an example of using per-atom masses with TIP4P water to study isotope effects. When setting up simulations
with the TIP4P pair styles for water, you have to provide exactly one atom type each to identify the water oxygen and
hydrogen atoms. Since the atom mass is normally tied to the atom type, this makes it impossible to study multiple
isotopes in the same simulation. With fix property/atom rmass however, the per-type masses are replaced by per-atom
masses. Asumming you have a working input deck for regular TIP4P water, where water oxygen is atom type 1 and
water hydrogen is atom type 2, the following lines of input script convert this to using per-atom masses:

fix Isotopes all property/atom rmass ghost yes

set type 1 mass 15.9994
set type 2 mass 1.008

When writing out the system data with the write_data command, there will be a new section named with the fix-ID
(i.e. Isotopes in this case). Alternatively, you can take an existing data file and just add this Isotopes section with one
line per atom containing atom-ID and mass. Either way, the extended data file can be read back with:

fix Isotopes all property/atom rmass ghost yes

read_data tip4p-isotopes.data fix Isotopes NULL Isotopes

Please note that the first Isotopes refers to the fix-ID and the second to the name of the section. The following input
script code will now change the first 100 water molecules in this example to heavy water:

group hwat id 2:300:3

group hwat id 3:300:3
set group hwat mass 2.0141018

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.

1428 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.152.4 Restart, fix_modify, output, run start/stop, minimize info

This fix writes the per-atom values it stores to binary restart files, so that the values can be restored when a simulation
is restarted. See the read_restart command for info on how to re-specify a fix in an input script that reads a restart file,
so that the operation of the fix continues in an uninterrupted fashion.

Warning: When reading data from a restart file, this fix command has to be specified exactly the same was in the
input script that created the restart file. LAMMPS will only check whether a fix is of the same style and has the
same fix ID and in case of a match will then try to initialize the fix with the data stored in the binary restart file. If
the names and associated date types in the new fix property/atom command do not match the old one exactly, data
can be corrupted or LAMMPS may crash.

None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access
by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

17.152.5 Restrictions

none

17.152.6 Related commands

read_data, set, compute property/atom

17.152.7 Default

The default keyword value is ghost = no.

17.153 fix python/invoke command

17.153.1 Syntax

fix ID group-ID python/invoke N callback function_name

• ID, group-ID are ignored by this fix

• python/invoke = style name of this fix command
• N = execute every N steps
• callback = post_force or end_of_step

17.153. fix python/invoke command 1429

LAMMPS Documentation, Release stable 29Sep2021

post_force = callback after force computations on atoms every N time steps

end_of_step = callback after every N time steps

17.153.2 Examples

python post_force_callback here """

from lammps import lammps

def post_force_callback(lammps_ptr, vflag):

lmp = lammps(ptr=lammps_ptr)
# access LAMMPS state using Python interface
"""

python end_of_step_callback here """

def end_of_step_callback(lammps_ptr):
lmp = lammps(ptr=lammps_ptr)
# access LAMMPS state using Python interface
"""

fix pf all python/invoke 50 post_force post_force_callback

fix eos all python/invoke 50 end_of_step end_of_step_callback

17.153.3 Description

This fix allows you to call a Python function during a simulation run. The callback is either executed after forces have
been applied to atoms or at the end of every N time steps.
Callback functions must be declared in the global scope of the active Python interpreter. This can either be done by
defining it inline using the python command or by importing functions from other Python modules. If LAMMPS is
driven using the library interface from Python, functions defined in the driving Python interpreter can also be executed.
Each callback is given a pointer object as first argument. This can be used to initialize an instance of the lammps Python
interface, which gives access to the LAMMPS state from Python.

Warning: While you can access the state of LAMMPS via library functions from these callbacks, trying to execute
input script commands will in the best case not work or in the worst case result in undefined behavior.

17.153.4 Restrictions

This fix is part of the PYTHON package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
Building LAMMPS with the PYTHON package will link LAMMPS with the Python library on your system. Settings
to enable this are in the lib/python/Makefile.lammps file. See the lib/python/README file for information on those
settings.

1430 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.153.5 Related commands

python command

17.154 fix python/move command

17.154.1 Syntax

fix python/move pymodule.CLASS

pymodule.CLASS = use class CLASS in module/file pymodule to compute how to move atoms

17.154.2 Examples

fix 1 all python/move py_nve.NVE

fix 1 all python/move py_nve.NVE_OPT

17.154.3 Description

The python/move fix style provides a way to define ways how particles are moved during an MD run from python script
code, that is loaded from a file into LAMMPS and executed at the various steps where other fixes can be executed. This
python script must contain specific python class definitions.
This allows to implement complex position updates and also modified time integration methods. Due to python be-
ing an interpreted language, however, the performance of this fix can be moderately to significantly slower than the
corresponding C++ code. For specific cases, this performance penalty can be limited through effective use of NumPy.

The python module file has to start with the following code:

from __future__ import print_function

import lammps
import ctypes
import traceback
import numpy as np
#
class LAMMPSFix(object):
def __init__(self, ptr, group_name="all"):
self.lmp = lammps.lammps(ptr=ptr)
self.group_name = group_name
#
class LAMMPSFixMove(LAMMPSFix):
def __init__(self, ptr, group_name="all"):
super(LAMMPSFixMove, self).__init__(ptr, group_name)
#
def init(self):
pass
#
def initial_integrate(self, vflag):
(continues on next page)

17.154. fix python/move command 1431

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

pass
#
def final_integrate(self):
pass
#
def initial_integrate_respa(self, vflag, ilevel, iloop):
pass
#
def final_integrate_respa(self, ilevel, iloop):
pass
#
def reset_dt(self):
pass

Any classes implementing new atom motion functionality have to be derived from the LAMMPSFixMove class, over-
riding the available methods as needed.
Examples for how to do this are in the examples/python folder.

17.154.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

17.154.5 Restrictions

This pair style is part of the PYTHON package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.

17.154.6 Related commands

fix nve, fix python/invoke

17.154.7 Default

none

17.155 fix qbmsst command

17.155.1 Syntax

fix ID group-ID qbmsst dir shockvel keyword value ...

• ID, group-ID are documented in fix command

1432 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• qbmsst = style name of this fix

• dir = x or y or z
• shockvel = shock velocity (strictly positive, velocity units)
• zero or more keyword/value pairs may be appended
• keyword = q or mu or p0 or v0 or e0 or tscale or damp or seed or f_max or N_f or eta or beta or T_init
q value = cell mass-like parameter (mass^2/distance^4 units)
mu value = artificial viscosity (mass/distance/time units)
p0 value = initial pressure in the shock equations (pressure units)
v0 value = initial simulation cell volume in the shock equations (distance^3 units)
e0 value = initial total energy (energy units)
tscale value = reduction in initial temperature (unitless fraction between 0.0 and␣
,→1.0)

damp value = damping parameter (time units) inverse of friction gamma

seed value = random number seed (positive integer)
f_max value = upper cutoff frequency of the vibration spectrum (1/time units)
N_f value = number of frequency bins (positive integer)
eta value = coupling constant between the shock system and the quantum thermal bath␣
,→(positive unitless)

beta value = the quantum temperature is updated every beta time steps (positive␣
,→integer)

T_init value = quantum temperature for the initial state (temperature units)

17.155.2 Examples

# (liquid methane modeled with the REAX force field, real units)
fix 1 all qbmsst z 0.122 q 25 mu 0.9 tscale 0.01 damp 200 seed 35082 f_max 0.3 N_f 100␣
,→eta 1 beta 400 T_init 110

# (quartz modeled with the BKS force field, metal units)

fix 2 all qbmsst z 72 q 40 tscale 0.05 damp 1 seed 47508 f_max 120.0 N_f 100 eta 1.0␣
,→beta 500 T_init 300

Two example input scripts are given, including shocked α-quartz and shocked liquid methane. The input script first
equilibrates an initial state with the quantum thermal bath at the target temperature and then applies fix qbmsst to
simulate shock compression with quantum nuclear correction. The following two figures plot relevant quantities for
shocked α-quartz.

P mi vi2
Figure 1. Classical temperature Tcl = 3N kB vs. time for coupling the α-quartz initial state with the quantum
thermal bath at target quantum temperature T qm = 300K. The NpH ensemble is used for time integration while QTB
provides the colored random force. T cl converges at the timescale of damp which is set to be 1 ps.

17.155. fix qbmsst command 1433

LAMMPS Documentation, Release stable 29Sep2021

Figure 2. Quantum temperature and pressure vs. time for simulating shocked α-quartz with fix qbmsst. The shock
propagates along the z direction. Restart of the fix qbmsst command is demonstrated in the example input script.
Thermodynamic quantities stay continuous before and after the restart.

17.155.3 Description

This command performs the Quantum-Bath coupled Multi-Scale Shock Technique (QBMSST) integration. See (Qi)
for a detailed description of this method. QBMSST provides description of the thermodynamics and kinetics of shock
processes while incorporating quantum nuclear effects. The shockvel setting determines the steady shock velocity that
will be simulated along direction dir.
Quantum nuclear effects (fix qtb) can be crucial especially when the temperature of the initial state is below the classical
limit or there is a great change in the zero point energies between the initial and final states. Theoretical post processing
quantum corrections of shock compressed water and methane have been reported as much as 30% of the temperatures
(Goldman). A self-consistent method that couples the shock to a quantum thermal bath described by a colored noise
Langevin thermostat has been developed by Qi et al (Qi) and applied to shocked methane. The onset of chemistry is
reported to be at a pressure on the shock Hugoniot that is 40% lower than observed with classical molecular dynamics.
It is highly recommended that the system be already in an equilibrium state with a quantum thermal bath at temperature
of T_init. The fix command fix qtb at constant temperature T_init could be used before applying this command to
introduce self-consistent quantum nuclear effects into the initial state.
The parameters q, mu, e0, p0, v0 and tscale are described in the command fix msst. The values of e0, p0, or v0 will be
calculated on the first step if not specified. The parameter of damp, f_max, and N_f are described in the command fix
qtb.
The fix qbmsst command couples the shock system to a quantum thermal bath with a rate that is proportional to the
change of the total energy of the shock system, E tot − E0tot . Here E etot consists of both the system energy and a
thermal term, see (Qi), and E0tot = e0 is the initial total energy.
The eta (η) parameter is a unitless coupling constant between the shock system and the quantum thermal bath. A
small η value cannot adjust the quantum temperature fast enough during the temperature ramping period of shock
compression while large η leads to big temperature oscillation. A value of η between 0.3 and 1 is usually appropriate
for simulating most systems under shock compression. We observe that different values of η lead to almost the same
final thermodynamic state behind the shock, as expected.
The quantum temperature is updated every beta (β) steps with an integration time interval β times longer than the
simulation time step. In that case, E tot is taken as its average over the past β steps. The temperature of the quantum

1434 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

thermal bath T qm changes dynamically according to the following equation where ∆t is the MD time step and γ is the
friction constant which is equal to the inverse of the damp parameter.
β
dT qm X E tot (t − l∆t) − E tot
0
= γη
dt 3βN kB
l=1

The parameter T_init is the initial temperature of the quantum thermal bath and the system before shock loading.
For all pressure styles, the simulation box stays orthorhombic in shape. Parrinello-Rahman boundary conditions (tilted
box) are supported by LAMMPS, but are not implemented for QBMSST.

17.155.4 Restart, fix_modify, output, run start/stop, minimize info

Because the state of the random number generator is not written to binary restart files, this fix cannot be restarted
“exactly” in an uninterrupted fashion. However, in a statistical sense, a restarted simulation should produce similar
behaviors of the system as if it is not interrupted. To achieve such a restart, one should write explicitly the same value
for q, mu, damp, f_max, N_f, eta, and beta and set tscale = 0 if the system is compressed during the first run.
The cumulative energy change in the system imposed by this fix is included in the thermodynamic output keywords
ecouple and econserve. See the thermo_style doc page for details.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the same cumulative
energy change due to this fix described in the previous paragraph. The scalar value calculated by this fix is “extensive”.
The progress of the QBMSST can be monitored by printing the global scalar and global vector quantities computed by
the fix.
As mentioned above, the scalar is the cumulative energy change due to the fix. By monitoring the thermodynamic
econserve output, this can be used to test if the MD timestep is sufficiently small for accurate integration of the dynamic
equations.
The global vector contains five values in the following order. The vector values output by this fix are “intensive”.
[dhugoniot, drayleigh, lagrangian_speed, lagrangian_position, quantum_temperature]
1. dhugoniot is the departure from the Hugoniot (temperature units).
2. drayleigh is the departure from the Rayleigh line (pressure units).
3. lagrangian_speed is the laboratory-frame Lagrangian speed (particle velocity) of the computational cell (velocity
units).
4. lagrangian_position is the computational cell position in the reference frame moving at the shock speed. This is
the distance of the computational cell behind the shock front.
5. quantum_temperature is the temperature of the quantum thermal bath T qm .
To print these quantities to the log file with descriptive column headers, the following LAMMPS commands are sug-
gested.

fix fix_id all msst z

variable dhug equal f_fix_id[1]
variable dray equal f_fix_id[2]
variable lgr_vel equal f_fix_id[3]
variable lgr_pos equal f_fix_id[4]
variable T_qm equal f_fix_id[5]
thermo_style custom step temp ke pe lz pzz econserve v_dhug v_dray v_lgr_vel v_lgr_
,→pos v_T_qm f_fix_id

17.155. fix qbmsst command 1435

LAMMPS Documentation, Release stable 29Sep2021

It is worth noting that the temp keyword for the thermo_style command prints the instantaneous classical temperature
T cl as described by the fix qtb command.

17.155.5 Restrictions

This fix style is part of the QTB package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
All cell dimensions must be periodic. This fix can not be used with a triclinic cell. The QBMSST fix has been tested
only for the group-ID all.

17.155.6 Related commands

fix qtb, fix msst

17.155.7 Default

The keyword defaults are q = 10, mu = 0, tscale = 0.01, damp = 1, seed = 880302, f_max = 200.0, N_f = 100, eta = 1.0,
beta = 100, and T_init=300.0. e0, p0, and v0 are calculated on the first step.

(Goldman) Goldman, Reed and Fried, J. Chem. Phys. 131, 204103 (2009)
(Qi) Qi and Reed, J. Phys. Chem. A 116, 10451 (2012).

17.156 fix qeq/point command

17.157 fix qeq/shielded command

17.158 fix qeq/slater command

17.159 fix qeq/dynamic command

17.160 fix qeq/fire command

17.160.1 Syntax

fix ID group-ID style Nevery cutoff tolerance maxiter qfile keyword ...

• ID, group-ID are documented in fix command

• style = qeq/point or qeq/shielded or qeq/slater or qeq/dynamic or qeq/fire

1436 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• Nevery = perform charge equilibration every this many steps

• cutoff = global cutoff for charge-charge interactions (distance unit)
• tolerance = precision to which charges will be equilibrated
• maxiter = maximum iterations to perform charge equilibration
• qfile = a filename with QEq parameters or coul/streitz or reaxff
• zero or more keyword/value pairs may be appended
• keyword = alpha or qdamp or qstep or warn
alpha value = Slater type orbital exponent (qeq/slater only)
qdamp value = damping factor for damped dynamics charge solver (qeq/dynamic and qeq/
,→fire only)

qstep value = time step size for damped dynamics charge solver (qeq/dynamic and qeq/
,→fire only)

warn value = do (=yes) or do not (=no) print a warning when the maximum number of␣
,→iterations is reached

17.160.2 Examples

fix 1 all qeq/point 1 10 1.0e-6 200 param.qeq1

fix 1 qeq qeq/shielded 1 8 1.0e-6 100 param.qeq2
fix 1 all qeq/slater 5 10 1.0e-6 100 params alpha 0.2
fix 1 qeq qeq/dynamic 1 12 1.0e-3 100 my_qeq
fix 1 all qeq/fire 1 10 1.0e-3 100 my_qeq qdamp 0.2 qstep 0.1

17.160.3 Description

Perform the charge equilibration (QEq) method as described in (Rappe and Goddard) and formulated in (Nakano) (also
known as the matrix inversion method) and in (Rick and Stuart) (also known as the extended Lagrangian method) based
on the electronegativity equilization principle.
These fixes can be used with any pair style in LAMMPS, so long as per-atom charges are defined. The most typical
use-case is in conjunction with a pair style that performs charge equilibration periodically (e.g. every timestep), such
as the ReaxFF or Streitz-Mintmire potential. But these fixes can also be used with potentials that normally assume
per-atom charges are fixed, e.g. a Buckingham or LJ/Coulombic potential.
Because the charge equilibration calculation is effectively independent of the pair style, these fixes can also be used to
perform a one-time assignment of charges to atoms. For example, you could define the QEq fix, perform a zero-timestep
run via the run command without any pair style defined which would set per-atom charges (based on the current atom
configuration), then remove the fix via the unfix command before performing further dynamics.

Note: Computing and using charge values different from published values defined for a fixed-charge potential like
Buckingham or CHARMM or AMBER, can have a strong effect on energies and forces, and produces a different model
than the published versions.

Note: The fix qeq/comb command must still be used to perform charge equilibration with the COMB potential. The fix
qeq/reaxff command can be used to perform charge equilibration with the ReaxFF force field, although fix qeq/shielded

17.160. fix qeq/fire command 1437

LAMMPS Documentation, Release stable 29Sep2021

yields the same results as fix qeq/reaxff if Nevery, cutoff, and tolerance are the same. Eventually the fix qeq/reaxff
command will be deprecated.

The QEq method minimizes the electrostatic energy of the system (or equalizes the derivative of energy with respect to
charge of all the atoms) by adjusting the partial charge on individual atoms based on interactions with their neighbors
within cutoff. It requires a few parameters in the appropriate units for each atom type which are read from a file specified
by qfile. The file has the following format

1 chi eta gamma zeta qcore

2 chi eta gamma zeta qcore
...
Ntype chi eta gamma zeta qcore

There have to be parameters given for every atom type. Wildcard entries are possible using the same type range syntax
as for “coeff” commands (i.e., n*m, n*, *m, *). Later entries will overwrite previous ones. Empty lines or any text
following the pound sign (#) are ignored. Each line starts with the atom type followed by five parameters. Only a subset
of the parameters is used by each QEq style as described below, thus the others can be set to 0.0 if desired, but all five
entries per line are required.
• chi = electronegativity in energy units
• eta = self-Coulomb potential in energy units
• gamma = shielded Coulomb constant defined by ReaxFF force field in distance units
• zeta = Slater type orbital exponent defined by the Streitz-Mintmire potential in reverse distance units
• qcore = charge of the nucleus defined by the Streitz-Mintmire potential potential in charge units
The fix qeq styles will print a warning if the charges are not equilibrated within tolerance by maxiter steps, unless the
warn keyword is used with “no” as argument. This latter option may be useful for testing and benchmarking purposes,
as it allows to use a fixed number of QEq iterations when tolerance is set to a small enough value to always reach the
maxiter limit. Turning off warnings will avoid the excessive output in that case.
The qeq/point style describes partial charges on atoms as point charges. Interaction between a pair of charged particles
is 1/r, which is the simplest description of the interaction between charges. Only the chi and eta parameters from the
qfile file are used. Note that Coulomb catastrophe can occur if repulsion between the pair of charged particles is too
weak. This style solves partial charges on atoms via the matrix inversion method. A tolerance of 1.0e-6 is usually a
good number.
The qeq/shielded style describes partial charges on atoms also as point charges, but uses a shielded Coulomb potential
to describe the interaction between a pair of charged particles. Interaction through the shielded Coulomb is given by
equation (13) of the ReaxFF force field paper. The shielding accounts for charge overlap between charged particles at
small separation. This style is the same as fix qeq/reaxff , and can be used with pair_style reaxff . Only the chi, eta, and
gamma parameters from the qfile file are used. When using the string reaxff as filename, these parameters are extracted
directly from an active reaxff pair style. This style solves partial charges on atoms via the matrix inversion method. A
tolerance of 1.0e-6 is usually a good number.
The qeq/slater style describes partial charges on atoms as spherical charge densities centered around atoms via the
Slater 1s orbital, so that the interaction between a pair of charged particles is the product of two Slater 1s orbitals.
The expression for the Slater 1s orbital is given under equation (6) of the Streitz-Mintmire paper. Only the chi, eta,
zeta, and qcore parameters from the qfile file are used. When using the string coul/streitz as filename, these parameters
are extracted directly from an active coul/streitz pair style. This style solves partial charges on atoms via the matrix
inversion method. A tolerance of 1.0e-6 is usually a good number. Keyword alpha can be used to change the Slater
type orbital exponent.
The qeq/dynamic style describes partial charges on atoms as point charges that interact through 1/r, but the extended
Lagrangian method is used to solve partial charges on atoms. Only the chi and eta parameters from the qfile file are used.
Note that Coulomb catastrophe can occur if repulsion between the pair of charged particles is too weak. A tolerance of

1438 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

1.0e-3 is usually a good number. Keyword qdamp can be used to change the damping factor, while keyword qstep can
be used to change the time step size.
The *qeq/fire* style describes the same charge model and charge solver as the qeq/dynamic style, but employs a FIRE
minimization algorithm to solve for equilibrium charges. Keyword qdamp can be used to change the damping factor,
while keyword qstep can be used to change the time step size.
Note that qeq/point, qeq/shielded, and qeq/slater describe different charge models, whereas the matrix inversion method
and the extended Lagrangian method (qeq/dynamic and qeq/fire) are different solvers.
Note that qeq/point, qeq/dynamic and qeq/fire styles all describe charges as point charges that interact through 1/r rela-
tionship, but solve partial charges on atoms using different solvers. These three styles should yield comparable results
if the QEq parameters and Nevery, cutoff, and tolerance are the same. Style qeq/point is typically faster, qeq/dynamic
scales better on larger sizes, and qeq/fire is faster than qeq/dynamic.

Note: To avoid the evaluation of the derivative of charge with respect to position, which is typically ill-defined, the
system should have a zero net charge.

Note: Developing QEq parameters (chi, eta, gamma, zeta, and qcore) is non-trivial. Charges on atoms are not guar-
anteed to equilibrate with arbitrary choices of these parameters. We do not develop these QEq parameters. See the
examples/qeq directory for some examples.

17.160.4 Restart, fix_modify, output, run start/stop, minimize info

No information about these fixes is written to binary restart files. No global scalar or vector or per-atom quantities are
stored by these fixes for access by various output commands. No parameter of these fixes can be used with the start/stop
keywords of the run command.
Thexe fixes are invoked during energy minimization.

17.160.5 Restrictions

These fixes are part of the QEQ package. They are only enabled if LAMMPS was built with that package. See the
Build package page for more info.
The qeq fixes are not compatible with the GPU and USER-INTEL packages.

17.160.6 Related commands

fix qeq/reaxff , fix qeq/comb

17.160. fix qeq/fire command 1439

LAMMPS Documentation, Release stable 29Sep2021

17.160.7 Default

warn yes

(Rappe and Goddard) A. K. Rappe and W. A. Goddard III, J Physical Chemistry, 95, 3358-3363 (1991).
(Nakano) A. Nakano, Computer Physics Communications, 104, 59-69 (1997).
(Rick and Stuart) S. W. Rick, S. J. Stuart, B. J. Berne, J Chemical Physics 101, 16141 (1994).
(Streitz-Mintmire) F. H. Streitz, J. W. Mintmire, Physical Review B, 50, 16, 11996 (1994)
(ReaxFF) A. C. T. van Duin, S. Dasgupta, F. Lorant, W. A. Goddard III, J Physical Chemistry, 105, 9396-9049 (2001)
(QEq/Fire) T.-R. Shan, A. P. Thompson, S. J. Plimpton, in preparation

17.161 fix qeq/comb command

Accelerator Variants: qeq/comb/omp

17.161.1 Syntax

fix ID group-ID qeq/comb Nevery precision keyword value ...

• ID, group-ID are documented in fix command

• qeq/comb = style name of this fix command
• Nevery = perform charge equilibration every this many steps
• precision = convergence criterion for charge equilibration
• zero or more keyword/value pairs may be appended
• keyword = file
file value = filename
filename = name of file to write QEQ equilibration info to

17.161.2 Examples

fix 1 surface qeq/comb 10 0.0001

17.161.3 Description

Perform charge equilibration (QeQ) in conjunction with the COMB (Charge-Optimized Many-Body) potential as de-
scribed in (COMB_1) and (COMB_2). It performs the charge equilibration portion of the calculation using the so-called
QEq method, whereby the charge on each atom is adjusted to minimize the energy of the system. This fix can only
be used with the COMB potential; see the fix qeq/reaxff command for a QeQ calculation that can be used with any
potential.
Only charges on the atoms in the specified group are equilibrated. The fix relies on the pair style (COMB in this case) to
calculate the per-atom electronegativity (effective force on the charges). An electronegativity equalization calculation

1440 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

(or QEq) is performed in an iterative fashion, which in parallel requires communication at each iteration for processors
to exchange charge information about nearby atoms with each other. See Rappe_and_Goddard and Rick_and_Stuart
for details.
During a run, charge equilibration is performed every Nevery time steps. Charge equilibration is also always enforced
on the first step of each run. The precision argument controls the tolerance for the difference in electronegativity for all
atoms during charge equilibration. Precision is a trade-off between the cost of performing charge equilibration (more
iterations) and accuracy.
If the file keyword is used, then information about each equilibration calculation is written to the specified file.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.161.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is performing charge equilibration. Default is the outermost level.
This fix produces a per-atom vector which can be accessed by various output commands. The vector stores the gradient
of the charge on each atom. The per-atom values be accessed on any timestep.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix can be invoked during energy minimization.

17.161.5 Restrictions

This fix command currently only supports pair style *comb*.

17.161.6 Related commands

pair_style comb

17.161. fix qeq/comb command 1441

LAMMPS Documentation, Release stable 29Sep2021

17.161.7 Default

No file output is performed.

(COMB_1) J. Yu, S. B. Sinnott, S. R. Phillpot, Phys Rev B, 75, 085311 (2007),

(COMB_2) T.-R. Shan, B. D. Devine, T. W. Kemper, S. B. Sinnott, S. R. Phillpot, Phys Rev B, 81, 125328 (2010).
(Rappe_and_Goddard) A. K. Rappe, W. A. Goddard, J Phys Chem 95, 3358 (1991).
(Rick_and_Stuart) S. W. Rick, S. J. Stuart, B. J. Berne, J Chem Phys 101, 16141 (1994).

17.162 fix qeq/reaxff command

Accelerator Variants: qeq/reaxff/kk, qeq/reaxff/omp

17.162.1 Syntax

fix ID group-ID qeq/reaxff Nevery cutlo cuthi tolerance params args

• ID, group-ID are documented in fix command

• qeq/reaxff = style name of this fix command
• Nevery = perform QEq every this many steps
• cutlo,cuthi = lo and hi cutoff for Taper radius
• tolerance = precision to which charges will be equilibrated
• params = reaxff or a filename
• one or more keywords or keyword/value pairs may be appended
keyword = dual or maxiter or nowarn
dual = process S and T matrix in parallel (only for qeq/reaxff/omp)
maxiter N = limit the number of iterations to N
nowarn = do not print a warning message if the maximum number of iterations was␣
,→reached

17.162.2 Examples

fix 1 all qeq/reaxff 1 0.0 10.0 1.0e-6 reaxff

fix 1 all qeq/reaxff 1 0.0 10.0 1.0e-6 param.qeq maxiter 500

1442 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.162.3 Description

Perform the charge equilibration (QEq) method as described in (Rappe and Goddard) and formulated in (Nakano). It is
typically used in conjunction with the ReaxFF force field model as implemented in the pair_style reaxff command, but
it can be used with any potential in LAMMPS, so long as it defines and uses charges on each atom. The fix qeq/comb
command should be used to perform charge equilibration with the COMB potential. For more technical details about
the charge equilibration performed by fix qeq/reaxff, see the (Aktulga) paper.
The QEq method minimizes the electrostatic energy of the system by adjusting the partial charge on individual atoms
based on interactions with their neighbors. It requires some parameters for each atom type. If the params setting above
is the word “reaxff”, then these are extracted from the pair_style reaxff command and the ReaxFF force field file it
reads in. If a file name is specified for params, then the parameters are taken from the specified file and the file must
contain one line for each atom type. The latter form must be used when performing QeQ with a non-ReaxFF potential.
Each line should be formatted as follows:

itype chi eta gamma

where itype is the atom type from 1 to Ntypes, chi denotes the electronegativity in eV, eta denotes the self-Coulomb
potential in eV, and gamma denotes the valence orbital exponent. Note that these 3 quantities are also in the ReaxFF
potential file, except that eta is defined here as twice the eta value in the ReaxFF file. Note that unlike the rest of
LAMMPS, the units of this fix are hard-coded to be A, eV, and electronic charge.
The optional dual keyword allows to perform the optimization of the S and T matrices in parallel. This is only supported
for the qeq/reaxff/omp style. Otherwise they are processed separately.
The optional maxiter keyword allows changing the max number of iterations in the linear solver. The default value is
200.
The optional nowarn keyword silences the warning message printed when the maximum number of iterations was
reached. This can be useful for comparing serial and parallel results where having the same fixed number of QEq
iterations is desired, which can be achieved by using a very small tolerance and setting maxiter to the desired number
of iterations.

17.162.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. This fix computes a global scalar (the number of itera-
tions) for access by various output commands. No parameter of this fix can be used with the start/stop keywords of the
run command.
This fix is invoked during energy minimization.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.162. fix qeq/reaxff command 1443

LAMMPS Documentation, Release stable 29Sep2021

17.162.5 Restrictions

This fix is part of the REAXFF package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.
This fix does not correctly handle interactions involving multiple periodic images of the same atom. Hence, it should
not be used for periodic cell dimensions less than 10 angstroms.

17.162.6 Related commands

pair_style reaxff , fix qeq/shielded

17.162.7 Default

maxiter 200

(Rappe) Rappe and Goddard III, Journal of Physical Chemistry, 95, 3358-3363 (1991).
(Nakano) Nakano, Computer Physics Communications, 104, 59-69 (1997).
(Aktulga) Aktulga, Fogarty, Pandit, Grama, Parallel Computing, 38, 245-259 (2012).

17.163 fix qmmm command

17.163.1 Syntax

fix ID group-ID qmmm

• ID, group-ID are documented in fix command

• qmmm = style name of this fix command

17.163.2 Examples

fix 1 qmol qmmm

17.163.3 Description

This fix provides functionality to enable a quantum mechanics/molecular mechanics (QM/MM) coupling of LAMMPS
to a quantum mechanical code. The current implementation only supports an ONIOM style mechanical coupling to
the Quantum ESPRESSO plane wave DFT package. Electrostatic coupling is in preparation and the interface has been
written in a manner that coupling to other QM codes should be possible without changes to LAMMPS itself.
The interface code for this is in the lib/qmmm directory of the LAMMPS distribution and is being made available at
this early stage of development in order to encourage contributions for interfaces to other QM codes. This will allow
the LAMMPS side of the implementation to be adapted if necessary before being finalized.
Details about how to use this fix are currently documented in the description of the QM/MM interface code itself in
lib/qmmm/README.

1444 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.163.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global scalar or vector or per-atom quantities are stored by this fix for access by various output commands. No
parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.163.5 Restrictions

This fix is part of the QMMM package. It is only enabled if LAMMPS was built with that package. It also requires
building a library provided with LAMMPS. See the Build package page for more info.
The fix is only functional when LAMMPS is built as a library and linked with a compatible QM program and a QM/MM
front end into a QM/MM executable. See the lib/qmmm/README file for details.

17.163.6 Related commands

none

17.163.7 Default

none

17.164 fix qtb command

17.164.1 Syntax

fix ID group-ID qtb keyword value ...

• ID, group-ID are documented in fix command

• qtb = style name of this fix
• zero or more keyword/value pairs may be appended
• keyword = temp or damp or seed or f_max or N_f
temp value = target quantum temperature (temperature units)
damp value = damping parameter (time units) inverse of friction gamma
seed value = random number seed (positive integer)
f_max value = upper cutoff frequency of the vibration spectrum (1/time units)
N_f value = number of frequency bins (positive integer)

17.164. fix qtb command 1445

LAMMPS Documentation, Release stable 29Sep2021

17.164.2 Examples

# (liquid methane modeled with the REAX force field, real units)
fix 1 all nve
fix 1 all qtb temp 110 damp 200 seed 35082 f_max 0.3 N_f 100
# (quartz modeled with the BKS force field, metal units)
fix 2 all nph iso 1.01325 1.01325 1
fix 2 all qtb temp 300 damp 1 seed 47508 f_max 120.0 N_f 100

17.164.3 Description

This command performs the quantum thermal bath scheme proposed by (Dammak) to include self-consistent quantum
nuclear effects, when used in conjunction with the fix nve or fix nph commands.
Classical molecular dynamics simulation does not include any quantum nuclear effect. Quantum treatment of the
vibrational modes will introduce zero point energy into the system, alter the energy power spectrum and bias the heat
capacity from the classical limit. Missing all the quantum nuclear effects, classical MD cannot model systems at
temperatures lower than their classical limits. This effect is especially important for materials with a large population
of hydrogen atoms and thus higher classical limits.
The equation of motion implemented by this command follows a Langevin form:

mi ai = fi + Ri − mi γvi

Here mi , ai , fi , Ri , γ, andvi represent in this order mass, acceleration, force exerted by all other atoms, random force,
frictional coefficient (the inverse of damping parameter damp), and velocity. The random force Ri is “colored” so that
any vibrational mode with frequency ω will have a temperature-sensitive energy θ(ω, T ) which resembles the energy
expectation for a quantum harmonic oscillator with the same natural frequency:
 −1
~ ~ω
θ(ωT ) = + ~ω exp( )−1
2 kB T
To efficiently generate the random forces, we employ the method of (Barrat), that circumvents the need to generate
all random forces for all times before the simulation. The memory requirement of this approach is less demanding
and independent of the simulation duration. Since the total random force Rtot does not necessarily vanish for a finite
number of atoms, Ri is replaced by Ri − N Rtot
tot
to avoid collective motion of the system.
The temp parameter sets the target quantum temperature. LAMMPS will still have an output temperature in its thermo
style. That is the instantaneous classical temperature T cl derived from the atom velocities at thermal equilibrium. A
non-zero T cl will be present even when the quantum temperature approaches zero. This is associated with zero-point
energy at low temperatures.
X mi v 2
i
T cl =
3N kB
The damp parameter is specified in time units, and it equals the inverse of the frictional coefficient γ. γ should be as
small as possible but slightly larger than the timescale of anharmonic coupling in the system which is about 10 ps to
100 ps. When γ is too large, it gives an energy spectrum that differs from the desired Bose-Einstein spectrum. When γ
is too small, the quantum thermal bath coupling to the system will be less significant than anharmonic effects, reducing
to a classical limit. We find that setting γ between 5 THz and 1 THz could be appropriate depending on the system.
The random number seed is a positive integer used to initiate a Marsaglia random number generator. Each processor
uses the input seed to generate its own unique seed and its own stream of random numbers. Thus the dynamics of the
system will not be identical on two runs on different numbers of processors.
The f_max parameter truncate the noise frequency domain so that vibrational modes with frequencies higher than f_max
will not be modulated. If we denote ∆t as the time interval for the MD integration, f_max is always reset by the code

1446 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

to make α = (int)(2 f_max ∆t)−1 a positive integer and print out relative information. An appropriate value for the
cutoff frequency f_max would be around 2~3 fD , where fD is the Debye frequency.
The N_f parameter is the frequency grid size, the number of points from 0 to f_max in the frequency domain that
will be sampled. 3*2N_f per-atom random numbers are required in the random force generation and there could be
as many atoms as in the whole simulation that can migrate into every individual processor. A larger N_f provides a
more accurate sampling of the spectrum while consumes more memory. With fixed f_max and γ, N_f should be big
enough to converge the classical temperature T cl as a function of target quantum bath temperature. Memory usage per
processor could be from 10 to 100 MBytes.

Note: Unlike the fix nvt command which performs Nose/Hoover thermostatting AND time integration, this fix does
NOT perform time integration. It only modifies forces to a colored thermostat. Thus you must use a separate time
integration fix, like fix nve or fix nph to actually update the velocities and positions of atoms (as shown in the examples).
Likewise, this fix should not normally be used with other fixes or commands that also specify system temperatures ,
e.g. fix nvt and fix temp/rescale.

17.164.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. Because the state of the random number generator is not
saved in restart files, this means you cannot do “exact” restarts with this fix. However, in a statistical sense, a restarted
simulation should produce similar behaviors of the system.
This fix is not invoked during energy minimization.

17.164.5 Restrictions

This fix style is part of the QTB package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.164.6 Related commands

fix nve, fix nph, fix langevin, fix qbmsst

17.164.7 Default

The keyword defaults are temp = 300, damp = 1, seed = 880302, f_max=200.0 and N_f = 100.

(Dammak) Dammak, Chalopin, Laroche, Hayoun, and Greffet, Phys Rev Lett, 103, 190601 (2009).
(Barrat) Barrat and Rodney, J. Stat. Phys, 144, 679 (2011).

17.164. fix qtb command 1447

LAMMPS Documentation, Release stable 29Sep2021

17.165 fix reaxff/bonds command

Accelerator Variants: reaxff/bonds/kk

17.165.1 Syntax

fix ID group-ID reaxff/bonds Nevery filename

• ID, group-ID are documented in fix command

• reax/bonds = style name of this fix command
• Nevery = output interval in timesteps
• filename = name of output file

17.165.2 Examples

fix 1 all reaxff/bonds 100 bonds.reaxff

17.165.3 Description

Write out the bond information computed by the ReaxFF potential specified by pair_style reaxff in the exact same
format as the original stand-alone ReaxFF code of Adri van Duin. The bond information is written to filename on
timesteps that are multiples of Nevery, including timestep 0. For time-averaged chemical species analysis, please see
the fix reaxff/species command.
The specified group-ID is ignored by this fix.
The format of the output file should be reasonably self-explanatory. The meaning of the column header abbreviations
is as follows:
• id = atom id
• type = atom type
• nb = number of bonds
• id_1 = atom id of first bond
• id_nb = atom id of Nth bond
• mol = molecule id
• bo_1 = bond order of first bond
• bo_nb = bond order of Nth bond
• abo = atom bond order (sum of all bonds)
• nlp = number of lone pairs
• q = atomic charge
If the filename ends with “.gz”, the output file is written in gzipped format. A gzipped dump file will be about 3x
smaller than the text version, but will also take longer to write.

1448 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.165.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix
can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.165.5 Restrictions

The fix reaxff/bonds command requires that the pair_style reaxff is invoked. This fix is part of the REAXFF package.
It is only enabled if LAMMPS was built with that package. See the Build package page for more info.
To write gzipped bond files, you must compile LAMMPS with the -DLAMMPS_GZIP option.

17.165.6 Related commands

pair_style reaxff , fix reaxff/species

17.165.7 Default

none

17.166 fix reaxff/species command

Accelerator Variants: reaxff/species/kk

17.166.1 Syntax

fix ID group-ID reaxff/species Nevery Nrepeat Nfreq filename keyword value ...

• ID, group-ID are documented in fix command

• reaxff/species = style name of this command
• Nevery = sample bond-order every this many timesteps
• Nrepeat = # of bond-order samples used for calculating averages

17.166. fix reaxff/species command 1449

LAMMPS Documentation, Release stable 29Sep2021

• Nfreq = calculate average bond-order every this many timesteps

• filename = name of output file
• zero or more keyword/value pairs may be appended
• keyword = cutoff or element or position
cutoff value = I J Cutoff
I, J = atom types
Cutoff = Bond-order cutoff value for this pair of atom types
element value = Element1, Element2, ...
position value = posfreq filepos
posfreq = write position files every this many timestep
filepos = name of position output file

17.166.2 Examples

fix 1 all reaxff/species 10 10 100 species.out

fix 1 all reaxff/species 1 2 20 species.out cutoff 1 1 0.40 cutoff 1 2 0.55
fix 1 all reaxff/species 1 100 100 species.out element Au O H position 1000 AuOH.pos

17.166.3 Description

Write out the chemical species information computed by the ReaxFF potential specified by pair_style reaxff . Bond-
order values (either averaged or instantaneous, depending on value of Nrepeat) are used to determine chemical bonds.
Every Nfreq timesteps, chemical species information is written to filename as a two line output. The first line is a
header containing labels. The second line consists of the following: timestep, total number of molecules, total number
of distinct species, number of molecules of each species. In this context, “species” means a unique molecule. The
chemical formula of each species is given in the first line.
If the filename ends with “.gz”, the output file is written in gzipped format. A gzipped dump file will be about 3x
smaller than the text version, but will also take longer to write.
Optional keyword cutoff can be assigned to change the minimum bond-order values used in identifying chemical
bonds between pairs of atoms. Bond-order cutoffs should be carefully chosen, as bond-order cutoffs that are too small
may include too many bonds (which will result in an error), while cutoffs that are too large will result in fragmented
molecules. The default cutoff of 0.3 usually gives good results.
The optional keyword element can be used to specify the chemical symbol printed for each LAMMPS atom type.
The number of symbols must match the number of LAMMPS atom types and each symbol must consist of 1 or 2
alphanumeric characters. Normally, these symbols should be chosen to match the chemical identity of each LAMMPS
atom type, as specified using the reaxff pair_coeff command and the ReaxFF force field file.
The optional keyword position writes center-of-mass positions of each identified molecules to file filepos every posfreq
timesteps. The first line contains information on timestep, total number of molecules, total number of distinct species,
and box dimensions. The second line is a header containing labels. From the third line downward, each molecule
writes a line of output containing the following information: molecule ID, number of atoms in this molecule, chemical
formula, total charge, and center-of-mass xyz positions of this molecule. The xyz positions are in fractional coordinates
relative to the box dimensions.
For the keyword position, the filepos is the name of the output file. It can contain the wildcard character “*”. If the “*”
character appears in filepos, then one file per snapshot is written at posfreq and the “*” character is replaced with the
timestep value. For example, AuO.pos.* becomes AuO.pos.0, AuO.pos.1000, etc.

1450 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the bond-order values are sampled to get the
average bond order. The species analysis is performed using the average bond-order on timesteps that are a multiple
of Nfreq. The average is over Nrepeat bond-order samples, computed in the preceding portion of the simulation every
Nevery timesteps. Nfreq must be a multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the
timesteps contributing to the average bond-order cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then bond-order values on timesteps 90,92,94,96,98,100 will
be used to compute the average bond-order for the species analysis output on timestep 100.

17.166.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes both a global vector of length 2 and a per-atom vector, either of which can be accessed by various
output commands. The values in the global vector are “intensive”.
The 2 values in the global vector are as follows:
• 1 = total number of molecules
• 2 = total number of distinct species
The per-atom vector stores the molecule ID for each atom as identified by the fix. If an atom is not in a molecule, its
ID will be 0. For atoms in the same molecule, the molecule ID for all of them will be the same and will be equal to the
smallest atom ID of any atom in the molecule.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.166.5 Restrictions

The “fix reaxff/species” requires that pair_style reaxff is used. This fix is part of the REAXFF package. It is only
enabled if LAMMPS was built with that package. See the Build package page for more info.
To write gzipped species files, you must compile LAMMPS with the -DLAMMPS_GZIP option.

17.166. fix reaxff/species command 1451

LAMMPS Documentation, Release stable 29Sep2021

17.166.6 Related commands

pair_style reaxff , fix reaxff/bonds

17.166.7 Default

The default values for bond-order cutoffs are 0.3 for all I-J pairs. The default element symbols are C, H, O, N. Position
files are not written by default.

17.167 fix recenter command

17.167.1 Syntax

fix ID group-ID recenter x y z keyword value ...

• ID, group-ID are documented in fix command

• recenter = style name of this fix command
• x,y,z = constrain center-of-mass to these coords (distance units), any coord can also be NULL or INIT (see below)
• zero or more keyword/value pairs may be appended
• keyword = shift or units
shift value = group-ID
group-ID = group of atoms whose coords are shifted
units value = box or lattice or fraction

17.167.2 Examples

fix 1 all recenter 0.0 0.5 0.0

fix 1 all recenter INIT INIT NULL
fix 1 all recenter INIT 0.0 0.0 units box

17.167.3 Description

Constrain the center-of-mass position of a group of atoms by adjusting the coordinates of the atoms every timestep.
This is simply a small shift that does not alter the dynamics of the system or change the relative coordinates of any
pair of atoms in the group. This can be used to insure the entire collection of atoms (or a portion of them) do not drift
during the simulation due to random perturbations (e.g. fix langevin thermostatting).
Distance units for the x,y,z values are determined by the setting of the units keyword, as discussed below. One or more
x,y,z values can also be specified as NULL, which means exclude that dimension from this operation. Or it can be
specified as INIT which means to constrain the center-of-mass to its initial value at the beginning of the run.
The center-of-mass (COM) is computed for the group specified by the fix. If the current COM is different than the
specified x,y,z, then a group of atoms has their coordinates shifted by the difference. By default the shifted group is
also the group specified by the fix. A different group can be shifted by using the shift keyword. For example, the COM
could be computed on a protein to keep it in the center of the simulation box. But the entire system (protein + water)
could be shifted.

1452 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

If the units keyword is set to box, then the distance units of x,y,z are defined by the units command - e.g. Angstroms for
real units. A lattice value means the distance units are in lattice spacings. The lattice command must have been previ-
ously used to define the lattice spacing. A fraction value means a fractional distance between the lo/hi box boundaries,
e.g. 0.5 = middle of the box. The default is to use lattice units.
Note that the velocity command can be used to create velocities with zero aggregate linear and/or angular momentum.

Note: This fix performs its operations at the same point in the timestep as other time integration fixes, such as fix
nve, fix nvt, or fix npt. Thus fix recenter should normally be the last such fix specified in the input script, since the
adjustments it makes to atom coordinates should come after the changes made by time integration. LAMMPS will
warn you if your fixes are not ordered this way.

Note: If you use this fix on a small group of atoms (e.g. a molecule in solvent) without using the shift keyword to adjust
the positions of all atoms in the system, then the results can be unpredictable. For example, if the molecule is pushed
consistently in one direction by a flowing solvent, its velocity will increase. But its coordinates will be re-centered,
meaning it is moved back towards the force. Thus over time, the velocity and effective temperature of the molecule
could become very large, though it won’t actually be moving due to the re-centering. If you are thermostatting the
entire system, then the solvent would be cooled to compensate. A better solution for this simulation scenario is to use
the fix spring command to tether the molecule in place.

17.167.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the distance the
group is moved by fix recenter.
This fix also computes global 3-vector which can be accessed by various output commands. The 3 quantities in the
vector are xyz components of displacement applied to the group of atoms by the fix.
The scalar and vector values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.167.5 Restrictions

This fix should not be used with an x,y,z setting that causes a large shift in the system on the first timestep, due to the
requested COM being very different from the initial COM. This could cause atoms to be lost, especially in parallel.
Instead, use the displace_atoms command, which can be used to move atoms a large distance.

17.167.6 Related commands

fix momentum, velocity

17.167. fix recenter command 1453

LAMMPS Documentation, Release stable 29Sep2021

17.167.7 Default

The option defaults are shift = fix group-ID, and units = lattice.

17.168 fix restrain command

17.168.1 Syntax

fix ID group-ID restrain keyword args ...

• ID, group-ID are documented in fix command

• restrain = style name of this fix command
• one or more keyword/arg pairs may be appended
• keyword = bond or lbound or angle or dihedral
bond args = atom1 atom2 Kstart Kstop r0start (r0stop)
atom1,atom2 = IDs of 2 atoms in bond
Kstart,Kstop = restraint coefficients at start/end of run (energy units)
r0start = equilibrium bond distance at start of run (distance units)
r0stop = equilibrium bond distance at end of run (optional) (distance units). If␣
,→not

specified it is assumed to be equal to r0start

lbound args = atom1 atom2 Kstart Kstop r0start (r0stop)
atom1,atom2 = IDs of 2 atoms in bond
Kstart,Kstop = restraint coefficients at start/end of run (energy units)
r0start = equilibrium bond distance at start of run (distance units)
r0stop = equilibrium bond distance at end of run (optional) (distance units). If␣
,→not

specified it is assumed to be equal to r0start

angle args = atom1 atom2 atom3 Kstart Kstop theta0
atom1,atom2,atom3 = IDs of 3 atoms in angle, atom2 = middle atom
Kstart,Kstop = restraint coefficients at start/end of run (energy units)
theta0 = equilibrium angle theta (degrees)
dihedral args = atom1 atom2 atom3 atom4 Kstart Kstop phi0 keyword/value
atom1,atom2,atom3,atom4 = IDs of 4 atoms in dihedral in linear order
Kstart,Kstop = restraint coefficients at start/end of run (energy units)
phi0 = equilibrium dihedral angle phi (degrees)
keyword/value = optional keyword value pairs. supported keyword/value pairs:
mult n = dihedral multiplicity n (integer >= 0, default = 1)

17.168.2 Examples

fix holdem all restrain bond 45 48 2000.0 2000.0 2.75

fix holdem all restrain lbound 45 48 2000.0 2000.0 2.75
fix holdem all restrain dihedral 1 2 3 4 2000.0 2000.0 120.0
fix holdem all restrain bond 45 48 2000.0 2000.0 2.75 dihedral 1 2 3 4 2000.0 2000.0 120.
,→0

fix texas_holdem all restrain dihedral 1 2 3 4 0.0 2000.0 120.0 dihedral 1 2 3 5 0.0␣
,→2000.0 -120.0 dihedral 1 2 3 6 0.0 2000.0 0.0

1454 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.168.3 Description

Restrain the motion of the specified sets of atoms by making them part of a bond or angle or dihedral interaction whose
strength can vary over time during a simulation. This is functionally similar to creating a bond or angle or dihedral for
the same atoms in a data file, as specified by the read_data command, albeit with a time-varying pre-factor coefficient,
and except for exclusion rules, as explained below.
For the purpose of force field parameter-fitting or mapping a molecular potential energy surface, this fix reduces the
hassle and risk associated with modifying data files. In other words, use this fix to temporarily force a molecule to
adopt a particular conformation. To create a permanent bond or angle or dihedral, you should modify the data file.

Note: Adding a bond/angle/dihedral with this command does not apply the exclusion rules and weighting factors
specified by the special_bonds command to atoms in the restraint that are now bonded (1-2,1-3,1-4 neighbors) as a
result. If they are close enough to interact in a pair_style sense (non-bonded interaction), then the bond/angle/dihedral
restraint interaction will simply be superposed on top of that interaction.

The group-ID specified by this fix is ignored.

The second example above applies a restraint to hold the dihedral angle formed by atoms 1, 2, 3, and 4 near 120 degrees
using a constant restraint coefficient. The fourth example applies similar restraints to multiple dihedral angles using a
restraint coefficient that increases from 0.0 to 2000.0 over the course of the run.

Note: Adding a force to atoms implies a change in their potential energy as they move due to the applied force field.
For dynamics via the run command, this energy can be added to the system’s potential energy for thermodynamic
output (see below). For energy minimization via the minimize command, this energy must be added to the system’s
potential energy to formulate a self-consistent minimization problem (see below).

In order for a restraint to be effective, the restraint force must typically be significantly larger than the forces associated
with conventional force field terms. If the restraint is applied during a dynamics run (as opposed to during an energy
minimization), a large restraint coefficient can significantly reduce the stable timestep size, especially if the atoms are
initially far from the preferred conformation. You may need to experiment to determine what value of K works best
for a given application.
For the case of finding a minimum energy structure for a single molecule with particular restraints (e.g. for fitting force
field parameters or constructing a potential energy surface), commands such as the following may be useful:

# minimize molecule energy with restraints

velocity all create 600.0 8675309 mom yes rot yes dist gaussian
fix NVE all nve
fix TFIX all langevin 600.0 0.0 100 24601
fix REST all restrain dihedral 2 1 3 8 0.0 5000.0 ${angle1} dihedral 3 1 2 9 0.0 5000.0 $
,→{angle2}

fix_modify REST energy yes

run 10000
fix TFIX all langevin 0.0 0.0 100 24601
fix REST all restrain dihedral 2 1 3 8 5000.0 5000.0 ${angle1} dihedral 3 1 2 9 5000.0␣
,→5000.0 ${angle2}

fix_modify REST energy yes

run 10000
# sanity check for convergence
minimize 1e-6 1e-9 1000 100000
# report unrestrained energies
(continues on next page)

17.168. fix restrain command 1455

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

unfix REST
run 0

The bond keyword applies a bond restraint to the specified atoms using the same functional form used by the bond_style
harmonic command. The potential associated with the restraint is

E = K(r − r0 )2

with the following coefficients:

• K (energy/distance^2)
• r0 (distance)
K and r0 are specified with the fix. Note that the usual 1/2 factor is included in K.

The lbound keyword applies a lower bound bond restraint to the specified atoms using the same functional form used
by the bond_style harmonic command if the distance between the atoms is smaller than the equilibrium bond distance
and 0 otherwise. The potential associated with the restraint is

E = K(r − r0 )2 , if r < r0

E=0 , if r ≥ r0
with the following coefficients:
• K (energy/distance^2)
• r0 (distance)
K and r0 are specified with the fix. Note that the usual 1/2 factor is included in K.

The angle keyword applies an angle restraint to the specified atoms using the same functional form used by the an-
gle_style harmonic command. The potential associated with the restraint is

E = K(θ − θ0 )2

with the following coefficients:

• K (energy)
• θ0 (degrees)
K and θ0 are specified with the fix. θ0 is specified in degrees, but LAMMPS converts it to radians internally; hence K
is effectively energy per radian^2. Note that the usual 1/2 factor is included in K.

The dihedral keyword applies a dihedral restraint to the specified atoms using a simplified form of the function used
by the dihedral_style charmm command. The potential associated with the restraint is

E = K[1 + cos(nφ − d)]

with the following coefficients:

• K (energy)

1456 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• n (multiplicity, >= 0)
• d (degrees) = φ0 + 180
K and φ0 are specified with the fix. Note that the value of the dihedral multiplicity n is set by default to 1. You can use
the optional mult keyword to set it to a different positive integer. Also note that the energy will be a minimum when
the current dihedral angle φ is equal to φ0 .

17.168.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy associated with this fix to the global
potential energy of the system as part of thermodynamic output The default setting for this fix is fix_modify energy no.
The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.

Note: If you want the fictitious potential energy associated with the added forces to be included in the total potential
energy of the system (the quantity being minimized), you MUST enable the fix_modify energy option for this fix.

This fix computes a global scalar and a global vector of length 3, which can be accessed by various output commands.
The scalar is the total potential energy for all the restraints as discussed above. The vector values are the sum of
contributions to the following individual categories:
• 1 = bond energy
• 2 = angle energy
• 3 = dihedral energy
The scalar and vector values calculated by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.

17.168.5 Restrictions

none

17.168.6 Related commands

none

17.168.7 Default

none

17.168. fix restrain command 1457

LAMMPS Documentation, Release stable 29Sep2021

17.169 fix rhok command

17.169.1 Syntax

fix ID group-ID rhok nx ny nz K a

• ID, group-ID are documented in fix command

• nx, ny, nz = k-vector of collective density field
• K = spring constant of bias potential
• a = anchor point of bias potential

17.169.2 Examples

fix bias all rhok 16 0 0 4.0 16.0

fix 1 all npt temp 0.8 0.8 4.0 z 2.2 2.2 8.0
# output of 4 values from fix rhok: U_bias rho_k_RE rho_k_IM \|rho_k\|
thermo_style custom step temp pzz lz f_bias f_bias[1] f_bias[2] f_bias[3]

17.169.3 Description

The fix applies a force to atoms given by the potential

1
U = K(|ρ~k | − a)2
2
N
X √
ρ~k = exp(−i~k · ~rj )/ N
j
~k =(2πnx /Lx , 2πny /Ly , 2πnz /Lz )

as described in (Pedersen).
This field, which biases configurations with long-range order, can be used to study crystal-liquid interfaces and deter-
mine melting temperatures (Pedersen).
An example of using the interface pinning method is located in the examples/PACKAGES/rhok directory.

17.169.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify energy option is supported by this fix to add the potential energy calculated by the fix to the global
potential energy of the system as part of thermodynamic output. The default setting for this fix is fix_modify energy no.
This fix computes a global scalar which can be accessed by various output commands. The scalar is the potential energy
discussed in the preceding paragraph. The scalar stored by this fix is “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
This fix is not invoked during energy minimization.

1458 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.169.5 Restrictions

This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS was built with that package. See the Build
package page for more info.

17.169.6 Related commands

thermo_style

17.169.7 Default

none

(Pedersen) Pedersen, J. Chem. Phys., 139, 104102 (2013).

17.170 fix rigid command

Accelerator Variants: rigid/omp

17.171 fix rigid/nve command

Accelerator Variants: rigid/nve/omp

17.172 fix rigid/nvt command

Accelerator Variants: rigid/nvt/omp

17.173 fix rigid/npt command

Accelerator Variants: rigid/npt/omp

17.174 fix rigid/nph command

Accelerator Variants: rigid/nph/omp

17.170. fix rigid command 1459

LAMMPS Documentation, Release stable 29Sep2021

17.175 fix rigid/small command

Accelerator Variants: rigid/small/omp

17.176 fix rigid/nve/small command

17.177 fix rigid/nvt/small command

17.178 fix rigid/npt/small command

17.179 fix rigid/nph/small command

17.179.1 Syntax

fix ID group-ID style bodystyle args keyword values ...

• ID, group-ID are documented in fix command

• style = rigid or rigid/nve or rigid/nvt or rigid/npt or rigid/nph or rigid/small or rigid/nve/small or rigid/nvt/small
or rigid/npt/small or rigid/nph/small
• bodystyle = single or molecule or group
single args = none
molecule args = none
custom args = i_propname or v_varname
i_propname = a custom integer vector defined via fix property/atom
v_varname = an atom-style or atomfile-style variable
group args = N groupID1 groupID2 ...
N = # of groups
groupID1, groupID2, ... = list of N group IDs
• zero or more keyword/value pairs may be appended
• keyword = langevin or reinit or temp or iso or aniso or x or y or z or couple or tparam or pchain or dilate or force
or torque or infile
langevin values = Tstart Tstop Tperiod seed
Tstart,Tstop = desired temperature at start/stop of run (temperature units)
Tdamp = temperature damping parameter (time units)
seed = random number seed to use for white noise (positive integer)
reinit = yes or no
temp values = Tstart Tstop Tdamp
Tstart,Tstop = desired temperature at start/stop of run (temperature units)
Tdamp = temperature damping parameter (time units)
iso or aniso values = Pstart Pstop Pdamp
Pstart,Pstop = scalar external pressure at start/end of run (pressure units)
Pdamp = pressure damping parameter (time units)
x or y or z values = Pstart Pstop Pdamp
Pstart,Pstop = external stress tensor component at start/end of run (pressure␣
,→units)

Pdamp = stress damping parameter (time units)

1460 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

couple = none or xyz or xy or yz or xz

tparam values = Tchain Titer Torder
Tchain = length of Nose/Hoover thermostat chain
Titer = number of thermostat iterations performed
Torder = 3 or 5 = Yoshida-Suzuki integration parameters
pchain values = Pchain
Pchain = length of the Nose/Hoover thermostat chain coupled with the barostat
dilate value = dilate-group-ID
dilate-group-ID = only dilate atoms in this group due to barostat volume changes
force values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass force is active
torque values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass torque is active
infile filename
filename = file with per-body values of mass, center-of-mass, moments of inertia
mol value = template-ID
template-ID = ID of molecule template specified in a separate molecule command

17.179.2 Examples

fix 1 clump rigid single reinit yes

fix 1 clump rigid/small molecule
fix 1 clump rigid single force 1 off off on langevin 1.0 1.0 1.0 428984
fix 1 polychains rigid/nvt molecule temp 1.0 1.0 5.0 reinit no
fix 1 polychains rigid molecule force 1*5 off off off force 6*10 off off on
fix 1 polychains rigid/small molecule langevin 1.0 1.0 1.0 428984
fix 2 fluid rigid group 3 clump1 clump2 clump3 torque * off off off
fix 1 rods rigid/npt molecule temp 300.0 300.0 100.0 iso 0.5 0.5 10.0
fix 1 particles rigid/npt molecule temp 1.0 1.0 5.0 x 0.5 0.5 1.0 z 0.5 0.5 1.0 couple xz
fix 1 water rigid/nph molecule iso 0.5 0.5 1.0
fix 1 particles rigid/npt/small molecule temp 1.0 1.0 1.0 iso 0.5 0.5 1.0

variable bodyid atom 1.0*gmask(clump1)+2.0*gmask(clump2)+3.0*gmask(clump3)

fix 1 clump rigid custom v_bodyid

variable bodyid atomfile bodies.txt

fix 1 clump rigid custom v_bodyid

fix 0 all property/atom i_bodyid

read_restart data.rigid fix 0 NULL Bodies
fix 1 clump rigid/small custom i_bodyid

17.179. fix rigid/nph/small command 1461

LAMMPS Documentation, Release stable 29Sep2021

17.179.3 Description

Treat one or more sets of atoms as independent rigid bodies. This means that each timestep the total force and torque
on each rigid body is computed as the sum of the forces and torques on its constituent particles. The coordinates,
velocities, and orientations of the atoms in each body are then updated so that the body moves and rotates as a single
entity. This is implemented by creating internal data structures for each rigid body and performing time integration on
these data structures. Positions, velocities, and orientations of the constituent particles are regenerated from the rigid
body data structures in every time step. This restricts which operations and fixes can be applied to rigid bodies. See
below for a detailed discussion.
Examples of large rigid bodies are a colloidal particle, or portions of a biomolecule such as a protein.
Example of small rigid bodies are patchy nanoparticles, such as those modeled in this paper by Sharon Glotzer’s group,
clumps of granular particles, lipid molecules consisting of one or more point dipoles connected to other spheroids
or ellipsoids, irregular particles built from line segments (2d) or triangles (3d), and coarse-grain models of nano or
colloidal particles consisting of a small number of constituent particles. Note that the fix shake command can also be
used to rigidify small molecules of 2, 3, or 4 atoms, e.g. water molecules. That fix treats the constituent atoms as point
masses.
These fixes also update the positions and velocities of the atoms in each rigid body via time integration, in the NVE,
NVT, NPT, or NPH ensemble, as described below.
There are two main variants of this fix, fix rigid and fix rigid/small. The NVE/NVT/NPT/NHT versions belong to one
of the two variants, as their style names indicate.

Note: Not all of the bodystyle options and keyword/value options are available for both the rigid and rigid/small
variants. See details below.

The rigid styles are typically the best choice for a system with a small number of large rigid bodies, each of which
can extend across the domain of many processors. It operates by creating a single global list of rigid bodies, which all
processors contribute to. MPI_Allreduce operations are performed each timestep to sum the contributions from each
processor to the force and torque on all the bodies. This operation will not scale well in parallel if large numbers of
rigid bodies are simulated.
The rigid/small styles are typically best for a system with a large number of small rigid bodies. Each body is assigned
to the atom closest to the geometrical center of the body. The fix operates using local lists of rigid bodies owned by
each processor and information is exchanged and summed via local communication between neighboring processors
when ghost atom info is accumulated.

Note: To use the rigid/small styles the ghost atom cutoff must be large enough to span the distance between the atom
that owns the body and every other atom in the body. This distance value is printed out when the rigid bodies are
defined. If the pair_style cutoff plus neighbor skin does not span this distance, then you should use the comm_modify
cutoff command with a setting epsilon larger than the distance.

Which of the two variants is faster for a particular problem is hard to predict. The best way to decide is to perform a
short test run. Both variants should give identical numerical answers for short runs. Long runs should give statistically
similar results, but round-off differences may accumulate to produce divergent trajectories.

Note: You should not update the atoms in rigid bodies via other time-integration fixes (e.g. fix nve, fix nvt, fix npt, fix
move), or you will have conflicting updates to positions and velocities resulting in unphysical behavior in most cases.
When performing a hybrid simulation with some atoms in rigid bodies, and some not, a separate time integration fix
like fix nve or fix nvt should be used for the non-rigid particles.

1462 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

Note: These fixes are overkill if you simply want to hold a collection of atoms stationary or have them move with a
constant velocity. A simpler way to hold atoms stationary is to not include those atoms in your time integration fix.
E.g. use “fix 1 mobile nve” instead of “fix 1 all nve”, where “mobile” is the group of atoms that you want to move. You
can move atoms with a constant velocity by assigning them an initial velocity (via the velocity command), setting the
force on them to 0.0 (via the fix setforce command), and integrating them as usual (e.g. via the fix nve command).

Warning: The aggregate properties of each rigid body are calculated at the start of a simulation run and are
maintained in internal data structures. The properties include the position and velocity of the center-of-mass of
the body, its moments of inertia, and its angular momentum. This is done using the properties of the constituent
atoms of the body at that point in time (or see the infile keyword option). Thereafter, changing these properties of
individual atoms in the body will have no effect on a rigid body’s dynamics, unless they effect any computation of
per-atom forces or torques. If the keyword reinit is set to yes (the default), the rigid body data structures will be
recreated at the beginning of each run command; if the keyword reinit is set to no, the rigid body data structures will
be built only at the very first run command and maintained for as long as the rigid fix is defined. For example, you
might think you could displace the atoms in a body or add a large velocity to each atom in a body to make it move
in a desired direction before a second run is performed, using the set or displace_atoms or velocity commands. But
these commands will not affect the internal attributes of the body unless reinit is set to yes. With reinit set to no
(or using the infile option, which implies reinit no) the position and velocity of individual atoms in the body will
be reset when time integration starts again.

Each rigid body must have two or more atoms. An atom can belong to at most one rigid body. Which atoms are in
which bodies can be defined via several options.

Note: With the rigid/small styles, which require that bodystyle be specified as molecule or custom, you can define a
system that has no rigid bodies initially. This is useful when you are using the mol keyword in conjunction with another
fix that is adding rigid bodies on-the-fly as molecules, such as fix deposit or fix pour.

For bodystyle single the entire fix group of atoms is treated as one rigid body. This option is only allowed for the rigid
styles.
For bodystyle molecule, atoms are grouped into rigid bodies by their respective molecule IDs: each set of atoms in the
fix group with the same molecule ID is treated as a different rigid body. This option is allowed for both the rigid and
rigid/small styles. Note that atoms with a molecule ID = 0 will be treated as a single rigid body. For a system with
atomic solvent (typically this is atoms with molecule ID = 0) surrounding rigid bodies, this may not be what you want.
Thus you should be careful to use a fix group that only includes atoms you want to be part of rigid bodies.
Bodystyle custom is similar to bodystyle molecule except that it is more flexible in using other per-atom properties
to define the sets of atoms that form rigid bodies. A custom per-atom integer vector defined by the fix property/atom
command can be used. Or an atom-style or atomfile-style variable can be used; the floating-point value produced by the
variable is rounded to an integer. As with bodystyle molecule, each set of atoms in the fix groups with the same integer
value is treated as a different rigid body. Since fix property/atom custom vectors and atom-style variables produce
values for all atoms, you should be careful to use a fix group that only includes atoms you want to be part of rigid
bodies.

Note: To compute the initial center-of-mass position and other properties of each rigid body, the image flags for each
atom in the body are used to “unwrap” the atom coordinates. Thus you must insure that these image flags are consistent
so that the unwrapping creates a valid rigid body (one where the atoms are close together), particularly if the atoms in
a single rigid body straddle a periodic boundary. This means the input data file or restart file must define the image

17.179. fix rigid/nph/small command 1463

LAMMPS Documentation, Release stable 29Sep2021

flags for each atom consistently or that you have used the set command to specify them correctly. If a dimension is
non-periodic then the image flag of each atom must be 0 in that dimension, else an error is generated.

The force and torque keywords discussed next are only allowed for the rigid styles.
By default, each rigid body is acted on by other atoms which induce an external force and torque on its center of mass,
causing it to translate and rotate. Components of the external center-of-mass force and torque can be turned off by the
force and torque keywords. This may be useful if you wish a body to rotate but not translate, or vice versa, or if you
wish it to rotate or translate continuously unaffected by interactions with other particles. Note that if you expect a rigid
body not to move or rotate by using these keywords, you must insure its initial center-of-mass translational or angular
velocity is 0.0. Otherwise the initial translational or angular momentum the body has will persist.
An xflag, yflag, or zflag set to off means turn off the component of force of torque in that dimension. A setting of on
means turn on the component, which is the default. Which rigid body(s) the settings apply to is determined by the first
argument of the force and torque keywords. It can be an integer M from 1 to Nbody, where Nbody is the number of
rigid bodies defined. A wild-card asterisk can be used in place of, or in conjunction with, the M argument to set the
flags for multiple rigid bodies. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of rigid bodies,
then an asterisk with no numeric values means all bodies from 1 to N. A leading asterisk means all bodies from 1 to n
(inclusive). A trailing asterisk means all bodies from n to N (inclusive). A middle asterisk means all types from m to
n (inclusive). Note that you can use the force or torque keywords as many times as you like. If a particular rigid body
has its component flags set multiple times, the settings from the final keyword are used.

Note: For computational efficiency, you may wish to turn off pairwise and bond interactions within each rigid body,
as they no longer contribute to the motion. The neigh_modify exclude and delete_bonds commands are used to do this.
If the rigid bodies have strongly overlapping atoms, you may need to turn off these interactions to avoid numerical
problems due to large equal/opposite intra-body forces swamping the contribution of small inter-body forces.

For computational efficiency, you should typically define one fix rigid or fix rigid/small command which includes all
the desired rigid bodies. LAMMPS will allow multiple rigid fixes to be defined, but it is more expensive.

The constituent particles within a rigid body can be point particles (the default in LAMMPS) or finite-size particles,
such as spheres or ellipsoids or line segments or triangles. See the atom_style sphere and ellipsoid and line and tri
commands for more details on these kinds of particles. Finite-size particles contribute differently to the moment of
inertia of a rigid body than do point particles. Finite-size particles can also experience torque (e.g. due to frictional
granular interactions) and have an orientation. These contributions are accounted for by these fixes.
Forces between particles within a body do not contribute to the external force or torque on the body. Thus for compu-
tational efficiency, you may wish to turn off pairwise and bond interactions between particles within each rigid body.
The neigh_modify exclude and delete_bonds commands are used to do this. For finite-size particles this also means the
particles can be highly overlapped when creating the rigid body.

The rigid, rigid/nve, rigid/small, and rigid/small/nve styles perform constant NVE time integration. They are referred to
below as the 4 NVE rigid styles. The only difference is that the rigid and rigid/small styles use an integration technique
based on Richardson iterations. The rigid/nve and rigid/small/nve styles uses the methods described in the paper by
Miller, which are thought to provide better energy conservation than an iterative approach.
The rigid/nvt and rigid/nvt/small styles performs constant NVT integration using a Nose/Hoover thermostat with chains
as described originally in (Hoover) and (Martyna), which thermostats both the translational and rotational degrees of
freedom of the rigid bodies. They are referred to below as the 2 NVT rigid styles. The rigid-body algorithm used by
rigid/nvt is described in the paper by Kamberaj.

1464 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The rigid/npt, rigid/nph, rigid/npt/small, and rigid/nph/small styles perform constant NPT or NPH integration using a
Nose/Hoover barostat with chains. They are referred to below as the 4 NPT and NPH rigid styles. For the NPT case,
the same Nose/Hoover thermostat is also used as with rigid/nvt and rigid/nvt/small.
The barostat parameters are specified using one or more of the iso, aniso, x, y, z and couple keywords. These keywords
give you the ability to specify 3 diagonal components of the external stress tensor, and to couple these components
together so that the dimensions they represent are varied together during a constant-pressure simulation. The effects of
these keywords are similar to those defined in fix npt/nph

Note: Currently the rigid/npt, rigid/nph, rigid/npt/small, and rigid/nph/small styles do not support triclinic (non-
orthogonal) boxes.

The target pressures for each of the 6 components of the stress tensor can be specified independently via the x, y, z
keywords, which correspond to the 3 simulation box dimensions. For each component, the external pressure or tensor
component at each timestep is a ramped value during the run from Pstart to Pstop. If a target pressure is specified for
a component, then the corresponding box dimension will change during a simulation. For example, if the y keyword is
used, the y-box length will change. A box dimension will not change if that component is not specified, although you
have the option to change that dimension via the fix deform command.
For all barostat keywords, the Pdamp parameter operates like the Tdamp parameter, determining the time scale on
which pressure is relaxed. For example, a value of 10.0 means to relax the pressure in a timespan of (roughly) 10 time
units (e.g. τ or fs or ps - see the units command).
Regardless of what atoms are in the fix group (the only atoms which are time integrated), a global pressure or stress
tensor is computed for all atoms. Similarly, when the size of the simulation box is changed, all atoms are re-scaled to
new positions, unless the keyword dilate is specified with a dilate-group-ID for a group that represents a subset of the
atoms. This can be useful, for example, to leave the coordinates of atoms in a solid substrate unchanged and controlling
the pressure of a surrounding fluid. Another example is a system consisting of rigid bodies and point particles where
the barostat is only coupled with the rigid bodies. This option should be used with care, since it can be unphysical to
dilate some atoms and not others, because it can introduce large, instantaneous displacements between a pair of atoms
(one dilated, one not) that are far from the dilation origin.
The couple keyword allows two or three of the diagonal components of the pressure tensor to be “coupled” together. The
value specified with the keyword determines which are coupled. For example, xz means the Pxx and Pzz components
of the stress tensor are coupled. Xyz means all 3 diagonal components are coupled. Coupling means two things: the
instantaneous stress will be computed as an average of the corresponding diagonal components, and the coupled box
dimensions will be changed together in lockstep, meaning coupled dimensions will be dilated or contracted by the
same percentage every timestep. The Pstart, Pstop, Pdamp parameters for any coupled dimensions must be identical.
Couple xyz can be used for a 2d simulation; the z dimension is simply ignored.
The iso and aniso keywords are simply shortcuts that are equivalent to specifying several other keywords together.
The keyword iso means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure),
and dilate/contract the dimensions together. Using “iso Pstart Pstop Pdamp” is the same as specifying these 4 keywords:
x Pstart Pstop Pdamp
y Pstart Pstop Pdamp
z Pstart Pstop Pdamp
couple xyz

The keyword aniso means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components
of the stress tensor as the driving forces, and the specified scalar external pressure. Using “aniso Pstart Pstop Pdamp”
is the same as specifying these 4 keywords:
x Pstart Pstop Pdamp
y Pstart Pstop Pdamp
(continues on next page)

17.179. fix rigid/nph/small command 1465

LAMMPS Documentation, Release stable 29Sep2021

(continued from previous page)

z Pstart Pstop Pdamp
couple none

The keyword/value option pairs are used in the following ways.

The reinit keyword determines, whether the rigid body properties are re-initialized between run commands. With the
option yes (the default) this is done, with the option no this is not done. Turning off the re-initialization can be helpful
to protect rigid bodies against unphysical manipulations between runs or when properties cannot be easily re-computed
(e.g. when read from a file). When using the infile keyword, the reinit option is automatically set to no.
The langevin and temp and tparam keywords perform thermostatting of the rigid bodies, altering both their translational
and rotational degrees of freedom. What is meant by “temperature” of a collection of rigid bodies and how it can be
monitored via the fix output is discussed below.
The langevin keyword applies a Langevin thermostat to the constant NVE time integration performed by any of the 4
NVE rigid styles: rigid, rigid/nve, rigid/small, rigid/small/nve. It cannot be used with the 2 NVT rigid styles: rigid/nvt,
rigid/small/nvt. The desired temperature at each timestep is a ramped value during the run from Tstart to Tstop. The
Tdamp parameter is specified in time units and determines how rapidly the temperature is relaxed. For example, a
value of 100.0 means to relax the temperature in a timespan of (roughly) 100 time units (τ or fs or ps - see the units
command). The random # seed must be a positive integer.
The way that Langevin thermostatting operates is explained on the fix langevin doc page. If you wish to simply viscously
damp the rotational motion without thermostatting, you can set Tstart and Tstop to 0.0, which means only the viscous
drag term in the Langevin thermostat will be applied. See the discussion on the fix viscous page for details.

Note: When the langevin keyword is used with fix rigid versus fix rigid/small, different dynamics will result for
parallel runs. This is because of the way random numbers are used in the two cases. The dynamics for the two cases
should be statistically similar, but will not be identical, even for a single timestep.

The temp and tparam keywords apply a Nose/Hoover thermostat to the NVT time integration performed by the 2 NVT
rigid styles. They cannot be used with the 4 NVE rigid styles. The desired temperature at each timestep is a ramped
value during the run from Tstart to Tstop. The Tdamp parameter is specified in time units and determines how rapidly
the temperature is relaxed. For example, a value of 100.0 means to relax the temperature in a timespan of (roughly)
100 time units (tau or fs or ps - see the units command).
Nose/Hoover chains are used in conjunction with this thermostat. The tparam keyword can optionally be used to change
the chain settings used. Tchain is the number of thermostats in the Nose Hoover chain. This value, along with Tdamp
can be varied to dampen undesirable oscillations in temperature that can occur in a simulation. As a rule of thumb,
increasing the chain length should lead to smaller oscillations. The keyword pchain specifies the number of thermostats
in the chain thermostatting the barostat degrees of freedom.

Note: There are alternate ways to thermostat a system of rigid bodies. You can use fix langevin to treat the individual
particles in the rigid bodies as effectively immersed in an implicit solvent, e.g. a Brownian dynamics model. For hybrid
systems with both rigid bodies and solvent particles, you can thermostat only the solvent particles that surround one or
more rigid bodies by appropriate choice of groups in the compute and fix commands for temperature and thermostatting.
The solvent interactions with the rigid bodies should then effectively thermostat the rigid body temperature as well
without use of the Langevin or Nose/Hoover options associated with the fix rigid commands.

The mol keyword can only be used with the rigid/small styles. It must be used when other commands, such as fix deposit
or fix pour, add rigid bodies on-the-fly during a simulation. You specify a template-ID previously defined using the

1466 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

molecule command, which reads a file that defines the molecule. You must use the same template-ID that the other
fix which is adding rigid bodies uses. The coordinates, atom types, atom diameters, center-of-mass, and moments of
inertia can be specified in the molecule file. See the molecule command for details. The only settings required to be
in this file are the coordinates and types of atoms in the molecule, in which case the molecule command calculates the
other quantities itself.
Note that these other fixes create new rigid bodies, in addition to those defined initially by this fix via the bodystyle
setting.
Also note that when using the mol keyword, extra restart information about all rigid bodies is written out whenever a
restart file is written out. See the NOTE in the next section for details.

The infile keyword allows a file of rigid body attributes to be read in from a file, rather then having LAMMPS compute
them. There are 5 such attributes: the total mass of the rigid body, its center-of-mass position, its 6 moments of inertia,
its center-of-mass velocity, and the 3 image flags of the center-of-mass position. For rigid bodies consisting of point
particles or non-overlapping finite-size particles, LAMMPS can compute these values accurately. However, for rigid
bodies consisting of finite-size particles which overlap each other, LAMMPS will ignore the overlaps when computing
these 4 attributes. The amount of error this induces depends on the amount of overlap. To avoid this issue, the values
can be pre-computed (e.g. using Monte Carlo integration).
The format of the file is as follows. Note that the file does not have to list attributes for every rigid body integrated
by fix rigid. Only bodies which the file specifies will have their computed attributes overridden. The file can contain
initial blank lines or comment lines starting with “#” which are ignored. The first non-blank, non-comment line should
list N = the number of lines to follow. The N successive lines contain the following information:

ID1 masstotal xcm ycm zcm ixx iyy izz ixy ixz iyz vxcm vycm vzcm lx ly lz ixcm iycm izcm
ID2 masstotal xcm ycm zcm ixx iyy izz ixy ixz iyz vxcm vycm vzcm lx ly lz ixcm iycm izcm
...
IDN masstotal xcm ycm zcm ixx iyy izz ixy ixz iyz vxcm vycm vzcm lx ly lz ixcm iycm izcm

The rigid body IDs are all positive integers. For the single bodystyle, only an ID of 1 can be used. For the group
bodystyle, IDs from 1 to Ng can be used where Ng is the number of specified groups. For the molecule bodystyle, use
the molecule ID for the atoms in a specific rigid body as the rigid body ID.
The masstotal and center-of-mass coordinates (xcm,ycm,zcm) are self-explanatory. The center-of-mass should be con-
sistent with what is calculated for the position of the rigid body with all its atoms unwrapped by their respective image
flags. If this produces a center-of-mass that is outside the simulation box, LAMMPS wraps it back into the box.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the values consistent with the current orientation of the
rigid body around its center of mass. The values are with respect to the simulation box XYZ axes, not with respect to
the principal axes of the rigid body itself. LAMMPS performs the latter calculation internally.
The (vxcm,vycm,vzcm) values are the velocity of the center of mass. The (lx,ly,lz) values are the angular momentum
of the body. The (vxcm,vycm,vzcm) and (lx,ly,lz) values can simply be set to 0 if you wish the body to have no initial
motion.
The (ixcm,iycm,izcm) values are the image flags of the center of mass of the body. For periodic dimensions, they
specify which image of the simulation box the body is considered to be in. An image of 0 means it is inside the box as
defined. A value of 2 means add 2 box lengths to get the true value. A value of -1 means subtract 1 box length to get
the true value. LAMMPS updates these flags as the rigid bodies cross periodic boundaries during the simulation.

Note: If you use the infile or mol keywords and write restart files during a simulation, then each time a restart file
is written, the fix also write an auxiliary restart file with the name rfile.rigid, where “rfile” is the name of the restart
file, e.g. tmp.restart.10000 and tmp.restart.10000.rigid. This auxiliary file is in the same format described above. Thus
it can be used in a new input script that restarts the run and re-specifies a rigid fix using an infile keyword and the

17.179. fix rigid/nph/small command 1467

LAMMPS Documentation, Release stable 29Sep2021

appropriate filename. Note that the auxiliary file will contain one line for every rigid body, even if the original file only
listed a subset of the rigid bodies.

If you use a temperature compute with a group that includes particles in rigid bodies, the degrees-of-freedom removed
by each rigid body are accounted for in the temperature (and pressure) computation, but only if the temperature group
includes all the particles in a particular rigid body.
A 3d rigid body has 6 degrees of freedom (3 translational, 3 rotational), except for a collection of point particles lying
on a straight line, which has only 5, e.g a dimer. A 2d rigid body has 3 degrees of freedom (2 translational, 1 rotational).

Note: You may wish to explicitly subtract additional degrees-of-freedom if you use the force and torque keywords to
eliminate certain motions of one or more rigid bodies. LAMMPS does not do this automatically.

The rigid body contribution to the pressure of the system (virial) is also accounted for by this fix.

If your simulation is a hybrid model with a mixture of rigid bodies and non-rigid particles (e.g. solvent) there are
several ways these rigid fixes can be used in tandem with fix nve, fix nvt, fix npt, and fix nph.
If you wish to perform NVE dynamics (no thermostatting or barostatting), use one of 4 NVE rigid styles to integrate
the rigid bodies, and fix nve to integrate the non-rigid particles.
If you wish to perform NVT dynamics (thermostatting, but no barostatting), you can use one of the 2 NVT rigid styles
for the rigid bodies, and any thermostatting fix for the non-rigid particles (fix nvt, fix langevin, fix temp/berendsen).
You can also use one of the 4 NVE rigid styles for the rigid bodies and thermostat them using fix langevin on the group
that contains all the particles in the rigid bodies. The net force added by fix langevin to each rigid body effectively
thermostats its translational center-of-mass motion. Not sure how well it does at thermostatting its rotational motion.
If you with to perform NPT or NPH dynamics (barostatting), you cannot use both fix npt and the NPT or NPH rigid
styles. This is because there can only be one fix which monitors the global pressure and changes the simulation box
dimensions. So you have 3 choices:
• Use one of the 4 NPT or NPH styles for the rigid bodies. Use the dilate all option so that it will dilate the positions
of the non-rigid particles as well. Use fix nvt (or any other thermostat) for the non-rigid particles.
• Use fix npt for the group of non-rigid particles. Use the dilate all option so that it will dilate the center-of-mass
positions of the rigid bodies as well. Use one of the 4 NVE or 2 NVT rigid styles for the rigid bodies.
• Use fix press/berendsen to compute the pressure and change the box dimensions. Use one of the 4 NVE or 2
NVT rigid styles for the rigid bodies. Use fix nvt (or any other thermostat) for the non-rigid particles.
In all case, the rigid bodies and non-rigid particles both contribute to the global pressure and the box is scaled the same
by any of the barostatting fixes.
You could even use the second and third options for a non-hybrid simulation consisting of only rigid bodies, assuming
you give fix npt an empty group, though it’s an odd thing to do. The barostatting fixes (fix npt and fix press/berensen)
will monitor the pressure and change the box dimensions, but not time integrate any particles. The integration of the
rigid bodies will be performed by fix rigid/nvt.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.

1468 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.179.4 Restart, fix_modify, output, run start/stop, minimize info

No information about the 4 NVE rigid styles is written to binary restart files. The exception is if the infile or mol
keyword is used, in which case an auxiliary file is written out with rigid body information each time a restart file is
written, as explained above for the infile keyword. For the 2 NVT rigid styles, the state of the Nose/Hoover thermostat
is written to binary restart files. Ditto for the 4 NPT and NPH rigid styles, and the state of the Nose/Hoover barostat.
See the read_restart command for info on how to re-specify a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.
The fix_modify temp and press options are supported by the 4 NPT and NPH rigid styles to change the computes used
to calculate the instantaneous pressure tensor. Note that the 2 NVT rigid fixes do not use any external compute to
compute instantaneous temperature.
The fix_modify bodyforces option is supported by all rigid styles to set whether per-body forces and torques are com-
puted early or late in a timestep, i.e. at the post-force stage or at the final-integrate stage or the timestep, respectively.
The cumulative energy change in the system imposed by the 6 NVT, NPT, NPH rigid fixes, via either thermostatting
and/or barostatting, is included in the thermodynamic output keywords ecouple and econserve. See the thermo_style
doc page for details.
The 2 NVE rigid fixes compute a global scalar which can be accessed by various output commands. The scalar value
calculated by these fixes is “intensive”. The scalar is the current temperature of the collection of rigid bodies. This is
averaged over all rigid bodies and their translational and rotational degrees of freedom. The translational energy of a
rigid body is 1/2 m v^2, where m = total mass of the body and v = the velocity of its center of mass. The rotational
energy of a rigid body is 1/2 I w^2, where I = the moment of inertia tensor of the body and w = its angular velocity.
Degrees of freedom constrained by the force and torque keywords are removed from this calculation, but only for the
rigid and rigid/nve fixes.
The 6 NVT, NPT, NPH rigid fixes compute a global scalar which can be accessed by various output commands. The
scalar is the same cumulative energy change due to these fixes described above. The scalar value calculated by this fix
is “extensive”.
The fix_modify virial option is supported by these fixes to add the contribution due to the added forces on atoms to both
the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands.
The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial yes.
All of the rigid styles (not the rigid/small styles) compute a global array of values which can be accessed by various
output commands. Similar information about the bodies defined by the rigid/small styles can be accessed via the
compute rigid/local command.
The number of rows in the array is equal to the number of rigid bodies. The number of columns is 15. Thus for each
rigid body, 15 values are stored: the xyz coords of the center of mass (COM), the xyz components of the COM velocity,
the xyz components of the force acting on the COM, the xyz components of the torque acting on the COM, and the xyz
image flags of the COM.
The center of mass (COM) for each body is similar to unwrapped coordinates written to a dump file. It will always
be inside (or slightly outside) the simulation box. The image flags have the same meaning as image flags for atom
positions (see the “dump” command). This means you can calculate the unwrapped COM by applying the image flags
to the COM, the same as when unwrapped coordinates are written to a dump file.

17.179. fix rigid/nph/small command 1469

LAMMPS Documentation, Release stable 29Sep2021

The force and torque values in the array are not affected by the force and torque keywords in the fix rigid command;
they reflect values before any changes are made by those keywords.
The ordering of the rigid bodies (by row in the array) is as follows. For the single keyword there is just one rigid body.
For the molecule keyword, the bodies are ordered by ascending molecule ID. For the group keyword, the list of group
IDs determines the ordering of bodies.
The array values calculated by these fixes are “intensive”, meaning they are independent of the number of atoms in the
simulation.
No parameter of these fixes can be used with the start/stop keywords of the run command. These fixes are not invoked
during energy minimization.

17.179.5 Restrictions

These fixes are all part of the RIGID package. It is only enabled if LAMMPS was built with that package. See the
Build package page for more info.
Assigning a temperature via the velocity create command to a system with rigid bodies may not have the desired out-
come for two reasons. First, the velocity command can be invoked before the rigid-body fix is invoked or initialized and
the number of adjusted degrees of freedom (DOFs) is known. Thus it is not possible to compute the target temperature
correctly. Second, the assigned velocities may be partially canceled when constraints are first enforced, leading to a
different temperature than desired. A workaround for this is to perform a run 0 command, which insures all DOFs
are accounted for properly, and then rescale the temperature to the desired value before performing a simulation. For
example:

velocity all create 300.0 12345

run 0 # temperature may not be 300K
velocity all scale 300.0 # now it should be

17.179.6 Related commands

delete_bonds, neigh_modify exclude, fix shake

17.179.7 Default

The option defaults are force * on on on and torque * on on on, meaning all rigid bodies are acted on by center-of-mass
force and torque. Also Tchain = Pchain = 10, Titer = 1, Torder = 3, reinit = yes.

(Hoover) Hoover, Phys Rev A, 31, 1695 (1985).

(Kamberaj) Kamberaj, Low, Neal, J Chem Phys, 122, 224114 (2005).
(Martyna) Martyna, Klein, Tuckerman, J Chem Phys, 97, 2635 (1992); Martyna, Tuckerman, Tobias, Klein, Mol Phys,
87, 1117.
(Miller) Miller, Eleftheriou, Pattnaik, Ndirango, and Newns, J Chem Phys, 116, 8649 (2002).
(Zhang) Zhang, Glotzer, Nanoletters, 4, 1407-1413 (2004).

1470 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.180 fix rigid/meso command

17.180.1 Syntax

fix ID group-ID rigid/meso bodystyle args keyword values ...

• ID, group-ID are documented in fix command

• rigid/meso = style name of this fix command
• bodystyle = single or molecule or group
single args = none
molecule args = none
custom args = i_propname or v_varname
i_propname = an integer property defined via fix property/atom
v_varname = an atom-style or atomfile-style variable
group args = N groupID1 groupID2 ...
N = # of groups
groupID1, groupID2, ... = list of N group IDs
• zero or more keyword/value pairs may be appended
• keyword = reinit or force or torque or infile
reinit = yes or no
force values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass force is active
torque values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass torque is active
infile filename
filename = file with per-body values of mass, center-of-mass, moments of inertia

17.180.2 Examples

fix 1 ellipsoid rigid/meso single

fix 1 rods rigid/meso molecule
fix 1 spheres rigid/meso single force 1 off off on
fix 1 particles rigid/meso molecule force 1*5 off off off force 6*10 off off on
fix 2 spheres rigid/meso group 3 sphere1 sphere2 sphere3 torque * off off off

17.180.3 Description

Treat one or more sets of mesoscopic SPH/SDPD particles as independent rigid bodies. This means that each timestep
the total force and torque on each rigid body is computed as the sum of the forces and torques on its constituent particles.
The coordinates and velocities of the particles in each body are then updated so that the body moves and rotates as a
single entity using the methods described in the paper by (Miller). Density and internal energy of the particles will
also be updated. This is implemented by creating internal data structures for each rigid body and performing time
integration on these data structures. Positions and velocities of the constituent particles are regenerated from the rigid
body data structures in every time step. This restricts which operations and fixes can be applied to rigid bodies. See
below for a detailed discussion.

17.180. fix rigid/meso command 1471

LAMMPS Documentation, Release stable 29Sep2021

The operation of this fix is exactly like that described by the fix rigid/nve command, except that particles’ density,
internal energy and extrapolated velocity are also updated.

Note: You should not update the particles in rigid bodies via other time-integration fixes (e.g. fix sph, fix
sph/stationary), or you will have conflicting updates to positions and velocities resulting in unphysical behavior in
most cases. When performing a hybrid simulation with some atoms in rigid bodies, and some not, a separate time
integration fix like fix sph should be used for the non-rigid particles.

Note: These fixes are overkill if you simply want to hold a collection of particles stationary or have them move with a
constant velocity. To hold particles stationary use fix sph/stationary instead. If you would like to move particles with
a constant velocity use fix meso/move.

Warning: The aggregate properties of each rigid body are calculated at the start of a simulation run and are
maintained in internal data structures. The properties include the position and velocity of the center-of-mass of
the body, its moments of inertia, and its angular momentum. This is done using the properties of the constituent
particles of the body at that point in time (or see the infile keyword option). Thereafter, changing these properties of
individual particles in the body will have no effect on a rigid body’s dynamics, unless they effect any computation
of per-particle forces or torques. If the keyword reinit is set to yes (the default), the rigid body data structures will
be recreated at the beginning of each run command; if the keyword reinit is set to no, the rigid body data structures
will be built only at the very first run command and maintained for as long as the rigid fix is defined. For example,
you might think you could displace the particles in a body or add a large velocity to each particle in a body to
make it move in a desired direction before a second run is performed, using the set or displace_atoms or velocity
commands. But these commands will not affect the internal attributes of the body unless reinit is set to yes. With
reinit set to no (or using the infile option, which implies reinit no) the position and velocity of individual particles
in the body will be reset when time integration starts again.

Each rigid body must have two or more particles. A particle can belong to at most one rigid body. Which particles are
in which bodies can be defined via several options.
For bodystyle single the entire fix group of particles is treated as one rigid body.
For bodystyle molecule, particles are grouped into rigid bodies by their respective molecule IDs: each set of particles
in the fix group with the same molecule ID is treated as a different rigid body. Note that particles with a molecule
ID = 0 will be treated as a single rigid body. For a system with solvent (typically this is particles with molecule ID =
0) surrounding rigid bodies, this may not be what you want. Thus you should be careful to use a fix group that only
includes particles you want to be part of rigid bodies.
Bodystyle custom is similar to bodystyle molecule except that it is more flexible in using other per-atom properties to
define the sets of particles that form rigid bodies. An integer vector defined by the fix property/atom command can
be used. Or an atom-style or atomfile-style variable can be used; the floating-point value produced by the variable is
rounded to an integer. As with bodystyle molecule, each set of particles in the fix groups with the same integer value
is treated as a different rigid body. Since fix property/atom vectors and atom-style variables produce values for all
particles, you should be careful to use a fix group that only includes particles you want to be part of rigid bodies.
For bodystyle group, each of the listed groups is treated as a separate rigid body. Only particles that are also in the fix
group are included in each rigid body.

Note: To compute the initial center-of-mass position and other properties of each rigid body, the image flags for each
particle in the body are used to “unwrap” the particle coordinates. Thus you must insure that these image flags are
consistent so that the unwrapping creates a valid rigid body (one where the particles are close together) , particularly

1472 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

if the particles in a single rigid body straddle a periodic boundary. This means the input data file or restart file must
define the image flags for each particle consistently or that you have used the set command to specify them correctly. If
a dimension is non-periodic then the image flag of each particle must be 0 in that dimension, else an error is generated.

By default, each rigid body is acted on by other particles which induce an external force and torque on its center of
mass, causing it to translate and rotate. Components of the external center-of-mass force and torque can be turned off
by the force and torque keywords. This may be useful if you wish a body to rotate but not translate, or vice versa, or
if you wish it to rotate or translate continuously unaffected by interactions with other particles. Note that if you expect
a rigid body not to move or rotate by using these keywords, you must insure its initial center-of-mass translational or
angular velocity is 0.0. Otherwise the initial translational or angular momentum, the body has, will persist.
An xflag, yflag, or zflag set to off means turn off the component of force or torque in that dimension. A setting of on
means turn on the component, which is the default. Which rigid body(s) the settings apply to is determined by the first
argument of the force and torque keywords. It can be an integer M from 1 to Nbody, where Nbody is the number of
rigid bodies defined. A wild-card asterisk can be used in place of, or in conjunction with, the M argument to set the
flags for multiple rigid bodies. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of rigid bodies,
then an asterisk with no numeric values means all bodies from 1 to N. A leading asterisk means all bodies from 1 to n
(inclusive). A trailing asterisk means all bodies from n to N (inclusive). A middle asterisk means all bodies from m to
n (inclusive). Note that you can use the force or torque keywords as many times as you like. If a particular rigid body
has its component flags set multiple times, the settings from the final keyword are used.
For computational efficiency, you should typically define one fix rigid/meso command which includes all the desired
rigid bodies. LAMMPS will allow multiple rigid/meso fixes to be defined, but it is more expensive.

The keyword/value option pairs are used in the following ways.

The reinit keyword determines, whether the rigid body properties are re-initialized between run commands. With the
option yes (the default) this is done, with the option no this is not done. Turning off the re-initialization can be helpful
to protect rigid bodies against unphysical manipulations between runs or when properties cannot be easily re-computed
(e.g. when read from a file). When using the infile keyword, the reinit option is automatically set to no.

The infile keyword allows a file of rigid body attributes to be read in from a file, rather then having LAMMPS compute
them. There are 5 such attributes: the total mass of the rigid body, its center-of-mass position, its 6 moments of inertia,
its center-of-mass velocity, and the 3 image flags of the center-of-mass position. For rigid bodies consisting of point
particles or non-overlapping finite-size particles, LAMMPS can compute these values accurately. However, for rigid
bodies consisting of finite-size particles which overlap each other, LAMMPS will ignore the overlaps when computing
these 4 attributes. The amount of error this induces depends on the amount of overlap. To avoid this issue, the values
can be pre-computed (e.g. using Monte Carlo integration).
The format of the file is as follows. Note that the file does not have to list attributes for every rigid body integrated
by fix rigid. Only bodies which the file specifies will have their computed attributes overridden. The file can contain
initial blank lines or comment lines starting with “#” which are ignored. The first non-blank, non-comment line should
list N = the number of lines to follow. The N successive lines contain the following information:

ID1 masstotal xcm ycm zcm ixx iyy izz ixy ixz iyz vxcm vycm vzcm lx ly lz ixcm iycm izcm
ID2 masstotal xcm ycm zcm ixx iyy izz ixy ixz iyz vxcm vycm vzcm lx ly lz ixcm iycm izcm
...
IDN masstotal xcm ycm zcm ixx iyy izz ixy ixz iyz vxcm vycm vzcm lx ly lz ixcm iycm izcm

The rigid body IDs are all positive integers. For the single bodystyle, only an ID of 1 can be used. For the group
bodystyle, IDs from 1 to Ng can be used where Ng is the number of specified groups. For the molecule bodystyle, use
the molecule ID for the atoms in a specific rigid body as the rigid body ID.

17.180. fix rigid/meso command 1473

LAMMPS Documentation, Release stable 29Sep2021

The masstotal and center-of-mass coordinates (xcm,ycm,zcm) are self-explanatory. The center-of-mass should be con-
sistent with what is calculated for the position of the rigid body with all its atoms unwrapped by their respective image
flags. If this produces a center-of-mass that is outside the simulation box, LAMMPS wraps it back into the box.
The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the values consistent with the current orientation of the
rigid body around its center of mass. The values are with respect to the simulation box XYZ axes, not with respect to
the principal axes of the rigid body itself. LAMMPS performs the latter calculation internally.
The (vxcm,vycm,vzcm) values are the velocity of the center of mass. The (lx,ly,lz) values are the angular momentum
of the body. The (vxcm,vycm,vzcm) and (lx,ly,lz) values can simply be set to 0 if you wish the body to have no initial
motion.
The (ixcm,iycm,izcm) values are the image flags of the center of mass of the body. For periodic dimensions, they
specify which image of the simulation box the body is considered to be in. An image of 0 means it is inside the box as
defined. A value of 2 means add 2 box lengths to get the true value. A value of -1 means subtract 1 box length to get
the true value. LAMMPS updates these flags as the rigid bodies cross periodic boundaries during the simulation.

Note: If you use the infile keyword and write restart files during a simulation, then each time a restart file is written,
the fix also write an auxiliary restart file with the name rfile.rigid, where “rfile” is the name of the restart file, e.g.
tmp.restart.10000 and tmp.restart.10000.rigid. This auxiliary file is in the same format described above. Thus it can
be used in a new input script that restarts the run and re-specifies a rigid fix using an infile keyword and the appropriate
filename. Note that the auxiliary file will contain one line for every rigid body, even if the original file only listed a
subset of the rigid bodies.

17.180.4 Restart, fix_modify, output, run start/stop, minimize info

No information is written to binary restart files. If the infile keyword is used, an auxiliary file is written out with rigid
body information each time a restart file is written, as explained above for the infile keyword.
None of the fix_modify options are relevant to this fix.
This fix computes a global array of values which can be accessed by various output commands.
The number of rows in the array is equal to the number of rigid bodies. The number of columns is 28. Thus for each rigid
body, 28 values are stored: the xyz coords of the center of mass (COM), the xyz components of the COM velocity, the
xyz components of the force acting on the COM, the components of the 4-vector quaternion representing the orientation
of the rigid body, the xyz components of the angular velocity of the body around its COM, the xyz components of the
torque acting on the COM, the 3 principal components of the moment of inertia, the xyz components of the angular
momentum of the body around its COM, and the xyz image flags of the COM.
The center of mass (COM) for each body is similar to unwrapped coordinates written to a dump file. It will always
be inside (or slightly outside) the simulation box. The image flags have the same meaning as image flags for particle
positions (see the “dump” command). This means you can calculate the unwrapped COM by applying the image flags
to the COM, the same as when unwrapped coordinates are written to a dump file.
The force and torque values in the array are not affected by the force and torque keywords in the fix rigid command;
they reflect values before any changes are made by those keywords.
The ordering of the rigid bodies (by row in the array) is as follows. For the single keyword there is just one rigid body.
For the molecule keyword, the bodies are ordered by ascending molecule ID. For the group keyword, the list of group
IDs determines the ordering of bodies.
The array values calculated by this fix are “intensive”, meaning they are independent of the number of particles in the
simulation.
No parameter of this fix can be used with the start/stop keywords of the run command.

1474 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

This fix is not invoked during energy minimization.

17.180.5 Restrictions

This fix is part of the DPD-SMOOTH package and also depends on the RIGID package. It is only enabled if LAMMPS
was built with both packages. See the Build package page for more info.
This fix requires that atoms store density and internal energy as defined by the atom_style sph command.
All particles in the group must be mesoscopic SPH/SDPD particles.

17.180.6 Related commands

fix meso/move, fix rigid, neigh_modify exclude

17.180.7 Default

The option defaults are force * on on on and torque * on on on, meaning all rigid bodies are acted on by center-of-mass
force and torque. Also reinit = yes.

(Miller) Miller, Eleftheriou, Pattnaik, Ndirango, and Newns, J Chem Phys, 116, 8649 (2002).

17.181 fix rx command

Accelerator Variants: rx/kk

17.181.1 Syntax

fix ID group-ID rx file localTemp matrix solver minSteps ...

• ID, group-ID are documented in fix command

• rx = style name of this fix command
• file = filename containing the reaction kinetic equations and Arrhenius parameters
• localTemp = none,lucy = no local temperature averaging or local temperature defined through Lucy weighting
function
• matrix = sparse, dense format for the stoichiometric matrix
• solver = lammps_rk4,rkf45 = rk4 is an explicit fourth order Runge-Kutta method; rkf45 is an adaptive fourth-order
Runge-Kutta-Fehlberg method
• minSteps = # of steps for rk4 solver or minimum # of steps for rkf45 (rk4 or rkf45)
• maxSteps = maximum number of steps for the rkf45 solver (rkf45 only)
• relTol = relative tolerance for the rkf45 solver (rkf45 only)
• absTol = absolute tolerance for the rkf45 solver (rkf45 only)
• diag = Diagnostics frequency for the rkf45 solver (optional, rkf45 only)

17.181. fix rx command 1475

LAMMPS Documentation, Release stable 29Sep2021

17.181.2 Examples

fix 1 all rx kinetics.rx none dense lammps_rk4

fix 1 all rx kinetics.rx none sparse lammps_rk4 1
fix 1 all rx kinetics.rx lucy sparse lammps_rk4 10
fix 1 all rx kinetics.rx none dense rkf45 1 100 1e-6 1e-8
fix 1 all rx kinetics.rx none dense rkf45 1 100 1e-6 1e-8 -1

17.181.3 Description

Fix rx solves the reaction kinetic ODEs for a given reaction set that is defined within the file associated with this
command.
For a general reaction such that

νA A + νB B → νC C

the reaction rate equation is defined to be of the form

r = k(T )[A]νA [B]νB

In the current implementation, the exponents are defined to be equal to the stoichiometric coefficients. A given reaction
set consisting of n reaction equations will contain a total of m species. A set of m ordinary differential equations (ODEs)
that describe the change in concentration of a given species as a function of time are then constructed based on the n
reaction rate equations.
The ODE systems are solved over the full DPD timestep dt using either a fourth order Runge-Kutta rk4 method with a
fixed step-size h, specified by the lammps_rk4 keyword, or a fourth order Runge-Kutta-Fehlberg (rkf45) method with
an adaptive step-size for h. The number of ODE steps per DPD timestep for the rk4 method is optionally specified
immediately after the rk4 keyword. The ODE step-size is set as dt/num_steps. Smaller step-sizes tend to yield more
accurate results but there is not control on the error. For error control, use the rkf45 ODE solver.
The rkf45 method adjusts the step-size so that the local truncation error is held within the specified absolute and
relative tolerances. The initial step-size h0 can be specified by the user or estimated internally. It is recommended that
the user specify h0 since this will generally reduced the number of ODE integration steps required. h0 is defined as dt /
min_steps if min_steps >= 1. If min_steps == 0, h0 is estimated such that an explicit Euler method would likely produce
an acceptable solution. This is generally overly conservative for the fourth-order method and users are advised to specify
h0 as some fraction of the DPD timestep. For small DPD timesteps, only one step may be necessary depending upon
the tolerances. Note that more than min_steps ODE steps may be taken depending upon the ODE stiffness but no more
than max_steps will be taken. If max_steps is reached, an error warning is printed and the simulation is stopped.
After each ODE step, the solution error e is tested and weighted using the absTol and relTol values. The error vector
is weighted as e / (relTol * |u| + absTol) where u is the solution vector. If the norm of the error is <= 1, the solution
is accepted, h is increased by a proportional amount, and the next ODE step is begun. Otherwise, h is shrunk and the
ODE step is repeated.
Run-time diagnostics are available for the rkf45 ODE solver. The frequency (in timesteps) that diagnostics are reported
is controlled by the last (optional) 12th argument. A negative frequency means that diagnostics are reported once at
the end of each run. A positive value N means that the diagnostics are reported once per N timesteps.
The diagnostics report the average # of integrator steps and RHS function evaluations and run-time per ODE as well as
the average/RMS/min/max per process. If the reporting frequency is 1, the RMS/min/max per ODE are also reported.
The per ODE statistics can be used to adjust the tolerance and min/max step parameters. The statistics per MPI process
can be useful to examine any load imbalance caused by the adaptive ODE solver. (Some DPD particles can take longer
to solve than others. This can lead to an imbalance across the MPI processes.)

1476 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

The filename specifies a file that contains the entire set of reaction kinetic equations and corresponding Arrhenius
parameters. The format of this file is described below.
There is no restriction on the total number or reaction equations that are specified. The species names are arbitrary string
names that are associated with the species concentrations. Each species in a given reaction must be preceded by it’s
stoichiometric coefficient. The only delimiters that are recognized between the species are either a + or = character.
The = character corresponds to an irreversible reaction. After specifying the reaction, the reaction rate constant is
determined through the temperature dependent Arrhenius equation:
−Ea
k = AT n e kB T

where A is the Arrhenius factor in time units or concentration/time units, n is the unitless exponent of the temperature
dependence, and Ea is the activation energy in energy units. The temperature dependence can be removed by specifying
the exponent as zero.
The internal temperature of the coarse-grained particles can be used in constructing the reaction rate constants at every
DPD timestep by specifying the keyword none. Alternatively, the keyword lucy can be specified to compute a local-
average particle internal temperature for use in the reaction rate constant expressions. The local-average particle internal
temperature is defined as:
P −1
−1 j=1 ωLucy (rij ) θj
θi = P
j=1 ωLucy (rij )

where the Lucy function is expressed as:

  3
3rij rij
ωLucy (rij ) = 1+ 1−
rc rc
The self-particle interaction is included in the above equation.
The stoichiometric coefficients for the reaction mechanism are stored in either a sparse or dense matrix format. The
dense matrix should only be used for small reaction mechanisms. The sparse matrix should be used when there are many
reactions (e.g., more than 5). This allows the number of reactions and species to grow while keeping the computational
cost tractable. The matrix format can be specified as using either the sparse or dense keywords. If all stoichiometric
coefficients for a reaction are small integers (whole numbers <= 3), a fast exponential function is used. This can save
significant computational time so users are encouraged to use integer coefficients where possible.

The format of a tabulated file is as follows (without the parenthesized comments):

# Rxn equations and parameters (one or␣

,→more comment or blank lines)

1.0 hcn + 1.0 no2 = 1.0 no + 0.5 n2 + 0.5 h2 + 1.0 co 2.49E+01 0.0 1.34 (rxn␣
,→equation, A, n, Ea)
1.0 hcn + 1.0 no = 1.0 co + 1.0 n2 + 0.5 h2 2.16E+00 0.0 1.52
...
1.0 no + 1.0 co = 0.5 n2 + 1.0 co2 1.66E+06 0.0 0.69

A section begins with a non-blank line whose first character is not a “#”; blank lines or lines starting with “#” can be
used as comments between sections.
Following a blank line, the next N lines list the N reaction equations. Each species within the reaction equation is
specified through its stoichiometric coefficient and a species tag. Reactant species are specified on the left-hand side of
the equation and product species are specified on the right-hand side of the equation. After specifying the reactant and
product species, the final three arguments of each line represent the Arrhenius parameter A, the temperature exponent
n, and the activation energy Ea.

17.181. fix rx command 1477

LAMMPS Documentation, Release stable 29Sep2021

Note that the species tags that are defined in the reaction equations are used by the fix eos/table/rx command to define
the thermodynamic properties of each species. Furthermore, the number of species molecules (i.e., concentration) can
be specified either with the set command using the “d_” prefix or by reading directly the concentrations from a data
file. For the latter case, the read_data command with the fix keyword should be specified, where the fix-ID will be the
“fix rx`ID with a <SPECIES”>`_ suffix, e.g.
fix foo all rx reaction.file . . . read_data data.dpd fix foo_SPECIES NULL Species

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.181.4 Restrictions

This command is part of the DPD-REACT package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info.
This command also requires use of the atom_style dpd command.
This command can only be used with a constant energy or constant enthalpy DPD simulation.

17.181.5 Related commands

fix eos/table/rx, fix shardlow, pair dpd/fdt/energy

17.181.6 Default

none

17.182 fix saed/vtk command

17.182.1 Syntax

fix ID group-ID saed/vtk Nevery Nrepeat Nfreak c_ID attribute args ... keyword args ...

• ID, group-ID are documented in fix command

• saed/vtk = style name of this fix command
• Nevery = use input values every this many timesteps
• Nrepeat = # of times to use input values for calculating averages

1478 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

• Nfreq = calculate averages every this many timesteps

• c_ID = saed compute ID
keyword = file or ave or start or file or overwrite:l
ave args = one or running or window M
one = output a new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
start args = Nstart
Nstart = start averaging on this timestep
file arg = filename
filename = name of file to output time averages to
overwrite arg = none = overwrite output file with only latest output

17.182.2 Examples

compute 1 all saed 0.0251 Al O Kmax 1.70 Zone 0 0 1 dR_Ewald 0.01 c 0.5 0.5 0.5
compute 2 all saed 0.0251 Ni Kmax 1.70 Zone 0 0 0 c 0.05 0.05 0.05 manual echo

fix 1 all saed/vtk 1 1 1 c_1 file Al2O3_001.saed

fix 2 all saed/vtk 1 1 1 c_2 file Ni_000.saed

17.182.3 Description

Time average computed intensities from compute saed and write output to a file in the third generation vtk image data
format for visualization directly in parallelized visualization software packages like ParaView and VisIt. Note that if
no time averaging is done, this command can be used as a convenient way to simply output diffraction intensities at a
single snapshot.
To produce output in the image data vtk format ghost data is added outside the Kmax range assigned in the compute saed.
The ghost data is assigned a value of -1 and can be removed setting a minimum isovolume of 0 within the visualization
software. SAED images can be created by visualizing a spherical slice of the data that is centered at R_Ewald*[h k
l]/norm([h k l]), where R_Ewald=1/lambda.
The group specified within this command is ignored. However, note that specified values may represent calculations
performed by saed computes which store their own “group” definitions.
Fix saed/vtk is designed to work only with compute saed values, e.g.

compute 3 top saed 0.0251 Al O

fix saed/vtk 1 1 1 c_3 file Al2O3_001.saed

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the input values will be used in order to contribute
to the average. The final averaged quantities are generated on timesteps that are a multiple of Nfreq. The average is
over Nrepeat quantities, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a
multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the average
value cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on timesteps 90,92,94,96,98,100 will be used to
compute the final average on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on timestep 200, etc. If
Nrepeat=1 and Nfreq = 100, then no time averaging is done; values are simply generated on timesteps 100,200,etc.

17.182. fix saed/vtk command 1479

LAMMPS Documentation, Release stable 29Sep2021

The output for fix ave/time/saed is a file written with the third generation vtk image data formatting. The filename
assigned by the file keyword is appended with _N.vtk where N is an index (0,1,2. . . ) to account for multiple diffraction
intensity outputs.
By default the header contains the following information (with example data):

# vtk DataFile Version 3.0 c_SAED

Image data set
ASCII
DATASET STRUCTURED_POINTS
DIMENSIONS 337 219 209
ASPECT_RATIO 0.00507953 0.00785161 0.00821458
ORIGIN -0.853361 -0.855826 -0.854316
POINT_DATA 15424827
SCALARS intensity float
LOOKUP_TABLE default
...data

In this example, kspace is sampled across a 337 x 219 x 209 point mesh where the mesh spacing is approximately
0.005, 0.007, and 0.008 inv(length) units in the k1, k2, and k3 directions, respectively. The data is shifted by -0.85,
-0.85, -0.85 inv(length) units so that the origin will lie at 0, 0, 0. Here, 15,424,827 kspace points are sampled in total.

Additional optional keywords also affect the operation of this fix.

The ave keyword determines how the values produced every Nfreq steps are averaged with values produced on previous
steps that were multiples of Nfreq, before they are accessed by another output command or written to a file.
If the ave setting is one, then the values produced on timesteps that are multiples of Nfreq are independent of each
other; they are output as-is without further averaging.
If the ave setting is running, then the values produced on timesteps that are multiples of Nfreq are summed and averaged
in a cumulative sense before being output. Each output value is thus the average of the value produced on that timestep
with all preceding values. This running average begins when the fix is defined; it can only be restarted by deleting the
fix via the unfix command, or by re-defining the fix by re-specifying it.
If the ave setting is window, then the values produced on timesteps that are multiples of Nfreq are summed and averaged
within a moving “window” of time, so that the last M values are used to produce the output. E.g. if M = 3 and Nfreq
= 1000, then the output on step 10000 will be the average of the individual values on steps 8000,9000,10000. Outputs
on early steps will average over less than M values if they are not available.
The start keyword specifies what timestep averaging will begin on. The default is step 0. Often input values can be 0.0
at time 0, so setting start to a larger value can avoid including a 0.0 in a running or windowed average.
The file keyword allows a filename to be specified. Every Nfreq steps, the vector of saed intensity data is written to
a new file using the third generation vtk format. The base of each file is assigned by the file keyword and this string
is appended with _N.vtk where N is an index (0,1,2. . . ) to account for situations with multiple diffraction intensity
outputs.
The overwrite keyword will continuously overwrite the output file with the latest output, so that it only contains one
timestep worth of output. This option can only be used with the ave running setting.

1480 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.182.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.182.5 Restrictions

The attributes for fix_saed_vtk must match the values assigned in the associated compute_saed command.

17.182.6 Related commands

compute_saed

17.182.7 Default

The option defaults are ave = one, start = 0, no file output.

(Coleman) Coleman, Spearot, Capolungo, MSMSE, 21, 055020 (2013).

17.183 fix setforce command

Accelerator Variants: setforce/kk

17.184 fix setforce/spin command

17.184.1 Syntax

fix ID group-ID setforce fx fy fz keyword value ...

• ID, group-ID are documented in fix command

• setforce = style name of this fix command
• fx,fy,fz = force component values
• any of fx,fy,fz can be a variable (see below)
• zero or more keyword/value pairs may be appended to args
• keyword = region
region value = region-ID
region-ID = ID of region atoms must be in to have added force

17.183. fix setforce command 1481

LAMMPS Documentation, Release stable 29Sep2021

17.184.2 Examples

fix freeze indenter setforce 0.0 0.0 0.0

fix 2 edge setforce NULL 0.0 0.0
fix 1 edge setforce/spin 0.0 0.0 0.0
fix 2 edge setforce NULL 0.0 v_oscillate

17.184.3 Description

Set each component of force on each atom in the group to the specified values fx,fy,fz. This erases all previously
computed forces on the atom, though additional fixes could add new forces. This command can be used to freeze certain
atoms in the simulation by zeroing their force, either for running dynamics or performing an energy minimization. For
dynamics, this assumes their initial velocity is also zero.
Any of the fx,fy,fz values can be specified as NULL which means do not alter the force component in that dimension.
Any of the 3 quantities defining the force components can be specified as an equal-style or atom-style variable, namely
fx, fy, fz. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the
variable will be evaluated each timestep, and its value used to determine the force component.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command
keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent
force field.
Atom-style variables can specify the same formulas as equal-style variables but can also include per-atom values, such
as atom coordinates. Thus it is easy to specify a spatially-dependent force field with optional time-dependence as well.
If the region keyword is used, the atom must also be in the specified geometric region in order to have force added to
it.

Style spin suffix sets the components of the magnetic precession vectors instead of the mechanical forces. This also
erases all previously computed magnetic precession vectors on the atom, though additional magnetic fixes could add
new forces.
This command can be used to freeze the magnetic moment of certain atoms in the simulation by zeroing their precession
vector.
All options defined above remain valid, they just apply to the magnetic precession vectors instead of the forces.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
The region keyword is also supported by Kokkos, but a Kokkos-enabled region must be used. See the region region
command for more information.
These accelerated styles are part of the r Kokkos package. They are only enabled if LAMMPS was built with that
package. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

1482 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.184.4 Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files.

The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is setting the forces to the desired values; on all other levels, the force is set to 0.0 for the atoms in the fix group, so that
setforce values are not counted multiple times. Default is to to override forces at the outermost level.
This fix computes a global 3-vector of forces, which can be accessed by various output commands. This is the total
force on the group of atoms before the forces on individual atoms are changed by the fix. The vector values calculated
by this fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize command, but you
cannot set forces to any value besides zero when performing a minimization. Use the fix addforce command if you
want to apply a non-zero force to atoms during a minimization.

17.184.5 Restrictions

The fix setforce/spin only makes sense when LAMMPS was built with the SPIN package.

17.184.6 Related commands

fix addforce, fix aveforce

17.184.7 Default

none

17.185 fix shake command

Accelerator Variants: shake/kk

17.186 fix rattle command

17.186.1 Syntax

fix ID group-ID style tol iter N constraint values ... keyword value ...

• ID, group-ID are documented in fix command

• style = shake or rattle = style name of this fix command
• tol = accuracy tolerance of SHAKE solution
• iter = max # of iterations in each SHAKE solution
• N = print SHAKE statistics every this many timesteps (0 = never)
• one or more constraint/value pairs are appended

17.185. fix shake command 1483

LAMMPS Documentation, Release stable 29Sep2021

• constraint = b or a or t or m
b values = one or more bond types
a values = one or more angle types
t values = one or more atom types
m value = one or more mass values
• zero or more keyword/value pairs may be appended
• keyword = mol
mol value = template-ID
template-ID = ID of molecule template specified in a separate molecule command

17.186.2 Examples

fix 1 sub shake 0.0001 20 10 b 4 19 a 3 5 2

fix 1 sub shake 0.0001 20 10 t 5 6 m 1.0 a 31
fix 1 sub shake 0.0001 20 10 t 5 6 m 1.0 a 31 mol myMol
fix 1 sub rattle 0.0001 20 10 t 5 6 m 1.0 a 31
fix 1 sub rattle 0.0001 20 10 t 5 6 m 1.0 a 31 mol myMol

17.186.3 Description

Apply bond and angle constraints to specified bonds and angles in the simulation by either the SHAKE or RATTLE
algorithms. This typically enables a longer timestep.
SHAKE vs RATTLE:
The SHAKE algorithm was invented for schemes such as standard Verlet timestepping, where only the coordinates
are integrated and the velocities are approximated as finite differences to the trajectories (Ryckaert et al. (1977)). If
the velocities are integrated explicitly, as with velocity Verlet which is what LAMMPS uses as an integration method,
a second set of constraining forces is required in order to eliminate velocity components along the bonds (Andersen
(1983)).
In order to formulate individual constraints for SHAKE and RATTLE, focus on a single molecule whose bonds are
constrained. Let Ri and Vi be the position and velocity of atom i at time n, for i =1,. . . ,N, where N is the number of
sites of our reference molecule. The distance vector between sites i and j is given by

rn+1
ij = rnj − rni

The constraints can then be formulated as

rn+1
ij · rn+1
ij = d2ij and
n+1
vij · rn+1
ij =0

The SHAKE algorithm satisfies the first condition, i.e. the sites at time n+1 will have the desired separations Dij
immediately after the coordinates are integrated. If we also enforce the second condition, the velocity components
along the bonds will vanish. RATTLE satisfies both conditions. As implemented in LAMMPS, fix rattle uses fix shake
for satisfying the coordinate constraints. Therefore the settings and optional keywords are the same for both fixes, and
all the information below about SHAKE is also relevant for RATTLE.
SHAKE:
Each timestep the specified bonds and angles are reset to their equilibrium lengths and angular values via the SHAKE
algorithm (Ryckaert et al. (1977)). This is done by applying an additional constraint force so that the new positions

1484 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

preserve the desired atom separations. The equations for the additional force are solved via an iterative method that
typically converges to an accurate solution in a few iterations. The desired tolerance (e.g. 1.0e-4 = 1 part in 10000)
and maximum # of iterations are specified as arguments. Setting the N argument will print statistics to the screen and
log file about regarding the lengths of bonds and angles that are being constrained. Small delta values mean SHAKE
is doing a good job.
In LAMMPS, only small clusters of atoms can be constrained. This is so the constraint calculation for a cluster can be
performed by a single processor, to enable good parallel performance. A cluster is defined as a central atom connected
to others in the cluster by constrained bonds. LAMMPS allows for the following kinds of clusters to be constrained:
one central atom bonded to 1 or 2 or 3 atoms, or one central atom bonded to 2 others and the angle between the 3
atoms also constrained. This means water molecules or CH2 or CH3 groups may be constrained, but not all the C-C
backbone bonds of a long polymer chain.
The b constraint lists bond types that will be constrained. The t constraint lists atom types. All bonds connected to
an atom of the specified type will be constrained. The m constraint lists atom masses. All bonds connected to atoms
of the specified masses will be constrained (within a fudge factor of MASSDELTA specified in fix_shake.cpp). The a
constraint lists angle types. If both bonds in the angle are constrained then the angle will also be constrained if its type
is in the list.
For all constraints, a particular bond is only constrained if both atoms in the bond are in the group specified with the
SHAKE fix.
The degrees-of-freedom removed by SHAKE bonds and angles are accounted for in temperature and pressure compu-
tations. Similarly, the SHAKE contribution to the pressure of the system (virial) is also accounted for.

Note: This command works by using the current forces on atoms to calculate an additional constraint force which
when added will leave the atoms in positions that satisfy the SHAKE constraints (e.g. bond length) after the next time
integration step. If you define fixes (e.g. fix efield) that add additional force to the atoms after fix shake operates, then
this fix will not take them into account and the time integration will typically not satisfy the SHAKE constraints. The
solution for this is to make sure that fix shake is defined in your input script after any other fixes which add or change
forces (to atoms that fix shake operates on).

The mol keyword should be used when other commands, such as fix deposit or fix pour, add molecules on-the-fly during
a simulation, and you wish to constrain the new molecules via SHAKE. You specify a template-ID previously defined
using the molecule command, which reads a file that defines the molecule. You must use the same template-ID that
the command adding molecules uses. The coordinates, atom types, special bond restrictions, and SHAKE info can be
specified in the molecule file. See the molecule command for details. The only settings required to be in this file (by
this command) are the SHAKE info of atoms in the molecule.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

RATTLE:

17.186. fix rattle command 1485

LAMMPS Documentation, Release stable 29Sep2021

The velocity constraints lead to a linear system of equations which can be solved analytically. The implementation of
the algorithm in LAMMPS closely follows (Andersen (1983)).

Note: The fix rattle command modifies forces and velocities and thus should be defined after all other integration fixes
in your input script. If you define other fixes that modify velocities or forces after fix rattle operates, then fix rattle will
not take them into account and the overall time integration will typically not satisfy the RATTLE constraints. You can
check whether the constraints work correctly by setting the value of RATTLE_DEBUG in src/fix_rattle.cpp to 1 and
recompiling LAMMPS.

17.186.4 Restart, fix_modify, output, run start/stop, minimize info

No information about these fixes is written to binary restart files.

The fix_modify virial option is supported by these fixes to add the contribution due to the added forces on atoms to both
the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands.
The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial yes.
No global or per-atom quantities are stored by these fixes for access by various output commands. No parameter of
these fixes can be used with the start/stop keywords of the run command. These fixes are not invoked during energy
minimization.

17.186.5 Restrictions

These fixes are part of the RIGID package. They are only enabled if LAMMPS was built with that package. See the
Build package page for more info.
For computational efficiency, there can only be one shake or rattle fix defined in a simulation.
If you use a tolerance that is too large or a max-iteration count that is too small, the constraints will not be enforced
very strongly, which can lead to poor energy conservation. You can test for this in your system by running a constant
NVE simulation with a particular set of SHAKE parameters and monitoring the energy versus time.
SHAKE or RATTLE should not be used to constrain an angle at 180 degrees (e.g. linear CO2 molecule). This causes
numeric difficulties. You can use fix rigid or fix rigid/small instead to make a linear molecule rigid.

17.186.6 Related commands

none

17.186.7 Default

none

(Ryckaert) J.-P. Ryckaert, G. Ciccotti and H. J. C. Berendsen, J of Comp Phys, 23, 327-341 (1977).
(Andersen) H. Andersen, J of Comp Phys, 52, 24-34 (1983).

1486 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.187 fix shardlow command

Accelerator Variants: shardlow/kk

17.187.1 Syntax

fix ID group-ID shardlow

• ID, group-ID are documented in fix command

• shardlow = style name of this fix command

17.187.2 Examples

fix 1 all shardlow

17.187.3 Description

Specifies that the Shardlow splitting algorithm (SSA) is to be used to integrate the DPD equations of motion. The
SSA splits the integration into a stochastic and deterministic integration step. The fix shardlow performs the stochastic
integration step and must be used in conjunction with a deterministic integrator (e.g. fix nve or fix nph). The stochastic
integration of the dissipative and random forces is performed prior to the deterministic integration of the conservative
force. Further details regarding the method are provided in (Lisal) and (Larentzos1).
The fix shardlow must be used with the pair_style dpd/fdt or pair_style dpd/fdt/energy command to properly initialize
the fluctuation-dissipation theorem parameter(s) sigma (and kappa, if necessary).
Note that numerous variants of DPD can be specified by choosing an appropriate combination of the integrator and
pair_style dpd/fdt command. DPD under isothermal conditions can be specified by using fix shardlow, fix nve and
pair_style dpd/fdt. DPD under isoenergetic conditions can be specified by using fix shardlow, fix nve and pair_style
dpd/fdt/energy. DPD under isobaric conditions can be specified by using fix shardlow, fix nph and pair_style dpd/fdt.
DPD under isoenthalpic conditions can be specified by using fix shardlow, fix nph and pair_style dpd/fdt/energy. Ex-
amples of each DPD variant are provided in the examples/PACKAGES/dpd-react directory.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available hardware, as discussed on the Speed packages doc
page. The accelerated styles take the same arguments and should produce the same results, except for round-off and
precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP and OPT packages, respectively. They are
only enabled if LAMMPS was built with those packages. See the Build package page for more info.
You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix
command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.
See the Speed packages page for more instructions on how to use the accelerated styles effectively.

17.187. fix shardlow command 1487

LAMMPS Documentation, Release stable 29Sep2021

17.187.4 Restrictions

This command is part of the DPD-REACT package. It is only enabled if LAMMPS was built with that package. See
the Build package page for more info.
This fix is currently limited to orthogonal simulation cell geometries.
This fix must be used with an additional fix that specifies time integration, e.g. fix nve or fix nph.
The Shardlow splitting algorithm requires the sizes of the sub-domain lengths to be larger than twice the cutoff+skin.
Generally, the domain decomposition is dependent on the number of processors requested.

17.187.5 Related commands

pair_style dpd/fdt, fix eos/cv

17.187.6 Default

none

(Lisal) M. Lisal, J.K. Brennan, J. Bonet Avalos, “Dissipative particle dynamics as isothermal, isobaric, isoenergetic,
and isoenthalpic conditions using Shardlow-like splitting algorithms.”, J. Chem. Phys., 135, 204105 (2011).
(Larentzos1) J.P. Larentzos, J.K. Brennan, J.D. Moore, M. Lisal and W.D. Mattson, “Parallel Implementation of
Isothermal and Isoenergetic Dissipative Particle Dynamics Using Shardlow-Like Splitting Algorithms”, Comput. Phys.
Commun., 185, 1987-1998 (2014).
(Larentzos2) J.P. Larentzos, J.K. Brennan, J.D. Moore, and W.D. Mattson, “LAMMPS Implementation of Constant
Energy Dissipative Particle Dynamics (DPD-E)”, ARL-TR-6863, U.S. Army Research Laboratory, Aberdeen Proving
Ground, MD (2014).

17.188 fix smd command

17.188.1 Syntax

fix ID group-ID smd type values keyword values

• ID, group-ID are documented in fix command

• smd = style name of this fix command
• mode = cvel or cfor to select constant velocity or constant force SMD
cvel values = K vel
K = spring constant (force/distance units)
vel = velocity of pulling (distance/time units)
cfor values = force
force = pulling force (force units)
• keyword = tether or couple

1488 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

tether values = x y z R0
x,y,z = point to which spring is tethered
R0 = distance of end of spring from tether point (distance units)
couple values = group-ID2 x y z R0
group-ID2 = 2nd group to couple to fix group with a spring
x,y,z = direction of spring, automatically computed with 'auto'
R0 = distance of end of spring (distance units)

17.188.2 Examples

fix pull cterm smd cvel 20.0 -0.00005 tether NULL NULL 100.0 0.0
fix pull cterm smd cvel 20.0 -0.0001 tether 25.0 25 25.0 0.0
fix stretch cterm smd cvel 20.0 0.0001 couple nterm auto auto auto 0.0
fix pull cterm smd cfor 5.0 tether 25.0 25.0 25.0 0.0

17.188.3 Description

This fix implements several options of steered MD (SMD) as reviewed in (Izrailev), which allows to induce conforma-
tional changes in systems and to compute the potential of mean force (PMF) along the assumed reaction coordinate
(Park) based on Jarzynski’s equality (Jarzynski). This fix borrows a lot from fix spring and fix setforce.
You can apply a moving spring force to a group of atoms (tether style) or between two groups of atoms (couple style).
The spring can then be used in either constant velocity (cvel) mode or in constant force (cfor) mode to induce transitions
in your systems. When running in tether style, you may need some way to fix some other part of the system (e.g. via
fix spring/self )
The tether style attaches a spring between a point at a distance of R0 away from a fixed point x,y,z and the center of
mass of the fix group of atoms. A restoring force of magnitude K (R - R0) Mi / M is applied to each atom in the group
where K is the spring constant, Mi is the mass of the atom, and M is the total mass of all atoms in the group. Note that
K thus represents the total force on the group of atoms, not a per-atom force.
In cvel mode the distance R is incremented or decremented monotonously according to the pulling (or pushing) velocity.
In cfor mode a constant force is added and the actual distance in direction of the spring is recorded.
The couple style links two groups of atoms together. The first group is the fix group; the second is specified by group-
ID2. The groups are coupled together by a spring that is at equilibrium when the two groups are displaced by a vector
in direction x,y,z with respect to each other and at a distance R0 from that displacement. Note that x,y,z only provides a
direction and will be internally normalized. But since it represents the absolute displacement of group-ID2 relative to
the fix group, (1,1,0) is a different spring than (-1,-1,0). For each vector component, the displacement can be described
with the auto parameter. In this case the direction is re-computed in every step, which can be useful for steering a local
process where the whole object undergoes some other change. When the relative positions and distance between the
two groups are not in equilibrium, the same spring force described above is applied to atoms in each of the two groups.
For both the tether and couple styles, any of the x,y,z values can be specified as NULL which means do not include
that dimension in the distance calculation or force application.
For constant velocity pulling (cvel mode), the running integral over the pulling force in direction of the spring is recorded
and can then later be used to compute the potential of mean force (PMF) by averaging over multiple independent
trajectories along the same pulling path.

17.188. fix smd command 1489

LAMMPS Documentation, Release stable 29Sep2021

17.188.4 Restart, fix_modify, output, run start/stop, minimize info

The fix stores the direction of the spring, current pulling target distance and the running PMF to binary restart files.
See the read_restart command for info on how to re-specify a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.
The fix_modify virial option is supported by this fix to add the contribution due to the added forces on atoms to both
the global pressure and per-atom stress of the system via the compute pressure and compute stress/atom commands.
The former can be accessed by thermodynamic output. The default setting for this fix is fix_modify virial no.
The fix_modify respa option is supported by this fix. This allows to set at which level of the r-RESPA integrator the fix
is adding its forces. Default is the outermost level.
This fix computes a vector list of 7 quantities, which can be accessed by various output commands. The quantities in
the vector are in this order: the x-, y-, and z-component of the pulling force, the total force in direction of the pull,
the equilibrium distance of the spring, the distance between the two reference points, and finally the accumulated PMF
(the sum of pulling forces times displacement).
The force is the total force on the group of atoms by the spring. In the case of the couple style, it is the force on the fix
group (group-ID) or the negative of the force on the second group (group-ID2). The vector values calculated by this
fix are “extensive”.
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during
energy minimization.

17.188.5 Restrictions

This fix is part of the MISC package. It is only enabled if LAMMPS was built with that package. See the Build package
page for more info.

17.188.6 Related commands

fix drag, fix spring, fix spring/self , fix spring/rg, fix colvars, fix plumed

17.188.7 Default

none

(Izrailev) Izrailev, Stepaniants, Isralewitz, Kosztin, Lu, Molnar, Wriggers, Schulten. Computational Molecular Dy-
namics: Challenges, Methods, Ideas, volume 4 of Lecture Notes in Computational Science and Engineering, pp. 39-65.
Springer-Verlag, Berlin, 1998.
(Park) Park, Schulten, J. Chem. Phys. 120 (13), 5946 (2004)
(Jarzynski) Jarzynski, Phys. Rev. Lett. 78, 2690 (1997)

1490 Chapter 17. Fixes

 LAMMPS Documentation, Release stable 29Sep2021

17.189 fix smd/adjust_dt command

17.189.1 Syntax

fix ID group-ID smd/adjust_dt arg

• ID, group-ID are documented in fix command

• smd/adjust_dt = style name of this fix command
• arg = s_fact
s_fact = safety factor

17.189.2 Examples

fix 1 all smd/adjust_dt 0.1

17.189.3 Description

The fix calculates a new stable time increment for use with the SMD time integrators.
The stable time increment is based on multiple conditions. For the SPH pair styles, a CFL criterion (Courant, Friedrichs
& Lewy, 1928) is evaluated, which determines the speed of