LAMMPS Users Manual

Manual

Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 2195

Download
Open PDF In Browser	View PDF

LAMMPS Users Manual
16 Mar 2018 version

http://lammps.sandia.gov - Sandia National Laboratories
pyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public

LAMMPS Users Manual

Table of Contents
LAMMPS Documentation......................................................................................1
16 Mar 2018 version........................................................................................1
Version info:................................................................................................1
1. Introduction.................................................................................................5
1.1 What is LAMMPS..................................................................................5
1.2 LAMMPS features.................................................................................6
1.3 LAMMPS non-features..........................................................................9
1.4 Open source distribution....................................................................11
1.5 Acknowledgments and citations.........................................................12
2. Getting Started..........................................................................................14
2.1 What's in the LAMMPS distribution...................................................14
2.2 Making LAMMPS................................................................................15
2.3 Making LAMMPS with optional packages..........................................25
2.4 Building LAMMPS as a library............................................................29
2.5 Running LAMMPS...............................................................................31
2.6 Command-line options........................................................................33
2.7 LAMMPS screen output......................................................................40
2.8 Tips for users of previous LAMMPS versions.....................................43
3. Commands.................................................................................................45
3.1 LAMMPS input script..........................................................................45
3.2 Parsing rules.......................................................................................46
3.3 Input script structure..........................................................................48
3.4 Commands listed by category.............................................................49
3.5 Individual commands..........................................................................50
Fix styles...................................................................................................51
Compute styles..........................................................................................52
Pair_style potentials..................................................................................52
Bond_style potentials................................................................................54
Angle_style potentials...............................................................................54
Dihedral_style potentials..........................................................................55
Improper_style potentials.........................................................................55
Kspace solvers..........................................................................................55
4. Packages....................................................................................................57
ASPHERE package....................................................................................60
BODY package..........................................................................................61
CLASS2 package.......................................................................................61
COLLOID package....................................................................................62
COMPRESS package.................................................................................63
CORESHELL package...............................................................................63
DIPOLE package.......................................................................................64
GPU package.............................................................................................64
GRANULAR package.................................................................................66
KIM package.............................................................................................66
KOKKOS package.....................................................................................68
KSPACE package......................................................................................69
LATTE package.........................................................................................70
MANYBODY package................................................................................71
MC package..............................................................................................72
i

LAMMPS Users Manual

Table of Contents
MEAM package.........................................................................................72
MISC package...........................................................................................73
MOLECULE package................................................................................74
MPIIO package.........................................................................................74
MSCG package..........................................................................................75
OPT package.............................................................................................76
PERI package............................................................................................77
POEMS package.......................................................................................77
PYTHON package.....................................................................................78
QEQ package............................................................................................79
REAX package...........................................................................................79
REPLICA package.....................................................................................80
RIGID package..........................................................................................81
SHOCK package........................................................................................82
SNAP package...........................................................................................82
SRD package.............................................................................................83
VORONOI package...................................................................................83
USER-ATC package...................................................................................84
USER-AWPMD package............................................................................85
USER-CGDNA package.............................................................................86
USER-CGSDK package.............................................................................87
USER-COLVARS package.........................................................................87
USER-DIFFRACTION package.................................................................88
USER-DPD package..................................................................................89
USER-DRUDE package.............................................................................90
USER-EFF package...................................................................................90
USER-FEP package...................................................................................91
USER-H5MD package...............................................................................92
USER-INTEL package...............................................................................93
USER-LB package.....................................................................................94
USER-MGPT package...............................................................................94
USER-MISC package................................................................................95
USER-MANIFOLD package......................................................................96
USER-MEAMC package............................................................................96
USER-MESO package...............................................................................97
USER-MOFFF package.............................................................................97
USER-MOLFILE package..........................................................................98
USER-NETCDF package...........................................................................99
USER-OMP package...............................................................................100
USER-PHONON package........................................................................101
USER-QMMM package...........................................................................101
USER-QTB package................................................................................102
USER-QUIP package...............................................................................103
USER-REAXC package............................................................................104
USER-SMD package...............................................................................104
USER-SMTBQ package...........................................................................105
USER-SPH package................................................................................106
USER-TALLY package.............................................................................106
ii

LAMMPS Users Manual

Table of Contents
5.

6.

7.
8.
9.

USER-UEF package................................................................................107
USER-VTK package.................................................................................107
Accelerating LAMMPS performance........................................................109
5.1 Measuring performance....................................................................109
5.2 General strategies.............................................................................110
5.3 Packages with optimized styles........................................................111
5.4 Comparison of various accelerator packages...................................114
How-to discussions...................................................................................145
6.1 Restarting a simulation.....................................................................145
6.2 2d simulations...................................................................................147
6.3 CHARMM, AMBER, and DREIDING force fields..............................147
6.4 Running multiple simulations from one input script........................149
6.5 Multi-replica simulations..................................................................150
6.6 Granular models...............................................................................151
6.7 TIP3P water model............................................................................152
6.8 TIP4P water model............................................................................153
6.9 SPC water model...............................................................................155
6.10 Coupling LAMMPS to other codes..................................................156
6.11 Visualizing LAMMPS snapshots......................................................157
6.12 Triclinic (non-orthogonal) simulation boxes...................................157
6.13 NEMD simulations..........................................................................163
6.14 Finite-size spherical and aspherical particles.................................163
6.15 Output from LAMMPS (thermo, dumps, computes, fixes,
variables).....................................................................................167
6.16 Thermostatting, barostatting, and computing temperature...........172
6.17 Walls...............................................................................................175
6.18 Elastic constants.............................................................................176
6.19 Library interface to LAMMPS.........................................................177
6.20 Calculating thermal conductivity....................................................180
6.21 Calculating viscosity.......................................................................181
6.22 Calculating a diffusion coefficient..................................................183
6.23 Using chunks to calculate system properties.................................183
6.24 Setting parameters for the kspace_style pppm/disp command......186
6.25 Polarizable models..........................................................................188
6.26 Adiabatic core/shell model..............................................................189
6.27 Drude induced dipoles....................................................................192
Example problems....................................................................................195
Lowercase directories.............................................................................195
Uppercase directories.............................................................................197
Performance & scalability........................................................................198
Additional tools........................................................................................200
amber2lmp tool.......................................................................................200
binary2txt tool.........................................................................................200
ch2lmp tool.............................................................................................201
chain tool................................................................................................201
colvars tools............................................................................................201
createatoms tool.....................................................................................202
doxygen tool............................................................................................202
iii

LAMMPS Users Manual

Table of Contents
drude tool................................................................................................202
eam database tool...................................................................................202
eam generate tool...................................................................................203
eff tool.....................................................................................................203
emacs tool...............................................................................................203
fep tool....................................................................................................203
i-pi tool....................................................................................................203
ipp tool....................................................................................................204
kate tool..................................................................................................204
lmp2arc tool............................................................................................204
lmp2cfg tool............................................................................................204
matlab tool..............................................................................................204
micelle2d tool..........................................................................................205
moltemplate tool.....................................................................................205
msi2lmp tool...........................................................................................205
phonon tool.............................................................................................205
polybond tool..........................................................................................206
pymol_asphere tool.................................................................................206
python tool..............................................................................................206
reax tool..................................................................................................206
smd tool..................................................................................................207
vim tool...................................................................................................207
xmgrace tool...........................................................................................207
10. Modifying & extending LAMMPS..........................................................208
10.1 Atom styles......................................................................................210
10.2 Bond, angle, dihedral, improper potentials....................................211
10.3 Compute styles................................................................................212
10.4 Dump styles....................................................................................213
10.5 Dump custom output options..........................................................213
10.6 Fix styles.........................................................................................213
10.7 Input script commands...................................................................216
10.8 Kspace computations......................................................................216
10.9 Minimization styles.........................................................................216
10.10 Pairwise potentials........................................................................217
10.11 Region styles.................................................................................217
10.12 Body styles....................................................................................218
10.13 Thermodynamic output options....................................................218
10.14 Variable options............................................................................219
10.15 Submitting new features for inclusion in LAMMPS......................219
11. Python interface to LAMMPS.................................................................224
11.1 Overview of running LAMMPS from Python...................................225
11.2 Overview of using Python from a LAMMPS script..........................226
11.3 Building LAMMPS as a shared library............................................227
11.4 Installing the Python wrapper into Python.....................................227
11.5 Extending Python with MPI to run in parallel................................228
11.6 Testing the Python-LAMMPS interface...........................................231
11.7 Using LAMMPS from Python..........................................................233
11.8 Example Python scripts that use LAMMPS....................................237
iv

LAMMPS Users Manual

Table of Contents
11.9 PyLammps interface.......................................................................238
12. Errors.....................................................................................................239
12.1 Common problems..........................................................................239
12.2 Reporting bugs................................................................................241
12.3 Error & warning messages.............................................................241
Errors:.....................................................................................................241
Warnings:................................................................................................353
13. Future and history.................................................................................365
13.1 Coming attractions.........................................................................365
13.2 Past versions...................................................................................365
Tutorials............................................................................................................368
Using LAMMPS with Bash on Windows.......................................................369
Installing Bash on Windows....................................................................369
Compiling LAMMPS in Bash on Windows..............................................376
Tutorial for Thermalized Drude oscillators in LAMMPS..............................379
LAMMPS GitHub tutorial.............................................................................387
PyLammps Tutorial......................................................................................403
Overview.................................................................................................403
Quick Start..............................................................................................403
Creating a new instance of PyLammps...................................................404
Commands..............................................................................................405
System state............................................................................................405
Working with LAMMPS variables...........................................................406
Retrieving the value of an arbitrary LAMMPS expressions....................406
Accessing atom data...............................................................................407
Evaluating thermo data..........................................................................407
Error handling with PyLammps..............................................................407
Using PyLammps in IPython notebooks and Jupyter..............................408
IPyLammps Examples.............................................................................408
Using PyLammps and mpi4py (Experimental)........................................413
Feedback and Contributing....................................................................413
Body particles..................................................................................................415
Manifolds (surfaces).......................................................................................421
LAMMPS Commands.......................................................................................423
angle_coeff command........................................................................................424
angle_style command...................................................................................426
atom_modify command................................................................................428
atom_style command....................................................................................431
balance command........................................................................................437
bond_coeff command...................................................................................446
bond_style command....................................................................................448
bond_write command...................................................................................450
boundary command......................................................................................451
box command...............................................................................................453
change_box command..................................................................................454
v

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
clear command.............................................................................................460
comm_modify command...............................................................................461
comm_style command..................................................................................464
compute command.......................................................................................465
compute_modify command...........................................................................470
create_atoms command...............................................................................472
create_bonds command................................................................................478
create_box command...................................................................................482
delete_atoms command................................................................................485
delete_bonds command................................................................................488
dielectric command......................................................................................491
dihedral_coeff command..............................................................................492
dihedral_style command..............................................................................494
dimension command....................................................................................497
displace_atoms command............................................................................498
dump command............................................................................................501
dump vtk command......................................................................................501
dump h5md command..................................................................................501
dump molfile command................................................................................501
dump netcdf command.................................................................................501
dump image command.................................................................................501
dump movie command.................................................................................501
dump h5md command..................................................................................512
dump image command.................................................................................514
dump movie command.................................................................................514
dump_modify command...............................................................................526
dump molfile command................................................................................541
dump netcdf command.................................................................................543
dump netcdf/mpiio command.......................................................................543
dump vtk command......................................................................................545
dump cfg/uef command................................................................................548
echo command.............................................................................................549
fix command.................................................................................................550
fix_modify command....................................................................................556
group command...........................................................................................558
group2ndx command...................................................................................563
ndx2group command...................................................................................563
if command...................................................................................................565
improper_coeff command.............................................................................569
improper_style command.............................................................................571
include command.........................................................................................573
info command...............................................................................................574
jump command.............................................................................................577
kspace_modify command.............................................................................580
kspace_style command.................................................................................586
label command.............................................................................................593
lattice command...........................................................................................594
vi

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
log command................................................................................................599
mass command.............................................................................................600
min_modify command..................................................................................602
min_style command......................................................................................604
minimize command......................................................................................606
molecule command......................................................................................611
neb command...............................................................................................619
neigh_modify command...............................................................................626
neighbor command......................................................................................630
newton command.........................................................................................632
next command..............................................................................................633
package command.......................................................................................636
pair_coeff command.....................................................................................646
pair_modify command..................................................................................649
pair_style command.....................................................................................654
pair_write command....................................................................................659
partition command.......................................................................................661
prd command...............................................................................................663
print command.............................................................................................669
processors command...................................................................................671
python command..........................................................................................677
quit command..............................................................................................685
read_data command.....................................................................................686
read_dump command...................................................................................706
read_restart command.................................................................................712
region command..........................................................................................717
replicate command.......................................................................................724
rerun command............................................................................................726
reset_timestep command.............................................................................730
restart command..........................................................................................731
run command...............................................................................................734
run_style command......................................................................................738
set command................................................................................................743
shell command.............................................................................................751
special_bonds command..............................................................................753
suffix command............................................................................................757
tad command................................................................................................759
temper command.........................................................................................764
temper/grem command................................................................................767
temper/npt command...................................................................................769
thermo command.........................................................................................771
thermo_modify command.............................................................................772
thermo_style command................................................................................775
timer command............................................................................................782
timestep command.......................................................................................785
uncompute command...................................................................................786
undump command........................................................................................787
vii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
unfix command.............................................................................................788
units command.............................................................................................789
variable command........................................................................................794
Numbers, constants, and thermo keywords...........................................802
Math Operators.......................................................................................802
Math Functions.......................................................................................803
Group and Region Functions..................................................................805
Special Functions....................................................................................806
Feature Functions...................................................................................807
Atom Values and Vectors........................................................................808
Compute References...............................................................................809
Fix References........................................................................................810
Variable References................................................................................811
velocity command........................................................................................816
write_coeff command...................................................................................821
write_data command....................................................................................822
write_dump command..................................................................................824
write_restart command................................................................................826
fix adapt command.......................................................................................828
fix adapt/fep command.................................................................................833
fix addforce command..................................................................................838
fix addtorque command...............................................................................841
fix append/atoms command.........................................................................843
fix atom/swap command...............................................................................845
fix ave/atom command.................................................................................848
fix ave/chunk command...............................................................................851
fix ave/correlate command...........................................................................859
fix ave/correlate/long command...................................................................865
fix ave/histo command.................................................................................868
fix ave/histo/weight command......................................................................868
fix ave/time command..................................................................................874
fix aveforce command..................................................................................880
fix balance command...................................................................................882
fix bond/break command..............................................................................889
fix bond/create command.............................................................................892
fix bond/swap command...............................................................................896
fix box/relax command.................................................................................900
fix cmap command.......................................................................................906
fix colvars command....................................................................................909
fix controller command................................................................................912
fix deform command....................................................................................916
fix deform/kk command................................................................................916
fix deposit command....................................................................................926
fix dpd/energy command..............................................................................931
fix dpd/energy/kk command.........................................................................931
fix edpd/source command............................................................................933
fix tdpd/source command.............................................................................933
viii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
fix drag command........................................................................................935
fix drude command......................................................................................936
fix drude/transform/direct command...........................................................937
fix drude/transform/inverse command.........................................................937
fix dt/reset command...................................................................................940
fix efield command.......................................................................................942
fix ehex command........................................................................................945
fix enforce2d command................................................................................948
fix eos/cv command......................................................................................950
fix eos/table command.................................................................................951
fix eos/table/rx command.............................................................................953
fix eos/table/rx/kk command........................................................................953
fix evaporate command................................................................................957
fix external command...................................................................................959
fix filter/corotate command..........................................................................962
fix flow/gauss command...............................................................................964
fix freeze command......................................................................................967
fix gcmc command.......................................................................................969
fix gld command...........................................................................................977
fix gle command...........................................................................................980
fix gravity command.....................................................................................983
fix gravity/omp command.............................................................................983
fix grem command.......................................................................................986
fix halt command..........................................................................................988
fix heat command.........................................................................................991
fix imd command..........................................................................................994
fix indent command......................................................................................997
fix ipi command..........................................................................................1001
fix langevin command................................................................................1003
fix langevin/kk command...........................................................................1003
fix langevin/drude command......................................................................1009
fix langevin/eff command...........................................................................1013
fix latte command.......................................................................................1015
fix lb/fluid command...................................................................................1019
fix lb/momentum command........................................................................1026
fix lb/pc command......................................................................................1028
fix lb/rigid/pc/sphere command.................................................................1029
fix lb/viscous command..............................................................................1032
fix lineforce command................................................................................1034
fix manifoldforce command........................................................................1035
fix meso command.....................................................................................1036
fix meso/stationary command....................................................................1037
fix momentum command............................................................................1038
fix momentum/kk command.......................................................................1038
fix move command.....................................................................................1040
fix mscg command.....................................................................................1044
fix msst command.....................................................................................1047
ix

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
fix mvv/dpd command................................................................................1051
fix mvv/edpd command..............................................................................1051
fix mvv/tdpd command...............................................................................1051
fix neb command........................................................................................1053
fix nvt command.........................................................................................1057
fix nvt/intel command.................................................................................1057
fix nvt/kk command....................................................................................1057
fix nvt/omp command.................................................................................1057
fix npt command.........................................................................................1057
fix npt/intel command................................................................................1057
fix npt/kk command....................................................................................1057
fix npt/omp command.................................................................................1057
fix nph command........................................................................................1057
fix nph/kk command...................................................................................1057
fix nph/omp command................................................................................1057
fix nvt/eff command...................................................................................1068
fix npt/eff command...................................................................................1068
fix nph/eff command...................................................................................1068
fix nph/asphere command..........................................................................1071
fix nph/asphere/omp command..................................................................1071
fix nph/body command...............................................................................1074
fix nph/sphere command............................................................................1077
fix nph/sphere/omp command....................................................................1077
fix nphug command....................................................................................1080
fix nphug/omp command............................................................................1080
fix npt/asphere command...........................................................................1084
fix npt/asphere/omp command...................................................................1084
fix npt/body command................................................................................1087
fix npt/sphere command.............................................................................1090
fix npt/sphere/omp command.....................................................................1090
fix nve command........................................................................................1093
fix nve/intel command................................................................................1093
fix nve/kk command...................................................................................1093
fix nve/omp command................................................................................1093
fix nve/asphere command..........................................................................1095
fix nve/asphere/intel command..................................................................1095
fix nve/asphere/noforce command.............................................................1097
fix nve/body command...............................................................................1098
fix nve/dot command..................................................................................1099
fix nve/dotc/langevin command..................................................................1100
fix nve/eff command...................................................................................1103
fix nve/limit command................................................................................1104
fix nve/line command.................................................................................1106
fix nve/manifold/rattle command...............................................................1107
fix nve/noforce command...........................................................................1109
fix nve/sphere command............................................................................1110
fix nve/sphere/omp command....................................................................1110
x

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
fix nve/tri command...................................................................................1112
fix nvk command........................................................................................1113
fix nvt/asphere command...........................................................................1115
fix nvt/asphere/omp command...................................................................1115
fix nvt/body command................................................................................1118
fix nvt/manifold/rattle command................................................................1121
fix nvt/sllod command................................................................................1123
fix nvt/sllod/intel command........................................................................1123
fix nvt/sllod/omp command........................................................................1123
fix nvt/sllod/eff command...........................................................................1126
fix nvt/sphere command.............................................................................1128
fix nvt/sphere/omp command.....................................................................1128
fix nvt/uef command...................................................................................1131
fix npt/uef command..................................................................................1131
fix oneway command..................................................................................1135
fix orient/fcc command...............................................................................1136
fix orient/bcc command..............................................................................1136
fix phonon command..................................................................................1140
fix pimd command......................................................................................1144
fix planeforce command.............................................................................1148
fix poems....................................................................................................1149
fix pour command......................................................................................1152
fix press/berendsen command...................................................................1157
fix print command......................................................................................1161
fix property/atom command.......................................................................1163
fix python/invoke command.......................................................................1168
fix python/move command.........................................................................1170
fix qbmsst command..................................................................................1172
fix qeq/point command...............................................................................1177
fix qeq/shielded command.........................................................................1177
fix qeq/slater command..............................................................................1177
fix qeq/dynamic command.........................................................................1177
fix qeq/fire command.................................................................................1177
fix qeq/comb command..............................................................................1181
fix qeq/comb/omp command......................................................................1181
fix qeq/reax command................................................................................1184
fix qeq/reax/kk command...........................................................................1184
fix qeq/reax/omp command........................................................................1184
fix qmmm command...................................................................................1187
fix qtb command.........................................................................................1189
fix reax/bonds command............................................................................1192
fix reax/c/bonds command.........................................................................1192
fix reax/c/bonds/kk command....................................................................1192
fix reax/c/species command.......................................................................1194
fix reax/c/species/kk command..................................................................1194
fix recenter command................................................................................1197
fix restrain command.................................................................................1199
xi

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
fix rigid command......................................................................................1203
fix rigid/omp command..............................................................................1203
fix rigid/nve command................................................................................1203
fix rigid/nve/omp command........................................................................1203
fix rigid/nvt command................................................................................1203
fix rigid/nvt/omp command........................................................................1203
fix rigid/npt command................................................................................1203
fix rigid/npt/omp command........................................................................1203
fix rigid/nph command...............................................................................1203
fix rigid/nph/omp command.......................................................................1203
fix rigid/small command.............................................................................1203
fix rigid/small/omp command.....................................................................1203
fix rigid/nve/small command......................................................................1203
fix rigid/nvt/small command.......................................................................1203
fix rigid/npt/small command......................................................................1203
fix rigid/nph/small command......................................................................1203
fix rhok command......................................................................................1217
fix rx command...........................................................................................1219
fix rx/kk command......................................................................................1219
fix saed/vtk command................................................................................1224
fix setforce command.................................................................................1227
fix setforce/kk command............................................................................1227
fix shake command.....................................................................................1230
fix rattle command.....................................................................................1230
fix shardlow command...............................................................................1234
fix shardlow/kk command..........................................................................1234
fix smd command.......................................................................................1236
fix smd/adjust_dt command........................................................................1239
fix smd/integrate_tlsph command..............................................................1240
fix smd/integrate_ulsph command.............................................................1241
fix smd/move_tri_surf command................................................................1242
fix smd/setvel command.............................................................................1244
fix smd/wall_surface command..................................................................1246
fix spring command....................................................................................1248
fix spring/chunk command.........................................................................1251
fix spring/rg command...............................................................................1253
fix spring/self command.............................................................................1255
fix srd command.........................................................................................1257
fix store/force command............................................................................1264
fix store/state command.............................................................................1266
fix wall/surface/globale command..............................................................1268
fix temp/berendsen command....................................................................1269
fix temp/csvr command..............................................................................1272
fix temp/csld command..............................................................................1272
fix temp/rescale command.........................................................................1275
fix temp/rescale/eff command....................................................................1278
fix tfmc command.......................................................................................1280
xii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
fix thermal/conductivity command.............................................................1283
fix ti/spring command................................................................................1286
fix tmd command........................................................................................1289
fix ttm command........................................................................................1292
fix ttm/mod command................................................................................1292
fix tune/kspace command...........................................................................1298
fix vector command....................................................................................1300
fix viscosity command................................................................................1303
fix viscous command..................................................................................1306
fix wall/lj93 command................................................................................1308
fix wall/lj93/kk command...........................................................................1308
fix wall/lj126 command..............................................................................1308
fix wall/lj1043 command............................................................................1308
fix wall/colloid command............................................................................1308
fix wall/harmonic command.......................................................................1308
fix wall/ees command.................................................................................1314
fix wall/region/ees command.....................................................................1314
fix wall/gran command...............................................................................1317
fix wall/gran/region command...................................................................1320
fix wall/piston command............................................................................1324
fix wall/reflect command............................................................................1326
fix wall/reflect/kk command.......................................................................1326
fix wall/region command............................................................................1329
fix wall/srd command.................................................................................1333
compute ackland/atom command..............................................................1336
compute angle command...........................................................................1338
compute angle/local command...................................................................1339
compute angmom/chunk command...........................................................1341
compute basal/atom command...................................................................1343
compute body/local command....................................................................1345
compute bond command............................................................................1347
compute bond/local command...................................................................1348
compute centro/atom command.................................................................1351
compute chunk/atom command.................................................................1354
compute cluster/atom command................................................................1365
compute fragment/atom command............................................................1365
compute aggregate/atom command...........................................................1365
compute cna/atom command.....................................................................1367
compute cnp/atom command.....................................................................1370
compute com command.............................................................................1373
compute com/chunk command...................................................................1374
compute contact/atom command...............................................................1376
compute coord/atom command..................................................................1377
compute damage/atom command..............................................................1380
compute dihedral command.......................................................................1381
compute dihedral/local command..............................................................1382
compute dilatation/atom command............................................................1384
xiii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
compute dipole/chunk command...............................................................1386
compute displace/atom command..............................................................1388
compute dpd command..............................................................................1390
compute dpd/atom command.....................................................................1392
compute edpd/temp/atom command..........................................................1394
compute erotate/asphere command...........................................................1395
compute erotate/rigid command................................................................1397
compute erotate/sphere command............................................................1398
compute erotate/sphere/atom command...................................................1399
compute event/displace command.............................................................1400
compute fep command...............................................................................1402
compute global/atom command.................................................................1407
compute group/group command................................................................1411
compute gyration command.......................................................................1414
compute gyration/chunk command............................................................1416
compute heat/flux command......................................................................1418
compute hexorder/atom command............................................................1422
compute improper command.....................................................................1424
compute improper/local command.............................................................1425
compute inertia/chunk command...............................................................1427
compute ke command................................................................................1429
compute ke/atom command.......................................................................1430
compute ke/atom/eff command..................................................................1431
compute ke/eff command...........................................................................1433
compute ke/rigid command........................................................................1435
compute meso/e/atom command................................................................1436
compute meso/rho/atom command............................................................1437
compute meso/t/atom command................................................................1438
compute msd command.............................................................................1439
compute msd/chunk command...................................................................1441
compute msd/nongauss command.............................................................1443
compute omega/chunk command...............................................................1445
compute orientorder/atom command.........................................................1447
compute pair command..............................................................................1450
compute pair/local command.....................................................................1452
compute pe command................................................................................1455
compute pe/atom command.......................................................................1457
compute plasticity/atom command............................................................1459
compute pressure command......................................................................1461
compute pressure/uef command................................................................1464
compute property/atom command.............................................................1465
compute property/chunk command...........................................................1468
compute property/local command..............................................................1470
compute rdf command...............................................................................1473
compute reduce command.........................................................................1477
compute reduce/region command..............................................................1477
compute rigid/local command....................................................................1481
xiv

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
compute saed command.............................................................................1485
compute slice command.............................................................................1489
compute smd/contact/radius command.....................................................1491
compute smd/damage command................................................................1492
compute smd/hourglass/error command...................................................1493
compute smd/internal/energy command....................................................1494
compute smd/plastic/strain command.......................................................1495
compute smd/plastic/strain/rate command................................................1496
compute smd/rho command.......................................................................1497
compute smd/tlsph/defgrad command.......................................................1498
compute smd/tlsph/dt command................................................................1499
compute smd/tlsph/num/neighs command.................................................1500
compute smd/tlsph/shape command..........................................................1501
compute smd/tlsph/strain command..........................................................1502
compute smd/tlsph/strain/rate command..................................................1503
compute smd/tlsph/stress command..........................................................1504
compute smd/triangle/mesh/vertices.........................................................1505
compute smd/ulsph/num/neighs command................................................1506
compute smd/ulsph/strain command.........................................................1507
compute smd/ulsph/strain/rate command..................................................1508
compute smd/ulsph/stress command.........................................................1509
compute smd/vol command........................................................................1510
compute sna/atom command.....................................................................1511
compute snad/atom command...................................................................1511
compute snav/atom command....................................................................1511
compute stress/atom command.................................................................1517
compute force/tally command....................................................................1520
compute heat/flux/tally command..............................................................1520
compute pe/tally command........................................................................1520
compute pe/mol/tally command.................................................................1520
compute stress/tally command...................................................................1520
compute tdpd/cc/atom command...............................................................1522
compute temp command............................................................................1523
compute temp/kk command.......................................................................1523
compute temp/asphere command..............................................................1525
compute temp/body command...................................................................1528
compute temp/chunk command.................................................................1531
compute temp/com command....................................................................1535
compute temp/cs command.......................................................................1537
compute temp/deform command...............................................................1539
compute temp/deform/eff command..........................................................1542
compute temp/drude command.................................................................1544
compute temp/eff command.......................................................................1546
compute temp/partial command................................................................1548
compute temp/profile command................................................................1550
compute temp/ramp command..................................................................1553
compute temp/region command................................................................1555
xv

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
compute temp/region/eff command...........................................................1557
compute temp/rotate command.................................................................1558
compute temp/sphere command................................................................1560
compute temp/uef command......................................................................1563
compute ti command..................................................................................1564
compute torque/chunk command...............................................................1567
compute vacf command.............................................................................1569
compute vcm/chunk command...................................................................1571
compute voronoi/atom command...............................................................1573
compute xrd command...............................................................................1577
pair_style adp command............................................................................1582
pair_style adp/omp command....................................................................1582
pair_style agni command...........................................................................1586
pair_style agni/omp command...................................................................1586
pair_style airebo command........................................................................1589
pair_style airebo/intel command................................................................1589
pair_style airebo/omp command................................................................1589
pair_style airebo/morse command.............................................................1589
pair_style airebo/morse/intel command.....................................................1589
pair_style airebo/morse/omp command.....................................................1589
pair_style rebo command...........................................................................1589
pair_style rebo/intel command...................................................................1589
pair_style rebo/omp command...................................................................1589
pair_style awpmd/cut command.................................................................1594
pair_style beck command...........................................................................1596
pair_style beck/gpu command....................................................................1596
pair_style beck/omp command...................................................................1596
pair_style body command...........................................................................1598
pair_style body/rounded/polygon command..............................................1600
pair_style bop command............................................................................1601
pair_style born command...........................................................................1609
pair_style born/omp command...................................................................1609
pair_style born/gpu command....................................................................1609
pair_style born/coul/long command...........................................................1609
pair_style born/coul/long/cs command.......................................................1609
pair_style born/coul/long/gpu command....................................................1609
pair_style born/coul/long/omp command...................................................1609
pair_style born/coul/msm command..........................................................1609
pair_style born/coul/msm/omp command...................................................1609
pair_style born/coul/wolf command...........................................................1609
pair_style born/coul/wolf/cs command.......................................................1609
pair_style born/coul/wolf/gpu command....................................................1609
pair_style born/coul/wolf/omp command...................................................1609
pair_style born/coul/dsf command.............................................................1609
pair_style born/coul/dsf/cs command.........................................................1609
pair_style brownian command...................................................................1613
pair_style brownian/omp command...........................................................1613
xvi

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style brownian/poly command...........................................................1613
pair_style brownian/poly/omp command....................................................1613
pair_style buck command...........................................................................1616
pair_style buck/gpu command...................................................................1616
pair_style buck/intel command..................................................................1616
pair_style buck/kk command......................................................................1616
pair_style buck/omp command...................................................................1616
pair_style buck/coul/cut command.............................................................1616
pair_style buck/coul/cut/gpu command......................................................1616
pair_style buck/coul/cut/intel command....................................................1616
pair_style buck/coul/cut/kk command........................................................1616
pair_style buck/coul/cut/omp command.....................................................1616
pair_style buck/coul/long command...........................................................1616
pair_style buck/coul/long/cs command......................................................1616
pair_style buck/coul/long/gpu command....................................................1616
pair_style buck/coul/long/intel command...................................................1616
pair_style buck/coul/long/kk command......................................................1616
pair_style buck/coul/long/omp command...................................................1616
pair_style buck/coul/msm command..........................................................1616
pair_style buck/coul/msm/omp command..................................................1616
pair_style buck/long/coul/long command...................................................1620
pair_style buck/long/coul/long/omp command...........................................1620
pair_style buck6d/coul/gauss/dsf...............................................................1623
pair_style buck6d/coul/gauss/long.............................................................1623
pair_style lj/charmm/coul/charmm command............................................1626
pair_style lj/charmm/coul/charmm/intel command....................................1626
pair_style lj/charmm/coul/charmm/omp command....................................1626
pair_style lj/charmm/coul/charmm/implicit command...............................1626
pair_style lj/charmm/coul/charmm/implicit/omp command.......................1626
pair_style lj/charmm/coul/long command..................................................1626
pair_style lj/charmm/coul/long/gpu command...........................................1626
pair_style lj/charmm/coul/long/intel command..........................................1626
pair_style lj/charmm/coul/long/opt command............................................1626
pair_style lj/charmm/coul/long/omp command..........................................1626
pair_style lj/charmm/coul/msm command..................................................1626
pair_style lj/charmm/coul/msm/omp command..........................................1626
pair_style lj/charmmfsw/coul/charmmfsh command..................................1626
pair_style lj/charmmfsw/coul/long command.............................................1626
pair_style lj/class2 command.....................................................................1632
pair_style lj/class2/gpu command..............................................................1632
pair_style lj/class2/kk command................................................................1632
pair_style lj/class2/omp command.............................................................1632
pair_style lj/class2/coul/cut command........................................................1632
pair_style lj/class2/coul/cut/kk command...................................................1632
pair_style lj/class2/coul/cut/omp command................................................1632
pair_style lj/class2/coul/long command......................................................1632
pair_style lj/class2/coul/long/gpu command...............................................1632
xvii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style lj/class2/coul/long/kk command.................................................1632
pair_style lj/class2/coul/long/omp command..............................................1632
pair_style colloid command........................................................................1636
pair_style colloid/gpu command.................................................................1636
pair_style colloid/omp command................................................................1636
pair_style comb command..........................................................................1641
pair_style comb/omp command..................................................................1641
pair_style comb3 command........................................................................1641
pair_style coul/cut command.....................................................................1645
pair_style coul/cut/gpu command..............................................................1645
pair_style coul/cut/kk command.................................................................1645
pair_style coul/cut/omp command..............................................................1645
pair_style coul/debye command.................................................................1645
pair_style coul/debye/gpu command..........................................................1645
pair_style coul/debye/kk command............................................................1645
pair_style coul/debye/omp command.........................................................1645
pair_style coul/dsf command......................................................................1645
pair_style coul/dsf/gpu command...............................................................1645
pair_style coul/dsf/kk command.................................................................1645
pair_style coul/dsf/omp command..............................................................1645
pair_style coul/long command....................................................................1645
pair_style coul/long/cs command...............................................................1645
pair_style coul/long/omp command............................................................1645
pair_style coul/long/gpu command............................................................1645
pair_style coul/long/kk command...............................................................1645
pair_style coul/msm command...................................................................1645
pair_style coul/msm/omp command...........................................................1645
pair_style coul/streitz command................................................................1645
pair_style coul/wolf command....................................................................1645
pair_style coul/wolf/kk command...............................................................1646
pair_style coul/wolf/omp command............................................................1646
pair_style coul/wolf/cs command...............................................................1646
pair_style tip4p/cut command....................................................................1646
pair_style tip4p/long command..................................................................1646
pair_style tip4p/cut/omp command............................................................1646
pair_style tip4p/long/omp command..........................................................1646
pair_style coul/diel command.....................................................................1652
pair_style coul/diel/omp command.............................................................1652
pair_style born/coul/long/cs command.......................................................1654
pair_style buck/coul/long/cs command......................................................1654
pair_style born/coul/dsf/cs command.........................................................1654
pair_style born/coul/wolf/cs command.......................................................1654
pair_style lj/cut/dipole/cut command.........................................................1657
pair_style lj/cut/dipole/cut/gpu command..................................................1657
pair_style lj/cut/dipole/cut/omp command.................................................1657
pair_style lj/sf/dipole/sf command..............................................................1657
pair_style lj/sf/dipole/sf/gpu command.......................................................1657
xviii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style lj/sf/dipole/sf/omp command......................................................1657
pair_style lj/cut/dipole/long command.......................................................1657
pair_style lj/long/dipole/long command.....................................................1657
pair_style dpd command............................................................................1666
pair_style dpd/gpu command.....................................................................1666
pair_style dpd/intel command....................................................................1666
pair_style dpd/omp command....................................................................1666
pair_style dpd/tstat command....................................................................1666
pair_style dpd/tstat/gpu command.............................................................1666
pair_style dpd/tstat/omp command............................................................1666
pair_style dpd/fdt command.......................................................................1670
pair_style dpd/fdt/energy command...........................................................1670
pair_style dpd/fdt/energy/kk command......................................................1670
pair_style dsmc command..........................................................................1674
pair_style eam command............................................................................1677
pair_style eam/gpu command....................................................................1677
pair_style eam/intel command...................................................................1677
pair_style eam/kk command.......................................................................1677
pair_style eam/omp command....................................................................1677
pair_style eam/opt command.....................................................................1677
pair_style eam/alloy command...................................................................1677
pair_style eam/alloy/gpu command............................................................1677
pair_style eam/alloy/intel command...........................................................1677
pair_style eam/alloy/kk command..............................................................1677
pair_style eam/alloy/omp command...........................................................1677
pair_style eam/alloy/opt command.............................................................1677
pair_style eam/cd command.......................................................................1677
pair_style eam/cd/omp command...............................................................1677
pair_style eam/fs command........................................................................1677
pair_style eam/fs/gpu command.................................................................1677
pair_style eam/fs/intel command...............................................................1677
pair_style eam/fs/kk command...................................................................1677
pair_style eam/fs/omp command................................................................1677
pair_style eam/fs/opt command.................................................................1677
pair_style edip command...........................................................................1686
pair_style edip/multi command..................................................................1686
pair_style eff/cut command........................................................................1690
pair_style eim command............................................................................1696
pair_style eim/omp command....................................................................1696
pair_style exp6/rx command......................................................................1700
pair_style exp6/rx/kk command.................................................................1700
pair_style extep command.........................................................................1704
pair_style gauss command.........................................................................1705
pair_style gauss/gpu command..................................................................1705
pair_style gauss/omp command.................................................................1705
pair_style gauss/cut command...................................................................1705
pair_style gauss/cut/omp command...........................................................1705
xix

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style gayberne command...................................................................1709
pair_style gayberne/gpu command............................................................1709
pair_style gayberne/intel command...........................................................1709
pair_style gayberne/omp command...........................................................1709
pair_style gran/hooke command................................................................1714
pair_style gran/omp command...................................................................1714
pair_style gran/hooke/history command....................................................1714
pair_style gran/hooke/history/omp command............................................1714
pair_style gran/hertz/history command.....................................................1714
pair_style gran/hertz/history/omp command.............................................1714
pair_style lj/gromacs command..................................................................1719
pair_style lj/gromacs/gpu command..........................................................1719
pair_style lj/gromacs/omp command..........................................................1719
pair_style lj/gromacs/coul/gromacs command...........................................1719
pair_style lj/gromacs/coul/gromacs/omp command...................................1719
pair_style gw command..............................................................................1723
pair_style gw/zbl command........................................................................1723
pair_style hbond/dreiding/lj command.......................................................1725
pair_style hbond/dreiding/lj/omp command...............................................1725
pair_style hbond/dreiding/morse command...............................................1725
pair_style hbond/dreiding/morse/omp command.......................................1725
pair_style hybrid command........................................................................1730
pair_style hybrid/omp command................................................................1730
pair_style hybrid/overlay command...........................................................1730
pair_style hybrid/overlay/omp command...................................................1730
pair_style hybrid/overlay/kk command......................................................1730
pair_style kim command............................................................................1737
pair_style kolmogorov/crespi/z command..................................................1740
pair_style lcbop command..........................................................................1742
pair_style line/lj command.........................................................................1744
pair_style list command.............................................................................1747
pair_style lj/cut command..........................................................................1750
pair_style lj/cut/gpu command...................................................................1750
pair_style lj/cut/intel command..................................................................1750
pair_style lj/cut/kk command.....................................................................1750
pair_style lj/cut/opt command....................................................................1750
pair_style lj/cut/omp command..................................................................1750
pair_style lj/cut/coul/cut command............................................................1750
pair_style lj/cut/coul/cut/gpu command.....................................................1750
pair_style lj/cut/coul/cut/omp command....................................................1750
pair_style lj/cut/coul/debye command........................................................1750
pair_style lj/cut/coul/debye/gpu command.................................................1750
pair_style lj/cut/coul/debye/kk command...................................................1750
pair_style lj/cut/coul/debye/omp command................................................1750
pair_style lj/cut/coul/dsf command.............................................................1750
pair_style lj/cut/coul/dsf/gpu command.....................................................1750
pair_style lj/cut/coul/dsf/kk command........................................................1750
xx

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style lj/cut/coul/dsf/omp command.....................................................1750
pair_style lj/cut/coul/long command..........................................................1750
pair_style lj/cut/coul/long/cs command......................................................1750
pair_style lj/cut/coul/long/gpu command...................................................1750
pair_style lj/cut/coul/long/intel command..................................................1750
pair_style lj/cut/coul/long/opt command....................................................1751
pair_style lj/cut/coul/long/omp command..................................................1751
pair_style lj/cut/coul/msm command..........................................................1751
pair_style lj/cut/coul/msm/gpu command...................................................1751
pair_style lj/cut/coul/msm/omp command..................................................1751
pair_style lj/cut/coul/wolf command...........................................................1751
pair_style lj/cut/coul/wolf/omp command...................................................1751
pair_style lj/cut/tip4p/cut command...........................................................1751
pair_style lj/cut/tip4p/cut/omp command...................................................1751
pair_style lj/cut/tip4p/long command.........................................................1751
pair_style lj/cut/tip4p/long/omp command.................................................1751
pair_style lj/cut/tip4p/long/opt command...................................................1751
pair_style lj96/cut command......................................................................1758
pair_style lj96/cut/gpu command...............................................................1758
pair_style lj96/cut/omp command..............................................................1758
pair_style lj/cubic command.......................................................................1760
pair_style lj/cubic/gpu command................................................................1760
pair_style lj/cubic/omp command...............................................................1760
pair_style lj/expand command....................................................................1763
pair_style lj/expand/gpu command.............................................................1763
pair_style lj/expand/omp command............................................................1763
pair_style lj/long/coul/long command.........................................................1765
pair_style lj/long/coul/long/intel command................................................1765
pair_style lj/long/coul/long/omp command.................................................1765
pair_style lj/long/coul/long/opt command..................................................1765
pair_style lj/long/tip4p/long command.......................................................1765
pair_style lj/smooth command....................................................................1769
pair_style lj/smooth/omp command............................................................1769
pair_style lj/smooth/linear command.........................................................1772
pair_style lj/smooth/linear/omp command.................................................1772
pair_style lj/cut/soft command...................................................................1774
pair_style lj/cut/soft/omp command...........................................................1774
pair_style lj/cut/coul/cut/soft command.....................................................1774
pair_style lj/cut/coul/cut/soft/omp command.............................................1774
pair_style lj/cut/coul/long/soft command...................................................1774
pair_style lj/cut/coul/long/soft/omp command...........................................1774
pair_style lj/cut/tip4p/long/soft command..................................................1774
pair_style lj/cut/tip4p/long/soft/omp command..........................................1774
pair_style lj/charmm/coul/long/soft command...........................................1774
pair_style lj/charmm/coul/long/soft/omp command...................................1774
pair_style coul/cut/soft command..............................................................1774
pair_style coul/cut/soft/omp command.......................................................1774
xxi

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style coul/long/soft command.............................................................1774
pair_style coul/long/soft/omp command.....................................................1774
pair_style tip4p/long/soft command...........................................................1774
pair_style tip4p/long/soft/omp command...................................................1774
pair_style lubricate command....................................................................1780
pair_style lubricate/omp command............................................................1780
pair_style lubricate/poly command............................................................1780
pair_style lubricate/poly/omp command....................................................1780
pair_style lubricateU command.................................................................1785
pair_style lubricateU/poly command..........................................................1785
pair_style lj/mdf command.........................................................................1789
pair_style buck/mdf command...................................................................1789
pair_style lennard/mdf command...............................................................1789
pair_style meam command.........................................................................1793
pair_style meam/c command......................................................................1793
pair_style meam/spline...............................................................................1800
pair_style meam/spline/omp.......................................................................1800
pair_style meam/sw/spline.........................................................................1804
pair_style meam/sw/spline/omp.................................................................1804
pair_style edpd command..........................................................................1807
pair_style mdpd command.........................................................................1807
pair_style mdpd/rhosum command............................................................1807
pair_style tdpd command...........................................................................1807
pair_style mgpt command..........................................................................1815
pair_style mie/cut command......................................................................1819
pair_style mie/cut/gpu command...............................................................1819
pair_style momb command........................................................................1821
pair_style morse command........................................................................1823
pair_style morse/gpu command.................................................................1823
pair_style morse/omp command................................................................1823
pair_style morse/opt command..................................................................1823
pair_style morse/smooth/linear command.................................................1823
pair_style morse/smooth/linear/omp command.........................................1823
pair_style morse/soft command.................................................................1823
pair_style morse/kk command....................................................................1823
pair_style multi/lucy command..................................................................1827
pair_style multi/lucy/rx command..............................................................1831
pair_style multi/lucy/rx/kk command.........................................................1831
pair_style nb3b/harmonic command..........................................................1836
pair_style nb3b/harmonic/omp command..................................................1836
pair_style nm/cut command.......................................................................1839
pair_style nm/cut/coul/cut command.........................................................1839
pair_style nm/cut/coul/long command.......................................................1839
pair_style nm/cut/omp command...............................................................1839
pair_style nm/cut/coul/cut/omp command.................................................1839
pair_style nm/cut/coul/long/omp command...............................................1839
pair_style none command..........................................................................1842
xxii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style oxdna/excv command................................................................1843
pair_style oxdna/stk command...................................................................1843
pair_style oxdna/hbond command..............................................................1843
pair_style oxdna/xstk command.................................................................1843
pair_style oxdna/coaxstk command............................................................1843
pair_style oxdna2/excv command..............................................................1845
pair_style oxdna2/stk command.................................................................1845
pair_style oxdna2/hbond command............................................................1845
pair_style oxdna2/xstk command...............................................................1845
pair_style oxdna2/coaxstk command..........................................................1845
pair_style oxdna2/dh command..................................................................1845
pair_style peri/pmb command....................................................................1848
pair_style peri/pmb/omp command............................................................1848
pair_style peri/lps command......................................................................1848
pair_style peri/lps/omp command..............................................................1848
pair_style peri/ves command......................................................................1848
pair_style peri/eps command.....................................................................1848
pair_style polymorphic command..............................................................1852
pair_style python command.......................................................................1858
pair_style quip command...........................................................................1862
pair_style reax command...........................................................................1864
pair_style reax/c command........................................................................1868
pair_style reax/c/kk command....................................................................1868
pair_style reax/c/omp command................................................................1868
pair_style resquared command..................................................................1874
pair_style resquared/gpu command...........................................................1874
pair_style resquared/omp command..........................................................1874
pair_style lj/sdk command..........................................................................1878
pair_style lj/sdk/gpu command...................................................................1878
pair_style lj/sdk/kk command.....................................................................1878
pair_style lj/sdk/omp command..................................................................1878
pair_style lj/sdk/coul/long command..........................................................1878
pair_style lj/sdk/coul/long/gpu command...................................................1878
pair_style lj/sdk/coul/long/omp command..................................................1878
pair_style smd/hertz command..................................................................1881
pair_style smd/tlsph command...................................................................1882
pair_style smd/tri_surface command.........................................................1884
pair_style smd/ulsph command..................................................................1885
pair_style smtbq command........................................................................1887
pair_style snap command...........................................................................1893
pair_style snap/kk command......................................................................1893
pair_style soft command............................................................................1897
pair_style soft/gpu command.....................................................................1897
pair_style soft/omp command....................................................................1897
pair_style sph/heatconduction command...................................................1900
pair_style sph/idealgas command..............................................................1901
pair_style sph/lj command..........................................................................1903
xxiii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style sph/rhosum command................................................................1905
pair_style sph/taitwater command.............................................................1906
pair_style sph/taitwater/morris command.................................................1908
pair_style srp command.............................................................................1910
pair_style sw command..............................................................................1913
pair_style sw/gpu command.......................................................................1913
pair_style sw/intel command......................................................................1913
pair_style sw/kk command.........................................................................1913
pair_style sw/omp command......................................................................1913
pair_style table command..........................................................................1917
pair_style table/gpu command...................................................................1917
pair_style table/kk command.....................................................................1917
pair_style table/omp command..................................................................1917
pair_style table/rx command......................................................................1922
pair_style table/rx/kk command.................................................................1922
pair_style tersoff command........................................................................1927
pair_style tersoff/table command...............................................................1927
pair_style tersoff/gpu.................................................................................1927
pair_style tersoff/intel................................................................................1927
pair_style tersoff/kk...................................................................................1927
pair_style tersoff/omp................................................................................1927
pair_style tersoff/table/omp command.......................................................1927
pair_style tersoff/mod command................................................................1933
pair_style tersoff/mod/c command.............................................................1933
pair_style tersoff/mod/gpu command.........................................................1933
pair_style tersoff/mod/kk command...........................................................1933
pair_style tersoff/mod/omp command........................................................1933
pair_style tersoff/mod/c/omp command.....................................................1933
pair_style tersoff/zbl command..................................................................1938
pair_style tersoff/zbl/gpu command...........................................................1938
pair_style tersoff/zbl/kk command.............................................................1938
pair_style tersoff/zbl/omp command..........................................................1938
pair_style thole command..........................................................................1945
pair_style lj/cut/thole/long command.........................................................1945
pair_style lj/cut/thole/long/omp command.................................................1945
pair_style tri/lj command...........................................................................1949
pair_style ufm command............................................................................1951
pair_style ufm/gpu command.....................................................................1951
pair_style ufm/omp command....................................................................1951
pair_style ufm/opt command......................................................................1951
pair_style vashishta command...................................................................1954
pair_style vashishta/gpu command............................................................1954
pair_style vashishta/omp command...........................................................1954
pair_style vashishta/kk command..............................................................1954
pair_style vashishta/table command..........................................................1954
pair_style vashishta/table/omp command..................................................1954
pair_style yukawa command......................................................................1959
xxiv

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
pair_style yukawa/gpu command...............................................................1959
pair_style yukawa/omp command..............................................................1959
pair_style yukawa/kk command.................................................................1959
pair_style yukawa/colloid command..........................................................1961
pair_style yukawa/colloid/gpu command...................................................1961
pair_style yukawa/colloid/omp command...................................................1961
pair_style zbl command..............................................................................1964
pair_style zbl/gpu command......................................................................1964
pair_style zbl/kk command.........................................................................1964
pair_style zbl/omp command......................................................................1964
pair_style zero command...........................................................................1967
bond_style class2 command.......................................................................1969
bond_style class2/omp command...............................................................1969
bond_style class2/kk command..................................................................1969
bond_style fene command..........................................................................1971
bond_style fene/intel command..................................................................1971
bond_style fene/kk command.....................................................................1971
bond_style fene/omp command..................................................................1971
bond_style fene/expand command.............................................................1973
bond_style fene/expand/omp command.....................................................1973
bond_style gromos command.....................................................................1975
bond_style gromos/omp command.............................................................1975
bond_style harmonic command..................................................................1977
bond_style harmonic/intel command.........................................................1977
bond_style harmonic/kk command.............................................................1977
bond_style harmonic/omp command..........................................................1977
bond_style harmonic/shift command..........................................................1979
bond_style harmonic/shift/omp command..................................................1979
bond_style harmonic/shift/cut command...................................................1981
bond_style harmonic/shift/cut/omp command...........................................1981
bond_style hybrid command......................................................................1983
bond_style morse command.......................................................................1985
bond_style morse/omp command...............................................................1985
bond_style none command.........................................................................1987
bond_style nonlinear command.................................................................1988
bond_style nonlinear/omp command..........................................................1988
bond_style oxdna/fene command...............................................................1990
bond_style oxdna2/fene command.............................................................1990
bond_style quartic command.....................................................................1992
bond_style quartic/omp command.............................................................1992
bond_style table command.........................................................................1994
bond_style table/omp command.................................................................1994
bond_style zero command..........................................................................1997
angle_style charmm command...................................................................1998
angle_style charmm/intel command...........................................................1998
angle_style charmm/kk command..............................................................1998
angle_style charmm/omp command...........................................................1998
xxv

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
angle_style class2 command......................................................................2000
angle_style class2/omp command..............................................................2000
angle_style class2/kk command.................................................................2000
angle_style class2/p6 command.................................................................2000
angle_style cosine command......................................................................2003
angle_style cosine/omp command..............................................................2003
angle_style cosine/buck6d command.........................................................2005
angle_style cosine/delta command.............................................................2007
angle_style cosine/delta/omp command.....................................................2007
angle_style cosine/periodic command........................................................2009
angle_style cosine/periodic/omp command................................................2009
angle_style cosine/shift command..............................................................2011
angle_style cosine/shift/omp command......................................................2011
angle_style cosine/shift/exp command.......................................................2013
angle_style cosine/shift/exp/omp command...............................................2013
angle_style cosine/squared command........................................................2015
angle_style cosine/squared/omp command................................................2015
angle_style dipole command......................................................................2017
angle_style dipole/omp command..............................................................2017
angle_style fourier command.....................................................................2020
angle_style fourier/omp command.............................................................2020
angle_style fourier/simple command.........................................................2022
angle_style fourier/simple/omp command.................................................2022
angle_style harmonic command.................................................................2024
angle_style harmonic/intel command.........................................................2024
angle_style harmonic/kk command............................................................2024
angle_style harmonic/omp command.........................................................2024
angle_style hybrid command......................................................................2026
angle_style none command........................................................................2028
angle_style quartic command....................................................................2029
angle_style quartic/omp command............................................................2029
angle_style sdk command..........................................................................2031
angle_style table command........................................................................2032
angle_style table/omp command................................................................2032
angle_style zero command.........................................................................2035
dihedral_style charmm command..............................................................2036
dihedral_style charmm/intel command......................................................2036
dihedral_style charmm/kk command.........................................................2036
dihedral_style charmm/omp command......................................................2036
dihedral_style charmmfsw command.........................................................2036
dihedral_style class2 command.................................................................2039
dihedral_style class2/omp command..........................................................2039
dihedral_style class2/kk command.............................................................2039
dihedral_style cosine/shift/exp command..................................................2043
dihedral_style cosine/shift/exp/omp command..........................................2043
dihedral_style fourier command................................................................2045
dihedral_style fourier/intel command........................................................2045
xxvi

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
dihedral_style fourier/omp command........................................................2045
dihedral_style harmonic command............................................................2047
dihedral_style harmonic/intel command....................................................2047
dihedral_style harmonic/omp command....................................................2047
dihedral_style helix command....................................................................2049
dihedral_style helix/omp command............................................................2049
dihedral_style hybrid command.................................................................2051
dihedral_style multi/harmonic command...................................................2053
dihedral_style multi/harmonic/omp command...........................................2053
dihedral_style nharmonic command..........................................................2055
dihedral_style nharmonic/omp command..................................................2055
dihedral_style none command....................................................................2057
dihedral_style opls command.....................................................................2058
dihedral_style opls/intel command.............................................................2058
dihedral_style opls/kk command................................................................2058
dihedral_style opls/omp command.............................................................2058
dihedral_style quadratic command............................................................2060
dihedral_style quadratic/omp command....................................................2060
dihedral_style spherical command.............................................................2062
dihedral_style table command...................................................................2064
dihedral_style table/omp command...........................................................2064
dihedral_style zero command....................................................................2068
improper_style class2 command................................................................2069
improper_style class2/omp command........................................................2069
improper_style class2/kk command...........................................................2069
improper_style cossq command.................................................................2072
improper_style cossq/omp command.........................................................2072
improper_style cvff command....................................................................2074
improper_style cvff/intel command............................................................2074
improper_style cvff/omp command............................................................2074
improper_style distance command............................................................2076
improper_style fourier command...............................................................2078
improper_style fourier/omp command.......................................................2078
improper_style harmonic command...........................................................2080
improper_style harmonic/intel command...................................................2080
improper_style harmonic/kk command......................................................2080
improper_style harmonic/omp command...................................................2080
improper_style hybrid command................................................................2082
improper_style inversion/harmonic command...........................................2084
improper_style none command..................................................................2086
improper_style ring command...................................................................2087
improper_style ring/omp command...........................................................2087
improper_style umbrella command............................................................2089
improper_style umbrella/omp command....................................................2089
improper_style zero command...................................................................2091
fix atc command.........................................................................................2092
fix_modify AtC add_molecule.....................................................................2098
xxvii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
syntax...................................................................................................2098
examples..............................................................................................2098
description...........................................................................................2098
restrictions...........................................................................................2098
related..................................................................................................2098
default..................................................................................................2098
fix_modify AtC add_species........................................................................2098
syntax...................................................................................................2098
examples..............................................................................................2098
description...........................................................................................2099
restrictions...........................................................................................2099
related..................................................................................................2099
default..................................................................................................2099
fix_modify AtC atom_element_map............................................................2099
syntax...................................................................................................2099
examples..............................................................................................2099
description...........................................................................................2099
restrictions...........................................................................................2099
related..................................................................................................2099
default..................................................................................................2099
fix_modify AtC atom_weight.......................................................................2100
syntax...................................................................................................2100
examples..............................................................................................2100
description...........................................................................................2100
restrictions...........................................................................................2100
related..................................................................................................2100
default..................................................................................................2100
fix_modify AtC atomic_charge....................................................................2100
syntax...................................................................................................2100
examples..............................................................................................2101
description...........................................................................................2101
restrictions...........................................................................................2101
related..................................................................................................2101
default..................................................................................................2101
fix_modify AtC boundary............................................................................2101
syntax...................................................................................................2101
examples..............................................................................................2101
description...........................................................................................2101
restrictions...........................................................................................2101
default..................................................................................................2101
fix_modify AtC boundary_dynamics...........................................................2102
syntax...................................................................................................2102
description...........................................................................................2102
restrictions...........................................................................................2102
related..................................................................................................2102
default..................................................................................................2102
fix_modify AtC boundary_faceset...............................................................2102
xxviii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
syntax...................................................................................................2102
examples..............................................................................................2102
description...........................................................................................2102
restrictions...........................................................................................2102
related..................................................................................................2103
default..................................................................................................2103
fix_modify AtC output boundary_integral..................................................2103
syntax...................................................................................................2103
examples..............................................................................................2103
description...........................................................................................2103
restrictions...........................................................................................2103
related..................................................................................................2103
default..................................................................................................2103
fix_modify AtC consistent_fe_initialization.................................................2103
syntax...................................................................................................2103
examples..............................................................................................2104
description...........................................................................................2104
restrictions...........................................................................................2104
related..................................................................................................2104
default..................................................................................................2104
fix_modify AtC output contour_integral.....................................................2104
syntax...................................................................................................2104
examples..............................................................................................2104
description...........................................................................................2104
restrictions...........................................................................................2104
related..................................................................................................2104
default..................................................................................................2105
fix_modify AtC control................................................................................2105
syntax...................................................................................................2105
examples..............................................................................................2105
description...........................................................................................2105
restrictions...........................................................................................2105
related..................................................................................................2105
default..................................................................................................2105
fix_modify AtC control momentum.............................................................2106
syntax...................................................................................................2106
examples..............................................................................................2106
description...........................................................................................2106
restrictions...........................................................................................2106
related..................................................................................................2106
default..................................................................................................2106
fix_modify AtC control thermal..................................................................2107
syntax...................................................................................................2107
examples..............................................................................................2107
description...........................................................................................2107
restrictions...........................................................................................2107
related..................................................................................................2107
xxix

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
default..................................................................................................2108
fix_modify AtC control thermal correction_max_iterations........................2108
syntax...................................................................................................2108
examples..............................................................................................2108
description...........................................................................................2108
restrictions...........................................................................................2108
related..................................................................................................2108
default..................................................................................................2108
fix_modify AtC decomposition....................................................................2108
syntax...................................................................................................2108
examples..............................................................................................2109
description...........................................................................................2109
restrictions...........................................................................................2109
related..................................................................................................2109
default..................................................................................................2109
fix_modify AtC extrinsic electron_integration............................................2109
syntax...................................................................................................2109
examples..............................................................................................2109
description...........................................................................................2109
restrictions...........................................................................................2109
default..................................................................................................2110
fix_modify AtC equilibrium_start...............................................................2110
syntax...................................................................................................2110
examples..............................................................................................2110
description...........................................................................................2110
restrictions...........................................................................................2110
related..................................................................................................2110
default..................................................................................................2110
fix_modify AtC extrinsic exchange.............................................................2110
syntax...................................................................................................2110
examples..............................................................................................2110
description...........................................................................................2111
restrictions...........................................................................................2111
related..................................................................................................2111
default..................................................................................................2111
fix_modify AtC fe_md_boundary.................................................................2111
syntax...................................................................................................2111
examples..............................................................................................2111
description...........................................................................................2111
restrictions...........................................................................................2111
related..................................................................................................2111
default..................................................................................................2112
fix_modify AtC fem create mesh................................................................2112
syntax...................................................................................................2112
examples..............................................................................................2112
description...........................................................................................2112
restrictions...........................................................................................2112
xxx

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
related..................................................................................................2112
default..................................................................................................2112
fix_modify AtC filter scale..........................................................................2112
syntax...................................................................................................2112
examples..............................................................................................2112
description...........................................................................................2113
restrictions...........................................................................................2113
related..................................................................................................2113
default..................................................................................................2113
fix_modify AtC filter type...........................................................................2113
syntax...................................................................................................2113
examples..............................................................................................2113
description...........................................................................................2113
restrictions...........................................................................................2113
related..................................................................................................2113
default..................................................................................................2113
fix atc command.........................................................................................2114
syntax...................................................................................................2114
examples..............................................................................................2114
description...........................................................................................2114
restrictions...........................................................................................2116
related..................................................................................................2116
default..................................................................................................2118
fix_modify AtC fix_flux................................................................................2118
syntax...................................................................................................2118
examples..............................................................................................2118
description...........................................................................................2119
restrictions...........................................................................................2119
related..................................................................................................2119
default..................................................................................................2119
fix_modify AtC fix.......................................................................................2119
syntax...................................................................................................2119
examples..............................................................................................2119
description...........................................................................................2119
restrictions...........................................................................................2119
related..................................................................................................2119
default..................................................................................................2119
fix_modify AtC computes............................................................................2120
syntax...................................................................................................2120
examples..............................................................................................2120
description...........................................................................................2120
restrictions...........................................................................................2120
related..................................................................................................2120
default..................................................................................................2120
fix_modify AtC fields..................................................................................2121
syntax...................................................................................................2121
examples..............................................................................................2121
xxxi

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
description...........................................................................................2121
restrictions...........................................................................................2122
related..................................................................................................2122
default..................................................................................................2122
fix_modify AtC gradients............................................................................2122
syntax...................................................................................................2122
examples..............................................................................................2122
description...........................................................................................2122
restrictions...........................................................................................2122
related..................................................................................................2122
default..................................................................................................2122
fix_modify AtC kernel.................................................................................2123
syntax...................................................................................................2123
examples..............................................................................................2123
description...........................................................................................2123
restrictions...........................................................................................2123
related..................................................................................................2123
default..................................................................................................2123
fix_modify AtC on_the_fly...........................................................................2123
syntax...................................................................................................2124
examples..............................................................................................2124
description...........................................................................................2124
restrictions...........................................................................................2124
related..................................................................................................2124
default..................................................................................................2124
fix_modify AtC rates...................................................................................2124
syntax...................................................................................................2124
examples..............................................................................................2125
description...........................................................................................2125
restrictions...........................................................................................2125
related..................................................................................................2125
default..................................................................................................2125
fix_modify AtC initial..................................................................................2125
syntax...................................................................................................2125
examples..............................................................................................2125
description...........................................................................................2125
restrictions...........................................................................................2125
default..................................................................................................2126
fix_modify AtC internal_atom_integrate.....................................................2126
syntax...................................................................................................2126
description...........................................................................................2126
default..................................................................................................2126
fix_modify AtC internal_element_set..........................................................2126
syntax...................................................................................................2126
examples..............................................................................................2126
description...........................................................................................2126
restrictions...........................................................................................2127
xxxii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
related..................................................................................................2127
default..................................................................................................2127
fix_modify AtC internal_quadrature...........................................................2127
syntax...................................................................................................2127
examples..............................................................................................2127
description...........................................................................................2127
optional................................................................................................2127
restrictions...........................................................................................2127
related..................................................................................................2127
default..................................................................................................2127
fix_modify AtC kernel.................................................................................2128
syntax...................................................................................................2128
examples..............................................................................................2128
description...........................................................................................2128
restrictions...........................................................................................2128
related..................................................................................................2128
default..................................................................................................2128
fix_modify AtC control localized_lambda...................................................2128
syntax...................................................................................................2128
examples..............................................................................................2129
description...........................................................................................2129
restrictions...........................................................................................2129
related..................................................................................................2129
default..................................................................................................2129
fix_modify AtC control lumped_lambda_solve............................................2129
syntax...................................................................................................2129
examples..............................................................................................2129
description...........................................................................................2129
restrictions...........................................................................................2129
related..................................................................................................2129
default..................................................................................................2129
fix_modify AtC control mask_direction......................................................2130
syntax...................................................................................................2130
examples..............................................................................................2130
description...........................................................................................2130
restrictions...........................................................................................2130
related..................................................................................................2130
default..................................................................................................2130
fix_modify AtC mass_matrix.......................................................................2130
syntax...................................................................................................2130
examples..............................................................................................2130
description...........................................................................................2130
restrictions...........................................................................................2130
related..................................................................................................2130
default..................................................................................................2131
fix_modify AtC material..............................................................................2131
syntax...................................................................................................2131
xxxiii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
examples..............................................................................................2131
description...........................................................................................2131
restrictions...........................................................................................2131
related..................................................................................................2131
default..................................................................................................2131
fix_modify AtC mesh add_to_nodeset.........................................................2131
syntax...................................................................................................2131
examples..............................................................................................2132
description...........................................................................................2132
restrictions...........................................................................................2132
related..................................................................................................2132
default..................................................................................................2132
fix_modify AtC mesh create.......................................................................2132
syntax...................................................................................................2132
examples..............................................................................................2132
description...........................................................................................2132
restrictions...........................................................................................2132
related..................................................................................................2132
default..................................................................................................2132
fix_modify AtC mesh create_elementset....................................................2133
syntax...................................................................................................2133
examples..............................................................................................2133
description...........................................................................................2133
restrictions...........................................................................................2133
related..................................................................................................2133
default..................................................................................................2133
fix_modify AtC mesh create_faceset box....................................................2133
syntax...................................................................................................2133
examples..............................................................................................2134
description...........................................................................................2134
restrictions...........................................................................................2134
related..................................................................................................2134
default..................................................................................................2134
fix_modify AtC mesh create_faceset plane.................................................2134
syntax...................................................................................................2134
examples..............................................................................................2134
description...........................................................................................2134
restrictions...........................................................................................2134
related..................................................................................................2134
default..................................................................................................2135
fix_modify AtC mesh create_nodeset.........................................................2135
syntax...................................................................................................2135
examples..............................................................................................2135
description...........................................................................................2135
restrictions...........................................................................................2135
related..................................................................................................2135
default..................................................................................................2135
xxxiv

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
fix_modify AtC mesh delete_elements........................................................2135
syntax...................................................................................................2135
examples..............................................................................................2136
description...........................................................................................2136
restrictions...........................................................................................2136
related..................................................................................................2136
default..................................................................................................2136
fix_modify AtC mesh nodeset_to_elementset.............................................2136
syntax...................................................................................................2136
examples..............................................................................................2136
description...........................................................................................2136
restrictions...........................................................................................2136
related..................................................................................................2136
default..................................................................................................2136
fix_modify AtC mesh output.......................................................................2137
syntax...................................................................................................2137
examples..............................................................................................2137
description...........................................................................................2137
restrictions...........................................................................................2137
related..................................................................................................2137
default..................................................................................................2137
fix_modify AtC mesh quadrature................................................................2137
syntax...................................................................................................2137
examples..............................................................................................2137
description...........................................................................................2137
restrictions...........................................................................................2138
related..................................................................................................2138
default..................................................................................................2138
fix_modify AtC mesh read..........................................................................2138
syntax...................................................................................................2138
examples..............................................................................................2138
description...........................................................................................2138
restrictions...........................................................................................2138
related..................................................................................................2138
default..................................................................................................2138
fix_modify AtC mesh write.........................................................................2138
syntax...................................................................................................2138
examples..............................................................................................2139
description...........................................................................................2139
restrictions...........................................................................................2139
related..................................................................................................2139
default..................................................................................................2139
fix_modify AtC time_integration (momentum)...........................................2139
syntax...................................................................................................2139
description...........................................................................................2139
examples..............................................................................................2139
description...........................................................................................2139
xxxv

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
related..................................................................................................2139
default..................................................................................................2140
fix_modify AtC output.................................................................................2140
syntax...................................................................................................2140
examples..............................................................................................2140
description...........................................................................................2140
restrictions...........................................................................................2140
related..................................................................................................2140
default..................................................................................................2140
fix_modify AtC output elementset..............................................................2141
syntax...................................................................................................2141
examples..............................................................................................2141
description...........................................................................................2141
restrictions...........................................................................................2141
related..................................................................................................2141
default..................................................................................................2141
fix_modify AtC output nodeset...................................................................2141
syntax...................................................................................................2141
examples..............................................................................................2141
description...........................................................................................2142
restrictions...........................................................................................2142
related..................................................................................................2142
default..................................................................................................2142
fix_modify AtC pair_interactions/bond_interactions..................................2142
syntax...................................................................................................2142
examples..............................................................................................2142
description...........................................................................................2142
restrictions...........................................................................................2142
related..................................................................................................2142
default..................................................................................................2142
fix_modify AtC poisson_solver....................................................................2142
syntax...................................................................................................2143
examples..............................................................................................2143
description...........................................................................................2143
restrictions...........................................................................................2143
related..................................................................................................2143
default..................................................................................................2143
fix_modify AtC read_restart.......................................................................2143
syntax...................................................................................................2143
examples..............................................................................................2143
description...........................................................................................2143
restrictions...........................................................................................2143
related..................................................................................................2144
default..................................................................................................2144
fix_modify AtC remove_molecule...............................................................2144
syntax...................................................................................................2144
examples..............................................................................................2144
xxxvi

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
description...........................................................................................2144
restrictions...........................................................................................2144
related..................................................................................................2144
default..................................................................................................2144
fix_modify AtC remove_source...................................................................2144
syntax...................................................................................................2144
examples..............................................................................................2145
description...........................................................................................2145
restrictions...........................................................................................2145
related..................................................................................................2145
default..................................................................................................2145
fix_modify AtC remove_species..................................................................2145
syntax...................................................................................................2145
examples..............................................................................................2145
description...........................................................................................2145
restrictions...........................................................................................2145
related..................................................................................................2145
default..................................................................................................2145
fix_modify AtC reset_atomic_reference_positions......................................2146
syntax...................................................................................................2146
examples..............................................................................................2146
description...........................................................................................2146
restrictions...........................................................................................2146
related..................................................................................................2146
default..................................................................................................2146
fix_modify AtC reset_time..........................................................................2146
syntax...................................................................................................2146
examples..............................................................................................2146
description...........................................................................................2146
restrictions...........................................................................................2146
related..................................................................................................2146
default..................................................................................................2146
syntax...................................................................................................2147
examples..............................................................................................2147
description...........................................................................................2147
restrictions...........................................................................................2147
related..................................................................................................2147
default..................................................................................................2147
fix_modify AtC sample_frequency..............................................................2147
syntax...................................................................................................2147
examples..............................................................................................2147
description...........................................................................................2147
restrictions...........................................................................................2147
related..................................................................................................2148
default..................................................................................................2148
fix_modify AtC set......................................................................................2148
syntax...................................................................................................2148
xxxvii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
examples..............................................................................................2148
description...........................................................................................2148
restrictions...........................................................................................2148
related..................................................................................................2148
default..................................................................................................2148
fix_modify AtC source................................................................................2149
syntax...................................................................................................2149
examples..............................................................................................2149
description...........................................................................................2149
restrictions...........................................................................................2149
related..................................................................................................2149
default..................................................................................................2149
fix_modify AtC source_integration.............................................................2149
syntax...................................................................................................2149
examples..............................................................................................2149
description...........................................................................................2149
restrictions...........................................................................................2149
related..................................................................................................2150
default..................................................................................................2150
fix_modify AtC temperature_definition......................................................2150
syntax...................................................................................................2150
examples..............................................................................................2150
description...........................................................................................2150
restrictions...........................................................................................2150
default..................................................................................................2150
fix_modify AtC time_integration (thermal).................................................2150
syntax...................................................................................................2150
description...........................................................................................2151
examples..............................................................................................2151
description...........................................................................................2151
related..................................................................................................2151
default..................................................................................................2151
fix_modify AtC filter...................................................................................2151
syntax...................................................................................................2151
examples..............................................................................................2151
description...........................................................................................2151
restrictions...........................................................................................2151
related..................................................................................................2152
default..................................................................................................2152
fix_modify AtC track_displacement............................................................2152
syntax...................................................................................................2152
examples..............................................................................................2152
description...........................................................................................2152
restrictions...........................................................................................2152
default..................................................................................................2152
fix_modify AtC unfix_flux...........................................................................2152
syntax...................................................................................................2152
xxxviii

LAMMPS Users Manual

Table of Contents
LAMMPS Commands
examples..............................................................................................2153
description...........................................................................................2153
restrictions...........................................................................................2153
related..................................................................................................2153
default..................................................................................................2153
fix_modify AtC unfix...................................................................................2153
syntax...................................................................................................2153
examples..............................................................................................2153
description...........................................................................................2153
restrictions...........................................................................................2153
related..................................................................................................2153
default..................................................................................................2153
fix_modify AtC write_atom_weights...........................................................2154
syntax...................................................................................................2154
examples..............................................................................................2154
description...........................................................................................2154
restrictions...........................................................................................2154
related..................................................................................................2154
default..................................................................................................2154
fix_modify AtC write_restart......................................................................2154
syntax...................................................................................................2154
examples..............................................................................................2154
description...........................................................................................2154
restrictions...........................................................................................2154
related..................................................................................................2155
default..................................................................................................2155

xxxix

LAMMPS Documentation
16 Mar 2018 version
Version info:
The LAMMPS "version" is the date when it was released, such as 1 May 2010.
LAMMPS is updated continuously. Whenever we fix a bug or add a feature, we release
it immediately, and post a notice on this page of the WWW site. Every 2-4 months one
of the incremental releases is subjected to more thorough testing and labeled as a
stable version.
Each dated copy of LAMMPS contains all the features and bug-fixes up to and
including that 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 at the top of the first page of the manual
(this page).
• If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current development version of LAMMPS.
• If you browse the HTML doc pages included in your tarball, they describe the
version you have.
• The PDF file on the WWW site or in the tarball is updated about once per
month. This is because it is large, and we don't want it to be part of every patch.
• There is also a Developer.pdf file in the doc directory, which describes the
internal structure and algorithms of LAMMPS.
LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel Simulator.
LAMMPS is a classical molecular dynamics simulation code designed to run efficiently
on parallel computers. It was developed at Sandia National Laboratories, a US
Department of Energy facility, with funding from the DOE. It is an open-source code,
distributed freely under the terms of the GNU Public License (GPL).
The current core group of LAMMPS developers is 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
Past core developers include Paul Crozier, Ray Shan and Mark Stevens, all at Sandia.
The LAMMPS home page at http://lammps.sandia.gov has more information about
the code and its uses. Interaction with external LAMMPS developers, bug reports and
feature requests are mainly coordinated through the LAMMPS project on GitHub. The
lammps.org domain, currently hosting public continuous integration testing and
precompiled Linux RPM and Windows installer packages is located at Temple
University and managed by Richard Berger, richard.berger at temple.edu.

1

LAMMPS Users Manual
The LAMMPS documentation is organized into the following sections. If you find
errors or omissions in this manual or have suggestions for useful information to add,
please send an email to the developers so we can improve the LAMMPS
documentation.
Once you are familiar with LAMMPS, you may want to bookmark this page at
Section_commands.html#comm since it gives quick access to documentation for all
LAMMPS commands.
PDF file of the entire manual, generated by htmldoc
1. Introduction
1.1 What is LAMMPS
1.2 LAMMPS features
1.3 LAMMPS non-features
1.4 Open source distribution
1.5 Acknowledgments and citations
2. Getting started
2.1 What's in the LAMMPS distribution
2.2 Making LAMMPS
2.3 Making LAMMPS with optional packages
2.4 Building LAMMPS as a library
2.5 Running LAMMPS
2.6 Command-line options
2.7 Screen output
2.8 Tips for users of previous versions
3. Commands
3.1 LAMMPS input script
3.2 Parsing rules
3.3 Input script structure
3.4 Commands listed by category
3.5 Commands listed alphabetically
4. Packages
4.1 Standard packages
4.2 User packages
5. Accelerating LAMMPS performance
5.1 Measuring performance
5.2 Algorithms and code options to boost performace
5.3 Accelerator packages with optimized styles
5.3.1 GPU package
5.3.2 USER-INTEL package
5.3.3 KOKKOS package
5.3.4 USER-OMP package
5.3.5 OPT package
5.4 Comparison of various accelerator packages
6. How-to discussions
6.1 Restarting a simulation
6.2 2d simulations
6.3 CHARMM and AMBER force fields
6.4 Running multiple simulations from one input script
6.5 Multi-replica simulations
2

LAMMPS Users Manual

7.
8.
9.
10.

11.

12.

6.6 Granular models
6.7 TIP3P water model
6.8 TIP4P water model
6.9 SPC water model
6.10 Coupling LAMMPS to other codes
6.11 Visualizing LAMMPS snapshots
6.12 Triclinic (non-orthogonal) simulation boxes
6.13 NEMD simulations
6.14 Finite-size spherical and aspherical particles
6.15 Output from LAMMPS (thermo, dumps, computes, fixes, variables)
6.16 Thermostatting, barostatting, and compute temperature
6.17 Walls
6.18 Elastic constants
6.19 Library interface to LAMMPS
6.20 Calculating thermal conductivity
6.21 Calculating viscosity
6.22 Calculating a diffusion coefficient
6.23 Using chunks to calculate system properties
6.24 Setting parameters for pppm/disp
6.25 Polarizable models
6.26 Adiabatic core/shell model
6.27 Drude induced dipoles
Example problems
Performance & scalability
Additional tools
Modifying & extending LAMMPS
10.1 Atom styles
10.2 Bond, angle, dihedral, improper potentials
10.3 Compute styles
10.4 Dump styles
10.5 Dump custom output options
10.6 Fix styles
10.7 Input script commands
10.8 Kspace computations
10.9 Minimization styles
10.10 Pairwise potentials
10.11 Region styles
10.12 Body styles
10.13 Thermodynamic output options
10.14 Variable options
10.15 Submitting new features for inclusion in LAMMPS
Python interface
11.1 Overview of running LAMMPS from Python
11.2 Overview of using Python from a LAMMPS script
11.3 Building LAMMPS as a shared library
11.4 Installing the Python wrapper into Python
11.5 Extending Python with MPI to run in parallel
11.6 Testing the Python-LAMMPS interface
11.7 Using LAMMPS from Python
11.8 Example Python scripts that use LAMMPS
Errors
3

LAMMPS Users Manual
12.1 Common problems
12.2 Reporting bugs
12.3 Error & warning messages
13. Future and history
13.1 Coming attractions
13.2 Past versions

4

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

1. Introduction
This section provides an overview of what LAMMPS can and can't do, describes what
it means for LAMMPS to be an open-source code, and acknowledges the funding and
people who have contributed to LAMMPS over the years.
1.1
1.2
1.3
1.4
1.5

What is LAMMPS
LAMMPS features
LAMMPS non-features
Open source distribution
Acknowledgments and citations

1.1 What is LAMMPS
LAMMPS is a classical molecular dynamics code that models an ensemble of particles
in a liquid, solid, or gaseous state. It can model atomic, polymeric, biological, metallic,
granular, and coarse-grained systems using a variety of force fields and boundary
conditions.
For examples of LAMMPS simulations, see the Publications page of the LAMMPS
WWW Site.
LAMMPS runs efficiently on single-processor desktop or laptop machines, but is
designed for parallel computers. It will run on any parallel machine that compiles
C++ and supports the MPI message-passing library. This includes distributed- or
shared-memory parallel machines and Beowulf-style clusters.
LAMMPS can model systems with only a few particles up to millions or billions. See
Section 8 for information on LAMMPS performance and scalability, or the Benchmarks
section of the LAMMPS WWW Site.
LAMMPS is a freely-available open-source code, distributed under the terms of the
GNU Public License, which means you can use or modify the code however you wish.
See this section for a brief discussion of the open-source philosophy.
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 Section 10 for
more details.
The current version of LAMMPS is written in C++. Earlier versions were written in
F77 and F90. See Section 13 for more information on different versions. All versions
can be downloaded from the LAMMPS WWW Site.
LAMMPS was originally developed under a US Department of Energy CRADA
(Cooperative Research and Development Agreement) between two DOE labs and 3
5

LAMMPS Users Manual
companies. It is distributed by Sandia National Labs. See this section for more
information on LAMMPS funding and individuals who have contributed to LAMMPS.
In the most general sense, LAMMPS integrates Newton's equations of motion for
collections of atoms, molecules, or macroscopic particles that interact via short- or
long-range forces with a variety of initial and/or boundary conditions. For
computational efficiency 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. On parallel
machines, LAMMPS uses spatial-decomposition techniques to partition the simulation
domain into small 3d sub-domains, one of which is assigned to each processor.
Processors communicate and store "ghost" atom information for atoms that border
their sub-domain. LAMMPS is most efficient (in a parallel sense) for systems whose
particles fill a 3d rectangular box with roughly uniform density. Papers with technical
details of the algorithms used in LAMMPS are listed in this section.

1.2 LAMMPS features
This section highlights LAMMPS features, with pointers to specific commands which
give more details. If LAMMPS doesn't have your favorite interatomic potential,
boundary condition, or atom type, see Section 10, which describes how you can add it
to LAMMPS.
General features

• runs on a single processor or in parallel
• distributed-memory message-passing parallelism (MPI)
• spatial-decomposition of simulation domain for parallelism
• open-source distribution
• highly portable C++
• optional libraries used: MPI and single-processor FFT
• GPU (CUDA and OpenCL), Intel(R) Xeon Phi(TM) coprocessors, 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 thru library interface or provided Python
wrapper
• couple with other codes: LAMMPS calls other code, other code calls LAMMPS,
umbrella code calls both
Particle and model types

(atom style command)
• atoms
• coarse-grained particles (e.g. bead-spring polymers)
• united-atom polymers or organic molecules
6

LAMMPS Users Manual
• 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
• point dipole particles
• rigid collections of particles
• hybrid combinations of these
Force fields

(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 (COMPASS), hydrogen bond, tabulated
• charged pairwise potentials: Coulombic, point-dipole
• manybody potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM),
embedded ion method (EIM), EDIP, ADP, Stillinger-Weber, Tersoff, REBO,
AIREBO, ReaxFF, COMB, SNAP, Streitz-Mintmire, 3-body polymorphic
• long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald,
Wolf, PPPM (similar to particle-mesh Ewald)
• 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
• electron force field (eFF, AWPMD)
• bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable)
• angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic,
class 2 (COMPASS)
• dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2
(COMPASS), OPLS
• improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS)
• polymer potentials: all-atom, united-atom, bead-spring, breakable
• water potentials: TIP3P, TIP4P, SPC
• implicit solvent potentials: hydrodynamic lubrication, Debye
• force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS,
GROMACS, COMPASS options
• access to KIM archive of potentials via pair kim
• hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can
be used in one simulation
• overlaid potentials: superposition of multiple pair potentials
Atom creation

(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)
7

LAMMPS Users Manual
• replicate existing atoms multiple times
• displace atoms
Ensembles, constraints, and boundary conditions

(fix command)
• 2d or 3d systems
• orthogonal or non-orthogonal (triclinic symmetry) simulation domains
• constant NVE, NVT, NPT, NPH, Parinello/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
• Monte Carlo bond breaking, formation, swapping
• atom/molecule insertion and deletion
• walls of various kinds
• non-equilibrium molecular dynamics (NEMD)
• variety of additional boundary conditions and constraints
Integrators

(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
Diagnostics

• see the various flavors of the fix and compute commands
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
• spatial and time averaging of per-atom quantities
• time averaging of system-wide quantities
• atom snapshots in native, XYZ, XTC, DCD, CFG formats
8

LAMMPS Users Manual
Multi-replica models

nudged elastic band parallel replica dynamics temperature accelerated dynamics
parallel tempering
Pre- and post-processing

• Various pre- and post-processing serial tools are packaged with LAMMPS; see
these doc pages.
• 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.
Specialized features

LAMMPS can be built with optional packages which implement a variety of additional
capabilities. An overview of all the packages is given here.
These are some LAMMPS capabilities which you may not think of as typical classical
molecular dynamics options:
• static and dynamic load-balancing
• generalized aspherical particles
• stochastic rotation dynamics (SRD)
• real-time visualization and interactive MD
• calculate virtual diffraction patterns
• atom-to-continuum coupling with finite elements
• coupled rigid body integration via the POEMS library
• QM/MM coupling
• path-integral molecular dynamics (PIMD) and this as well
• Monte Carlo via GCMC and tfMC atom swapping and bond swapping
• Direct Simulation Monte Carlo for low-density fluids
• Peridynamics mesoscale modeling
• Lattice Boltzmann fluid
• targeted and steered molecular dynamics
• two-temperature electron model

1.3 LAMMPS non-features
LAMMPS is designed to efficiently compute Newton's equations of motion for a system
of interacting particles. Many of the tools needed to pre- and post-process the data for
such simulations are not included in the LAMMPS kernel for several reasons:
• the desire to keep LAMMPS simple
• they are not parallel operations
• other codes already do them
• limited development resources
Specifically, LAMMPS itself does not:
9

LAMMPS Users Manual
• run thru a GUI
• build molecular systems
• assign force-field coefficients automagically
• perform sophisticated analyses of your MD simulation
• visualize your MD simulation
• plot your output data
A few tools for pre- and post-processing tasks are provided as part of the LAMMPS
package; they are described in this section. However, many people use other codes or
write their own tools for these tasks.
As noted above, our group has also written and released a separate toolkit called
Pizza.py which addresses some of the listed bullets. It 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.
LAMMPS requires as input a list of initial atom coordinates and types, molecular
topology information, and force-field coefficients assigned to all atoms and bonds.
LAMMPS will not build molecular systems and assign force-field parameters for you.
For atomic systems LAMMPS provides a create_atoms command which places atoms
on solid-state lattices (fcc, bcc, user-defined, etc). Assigning small numbers of force
field coefficients can be done via the pair coeff, bond coeff, angle coeff, etc
commands. For molecular systems or more complicated simulation geometries, users
typically use another code as a builder and convert its output to LAMMPS input
format, or write their own code to generate atom coordinate and molecular topology
for LAMMPS to read in.
For complicated molecular systems (e.g. a protein), a multitude of topology
information and hundreds of force-field coefficients must typically be specified. We
suggest you use a program like CHARMM or AMBER or other molecular builders to
setup such problems and dump its information to a file. You can then reformat the file
as LAMMPS input. Some of the tools in this section can assist in this process.
Similarly, LAMMPS creates output files in a simple format. Most users post-process
these files with their own analysis tools or re-format them for input into other
programs, including visualization packages. If you are convinced you need to compute
something on-the-fly as LAMMPS runs, see Section 10 for a discussion of how you can
use the dump and compute and fix commands to print out data of your choosing. Keep
in mind that complicated computations can slow down the molecular dynamics
timestepping, particularly if the computations are not parallel, so it is often better to
leave such analysis to post-processing codes.
For high-quality visualization we recommend the following packages:
• VMD
• AtomEye
• OVITO
• ParaView
• PyMol
• Raster3d
10

LAMMPS Users Manual
• RasMol
Other features that LAMMPS does not yet (and may never) support are discussed in
Section 13.
Finally, these are freely-available molecular dynamics codes, most of them parallel,
which may be well-suited to the problems you want to model. They can also be used in
conjunction with LAMMPS to perform complementary modeling tasks.
• CHARMM
• AMBER
• NAMD
• NWCHEM
• DL_POLY
• Tinker
CHARMM, AMBER, NAMD, NWCHEM, and Tinker are designed primarily for
modeling biological molecules. CHARMM and AMBER use atom-decomposition
(replicated-data) strategies for parallelism; NAMD and NWCHEM use
spatial-decomposition approaches, similar to LAMMPS. Tinker is a serial code.
DL_POLY includes potentials for a variety of biological and non-biological materials;
both a replicated-data and spatial-decomposition version exist.

1.4 Open source distribution
LAMMPS comes with no warranty of any kind. As each source file states in its header,
it is a copyrighted code that is distributed free-of- charge, under the terms of the GNU
Public License (GPL). This is often referred to as open-source distribution - see
www.gnu.org or www.opensource.org for more details. The legal text of the GPL is in
the LICENSE file that is included in the LAMMPS distribution.
Here is a summary of what the GPL means for LAMMPS users:
(1) Anyone is free to use, 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 distribute it under the terms of the GPL. You should clearly annotate
such a code as a derivative version of LAMMPS.
(3) If you release any code that includes LAMMPS source code, then it must also be
open-sourced, meaning you distribute it under the terms of the GPL.
(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.
In the spirit of an open-source code, these are various ways you can contribute to
making LAMMPS better. You can send email to the developers on any of these items.

11

LAMMPS Users Manual
• Point prospective users to the LAMMPS WWW Site. Mention it in talks or link to
it from your WWW site.
• If you find an error or omission in this manual or on the LAMMPS WWW Site, or
have a suggestion for something to clarify or include, send an email to the
developers.
• If you find a bug, Section 12.2 describes how to report it.
• If you publish a paper using LAMMPS results, send the citation (and any cool
pictures or movies if you like) to add to the Publications, Pictures, and Movies
pages of the LAMMPS WWW Site, with links and attributions back to you.
• Create a new Makefile.machine that can be added to the src/MAKE directory.
• The tools sub-directory of the LAMMPS distribution has various stand-alone
codes for pre- and post-processing of LAMMPS data. More details are given in
Section 9. If you write a new tool that users will find useful, it can be added to
the LAMMPS distribution.
• LAMMPS is designed to be easy to extend with new code for features like
potentials, boundary conditions, diagnostic computations, etc. This section gives
details. If you add a feature of general interest, it can be added to the LAMMPS
distribution.
• The Benchmark page of the LAMMPS WWW Site lists LAMMPS performance on
various platforms. The files needed to run the benchmarks are part of the
LAMMPS distribution. If your machine is sufficiently different from those listed,
your timing data can be added to the page.
• You can send feedback for the User Comments page of the LAMMPS WWW
Site. It might be added to the page. No promises.
• Cash. Small denominations, unmarked bills preferred. Paper sack OK. Leave on
desk. VISA also accepted. Chocolate chip cookies encouraged.
1.5 Acknowledgments and citations
LAMMPS development has been funded by the US Department of Energy (DOE),
through its CRADA, LDRD, ASCI, and Genomes-to-Life programs and its OASCR and
OBER offices.
Specifically, work on the latest version was funded in part by the US Department of
Energy's Genomics:GTL program (www.doegenomestolife.org) under the project,
"Carbon Sequestration in Synechococcus Sp.: From Molecular Machines to
Hierarchical Modeling".
The following paper describe the basic parallel algorithms used in LAMMPS. If you
use LAMMPS results in your published work, please cite this paper and include a
pointer to the LAMMPS WWW Site (http://lammps.sandia.gov):
S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J
Comp Phys, 117, 1-19 (1995).
Other papers describing specific algorithms used in LAMMPS are listed under the
Citing LAMMPS link of the LAMMPS WWW page.
The Publications link on the LAMMPS WWW page lists papers that have cited
LAMMPS. If your paper is not listed there for some reason, feel free to send us the
info. If the simulations in your paper produced cool pictures or animations, we'll be
12

LAMMPS Users Manual
pleased to add them to the Pictures or Movies pages of the LAMMPS WWW site.
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
Past primary developers include Paul Crozier and Mark Stevens, both at Sandia, and
Ray Shan, now at Materials Design.
The following folks are responsible for significant contributions to the code, or other
aspects of the LAMMPS development effort. Many of the packages they have written
are somewhat unique to LAMMPS and the code would not be as general-purpose as it
is without their expertise and efforts.
• Axel Kohlmeyer (Temple U), akohlmey at gmail.com, SVN and Git repositories,
indefatigable mail list responder, USER-CGSDK, USER-OMP, USER-COLVARS,
USER-MOLFILE, USER-QMMM, USER-TALLY, and COMPRESS packages
• Roy Pollock (LLNL), Ewald and PPPM solvers
• Mike Brown (ORNL), brownw at ornl.gov, GPU and USER-INTEL package
• Greg Wagner (Sandia), gjwagne at sandia.gov, MEAM package for MEAM
potential
• Mike Parks (Sandia), mlparks at sandia.gov, PERI package for Peridynamics
• Rudra Mukherjee (JPL), Rudranarayan.M.Mukherjee at jpl.nasa.gov, POEMS
package for articulated rigid body motion
• Reese Jones (Sandia) and collaborators, rjones at sandia.gov, USER-ATC
package for atom/continuum coupling
• Ilya Valuev (JIHT), valuev at physik.hu-berlin.de, USER-AWPMD package for
wave-packet MD
• Christian Trott (U Tech Ilmenau), christian.trott at tu-ilmenau.de, USER-CUDA
and KOKKOS packages
• Andres Jaramillo-Botero (Caltech), ajaramil at wag.caltech.edu, USER-EFF
package for electron force field
• Christoph Kloss (JKU), Christoph.Kloss at jku.at, USER-LIGGGHTS package for
granular models and granular/fluid coupling
• Metin Aktulga (LBL), hmaktulga at lbl.gov, USER-REAXC package for C version
of ReaxFF
• Georg Gunzenmuller (EMI), georg.ganzenmueller at emi.fhg.de, USER-SMD and
USER-SPH packages
• Colin Denniston (U Western Ontario), cdennist at uwo.ca, USER-LB package
As discussed in Section 13, 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 (LLNL)
13

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

2. Getting Started
This section describes how to build and run LAMMPS, for both new and experienced
users.
2.1
2.2
2.3
2.4
2.5
2.6
2.7
2.8

What's in the LAMMPS distribution
Making LAMMPS
Making LAMMPS with optional packages
Building LAMMPS as a library
Running LAMMPS
Command-line options
Screen output
Tips for users of previous versions

2.1 What's in the LAMMPS distribution
When you download a LAMMPS tarball you will need to unzip and untar the
downloaded file with the following commands, after placing the tarball in an
appropriate directory.
tar -xzvf lammps*.tar.gz

This will create a LAMMPS directory containing two files and several sub-directories:
README text file
LICENSE the GNU General Public License (GPL)
bench
benchmark problems
doc
documentation
examples simple test problems
potentials embedded atom method (EAM) potential files
src
source files
tools
pre- and post-processing tools
Note that the download page also has links to download pre-build Windows installers,
as well as pre-built packages for several widely used Linux distributions. It also has
instructions for how to download/install LAMMPS for Macs (via Homebrew), and to
download and update LAMMPS from SVN and Git repositories, which gives you access
to the up-to-date sources that are used by the LAMMPS core developers.
The Windows and Linux packages for serial or parallel include only selected packages
and bug-fixes/upgrades listed on this page up to a certain date, as stated on the
download page. If you want an executable with non-included packages or that is more
current, then you'll need to build LAMMPS yourself, as discussed in the next section.
Skip to the Running LAMMPS sections for info on how to launch a LAMMPS Windows
executable on a Windows box.
14

LAMMPS Users Manual
2.2 Making LAMMPS
This section has the following sub-sections:
2.2.1
2.2.1
2.2.3
2.2.4
2.2.5
2.2.6

Read this first
Steps to build a LAMMPS executable
Common errors that can occur when making LAMMPS
Additional build tips
Building for a Mac
Building for Windows

Read this first

If you want to avoid building LAMMPS yourself, read the preceding section about
options available for downloading and installing executables. Details are discussed on
the download page.
Building LAMMPS can be simple or not-so-simple. If all you need are the default
packages installed in LAMMPS, and MPI is already installed on your machine, or you
just want to run LAMMPS in serial, then you can typically use the Makefile.mpi or
Makefile.serial files in src/MAKE by typing one of these lines (from the src dir):
make mpi
make serial

Note that on a facility supercomputer, there are often "modules" loaded in your
environment that provide the compilers and MPI you should use. In this case, the
"mpicxx" compile/link command in Makefile.mpi should simply work by accessing
those modules.
It may be the case that one of the other Makefile.machine files in the src/MAKE
sub-directories is a better match to your system (type "make" to see a list), you can
use it as-is by typing (for example):
make stampede

If any of these builds (with an existing Makefile.machine) works on your system, then
you're done!
If you need to install an optional package with a LAMMPS command you want to use,
and the package does not depend on an extra library, you can simply type
make name

before invoking (or re-invoking) the above steps. "Name" is the lower-case name of the
package, e.g. replica or user-misc.
If you want to do one of the following:
• use a LAMMPS command that requires an extra library (e.g. dump image)
15

LAMMPS Users Manual
• build with a package that requires an extra library
• build with an accelerator package that requires special compiler/linker settings
• run on a machine that has its own compilers, settings, or libraries
then building LAMMPS is more complicated. You may need to find where extra
libraries exist on your machine or install them if they don't. You may need to build
extra libraries that are included in the LAMMPS distribution, before building
LAMMPS itself. You may need to edit a Makefile.machine file to make it compatible
with your system.
Please read the following sections carefully. If you are not comfortable with makefiles,
or building codes on a Unix platform, or running an MPI job on your machine, please
find a local expert to help you. Many compilation, linking, and run problems users
experience are often not LAMMPS issues - they are peculiar to the user's system,
compilers, libraries, etc. Such questions are better answered by a local expert.
If you have a build problem that you are convinced is a LAMMPS issue (e.g. the
compiler complains about a line of LAMMPS source code), then please post the issue
to the LAMMPS mail list.
If you succeed in building LAMMPS on a new kind of machine, for which there isn't a
similar machine Makefile included in the src/MAKE/MACHINES directory, then send it
to the developers and we can include it in the LAMMPS distribution.
Steps to build a LAMMPS executable
Step 0

The src directory contains the C++ source and header files for LAMMPS. It also
contains a top-level Makefile and a MAKE sub-directory with low-level Makefile.* files
for many systems and machines. See the src/MAKE/README file for a quick overview
of what files are available and what sub-directories they are in.
The src/MAKE dir has a few files that should work as-is on many platforms. The
src/MAKE/OPTIONS dir has more that invoke additional compiler, MPI, and other
setting options commonly used by LAMMPS, to illustrate their syntax. The
src/MAKE/MACHINES dir has many more that have been tweaked or optimized for
specific machines. These files are all good starting points if you find you need to
change them for your machine. Put any file you edit into the src/MAKE/MINE
directory and it will be never be touched by any LAMMPS updates.
>From within the src directory, type "make" or "gmake". You should see a list of
available choices from src/MAKE and all of its sub-directories. If one of those has the
options you want or is the machine you want, you can type a command like:
make mpi

or
make serial

16

LAMMPS Users Manual
or
gmake mac

Note that the corresponding Makefile.machine can exist in src/MAKE or any of its
sub-directories. If a file with the same name appears in multiple places (not a good
idea), the order they are used is as follows: src/MAKE/MINE, src/MAKE,
src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference to a file you have
created/edited and put in src/MAKE/MINE.
Note that on a multi-processor or multi-core platform you can launch a parallel make,
by using the "-j" switch with the make command, which will build LAMMPS more
quickly.
If you get no errors and an executable like lmp_mpi or lmp_serial or lmp_mac is
produced, then you're done; it's your lucky day.
Note that by default only a few of LAMMPS optional packages are installed. To build
LAMMPS with optional packages, see this section below.
Step 1

If Step 0 did not work, you will need to create a low-level Makefile for your machine,
like Makefile.foo. You should make a copy of an existing Makefile.* in src/MAKE or
one of its sub-directories as a starting point. The only portions of the file you need to
edit are the first line, the "compiler/linker settings" section, and the
"LAMMPS-specific settings" section. When it works, put the edited file in
src/MAKE/MINE and it will not be altered by any future LAMMPS updates.
Step 2

Change the first line of Makefile.foo to list the word "foo" after the "#", and whatever
other options it will set. This is the line you will see if you just type "make".
Step 3

The "compiler/linker settings" section lists compiler and linker settings for your C++
compiler, including optimization flags. You can use g++, the open-source GNU
compiler, which is available on all Unix systems. You can also use mpicxx which will
typically be available if MPI is installed on your system, though you should check
which actual compiler it wraps. Vendor compilers often produce faster code. On boxes
with Intel CPUs, we suggest using the Intel icc compiler, which can be downloaded
from Intel's compiler site.
If building a C++ code on your machine requires additional libraries, then you should
list them as part of the LIB variable. You should not need to do this if you use mpicxx.
The DEPFLAGS setting is what triggers the C++ compiler to create a dependency list
for a source file. This speeds re-compilation when source (*.cpp) or header (*.h) files
are edited. Some compilers do not support dependency file creation, or may use a
different switch than -D. GNU g++ and Intel icc works with -D. If your compiler can't
create dependency files, then you'll need to create a Makefile.foo patterned after
17

LAMMPS Users Manual
Makefile.storm, which uses different rules that do not involve dependency files. Note
that when you build LAMMPS for the first time on a new platform, a long list of *.d
files will be printed out rapidly. This is not an error; it is the Makefile doing its normal
creation of dependencies.
Step 4

The "system-specific settings" section has several parts. Note that if you change any
-D setting in this section, you should do a full re-compile, after typing "make clean"
(which will describe different clean options).
The LMP_INC variable is used to include options that turn on ifdefs within the
LAMMPS code. The options that are currently recognized are:
• -DLAMMPS_GZIP
• -DLAMMPS_JPEG
• -DLAMMPS_PNG
• -DLAMMPS_FFMPEG
• -DLAMMPS_MEMALIGN
• -DLAMMPS_SMALLBIG
• -DLAMMPS_BIGBIG
• -DLAMMPS_SMALLSMALL
• -DLAMMPS_LONGLONG_TO_LONG
• -DLAMMPS_EXCEPTIONS
• -DPACK_ARRAY
• -DPACK_POINTER
• -DPACK_MEMCPY
The read_data and dump commands will read/write gzipped files if you compile with
-DLAMMPS_GZIP. It requires that your machine 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 calls
(required by popen()) can interfere 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 are provided in the COMPRESS package. From more details about compiling
LAMMPS with packages, please see below.
If you use -DLAMMPS_JPEG, the dump image command will be able to write out JPEG
image files. For JPEG files, you must also link LAMMPS with a JPEG library, as
described below. If you use -DLAMMPS_PNG, the dump image command will be able
to write out PNG image files. For PNG files, you must also link LAMMPS with a PNG
library, as described below. If neither of those two defines are used, LAMMPS will
only be able to write out uncompressed PPM image files.
If you use -DLAMMPS_FFMPEG, the dump movie command will be available to
support on-the-fly generation of rendered movies the need to store intermediate image
files. It requires that your machines supports the "popen" function in the standard
runtime library and that an FFmpeg executable can be found by LAMMPS during the
18

LAMMPS Users Manual
run.
NOTE: Similar to the note above, this option can conflict with high-speed networks,
because it uses popen().
Using -DLAMMPS_MEMALIGN= enables the use of the posix_memalign() call instead
of malloc() when large chunks or memory are allocated by LAMMPS. This can help to
make more efficient use of vector instructions of modern CPUS, since dynamically
allocated memory has to be aligned on larger than default byte boundaries (e.g. 16
bytes instead of 8 bytes on x86 type platforms) for optimal performance.
Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG,
-DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These
settings refer to use of 4-byte (small) vs 8-byte (big) integers within LAMMPS, as
specified in src/lmptype.h. The only reason to use the BIGBIG setting is to enable
simulation of huge molecular systems (which store bond topology info) with more than
2 billion atoms, or to track the image flags of moving atoms that wrap around a
periodic box more than 512 times. Normally, the only reason to use SMALLSMALL is
if your machine does not support 64-bit integers, though you can use SMALLSMALL
setting if you are running in serial or on a desktop machine or small cluster where you
will never run large systems or for long time (more than 2 billion atoms, more than 2
billion timesteps). See the Additional build tips section below for more details on these
settings.
Note that the USER-ATC package is not currently compatible with
-DLAMMPS_BIGBIG. Also the GPU package requires the lib/gpu library to be compiled
with the same setting, or the link will fail.
The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or MPI
version does not recognize "long long" data types. In this case a "long" data type is
likely already 64-bits, in which case this setting will convert to that data type.
The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative versions of
error handling inside of LAMMPS. This is useful when external codes drive LAMMPS
as a library. Using this option, LAMMPS errors do not kill the caller. Instead, the call
stack is unwound and control returns to the caller. The library interface provides the
lammps_has_error() and lammps_get_last_error_message() functions to detect and find
out more about a LAMMPS error.
Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY options
can make for faster parallel FFTs (in the PPPM solver) on some platforms. The
-DPACK_ARRAY setting is the default. See the kspace_style command for info about
PPPM. See Step 6 below for info about building LAMMPS with an FFT library.
Step 5

The 3 MPI variables are used to specify an MPI library to build LAMMPS with. Note
that you do not need to set these if you use the MPI compiler mpicxx for your CC and
LINK setting in the section above. The MPI wrapper knows where to find the needed
files.

19

LAMMPS Users Manual
If you want LAMMPS to run in parallel, you must have an MPI library installed on your
platform. If MPI is installed on your system in the usual place (under /usr/local), you
also may not need to specify these 3 variables, assuming /usr/local is in your path. On
some large parallel machines which use "modules" for their compile/link
environments, you may simply need to include the correct module in your build
environment, before building LAMMPS. Or the parallel machine may have a
vendor-provided MPI which the compiler has no trouble finding.
Failing this, these 3 variables can be used to specify where the mpi.h file (MPI_INC)
and the MPI library file (MPI_PATH) are found and the name of the library file
(MPI_LIB).
If you are installing MPI yourself, we recommend Argonne's MPICH2 or OpenMPI.
MPICH can be downloaded from the Argonne MPI site. OpenMPI can be downloaded
from the OpenMPI site. Other MPI packages should also work. If you are running on a
big parallel platform, your system people 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
find out how to build and link with it. If you use MPICH or OpenMPI, you will have to
configure and build it for your platform. The MPI configure script should have
compiler options to enable you to use the same compiler you are using for the
LAMMPS build, which can avoid problems that can arise when linking LAMMPS to the
MPI library.
If you just want to run LAMMPS on a single processor, you can use the dummy MPI
library provided in src/STUBS, since you don't need a true MPI library installed on
your system. See src/MAKE/Makefile.serial for how to specify the 3 MPI variables in
this case. You will also need to build the STUBS library for your platform before
making LAMMPS itself. Note that if you are building with src/MAKE/Makefile.serial,
e.g. by typing "make serial", then the STUBS library is built for you.
To build the STUBS library from the src directory, type "make mpi-stubs", or from the
src/STUBS dir, type "make". This should create a libmpi_stubs.a file suitable for
linking to LAMMPS. If the build fails, you will need to edit the STUBS/Makefile for
your platform.
The file STUBS/mpi.c provides a CPU timer function called MPI_Wtime() that calls
gettimeofday() . If your system doesn't support gettimeofday() , you'll 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.
Step 6

The 3 FFT variables allow you to specify an FFT library which LAMMPS uses (for
performing 1d FFTs) when running the particle-particle particle-mesh (PPPM) option
for long-range Coulombics via the kspace_style command.
LAMMPS supports common open-source or vendor-supplied FFT libraries for this
purpose. If you leave these 3 variables blank, LAMMPS will use the open-source KISS
FFT library, which is included in the LAMMPS distribution. This library is portable to
all platforms and for typical LAMMPS simulations is almost as fast as FFTW or vendor
optimized libraries. If you are not including the KSPACE package in your build, you
20

LAMMPS Users Manual
can also leave the 3 variables blank.
Otherwise, select which kinds of FFTs to use as part of the FFT_INC setting by a
switch of the form -DFFT_XXX. Recommended values for XXX are: MKL or FFTW3.
FFTW2 and NONE are supported as legacy options. Selecting -DFFT_FFTW will use
the FFTW3 library and -DFFT_NONE will use the KISS library described above.
You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables, so the
compiler and linker can find the needed FFT header and library files. Note that on
some large parallel machines which use "modules" for their compile/link
environments, you may simply need to include the correct module in your build
environment. Or the parallel machine may have a vendor-provided FFT library which
the compiler has no trouble finding. See the src/MAKE/OPTIONS/Makefile.fftw file for
an example of how to specify these variables to use the FFTW3 library.
FFTW is fast, portable library that should also work on any platform and typically be
faster than KISS FFT. You can download it from www.fftw.org. Both the legacy version
2.1.X and the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3.
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.
If you wish to have FFTW support for single-precision FFTs (see below about
-DFFT_SINGLE) in addition to the default double-precision FFTs, you will need to
build FFTW a second time for single-precision. For FFTW3, do this via:
make clean
./configure --enable-single; make; make install

which should produce the additional library libfftw3f.a.
For FFTW2, do this:
make clean
./configure --enable-float --enable-type-prefix; make; make install

which should produce the additional library libsfftw.a and additional include file
sfttw.a. Note that on some platforms FFTW2 has been pre-installed for both singleand double-precision, and may already have these files as well as libdfftw.a and
dfftw.h for double precision.
The FFT_INC variable also allows for a -DFFT_SINGLE setting that will use
single-precision FFTs with PPPM, which can speed-up long-range calculations,
particularly in parallel or on GPUs. Fourier transform and related PPPM operations
are somewhat insensitive to floating point truncation errors and thus do not always
need to be performed in double precision. Using the -DFFT_SINGLE setting trades off
a little accuracy for reduced memory use and parallel communication costs for
transposing 3d FFT data. Note that single precision FFTs have only been tested with
the FFTW3, FFTW2, MKL, and KISS FFT options.

21

LAMMPS Users Manual
When using -DFFT_SINGLE with FFTW3 or FFTW2, you need to build FFTW with
support for single-precision, as explained above. For FFTW3 you also need to include
-lfftw3f with the FFT_LIB setting, in addition to -lfftw3. For FFTW2, you also need to
specify -DFFT_SIZE with the FFT_INC setting and -lsfftw with the FFT_LIB setting (in
place of -lfftw). Similarly, if FFTW2 has been pre-installed with an explicit
double-precision library (libdfftw.a and not the default libfftw.a), then you can specify
-DFFT_SIZE (and not -DFFT_SINGLE), and specify -ldfftw to use double-precision
FFTs.
Step 7

The 3 JPG variables allow you to specify a JPEG and/or PNG library which LAMMPS
uses when writing out JPEG or PNG files via the dump image command. These can be
left blank if you do not use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches
discussed above in Step 4, since in that case JPEG/PNG output will be disabled.
A standard JPEG library usually goes by the name libjpeg.a or libjpeg.so and has an
associated header file jpeglib.h. Whichever JPEG library you have on your platform,
you'll need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that
the compiler and linker can find it.
A standard PNG library usually goes by the name libpng.a or libpng.so and has an
associated header file png.h. Whichever PNG library you have on your platform, you'll
need to set the appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the
compiler and linker can find it.
As before, if these header and library files are in the usual place on your machine, you
may not need to set these variables.
Step 8

Note that by default only a few of LAMMPS optional packages are installed. To build
LAMMPS with optional packages, see this section below, before proceeding to Step 9.
Step 9

That's it. Once you have a correct Makefile.foo, and you have pre-built any other
needed libraries (e.g. MPI, FFT, etc) all you need to do from the src directory is type
something like this:
make foo
make -j N foo
gmake foo
gmake -j N foo

The -j or -j N switches perform a parallel build which can be much faster, depending
on how many cores your compilation machine has. N is the number of cores the build
runs on.
You should get the executable lmp_foo when the build is complete.
Errors that can occur when making LAMMPS :h5
22

LAMMPS Users Manual
If an error occurs when building LAMMPS, the compiler or linker will state very
explicitly what the problem is. The error message should give you a hint as to which of
the steps above has failed, and what you need to do in order to fix it. Building a code
with a Makefile is a very logical process. The compiler and linker need to find the
appropriate files and those files need to be compatible with LAMMPS settings and
source files. When a make fails, there is usually a very simple reason, which you or a
local expert will need to fix.
Here are two non-obvious errors that can occur:
(1) If the make command breaks immediately with errors that indicate it can't find
files with a "*" in their names, this can be because your machine's native make doesn't
support wildcard expansion in a makefile. Try gmake instead of make. If that doesn't
work, try using a -f switch with your make command to use a pre-generated
Makefile.list which explicitly lists all the needed files, e.g.
make makelist
make -f Makefile.list linux
gmake -f Makefile.list mac

The first "make" command will create a current Makefile.list with all the file names in
your src dir. The 2nd "make" command (make or gmake) will use it to build LAMMPS.
Note that you should include/exclude any desired optional packages before using the
"make makelist" command.
(2) If you get an error that says something like 'identifier "atoll" is undefined', then
your machine does not support "long long" integers. Try using the
-DLAMMPS_LONGLONG_TO_LONG setting described above in Step 4.
Additional build tips
Building LAMMPS for multiple platforms.

You can make LAMMPS for multiple platforms from the same src directory. Each
target creates its own object sub-directory called Obj_target where it stores the
system-specific *.o files.
Cleaning up.

Typing "make clean-all" or "make clean-machine" will delete *.o object files created
when LAMMPS is built, for either all builds or for a particular machine.
Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL

As explained above, any of these 3 settings can be specified on the LMP_INC line in
your low-level src/MAKE/Makefile.foo.
The default is -DLAMMPS_SMALLBIG which allows for systems with up to 2^63
atoms and 2^63 timesteps (about 9e18). The atom limit is for atomic systems which
do not store bond topology info and thus do not require atom IDs. If you use atom IDs
for atomic systems (which is the default) or if you use a molecular model, which stores
bond topology info and thus requires atom IDs, the limit is 2^31 atoms (about 2
23

LAMMPS Users Manual
billion). This is because the IDs are stored in 32-bit integers.
Likewise, with this setting, the 3 image flags for each atom (see the dump doc page
for a discussion) are stored in a 32-bit integer, which means the atoms can only wrap
around a periodic box (in each dimension) at most 512 times. If atoms move through
the periodic box more than this many times, the image flags 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.
To allow for larger atomic systems with atom IDs or larger molecular systems or
larger image flags, compile with -DLAMMPS_BIGBIG. This stores atom IDs and image
flags in 64-bit integers. This enables atomic or molecular systems with atom IDS of up
to 2^63 atoms (about 9e18). And image flags will not "roll over" until they reach 2^20
= 1048576.
If your system does not support 8-byte integers, you will need to compile with the
-DLAMMPS_SMALLSMALL setting. This will restrict the total number of atoms (for
atomic or molecular systems) and timesteps to 2^31 (about 2 billion). Image flags will
roll over at 2^9 = 512.
Note that in src/lmptype.h there are definitions of all these data types as well as the
MPI data types associated with them. The MPI types need to be consistent with the
associated C data types, or else LAMMPS will generate a run-time error. As far as we
know, the settings defined in src/lmptype.h are portable and work on every current
system.
In all cases, the size of problem that can be run on a per-processor basis is limited by
4-byte integer storage to 2^31 atoms per processor (about 2 billion). This should not
normally be a limitation since such a problem would have a huge per-processor
memory footprint due to neighbor lists and would run very slowly in terms of CPU
secs/timestep.
Building for a Mac

OS X is a derivative of BSD Unix, so it should just work. See the
src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files.
Building for Windows

If you want to build a Windows version of LAMMPS, you can build it yourself, but it
may require some effort. LAMMPS expects a Unix-like build environment for the
default build procedure. This can be done using either Cygwin or MinGW; the latter
also exists as a ready-to-use Linux-to-Windows cross-compiler in several Linux
distributions. In these cases, you can do the installation after installing several
unix-style commands like make, grep, sed and bash with some shell utilities.
For Cygwin and the MinGW cross-compilers, suitable makefiles are provided in
src/MAKE/MACHINES. When using other compilers, like Visual C++ or Intel
compilers for Windows, you may have to implement your own build system. Due to
differences between the Windows OS and Windows system libraries to Unix-like
environments like Linux or MacOS, when compiling for Windows a few adjustments
24

LAMMPS Users Manual
may be needed:
• Do not set the -DLAMMPS_MEMALIGN define (see LMP_INC makefile variable)
• Add -lwsock32 -lpsapi to the linker flags (see LIB makefile variable)
• Try adding -static-libgcc or -static or both to the linker flags when your
LAMMPS executable complains about missing .dll files
Since none of the current LAMMPS core developers has significant experience
building executables on Windows, we are happy to distribute contributed instructions
and modifications to improve the situation, but we cannot provide support for those.
With the so-called "Anniversary Update" to Windows 10, there is a Ubuntu Linux
subsystem available for Windows, that can be installed and then used to
compile/install LAMMPS as if you are running on a Ubuntu Linux system instead of
Windows.
As an alternative, you can download pre-compiled installer packages from
packages.lammps.org/windows.html. These executables are built with most optional
packages included and the download includes documentation, potential files, some
tools and many examples, but no source code.
2.3 Making LAMMPS with optional packages
This section has the following sub-sections:
2.3.1 Package basics
2.3.2 Including/excluding packages
2.3.3 Packages that require extra libraries
Package basics:

The source code for LAMMPS is structured as a set of core files which are always
included, plus optional packages. Packages are groups of files that enable a specific
set of features. For example, force fields for molecular systems or granular systems
are in packages.
Section 4 in the manual has details about all the packages, which come in two flavors:
standard and user packages. It also has specific instructions for building LAMMPS
with any package which requires an extra library. General instructions are below.
You can see the list of all packages by typing "make package" from within the src
directory of the LAMMPS distribution. It will also list various make commands that
can be used to manage packages.
If you use a command in a LAMMPS input script that is part of a package, you must
have built LAMMPS with that package, else you will get an error that the style is
invalid or the command is unknown. Every command's doc page specifies if it is part
of a package. You can type
lmp_machine -h

25

LAMMPS Users Manual
to run your executable with the optional -h command-line switch for "help", which will
list the styles and commands known to your executable, and immediately exit.
Including/excluding packages

To use (or not use) a package you must install it (or un-install it) before building
LAMMPS. From the src directory, this is as simple as:
make yes-colloid
make mpi

or
make no-user-omp
make mpi

NOTE: You should NOT install/un-install packages and build LAMMPS in a single
make command using 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 command.
Any package can be installed or not in a LAMMPS build, independent of all other
packages. However, some packages include files derived from files in other packages.
LAMMPS checks for this and does the right thing. I.e. 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: The one exception is that we do not recommend building with both the
KOKKOS package installed and any of the other acceleration packages (GPU, OPT,
USER-INTEL, USER-OMP) also installed. This is because of how Kokkos sometimes
builds using a wrapper compiler which can make it difficult to invoke all the
compile/link flags correctly for both Kokkos and non-Kokkos files.
If you will never run simulations that use the features in a particular packages, there
is no reason to include it in your build. For some packages, this will keep you from
having to build extra libraries, and will also produce a smaller executable which may
run a bit faster.
When you download a LAMMPS tarball, three packages are pre-installed in the src
directory -- KSPACE, MANYBODY, MOLECULE -- because they are so commonly used.
When you download LAMMPS source files from the SVN or Git repositories, no
packages are pre-installed.
Packages are installed or un-installed by typing
make yes-name
make no-name

where "name" is the name of the package in lower-case, e.g. name = kspace for the
KSPACE package or name = user-atc for the USER-ATC package. You can also type
any of these commands:

26

LAMMPS Users Manual
make yes-all
install all packages
make no-all
un-install all packages
make yes-standard or make yes-std install standard packages
make no-standard or make no-std un-install standard packages
make yes-user
install user packages
make no-user
un-install user packages
make yes-lib
install packages that require extra libraries
make no-lib
un-install packages that require extra libraries
make yes-ext
install packages that require external libraries
make no-ext
un-install 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 works by simply moving files back and
forth between the main src directory and sub-directories with the package name (e.g.
src/KSPACE, src/USER-ATC), so that the files are included or excluded when LAMMPS
is built. After you have installed or un-installed a package, you must re-build LAMMPS
for the action to take effect.
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 have downloaded a patch from the LAMMPS
web site.
Typing "make package-status" or "make ps" will 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.
Typing "make package-installed" or "make pi" will list which packages are currently
installed, without listing the status of packages that are not installed.
Typing "make package-update" or "make pu" will overwrite src files with files from the
package sub-directories if the package is installed. It should be used after a patch has
been applied, since patches only update the files in the package sub-directory, but not
the src files.
Typing "make package-overwrite" will overwrite files in the package sub-directories
with src files.
Typing "make package-diff" lists all differences between these files.
Again, just type "make package" to see all of the package-related make options.
Packages that require extra libraries

A few of the standard and user packages require extra libraries. See Section 4 for two
tables of packages which indicate which ones require libraries. For each such
package, the Section 4 doc page gives details on how to build the extra library,
including how to download it if necessary. The basic ideas are summarized here.
27

LAMMPS Users Manual
System libraries:
Packages in the tables Section 4 with a "sys" in the last column link to system libraries
that typically already exist on your machine. E.g. the python package links to a system
Python library. If your machine does not have the required library, you will have to
download and install it on your machine, in either the system or user space.
Internal libraries:
Packages in the tables Section 4 with an "int" in the last column link to internal
libraries whose source code is included with LAMMPS, in the lib/name directory
where name is the package name. You must first build the library in that directory
before building LAMMPS with that package installed. E.g. the gpu package links to a
library you build in the lib/gpu dir. You can often do the build in one step by typing
"make lib-name args=..." from the src dir, with appropriate arguments. You can leave
off the args to see a help message. See Section 4 for details for each package.
External libraries:
Packages in the tables Section 4 with an "ext" in the last column link to external
libraries whose source code is not included with LAMMPS. You must first download
and install the library before building LAMMPS with that package installed. E.g. the
voronoi package links to the freely available Voro++ library. You can often do the
download/build in one step by typing "make lib-name args=..." from the src dir, with
appropriate arguments. You can leave off the args to see a help message. See Section
4 for details for each package.
Possible errors:
There are various common errors which can occur when building extra libraries or
when building LAMMPS with packages that require the extra libraries.
If you cannot build the extra library itself successfully, you may need to edit or create
an appropriate Makefile for your machine, e.g. with appropriate compiler or system
settings. Provided makefiles are typically in the lib/name directory. E.g. see the
Makefile.* files in lib/gpu.
The LAMMPS build often uses settings in a lib/name/Makefile.lammps file which
either exists in the LAMMPS distribution or is created or copied from a
lib/name/Makefile.lammps.* file when the library is built. If those settings are not
correct for your machine you will need to edit or create an appropriate
Makefile.lammps file.
Package-specific details for these steps are given in Section 4 an in README files in
the lib/name directories.
Compiler options needed for accelerator packages:
Several packages contain code that is optimized for specific hardware, e.g. CPU, KNL,
or GPU. These are the OPT, GPU, KOKKOS, USER-INTEL, and USER-OMP packages.
Compiling and linking the source files in these accelerator packages for optimal
28

LAMMPS Users Manual
performance requires specific settings in the Makefile.machine file you use.
A summary of the Makefile.machine settings needed for each of these packages is
given in Section 4. More info is given on the doc pages that describe each package in
detail:
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5

USER-INTEL package
GPU package
KOKKOS package
USER-OMP package
OPT package

You can also use or examine the following machine Makefiles in src/MAKE/OPTIONS,
which include the settings. Note that the USER-INTEL and KOKKOS packages can use
settings that build LAMMPS for different hardware. The USER-INTEL package can be
compiled for Intel CPUs and KNLs; the KOKKOS package builds for CPUs (OpenMP),
GPUs (CUDA), and Intel KNLs.
• Makefile.intel_cpu
• Makefile.intel_phi
• Makefile.kokkos_omp
• Makefile.kokkos_cuda_mpi
• Makefile.kokkos_phi
• Makefile.omp
• Makefile.opt
2.4 Building LAMMPS as a library
LAMMPS can be built as either a static or shared library, which can then be called
from another application or a scripting language. See this section for more info on
coupling LAMMPS to other codes. See this section for more info on wrapping and
running LAMMPS from Python.
Static library

To build LAMMPS as a static library (*.a file on Linux), type
make foo mode=lib

where foo is the machine name. This kind of library is typically used to statically link a
driver application to LAMMPS, so that you can insure all dependencies are satisfied at
compile time. This will use the ARCHIVE and ARFLAGS settings in
src/MAKE/Makefile.foo. The build will create the file liblammps_foo.a which another
application can link to. It will also create a soft link liblammps.a, which will point to
the most recently built static library.
Shared library

To build LAMMPS as a shared library (*.so file on Linux), which can be dynamically
loaded, e.g. from Python, type

29

LAMMPS Users Manual
make foo mode=shlib

where foo is the machine name. This kind of library is required when wrapping
LAMMPS with Python; see Section 11 for details. This will use the SHFLAGS and
SHLIBFLAGS settings in src/MAKE/Makefile.foo and perform the build in the
directory Obj_shared_foo. This is so that each file can be compiled with the -fPIC flag
which is required for inclusion in a shared library. The build will create the file
liblammps_foo.so which another application can link to dynamically. It will also create
a soft link liblammps.so, which will point to the most recently built shared library. This
is the file the Python wrapper loads by default.
Note that for a shared library to be usable by a calling program, all the auxiliary
libraries it depends on must also exist as shared libraries. This will be the case for
libraries included with LAMMPS, such as the dummy MPI library in src/STUBS or any
package libraries in lib/packages, since they are always built as shared libraries using
the -fPIC switch. However, if a library like MPI or FFTW does not exist as a shared
library, the shared library build will generate an error. This means you will need to
install a shared library version of the auxiliary library. The build instructions for the
library should tell you how to do this.
Here is an example of such errors when the system FFTW or provided lib/colvars
library have not been built as shared libraries:
/usr/bin/ld: /usr/local/lib/libfftw3.a(mapflags.o): relocation
R_X86_64_32 against '.rodata' can not be used when making a shared
object; recompile with -fPIC
/usr/local/lib/libfftw3.a: could not read symbols: Bad value
/usr/bin/ld: ../../lib/colvars/libcolvars.a(colvarmodule.o):
relocation R_X86_64_32 against '__pthread_key_create' can not be used
when making a shared object; recompile with -fPIC
../../lib/colvars/libcolvars.a: error adding symbols: Bad value

As an example, here is how to build and install the MPICH library, a popular
open-source version of MPI, distributed by Argonne National Labs, 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. The end result should be the file
/usr/local/lib/libmpich.so.
Additional requirement for using a shared library:

The operating system finds shared libraries to load at run-time using the environment
variable LD_LIBRARY_PATH. So you may wish to copy the file src/liblammps.so or
src/liblammps_g++.so (for example) to a place the system can find it by default, such
as /usr/local/lib, or you may wish to add the LAMMPS src directory to
LD_LIBRARY_PATH, so that the current version of the shared library is always
available to programs that use it.
30

LAMMPS Users Manual
For the csh or tcsh shells, you would add something like this to your ~/.cshrc file:
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src
Calling the LAMMPS library

Either flavor of library (static or shared) allows one or more LAMMPS objects to be
instantiated from the calling program.
When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from within the calling
code, as needed.
When used from a C or Fortran program or a scripting language like Python, the
library has a simple function-style interface, provided in src/library.cpp and
src/library.h.
See the sample codes in examples/COUPLE/simple for examples of C++ and C and
Fortran codes that invoke LAMMPS thru its library interface. There are other
examples as well in the COUPLE directory which are discussed in Section 6.10 of the
manual. See Section 11 of the manual for a description of the Python wrapper
provided with LAMMPS that operates through the LAMMPS library interface.
The files src/library.cpp and library.h define the C-style API for using LAMMPS as a
library. See Section 6.19 of the manual for a description of the interface and how to
extend it for your needs.
2.5 Running LAMMPS
By default, LAMMPS runs by reading commands from standard input. Thus if you run
the LAMMPS executable by itself, e.g.
lmp_linux

it will simply wait, expecting commands from the keyboard. Typically you should put
commands in an input script and use I/O redirection, e.g.
lmp_linux Run... , then typing "cmd".
• Move to the directory where you have your input, e.g. a copy of the in.lj input
from the bench folder. (e.g. by typing: cd "Documents").
• At the command prompt, type "lmp_serial -in in.lj", replacing in.lj with the
name of your LAMMPS input script.
The serial executable includes support for multi-threading parallelization from
the styles in the USER-OMP packages.
To run with, e.g. 4 threads, type "lmp_serial -in in.lj -pk omp 4 -sf omp"
For the MPI version, which allows you to run LAMMPS under Windows with the more
general message passing parallel library (LAMMPS has been designed from ground up
to use MPI efficiently), follow these steps:
• Download and install a compatible MPI library binary package: for 32-bit
Windows mpich2-1.4.1p1-win-ia32.msi and 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
subdirectory 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 type something like this:
mpiexec -localonly 4 lmp_mpi -in in.lj

32

LAMMPS Users Manual
or
mpiexec -np 4 lmp_mpi -in in.lj

• replacing in.lj with the name of your LAMMPS input script. For the latter case,
you may be prompted to enter your password.
• 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:
lmp_mpi -in in.lj

And the parallel executable also includes OpenMP multi-threading, which can
be combined with MPI using something like:
mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp

The screen output from LAMMPS is described in a section below. As it runs, LAMMPS
also writes a log.lammps file with the same information.
Note that this sequence of commands copies the LAMMPS executable (lmp_linux) to
the directory with the input files. This may not be necessary, but some versions of MPI
reset the working directory to where the executable is, rather than leave it as the
directory where you launch mpirun from (if you launch lmp_linux on its own and not
under mpirun). If that happens, LAMMPS will look for additional input files and write
its output files to the executable directory, rather than your working directory, which
is probably not what you want.
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 Section
12 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 a 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 can cause slight differences and
eventual divergence of molecular dynamics phase space trajectories.
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 setup a
smaller problem.
2.6 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
33

LAMMPS Users Manual
• -h or -help
• -i or -in
• -k or -kokkos
• -l or -log
• -nc or -nocite
• -pk or -package
• -p or -partition
• -pl or -plog
• -ps or -pscreen
• -r or -restart
• -ro or -reorder
• -sc or -screen
• -sf or -suffix
• -v or -var
For example, lmp_ibm might be launched as follows:
mpirun -np 16 lmp_ibm -v f tmp.out -l my.log -sc none -in in.alloy
mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none -in in.alloy

Here are the details on the options:
-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 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. I/O
redirection should also work in parallel, but if it does not (in the unlikely case that an
MPI implementation does not support it), then use the -in flag. Note that this is a
required switch when running LAMMPS in multi-partition mode, since multiple
processors cannot all read from stdin.
-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 above in Section 2.3, this
switch must be set to enable running with the KOKKOS-enabled styles the package
34

LAMMPS Users Manual
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
USER-OMP 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 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. Example of when to use these options
and what settings to use on different platforms is given in Section 5.3.
• 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
3 environment variables
SLURM_LOCALID (various MPI variants compiled with SLURM support)
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

35

LAMMPS Users Manual
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

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 hi-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 hi-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.
-nocite

Disable writing the log.cite file which is normally written to list references for specific
cite-able features used during a LAMMPS run. See the citation page for more details.
-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 USER-INTEL and USER-OMP packages which can be
used together.
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 processors are split into separate
36

LAMMPS Users Manual
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 e useful for running multi-replica simulations,
where each replica runs on 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 Section 6.4 of the manual. 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.
-restart 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 ...

Note that the specified restartfile and datafile can have wild-card characters ("*",%")
as described by the read_restart and write_data commands. But a filename such as
file.* will need to be enclosed in quotes to avoid shell expansion of the "*" character.
Note that following restartfile, the optional flag remap can be used. This has the same
effect as adding it to the read_restart command, as explained on its doc page. This is
only useful if the reading of 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.
37

LAMMPS Users Manual
Also note that following datafile, the same optional keyword/value pairs can be listed
as used by the write_data command.
-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 2nd partition) is matched up with a specific set of processors in the 1st partition.
See the Section 5 doc pages 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 2nd set in the 2nd partition. The -reorder
command-line switch can alter this so that the 1st N procs in the 1st partition and one
proc in the 2nd 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
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
38

LAMMPS Users Manual
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 out command for how to output info on the final assignment of physical
processors to the LAMMPS simulation domain.
-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, hi-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 hi-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.
-suffix style args

Use variants of various styles if they exist. The specified style can be cuda, gpu, intel,
kk, omp, opt, or hybrid. These refer to optional packages that LAMMPS can be built
with, as described above in Section 2.3. The "gpu" style corresponds to the GPU
package, the "intel" style to the USER-INTEL package, the "kk" style to the KOKKOS
package, the "opt" style to the OPT package, and the "omp" style to the USER-OMP
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 USER-INTEL package if they are installed and available, but styles for
the USER-OMP 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.
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, pair, 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.

39

LAMMPS Users Manual
For the USER-INTEL package, using this command-line switch also invokes the
default USER-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 USER-OMP
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
USER-INTEL package. It will also invoke the default USER-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.
For the KOKKOS package, using this command-line switch also invokes the default
KOKKOS settings, as if the command "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 this section 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 they
start with a "-", e.g. a negative numeric value. It is OK if the first value1 starts with a
"-", since it is automatically skipped.
2.7 LAMMPS screen 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 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,
40

LAMMPS Users Manual
LAMMPS prints the final thermodynamic state and a total run time for the simulation.
It then 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:
Histogram:
Nghost:
Histogram:
Neighs:
Histogram:

501 ave 508 max 490 min
1 0 0 0 0 0 1 1 0 1
6586.25 ave 6628 max 6548 min
1 0 1 0 0 0 1 0 0 1
177007 ave 180562 max 170212 min
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
time for the section. The Performance line is provided for convenience to help
predicting the number of loop continuations required and for comparing performance
with other, similar MD codes. 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 no
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 stands for all non-bonded force computation
• Bond stands for bonded interactions: bonds, angles, dihedrals, impropers
• Kspace stands for reciprocal space interactions: Ewald, PPPM, MSM
• Neigh stands for neighbor list construction
• Comm stands for communicating atoms and their properties
• Output stands for writing dumps and thermo output
• Modify stands for fixes and computes called by them
• Other is the remaining time

41

LAMMPS Users Manual
For each category, there is a breakdown of the least, average and most amount of wall
time a processor spent on this section. Also you have the variation from the average
time. Together these numbers allow to gauge the amount of load imbalance in this
segment of the calculation. Ideally the difference between minimum, maximum and
average is small and thus the variation from the average close to zero. The final
column shows the percentage of the total loop time is spent in this section.
When using the timer full setting, an additional column is present 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 entry is the Reduce
section, which lists the time spent in reducing the per-thread data elements to the
storage for non-threaded computation. These thread timings are taking from the first
MPI rank only and and thus, as 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 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 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 during the run is given as well as 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 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.
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

42

LAMMPS Users Manual
The first line prints the criterion that determined the minimization to be completed.
The third 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 force vector; the inf-norm is the largest
component. Then some information 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.
If a kspace_style long-range Coulombics solve was performed 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 gives the time spent doing 3d FFTs (4 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.
2.8 Tips for users of previous LAMMPS versions
The current C++ began with a complete rewrite of LAMMPS 2001, which was written
in F90. Features of earlier versions of LAMMPS are listed in Section 13. The F90 and
F77 versions (2001 and 99) are also freely distributed as open-source codes; check the
LAMMPS WWW Site for distribution information if you prefer those versions. The 99
and 2001 versions are no longer under active development; they do not have all the
features of C++ LAMMPS.
If you are a previous user of LAMMPS 2001, these are the most significant changes
you will notice in C++ LAMMPS:
(1) The names and arguments of many input script commands have changed. All
commands are now a single word (e.g. read_data instead of read data).
(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS, but you may
need to specify the relevant commands in different ways.
(3) The format of the data file can be streamlined for some problems. See the
read_data command for details. The data file section "Nonbond Coeff" has been
renamed to "Pair Coeff" in C++ LAMMPS.
(4) Binary restart files written by LAMMPS 2001 cannot be read by C++ LAMMPS
with a read_restart command. This is because they were output by F90 which writes
in a different binary format than C or C++ writes or reads. Use the restart2data tool
provided with LAMMPS 2001 to convert the 2001 restart file to a text data file. Then
edit the data file as necessary before using the C++ LAMMPS read_data command to
43

LAMMPS Users Manual
read it in.
(5) There are numerous small numerical changes in C++ LAMMPS that mean you will
not get identical answers when comparing to a 2001 run. However, your initial
thermodynamic energy and MD trajectory should be close if you have setup the
problem for both codes the same.

44

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

3. Commands
This section describes how a LAMMPS input script is formatted and the input script
commands used to define a LAMMPS simulation.
3.1
3.2
3.3
3.4
3.5

LAMMPS input script
Parsing rules
Input script structure
Commands listed by category
Commands listed alphabetically

3.1 LAMMPS input script
LAMMPS executes by reading commands from a input script (text file), one line at a
time. When the input script ends, LAMMPS exits. Each command causes LAMMPS to
take some action. It may set an internal variable, read in a file, or run a simulation.
Most commands have default settings, which means you only need to use the
command if you wish to change the default.
In many cases, the ordering of commands in an input script is not important. However
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

In the first case, the specified timestep (0.5 fmsec) is used for two simulations of 100
timesteps each. In the 2nd case, the default timestep (1.0 fmsec) is used for the 1st
100 step simulation and a 0.5 fmsec timestep is used for the 2nd 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
45

LAMMPS Users Manual
effect. For example, the read_data command initializes 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. This section gives more information on what errors mean. The
documentation for each command lists restrictions on how the command can be used.

3.2 Parsing rules
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 is 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. See an exception 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.
(3) The line is searched repeatedly for $ characters, which indicate variables that are
replaced with a text string. See an exception in (6).
If the $ is followed by 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 variable
names "myTemp" and "x".
How the variable is converted to a text string depends on what style of variable it is;
see the variable doc 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.
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

46

LAMMPS Users Manual
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.
Note that neither the curly-bracket or immediate form of variables can contain nested
$ characters for other variables to substitute for. Thus you cannot do this:
variable
variable
print

a equal 2
b2 equal 4
"B2 = ${b$a}"

Nor can you specify this $($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 whitespace (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
"""

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

47

LAMMPS Users Manual
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.
3.3 Input script structure
This section describes the structure of a typical LAMMPS input script. The "examples"
directory in the LAMMPS distribution contains many sample input scripts; the
corresponding problems are discussed in Section 7, and animated on the LAMMPS
WWW Site.
A LAMMPS input script typically has 4 parts:
1.
2.
3.
4.

Initialization
Atom definition
Settings
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 the commands need only be used if a
non-default value is desired.
(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.
(2) Atom definition
There are 3 ways to define atoms in LAMMPS. Read them in from a data or restart file
via the read_data or read_restart commands. These files can contain molecular
topology information. Or create atoms on a lattice (with no molecular topology), using
these commands: lattice, region, create_box, create_atoms. The entire set of atoms
can be duplicated to make a larger simulation using the replicate command.
(3) Settings
Once atoms and molecular topology are defined, a variety of settings can be specified:
force field coefficients, simulation parameters, output options, etc.

48

LAMMPS Users Manual
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.
(4) Run a simulation
A molecular dynamics simulation is run using the run command. Energy minimization
(molecular statics) is performed using the minimize command. A parallel tempering
(replica-exchange) simulation can be run using the temper command.

3.4 Commands listed by category
This section lists core LAMMPS commands, grouped by category. The next section
lists all commands alphabetically. The next section also includes (long) lists of style
options for entries that appear in the following categories as a single command (fix,
compute, pair, etc). Commands that are added by user packages are not included in
the categories here, but they are in the next section.
Initialization:
newton, package, processors, suffix, units
Setup simulation box:
boundary, box, change_box, create_box, dimension, lattice, region
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
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
Settings:
49

LAMMPS Users Manual
comm_modify, comm_style, info, min_modify, min_style, neigh_modify, neighbor,
partition, reset_timestep, run_style, timer, timestep
Operations within timestepping (fixes) and diagnostics (computes):
compute, compute_modify, fix, fix_modify, uncompute, unfix
Output:
dump image, dump movie, dump, dump_modify, restart, thermo, thermo_modify,
thermo_style, undump, write_coeff, write_data, write_dump, write_restart
Actions:
minimize, neb, prd, rerun, run, tad, temper
Input script control:
clear, echo, if, include, jump, label, log, next, print, python, quit, shell, variable
3.5 Individual commands
This section lists all LAMMPS commands alphabetically, with a separate listing below
of styles within certain commands. The previous section lists the same commands,
grouped by category. Note that some style options for some commands are part of
specific LAMMPS packages, which means they cannot be used unless the package was
included when LAMMPS was built. Not all packages are included in a default
LAMMPS build. These dependencies are listed as Restrictions in the command's
documentation.
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 image
dump_modify dump movie
echo
fix
fix_modify
group
if
info
improper_coeff improper_style
include
jump
kspace_modify kspace_style
label
lattice
log
mass
minimize
min_modify
min_style
molecule
neb
neigh_modify
neighbor
newton
next
package
pair_coeff
pair_modify
pair_style
pair_write
partition
prd
print
processors
python
quit
read_data
read_dump
read_restart
region
replicate
rerun
reset_timestep
restart
run
run_style
set
shell
special_bonds
suffix
tad
temper
thermo
thermo_modify
thermo_style
timer
timestep
uncompute
undump
unfix
units
variable
velocity
write_coeff
write_data
write_dump
write_restart
50

LAMMPS Users Manual
These are additional commands in USER packages, which can be used if LAMMPS is
built with the appropriate package.
dump netcdf dump netcdf/mpiio dump vtk
group2ndx
ndx2group
temper/grem
temper/npt
Fix styles
See the fix command for one-line descriptions of each style or click on the style itself
for a full description. Some of the styles have accelerated versions, which can be used
if LAMMPS is built with the appropriate accelerated package. This is indicated by
additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
USER-OMP, t = OPT.

o

d

re

addforce
append/atoms atom/swap
ave/histo/weight
ave/time
balance
controller
deform (k)
deposit
evaporate
external
freeze
indent
latte
langevin (k)
neb

nph (ko)

nphug (o)

npt/body

npt/sphere (o)

nve (kio)

nve/noforce
(o)

nve/sphere
(o)
orient/bcc

nve/tri

aveforce
bond/break
drag
gcmc
lineforce
nph/asphere
(o)

ave/atom
bond/create
dt/reset
gld
momentum (k)

ave/chunk
bond/swap
efield
gravity (o)
move

nph/body

nph/sphere (o)

nve/asphere (i) nve/asphere/noforce
nvt (iko)

nvt/asphere (o)

nve/body
nvt/body

oneway
orient/fcc
planeforce
poems
pour
property/atom
python/invoke python/move qeq/comb (o)
qeq/dynamic
qeq/fire
(k)
ed
qeq/slater
rattle
reax/bonds
recenter
restrain
rigid (o)
rigid/small
o)
rigid/nve (o)
rigid/nvt (o)
rigid/small/nph
rigid/small/npt
rigid/small/nve
(o)
k)
shake
spring
spring/chunk
spring/rg
spring/self
srd
e temp/berendsen
temp/csld
temp/csvr
temp/rescale
tfmc
thermal/conductivity
tune/kspace
vector
viscosity
viscous
wall/colloid
wall/gran
nic
wall/lj1043
wall/lj126
wall/lj93 (k)
wall/piston
wall/reflect (k)
wall/region
These are additional fix styles in USER packages, which can be used if LAMMPS is
built with the appropriate package.

apt/fep
drude
able/rx (k)
ipi
d/pc/sphere
vv/edpd

addtorque
atc
ave/correlate/long
colvars
drude/transform/direct drude/transform/reverse
edpd/source
eos/cv
filter/corotate
flow/gauss
gle
grem
langevin/drude
langevin/eff
lb/fluid
lb/momentum
lb/viscous
meso
manifoldforce
meso/stationary
mvv/tdpd
nve/dot
nve/dotc/langevin nve/manifold/rattle
51

LAMMPS Users Manual

nifold/rattle
pt/uef
mmm
ed/vtk
angulated/surface
m/mod

nph/eff
nvt/uef
qtb
shardlow (k)
smd/setvel
wall/ees

npt/eff
phonon
reax/c/bonds (k)
smd
smd/wall/surface
wall/region/ees

nve/eff
nvt/eff
pimd
qbmsst
reax/c/species (k)
rhok
smd/adjust/dt
smd/integrate/tlsph s
tdpd/source
temp/rescale/eff

Compute styles
See the compute command for one-line descriptions of each style or click on the style
itself for a full description. Some of the styles have accelerated versions, which can be
used if LAMMPS is built with the appropriate accelerated package. This is indicated
by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
USER-OMP, t = OPT.

aggregate/atom
angle
angle/local angmom/chunk
body/local
bond
bond/local
centro/atom
chunk/atom
cluster/atom
cna/atom
com
com/chunk
contact/atom
coord/atom
damage/atom
dihedral
dihedral/local
dilatation/atom
dipole/chunk
displace/atom erotate/asphere erotate/rigid erotate/sphere
erotate/sphere/atom event/displace fragment/atom global/atom
group/group
gyration
gyration/chunk
heat/flux
hexorder/atom
improper
improper/local inertia/chunk
ke
ke/atom
ke/rigid
msd
msd/chunk
msd/nongauss
omega/chunk
orientorder/atom
pair
pair/local
pe
pe/atom
plasticity/atom
pressure
property/atom property/local property/chunk
rdf
reduce
reduce/region
rigid/local
slice
sna/atom
snad/atom
snav/atom
stress/atom
temp (k)
temp/asphere
temp/body
temp/chunk
temp/com
temp/deform
temp/partial
temp/profile
temp/ramp
temp/region
temp/sphere
ti
torque/chunk
vacf
vcm/chunk
voronoi/atom
These are additional compute styles in USER packages, which can be used if LAMMPS
is built with the appropriate package.

nd/atom
basal/atom
cnp/atom
dpd
dpd/atom
edp
ep
force/tally
heat/flux/tally
ke/eff
ke/atom/eff
m
ho/atom
meso/t/atom
pe/tally
pe/mol/tally
pressure/uef
tact/radius
smd/damage
smd/hourglass/error
smd/internal/energy smd/plastic/strain smd/pl
d/rho
smd/tlsph/defgrad
smd/tlsph/dt
smd/tlsph/num/neighs smd/tlsph/shape
smd
/strain/rate smd/tlsph/stress smd/triangle/mesh/vertices smd/ulsph/num/neighs smd/ulsph/strain smd/u
ph/stress
smd/vol
stress/tally
tdpd/cc/atom
temp/drude
eform/eff
temp/region/eff
temp/rotate
temp/uef
xrd
Pair_style potentials
See the pair_style command for an overview of pair potentials. Click on the style itself
for a full description. Many of the styles have accelerated versions, which can be used
if LAMMPS is built with the appropriate accelerated package. This is indicated by
52

LAMMPS Users Manual
additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
USER-OMP, t = OPT.
none
adp (o)
body
born/coul/dsf/cs
born/coul/wolf (go)
buck (giko)
buck/coul/msm (o)
comb3
coul/long (gko)
coul/wolf (ko)
dsmc

zero
airebo (oi)
bop
born/coul/long (go)
born/coul/wolf/cs
buck/coul/cut (giko)
buck/long/coul/long (o)
coul/cut (gko)
coul/long/cs
coul/wolf/cs
eam (gikot)

hybrid
airebo/morse (oi)
born (go)
born/coul/long/cs
brownian (o)
buck/coul/long (giko)
colloid (go)
coul/debye (gko)
coul/msm
dpd (gio)
eam/alloy (gikot)

eim (o)

gauss (go)

gayberne (gio)

gran/hooke (o)
hbond/dreiding/lj
(o)

gran/hooke/history (o)

gw

hybrid/overlay (k
beck (go)
born/coul/dsf
born/coul/msm (o
brownian/poly (o
buck/coul/long/cs
comb (o)
coul/dsf (gko)
coul/streitz
dpd/tstat (go)
eam/fs (gikot)
gran/hertz/histor
(o)
gw/zbl

hbond/dreiding/morse (o)

kim

lcbop

lj/charmm/coul/charmm/implicit lj/charmm/coul/lon
(ko)
(giko)
lj/charmm/coul/msm lj/charmmfsw/coul/charmmfsh
lj/charmmfsw/coul/long
lj/class2 (gko)
lj/class2/coul/cut
lj/class2/coul/long (gko)
lj/cubic (go)
lj/cut (gikot)
(ko)
lj/cut/coul/long
lj/cut/coul/cut (gko)
lj/cut/coul/debye (gko)
lj/cut/coul/dsf (gko)
(gikot)
lj/cut/dipole/cut
lj/cut/coul/long/cs
lj/cut/coul/msm (go)
lj/cut/coul/wolf (o)
(go)
lj/cut/dipole/long
lj/cut/tip4p/cut (o)
lj/cut/tip4p/long (ot)
lj/expand (gko)
lj/gromacs (gko)
lj/gromacs/coul/gromacs (ko)
lj/long/coul/long (io)
lj/long/dipole/lon
lj/long/tip4p/long
lj/smooth (o)
lj/smooth/linear (o)
lj96/cut (go)
lubricate (o)
lubricate/poly (o)
lubricateU
lubricateU/poly
meam
mie/cut (o)
morse (gkot)
nb3b/harmonic (o
nm/cut (o)
nm/cut/coul/cut (o)
nm/cut/coul/long (o)
peri/eps
peri/lps (o)
peri/pmb (o)
peri/ves
polymorphic
python
reax
rebo (oi)
resquared (go)
snap (k)
soft (go)
sw (giko)
table (gko)
tersoff (giko)
tersoff/mod (gko)
tersoff/mod/c (o)
tersoff/zbl (gko)
tip4p/cut (o)
tip4p/long (o)
tri/lj
ufm (got)
vashishta (ko)
vashishta/table (o)
yukawa (gok)
yukawa/colloid (g
zbl (gok)
These are additional pair styles in USER packages, which can be used if LAMMPS is
built with the appropriate package.
line/lj

lj/charmm/coul/charmm (iko)

53

LAMMPS Users Manual
agni (o)
coul/diel (o)
eam/cd (o)
eff/cut

awpmd/cut
coul/long/soft (o)
edip (o)
exp6/rx (k)

buck/mdf
dpd/fdt
edip/multi
extep

kolmogorov/crespi/z

lennard/mdf

list

lj/cut/coul/cut/soft
(o)

lj/cut/coul/long/soft
lj/cut/dipole/sf (go)
(o)
lj/cut/tip4p/long/soft
lj/cut/thole/long (o)
lj/mdf
(o)
lj/sdk/coul/long (go) lj/sdk/coul/msm (o)
mdpd
meam/c
meam/spline (o)
meam/sw/spline
momb
morse/smooth/linear
morse/soft
multi/lucy/rx (k)
oxdna/coaxstk
oxdna/excv
oxdna/stk
oxdna/xstk
oxdna2/coaxstk
oxdna2/excv
oxdna2/stk
quip
smd/hertz
smd/tlsph
smd/triangulated/surface
smtbq
snap (k)
sph/heatconduction
sph/lj
sph/rhosum
sph/taitwater
srp
table/rx (k)
tdpd
thole
tip4p/long/soft (o)

coul/cut/soft (o)
dpd/fdt/energy (k)
edpd
gauss/cut
lj/charmm/coul/long/soft
(o)
lj/cut/soft (o)
lj/sdk (gko)
mdpd/rhosum
mgpt
multi/lucy
oxdna/hbond
oxdna2/dh
reax/c (ko)
smd/ulsph
sph/idealgas
sph/taitwater/morris
tersoff/table (o)

Bond_style potentials
See the bond_style command for an overview of bond potentials. Click on the style
itself for a full description. Some of the styles have accelerated versions, which can be
used if LAMMPS is built with the appropriate accelerated package. This is indicated
by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
USER-OMP, t = OPT.
none
zero
hybrid
class2 (ko)
fene (iko) fene/expand (o) gromos (o) harmonic (ko)
morse (o) nonlinear (o) quartic (o)
table (o)
These are additional bond styles in USER packages, which can be used if LAMMPS is
built with the appropriate package.
harmonic/shift (o)

harmonic/shift/cut
oxdna/fene oxdna2/fene
(o)

Angle_style potentials
See the angle_style command for an overview of angle potentials. Click on the style
itself for a full description. Some of the styles have accelerated versions, which can be
used if LAMMPS is built with the appropriate accelerated package. This is indicated
by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
USER-OMP, t = OPT.
54

LAMMPS Users Manual
none
zero
hybrid
charmm (ko)
class2 (ko)
cosine (o)
cosine/delta (o) cosine/periodic (o)
cosine/squared (o) harmonic (iko)
table (o)
These are additional angle styles in USER packages, which can be used if LAMMPS is
built with the appropriate package.
cosine/shift (o) cosine/shift/exp (o) dipole (o) fourier (o)
fourier/simple (o)
quartic (o)
sdk
Dihedral_style potentials
See the dihedral_style command for an overview of dihedral potentials. Click on the
style itself for a full description. Some of the styles have accelerated versions, which
can be used if LAMMPS is built with the appropriate accelerated package. This is
indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
none
zero
hybrid
charmm (iko)
charmmfsw
class2 (ko) harmonic (io)
helix (o)
multi/harmonic (o) opls (iko)
These are additional dihedral styles in USER packages, which can be used if LAMMPS
is built with the appropriate package.
cosine/shift/exp (o) fourier (io) nharmonic (o)
spherical (o)

quadratic
(o)

table (o)

Improper_style potentials
See the improper_style command for an overview of improper potentials. Click on the
style itself for a full description. Some of the styles have accelerated versions, which
can be used if LAMMPS is built with the appropriate accelerated package. This is
indicated by additional letters in parenthesis: g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
none
zero
hybrid
class2 (ko)
cvff (io) harmonic (iko) umbrella (o)
These are additional improper styles in USER packages, which can be used if
LAMMPS is built with the appropriate package.
cossq (o) distance fourier (o) ring (o)
Kspace solvers
See the kspace_style command for an overview of Kspace solvers. Click on the style
itself for a full description. Some of the styles have accelerated versions, which can be
used if LAMMPS is built with the appropriate accelerated package. This is indicated
55

LAMMPS Users Manual
by additional letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
USER-OMP, t = OPT.
ewald (o)
ewald/disp
msm (o)
msm/cg (o)
pppm (gok)
pppm/cg (o) pppm/disp (i) pppm/disp/tip4p
pppm/stagger pppm/tip4p (o)

56

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

4. Packages
This section gives an overview of the optional packages that extend LAMMPS
functionality with instructions on how to build LAMMPS with each of them. Packages
are groups of files that enable a specific set of features. For example, force fields for
molecular systems or granular systems 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. Section 2.3 gives general info on
how to install and un-install packages as part of the LAMMPS build process.
There are two kinds of packages in LAMMPS, standard and user packages:
• Table of standard packages
• Table of user packages
Either of these kinds of packages may work as is, may require some additional code
compiled located in the lib folder, or may require an external library to be
downloaded, compiled, installed, and LAMMPS configured to know about its location
and additional compiler flags. You can often do the build of the internal or external
libraries in one step by typing "make lib-name args='...'" from the src dir, with
appropriate arguments included in args='...'. If you just type "make lib-name" you
should see a help message about supported flags and some examples. For more details
about this, please study the tables below and the sections about the individual
packages.
Standard packages are supported by the LAMMPS developers and are written in a
syntax and style consistent with the rest of LAMMPS. This means the developers will
answer questions about them, debug and fix them if necessary, and keep them
compatible with future changes to LAMMPS.
User packages have been contributed by users, and begin with the "user" prefix. If
they are a single command (single file), they are typically in the user-misc package.
User packages don't necessarily meet the requirements of the standard packages. This
means the developers will try to keep things working and usually can answer technical
questions about compiling the package. If you have problems using a feature provided
in a user package, you may need to contact the contributor directly to get help.
Information on how to submit additions you make to LAMMPS as single files or as a
standard or user package are given in this section of the manual.
Following the next two tables is a sub-section for each package. It lists authors (if
applicable) and summarizes the package contents. It has specific instructions on how
to install the package, including (if necessary) downloading or building any extra
library it requires. It also gives links to documentation, example scripts, and
pictures/movies (if available) that illustrate use of the package.
NOTE: To see the complete list of commands a package adds to LAMMPS, just look at
the files in its src directory, e.g. "ls src/GRANULAR". Files with names that start with
57

LAMMPS Users Manual
fix, compute, atom, pair, bond, angle, etc correspond to commands with the same style
names.
In these two tables, 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; USER/atc refers to the examples/USER/atc
directory. The "Library" column indicates whether an extra library is needed to build
and use the package:
• dash = 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

Standard packages
Package
ASPHERE
BODY
CLASS2
COLLOID
COMPRESS
CORESHELL

Description
aspherical particle models
body-style particles
class 2 force fields
colloidal particles
I/O compression
adiabatic core/shell model

Doc page
Example
Library
Section 6.6.14
ellipse
body
body
pair_style lj/class2
atom_style colloid
colloid
dump */gz
sys
Section 6.6.25
coreshell
pair_style
dipole
DIPOLE
point dipole particles
dipole/cut
GPU
GPU-enabled styles
Section 5.3.1
Benchmarks
int
GRANULAR
granular systems
Section 6.6.6
pour
KIM
OpenKIM wrapper
pair_style kim
kim
ext
KOKKOS
Kokkos-enabled styles
Section 5.3.3
Benchmarks
KSPACE
long-range Coulombic solvers
kspace_style
peptide
quantum DFTB forces via
LATTE
fix latte
latte
ext
LATTE
MANYBODY
many-body potentials
pair_style tersoff
shear
MC
Monte Carlo options
fix gcmc
MEAM
modified EAM potential
pair_style meam
meam
int
miscellanous single-file
MISC
commands
MOLECULE molecular system force fields
Section 6.6.3
peptide
MPI parallel I/O dump and
MPIIO
dump
restart
multi-scale coarse-graining
MSCG
fix mscg
mscg
ext
wrapper
OPT
optimized pair styles
Section 5.3.5
Benchmarks
-

58

LAMMPS Users Manual
PERI
POEMS

QEQ
REAX
REPLICA
RIGID
SHOCK
SNAP
SRD

Peridynamics models
coupled rigid body motion
embed Python code in an
input script
QEq charge equilibration
ReaxFF potential (Fortran)
multi-replica methods
rigid bodies and constraints
shock loading methods
quantum-fitted potential
stochastic rotation dynamics

VORONOI

Voronoi tesselation

PYTHON

pair_style peri
fix poems

peri
rigid

int

python

python

sys

fix qeq
pair_style reax
Section 6.6.5
fix rigid
fix msst
pair_style snap
fix srd
compute
voronoi/atom

qeq
reax
tad
rigid
snap
srd

int
-

-

ext

USER packages
Package

Description
Doc page
Example
Library
atom-to-continuum
fix atc
USER/atc
int
USER-ATC
coupling
USER-AWPMD
wave-packet MD
pair_style awpmd/cut
USER/awpmd
int
coarse-grained
src/USER-CGDNA/README
USER/cgdna
USER-CGDNA
DNA force fields
SDK
USER-CGSDK
coarse-graining
pair_style lj/sdk
USER/cgsdk
model
collective variables
fix colvars
USER/colvars
int
USER-COLVARS
library
virtual x-ray and
compute xrd
USER/diffraction
USER-DIFFRACTION
electron diffraction
reactive dissipative
USER-DPD
src/USER-DPD/README
USER/dpd
particle dynamics
USER-DRUDE
Drude oscillators
tutorial
USER/drude
USER-EFF
electron force field
pair_style eff/cut
USER/eff
free energy
USER-FEP
compute fep
USER/fep
perturbation
dump output via
USER-H5MD
dump h5md
ext
HDF5
optimized Intel
USER-INTEL
CPU and KNL
Section 5.3.2
Benchmarks
styles
Lattice Boltzmann
USER-LB
fix lb/fluid
USER/lb
fluid
motion on 2d
USER-MANIFOLD
fix manifoldforce
USER/manifold
surfaces
USER-MEAMC
pair_style meam/c
meam
59

LAMMPS Users Manual

USER-MESO
USER-MGPT
USER-MISC
USER-MOFFF
USER-MOLFILE
USER-NETCDF
USER-OMP
USER-PHONON
USER-QMMM
USER-QTB
USER-QUIP
USER-REAXC
USER-SMD
USER-SMTBQ
USER-SPH
USER-TALLY
USER-UEF
USER-VTK

modified EAM
potential (C++)
mesoscale DPD
pair_style edpd
models
fast MGPT
pair_style mgpt
multi-ion potentials
single-file
USER-MISC/README
contributions
styles for MOF-FF
pair_style buck6d/coul/gauss
force field
VMD molfile
dump molfile
plug-ins
dump output via
dump netcdf
NetCDF
OpenMP-enabled
Section 5.3.4
styles
phonon dynamical
fix phonon
matrix
QM/MM coupling
fix qmmm
quantum nuclear
fix qtb fix qbmsst
effects
QUIP/libatoms
pair_style quip
interface
ReaxFF potential
pair_style reaxc
(C/C++)
smoothed Mach
SMD User Guide
dynamics
second moment
tight binding QEq
pair_style smtbq
potential
smoothed particle
SPH User Guide
hydrodynamics
pairwise tally
compute XXX/tally
computes
extensional flow
fix nvt/uef
dump output via
compute vtk
VTK

USER/meso

-

USER/mgpt

-

USER/misc

-

USER/mofff

-

-

ext

-

ext

Benchmarks

-

USER/phonon

-

USER/qmmm

ext

qtb

-

USER/quip

ext

reax

-

USER/smd

ext

USER/smtbq

-

USER/sph

-

USER/tally

-

USER/uef

-

-

ext

ASPHERE package
Contents:
Computes, time-integration fixes, and pair styles for aspherical particle models
including ellipsoids, 2d lines, and 3d triangles.
60

LAMMPS Users Manual
Install or un-install:
make yes-asphere
make machine
make no-asphere
make machine

Supporting info:
• src/ASPHERE: filenames -> commands
• Section 6.14
• pair_style gayberne
• pair_style resquared
• doc/PDF/pair_gayberne_extra.pdf
• doc/PDF/pair_resquared_extra.pdf
• examples/ASPHERE
• examples/ellipse
• http://lammps.sandia.gov/movies.html#line
• http://lammps.sandia.gov/movies.html#tri

BODY package
Contents:
Body-style particles with internal structure. Computes, time-integration fixes, pair
styles, as well as the body styles themselves. See the body doc page for an overview.
Install or un-install:
make yes-body
make machine
make no-body
make machine

Supporting info:
• src/BODY filenames -> commands
• body
• atom_style body
• fix nve/body
• pair_style body
• examples/body

CLASS2 package
Contents:

61

LAMMPS Users Manual
Bond, angle, dihedral, improper, and pair styles for the COMPASS CLASS2 molecular
force field.
Install or un-install:
make yes-class2
make machine
make no-class2
make machine

Supporting info:
• src/CLASS2: filenames -> commands
• bond_style class2
• angle_style class2
• dihedral_style class2
• improper_style class2
• pair_style lj/class2

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.
Install or un-install:
make yes-colloid
make machine
make no-colloid
make machine

Supporting info:
• src/COLLOID: filenames -> commands
• fix wall/colloid
• pair_style colloid
• pair_style yukawa/colloid
• pair_style brownian
• pair_style lubricate
• pair_style lubricateU
• examples/colloid
• examples/srd

62

LAMMPS Users Manual
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 or un-install:
Note that building with this package assumes you have the zlib compression library
available on your system. The LAMMPS build uses the settings in the
lib/compress/Makefile.lammps file in the compile/link process. You should only need to
edit this file if the LAMMPS build fails on your system.
make yes-compress
make machine
make no-compress
make machine

Supporting info:
• src/COMPRESS: filenames -> commands
• src/COMPRESS/README
• lib/compress/README
• dump atom/gz
• dump cfg/gz
• dump custom/gz
• dump xyz/gz

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 Section 6.26 for an overview of
how to use this package.
Author: Hendrik Heenen (Technical U of Munich).
Install or un-install:
make yes-coreshell
make machine

63

LAMMPS Users Manual
make no-coreshell
make machine

Supporting info:
• src/CORESHELL: filenames -> commands
• Section 6.26
• Section 6.25
• compute temp/cs
• pair_style born/coul/long/cs
• pair_style buck/coul/long/cs
• pair_style lj/cut/coul/long/cs
• examples/coreshell

DIPOLE package
Contents:
An atom style and several pair styles for point dipole models with short-range or
long-range interactions.
Install or un-install:
make yes-dipole
make machine
make no-dipole
make machine

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
• examples/dipole

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. Section 5.3.1 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
64

LAMMPS Users Manual
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.
Install or un-install:
Before building LAMMPS with this package, you must first build the GPU library in
lib/gpu from a set of provided C and CUDA files. You can do this manually if you
prefer; follow the instructions in lib/gpu/README. Please note, that the GPU library
uses MPI calls, so you have to make certain to use the same MPI library (or the
STUBS library) settings as the main LAMMPS code. That same applies to the
-DLAMMPS_BIGBIG, -DLAMMPS_SMALLBIG, or -DLAMMPS_SMALLSMALL define.
You can also do it 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
make
make
make

lib-gpu
#
lib-gpu args="-b"
#
lib-gpu args="-m xk7 -p
lib-gpu args="-m mpi -p

print help message
build GPU library with default Makefile.linux
single -o xk7.single" # create new Makefile.xk7.single, altered f
mixed -b" # build GPU library with mixed precision using settings

Note that this procedure through the '-m machine' flag starts with one of the existing
Makefile.machine files in lib/gpu. For your convenience, 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 that Makefile, via the -h, -a, -p, -e switches, and also save a copy of the new
Makefile, if desired:
• CUDA_HOME = where NVIDIA CUDA software is installed on your system
• CUDA_ARCH = what GPU hardware you have (see help message for details)
• CUDA_PRECISION = precision (double, mixed, single)
• EXTRAMAKE = which Makefile.lammps.* file to copy to Makefile.lammps
If the library build is successful, at least 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 settings in Makefile.lammps for
your machine are not correct, the LAMMPS build will fail, and
lib/gpu/Makefile.lammps may need to be edited.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-gpu
make machine
make no-gpu
make machine

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

LAMMPS Users Manual
Supporting info:
• src/GPU: filenames -> commands
• src/GPU/README
• lib/gpu/README
• Section 5.3
• Section 5.3.1
• Section 2.6 -sf gpu
• Section 2.6 -pk gpu
• package gpu
• Pair Styles section of Section 3.5 for pair styles followed by (g)
• Benchmarks page of web site

GRANULAR package
Contents:
Pair styles and fixes for finite-size granular particles, which interact with each other
and boundaries via frictional and dissipative potentials.
Install or un-install:
make yes-granular
make machine
make no-granular
make machine

Supporting info:
• src/GRANULAR: filenames -> commands
• Section 6.6,
• fix pour
• fix wall/gran
• pair_style gran/hooke
• pair_style gran/hertz/history
• examples/granregion
• examples/pour
• bench/in.chute
• http://lammps.sandia.gov/pictures.html#jamming
• http://lammps.sandia.gov/movies.html#hopper
• http://lammps.sandia.gov/movies.html#dem
• http://lammps.sandia.gov/movies.html#brazil
• http://lammps.sandia.gov/movies.html#granregion

KIM package
Contents:

66

LAMMPS Users Manual
A pair_style kim command which is a wrapper on the Knowledge Base for Interatomic
Models (KIM) repository of interatomic potentials, enabling any of them to be used in
LAMMPS simulations.
To use this package you must have the KIM library available on your system.
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 James
Sethna (Cornell U).
Authors: Ryan Elliott (U Minnesota) is the main developer for the KIM API which the
pair_style kim command uses. He developed the pair style in collaboration with
Valeriu Smirichinski (U Minnesota).
Install or un-install:
Before building LAMMPS with this package, you must first download and build the
KIM library and include the KIM models that you want to use. You can do this
manually if you prefer; follow the instructions in lib/kim/README. You can also do it
in one step from the lammps/src dir, using a command like these, which simply invoke
the lib/kim/Install.py script with the specified args.
make
make
make
make
make
make
make

lib-kim
lib-kim
lib-kim
lib-kim
lib-kim
lib-kim
lib-kim

args="-b
args="-b
args="-b
args="-n
args="-p
args="-p

# print help message
"
# (re-)install KIM API lib with only example models
-a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
-a everything"
# install KIM API lib with all models
-a EAM_Dynamo_Ackland_W__MO_141627196590_002"
# add one model or mo
/usr/local/kim-api" # use an existing KIM API installation at the provide
/usr/local/kim-api -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto

Note that in LAMMPS lingo, a KIM model driver is a pair style (e.g. EAM or Tersoff). A
KIM model is a pair style for a particular element or alloy and set of parameters, e.g.
EAM for Cu with a specific EAM potential file. Also note that installing the KIM API
library with all its models, may take around 30 min to build. Of course you only need
to do that once.
See the list of KIM model drivers here:
https://openkim.org/kim-items/model-drivers/alphabetical
See the list of all KIM models here:
https://openkim.org/kim-items/models/by-model-drivers
See the list of example KIM models included by default here:
https://openkim.org/kim-api in the "What is in the KIM API source package?" section
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-kim
make machine
make no-kim
make machine

67

LAMMPS Users Manual
Supporting info:
• src/KIM: filenames -> commands
• src/KIM/README
• lib/kim/README
• pair_style kim
• examples/kim

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. Section 5.3.3 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, USER-INTEL, and USER-OMP packages, which have styles
optimized for CPUs, KNLs, and GPUs.
You must have a C++11 compatible compiler to use this package.
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 or un-install:
For the KOKKOS package, you have 3 choices when building. You can build with
either CPU or KNL or GPU support. Each choice requires additional settings in your
Makefile.machine for the KOKKOS_DEVICES and KOKKOS_ARCH settings. See the
src/MAKE/OPTIONS/Makefile.kokkos* files for examples.
For multicore CPUs using OpenMP:
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = HSW

# HSW = Haswell, SNB = SandyBridge, BDW = Broadwell, etc

For Intel KNLs using OpenMP:
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNL

For NVIDIA GPUs using CUDA:
KOKKOS_DEVICES = Cuda
KOKKOS_ARCH = Pascal60,Power8
KOKKOS_ARCH = Kepler37,Power8

# P100 hosted by an IBM Power8, etc
# K80 hosted by an IBM Power8, etc

68

LAMMPS Users Manual
For GPUs, you also need these 2 lines in your Makefile.machine before the CC line is
defined, in this case for use with OpenMPI mpicxx. The 2 lines define a nvcc wrapper
compiler, which will use nvcc for compiling CUDA files or use a C++ compiler for
non-Kokkos, non-CUDA files.
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
CC =
mpicxx

Once you have an appropriate Makefile.machine, you can install/un-install the package
and build LAMMPS in the usual manner. Note that you cannot build one executable to
run on multiple hardware targets (CPU or KNL or GPU). You need to build LAMMPS
once for each hardware target, to produce a separate executable. Also note that we do
not recommend building with other acceleration packages installed (GPU, OPT,
USER-INTEL, USER-OMP) when also building with KOKKOS.
make yes-kokkos
make machine
make no-kokkos
make machine

Supporting info:
• src/KOKKOS: filenames -> commands
• src/KOKKOS/README
• lib/kokkos/README
• Section 5.3
• Section 5.3.3
• Section 2.6 -k on ...
• Section 2.6 -sf kk
• Section 2.6 -pk kokkos
• package kokkos
• Styles sections of Section 3.5 for styles followed by (k)
• Benchmarks page of web site

KSPACE package
Contents:
A variety of long-range Coulombic solvers, as well as pair styles which compute the
corresponding short-range pairwise Coulombic interactions. These include Ewald,
particle-particle particle-mesh (PPPM), and multilevel summation method (MSM)
solvers.
Install or un-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,
3rd party libraries like FFTW, or a vendor-supplied FFT library. See step 6 of Section
2.2.2 of the manual for details on how to select different FFT options in your machine
69

LAMMPS Users Manual
Makefile.
make yes-kspace
make machine
make no-kspace
make machine

Supporting info:
• src/KSPACE: filenames -> commands
• kspace_style
• doc/PDF/kspace.pdf
• Section 6.7
• Section 6.8
• Section 6.9
• pair_style coul
• Pair Styles section of Section 3.5 with "long" or "msm" in pair style name
• examples/peptide
• bench/in.rhodo

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 web site:
https://github.com/lanl/LATTE. A brief technical description 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 or un-install:
Before building LAMMPS with this package, you must first download and build the
LATTE library. You can do this 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
make
make
make

lib-latte
lib-latte args="-b"
lib-latte args="-p $HOME/latte"
lib-latte args="-b -m gfortran"

#
#
#
#
#

print help message
download and build in lib/latte/LATTE-master
use existing LATTE installation in $HOME/latte
download and build in lib/latte and
copy Makefile.lammps.gfortran to Makefile.lammps

70

LAMMPS Users Manual
Note that 3 symbolic (soft) links, "includelink" and "liblink" and "filelink.o", are
created in lib/latte to point into the LATTE home dir. When LAMMPS builds in src 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.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-latte
make machine
make no-latte
make machine

Supporting info:
• src/LATTE: filenames -> commands
• src/LATTE/README
• lib/latte/README
• fix latte
• examples/latte
• LAMMPS-LATTE tutorial

MANYBODY package
Contents:
A variety of manybody and bond-order potentials. These include (AI)REBO, BOP, EAM,
EIM, Stillinger-Weber, and Tersoff potentials.
Install or un-install:
make yes-manybody
make machine
make no-manybody
make machine

Supporting info:
• src/MANYBODY: filenames -> commands
• Pair Styles section of Section 3.5
• examples/comb
• examples/eim
• examples/nb3d
• examples/shear
• examples/streitz
• examples/vashishta
• bench/in.eam

71

LAMMPS Users Manual
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) in conjuction with dynamics.
Install or un-install:
make yes-mc
make machine
make no-mc
make machine

Supporting info:
• src/MC: filenames -> commands
• fix atom/swap
• fix bond/break
• fix bond/create
• fix bond/swap
• fix gcmc
• pair_style dsmc
• http://lammps.sandia.gov/movies.html#gcmc

MEAM package
Contents:
A pair style for the modified embedded atom (MEAM) potential.
Please note that the MEAM package has been superseded by the USER-MEAMC
package, which is a direct translation of the MEAM package to C++. USER-MEAMC
contains additional optimizations making it run faster than MEAM on most machines,
while providing the identical features and USER interface.
Author: Greg Wagner (Northwestern U) while at Sandia.
Install or un-install:
Before building LAMMPS with this package, you must first build the MEAM library in
lib/meam. You can do this manually if you prefer; follow the instructions in
lib/meam/README. You can also do it in one step from the lammps/src dir, using a
command like these, which simply invoke the lib/meam/Install.py script with the
specified args:

make lib-meam
# print help message
make lib-meam args="-m mpi"
# build with default Fortran compiler compatible with your MPI l
make lib-meam args="-m serial" # build with compiler compatible with "make serial" (GNU Fortran

72

LAMMPS Users Manual
make lib-meam args="-m ifort"

# build with Intel Fortran compiler using Makefile.ifort

The build should produce two files: lib/meam/libmeam.a and
lib/meam/Makefile.lammps. The latter is copied from an existing Makefile.lammps.*
and has settings needed to link C++ (LAMMPS) with Fortran (MEAM library).
Typically the two compilers used for LAMMPS and the MEAM library need to be
consistent (e.g. both Intel or both GNU compilers). If necessary, you can edit/create a
new lib/meam/Makefile.machine file for your system, which should define an
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine file.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-meam
make machine
make no-meam
make machine

NOTE: You should test building the MEAM library with both the Intel and GNU
compilers to see if a simulation runs faster with one versus the other on your system.
Supporting info:
• src/MEAM: filenames -> commands
• src/meam/README
• lib/meam/README
• pair_style meam
• examples/meam

MISC package
Contents:
A variety of compute, fix, pair, dump 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.
Install or un-install:
make yes-misc
make machine
make no-misc
make machine

Supporting info:
• src/MISC: filenames -> commands
73

LAMMPS Users Manual
• compute ti
• fix evaporate
• fix orient/fcc
• fix ttm
• fix thermal/conductivity
• fix viscosity
• examples/KAPPA
• examples/VISCOSITY
• http://lammps.sandia.gov/pictures.html#ttm
• http://lammps.sandia.gov/movies.html#evaporation

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.
Install or un-install:
make yes-molecule
make machine
make no-molecule
make machine

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
• Section 6.3
• examples/cmap
• examples/dreiding
• examples/micelle,
• examples/peptide
• bench/in.chain
• bench/in.rhodo

MPIIO package
Contents:

74

LAMMPS Users Manual
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 or un-install:
Note that MPIIO is part of the standard message-passing interface (MPI) library, so
you should not need any additional compiler or link settings, beyond what LAMMPS
normally uses for MPI on your system.
make yes-mpiio
make machine
make no-mpiio
make machine

Supporting info:
• src/MPIIO: filenames -> commands
• dump
• restart
• write_restart
• read_restart

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 or un-install:
Before building LAMMPS with this package, you must first download and build the
MS-CG library. Building the MS-CG library and using it from LAMMPS requires a
C++11 compatible compiler and 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.
Assuming these libraries are in place, you can do the download and build of MS-CG
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

75

LAMMPS Users Manual

# with the settings compatible with "make serial"
# 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/l
make lib-mscg args="-b -m mpi"

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.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-mscg
make machine
make no-mscg
make machine

Supporting info:
• src/MSCG: filenames -> commands
• src/MSCG/README
• lib/mscg/README
• examples/mscg

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. Section 5.3.5 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, USER-INTEL, and USER-OMP
packages, which have styles optimized for CPU performance.
Authors: James Fischer (High Performance Technologies), David Richie, and Vincent
Natoli (Stone Ridge Technolgy).
Install or un-install:
make yes-opt
make machine
make no-opt
make machine

NOTE: The compile flag "-restrict" must be used to build LAMMPS with the OPT
package when using Intel compilers. It should be added to the CCFLAGS line of your
Makefile.machine. See Makefile.opt in src/MAKE/OPTIONS for an example.
• CCFLAGS: add -restrict for Intel compilers
76

LAMMPS Users Manual
Supporting info:
• src/OPT: filenames -> commands
• Section 5.3
• Section 5.3.5
• Section 2.6 -sf opt
• Pair Styles section of Section 3.5 for pair styles followed by (t)
• Benchmarks page of web site

PERI package
Contents:
An atom style, several pair styles which implement different Peridynamics materials
models, and several computes which calculate diagnostics. Peridynamics is a 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).
Install or un-install:
make yes-peri
make machine
make no-peri
make machine

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
• http://lammps.sandia.gov/movies.html#peri

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

LAMMPS Users Manual
Author: Rudra Mukherjee (JPL) while at RPI.
Install or un-install:
Before building LAMMPS with this package, you must first 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
make
make
make

lib-poems
lib-poems args="-m serial"
lib-poems args="-m mpi"
lib-poems args="-m icc"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU g++ compiler (settings as with "make serial")
default MPI C++ compiler (settings as with "make
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.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-poems
make machine
make no-meam
make machine

Supporting info:
• src/POEMS: filenames -> commands
• src/POEMS/README
• lib/poems/README
• fix poems
• examples/rigid

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
Section 11.2 for an overview of using Python from LAMMPS in this manner and the
entire section for other ways to use LAMMPS and Python together.
Install or un-install:
make yes-python
make machine

78

LAMMPS Users Manual
make no-python
make machine

NOTE: Building with the PYTHON package assumes you have a Python shared library
available on your system, which needs to be a Python 2 version, 2.6 or later. Python 3
is not yet supported. See the lib/python/README for more details. Note that the build
uses the lib/python/Makefile.lammps file in the compile/link process. You should only
need to create a new Makefile.lammps.* file (and copy it to Makefile.lammps) if the
LAMMPS build fails.
Supporting info:
• src/PYTHON: filenames -> commands
• Section 11
• lib/python/README
• examples/python

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.
Install or un-install:
make yes-qeq
make machine
make no-qeq
make machine

Supporting info:
• src/QEQ: filenames -> commands
• fix qeq/*
• examples/qeq
• examples/streitz

REAX package
Contents:
A pair style which wraps a Fortran library which implements the ReaxFF potential,
which is a universal reactive force field. See the USER-REAXC package for an
alternate implementation in C/C++. Also a fix reax/bonds command for monitoring
molecules as bonds are created and destroyed.
Author: Aidan Thompson (Sandia).
79

LAMMPS Users Manual
Install or un-install:
Before building LAMMPS with this package, you must first build the REAX library in
lib/reax. You can do this manually if you prefer; follow the instructions in
lib/reax/README. You can also do it in one step from the lammps/src dir, using a
command like these, which simply invoke the lib/reax/Install.py script with the
specified args:
make
make
make
make

lib-reax
lib-reax args="-m serial"
lib-reax args="-m mpi"
lib-reax args="-m ifort"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU Fortran compiler (settings as with "make seri
default MPI Fortran compiler (settings as with "m
Intel ifort compiler

The build should produce two files: lib/reax/libreax.a and lib/reax/Makefile.lammps.
The latter is copied from an existing Makefile.lammps.* and has settings needed to
link C++ (LAMMPS) with Fortran (REAX library). Typically the two compilers used for
LAMMPS and the REAX library need to be consistent (e.g. both Intel or both GNU
compilers). If necessary, you can edit/create a new lib/reax/Makefile.machine file for
your system, which should define an EXTRAMAKE variable to specify a corresponding
Makefile.lammps.machine file.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-reax
make machine
make no-reax
make machine

Supporting info:
• src/REAX: filenames -> commands
• lib/reax/README
• pair_style reax
• fix reax/bonds
• examples/reax

REPLICA package
Contents:
A collection of multi-replica methods which can be used when running multiple
LAMMPS simulations (replicas). See Section 6.5 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), parallel tempering, and a verlet/split algorithm for performing long-range
Coulombics on one set of processors, and the remainder of the force field calcalation
on another set.
Install or un-install:

80

LAMMPS Users Manual
make yes-replica
make machine
make no-replica
make machine

Supporting info:
• src/REPLICA: filenames -> commands
• Section 6.5
• neb
• prd
• tad
• temper,
• run_style verlet/split
• examples/neb
• examples/prd
• examples/tad

RIGID package
Contents:
Fixes which enforce rigid constraints on collections of atoms or particles. This
includes SHAKE and RATTLE, as well as varous rigid-body integrators for a few large
bodies or many small bodies. Also several computes which calculate properties of rigid
bodies.
To install/build:
make yes-rigid
make machine

To un-install/re-build:
make no-rigid
make machine

Supporting info:
• src/RIGID: filenames -> commands
• >compute erotate/rigid
• fix shake
• fix rattle
• fix rigid/*
• examples/ASPHERE
• examples/rigid
• bench/in.rhodo
• http://lammps.sandia.gov/movies.html#box
• http://lammps.sandia.gov/movies.html#star

81

LAMMPS Users Manual
SHOCK package
Contents:
Fixes for running impact simulations where a shock-wave passes through a material.
Install or un-install:
make yes-shock
make machine
make no-shock
make machine

Supporting info:
• src/SHOCK: filenames -> commands
• fix append/atoms
• fix msst
• fix nphug
• fix wall/piston
• examples/hugoniostat
• examples/msst

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).
Install or un-install:
make yes-snap
make machine
make no-snap
make machine

Supporting info:
• src/SNAP: filenames -> commands
• pair_style snap
• compute sna/atom
• compute snad/atom
• compute snav/atom
• examples/snap
82

LAMMPS Users Manual

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.
To install/build:
make yes-srd
make machine

To un-install/re-build:
make no-srd
make machine

Supporting info:
• src/SRD: filenames -> commands
• fix srd
• fix wall/srd
• examples/srd
• examples/ASPHERE
• http://lammps.sandia.gov/movies.html#tri
• http://lammps.sandia.gov/movies.html#line
• http://lammps.sandia.gov/movies.html#poly

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 or un-install:
Before building LAMMPS with this package, you must first download and build the
Voro++ library. You can do this 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:
83

LAMMPS Users Manual
make lib-voronoi
make lib-voronoi args="-b"

# print help message
# download and build the default version in lib/voron

Note that 2 symbolic (soft) links, "includelink" and "liblink", are created in lib/voronoi
to point to the Voro++ src dir. When LAMMPS builds in src it will use these links. You
should not need to edit the lib/voronoi/Makefile.lammps file.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-voronoi
make machine
make no-voronoi
make machine

Supporting info:
• src/VORONOI: filenames -> commands
• src/VORONOI/README
• lib/voronoi/README
• compute voronoi/atom
• examples/voronoi

USER-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 or un-install:
Before building LAMMPS with this package, you must first 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
make
make
make

lib-atc
lib-atc args="-m serial"
lib-atc args="-m mpi"
lib-atc args="-m icc"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU g++ compiler and MPI STUBS (settings as with
default MPI compiler (settings as with "make mpi
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
84

LAMMPS Users Manual
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
make
make
make

lib-linalg
lib-linalg args="-m serial"
lib-linalg args="-m mpi"
lib-linalg args="-m gfortran"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU Fortran compiler (settings as with "make s
default MPI Fortran compiler (settings as with
GNU Fortran compiler

You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-user-atc
make machine
make no-user-atc
make machine

Supporting info:
• src/USER-ATC: filenames -> commands
• src/USER-ATC/README
• fix atc
• examples/USER/atc
• http://lammps.sandia.gov/pictures.html#atc

USER-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 or un-install:
Before building LAMMPS with this package, you must first 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
make
make
make

lib-awpmd
lib-awpmd args="-m serial"
lib-awpmd args="-m mpi"
lib-awpmd args="-m icc"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU g++ compiler and MPI STUBS (settings as with
default MPI compiler (settings as with "make mpi"
Intel icc compiler

85

LAMMPS Users Manual
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
make
make
make

lib-linalg
lib-linalg args="-m serial"
lib-linalg args="-m mpi"
lib-linalg args="-m gfortran"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU Fortran compiler (settings as with "make s
default MPI Fortran compiler (settings as with
GNU Fortran compiler

You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-user-awpmd
make machine
make no-user-awpmd
make machine

Supporting info:
• src/USER-AWPMD: filenames -> commands
• src/USER-AWPMD/README
• pair_style awpmd/cut
• examples/USER/awpmd

USER-CGDNA package
Contents:
Several pair styles, a bond style, and integration fixes for coarse-grained models of
single- and double-stranded DNA based on the oxDNA model of Doye, Louis and
Ouldridge at the University of Oxford. This includes Langevin-type rigid-body
integrators with improved stability.
Author: Oliver Henrich (University of Strathclyde, Glasgow).
Install or un-install:
make yes-user-cgdna
make machine
make no-user-cgdna
make machine

Supporting info:
86

LAMMPS Users Manual
• src/USER-CGDNA: filenames -> commands
• /src/USER-CGDNA/README
• pair_style oxdna/*
• pair_style oxdna2/*
• bond_style oxdna/*
• bond_style oxdna2/*
• fix nve/dotc/langevin

USER-CGSDK 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).
Install or un-install:
make yes-user-cgsdk
make machine
make no-user-cgsdk
make machine

Supporting info:
• src/USER-CGSDK: filenames -> commands
• src/USER-CGSDK/README
• pair_style lj/sdk/*
• angle_style sdk
• examples/USER/cgsdk
• http://lammps.sandia.gov/pictures.html#cg

USER-COLVARS package
Contents:
COLVARS stands for collective variables, which can be used to implement various
enhanced sampling methods, including 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, Philadelphia, 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.
87

LAMMPS Users Manual
Install or un-install:
Before building LAMMPS with this package, you must first build the COLVARS library
in lib/colvars. You can do this manually if you prefer; follow the instructions in
lib/colvars/README. You can also do it in one step from the lammps/src dir, using a
command like these, which simply invoke the lib/colvars/Install.py script with the
specified args:
make
make
make
make

lib-colvars
lib-colvars args="-m serial"
lib-colvars args="-m mpi"
lib-colvars args="-m g++-debug"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU g++ compiler (settings as with "make ser
default MPI compiler (settings as with "make
GNU g++ compiler and colvars debugging enabl

The build should produce two files: lib/colvars/libcolvars.a and
lib/colvars/Makefile.lammps. The latter is copied from an existing Makefile.lammps.*
and has settings needed to build LAMMPS with the COLVARS library (though typically
the settings are just blank). If necessary, you can edit/create a new
lib/colvars/Makefile.machine file for your system, which should define an
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine file.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-user-colvars
make machine
make no-user-colvars
make machine

Supporting info:
• src/USER-COLVARS: filenames -> commands
• doc/PDF/colvars-refman-lammps.pdf
• src/USER-COLVARS/README
• lib/colvars/README
• fix colvars
• examples/USER/colvars

USER-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.
Install or un-install:
make yes-user-diffraction
make machine
make no-user-diffraction

88

LAMMPS Users Manual
make machine

Supporting info:
• src/USER-DIFFRACTION: filenames -> commands
• compute saed
• compute xrd
• fix saed/vtk
• examples/USER/diffraction

USER-DPD package
Contents:
DPD stands for dissipative particle dynamics. This package implements coarse-grained
DPD-based models for energetic, 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 and John Brennan
(ARL).
Install or un-install:
make yes-user-dpd
make machine
make no-user-dpd
make machine

Supporting info:
• src/USER-DPD: filenames -> commands
• /src/USER-DPD/README
• compute dpd
• compute dpd/atom
• 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
89

LAMMPS Users Manual
• examples/USER/dpd

USER-DRUDE package
Contents:
Fixes, pair styles, and a compute to simulate thermalized Drude oscillators as a model
of polarization. See Section 6.27 for an overview of how to use the package. There are
auxiliary tools for using this package in tools/drude.
Authors: Alain Dequidt (U Blaise Pascal Clermont-Ferrand), Julien Devemy (CNRS),
and Agilio Padua (U Blaise Pascal).
Install or un-install:
make yes-user-drude
make machine
make no-user-drude
make machine

Supporting info:
• src/USER-DRUDE: filenames -> commands
• Section 6.27
• Section 6.25
• src/USER-DRUDE/README
• fix drude
• fix drude/transform/*
• compute temp/drude
• pair_style thole
• pair_style lj/cut/thole/long
• examples/USER/drude
• tools/drude

USER-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).
Install or un-install:
90

LAMMPS Users Manual
make yes-user-eff
make machine
make no-user-eff
make machine

Supporting info:
• src/USER-EFF: filenames -> commands
• src/USER-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/USER/eff
• tools/eff/README
• tools/eff
• http://lammps.sandia.gov/movies.html#eff

USER-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 (Universite Blaise Pascal Clermont-Ferrand)
Install or un-install:
make yes-user-fep
make machine
make no-user-fep
make machine

Supporting info:
• src/USER-FEP: filenames -> commands
• src/USER-FEP/README
• fix adapt/fep
• compute fep
• pair_style */soft
• examples/USER/fep
• tools/fep/README
91

LAMMPS Users Manual
• tools/fep

USER-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 or un-install:
Note that to follow these steps to compile and link to the CH5MD library, you need the
standard HDF5 software package installed on your system, which should include the
h5cc compiler and the HDF5 library.
Before building LAMMPS with this package, you must first 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
make lib-hm5d args="-m h5cc"

# print help message
# 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.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-user-h5md
make machine
make no-user-h5md
make machine

Supporting info:
• src/USER-H5MD: filenames -> commands
• src/USER-H5MD/README
• lib/h5md/README
• dump h5md
92

LAMMPS Users Manual

USER-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. Section 5.3.2 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 USER-OMP 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
suboptimal.
NOTE: the USER-INTEL package contains styles that require using the -restrict flag,
when compiling with Intel compilers.
Author: Mike Brown (Intel).
Install or un-install:
For the USER-INTEL package, you have 2 choices when building. You can build with
either CPU or KNL support. Each choice requires additional settings in your
Makefile.machine for CCFLAGS and LINKFLAGS and optimized malloc libraries. See
the src/MAKE/OPTIONS/Makefile.intel_cpu and src/MAKE/OPTIONS/Makefile.knl files
for examples.
For CPUs:
OPTFLAGS =
CCFLAGS =
LINKFLAGS =
LIB =

-xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits
-g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $
-g -qopenmp $(OPTFLAGS)
-ltbbmalloc -ltbbmalloc_proxy

For KNLs:
OPTFLAGS =
CCFLAGS =
LINKFLAGS =
LIB =

-xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits
-g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $
-g -qopenmp $(OPTFLAGS)
-ltbbmalloc

Once you have an appropriate Makefile.machine, you can install/un-install the package
and build LAMMPS in the usual manner. Note that you cannot build one executable to
run on multiple hardware targets (Intel CPUs or KNL). You need to build LAMMPS
once for each hardware target, to produce a separate executable.
You should also typically install the USER-OMP package, as it can be used in tandem
with the USER-INTEL package to good effect, as explained in Section 5.3.2.
93

LAMMPS Users Manual
make yes-user-intel yes-user-omp
make machine
make no-user-intel no-user-omp
make machine

Supporting info:
• src/USER-INTEL: filenames -> commands
• src/USER-INTEL/README
• Section 5.3
• Section 5.3.2
• Section 2.6 -sf intel
• Section 2.6 -pk intel
• package intel
• Styles sections of Section 3.5 for styles followed by (i)
• src/USER-INTEL/TEST
• Benchmarks page of web site

USER-LB package
Contents:
Fixes which implement a background Lattice-Boltzmann (LB) fluid, which can be used
to model MD particles influenced by hydrodynamic forces.
Authors: Frances Mackay and Colin Denniston (University of Western Ontario).
Install or un-install:
make yes-user-lb
make machine
make no-user-lb
make machine

Supporting info:
• src/USER-LB: filenames -> commands
• src/USER-LB/README
• fix lb/fluid
• fix lb/momentum
• fix lb/viscous
• examples/USER/lb

USER-MGPT package
Contents:

94

LAMMPS Users Manual
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).
Install or un-install:
make yes-user-mgpt
make machine
make no-user-mgpt
make machine

Supporting info:
• src/USER-MGPT: filenames -> commands
• src/USER-MGPT/README
• pair_style mgpt
• examples/USER/mgpt

USER-MISC package
Contents:
A potpourri of (mostly) unrelated features contributed to LAMMPS by users. Each
feature is a single fix, compute, pair, bond, angle, dihedral, improper, or command
style.
Authors: The author for each style in the package is listed in the
src/USER-MISC/README file.
Install or un-install:
make yes-user-misc
make machine
make no-user-misc
make machine

Supporting info:
• src/USER-MISC: filenames -> commands
• src/USER-MISC/README
• one doc page per individual command listed in src/USER-MISC/README
• examples/USER/misc

95

LAMMPS Users Manual
USER-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: Brandeis University, Waltham, MA, USA)
Install or un-install:
make yes-user-manifold
make machine
make no-user-manifold
make machine

Supporting info:
• src/USER-MANIFOLD: filenames -> commands
• src/USER-MANIFOLD/README
• doc/manifolds
• fix manifoldforce
• fix nve/manifold/rattle
• fix nvt/manifold/rattle
• examples/USER/manifold
• http://lammps.sandia.gov/movies.html#manifold

USER-MEAMC package
Contents:
A pair style for the modified embedded atom (MEAM) potential translated from the
Fortran version in the MEAM package to plain C++. In contrast to the MEAM
package, no library needs to be compiled and the pair style can be instantiated
multiple times.
Author: Sebastian Huetter, (Otto-von-Guericke University Magdeburg) based on the
Fortran version of Greg Wagner (Northwestern U) while at Sandia.
Install or un-install:
make yes-user-meamc
make machine
make no-user-meamc
make machine

96

LAMMPS Users Manual
Supporting info:
• src/USER-MEAMC: filenames -> commands
• src/USER-MEAMC/README
• pair_style meam/c
• examples/meam

USER-MESO package
Contents:
Several extensions of the 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 transport 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)
Install or un-install:
make yes-user-meso
make machine
make no-user-meso
make machine

Supporting info:
• src/USER-MESO: filenames -> commands
• src/USER-MESO/README
• atom_style edpd
• pair_style edpd
• pair_style mdpd
• pair_style tdpd
• fix mvv/dpd
• examples/USER/meso
• http://lammps.sandia.gov/movies.html#mesodpd

USER-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.
97

LAMMPS Users Manual
Author: Hendrik Heenen (Technical U of Munich), Rochus Schmid (Ruhr-University
Bochum).
Install or un-install:
make yes-user-mofff
make machine
make no-user-mofff
make machine

Supporting info:
• src/USER-MOFFF: filenames -> commands
• src/USER-MOFFF/README
• pair_style buck6d/coul/gauss
• angle_style class2
• angle_style cosine/buck6d
• improper_style inversion/harmonic
• examples/USER/mofff

USER-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 recompile 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 or un-install:
Note that the lib/molfile/Makefile.lammps file has a setting for a dynamic loading
library libdl.a that should is typically present on all systems, which 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.
make yes-user-molfile

98

LAMMPS Users Manual
make machine
make no-user-molfile
make machine

Supporting info:
• src/USER-MOLFILE: filenames -> commands
• src/USER-MOLFILE/README
• lib/molfile/README
• dump molfile

USER-NETCDF package
Contents:
Dump styles for writing NetCDF formatted dump files. NetCDF is a portable, binary,
self-describing file format developed 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
• AtomEye (the libAtoms version of AtomEye contains a NetCDF reader not
present in the standard distribution)
Author: Lars Pastewka (Karlsruhe Institute of Technology).
Install or un-install:
Note that to follow these steps, you need the standard NetCDF software package
installed on your system. The lib/netcdf/Makefile.lammps file has settings for NetCDF
include and library files that LAMMPS needs to compile and linkk 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.
make yes-user-netcdf
make machine
make no-user-netcdf
make machine

Supporting info:
• src/USER-NETCDF: filenames -> commands
• src/USER-NETCDF/README
99

LAMMPS Users Manual
• lib/netcdf/README
• dump netcdf

USER-OMP 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. Section 5.3.4 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 USER-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 compilers, 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 USER-OMP 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 optimization. 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 or un-install:
make yes-user-omp
make machine
make no-user-omp
make machine

• CCFLAGS: add -fopenmp (and -restrict when using Intel compilers)
• LINKFLAGS: add -fopenmp
Supporting info:
• src/USER-OMP: filenames -> commands
• src/USER-OMP/README
• Section 5.3
• Section 5.3.4
• Section 2.6 -sf omp
• Section 2.6 -pk omp
• package omp
• Styles sections of Section 3.5 for styles followed by (o)
100

LAMMPS Users Manual
• Benchmarks page of web site

USER-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.
Author: Ling-Ti Kong (Shanghai Jiao Tong University).
Install or un-install:
make yes-user-phonon
make machine
make no-user-phonon
make machine

Supporting info:
• src/USER-PHONON: filenames -> commands
• src/USER-PHONON/README
• fix phonon
• examples/USER/phonon

USER-QMMM package
Contents:
A fix qmmm command which allows LAMMPS to be used in a QM/MM simulation,
currently only in combination with the Quantum ESPRESSO package.
To use this package you must have Quantum ESPRESSO available on your system.
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.
Author: Axel Kohlmeyer (Temple U).
Install or un-install:
Before building LAMMPS with this package, you must first 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:
101

LAMMPS Users Manual
make
make
make
make

lib-qmmm
lib-qmmm args="-m serial"
lib-qmmm args="-m mpi"
lib-qmmm args="-m gfortran"

#
#
#
#

print
build
build
build

help
with
with
with

message
GNU Fortran compiler (settings as in "make seri
default MPI compiler (settings as in "make mpi"
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/un-install the package and build LAMMPS in the usual manner:
make yes-user-qmmm
make machine
make no-user-qmmm
make machine

NOTE: The LAMMPS executable these steps produce is not yet functional for a
QM/MM simulation. You must also build Quantum ESPRESSO and create a new
executable which links LAMMPS and Quantum ESPRESSO together. These are steps 3
and 4 described in the lib/qmmm/README file.
Supporting info:
• src/USER-QMMM: filenames -> commands
• src/USER-QMMM/README
• lib/qmmm/README
• fix phonon
• lib/qmmm/example-ec/README
• lib/qmmm/example-mc/README

USER-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).
Install or un-install:
make yes-user-qtb
make machine

102

LAMMPS Users Manual
make no-user-qtb
make machine

Supporting info:
• src/USER-QTB: filenames -> commands
• src/USER-QTB/README
• fix qtb
• fix qbmsst
• examples/USER/qtb

USER-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 or un-install:
Note that to follow these steps to compile and link to the QUIP library, you must first
download and build QUIP on your systems. It can be obtained from GitHub. See step 1
and step 1.1 in the lib/quip/README file for details on how to do this. Note that it
requires setting two environment variables, QUIP_ROOT and QUIP_ARCH, which will
be 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 this file if the LAMMPS
build can not use its settings to successfully build on your system.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-user-quip
make machine
make no-user-quip
make machine

Supporting info:
• src/USER-QUIP: filenames -> commands
• src/USER-QUIP/README
• pair_style quip
• examples/USER/quip

103

LAMMPS Users Manual
USER-REAXC package
Contents:
A pair style which implements the ReaxFF potential in C/C++ (in contrast to the REAX
package and its Fortran library). ReaxFF is universal reactive force field. See the
src/USER-REAXC/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.
Install or un-install:
make yes-user-reaxc
make machine
make no-user-reaxc
make machine

Supporting info:
• src/USER-REAXC: filenames -> commands
• src/USER-REAXC/README
• pair_style reax/c
• fix reax/c/bonds
• fix reax/c/species
• examples/reax

USER-SMD 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 USER-SPH package).
This package solves solids mechanics problems via a state of the art stabilized
meshless method with hourglass control. 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 or un-install:

104

LAMMPS Users Manual
Before building LAMMPS with this package, you must first download the Eigen
library. Eigen is a template library, so you do not need to build it, just download it.
You can do this 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 and build in default lib/smd/eigen-eigen-...
make lib-smd args="-p /usr/include/eigen3"
# use existing Eigen installation in /usr/include

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.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-user-smd
make machine
make no-user-smd
make machine

Supporting info:
• src/USER-SMD: filenames -> commands
• src/USER-SMD/README
• doc/PDF/SMD_LAMMPS_userguide.pdf
• examples/USER/smd
• http://lammps.sandia.gov/movies.html#smd

USER-SMTBQ package
Contents:
A pair style which implements a Second Moment Tight Binding model with QEq
charge equilibration (SMTBQ) potential for the description of ionocovalent bonds in
oxides.
Authors: Nicolas Salles, Emile Maras, Olivier Politano, and Robert Tetot
(LAAS-CNRS, France).
Install or un-install:
make yes-user-smtbq
make machine
make no-user-smtbq
make machine

Supporting info:

105

LAMMPS Users Manual
• src/USER-SMTBQ: filenames -> commands
• src/USER-SMTBQ/README
• pair_style smtbq
• examples/USER/smtbq

USER-SPH package
Contents:
An atom style, fixes, computes, and several pair styles which implements smoothed
particle hydrodynamics (SPH) for liquids. See the related USER-SMD 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).
Install or un-install:
make yes-user-sph
make machine
make no-user-sph
make machine

Supporting info:
• src/USER-SPH: filenames -> commands
• src/USER-SPH/README
• doc/PDF/SPH_LAMMPS_userguide.pdf
• examples/USER/sph
• http://lammps.sandia.gov/movies.html#sph

USER-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).

106

LAMMPS Users Manual
Install or un-install:
make yes-user-tally
make machine
make no-user-tally
make machine

Supporting info:
• src/USER-TALLY: filenames -> commands
• src/USER-TALLY/README
• compute */tally
• examples/USER/tally

USER-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).
Install or un-install:
make yes-user-uef
make machine
make no-user-uef
make machine

Supporting info:
• src/USER-UEF: filenames -> commands
• src/USER-UEF/README
• fix nvt/uef
• fix npt/uef
• compute pressure/uef
• compute temp/uef
• dump cfg/uef
• examples/uef

USER-VTK package
Contents:
A dump vtk command which outputs snapshot info in the VTK format, enabling
visualization by Paraview or other visualization packages.
107

LAMMPS Users Manual
To use this package you must have VTK library available on your system.
Authors: Richard Berger (JKU) and Daniel Queteschiner (DCS Computing).
Install or un-install:
The lib/vtk/Makefile.lammps file has settings for accessing VTK files and its library,
which are required for LAMMPS to build and link 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.
You can then install/un-install the package and build LAMMPS in the usual manner:
make yes-user-vtk
make machine
make no-user-vtk
make machine

Supporting info:
• src/USER-VTK: filenames -> commands
• src/USER-VTK/README
• lib/vtk/README
• dump vtk

108

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

5. Accelerating LAMMPS 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 coprocessors.
• 5.1 Measuring performance
• 5.2 Algorithms and code options to boost performace
• 5.3 Accelerator packages with optimized styles
• 5.3.1 GPU package
• 5.3.2 USER-INTEL package
• 5.3.3 KOKKOS package
• 5.3.4 USER-OMP package
• 5.3.5 OPT package
• 5.4 Comparison of various accelerator packages
The Benchmark page of the LAMMPS web site gives performance results for the
various accelerator packages discussed in Section 5.2, for several of the standard
LAMMPS benchmark problems, as a function of problem size and number of compute
nodes, on different hardware platforms.

5.1 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. This section of the manual has 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.
109

LAMMPS Users Manual
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 recompile LAMMPS, to obtain synchronized timings.
5.2 General strategies
NOTE: this section 5.2 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
• 2-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
2-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 staggered PPPM gives little
benefit and can be up to 2x slower in the kspace time. For example, the rhodopsin
110

LAMMPS Users Manual
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.

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.
5.3 Packages with optimized styles
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 coprocessors.
All of these commands are in packages provided with LAMMPS. An overview of
packages is give in Section packages.
These are the accelerator packages currently in LAMMPS, either as standard or user
packages:
GPU Package
for NVIDIA GPUs as well as OpenCL support
USER-INTEL Package for Intel CPUs and Intel Xeon Phi
KOKKOS Package
for Nvidia GPUs, Intel Xeon Phi, and OpenMP threading
USER-OMP Package for OpenMP threading and generic CPU optimizations
OPT Package
generic CPU optimizations
Inverting this list, LAMMPS currently has acceleration support for three kinds of
111

LAMMPS Users Manual
hardware, via the listed packages:
Many-core CPUs USER-INTEL, KOKKOS, USER-OMP, OPT packages
NVIDIA GPUs
GPU, KOKKOS packages
Intel Phi
USER-INTEL, KOKKOS packages
Which package is fastest for your hardware may depend on the size problem you are
running and what commands (accelerated 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. Otherwise, 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
• pair_style
• pair_style
• pair_style
• pair_style

lj/cut/gpu
lj/cut/intel
lj/cut/kk
lj/cut/omp
lj/cut/opt

To see what accelerate styles are currently available, see Section 3.5 of the manual.
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
install the accelerator package
add compile/link flags to Makefile.machine in
src/MAKE
re-build LAMMPS
prepare and test a regular LAMMPS simulation

only for GPU package
make yes-opt, make yes-user-intel,
etc
only for USER-INTEL, KOKKOS,
USER-OMP, OPT packages
make machine
lmp_machine -in in.script; mpirun
-np 32 lmp_machine -in in.script

enable specific accelerator support via '-k on'
only needed for KOKKOS package
command-line switch,
set any needed options for the package via "-pk"
only if defaults need to be changed
command-line switch or package command,
use accelerated styles in your input via "-sf"
lmp_machine -in in.script -sf gpu
command-line switch or suffix command
Note that the first 4 steps can be done as a single command with suitable make
command invocations. This is discussed in Section 4 of the manual, and its use is
112

LAMMPS Users Manual
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.
NOTE: With a few exceptions, you can build a single LAMMPS executable with all its
accelerator packages installed. Note however that the USER-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 USER-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 USER-INTEL Phi and KOKKOS Phi options
• the USER-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=

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 dirs.
As mentioned above, the Benchmark page of the LAMMPS web site gives performance
results for the various accelerator 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
NVIDIA 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 USER-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) coprocessors. This can result in additional speedup over 2x
depending on the hardware configuration.

113

LAMMPS Users Manual
• Styles with a "kk" suffix are part of the KOKKOS package, and can be run using
OpenMP on multicore CPUs, on an NVIDIA 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 USER-OMP 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
• restrictions
5.4 Comparison of various accelerator packages
NOTE: this section still needs to be re-worked with additional KOKKOS and
USER-INTEL information.
The next section compares and contrasts the various accelerator options, since there
are multiple ways to perform OpenMP threading, run on GPUs, and run on Intel Xeon
Phi coprocessors.
All 3 of these packages accelerate a LAMMPS calculation using NVIDIA hardware, but
they do it in different ways.
As a consequence, for a particular simulation on specific hardware, one package may
be faster than the other. We give guidelines below, but the best way to determine
which package is faster for your input script is to try both of them on your machine.
See the benchmarking section below for examples where this has been done.
Guidelines for using each package optimally:
• The GPU package allows you to assign multiple CPUs (cores) to a single GPU (a
common configuration for "hybrid" nodes that contain multicore CPU(s) and
GPU(s)) and works effectively in this mode.
• The GPU package moves per-atom data (coordinates, forces) back-and-forth
between the CPU and GPU 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
114

LAMMPS Users Manual
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, if the
number of atoms per GPU is smaller. 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 packages compute bonded interactions (bonds, angles, etc) on the CPU. If
the GPU package 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.
• When using the GPU package with multiple CPUs assigned to one GPU, its
performance depends to some extent on high bandwidth between the CPUs and
the GPU. Hence its performance is affected if full 16 PCIe lanes are not
available for each GPU. In HPC environments this can be the case if S2050/70
servers are used, where two devices generally share one PCIe 2.0 16x slot. Also
many multi-GPU mainboards do not provide full 16 lanes to each of the PCIe 2.0
16x slots.
Differences between the two packages:
• The GPU package accelerates only pair force, neighbor list, and PPPM
calculations.
• The GPU package requires neighbor lists to be built on the CPU when using
exclusion lists, hybrid pair styles, or a triclinic simulation box.

115

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands
Return to Section accelerate overview
5.3.1 GPU package

The GPU package was developed by Mike Brown at ORNL and his collaborators,
particularly Trung Nguyen (ORNL). It provides GPU versions of many pair styles,
including the 3-body Stillinger-Weber pair style, and for 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) moves 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.
• Asynchronous force computations can be performed simultaneously on the
CPU(s) and GPU.
• 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 NVIDIA support as well as
more general OpenCL support, so that the same functionality can eventually be
supported on a variety of GPU hardware.
Here is a quick overview of how to enable and use the GPU package:
• build the library in lib/gpu for your GPU hardware with the desired precision
settings
• install the GPU package and build LAMMPS as usual
• use the mpirun command to set the number of MPI tasks/node which
determines the number of MPI tasks/GPU
• specify the # of GPUs per node
• use GPU styles in your input script
The latter two steps can be done using the "-pk gpu" and "-sf gpu" command-line
switches respectively. Or the effect of the "-pk" or "-sf" switches can be duplicated by
adding the package gpu or suffix gpu commands respectively to your input script.
Required hardware/software:
To use this package, you currently need to have an NVIDIA GPU and install the
NVIDIA CUDA software on your system:
• Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/0/information
116

LAMMPS Users Manual
• 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
Building LAMMPS with the GPU package:
This requires two steps (a,b): build the GPU library, then build LAMMPS with the GPU
package.
You can do both these steps in one line as described in Section 4 of the manual.
Or you can follow these two (a,b) steps:
(a) Build the GPU library
The GPU library is in lammps/lib/gpu. Select a Makefile.machine (in lib/gpu)
appropriate for your system. You should pay special attention to 3 settings in this
makefile.
• CUDA_HOME = needs to be where NVIDIA CUDA software is installed on your
system
• CUDA_ARCH = needs to be appropriate to your GPUs
• CUDA_PREC = precision (double, mixed, single) you desire
See lib/gpu/Makefile.linux.double for examples of the ARCH settings for different GPU
choices, e.g. Fermi vs Kepler. It also lists the possible precision settings:
CUDA_PREC = -D_SINGLE_SINGLE
CUDA_PREC = -D_DOUBLE_DOUBLE
CUDA_PREC = -D_SINGLE_DOUBLE

# single precision for all calculations
# double precision for all calculations
# accumulation of forces, etc, in double

The last setting is the mixed mode referred to above. Note that your GPU must
support double precision to use either the 2nd or 3rd of these settings.
To build the library, type:
make -f Makefile.machine

If successful, it will produce the files libgpu.a and Makefile.lammps.
The latter file has 3 settings that need to be appropriate for the paths and settings for
the CUDA system software on your machine. Makefile.lammps is a copy of the file
specified by the EXTRAMAKE setting in Makefile.machine. You can change
EXTRAMAKE or create your own Makefile.lammps.machine if needed.
Note that to change the precision of the GPU library, you need to re-build the entire
library. Do a "clean" first, e.g. "make -f Makefile.linux clean", followed by the make
command above.
(b) Build LAMMPS with the GPU package
117

LAMMPS Users Manual
cd lammps/src
make yes-gpu
make machine

No additional compile/link flags are needed in Makefile.machine.
Note that if you change the GPU library precision (discussed above) and rebuild the
GPU library, then you also need to re-install the GPU package and re-build LAMMPS,
so that all affected files are re-compiled and linked to the new GPU library.
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.
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.
lmp_machine -sf gpu -pk gpu 1 -in in.script
mpirun -np 12 lmp_machine -sf gpu -pk gpu 2 -in in.script
mpirun -np 48 -ppn 12 lmp_machine -sf gpu -pk gpu 2 -in in.script

# 1 MPI task uses 1 GPU
# 12 MPI tasks share 2 GPUs
# ditto on 4 16-core nodes

Note that if the "-sf gpu" switch is used, it also issues a default package gpu 1
command, which sets the number of GPUs/node to 1.
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 same as the "package gpu" command.
See the package command doc 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.

118

LAMMPS Users Manual
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).
See the Benchmark page of the LAMMPS web site 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.
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 packakge
command doc page for details.
• As described by the package gpu command, GPU accelerated pair styles can
perform computations asynchronously 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.
• 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.

119

LAMMPS Users Manual
• 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.
Restrictions:
None.

120

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands
Return to Section accelerate overview
5.3.2 USER-INTEL package

The USER-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
coprocessors 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 coprocessor 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 coprocessor cores simultaneously.
Currently Available USER-INTEL Styles:
• Angle Styles: charmm, harmonic
• Bond Styles: fene, fourier, harmonic
• Dihedral Styles: charmm, 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
Speed-ups to expect:
The speedups 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 performed using the input files available in the
src/USER-INTEL/TEST directory with the provided run script. These are scalable 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 warmup run (for use
with offload benchmarks).

121

LAMMPS Users Manual

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/USER-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 USER-INTEL package is deterministic. This means
that the results should be reproducible from run to run with the same parallel
configurations and when using determinstic libraries or library settings (MPI,
OpenMP, FFT). However, there are differences in the USER-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 generator
included in the Intel MKL library (that should be more robust than the default
122

LAMMPS Users Manual
Masaglia random number generator)
The precision mode (described below) used with the USER-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.
Quick Start for Experienced Users:
LAMMPS should be built with the USER-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 coprocessors (Offload):
• Edit src/MAKE/OPTIONS/Makefile.intel_coprocessor as necessary
• "-pk intel N omp 1" added to command-line where N is the number of
coprocessors per node.
Required hardware/software:
In order to use offload to coprocessors, an Intel Xeon Phi coprocessor and an Intel
compiler are required. For this, the recommended version of the Intel compiler is
14.0.1.106 or versions 15.0.2.044 and higher.

123

LAMMPS Users Manual
Although any compiler can be used with the USER-INTEL package, currently,
vectorization directives are disabled by default 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.
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 USER-INTEL package, USER-OMP
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 USER-INTEL package:
NOTE: See the src/USER-INTEL/README file for additional flags that might be
needed for best performance on Intel server processors code-named "Skylake".
The USER-INTEL package must be installed into the source directory:
make yes-user-intel

124

LAMMPS Users Manual
Several example Makefiles for building with the Intel compiler are included with
LAMMPS in the src/MAKE/OPTIONS/ directory:
Makefile.intel_cpu_intelmpi
Makefile.knl
Makefile.intel_cpu_mpich
Makefile.intel_cpu_openpmi
Makefile.intel_coprocessor

#
#
#
#
#

Intel
Intel
Intel
Intel
Intel

Compiler,
Compiler,
Compiler,
Compiler,
Compiler,

Intel MPI, No Offload
Intel MPI, No Offload
MPICH, No Offload
OpenMPI, No Offload
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-user-intel
source /opt/intel/parallel_studio_xe_2016.3.067/psxevars.sh
# or psxevars.csh for C-shell
make intel_cpu_intelmpi

Alternatively this can be done as a single command with suitable make command
invocations. This is discussed in Section 4 of the manual.
Note that if you build with support for a Phi coprocessor, the same binary can be used
on nodes with or without coprocessors installed. However, if you do not have
coprocessors on your system, building without offload support will produce a smaller
binary.
The general requirements for Makefiles with the USER-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 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: 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 USER-INTEL package:
Running LAMMPS with the USER-INTEL package is similar to normal use with the
exceptions that one should 1) specify that LAMMPS should use the USER-INTEL
125

LAMMPS Users Manual
package, 2) specify the number of OpenMP threads, and 3) optionally specify the
specific LAMMPS styles that should use the USER-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 coprocessor), 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 memory 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 coprocessor. 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 machine with Intel Hyper-Threading technology
disabled.
Run with the USER-INTEL package from the command line:
To enable USER-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 USER-INTEL package. The default package command will specify
that USER-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 coprocessors are present and the binary was built with offload support, that 1
coprocessor per node will be used with automatic balancing of work between the CPU
and the coprocessor.
You can specify different options for the USER-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 coprocessors/node (ignored without
offload support). Common options to the USER-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
126

LAMMPS Users Manual
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
mpirun -np 72 -ppn 36 lmp_machine -sf intel -in in.script -pk intel 0 omp 2 mode double

Or run with the USER-INTEL package by editing an input script:
As an alternative to adding command-line arguments, the input script can be edited to
enable the USER-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 USER-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
USER-INTEL styles for the commands that follow in the input script.
Tuning for Performance:
NOTE: The USER-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 preprocessor 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 USER-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 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 USER-INTEL package. You can mix the
127

# 2 n
# Don

LAMMPS Users Manual
USER-INTEL package with styles from the OPT package or the USER-OMP 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 USER-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 coprocessors, best performance will
typically be achieved with concurrent calculations performed on both the CPU and the
coprocessor. This is achieved by offloading only a fraction of the neighbor and pair
computations to the coprocessor 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 coprocessor 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
coprocessor. In this plot, the vertical access is time and routines running at the same
time are running concurrently on both the host and the coprocessor.

128

LAMMPS Users Manual

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 coprocessor. A balance of 0.5 runs half of the
calculations on the coprocessor. Setting the balance to -1 (the default) will enable
dynamic load balancing that continously 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 coprocessor. 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
coprocessor. 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
coprocessor. 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 USER-INTEL package has two modes for deciding which atoms will be handled by
the coprocessor. 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
computation on the coprocessor when the newton setting is "on". The default is
dependent on the style being used, however, better performance may be achieved by
129

LAMMPS Users Manual
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 asynchronous offload
tasks.
If pair computations are being offloaded to an Intel Xeon Phi coprocessor, 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 coprocessor
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 coprocessor 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 coprocessor
threads per MPI task.
Restrictions:
When offloading to a coprocessor, 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. Special_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 USER-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., Thakker, 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 Dynamics Simulation Rates with an 8-Fold Increase in
Electrical Power Efficiency. 2016 High Performance Computing, 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 Dynamics Software with Directive-Based Offload.
Computer Physics Communications. 2015. 195: p. 95-101.

130

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands
Return to Section accelerate overview
5.3.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 backend 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 Github.
Kokkos is part of Trilinos. The Kokkos library was written primarily by Carter
Edwards, Christian Trott, and Dan Sunderland (all Sandia).
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
programmers' guide at /lib/kokkos/doc/Kokkos_PG.pdf.
Kokkos currently provides support for 3 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), and CUDA (for NVIDIA GPUs). You choose the mode at build time to
produce an executable compatible with specific hardware.
Building LAMMPS with the KOKKOS package:
NOTE: Kokkos support within LAMMPS must be built with a C++11 compatible
compiler. This means GCC version 4.7.2 or later, Intel 14.0.4 or later, or Clang 3.5.2
or later is required.
The recommended method of building the KOKKOS package is to start with the
provided Kokkos Makefiles in /src/MAKE/OPTIONS/. You may need to modify the
KOKKOS_ARCH variable in the Makefile to match your specific hardware. For
example:
• for
• for
• for
• for

Sandy Bridge CPUs, set KOKKOS_ARCH=SNB
Broadwell CPUs, set KOKKOS_ARCH=BWD
K80 GPUs, set KOKKOS_ARCH=Kepler37
P100 GPUs and Power8 CPUs, set KOKKOS_ARCH=Pascal60,Power8

See the Advanced Kokkos Options section below for a listing of all KOKKOS_ARCH
options.
Compile for CPU-only (MPI only, no threading):

131

LAMMPS Users Manual
use a C++11 compatible compiler and set KOKKOS_ARCH variable in
/src/MAKE/OPTIONS/Makefile.kokkos_mpi_only as described above. Then do the
following:
cd lammps/src
make yes-kokkos
make kokkos_mpi_only

Compile for CPU-only (MPI plus OpenMP threading):
NOTE: To build with Kokkos support for OpenMP threading, your compiler must
support the OpenMP interface. You should have one or more multi-core CPUs so that
multiple threads can be launched by each MPI task running on a CPU.
use a C++11 compatible compiler and set KOKKOS_ARCH variable in
/src/MAKE/OPTIONS/Makefile.kokkos_omp as described above. Then do the following:
cd lammps/src
make yes-kokkos
make kokkos_omp

Compile for Intel KNL Xeon Phi (Intel Compiler, OpenMPI):
use a C++11 compatible compiler and do the following:
cd lammps/src
make yes-kokkos
make kokkos_phi

Compile for CPUs and GPUs (with OpenMPI or MPICH):
NOTE: To build with Kokkos support for NVIDIA GPUs, NVIDIA CUDA software
version 7.5 or later must be installed on your system. See the discussion for the GPU
package for details of how to check and do this.
use a C++11 compatible compiler and set KOKKOS_ARCH variable in
/src/MAKE/OPTIONS/Makefile.kokkos_cuda_mpi for both GPU and CPU as described
above. Then do the following:
cd lammps/src
make yes-kokkos
make kokkos_cuda_mpi

Alternative Methods of Compiling:
Alternatively, the KOKKOS package can be built by specifying Kokkos variables on the
make command line. For example:
make mpi KOKKOS_DEVICES=OpenMP KOKKOS_ARCH=SNB
make kokkos_cuda_mpi KOKKOS_ARCH=Pascal60,Power8

# set the KOKKOS_DEVICES and KOKKOS_ARCH var
# set the KOKKOS_ARCH variable explicitly

Setting the KOKKOS_DEVICES and KOKKOS_ARCH variables on the make command
line requires a GNU-compatible make command. Try "gmake" if your system's
132

LAMMPS Users Manual
standard make complains.
NOTE: If you build using make line variables and re-build LAMMPS twice with
different KOKKOS options and the *same* target, then you *must* perform a "make
clean-all" or "make clean-machine" before each build. This is to force all the
KOKKOS-dependent files to be re-compiled with the new options.
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
mpirun
mpirun
mpirun

-np
-np
-np
-np

16 lmp_kokkos_mpi_only -k on -sf kk -in in.lj
2 -ppn 1 lmp_kokkos_omp -k on t 16 -sf kk -in in.lj
2 lmp_kokkos_omp -k on t 8 -sf kk -in in.lj
32 -ppn 4 lmp_kokkos_omp -k on t 4 -sf kk -in in.lj

#
#
#
#

1
2
1
8

node, 16
nodes, 1
node, 2
nodes, 4

MPI
MPI
MPI
MPI

tasks/node, no
task/node, 16
tasks/node, 8
tasks/node, 4

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 arguments
for hardware settings appropriate to your system. Those arguments are documented
here. 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 hyperthreading is enabled, then the
product of MPI tasks * OpenMP threads/task should not exceed the physical number of
cores * hardware threads. The "-k on" 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: The default for the package kokkos command is to use "full" neighbor lists and
set the Newton flag to "off" for both pairwise and bonded interactions. However, when
running on CPUs, it will typically be faster to use "half" neighbor lists and set the
Newton flag to "on", just as is the case for non-accelerated pair styles. It can also be
faster to use non-threaded communication. Use the "-pk kokkos" command-line switch
133

LAMMPS Users Manual
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.l

If the newton command is used in the input script, it can also override the Newton flag
defaults.
Core 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 better set OMP_PROC_BIND=spread and
OMP_PLACES=threads. For binding threads with the KOKKOS pthreads option,
compile LAMMPS the KOKKOS HWLOC=yes option as described below.
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 hyperthreads,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.

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 thr
mpirun -np 66 lmp_kokkos_phi -k on t 4 -sf kk -in in.lj
# 1 node, 66 MPI tasks/node, 4 thr
mpirun -np 32 lmp_kokkos_phi -k on t 8 -sf kk -in in.lj
# 1 node, 32 MPI tasks/node, 8 thr
mpirun -np 512 -ppn 64 lmp_kokkos_phi -k on t 4 -sf kk -in in.lj # 8 nodes, 64 MPI tasks/node,

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

LAMMPS Users Manual
NOTE: The default for the package kokkos command is to use "full" neighbor lists and
set the Newton flag to "off" for both pairwise and bonded interactions. When running
on KNL, this will typically be best for pair-wise potentials. For manybody potentials,
using "half" neighbor lists and setting the Newton flag to "on" may be faster. It can
also be faster to use non-threaded communication. 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 64 lmp_kokkos_phi -k on t 4 -sf kk -pk kokkos comm no -in in.lj
# Newton off,
mpirun -np 64 lmp_kokkos_phi -k on t 4 -sf kk -pk kokkos newton on neigh half comm no -in in.re

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 coprocessors such as Knight's
Corner (KNC), your system must be configured to use them in "native" mode, not
"offload" mode like the USER-INTEL package supports.
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 # 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 significant
portions of the input script have not been ported to use Kokkos. Using CUDA MPS is
recommended in this scenario. 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
mpirun -np 32 -ppn 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -in in.lj

# 1 node,
2 MPI task
# 16 nodes, 2 MPI task

NOTE: The default for the package kokkos command 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, using "half" neighbor lists and setting the Newton flag to
"on" may be faster. For many pair styles, setting the neighbor binsize equal to the
ghost atom cutoff will give speedup. 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 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos binsize 2.8 -in in.lj
# S
mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2

NOTE: For good performance of the KOKKOS package on GPUs, you must have Kepler
generation GPUs (or later). The Kokkos library exploits texture cache options not
135

LAMMPS Users Manual
supported by Telsa generation GPUs (or older).
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 production runs.
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 arguments 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 (experimental):
With the KOKKOS package, both OpenMP multi-threading and GPUs can be used
together in a few special cases. In the Makefile, 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

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

136

LAMMPS Users Manual
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.
Speed-ups 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 USER-OMP 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 USER-OMP package.
• When running large number of atoms per GPU, KOKKOS is typically faster than
the GPU package.
• When running on Intel hardware, KOKKOS is not as fast as the USER-INTEL
package, which is optimized for that hardware.
See the Benchmark page of the LAMMPS web site for performance of the KOKKOS
package on different hardware.
Advanced Kokkos options:
There are other allowed options when building with the KOKKOS package. As above,
they can be set either as variables on the make command line or in Makefile.machine.
This is the full list of options, including those discussed above. Each takes a value
shown below. The default value is listed, which is set in the
/lib/kokkos/Makefile.kokkos file.
• KOKKOS_DEVICES, values = Serial, OpenMP, Pthreads, Cuda, default =
OpenMP
• KOKKOS_ARCH, values = KNC, SNB, HSW, Kepler30, Kepler32, Kepler35,
Kepler37, Maxwell50, Maxwell52, Maxwell53, Pascal60, Pascal61, ARMv80,
ARMv81, ARMv81, ARMv8-ThunderX, BGQ, Power7, Power8, Power9, KNL,
BDW, SKX, default = none
• KOKKOS_DEBUG, values = yes, no, default = no
137

LAMMPS Users Manual
• KOKKOS_USE_TPLS, values = hwloc, librt, experimental_memkind, default =
none
• KOKKOS_CXX_STANDARD, values = c++11, c++1z, default = c++11
• KOKKOS_OPTIONS, values = aggressive_vectorization, disable_profiling,
default = none
• KOKKOS_CUDA_OPTIONS, values = force_uvm, use_ldg, rdc, enable_lambda,
default = enable_lambda
KOKKOS_DEVICES sets the parallelization method used for Kokkos code (within
LAMMPS). KOKKOS_DEVICES=Serial means that no threading will be used.
KOKKOS_DEVICES=OpenMP means that OpenMP threading will be used.
KOKKOS_DEVICES=Pthreads means that pthreads will be used.
KOKKOS_DEVICES=Cuda means an NVIDIA GPU running CUDA will be used.
KOKKOS_ARCH enables compiler switches needed when compiling for a specific
hardware:
• ARMv80 = ARMv8.0 Compatible CPU
• ARMv81 = ARMv8.1 Compatible CPU
• ARMv8-ThunderX = ARMv8 Cavium ThunderX CPU
• SNB = Intel Sandy/Ivy Bridge CPUs
• HSW = Intel Haswell CPUs
• BDW = Intel Broadwell Xeon E-class CPUs
• SKX = Intel Sky Lake Xeon E-class HPC CPUs (AVX512)
• KNC = Intel Knights Corner Xeon Phi
• KNL = Intel Knights Landing Xeon Phi
• Kepler30 = NVIDIA Kepler generation CC 3.0
• Kepler32 = NVIDIA Kepler generation CC 3.2
• Kepler35 = NVIDIA Kepler generation CC 3.5
• Kepler37 = NVIDIA Kepler generation CC 3.7
• Maxwell50 = NVIDIA Maxwell generation CC 5.0
• Maxwell52 = NVIDIA Maxwell generation CC 5.2
• Maxwell53 = NVIDIA Maxwell generation CC 5.3
• Pascal60 = NVIDIA Pascal generation CC 6.0
• Pascal61 = NVIDIA Pascal generation CC 6.1
• BGQ = IBM Blue Gene/Q CPUs
• Power8 = IBM POWER8 CPUs
• Power9 = IBM POWER9 CPUs
KOKKOS_USE_TPLS=hwloc binds threads to hardware cores, so they do not migrate
during a simulation. KOKKOS_USE_TPLS=hwloc should always be used if running
with KOKKOS_DEVICES=Pthreads for pthreads. It is not necessary for
KOKKOS_DEVICES=OpenMP for OpenMP, because OpenMP provides alternative
methods via environment variables for binding threads to hardware cores. More info
on binding threads to cores is given in Section 5.3.
KOKKOS_USE_TPLS=librt enables use of a more accurate timer mechanism on most
Unix platforms. This library is not available on all platforms.
KOKKOS_DEBUG is only useful when developing a Kokkos-enabled style within
LAMMPS. KOKKOS_DEBUG=yes enables printing of run-time debugging information
138

LAMMPS Users Manual
that can be useful. It also enables runtime bounds checking on Kokkos data
structures.
KOKKOS_CXX_STANDARD and KOKKOS_OPTIONS are typically not changed when
building LAMMPS.
KOKKOS_CUDA_OPTIONS are additional options for CUDA. The LAMMPS KOKKOS
package must be compiled with the enable_lambda option when using GPUs.
Restrictions:
Currently, there are no precision options with the KOKKOS package. All compilation
and computation is performed in double precision.

139

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands
Return to Section 5 overview
5.3.4 USER-OMP package

The USER-OMP package was developed by Axel Kohlmeyer at Temple University. It
provides multi-threaded versions of most pair styles, nearly all bonded styles (bond,
angle, dihedral, improper), several Kspace styles, and a few fix styles. The package
currently uses the OpenMP interface for multi-threading.
Here is a quick overview of how to use the USER-OMP package, assuming one or
more 16-core nodes. More details follow.
use -fopenmp with CCFLAGS and LINKFLAGS in Makefile.machine
make yes-user-omp
make mpi
# build with USER-OMP package, if settings added to
make omp
# or Makefile.omp already has settings
lmp_mpi -sf omp -pk omp 16 = 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.

6.9 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 epsilon of OO = 0.1553
LJ sigma of OO = 3.166
LJ epsilon, sigma of OH, HH = 0.0
r0 of OH bond = 1.0
theta of HOH angle = 109.47
Note that as originally proposed, the SPC model was run with a 9 Angstrom cutoff for
both LJ and Coulommbic terms. It can also be used with long-range Coulombics
(Ewald or PPPM in LAMMPS), without changing any of the parameters above, though
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.

155

LAMMPS Users Manual
6.10 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 3 ways. Each has advantages and
disadvantages, which you'll 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 its 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 the
POEMS package that performs constrained rigid-body motion on groups of atoms is
hooked to LAMMPS. See the fix poems command for more details. See this section of
the documentation 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 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 thru files that the
command writes and reads.
See Section 10 of the documentation for 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.
Examples of driver codes that call LAMMPS as a library are included in the
examples/COUPLE directory of the LAMMPS distribution; see
examples/COUPLE/README for more details:
• simple: simple driver programs in C++ and C which invoke LAMMPS as a
library
• lammps_quest: coupling of LAMMPS and Quest, to run classical MD with
quantum forces calculated by a density functional code
• lammps_spparks: coupling of LAMMPS and SPPARKS, to couple a kinetic Monte
Carlo model for grain growth using MD to calculate strain induced across grain
boundaries
156

LAMMPS Users Manual
This section of the documentation describes how to build LAMMPS as a library. Once
this is done, you can interface with LAMMPS either via C++, C, Fortran, or Python (or
any other language that supports a vanilla C-like interface). For example, from C++
you could create one (or more) "instances" of LAMMPS, pass it an input script to
process, or execute individual commands, all by invoking the correct class methods in
LAMMPS. From C or Fortran you can make function calls to do the same things. See
Section 11 of the manual for a description of the Python wrapper provided with
LAMMPS that operates through the LAMMPS library interface.
The files src/library.cpp and library.h contain the C-style interface to LAMMPS. See
Section 6.19 of the manual for a description of the interface and how to extend it for
your needs.
Note that the lammps_open() function that creates an instance of LAMMPS takes an
MPI communicator as an argument. This means that instance of LAMMPS will run on
the set of processors in the communicator. Thus the calling code can run LAMMPS on
all or a subset of processors. For example, a wrapper script might decide to alternate
between LAMMPS and another code, allowing them both to run on all the processors.
Or it might allocate half the processors to LAMMPS and half to the other code and run
both codes simultaneously before syncing them up periodically. Or it might instantiate
multiple instances of LAMMPS to perform different calculations.

6.11 Visualizing LAMMPS snapshots
LAMMPS itself does not do visualization, but snapshots from LAMMPS simulations
can be visualized (and analyzed) in a variety of ways.
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 Section 9 doc 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 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.

6.12 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,
157

LAMMPS Users Manual
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 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. 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 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:

158

LAMMPS Users Manual

where A = | A | indicates the scalar length of A. The hat symbol (^) indicates the
corresponding unit vector. beta and gamma 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, velocities, 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:

159

LAMMPS Users Manual
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 2nd 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.
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 1st 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 doc
page for further details.
One exception to this rule is if the 1st 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.

160

LAMMPS Users Manual
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 alpha, beta and gamma. 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,alpha,beta,gamma) and the
LAMMPS box sizes (lx,ly,lz) = (xhi-xlo,yhi-ylo,zhi-zlo) and tilt factors (xy,xz,yz) is as
follows:

The inverse relationship can be written as follows:

161

LAMMPS Users Manual

The values of a, b, c , alpha, beta , and gamma can be printed out or accessed by
computes using the thermo_style custom keywords cella, cellb, cellc, cellalpha,
cellbeta, cellgamma, respectively.
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
xlo_bound
ylo_bound
zlo_bound

BOUNDS xy
xhi_bound
yhi_bound
zhi_bound

xz yz
xy
xz
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
xhi_bound
ylo_bound
yhi_bound
zlo_bound
zhi_bound

=
=
=
=
=
=

xlo
xhi
ylo
yhi
zlo
zhi

+
+
+
+

MIN(0.0,xy,xz,xy+xz)
MAX(0.0,xy,xz,xy+xz)
MIN(0.0,yz)
MAX(0.0,yz)

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

162

LAMMPS Users Manual
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.

6.13 NEMD simulations
Non-equilibrium molecular dynamics or NEMD simulations are typically used to
measure a fluid's rheological properties 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.
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.

6.14 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:
163

LAMMPS Users Manual
• 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 directories 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 spheriods 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.

164

LAMMPS Users Manual
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 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
• pair_style
• pair_style
• pair_style
• pair_style
• pair_style
• pair_style
• pair_style
• pair_style
• pair_style
• pair_style

gran/history
gran/hertzian
gran/no_history
dipole/cut
gayberne
resquared
brownian
lubricate
line/lj
tri/lj
body

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

LAMMPS Users Manual
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
• compute
• compute
• compute

temp/sphere
temp/asphere
erotate/sphere
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:
166

LAMMPS Users Manual
• 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.
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 partices 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.

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

167

LAMMPS Users Manual
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 ->
168

LAMMPS Users Manual
scalar). Thus a command that uses scalar values as input can typically also process
elements of a vector or array.
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
169

LAMMPS Users Manual
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 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 thermodynamic 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.

170

LAMMPS Users Manual
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.
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 doc 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 doc 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 commands 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
171

LAMMPS Users Manual
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.
Command
thermo_style
custom
dump custom
dump local
fix print
print

Input

Output

global scalars

screen, log file

per-atom vectors
local vectors
global scalar from variable
global scalar from variable

computes

N/A

fixes

N/A
global scalars and vectors,
per-atom vectors
per-atom/local vectors
global vectors/arrays

dump file
dump file
screen, file
screen
global/per-atom/local
scalar/vector/array
global/per-atom/local
scalar/vector/array
global scalar and vector,
per-atom vector
global scalar/vector
global vector/array

per-atom vectors

per-atom vector/array

local vectors

local vector/array

variables
compute reduce
compute slice
compute
property/atom
compute
property/local
fix vector
fix ave/atom
fix ave/time
fix ave/chunk
fix ave/histo
fix ave/correlate
fix store/state

global scalars
global vector
per-atom vectors
per-atom vector/array
global scalars/vectors
global scalar/vector/array, file
per-atom vectors
global array, file
global/per-atom/local scalars and
global array, file
vectors
global scalars
global array, file
per-atom vectors
per-atom vector/array

6.16 Thermostatting, barostatting, and computing temperature
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.
Temperature is computed as kinetic energy divided by some number of degrees of
freedom (and the Boltzmann constant). Since kinetic energy is a function of particle
172

LAMMPS Users Manual
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,
and the compute pressure command calculates pressure.
• compute
• compute
• compute
• compute
• compute
• compute
• compute
• compute
• compute

temp
temp/sphere
temp/asphere
temp/com
temp/deform
temp/partial
temp/profile
temp/ramp
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 argument, another temperature compute that subtracts a velocity bias.
This allows the translational velocity of spherical or aspherical particles to be adjusted
in prescribed ways.
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
• 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 NEMD simulations section of this 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.
DPD thermostatting alters pairwise interactions in a manner analogous to the
per-particle thermostatting of fix langevin.
173

LAMMPS Users Manual
Any of the thermostatting fixes can use 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.
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
Barostatting in LAMMPS is also performed by fixes. Two barosttating methods are
currently available: Nose-Hoover (npt and nph) and Berendsen:
• fix
• fix
• fix
• fix
• fix

npt
npt/sphere
npt/asphere
nph
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
174

LAMMPS Users Manual
one of the constant NVE fixes or with one of the NVT fixes.
Finally, thermodynamic output, which can be setup via the thermo_style command,
often includes temperature and pressure values. As explained on the doc page for the
thermo_style command, the default T and P are setup by the thermo command itself.
They are NOT the ones associated with any thermostatting or barostatting fix you
have defined or with any compute that calculates a temperature or pressure. Thus if
you want to view these values of T and P, you need to specify them explicitly via a
thermo_style custom command. Or you can use the thermo_modify command to
re-define what temperature or pressure compute is used for default thermodynamic
output.

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

175

LAMMPS Users Manual
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
• fix
• fix
• fix
• fix
• fix
• fix

wall/reflect - reflective flat walls
wall/lj93 - flat walls, with Lennard-Jones 9/3 potential
wall/lj126 - flat walls, with Lennard-Jones 12/6 potential
wall/colloid - flat walls, with pair_style colloid potential
wall/harmonic - flat walls, with repulsive harmonic spring potential
wall/region - use region surface as wall
wall/gran - flat or curved walls with pair_style granular potential

The lj93, lj126, colloid, and harmonic 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 regoin
surfaces to be used as frictional walls, as well as triangulated surfaces.

6.18 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 in this section.
Calculating elastic constants at finite temperature is more challenging, because it is
necessary to run a simulation that perfoms 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
176

LAMMPS Users Manual
fluctuations that occur in an NPT simulation. This method can also be slow to
converge and requires careful post-processing (Shinoda)

6.19 Library interface to LAMMPS
As described in Section 2.5, LAMMPS can be built as a library, so that it can be called
by another code, used in a coupled manner with other codes, or driven through a
Python interface.
All of these methodologies use a C-style interface to LAMMPS that is provided in the
files src/library.cpp and src/library.h. The functions therein have a C-style argument
list, but contain C++ code you could write yourself in a C++ application that was
invoking LAMMPS directly. The C++ code in the functions illustrates how to invoke
internal LAMMPS operations. Note that LAMMPS classes are defined within a
LAMMPS namespace (LAMMPS_NS) if you use them from another C++ application.
Library.cpp contains these functions for creating and destroying an instance of
LAMMPS and sending it commands to execute. See the documentation in the
src/library.cpp file for details:
void lammps_open(int, char **, MPI_Comm, void **)
void lammps_open_no_mpi(int, char **, void **)
void lammps_close(void *)
int lammps_version(void *)
void lammps_file(void *, char *)
char *lammps_command(void *, char *)
void lammps_commands_list(void *, int, char **)
void lammps_commands_string(void *, char *)
void lammps_free(void *)

The lammps_open() function is used to initialize LAMMPS, passing in a list of strings
as if they were command-line arguments when LAMMPS is run in stand-alone mode
from the command line, and a MPI communicator for LAMMPS to run under. It
returns a ptr to the LAMMPS object that is created, and which is used in subsequent
library calls. The lammps_open() function can be called multiple times, to create
multiple instances of LAMMPS.
LAMMPS will run on the set of processors in the communicator. This means the
calling code can run LAMMPS on all or a subset of processors. For example, a
wrapper script might decide to alternate between LAMMPS and another code,
allowing them both to run on all the processors. Or it might allocate half the
processors to LAMMPS and half to the other code and run both codes simultaneously
before syncing them up periodically. Or it might instantiate multiple instances of
LAMMPS to perform different calculations.
The lammps_open_no_mpi() function is similar except that no MPI communicator is
passed from the caller. Instead, MPI_COMM_WORLD is used to instantiate LAMMPS,
and MPI is initialized if necessary.
The lammps_close() function is used to shut down an instance of LAMMPS and free all
its memory.
177

LAMMPS Users Manual
The lammps_version() function can be used to determined the specific version of the
underlying LAMMPS code. This is particularly useful when loading LAMMPS as a
shared library via dlopen(). The code using the library interface can than use this
information to adapt to changes to the LAMMPS command syntax between versions.
The returned LAMMPS version code is an integer (e.g. 2 Sep 2015 results in
20150902) that grows with every new LAMMPS version.
The lammps_file(), lammps_command(), lammps_commands_list(), and
lammps_commands_string() functions are used to pass one or more commands to
LAMMPS to execute, the same as if they were coming from an input script.
Via these functions, the calling code can read or generate a series of LAMMPS
commands one or multiple at a time and pass it thru the library interface to setup a
problem and then run it in stages. The caller can interleave the command function
calls with operations it performs, calls to extract information from or set information
within LAMMPS, or calls to another code's library.
The lammps_file() function passes the filename of an input script. The
lammps_command() function passes a single command as a string. The
lammps_commands_list() function passes multiple commands in a char** list. In both
lammps_command() and lammps_commands_list(), individual commands may or may
not have a trailing newline. The lammps_commands_string() function passes multiple
commands concatenated into one long string, separated by newline characters. In
both lammps_commands_list() and lammps_commands_string(), a single command can
be spread across multiple lines, if the last printable character of all but the last line is
"&", the same as if the lines appeared in an input script.
The lammps_free() function is a clean-up function to free memory that the library
allocated previously via other function calls. See comments in src/library.cpp file for
which other functions need this clean-up.
Library.cpp also contains these functions for extracting information from LAMMPS
and setting value within LAMMPS. Again, see the documentation in the src/library.cpp
file for details, including which quantities can be queried by name:
void *lammps_extract_global(void *, char *)
void lammps_extract_box(void *, double *, double *,
double *, double *, double *, int *, int *)
void *lammps_extract_atom(void *, char *)
void *lammps_extract_compute(void *, char *, int, int)
void *lammps_extract_fix(void *, char *, int, int, int, int)
void *lammps_extract_variable(void *, char *, char *)
void lammps_reset_box(void *, double *, double *, double, double, double)
int lammps_set_variable(void *, char *, char *)
double lammps_get_thermo(void *, char *)
int lammps_get_natoms(void *)
void lammps_gather_atoms(void *, double *)
void lammps_scatter_atoms(void *, double *)
void lammps_create_atoms(void *, int, tagint *, int *, double *, double *,
imageint *, int)

178

LAMMPS Users Manual
The extract functions return a pointer to various global or per-atom quantities stored
in LAMMPS or to values calculated by a compute, fix, or variable. The pointer
returned by the extract_global() function can be used as a permanent reference to a
value which may change. For the extract_atom() method, see the extract() method in
the src/atom.cpp file for a list of valid per-atom properties. New names could easily be
added if the property you want is not listed. For the other extract functions, the
underlying storage may be reallocated as LAMMPS runs, so you need to re-call the
function to assure a current pointer or returned value(s).
The lammps_reset_box() function resets the size and shape of the simulation box, e.g.
as part of restoring a previously extracted and saved state of a simulation.
The lammps_set_variable() function can set an existing string-style variable to a new
string value, so that subsequent LAMMPS commands can access the variable.
The lammps_get_thermo() function returns the current value of a thermo keyword as a
double precision value.
The lammps_get_natoms() function returns the total number of atoms in the system
and can be used by the caller to allocate space for the lammps_gather_atoms() and
lammps_scatter_atoms() functions. The gather function collects peratom info of the
requested type (atom coords, types, forces, etc) from all processors, orders them by
atom ID, and returns a full list to each calling processor. The scatter function does the
inverse. It distributes the same peratom values, passed by the caller, to each atom
owned by individual processors. Both methods are thus a means to extract or assign
(overwrite) any peratom quantities within LAMMPS. See the extract() method in the
src/atom.cpp file for a list of valid per-atom properties. New names could easily be
added if the property you want is not listed. A special treatment is applied for
accessing image flags via the "image" property. Image flags are stored in a packed
format with all three image flags stored in a single integer. When signaling to access
the image flags as 3 individual values per atom instead of 1, the data is transparently
packed or unpacked by the library interface.
The lammps_create_atoms() function takes a list of N atoms as input with atom types
and coords (required), an optionally atom IDs and velocities and image flags. It uses
the coords of each atom to assign it as a new atom to the processor that owns it. 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() or
lammps_extract_atom() functions.
The examples/COUPLE and python directories have example C++ and C and Python
codes which show how a driver code can link to LAMMPS as a library, run LAMMPS
on a subset of processors, grab data from LAMMPS, change it, and put it back into
LAMMPS.
NOTE: You can write code for additional functions as needed to define how your code
talks to LAMMPS and add them to src/library.cpp and src/library.h, as well as to the
Python interface. The added functions can access or change any LAMMPS data you
wish.
179

LAMMPS Users Manual
6.20 Calculating 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 this section of the manual 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.
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 doc
180

LAMMPS Users Manual
page for the compute heat/flux command for an example input script that calculates
the thermal conductivity of solid Ar via the GK formalism.

6.21 Calculating viscosity
The shear viscosity eta of a fluid can be measured in at least 5 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. Also,
see this section of the manual 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.
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 by the compute pressure command, can also be monitored,
which is the J term in the equation above. See this section of the manual for details on
NEMD simulations.
The third method is to perform a reverse non-equilibrium MD simulation using the fix
viscosity command which implements 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
monitored 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.

181

LAMMPS Users Manual
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
variable
variable
variable
variable
variable
variable

real
T equal 86.4956
V equal vol
dt equal 4.0
p equal 400
# correlation length
s equal 5
# sample interval
d equal $p*$s
# dump interval

# convert from LAMMPS real units to SI
variable
variable
variable
variable
variable

kB equal 1.3806504e-23
# [J/K/ Boltzmann
atm2Pa equal 101325.0
A2m equal 1.0e-10
fs2s equal 1.0e-15
convert equal ${atm2Pa}*${atm2Pa}*${fs2s}*${A2m}*${A2m}*${A2m}

# setup problem
dimension
boundary
lattice
region
create_box
create_atoms
mass
pair_style
pair_coeff
timestep
thermo

3
p p p
fcc 5.376 orient x 1 0 0 orient y 0 1 0 orient z 0 0 1
box block 0 4 0 4 0 4
1 box
1 box
1 39.948
lj/cut 13.0
* * 0.2381 3.405
${dt}
$d

# equilibration and thermalization
velocity
fix
run

all create $T 102486 mom yes rot yes dist gaussian
NVT all nvt temp $T $T 10 drag 0.2
8000

# viscosity calculation, switch to NVE if desired
#unfix
#fix

NVT
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

182

LAMMPS Users Manual
variable
print

ndens equal count(all)/vol
"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.

6.22 Calculating a diffusion coefficient
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.

6.23 Using 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, each of the 3 kinds of chunk-related commands is briefly overviewed. Then some
examples are given of how to compute different properties with chunk commands.
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:
183

LAMMPS Users Manual
atoms in same molecule
atoms of same atom type
all atoms with same atom property
(charge, radius, etc)

chunk ID = molecule ID
chunk ID = atom type
chunk ID = output of compute
property/atom
chunk ID = output of compute
atoms in same cluster
cluster/atom command
atoms in same spatial bin
chunk ID = bin ID
chunk ID = molecule ID used to define
atoms in same rigid body
rigid bodies
atoms with similar potential energy
chunk ID = output of compute pe/atom
chunk ID = output of compute
atoms with same local defect structure
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 Section 10
of the documentation for 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.

184

LAMMPS Users Manual
Compute */chunk commands:

Currently the following computes operate on chunks of atoms to produce per-chunk
values.
• compute
• compute
• compute
• compute
• compute
• compute
• compute
• compute

com/chunk
gyration/chunk
inertia/chunk
msd/chunk
property/chunk
temp/chunk
torque/chunk
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, wih one or
more values per chunk. They 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(). E.g.
to find the largest cluster or fastest diffusing molecule.
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

(3) Center of mass of each molecule:
185

LAMMPS Users Manual
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.his

6.24 Setting parameters for the kspace_style pppm/disp command
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 dependent on the
chosen unit settings. For real units, 0.0001 and 0.002 seem to provide reasonable
accurate and efficient 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
186

LAMMPS Users Manual
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 accuracies 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 outut, 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 substantially 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.
187

LAMMPS Users Manual
6.25 Polarizable models
In polarizable force fields the charge distributions in molecules and materials respond
to their electrostatic environments. 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 USER-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 remediate this and other issues. Specifically, the Drude model
includes specific thermostating of the core-Drude pairs and short-range damping of
the induced dipoles.
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
188

LAMMPS Users Manual
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 thermostated
separately as well.

6.26 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.
Technically, shells are attached to the cores by a spring force f = k*r where k is a
parametrized 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
216

atoms
bonds

# core and shell atoms
# number of core/shell springs

4
2

atom types
bond types

# 2 cores and 2 shells for Na and Cl

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
2
3
4

#
#
#
#

20.690784
31.90500
2.298976
3.54500

Na
Cl
Na
Cl

core
core
shell
shell

Atoms
1
1
2
1
3
2
4
2
(...)

2
4
1
3

1.5005
-2.5005
1.5056
-0.5056

0.00000000
0.00000000
4.01599500
4.01599500

0.00000000
0.00000000
4.01599500
4.01599500

0.00000000
0.00000000
4.01599500
4.01599500

#
#
#
#

core of core/shell pair 1
shell of core/shell pair 1
core of core/shell pair 2
shell of core/shell pair 2

189

LAMMPS Users Manual
Bonds

# Bond topology for spring forces

1
2
2
2
(...)

1
3

2
4

# spring for core/shell pair 1
# 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 doc 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
pair_coeff
pair_coeff
pair_coeff
pair_coeff

born/coul/long/cs 20.0 20.0
* *
0.0 1.000
0.00 0.00
0.00
3 3
487.0 0.23768 0.00 1.05
0.50 #Na-Na
3 4 145134.0 0.23768 0.00 6.99
8.70 #Na-Cl
4 4 405774.0 0.23768 0.00 72.40 145.40 #Cl-Cl

bond_style
bond_coeff
bond_coeff

harmonic
1 63.014 0.0
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 behaviour, 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
190

LAMMPS Users Manual
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 (2nd
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 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
fix thermostatequ all nve
fix_modify thermoberendsen temp CSequ
thermo_modify temp CSequ

# thermostat for the true physical syst
# integrator as needed for the berendse

# output of center-of-mass derived temp

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
thermo_modify temp CSequ press thermo_press_lmp
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 for individual particles
# modify thermo to regular pressure

# pressure modification for correct kin

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 noticable over long trajectories. Therefore 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
191

LAMMPS Users Manual
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, 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
fix ave_chunk all ave/time 10 1 10 c_cstherm file chunk.dump mode vector

# note the chosen de

For example if core/shell pairs and other molecules are present:
fix csinfo all property/atom i_CSID
read_data NaCl_CS_x0.1_prop.data fix csinfo NULL CS-Info
compute prop all property/atom i_CSID
(...)

# property/atom command
# atom property added in the data-fil

The additional section in the date file would be formatted like this:
CS-Info

# header of additional section

1
1
2
1
3
2
4
2
5
3
6
3
7
4
8
4
(...)

# column 1 = atom ID, column 2 = core/shell ID

6.27 Drude induced dipoles
The thermalized Drude model, similarly to the core-shell model, represents induced
dipoles by a pair of charges (the core atom and the Drude particle) connected by a
harmonic spring. The Drude model has a number of features aimed at its use in
molecular systems (Lamoureux and Roux):

192

LAMMPS Users Manual
• Thermostating 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.
• 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
available 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 two 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. The former requires use of the command comm_modify vel
yes. The latter 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.

(Berendsen) Berendsen, Grigera, Straatsma, J Phys Chem, 91, 6269-6271 (1987).
(Cornell) Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell,
Kollman, JACS 117, 5179-5197 (1995).

193

LAMMPS Users Manual
(Horn) Horn, Swope, Pitera, Madura, Dick, Hura, and Head-Gordon, J Chem Phys,
120, 9665 (2004).
(Ikeshoji) Ikeshoji and Hafskjold, Molecular Physics, 81, 251-261 (1994).
(Wirnsberger) Wirnsberger, Frenkel, and Dellago, J Chem Phys, 143, 124104 (2015).
(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).
(Jorgensen) Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem Phys, 79, 926
(1983).
(Price) Price and Brooks, J Chem Phys, 121, 10096 (2004).
(Shinoda) Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).
(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).
(Lamoureux and Roux) G. Lamoureux, B. Roux, J. Chem. Phys 119, 3025 (2003)

194

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

7. Example problems
The LAMMPS distribution includes an examples sub-directory with many sample
problems. Many are 2d models that run quickly are 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 web site.
There are two kinds of sub-directories in the examples dir. Lowercase dirs contain one
or a few simple, quick-to-run problems. Uppercase dirs 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.
Lowercase directories
accelerate
airebo
balance
body
cmap
colloid
comb
coreshell
controller
crack

run with various acceleration options (OpenMP, GPU, Phi)
polyethylene with AIREBO potential
dynamic load balancing, 2d system
body particles, 2d system
CMAP 5-body contributions to CHARMM force field
big colloid particles in a small particle solvent, 2d system
models using the COMB potential
core/shell model using CORESHELL package
use of fix controller as a thermostat
crack propagation in a 2d solid
195

LAMMPS Users Manual
deposit
deposit atoms and molecules on a surface
dipole
point dipolar particles, 2d system
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
indent
spherical indenter into a 2d solid
kim
use of potentials in Knowledge Base for Interatomic Models (KIM)
meam
MEAM test for SiC and shear (same as shear examples)
melt
rapid melt of 3d LJ system
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
nb3b
use of nonbonded 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
reax
RDX and TATB models using the ReaxFF
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
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 .
lmp_linux -in in.indent

# copy LAMMPS executable to this dir
# run the problem

196

LAMMPS Users Manual
Running the simulation produces the files dump.indent and log.lammps. You can
visualize the dump file of snapshots with a variety of 3rd-party tools highlighted on the
Visualization page of the LAMMPS web site.
If you uncomment the dump image line(s) in the input script a series of JPG images
will be produced by the run (assuming you built LAMMPS with JPG support; see
Section 2.2 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 doc 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

Uppercase directories
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
KAPPA
compute thermal conductivity via several methods
MC
using LAMMPS in a Monte Carlo mode to relax the energy of a system
USER
examples for USER packages and USER-contributed commands
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.
ASPHERE

The USER directory has a large number of sub-directories which correspond by name
to a USER package. They contain scripts that illustrate how to use the command(s)
provided in that package. Many of the sub-directories have their own README files
which give further instructions. See the Section 4 doc page for more info on specific
USER packages.

197

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

8. Performance & scalability
Current LAMMPS performance is discussed on the Benchmarks page of the LAMMPS
WWW Site where CPU timings and parallel efficiencies 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.
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 dirs
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 dirs and the Section 5.3 doc 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.

198

LAMMPS Users Manual
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 parallel efficiencies 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.

199

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

9. Additional 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 home page
at http://lammps.sandia.gov/prepost.html
A few additional tools are provided with the LAMMPS distribution and are described
in this section.
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.
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 Sandia, 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.
amber2lmp binary2txt ch2lmp chain colvars createatoms doxygen drude eam
database eam generate eff emacs fep i-pi ipp kate lmp2arc lmp2cfg matlab micelle2d
moltemplate msi2lmp phonon polybond pymol_asphere python reax smd vim xmgrace
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'll need to experiment with them
and make necessary modifications yourself.
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

200

LAMMPS Users Manual
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.
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.
chain tool
The file chain.f 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  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.
colvars tools
The colvars directory contains a collection of tools for postprocessing 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:
201

LAMMPS Users Manual
MC-based integration of multidimensional free energy gradient Version 20110511
Syntax: ./abf_integrate  [-n

] [-t

] [-m [0|1] (metadynamics)] [-h

The LAMMPS interface to the colvars collective variable library, as well as these tools,
were created by Axel Kohlmeyer (akohlmey at gmail.com) at ICTP, Italy.
createatoms tool
The tools/createatoms directory contains a Fortran program called createAtoms.f
which can generate a variety of interesting 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.
doxygen tool
The tools/doxygen directory contains a shell script called doxygen.sh which can
generate a call graph and API lists using the Doxygen software.
See the included README file for details.
The tool is authored by Nandor Tamaskovics, numericalfreedom at googlemail.com.
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
univ-bpclermont.fr, alain.dequidt at univ-bpclermont.fr
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).

202

LAMMPS Users Manual
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).
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).
emacs tool
The tools/emacs directory contains a Lips add-on file for Emacs that enables a
lammps-mode for editing of input scripts when using Emacs, with various highlighting
options setup.
These tools were provided by Aidan Thompson at Sandia (athomps at sandia.gov).
fep tool
The tools/fep directory contains Python scripts useful for post-processing results from
performing free-energy perturbation simulations using the USER-FEP package.
The scripts were contributed by Agilio Padua (Universite Blaise Pascal
Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.
See README file in the tools/fep directory.
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 doc page for
further details on running PIMD calculations with LAMMPS.

203

LAMMPS Users Manual
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.
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).
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).
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).
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.

204

LAMMPS Users Manual
These scripts were written by Arun Subramaniyan at Purdue Univ (asubrama at
purdue.edu).
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  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.
moltemplate tool
The moltemplate sub-directory contains a Python-based tool for building molecular
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 http://moltemplate.org.
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 bugfix.
See the README file in the tools/msi2lmp folder for more information.
phonon tool
The phonon sub-directory contains a post-processing tool useful for analyzing the
output of the fix phonon command in the USER-PHONON package.
See the README file for instruction on building the tool and what library it needs.
And see the examples/USER/phonon directory for example problems that can be
post-processed with this tool.

205

LAMMPS Users Manual
This tool was written by Ling-Ti Kong at Shanghai Jiao Tong University.
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.
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.
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
• 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.
reax tool
The reax sub-directory contains stand-alond codes that can post-process the output of
the fix reax/bonds command from a LAMMPS simulation using ReaxFF. See the
README.txt file for more info.
These tools were written by Aidan Thompson at Sandia.

206

LAMMPS Users Manual
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 (USER-SMD) package into a VTK-compatible unstructured 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 USER-SMD package author, Georg Ganzenmuller at the
Fraunhofer-Institute for High-Speed Dynamics, Ernst Mach Institute in Germany
(georg.ganzenmueller at emi.fhg.de).
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)
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)

207

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

10. Modifying & extending LAMMPS
This section describes how to customize LAMMPS by modifying and extending its
source code.
10.1 Atom styles
10.2 Bond, angle, dihedral, improper potentials
10.3 Compute styles
10.4 Dump styles
10.5 Dump custom output options
10.6 Fix styles which include integrators, temperature and pressure control, force
constraints, boundary conditions, diagnostic output, etc
10.7 Input script commands
10.8 Kspace computations
10.9 Minimization styles
10.10 Pairwise potentials
10.11 Region styles
10.12 Body styles
10.13 Thermodynamic output options
10.14 Variable options
10.15 Submitting new features for inclusion in LAMMPS
LAMMPS is designed in a modular fashion so as to be easy to modify and extend with
new functionality. In fact, about 75% of its source code is files added in this fashion.
In this section, changes and additions users can make are listed along with minimal
instructions. If you add a new feature to LAMMPS and think it will be of interest to
general users, we encourage you to submit it to the developers for inclusion in the
released version of LAMMPS. Information about how to do this is provided below.
The best way to add a new feature is to find a similar feature in LAMMPS 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 hi-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 in this section 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 dir and re-building LAMMPS.
The advantage of C++ and its object-orientation is that all the code and variables
208

LAMMPS Users Manual
needed to define the new feature are in the 2 files you write, and thus shouldn't 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
PairStyle(foo,PairFoo)
#else
...
(class definition for PairFoo)
...
#endif

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.
As illustrated by this pairwise example, many kinds of options are referred to in the
LAMMPS documentation as the "style" of a particular command.
The instructions below give 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. Virtual functions in the base class header file which are set = 0 are ones
you must define in your new derived class to give it the functionality LAMMPS
expects. Virtual functions that are not set to 0 are functions you can optionally define.
Additionally, new output options can be added directly to the thermo.cpp,
dump_custom.cpp, and variable.cpp files as explained below.
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.
• Don't do anything within the timestepping of a run that isn't parallel. E.g. don't
accumulate a bunch of data on a single processor and analyze it. You run the
risk of seriously degrading the parallel efficiency.
• If your new feature reads arguments or writes output, make sure you follow the
unit conventions discussed by the units command.
• If you add something you think is truly useful and doesn't impact LAMMPS
performance when it isn't used, send an email to the developers. We might be
209

LAMMPS Users Manual
interested in adding it to the LAMMPS distribution. See further details on this
at the bottom of this page.

10.1 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. 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 a simple example of an atom style.
Here is a brief description of methods you define in your new derived class. See
atom_vec.h for details.
init
grow

one time setup (optional)
re-allocate atom arrays to longer lengths (required)
make array pointers in Atom and AtomVec classes consistent
grow_reset
(required)
copy info for one atom to another atom's array locations
copy
(required)
store an atom's info in a buffer communicated every timestep
pack_comm
(required)
pack_comm_vel
add velocity info to communication buffer (required)
pack_comm_hybrid
store extra info unique to this atom style (optional)
unpack_comm
retrieve an atom's info from the buffer (required)
unpack_comm_vel
also retrieve velocity info (required)
unpack_comm_hybrid retrieve extra info unique to this atom style (optional)
store an atom's info in a buffer communicating partial forces
pack_reverse
(required)
pack_reverse_hybrid
store extra info unique to this atom style (optional)
unpack_reverse
retrieve an atom's info from the buffer (required)
unpack_reverse_hybrid retrieve extra info unique to this atom style (optional)
store an atom's info in a buffer communicated on neighbor
pack_border
re-builds (required)
pack_border_vel
add velocity info to buffer (required)
pack_border_hybrid
store extra info unique to this atom style (optional)
unpack_border
retrieve an atom's info from the buffer (required)
unpack_border_vel
also retrieve velocity info (required)
unpack_border_hybrid retrieve extra info unique to this atom style (optional)
store all an atom's info to migrate to another processor
pack_exchange
(required)
unpack_exchange
retrieve an atom's info from the buffer (required)

210

LAMMPS Users Manual
number of restart quantities associated with proc's atoms
(required)
pack_restart
pack atom quantities into a buffer (required)
unpack_restart
unpack atom quantities from a buffer (required)
create_atom
create an individual atom of this style (required)
data_atom
parse an atom line from the data file (required)
data_atom_hybrid
parse additional atom info unique to this atom style (optional)
data_vel
parse one line of velocity information from data file (optional)
parse additional velocity data unique to this atom style
data_vel_hybrid
(optional)
memory_usage
tally memory allocated by atom arrays (required)
The constructor of the derived class sets values for several variables that you must set
when defining a new atom style, which are documented in atom_vec.h. New atom
arrays are defined in atom.cpp. Search for the word "customize" and you will find
locations you will need to modify.
size_restart

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 doc page for examples of cases where this is useful
and details on how to initialize, access, and output the custom values.
New pair styles, fixes, or computes can be added to LAMMPS, as discussed below. The
code for these classes can use the per-atom properties defined by fix property/atom.
The Atom class has a find_custom() method that is useful in this context:
int index = atom->find_custom(char *name, int &flag);

The "name" of a custom attribute, as specified in the fix property/atom command, is
checked to verify that it exists and its index is returned. The method also sets flag =
0/1 depending on whether it is an integer or floating-point attribute. The vector of
values associated with the attribute can then be accessed using the returned index as
int *ivector = atom->ivector[index];
double *dvector = atom->dvector[index];

Ivector or dvector are vectors of length Nlocal = # of owned atoms, which store the
attributes of individual atoms.

10.2 Bond, angle, dihedral, improper potentials
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.

211

LAMMPS Users Manual
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
init_style
compute
settings
coeff
equilibrium_distance
equilibrium_angle
write & read_restart
single
memory_usage

check if all coefficients are set, calls init_style (optional)
check if style specific conditions are met (optional)
compute the molecular interactions (required)
apply global settings for all types (optional)
set coefficients for one type (required)
length of bond, used by SHAKE (required, bond only)
opening of angle, used by SHAKE (required, angle only)
writes/reads coeffs to restart files (required)
force and energy of a single bond or angle (required, bond or
angle only)
tally memory allocated by the style (optional)

10.3 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.
init
init_list
compute_scalar
compute_vector
compute_peratom
compute_local
pack_comm
unpack_comm
pack_reverse
unpack_reverse
remove_bias
remove_bias_all
restore_bias
restore_bias_all
pair_tally_callback

perform one time setup (required)
neighbor list setup, if needed (optional)
compute a scalar quantity (optional)
compute a vector of quantities (optional)
compute one or more quantities per atom (optional)
compute one or more quantities per processor (optional)
pack a buffer with items to communicate (optional)
unpack the buffer (optional)
pack a buffer with items to reverse communicate (optional)
unpack the buffer (optional)
remove velocity bias from one atom (optional)
remove velocity bias from all atoms in group (optional)
restore velocity bias for one atom after remove_bias (optional)
same as before, but for all atoms in group (optional)
callback function for tally-style computes (optional).
212

LAMMPS Users Manual
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 USER-TALLY
package provides examples_compute_tally.html for utilizing this mechanism.

10.4 Dump styles
10.5 Dump custom output options
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.
Alternatively, you can add new keywords to the dump custom command. Search for
the word "customize" in dump_custom.cpp to see the half-dozen or so locations where
code will need to be added.

10.6 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
213

LAMMPS Users Manual
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.
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)
called immediately before the 1st timestep and after forces
setup
are computed (optional)
like setup_pre_force, but for minimizations instead of MD runs
min_setup_pre_force
(optional)
min_setup
like setup, but for minimizations instead of MD runs (optional)
initial_integrate
called at very beginning of each timestep (optional)
called before atom exchange on re-neighboring steps
pre_exchange
(optional)
pre_neighbor
called before neighbor list build (optional)
pre_force
called before pair & molecular forces are computed (optional)
called after pair & molecular forces are computed and
post_force
communicated (optional)
final_integrate
called at end of each timestep (optional)
end_of_step
called at very end of timestep (optional)
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 atom info when an atom migrates to a new processor
copy_arrays
(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)
called after the first half integration step is done in rRESPA
post_integrate_respa
(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)
called after pair & molecular forces are computed in
min_pre_force
minimizer (optional)
setmask

214

LAMMPS Users Manual
called after pair & molecular forces are computed and
communicated in minimizer (optional)
store extra data for linesearch based minimization on a LIFO
min_store
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)
report number of degrees of freedom added by this fix in
min_dof
minimization (optional)
report maximum allowed step size during linesearch
max_alpha
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 a buffer to reverse communicate a per-atom quantity
pack_reverse_comm
(optional)
unpack a buffer to reverse communicate a per-atom quantity
unpack_reverse_comm
(optional)
report number of degrees of freedom removed by this fix
dof
during MD (optional)
compute_scalar
return a global scalar property that the fix computes (optional)
return a component of a vector property that the fix computes
compute_vector
(optional)
return a component of an array property that the fix computes
compute_array
(optional)
deform
called when the box size is changed (optional)
called when a change of the target temperature is requested
reset_target
during a run (optional)
is called when a change of the time step is requested during a
reset_dt
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 determines when the fix will be invoked during the
timestep. Fixes that perform time integration (nve, nvt, npt) implement
initial_integrate() and final_integrate() to perform velocity Verlet updates. Fixes that
constrain forces implement post_force().
min_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).

215

LAMMPS Users Manual
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 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.

10.7 Input script commands
New commands can be added to LAMMPS input scripts by adding new classes that
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 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.

10.8 Kspace computations
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.
init
setup
compute
memory_usage

initialize the calculation before a run
computation before the 1st timestep of a run
every-timestep computation
tally of memory usage

10.9 Minimization styles
Classes that perform energy minimization derived from the Min class. New styles can
be created to add new minimization algorithms to LAMMPS.
216

LAMMPS Users Manual
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

10.10 Pairwise potentials
Classes that compute pairwise interactions are derived from the Pair class. In
LAMMPS, pairwise calculation include manybody 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:
compute
settings
coeff
init_one
init_style
write & read_restart
write & read_restart_settings

workhorse routine that computes pairwise interactions
reads the input script line with arguments you define
set coefficients for one i,j type pair
perform initialization for one i,j type pair
initialization specific to this pair style
write/read i,j pair coeffs to restart files
write/read global settings to restart files
force and energy of a single pairwise interaction
single
between 2 atoms
compute_inner/middle/outer versions of compute used by rRESPA
The inner/middle/outer routines are optional.

10.11 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
217

LAMMPS Users Manual
surface_interior determine if a point is within a cutoff distance inside of surc
surface_exterior determine if a point is within a cutoff distance outside of surf
shape_update
change region shape if set by time-dependent variable

10.12 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 Section 6.14 of the manual for an overview of using body particles and the body
doc page for details on 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.
data_body
noutrow
noutcol
output
pack_comm_body
unpack_comm_body
pack_border_body
unpack_border_body

process a line from the Bodies section of a data file
number of sub-particles output is generated for
number of values per-sub-particle output is generated for
output values for the Mth sub-particle
body attributes to communicate every timestep
unpacking of those attributes
body attributes to communicate when reneighboring is done
unpacking of those attributes

10.13 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
218

LAMMPS Users Manual
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, computes, 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.

10.14 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) was discussed here on this 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).
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) was discussed here on this page.

10.15 Submitting new features for inclusion in LAMMPS
We encourage users to submit new features or modifications for LAMMPS to the core
developers so they can be added to the LAMMPS distribution. The preferred way to
manage and coordinate this is as of Fall 2016 via the LAMMPS project on GitHub. An
alternative is to contact the LAMMPS developers or the indicated developer of a
package or feature directly and send in your contribution via e-mail.
219

LAMMPS Users Manual
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
result 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.
How quickly your contribution will be integrated depends largely on how much effort
it will cause to integrate and test it, how much it requires changes to the core
codebase, and of how much interest it is to the larger LAMMPS community. Please see
below for a checklist of typical requirements. Once you have prepared everything, see
this tutorial for instructions on how to submit your changes or new files through a
GitHub pull request. If you prefer to submit patches or full files, you should first make
certain, that your code works correctly with the latest patch-level version of LAMMPS
and contains all bugfixes from it. Then create a gzipped tar file of all changed or
added files or a corresponding patch file using 'diff -u' or 'diff -c' and compress it with
gzip. Please only use gzip compression, as this works well on all platforms.
If the new features/files are broadly useful we may add them as core files to LAMMPS
or as part of a standard package. Else we will add them as a user-contributed file or
package. Examples of user packages are in src sub-directories that start with USER.
The USER-MISC package is simply a collection of (mostly) unrelated single files,
which is the simplest way to have your contribution quickly added to the LAMMPS
distribution. You can see a list of the both standard and user packages by typing
"make package" in the LAMMPS src directory.
Note that by providing us files to release, you are agreeing to make them open-source,
i.e. we can release them under the terms of the GPL, used as a license for the rest of
LAMMPS. See Section 1.4 for details.
With user packages and files, all we are really providing (aside from the fame and
fortune that accompanies having your name in the source code and on the Authors
page of the LAMMPS WWW site), is a means for you to distribute your work to the
LAMMPS user community, and a mechanism for others to easily try out your new
feature. This may help you find bugs or make contact with new collaborators. Note
that you're also implicitly agreeing to support your code which means answer
questions, fix bugs, and maintain it if LAMMPS changes in some way that breaks it (an
unusual event).
NOTE: If you prefer to actively develop and support your add-on feature yourself, then
you may wish to make it available for download from your own website, as a user
package that LAMMPS users can add to their copy of LAMMPS. See the Offsite
LAMMPS packages and tools page of the LAMMPS web site for examples of groups
that do this. We are happy to advertise your package and web site from that page.
Simply email the developers with info about your package and we will post it there.
The previous sections of this doc page describe how to add new "style" files of various
kinds to LAMMPS. Packages are simply collections of one or more new class files
which are invoked as a new style within a LAMMPS input script. If designed correctly,
these additions typically do not require changes to the main core of LAMMPS; they
220

LAMMPS Users Manual
are simply add-on files. If you think your new feature requires non-trivial changes in
core LAMMPS files, you'll need to communicate with the developers, since we may or
may not want to make those changes. An example of a trivial change is making a
parent-class method "virtual" when you derive a new child class from it.
Here is a checklist of steps you need to follow to submit a single file or user package
for our consideration. Following these steps will save both you and us time. See
existing files in packages in the src dir for examples. If you are uncertain, please ask.
• All source files you provide must compile with the most current version of
LAMMPS with multiple configurations. In particular you need to test compiling
LAMMPS from scratch with -DLAMMPS_BIGBIG set in addition to the default
-DLAMMPS_SMALLBIG setting. Your code will need to work correctly in serial
and in parallel using MPI.
• For consistency with the rest of LAMMPS and especially, if you want your
contribution(s) to be added to main LAMMPS code or one of its standard
packages, it needs to be written in a style compatible with other LAMMPS
source files. This means: 2-character indentation per level, no tabs, no lines
over 80 characters. I/O is done via the C-style stdio library, class header files
should not import any system headers outside , STL containers should be
avoided in headers, and forward declarations used where possible or needed.
All added code should be placed into the LAMMPS_NS namespace or a
sub-namespace; global or static variables should be avoided, as they conflict
with the modular nature of LAMMPS and the C++ class structure. Header files
must not import namespaces with using. This all is so the developers can more
easily understand, integrate, and maintain your contribution and reduce
conflicts with other parts of LAMMPS. This basically means that the code
accesses data structures, performs its operations, and is formatted similar to
other LAMMPS source files, including the use of the error class for error and
warning messages.
• If you want your contribution to be added as a user-contributed feature, and it's
a single file (actually a *.cpp and *.h file) it can rapidly be added to the
USER-MISC directory. Send us the one-line entry to add to the
USER-MISC/README file in that dir, along with the 2 source files. You can do
this multiple times if you wish to contribute several individual features.
• If you want your contribution to be added as a user-contribution and it is
several related features, it is probably best to make it a user package directory
with a name like USER-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. If
your files depend on other LAMMPS style files 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. See other README and
Install.sh files in other USER directories as examples. Send us a tarball of this
USER-FOO directory.
• Your new source files need to have the LAMMPS copyright, GPL notice, and
your name and email address at the top, like other user-contributed LAMMPS
source files. They need to create a class that is inside the LAMMPS namespace.
If the file is for one of the USER packages, including USER-MISC, then we are
not as picky about the coding style (see above). I.e. the files do not need to be in
the same stylistic format and syntax as other LAMMPS files, though that would
221

LAMMPS Users Manual
be nice for developers as well as users who try to read your code.
• You must also create a documentation file for each new command or style you
are adding to LAMMPS. For simplicity and convenience, the documentation of
groups of closely related commands or styles may be combined into a single file.
This will be one file for a single-file feature. For a package, it might be several
files. These are simple text files with a specific markup language, that are then
auto-converted to HTML and PDF. The tools for this conversion are included in
the source distribution, and the translation can be as simple as doing "make
html pdf" in the doc folder. Thus the documentation source files must be in the
same format and style as other *.txt files in the lammps/doc/src directory for
similar commands and styles; use one or more of them as a starting point. A
description of the markup can also be found in
lammps/doc/utils/txt2html/README.html As appropriate, the text files can
include links to equations (see doc/Eqs/*.tex for examples, we auto-create the
associated JPG files), or figures (see doc/JPG for examples), or even additional
PDF files with further details (see doc/PDF for examples). The doc page should
also include literature citations as appropriate; see the bottom of doc/fix_nh.txt
for examples and the earlier part of the same file for how to format the cite
itself. The "Restrictions" section of the doc page should indicate that your
command is only available if LAMMPS is built with the appropriate USER-MISC
or USER-FOO package. See other user package doc files for examples of how to
do this. The prerequisite for building the HTML format files are Python 3.x and
virtualenv, the requirement for generating the PDF format manual is the
htmldoc software. Please run at least "make html" and carefully inspect and
proofread the resulting HTML format doc page before submitting your code.
• For a new package (or even a single command) you should include one or more
example scripts demonstrating its use. These should run in no more than a
couple minutes, even on a single processor, and not require large data files as
input. See directories under examples/USER for examples of input scripts other
users provided for their packages. These example inputs are also required for
validating memory accesses and testing for memory leaks with valgrind
• 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/USER-EFF/atom_vec_electron.cpp for an example. A LaTeX citation is stored
in a variable at the top of the file and a single line of code that references the
variable is added to the constructor of the class. Whenever a user invokes your
feature from their input script, this will cause LAMMPS to output the citation to
a log.cite file and prompt the user to examine the file. Note that you should only
use this for a paper you or your group authored. E.g. adding a cite 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 kind of citation should just be in the
doc page you provide.
Finally, as a general rule-of-thumb, the more clear and self-explanatory you make your
documentation and README files, and the easier you make it for people to get
started, e.g. by providing example scripts, the more likely it is that users will try out
your new feature.

222

LAMMPS Users Manual
(Foo) Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).

223

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

11. Python interface to LAMMPS
LAMMPS can work together with Python in three ways. First, Python can wrap
LAMMPS through the LAMMPS library interface, so that a Python script can create
one or more instances of LAMMPS and launch one or more simulations. In Python
lingo, this is "extending" Python with LAMMPS.
Second, the low-level Python interface can be used indirectly through the PyLammps
and IPyLammps wrapper classes in Python. These wrappers try to simplify the usage
of LAMMPS in Python by providing an object-based interface to common LAMMPS
functionality. It also reduces the amount of code necessary to parameterize LAMMPS
scripts through Python and makes variables and computes directly accessible. See
PyLammps interface for more details.
Third, LAMMPS can use the Python interpreter, so that a LAMMPS input script can
invoke Python code, and pass information back-and-forth between the input script and
Python functions you write. The Python code can also callback to LAMMPS to query or
change its attributes. In Python lingo, this is "embedding" Python in LAMMPS.
This section describes how to use these three approaches.
• 11.1
• 11.2
• 11.3
• 11.4
• 11.5
• 11.6
• 11.7
• 11.8
• 11.9

Overview of running LAMMPS from Python
Overview of using Python from a LAMMPS script
Building LAMMPS as a shared library
Installing the Python wrapper into Python
Extending Python with MPI to run in parallel
Testing the Python-LAMMPS interface
Using LAMMPS from Python
Example Python scripts that use LAMMPS
PyLammps interface

If you are not familiar with it, Python is a powerful scripting and programming
language which can essentially do anything that faster, lower-level languages like C or
C++ can do, but typically with much fewer lines of code. When used in embedded
mode, Python can perform operations that the simplistic LAMMPS input script syntax
cannot. Python can be also be used as a "glue" language to drive a program through
its library interface, or to hook multiple pieces of software together, such as a
simulation package plus a visualization package, or to run a coupled multiscale or
multiphysics model.
See Section 6.10 of the manual and the couple directory of the distribution for more
ideas about coupling LAMMPS to other codes. See Section 6.19 for a description of
the LAMMPS library interface provided in src/library.cpp and src/library.h, and how to
extend it for your needs. As described below, that interface is what 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 library
interface is designed to be easy to add functions to. Thus the Python interface to
224

LAMMPS Users Manual
LAMMPS is also 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
useful to other users, please email them to the developers. We can include them in the
LAMMPS distribution.

11.1 Overview of running LAMMPS from Python
The LAMMPS distribution includes a python directory with all you need to run
LAMMPS from Python. The python/lammps.py file wraps the LAMMPS library
interface, with one wrapper function per LAMMPS library function. This file 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 give it an input script, run LAMMPS incrementally, extract LAMMPS results, an
modify internal LAMMPS variables. From a Python script you can do this in serial or
parallel. Running Python interactively in parallel does not generally work, unless you
have a version of Python that extends standard Python to enable multiple instances of
Python to read what you type.
To do all of this, you must first build LAMMPS as a shared library, then insure that
your Python can find the python/lammps.py file and the shared library. These steps
are explained in subsequent sections 11.3 and 11.4. Sections 11.5 and 11.6 discuss
using MPI from a parallel Python program and how to test that you are ready to use
LAMMPS from Python. Section 11.7 lists all the functions in the current LAMMPS
library interface and how to call them from Python.
Section 11.8 gives some examples of coupling LAMMPS to other tools via Python. For
example, LAMMPS can easily be coupled to a GUI or other visualization tools that
display graphs or animations in real time as LAMMPS runs. Examples of such scripts
are included in the python directory.
Two advantages of using Python to run LAMMPS are how concise the language is, and
that it can be run interactively, enabling rapid development and debugging of
programs. If you use it to mostly invoke costly operations within LAMMPS, such as
running a simulation for a reasonable number of timesteps, then the overhead cost of
invoking LAMMPS thru Python will be negligible.
The Python wrapper for LAMMPS uses the amazing and magical (to me) "ctypes"
package in Python, which auto-generates the interface code needed between Python
and a set of C interface routines for a library. Ctypes is part of standard Python for
versions 2.5 and later. You can check which version of Python you have installed, by
simply typing "python" at a shell prompt.

225

LAMMPS Users Manual
11.2 Overview of using Python from a LAMMPS script
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 previous section 11.1. 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 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 doc 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.
The fix python/invoke command can execute Python code at selected timesteps during
a simulation run.
The pair_style python command allows you to define pairwise potentials as python
code which encodes a single pairwise interaction. This is useful for
rapid-developement and debugging of a new potential.
To use any of these commands, you only need to build LAMMPS with the PYTHON
package installed:
226

LAMMPS Users Manual
make yes-python
make machine

Note that this will link LAMMPS with the Python library on your system, which
typically requires several auxiliary system libraries to also be linked. The list of these
libraries and the paths to find them are specified in the lib/python/Makefile.lammps
file. You need to insure that file contains the correct information for your version of
Python and your machine to successfully build LAMMPS. See the lib/python/README
file for more info.
If you want to write Python code with callbacks to LAMMPS, then you must also follow
the steps overviewed in the preceding section (11.1) for running LAMMPS from
Python. I.e. you must build LAMMPS as a shared library and insure that Python can
find the python/lammps.py file and the shared library.

11.3 Building LAMMPS as a shared library
Instructions on how to build LAMMPS as a shared library are given in Section 2.4. A
shared library is one that is dynamically loadable, which is what Python requires to
wrap LAMMPS. On Linux this is a library file that ends in ".so", not ".a".
From the src directory, type
make foo mode=shlib

where foo is the machine target name, such as linux or g++ or serial. This should
create the file liblammps_foo.so in the src directory, as well as a soft link
liblammps.so, which is what the Python wrapper will load by default. Note that if you
are building multiple machine versions of the shared library, the soft link is always set
to the most recently built version.
NOTE: If you are building LAMMPS with an MPI or FFT library or other auxiliary
libraries (used by various packages), then all of these extra libraries must also be
shared libraries. If the LAMMPS shared-library build fails with an error complaining
about this, see Section 2.4 for more details.

11.4 Installing the Python wrapper into Python
For Python to invoke LAMMPS, there are 2 files it needs to know about:
• python/lammps.py
• src/liblammps.so
Lammps.py is the Python wrapper on the LAMMPS library interface. Liblammps.so is
the shared LAMMPS library that Python loads, as described above.
You can insure Python can find these files in one of two ways:
• set two environment variables
227

LAMMPS Users Manual
• run the python/install.py script
If you set the paths to these files as environment variables, you only have to do it
once. For the csh or tcsh shells, add something like this to your ~/.cshrc file, one line
for each of the two files:
setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src

If you use the python/install.py script, you need to invoke it every time you rebuild
LAMMPS (as a shared library) or make changes to the python/lammps.py file.
You can invoke install.py from the python directory as
% python install.py [libdir] [pydir]

The optional libdir is where to copy the LAMMPS shared library to; the default is
/usr/local/lib. The optional pydir is where to copy the lammps.py file to; the default is
the site-packages directory of the version of Python that is running the install script.
Note that libdir must be a location that is in your default LD_LIBRARY_PATH, like
/usr/local/lib or /usr/lib. And pydir must be a location that Python looks in by default
for imported modules, like its site-packages dir. If you want to copy these files to
non-standard locations, such as within your own user space, you will need to set your
PYTHONPATH and LD_LIBRARY_PATH environment variables accordingly, as above.
If the install.py script does not allow you to copy files into system directories, prefix
the python command with "sudo". If you do this, make sure that the Python that root
runs is the same as the Python you run. E.g. you may need to do something like
% sudo /usr/local/bin/python install.py [libdir] [pydir]

You can also invoke install.py from the make command in the src directory as
% make install-python

In this mode you cannot append optional arguments. Again, you may need to prefix
this with "sudo". In this mode you cannot control which Python is invoked by root.
Note that if you want Python to be able to load different versions of the LAMMPS
shared library (see this section below), you will need to manually copy files like
liblammps_g++.so into the appropriate system directory. This is not needed if you set
the LD_LIBRARY_PATH environment variable as described above.

11.5 Extending Python with MPI 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.

228

LAMMPS Users Manual
There are several Python packages available that purport to wrap MPI as a library and
allow MPI functions to be called from Python. However, development on most of them
seems to be halted except on:
• mpi4py
• PyPar
Both packages, PyPar and mpi4py have been successfully tested with LAMMPS. PyPar
is simpler and easy to set up and use, but supports only a subset of MPI. Mpi4py is
more MPI-feature complete, but also a bit more complex to use. As of version 2.0.0,
mpi4py is the only python MPI wrapper that allows passing a custom MPI
communicator to the LAMMPS constructor, which means one can easily run one or
more LAMMPS instances on subsets of the total MPI ranks.
PyPar requires the ubiquitous Numpy package be installed in your Python. After
launching Python, type
import numpy

to see if it is installed. If not, here is how to install it (version 1.3.0b1 as of April 2009).
Unpack the numpy tarball and from its top-level directory, type
python setup.py build
sudo python setup.py install

The "sudo" is only needed if required to copy Numpy files into your Python
distribution's site-packages directory.
To install PyPar (version pypar-2.1.4_94 as of Aug 2012), unpack it and from its
"source" directory, type
python setup.py build
sudo python setup.py install

Again, the "sudo" is only needed if required to copy PyPar files into your Python
distribution's site-packages directory.
If you have successfully installed PyPar, you should be able to run Python and type
import pypar

without error. You should also be able to run python in parallel on a simple test script
% mpirun -np 4 python test.py

where test.py contains the lines
import pypar
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())

and see one line of output for each processor you run on.

229

LAMMPS Users Manual
NOTE: To use PyPar and LAMMPS in parallel from Python, you must insure both are
using the same version of MPI. If you only have one MPI installed on your system, this
is not an issue, but it can be if you have multiple MPIs. Your LAMMPS build is explicit
about which MPI it is using, since you specify the details in your lo-level
src/MAKE/Makefile.foo file. PyPar 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 PyPar and LAMMPS together, this is an issue you
may need to address, e.g. by moving other MPI installations so that PyPar finds the
right one.
To install mpi4py (version mpi4py-2.0.0 as of Oct 2015), unpack it and from its main
directory, type
python setup.py build
sudo python setup.py install

Again, the "sudo" is only needed if required to copy mpi4py files into your Python
distribution's site-packages directory. To install with user privilege into the user local
directory type
python setup.py install --user

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 python test.py

where test.py contains the lines
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: To use mpi4py and LAMMPS in parallel from Python, you must insure both are
using the same version of MPI. If you only have one MPI installed on your system, this
is not an issue, but it can be if you have multiple MPIs. Your LAMMPS build is explicit
about which MPI it is using, since you specify the details in your lo-level
src/MAKE/Makefile.foo file. 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 moving other MPI installations so that mpi4py finds the
right one.

230

LAMMPS Users Manual
11.6 Testing the Python-LAMMPS interface
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 2nd 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.
You can also test the load directly in Python as follows, without first importing from
the lammps.py file:
>>> from ctypes import CDLL
>>> CDLL("liblammps.so")

If an error occurs, carefully go thru the steps in Section 2.4 and above about building
a shared library and about insuring Python can find the necessary two files it needs.
Test LAMMPS and Python in serial:

To run a LAMMPS test 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
% python 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_g++ -in in.lj
Test LAMMPS and Python in parallel:

To run LAMMPS in parallel, assuming you have installed the PyPar package as
discussed above, create a test.py file containing these lines:
import pypar
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp

231

LAMMPS Users Manual
pypar.finalize()

To run LAMMPS in parallel, assuming you have installed the mpi4py package as
discussed above, 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()
print "Proc %d out of %d procs has" % (me,nprocs),lmp
MPI.Finalize()

You can either script in parallel as:
% mpirun -np 4 python test.py

and you should see the same output as if you had typed
% mpirun -np 4 lmp_g++ -in in.lj

Note that if you leave out the 3 lines from test.py that specify PyPar commands you
will instantiate and run LAMMPS independently on each of the P processors specified
in the mpirun command. In this case you should get 4 sets of output, each showing
that a LAMMPS run was made on a single processor, instead of one set of output
showing that LAMMPS ran on 4 processors. If the 1-processor outputs occur, it means
that PyPar is not working correctly.
Also note that once you import the PyPar module, PyPar initializes MPI for you, and
you can use MPI calls directly in your Python script, as described in the PyPar
documentation. The last line of your Python script should be pypar.finalize(), to insure
MPI is shut down correctly.
Running Python scripts:

Note that any Python script (not just for LAMMPS) can be invoked in one of several
ways:
% python foo.script
% python -i foo.script
% foo.script

The last command requires that the first line of the script be something like this:
#!/usr/local/bin/python
#!/usr/local/bin/python -i

where the path points to where you have Python installed, and that you have made the
script file executable:
% chmod +x foo.script

232

LAMMPS Users Manual
Without the "-i" flag, Python will exit when the script finishes. With the "-i" flag, you
will be left in the Python interpreter 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.

11.7 Using LAMMPS from Python
As described above, the Python interface to LAMMPS consists of a Python "lammps"
module, the source code for which is in python/lammps.py, which creates a "lammps"
object, with a set of methods that can be invoked on that object. The sample Python
code below assumes you have first imported the "lammps" module in your Python
script, as follows:
from lammps import lammps

These are the methods defined by the lammps module. If you look at the files
src/library.cpp and src/library.h you will see that they correspond one-to-one with
calls you can make to the LAMMPS library from a C++ or C or Fortran program, and
which are described in Section 6.19 of the manual.
lmp = lammps()
lmp
lmp
lmp
lmp

# create a LAMMPS object using the default liblammps.so library
# 4 optional args are allowed: name, cmdargs, ptr, comm
= lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object
= lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2
= lammps(name="g++")
# create a LAMMPS object using the liblammps_g++.so library
= lammps(name="g++",cmdargs=list)
# add LAMMPS command-line args, e.g. list = ["-echo","

lmp.close()

# destroy a LAMMPS object

version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 2015
-> 20150902
lmp.file(file)
lmp.command(cmd)

# run an entire input script, file = "in.lj"
# invoke a single LAMMPS command, cmd = "run 100"

lmp.commands_list(cmdlist) # invoke commands in cmdlist = "run 10", "run 20"
lmp.commands_string(multicmd) # invoke commands in multicmd = "run 10\nrun 20"
xlo = lmp.extract_global(name,type)

# extract a global quantity
# name = "boxxlo", "nlocal", etc
# type = 0 = int
#
1 = double

coords = lmp.extract_atom(name,type)

# extract a per-atom quantity
# name = "x", "type", etc
# type = 0 = vector of ints
#
1 = array of ints
#
2 = vector of doubles
#
3 = array of doubles

eng = lmp.extract_compute(id,style,type)
v3 = lmp.extract_fix(id,style,type,i,j)

# extract value(s) from a compute
# extract value(s) from a fix

233

LAMMPS Users Manual
#
#
#
#
#
#
#
#
var = lmp.extract_variable(name,group,flag)

id = ID of compute or fix
style = 0 = global data
1 = per-atom data
2 = local data
type = 0 = scalar
1 = vector
2 = array
i,j = indices of value in global vector or array
#
#
#
#
#

extract value(s) from a variable
name = name of variable
group = group ID (ignored for equal-style variab
flag = 0 = equal-style variable
1 = atom-style variable

flag = lmp.set_variable(name,value) # set existing named string-style variable to
value, flag = 0 if successful value = lmp.get_thermo(name) # return current value of a
thermo keyword
natoms = lmp.get_natoms()
data = lmp.gather_atoms(name,type,count)
lmp.scatter_atoms(name,type,count,data)

#
#
#
#
#
#
#

total # of atoms as int
return per-atom property of all atoms gathered into
name = "x", "charge", "type", etc
count = # of per-atom values, 1 or 3, etc
scatter per-atom property to all atoms from data, o
name = "x", "charge", "type", etc
count = # of per-atom values, 1 or 3, etc

The lines
from lammps import lammps
lmp = lammps()

create an instance of LAMMPS, wrapped in a Python class by the lammps Python
module, and return an instance of the Python class as lmp. It is used to make all
subsequent calls to the LAMMPS library.
Additional arguments to lammps() can be used to tell Python the name of the shared
library to load or to pass arguments to the LAMMPS instance, the same as if LAMMPS
were launched from a command-line prompt.
If the ptr argument is set like this:
lmp = lammps(ptr=lmpptr)

then lmpptr must be an argument passed to Python via the LAMMPS python
command, when it is used to define a Python function that is invoked by the LAMMPS
input script. This mode of using Python with LAMMPS is described above in 11.2. The
variable lmpptr refers to the instance of LAMMPS that called the embedded Python
interpreter. Using it as an argument to lammps() allows the returned Python class
instance "lmp" to make calls to that instance of LAMMPS. See the python command
doc page for examples using this syntax.
Note that you can create multiple LAMMPS objects in your Python script, and
coordinate and run multiple simulations, e.g.
234

LAMMPS Users Manual
from lammps import lammps
lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2")

The file(), command(), commands_list(), commands_string() methods allow an input
script, a single command, or multiple commands to be invoked.
The extract_global(), extract_atom(), extract_compute(), extract_fix(), and
extract_variable() methods return values or pointers to data structures internal to
LAMMPS.
For extract_global() see the src/library.cpp file for the list of valid names. New names
could easily be added. A double or integer is returned. You need to specify the
appropriate data type via the type argument.
For extract_atom(), a pointer to internal LAMMPS atom-based data is returned, which
you can use via normal Python subscripting. See the extract() method in the
src/atom.cpp file for a list of valid names. Again, new names could easily be added if
the property you want is not listed. A pointer to a vector of doubles or integers, or a
pointer to an array of doubles (double **) or integers (int **) is returned. You need to
specify the appropriate data type via the type argument.
For extract_compute() and extract_fix(), the global, per-atom, or local data calculated
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. The I,J arguments can be left out if not needed. See
Section 6.15 of the manual 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 extract_variable(), an equal-style or atom-style variable is evaluated and its result
returned.
For equal-style variables a single double value is returned and the group argument is
ignored. For atom-style variables, a vector of doubles 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.
The get_natoms() method returns the total number of atoms in the simulation, as an
int.
The gather_atoms() method allows any per-atom property (coordinates, velocities, etc)
to be extracted from LAMMPS. It returns a ctypes vector of ints or doubles as
specified by type, of length count*natoms, for the named property for all atoms in the
simulation. The data is ordered by count and then by atom ID. See the extract()
method in the src/atom.cpp file for a list of valid names. Again, new names could
235

LAMMPS Users Manual
easily be added if the property you want is missing. The vector can be used via normal
Python subscripting. If atom IDs are not consecutively ordered within LAMMPS, a
None is returned as indication of an error. A special treatment is applied for image
flags stored in the "image" property. All three image flags are stored in a packed
format in a single integer, so count would be 1 to retrieve that integer, however also a
count value of 3 can be used and then the image flags will be unpacked into 3
individual integers, ordered in a similar fashion as coordinates.
Note that the data structure gather_atoms("x") returns 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) Gathert_atoms() returns a list of all atoms in the simulation; extract_atoms()
returns just the atoms local to each processor. (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.
The scatter_atoms() method allows any per-atom property (coordinates, velocities, etc)
to be inserted into LAMMPS, overwriting the current property. It takes a vector of ints
or doubles as specified by type, of length count*natoms, for the named property for all
atoms in the simulation. The data should be ordered by count and then by atom ID.
See the extract() method in the src/atom.cpp file for a list of valid names. Again, new
names could easily be added if the property you want is missing. It uses the vector of
data to overwrite the corresponding properties for each atom inside LAMMPS. This
requires LAMMPS to have its "map" option enabled; see the atom_modify command
for details. If it is not, or if atom IDs are not consecutively ordered, no coordinates are
reset. Similar as for gather_atoms() a special treatment is applied for image flags,
which can be provided in packed (count = 1) or unpacked (count = 3) format and in
the latter case, they will be packed before applied to atoms.
The array of coordinates passed to scatter_atoms() must be a ctypes vector of ints or
doubles, allocated and initialized something like this:
from ctypes import *
natoms = lmp.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
x[0] = x coord of atom with ID
x[1] = y coord of atom with ID
x[2] = z coord of atom with ID
x[3] = x coord of atom with ID
...
x[n3-1] = z coord of atom with
lmp.scatter_atoms("x",1,3,x)

1
1
1
2
ID natoms

Alternatively, you can just change values in the vector returned by
gather_atoms("x",1,3), since it is a ctypes vector of doubles.
As noted above, these Python class methods correspond one-to-one with the functions
236

LAMMPS Users Manual
in the LAMMPS library interface in src/library.cpp and library.h. This means you can
extend the Python wrapper via the following 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.py for this interface function.
• You should now be able to invoke the new interface function from a Python
script. Isn't ctypes amazing?

11.8 Example Python scripts that use 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
demo.py
simple.py
similar to examples/COUPLE/simple/simple.cpp
same as simple.py but running in parallel on a
subset of procs
GUI go/stop/temperature-slider to control
LAMMPS
real-time temperature plot with GnuPlot via
Pizza.py
real-time viz via some viz package
combination of viz_tool.py and plot.py and gui.py

read/run a LAMMPS input script
thru Python
invoke various LAMMPS library
interface routines
run in parallel
split.py
gui.py
plot.py
viz_tool.py
vizplotgui_tool.py

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:
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 WWW pages here or
here for more details:
http://mt.seas.upenn.edu/Archive/Graphics/A
http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html

The latter link is to AtomEye 3 which has the scriping capability needed by these
Python scripts.
237

LAMMPS Users Manual
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
WWW pages here or here for more details:
http://www.pymol.org
http://sourceforge.net/scm/?type=svn&group_id=4546

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. Click to see larger images:

11.9 PyLammps interface
Please see the PyLammps Tutorial.

238

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

12. Errors
This section describes the errors you can encounter when using LAMMPS, either
conceptually, or as printed out by the program.
12.1 Common problems
12.2 Reporting bugs
12.3 Error & warning messages

12.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 doesn't
catch that you think it should flag, please send an email to the developers.

239

LAMMPS Users Manual
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 argument. The installation and compilation of optional packages is
explained in the installation instructions.
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 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 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.
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 shouldn't 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 doesn't
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
240

LAMMPS Users Manual
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.

12.2 Reporting bugs
If you are confident that you have found a bug in LAMMPS, follow these steps.
Check the New features and bug fixes section of the LAMMPS WWW site to see if the
bug has already been reported or fixed or the Unfixed bug to see if a fix is pending.
Check the mailing list to see if it has been discussed before.
If not, send an email to the mailing list describing the problem with any ideas you
have as to what is causing it or where in the code the problem might be. The
developers will ask for more info if needed, such as an input script or data files.
The most useful thing you can do to help us fix the bug is to isolate the problem. Run
it on the smallest number of atoms and fewest number of processors and with the
simplest input script that reproduces the bug and try to identify what command or
combination of commands is causing the problem.
As a last resort, you can send an email directly to the developers.
12.3 Error & warning messages
These are two alphabetic lists of the ERROR and WARNING messages LAMMPS prints
out and the reason why. If the explanation here is not sufficient, the documentation
for the offending command may help. Error and warning messages also list the source
file and line number where the error was generated. For example, this message
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.
Note that error messages from user-contributed packages are not listed here. If such
an error occurs and is not self-explanatory, you'll need to look in the source code or
contact the author of the package.
Errors:
1-3 bond count is inconsistent
An inconsistency was detected when computing the number of 1-3 neighbors for
241

LAMMPS Users Manual
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.
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
242

LAMMPS Users Manual
The set 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 atoms %d %d %d missing on proc %d 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 atoms missing on proc %d 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 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
243

LAMMPS Users Manual
The boundary style of the face where atoms are added must be of type m
(shrink/minimum).
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 number 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 sorting has bin size = 0.0
The neighbor cutoff is being used as the bin size, but it is zero. Thus you must
explicitly list a bin size in the atom_modify sort command or turn off sorting.
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
244

LAMMPS Users Manual
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.
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.
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
245

LAMMPS Users Manual
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 Coulomb cutoff in fix tune/kspace
Fix tune/kspace tried to find the optimal real space Coulomb 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 spheriods 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.
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 potentials are defined.
Bond atom missing in box size check
The 2nd atoms 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 atom missing in delete_bonds
246

LAMMPS Users Manual
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 2nd 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
particular 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 2nd 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 2nd 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
247

LAMMPS Users Manual
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.
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.
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.
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 doc page discussion of command-line switches.
Can only use -pscreen with multiple partitions
Self-explanatory. See doc 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.
248

LAMMPS Users Manual
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 supported.
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 recompile)
Single precision 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.
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.
249

LAMMPS Users Manual
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 nonperiodic 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 migrated 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 memory allocaters, 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.
250

LAMMPS Users Manual
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.
Cannot displace_atoms after reading restart file with per-atom info
This is because the restart file info cannot be migrated 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.
251

LAMMPS Users Manual
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.
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.
252

LAMMPS Users Manual
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/spatial 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.
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
253

LAMMPS Users Manual
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.
254

LAMMPS Users Manual
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.
Cannot replicate 2d simulation in z dimension
The replicate command cannot replicate a 2d simulation in the z dimension.
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 dependence. 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 nonperiodic Z dimension
Use the boundary command to make the z dimension periodic 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.
255

LAMMPS Users Manual
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.
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 -cuda on and -kokkos on together
This is not allowed since both packages can use GPUs.
Cannot use -cuda on without USER-CUDA installed
The USER-CUDA package must be installed via "make yes-user-cuda" before
LAMMPS is built.
Cannot use -kokkos on without KOKKOS installed
Self-explanatory.
Cannot use -reorder after -partition
Self-explanatory. See doc 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 GPU package with USER-CUDA package enabled
You cannot use both the GPU and USER-CUDA packages together. Use one or
the other.
Cannot use Kokkos pair style with rRESPA inner/middle
Self-explanatory.
256

LAMMPS Users Manual
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 regions.
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 create 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.
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
257

LAMMPS Users Manual
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
258

LAMMPS Users Manual
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 hardwired 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.
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 ave/spatial z for 2 dimensional model
Self-explanatory.
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 2nd 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 dimension 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 2nd 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
259

LAMMPS Users Manual
The x, y, z options cannot be applied to shrink-wrapped dimensions.
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 dimension twice.
Cannot use fix nvt/npt/nph on a 2nd non-periodic dimension
When specifying an off-diagonal pressure component, the 2nd 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 nvt/npt/nph on a non-periodic dimension
When specifying a diagonal pressure component, the dimension 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 2nd dimension in the barostatted tilt factor must be periodic.
Cannot use fix nvt/npt/nph with xz scaling when z is non-periodic dimension
The 2nd dimension in the barostatted tilt factor must be periodic.
Cannot use fix nvt/npt/nph with yz scaling when z is non-periodic dimension
The 2nd dimension in the barostatted 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
260

LAMMPS Users Manual
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 dimension 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.
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
261

LAMMPS Users Manual
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.
262

LAMMPS Users Manual
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.
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
263

LAMMPS Users Manual
Fix setforce cannot be used in this manner. Use fix addforce instead.
Cannot use nonperiodic boundares with fix ttm
This fix requires a fully periodic simulation box.
Cannot use nonperiodic boundaries with Ewald
For kspace style ewald, all 3 dimensions must have periodic boundaries unless
you use the kspace_modify command to define a 2d slab with a non-periodic z
dimension.
Cannot use nonperiodic boundaries with EwaldDisp
For kspace style ewald/disp, all 3 dimensions must have periodic boundaries
unless you use the kspace_modify command to define a 2d slab with a
non-periodic z dimension.
Cannot use nonperiodic boundaries with PPPM
For kspace style pppm, all 3 dimensions must have periodic boundaries unless
you use the kspace_modify command to define a 2d slab with a non-periodic z
dimension.
Cannot use nonperiodic boundaries with PPPMDisp
For kspace style pppm/disp, all 3 dimensions must have periodic 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 hybrid with GPU neighbor list builds
Neighbor list builds must be done on the CPU for this pair style.
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.
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
264

LAMMPS Users Manual
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 constant
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.
Change_box volume used incorrectly
265

LAMMPS Users Manual
The "dim volume" option must be used immediately following one or two
settings 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 ID for compute chunk /atom does not exist
Self-explanatory.
Compute ID for compute chunk/atom does not exist
Self-explanatory.
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.
266

LAMMPS Users Manual
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/spatial does not exist
Self-explanatory.
Compute ID for fix ave/time 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 periodic 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.
267

LAMMPS Users Manual
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 enabled.
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.
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
268

LAMMPS Users Manual
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 developers.
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.
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.
269

LAMMPS Users Manual
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 computation must compute
temperature.
Compute property/atom floating point vector does not exist
The command is accessing a vector added by the fix property/atom command,
that does not exist.
Compute property/atom for atom property that isn't allocated
Self-explanatory.
Compute property/atom integer vector does not exist
The command is accessing a vector added by the fix property/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 isn't 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.
270

LAMMPS Users Manual
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.
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 temperature.
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
271

LAMMPS Users Manual
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.
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 doc 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 doc 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.
272

LAMMPS Users Manual
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. Usually
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.
Could not find compute ID to delete
Self-explanatory.
Could not find compute displace/atom fix ID
273

LAMMPS Users Manual
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.
274

LAMMPS Users Manual
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 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.
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
275

LAMMPS Users Manual
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 temperature 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.
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.
Coulomb cut not supported in pair_style buck/long/coul/coul
Must use long-range Coulombic interactions.
Coulomb cut not supported in pair_style lj/long/coul/long
Must use long-range Coulombic interactions.
Coulomb cut not supported in pair_style lj/long/tip4p/long
Must use long-range Coulombic interactions.
Coulomb cutoffs of pair hybrid sub-styles do not match
If using a Kspace solver, all Coulomb 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
276

LAMMPS Users Manual
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 property/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.
Delete region ID does not exist
Self-explanatory.
Delete_atoms command before simulation box is defined
277

LAMMPS Users Manual
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
The requested elements were not found in the MEAM file.
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.
278

LAMMPS Users Manual
Dihedral atoms %d %d %d %d 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 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.
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 command.
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 setting. 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 dihedral_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 defined.
Dihedral_style command when no dihedrals allowed
The chosen atom style does not allow for dihedrals to be defined.
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.
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
279

LAMMPS Users Manual
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.
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.
280

LAMMPS Users Manual
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 persp option is not yet supported
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.
Dump local fix does not compute local vector
Self-explanatory.
Dump local fix vector is accessed out-of-range
281

LAMMPS Users Manual
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 isn't 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
282

LAMMPS Users Manual
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 didn't on this timestep. See the variable doc 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 vdw spline: inner radius > outer radius
A pre-tabulated spline is invalid. Likely a problem with the potential
parameters.
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
283

LAMMPS Users Manual
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/spatial 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.
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.
284

LAMMPS Users Manual
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
285

LAMMPS Users Manual
Self-explanatory.
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.
286

LAMMPS Users Manual
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/spatial compute does not calculate a per-atom array
Self-explanatory.
Fix ave/spatial compute does not calculate a per-atom vector
A compute used by fix ave/spatial must generate per-atom values.
Fix ave/spatial compute does not calculate per-atom values
A compute used by fix ave/spatial must generate per-atom values.
Fix ave/spatial compute vector is accessed out-of-range
The index for the vector is out of bounds.
Fix ave/spatial fix does not calculate a per-atom array
Self-explanatory.
Fix ave/spatial fix does not calculate a per-atom vector
A fix used by fix ave/spatial must generate per-atom values.
Fix ave/spatial fix does not calculate per-atom values
A fix used by fix ave/spatial must generate per-atom values.
Fix ave/spatial fix vector is accessed out-of-range
The index for the vector is out of bounds.
Fix ave/spatial for triclinic boxes requires units reduced
Self-explanatory.
Fix ave/spatial settings invalid with changing box size
If the box size changes, only the units reduced option can be used.
Fix ave/spatial variable is not atom-style variable
A variable used by fix ave/spatial must generate per-atom values.
Fix ave/time cannot set output array intensive/extensive from these inputs
One of more of the vector inputs has individual elements which are flagged as
intensive or extensive. Such an input cannot be flagged as all
intensive/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.
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
287

LAMMPS Users Manual
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 using 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 distance 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 incrementally, 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
288

LAMMPS Users Manual

Fix

Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix

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.
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.
deform tilt factors require triclinic box
Cannot deform the tilt factors of a simulation box unless it is a triclinic
(non-orthogonal) box.
deform volume setting is invalid
Cannot use volume style unless other dimensions are being controlled.
deposit and fix rigid/small not using same molecule template ID
Self-explanatory.
deposit and fix shake not using same molecule template ID
Self-explanatory.
deposit molecule must have atom types
The defined molecule does not specify atom types.
deposit molecule must have coordinates
The defined molecule does not specify coordinates.
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.
deposit region cannot be dynamic
Only static regions can be used with fix deposit.
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.
deposit shake fix does not exist
Self-explanatory.
efield requires atom attribute q or mu
The atom style defined does not have this attribute.
efield with dipoles cannot use atom-style variables
This option is not supported.
evaporate molecule requires atom attribute molecule
The atom style being used does not define a molecule ID.
external callback function not set
This must be done by an external program in order to use this 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.
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.
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.
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.
for fix ave/spatial not computed at compatible time
289

LAMMPS Users Manual

Fix
Fix
Fix
Fix
Fix
Fix
Fix

Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix
Fix

Fixes generate their values on specific timesteps. Fix ave/spatial is requesting a
value on a non-allowed timestep.
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.
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.
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.
freeze requires atom attribute torque
The atom style defined does not have this attribute.
gcmc and fix shake not using same molecule template ID
Self-explanatory.
gcmc atom has charge, but atom style does not
Self-explanatory.
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
belonging to a molecule could be deleted.
gcmc does not (yet) work with atom_style template
Self-explanatory.
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.
gcmc molecule has charges, but atom style does not
Self-explanatory.
gcmc molecule must have atom types
The defined molecule does not specify atom types.
gcmc molecule must have coordinates
The defined molecule does not specify coordinates.
gcmc molecule template ID must be same as atom_style template ID
When using atom_style template, you cannot insert molecules that are not in
that template.
gcmc put atom outside box
This should not normally happen. Contact the developers.
gcmc ran out of available atom IDs
See the setting for tagint in the src/lmptype.h file.
gcmc ran out of available molecule IDs
See the setting for tagint in the src/lmptype.h file.
gcmc region cannot be dynamic
Only static regions can be used with fix gcmc.
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.
gcmc region extends outside simulation box
Self-explanatory.
gcmc shake fix does not exist
Self-explanatory.
gld c coefficients must be >= 0
290

LAMMPS Users Manual
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 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 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.
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
291

LAMMPS Users Manual
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 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.
Fix nvt/npt/nph dilate group ID does not exist
Self-explanatory.
292

LAMMPS Users Manual
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 cannot 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
293

LAMMPS Users Manual
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.
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 recompile.
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 recompile.
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 recompile.
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.
294

LAMMPS Users Manual
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.
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
295

LAMMPS Users Manual
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 particles.
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 isn't 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.
296

LAMMPS Users Manual
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 integration
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 output 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. Compute 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.
297

LAMMPS Users Manual
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.
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 temperature.
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.
GPU split param must be positive for hybrid pair styles
See the package gpu command.
GPUs are requested but Kokkos has not been compiled for CUDA
298

LAMMPS Users Manual
Recompile 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 command. You can use -echo screen as a command-line
option when running LAMMPS to see the offending line.
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)
299

LAMMPS Users Manual
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 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 atoms missing on proc %d at step %ld
300

LAMMPS Users Manual
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 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 improper_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 defined.
Improper_style command when no impropers allowed
The chosen atom style does not allow for impropers to be defined.
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.
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 doc page for body style.
Incorrect # of integer values in Bodies section of data file
See doc 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.
301

LAMMPS Users Manual
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.
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 doc 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 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 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 potential 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
302

LAMMPS Users Manual
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 doc 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.
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 whitespace
An end quote must be followed by whitespace.
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
303

LAMMPS Users Manual
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 doesn't contain the
correct magic string at the beginning.
Invalid Masses 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.
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
304

LAMMPS Users Manual
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 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 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 atom/swap command
The atom type specified in the atom/swap command does not exist.
Invalid atom type in fix bond/create command
305

LAMMPS Users Manual
Self-explanatory.
Invalid atom type in fix deposit command
Self-explanatory.
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.
306

LAMMPS Users Manual
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.
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 package
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
307

LAMMPS Users Manual
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 specified dihedral
types.
Invalid dihedral type in dihedrals section of molecule file
Self-explanatory.
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.
308

LAMMPS Users Manual
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 persp value
Persp value must be >= 0.0.
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 specified.
Invalid fix box/relax pressure settings
Settings for coupled dimensions must be the same.
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.
309

LAMMPS Users Manual
Invalid fix rigid/small npt/nph command for a 2d simulation
Cannot control z dimension in a 2d model.
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.
310

LAMMPS Users Manual
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.
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 cannot 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.
311

LAMMPS Users Manual
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 integer.
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.
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
312

LAMMPS Users Manual
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 thru 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
313

LAMMPS Users Manual
Volume must be > 0.0.
Invalid wiggle direction for fix wall/gran
Self-explanatory.
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 neighbor iterator exceeded range
This should not happen. It likely indicates a bug in the KIM implementation of
the interatomic potential where it is requesting neighbors incorrectly.
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 gwald 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 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
314

LAMMPS Users Manual
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.
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
volume.
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 reneighboring.
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
315

LAMMPS Users Manual
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.
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 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 special flags but no bonds
Self-explanatory.
Molecule file needs both Special Bond sections
316

LAMMPS Users Manual
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.
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
317

LAMMPS Users Manual

Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must
Must

Must use an angle_style command before reading a data file that defines Angle
Coeffs.
define angle_style before BondAngle Coeffs
Must use an angle_style command before reading a data file that defines Angle
Coeffs.
define angle_style before BondBond Coeffs
Must use an angle_style command before reading a data file that defines Angle
Coeffs.
define bond_style before Bond Coeffs
Must use a bond_style command before reading a data file that defines Bond
Coeffs.
define dihedral_style before AngleAngleTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines
AngleAngleTorsion Coeffs.
define dihedral_style before AngleTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines
AngleTorsion Coeffs.
define dihedral_style before BondBond13 Coeffs
Must use a dihedral_style command before reading a data file that defines
BondBond13 Coeffs.
define dihedral_style before Dihedral Coeffs
Must use a dihedral_style command before reading a data file that defines
Dihedral Coeffs.
define dihedral_style before EndBondTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines
EndBondTorsion Coeffs.
define dihedral_style before MiddleBondTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines
MiddleBondTorsion Coeffs.
define improper_style before AngleAngle Coeffs
Must use an improper_style command before reading a data file that defines
AngleAngle Coeffs.
define improper_style before Improper Coeffs
Must use an improper_style command before reading a data file that defines
Improper Coeffs.
define pair_style before Pair Coeffs
Must use a pair_style command before reading a data file that defines Pair
Coeffs.
define pair_style before PairIJ Coeffs
Must use a pair_style command before reading a data file that defines PairIJ
Coeffs.
have more than one processor partition to temper
Cannot use the temper command with only one processor partition. Use the
-partition command-line option.
read Atoms before Angles
The Atoms section of a data file must come before an Angles section.
read Atoms before Bodies
The Atoms section of a data file must come before a Bodies section.
read Atoms before Bonds
The Atoms section of a data file must come before a Bonds section.
read Atoms before Dihedrals
318

LAMMPS Users Manual
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 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 USER-OMP package, set the number 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 'kspace_modify pressure/scalar no' for rRESPA with kspace_style MSM
The kspace scalar pressure option 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.
319

LAMMPS Users Manual
Must use a molecular atom style with fix poems molecule
Self-explanatory.
Must use a z-axis cylinder region with fix pour
Self-explanatory.
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 doc 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 command 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
320

LAMMPS Users Manual
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 "extra/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 "extra/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.
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
321

LAMMPS Users Manual
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 requested
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.
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
322

LAMMPS Users Manual
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 Makefile. See Section_start 2.2 of the manual for more details.
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
323

LAMMPS Users Manual
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 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 setting 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.
OFFSET 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
324

LAMMPS Users Manual
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 efficient 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 afer a read_data, read_restart, or
create_box command.
Package cuda command without USER-CUDA package enabled
The USER-CUDA package must be installed via "make yes-user-cuda" before
LAMMPS is built, and the "-c on" must be used to enable the package.
Package gpu command without GPU package installed
The GPU package must be installed via "make yes-gpu" before LAMMPS is built.
Package intel command without USER-INTEL package installed
The USER-INTEL package must be installed via "make yes-user-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 USER-OMP package installed
The USER-OMP package must be installed via "make yes-user-omp" before
LAMMPS is built.
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
325

LAMMPS Users Manual
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
cutoffs.
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 attributes.
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 doesn't 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.
Pair lj/long/dipole/long requires atom attributes mu, torque
326

LAMMPS Users Manual
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 Peridynamic 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 potential.
Pair style BOP requires atom IDs
This is a requirement to use the BOP potential.
Pair style BOP requires newton pair on
327

LAMMPS Users Manual
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 potential.
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.
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 doc 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
328

LAMMPS Users Manual
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 requested 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.
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
329

LAMMPS Users Manual
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 water 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.
Pair style lj/long/tip4p/long requires atom IDs
330

LAMMPS Users Manual

Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair
Pair

There are no atom IDs defined in the system and the TIP4P potential requires
them to find O,H atoms with a water molecule.
style lj/long/tip4p/long requires atom attribute q
The atom style defined does not have these attributes.
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.
style lj/sdk/coul/long/gpu requires atom attribute q
The atom style defined does not have this attribute.
style nb3b/harmonic requires atom IDs
This is a requirement to use this potential.
style nb3b/harmonic requires newton pair on
See the newton command. This is a restriction to use this potential.
style nm/cut/coul/cut requires atom attribute q
The atom style defined does not have this attribute.
style nm/cut/coul/long requires atom attribute q
The atom style defined does not have this attribute.
style peri requires atom style peri
Self-explanatory.
style polymorphic requires atom IDs
This is a requirement to use the polymorphic potential.
style polymorphic requires newton pair on
See the newton command. This is a restriction to use the polymorphic potential.
style reax requires atom IDs
This is a requirement to use the ReaxFF potential.
style reax requires atom attribute q
The atom style defined does not have this attribute.
style reax requires newton pair on
This is a requirement to use the ReaxFF potential.
style requires a KSpace style
No kspace style is defined.
style requires use of kspace_style ewald/disp
Self-explanatory.
style sw/gpu requires atom IDs
This is a requirement to use this potential.
style sw/gpu requires newton pair off
See the newton command. This is a restriction to use this potential.
style vashishta/gpu requires atom IDs
This is a requirement to use this potential.
style vashishta/gpu requires newton pair off
See the newton command. This is a restriction to use this potential.
style tersoff/gpu requires atom IDs
This is a requirement to use the tersoff/gpu potential.
style tersoff/gpu requires newton pair off
See the newton command. This is a restriction to use this pair style.
style tip4p/cut requires atom IDs
This is a requirement to use this potential.
style tip4p/cut requires atom attribute q
The atom style defined does not have this attribute.
style tip4p/cut requires newton pair on
See the newton command. This is a restriction to use this potential.
331

LAMMPS Users Manual
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.
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 setting 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 didn't on this timestep. See the variable doc page for ideas on how to
332

LAMMPS Users Manual
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 didn't on this timestep. See the variable doc 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.
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.
333

LAMMPS Users Manual
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 processors
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.
334

LAMMPS Users Manual
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.
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 isn't 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.
335

LAMMPS Users Manual
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.
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 2nd 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
336

LAMMPS Users Manual
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 doesn't contain a
recognized byte-orderomg 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.
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 restrain 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
337

LAMMPS Users Manual
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 message 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
338

LAMMPS Users Manual
Self-explanatory.
Set command with no atoms existing
No atoms are yet defined so the set command cannot be used.
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
command 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 whenthe 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.
Specified processors != physical processors
339

LAMMPS Users Manual
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 create_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 create_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.
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
340

LAMMPS Users Manual
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.
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.
341

LAMMPS Users Manual
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
342

LAMMPS Users Manual
Self-explanatory.
Thermo fix does not compute scalar
Self-explanatory.
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 requires 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 requires 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
computing this quantity.
Thermo style does not use temp
Cannot use thermo_modify to set this parameter since the thermo_style is not
computing 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 temperature.
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.
Threshhold for an atom property that isn't 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
343

LAMMPS Users Manual

Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too
Too

Table size specified via pair_modify command does not work with your
machine's floating point representation.
few lines in %s section of data file
Self-explanatory.
few values in body lines in data file
Self-explanatory.
few values in body section of molecule file
Self-explanatory.
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.
many MSM grid levels
The max number of MSM grid levels is hardwired to 10.
many args in variable function
More args are used than any variable function allows.
many atom pairs for pair bop
The number of atomic pairs exceeds the expected number. Check your atomic
structure to ensure that it is realistic.
many atom sorting bins
This is likely due to an immense simulation box that has blown up to a large
size.
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.
many atoms for dump dcd
The system size must fit in a 32-bit integer to use this dump style.
many atoms for dump xtc
The system size must fit in a 32-bit integer to use this dump style.
many atoms to dump sort
Cannot sort when running with more than 2^31 atoms.
many exponent bits for lookup table
Table size specified via pair_modify command does not work with your
machine's floating point representation.
many groups
The maximum number of atom groups (including the "all" group) is given by
MAX_GROUP in group.cpp and is 32.
many iterations
You must use a number of iterations that fit in a 32-bit integer for minimization.
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.
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.
many mantissa bits for lookup table
Table size specified via pair_modify command does not work with your
machine's floating point representation.
many masses for fix shake
The fix shake command cannot list more masses than there are atom types.
many molecules for fix poems
The limit is 2^31 = ~2 billion molecules.
344

LAMMPS Users Manual
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.
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.
USER-CUDA mode requires CUDA variant of min style
CUDA mode is enabled, so the min style must include a cuda suffix.
USER-CUDA mode requires CUDA variant of run style
CUDA mode is enabled, so the run style must include a cuda suffix.
USER-CUDA package does not yet support comm_style tiled
Self-explanatory.
USER-CUDA package requires a cuda enabled atom_style
Self-explanatory.
Unable to initialize accelerator for use
There was a problem initializing an accelerator for the gpu package
345

LAMMPS Users Manual
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 end of AngleCoeffs section
Read a blank line.
Unexpected end of BondCoeffs section
Read a blank line.
Unexpected end of DihedralCoeffs section
Read a blank line.
Unexpected end of ImproperCoeffs section
Read a blank line.
Unexpected end of PairCoeffs section
Read a blank line.
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.
Unknown angle style
The choice of angle style is unknown.
Unknown atom style
The choice of atom style is unknown.
Unknown body style
The choice of body style is unknown.
Unknown 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.
Unknown command: %s
The command is not known to LAMMPS. Check the input script.
346

LAMMPS Users Manual
Unknown compute style
The choice of compute style is unknown.
Unknown dihedral style
The choice of dihedral style is unknown.
Unknown dump reader style
The choice of dump reader style via the format keyword is unknown.
Unknown dump style
The choice of dump style is unknown.
Unknown error in GPU library
Self-explanatory.
Unknown fix style
The choice of fix style is unknown.
Unknown identifier in data file: %s
A section of the data file cannot be read by LAMMPS.
Unknown improper style
The choice of improper style is unknown.
Unknown keyword in thermo_style custom command
One or more specified keywords are not recognized.
Unknown 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.
Unknown pair style
The choice of pair style is unknown.
Unknown pair_modify hybrid sub-style
The choice of sub-style is unknown.
Unknown 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 file 1
The lattice type in an entry of the MEAM library file is not valid.
Unrecognized lattice type in MEAM file 2
The lattice type in an entry of the MEAM parameter file is not valid.
Unrecognized pair style in compute pair command
Self-explanatory.
Unrecognized virial argument in pair_style command
Only two options are supported: LAMMPSvirial and KIMvirial
Unsupported mixing rule in kspace_style ewald/disp
347

LAMMPS Users Manual
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 currently supported.
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 velocity 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 required.
Using suffix cuda without USER-CUDA package enabled
Self-explanatory.
Using suffix gpu without GPU package installed
Self-explanatory.
Using suffix intel without USER-INTEL package installed
Self-explanatory.
Using suffix kk without KOKKOS package enabled
Self-explanatory.
Using suffix omp without USER-OMP 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 variable 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
348

LAMMPS Users Manual
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 persp 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.
349

LAMMPS Users Manual
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 persp does not exist
350

LAMMPS Users Manual
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.
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.
351

LAMMPS Users Manual
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 isn't 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.
Velocity temperature ID does not compute temperature
The compute ID given to the velocity command must compute 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.
352

LAMMPS Users Manual
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 didn't on this timestep. See the variable doc 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 doesn't 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.
Warnings:
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
353

LAMMPS Users Manual
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.
Atom style in data file differs from currently defined atom style
Self-explanatory.
Bond atom missing in box size check
The 2nd atoms 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 atom missing in image check
The 2nd 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 2nd 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.
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.
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 associated 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.
Charges did not converge at step %ld: %lg
Self-explanatory.
Communication cutoff is too small for SNAP micro load balancing, increased to %lf
354

LAMMPS Users Manual
Self-explanatory.
Compute cna/atom cutoff may be too large to find ghost atom neighbors
The neighbor cutoff used may not encompass enough ghost atoms to perform
this operation correctly.
Computing temperature of portions of rigid bodies
The group defined by the temperature compute does not encompass 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 neighbor 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.
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 potential 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.
Energy tally does not account for 'zero yes'
The energy removed by using the 'zero yes' flag is not accounted for in the
energy tally and thus energy conservation cannot be monitored in this case.
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 cutoff value may help.
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 SRD walls overlap but fix srd overlap not set
You likely want to set this in your input script.
Fix bond/swap will ignore defined angles
355

LAMMPS Users Manual
See the doc 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 diameter, 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 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.
Fix thermal/conductivity comes before fix ave/spatial
The order of these 2 fixes in your input script is such that fix
thermal/conductivity comes first. If you are using fix ave/spatial to measure the
temperature profile induced by fix viscosity, then this may cause a glitch in the
profile since you are averaging immediately after swaps have occurred. Flipping
the order of the 2 fixes typically helps.
Fix viscosity comes before fix ave/spatial
The order of these 2 fixes in your input script is such that fix viscosity comes
first. If you are using fix ave/spatial to measure the velocity profile induced by
356

LAMMPS Users Manual
fix viscosity, then this may cause a glitch in the profile since you are averaging
immediately after swaps have occurred. Flipping the order of the 2 fixes
typically helps.
Fixes cannot send data in Kokkos communication, switching to classic communication
This is current restriction with Kokkos.
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
computes 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=%d\n
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.
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.
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
357

LAMMPS Users Manual
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.
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 reneighboring.
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
358

LAMMPS Users Manual
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.
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 interactions 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
values. 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 2nd partition performs a kspace calculation so the kspace_style command
must be used.
No automatic unit conversion to XTC file format conventions possible for units lj
This means no scaling will be performed.
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 reax
359

LAMMPS Users Manual
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 USER-OMP
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 immediately 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.
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.
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 desired. 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.
360

LAMMPS Users Manual
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 dimension 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 setting in the restart file.
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
361

LAMMPS Users Manual
See the inside keyword if you want this message 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 relecting walls
LAMMPS allows this, but their dynamics are not computed 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.
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/spatial will be removed in the summer of
2015
Self-explanatory.
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.
362

LAMMPS Users Manual
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 manybody 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 manybody 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.
pair style reax is now deprecated and will soon be retired. Users should switch to
pair_style reax/c
363

LAMMPS Users Manual
Self-explanatory.

364

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS
Commands - Next Section

13. Future and history
This section lists features we plan to add to LAMMPS, features of previous versions of
LAMMPS, and features of other parallel molecular dynamics codes our group has
distributed.
13.1 Coming attractions
13.2 Past versions

13.1 Coming attractions
As of summer 2016 we are using the LAMMPS project issue tracker on GitHub for
keeping track of suggested, planned or pending new features. This includes
discussions of how to best implement them, or why they would be useful. Especially if
a planned or proposed feature is non-trivial to add, e.g. because it requires changes to
some of the core classes of LAMMPS, people planning to contribute a new feature to
LAMMS are encouraged to submit an issue about their planned implementation this
way in order to receive feedback from the LAMMPS core developers. They will provide
suggestions about the validity of the proposed approach and possible improvements,
pitfalls or alternatives.
Please see some of the closed issues for examples of how to suggest code
enhancements, submit proposed changes, or report possible bugs and how they are
resolved.
As an alternative to using GitHub, you may e-mail the core developers or send an
e-mail to the LAMMPS Mail list if you want to have your suggestion added to the list.
13.2 Past versions
LAMMPS development began in the mid 1990s under a cooperative research &
development agreement (CRADA) between two DOE labs (Sandia and LLNL) and 3
companies (Cray, Bristol Myers Squibb, and Dupont). The goal was to develop a
large-scale parallel classical MD code; the coding effort was led by Steve Plimpton at
Sandia.
After the CRADA ended, a final F77 version, LAMMPS 99, was released. As
development of LAMMPS continued at Sandia, its memory management was
converted to F90; a final F90 version was released as LAMMPS 2001.
The current LAMMPS is a rewrite in C++ and was first publicly released as an open
source code in 2004. It includes many new features beyond those in LAMMPS 99 or
2001. It also includes features from older parallel MD codes written at Sandia, namely
ParaDyn, Warp, and GranFlow (see below).

365

LAMMPS Users Manual
In late 2006 we began merging new capabilities into LAMMPS that were developed by
Aidan Thompson at Sandia for his MD code GRASP, which has a parallel framework
similar to LAMMPS. Most notably, these have included many-body potentials Stillinger-Weber, Tersoff, ReaxFF - and the associated charge-equilibration routines
needed for ReaxFF.
The History link on the LAMMPS WWW page gives a timeline of features added to the
C++ open-source version of LAMMPS over the last several years.
These older codes are available for download from the LAMMPS WWW site, except for
Warp & GranFlow which were primarily used internally. A brief listing of their
features is given here.
LAMMPS 2001
• F90 + MPI
• dynamic memory
• spatial-decomposition parallelism
• NVE, NVT, NPT, NPH, rRESPA integrators
• LJ and Coulombic pairwise force fields
• all-atom, united-atom, bead-spring polymer force fields
• CHARMM-compatible force fields
• class 2 force fields
• 3d/2d Ewald & PPPM
• various force and temperature constraints
• SHAKE
• Hessian-free truncated-Newton minimizer
• user-defined diagnostics
LAMMPS 99
• F77 + MPI
• static memory allocation
• spatial-decomposition parallelism
• most of the LAMMPS 2001 features with a few exceptions
• no 2d Ewald & PPPM
• molecular force fields are missing a few CHARMM terms
• no SHAKE
Warp
• F90 + MPI
• spatial-decomposition parallelism
• embedded atom method (EAM) metal potentials + LJ
• lattice and grain-boundary atom creation
• NVE, NVT integrators
• boundary conditions for applying shear stresses
• temperature controls for actively sheared systems
• per-atom energy and centro-symmetry computation and output
ParaDyn
366

LAMMPS Users Manual
• F77 + MPI
• atom- and force-decomposition parallelism
• embedded atom method (EAM) metal potentials
• lattice atom creation
• NVE, NVT, NPT integrators
• all serial DYNAMO features for controls and constraints
GranFlow
• F90 + MPI
• spatial-decomposition parallelism
• frictional granular potentials
• NVE integrator
• boundary conditions for granular flow and packing and walls
• particle insertion

367

LAMMPS Users Manual

Tutorials
The following pages contain some in-depth tutorials for selected topics, that did not fit
into any other place in the manual.

368

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

Using LAMMPS with Bash on Windows
written by Richard Berger
Starting with Windows 10 you can install Linux tools directly in Windows. This allows
you to compile LAMMPS following the same procedure as on a real Ubuntu Linux
installation. Software can be easily installed using the package manager via apt-get
and all files are accessible in both the Windows Explorer and your Linux shell (bash).
This avoids switching to a different operating system or installing a virtual machine.
Everything runs on Windows.
Installing Bash on Windows
Prerequisites

• Windows 10 (64bit only)
• Latest updates installed
Enable developer mode

You enable this feature by first opening Windows Settings and enabling Developer
mode. Go to the Windows settings and search for "developer". This will allow you to
install software which comes from outside of the Windows Store. You might be
prompted to reboot your compute. Please do so.

369

LAMMPS Users Manual

Install Windows Subsystem for Linux

Next you must ensure that the Window Subsystem for Linux is installed. Again, search
for "enable windows features" in the Settings dialog. This opens a dialog with a list of
features you can install. Add a checkmark to Windows Subsystem for Linux (Beta) and
press OK.

370

LAMMPS Users Manual

Install Bash for Windows

After installation completes, type "bash" in the Windows Start menu search. Select the
first found option. This will launch a command-line window which will prompt you
about installing Ubuntu on Windows. Confirm with "y" and press enter. This will then
download Ubuntu for Windows.

371

LAMMPS Users Manual

372

LAMMPS Users Manual

During installation, you will be asked for a new password. This will be used for
installing new software and running commands with sudo.

373

LAMMPS Users Manual

Type exit to close the command-line window.
Go to the Start menu and type "bash" again. This time you will see a "Bash on Ubuntu
on Windows" Icon. Start this program.

374

LAMMPS Users Manual

Congratulations, you have installed Bash on Ubuntu on Windows.

375

LAMMPS Users Manual

Compiling LAMMPS in Bash on Windows
The installation of LAMMPS in this environment is identical to working inside of a real
Ubuntu Linux installation. At the time writing, it uses Ubuntu 16.04.
Installing prerequisite packages

First upgrade all existing packages using
sudo apt update
sudo apt upgrade -y

Next install the following packages, which include compilers and libraries needed for
various LAMMPS features:

sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev lib
Files in Ubuntu on Windows

When you launch "Bash on Ubuntu on Windows" you will start out in your Linux user
home directory /home/username. You can access your Windows user directory using
the /mnt/c/Users/username folder.

376

LAMMPS Users Manual
Download LAMMPS

Obtain a copy of the LAMMPS code and go into it using "cd"
Option 1: Downloading LAMMPS tarball using wget

wget http://lammps.sandia.gov/tars/lammps-stable.tar.gz
tar xvzf lammps-stable.tar.gz
cd lammps-31Mar17
Option 2: Obtaining LAMMPS code from GitHub

git clone https://github.com/lammps/lammps.git
cd lammps
Compiling LAMMPS

At this point you can compile LAMMPS like on Ubuntu Linux.
Compiling serial version

cd src/
make -j 4 serial

This will create an executable called lmp_serial in the src/ directory
Compiling MPI version

cd src/
make -j 4 mpi

This will create an executable called lmp_mpi in the src/ directory
Finally, please note the absolute path of your src folder. You can get this using
pwd

or
echo $PWD

To run any examples you need the location of the executable. For now, let us save this
location in a temporary variable
LAMMPS_DIR=$PWD
Running an example script

Once compiled you can execute some of the LAMMPS examples. Switch into the
examples/melt folder
cd ../examples/melt

377

LAMMPS Users Manual
The full path of the serial executable is $LAMMPS_DIR/lmp_serial, while the mpi
version is $LAMMPS_DIR/lmp_mpi. You can run the melt example with either version
as follows:
$LAMMPS_DIR/lmp_serial -in in.melt

or
mpirun -np 4 $LAMMPS_DIR/lmp_mpi -in in.melt

Note the use of our variable $LAMMPS_DIR, which expands into the full path of the
LAMMPS src folder we saved earlier.
Adding your executable directory to your PATH

You can avoid having to type the full path of your LAMMPS binary by adding its parent
folder to the PATH environment variable as follows:
export PATH=$LAMMPS_DIR:$PATH

Input scripts can then be run like this:
lmp_serial -in in.melt

or
mpirun -np 4 lmp_mpi -in in.melt

However, this PATH variable will not persist if you close your bash window. To persist
this setting edit the $HOME/.bashrc file using your favorite editor and add this line
export PATH=/full/path/to/your/lammps/src:$PATH

Example:
For an executable lmp_serial with a full path
/home/richard/lammps/src/lmp_serial

the PATH variable should be
export PATH=/home/richard/lammps/src:$PATH

NOTE: This should give you a jump start when trying to run LAMMPS on Windows. To
become effective in this environment I encourage you to look into Linux tutorials
explaining Bash and Basic Unix commands (e.g., Linux Journey)

378

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

Tutorial for Thermalized Drude oscillators in LAMMPS
This tutorial explains how to use Drude oscillators in LAMMPS to simulate polarizable
systems using the USER-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 USER-DRUDE package activated. Then, the data file and input
scripts have to be modified to include the Drude dipoles and how to handle them.
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, \(m_C + m_D = m\). The sum of their charges should be the charge of the initial
(unsplit) atom, \(q_C + q_D = q\). A harmonic potential between the core and Drude
partners should be present, with force constant \(k_D\) and an equilibrium distance of
zero. The (half-)stiffness of the harmonic bond \(K_D = k_D/2\) and the Drude charge
\(q_D\) are related to the atom polarizability \(\alpha\) by
\begin{equation} K_D = \frac 1 2\, \frac {q_D^2} \alpha \end{equation}
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 ot 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:
• Lamoureux and Roux suggest adopting a global half-stiffness, \(K_D\) = 500
kcal/(mol Ang \({}^2\)) - which corresponds to a force constant \(k_D\) = 4184
kJ/(mol Ang \({}^2\)) - for all types of core-Drude bond, a global mass \(m_D\) =
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 \(q_D\)
= -1.0e and a global mass \(m_D\) = 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
379

LAMMPS Users Manual
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 remediate
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 USER-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
OH
0.4
-1.0
4184.0
0.63
CA
0.4
-1.0
4184.0
1.36
CAI
0.4
-1.0
4184.0
1.09

thole
0.67
2.51
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
380

LAMMPS Users Manual
of lines of the Masses section. You probably need to edit it to add these names. It
should look like
Masses
1
2
3
4
5

12.011
12.011
15.999
1.008
1.008

#
#
#
#
#

CAI
CA
OH
HA
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 epsilon is 0. so the only
pair_coeff line that needs to be added is
pair_coeff * 6* 0.0 0.0 # All-DPs

381

LAMMPS Users Manual
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 thermostate the
DPs together with their DC. For this, ghost atoms need to know their velocities. Thus
you need to add the following command:
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

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]

382

LAMMPS Users Manual
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
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
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff

1
1
1
1
2
2
2
3
3
4
*
*
1
1
1
1
1
1
2
2
2
2
2
3
3
3
3
6
6
6

1
2
3
4
2
3
4
3
4
4
5
6*
1
2
3
6
7
8
2
3
6
7
8
3
6
7
8
6
7
8

lj/cut/coul/long
0.0700
lj/cut/coul/long
0.0700
lj/cut/coul/long
0.1091
lj/cut/coul/long
0.0458
lj/cut/coul/long
0.0700
lj/cut/coul/long
0.1091
lj/cut/coul/long
0.0458
lj/cut/coul/long
0.1700
lj/cut/coul/long
0.0714
lj/cut/coul/long
0.0300
lj/cut/coul/long
0.0000
lj/cut/coul/long
0.0000
thole
1.090
2.510
thole
1.218
2.510
thole
0.829
1.590
thole
1.090
2.510
thole
1.218
2.510
thole
0.829
1.590
thole
1.360
2.510
thole
0.926
1.590
thole
1.218
2.510
thole
1.360
2.510
thole
0.926
1.590
thole
0.630
0.670
thole
0.829
1.590
thole
0.926
1.590
thole
0.630
0.670
thole
1.090
2.510
thole
1.218
2.510
thole
0.829
1.590

3.550
3.550
3.310
2.985
3.550
3.310
2.985
3.070
2.745
2.420
0.000
0.000

383

LAMMPS Users Manual
pair_coeff
pair_coeff
pair_coeff

7
7
8

7 thole
8 thole
8 thole

1.360
0.926
0.630

2.510
1.590
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 special_bonds command (0.0, 0.0, and 0.5 in the example
above). Without using the pair_style thole, dipole-dipole interactions 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 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 intergation 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
fix
fix
fix

DIRECT all drude/transform/direct
NVT1 ATOMS nvt temp 300. 300. 100
NVT2 DRUDES nvt temp 1. 1. 20
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). To avoid the
flying ice cube artifact (Lamoureux), 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:
384

LAMMPS Users Manual
fix MOMENTUM all momentum 100 linear 1 1 1

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 thermostating and
barostating 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

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
fix
fix
fix

DIRECT all drude/transform/direct
RIGID ATOMS rigid/nvt/small molecule temp 300. 300. 100
NVT DRUDES nvt temp 1. 1. 20
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

385

LAMMPS Users Manual
(Lamoureux) 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).
(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)

386

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

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 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 Section 10.15
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.

387

LAMMPS Users Manual

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:
$ git clone https://github.com/

or, if you have set up your GitHub account for using SSH keys, via SSH:
$ git clone git@github.com:

You can find the proper URL by clicking the "Clone or download"-button:

388

LAMMPS Users Manual

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
389

LAMMPS Users Manual
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/tutorial_github.txt
$ git add doc/src/JPG/tutorial*.png

IMPORTANT NOTE: Do not use git commit -a (or git add -A). The -a flag (or -A flag)
will automatically include _all_ modified or 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 git@github.com: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
390

LAMMPS Users Manual
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.
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.

391

LAMMPS Users Manual

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):

392

LAMMPS Users Manual
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".

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:

393

LAMMPS Users Manual

If all is fine, you will see this:

394

LAMMPS Users Manual

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.
Assignees
There is an assignee label 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)
395

LAMMPS Users Manual
Steve Plimpton (sjplimp).
• 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 lead developer
Steve Plimpton and means it is considered ready for merging.
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,
396

LAMMPS Users Manual
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:

For some reason, the highlighted button didn't work in my case, but I can go to my
own repository and merge the pull request from there:

397

LAMMPS Users Manual

Be sure to check the changes to see if you agree with them by clicking on the tab
button:

398

LAMMPS Users Manual

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.

399

LAMMPS Users Manual

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:

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:

400

LAMMPS Users Manual
$
$
$
$

git
git
git
git

add tutorial_github.txt
add JPG/tutorial_reverse_pull_request*.png
commit -m "Updated text and images on reverse pull requests"
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
git
git
git

add tutorial_github.txt
add JPG/tutorial_reverse_pull_request6.png
commit -m "Merged Axel's suggestions and updated text"
push git@github.com:Pakketeretet2/lammps

This merge also shows up on the lammps Github page:

After a merge
When everything is fine, the feature branch is merged into the master branch:

401

LAMMPS Users Manual
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_" 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.

402

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

PyLammps Tutorial
Overview
PyLammps is a Python wrapper class which can be created on its own or use an
existing lammps Python object. It creates a simpler, Python-like interface to common
LAMMPS functionality. Unlike the original flat C-types interface, it exposes a
discoverable API. It no longer requires knowledge of the underlying C++ code
implementation. Finally, the IPyLammps wrapper builds on top of PyLammps and adds
some additional features for IPython integration into IPython notebooks, e.g. for
embedded visualization output from dump/image.
Comparison of lammps and PyLammps interfaces
lammps.lammps

• uses C-Types
• 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)
lammps.PyLammps

• higher-level abstraction built on top of original C-Types 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.
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" JP

403

LAMMPS Users Manual
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.
cd $LAMMPS_DIR/python
python install.py

NOTE: Recompiling the shared library requires reinstalling the Python package
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 name 'testing'
# activate 'testing' environment
source testing/bin/activate
# install LAMMPS package in virtualenv
(testing) cd $LAMMPS_DIR/python
(testing) python install.py
# install other useful packages
(testing) pip install matplotlib jupyter mpi4py
...
# return to original shell
(testing) deactivate

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 constructor, a new lammps instance is created.
from lammps import PyLammps
L = PyLammps()

404

LAMMPS Users Manual
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 whitespace, 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 whitespace.
The benefit of this approach is avoiding redundant command calls and easier
parameterization. In the original interface parametrization 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)

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
405

LAMMPS Users Manual
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")

406

LAMMPS Users Manual
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 trajectories 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].step # list of time steps in first run
L.runs[0].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].step
ke
= L.runs[0].ke
plt.plot(steps, ke)

Error handling with PyLammps
Compiling the shared library with C++ exception support provides a better error
handling experience. Without exceptions the LAMMPS code will terminate the current
407

LAMMPS Users Manual
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.
IMPORTANT NOTE: 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
subdirectory. 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 harmonic 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
408

LAMMPS Users Manual
other using matplotlib, which embeds the generated plot inside the IPython notebook.

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

LAMMPS Users Manual

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)

410

LAMMPS Users Manual

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]
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")

411

LAMMPS Users Manual
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.

412

LAMMPS Users Manual
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"))
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

IMPORTANT NOTE: 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 (richard.berger@temple.edu). We also want to
encourage people to write tutorial style IPython notebooks showcasing LAMMPS
usage and maybe their latest research results.

413

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

414

Body particles
Overview:
This doc page is not about a LAMMPS input script command, but about body particles,
which 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 that body particles. See
Section 6.14 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 convex polygon with N vertices
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.
NOTE: The rounded/polygon style listed in the table above and described below has
not yet been relesed in LAMMPS. It will be soon.
We hope to add more styles in the future. See Section 10.12 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, outputting 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.
Thus it only makes sense to use body particles and develop such a pair style, when
415

LAMMPS Users Manual
particle/particle interactions are more complex than what the fix rigid command can
already calculate. For example, if particles have 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
then the interaction between pairs of particles is likely to be more complex than the
summation of simple sub-particle interactions. An example is contact or frictional
forces between particles with planar surfaces that inter-penetrate.
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

416

LAMMPS Users Manual
...
xN yN zN

N is the number of sub-particles in the body particle. M = 6 + 3*N. 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 command can be used with this body style to compute body/body
and body/non-body interactions.
For output purposes via the compute body/local and dump local commands, this body
style produces one datum for each of the N sub-particles in a body particle. The datum
has 3 values:
1 = x position of sub-particle
2 = y position of sub-particle
3 = z position of sub-particle

These values are the current position of the sub-particle 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.
For images created by the dump image command, if the body keyword is set, then
each body particle 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.
Specifics of body style rounded/polygon:
NOTE: Aug 2016 - This body style has not yet been added to LAMMPS. The info below
is a placeholder.
The rounded/polygon body style represents body particles as a convex polygon with a
variable number N > 2 of vertices, which can only be used for 2d models. One
example 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

417

LAMMPS Users Manual
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
i j j k k ...
radius

N is the number of vertices in the body particle. M = 6 + 3*N + 2*N + 1. 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, followed by 2N vertex
indices corresponding to the end points of the N edges, followed by a single radius
value = the smallest circle encompassing the polygon. That last value is used to
facilitate the body/body contact detection. These floating-point 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 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 particles whose edge
length is sqrt(2):
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
0 1 1 2 2 3 3 0
1.0

The pair_style body/rounded/polygon command can be used with this body style to
compute body/body interactions.
For output purposes via the compute body/local and dump local commands, this body
style produces one datum for each of the N sub-particles in a body particle. The datum
has 3 values:
1 = x position of vertex
2 = y position of vertex
3 = z position of vertex

418

LAMMPS Users Manual
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.
For images created by the dump image command, if the body keyword is set, then
each body particle is drawn as a convex polygon consisting of N line segments. Note
that the line segments are drawn between the N vertices, which does not correspond
exactly to the physical extent of the body (because the pair_style rounded/polygon
defines finite-size spheres at those point and the line segments between the spheres
are tangent to the spheres). The drawn diameter of each line segment is determined
by the bflag1 parameter for the body keyword. The bflag2 argument is ignored.

(Fraige) F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds, Particuology, 6, 455
(2008).

419

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

420

Manifolds (surfaces)
Overview:
This doc page is not about a LAMMPS input script command, but about manifolds,
which are generalized surfaces, as defined and used by the USER-MANIFOLD
package, to track particle motion on the manifolds. See the
src/USER-MANIFOLD/README file for more details about the package and its
commands.
Below is a list of currently supported manifolds by the USER-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.
manifold

parameters equation

cylinder

R

cylinder_dent

Rla

dumbbell

aABc

ellipsoid

abc

gaussian_bump A l rc1 rc2

x^2 + y^2 - R^2 = 0
x^2 + y^2 - r(z)^2 = 0, r(x) =
R if | z | > l, r(z) = R - a*(1 +
cos(z/l))/2 otherwise
-( x^2 + y^2 ) + (a^2 z^2/c^2) * ( 1 +
(A*sin(B*z^2))^4) = 0
(x/a)^2 + (y/b)^2 + (z/c)^2 =
0
if( x < rc1) -z + A * exp( -x^2 /
(2 l^2) ); else if( x < rc2 ) -z +
a + b*x + c*x^2 + d*x^3; else
z

plane

a b c x0 y0
z0

a*(x-x0) + b*(y-y0) + c*(z-z0)
=0

plane_wiggle

aw

z - a*sin(w*x) = 0

sphere

R

supersphere

spine

spine_two

x^2 + y^2 + z^2 - R^2 = 0
| x |^q + | y |^q + | z |^q Rq
R^q = 0
-(x^2 + y^2) + (a^2 z^2/f(z)^2)*(1 +
a, A, B, B2,
(A*sin(g(z)*z^2))^4), f(z) = c
c
if z > 0, 1 otherwise; g(z) = B
if z > 0, B2 otherwise
a, A, B, B2, -(x^2 + y^2) + (a^2 c
z^2/f(z)^2)*(1 +
(A*sin(g(z)*z^2))^2), f(z) = c
if z > 0, 1 otherwise; g(z) = B

description
Cylinder along z-axis,
axis going through
(0,0,0)
A cylinder with a dent
around z = 0
A dumbbell
An ellipsoid
A Gaussian bump at x =
y = 0, smoothly tapered
to a flat plane z = 0.
A plane with normal
(a,b,c) going through
point (x0,y0,z0)
A plane with a sinusoidal
modulation on z along x.
A sphere of radius R
A supersphere of
hyperradius R
An approximation to a
dendtritic spine
Another approximation to
a dendtritic spine

421

LAMMPS Users Manual
if z > 0, B2 otherwise

thylakoid

wB LB lB

Various, see (Paquay)

torus

Rr

(R - sqrt( x^2 + y^2 ) )^2 +
z^2 - r^2

A model grana thylakoid
consisting of two
block-like compartments
connected by a bridge of
width wB, length LB and
taper length lB
A torus with large radius
R and small radius r,
centered on (0,0,0)

(Paquay) Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at
arXiv:1411.3019.

422

LAMMPS Commands
The following pages contain the detailed documentation of all LAMMPS commands
included in this version of LAMMPS. Generic commands are listed first (in
alphabetical order) followed by command categories like compute styles or pair styles
and so on.
The documentation for the USER-ATC package fix_modify commands follow at the
very end of this manual.

423

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

angle_coeff command
Syntax:
angle_coeff N args

• N = angle type (see asterisk form below)
• args = coefficients for one or more angle types
Examples:
angle_coeff 1 300.0 107.0
angle_coeff * 5.0
angle_coeff 2*10 5.0

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
1st 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 1st example above would be listed as
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.
Here is an alphabetic list of angle styles defined in LAMMPS. Click on the style to
424

LAMMPS Users Manual
display the formula it computes and coefficients specified by the associated
angle_coeff command.
Note that there are also additional angle styles submitted by users which are included
in the LAMMPS distribution. The list of these with links to the individual styles are
given in the angle section of this page.
• angle_style none - turn off angle interactions
• angle_style hybrid - define multiple styles of angle interactions
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style

charmm - CHARMM angle
class2 - COMPASS (class 2) angle
cosine - cosine angle potential
cosine/delta - difference of cosines angle potential
cosine/periodic - DREIDING angle
cosine/squared - cosine squared angle potential
harmonic - harmonic angle
table - tabulated by angle

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.
Related commands:
angle_style
Default: none

425

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

angle_style command
Syntax:
angle_style style

• style = none or hybrid or charmm or class2 or cosine or cosine/squared or
harmonic
Examples:
angle_style harmonic
angle_style charmm
angle_style hybrid harmonic cosine

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 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 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.
Note that there are also additional angle styles submitted by users which are included
in the LAMMPS distribution. The list of these with links to the individual styles are
given in the angle section of this page.
• angle_style none - turn off angle interactions
426

LAMMPS Users Manual
• angle_style zero - topology but no interactions
• angle_style hybrid - define multiple styles of angle interactions
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style
• angle_style

charmm - CHARMM angle
class2 - COMPASS (class 2) angle
cosine - cosine angle potential
cosine/delta - difference of cosines angle potential
cosine/periodic - DREIDING angle
cosine/squared - cosine squared angle potential
harmonic - harmonic angle
table - tabulated by angle

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 Making LAMMPS section for more info
on packages. The doc pages for individual bond potentials tell if it is part of a package.
Related commands:
angle_coeff
Default:
angle_style none

427

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

atom_modify command
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)

Examples:
atom_modify map yes
atom_modify map hash sort 10000 2.0
atom_modify first colloid

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 in Section 2.2 of the manual. 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
428

LAMMPS Users Manual
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 descibed 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 atom-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.
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,
429

LAMMPS Users Manual
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.
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".
Related commands: none
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.

(Meloni) Meloni, Rosati and Colombo, J Chem Phys, 126, 121102 (2007).

430

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

atom_style command
Syntax:
atom_style style args

• style = angle or atomic or body or bond or charge or dipole or dpd or edpd or
mdpd or tdpd or electron or ellipsoid or full or line or meso or molecular or peri
or smd or sphere 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 body doc page for details
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
Examples:
atom_style
atom_style
atom_style
atom_style
atom_style
atom_style
atom_style
atom_style

atomic
bond
full
body nparticle 2 10
hybrid charge bond
hybrid charge body nparticle 2 5
template myMols
tdpd 2

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.
The choice of style affects what quantities are stored by each atom, what quantities
are communicated between processors to enable forces to be computed, and what
quantities are listed in the data file read by the read_data command.
431

LAMMPS Users Manual
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

atomic

only the default values

bond
charge
dipole
dpd
edpd
mdpd
tdpd
electron
ellipsoid
full
line
meso
molecular

mass, inertia moments, quaternion,
angular momentum
bonds
charge
charge and dipole moment
internal temperature and internal energies
temperature and heat capacity
density
chemical concentration
charge and spin and eradius
shape, quaternion, angular momentum
molecular + charge
end points, angular velocity
rho, e, cv
bonds, angles, dihedrals, impropers

peri

mass, volume

body

smd
sphere

volume, kernel diameter, contact radius,
mass
diameter, mass, angular velocity

bead-spring polymers with
stiffness
coarse-grain liquids, solids,
metals
arbitrary bodies
bead-spring polymers
atomic system with charges
system with dipolar particles
DPD particles
eDPD particles
mDPD particles
tDPD particles
electronic force field
aspherical particles
bio-molecules
rigid bodies
SPH particles
uncharged molecules
mesocopic Peridynamic
models
solid and fluid SPH particles

granular models
small molecules with fixed
template
template index, template atom
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 doc 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
Section 6.14 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.
432

LAMMPS Users Manual
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.
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 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 dpd style is for dissipative particle dynamics (DPD) particles. Note that it is part
of the USER-DPD 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 considering 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 meso style is for smoothed particle hydrodynamics (SPH) particles which store a
density (rho), energy (e), 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.

433

LAMMPS Users Manual
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 (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.
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 body doc 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 command. These arguments are described in the
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.
434

LAMMPS Users Manual
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 this
section.
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 Section 5 of the manual. 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,
USER-INTEL, USER-OMP, 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 Making LAMMPS section 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 Section 5 of the manual for more instructions on how to use the accelerated styles
effectively.
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 Making LAMMPS section 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.
435

LAMMPS Users Manual
The electron style is part of the USER-EFF package for electronic force fields.
The dpd style is part of the USER-DPD package for dissipative particle dynamics
(DPD).
The edpd, mdpd, and tdpd styles are part of the USER-MESO package for
energy-conserving dissipative particle dynamics (eDPD), many-body dissipative
particle dynamics (mDPD), and transport dissipative particle dynamics (tDPD),
respectively.
The meso style is part of the USER-SPH package for smoothed particle hydrodynamics
(SPH). See this PDF guide to using SPH in LAMMPS.
The wavepacket style is part of the USER-AWPMD package for the antisymmetrized
wave packet MD method.
Related commands:
read_data, pair_style
Default:
atom_style atomic

(Grime) Grime and Voth, to appear in J Chem Theory & Computation (2014).

436

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

balance command
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
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 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 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 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
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshold is reached
rcb args = none

x dimension

y dimension

z dimension
than once

• 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 com
name = atom property name (without d_ prefix)
out arg = filename
filename = write each processor's sub-domain to a file

Examples:
balance
balance
balance
balance
balance
balance

0.9
1.2
1.0
1.1
1.0
1.0

x uniform y 0.4 0.5 0.6
shift xz 5 1.1
shift xz 5 1.1
rcb
shift x 10 1.1 weight group 2 fast 0.5 slow 2.0
shift x 10 1.1 weight time 0.8 weight neigh 0.5 weight store balance

437

LAMMPS Users Manual
balance 1.0 shift x 20 1.0 out tmp.balance

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
438

LAMMPS Users Manual
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 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.

439

LAMMPS Users Manual

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

440

LAMMPS Users Manual
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". Eacn 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 rebalance 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.
Once the rebalancing is complete and final processor sub-domains assigned, particles
are migrated to their new owning processor, and the balance procedure ends.
NOTE: At each rebalance 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 ot 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
441

LAMMPS Users Manual
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 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.
442

LAMMPS Users Manual
This weight style is useful in combination with pair style hybrid, e.g. when combining
a more costly manybody 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 neighbors 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 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
443

LAMMPS Users Manual
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 property specified by name. This must be a
property defined as d_name via the fix property/atom command. Note that these
custom per-atom properties can be output in a dump file, so this is a way to examine,
debug, or visualize the per-particle weights computed during the load-balancing
operation.
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
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

444

LAMMPS Users Manual
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".
Restrictions:
For 2d simulations, the z style cannot be used. Nor can a "z" appear in dimstr for the
shift style.
Related commands:
group, processors, fix balance
Default: none

445

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

bond_coeff command
Syntax:
bond_coeff N args

• N = bond type (see asterisk form below)
• args = coefficients for one or more bond types
Examples:
bond_coeff
bond_coeff
bond_coeff
bond_coeff

5 80.0 1.2
* 30.0 1.5 1.0 1.0
1*4 30.0 1.5 1.0 1.0
1 harmonic 200.0 1.0

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
1st 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 1st example above would be listed as
5 80.0 1.2

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.

446

LAMMPS Users Manual
Note that here are also additional bond styles submitted by users which are included
in the LAMMPS distribution. The list of these with links to the individual styles are
given in the bond section of this page.
• bond_style none - turn off bonded interactions
• bond_style hybrid - define multiple styles of bond interactions
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style

class2 - COMPASS (class 2) bond
fene - FENE (finite-extensible non-linear elastic) bond
fene/expand - FENE bonds with variable size particles
harmonic - harmonic bond
morse - Morse bond
nonlinear - nonlinear bond
quartic - breakable quartic bond
table - tabulated by bond length

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.
Related commands:
bond_style
Default: none

447

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

bond_style command
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

Examples:
bond_style harmonic
bond_style fene
bond_style hybrid harmonic fene

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

448

LAMMPS Users Manual
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.
Note that there are also additional bond styles submitted by users which are included
in the LAMMPS distribution. The list of these with links to the individual styles are
given in the bond section of this page.
• bond_style none - turn off bonded interactions
• bond_style zero - topology but no interactions
• bond_style hybrid - define multiple styles of bond interactions
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style
• bond_style

class2 - COMPASS (class 2) bond
fene - FENE (finite-extensible non-linear elastic) bond
fene/expand - FENE bonds with variable size particles
harmonic - harmonic bond
morse - Morse bond
nonlinear - nonlinear bond
quartic - breakable quartic bond
table - tabulated by bond length

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 Making LAMMPS section for more info
on packages. The doc pages for individual bond potentials tell if it is part of a package.
Related commands:
bond_coeff, delete_bonds
Default:
bond_style none

449

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

bond_write command
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)
•
Examples:
bond_write 1 500 0.5 3.5 table.txt Harmonic_1
bond_write 3 1000 0.1 6.0 table.txt Morse

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 (in force units).
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.
Related commands:
bond_style table, bond_style, bond_coeff
Default: none
450

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

boundary command
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

Examples:
boundary p p f
boundary p fs p
boundary s f fm

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 matter 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).
451

LAMMPS Users Manual
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 2nd dimension of a tilt factor
(e.g. y for xy) is periodic, then the periodicity is enforced with the tilt factor offset. If
the 1st 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 Section 6.12 of the doc pages for a geometric description of triclinic boxes, as
defined by LAMMPS, and how to transform these parameters to and from other
commonly used triclinic representations.
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.
Related commands:
See the thermo_modify command for a discussion of lost atoms.
Default:
boundary p p p

452

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

box command
Syntax:
box keyword value ...

• one or more keyword/value pairs may be appended
• keyword = tilt
tilt value = small or large

Examples:
box tilt large
box tilt small

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 this section of
the manual 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 1st 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.
Restrictions:
This command cannot be used after the simulation box is defined by a read_data or
create_box command or read_restart command.
Related commands: none
Default:
The default value is tilt = small.

453

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

change_box command
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 re
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

• 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

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

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
454

LAMMPS Users Manual
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 Section 6.12 of the doc pages for a geometric description of triclinic boxes, as
defined by LAMMPS, and how to transform 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 command) 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 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.
455

LAMMPS Users Manual
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.
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 this 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.
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

456

LAMMPS Users Manual
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.
457

LAMMPS Users Manual
The ortho and triclinic keywords convert the simulation box to be orthogonal or
triclinic (non-orthogonal). See this section for a discussion of how non-orthogonal
boxes are represented in LAMMPS.
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.
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.
Related commands:
458

LAMMPS Users Manual
fix deform, boundary
Default:
The option default is units = lattice.

459

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

clear command
Syntax:
clear

Examples:
(commands for 1st simulation)
clear
(commands for 2nd simulation)

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 command), echo status (echo command), and input
script variables (variable command).
Restrictions: none
Related commands: none
Default: none

460

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

comm_modify command
Syntax:
comm_modify keyword value ...

• zero or more keyword/value pairs may be appended
• keyword = mode or cutoff or cutoff/multi or group or vel
mode value = single or multi = communicate atoms within a single or multiple distances
cutoff value = Rcut (distance units) = communicate atoms from this far away
cutoff/multi type value
type = atom type or type range (supports asterisk notation)
value = Rcut (distance units) = communicate atoms for selected types from this far
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

Examples:
comm_modify
comm_modify
comm_modift
comm_modify
comm_modify
comm_modify

mode multi
mode multi group solvent
mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0
vel yes
mode single cutoff 5.0 vel yes
cutoff/multi * 0.0

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 command, all communication settings are restored to their default values,
including those previously reset by a comm_modify command. Thus if your input script
specifies a comm_style 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.
For many systems this is an efficient algorithm, but for systems with widely varying
cutoffs for different type pairs, the multi mode can be faster. In this case, each atom
type is assigned its own distance cutoff for communication purposes, and fewer atoms
will be communicated. See the neighbor multi command for a neighbor list
construction option that may also be beneficial for simulations of this kind.

461

LAMMPS Users Manual
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 and the ghost cutoff is set to the neighbor
cutoff. Specifying a cutoff value of 0.0 will reset any previous value to the default.
The cutoff/multi option is equivalent to cutoff, but applies to communication mode
multi instead. Since in this case the communication cutoffs are determined per atom
type, a type specifier is needed and cutoff for one or multiple types can be extended.
Also ranges of types using the usual asterisk notation can be given.
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 multibody 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 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
462

LAMMPS Users Manual
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).
Restrictions:
Communication mode multi is currently only available for comm_style brick.
Related commands:
comm_style, neighbor
Default:
The option defauls 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.

463

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

comm_style command
Syntax:
comm_style style

• style = brick or tiled
Examples:
comm_style brick
comm_style tiled

Description:
This command sets the style of 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.
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 decomposition. 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.
Restrictions: none
Related commands:
comm_modify, processors, balance, fix balance
Default:
The default style is brick.

464

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

compute command
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
Examples:
compute 1 all temp
compute newtemp flow temp/partial 1 1 0
compute 3 all ke/atom

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 this howto
section 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 produces either global or per-atom or local quantities, but
never more than one of these (with only a few exceptions, as documented by
individual compute commands).
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
465

LAMMPS Users Manual
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.
• 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 doc 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

466

LAMMPS Users Manual
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 this section of the manual) and
the results of their calculations accessed in the various ways described above.
Each compute style has its own doc page which describes its arguments and what it
does. Here is an alphabetic list of compute styles available in LAMMPS. They are also
given in more compact form in the Compute section of this page.
There are also additional compute styles (not listed here) submitted by users which
are included in the LAMMPS distribution. The list of these with links to the individual
styles are given in the compute section of this page.
• aggregate/atom - aggregate ID for each atom
• angle/local - theta and energy of each angle
• angmom/chunk - angular momentum for each chunk
• body/local - attributes of body sub-particles
• bond - values computed by a bond style
• bond/local - distance and energy of each bond
• centro/atom - centro-symmetry parameter for each atom
• chunk/atom - assign chunk IDs to each atom
• cluster/atom - cluster ID for each atom
• cna/atom - common neighbor analysis (CNA) 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/local - angle of each dihedral
• dilatation/atom - Peridynamic dilatation for each atom
• displace/atom - displacement of each atom
• erotate/asphere - rotational energy of aspherical particles
• erotate/rigid - rotational energy of rigid bodies
• erotate/sphere - rotational energy of spherical particles
467

LAMMPS Users Manual
• erotate/sphere/atom - rotational energy for each spherical particle
• event/displace - detect event on atom displacement
• fragment/atom - fragment ID for each 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
• heat/flux - heat flux through a group of atoms
• hexorder/atom - bond orientational order parameter q6
• 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/rigid - translational kinetic energy of rigid bodies
• 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
• plasticity/atom - Peridynamic plasticity for each atom
• pressure - total pressure and pressure tensor
• property/atom - convert atom attributes to per-atom vectors/arrays
• property/local - convert local attributes to localvectors/arrays
• property/chunk - extract various per-chunk attributes
• rdf - radial distribution function g(r) histogram of group of atoms
• reduce - combine per-atom quantities into a single global value
• reduce/region - same as compute reduce, within a region
• rigid/local - extract rigid body attributes
• slice - extract values from global vector or array
• sna/atom - calculate bispectrum coefficients for each atom
• snad/atom - derivative of bispectrum coefficients for each atom
• snav/atom - virial contribution from bispectrum coefficients for each atom
• stress/atom - stress tensor for each atom
• 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/deform - temperature excluding box deformation velocity
• 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/sphere - temperature of spherical particles
• ti - thermodynamic integration free energy values
• torque/chunk - torque applied on each chunk
• vacf - velocity-autocorrelation function of group of atoms
• vcm/chunk - velocity of center-of-mass for each chunk
468

LAMMPS Users Manual
• voronoi/atom - Voronoi volume and neighbors for each atom
There are also additional compute styles submitted by users which are included in the
LAMMPS distribution. The list of these with links to the individual styles are given in
the compute section of this page.
There are also additional accelerated compute styles included in the LAMMPS
distribution for faster performance on CPUs and GPUs. The list of these with links to
the individual styles are given in the pair section of this page.
Restrictions: none
Related commands:
uncompute, compute_modify, fix ave/atom, fix ave/time, fix ave/histo
Default: none

469

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

compute_modify command
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 recompute the number of degrees of freedom (DOF) contributing
dynamic syntax is identical to dynamic/dof, will be disabled at some point

Examples:
compute_modify myTemp extra/dof 0
compute_modify newtemp dynamic/dof yes extra/dof 600

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 normalizing 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 momentum. 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.
Restrictions: none
470

LAMMPS Users Manual
Related commands:
compute
Default:
The option defaults are extra/dof = 2 or 3 for 2d or 3d systems and dynamic/dof = no.

471

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

create_atoms command
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
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 remap or var or set 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
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

Examples:
create_atoms
create_atoms
create_atoms
create_atoms

1
3
3
1

box
region regsphere basis 2 3
single 0 0 5
box var v set x xpos set y ypos

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
472

LAMMPS Users Manual
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 simulation box is periodic, you should insure its size is
a multiple of the lattice spacings, to avoid unwanted atom overlaps 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
473

LAMMPS Users Manual
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 doc 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
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 doesn't 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
474

LAMMPS Users Manual
unit cell of the lattice. By default, all created atoms are assigned the argument type as
their atom type.
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. Click on the
image for a larger version.
dimension
variable
variable
lattice
region
create_box

2
x equal 100
y equal 25
hex 0.8442
box block 0 $x 0 $y -0.5 0.5
1 box

variable
variable
variable
create_atoms
write_dump

xx internal 0.0
yy internal 0.0
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)
1 box var v set x xx set y yy
all atom sinusoid.lammpstrj

475

LAMMPS Users Manual

The rotate keyword can only be used with the single style and when adding a single
molecule. It allows to specify the orientation at which the molecule is 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. When a simulation is
performed on different numbers of processors, there is no guarantee a particular
created atom will be assigned the same ID. 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
• angular momentum = 0.0 0.0 0.0
• quaternion = (1,0,0,0)
• bonds, angles, dihedrals, impropers = none

476

LAMMPS Users Manual
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.
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.
Related commands:
lattice, region, create_box, read_data, read_restart
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.

477

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

create_bonds command
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
single/angle args = atype aatom1 aatom2 aatom3
atype = bond type of new angle
aatom1,aatom2,aatom3 = atom IDs for three atoms in angle
single/dihedral args = dtype datom1 datom2 datom3 datom4
dtype = bond type of new dihedral
datom1,datom2,datom3,datom4 = atom IDs for four atoms in dihedral

• zero or more keyword/value pairs may be appended
• keyword = special
special value = yes or no

Examples:
create_bonds many all all 1 1.0 1.2
create_bonds many surf solvent 3 2.0 2.4
create_bond single/bond 1 1 2
create_bond single/angle 5 52 98 107 special no

Description:
Create bonds between pairs of atoms that meet a specified distance criteria. Or
create a single bond, angle, or dihedral between 2, 3, or 4 specified atoms.
The new bond (angle, dihedral) interactions will then be computed during a
simulation by the bond (angle, dihedral) potential defined by the bond_style,
bond_coeff, angle_style, angle_coeff, dihedral_style, dihedral_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 to a system
incrementally, then continuing a simulation.

478

LAMMPS Users Manual
Note that this command does not auto-create any angle or dihedral interactions
when a bond is added. Nor does it auto-create any bonds when an angle or dihedral
is added. Or auto-create any angles when a dihedral 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 dihedral that would normally be defined in a data file for a complex system
of molecules.
NOTE: If the system has no bonds (angles, dihedrals) 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 and dihedrals. Otherwise an error may occur
when too many bonds (angles, dihedrals) 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 and dihedrals. See the doc pages for these 2 commands for details.
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.
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 Coulombic interactions via the kspace_style command for
your subsequent simulation.
479

LAMMPS Users Manual
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 btype between two atoms
with IDs batom1 and batom2. 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 keyword special controls whether an internal list of special bonds is created
after one or more bonds, or a single angle or dihedral is added to the system.
The default value is yes. A value of no cannot be used with the many style.
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) is added:
create_bonds
create_bonds
...
create_bonds
create_bonds

single/bond 5 52 98 special no
single/bond 5 73 74 special no
single/bond 5 17 386 special no
single/bond 4 112 183 special yes

Note that you MUST insure the internal list is re-built after the last bond (angle,
dihedral) 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.
Restrictions:
This command cannot be used with molecular systems defined using molecule
template files via the molecule and atom_style template commands.
Related commands:
create_atoms, delete_bonds

480

LAMMPS Users Manual
Default:
The keyword default is special = yes.

481

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

create_box command
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 extra/angle/per/atom or extra/dihedral/per/atom or
extra/improper/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
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

Examples:
create_box 2 mybox
create_box 2 mybox bond/types 2 extra/bond/per/atom 1

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 orthogonal 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 parallelipiped.

482

LAMMPS Users Manual
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 Section 6.12 of the doc pages for a geometric description of triclinic boxes, as
defined by LAMMPS, and how to transform 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 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.

483

LAMMPS Users Manual
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.
Restrictions:
An atom_style and region must have been previously defined to use this command.
Related commands:
read_data, create_atoms, region
Default: none

484

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

delete_atoms command
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
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

Examples:
delete_atoms
delete_atoms
delete_atoms
delete_atoms
delete_atoms

group edge
region sphere compress no
overlap 0.3 all all
overlap 0.5 solvent colloid
porosity cube 0.1 482793 bond yes

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
485

LAMMPS Users Manual
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.
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. 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.
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
486

LAMMPS Users Manual
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.
Related commands:
create_atoms
Default:
The option defaults are compress = yes, bond = no, mol = no.

487

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

delete_bonds command
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
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
Examples:
delete_bonds
delete_bonds
delete_bonds
delete_bonds

frozen multi remove
all atom 4 special
all bond 0*3 special
all stats

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,
488

LAMMPS Users Manual
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 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.

489

LAMMPS Users Manual
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.
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
recomputed, 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.
Related commands:
neigh_modify exclude, special_bonds, fix shake
Default: none

490

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dielectric command
Syntax:
dielectric value

• value = dielectric constant
Examples:
dielectric 2.0

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.
Restrictions: none
Related commands:
pair_style
Default:
dielectric 1.0

491

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dihedral_coeff command
Syntax:
dihedral_coeff N args

• N = dihedral type (see asterisk form below)
• args = coefficients for one or more dihedral types
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

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
1st 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 1st 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.

492

LAMMPS Users Manual
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.
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.
Note that there are also additional dihedral styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to the individual
styles are given in the dihedral section of this page.
• dihedral_style none - turn off dihedral interactions
• dihedral_style hybrid - define multiple styles of dihedral interactions
• dihedral_style
• dihedral_style
• dihedral_style
• dihedral_style
• dihedral_style
• dihedral_style

charmm - CHARMM dihedral
class2 - COMPASS (class 2) dihedral
harmonic - harmonic dihedral
helix - helix dihedral
multi/harmonic - multi-harmonic dihedral
opls - OPLS dihedral

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.
Related commands:
dihedral_style
Default: none

493

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dihedral_style command
Syntax:
dihedral_style style

• style = none or hybrid or charmm or class2 or harmonic or helix or
multi/harmonic or opls
Examples:
dihedral_style harmonic
dihedral_style multi/harmonic
dihedral_style hybrid harmonic charmm

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

494

LAMMPS Users Manual

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.
Note that there are also additional dihedral styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to the individual
styles are given in the dihedral section of this page.
• dihedral_style none - turn off dihedral interactions
• dihedral_style zero - topology but no interactions
• dihedral_style hybrid - define multiple styles of dihedral interactions
• dihedral_style
• dihedral_style
• dihedral_style
• dihedral_style
• dihedral_style
• dihedral_style

charmm - CHARMM dihedral
class2 - COMPASS (class 2) dihedral
harmonic - harmonic dihedral
helix - helix dihedral
multi/harmonic - multi-harmonic dihedral
opls - OPLS dihedral

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 Making LAMMPS section for more info
495

LAMMPS Users Manual
on packages. The doc pages for individual dihedral potentials tell if it is part of a
package.
Related commands:
dihedral_coeff
Default:
dihedral_style none

496

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dimension command
Syntax:
dimension N

• N = 2 or 3
Examples:
dimension 2

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 in Section 6 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.
Restrictions:
This command must be used before the simulation box is defined by a read_data or
create_box command.
Related commands:
fix enforce2d
Default:
dimension 3

497

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

displace_atoms command
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

Examples:
displace_atoms top move 0 -5 0 units box
displace_atoms flow ramp x 0.0 5.0 y 2.0 20.5

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
498

LAMMPS Users Manual
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 thru 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 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.
Restrictions:
For a 2d simulation, only rotations around the a vector parallel to the z-axis are
499

LAMMPS Users Manual
allowed.
Related commands:
lattice, change_box, fix move
Default:
The option defaults are units = lattice.

500

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump command
dump vtk command
dump h5md command
dump molfile command
dump netcdf command
dump image command
dump movie command
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
• style = atom or atom/gz or atom/mpiio or cfg or cfg/gz or cfg/mpiio or custom or
custom/gz or custom/mpiio or dcd or h5md or image or or local or molfile or
movie or netcdf or netcdf/mpiio or vtk or xtc or xyz or xyz/gz 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/mpiio args = none
cfg args = same as custom args, see below
cfg/gz args = same as custom args, see below
cfg/mpiio args = same as custom args, see below
custom, custom/gz, custom/mpiio args = see below
dcd args = none
h5md args = discussed on dump h5md doc page
image args = discussed on dump image doc page
local 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/mpiio args = none

• custom or custom/gz or custom/mpiio or netcdf or netcdf/mpiio args = list of
atom attributes
possible attributes = id, mol, proc, procp1, type, element, mass,

501

LAMMPS Users Manual
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[N], f_ID, f_ID[N], v_name

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
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 incl
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
v_name = per-atom vector calculated by an atom-style variable with name
d_name = per-atom floating point vector with name, managed by fix property/atom
i_name = per-atom integer vector with name, managed by fix property/atom

• local 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
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 wil

Examples:
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump
dump

myDump all atom 100 dump.atom
myDump all atom/mpiio 100 dump.atom.mpiio
myDump all atom/gz 100 dump.atom.gz
2 subgroup atom 50 dump.run.bin
2 subgroup atom 50 dump.run.mpiio.bin
4a all custom 100 dump.myforce.* id type x y vx fx
4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
4b flow custom 100 dump.%.myforce id type c_myF[*] v_ke
2 inner cfg 10 dump.snap.*.cfg mass type xs ys zs vx vy vz
snap all cfg 100 dump.config.*.cfg mass type xs ys zs id type c_Stress[2]
1 all xtc 1000 file.xtc

502

LAMMPS Users Manual
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 commands can also alter what atoms are included. Not all styles support
all these options; see details below.
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, 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.
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.
503

LAMMPS Users Manual
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.
The atom, local, and custom styles create files in a simple text format that is
self-explanatory when viewing a dump file. Many of the LAMMPS post-processing
tools, 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 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
xlo_bound
ylo_bound
zlo_bound

BOUNDS xy
xhi_bound
yhi_bound
zhi_bound

xz yz xx yy zz
xy
xz
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 this section of the doc pages 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
504

LAMMPS Users Manual
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 doesn't 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 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 molecular 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.
505

LAMMPS Users Manual
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 thru 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 minimization 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.
If a "%" character appears in the filename, then each of P processors writes a portion
of the dump file, and the "%" character is replaced with the processor ID from 0 to
506

LAMMPS Users Manual
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
make mpi

# installs the MPIIO package
# 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, 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
507

LAMMPS Users Manual
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 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.
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.

508

LAMMPS Users Manual
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 in
Section 6.12.
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 thru 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 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.

509

LAMMPS Users Manual
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 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
510

LAMMPS Users Manual
file.
The d_name and i_name attributes allow to output custom per atom floating point or
integer properties that are managed by fix property/atom.
See Section 10 of the manual 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.
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
Making LAMMPS section of the documentation.
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 Making
LAMMPS section 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
Making LAMMPS section 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 Making LAMMPS section for more info.
Related commands:
dump h5md, dump image, dump molfile, dump_modify, undump
Default:
The defaults for the image and movie styles are listed on the dump image doc page.

511

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump h5md command
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 "subintervals"
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
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 following the element declaration:
every N_element

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"

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.

512

LAMMPS Users Manual
Each data element is written every N*N_element steps. For image, no subinterval 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
subintervals 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

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 USER-H5MD package. It is only enabled if
LAMMPS was built with that package. See the Making LAMMPS section for more info.
It also requires (i) building the ch5md library provided with LAMMPS (See the Making
LAMMPS section 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.
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].

513

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump image command
dump movie command
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 persp 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)
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)

514

LAMMPS Users Manual
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)
persp value = pfactor = amount of "perspective" in image
pfactor = amount of perspective (0 = none, <1 = some, > 1 = highly skewed)
pfactor 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

Examples:
dump
dump
dump
dump
dump
dump

d0
d1
d2
m0
m1
m2

all image 100 dump.*.jpg type type
mobile image 500 snap.*.png element element ssao yes 4539 0.6
all image 200 img-*.ppm type type zoom 2.5 adiam 1.5 size 1280 720
all movie 1000 movie.mpg type type size 640 480
all movie 1000 movie.avi type type size 640 480
all movie 100 movie.m4v type type zoom 1.8 adiam v_value size 1280 720

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. Click to see the
full-size images:

515

LAMMPS Users Manual

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.
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 this section of the manual for
instructions on how to do this.
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 minimization 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,
516

LAMMPS Users Manual
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 calculated 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
• type
• type
• type
• type
• type

1
2
3
4
5
6

=
=
=
=
=
=

red
green
blue
yellow
aqua
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 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".
517

LAMMPS Users Manual
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
• type
• type
• type
• type
• type

1
2
3
4
5
6

=
=
=
=
=
=

red
green
blue
yellow
aqua
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.

518

LAMMPS Users Manual
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.
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
• type
• type
• type
• type
• type

1
2
3
4
5
6

=
=
=
=
=
=

red
green
blue
yellow
aqua
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
• type
• type
• type
• type
• type

1
2
3
4
5
6

=
=
=
=
=
=

red
green
blue
yellow
aqua
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.

519

LAMMPS Users Manual
The body doc 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 body doc 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
• type
• type
• type
• type
• type

1
2
3
4
5
6

=
=
=
=
=
=

red
green
blue
yellow
aqua
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. An example
is the fix surface/global command which can draw lines or triangles for 2d/3d
simulations.
NOTE: Aug 2016 - The fix surface/global command is not yet added to LAMMPS.
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 doc 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
• type
• type
• type
• type
• type

1
2
3
4
5
6

=
=
=
=
=
=

red
green
blue
yellow
aqua
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.

520

LAMMPS Users Manual
The view, center, up, zoom, and persp 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, zoom, and persp 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
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 persp keyword determines how much depth perspective is present in the image.
Depth perspective makes lines that are parallel in simulation space appear
non-parallel in the image. A pfactor value of 0.0 means that parallel lines will meet at
infinity (1.0/pfactor), which is an orthographic rendering with no perspective. A
pfactor value between 0.0 and 1.0 will introduce more perspective. A pfactor value >
521

LAMMPS Users Manual
1 will create a highly skewed image with a large amount of perspective.
NOTE: The persp keyword is not yet supported as an option.
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

522

LAMMPS Users Manual
Animated GIF files from ImageMagick are unoptimized. You can use a program
like gifsicle to optimize and massively shrink them. MPEG files created by
ImageMagick are in MPEG-1 format with rather inefficient compression and low
quality.
• 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

Frontends 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. Similarly 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 Section 10 of the manual 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.
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
523

LAMMPS Users Manual
-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 Making LAMMPS section of the documentation for details on how to compile
with optional switches.
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
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).
Related commands:
dump, dump_modify, undump
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
• persp = 0.0
524

LAMMPS Users Manual
• box = yes 0.02
• axes = no 0.0 0.0
• subbox no 0.0
• shiny = 1.0
• ssao = no

525

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump_modify command
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 element or every or fileper or first or flush
or format or image or label or nfile or pad or precision or region or scale or sort
or thresh or unwrap
append arg = yes or no
at arg = N
N = index of frame written upon first dump
buffer arg = yes or no
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
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
flush arg = yes or no
image arg = yes or no
label arg = string
string = character string (e.g. BONDS) to use in header of dump local 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"
scale arg = yes or no
sfactor arg = coordinate scaling factor (> 0.0)
thermo arg = yes or no
tfactor arg = time 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
thresh args = attribute operator value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
operator = "

• 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
acolor args = type color

526

LAMMPS Users Manual
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
framerate arg = fps
fps = frames per second for movie

Examples:
dump_modify
dump_modify
dump_modify
dump_modify
dump_modify
dump_modify
dump_modify
dump_modify

1 format line "%d %d %20.15g %g %g" scale yes
1 format float %20.15g scale yes
myDump image yes scale no flush yes
1 region mySphere thresh x <0.0 thresh epair >= 3.2
xtcdump precision 10000 sfactor 0.1
1 every 1000 nfile 20
1 every v_myVar
1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red

Description:
Modify the parameters of a previously defined dump command. Not all parameters are
relevant to all dump styles.

527

LAMMPS Users Manual
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 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 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 whitespace separated text will be accepted.

528

LAMMPS Users Manual
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
dump
dump_modify

s equal logfreq(10,3,10)
1 all atom 100 tmp.dump
1 every v_s first yes

The following commands would write snapshots at the timesteps listed in file
tmp.times:
variable
variable
dump
dump_modify

f
s
1
1

file tmp.times
equal next(f)
all atom 100 tmp.dump
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.

529

LAMMPS Users Manual
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, 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 5th 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 it 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 appropriate for an 8-byte signed
integer, e.g. one with "%ld", if LAMMPS was compiled with the -DLAMMPS_BIGBIG
option for 8-byte IDs.
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 "%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.
530

LAMMPS Users Manual
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 thru 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 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.
For the fileper keyword, the specified value of Np means write one file for every Np
processors. For example, if Np = 4, every 4th 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
531

LAMMPS Users Manual
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 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 fmsec used by real units are 0.1 nm and
0.001 psec respectively. If you are using a units system with distance and time units
far from nm and psec, 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 thermo keyword (netcdf only) triggers writing of thermo information to the dump
file alongside per-atom data. The data included in the dump file is identical to the data
specified by thermo_style.
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 normalized 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 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.

532

LAMMPS Users Manual
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 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 doc 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 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 thru a periodic boundary one or more times, the
533

LAMMPS Users Manual
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 atomt 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.

534

LAMMPS Users Manual
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.
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 2nd 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 continuous, 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
535

LAMMPS Users Manual
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
variable
dump
dump_modify

colors string &
"red green blue yellow white &
purple pink orange lime gray"
mol atom mol%10
1 all image 250 image.*.jpg v_mol type &
zoom 1.6 adiam 1.5
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
536

LAMMPS Users Manual
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 associates 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.
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
537

LAMMPS Users Manual
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.

Restrictions: none
Related commands:
dump, dump image, undump
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
• flush = yes
• format = %d and %g for each integer or floating point value
• image = no
• label = ENTRIES
• 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
• 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
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"
538

LAMMPS Users Manual
• 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"
• 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. Additional 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.
aliceblue = 240,
248, 255
beige = 245,
245, 220
blueviolet = 138,
43, 226
chocolate = 210,
105, 30
cyan = 0, 255,
255
darkgreen = 0,
100, 0
darkorchid =
153, 50, 204
darkslategray =
47, 79, 79
dimgray = 105,
105, 105
fuchsia = 255, 0,
255
gray = 128, 128,
128
indianred = 205,
92, 92
lavenderblush =
255, 240, 245
lightcyan = 224,
255, 255
lightsalmon =
255, 160, 122

antiquewhite = 250,
aqua = 0, 255, 255
235, 215
bisque = 255, 228,
black = 0, 0, 0
196
burlywood = 222,
brown = 165, 42, 42
184, 135
cornflowerblue =
coral = 255, 127, 80
100, 149, 237
darkcyan = 0, 139,
darkblue = 0, 0, 139
139
darkkhaki = 189,
darkmagenta =
183, 107
139, 0, 139
darksalmon = 233,
darkred = 139, 0, 0
150, 122
darkturquoise = 0, darkviolet = 148, 0,
206, 209
211
dodgerblue = 30,
firebrick = 178, 34,
144, 255
34
gainsboro = 220,
ghostwhite = 248,
220, 220
248, 255
greenyellow = 173,
green = 0, 128, 0
255, 47
ivory = 255, 240,
indigo = 75, 0, 130
240
lawngreen = 124,
lemonchiffon =
252, 0
255, 250, 205
lightgoldenrodyellow lightgreen = 144,
= 250, 250, 210
238, 144
lightseagreen = 32, lightskyblue = 135,
178, 170
206, 250
lime = 0, 255, 0

aquamarine =
127, 255, 212
blanchedalmond
= 255, 255, 205
cadetblue = 95,
158, 160
cornsilk = 255,
248, 220
darkgoldenrod =
184, 134, 11
darkolivegreen =
85, 107, 47
darkseagreen =
143, 188, 143
deeppink = 255,
20, 147
floralwhite =
255, 250, 240
gold = 255, 215,
0
honeydew = 240,
255, 240
khaki = 240,
230, 140
lightblue = 173,
216, 230
lightgrey = 211,
211, 211
lightslategray =
119, 136, 153

azure = 240,
255, 255
blue = 0, 0, 255
chartreuse =
127, 255, 0
crimson = 220,
20, 60
darkgray = 169,
169, 169
darkorange =
255, 140, 0
darkslateblue =
72, 61, 139
deepskyblue =
0, 191, 255
forestgreen =
34, 139, 34
goldenrod =
218, 165, 32
hotpink = 255,
105, 180
lavender = 230,
230, 250
lightcoral = 240,
128, 128
lightpink = 255,
182, 193
lightsteelblue =
176, 196, 222

539

LAMMPS Users Manual
lightyellow =
255, 255, 224
maroon = 128, mediumaquamarine
0, 0
= 102, 205, 170
mediumseagreen mediumslateblue =
= 60, 179, 113 123, 104, 238
midnightblue = mintcream = 245,
25, 25, 112
255, 250
oldlace = 253, 245,
navy = 0, 0, 128
230
orangered =
orchid = 218, 112,
255, 69, 0
214
palevioletred = papayawhip = 255,
219, 112, 147
239, 213
plum = 221,
powderblue = 176,
160, 221
224, 230
royalblue = 65, saddlebrown = 139,
105, 225
69, 19
seashell = 255,
sienna = 160, 82, 45
245, 238
slategray = 112, snow = 255, 250,
128, 144
250
teal = 0, 128,
thistle = 216, 191,
128
216
wheat = 245,
white = 255, 255,
222, 179
255

limegreen = 50,
linen = 250, 240, magenta = 255,
205, 50
230
0, 255
mediumblue = 0, 0, mediumorchid = mediumpurple =
205
186, 85, 211
147, 112, 219
mediumspringgreen mediumturquoise mediumvioletred
= 0, 250, 154
= 72, 209, 204
= 199, 21, 133
mistyrose = 255,
moccasin = 255, navajowhite =
228, 225
228, 181
255, 222, 173
olivedrab = 107, orange = 255,
olive = 128, 128, 0
142, 35
165, 0
palegoldenrod =
palegreen = 152, paleturquoise =
238, 232, 170
251, 152
175, 238, 238
peachpuff = 255,
peru = 205, 133, pink = 255, 192,
239, 213
63
203
rosybrown =
purple = 128, 0,
red = 255, 0, 0
188, 143, 143
128
salmon = 250, 128, sandybrown =
seagreen = 46,
114
244, 164, 96
139, 87
silver = 192, 192,
skyblue = 135,
slateblue = 106,
192
206, 235
90, 205
springgreen = 0,
steelblue = 70,
tan = 210, 180,
255, 127
130, 180
140
tomato = 253, 99, turquoise = 64, violet = 238,
71
224, 208
130, 238
whitesmoke = 245, yellow = 255,
yellowgreen =
245, 245
255, 0
154, 205, 50

540

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump molfile command
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)
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

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.

541

LAMMPS Users Manual
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 minimization 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.
Restrictions:
The molfile dump style is part of the USER-MOLFILE package. It is only enabled if
LAMMPS was built with that package. See the Making LAMMPS section for more info.
Molfile plugins provide a consistent programming interface to read and write file
formats commonly used in molecular simulations. The USER-MOLFILE package only
provides the interface code, not the plugins. These 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 recompile the application
itself. The plugins are installed in the directory: /plugins//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: /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)
Related commands:
dump, dump_modify, undump
Default:
The default path is ".". All other properties have to be specified.

542

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump netcdf command
dump netcdf/mpiio command
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
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

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.
Restrictions:

543

LAMMPS Users Manual
The netcdf and netcdf/mpiio dump styles are part of the USER-NETCDF package.
They are only enabled if LAMMPS was built with that package. See the Making
LAMMPS section for more info.
Related commands:
dump, dump_modify, undump

544

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump vtk command
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
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

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.
IMPORTANT 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.
IMPORTANT NOTE: 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
545

LAMMPS Users Manual
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 doc 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 doc 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 minimization 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 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.
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 "%" character is replaced with the processor ID from 0 to P-1
546

LAMMPS Users Manual
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.
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.
Restrictions:
The vtk style does not support writing of gzipped dump files.
The vtk dump style is part of the USER-VTK package. It is only enabled if LAMMPS
was built with that package. See the Making LAMMPS section 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 Makefile.lammps file in that directory is appropriate
for your machine.
The vtk dump style supports neither buffering or custom format strings.
Related commands:
dump, dump image, dump_modify, undump
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.

547

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump cfg/uef command
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

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

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.
Restrictions:
This fix is part of the USER-UEF package. It is only enabled if LAMMPS was built with
that package. See the Making LAMMPS section for more info.
This command can only be used when fix nvt/uef or fix npt/uef is active.
Related commands:
dump, fix nvt/uef
Default: none

548

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

echo command
Syntax:
echo style

• style = none or screen or log or both
Examples:
echo both
echo log

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.
Restrictions: none
Related commands: none
Default:
echo log

549

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

fix command
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
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

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 during 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 dozens of fixes defined in LAMMPS and new
ones can be added; see this section for a discussion.
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 doc page
for individual fixes for details.
550

LAMMPS Users Manual
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 may produces either global or per-atom or local quantities (or
none at all), but never more than one of these.
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:
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.

551

LAMMPS Users Manual
See this howto section 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 doc page for individual fixes for further info.
Each fix style has its own documentation 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 given in more compact form in the Fix section of this page.
There are also additional fix styles (not listed here) submitted by users which are
included in the LAMMPS distribution. The list of these with links to the individual
styles are given in the fix section of this page.
• adapt - change a simulation parameter over time
• addforce - add a force to each atom
• append/atoms - append atoms to a running simulation
• atom/swap - Monte Carlo atom type swapping
• aveforce - add an averaged force to each atom
• ave/atom - compute per-atom time-averaged quantities
• ave/chunk - compute per-chunk time-averaged quantities
• ave/correlate - compute/output time correlations
• ave/histo - compute/output time-averaged histograms
• ave/time - compute/output global time-averaged quantities
• balance - perform dynamic load-balancing
• bond/break - break bonds on the fly
• bond/create - create bonds on the fly
• bond/swap - Monte Carlo bond swapping
• box/relax - relax box size during energy minimization
• deform - change the simulation box size/shape
• deposit - add new atoms above a surface
• drag - drag atoms towards a defined coordinate
• dt/reset - reset the timestep based on velocity, forces
• efield - impose electric field on system
• ehex - ehanced heat exchange algorithm
• enforce2d - zero out z-dimension velocity and force
• evaporate - remove atoms from simulation periodically
• external - callback to an external driver program
• freeze - freeze atoms in a granular simulation
• gcmc - grand canonical insertions/deletions
• gld - generalized Langevin dynamics integrator
• gravity - add gravity to atoms in a granular simulation
• halt - terminate a dynamics run or minimization
• heat - add/subtract momentum-conserving heat
• indent - impose force due to an indenter
552

LAMMPS Users Manual
• latte - wrapper on LATTE density-functional tight-binding code
• langevin - Langevin temperature control
• lineforce - constrain atoms to move in a line
• momentum - zero the linear and/or angular momentum of a group of atoms
• move - move atoms in a prescribed fashion
• msst - multi-scale shock technique (MSST) integration
• neb - nudged elastic band (NEB) spring forces
• nph - constant NPH time integration via Nose/Hoover
• nphug - constant-stress Hugoniostat integration
• nph/asphere - NPH for aspherical particles
• nph/body - NPH for body particles
• nph/sphere - NPH for spherical particles
• npt - constant NPT time integration via Nose/Hoover
• npt/asphere - NPT for aspherical particles
• npt/body - NPT for body particles
• npt/sphere - NPT for spherical particles
• nve - constant NVE time integration
• nve/asphere - NVE for aspherical particles
• nve/asphere/noforce - NVE for aspherical particles without forces"
• nve/body - NVE for body particles
• nve/limit - NVE with limited step length
• nve/line - NVE for line segments
• nve/noforce - NVE without forces (v only)
• nve/sphere - NVE for spherical particles
• nve/tri - NVE for triangles
• nvt - constant NVT time integration via Nose/Hoover
• nvt/asphere - NVT for aspherical particles
• nvt/body - NVT for body particles
• nvt/sllod - NVT for NEMD with SLLOD equations
• nvt/sphere - NVT for spherical particles
• 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
• planeforce - constrain atoms to move in a plane
• poems - constrain clusters of atoms to move as coupled rigid bodies
• pour - pour new atoms/molecules into a granular simulation domain
• press/berendsen - pressure control by Berendsen barostat
• print - print text and variables during a simulation
• property/atom - add customized per-atom values
• qeq/comb - charge equilibration for COMB potential qeq/dynamic - charge
equilibration via dynamic method qeq/fire - charge equilibration via FIRE
minimizer qeq/point - charge equilibration via point method qeq/shielded charge equilibration via shielded method qeq/slater - charge equilibration via
Slater method rattle - RATTLE constraints on bonds and/or angles
• reax/bonds - write out ReaxFF bond information recenter - constrain the
center-of-mass position of a group of atoms
• restrain - constrain a bond, angle, dihedral
• rigid - constrain one or more clusters of atoms to move as a rigid body with NVE
integration
• rigid/nph - constrain one or more clusters of atoms to move as a rigid body with
NPH integration
553

LAMMPS Users Manual
• rigid/npt - constrain one or more 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/nvt - constrain one or more 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
• rigid/small/nph - constrain many small clusters of atoms to move as a rigid body
with NPH integration
• rigid/small/npt - constrain many small clusters of atoms to move as a rigid body
with NPT integration
• rigid/small/nve - constrain many small clusters of atoms to move as a rigid body
with alternate NVE integration
• rigid/small/nvt - constrain many small clusters of atoms to move as a rigid body
with NVT integration
• setforce - set the force on each atom
• shake - SHAKE constraints on bonds and/or angles
• 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
• 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
• tfmc - perform force-bias Monte Carlo with time-stamped method
• thermal/conductivity - Muller-Plathe kinetic energy exchange for thermal
conductivity calculation
• tmd - guide a group of atoms to a new configuration
• ttm - two-temperature model for electronic/atomic coupling
• 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/colloid - Lennard-Jones wall interacting with finite-size particles
• wall/gran - frictional wall(s) for granular simulations
• wall/harmonic - harmonic spring wall
• wall/lj1043 - Lennard-Jones 10-4-3 wall
• wall/lj126 - Lennard-Jones 12-6 wall
• wall/lj93 - Lennard-Jones 9-3 wall
• wall/piston - moving reflective piston wall
• wall/reflect - reflecting wall(s)
• wall/region - use region surface as wall
• wall/srd - slip/no-slip wall for SRD particles
Restrictions:
554

LAMMPS Users Manual
Some fix styles are part of specific packages. They are only enabled if LAMMPS was
built with that package. See the Making LAMMPS section for more info on packages.
The doc pages for individual fixes tell if it is part of a package.
Related commands:
unfix, fix_modify
Default: none

555

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

fix_modify command
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
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 recompute the number of degrees of freedom (DOF) contributing

Examples:
fix_modify 3 temp myTemp press myPress
fix_modify 1 energy yes
fix_modify tether respa 2

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. energy yes adds a
contribution to the potential energy of the system. The fix's global and per-atom
energy is included in the calculation performed by the compute pe or compute
pe/atom commands. See the thermo_style command for info on how potential energy
is output. For fixes that tally a global energy, it can be printed by using the keyword
f_ID in the thermo_style custom command, where ID is the fix-ID of the appropriate
fix.
556

LAMMPS Users Manual
NOTE: You must also specify the energy yes setting for a fix if you are using it when
performing an energy minimization and if you want the energy and forces it produces
to be part of the optimization criteria.
The virial keyword can be used with fixes that support it. virial yes adds a contribution
to the virial of the system. The fix's global and per-atom virial is included in the
calculation performed by the compute pressure or compute stress/atom commands.
See the thermo_style command for info on how pressure is output.
NOTE: You must specify the virial yes setting for a fix if you are doing box relaxation
and if you want virial contribution of the fix to be part of the relaxation criteria,
although this seems unlikely.
NOTE: This option is only supported by fixes that explicitly say so. For some of these
(e.g. the fix shake command) the default setting is virial yes, for others it is virial no.
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.
Restrictions: none
Related commands:
fix, compute temp, compute pressure, thermo_style
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.
557

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

group command
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 = "

Examples:
group
group
group
group
group
group
group
group
group
group
group
group
group
group

edge region regstrip
water type 3 4
sub id 10 25 50
sub id 10 25 50 500:1000
sub id 100:10000:10
sub id <= 150
polyA molecule 50 250
hienergy variable eng
hienergy include molecule
boundary subtract all a2 a3
boundary union lower upper
boundary intersect upper flow
boundary delete
mine dynamic all region myRegion every 100

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
558

LAMMPS Users Manual
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 2nd 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 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 3rd
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 4th 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.

559

LAMMPS Users Manual
Atom-style variables can specify formulas that include thermodynamic quantities,
per-atom values such as atom coordinates, 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
compute
thermo_style
run

1 all pe/atom
2 all reduce sum c_1
custom step temp pe c_2
0

variable
group

eatom atom "c_1 > -3.0"
hienergy variable eatom

Note that these lines
compute
thermo_style
run

2 all reduce sum c_1
custom step temp pe c_2
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
thermodynamic 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 doc 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 2nd
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 communication 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.

560

LAMMPS Users Manual
The subtract style takes a list of two or more existing group names as arguments. All
atoms that belong to the 1st group, but not to any of the other groups are added to the
specified group.
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 per-atom property name must be a previously defined per-atom
property. The per-atom property is evaluated and atoms whose values are 0.0 are
removed from the dynamic group, otherwise they are added to the group.
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
variable
region

nsteps equal 5000
rad equal 18-(step/v_nsteps)*(18-5)
ss sphere 20 20 0 v_rad

561

LAMMPS Users Manual
group
fix
run
group
run

mobile dynamic all region ss
1 mobile nve
${nsteps}
mobile static
${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 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.
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.
Related commands:
dump, fix, region, velocity
Default:
All atoms belong to the "all" group.

562

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

group2ndx command
ndx2group command
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
Examples:
group2ndx
group2ndx
ndx2group
ndx2group

allindex.ndx
someindex.ndx upper lower mobile
someindex.ndx
someindex.ndx mobile

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.
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 USER-COLVARS package. They are only enabled if
LAMMPS was built with that package. See the Making LAMMPS section for more info.
Related commands:
group, dump, fix colvars

563

LAMMPS Users Manual
Default: none

564

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

if command
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)
Examples:
if
if
if
if

"${steps} > 1000" then quit
"${myString} == a10" then quit
"$x <= $y" then "print X is smaller = $x" else "print Y is smaller = $y"
"(${eng} > 0.0) || ($n <1000)" then &
"timestep 0.005" &
elif $n

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 aren't
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,
except an include command, which is not allowed. 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.
565

LAMMPS Users Manual
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. See Section 3.2 of the manual for 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"
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 thru the outer
loop.
label
variable
label
variable
print
run
if
next
jump
label
variable
next
jump

loopa
a loop 5
loopb
b loop 5
"A,B = $a,$b"
10000
"$b > 2" then "jump SELF break"
b
in.script loopb
break
b delete
a
SELF loopa

566

LAMMPS Users Manual
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 or
underscores):
0.2, 100, 1.0e20, -15.4, etc
InP, myString, a123, ab_23_cd, etc

and Boolean operators:
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 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.
Restrictions: none
567

LAMMPS Users Manual
Related commands:
variable, print
Default: none

568

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

improper_coeff command
Syntax:
improper_coeff N args

• N = improper type (see asterisk form below)
• args = coefficients for one or more improper types
Examples:
improper_coeff 1 300.0 0.0
improper_coeff * 80.2 -1 2
improper_coeff *4 80.2 -1 2

Description:
Specify the improper force field coefficients for one or more improper types. The
number and meaning of the coefficients 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
1st 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).
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 improper_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 1st 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.

569

LAMMPS Users Manual
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.
Note that there are also additional improper styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to the individual
styles are given in the improper section of this page.
• improper_style none - turn off improper interactions
• improper_style hybrid - define multiple styles of improper interactions
• improper_style
• improper_style
• improper_style
• improper_style

class2 - COMPASS (class 2) improper
cvff - CVFF improper
harmonic - harmonic improper
umbrella - DREIDING improper

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.
Related commands:
improper_style
Default: none

570

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

improper_style command
Syntax:
improper_style style

• style = none or hybrid or class2 or cvff or harmonic
Examples:
improper_style harmonic
improper_style cvff
improper_style hybrid cvff harmonic

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 improper 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 improper_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.
Note that there are also additional improper styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to the individual
styles are given in the improper section of this page.
• improper_style none - turn off improper interactions
• improper_style zero - topology but no interactions
571

LAMMPS Users Manual
• improper_style hybrid - define multiple styles of improper interactions
• improper_style
• improper_style
• improper_style
• improper_style

class2 - COMPASS (class 2) improper
cvff - CVFF improper
harmonic - harmonic improper
umbrella - DREIDING improper

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 Making LAMMPS section for more info
on packages. The doc pages for individual improper potentials tell if it is part of a
package.
Related commands:
improper_coeff
Default:
improper_style none

572

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

include command
Syntax:
include file

• file = filename of new input script to switch to
Examples:
include newfile
include in.run2

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.
Restrictions: none
Related commands:
variable, jump
Default: none

573

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

info command
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, 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
Examples:
info
info
info
info
info
info

system
groups computes variables
all out log
all out append info.txt
styles all
styles atom

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

LAMMPS Users Manual
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 frequencies.
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 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
The time category prints the accumulated CPU and wall time for the process that
writes output (usually MPI rank 0).
Restrictions: none
Related commands:
575

LAMMPS Users Manual
print
Default:
The out option has the default screen.
The styles option has the default all.

576

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

jump command
Syntax:
jump file label

• file = filename of new input script to switch to
• label = optional label within file to jump to
Examples:
jump newfile
jump in.run2 runloop
jump SELF runloop

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++  2" then "jump SELF break"
b
in.script loopb
break
b delete
a
SELF loopa

Restrictions:

578

LAMMPS Users Manual
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.
Related commands:
variable, include, label, next
Default: none

579

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

kspace_modify command
Syntax:
kspace_modify keyword value ...

• one or more keyword/value pairs may be listed

keyword = mesh or order or order/disp or mix/disp or overlap or minorder or force or gew
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
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
mix/disp value = pair or geom or none
overlap = yes or no = whether the grid stencil for PPPM is allowed to overlap into mor
minorder value = M
M = min allowed extent of Gaussian when auto-adjusting to minimize grid communicatio
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
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
compute value = yes or no
cutoff/adjust value = yes or no
pressure/scalar value = yes or no
fftbench value = yes or no
collective value = yes or no
diff value = ad or ik = 2 or 4 FFTs for PPPM in smoothed or non-smoothed mode
kmax/ewald value = kx ky kz
kx,ky,kz = number of Ewald sum kspace vectors in each dimension
force/disp/real value = accuracy (force units)
force/disp/kspace value = accuracy (force units)
splittol value = tol
tol = relative size of two eigenvalues (see discussion below)
disp/auto value = yes or no

Examples:
kspace_modify mesh 24 24 30 order 6
kspace_modify slab 3.0

Description:
Set parameters used by the kspace solvers defined by the kspace_style command. Not
all parameters are relevant to all kspace styles.

580

LAMMPS Users Manual
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 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 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 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 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 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
581

LAMMPS Users Manual
keyword is not currently supported in MSM.
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 force keyword overrides the relative accuracy parameter set by the kspace_style
command with an absolute accuracy. 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 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.

582

LAMMPS Users Manual
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 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 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 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 a some seconds later than it would if this option were off.
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 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 PPPM mesh to achieve the same accuracy as the ik
583

LAMMPS Users Manual
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 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.
With the mix/disp keyword one can select 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 approximated.
This leads to faster computations, but the accuracy in the reciprocal space
computations of the dispersion part is decreased.
The force/disp/real and force/disp/kspace keywords set the force accuracy for the real
and 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 How-To discussion.
Restrictions: none
Related commands:
kspace_style, boundary
Default:
The option defaults are mesh = mesh/disp = 0 0 0, order = order/disp = 5 (PPPM),
order = 10 (MSM), minorder = 2, overlap = yes, force = -1.0, gewald = gewald/disp =
0.0, slab = 1.0, compute = yes, cutoff/adjust = yes (MSM), pressure/scalar = yes
584

LAMMPS Users Manual
(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.

(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).

585

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

kspace_style command
Syntax:
kspace_style style value

• style = none or ewald or ewald/disp 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/kk or pppm/omp or pppm/cg/omp or pppm/tip4p/omp or msm or msm/cg
or msm/omp or msm/cg/omp
none value = none
ewald value = accuracy
accuracy = desired relative error in forces
ewald/disp value = accuracy
accuracy = desired relative error in forces
ewald/omp value = accuracy
accuracy = desired relative error in forces
pppm value = accuracy
accuracy = desired relative error in forces
pppm/cg value = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
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/kk value = accuracy
accuracy = desired relative error in forces
pppm/omp value = accuracy
accuracy = desired relative error in forces
pppm/cg/omp value = accuracy
accuracy = desired relative error in forces
pppm/disp/intel value = accuracy
accuracy = desired relative error in forces
pppm/tip4p/omp value = accuracy
accuracy = desired relative error in forces
pppm/stagger 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)

586

LAMMPS Users Manual
Examples:
kspace_style
kspace_style
kspace style
kspace_style

pppm 1.0e-4
pppm/cg 1.0e-5 1.0e-6
msm 1.0e-4
none

Description:
Define a long-range solver for LAMMPS to use each timestep to compute long-range
Coulombic interactions or long-range 1/r^6 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/r^N 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
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/r^6 potentials and
is useful for simulation of interfaces (Veld). It also performs standard Coulombic
Ewald summations, but in a more efficient manner than the ewald style. The 1/r^6
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 style can also be
used with point-dipoles (Toukmaji) and is currently the only kspace solver in LAMMPS
with this capability.
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. It is closely related
to the particle-mesh Ewald technique (PME) (Darden) used in AMBER and CHARMM.
The cost of traditional Ewald summation scales as N^(3/2) where N is the number of
atoms in the system. The PPPM solver scales as Nlog(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
587

LAMMPS Users Manual
the absolute charge value which determines whether a particle is considered charged
or not. Its default value is 1.0e-5.
The pppm/tip4p style is identical to the pppm style except that it adds a charge at the
massless 4th 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 Section 5.
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 potentials 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 How-To discussion.
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 lo-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 in this section of the manual. 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 solves are done. This method
does not use FFTs and scales as N. It may therefore be faster than the other K-space
588

LAMMPS Users Manual
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
coulomb 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 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 are estimated using
equations 33 and 46 of (Wang).
589

LAMMPS Users Manual
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 in Section 5 of the manual. 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 lo-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 also performs charge assignment and force interpolation
calculations on the GPU while the FFTs themselves are calculated on the CPU in
non-threaded mode.
These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, USER-OMP,
and OPT packages respectively. They are only enabled if LAMMPS was built with
those packages. See the Making LAMMPS section for more info.
See Section 5 of the manual for more instructions on how to use the accelerated styles
effectively.
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 suffix versions of these styles.
All of the kspace styles are part of the KSPACE package. They are only enabled if
LAMMPS was built with that package. See the Making LAMMPS section for more info.
Note that the KSPACE package is installed by default.
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.

590

LAMMPS Users Manual
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
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).
(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).

591

LAMMPS Users Manual
(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 (2009) 164-177.

592

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

label command
Syntax:
label ID

• ID = string used as label name
Examples:
label xyz
label loop

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.
Restrictions: none
Related commands: none
Default: none

593

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

lattice command
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)

Examples:
lattice
lattice
lattice
lattice

fcc 3.52
hex 0.85
sq 0.8 origin 0.0 0.5 0.0 orient x 1 1 0 orient y -1 1 0
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

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

LAMMPS Users Manual
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 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
595

LAMMPS Users Manual
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 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.
596

LAMMPS Users Manual
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.
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 (courtesy of Aidan Thompson),
with its 8 atom unit cell.
variable a equal
variable b equal
variable c equal
variable
variable
variable
variable
variable
variable

4.340330
$a*sqrt(3.0)
$a*sqrt(8.0/3.0)

1_3 equal 1.0/3.0
2_3 equal 2.0/3.0
1_6 equal 1.0/6.0
5_6 equal 5.0/6.0
1_12 equal 1.0/12.0
5_12 equal 5.0/12.0

lattice custom
a1
a2
a3
basis

1.0
$a
0.0
0.0
0.0

&
0.0
$b
0.0
0.0

0.0
0.0
$c
0.0

&
&
&
&

597

LAMMPS Users Manual
basis
basis
basis
basis
basis
basis
basis

0.5
${1_3}
${5_6}
0.0
0.5
${1_3}
${5_6}

0.5
0.0
0.5
0.0
0.5
0.0
0.5

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

0.0
0.5
0.5
0.625
0.625
0.125
0.125

&
&
&
&
&
&

&
&
&

Restrictions:
The a1,a2,a3,basis keywords can only be used with style custom.
Related commands:
dimension, create_atoms, region
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.

598

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

log command
Syntax:
log file keyword

• file = name of new logfile
• keyword = append if output should be appended to logfile (optional)
Examples:
log log.equil
log log.equil append

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 command-line switch -log. See Section 2.6 for details.
Restrictions: none
Related commands: none
Default:
The default LAMMPS log file is named log.lammps

599

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

mass command
Syntax:
mass I value

• I = atom type (see asterisk form below)
• value = mass
Examples:
mass 1 1.0
mass * 62.5
mass 2* 62.5

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 1st 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 1st 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
600

LAMMPS Users Manual
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.
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.
Related commands: none
Default: none

601

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

min_modify command
Syntax:
min_modify keyword values ...

• one or more keyword/value pairs may be listed
keyword = dmax or line
dmax value = max
max = maximum distance for line search to move (distance units)
line value = backtrack or quadratic or forcezero
backtrack,quadratic,forcezero = style of linesearch to use

Examples:
min_modify dmax 0.2

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

LAMMPS Users Manual
Restrictions: none
Related commands:
min_style, minimize
Default:
The option defaults are dmax = 0.1 and line = quadratic.

603

LAMMPS Users Manual
LAMMPS WWW Page - LAMMPS Documentation - LAMMPS Commands

min_style command
Syntax:
min_style style

• style = cg or hftn or sd or quickmin or fire
Examples:
min_style cg
min_style fire

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

604

LAMMPS Users Manual
Either the quickmin and fire styles are useful in the context of nudged elastic band
(NEB) calculations via the neb 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.
NOTE: The quickmin, fire, and hftn styles do not yet support the use of the fix
box/relax command or minimizations involving the electron radius in eFF models.
Restrictions: none
Related commands:
min_modify, minimize, neb
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).

605

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

minimize command
Syntax:
minimize etol ftol maxiter maxeval

• etol = stopping tolerance for energy (unitless)
• ftol = stopping tolerance for force (force units)
• maxiter = max iterations of minimizer
• maxeval = max number of force/energy evaluations
Examples:
minimize 1.0e-4 1.0e-6 100 1000
minimize 0.0 1.0e-8 1000 100000

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.
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've tried. The backtracking method is described in Nocedal and Wright's Numerical
Optimization (Procedure 3.1 on p 41).

606

LAMMPS Users Manual
The minimization styles quickmin and fire 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:

where the first term is the sum of all non-bonded pairwise interactions including
long-range Coulombic interactions, the 2nd thru 5th 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 thru 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
• the
• the
• the
• the

change in energy between outer iterations is less than etol
2-norm (length) of the global force vector is less than the ftol
line search fails because the step distance backtracks to 0.0
number of outer iterations or timesteps exceeds maxiter
number of total force evaluations exceeds maxeval

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
607

LAMMPS Users Manual
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
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
608

LAMMPS Users Manual
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
manybody 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 always 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 apply force constraints) 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
• fix
• fix
• fix
• fix
• fix
• fix
• fix
• fix
• fix
• fix
• fix
• fix

addforce
addtorque
efield
enforce2d
indent
lineforce
planeforce
setforce
spring
spring/self
viscous
wall
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.
Restrictions:
Features that are not yet implemented are listed here, in case someone knows how
they could be coded:
609

LAMMPS Users Manual
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.
Related commands:
min_modify, min_style, run_style
Default: none

610

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

molecule command
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

Examples:
molecule
molecule
molecule
molecule
molecule

1 mymol.txt
1 co2.txt h2o.txt
CO2 co2.txt boff 3 aoff 2
1 mymol.txt offset 6 9 18 23 14
objects file.1 scale 1.5 file.1 scale 2.0 file.2 scale 1.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
• create_atoms
• atom_style template

611

LAMMPS Users Manual
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, 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, imporopers, 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. If such molecules do not already exist when LAMMPS creates
the simulation box, via the create_box or read_data command, when you later add
them you may overflow the pre-allocated data structures which store molecular
topology information with each atom, and an error will be generated. Both the
create_box command and the data files read by 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 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 whitespace 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
doesn't contain a header keyword, the line begins the body of the file.

612

LAMMPS Users Manual
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
• 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, 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
613

LAMMPS Users Manual
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.
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. In each case the ID is ignored; it is simply included for
readability, and should be a number from 1 to Nlines for the section, indicating which
atom (or bond, etc) the entry applies to. The lines are assumed to be listed in order
from 1 to Nlines, but LAMMPS does not check for this.
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
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
• 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
614

LAMMPS Users Manual
• 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
• 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
615

LAMMPS Users Manual
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 doc 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 doc 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)
• 2 = part of a 2-atom SHAKE cluster with a single bond
616

LAMMPS Users Manual
• 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 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 doc 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.
617

LAMMPS Users Manual
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 2nd 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 2nd non-central atom (value c in the
Shake Atoms section).
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 2nd non-central atom (value c in the Shake
Atoms section), and c = bondtype of the bond between the central atom and the 3rd
non-central atom (value d in the Shake Atoms section).
See the fix shake doc page for a further description of SHAKE clusters.
Restrictions: none
Related commands:
fix deposit, fix pour, fix gcmc
Default:
The default keywords values are offset 0 0 0 0 0 and scale = 1.0.

618

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

neb command
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
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

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; see Section 2.6 of the
manual. 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 Section 6.5 of the manual for further discussion.
619

LAMMPS Users Manual
NOTE: As explained below, a NEB calculation perfoms 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 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 2nd 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
620

LAMMPS Users Manual
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
621

LAMMPS Users Manual
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 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 nugding 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
622

LAMMPS Users Manual
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.
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
623

LAMMPS Users Manual
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 suplementary information
can help understanding what is going wrong. For instance when the path angle
becomes accute 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.
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
624

LAMMPS Users Manual
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. Click on them to see a larger image.

Restrictions:
This command can only be used if LAMMPS was built with the REPLICA package. See
the Making LAMMPS section for more info on packages.
Related commands:
prd, temper, fix langevin, fix viscous
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)

625

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

neigh_modify command
Syntax:
neigh_modify keyword values ...

• one or more keyword/value pairs may be listed

keyword = delay or every or check or once or cluster or include or exclude or page or on
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)

Examples:
neigh_modify
neigh_modify
neigh_modify
neigh_modify
neigh_modify

every 2
exclude
exclude
exclude
exclude

delay 10 check yes page 100000
type 2 3
group frozen frozen check no
group residue1 chain3
molecule/intra rigid

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

LAMMPS Users Manual
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 interactions, 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.
627

LAMMPS Users Manual
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.
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 doesn't 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've
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 minimum pair cutoff. Typically these are
good values 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
628

LAMMPS Users Manual
will use the default binsize of 1/2 the cutoff.
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.
Related commands:
neighbor, delete_bonds
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.

629

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

neighbor command
Syntax:
neighbor skin style

• skin = extra distance beyond force cutoff (distance units)
• style = bin or nsq or multi
Examples:
neighbor 0.3 bin
neighbor 2.0 nsq

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.
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 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. For style multi the bin size is set to 1/2 of the shortest cutoff distance and
multiple sets of bins are defined to search over for different atom types. This imposes
some extra setup overhead, but the searches themselves may be much faster for the
short-cutoff cases. See the comm_modify mode multi command for a communication
option option that may also be beneficial for simulations of this kind.
The neigh_modify command has additional options that control how often neighbor
lists are built and which pairs are stored in the list.

630

LAMMPS Users Manual
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 this section for details.
Restrictions: none
Related commands:
neigh_modify, units, comm_modify
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

631

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

newton command
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
Examples:
newton off
newton on off

Description:
This command turns Newton's 3rd law on or off for pairwise and bonded interactions.
For most problems, setting Newton's 3rd 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.
Restrictions:
The newton bond setting cannot be changed after the simulation box is defined by a
read_data or create_box command.
Related commands:
run_style respa
Default:
newton on

632

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

next command
Syntax:
next variables

• variables = one or more variable names
Examples:
next x
next a t x myTemp

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.

633

LAMMPS Users Manual
When the next command is used with universe- or uloop-style variables, all universeor 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 is described in this section of the manual. Universe- and
uloop-style variables are incremented using the files "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 thru 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
4th 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 thru the outer
loop.
label
variable
label
variable
print
run

loopa
a loop 5
loopb
b loop 5
"A,B = $a,$b"
10000

634

LAMMPS Users Manual
if
next
jump
label
variable

$b > 2 then "jump in.script break"
b
in.script loopb
break
b delete

next
jump

a
in.script loopa

Restrictions:
As described above.
Related commands:
jump, include, shell, variable,
Default: none

635

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

package command
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 binsize or split or gpuID or tpa or device or blocksiz
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)
binsize value = size
size = bin size for neighbor list construction (distance units)
split = fraction
fraction = fraction of atoms assigned to GPU (default = 1.0)
gpuID values = first last
first = ID of first GPU to be used on each node
last = ID of last GPU to be used on each node
tpa value = Nthreads
Nthreads = # of GPU threads used per atom
device value = device_type
device_type = kepler or fermi or cypress or generic
blocksize value = size
size = thread block size for pair force computation
intel args = NPhi keyword value ...
Nphi = # of coprocessors 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 coprocessor, -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 coprocessor threads per coprocessor core (default = 4)
tptask value = Ntptask
Ntptask = max number of coprocessor threads per MPI task (default = 240)
no_affinity values = none
kokkos args = keyword value ...
zero or more keyword/value pairs may be appended

636

LAMMPS Users Manual

keywords = neigh or neigh/qeq or newton or binsize or comm or comm/exchange or comm/
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
newton = off or on
off = set Newton pairwise and bonded flags off (default)
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 comm/reverse
comm/exchange value = no or host or device
comm/forward value = no or host 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)
omp args = Nthreads keyword value ...
Nthread = # 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

Examples:
package
package
package
package
package
package
package
package

gpu 1
gpu 1 split 0.75
gpu 2 split -1.0
kokkos neigh half comm device
omp 0 neigh no
omp 4
intel 1
intel 2 omp 4 mode mixed balance 0.5

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, USER-INTEL, KOKKOS, and USER-OMP.
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
637

LAMMPS Users Manual
invoked by other accelerator settings.
The KOKKOS package requires a "-k on" command-line switch respectively, which
invokes a "package kokkos" command with default settings.
For the GPU, USER-INTEL, and USER-OMP 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", "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 Section 5.3 section of the manual 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. There must be at least as
many MPI tasks per node as GPUs, as set by the mpirun or mpiexec command. 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 list calculation
currently cannot be used with hybrid pair styles. 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 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
bins = the size of the pairwise cutoff + neighbor skin distance. This is 2x larger than
the LAMMPS default used for neighbor list building on the CPU. This will be close to
optimal for the GPU, so you do not normally need to use this keyword. Note that if you
use a longer-than-usual pairwise cutoff, e.g. to allow for a smaller fraction of KSpace
638

LAMMPS Users Manual
work with a long-range Coulombic solver because the GPU is faster at performing
pairwise interactions, then it may be optimal to make the binsize smaller than the
default. For example, with a cutoff of 20*sigma in LJ units and a neighbor skin
distance of sigma, a binsize = 5.25*sigma can be more efficient than the default.
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
package gpu 2 split -1

# launch command
# input script command

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 allows selection of which GPUs on each node will be used for a
simulation. The first and last values specify the GPU IDs to use (from 0 to Ngpu-1). By
default, first = 0 and last = Ngpu-1, so that all GPUs are used, assuming Ngpu is set
to the number of physical GPUs. If you only wish to use a subset, set Ngpu to a smaller
number and first/last to a sub-range of the available GPUs.
The tpa keyword sets the number of GPU thread per atom used to perform force
calculations. With a default value of 1, the number of threads 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 threads per atom must
be a power of 2 and currently cannot be greater than 32.
The device keyword can be used to tune parameters optimized for a specific
accelerator, when using OpenCL. For CUDA, the device keyword is ignored.
Currently, the device type is limited to NVIDIA Kepler, NVIDIA Fermi, AMD Cypress,
or a generic device. More devices may be added later. The default device type can be
specified when building LAMMPS with the GPU library, via settings in the
lib/gpu/Makefile that is used.
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
639

LAMMPS Users Manual
the specific GPU hardware. Typical choices are 64, 128, or 256. A larger blocksize
increases occupancy of individual GPU cores, but reduces the total number of thread
blocks, thus may lead to load imbalance.
The intel style invokes settings associated with the use of the USER-INTEL package.
All of its settings, except the omp and mode keywords, are ignored if LAMMPS was
not built with Xeon Phi coprocessor support. All of its settings, including the omp and
mode keyword are applicable if LAMMPS was built with coprocessor support.
The Nphi argument sets the number of coprocessors per node. This can be set to any
value, including 0, if LAMMPS was not built with coprocessor support.
Optional keyword/value pairs can also be specified. Each has a default value as listed
below.
The omp keyword determines the number of OpenMP threads allocated for each MPI
task when any portion of the interactions computed by a USER-INTEL pair style are
run on the CPU. This can be the case even if LAMMPS was built with coprocessor
support; see the balance keyword discussion below. If you are running with less MPI
tasks/node than there are CPUs, it can be advantageous to use OpenMP threading on
the CPUs.
NOTE: The omp keyword has nothing to do with coprocessor threads on the Xeon Phi;
see the tpc and tptask keywords below for a discussion of coprocessor threads.
The Nthread value for the omp keyword sets the number of OpenMP threads allocated
for each MPI task. Setting Nthread = 0 (the default) 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, which is usually a value of 1.
For more details, including examples of how to set the OMP_NUM_THREADS
environment variable, see the discussion of the Nthreads setting on this doc page for
the "package omp" command. Nthreads is a required argument for the USER-OMP
package. Its meaning is exactly the same for the USER-INTEL package.
NOTE: If you build LAMMPS with both the USER-INTEL and USER-OMP packages, be
aware that both packages allow setting of the Nthreads value via their package
commands, but there is only a single global Nthreads value used by OpenMP. Thus if
both package commands are invoked, you should insure the two values are consistent.
If they are not, the last one invoked will take precedence, for both 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.
The mode keyword determines the precision mode to use for computing pair style
forces, either on the CPU or on the coprocessor, when using a USER-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
640

LAMMPS Users Manual
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 Hyperthreading 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 USER-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 preprocessor flag -DLMP_INTEL_USELRT in the
makefile when compiling LAMMPS.
The balance keyword sets the fraction of pair style work offloaded to the coprocessor
for split values between 0.0 and 1.0 inclusive. While this fraction of work is running on
the coprocessor, 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 coprocessor and can also overlap MPI
communication of forces with computation on the coprocessor 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 coprocessor threads Ntpc that will run on each
core of the coprocessor. 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 coprocessor 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 coprocessor. Affinity settings
641

LAMMPS Users Manual
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.
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.
A value of full uses a full neighbor lists and is the default. This performs twice as much
computation as the half option, however that is often a win because it is thread-safe
and doesn't require atomic operations in the calculation of pair forces. For that
reason, full is the default setting. However, when running in MPI-only mode with 1
thread per MPI task, half neighbor lists will typically be faster, just as it is for
non-accelerated pair styles. Similarly, the neigh/qeq keyword determines how
neighbor lists are built for fix qeq/reax/kk. If not explicitly set, the value of neigh/qeq
will match neigh.
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 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 in MPI-only
mode with 1 thread per MPI task, a value of on will typically 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 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 can be set by this keyword. 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.
The comm and comm/exchange and 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 rebuilt. 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.
The comm keyword is simply a short-cut to set the same value for both the
comm/exchange and comm/forward and comm/reverse keywords.
642

LAMMPS Users Manual
The value options for all 3 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.
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 may also be the fastest choice when using Kokkos styles in
MPI-only mode (i.e. with a thread count of 1).
When running on CPUs or Xeon Phi, the host and device values work identically. When
using GPUs, the device value 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. This requires that your MPI is able to access GPU memory directly.
Currently that is true for OpenMPI 1.8 (or later versions), Mvapich2 1.9 (or later), and
CrayMPI. If your script uses styles (e.g. fixes) which are not yet supported by the
KOKKOS package, then data has to be move 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.
The omp style invokes settings associated with the use of the USER-OMP package.
The Nthread 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 Nthread = 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 2nd example
line above is for MPICH; the 3rd example line with -x is for OpenMPI. Check your MPI
643

LAMMPS Users Manual
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 USER-OMP package and the parallel
efficiency can be very different, too.
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.
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 Making LAMMPS section for more info.
The intel style of this command can only be invoked if LAMMPS was built with the
USER-INTEL package. See the Making LAMMPS section for more info.
The kk style of this command can only be invoked if LAMMPS was built with the
KOKKOS package. See the Making LAMMPS section for more info.
The omp style of this command can only be invoked if LAMMPS was built with the
USER-OMP package. See the Making LAMMPS section for more info.
Related commands:
suffix, "-pk" command-line setting
Default:
For the GPU package, the default is Ngpu = 1 and the option defaults are neigh = yes,
newton = off, binsize = 0.0, split = 1.0, gpuID = 0 to Ngpu-1, tpa = 1, and device =
not used. 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 USER-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"
644

LAMMPS Users Manual
and "mode", are ignored if LAMMPS was not built with Xeon Phi coprocessor 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 or
via the "-pk intel" command-line switch.
For the KOKKOS package, the option defaults neigh = full, neigh/qeq = full, newton =
off, binsize = 0.0, and comm = device. These settings are made automatically by the
required "-k on" command-line switch. You can change them bu using the package
kokkos command in your input script or via the "-pk kokkos" command-line switch.
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.

645

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

pair_coeff command
Syntax:
pair_coeff I J args

• I,J = atom types (see asterisk form below)
• args = coefficients for one or more pairs of atom types
Examples:
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff
pair_coeff

1 2 1.0 1.0 2.5
2 * 1.0 1.0
3* 1*2 1.0 1.0 2.5
* * 1.0 1.0
* * nialhjea 1 1 2
* 3 morse.table ENTRY1
1 2 lj/cut 1.0 1.0 2.5 (for pair_style hybrid)

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 1st 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
646

LAMMPS Users Manual
in a data file, the line corresponding to the 1st example above would be listed as
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 doc 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.
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 the directory specified by the LAMMPS_POTENTIALS
environment variable. Thus if this is set to the potentials directory in the LAMMPS
distro, 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 alphabetic list of pair styles defined in LAMMPS is given on the pair_style doc
page. They are also given in more compact form in the pair section of this page.
Click on the style to display the formula it computes, arguments specified in the
pair_style command, and coefficients specified by the associated pair_coeff command.
Note that there are also additional pair styles (not listed on the pair_style doc page)
submitted by users which are included in the LAMMPS distribution. The list of these
with links to the individual styles are given in the pair section of this page.
There are also additional accelerated pair styles (not listed on the pair_style doc page)
included in the LAMMPS distribution for faster performance on CPUs and GPUs. The
647

LAMMPS Users Manual
list of these with links to the individual styles are given in the pair section of this page.
Restrictions:
This command must come after the simulation box is defined by a read_data,
read_restart, or create_box command.
Related commands:
pair_style, pair_modify, read_data, read_restart, pair_write
Default: none

648

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

pair_modify command
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
pair values = sub-style N special which wt1 wt2 wt3
or sub-style N compute/tally flag
sub-style = sub-style of pair hybrid
N = which instance of sub-style (only if sub-style is used multiple times)
special which wt1 wt2 wt3 = override special_bonds settings (optional)
which = lj/coul or lj or coul
w1,w2,w3 = 1-2, 1-3, and 1-4 weights from 0.0 to 1.0 inclusive
compute/tally flag = yes or no
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

Examples:
pair_modify
pair_modify
pair_modify
pair_modify
pair_modify
pair_modify

shift yes mix geometric
tail yes
table 12
pair lj/cut compute no
pair tersoff compute/tally no
pair lj/cut/coul/long 1 special lj/coul 0.0 0.0 0.0

Description:
Modify the parameters of the currently defined pair style. Not all parameters are
relevant to all pair styles.
If used, the pair keyword must appear first in the list of keywords. It can only be used
with the hybrid and hybrid/overlay pair styles. It means 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. Note that if the pair keyword is
not used, and the pair style is hybrid or hybrid/overlay, then all the specified keywords
649

LAMMPS Users Manual
will be applied to all sub-styles.
The special and compute/tally keywords can only be used in conjunction with the pair
keyword and must directly follow it. special allows to override the special_bonds
settings for the specified sub-style. compute/tally allows to disable or enable
registering compute */tally computes for a given sub-style. More details are given
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. Also, some mix options are not available
for certain pair styles. See the doc page for individual pair styles for those restrictions.
Note also that the pair_coeff command also can be to directly set coefficients for a
specific I != J pairing, in which case no mixing is performed.
mix geometric
epsilon_ij = sqrt(epsilon_i * epsilon_j)
sigma_ij = sqrt(sigma_i * sigma_j)

mix arithmetic
epsilon_ij = sqrt(epsilon_i * epsilon_j)
sigma_ij = (sigma_i + sigma_j) / 2

mix sixthpower
epsilon_ij = (2 * sqrt(epsilon_i*epsilon_j) * sigma_i^3 * sigma_j^3) /
(sigma_i^6 + sigma_j^6)
sigma_ij = ((sigma_i**6 + sigma_j**6) / 2) ^ (1/6)

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.
The table and table/disp keywords apply to pair styles with a long-range Coulombic
term or long-range dispersion term respectively; see the doc 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.
650

LAMMPS Users Manual
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 doc 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 updates to relect the changed atom count. If this is a large effect in your
651

LAMMPS Users Manual
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.
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 special keyword allows to override the 1-2, 1-3, and 1-4 exclusion settings for
individual sub-styles of a hybrid pair style. It requires 4 arguments similar to the
special_bonds command, which and wt1,wt2,wt3. The which argument can be lj to
change the Lennard-Jones settings, coul to change the Coulombic settings, or lj/coul to
change both to the same set of 3 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 only be used in conjunction with the pair
keyword and has to directly follow it.
NOTE: The global settings specified by the special_bonds command affect the
construction of neighbor lists. Weights of 0.0 (for 1-2, 1-3, or 1-4 neighbors) exclude
those pairs from the neighbor list entirely. Weights of 1.0 store the neighbor with no
weighting applied. Thus only global values different from exactly 0.0 or 1.0 can be
overridden and an error is generated if the requested setting is not compatible with
the global setting. Substituting 1.0e-10 for 0.0 and 0.9999999999 for 1.0 is usually a
sufficient workaround in this case without causing a significant error.
The compute/tally keyword takes exactly 1 argument (no or yes), and allows to
selectively disable or enable processing of the various compute */tally styles for a
given pair hybrid or hybrid/overlay sub-style.
NOTE: Any "pair_modify pair compute/tally" command must be issued before the
corresponding compute style is defined.
Restrictions: none
You cannot use shift yes with tail yes, since those are conflicting options. You cannot
use tail yes with 2d simulations.
Related commands:
652

LAMMPS Users Manual
pair_style, >pair_style hybrid, pair_coeff, thermo_style, compute */tally
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).

653

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

pair_style command
Syntax:
pair_style style args

• style = one of the styles from the list below
• args = arguments used by a particular style
Examples:
pair_style
pair_style
pair_style
pair_style
pair_style

lj/cut 2.5
eam/alloy
hybrid lj/charmm/coul/long 10.0 eam
table linear 1000
none

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 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
654

LAMMPS Users Manual
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 given in
more compact form in the pair section of this page.
Click on the style to display the formula it computes, arguments specified in the
pair_style command, and coefficients specified by the associated pair_coeff command.
There are also additional pair styles (not listed here) submitted by users which are
included in the LAMMPS distribution. The list of these with links to the individual
styles are given in the pair section of this page.
There are also additional accelerated pair styles (not listed here) included in the
LAMMPS distribution for faster performance on CPUs and GPUs. The list of these with
links to the individual styles are given in the pair section of this page.
• pair_style
• pair_style
• pair_style
• pair_style

none - turn off pairwise interactions
hybrid - multiple styles of pairwise interactions
hybrid/overlay - multiple styles of superposed pairwise interactions
zero - neighbor list but no interactions

• pair_style adp - angular dependent potential (ADP) of Mishin
• pair_style airebo - AIREBO potential of Stuart
• pair_style airebo/morse - AIREBO with Morse instead of LJ
• pair_style beck - Beck potential
• pair_style body - interactions between body particles
• pair_style bop - BOP potential of Pettifor
• pair_style born - Born-Mayer-Huggins potential
• pair_style born/coul/long - Born-Mayer-Huggins with long-range Coulombics
• pair_style born/coul/long/cs - Born-Mayer-Huggins with long-range Coulombics
and core/shell
• pair_style born/coul/msm - Born-Mayer-Huggins with long-range MSM
Coulombics
• pair_style born/coul/wolf - Born-Mayer-Huggins with Coulombics via Wolf
potential
• pair_style brownian - Brownian potential for Fast Lubrication Dynamics
• pair_style brownian/poly - Brownian potential for Fast Lubrication Dynamics
with polydispersity
• pair_style buck - Buckingham potential
• pair_style buck/coul/cut - Buckingham with cutoff Coulomb
• pair_style buck/coul/long - Buckingham with long-range Coulombics
655

LAMMPS Users Manual
• pair_style buck/coul/long/cs - Buckingham with long-range Coulombics and
core/shell
• pair_style buck/coul/msm - Buckingham long-range MSM Coulombics
• pair_style buck/long/coul/long - long-range Buckingham with long-range
Coulombics
• pair_style colloid - integrated colloidal potential
• pair_style comb - charge-optimized many-body (COMB) potential
• pair_style comb3 - charge-optimized many-body (COMB3) potential
• pair_style coul/cut - cutoff Coulombic potential
• pair_style coul/debye - cutoff Coulombic potential with Debye screening
• pair_style coul/dsf - Coulombics via damped shifted forces
• pair_style coul/long - long-range Coulombic potential
• pair_style coul/long/cs - long-range Coulombic potential and core/shell
• pair_style coul/msm - long-range MSM Coulombics
• pair_style coul/streitz - Coulombics via Streitz/Mintmire Slater orbitals
• pair_style coul/wolf - Coulombics via Wolf potential
• pair_style dpd - dissipative particle dynamics (DPD)
• pair_style dpd/tstat - DPD thermostatting
• pair_style dsmc - Direct Simulation Monte Carlo (DSMC)
• pair_style eam - embedded atom method (EAM)
• pair_style eam/alloy - alloy EAM
• pair_style eam/fs - Finnis-Sinclair EAM
• pair_style eim - embedded ion method (EIM)
• pair_style gauss - Gaussian potential
• pair_style gayberne - Gay-Berne ellipsoidal potential
• pair_style gran/hertz/history - granular potential with Hertzian interactions
• pair_style gran/hooke - granular potential with history effects
• pair_style gran/hooke/history - granular potential without history effects
• pair_style hbond/dreiding/lj - DREIDING hydrogen bonding LJ potential
• pair_style hbond/dreiding/morse - DREIDING hydrogen bonding Morse potential
• pair_style kim - interface to potentials provided by KIM project
• pair_style lcbop - long-range bond-order potential (LCBOP)
• pair_style line/lj - LJ potential between line segments
• pair_style lj/charmm/coul/charmm - CHARMM potential with cutoff Coulomb
• pair_style lj/charmm/coul/charmm/implicit - CHARMM for implicit solvent
• pair_style lj/charmm/coul/long - CHARMM with long-range Coulomb
• pair_style lj/charmm/coul/msm - CHARMM with long-range MSM Coulombics
• pair_style lj/class2 - COMPASS (class 2) force field with no Coulomb
• pair_style lj/class2/coul/cut - COMPASS with cutoff Coulomb
• pair_style lj/class2/coul/long - COMPASS with long-range Coulomb
• pair_style lj/cubic - LJ with cubic after inflection point
• pair_style lj/cut - cutoff Lennard-Jones potential with no Coulomb
• pair_style lj/cut/coul/cut - LJ with cutoff Coulomb
• pair_style lj/cut/coul/debye - LJ with Debye screening added to Coulomb
• pair_style lj/cut/coul/dsf - LJ with Coulombics via damped shifted forces
• pair_style lj/cut/coul/long - LJ with long-range Coulombics
• pair_style lj/cut/coul/long/cs - LJ with long-range Coulombics and core/shell
• pair_style lj/cut/coul/msm - LJ with long-range MSM Coulombics
• pair_style lj/cut/dipole/cut - point dipoles with cutoff
• pair_style lj/cut/dipole/long - point dipoles with long-range Ewald
• pair_style lj/cut/tip4p/cut - LJ with cutoff Coulomb for TIP4P water
656

LAMMPS Users Manual
• pair_style lj/cut/tip4p/long - LJ with long-range Coulomb for TIP4P water
• pair_style lj/expand - Lennard-Jones for variable size particles
• pair_style lj/gromacs - GROMACS-style Lennard-Jones potential
• pair_style lj/gromacs/coul/gromacs - GROMACS-style LJ and Coulombic
potential
• pair_style lj/long/coul/long - long-range LJ and long-range Coulombics
• pair_style lj/long/dipole/long - long-range LJ and long-range point dipoles
• pair_style lj/long/tip4p/long - long-range LJ and long-range Coulomb for TIP4P
water
• pair_style lj/smooth - smoothed Lennard-Jones potential
• pair_style lj/smooth/linear - linear smoothed Lennard-Jones potential
• pair_style lj96/cut - Lennard-Jones 9/6 potential
• pair_style lubricate - hydrodynamic lubrication forces
• pair_style lubricate/poly - hydrodynamic lubrication forces with polydispersity
• pair_style lubricateU - hydrodynamic lubrication forces for Fast Lubrication
Dynamics
• pair_style lubricateU/poly - hydrodynamic lubrication forces for Fast
Lubrication with polydispersity
• pair_style meam - modified embedded atom method (MEAM)
• pair_style mie/cut - Mie potential
• pair_style morse - Morse potential
• pair_style nb3b/harmonic - nonbonded 3-body harmonic potential
• pair_style nm/cut - N-M potential
• pair_style nm/cut/coul/cut - N-M potential with cutoff Coulomb
• pair_style nm/cut/coul/long - N-M potential with long-range Coulombics
• pair_style peri/eps - peridynamic EPS potential
• pair_style peri/lps - peridynamic LPS potential
• pair_style peri/pmb - peridynamic PMB potential
• pair_style peri/ves - peridynamic VES potential
• pair_style polymorphic - polymorphic 3-body potential
• pair_style reax - ReaxFF potential
• pair_style rebo - 2nd generation REBO potential of Brenner
• pair_style resquared - Everaers RE-Squared ellipsoidal potential
• pair_style snap - SNAP quantum-accurate potential
• pair_style soft - Soft (cosine) potential
• pair_style sw - Stillinger-Weber 3-body potential
• pair_style table - tabulated pair potential
• pair_style tersoff - Tersoff 3-body potential
• pair_style tersoff/mod - modified Tersoff 3-body potential
• pair_style tersoff/zbl - Tersoff/ZBL 3-body potential
• pair_style tip4p/cut - Coulomb for TIP4P water w/out LJ
• pair_style tip4p/long - long-range Coulombics for TIP4P water w/out LJ
• pair_style tri/lj - LJ potential between triangles
• pair_style vashishta - Vashishta 2-body and 3-body potential
• pair_style yukawa - Yukawa potential
• pair_style yukawa/colloid - screened Yukawa potential for finite-size particles
• pair_style zbl - Ziegler-Biersack-Littmark potential
Restrictions:

657

LAMMPS Users Manual
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 Making LAMMPS section for more info on packages.
The doc pages for individual pair potentials tell if it is part of a package.
Related commands:
pair_coeff, read_data, pair_modify, kspace_style, dielectric, pair_write
Default:
pair_style none

658

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

pair_write command
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)
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

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.
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.
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).
Restrictions:
659

LAMMPS Users Manual
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.
Related commands:
pair_style table, pair_style, pair_coeff
Default: none

660

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

partition command
Syntax:
partition style N command ...

• style = yes or no
• N = partition number (see asterisk form below)
• command = any LAMMPS command
Examples:
partition
partition
partition
partition

yes 1 processors 4 10 6
no 5 print "Active partition"
yes *5 fix all nve
yes 6* fix all nvt temp 1.0 1.0 0.1

Description:
This command invokes the specified command on a subset of the partitions of
processors you have defined via the -partition command-line switch. See Section 2.6
for an explanation of the 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
1st 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).

661

LAMMPS Users Manual
This command can be useful for the "run_style verlet/split" command which imposed
requirements on how the processors command lays out a 3d grid of processors in each
of 2 partitions.
Restrictions: none
Related commands:
run_style verlet/split
Default: none

662

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

prd command
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

Examples:
prd 5000 100 10 10 100 1 54982
prd 5000 100 10 10 100 1 54982 min 0.1 0.1 100 200

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 this paper by Art Voter. It 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 for such systems in given in this
review paper from the same 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. Running multiple replicas gives an
effective enhancement in the timescale spanned by the multiple simulations, while
663

LAMMPS Users Manual
waiting for an event to occur.
Each replica runs on a partition of one or more processors. Processor partitions are
defined at run-time using the -partition command-line switch; see Section 2.6 of the
manual. 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 Section 6.5 of the
manual 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 defined 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 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.
664

LAMMPS Users Manual
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.
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
665

LAMMPS Users Manual
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 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
666

LAMMPS Users Manual
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.
Restrictions:
This command can only be used if LAMMPS was built with the REPLICA package. See
the Making LAMMPS section for more info on packages.
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.
Related commands:
compute event/displace, min_modify, min_style, run_style, minimize, velocity, temper,
neb, tad
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).
667

LAMMPS Users Manual
(Voter2002) Voter, Montalenti, Germann, Annual Review of Materials Research 32,
321 (2002).

668

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

print command
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

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 """
System volume = $v
System temperature = $t
"""

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 individual 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
669

LAMMPS Users Manual
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 properties, group
properties, thermodynamic properties, global values calculated by a compute or fix, or
references to other variables.
Restrictions: none
Related commands:
fix print, variable
Default:
The option defaults are no file output, screen = yes, and universe = no.

670

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

processors command
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

Examples:
processors
processors
processors
processors
processors
processors
processors

*
2
*
*
*
4
*

*
4
*
*
*
8
*

5
4
8 map xyz
* grid numa
* grid twolevel 4 * * 1
16 grid custom myfile
* part 1 2 multiple

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
671

LAMMPS Users Manual
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 this section for an explanation of the -partition command-line
switch. 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.

672

LAMMPS Users Manual
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 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

673

LAMMPS Users Manual
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:
proc
proc
proc
proc
proc
proc
proc
proc

0
1
2
3
4
5
6
7

=
=
=
=
=
=
=
=

lo
hi
lo
hi
lo
hi
lo
hi

x,
x,
x,
x,
x,
x,
x,
x,

lo
lo
hi
hi
lo
lo
hi
hi

y,
y,
y,
y,
y,
y,
y,
y,

lo
lo
lo
lo
hi
hi
hi
hi

z
z
z
z
z
z
z
z

octant
octant
octant
octant
octant
octant
octant
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
674

LAMMPS Users Manual
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 "processors" 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
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.
Restrictions:
This command cannot be used after the simulation box is defined by a read_data or
675

LAMMPS Users Manual
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.
Related commands:
partition, -reorder command-line switch
Default:
The option defaults are Px Py Pz = * * *, grid = onelevel, and map = cart.

676

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

python command
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 sou
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
varReturn = v_name = LAMMPS variable name which return value of function will be as
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

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

677

LAMMPS Users Manual
for i in range(N):
cut = cut0 + i*0.1
lmp.set_variable("cut",cut)
lmp.command("pair_style lj/cut ${cut}")
lmp.command("pair_coeff * * 1.0 1.0")
lmp.command("run 100")
"""

# set a variable in LAMMPS
# LAMMPS commands

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 in Section 11.
There is an examples/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.

678

LAMMPS Users Manual
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

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
679

LAMMPS Users Manual
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 Section
3.2, 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:
nsteplast = -1
nvaluelast = 0
def expensive(nstep):
global nsteplast,nvaluelast
if nstep == nsteplast: return nvaluelast
nsteplast = nstep

680

LAMMPS Users Manual
# 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"')
...

681

LAMMPS Users Manual
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
Python module lammps.py in the python dir of the distribution. 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
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.
Section 11.7 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)
lmp.command("pair_style lj/cut ${cut}")
#lmp.command("pair_style lj/cut %d" % cut)

# set a variable in LAMMPS
# LAMMPS command
# LAMMPS command option

lmp.command("pair_coeff * * 1.0 1.0")
lmp.command("run 10")
pe = lmp.extract_compute("thermo_pe",0,0)
print "PE",pe/natoms,thresh
if pe/natoms 

---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Page Count                      : 2195
Page Layout                     : SinglePage
Page Mode                       : UseNone
Producer                        : htmldoc 1.8.28 Copyright 1997-2006 Easy Software Products, All Rights Reserved.
Create Date                     : 2018:03:16 15:00:16
Title                           : LAMMPS Users Manual
Author                          : http://lammps.sandia.gov - Sandia National Laboratories, Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License.

EXIF Metadata provided by EXIF.tools