LAMMPS Users Manual

User Manual:

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

Download
Open PDF In Browser	View PDF

LAMMPS Users Manual
31 Mar 2017 version
http://lammps.sandia.gov - Sandia National Laboratories
Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License.

LAMMPS Users Manual

Table of Contents
LAMMPS Documentation.......................................................................................................................1
31 Mar 2017 version..........................................................................................................................1
Version info:...............................................................................................................................1
1. Introduction...................................................................................................................................4
1.1 What is LAMMPS................................................................................................................4
1.2 LAMMPS features................................................................................................................5
1.3 LAMMPS non-features.........................................................................................................8
1.4 Open source distribution.....................................................................................................10
1.5 Acknowledgments and citations.........................................................................................11
2. Getting Started.............................................................................................................................13
2.1 What's in the LAMMPS distribution..................................................................................13
2.2 Making LAMMPS..............................................................................................................14
2.3 Making LAMMPS with optional packages........................................................................22
2.4 Building LAMMPS via the Make.py tool..........................................................................26
2.5 Building LAMMPS as a library..........................................................................................28
2.6 Running LAMMPS.............................................................................................................30
2.7 Command-line options........................................................................................................32
2.8 LAMMPS screen output.....................................................................................................38
2.9 Tips for users of previous LAMMPS versions...................................................................40
3. Commands...................................................................................................................................42
3.1 LAMMPS input script........................................................................................................42
3.2 Parsing rules........................................................................................................................43
3.3 Input script structure...........................................................................................................44
3.4 Commands listed by category.............................................................................................46
3.5 Individual commands..........................................................................................................47
Fix styles...................................................................................................................................47
Compute styles..........................................................................................................................48
Pair_style potentials..................................................................................................................49
Bond_style potentials................................................................................................................50
Angle_style potentials...............................................................................................................51
Dihedral_style potentials..........................................................................................................51
Improper_style potentials.........................................................................................................51
Kspace solvers..........................................................................................................................52
4. Packages......................................................................................................................................53
4.1 Standard packages...............................................................................................................53
4.2 User packages.....................................................................................................................70
5. Accelerating LAMMPS performance.........................................................................................84
5.1 Measuring performance......................................................................................................84
5.2 General strategies................................................................................................................85
5.3 Packages with optimized styles..........................................................................................86
5.4 Comparison of various accelerator packages......................................................................89
6. How-to discussions....................................................................................................................115
6.1 Restarting a simulation.....................................................................................................115
6.2 2d simulations...................................................................................................................117
6.3 CHARMM, AMBER, and DREIDING force fields.........................................................117
6.4 Running multiple simulations from one input script........................................................119
6.5 Multi-replica simulations..................................................................................................120
6.6 Granular models................................................................................................................121
i

LAMMPS Users Manual

Table of Contents
6.7 TIP3P water model...........................................................................................................122
6.8 TIP4P water model...........................................................................................................123
6.9 SPC water model..............................................................................................................124
6.10 Coupling LAMMPS to other codes................................................................................125
6.11 Visualizing LAMMPS snapshots....................................................................................126
6.12 Triclinic (non-orthogonal) simulation boxes..................................................................127
6.13 NEMD simulations.........................................................................................................131
6.14 Finite-size spherical and aspherical particles..................................................................132
6.15 Output from LAMMPS (thermo, dumps, computes, fixes, variables)...........................135
6.16 Thermostatting, barostatting, and computing temperature.............................................140
6.17 Walls...............................................................................................................................142
6.18 Elastic constants..............................................................................................................143
6.19 Library interface to LAMMPS.......................................................................................143
6.20 Calculating thermal conductivity....................................................................................146
6.21 Calculating viscosity.......................................................................................................147
6.22 Calculating a diffusion coefficient..................................................................................149
6.23 Using chunks to calculate system properties..................................................................149
6.24 Setting parameters for the kspace_style pppm/disp command.......................................152
6.25 Polarizable models..........................................................................................................153
6.26 Adiabatic core/shell model.............................................................................................154
6.27 Drude induced dipoles....................................................................................................157
7. Example problems.....................................................................................................................160
Lowercase directories.............................................................................................................160
Uppercase directories..............................................................................................................162
8. Performance & scalability.........................................................................................................163
9. Additional tools.........................................................................................................................165
amber2lmp tool.......................................................................................................................165
binary2txt tool.........................................................................................................................165
ch2lmp tool.............................................................................................................................166
chain tool.................................................................................................................................166
colvars tools............................................................................................................................166
createatoms tool......................................................................................................................166
drude tool................................................................................................................................167
eam database tool....................................................................................................................167
eam generate tool....................................................................................................................167
eff tool.....................................................................................................................................167
emacs tool...............................................................................................................................167
fep tool....................................................................................................................................167
i-pi tool....................................................................................................................................168
ipp tool....................................................................................................................................168
kate tool...................................................................................................................................168
lmp2arc tool............................................................................................................................168
lmp2cfg tool............................................................................................................................168
matlab tool..............................................................................................................................169
micelle2d tool.........................................................................................................................169
moltemplate tool.....................................................................................................................169
msi2lmp tool...........................................................................................................................169
phonon tool.............................................................................................................................169
ii

LAMMPS Users Manual

Table of Contents
polybond tool..........................................................................................................................170
pymol_asphere tool.................................................................................................................170
python tool..............................................................................................................................170
reax tool..................................................................................................................................170
smd tool...................................................................................................................................170
vim tool...................................................................................................................................171
xmgrace tool...........................................................................................................................171
10. Modifying & extending LAMMPS.........................................................................................172
10.1 Atom styles.....................................................................................................................173
10.2 Bond, angle, dihedral, improper potentials.....................................................................175
10.3 Compute styles................................................................................................................175
10.4 Dump styles....................................................................................................................176
10.5 Dump custom output options..........................................................................................176
10.6 Fix styles.........................................................................................................................177
10.7 Input script commands....................................................................................................179
10.8 Kspace computations......................................................................................................179
10.9 Minimization styles.........................................................................................................179
10.10 Pairwise potentials........................................................................................................180
10.11 Region styles.................................................................................................................180
10.12 Body styles....................................................................................................................180
10.13 Thermodynamic output options....................................................................................181
10.14 Variable options............................................................................................................181
10.15 Submitting new features for inclusion in LAMMPS....................................................182
11. Python interface to LAMMPS.................................................................................................186
11.1 Overview of running LAMMPS from Python................................................................187
11.2 Overview of using Python from a LAMMPS script.......................................................187
11.3 Building LAMMPS as a shared library..........................................................................188
11.4 Installing the Python wrapper into Python.....................................................................189
11.5 Extending Python with MPI to run in parallel................................................................190
11.6 Testing the Python-LAMMPS interface.........................................................................192
11.7 Using LAMMPS from Python........................................................................................194
11.8 Example Python scripts that use LAMMPS...................................................................197
11.9 PyLammps interface.......................................................................................................199
12. Errors.......................................................................................................................................200
12.1 Common problems..........................................................................................................200
12.2 Reporting bugs................................................................................................................201
12.3 Error & warning messages..............................................................................................202
Errors:.....................................................................................................................................202
Warnings:................................................................................................................................307
13. Future and history....................................................................................................................317
13.1 Coming attractions..........................................................................................................317
13.2 Past versions...................................................................................................................317
Tutorial for Thermalized Drude oscillators in LAMMPS.............................................................320
LAMMPS GitHub tutorial.............................................................................................................327
PyLammps Tutorial........................................................................................................................................342
Body particles......................................................................................................................................343
Manifolds (surfaces)......................................................................................................................347
iii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
angle_coeff command...................................................................................................................348
angle_style command....................................................................................................................350
atom_modify command.................................................................................................................352
atom_style command.....................................................................................................................355
balance command..........................................................................................................................360
bond_coeff command....................................................................................................................368
bond_style command.....................................................................................................................370
bond_write command....................................................................................................................372
boundary command.......................................................................................................................373
box command................................................................................................................................375
change_box command...................................................................................................................376
clear command..............................................................................................................................381
comm_modify command...............................................................................................................382
comm_style command...................................................................................................................385
compute command........................................................................................................................386
compute_modify command...........................................................................................................390
create_atoms command.................................................................................................................392
create_bonds command.................................................................................................................397
create_box command.....................................................................................................................399
delete_atoms command.................................................................................................................402
delete_bonds command.................................................................................................................405
dielectric command.......................................................................................................................408
dihedral_coeff command...............................................................................................................409
dihedral_style command................................................................................................................411
dimension command......................................................................................................................413
displace_atoms command..............................................................................................................414
dump command.............................................................................................................................416
dump custom/vtk command..........................................................................................................416
dump h5md command...................................................................................................................416
dump image command..................................................................................................................416
dump movie command..................................................................................................................416
dump molfile command.................................................................................................................416
dump nc command........................................................................................................................416
dump custom/vtk command..........................................................................................................426
dump h5md command...................................................................................................................431
dump image command..................................................................................................................433
dump movie command..................................................................................................................433
dump_modify command................................................................................................................443
dump molfile command.................................................................................................................456
dump nc command........................................................................................................................458
dump nc/mpiio command..............................................................................................................458
echo command...............................................................................................................................459
fix command..................................................................................................................................460
fix_modify command....................................................................................................................465
group command.............................................................................................................................467
group2ndx command.....................................................................................................................472
ndx2group command.....................................................................................................................472
iv

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
if command....................................................................................................................................473
improper_coeff command.............................................................................................................476
improper_style command..............................................................................................................478
include command..........................................................................................................................480
info command................................................................................................................................481
jump command..............................................................................................................................483
kspace_modify command..............................................................................................................486
kspace_style command..................................................................................................................491
label command..............................................................................................................................497
lattice command............................................................................................................................498
log command.................................................................................................................................502
mass command..............................................................................................................................503
min_modify command..................................................................................................................505
min_style command......................................................................................................................507
minimize command.......................................................................................................................509
molecule command........................................................................................................................513
neb command................................................................................................................................520
neigh_modify command................................................................................................................526
neighbor command........................................................................................................................530
newton command..........................................................................................................................532
next command...............................................................................................................................533
package command.........................................................................................................................536
pair_coeff command......................................................................................................................545
pair_modify command..................................................................................................................548
pair_style command......................................................................................................................552
pair_write command......................................................................................................................556
partition command.........................................................................................................................558
prd command.................................................................................................................................560
print command...............................................................................................................................565
processors command.....................................................................................................................567
python command...........................................................................................................................572
quit command................................................................................................................................580
read_data command.......................................................................................................................581
read_dump command....................................................................................................................598
read_restart command...................................................................................................................603
region command............................................................................................................................607
replicate command........................................................................................................................613
rerun command..............................................................................................................................615
reset_timestep command...............................................................................................................618
restart command............................................................................................................................619
run command.................................................................................................................................622
run_style command.......................................................................................................................626
set command..................................................................................................................................631
shell command...............................................................................................................................638
special_bonds command................................................................................................................640
suffix command.............................................................................................................................644
tad command.................................................................................................................................646
v

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
temper command...........................................................................................................................651
temper/grem command..................................................................................................................654
thermo command...........................................................................................................................656
thermo_modify command.............................................................................................................657
thermo_style command.................................................................................................................660
timer command..............................................................................................................................666
timestep command.........................................................................................................................668
uncompute command....................................................................................................................669
undump command.........................................................................................................................670
unfix command..............................................................................................................................671
units command..............................................................................................................................672
variable command.........................................................................................................................676
Numbers, constants, and thermo keywords............................................................................683
Math Operators.......................................................................................................................683
Math Functions.......................................................................................................................684
Group and Region Functions..................................................................................................686
Special Functions....................................................................................................................686
Feature Functions....................................................................................................................687
Atom Values and Vectors.......................................................................................................688
Compute References...............................................................................................................689
Fix References........................................................................................................................690
Variable References................................................................................................................690
velocity command.........................................................................................................................695
write_coeff command....................................................................................................................699
write_data command.....................................................................................................................700
write_dump command...................................................................................................................702
write_restart command..................................................................................................................704
fix adapt command........................................................................................................................706
fix adapt/fep command..................................................................................................................710
fix addforce command...................................................................................................................714
fix addtorque command.................................................................................................................717
fix append/atoms command...........................................................................................................719
fix atc command............................................................................................................................721
fix atom/swap command...............................................................................................................727
fix ave/atom command..................................................................................................................730
fix ave/chunk command................................................................................................................733
fix ave/correlate command............................................................................................................740
fix ave/correlate/long command....................................................................................................745
fix ave/histo command..................................................................................................................748
fix ave/histo/weight command......................................................................................................748
fix ave/time command...................................................................................................................754
fix aveforce command...................................................................................................................759
fix balance command.....................................................................................................................761
fix bond/break command...............................................................................................................767
fix bond/create command..............................................................................................................770
fix bond/swap command...............................................................................................................774
fix box/relax command..................................................................................................................777
vi

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
fix cmap command........................................................................................................................783
fix colvars command.....................................................................................................................785
fix controller command.................................................................................................................787
fix deform command.....................................................................................................................791
fix deform/kk command................................................................................................................791
fix deposit command.....................................................................................................................800
fix dpd/energy command...............................................................................................................805
fix drag command..........................................................................................................................807
fix drude command........................................................................................................................808
fix drude/transform/direct command.............................................................................................809
fix drude/transform/inverse command..........................................................................................809
fix dt/reset command.....................................................................................................................812
fix efield command........................................................................................................................814
fix ehex command.........................................................................................................................817
fix enforce2d command.................................................................................................................820
fix eos/cv command.......................................................................................................................821
fix eos/table command...................................................................................................................822
fix eos/table/rx command..............................................................................................................824
fix evaporate command.................................................................................................................827
fix external command....................................................................................................................829
fix filter/corotate command...........................................................................................................832
fix flow/gauss command...............................................................................................................834
fix freeze command.......................................................................................................................837
fix gcmc command........................................................................................................................839
fix gld command............................................................................................................................846
fix gle command............................................................................................................................849
fix gravity command.....................................................................................................................852
fix gravity/omp command.............................................................................................................852
fix grem command.........................................................................................................................855
fix halt command...........................................................................................................................857
fix heat command..........................................................................................................................860
fix imd command...........................................................................................................................862
fix indent command.......................................................................................................................865
fix ipi command.............................................................................................................................868
fix langevin command...................................................................................................................870
fix langevin/kk command..............................................................................................................870
fix langevin/drude command.........................................................................................................875
fix langevin/eff command.............................................................................................................879
fix lb/fluid command.....................................................................................................................881
fix lb/momentum command..........................................................................................................888
fix lb/pc command.........................................................................................................................890
fix lb/rigid/pc/sphere command.....................................................................................................891
fix lb/viscous command.................................................................................................................894
fix lineforce command...................................................................................................................896
fix manifoldforce command..........................................................................................................897
fix meso command........................................................................................................................898
fix meso/stationary command.......................................................................................................899
vii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
fix momentum command...............................................................................................................900
fix momentum/kk command.........................................................................................................900
fix move command........................................................................................................................902
fix mscg command........................................................................................................................906
fix msst command........................................................................................................................908
fix neb command...........................................................................................................................911
fix nvt command............................................................................................................................913
fix nvt/intel command...................................................................................................................913
fix nvt/kk command.......................................................................................................................913
fix nvt/omp command...................................................................................................................913
fix npt command............................................................................................................................913
fix npt/intel command...................................................................................................................913
fix npt/kk command.......................................................................................................................913
fix npt/omp command...................................................................................................................913
fix nph command...........................................................................................................................913
fix nph/kk command......................................................................................................................913
fix nph/omp command...................................................................................................................913
fix nvt/eff command......................................................................................................................923
fix npt/eff command......................................................................................................................923
fix nph/eff command.....................................................................................................................923
fix nph/asphere command.............................................................................................................926
fix nph/asphere/omp command.....................................................................................................926
fix nph/body command..................................................................................................................929
fix nph/sphere command...............................................................................................................932
fix nph/sphere/omp command.......................................................................................................932
fix nphug command.......................................................................................................................935
fix nphug/omp command...............................................................................................................935
fix npt/asphere command..............................................................................................................939
fix npt/asphere/omp command......................................................................................................939
fix npt/body command...................................................................................................................942
fix npt/sphere command................................................................................................................945
fix npt/sphere/omp command........................................................................................................945
fix nve command...........................................................................................................................948
fix nve/intel command...................................................................................................................948
fix nve/kk command......................................................................................................................948
fix nve/omp command...................................................................................................................948
fix nve/asphere command..............................................................................................................950
fix nve/asphere/intel command.....................................................................................................950
fix nve/asphere/noforce command................................................................................................952
fix nve/body command..................................................................................................................953
fix nve/dot command.....................................................................................................................954
fix nve/dotc/langevin command....................................................................................................955
fix nve/eff command.....................................................................................................................957
fix nve/limit command..................................................................................................................958
fix nve/line command....................................................................................................................960
fix nve/manifold/rattle command..................................................................................................961
fix nve/noforce command..............................................................................................................963
viii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
fix nve/sphere command...............................................................................................................964
fix nve/sphere/omp command.......................................................................................................964
fix nve/tri command......................................................................................................................966
fix nvk command...........................................................................................................................967
fix nvt/asphere command..............................................................................................................969
fix nvt/asphere/omp command......................................................................................................969
fix nvt/body command...................................................................................................................972
fix nvt/manifold/rattle command...................................................................................................975
fix nvt/sllod command...................................................................................................................977
fix nvt/sllod/intel command...........................................................................................................977
fix nvt/sllod/omp command...........................................................................................................977
fix nvt/sllod/eff command.............................................................................................................980
fix nvt/sphere command................................................................................................................982
fix nvt/sphere/omp command........................................................................................................982
fix oneway command....................................................................................................................985
fix orient/fcc command.................................................................................................................986
fix orient/bcc command.................................................................................................................986
fix phonon command.....................................................................................................................990
fix pimd command.........................................................................................................................994
fix planeforce command................................................................................................................998
fix poems.......................................................................................................................................999
fix pour command.......................................................................................................................1001
fix press/berendsen command.....................................................................................................1005
fix print command.......................................................................................................................1009
fix property/atom command........................................................................................................1011
fix qbmsst command...................................................................................................................1015
fix qeq/point command................................................................................................................1019
fix qeq/shielded command...........................................................................................................1019
fix qeq/slater command...............................................................................................................1019
fix qeq/dynamic command..........................................................................................................1019
fix qeq/fire command..................................................................................................................1019
fix qeq/comb command...............................................................................................................1023
fix qeq/comb/omp command.......................................................................................................1023
fix qeq/reax command.................................................................................................................1025
fix qeq/reax/kk command............................................................................................................1025
fix qmmm command...................................................................................................................1027
fix qtb command..........................................................................................................................1028
fix reax/bonds command.............................................................................................................1031
fix reax/c/bonds command..........................................................................................................1031
fix reax/c/bonds/kk command.....................................................................................................1031
fix reax/c/species command........................................................................................................1033
fix reax/c/species/kk command...................................................................................................1033
fix recenter command..................................................................................................................1036
fix restrain command...................................................................................................................1038
fix rigid command.......................................................................................................................1042
fix rigid/nve command................................................................................................................1042
fix rigid/nvt command.................................................................................................................1042
ix

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
fix rigid/npt command.................................................................................................................1042
fix rigid/nph command................................................................................................................1042
fix rigid/small command.............................................................................................................1042
fix rigid/nve/small command.......................................................................................................1042
fix rigid/nvt/small command.......................................................................................................1042
fix rigid/npt/small command.......................................................................................................1042
fix rigid/nph/small command......................................................................................................1042
fix rx command...........................................................................................................................1053
fix saed/vtk command.................................................................................................................1057
fix setforce command..................................................................................................................1060
fix setforce/kk command.............................................................................................................1060
fix shake command......................................................................................................................1062
fix rattle command.......................................................................................................................1062
fix shardlow command................................................................................................................1066
fix smd command........................................................................................................................1068
fix smd/adjust_dt command........................................................................................................1071
fix smd/integrate_tlsph command...............................................................................................1072
fix smd/integrate_ulsph command..............................................................................................1073
fix smd/move_tri_surf command................................................................................................1074
fix smd/setvel command..............................................................................................................1076
fix smd/wall_surface command...................................................................................................1078
fix spring command.....................................................................................................................1080
fix spring/chunk command..........................................................................................................1083
fix spring/rg command................................................................................................................1085
fix spring/self command..............................................................................................................1087
fix srd command..........................................................................................................................1089
fix store/force command..............................................................................................................1095
fix store/state command...............................................................................................................1097
fix temp/berendsen command.....................................................................................................1099
fix temp/csvr command...............................................................................................................1102
fix temp/csld command...............................................................................................................1102
fix temp/rescale command...........................................................................................................1105
fix temp/rescale/eff command.....................................................................................................1108
fix tfmc command.......................................................................................................................1110
fix thermal/conductivity command.............................................................................................1113
fix ti/spring command.................................................................................................................1116
fix tmd command.........................................................................................................................1119
fix ttm command.........................................................................................................................1121
fix ttm/mod command.................................................................................................................1121
fix tune/kspace command............................................................................................................1127
fix vector command.....................................................................................................................1129
fix viscosity command.................................................................................................................1132
fix viscous command...................................................................................................................1135
fix wall/lj93 command.................................................................................................................1137
fix wall/lj126 command...............................................................................................................1137
fix wall/lj1043 command.............................................................................................................1137
fix wall/colloid command............................................................................................................1137
x

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
fix wall/harmonic command........................................................................................................1137
fix wall/gran command................................................................................................................1142
fix wall/gran/region command....................................................................................................1145
fix wall/piston command.............................................................................................................1149
fix wall/reflect command.............................................................................................................1151
fix wall/reflect/kk command.......................................................................................................1151
fix wall/region command.............................................................................................................1154
fix wall/srd command..................................................................................................................1158
compute ackland/atom command................................................................................................1161
compute angle command.............................................................................................................1163
compute angle/local command....................................................................................................1164
compute angmom/chunk command.............................................................................................1166
compute basal/atom command....................................................................................................1168
compute body/local command.....................................................................................................1170
compute bond command.............................................................................................................1172
compute bond/local command.....................................................................................................1173
compute centro/atom command..................................................................................................1176
compute chunk/atom command...................................................................................................1179
compute cluster/atom command..................................................................................................1188
compute cna/atom command.......................................................................................................1190
compute com command...............................................................................................................1192
compute com/chunk command....................................................................................................1193
compute contact/atom command.................................................................................................1195
compute coord/atom command...................................................................................................1196
compute damage/atom command................................................................................................1198
compute dihedral command........................................................................................................1199
compute dihedral/local command...............................................................................................1200
compute dilatation/atom command.............................................................................................1202
compute dipole/chunk command.................................................................................................1203
compute displace/atom command...............................................................................................1205
compute dpd command...............................................................................................................1206
compute dpd/atom command......................................................................................................1208
compute erotate/asphere command.............................................................................................1209
compute erotate/rigid command..................................................................................................1211
compute erotate/sphere command...............................................................................................1212
compute erotate/sphere/atom command......................................................................................1213
compute event/displace command...............................................................................................1214
compute fep command................................................................................................................1215
compute global/atom command..................................................................................................1220
compute group/group command..................................................................................................1223
compute gyration command........................................................................................................1226
compute gyration/chunk command.............................................................................................1228
compute heat/flux command.......................................................................................................1230
compute hexorder/atom command..............................................................................................1234
compute improper command.......................................................................................................1236
compute improper/local command..............................................................................................1237
compute inertia/chunk command................................................................................................1239
xi

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
compute ke command..................................................................................................................1241
compute ke/atom command.........................................................................................................1242
compute ke/atom/eff command...................................................................................................1243
compute ke/eff command............................................................................................................1245
compute ke/rigid command.........................................................................................................1247
compute meso/e/atom command.................................................................................................1248
compute meso/rho/atom command.............................................................................................1249
compute meso/t/atom command..................................................................................................1250
compute msd command...............................................................................................................1251
compute msd/chunk command....................................................................................................1253
compute msd/nongauss command...............................................................................................1255
compute omega/chunk command................................................................................................1257
compute orientorder/atom command...........................................................................................1259
compute pair command...............................................................................................................1262
compute pair/local command......................................................................................................1264
compute pe command..................................................................................................................1266
compute pe/atom command.........................................................................................................1268
compute plasticity/atom command..............................................................................................1270
compute pressure command........................................................................................................1271
compute property/atom command...............................................................................................1274
compute property/chunk command.............................................................................................1277
compute property/local command...............................................................................................1279
compute rdf command.................................................................................................................1282
compute reduce command...........................................................................................................1285
compute reduce/region command...............................................................................................1285
compute rigid/local command.....................................................................................................1288
compute saed command..............................................................................................................1291
compute slice command..............................................................................................................1295
compute smd/contact/radius command.......................................................................................1297
compute smd/damage command.................................................................................................1298
compute smd/hourglass/error command.....................................................................................1299
compute smd/internal/energy command.....................................................................................1300
compute smd/plastic/strain command.........................................................................................1301
compute smd/plastic/strain/rate command..................................................................................1302
compute smd/rho command........................................................................................................1303
compute smd/tlsph/defgrad command.........................................................................................1304
compute smd/tlsph/dt command..................................................................................................1305
compute smd/tlsph/num/neighs command..................................................................................1306
compute smd/tlsph/shape command............................................................................................1307
compute smd/tlsph/strain command............................................................................................1308
compute smd/tlsph/strain/rate command.....................................................................................1309
compute smd/tlsph/stress command............................................................................................1310
compute smd/triangle/mesh/vertices...........................................................................................1311
compute smd/ulsph/num/neighs command.................................................................................1312
compute smd/ulsph/strain command...........................................................................................1313
compute smd/ulsph/strain/rate command....................................................................................1314
compute smd/ulsph/stress command...........................................................................................1315
xii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
compute smd/vol command.........................................................................................................1316
compute sna/atom command.......................................................................................................1317
compute snad/atom command.....................................................................................................1317
compute snav/atom command.....................................................................................................1317
compute stress/atom command...................................................................................................1322
compute force/tally command.....................................................................................................1325
compute heat/flux/tally command...............................................................................................1325
compute pe/tally command.........................................................................................................1325
compute pe/mol/tally command..................................................................................................1325
compute stress/tally command....................................................................................................1325
compute temp command.............................................................................................................1327
compute temp/kk command........................................................................................................1327
compute temp/asphere command................................................................................................1329
compute temp/body command....................................................................................................1332
compute temp/chunk command...................................................................................................1334
compute temp/com command.....................................................................................................1338
compute temp/cs command.........................................................................................................1340
compute temp/deform command.................................................................................................1342
compute temp/deform/eff command...........................................................................................1344
compute temp/drude command...................................................................................................1345
compute temp/eff command........................................................................................................1347
compute temp/partial command..................................................................................................1349
compute temp/profile command..................................................................................................1351
compute temp/ramp command....................................................................................................1354
compute temp/region command..................................................................................................1356
compute temp/region/eff command.............................................................................................1358
compute temp/rotate command...................................................................................................1359
compute temp/sphere command..................................................................................................1361
compute ti command...................................................................................................................1363
compute torque/chunk command................................................................................................1365
compute vacf command...............................................................................................................1367
compute vcm/chunk command....................................................................................................1369
compute voronoi/atom command................................................................................................1371
compute xrd command................................................................................................................1375
pair_style adp command..............................................................................................................1380
pair_style adp/omp command.....................................................................................................1380
pair_style agni command.............................................................................................................1383
pair_style agni/omp command....................................................................................................1383
pair_style airebo command.........................................................................................................1386
pair_style airebo/omp command.................................................................................................1386
pair_style airebo/morse command...............................................................................................1386
pair_style airebo/morse/omp command......................................................................................1386
pair_style rebo command............................................................................................................1386
pair_style rebo/omp command....................................................................................................1386
pair_style awpmd/cut command..................................................................................................1390
pair_style beck command............................................................................................................1392
pair_style beck/gpu command.....................................................................................................1392
xiii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style beck/omp command....................................................................................................1392
pair_style body command...........................................................................................................1394
pair_style bop command.............................................................................................................1396
pair_style born command............................................................................................................1403
pair_style born/omp command....................................................................................................1403
pair_style born/gpu command.....................................................................................................1403
pair_style born/coul/long command............................................................................................1403
pair_style born/coul/long/cs command.......................................................................................1403
pair_style born/coul/long/gpu command.....................................................................................1403
pair_style born/coul/long/omp command....................................................................................1403
pair_style born/coul/msm command...........................................................................................1403
pair_style born/coul/msm/omp command...................................................................................1403
pair_style born/coul/wolf command............................................................................................1403
pair_style born/coul/wolf/gpu command.....................................................................................1403
pair_style born/coul/wolf/omp command...................................................................................1403
pair_style born/coul/dsf command..............................................................................................1403
pair_style born/coul/dsf/cs command..........................................................................................1403
pair_style brownian command....................................................................................................1407
pair_style brownian/omp command............................................................................................1407
pair_style brownian/poly command............................................................................................1407
pair_style brownian/poly/omp command....................................................................................1407
pair_style buck command............................................................................................................1410
pair_style buck/gpu command.....................................................................................................1410
pair_style buck/intel command...................................................................................................1410
pair_style buck/kk command.......................................................................................................1410
pair_style buck/omp command...................................................................................................1410
pair_style buck/coul/cut command..............................................................................................1410
pair_style buck/coul/cut/gpu command.......................................................................................1410
pair_style buck/coul/cut/intel command.....................................................................................1410
pair_style buck/coul/cut/kk command.........................................................................................1410
pair_style buck/coul/cut/omp command.....................................................................................1410
pair_style buck/coul/long command...........................................................................................1410
pair_style buck/coul/long/cs command.......................................................................................1410
pair_style buck/coul/long/gpu command....................................................................................1410
pair_style buck/coul/long/intel command...................................................................................1410
pair_style buck/coul/long/kk command......................................................................................1410
pair_style buck/coul/long/omp command...................................................................................1410
pair_style buck/coul/msm command...........................................................................................1410
pair_style buck/coul/msm/omp command...................................................................................1410
pair_style buck/long/coul/long command...................................................................................1414
pair_style buck/long/coul/long/omp command...........................................................................1414
pair_style lj/charmm/coul/charmm command.............................................................................1417
pair_style lj/charmm/coul/charmm/omp command.....................................................................1417
pair_style lj/charmm/coul/charmm/implicit command...............................................................1417
pair_style lj/charmm/coul/charmm/implicit/omp command.......................................................1417
pair_style lj/charmm/coul/long command...................................................................................1417
pair_style lj/charmm/coul/long/gpu command............................................................................1417
xiv

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style lj/charmm/coul/long/intel command...........................................................................1417
pair_style lj/charmm/coul/long/opt command.............................................................................1417
pair_style lj/charmm/coul/long/omp command...........................................................................1417
pair_style lj/charmm/coul/msm command..................................................................................1417
pair_style lj/charmm/coul/msm/omp command..........................................................................1417
pair_style lj/charmmfsw/coul/charmmfsh command..................................................................1417
pair_style lj/charmmfsw/coul/long command.............................................................................1417
pair_style lj/class2 command......................................................................................................1422
pair_style lj/class2/gpu command...............................................................................................1422
pair_style lj/class2/kk command.................................................................................................1422
pair_style lj/class2/omp command..............................................................................................1422
pair_style lj/class2/coul/cut command........................................................................................1422
pair_style lj/class2/coul/cut/kk command...................................................................................1422
pair_style lj/class2/coul/cut/omp command................................................................................1422
pair_style lj/class2/coul/long command......................................................................................1422
pair_style lj/class2/coul/long/gpu command...............................................................................1422
pair_style lj/class2/coul/long/kk command.................................................................................1422
pair_style lj/class2/coul/long/omp command..............................................................................1422
pair_style colloid command........................................................................................................1425
pair_style colloid/gpu command.................................................................................................1425
pair_style colloid/omp command................................................................................................1425
pair_style comb command...........................................................................................................1430
pair_style comb/omp command..................................................................................................1430
pair_style comb3 command.........................................................................................................1430
pair_style coul/cut command.......................................................................................................1434
pair_style coul/cut/gpu command...............................................................................................1434
pair_style coul/cut/kk command.................................................................................................1434
pair_style coul/cut/omp command..............................................................................................1434
pair_style coul/debye command..................................................................................................1434
pair_style coul/debye/gpu command...........................................................................................1434
pair_style coul/debye/kk command.............................................................................................1434
pair_style coul/debye/omp command..........................................................................................1434
pair_style coul/dsf command.......................................................................................................1434
pair_style coul/dsf/gpu command...............................................................................................1434
pair_style coul/dsf/kk command.................................................................................................1434
pair_style coul/dsf/omp command..............................................................................................1434
pair_style coul/long command....................................................................................................1434
pair_style coul/long/cs command................................................................................................1434
pair_style coul/long/omp command............................................................................................1434
pair_style coul/long/gpu command.............................................................................................1434
pair_style coul/long/kk command...............................................................................................1434
pair_style coul/msm command....................................................................................................1434
pair_style coul/msm/omp command...........................................................................................1434
pair_style coul/streitz command..................................................................................................1434
pair_style coul/wolf command....................................................................................................1434
pair_style coul/wolf/kk command...............................................................................................1435
pair_style coul/wolf/omp command............................................................................................1435
xv

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style tip4p/cut command.....................................................................................................1435
pair_style tip4p/long command...................................................................................................1435
pair_style tip4p/cut/omp command.............................................................................................1435
pair_style tip4p/long/omp command...........................................................................................1435
pair_style coul/diel command.....................................................................................................1441
pair_style coul/diel/omp command.............................................................................................1441
pair_style born/coul/long/cs command.......................................................................................1443
pair_style buck/coul/long/cs command.......................................................................................1443
pair_style born/coul/dsf/cs command..........................................................................................1443
pair_style lj/cut/dipole/cut command..........................................................................................1445
pair_style lj/cut/dipole/cut/gpu command...................................................................................1445
pair_style lj/cut/dipole/cut/omp command..................................................................................1445
pair_style lj/sf/dipole/sf command..............................................................................................1445
pair_style lj/sf/dipole/sf/gpu command.......................................................................................1445
pair_style lj/sf/dipole/sf/omp command......................................................................................1445
pair_style lj/cut/dipole/long command........................................................................................1445
pair_style lj/long/dipole/long command......................................................................................1445
pair_style dpd command.............................................................................................................1453
pair_style dpd/gpu command......................................................................................................1453
pair_style dpd/omp command.....................................................................................................1453
pair_style dpd/tstat command......................................................................................................1453
pair_style dpd/tstat/gpu command...............................................................................................1453
pair_style dpd/tstat/omp command.............................................................................................1453
pair_style dpd/fdt command........................................................................................................1457
pair_style dpd/fdt/energy command............................................................................................1457
pair_style dsmc command...........................................................................................................1460
pair_style eam command.............................................................................................................1463
pair_style eam/gpu command......................................................................................................1463
pair_style eam/intel command.....................................................................................................1463
pair_style eam/kk command........................................................................................................1463
pair_style eam/omp command.....................................................................................................1463
pair_style eam/opt command.......................................................................................................1463
pair_style eam/alloy command....................................................................................................1463
pair_style eam/alloy/gpu command.............................................................................................1463
pair_style eam/alloy/kk command...............................................................................................1463
pair_style eam/alloy/omp command...........................................................................................1463
pair_style eam/alloy/opt command.............................................................................................1463
pair_style eam/cd command........................................................................................................1463
pair_style eam/cd/omp command................................................................................................1463
pair_style eam/fs command.........................................................................................................1463
pair_style eam/fs/gpu command..................................................................................................1463
pair_style eam/fs/kk command....................................................................................................1463
pair_style eam/fs/omp command.................................................................................................1463
pair_style eam/fs/opt command...................................................................................................1463
pair_style edip command.............................................................................................................1471
pair_style eff/cut command.........................................................................................................1474
pair_style eim command.............................................................................................................1480
xvi

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style eim/omp command.....................................................................................................1480
pair_style exp6/rx command.......................................................................................................1484
pair_style gauss command...........................................................................................................1487
pair_style gauss/gpu command...................................................................................................1487
pair_style gauss/omp command..................................................................................................1487
pair_style gauss/cut command.....................................................................................................1487
pair_style gauss/cut/omp command............................................................................................1487
pair_style gayberne command.....................................................................................................1490
pair_style gayberne/gpu command..............................................................................................1490
pair_style gayberne/intel command.............................................................................................1490
pair_style gayberne/omp command.............................................................................................1490
pair_style gran/hooke command.................................................................................................1494
pair_style gran/omp command....................................................................................................1494
pair_style gran/hooke/history command.....................................................................................1494
pair_style gran/hooke/history/omp command.............................................................................1494
pair_style gran/hertz/history command.......................................................................................1494
pair_style gran/hertz/history/omp command...............................................................................1494
pair_style lj/gromacs command...................................................................................................1499
pair_style lj/gromacs/gpu command...........................................................................................1499
pair_style lj/gromacs/omp command..........................................................................................1499
pair_style lj/gromacs/coul/gromacs command............................................................................1499
pair_style lj/gromacs/coul/gromacs/omp command....................................................................1499
pair_style hbond/dreiding/lj command........................................................................................1502
pair_style hbond/dreiding/lj/omp command...............................................................................1502
pair_style hbond/dreiding/morse command................................................................................1502
pair_style hbond/dreiding/morse/omp command........................................................................1502
pair_style hybrid command.........................................................................................................1507
pair_style hybrid/omp command.................................................................................................1507
pair_style hybrid/overlay command............................................................................................1507
pair_style hybrid/overlay/omp command....................................................................................1507
pair_style kim command.............................................................................................................1513
pair_style kolmogorov/crespi/z command..................................................................................1515
pair_style lcbop command...........................................................................................................1517
pair_style line/lj command..........................................................................................................1519
pair_style list command...............................................................................................................1522
pair_style lj/cut command...........................................................................................................1525
pair_style lj/cut/gpu command....................................................................................................1525
pair_style lj/cut/intel command...................................................................................................1525
pair_style lj/cut/kk command......................................................................................................1525
pair_style lj/cut/opt command.....................................................................................................1525
pair_style lj/cut/omp command...................................................................................................1525
pair_style lj/cut/coul/cut command.............................................................................................1525
pair_style lj/cut/coul/cut/gpu command......................................................................................1525
pair_style lj/cut/coul/cut/omp command.....................................................................................1525
pair_style lj/cut/coul/debye command.........................................................................................1525
pair_style lj/cut/coul/debye/gpu command.................................................................................1525
pair_style lj/cut/coul/debye/kk command...................................................................................1525
xvii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style lj/cut/coul/debye/omp command................................................................................1525
pair_style lj/cut/coul/dsf command.............................................................................................1525
pair_style lj/cut/coul/dsf/gpu command......................................................................................1525
pair_style lj/cut/coul/dsf/kk command........................................................................................1525
pair_style lj/cut/coul/dsf/omp command.....................................................................................1525
pair_style lj/cut/coul/long command...........................................................................................1525
pair_style lj/cut/coul/long/cs command.......................................................................................1525
pair_style lj/cut/coul/long/gpu command....................................................................................1525
pair_style lj/cut/coul/long/intel command...................................................................................1525
pair_style lj/cut/coul/long/opt command.....................................................................................1526
pair_style lj/cut/coul/long/omp command...................................................................................1526
pair_style lj/cut/coul/msm command..........................................................................................1526
pair_style lj/cut/coul/msm/gpu command...................................................................................1526
pair_style lj/cut/coul/msm/omp command..................................................................................1526
pair_style lj/cut/tip4p/cut command............................................................................................1526
pair_style lj/cut/tip4p/cut/omp command....................................................................................1526
pair_style lj/cut/tip4p/long command..........................................................................................1526
pair_style lj/cut/tip4p/long/omp command.................................................................................1526
pair_style lj/cut/tip4p/long/opt command...................................................................................1526
pair_style lj96/cut command.......................................................................................................1532
pair_style lj96/cut/gpu command................................................................................................1532
pair_style lj96/cut/omp command...............................................................................................1532
pair_style lj/cubic command.......................................................................................................1534
pair_style lj/cubic/gpu command................................................................................................1534
pair_style lj/cubic/omp command...............................................................................................1534
pair_style lj/expand command.....................................................................................................1536
pair_style lj/expand/gpu command.............................................................................................1536
pair_style lj/expand/omp command............................................................................................1536
pair_style lj/long/coul/long command.........................................................................................1538
pair_style lj/long/coul/long/omp command.................................................................................1538
pair_style lj/long/coul/long/opt command...................................................................................1538
pair_style lj/long/tip4p/long command.......................................................................................1538
pair_style lj/sf command.............................................................................................................1542
pair_style lj/sf/omp command.....................................................................................................1542
pair_style lj/smooth command....................................................................................................1544
pair_style lj/smooth/omp command............................................................................................1544
pair_style lj/smooth/linear command..........................................................................................1546
pair_style lj/smooth/linear/omp command..................................................................................1546
pair_style lj/cut/soft command....................................................................................................1548
pair_style lj/cut/soft/omp command............................................................................................1548
pair_style lj/cut/coul/cut/soft command......................................................................................1548
pair_style lj/cut/coul/cut/soft/omp command..............................................................................1548
pair_style lj/cut/coul/long/soft command....................................................................................1548
pair_style lj/cut/coul/long/soft/omp command............................................................................1548
pair_style lj/cut/tip4p/long/soft command...................................................................................1548
pair_style lj/cut/tip4p/long/soft/omp command..........................................................................1548
pair_style lj/charmm/coul/long/soft command............................................................................1548
xviii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style lj/charmm/coul/long/soft/omp command...................................................................1548
pair_style coul/cut/soft command...............................................................................................1548
pair_style coul/cut/soft/omp command.......................................................................................1548
pair_style coul/long/soft command.............................................................................................1548
pair_style coul/long/soft/omp command.....................................................................................1548
pair_style tip4p/long/soft command............................................................................................1548
pair_style tip4p/long/soft/omp command....................................................................................1548
pair_style lubricate command.....................................................................................................1553
pair_style lubricate/omp command.............................................................................................1553
pair_style lubricate/poly command.............................................................................................1553
pair_style lubricate/poly/omp command.....................................................................................1553
pair_style lubricateU command...................................................................................................1557
pair_style lubricateU/poly command..........................................................................................1557
pair_style lj/mdf command..........................................................................................................1561
pair_style buck/mdf command....................................................................................................1561
pair_style lennard/mdf command................................................................................................1561
pair_style meam command..........................................................................................................1564
pair_style meam/spline................................................................................................................1570
pair_style meam/spline/omp........................................................................................................1570
pair_style meam/sw/spline..........................................................................................................1573
pair_style meam/sw/spline/omp..................................................................................................1573
pair_style mgpt command...........................................................................................................1576
pair_style mie/cut command.......................................................................................................1580
pair_style mie/cut/gpu command................................................................................................1580
pair_style momb command.........................................................................................................1582
pair_style morse command..........................................................................................................1584
pair_style morse/gpu command...................................................................................................1584
pair_style morse/omp command.................................................................................................1584
pair_style morse/opt command...................................................................................................1584
pair_style morse/smooth/linear command...................................................................................1584
pair_style morse/smooth/linear/omp command..........................................................................1584
pair_style morse/soft command...................................................................................................1584
pair_style morse/kk command.....................................................................................................1584
pair_style multi/lucy command...................................................................................................1587
pair_style multi/lucy/rx command...............................................................................................1591
pair_style nb3b/harmonic command...........................................................................................1595
pair_style nb3b/harmonic/omp command...................................................................................1595
pair_style nm/cut command........................................................................................................1597
pair_style nm/cut/coul/cut command..........................................................................................1597
pair_style nm/cut/coul/long command........................................................................................1597
pair_style nm/cut/omp command................................................................................................1597
pair_style nm/cut/coul/cut/omp command..................................................................................1597
pair_style nm/cut/coul/long/omp command................................................................................1597
pair_style none command............................................................................................................1600
pair_style oxdna/excv command.................................................................................................1601
pair_style oxdna/stk command....................................................................................................1601
pair_style oxdna/hbond command...............................................................................................1601
xix

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style oxdna/xstk command..................................................................................................1601
pair_style oxdna/coaxstk command............................................................................................1601
pair_style oxdna2/excv command...............................................................................................1603
pair_style oxdna2/stk command..................................................................................................1603
pair_style oxdna2/hbond command.............................................................................................1603
pair_style oxdna2/xstk command................................................................................................1603
pair_style oxdna2/coaxstk command..........................................................................................1603
pair_style oxdna2/dh command...................................................................................................1603
pair_style peri/pmb command.....................................................................................................1605
pair_style peri/pmb/omp command.............................................................................................1605
pair_style peri/lps command.......................................................................................................1605
pair_style peri/lps/omp command...............................................................................................1605
pair_style peri/ves command.......................................................................................................1605
pair_style peri/eps command.......................................................................................................1605
pair_style polymorphic command...............................................................................................1609
pair_style quip command............................................................................................................1615
pair_style reax command.............................................................................................................1617
pair_style reax/c command..........................................................................................................1621
pair_style reax/c/kk command.....................................................................................................1621
pair_style resquared command....................................................................................................1627
pair_style resquared/gpu command.............................................................................................1627
pair_style resquared/omp command............................................................................................1627
pair_style lj/sdk command...........................................................................................................1631
pair_style lj/sdk/gpu command...................................................................................................1631
pair_style lj/sdk/kk command.....................................................................................................1631
pair_style lj/sdk/omp command..................................................................................................1631
pair_style lj/sdk/coul/long command..........................................................................................1631
pair_style lj/sdk/coul/long/gpu command...................................................................................1631
pair_style lj/sdk/coul/long/omp command..................................................................................1631
pair_style smd/hertz command....................................................................................................1634
pair_style smd/tlsph command....................................................................................................1635
pair_style smd/tri_surface command...........................................................................................1636
pair_style smd/ulsph command...................................................................................................1637
pair_style smtbq command..........................................................................................................1639
pair_style snap command............................................................................................................1645
pair_style soft command.............................................................................................................1648
pair_style soft/gpu command......................................................................................................1648
pair_style soft/omp command.....................................................................................................1648
pair_style sph/heatconduction command....................................................................................1651
pair_style sph/idealgas command................................................................................................1652
pair_style sph/lj command...........................................................................................................1654
pair_style sph/rhosum command.................................................................................................1656
pair_style sph/taitwater command...............................................................................................1657
pair_style sph/taitwater/morris command...................................................................................1659
pair_style srp command...............................................................................................................1661
pair_style sw command...............................................................................................................1664
pair_style sw/gpu command........................................................................................................1664
xx

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
pair_style sw/intel command.......................................................................................................1664
pair_style sw/kk command..........................................................................................................1664
pair_style sw/omp command.......................................................................................................1664
pair_style table command............................................................................................................1668
pair_style table/gpu command.....................................................................................................1668
pair_style table/kk command.......................................................................................................1668
pair_style table/omp command...................................................................................................1668
pair_style table/rx command.......................................................................................................1672
pair_style tersoff command.........................................................................................................1676
pair_style tersoff/table command................................................................................................1676
pair_style tersoff/gpu...................................................................................................................1676
pair_style tersoff/intel..................................................................................................................1676
pair_style tersoff/kk.....................................................................................................................1676
pair_style tersoff/omp..................................................................................................................1676
pair_style tersoff/table/omp command........................................................................................1676
pair_style tersoff/mod command.................................................................................................1681
pair_style tersoff/mod/c command..............................................................................................1681
pair_style tersoff/mod/gpu command..........................................................................................1681
pair_style tersoff/mod/kk command............................................................................................1681
pair_style tersoff/mod/omp command.........................................................................................1681
pair_style tersoff/mod/c/omp command......................................................................................1681
pair_style tersoff/zbl command...................................................................................................1685
pair_style tersoff/zbl/gpu command............................................................................................1685
pair_style tersoff/zbl/kk command..............................................................................................1685
pair_style tersoff/zbl/omp command...........................................................................................1685
pair_style thole command...........................................................................................................1691
pair_style lj/cut/thole/long command..........................................................................................1691
pair_style lj/cut/thole/long/omp command..................................................................................1691
pair_style tri/lj command.............................................................................................................1694
pair_style vashishta command.....................................................................................................1696
pair_style vashishta/omp command............................................................................................1696
pair_style vashishta/kk command...............................................................................................1696
pair_style vashishta/table command............................................................................................1696
pair_style vashishta/table/omp command...................................................................................1696
pair_style yukawa command.......................................................................................................1701
pair_style yukawa/gpu command................................................................................................1701
pair_style yukawa/omp command...............................................................................................1701
pair_style yukawa/colloid command...........................................................................................1703
pair_style yukawa/colloid/gpu command....................................................................................1703
pair_style yukawa/colloid/omp command...................................................................................1703
pair_style zbl command...............................................................................................................1706
pair_style zbl/gpu command.......................................................................................................1706
pair_style zbl/omp command......................................................................................................1706
pair_style zero command.............................................................................................................1709
bond_style class2 command........................................................................................................1711
bond_style class2/omp command................................................................................................1711
bond_style class2/kk command...................................................................................................1711
xxi

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
bond_style fene command...........................................................................................................1713
bond_style fene/intel command...................................................................................................1713
bond_style fene/kk command......................................................................................................1713
bond_style fene/omp command...................................................................................................1713
bond_style fene/expand command..............................................................................................1715
bond_style fene/expand/omp command......................................................................................1715
bond_style oxdna/fene command................................................................................................1717
bond_style oxdna2/fene command..............................................................................................1717
bond_style harmonic command...................................................................................................1719
bond_style harmonic/intel command..........................................................................................1719
bond_style harmonic/kk command.............................................................................................1719
bond_style harmonic/omp command..........................................................................................1719
bond_style harmonic/shift command..........................................................................................1721
bond_style harmonic/shift/omp command..................................................................................1721
bond_style harmonic/shift/cut command....................................................................................1723
bond_style harmonic/shift/cut/omp command............................................................................1723
bond_style hybrid command.......................................................................................................1725
bond_style morse command........................................................................................................1727
bond_style morse/omp command................................................................................................1727
bond_style none command..........................................................................................................1729
bond_style nonlinear command...................................................................................................1730
bond_style nonlinear/omp command..........................................................................................1730
bond_style quartic command.......................................................................................................1732
bond_style quartic/omp command..............................................................................................1732
bond_style table command..........................................................................................................1734
bond_style table/omp command..................................................................................................1734
bond_style zero command...........................................................................................................1737
angle_style charmm command....................................................................................................1738
angle_style charmm/intel command............................................................................................1738
angle_style charmm/kk command...............................................................................................1738
angle_style charmm/omp command............................................................................................1738
angle_style class2 command.......................................................................................................1740
angle_style class2/omp command...............................................................................................1740
angle_style class2/kk command..................................................................................................1740
angle_style cosine command.......................................................................................................1743
angle_style cosine/omp command...............................................................................................1743
angle_style cosine/delta command..............................................................................................1745
angle_style cosine/delta/omp command......................................................................................1745
angle_style cosine/periodic command.........................................................................................1747
angle_style cosine/periodic/omp command................................................................................1747
angle_style cosine/shift command...............................................................................................1749
angle_style cosine/shift/omp command......................................................................................1749
angle_style cosine/shift/exp command........................................................................................1751
angle_style cosine/shift/exp/omp command...............................................................................1751
angle_style cosine/squared command.........................................................................................1753
angle_style cosine/squared/omp command.................................................................................1753
angle_style dipole command.......................................................................................................1755
xxii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
angle_style dipole/omp command...............................................................................................1755
angle_style fourier command......................................................................................................1758
angle_style fourier/omp command..............................................................................................1758
angle_style fourier/simple command..........................................................................................1760
angle_style fourier/simple/omp command..................................................................................1760
angle_style harmonic command..................................................................................................1762
angle_style harmonic/intel command..........................................................................................1762
angle_style harmonic/kk command.............................................................................................1762
angle_style harmonic/omp command..........................................................................................1762
angle_style hybrid command.......................................................................................................1764
angle_style none command.........................................................................................................1766
angle_style quartic command......................................................................................................1767
angle_style quartic/omp command..............................................................................................1767
angle_style sdk command...........................................................................................................1769
angle_style table command.........................................................................................................1770
angle_style table/omp command.................................................................................................1770
angle_style zero command..........................................................................................................1773
dihedral_style charmm command...............................................................................................1774
dihedral_style charmm/intel command.......................................................................................1774
dihedral_style charmm/kk command..........................................................................................1774
dihedral_style charmm/omp command.......................................................................................1774
dihedral_style charmmfsh command...........................................................................................1774
dihedral_style class2 command...................................................................................................1777
dihedral_style class2/omp command...........................................................................................1777
dihedral_style class2/kk command..............................................................................................1777
dihedral_style cosine/shift/exp command...................................................................................1781
dihedral_style cosine/shift/exp/omp command...........................................................................1781
dihedral_style fourier command..................................................................................................1783
dihedral_style fourier/omp command.........................................................................................1783
dihedral_style harmonic command.............................................................................................1785
dihedral_style harmonic/intel command.....................................................................................1785
dihedral_style harmonic/omp command.....................................................................................1785
dihedral_style helix command.....................................................................................................1787
dihedral_style helix/omp command............................................................................................1787
dihedral_style hybrid command..................................................................................................1789
dihedral_style multi/harmonic command....................................................................................1791
dihedral_style multi/harmonic/omp command............................................................................1791
dihedral_style nharmonic command...........................................................................................1793
dihedral_style nharmonic/omp command...................................................................................1793
dihedral_style none command.....................................................................................................1795
dihedral_style opls command......................................................................................................1796
dihedral_style opls/intel command..............................................................................................1796
dihedral_style opls/kk command.................................................................................................1796
dihedral_style opls/omp command..............................................................................................1796
dihedral_style quadratic command..............................................................................................1798
dihedral_style quadratic/omp command.....................................................................................1798
dihedral_style spherical command..............................................................................................1800
xxiii

LAMMPS Users Manual

Table of Contents
PyLammps Tutorial
dihedral_style table command.....................................................................................................1802
dihedral_style table/omp command.............................................................................................1802
dihedral_style zero command......................................................................................................1805
improper_style class2 command.................................................................................................1806
improper_style class2/omp command.........................................................................................1806
improper_style class2/kk command............................................................................................1806
improper_style cossq command..................................................................................................1809
improper_style cossq/omp command..........................................................................................1809
improper_style cvff command.....................................................................................................1811
improper_style cvff/intel command............................................................................................1811
improper_style cvff/omp command............................................................................................1811
improper_style distance command..............................................................................................1813
improper_style fourier command................................................................................................1815
improper_style fourier/omp command........................................................................................1815
improper_style harmonic command............................................................................................1817
improper_style harmonic/intel command....................................................................................1817
improper_style harmonic/kk command.......................................................................................1817
improper_style harmonic/omp command....................................................................................1817
improper_style hybrid command.................................................................................................1819
improper_style none command...................................................................................................1820
improper_style ring command.....................................................................................................1821
improper_style ring/omp command............................................................................................1821
improper_style umbrella command.............................................................................................1823
improper_style umbrella/omp command.....................................................................................1823
improper_style zero command....................................................................................................1825
fix_modify AtC add_molecule.....................................................................................................................1827
syntax................................................................................................................................................1827
examples...........................................................................................................................................1827
description.........................................................................................................................................1827
restrictions.........................................................................................................................................1827
related................................................................................................................................................1827
default...............................................................................................................................................1827
fix_modify AtC add_species.........................................................................................................................1828
syntax................................................................................................................................................1828
examples...........................................................................................................................................1828
description.........................................................................................................................................1828
restrictions.........................................................................................................................................1828
related................................................................................................................................................1828
default...............................................................................................................................................1828
fix_modify AtC atom_element_map...........................................................................................................1829
syntax................................................................................................................................................1829
examples...........................................................................................................................................1829
description.........................................................................................................................................1829
restrictions.........................................................................................................................................1829
xxiv

LAMMPS Users Manual

Table of Contents
fix_modify AtC atom_element_map
related................................................................................................................................................1829
default...............................................................................................................................................1829
fix_modify AtC atom_weight.......................................................................................................................1830
syntax................................................................................................................................................1830
examples...........................................................................................................................................1830
description.........................................................................................................................................1830
restrictions.........................................................................................................................................1830
related................................................................................................................................................1830
default...............................................................................................................................................1830
fix_modify AtC atomic_charge....................................................................................................................1831
syntax................................................................................................................................................1831
examples...........................................................................................................................................1831
description.........................................................................................................................................1831
restrictions.........................................................................................................................................1831
related................................................................................................................................................1831
default...............................................................................................................................................1831
fix_modify AtC boundary............................................................................................................................1832
syntax................................................................................................................................................1832
examples...........................................................................................................................................1832
description.........................................................................................................................................1832
restrictions.........................................................................................................................................1832
default...............................................................................................................................................1832
fix_modify AtC boundary_dynamics..........................................................................................................1833
syntax................................................................................................................................................1833
description.........................................................................................................................................1833
restrictions.........................................................................................................................................1833
related................................................................................................................................................1833
default...............................................................................................................................................1833
fix_modify AtC boundary_faceset...............................................................................................................1834
syntax................................................................................................................................................1834
examples...........................................................................................................................................1834
description.........................................................................................................................................1834
restrictions.........................................................................................................................................1834
related................................................................................................................................................1834
default...............................................................................................................................................1834
fix_modify AtC output boundary_integral.................................................................................................1835
syntax................................................................................................................................................1835
examples...........................................................................................................................................1835
description.........................................................................................................................................1835
restrictions.........................................................................................................................................1835
related................................................................................................................................................1835
xxv

LAMMPS Users Manual

Table of Contents
fix_modify AtC output boundary_integral
default...............................................................................................................................................1835
fix_modify AtC consistent_fe_initialization...............................................................................................1836
syntax................................................................................................................................................1836
examples...........................................................................................................................................1836
description.........................................................................................................................................1836
restrictions.........................................................................................................................................1836
related................................................................................................................................................1836
default...............................................................................................................................................1836
fix_modify AtC output contour_integral....................................................................................................1837
syntax................................................................................................................................................1837
examples...........................................................................................................................................1837
description.........................................................................................................................................1837
restrictions.........................................................................................................................................1837
related................................................................................................................................................1837
default...............................................................................................................................................1837
fix_modify AtC control.................................................................................................................................1838
syntax................................................................................................................................................1838
examples...........................................................................................................................................1838
description.........................................................................................................................................1838
restrictions.........................................................................................................................................1838
related................................................................................................................................................1838
default...............................................................................................................................................1838
fix_modify AtC control momentum............................................................................................................1840
syntax................................................................................................................................................1840
examples...........................................................................................................................................1840
description.........................................................................................................................................1840
restrictions.........................................................................................................................................1840
related................................................................................................................................................1840
default...............................................................................................................................................1840
fix_modify AtC control thermal..................................................................................................................1841
syntax................................................................................................................................................1841
examples...........................................................................................................................................1841
description.........................................................................................................................................1841
restrictions.........................................................................................................................................1841
related................................................................................................................................................1841
default...............................................................................................................................................1842
fix_modify AtC control thermal correction_max_iterations....................................................................1843
syntax................................................................................................................................................1843
examples...........................................................................................................................................1843
description.........................................................................................................................................1843
restrictions.........................................................................................................................................1843
xxvi

LAMMPS Users Manual

Table of Contents
fix_modify AtC control thermal correction_max_iterations
related................................................................................................................................................1843
default...............................................................................................................................................1843
fix_modify AtC decomposition....................................................................................................................1844
syntax................................................................................................................................................1844
examples...........................................................................................................................................1844
description.........................................................................................................................................1844
restrictions.........................................................................................................................................1844
related................................................................................................................................................1844
default...............................................................................................................................................1844
fix_modify AtC extrinsic electron_integration...........................................................................................1845
syntax................................................................................................................................................1845
examples...........................................................................................................................................1845
description.........................................................................................................................................1845
restrictions.........................................................................................................................................1845
default...............................................................................................................................................1845
fix_modify AtC equilibrium_start...............................................................................................................1846
syntax................................................................................................................................................1846
examples...........................................................................................................................................1846
description.........................................................................................................................................1846
restrictions.........................................................................................................................................1846
related................................................................................................................................................1846
default...............................................................................................................................................1846
fix_modify AtC extrinsic exchange..............................................................................................................1847
syntax................................................................................................................................................1847
examples...........................................................................................................................................1847
description.........................................................................................................................................1847
restrictions.........................................................................................................................................1847
related................................................................................................................................................1847
default...............................................................................................................................................1847
fix_modify AtC fe_md_boundary................................................................................................................1848
syntax................................................................................................................................................1848
examples...........................................................................................................................................1848
description.........................................................................................................................................1848
restrictions.........................................................................................................................................1848
related................................................................................................................................................1848
default...............................................................................................................................................1848
fix_modify AtC fem create mesh.................................................................................................................1849
syntax................................................................................................................................................1849
examples...........................................................................................................................................1849
description.........................................................................................................................................1849
restrictions.........................................................................................................................................1849
xxvii

LAMMPS Users Manual

Table of Contents
fix_modify AtC fem create mesh
related................................................................................................................................................1849
default...............................................................................................................................................1849
fix_modify AtC filter scale...........................................................................................................................1850
syntax................................................................................................................................................1850
examples...........................................................................................................................................1850
description.........................................................................................................................................1850
restrictions.........................................................................................................................................1850
related................................................................................................................................................1850
default...............................................................................................................................................1850
fix_modify AtC filter type............................................................................................................................1851
syntax................................................................................................................................................1851
examples...........................................................................................................................................1851
description.........................................................................................................................................1851
restrictions.........................................................................................................................................1851
related................................................................................................................................................1851
default...............................................................................................................................................1851
fix atc command............................................................................................................................................1852
syntax................................................................................................................................................1852
examples...........................................................................................................................................1852
description.........................................................................................................................................1852
restrictions.........................................................................................................................................1854
related................................................................................................................................................1854
default...............................................................................................................................................1856
fix_modify AtC fix_flux................................................................................................................................1857
syntax................................................................................................................................................1857
examples...........................................................................................................................................1857
description.........................................................................................................................................1857
restrictions.........................................................................................................................................1857
related................................................................................................................................................1857
default...............................................................................................................................................1857
fix_modify AtC fix.........................................................................................................................................1858
syntax................................................................................................................................................1858
examples...........................................................................................................................................1858
description.........................................................................................................................................1858
restrictions.........................................................................................................................................1858
related................................................................................................................................................1858
default...............................................................................................................................................1858
fix_modify AtC computes.............................................................................................................................1859
syntax................................................................................................................................................1859
examples...........................................................................................................................................1859
description.........................................................................................................................................1859
xxviii

LAMMPS Users Manual

Table of Contents
fix_modify AtC computes
restrictions.........................................................................................................................................1859
related................................................................................................................................................1859
default...............................................................................................................................................1859
fix_modify AtC fields....................................................................................................................................1860
syntax................................................................................................................................................1860
examples...........................................................................................................................................1860
description.........................................................................................................................................1860
restrictions.........................................................................................................................................1861
related................................................................................................................................................1861
default...............................................................................................................................................1861
fix_modify AtC gradients.............................................................................................................................1862
syntax................................................................................................................................................1862
examples...........................................................................................................................................1862
description.........................................................................................................................................1862
restrictions.........................................................................................................................................1862
related................................................................................................................................................1862
default...............................................................................................................................................1862
fix_modify AtC kernel..................................................................................................................................1863
syntax................................................................................................................................................1863
examples...........................................................................................................................................1863
description.........................................................................................................................................1863
restrictions.........................................................................................................................................1863
related................................................................................................................................................1863
default...............................................................................................................................................1863
fix_modify AtC on_the_fly...........................................................................................................................1864
syntax................................................................................................................................................1864
examples...........................................................................................................................................1864
description.........................................................................................................................................1864
restrictions.........................................................................................................................................1864
related................................................................................................................................................1864
default...............................................................................................................................................1864
fix_modify AtC rates.....................................................................................................................................1865
syntax................................................................................................................................................1865
examples...........................................................................................................................................1865
description.........................................................................................................................................1865
restrictions.........................................................................................................................................1865
related................................................................................................................................................1865
default...............................................................................................................................................1865
fix_modify AtC initial...................................................................................................................................1866
syntax................................................................................................................................................1866
examples...........................................................................................................................................1866
xxix

LAMMPS Users Manual

Table of Contents
fix_modify AtC initial
description.........................................................................................................................................1866
restrictions.........................................................................................................................................1866
default...............................................................................................................................................1866
fix_modify AtC internal_atom_integrate...................................................................................................1867
syntax................................................................................................................................................1867
description.........................................................................................................................................1867
default...............................................................................................................................................1867
fix_modify AtC internal_element_set.........................................................................................................1868
syntax................................................................................................................................................1868
examples...........................................................................................................................................1868
description.........................................................................................................................................1868
restrictions.........................................................................................................................................1868
related................................................................................................................................................1868
default...............................................................................................................................................1868
fix_modify AtC internal_quadrature..........................................................................................................1869
syntax................................................................................................................................................1869
examples...........................................................................................................................................1869
description.........................................................................................................................................1869
optional.............................................................................................................................................1869
restrictions.........................................................................................................................................1869
related................................................................................................................................................1869
default...............................................................................................................................................1869
fix_modify AtC kernel..................................................................................................................................1870
syntax................................................................................................................................................1870
examples...........................................................................................................................................1870
description.........................................................................................................................................1870
restrictions.........................................................................................................................................1870
related................................................................................................................................................1870
default...............................................................................................................................................1870
fix_modify AtC control localized_lambda..................................................................................................1871
syntax................................................................................................................................................1871
examples...........................................................................................................................................1871
description.........................................................................................................................................1871
restrictions.........................................................................................................................................1871
related................................................................................................................................................1871
default...............................................................................................................................................1871
fix_modify AtC control lumped_lambda_solve..........................................................................................1872
syntax................................................................................................................................................1872
examples...........................................................................................................................................1872
description.........................................................................................................................................1872
restrictions.........................................................................................................................................1872
xxx

LAMMPS Users Manual

Table of Contents
fix_modify AtC control lumped_lambda_solve
related................................................................................................................................................1872
default...............................................................................................................................................1872
fix_modify AtC control mask_direction.....................................................................................................1873
syntax................................................................................................................................................1873
examples...........................................................................................................................................1873
description.........................................................................................................................................1873
restrictions.........................................................................................................................................1873
related................................................................................................................................................1873
default...............................................................................................................................................1873
fix_modify AtC mass_matrix.......................................................................................................................1874
syntax................................................................................................................................................1874
examples...........................................................................................................................................1874
description.........................................................................................................................................1874
restrictions.........................................................................................................................................1874
related................................................................................................................................................1874
default...............................................................................................................................................1874
fix_modify AtC material...............................................................................................................................1875
syntax................................................................................................................................................1875
examples...........................................................................................................................................1875
description.........................................................................................................................................1875
restrictions.........................................................................................................................................1875
related................................................................................................................................................1875
default...............................................................................................................................................1875
fix_modify AtC mesh add_to_nodeset........................................................................................................1876
syntax................................................................................................................................................1876
examples...........................................................................................................................................1876
description.........................................................................................................................................1876
restrictions.........................................................................................................................................1876
related................................................................................................................................................1876
default...............................................................................................................................................1876
fix_modify AtC mesh create.........................................................................................................................1877
syntax................................................................................................................................................1877
examples...........................................................................................................................................1877
description.........................................................................................................................................1877
restrictions.........................................................................................................................................1877
related................................................................................................................................................1877
default...............................................................................................................................................1877
fix_modify AtC mesh create_elementset.....................................................................................................1878
syntax................................................................................................................................................1878
examples...........................................................................................................................................1878
description.........................................................................................................................................1878
xxxi

LAMMPS Users Manual

Table of Contents
fix_modify AtC mesh create_elementset
restrictions.........................................................................................................................................1878
related................................................................................................................................................1878
default...............................................................................................................................................1878
fix_modify AtC mesh create_faceset box....................................................................................................1879
syntax................................................................................................................................................1879
examples...........................................................................................................................................1879
description.........................................................................................................................................1879
restrictions.........................................................................................................................................1879
related................................................................................................................................................1879
default...............................................................................................................................................1879
fix_modify AtC mesh create_faceset plane.................................................................................................1880
syntax................................................................................................................................................1880
examples...........................................................................................................................................1880
description.........................................................................................................................................1880
restrictions.........................................................................................................................................1880
related................................................................................................................................................1880
default...............................................................................................................................................1880
fix_modify AtC mesh create_nodeset..........................................................................................................1881
syntax................................................................................................................................................1881
examples...........................................................................................................................................1881
description.........................................................................................................................................1881
restrictions.........................................................................................................................................1881
related................................................................................................................................................1881
default...............................................................................................................................................1881
fix_modify AtC mesh delete_elements........................................................................................................1882
syntax................................................................................................................................................1882
examples...........................................................................................................................................1882
description.........................................................................................................................................1882
restrictions.........................................................................................................................................1882
related................................................................................................................................................1882
default...............................................................................................................................................1882
fix_modify AtC mesh nodeset_to_elementset.............................................................................................1883
syntax................................................................................................................................................1883
examples...........................................................................................................................................1883
description.........................................................................................................................................1883
restrictions.........................................................................................................................................1883
related................................................................................................................................................1883
default...............................................................................................................................................1883
fix_modify AtC mesh output........................................................................................................................1884
syntax................................................................................................................................................1884
examples...........................................................................................................................................1884
xxxii

LAMMPS Users Manual

Table of Contents
fix_modify AtC mesh output
description.........................................................................................................................................1884
restrictions.........................................................................................................................................1884
related................................................................................................................................................1884
default...............................................................................................................................................1884
fix_modify AtC mesh quadrature................................................................................................................1885
syntax................................................................................................................................................1885
examples...........................................................................................................................................1885
description.........................................................................................................................................1885
restrictions.........................................................................................................................................1885
related................................................................................................................................................1885
default...............................................................................................................................................1885
fix_modify AtC mesh read...........................................................................................................................1886
syntax................................................................................................................................................1886
examples...........................................................................................................................................1886
description.........................................................................................................................................1886
restrictions.........................................................................................................................................1886
related................................................................................................................................................1886
default...............................................................................................................................................1886
fix_modify AtC mesh write..........................................................................................................................1887
syntax................................................................................................................................................1887
examples...........................................................................................................................................1887
description.........................................................................................................................................1887
restrictions.........................................................................................................................................1887
related................................................................................................................................................1887
default...............................................................................................................................................1887
fix_modify AtC time_integration (momentum).........................................................................................1888
syntax................................................................................................................................................1888
description.........................................................................................................................................1888
examples...........................................................................................................................................1888
description.........................................................................................................................................1888
related................................................................................................................................................1888
default...............................................................................................................................................1888
fix_modify AtC output..................................................................................................................................1889
syntax................................................................................................................................................1889
examples...........................................................................................................................................1889
description.........................................................................................................................................1889
restrictions.........................................................................................................................................1889
related................................................................................................................................................1889
default...............................................................................................................................................1889

xxxiii

LAMMPS Users Manual

Table of Contents
fix_modify AtC output elementset...............................................................................................................1890
syntax................................................................................................................................................1890
examples...........................................................................................................................................1890
description.........................................................................................................................................1890
restrictions.........................................................................................................................................1890
related................................................................................................................................................1890
default...............................................................................................................................................1890
fix_modify AtC output nodeset....................................................................................................................1891
syntax................................................................................................................................................1891
examples...........................................................................................................................................1891
description.........................................................................................................................................1891
restrictions.........................................................................................................................................1891
related................................................................................................................................................1891
default...............................................................................................................................................1891
fix_modify AtC pair_interactions/bond_interactions................................................................................1892
syntax................................................................................................................................................1892
examples...........................................................................................................................................1892
description.........................................................................................................................................1892
restrictions.........................................................................................................................................1892
related................................................................................................................................................1892
default...............................................................................................................................................1892
fix_modify AtC poisson_solver....................................................................................................................1893
syntax................................................................................................................................................1893
examples...........................................................................................................................................1893
description.........................................................................................................................................1893
restrictions.........................................................................................................................................1893
related................................................................................................................................................1893
default...............................................................................................................................................1893
fix_modify AtC read_restart........................................................................................................................1894
syntax................................................................................................................................................1894
examples...........................................................................................................................................1894
description.........................................................................................................................................1894
restrictions.........................................................................................................................................1894
related................................................................................................................................................1894
default...............................................................................................................................................1894
fix_modify AtC remove_molecule...............................................................................................................1895
syntax................................................................................................................................................1895
examples...........................................................................................................................................1895
description.........................................................................................................................................1895
restrictions.........................................................................................................................................1895
related................................................................................................................................................1895
default...............................................................................................................................................1895

xxxiv

LAMMPS Users Manual

Table of Contents
fix_modify AtC remove_source...................................................................................................................1896
syntax................................................................................................................................................1896
examples...........................................................................................................................................1896
description.........................................................................................................................................1896
restrictions.........................................................................................................................................1896
related................................................................................................................................................1896
default...............................................................................................................................................1896
fix_modify AtC remove_species...................................................................................................................1897
syntax................................................................................................................................................1897
examples...........................................................................................................................................1897
description.........................................................................................................................................1897
restrictions.........................................................................................................................................1897
related................................................................................................................................................1897
default...............................................................................................................................................1897
fix_modify AtC reset_atomic_reference_positions....................................................................................1898
syntax................................................................................................................................................1898
examples...........................................................................................................................................1898
description.........................................................................................................................................1898
restrictions.........................................................................................................................................1898
related................................................................................................................................................1898
default...............................................................................................................................................1898
fix_modify AtC reset_time...........................................................................................................................1899
syntax................................................................................................................................................1899
examples...........................................................................................................................................1899
description.........................................................................................................................................1899
restrictions.........................................................................................................................................1899
related................................................................................................................................................1899
default...............................................................................................................................................1899
syntax................................................................................................................................................1899
examples...........................................................................................................................................1899
description.........................................................................................................................................1899
restrictions.........................................................................................................................................1899
related................................................................................................................................................1899
default...............................................................................................................................................1899
fix_modify AtC sample_frequency..............................................................................................................1901
syntax................................................................................................................................................1901
examples...........................................................................................................................................1901
description.........................................................................................................................................1901
restrictions.........................................................................................................................................1901
related................................................................................................................................................1901
default...............................................................................................................................................1901

xxxv

LAMMPS Users Manual

Table of Contents
fix_modify AtC set........................................................................................................................................1902
syntax................................................................................................................................................1902
examples...........................................................................................................................................1902
description.........................................................................................................................................1902
restrictions.........................................................................................................................................1902
related................................................................................................................................................1902
default...............................................................................................................................................1902
fix_modify AtC source..................................................................................................................................1903
syntax................................................................................................................................................1903
examples...........................................................................................................................................1903
description.........................................................................................................................................1903
restrictions.........................................................................................................................................1903
related................................................................................................................................................1903
default...............................................................................................................................................1903
fix_modify AtC source_integration.............................................................................................................1904
syntax................................................................................................................................................1904
examples...........................................................................................................................................1904
description.........................................................................................................................................1904
restrictions.........................................................................................................................................1904
related................................................................................................................................................1904
default...............................................................................................................................................1904
fix_modify AtC temperature_definition.....................................................................................................1905
syntax................................................................................................................................................1905
examples...........................................................................................................................................1905
description.........................................................................................................................................1905
restrictions.........................................................................................................................................1905
default...............................................................................................................................................1905
fix_modify AtC time_integration (thermal)...............................................................................................1906
syntax................................................................................................................................................1906
description.........................................................................................................................................1906
examples...........................................................................................................................................1906
description.........................................................................................................................................1906
related................................................................................................................................................1906
default...............................................................................................................................................1906
fix_modify AtC filter.....................................................................................................................................1907
syntax................................................................................................................................................1907
examples...........................................................................................................................................1907
description.........................................................................................................................................1907
restrictions.........................................................................................................................................1907
related................................................................................................................................................1907
default...............................................................................................................................................1907

xxxvi

LAMMPS Users Manual

Table of Contents
fix_modify AtC track_displacement...........................................................................................................1908
syntax................................................................................................................................................1908
examples...........................................................................................................................................1908
description.........................................................................................................................................1908
restrictions.........................................................................................................................................1908
default...............................................................................................................................................1908
fix_modify AtC unfix_flux...........................................................................................................................1909
syntax................................................................................................................................................1909
examples...........................................................................................................................................1909
description.........................................................................................................................................1909
restrictions.........................................................................................................................................1909
related................................................................................................................................................1909
default...............................................................................................................................................1909
fix_modify AtC unfix....................................................................................................................................1910
syntax................................................................................................................................................1910
examples...........................................................................................................................................1910
description.........................................................................................................................................1910
restrictions.........................................................................................................................................1910
related................................................................................................................................................1910
default...............................................................................................................................................1910
fix_modify AtC write_atom_weights...........................................................................................................1911
syntax................................................................................................................................................1911
examples...........................................................................................................................................1911
description.........................................................................................................................................1911
restrictions.........................................................................................................................................1911
related................................................................................................................................................1911
default...............................................................................................................................................1911
fix_modify AtC write_restart.......................................................................................................................1912
syntax................................................................................................................................................1912
examples...........................................................................................................................................1912
description.........................................................................................................................................1912
restrictions.........................................................................................................................................1912
related................................................................................................................................................1912
default...............................................................................................................................................1912

xxxvii

LAMMPS Documentation
31 Mar 2017 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.
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
1

LAMMPS Users Manual
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 via the Make.py script
2.5 Building LAMMPS as a library
2.6 Running LAMMPS
2.7 Command-line options
2.8 Screen output
2.9 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
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
2

LAMMPS Users Manual
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
7. Example problems
8. Performance & scalability
9. Additional tools
10. 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
11. 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
12. Errors
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
3

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 What is LAMMPS
1.2 LAMMPS features
1.3 LAMMPS non-features
1.4 Open source distribution
1.5 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 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
4

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

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

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

7

LAMMPS Users Manual
Specialized features

These are LAMMPS capabilities which you may not think of as typical 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:
• 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.
8

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

9

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

10

LAMMPS Users Manual
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 pleased to add them to the Pictures or Movies pages of the LAMMPS WWW
site.
The core group of LAMMPS developers is at Sandia National Labs:
• Steve Plimpton, sjplimp at sandia.gov
• Aidan Thompson, athomps at sandia.gov
• Paul Crozier, pscrozi at sandia.gov
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-CG-CMM and USER-OMP packages
• Roy Pollock (LLNL), Ewald and PPPM solvers
• Mike Brown (ORNL), brownw at ornl.gov, GPU 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 package
• 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
11

LAMMPS Users Manual
• Georg Gunzenmuller (EMI), georg.ganzenmueller at emi.fhg.de, USER-SPH 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)

12

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 What's in the LAMMPS distribution
2.2 Making LAMMPS
2.3 Making LAMMPS with optional packages
2.4 Building LAMMPS via the Make.py script
2.5 Building LAMMPS as a library
2.6 Running LAMMPS
2.7 Command-line options
2.8 Screen output
2.9 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.

13

LAMMPS Users Manual
2.2 Making LAMMPS
This section has the following sub-sections:
2.2.1 Read this first
2.2.1 Steps to build a LAMMPS executable
2.2.3 Common errors that can occur when making LAMMPS
2.2.4 Additional build tips
2.2.5 Building for a Mac
2.2.6 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
just 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 want to do one of the following:
• use optional LAMMPS features that require additional libraries
• use optional packages that require additional libraries
• use optional accelerator packages that require special compiler/linker settings
• run on a specialized platform that has its own compilers, settings, or other libs to use
then building LAMMPS is more complicated. You may need to find where auxiliary libraries exist on your
machine or install them if they don't. You may need to build additional libraries that are part of the LAMMPS
package, before building LAMMPS. You may need to edit a Makefile.machine file to make it compatible with
your system.
Note that there is a Make.py tool in the src directory that automates several of these steps, but you still have to
know what you are doing. Section 2.4 below describes the tool. It is a convenient way to work with
installing/un-installing various packages, the Makefile.machine changes required by some packages, and the
auxiliary libraries some of them use.
14

LAMMPS Users Manual
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 that users have are often not really 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

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

LAMMPS Users Manual
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
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_XDR
• -DLAMMPS_SMALLBIG
• -DLAMMPS_BIGBIG
• -DLAMMPS_SMALLSMALL
16

LAMMPS Users Manual
• -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 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.
If you use -DLAMMPS_XDR, the build will include XDR compatibility files for doing particle dumps in
XTC format. This is only necessary if your platform does have its own XDR files available. See the
Restrictions section of the dump command for details.
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.

17

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

18

LAMMPS Users Manual
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 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.
FFTW is a fast, portable library that should also work on any platform. 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. Note that on some
platforms FFTW2 has been pre-installed, and uses renamed files indicating the precision it was compiled
with, e.g. sfftw.h, or dfftw.h instead of fftw.h. In this case, you can specify an additional define variable for
FFT_INC called -DFFTW_SIZE, which will select the correct include file. In this case, for FFT_LIB you
must also manually specify the correct library, namely -lsfftw or -ldfftw.
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.
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.

19

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

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

LAMMPS Users Manual
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. Since none of the current LAMMPS core developers has significant experience
building executables on Windows, we are happy to distribute contributed instructions and modifications, 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 "daily builds" (and some older versions) of the installer packages from
rpm.lammps.org/windows.html. These executables are built with most optional packages 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
2.3.4 Packages that require Makefile.machine settings
Note that the following Section 2.4 describes the Make.py tool which can be used to install/un-install
packages and build the auxiliary libraries which some of them use. It can also auto-edit a Makefile.machine to
add settings needed by some packages.
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, including specific instructions for building
LAMMPS with each package, which are covered in a more general manner below.

22

LAMMPS Users Manual
You can see the list of all packages by typing "make package" from within the src directory of the LAMMPS
distribution. This also lists various make commands that can be used to manipulate 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 also type
lmp_machine -h

to run your executable with the optional -h command-line switch for "help", which will simply list the styles
and commands known to your executable, and immediately exit.
There are two kinds of packages in LAMMPS, standard and user packages. More information about the
contents of standard and user packages is given in Section 4 of the manual. The difference between standard
and user packages is as follows:
Standard packages, such as molecule or kspace, are supported by the LAMMPS developers and are written in
a syntax and style consistent with the rest of LAMMPS. This means we will answer questions about them,
debug and fix them if necessary, and keep them compatible with future changes to LAMMPS.
User packages, such as user-atc or user-omp, have been contributed by users, and always begin with the user
prefix. If they are a single command (single file), they are typically in the user-misc package. Otherwise, they
are a set of files grouped together which add a specific functionality to the code.
User packages don't necessarily meet the requirements of the standard packages. 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 either a standard or user-contributed
package are given in this section of the documentation.
Including/excluding packages

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

or
make no-manybody
make mpi

NOTE: You should NOT include/exclude 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.
Some packages have individual files that depend on other packages being included. 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.
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 auxiliary libraries (see below), and
23

LAMMPS Users Manual
will also produce a smaller executable which may run a bit faster.
When you download a LAMMPS tarball, these 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 included or excluded by typing "make yes-name" or "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 "make yes-standard", "make no-standard", "make yes-std", "make
no-std", "make yes-user", "make no-user", "make yes-lib", "make no-lib", "make yes-all", or "make no-all" to
include/exclude various sets of packages. Type "make package" to see all of the package-related make
options.
NOTE: Inclusion/exclusion of 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
seen or not seen when LAMMPS is built. After you have included or excluded a package, you must re-build
LAMMPS.
Additional package-related make options exist to help manage LAMMPS 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 WWW site.
Typing "make package-update" or "make pu" will overwrite src files with files from the package
sub-directories if the package has been included. It should be used after a patch is installed, 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-status" or "make ps" will show which packages are currently included. For those that
are included, it will list any files that are different in the src directory and package sub-directory. Typing
"make package-diff" lists all differences between these files. Again, 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 additional auxiliary libraries. Many of them are provided
with LAMMPS, in which case they must be compiled first, before LAMMPS is built, if you wish to include
that package. If you get a LAMMPS build error about a missing library, this is likely the reason. See the
Section 4 doc page for a list of packages that have these kinds of auxiliary libraries.
The lib directory in the distribution has sub-directories with package names that correspond to the needed
auxiliary libs, e.g. lib/gpu. Each sub-directory has a README file that gives more details. Code for most of
the auxiliary libraries is included in that directory. Examples are the USER-ATC and MEAM packages.
A few of the lib sub-directories do not include code, but do include instructions (and sometimes scripts) that
automate the process of downloading the auxiliary library and installing it so LAMMPS can link to it.
Examples are the KIM, VORONOI, USER-MOLFILE, and USER-SMD packages.
The lib/python directory (for the PYTHON package) contains only a choice of Makefile.lammps.* files. This
is because no auxiliary code or libraries are needed, only the Python library and other system libs that should
already available on your system. However, the Makefile.lammps file is needed to tell LAMMPS which libs
to use and where to find them.
24

LAMMPS Users Manual
For libraries with provided code, the sub-directory README file (e.g. lib/atc/README) has instructions on
how to build that library. This information is also summarized in Section 4. Typically this is done by typing
something like:
make -f Makefile.g++

If one of the provided Makefiles is not appropriate for your system you will need to edit or add one. Note that
all the Makefiles have a setting for EXTRAMAKE at the top that specifies a Makefile.lammps.* file.
If the library build is successful, it will produce 2 files in the lib directory:
libpackage.a
Makefile.lammps

The Makefile.lammps file will typically be a copy of one of the Makefile.lammps.* files in the library
directory.
Note that you must insure that the settings in Makefile.lammps are appropriate for your system. If they are
not, the LAMMPS build may fail. To fix this, you can edit or create a new Makefile.lammps.* file for your
system, and copy it to Makefile.lammps.
As explained in the lib/package/README files, the settings in Makefile.lammps are used to specify
additional system libraries and their locations so that LAMMPS can build with the auxiliary library. For
example, if the MEAM package is used, the auxiliary library consists of F90 code, built with a Fortran
complier. To link that library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS is built
with, typically requires additional Fortran-to-C libraries be included in the link. Another example are the
BLAS and LAPACK libraries needed to use the USER-ATC or USER-AWPMD packages.
For libraries without provided code, the sub-directory README file has information on where to download
the library and how to build it, e.g. lib/voronoi/README and lib/smd/README. The README files also
describe how you must either (a) create soft links, via the "ln" command, in those directories to point to where
you built or installed the packages, or (b) check or edit the Makefile.lammps file in the same directory to
provide that information.
Some of the sub-directories, e.g. lib/voronoi, also have an install.py script which can be used to automate the
process of downloading/building/installing the auxiliary library, and setting the needed soft links. Type
"python install.py" for further instructions.
As with the sub-directories containing library code, if the soft links or settings in the
lib/package/Makefile.lammps files are not correct, the LAMMPS build will typically fail.
Packages that require Makefile.machine settings

A few packages require specific settings in Makefile.machine, to either build or use the package effectively.
These are the USER-INTEL, KOKKOS, USER-OMP, and OPT packages, used for accelerating code
performance on CPUs or other hardware, as discussed in Section 5.3.
A summary of what Makefile.machine changes are needed for each of these packages is given in Section 4.
The details are given on the doc pages that describe each of these accelerator packages in detail:

25

LAMMPS Users Manual
5.3.1 USER-INTEL package
5.3.3 KOKKOS package
5.3.4 USER-OMP package
5.3.5 OPT package
You can also look at the following machine Makefiles in src/MAKE/OPTIONS, which include the changes.
Note that the USER-INTEL and KOKKOS packages allow for settings that build LAMMPS for different
hardware. The USER-INTEL package builds for CPU and the Xeon Phi, the KOKKOS package builds for
OpenMP, GPUs (Cuda), and the Xeon Phi.
• Makefile.intel_cpu
• Makefile.intel_phi
• Makefile.kokkos_omp
• Makefile.kokkos_cuda
• Makefile.kokkos_phi
• Makefile.omp
• Makefile.opt
Also note that the Make.py tool, described in the next Section 2.4 can automatically add the needed info to an
existing machine Makefile, using simple command-line arguments.
2.4 Building LAMMPS via the Make.py tool
The src directory includes a Make.py script, written in Python, which can be used to automate various steps of
the build process. It is particularly useful for working with the accelerator packages, as well as other packages
which require auxiliary libraries to be built.
The goal of the Make.py tool is to allow any complex multi-step LAMMPS build to be performed as a single
Make.py command. And you can archive the commands, so they can be re-invoked later via the -r (redo)
switch. If you find some LAMMPS build procedure that can't be done in a single Make.py command, let the
developers know, and we'll see if we can augment the tool.
You can run Make.py from the src directory by typing either:
Make.py -h
python Make.py -h

which will give you help info about the tool. For the former to work, you may need to edit the first line of
Make.py to point to your local Python. And you may need to insure the script is executable:
chmod +x Make.py

Here are examples of build tasks you can perform with Make.py:
Install/uninstall packages
Build specific auxiliary libs
Build libs for all installed packages
Create a Makefile from scratch with compiler and MPI
settings

Make.py -p no-lib kokkos omp intel
Make.py -a lib-atc lib-meam
Make.py -p cuda gpu -gpu mode=double
arch=31 -a lib-all
Make.py -m none -cc g++ -mpi mpich -a file

26

LAMMPS Users Manual
Augment Makefile.serial with settings for installed packages Make.py -p intel -intel cpu -m serial -a file
Add JPG and FFTW support to Makefile.mpi
Make.py -m mpi -jpg -fft fftw -a file
Build LAMMPS with a parallel make using Makefile.mpi
Make.py -j 16 -m mpi -a exe
Build LAMMPS and libs it needs using Makefile.serial with Make.py -p gpu intel -intel cpu -a lib-all file
accelerator settings
serial
The bench and examples directories give Make.py commands that can be used to build LAMMPS with the
various packages and options needed to run all the benchmark and example input scripts. See these files for
more details:
• bench/README
• bench/FERMI/README
• bench/KEPLER/README
• bench/PHI/README
• examples/README
• examples/accelerate/README
• examples/accelerate/make.list
All of the Make.py options and syntax help can be accessed by using the "-h" switch.
E.g. typing "Make.py -h" gives
Syntax: Make.py switch args ...
switches can be listed in any order
help switch:
-h prints help and syntax for all other specified switches
switch for actions:
-a lib-all, lib-dir, clean, file, exe or machine
list one or more actions, in any order
machine is a Makefile.machine suffix, must be last if used
one-letter switches:
-d (dir), -j (jmake), -m (makefile), -o (output),
-p (packages), -r (redo), -s (settings), -v (verbose)
switches for libs:
-atc, -awpmd, -colvars, -cuda
-gpu, -meam, -poems, -qmmm, -reax
switches for build and makefile options:
-intel, -kokkos, -cc, -mpi, -fft, -jpg, -png

Using the "-h" switch with other switches and actions gives additional info on all the other specified switches
or actions. The "-h" can be anywhere in the command-line and the other switches do not need their arguments.
E.g. type "Make.py -h -d -atc -intel" will print:
-d dir
dir = LAMMPS home dir
if -d not specified, working dir must be lammps/src
-atc make=suffix lammps=suffix2
all args are optional and can be in any order
make = use Makefile.suffix (def = g++)
lammps = use Makefile.lammps.suffix2 (def = EXTRAMAKE in makefile)
-intel mode
mode = cpu or phi (def = cpu)
build Intel package for CPU or Xeon Phi

27

LAMMPS Users Manual
Note that Make.py never overwrites an existing Makefile.machine. Instead, it creates
src/MAKE/MINE/Makefile.auto, which you can save or rename if desired. Likewise it creates an executable
named src/lmp_auto, which you can rename using the -o switch if desired.
The most recently executed Make.py command is saved in src/Make.py.last. You can use the "-r" switch (for
redo) to re-invoke the last command, or you can save a sequence of one or more Make.py commands to a file
and invoke the file of commands using "-r". You can also label the commands in the file and invoke one or
more of them by name.
A typical use of Make.py is to start with a valid Makefile.machine for your system, that works for a vanilla
LAMMPS build, i.e. when optional packages are not installed. You can then use Make.py to add various
settings (FFT, JPG, PNG) to the Makefile.machine as well as change its compiler and MPI options. You can
also add additional packages to the build, as well as build the needed supporting libraries.
You can also use Make.py to create a new Makefile.machine from scratch, using the "-m none" switch, if you
also specify what compiler and MPI options to use, via the "-cc" and "-mpi" switches.
2.5 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
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
28

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

LAMMPS Users Manual
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.6 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.
For the MPI version, which allows you to run LAMMPS under Windows on multiple processors, follow these
steps:
30

LAMMPS Users Manual
• Download and install MPICH2 for Windows.
The LAMMPS Windows installer packages will automatically adjust your path for the default
location of this MPI package. After the installation of the MPICH 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

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

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.

31

LAMMPS Users Manual
2.7 Command-line options
At run time, LAMMPS recognizes several optional command-line switches which may be used in any order.
Either the full word or a one-or-two letter abbreviation can be used:
• -e or -echo
• -h or -help
• -i or -in
• -k or -kokkos
• -l or -log
• -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 ...

32

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

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
33

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

34

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

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

36

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

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

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

39

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

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.9 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 read
it in.
(5) There are numerous small numerical changes in C++ LAMMPS that mean you will not get identical
40

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

41

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 LAMMPS input script
3.2 Parsing rules
3.3 Input script structure
3.4 Commands listed by category
3.5 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 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
42

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

43

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

LAMMPS Users Manual
A LAMMPS input script typically has 4 parts:
1. Initialization
2. Atom definition
3. Settings
4. Run a simulation
The last 2 parts can be repeated as many times as desired. I.e. run a simulation, change some settings, run
some more, etc. Each of the 4 parts is now described in more detail. Remember that almost all 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.
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.
45

LAMMPS Users Manual

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

46

LAMMPS Users Manual
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
These are additional commands in USER packages, which can be used if LAMMPS is built with the
appropriate package.
dump custom/vtk dump nc dump nc/mpiio
group2ndx
ndx2group temper/grem
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.
adapt
ave/histo
cmap
enforce2d
heat
neb

addforce
append/atoms
ave/histo/weight
ave/time
controller
deform (k)
evaporate
external
indent
langevin (k)
nph (ko)

nphug (o)

atom/swap
balance
deposit
freeze
lineforce

aveforce
bond/break
drag
gcmc
momentum (k)

ave/atom
bond/create
dt/reset
gld
move

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

nph/asphere (o)

nph/body

nph/sphere (o)

npt (kio)

ave/corre
box/rel
ehex
halt
msst
npt/asph
(o)
47

LAMMPS Users Manual
npt/body

npt/sphere (o)

nve (kio)

nve/asphere (i)

nve/asphere/noforce

nve/noforce

nve/sphere (o)

nve/tri

nvt (iko)

nvt/asphere (o)

nve/body

nve/limit

nve/lin
nvt/sph
nvt/body
nvt/sllod (io)
(o)
pour
press/berendsen
print
qeq/shielded
qeq/slater
rattle
rigid/npt (o) rigid/nve (o) rigid/nvt

oneway
orient/bcc
orient/fcc
planeforce
poems
property/atom qeq/comb (o) qeq/dynamic
qeq/fire
qeq/point
reax/bonds
recenter
restrain
rigid (o)
rigid/nph (o)
rigid/small/nph rigid/small/npt
rigid/small (o)
rigid/small/nve (o) rigid/small/nvt (o) setforce (k)
shake
spring
(o)
(o)
spring/chunk
spring/rg
spring/self
srd
store/force
store/state temp/berendsen temp/cs
temp/csvr
temp/rescale
tfmc
thermal/conductivity
tmd
ttm
tune/kspace
vecto
viscosity
viscous
wall/colloid
wall/gran
wall/gran/region wall/harmonic wall/lj1043
wall/lj1
wall/reflect
wall/lj93
wall/piston
wall/region
wall/srd
(k)
These are additional fix styles in USER packages, which can be used if LAMMPS is built with the appropriate
package.

adapt/fep
addtorque
atc
ave/correlate/long
colvars
dpd/energy
drude
drude/transform/direct drude/transform/reverse
eos/cv
eos/table
eos/table/rx
filter/corotate
flow/gauss
gle
grem
imd
ipi
langevin/drude
langevin/eff
lb/fluid
lb/momentum
lb/pc
lb/rigid/pc/sphere
lb/viscous
meso
manifoldforce
meso/stationary
nve/dot
nve/dotc/langevin
nve/manifold/rattle
nvk
nvt/manifold/rattle
nph/eff
npt/eff
nve/eff
nvt/eff
nvt/sllod/eff
phonon
pimd
qbmsst
qeq/reax
qmmm
qtb
reax/c/bonds
reax/c/species
rx
saed/vtk
shardlow
smd
smd/adjust/dt
smd/integrate/tlsph smd/integrate/ulsph smd/move/triangulated/s
smd/setvel
smd/wall/surface
temp/rescale/eff
ti/spring
ttm/mod
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.
angle
centro/atom
contact/atom
dipole/chunk
event/displace
hexorder/atom
ke/rigid
pair
property/atom
rigid/local

angle/local
chunk/atom
coord/atom
displace/atom
global/atom
improper
msd
pair/local
property/local
slice

angmom/chunk body/local
bond
bond/local
cluster/atom
cna/atom
com
com/chunk
damage/atom
dihedral
dihedral/local
dilatation/atom
erotate/asphere erotate/rigid erotate/sphere erotate/sphere/atom
group/group
gyration
gyration/chunk
heat/flux
improper/local inertia/chunk
ke
ke/atom
msd/chunk msd/nongauss omega/chunk orientorder/atom
pe
pe/atom
plasticity/atom
pressure
property/chunk
rdf
reduce
reduce/region
sna/atom
snad/atom
snav/atom
stress/atom
48

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

ackland/atom
basal/atom
dpd
dpd/atom
fep
force/tally
heat/flux/tally
ke/eff
ke/atom/eff
meso/e/atom
meso/rho/atom
meso/t/atom
pe/tally
pe/mol/tally
saed
smd/contact/radius
smd/damage
smd/hourglass/error
smd/internal/energy smd/plastic/strain smd/plastic/strain/rate
smd/rho
smd/tlsph/defgrad
smd/tlsph/dt
smd/tlsph/num/neighs smd/tlsph/shape
smd/tlsph/strain
smd/tlsph/strain/rate smd/tlsph/stress smd/triangle/mesh/vertic
smd/ulsph/num/neighs smd/ulsph/strain smd/ulsph/strain/rate smd/ulsph/stress
smd/vol
stress/tally
temp/drude
temp/eff
temp/deform/eff
temp/region/eff
temp/rotate
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 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/coul/cut (gkio)
buck/long/coul/long (o)
coul/cut (gko)
coul/long/cs
dpd (go)
eam/alloy (gkot)

zero
airebo (o)
bop
born/coul/long (go)
brownian (o)
buck/coul/long (gkio)
colloid (go)
coul/debye (gko)
coul/msm
dpd/tstat (go)
eam/fs (gkot)

hybrid
airebo/morse (o)
born (go)
born/coul/long/cs
brownian/poly (o)
buck/coul/long/cs
comb (o)
coul/dsf (gko)
coul/streitz
dsmc
eim (o)

hybrid/overlay
beck (go)
born/coul/dsf
born/coul/msm (o)
buck (gkio)
buck/coul/msm (o)
comb3
coul/long (gko)
coul/wolf (ko)
eam (gkiot)
gauss (go)
gran/hooke/history
gayberne (gio)
gran/hertz/history (o)
gran/hooke (o)
(o)
hbond/dreiding/lj (o)
hbond/dreiding/morse (o)
kim
lcbop
lj/charmm/coul/charmm/implicit lj/charmm/coul/long
line/lj
lj/charmm/coul/charmm (ko)
(ko)
(giko)
lj/charmm/coul/msm lj/charmmfsw/coul/charmmfsh
lj/charmmfsw/coul/long
lj/class2 (gko)
lj/class2/coul/cut (ko)
lj/class2/coul/long (gko)
lj/cubic (go)
lj/cut (gikot)
lj/cut/coul/long
lj/cut/coul/cut (gko)
lj/cut/coul/debye (gko)
lj/cut/coul/dsf (gko)
(gikot)
lj/cut/coul/long/cs
lj/cut/coul/msm (go)
lj/cut/dipole/cut (go)
lj/cut/dipole/long
lj/cut/tip4p/cut (o)
lj/cut/tip4p/long (ot)
lj/expand (gko)
lj/gromacs (gko)
lj/long/coul/long (o)
lj/long/dipole/long
lj/long/tip4p/long
49

LAMMPS Users Manual
lj/gromacs/coul/gromacs
(ko)
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
reax
rebo (o)
resquared (go)
snap
soft (go)
sw (gkio)
table (gko)
tersoff (gkio)
tersoff/mod (gko)
tersoff/mod/c (o)
tersoff/zbl (gko)
tip4p/cut (o)
tip4p/long (o)
tri/lj
vashishta (ko)
vashishta/table (o)
yukawa (go)
yukawa/colloid (go)
zbl (go)
These are additional pair styles in USER packages, which can be used if LAMMPS is built with the
appropriate package.
agni (o)
awpmd/cut
buck/mdf
coul/cut/soft (o)
coul/diel (o)
coul/long/soft (o)
dpd/fdt
dpd/fdt/energy
eam/cd (o)
edip (o)
eff/cut
exp6/rx
gauss/cut
kolmogorov/crespi/z
lennard/mdf
list
lj/charmm/coul/long/soft (o) lj/cut/coul/cut/soft (o) lj/cut/coul/long/soft (o) lj/cut/dipole/sf (go)
lj/cut/soft (o)
lj/cut/thole/long (o) lj/cut/tip4p/long/soft (o)
lj/mdf
lj/sdk (gko)
lj/sdk/coul/long (go)
lj/sdk/coul/msm (o)
lj/sf (o)
meam/spline (o)
meam/sw/spline
mgpt
momb
morse/smooth/linear
morse/soft
multi/lucy
multi/lucy/rx
oxdna/coaxstk
oxdna/excv
oxdna/hbond
oxdna/stk
oxdna/xstk
oxdna2/coaxstk
oxdna2/dh
oxdna2/excv
oxdna2/stk
quip
reax/c (k)
smd/hertz
smd/tlsph
smd/triangulated/surface
smd/ulsph
smtbq
sph/heatconduction
sph/idealgas
sph/lj
sph/rhosum
sph/taitwater
sph/taitwater/morris
srp
table/rx
tersoff/table (o)
thole
tip4p/long/soft (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) 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.
50

LAMMPS Users Manual
harmonic/shift (o) harmonic/shift/cut (o) oxdna/fene oxdna2/fene
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.
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 (ko)
charmmfsh
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 (o) nharmonic (o) quadratic (o)
spherical (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 (ko) umbrella (o)
These are additional improper styles in USER packages, which can be used if LAMMPS is built with the
appropriate package.

51

LAMMPS Users Manual
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 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 (go)
pppm/cg (o) pppm/disp pppm/disp/tip4p
pppm/stagger pppm/tip4p (o)

52

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

4. Packages
This section gives an overview of the add-on optional packages that extend LAMMPS functionality. Packages
are groups of files that enable a specific set of features. For example, force fields for molecular systems or
granular systems are in packages. You can see the list of all packages by typing "make package" from within
the src directory of the LAMMPS distribution.
Here are links for two tables below, which list standard and user packages.
4.1 Standard packages
4.2 User packages
Section 2.3 of the manual describes the difference between standard packages and user packages. It also has
general details on how to include/exclude specific packages as part of the LAMMPS build process, and on
how to build auxiliary libraries or modify a machine Makefile if a package requires it.
Following the two tables below, is a sub-section for each package. It has a summary of what the package
contains. It has specific instructions on how to install it, build or obtain any auxiliary library it requires, and
any Makefile.machine changes it requires. It also lists pointers to examples of its use or documentation
provided in the LAMMPS distribution. If you want to know the complete list of commands that a package
adds to LAMMPS, simply list the files in its directory, e.g. "ls src/GRANULAR". Source files with names
that start with compute, fix, pair, bond, etc correspond to command styles with the same names.
NOTE: The USER package sub-sections below are still being filled in, as of March 2016.
Unless otherwise noted below, every package is independent of all the others. I.e. any package can be
included or excluded in a LAMMPS build, independent of all other packages. However, note that some
packages include commands derived from commands in other packages. If the other package is not installed,
the derived command from the new package will also not be installed when you include the new one. E.g. the
pair lj/cut/coul/long/omp command from the USER-OMP package will not be installed as part of the
USER-OMP package if the KSPACE package is not also installed, since it contains the pair lj/cut/coul/long
command. If you later install the KSPACE package and the USER-OMP package is already installed, both the
pair lj/cut/coul/long and lj/cut/coul/long/omp commands will be installed.
4.1 Standard packages
The current list of standard packages is as follows. Each package name links to a sub-section below with more
details.
Package
ASPHERE
BODY

Description
aspherical particles
body-style particles

Author(s)
-

CLASS2

class 2 force fields

-

COLLOID

colloidal particles

Kumar (1)

COMPRESS

I/O compression

Doc page
Section 6.6.14
body
pair_style
lj/class2
atom_style
colloid
dump */gz

Example
ellipse
body

Library
-

-

-

colloid

-

-

53

LAMMPS Users Manual
Axel Kohlmeyer (Temple
U)
Hendrik Heenen
CORESHELL adiabatic core/shell model
(Technical U of Munich)
DIPOLE

point dipole particles

-

GPU
GRANULAR

GPU-enabled styles
granular systems

KIM

openKIM potentials

Mike Brown (ORNL)
Smirichinski & Elliot &
Tadmor (3)
Trott & Moore (4)

KOKKOS

Kokkos-enabled styles
long-range Coulombic
KSPACE
solvers
MANYBODY many-body potentials
MEAM
modified EAM potential
MC
Monte Carlo options
molecular system force
MOLECULE
fields
OPT
PERI
POEMS
PYTHON
REAX
REPLICA
RIGID
SHOCK
SNAP
SRD
VORONOI

optimized pair styles

pair_style
dipole/cut
Section 5.3.1
Section 6.6.6
pair_style kim

coreshell

-

dipole

-

gpu
pour

lib/gpu
-

kim

KIM

Section 5.3.3

kokkos lib/kokkos

-

kspace_style

peptide

-

Greg Wagner (Sandia)
-

pair_style tersoff
pair_style meam
fix gcmc

shear
meam
-

lib/meam
-

-

Section 6.6.3

peptide

-

Section 5.3.5

-

-

pair_style peri

peri

-

fix poems

rigid

lib/poems

python

python

lib/python

pair_style reax

reax

lib/reax

Section 6.6.5
fix rigid
fix msst

tad
rigid
-

-

pair snap

snap

-

fix srd

srd

-

compute
voronoi/atom

-

Voro++

Fischer & Richie &
Natoli (2)
Mike Parks (Sandia)

Peridynamics models
coupled rigid body
Rudra Mukherjee (JPL)
motion
embed Python code in an
input script
Aidan Thompson
ReaxFF potential
(Sandia)
multi-replica methods
rigid bodies
shock loading methods
Aidan Thompson
quantum-fit potential
(Sandia)
stochastic rotation
dynamics
Voronoi tesselations

Section 6.6.25

Daniel Schwen (LANL)

The "Authors" column lists a name(s) if a specific person is responsible for creating and maintaining the
package.
(1) The COLLOID package includes Fast Lubrication Dynamics pair styles which were created by Amit
Kumar and Michael Bybee from Jonathan Higdon's group at UIUC.
(2) The OPT package was created by James Fischer (High Performance Technologies), David Richie, and
Vincent Natoli (Stone Ridge Technolgy).
(3) The KIM package was created by Valeriu Smirichinski, Ryan Elliott, and Ellad Tadmor (U Minn).
54

LAMMPS Users Manual
(4) The KOKKOS package was created primarily by Christian Trott and Stan Moore (Sandia). It uses the
Kokkos library which was developed by Carter Edwards, Christian Trott, and others at Sandia.
The "Doc page" column links to either a sub-section of the Section 6 of the manual, or an input script
command implemented as part of the package, or to additional documentation provided within the package.
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.
The "Library" column lists an external library which must be built first and which LAMMPS links to when it
is built. If it is listed as lib/package, then the code for the library is under the lib directory of the LAMMPS
distribution. See the lib/package/README file for info on how to build the library. If it is not listed as
lib/package, then it is a third-party library not included in the LAMMPS distribution. See details on all of this
below for individual packages.

ASPHERE package

Contents: Several computes, time-integration fixes, and pair styles for aspherical particle models: ellipsoids,
2d lines, 3d triangles.
To install via make or Make.py:
make yes-asphere
make machine
Make.py -p asphere -a machine

To un-install via make or Make.py:
make no-asphere
make machine
Make.py -p ^asphere -a machine

Supporting info: 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

BODY package

Contents: Support for body-style particles. Computes, time-integration fixes, pair styles, as well as the body
styles themselves. See the body doc page for an overview.
To install via make or Make.py:
make yes-body
make machine
Make.py -p body -a machine

To un-install via make or Make.py:
55

LAMMPS Users Manual
make no-body
make machine
Make.py -p ^body -a machine

Supporting info: atom_style body, body, pair_style body, examples/body

CLASS2 package

Contents: Bond, angle, dihedral, improper, and pair styles for the COMPASS CLASS2 molecular force field.
To install via make or Make.py:
make yes-class2
make machine
Make.py -p class2 -a machine

To un-install via make or Make.py:
make no-class2
make machine
Make.py -p ^class2 -a machine

Supporting info: bond_style class2, angle_style class2, dihedral_style class2, improper_style class2, pair_style
lj/class2

COLLOID package

Contents: Support for coarse-grained colloidal particles. Wall fix and pair styles that implement colloidal
interaction models for finite-size particles. This includes the Fast Lubrication Dynamics method for
hydrodynamic interactions, which is a simplified approximation to Stokesian dynamics.
To install via make or Make.py:
make yes-colloid
make machine
Make.py -p colloid -a machine

To un-install via make or Make.py:
make no-colloid
make machine
Make.py -p ^colloid -a machine

Supporting info: fix wall/colloid, pair_style colloid, pair_style yukawa/colloid, pair_style brownian, pair_style
lubricate, pair_style lubricateU, examples/colloid, examples/srd

56

LAMMPS Users Manual
COMPRESS package

Contents: Support for compressed output of dump files via the zlib compression library, using dump styles
with a "gz" in their style name.
Building with the COMPRESS package assumes you have the zlib compression library available on your
system. The build uses the lib/compress/Makefile.lammps file in the compile/link process. You should only
need to edit this file if the LAMMPS build cannot find the zlib info it specifies.
To install via make or Make.py:
make yes-compress
make machine
Make.py -p compress -a machine

To un-install via make or Make.py:
make no-compress
make machine
Make.py -p ^compress -a machine

Supporting info: 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
compute temp/cs command measures the temperature of a system with core/shell particles. The pair styles
augment Born, Buckingham, and Lennard-Jones styles with core/shell capabilities. See Section 6.26 for an
overview of how to use the package.
To install via make or Make.py:
make yes-coreshell
make machine
Make.py -p coreshell -a machine

To un-install via make or Make.py:
make no-coreshell
make machine
Make.py -p ^coreshell -a machine

Supporting info: Section 6.26, compute temp/cs, pair_style born/coul/long/cs, >pair_style buck/coul/long/cs,
pair_style lj/cut/coul/long/cs, examples/coreshell

57

LAMMPS Users Manual
DIPOLE package

Contents: An atom style and several pair styles to support point dipole models with short-range or long-range
interactions.
To install via make or Make.py:
make yes-dipole
make machine
Make.py -p dipole -a machine

To un-install via make or Make.py:
make no-dipole
make machine
Make.py -p ^dipole -a machine

Supporting info: 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 for NVIDIA GPUs.
All of them have a "gpu" in their style name. Section 5.3.1 gives details of what hardware and Cuda software
is required on your system, and how to build and use this package. See the KOKKOS package, which also has
GPU-enabled styles.
Building LAMMPS with the GPU package requires first building the GPU library itself, which is a set of C
and Cuda files in lib/gpu. Details of how to do this are in lib/gpu/README. As illustrated below, perform a
"make" using one of the Makefile.machine files in lib/gpu which should create a lib/reax/libgpu.a file.
Makefile.linux.* and Makefile.xk7 are examples for different platforms. There are 3 important settings in the
Makefile.machine you use:
• CUDA_HOME = where NVIDIA Cuda software is installed on your system
• CUDA_ARCH = appropriate to your GPU hardware
• CUDA_PREC = precision (double, mixed, single) you desire
See example Makefile.machine files in lib/gpu for the syntax of these settings. See
lib/gpu/Makefile.linux.double for ARCH settings for various NVIDIA GPUs. The "make" also creates a
lib/gpu/Makefile.lammps file. This file has settings that enable LAMMPS to link with Cuda libraries. If the
settings in Makefile.lammps for your machine are not correct, the LAMMPS link will fail. Note that the
Make.py script has a "-gpu" option to allow the GPU library (with several of its options) and LAMMPS to be
built in one step, with Type "python src/Make.py -h -gpu" to see the details.
To install via make or Make.py:
cd ~/lammps/lib/gpu
make -f Makefile.linux.mixed
cd ~/lammps/src
make yes-gpu

# for example

58

LAMMPS Users Manual
make machine
Make.py -p gpu -gpu mode=mixed arch=35 -a machine

To un-install via make or Make.py:
make no-gpu
make machine
Make.py -p ^gpu -a machine

Supporting info: src/GPU/README, lib/gpu/README, Section 5.3, Section 5.3.1, Pair Styles section of
Section 3.5 for any pair style listed with a (g), kspace_style, package gpu, examples/accelerate, bench/FERMI,
bench/KEPLER

GRANULAR package

Contents: Fixes and pair styles that support models of finite-size granular particles, which interact with each
other and boundaries via frictional and dissipative potentials.
To install via make or Make.py:
make yes-granular
make machine
Make.py -p granular -a machine

To un-install via make or Make.py:
make no-granular
make machine
Make.py -p ^granular -a machine

Supporting info: Section 6.6, fix pour, fix wall/gran, pair_style gran/hooke, pair_style gran/hertz/history,
examples/pour, bench/in.chute

KIM package

Contents: A pair style that interfaces to the Knowledge Base for Interatomic Models (KIM) repository of
interatomic potentials, so that KIM potentials can be used in a LAMMPS simulation.
To build LAMMPS with the KIM package you must have previously installed the KIM API (library) on your
system. The lib/kim/README file explains how to download and install KIM. Building with the KIM
package also uses the lib/kim/Makefile.lammps file in the compile/link process. You should not need to edit
this file.
To install via make or Make.py:
make yes-kim
make machine

59

LAMMPS Users Manual
Make.py -p kim -a machine

To un-install via make or Make.py:
make no-kim
make machine
Make.py -p ^kim -a machine

Supporting info: src/KIM/README, lib/kim/README, pair_style kim, examples/kim

KOKKOS package

Contents: Dozens of atom, pair, bond, angle, dihedral, improper styles which run with the Kokkos library to
provide optimization for multicore CPUs (via OpenMP), NVIDIA GPUs, or the Intel Xeon Phi (in native
mode). All of them have a "kk" 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. See the GPU, OPT, USER-INTEL,
USER-OMP packages, which also provide optimizations for the same range of hardware.
Building with the KOKKOS package requires choosing which of 3 hardware options you are optimizing for:
CPU acceleration via OpenMP, GPU acceleration, or Intel Xeon Phi. (You can build multiple times to create
LAMMPS executables for different hardware.) It also requires a C++11 compatible compiler. For GPUs, the
NVIDIA "nvcc" compiler is used, and an appropriate KOKKOS_ARCH setting should be made in your
Makefile.machine for your GPU hardware and NVIDIA software.
The simplest way to do this is to use Makefile.kokkos_cuda or Makefile.kokkos_omp or Makefile.kokkos_phi
in src/MAKE/OPTIONS, via "make kokkos_cuda" or "make kokkos_omp" or "make kokkos_phi". (Check the
KOKKOS_ARCH setting in Makefile.kokkos_cuda), Or, as illustrated below, you can use the Make.py script
with its "-kokkos" option to choose which hardware to build for. Type "python src/Make.py -h -kokkos" to see
the details. If these methods do not work on your system, you will need to read the Section 5.3.3 doc page for
details of what Makefile.machine settings are needed.
To install via make or Make.py for each of 3 hardware options:
make
make
make
make

yes-kokkos
kokkos_omp
kokkos_cuda
kokkos_phi

# for CPUs with OpenMP
# for GPUs, check the KOKKOS_ARCH setting in Makefile.kokkos_cuda
# for Xeon Phis

Make.py -p kokkos -kokkos omp -a machine # for CPUs with OpenMP Make.py -p kokkos -kokkos cuda
arch=35 -a machine # for GPUs of style arch Make.py -p kokkos -kokkos phi -a machine # for Xeon Phis
To un-install via make or Make.py:
make no-kokkos
make machine
Make.py -p ^kokkos -a machine

Supporting info: src/KOKKOS/README, lib/kokkos/README, Section 5.3, Section 5.3.3, Pair Styles
section of Section 3.5 for any pair style listed with a (k), package kokkos, examples/accelerate, bench/FERMI,
bench/KEPLER
60

LAMMPS Users Manual

KSPACE package

Contents: A variety of long-range Coulombic solvers, and pair styles which compute the corresponding
short-range portion of the pairwise Coulombic interactions. These include Ewald, particle-particle
particle-mesh (PPPM), and multilevel summation method (MSM) solvers.
Building with the KSPACE 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, or 3rd party libraries like FFTW or a
vendor-supplied FFT library. See step 6 of Section 2.2.2 of the manual for details of how to select different
FFT options in your machine Makefile. The Make.py tool has an "-fft" option which can insert these settings
into your machine Makefile automatically. Type "python src/Make.py -h -fft" to see the details.
To install via make or Make.py:
make yes-kspace
make machine
Make.py -p kspace -a machine

To un-install via make or Make.py:
make no-kspace
make machine
Make.py -p ^kspace -a machine

Supporting info: kspace_style, doc/PDF/kspace.pdf, Section 6.7, Section 6.8, Section 6.9, pair_style coul,
other pair style command doc pages which have "long" or "msm" in their style name, examples/peptide,
bench/in.rhodo

MANYBODY package

Contents: A variety of many-body and bond-order potentials. These include (AI)REBO, EAM, EIM, BOP,
Stillinger-Weber, and Tersoff potentials. Do a directory listing, "ls src/MANYBODY", to see the full list.
To install via make or Make.py:
make yes-manybody
make machine
Make.py -p manybody -a machine

To un-install via make or Make.py:
make no-manybody
make machine
Make.py -p ^manybody -a machine

Supporting info:
61

LAMMPS Users Manual
Examples: Pair Styles section of Section 3.5, examples/comb, examples/eim, examples/nb3d,
examples/vashishta

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, and for performing atomic swaps and grand-canonical MC in
conjuction with dynamics.
To install via make or Make.py:
make yes-mc
make machine
Make.py -p mc -a machine

To un-install via make or Make.py:
make no-mc
make machine
Make.py -p ^mc -a machine

Supporting info: fix atom/swap, fix bond/break, fix bond/create, fix bond/swap, fix gcmc, pair_style dsmc

MEAM package

Contents: A pair style for the modified embedded atom (MEAM) potential.
Building LAMMPS with the MEAM package requires first building the MEAM library itself, which is a set
of Fortran 95 files in lib/meam. Details of how to do this are in lib/meam/README. As illustrated below,
perform a "make" using one of the Makefile.machine files in lib/meam which should create a
lib/meam/libmeam.a file. Makefile.gfortran and Makefile.ifort are examples for the GNU Fortran and Intel
Fortran compilers. The "make" also copies a lib/meam/Makefile.lammps.machine file to
lib/meam/Makefile.lammps. This file has settings that enable the C++ compiler used to build LAMMPS to
link with a Fortran library (typically the 2 compilers to be consistent e.g. both Intel compilers, or both GNU
compilers). If the settings in Makefile.lammps for your compilers and machine are not correct, the LAMMPS
link will fail. Note that the Make.py script has a "-meam" option to allow the MEAM library and LAMMPS to
be built in one step. Type "python src/Make.py -h -meam" to see the details.
NOTE: The MEAM potential can run dramatically faster if built with the Intel Fortran compiler, rather than
the GNU Fortran compiler.
To install via make or Make.py:
cd ~/lammps/lib/meam
make -f Makefile.gfortran
cd ~/lammps/src
make yes-meam
make machine

# for example

62

LAMMPS Users Manual
Make.py -p meam -meam make=gfortran -a machine

To un-install via make or Make.py:
make no-meam
make machine
Make.py -p ^meam -a machine

Supporting info: lib/meam/README, pair_style meam, examples/meam

MISC package

Contents: A variety of computes, fixes, and pair styles that are not commonly used, but don't align with other
packages. Do a directory listing, "ls src/MISC", to see the list of commands.
To install via make or Make.py:
make yes-misc
make machine
Make.py -p misc -a machine

To un-install via make or Make.py:
make no-misc
make machine
Make.py -p ^misc -a machine

Supporting info: compute ti, fix evaporate, fix tmm, fix viscosity, examples/misc

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 terms for the Dreiding
(hydrogen-bonding) and CHARMM force fields, and TIP4P water model.
To install via make or Make.py:
make yes-molecule
make machine
Make.py -p molecule -a machine

To un-install via make or Make.py:
make no-molecule
make machine
Make.py -p ^molecule -a machine

63

LAMMPS Users Manual
Supporting info: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/micelle, examples/peptide,
bench/in.chain, bench/in.rhodo

MPIIO package

Contents: Support for parallel output/input of dump and restart files via the MPIIO library, which is part of the
standard message-passing interface (MPI) 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.
To install via make or Make.py:
make yes-mpiio
make machine
Make.py -p mpiio -a machine

To un-install via make or Make.py:
make no-mpiio
make machine
Make.py -p ^mpiio -a machine

Supporting info: dump, restart, write_restart, read_restart

OPT package

Contents: A handful of pair styles with an "opt" in their style name which are optimized for improved CPU
performance on single or multiple cores. These include EAM, LJ, CHARMM, and Morse potentials. Section
5.3.5 gives details of how to build and use this package. See the KOKKOS, USER-INTEL, and USER-OMP
packages, which also have styles optimized for CPU performance.
Some C++ compilers, like the Intel compiler, require the compile flag "-restrict" to build LAMMPS with the
OPT package. It should be added to the CCFLAGS line of your Makefile.machine. Or use Makefile.opt in
src/MAKE/OPTIONS, via "make opt". For compilers that use the flag, the Make.py command adds it
automatically to the Makefile.auto file it creates and uses.
To install via make or Make.py:
make yes-opt
make machine
Make.py -p opt -a machine

To un-install via make or Make.py:
make no-opt
make machine
Make.py -p ^opt -a machine

64

LAMMPS Users Manual
Supporting info: Section 5.3, Section 5.3.5, Pair Styles section of Section 3.5 for any pair style listed with an
(t), examples/accelerate, bench/KEPLER

PERI package

Contents: Support for the Peridynamics method, a particle-based meshless continuum model. The package
includes an atom style, several computes which calculate diagnostics, and several Peridynamic pair styles
which implement different materials models.
To install via make or Make.py:
make yes-peri
make machine
Make.py -p peri -a machine

To un-install via make or Make.py:
make no-peri
make machine
Make.py -p ^peri -a machine

Supporting info: doc/PDF/PDLammps_overview.pdf, doc/PDF/PDLammps_EPS.pdf,
doc/PDF/PDLammps_VES.pdf, atom_style peri, compute damage/atom, pair_style peri/pmb, examples/peri

POEMS package

Contents: A fix that wraps the Parallelizable Open source Efficient Multibody Software (POEMS) librar,
which is able to simulate the dynamics of articulated body systems. These are systems with multiple rigid
bodies (collections of atoms or particles) whose motion is coupled by connections at hinge points.
Building LAMMPS with the POEMS package requires first building the POEMS library itself, which is a set
of C++ files in lib/poems. Details of how to do this are in lib/poems/README. As illustrated below, perform
a "make" using one of the Makefile.machine files in lib/poems which should create a lib/meam/libpoems.a
file. Makefile.g++ and Makefile.icc are examples for the GNU and Intel C++ compilers. The "make" also
creates a lib/poems/Makefile.lammps file which you should not need to change. Note the Make.py script has a
"-poems" option to allow the POEMS library and LAMMPS to be built in one step. Type "python
src/Make.py -h -poems" to see the details.
To install via make or Make.py:
cd ~/lammps/lib/poems
make -f Makefile.g++
cd ~/lammps/src
make yes-poems
make machine

# for example

Make.py -p poems -poems make=g++ -a machine

To un-install via make or Make.py:
65

LAMMPS Users Manual
make no-meam
make machine
Make.py -p ^meam -a machine

Supporting info: 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 and for other ways to use LAMMPS and Python together.
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. The build uses the contents
of the lib/python/Makefile.lammps file to find all the Python files required in the build/link process. See the
lib/python/README file if the settings in that file do not work on your system. Note that the Make.py script
has a "-python" option to allow an alternate lib/python/Makefile.lammps file to be specified and LAMMPS to
be built in one step. Type "python src/Make.py -h -python" to see the details.
To install via make or Make.py:
make yes-python
make machine
Make.py -p python -a machine

To un-install via make or Make.py:
make no-python
make machine
Make.py -p ^python -a machine

Supporting info: examples/python

QEQ package

Contents: Several fixes for performing charge equilibration (QEq) via severeal different algorithms. These can
be used with pair styles that use QEq as part of their formulation.
To install via make or Make.py:
make yes-qeq
make machine
Make.py -p qeq -a machine

To un-install via make or Make.py:
make no-qeq

66

LAMMPS Users Manual
make machine
Make.py -p ^qeq -a machine

Supporting info: fix qeq/*, examples/qeq

REAX package

Contents: A pair style for the ReaxFF potential, a universal reactive force field, as well as a fix reax/bonds
command for monitoring molecules as bonds are created and destroyed.
Building LAMMPS with the REAX package requires first building the REAX library itself, which is a set of
Fortran 95 files in lib/reax. Details of how to do this are in lib/reax/README. As illustrated below, perform a
"make" using one of the Makefile.machine files in lib/reax which should create a lib/reax/libreax.a file.
Makefile.gfortran and Makefile.ifort are examples for the GNU Fortran and Intel Fortran compilers. The
"make" also copies a lib/reax/Makefile.lammps.machine file to lib/reax/Makefile.lammps. This file has
settings that enable the C++ compiler used to build LAMMPS to link with a Fortran library (typically the 2
compilers to be consistent e.g. both Intel compilers, or both GNU compilers). If the settings in
Makefile.lammps for your compilers and machine are not correct, the LAMMPS link will fail. Note that the
Make.py script has a "-reax" option to allow the REAX library and LAMMPS to be built in one step. Type
"python src/Make.py -h -reax" to see the details.
To install via make or Make.py:
cd ~/lammps/lib/reax
make -f Makefile.gfortran
cd ~/lammps/src
make yes-reax
make machine

# for example

Make.py -p reax -reax make=gfortran -a machine

To un-install via make or Make.py:
make no-reax
make machine
Make.py -p ^reax -a machine

Supporting info: lib/reax/README, pair_style reax, fix reax/bonds, examples/reax

REPLICA package

Contents: A collection of multi-replica methods that are used by invoking multiple instances (replicas) of
LAMMPS simulations. Communication between individual replicas is performed in different ways by the
different methods. See Section 6.5 for an overview of how to run multi-replica simulations in LAMMPS.
Multi-replica methods included in the package are 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 calculation
on another set.

67

LAMMPS Users Manual
To install via make or Make.py:
make yes-replica
make machine
Make.py -p replica -a machine

To un-install via make or Make.py:
make no-replica
make machine
Make.py -p ^replica -a machine

Supporting info: Section 6.5, neb, prd, tad, temper, run_style verlet/split, examples/neb, examples/prd,
examples/tad

RIGID package

Contents: A collection of computes and fixes which enforce rigid constraints on collections of atoms or
particles. This includes SHAKE and RATTLE, as well as variants of rigid-body time integrators for a few
large bodies or many small bodies.
To install via make or Make.py:
make yes-rigid
make machine
Make.py -p rigid -a machine

To un-install via make or Make.py:
make no-rigid
make machine
Make.py -p ^rigid -a machine

Supporting info: compute erotate/rigid, fix shake, fix rattle, fix rigid/*, examples/ASPHERE, examples/rigid

SHOCK package

Contents: A small number of fixes useful for running impact simulations where a shock-wave passes through
a material.
To install via make or Make.py:
make yes-shock
make machine
Make.py -p shock -a machine

68

LAMMPS Users Manual
To un-install via make or Make.py:
make no-shock
make machine
Make.py -p ^shock -a machine

Supporting info: 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), which is an empirical potential
which can be quantum accurate when fit to an archive of DFT data. Computes useful for analyzing properties
of the potential are also included.
To install via make or Make.py:
make yes-snap
make machine
Make.py -p snap -a machine

To un-install via make or Make.py:
make no-snap
make machine
Make.py -p ^snap -a machine

Supporting info: pair snap, compute sna/atom, compute snad/atom, compute snav/atom, examples/snap

SRD package

Contents: Two fixes which implement the Stochastic Rotation Dynamics (SRD) method for coarse-graining of
a solvent, typically around large colloidal-scale particles.
To install via make or Make.py:
make yes-srd
make machine
Make.py -p srd -a machine

To un-install via make or Make.py:
make no-srd
make machine
Make.py -p ^srd -a machine

Supporting info: fix srd, fix wall/srd, examples/srd, examples/ASPHERE
69

ckage

ER-ATC

-AWPMD

CG-CMM

-CGDNA

LAMMPS Users Manual

VORONOI package

Contents: A compute voronoi/atom command which computes the Voronoi tesselation of a collection of
atoms or particles by wrapping the Voro++ lib
To build LAMMPS with the KIM package you must have previously installed the KIM API (library) on your
system. The lib/kim/README file explains how to download and install KIM. Building with the KIM
package also uses the lib/kim/Makefile.lammps file in the compile/link process. You should not need to edit
this file.
To build LAMMPS with the VORONOI package you must have previously installed the Voro++ library on
your system. The lib/voronoi/README file explains how to download and install Voro++. There is a
lib/voronoi/install.py script which automates the process. Type "python install.py" to see instructions. The
final step is to create soft links in the lib/voronoi directory for "includelink" and "liblink" which point to
installed Voro++ directories. Building with the VORONOI package uses the contents of the
lib/voronoi/Makefile.lammps file in the compile/link process. You should not need to edit this file. Note that
the Make.py script has a "-voronoi" option to allow the Voro++ library to be downloaded and/or installed and
LAMMPS to be built in one step. Type "python src/Make.py -h -voronoi" to see the details.
To install via make or Make.py:
cd ~/lammps/lib/voronoi
python install.py -g -b -l
cd ~/lammps/src
make yes-voronoi
make machine

# download Voro++, build in lib/voronoi, create links

Make.py -p voronoi -voronoi install="-g -b -l" -a machine

To un-install via make or Make.py:
make no-voronoi
make machine
Make.py -p ^voronoi -a machine

Supporting info: src/VORONOI/README, lib/voronoi/README, compute voronoi/atom, examples/voronoi
4.2 User packages
The current list of user-contributed packages is as follows:
Description
atom-to-continuum
coupling
wave-packet MD
coarse-graining
model

Author(s)
Jones & Templeton &
Zimmerman (1)
Ilya Valuev (JIHT)
Axel Kohlmeyer
(Temple U)

Doc page

Example

Pic/movie

Librar

fix atc

USER/atc

atc

lib/at

pair_style awpmd/cut

USER/awpmd

-

pair_style lj/sdk

USER/cg-cmm

cg

-

src/USER-CGDNA/README

USER/cgdna

-

-

lib/awp

70

COLVARS

FFRACTION

ER-DPD

R-DRUDE

ER-EFF

ER-FEP

R-H5MD

R-INTEL

ER-LB

R-MGPT

R-MISC

MANIFOLD

MOLFILE

NC-DUMP

R-OMP

PHONON

R-QMMM

ER-QTB

R-QUIP

R-REAXC

LAMMPS Users Manual
coarse-grained
DNA force fields
collective variables

Oliver Henrich (U
Strathclyde Glasgow)
Fiorin & Henin &
Kohlmeyer (2)

virutal x-ray and
Shawn Coleman (ARL)
electron diffraction
reactive dissipative
Larentzos & Mattox &
particle dynamics
Brennan (5)
(DPD)
Dequidt & Devemy &
Drude oscillators
Padua (3)
Andres Jaramillo-Botero
electron force field
(Caltech)
Agilio Padua (U Blaise
free energy
Pascal
perturbation
Clermont-Ferrand)
dump output via
Pierre de Buyl (KU
HDF5
Leuven)
Vectorized CPU
W. Michael Brown
and Intel(R)
(Intel)
coprocessor styles
Lattice Boltzmann
Colin Denniston (U
fluid
Western Ontario)
fast MGPT
Tomas Oppelstrup &
multi-ion potentials John Moriarty (LLNL)
single-file
USER-MISC/README
contributions
Stefan Paquay
motion on 2d
(Eindhoven U of
surface
Technology)
VMD molfile
Axel Kohlmeyer
plug-ins
(Temple U)
Lars Pastewka
dump output via
(Karlsruhe Institute of
NetCDF
Technology
OpenMP threaded
Axel Kohlmeyer
styles
(Temple U)
phonon dynamical Ling-Ti Kong (Shanghai
matrix
Jiao Tong U)
Axel Kohlmeyer
QM/MM coupling
(Temple U)
quantum nuclear
Yuan Shen (Stanford)
effects
QUIP/libatoms Albert Bartok-Partay (U
interface
Cambridge)
Metin Aktulga (LBNL)

fix colvars

USER/colvars

colvars

lib/colv

compute xrd

USER/diffraction

-

-

src/USER-DPD/README

USER/dpd

-

-

tutorial

USER/drude

-

-

pair_style eff/cut

USER/eff

eff

-

compute fep

USER/fep

-

-

dump h5md

-

-

lib/h5m

Section 5.3.2

examples/intel

-

-

fix lb/fluid

USER/lb

-

-

pair_style mgpt

USER/mgpt

-

-

USER-MISC/README

-

-

-

fix manifoldforce

USER/manifold

manifold

-

dump molfile

-

-

KIT)

dump nc / dump
nc/mpiio

-

-

Section 5.3.4

-

-

-

fix phonon

USER/phonon

-

-

fix qmmm

USER/qmmm

-

fix qtb fix qbmsst

qtb

-

pair_style quip

USER/quip

-

pair_style reaxc

reax

-

VMD-MO

lib/qmm
-

lib/qu
71

R-SMD

R-SMTBQ

ER-SPH

R-TALLY

ER-VTK

LAMMPS Users Manual
C version of
ReaxFF
smoothed Mach
dynamics
Second Moment
Tight Binding QEq potential
smoothed particle
hydrodynamics
Pairwise tallied
computes

Georg Ganzenmuller
(EMI)

SMD User Guide

USER/smd

-

-

Salles & Maras &
Politano & Tetot (4)

pair_style smtbq

USER/smtbq

-

-

SPH User Guide

USER/sph

sph

-

compute XXX/tally

USER/tally

-

-

compute custom/vtk

-

-

lib/vt

Georg Ganzenmuller
(EMI)
Axel Kohlmeyer
(Temple U)
Berger and Queteschiner
VTK-style dumps
(6)

The "Authors" column lists a name(s) if a specific person is responsible for creating and maintaining the
package.
(1) The ATC package was created by Reese Jones, Jeremy Templeton, and Jon Zimmerman (Sandia).
(2) The COLVARS package was created by Axel Kohlmeyer (Temple U) using the colvars module library
written by Giacomo Fiorin (Temple U) and Jerome Henin (LISM, Marseille, France).
(3) The DRUDE package was created by Alain Dequidt (U Blaise Pascal Clermont-Ferrand) and co-authors
Julien Devemy (CNRS) and Agilio Padua (U Blaise Pascal).
(4) The SMTBQ package was created by Nicolas Salles, Emile Maras, Olivier Politano, and Robert Tetot
(LAAS-CNRS, France).
(5) The USER-DPD package was created by James Larentzos (ARL), Timothy Mattox (Engility), and John
Brennan (ARL).
(6) The USER-VTK package was created by Richard Berger (JKU) and Daniel Queteschiner (DCS
Computing).
The "Doc page" column links to either a sub-section of the Section 6 of the manual, or an input script
command implemented as part of the package, or to additional documentation provided within the package.
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.
The "Library" column lists an external library which must be built first and which LAMMPS links to when it
is built. If it is listed as lib/package, then the code for the library is under the lib directory of the LAMMPS
distribution. See the lib/package/README file for info on how to build the library. If it is not listed as
lib/package, then it is a third-party library not included in the LAMMPS distribution. See details on all of this
below for individual packages.

72

LAMMPS Users Manual
USER-ATC package

Contents: ATC stands for atoms-to-continuum. This package implements a fix atc command to either couple
MD with continuum finite element equations or perform on-the-fly post-processing of atomic information to
continuum fields. See src/USER-ATC/README for more details.
To build LAMMPS with this package ...
To install via make or Make.py:
make yes-user-atc
make machine
Make.py -p atc -a machine

To un-install via make or Make.py:
make no-user-atc
make machine
Make.py -p ^atc -a machine

Supporting info:src/USER-ATC/README, fix atc, examples/USER/atc
Authors: Reese Jones (rjones at sandia.gov), Jeremy Templeton (jatempl at sandia.gov) and Jon Zimmerman
(jzimmer at sandia.gov) at Sandia. Contact them directly if you have questions.

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 an MD calculation. See
src/USER-AWPMD/README for more details.
To build LAMMPS with this package ...
Supporting info: src/USER-AWPMD/README, fix awpmd/cut, examples/USER/awpmd
Author: Ilya Valuev at the JIHT in Russia (valuev at physik.hu-berlin.de). Contact him directly if you have
questions.

USER-CG-CMM package

Contents: CG-CMM stands for coarse-grained ??. This package implements several pair styles and an angle
style using the coarse grained parametrization of Shinoda, DeVane, Klein, Mol Sim, 33, 27 (2007) (SDK),
with extensions to simulate ionic liquids, electrolytes, lipids and charged amino acids. See
src/USER-CG-CMM/README for more details.
Supporting info: src/USER-CG-CMM/README, pair lj/sdk, pair lj/sdk/coul/long, angle sdk,
examples/USER/cg-cmm

73

LAMMPS Users Manual
Author: Axel Kohlmeyer at Temple U (akohlmey at gmail.com). Contact him directly if you have questions.

USER-CGDNA package

Contents: The CGDNA package implements coarse-grained force fields for single- and double-stranded DNA.
These are at the moment mainly the oxDNA and oxDNA2 models, developed by Doye, Louis and Ouldridge
at the University of Oxford. The package also contains Langevin-type rigid-body integrators with improved
stability.
See these doc pages to get started:
• bond_style oxdna/fene
• bond_style oxdna2/fene
• pair_style oxdna/...
• pair_style oxdna2/...
• fix nve/dotc/langevin
Supporting info: /src/USER-CGDNA/README, bond_style oxdna/fene, bond_style oxdna2/fene, pair_style
oxdna/..., pair_style oxdna2/..., fix nve/dotc/langevin
Author: Oliver Henrich at the University of Strathclyde, Glasgow, UK and University of Edinburgh
(ohenrich@ph.ed.ac.uk). Contact him directly if you have any questions.

USER-COLVARS package

Contents: COLVARS stands for collective variables which can be used to implement Adaptive Biasing Force,
Metadynamics, Steered MD, Umbrella Sampling and Restraints. This package implements a fix colvars
command which wraps a COLVARS library which can perform those kinds of simulations. See
src/USER-COLVARS/README for more details.
Supporting info: doc/PDF/colvars-refman-lammps.pdf, src/USER-COLVARS/README,
lib/colvars/README, fix colvars, examples/USER/colvars
Authors: Axel Kohlmeyer at Temple U (akohlmey at gmail.com) wrote the fix. The COLVARS library itself
is written and maintained by Giacomo Fiorin (ICMS, Temple University, Philadelphia, PA, USA) and Jerome
Henin (LISM, CNRS, Marseille, France). Contact them directly if you have questions.

USER-DIFFRACTION package

Contents: This packages implements two computes and a fix for calculating x-ray and electron diffraction
intensities based on kinematic diffraction theory. See src/USER-DIFFRACTION/README for more details.
Supporting info: compute saed, compute xrd, fix saed/vtk, examples/USER/diffraction
Author: Shawn P. Coleman (shawn.p.coleman8.ctr at mail.mil) while at the University of Arkansas. Contact
him directly if you have questions.

74

LAMMPS Users Manual
USER-DPD package

Contents: DPD stands for dissipative particle dynamics, This package implements DPD for isothermal,
isoenergetic, isobaric and isenthalpic conditions. It also has extensions for performing reactive DPD, where
each particle has internal state for multiple species and a coupled set of chemical reaction ODEs are integrated
each timestep. The DPD equations of motion are integrated efficiently through the Shardlow splitting
algorithm. See src/USER-DPD/README for more details.
Supporting info: /src/USER-DPD/README, compute dpd compute dpd/atom fix eos/cv fix eos/table fix
eos/table/rx fix shardlow fix rx pair table/rx pair dpd/fdt pair dpd/fdt/energy pair exp6/rx pair multi/lucy pair
multi/lucy/rx, examples/USER/dpd
Authors: James Larentzos (ARL) (james.p.larentzos.civ at mail.mil), Timothy Mattox (Engility Corp)
(Timothy.Mattox at engilitycorp.com) and John Brennan (ARL) (john.k.brennan.civ at mail.mil). Contact
them directly if you have questions.

USER-DRUDE package

Contents: This package contains methods for simulating polarizable systems using thermalized Drude
oscillators. It has computes, fixes, and pair styles for this purpose. See Section 6.27 for an overview of how to
use the package. See src/USER-DRUDE/README for additional details. There are auxiliary tools for using
this package in tools/drude.
Supporting info: Section 6.27, src/USER-DRUDE/README, fix drude, fix drude/transform/*, compute
temp/drude, pair thole, pair lj/cut/thole/long, examples/USER/drude, tools/drude
Authors: Alain Dequidt at Universite Blaise Pascal Clermont-Ferrand (alain.dequidt at univ-bpclermont.fr);
co-authors: Julien Devemy, Agilio Padua. Contact them directly if you have questions.

USER-EFF package

Contents: EFF stands for electron force field. 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. See src/USER-EFF/README for more
details. There are auxiliary tools for using this package in tools/eff; see its README file.
Supporting info:
Author: Andres Jaramillo-Botero at CalTech (ajaramil at wag.caltech.edu). Contact him directly if you have
questions.

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. See src/USER-FEP/README for more details. There are auxiliary tools for using this package in
tools/fep; see its README file.

75

LAMMPS Users Manual
Supporting info: src/USER-FEP/README, fix adapt/fep, compute fep, pair_style */soft, examples/USER/fep
Author: Agilio Padua at Universite Blaise Pascal Clermont-Ferrand (agilio.padua at univ-bpclermont.fr).
Contact him directly if you have questions.

USER-H5MD package

Contents: H5MD stands for HDF5 for MD. HDF5 is a binary, portable, 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. See
src/USER-H5MD/README for more details.
Supporting info: src/USER-H5MD/README, lib/h5md/README, dump h5md
Author: Pierre de Buyl at KU Leuven (see http://pdebuyl.be) created this package as well as the H5MD format
and library. Contact him directly if you have questions.

USER-INTEL package

Contents: Dozens of pair, bond, angle, dihedral, and improper styles that are optimized for Intel CPUs and the
Intel Xeon Phi (in offload mode). 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. Also see
src/USER-INTEL/README for more details. See the KOKKOS, OPT, and USER-OMP packages, which
also have CPU and Phi-enabled styles.
Supporting info: examples/accelerate, src/USER-INTEL/TEST
Section 5.3
Author: Mike Brown at Intel (michael.w.brown at intel.com). Contact him directly if you have questions.
For the USER-INTEL package, you have 2 choices when building. You can build with CPU or Phi support.
The latter uses Xeon Phi chips in "offload" mode. Each of these modes requires additional settings in your
Makefile.machine for CCFLAGS and LINKFLAGS.
For CPU mode (if using an Intel compiler):
• CCFLAGS: add -fopenmp, -DLAMMPS_MEMALIGN=64, -restrict, -xHost, -fno-alias, -ansi-alias,
-override-limits
• LINKFLAGS: add -fopenmp
For Phi mode add the following in addition to the CPU mode flags:
• CCFLAGS: add -DLMP_INTEL_OFFLOAD and
• LINKFLAGS: add -offload
And also add this to CCFLAGS:

-offload-option,mic,compiler,"-fp-model fast=2 -mGLOB_default_function_attrs=\"gather_scatter_l

76

LAMMPS Users Manual
Examples:

USER-LB package

Supporting info:
This package contains a LAMMPS implementation of a background Lattice-Boltzmann fluid, which can be
used to model MD particles influenced by hydrodynamic forces.
See this doc page and its related commands to get started:
fix lb/fluid
The people who created this package are Frances Mackay (fmackay at uwo.ca) and Colin (cdennist at uwo.ca)
Denniston, University of Western Ontario. Contact them directly if you have questions.
Examples: examples/USER/lb

USER-MGPT package

Supporting info:
This package contains a fast implementation for LAMMPS of 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 Lawrence Livermore
National Lab (LLNL).
In the general matrix representation of MGPT, which can also be applied to f-band actinide metals, the
multi-ion potentials are evaluated on the fly during a simulation through d- or f-state matrix multiplication,
and the forces that move the ions are determined analytically. The mgpt pair style in this package calculates
forces and energies using an optimized matrix-MGPT algorithm due to Tomas Oppelstrup at LLNL.
See this doc page to get started:
pair_style mgpt
The persons who created the USER-MGPT package are Tomas Oppelstrup (oppelstrup2@llnl.gov) and John
Moriarty (moriarty2@llnl.gov) Contact them directly if you have any questions.
Examples: examples/USER/mgpt

USER-MISC package

Supporting info:
The files in this package are a potpourri of (mostly) unrelated features contributed to LAMMPS by users.
Each feature is a single pair of files (*.cpp and *.h).
77

LAMMPS Users Manual
More information about each feature can be found by reading its doc page in the LAMMPS doc directory. The
doc page which lists all LAMMPS input script commands is as follows:
Section 3.5
User-contributed features are listed at the bottom of the fix, compute, pair, etc sections.
The list of features and author of each is given in the src/USER-MISC/README file.
You should contact the author directly if you have specific questions about the feature or its coding.
Examples: examples/USER/misc

USER-MANIFOLD package

Supporting info:
This package contains a dump molfile command which uses molfile plugins that are bundled with the VMD
molecular visualization and analysis program, to enable LAMMPS to dump its information in formats
compatible with various molecular simulation tools.
This package allows LAMMPS to perform MD simulations of particles constrained on a manifold (i.e., a 2D
subspace of the 3D simulation box). It achieves this using the RATTLE constraint algorithm applied to
single-particle constraint functions g(xi,yi,zi) = 0 and their derivative (i.e. the normal of the manifold) n =
grad(g).
See this doc page to get started:
fix manifoldforce
The person who created this package is Stefan Paquay, at the Eindhoven University of Technology (TU/e),
The Netherlands (s.paquay at tue.nl). Contact him directly if you have questions.

USER-MOLFILE package

Supporting info:
This package contains a dump molfile command which uses molfile plugins that are bundled with the VMD
molecular visualization and analysis program, to enable LAMMPS to dump its information in formats
compatible with various molecular simulation tools.
The 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.
See this doc page to get started:
dump molfile
78

LAMMPS Users Manual
The person who created this package is Axel Kohlmeyer at Temple U (akohlmey at gmail.com). Contact him
directly if you have questions.

USER-NC-DUMP package

Contents: Dump styles for writing NetCDF format files. NetCDF is a binary, portable, self-describing file
format on top of HDF5. The file format contents follow the AMBER NetCDF trajectory conventions
(http://ambermd.org/netcdf/nctraj.xhtml), but include extensions to this convention. This package implements
a dump nc command and a dump nc/mpiio command to output LAMMPS snapshots in this format. See
src/USER-NC-DUMP/README for more details.
NetCDF files can be directly visualized with the following tools:
• Ovito (http://www.ovito.org/). Ovito supports the AMBER convention and all of the above
extensions.
• 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
The person who created these files is Lars Pastewka at Karlsruhe Institute of Technology (lars.pastewka at
kit.edu). Contact him directly if you have questions.

USER-OMP package

Supporting info:
This package provides OpenMP multi-threading support and other optimizations of various LAMMPS pair
styles, dihedral styles, and fix styles.
See this section of the manual to get started:
Section 5.3
The person who created this package is Axel Kohlmeyer at Temple U (akohlmey at gmail.com). Contact him
directly if you have questions.
For the USER-OMP package, your Makefile.machine needs additional settings for CCFLAGS and
LINKFLAGS.
• CCFLAGS: add -fopenmp and -restrict
• LINKFLAGS: add -fopenmp
Examples: examples/accelerate, bench/KEPLER

USER-PHONON package

This package contains a fix phonon command that calculates dynamical matrices, which can then be used to
compute phonon dispersion relations, directly from molecular dynamics simulations.
79

LAMMPS Users Manual
See this doc page to get started:
fix phonon
The person who created this package is Ling-Ti Kong (konglt at sjtu.edu.cn) at Shanghai Jiao Tong
University. Contact him directly if you have questions.
Examples: examples/USER/phonon

USER-QMMM package

Supporting info:
This package provides a fix qmmm command which allows LAMMPS to be used in a QM/MM simulation,
currently only in combination with pw.x code from the Quantum ESPRESSO package.
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.
See this doc page to get started:
fix qmmm
as well as the lib/qmmm/README file.
The person who created this package is Axel Kohlmeyer at Temple U (akohlmey at gmail.com). Contact him
directly if you have questions.

USER-QTB package

Supporting info:
This package provides a self-consistent quantum treatment of the 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, alter the energy power spectrum and the heat capacity towards their quantum nature. This
package could be of interest if one wants to model systems at temperatures lower than their classical limits or
when temperatures ramp up across the classical limits in the simulation.
See these two doc pages to get started:
fix qtb provides quantum nulcear correction through a colored thermostat and can be used with other time
integration schemes like fix nve or fix nph.
fix qbmsst enables quantum nuclear correction of a multi-scale shock technique simulation by coupling the
quantum thermal bath with the shocked system.
The person who created this package is Yuan Shen (sy0302 at stanford.edu) at Stanford University. Contact
him directly if you have questions.
80

LAMMPS Users Manual
Examples: examples/USER/qtb

USER-QUIP package

Supporting info:
Examples: examples/USER/quip

USER-REAXC package

Supporting info:
This package contains a implementation for LAMMPS of the ReaxFF force field. ReaxFF uses
distance-dependent bond-order functions to represent the contributions of chemical bonding to the potential
energy. It was originally developed by Adri van Duin and the Goddard group at CalTech.
The USER-REAXC version of ReaxFF (pair_style reax/c), implemented in C, should give identical or very
similar results to pair_style reax, which is a ReaxFF implementation on top of a Fortran library, a version of
which library was originally authored by Adri van Duin.
The reax/c version should be somewhat faster and more scalable, particularly with respect to the charge
equilibration calculation. It should also be easier to build and use since there are no complicating issues with
Fortran memory allocation or linking to a Fortran library.
For technical details about this implementation of ReaxFF, see this paper:
Parallel and Scalable Reactive Molecular Dynamics: Numerical Methods and Algorithmic Techniques, H. M.
Aktulga, J. C. Fogarty, S. A. Pandit, A. Y. Grama, Parallel Computing, in press (2011).
See the doc page for the pair_style reax/c command for details of how to use it in LAMMPS.
The person who created this package is Hasan Metin Aktulga (hmaktulga at lbl.gov), while at Purdue
University. Contact him directly, or Aidan Thompson at Sandia (athomps at sandia.gov), if you have
questions.
Examples: examples/reax

USER-SMD package

Supporting info:
This package implements smoothed Mach dynamics (SMD) in LAMMPS. Currently, the package has the
following features:
* Does liquids via traditional Smooth Particle Hydrodynamics (SPH)
* Also solves solids mechanics problems via a state of the art stabilized meshless method with hourglass
control.
81

LAMMPS Users Manual
* Can specify hydrostatic interactions independently from material strength models, i.e. pressure and
deviatoric stresses are separated.
* Many material models available (Johnson-Cook, plasticity with hardening, Mie-Grueneisen, Polynomial
EOS). Easy to add new material models.
* Rigid boundary conditions (walls) can be loaded as surface geometries from *.STL files.
See the file doc/PDF/SMD_LAMMPS_userguide.pdf to get started.
There are example scripts for using this package in examples/USER/smd.
The person who created this package is Georg Ganzenmuller at the Fraunhofer-Institute for High-Speed
Dynamics, Ernst Mach Institute in Germany (georg.ganzenmueller at emi.fhg.de). Contact him directly if you
have questions.
Examples: examples/USER/smd

USER-SMTBQ package

Supporting info:
This package implements the Second Moment Tight Binding - QEq (SMTB-Q) potential for the description of
ionocovalent bonds in oxides.
There are example scripts for using this package in examples/USER/smtbq.
See this doc page to get started:
pair_style smtbq
The persons who created the USER-SMTBQ package are Nicolas Salles, Emile Maras, Olivier Politano,
Robert Tetot, who can be contacted at these email addresses: lammps@u-bourgogne.fr, nsalles@laas.fr.
Contact them directly if you have any questions.
Examples: examples/USER/smtbq

USER-SPH package

Supporting info:
This package implements smoothed particle hydrodynamics (SPH) in LAMMPS. Currently, the package has
the following features:
* Tait, ideal gas, Lennard-Jones equation of states, full support for complete (i.e. internal-energy dependent)
equations of state
* Plain or Monaghans XSPH integration of the equations of motion

82

LAMMPS Users Manual
* Density continuity or density summation to propagate the density field
* Commands to set internal energy and density of particles from the input script
* Output commands to access internal energy and density for dumping and thermo output
See the file doc/PDF/SPH_LAMMPS_userguide.pdf to get started.
There are example scripts for using this package in examples/USER/sph.
The person who created this package is Georg Ganzenmuller at the Fraunhofer-Institute for High-Speed
Dynamics, Ernst Mach Institute in Germany (georg.ganzenmueller at emi.fhg.de). Contact him directly if you
have questions.
Examples: examples/USER/sph

USER-TALLY package

Supporting info:
Examples: examples/USER/tally

USER-VTK package

83

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

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

85

LAMMPS Users Manual

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 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
86

LAMMPS Users Manual
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 lj/cut/gpu
• pair_style lj/cut/intel
• pair_style lj/cut/kk
• pair_style lj/cut/omp
• pair_style lj/cut/opt
To see what accelerate styles are currently available, 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
only needed for KOKKOS package

enable specific accelerator support via '-k on' command-line switch,
set any needed options for the package via "-pk" command-line switch
only if defaults need to be changed
or package command,
use accelerated styles in your input via "-sf" command-line switch or
lmp_machine -in in.script -sf gpu
suffix command
Note that the first 4 steps can be done as a single command, using the src/Make.py tool. This tool is discussed
in Section 2.4 of the manual, and its use is illustrated in the individual accelerator sections. Typically these
steps only need to be done once, to create an executable that uses one or more accelerator packages.

The last 4 steps can all be done from the command-line when LAMMPS is launched, without changing your
input script, as illustrated in the individual accelerator sections. Or you can add package and suffix commands
to your input script.
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:

87

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

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

89

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

90

LAMMPS Users Manual
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, using the src/Make.py script, described in Section 2.4 of the manual.
Type "Make.py -h" for help. If run from the src directory, this command will create src/lmp_gpu using
src/MAKE/Makefile.mpi as the starting Makefile.machine:
Make.py -p gpu -gpu mode=single arch=31 -o gpu -a lib-gpu file mpi

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
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
91

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

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

93

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, harmonic
• Dihedral Styles: charmm, harmonic, opls
• Fixes: nve, npt, nvt, nvt/sllod
• Improper Styles: cvff, harmonic
• Pair Styles: buck/coul/cut, buck/coul/long, buck, eam, gayberne, charmm/coul/long, lj/cut,
lj/cut/coul/long, sw, tersoff
• K-Space Styles: pppm
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. 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).

94

LAMMPS Users Manual

Results are speedups obtained on Intel Xeon E5-2697v4 processors (code-named Broadwell) and Intel Xeon
Phi 7250 processors (code-named Knights Landing) with "18 Jun 2016" LAMMPS built with Intel Parallel
Studio 2016 update 3. Results are with 1 MPI task per physical core. See src/USER-INTEL/TEST/README
for the raw simulation rates and instructions to reproduce.
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.
For Intel Xeon CPUs:
• Edit src/MAKE/OPTIONS/Makefile.intel_cpu_intelmpi as necessary.
• If using kspace_style pppm in the input script, add "neigh_modify binsize 3" and "kspace_modify diff
ad" to the input script for better performance.
• "-pk intel 0 omp 2 -sf intel" added to LAMMPS command-line
For Intel Xeon Phi CPUs for simulations without kspace_style pppm in the input script
• Edit src/MAKE/OPTIONS/Makefile.knl as necessary.
• Runs should be performed using MCDRAM.
• "-pk intel 0 omp 2 -sf intel" or "-pk intel 0 omp 4 -sf intel" should be added to the LAMMPS
command-line. Choice for best performance will depend on the simulation.
For Intel Xeon Phi CPUs for simulations with kspace_style pppm in the input script:
• Edit src/MAKE/OPTIONS/Makefile.knl as necessary.
• Runs should be performed using MCDRAM.
95

LAMMPS Users Manual
• Add "neigh_modify binsize 3" to the input script for better performance.
• Add "kspace_modify diff ad" to the input script for better performance.
• export KMP_AFFINITY=none
• "-pk intel 0 omp 3 lrt yes -sf intel" or "-pk intel 0 omp 1 lrt yes -sf intel" added to LAMMPS
command-line. Choice for best performance will depend on the simulation.
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.
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

96

LAMMPS Users Manual
Building LAMMPS with the USER-INTEL package:
The USER-INTEL package must be installed into the source directory:
make yes-user-intel

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, the build can be accomplished with the src/Make.py script, described in Section 2.4 of the
manual. Type "Make.py -h" for help. For an example:
Make.py -v -p intel omp -intel cpu -a file intel_cpu_intelmpi

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.
"-DLAMMPS_MEMALIGN=64" is required for CCFLAGS. When using Intel compilers, "-restrict" is
required and "-qopenmp" is highly recommended for CCFLAGS and LINKFLAGS. LIB should include
"-ltbbmalloc". 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". The Make.py command will add
all of these automatically.
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 package, 2) specify the number of OpenMP
97

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

# 2 n
# Don

LAMMPS Users Manual
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 and neigh_modify binsize 3 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.
On Intel Xeon Phi x200 series CPUs, this will likely always 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 machine. To use this 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.
Not all styles are supported in the USER-INTEL package. You can mix the 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.
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:

99

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

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

LAMMPS Users Manual
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 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
International Conference for High Performance Computing. In press.
• 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.

101

LAMMPS Users Manual
Previous Section - LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands
Return to Section accelerate overview
5.3.3 KOKKOS package

The KOKKOS package was developed primarily by Christian Trott (Sandia) with contributions of various
styles by others, including Sikandar Mashayak (UIUC), Stan Moore (Sandia), and Ray Shan (Sandia). The
underlying Kokkos library was written primarily by Carter Edwards, Christian Trott, and Dan Sunderland (all
Sandia).
The 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 library is part of Trilinos and can also be downloaded from Github. Kokkos is a templated C++
library that provides two key abstractions for an application like LAMMPS. First, it allows a single
implementation of an application kernel (e.g. a pair style) to run efficiently on different kinds of hardware,
such as a GPU, Intel Phi, or many-core CPU.
The Kokkos library also provides data abstractions to adjust (at compile time) the memory layout of basic data
structures like 2d and 3d arrays and allow the transparent utilization of special hardware load and store
operations. Such data structures are used in LAMMPS to store atom coordinates or forces or neighbor lists.
The layout is chosen to optimize performance on different platforms. Again this functionality is hidden from
the developer, and does not affect how the kernel is coded.
These abstractions are set at build time, when LAMMPS is compiled with the KOKKOS package installed.
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.
Kokkos currently provides support for 3 modes of execution (per MPI task). These are OpenMP (for
many-core CPUs), Cuda (for NVIDIA GPUs), and OpenMP (for Intel Phi). Note that the KOKKOS package
supports running on the Phi in native mode, not offload mode like the USER-INTEL package supports. You
choose the mode at build time to produce an executable compatible with specific hardware.
Here is a quick overview of how to use the KOKKOS package for CPU acceleration, assuming one or more
16-core nodes. More details follow.

use a C++11 compatible compiler
make yes-kokkos
make mpi KOKKOS_DEVICES=OpenMP
# build with the KOKKOS package
make kokkos_omp
# or Makefile.kokkos_omp already has variable se
Make.py -v -p kokkos -kokkos omp -o mpi -a file mpi
# or one-line build via Make.py
mpirun
mpirun
mpirun
mpirun

-np
-np
-np
-np

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

#
#
#
#

1
2
1
8

node, 16 MPI tasks/node, no threa
nodes, 1 MPI task/node, 16 thread
node, 2 MPI tasks/node, 8 threads
nodes, 4 MPI tasks/node, 4 thread

• specify variables and settings in your Makefile.machine that enable OpenMP, GPU, or Phi support
• include the KOKKOS package and build LAMMPS

102

LAMMPS Users Manual
• enable the KOKKOS package and its hardware options via the "-k on" command-line switch use
KOKKOS styles in your input script
Here is a quick overview of how to use the KOKKOS package for GPUs, assuming one or more nodes, each
with 16 cores and a GPU. More details follow.
discuss use of NVCC, which Makefiles to examine
use a C++11 compatible compiler
KOKKOS_DEVICES = Cuda, OpenMP
KOKKOS_ARCH = Kepler35
make yes-kokkos
make machine
Make.py -p kokkos -kokkos cuda arch=31 -o kokkos_cuda -a file kokkos_cuda
mpirun -np 1 lmp_cuda -k on t 6 -sf kk -in in.lj
mpirun -np 4 -ppn 1 lmp_cuda -k on t 6 -sf kk -in in.lj

# one MPI task, 6 threads on CPU
# ditto on 4 nodes

mpirun -np 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj
mpirun -np 32 -ppn 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj

# two MPI tasks, 8 threads per C
# ditto on 16 nodes

Here is a quick overview of how to use the KOKKOS package for the Intel Phi:
use a C++11 compatible compiler
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNC
make yes-kokkos
make machine
Make.py -p kokkos -kokkos phi -o kokkos_phi -a file mpi

host=MIC, Intel Phi with 61 cores (240 threads/phi via 4x hardware threading):
mpirun -np 1 lmp_g++ -k on t 240 -sf kk -in in.lj
# 1 MPI task on 1 Phi, 1*240 = 240
mpirun -np 30 lmp_g++ -k on t 8 -sf kk -in in.lj
# 30 MPI tasks on 1 Phi, 30*8 = 240
mpirun -np 12 lmp_g++ -k on t 20 -sf kk -in in.lj
# 12 MPI tasks on 1 Phi, 12*20 = 24
mpirun -np 96 -ppn 12 lmp_g++ -k on t 20 -sf kk -in in.lj
# ditto on 8 Phis

Required hardware/software:
Kokkos support within LAMMPS must be built with a C++11 compatible compiler. If using gcc, version
4.7.2 or later is required.
To build with Kokkos support for CPUs, 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.
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.
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 supported by Telsa generation GPUs (or
older).
To build with Kokkos support for Intel Xeon Phi coprocessors, your sysmte must be configured to use them in
"native" mode, not "offload" mode like the USER-INTEL package supports.

103

LAMMPS Users Manual
Building LAMMPS with the KOKKOS package:
You must choose at build time whether to build for CPUs (OpenMP), GPUs, or Phi.
You can do any of these in one line, using the src/Make.py script, described in Section 2.4 of the manual.
Type "Make.py -h" for help. If run from the src directory, these commands will create src/lmp_kokkos_omp,
lmp_kokkos_cuda, and lmp_kokkos_phi. Note that the OMP and PHI options use src/MAKE/Makefile.mpi as
the starting Makefile.machine. The CUDA option uses src/MAKE/OPTIONS/Makefile.kokkos_cuda.
The latter two steps can be done using the "-k on", "-pk kokkos" and "-sf kk" command-line switches
respectively. Or the effect of the "-pk" or "-sf" switches can be duplicated by adding the package kokkos or
suffix kk commands respectively to your input script.
Or you can follow these steps:
CPU-only (run all-MPI or with OpenMP threading):
cd lammps/src
make yes-kokkos
make kokkos_omp

CPU-only (only MPI, no threading):
cd lammps/src
make yes-kokkos
make kokkos_mpi

Intel Xeon Phi (Intel Compiler, Intel MPI):
cd lammps/src
make yes-kokkos
make kokkos_phi

CPUs and GPUs (with MPICH):
cd lammps/src
make yes-kokkos
make kokkos_cuda_mpich

These examples set the KOKKOS-specific OMP, MIC, CUDA variables on the make command line which
requires a GNU-compatible make command. Try "gmake" if your system's standard make complains.
NOTE: If you build using make line variables and re-build LAMMPS twice with different KOKKOS options
and the *same* target, e.g. g++ in the first two examples above, 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.
NOTE: Currently, there are no precision options with the KOKKOS package. All compilation and
computation is performed in double precision.
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
104

LAMMPS Users Manual
lib/kokkos/Makefile.kokkos file.
#Default settings specific options #Options: force_uvm,use_ldg,rdc
• KOKKOS_DEVICES, values = OpenMP, Serial, Pthreads, Cuda, default = OpenMP
• KOKKOS_ARCH, values = KNC, SNB, HSW, Kepler, Kepler30, Kepler32, Kepler35, Kepler37,
Maxwell, Maxwell50, Maxwell52, Maxwell53, ARMv8, BGQ, Power7, Power8, default = none
• KOKKOS_DEBUG, values = yes, no, default = no
• KOKKOS_USE_TPLS, values = hwloc, librt, default = none
• KOKKOS_CUDA_OPTIONS, values = force_uvm, use_ldg, rdc
KOKKOS_DEVICE sets the parallelization method used for Kokkos code (within LAMMPS).
KOKKOS_DEVICES=OpenMP means that OpenMP will be used. KOKKOS_DEVICES=Pthreads means
that pthreads will be used. KOKKOS_DEVICES=Cuda means an NVIDIA GPU running CUDA will be used.
If KOKKOS_DEVICES=Cuda, then the lo-level Makefile in the src/MAKE directory must use "nvcc" as its
compiler, via its CC setting. For best performance its CCFLAGS setting should use -O3 and have a
KOKKOS_ARCH setting that matches the compute capability of your NVIDIA hardware and software
installation, e.g. KOKKOS_ARCH=Kepler30. Note the minimal required compute capability is 2.0, but this
will give significantly reduced performance compared to Kepler generation GPUs with compute capability
3.x. For the LINK setting, "nvcc" should not be used; instead use g++ or another compiler suitable for linking
C++ applications. Often you will want to use your MPI compiler wrapper for this setting (i.e. mpicxx).
Finally, the lo-level Makefile must also have a "Compilation rule" for creating *.o files from *.cu files. See
src/Makefile.cuda for an example of a lo-level Makefile with all of these settings.
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_ARCH=KNC enables compiler switches needed when compiling for an Intel Phi processor.
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 that can be useful. It also
enables runtime bounds checking on Kokkos data structures.
KOKKOS_CUDA_OPTIONS are additional options for CUDA.
For more information on Kokkos see the Kokkos programmers' guide here: /lib/kokkos/doc/Kokkos_PG.pdf.
Run with the KOKKOS 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.

105

LAMMPS Users Manual
When using KOKKOS built with host=OMP, you need to choose how many OpenMP threads per MPI task
will be used (via the "-k" command-line switch discussed below). 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.
When using the KOKKOS package built with device=CUDA, you must use exactly one MPI task per physical
GPU.
When using the KOKKOS package built with host=MIC for Intel Xeon Phi coprocessor support you need to
insure there are one or more MPI tasks per coprocessor, and choose the number of coprocessor threads to use
per MPI task (via the "-k" command-line switch discussed below). The product of MPI tasks * coprocessor
threads/task should not exceed the maximum number of threads the coprocessor is designed to run, otherwise
performance will suffer. This value is 240 for current generation Xeon Phi(TM) chips, which is 60 physical
cores * 4 threads/core. Note that with the KOKKOS package you do not need to specify how many Phi
coprocessors there are per node; each coprocessors is simply treated as running some number of MPI tasks.
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. The two
most commonly used options are:
-k on t Nt g Ng

The "t Nt" option applies to host=OMP (even if device=CUDA) and host=MIC. For host=OMP, it specifies
how many OpenMP threads per MPI task to use with a node. For host=MIC, it specifies how many Xeon Phi
threads per MPI task to use within a node. The default is Nt = 1. Note that for host=OMP this is effectively
MPI-only mode which may be fine. But for host=MIC you will typically end up using far less than all the 240
available threads, which could give very poor performance.
The "g Ng" option applies to device=CUDA. It specifies how many GPUs per compute node to use. The
default is 1, so this only needs to be specified is you have 2 or more GPUs per compute node.
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.
Use the "-sf kk" command-line switch, which will automatically append "kk" to styles that support it. Use the
"-pk kokkos" command-line switch if you wish to change any of the default package kokkos optionns set by
the "-k on" command-line switch.
Note that 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. This typically gives fastest performance. If the newton
command is used in the input script, it can override the Newton flag defaults.
However, when running in MPI-only mode with 1 thread per MPI task, 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. You can do
this with the "-pk" command-line switch.
Or run with the KOKKOS package by editing an input script:
The discussion above for the mpirun/mpiexec command and setting appropriate thread and GPU values for
host=OMP or host=MIC or device=CUDA are the same.

106

LAMMPS Users Manual
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.
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.
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 Xeon Phi, 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.
Guidelines for best performance:
Here are guidline for using the KOKKOS package on the different hardware configurations listed above.
Many of the guidelines use the package kokkos command See its doc page for details and default settings.
Experimenting with its options can provide a speed-up for specific calculations.
Running on a multi-core CPU:
If N is the number of physical cores/node, then the number of MPI tasks/node * number of threads/task should
not exceed N, and should typically equal N. Note that the default threads/task is 1, as set by the "t" keyword of
the "-k" command-line switch. If you do not change this, no additional parallelism (beyond MPI) will be
invoked on the host CPU(s).
You can compare the performance running in different modes:
• run with 1 MPI task/node and N threads/task
• run with N MPI tasks/node and 1 thread/task
• run with settings in between these extremes
Examples of mpirun commands in these modes are shown above.
107

LAMMPS Users Manual
When using KOKKOS to perform 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 the KOKKOS OMP option, 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. For binding threads with the KOKKOS pthreads option,
compile LAMMPS the KOKKOS HWLOC=yes option, as discussed in Section 2.3.4 of the manual.
Running on GPUs:
Insure the -arch setting in the machine makefile you are using, e.g. src/MAKE/Makefile.cuda, is correct for
your GPU hardware/software (see this section of the manual for details).
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.
Use the "-k" command-line switch to specify the number of GPUs per node, and the number of threads per
MPI task. 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 * number of threads/task should not exceed N. With one GPU (and one MPI task)
it may be faster to use less than all the available cores, by setting threads/task to a smaller value. This is
because using all the cores on a dual-socket node will incur extra cost to copy memory from the 2nd socket to
the GPU.
Examples of mpirun commands that follow these rules are shown above.
NOTE: When using a GPU, you will achieve the best performance if your input script does not use any 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.
You cannot yet assign multiple MPI tasks to the same GPU with the KOKKOS package. We plan to support
this in the future, similar to the GPU package in LAMMPS.
You cannot yet use both the host (multi-threaded) and device (GPU) together to compute pairwise interactions
with the KOKKOS package. We hope to support this in the future, similar to the GPU package in LAMMPS.
Running on an Intel Phi:
Kokkos only uses Intel Phi processors in their "native" mode, i.e. not hosted by a CPU.
As illustrated above, build LAMMPS with OMP=yes (the default) and MIC=yes. The latter insures code is
correctly compiled for the Intel Phi. The OMP setting means OpenMP will be used for parallelization on the
Phi, which is currently the best option within Kokkos. In the future, other options may be added.

108

LAMMPS Users Manual
Current-generation Intel Phi chips have either 61 or 57 cores. One core should be excluded for running the
OS, leaving 60 or 56 cores. Each core is hyperthreaded, so there are effectively N = 240 (4*60) or N = 224
(4*56) cores to run on.
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 2 values should be N, i.e. 240 or 224. Also,
the number of threads/task should be a multiple of 4 so that logical threads from more than one MPI task do
not run on the same physical core.
Examples of mpirun commands that follow these rules are shown above.
Restrictions:
As noted above, if using GPUs, the number of MPI tasks per compute node should equal to the number of
GPUs per compute node. In the future Kokkos will support assigning multiple MPI tasks to a single GPU.
Currently Kokkos does not support AMD GPUs due to limits in the available backend programming models.
Specifically, Kokkos requires extensive C++ support from the Kernel language. This is expected to change in
the future.

109

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
Make.py -v -p omp -o mpi -a file mpi
# or one-line build via Make.py
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
124

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

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

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

126

LAMMPS Users Manual

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, 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:

127

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:

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
128

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

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

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

130

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

LAMMPS Users Manual

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

132

LAMMPS Users Manual
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.
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 gran/history
• pair_style gran/hertzian
• pair_style gran/no_history
• pair_style dipole/cut
• pair_style gayberne
• pair_style resquared
• pair_style brownian
• pair_style lubricate
• pair_style line/lj
• pair_style tri/lj
• pair_style body
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
133

LAMMPS Users Manual
used with line segment, triangular, and body particles respectively.
Time integration

There are several fixes that perform time integration on finite-size spherical particles, meaning the integrators
update the rotational orientation and angular velocity or angular momentum of the particles:
• fix nve/sphere
• fix nvt/sphere
• fix npt/sphere
Likewise, there are 3 fixes that perform time integration on ellipsoidal particles:
• fix nve/asphere
• fix nvt/asphere
• fix npt/asphere
The advantage of these fixes is that those which thermostat the particles include the rotational degrees of
freedom in the temperature calculation and thermostatting. The fix langevin command can also be used with
its omgea or angmom options to thermostat the rotational degrees of freedom for spherical or ellipsoidal
particles. Other thermostatting fixes only operate on the translational kinetic energy of finite-size particles.
These fixes perform constant NVE time integration on line segment, triangular, and body particles:
• fix nve/line
• fix nve/tri
• fix nve/body
Note that for mixtures of point and finite-size particles, these integration fixes can only be used with groups
which contain finite-size particles.
Computes, thermodynamics, and dump output

There are several computes that calculate the temperature or rotational energy of spherical or ellipsoidal
particles:
• compute temp/sphere
• compute temp/asphere
• compute erotate/sphere
• compute erotate/asphere
These include rotational degrees of freedom in their computation. If you wish the thermodynamic output of
temperature or pressure to use one of these computes (e.g. for a system entirely composed of finite-size
particles), then the compute can be defined and the thermo_modify command used. Note that by default
thermodynamic quantities will be calculated with a temperature that only includes translational degrees of
freedom. See the thermo_style command for details.
These commands can be used to output various attributes of finite-size particles:
• dump custom
• compute property/atom
134

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

LAMMPS Users Manual
The following sub-sections discuss different LAMMPS command related to output and the kind of data they
operate on and produce:
• Global/per-atom/local data
• Scalar/vector/array data
• Thermodynamic output
• Dump file output
• Fixes that write output files
• Computes that process output quantities
• Fixes that process output quantities
• Computes that generate values to output
• Fixes that generate values to output
• Variables that generate values to output
• Summary table of output options and data flow between commands
Global/per-atom/local data

Various output-related commands work with three different styles of data: global, per-atom, or local. A global
datum is one or more system-wide values, e.g. the temperature of the system. A per-atom datum is one or
more values per atom, e.g. the kinetic energy of each atom. Local datums are calculated by each processor
based on the atoms it owns, but there may be zero or more per atom, e.g. a list of bond distances.
Scalar/vector/array data

Global, per-atom, and local datums can each come in three kinds: a single scalar value, a vector of values, or a
2d array of values. The doc page for a "compute" or "fix" or "variable" that generates data will specify both
the style and kind of data it produces, e.g. a per-atom vector.
When a quantity is accessed, as in many of the output commands discussed below, it can be referenced via the
following bracket notation, where ID in this case is the ID of a compute. The leading "c_" would be replaced
by "f_" for a fix, or "v_" for a variable:
c_ID
entire scalar, vector, or array
c_ID[I] one element of vector, one column of array
c_ID[I][J] one element of array
In other words, using one bracket reduces the dimension of the data once (vector -> scalar, array -> vector).
Using two brackets reduces the dimension twice (array -> scalar). Thus a command that uses scalar values as
input can typically also process elements of a vector or array.
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
136

LAMMPS Users Manual
intensive values; you can include a division by "natoms" in the formula if desired, to make an extensive
calculation produce an intensive result.
Dump file output

Dump file output is specified by the dump and dump_modify commands. There are several pre-defined
formats (dump atom, dump xtc, etc).
There is also a dump custom format where the user specifies what values are output with each atom.
Pre-defined atom attributes can be specified (id, x, fx, etc). Three additional kinds of keywords can also be
specified (c_ID, f_ID, v_name), where a compute or fix or variable provides the values to be output. In each
case, the compute, fix, or variable must generate per-atom values for input to the dump custom command.
There is also a dump local format where the user specifies what local values to output. A pre-defined index
keyword can be specified to enumerate the local values. Two additional kinds of keywords can also be
specified (c_ID, f_ID), where a compute or fix or variable provides the values to be output. In each case, the
compute or fix must generate local values for input to the dump local command.
Fixes that write output files

Several fixes take various quantities as input and can write output files: fix ave/time, fix ave/chunk, fix
ave/histo, fix ave/correlate, and fix print.
The fix ave/time command enables direct output to a file and/or time-averaging of global scalars or vectors.
The user specifies one or more quantities as input. These can be global compute values, global fix values, or
variables of any style except the atom style which produces per-atom values. Since a variable can refer to
keywords used by the thermo_style custom command (like temp or press) and individual per-atom values, a
wide variety of quantities can be time averaged and/or output in this way. If the inputs are one or more scalar
values, then the fix generate a global scalar or vector of output. If the inputs are one or more vector values,
then the fix generates a global vector or array of output. The time-averaged output of this fix can also be used
as input to other output commands.
The fix ave/chunk command enables direct output to a file of chunk-averaged per-atom quantities like those
output in dump files. Chunks can represent spatial bins or other collections of atoms, e.g. individual
molecules. The per-atom 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.
137

LAMMPS Users Manual
Computes that process output quantities

The compute reduce and compute reduce/region commands take one or more per-atom or local vector
quantities as inputs and "reduce" them (sum, min, max, ave) to scalar quantities. These are produced as output
values which can be used as input to other output commands.
The compute slice command take one or more global vector or array quantities as inputs and extracts a subset
of their values to create a new vector or array. These are produced as output values which can be used as input
to other output commands.
The compute property/atom command takes a list of one or more pre-defined atom attributes (id, x, fx, etc)
and stores the values in a per-atom vector or array. These are produced as output values which can be used as
input to other output commands. The list of atom attributes is the same as for the dump custom command.
The compute property/local command takes a list of one or more pre-defined local attributes (bond info, angle
info, etc) and stores the values in a local vector or array. These are produced as output values which can be
used as input to other output commands.
Fixes that process output quantities

The fix vector command can create global vectors as output from global scalars as input, accumulating them
one element at a time.
The fix ave/atom command performs time-averaging of per-atom vectors. The per-atom quantities can be
atom attributes such as position, velocity, force. They can also be per-atom quantities calculated by a
compute, by a fix, or by an atom-style variable. The time-averaged per-atom output of this fix can be used as
input to other output commands.
The fix store/state command can archive one or more per-atom attributes at a particular time, so that the old
values can be used in a future calculation or output. The list of atom attributes is the same as for the dump
custom command, including per-atom quantities calculated by a compute, by a fix, or by an atom-style
variable. The output of this fix can be used as input to other output commands.
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.

138

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

Input
global scalars
per-atom vectors
local vectors
global scalar from variable
global scalar from variable
N/A
N/A
global scalars and vectors, per-atom vectors
per-atom/local vectors
global vectors/arrays

Output
screen, log file
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

global scalars
per-atom vectors
global scalars/vectors
per-atom vectors
global/per-atom/local scalars and vectors
global scalars
per-atom vectors

global vector
per-atom vector/array
global scalar/vector/array, file
global array, file
global array, file
global array, file
per-atom vector/array

139

LAMMPS Users Manual
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 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 temp
• compute temp/sphere
• compute temp/asphere
• compute temp/com
• compute temp/deform
• compute temp/partial
• compute temp/profile
• compute temp/ramp
• compute temp/region
All but the first 3 calculate velocity biases directly (e.g. advection velocities) that are removed when
computing the thermal temperature. Compute temp/sphere and compute temp/asphere compute kinetic energy
for finite-size particles that includes rotational degrees of freedom. They both allow for velocity biases
indirectly, via an optional extra 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
140

LAMMPS Users Manual
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.
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 npt
• fix npt/sphere
• fix npt/asphere
• fix nph
• fix press/berendsen
The fix npt commands include a Nose-Hoover thermostat and barostat. Fix nph is just a Nose/Hoover
barostat; it does no thermostatting. Both fix nph and fix press/berendsen can be used in conjunction with any
of the thermostatting fixes.
As with the thermostats, fix npt and fix nph only use translational motion of the particles in computing T and
P and performing thermo/barostatting. Fix npt/sphere and fix npt/asphere thermo/barostat using not only
translation velocities but also rotational velocities for spherical and aspherical particles.
All of the barostatting fixes use the compute pressure compute to calculate a current pressure. By default, this
compute is created with a simple compute temp (see the last argument of the compute pressure command),
which is used to calculated the kinetic component of the pressure. The barostatting fixes can also use
temperature computes that remove bias for the purpose of computing the kinetic component which contributes
to the current pressure. See the doc pages for the individual fixes and for the fix_modify command for
instructions on how to assign a temperature or pressure compute to a barostatting fix.
NOTE: As with the thermostats, the Nose/Hoover methods (fix npt and fix nph) perform time integration. Fix
press/berendsen does NOT, so it should be used with one of the constant NVE fixes or with one of the NVT
fixes.
141

LAMMPS Users Manual
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.
Idealized walls can be specified via several fix commands. Fix wall/gran creates frictional walls for use with
granular particles; all the other commands create smooth walls.
• fix wall/reflect - reflective flat walls
• fix wall/lj93 - flat walls, with Lennard-Jones 9/3 potential
• fix wall/lj126 - flat walls, with Lennard-Jones 12/6 potential
• fix wall/colloid - flat walls, with pair_style colloid potential
• fix wall/harmonic - flat walls, with repulsive harmonic spring potential
• fix wall/region - use region surface as wall
• fix wall/gran - flat or curved walls with pair_style granular potential

142

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

143

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

144

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

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
145

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

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
146

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

147

LAMMPS Users Manual
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
variable
ndens equal count(all)/vol
print
"average viscosity: $v [Pa.s] @ $T K, ${ndens} /A^3"

The fifth method is related to the above Green-Kubo method, but uses the Einstein formulation, analogous to
the Einstein mean-square-displacement formulation for self-diffusivity. The time-integrated momentum fluxes
148

LAMMPS Users Manual
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:
atoms in same molecule
atoms of same atom type
all atoms with same atom property (charge,
radius, etc)
atoms in same cluster
atoms in same spatial bin
atoms in same rigid body

chunk ID = molecule ID
chunk ID = atom type
chunk ID = output of compute property/atom
chunk ID = output of compute cluster/atom command
chunk ID = bin ID
chunk ID = molecule ID used to define rigid bodies
149

LAMMPS Users Manual
atoms with similar potential energy

chunk ID = output of compute pe/atom
chunk ID = output of compute centro/atom or compute
atoms with same local defect structure
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.
Compute */chunk commands:

Currently the following computes operate on chunks of atoms to produce per-chunk values.
• compute com/chunk
• compute gyration/chunk
• compute inertia/chunk
• compute msd/chunk
• compute property/chunk
• compute temp/chunk
• compute torque/chunk
• compute vcm/chunk
They each take the ID of a compute chunk/atom command as input. As their names indicate, they calculate the
center-of-mass, radius of gyration, moments of inertia, mean-squared displacement, temperature, torque, and
velocity of center-of-mass for each chunk of atoms. The compute property/chunk command can tally the
count of atoms in each chunk and extract other per-chunk properties.
The reason these various calculations are not part of the fix ave/chunk command, is that each requires a more
complicated operation than simply summing and averaging over per-atom values in each chunk. For example,
150

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

151

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

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

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
153

LAMMPS Users Manual
freedom representing polarization are massless. An alternative is to attribute a mass to the additional degrees
of freedom and perform time integration using an extended Lagrangian technique. For the fluctuating charge
scheme this is done by fix qeq/dynamic, and for the charge-on-spring models by the methods outlined in the
next two sections. The assignment of masses to the additional degrees of freedom can lead to unphysical
trajectories if care is not exerted in choosing the parameters of the polarizable models and the simulation
conditions.
In the core-shell model the vibration of the shells is kept faster than the ionic vibrations to mimic the fast
response of the polarizable electrons. But in molecular systems thermalizing the core-Drude pairs at
temperatures comparable to the rest of the simulation leads to several problems (kinetic energy transfer, too
short a timestep, etc.) In order to avoid these problems the relative motion of the Drude particles with respect
to their cores is kept "cold" so the vibration of the core-Drude pairs is very slow, approaching the
self-consistent regime. In both models the temperature is regulated using the velocities of the center of mass
of core+shell (or Drude) pairs, but in the Drude model the actual relative core-Drude particle motion is
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

154

LAMMPS Users Manual
1
1
2
1
3
2
4
2
(...)
Bonds

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

# 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 input
155

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

LAMMPS Users Manual
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):
• 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
157

LAMMPS Users Manual
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 keyword of the special_bonds 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).

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

158

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

159

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
balance
body
cmap
colloid
comb
coreshell
controller
crack
deposit
dipole
dreiding
eim
ellipse
flow
friction

run with various acceleration options (OpenMP, GPU, Phi)
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
deposit atoms and molecules on a surface
point dipolar particles, 2d system
methanol via Dreiding FF
NaCl using the EIM potential
ellipsoidal particles in spherical solvent, 2d system
Couette and Poiseuille flow in a 2d channel
frictional contact of spherical asperities between 2d surfaces
160

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

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.

161

LAMMPS Users Manual
% convert -loop 1 *.jpg foo.gif

Uppercase directories
ASPHERE various aspherical particle models, using ellipsoids, rigid bodies, line/triangle particles, etc
COUPLE
examples of how to use LAMMPS as a library
DIFFUSE
compute diffusion coefficients via several methods
ELASTIC compute elastic constants at zero temperature
ELASTIC_T compute elastic constants at finite temperature
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.
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.

162

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

163

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

164

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

165

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

166

LAMMPS Users Manual
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov.
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).
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.

167

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

168

LAMMPS Users Manual
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.
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 input 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.
See the README file 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.
169

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

170

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

171

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 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
172

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

LAMMPS Users Manual
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
one time setup (optional)
grow
re-allocate atom arrays to longer lengths (required)
grow_reset
make array pointers in Atom and AtomVec classes consistent (required)
copy
copy info for one atom to another atom's array locations (required)
pack_comm
store an atom's info in a buffer communicated every timestep (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)
pack_reverse
store an atom's info in a buffer communicating partial forces (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)
pack_border
store an atom's info in a buffer communicated on neighbor 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)
pack_exchange
store all an atom's info to migrate to another processor (required)
unpack_exchange
retrieve an atom's info from the buffer (required)
size_restart
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)
data_vel_hybrid
parse additional velocity data unique to this atom style (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.
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
174

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

175

LAMMPS Users Manual
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
perform one time setup (required)
init_list
neighbor list setup, if needed (optional)
compute_scalar
compute a scalar quantity (optional)
compute_vector
compute a vector of quantities (optional)
compute_peratom compute one or more quantities per atom (optional)
compute_local
compute one or more quantities per processor (optional)
pack_comm
pack a buffer with items to communicate (optional)
unpack_comm
unpack the buffer (optional)
pack_reverse
pack a buffer with items to reverse communicate (optional)
unpack_reverse
unpack the buffer (optional)
remove_bias
remove velocity bias from one atom (optional)
remove_bias_all remove velocity bias from all atoms in group (optional)
restore_bias
restore velocity bias for one atom after remove_bias (optional)
restore_bias_all
same as before, but for all atoms in group (optional)
pair_tally_callback callback function for tally-style computes (optional).
memory_usage
tally memory usage (optional)
Tally-style computes are a special case, as their computation is done in two stages: the callback function is
registered with the pair style and then called from the Pair::ev_tally() function, which is called for each pair
after force and energy has been computed for this pair. Then the tallied values are retrieved with the standard
compute_scalar or compute_vector or compute_peratom methods. The 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
count
pack
write_data

write the header section of a snapshot of atoms
count the number of lines a processor will output
pack a proc's output data into a buffer
write a proc's data to a file

176

LAMMPS Users Manual
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 similar to what you want to implement.
Here is a brief description of methods you can define in your new derived class. See fix.h for details.
setmask
init
setup_pre_exchange
setup_pre_force
setup
min_setup_pre_force
min_setup
initial_integrate
pre_exchange
pre_neighbor
pre_force
post_force
final_integrate
end_of_step
write_restart
restart
grow_arrays
copy_arrays
pack_exchange
unpack_exchange
pack_restart
unpack_restart
size_restart
maxsize_restart

determines when the fix is called during the timestep (required)
initialization before a run (optional)
called before atom exchange in setup (optional)
called before force computation in setup (optional)
called immediately before the 1st timestep and after forces are computed (optional)
like setup_pre_force, but for minimizations instead of MD runs (optional)
like setup, but for minimizations instead of MD runs (optional)
called at very beginning of each timestep (optional)
called before atom exchange on re-neighboring steps (optional)
called before neighbor list build (optional)
called before pair & molecular forces are computed (optional)
called after pair & molecular forces are computed and communicated (optional)
called at end of each timestep (optional)
called at very end of timestep (optional)
dumps fix info to restart file (optional)
uses info from restart file to re-initialize the fix (optional)
allocate memory for atom-based arrays used by fix (optional)
copy atom info when an atom migrates to a new processor (optional)
store atom's data in a buffer (optional)
retrieve atom's data from a buffer (optional)
store atom's data for writing to restart file (optional)
retrieve atom's data from a restart file buffer (optional)
size of atom's data (optional)
max size of atom's data (optional)
177

LAMMPS Users Manual
setup_pre_force_respa
initial_integrate_respa
post_integrate_respa
pre_force_respa
post_force_respa
final_integrate_respa
min_pre_force

same as setup_pre_force, but for rRESPA (optional)
same as initial_integrate, but for rRESPA (optional)
called after the first half integration step is done in rRESPA (optional)
same as pre_force, but for rRESPA (optional)
same as post_force, but for rRESPA (optional)
same as final_integrate, but for rRESPA (optional)
called after pair & molecular forces are computed in minimizer (optional)
called after pair & molecular forces are computed and communicated in minimizer
min_post_force
(optional)
min_store
store extra data for linesearch based minimization on a LIFO stack (optional)
min_pushstore
push the minimization LIFO stack one element down (optional)
min_popstore
pop the minimization LIFO stack one element up (optional)
min_clearstore
clear minimization LIFO stack (optional)
min_step
reset or move forward on line search minimization (optional)
min_dof
report number of degrees of freedom added by this fix in minimization (optional)
max_alpha
report maximum allowed step size during linesearch minimization (optional)
pack_comm
pack a buffer to communicate a per-atom quantity (optional)
unpack_comm
unpack a buffer to communicate a per-atom quantity (optional)
pack_reverse_comm pack a buffer to reverse communicate a per-atom quantity (optional)
unpack_reverse_comm unpack a buffer to reverse communicate a per-atom quantity (optional)
dof
report number of degrees of freedom removed by this fix during MD (optional)
compute_scalar
return a global scalar property that the fix computes (optional)
compute_vector
return a component of a vector property that the fix computes (optional)
compute_array
return a component of an array property that the fix computes (optional)
deform
called when the box size is changed (optional)
reset_target
called when a change of the target temperature is requested during a run (optional)
reset_dt
is called when a change of the time step is requested during a run (optional)
modify_param
called when a fix_modify request is executed (optional)
memory_usage
report memory used by fix (optional)
thermo
compute quantities for thermodynamic output (optional)
Typically, only a small fraction of these methods are defined for a particular fix. Setmask is mandatory, as it
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().
Fixes that perform diagnostics typically implement end_of_step(). For an end_of_step fix, one of your fix
arguments must be the variable "nevery" which is used to determine when to call the fix and you must set this
variable in the constructor of your fix. By convention, this is the first argument the fix defines (after the ID,
group-ID, style).
If the fix needs to store information for each atom that persists from timestep to timestep, it can manage that
memory and migrate the info with the atoms as they move from processors to processor by implementing the
grow_arrays, copy_arrays, pack_exchange, and unpack_exchange methods. Similarly, the pack_restart and
unpack_restart methods can be implemented to store information about the fix in restart files. If you wish an
178

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

179

LAMMPS Users Manual

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

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
surface_interior
surface_exterior
shape_update

determine whether a point is in the region
determine if a point is within a cutoff distance inside of surc
determine if a point is within a cutoff distance outside of surf
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
180

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

181

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

182

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

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

184

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

185

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

186

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

11.2 Overview of using Python from a LAMMPS script
NOTE: It is not currently possible to use the python command described in this section with Python 3, only
with Python 2. The C API changed from Python 2 to 3 and the LAMMPS code is not compatible with both.
LAMMPS has a python command which can be used in an input script 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
187

LAMMPS Users Manual
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.
To run pure Python code from LAMMPS, you only need to build LAMMPS with the PYTHON package
installed:
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.5. 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.5 for more details.

188

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

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

190

LAMMPS Users Manual
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())

and see one line of output for each processor you run on.
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.

191

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.5 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
pypar.finalize()

192

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

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.

193

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

#
#
#
#
#
#
#
#
#
#

var = lmp.extract_variable(name,group,flag)

extract
extract
id = ID
style =

value(s) from a compute
value(s) from a fix
of compute or fix
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

194

LAMMPS Users Manual
#

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

195

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

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

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
197

LAMMPS Users Manual
combination of viz_tool.py and plot.py and gui.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.
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:

198

LAMMPS Users Manual

11.9 PyLammps interface
Please see the PyLammps Tutorial.

199

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

200

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

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

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

LAMMPS Users Manual
Angle style hybrid cannot use same angle style twice
Self-explanatory.
Angle table must range from 0 to 180 degrees
Self-explanatory.
Angle table parameters did not set N
List of angle table parameters must include N setting.
Angle_coeff command before angle_style is defined
Coefficients cannot be set in the data file or via the angle_coeff command until an angle_style has
been assigned.
Angle_coeff command before simulation box is defined
The angle_coeff command cannot be used before a read_data, read_restart, or create_box command.
Angle_coeff command when no angles allowed
The chosen atom style does not allow for angles to be defined.
Angle_style command when no angles allowed
The chosen atom style does not allow for angles to be defined.
Angles assigned incorrectly
Angles read in from the data file were not assigned correctly to atoms. This means there is something
invalid about the topology definitions.
Angles defined but no angle types
The data file header lists angles but no angle types.
Append boundary must be shrink/minimum
The boundary style of the face where atoms are added must be of type m (shrink/minimum).
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
204

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

LAMMPS Users Manual
Specified angle type is not valid.
Bad TIP4P angle type for PPPMDisp/TIP4P
Specified angle type is not valid.
Bad TIP4P bond type for PPPM/TIP4P
Specified bond type is not valid.
Bad TIP4P bond type for PPPMDisp/TIP4P
Specified bond type is not valid.
Bad fix ID in fix append/atoms command
The value of the fix_id for keyword spatial must start with 'f_'.
Bad grid of processors
The 3d grid of processors defined by the processors command does not match the number of
processors LAMMPS is being run on.
Bad kspace_modify kmax/ewald parameter
Kspace_modify values for the kmax/ewald keyword must be integers > 0
Bad kspace_modify slab parameter
Kspace_modify value for the slab/volume keyword must be >= 2.0.
Bad matrix inversion in mldivide3
This error should not occur unless the matrix is badly formed.
Bad principal moments
Fix rigid did not compute the principal moments of inertia of a rigid group of atoms correctly.
Bad quadratic solve for particle/line collision
This is an internal error. It should normally not occur.
Bad quadratic solve for particle/tri collision
This is an internal error. It should normally not occur.
Bad real space 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

206

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

LAMMPS Users Manual
The values in the tabulated file must be monotonically increasing.
BondAngle coeff for hybrid angle has invalid format
No "ba" field should appear in data file entry.
BondBond coeff for hybrid angle has invalid format
No "bb" field should appear in data file entry.
Bond_coeff command before bond_style is defined
Coefficients cannot be set in the data file or via the bond_coeff command until an bond_style has
been assigned.
Bond_coeff command before simulation box is defined
The bond_coeff command cannot be used before a read_data, read_restart, or create_box command.
Bond_coeff command when no bonds allowed
The chosen atom style does not allow for bonds to be defined.
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.
Can only use TAD with 1-processor replicas for NEB
This is current restriction for NEB as implemented in LAMMPS.
208

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

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

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

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

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

LAMMPS Users Manual
Self-explanatory.
Cannot open restart file %s
Self-explanatory.
Cannot open restart file for reading - MPI error: %s
This error was generated by MPI when reading/writing an MPI-IO restart file.
Cannot open restart file for writing - MPI error: %s
This error was generated by MPI when reading/writing an MPI-IO restart file.
Cannot open screen file
The screen file specified as a command-line argument cannot be opened. Check that the directory you
are running in allows for files to be created.
Cannot open temporary file for world counter.
Self-explanatory.
Cannot open universe log file
For a multi-partition run, the master log file cannot be opened. Check that the directory you are
running in allows for files to be created.
Cannot open universe screen file
For a multi-partition run, the master screen file cannot be opened. Check that the directory you are
running in allows for files to be created.
Cannot read from restart file - MPI error: %s
This error was generated by MPI when reading/writing an MPI-IO restart file.
Cannot read_data without add keyword after simulation box is defined
Self-explanatory.
Cannot read_restart after simulation box is defined
The read_restart command cannot be used after a read_data, read_restart, or create_box command.
Cannot redefine variable as a different style
An equal-style variable can be re-defined but only if it was originally an equal-style variable.
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.
214

LAMMPS Users Manual
Cannot set mass for this atom style
This atom style does not support mass settings for each atom type. Instead they are defined on a
per-atom basis in the data file.
Cannot set meso/cv for this atom style
Self-explanatory.
Cannot set meso/e for this atom style
Self-explanatory.
Cannot set meso/rho for this atom style
Self-explanatory.
Cannot set non-zero image flag for non-periodic dimension
Self-explanatory.
Cannot set non-zero z velocity for 2d simulation
Self-explanatory.
Cannot set quaternion for atom that has none
Self-explanatory.
Cannot set quaternion with xy components for 2d system
Self-explanatory.
Cannot set respa hybrid and any of pair/inner/middle/outer
In the rRESPA integrator, you must compute pairwise potentials either all together (pair), with
different cutoff regions (inner/middle/outer), or per hybrid sub-style (hybrid). You cannot mix those.
Cannot set respa middle without inner/outer
In the rRESPA integrator, you must define both a inner and outer setting in order to use a middle
setting.
Cannot set restart file size - MPI error: %s
This error was generated by MPI when reading/writing an MPI-IO restart file.
Cannot set smd/contact/radius for this atom style
Self-explanatory.
Cannot set smd/mass/density for this atom style
Self-explanatory.
Cannot set temperature for fix rigid/nph
The temp keyword cannot be specified.
Cannot set theta for atom that is not a line
Self-explanatory.
Cannot set this attribute for this atom style
The attribute being set does not exist for the defined atom style.
Cannot set variable z velocity for 2d simulation
Self-explanatory.
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.
215

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

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

LAMMPS Users Manual
Self-explanatory.
Cannot use chosen neighbor list style with tersoff/zbl/kk
Self-explanatory.
Cannot use compute chunk/atom bin z for 2d model
Self-explanatory.
Cannot use compute cluster/atom unless atoms have IDs
Atom IDs are used to identify clusters.
Cannot use create_atoms rotate unless single style
Self-explanatory.
Cannot use create_bonds unless atoms have IDs
This command requires a mapping from global atom IDs to local atoms, but the atoms that have been
defined have no IDs.
Cannot use create_bonds with non-molecular system
Self-explanatory.
Cannot use cwiggle in variable formula between runs
This is a function of elapsed time.
Cannot use delete_atoms bond yes with atom_style template
This is because the bonds for that atom style are 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.
218

LAMMPS Users Manual
Cannot use fix deform on a shrink-wrapped boundary
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
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.
219

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

LAMMPS Users Manual
Self-explanatory.
Cannot use neigh_modify exclude with GPU neighbor builds
This is a current limitation of the GPU implementation in LAMMPS.
Cannot use neighbor bins - box size << cutoff
Too many neighbor bins will be created. This typically happens when the simulation box is very small
in some dimension, compared to the neighbor cutoff. Use the "nsq" style instead of "bin" style.
Cannot use newton pair with beck/gpu pair style
Self-explanatory.
Cannot use newton pair with born/coul/long/gpu pair style
Self-explanatory.
Cannot use newton pair with born/coul/wolf/gpu pair style
Self-explanatory.
Cannot use newton pair with born/gpu pair style
Self-explanatory.
Cannot use newton pair with buck/coul/cut/gpu pair style
Self-explanatory.
Cannot use newton pair with buck/coul/long/gpu pair style
Self-explanatory.
Cannot use newton pair with buck/gpu pair style
Self-explanatory.
Cannot use newton pair with colloid/gpu pair style
Self-explanatory.
Cannot use newton pair with coul/cut/gpu pair style
Self-explanatory.
Cannot use newton pair with coul/debye/gpu pair style
Self-explanatory.
Cannot use newton pair with coul/dsf/gpu pair style
Self-explanatory.
Cannot use newton pair with coul/long/gpu pair style
Self-explanatory.
Cannot use newton pair with dipole/cut/gpu pair style
Self-explanatory.
Cannot use newton pair with dipole/sf/gpu pair style
Self-explanatory.
Cannot use newton pair with dpd/gpu pair style
Self-explanatory.
Cannot use newton pair with dpd/tstat/gpu pair style
Self-explanatory.
Cannot use newton pair with eam/alloy/gpu pair style
Self-explanatory.
Cannot use newton pair with eam/fs/gpu pair style
Self-explanatory.
Cannot use newton pair with eam/gpu pair style
Self-explanatory.
Cannot use newton pair with gauss/gpu pair style
Self-explanatory.
Cannot use newton pair with gayberne/gpu pair style
Self-explanatory.
Cannot use newton pair with lj/charmm/coul/long/gpu pair style
Self-explanatory.
Cannot use newton pair with lj/class2/coul/long/gpu pair style
221

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

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

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

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

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

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

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

228

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

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

230

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

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

LAMMPS Users Manual
Self-explanatory.
Could not find dump custom variable name
Self-explanatory.
Could not find dump group ID
A group ID used in the dump command does not exist.
Could not find dump local compute ID
Self-explanatory.
Could not find dump local fix ID
Self-explanatory.
Could not find dump modify compute ID
Self-explanatory.
Could not find dump modify custom atom floating point property ID
Self-explanatory.
Could not find dump modify custom atom integer property ID
Self-explanatory.
Could not find dump modify fix ID
Self-explanatory.
Could not find dump modify variable name
Self-explanatory.
Could not find fix ID to delete
Self-explanatory.
Could not find fix adapt storage fix ID
This should not happen unless you explicitly deleted a secondary fix that fix adapt created internally.
Could not find fix 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.
233

LAMMPS Users Manual
Could not find set group ID
Group ID specified in set command does not exist.
Could not find specified fix gcmc group ID
Self-explanatory.
Could not find thermo compute ID
Compute ID specified in thermo_style command does not exist.
Could not find thermo custom compute ID
The compute ID needed by thermo style custom to compute a requested quantity does not exist.
Could not find thermo custom fix ID
The fix ID needed by thermo style custom to compute a requested quantity does not exist.
Could not find thermo custom variable name
Self-explanatory.
Could not find thermo fix ID
Fix ID specified in thermo_style command does not exist.
Could not find thermo variable name
Self-explanatory.
Could not find thermo_modify pressure ID
The compute ID needed by thermo style custom to compute pressure does not exist.
Could not find thermo_modify temperature ID
The compute ID needed by thermo style custom to compute 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
234

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

LAMMPS Users Manual
Self-explanatory.
Delete_atoms command before simulation box is defined
The delete_atoms command cannot be used before a read_data, read_restart, or create_box command.
Delete_atoms cutoff > max neighbor cutoff
Can only delete atoms in atom pairs that will be in neighbor list.
Delete_atoms mol yes requires atom attribute molecule
Cannot use this option with a non-molecular system.
Delete_atoms requires a pair style be defined
This is because atom deletion within a cutoff uses a pairwise neighbor list.
Delete_bonds command before simulation box is defined
The delete_bonds command cannot be used before a read_data, read_restart, or create_box command.
Delete_bonds command with no atoms existing
No atoms are yet defined so the delete_bonds command cannot be used.
Deposition region extends outside simulation box
Self-explanatory.
Did not assign all atoms correctly
Atoms read in from a data file were not assigned correctly to processors. This is likely due to some
atom coordinates being outside a non-periodic simulation box.
Did not assign all restart atoms correctly
Atoms read in from the restart file were not assigned correctly to processors. This is likely due to
some atom coordinates being outside a non-periodic simulation box. Normally this should not happen.
You may wish to use the "remap" option on the read_restart command to see if this helps.
Did not find all elements in MEAM library file
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.
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
236

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

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

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

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

LAMMPS Users Manual
Something in the output to the file triggered an error.
Error writing out time averaged data
Something in the output to the file triggered an error.
Failed to allocate %ld bytes for array %s
Your LAMMPS simulation has run out of memory. You need to run a smaller simulation or on more
processors.
Failed to open FFmpeg pipeline to file %s
The specified file cannot be opened. Check that the path and name are correct and writable and that
the FFmpeg executable can be found and run.
Failed to reallocate %ld bytes for array %s
Your LAMMPS simulation has run out of memory. You need to run a smaller simulation or on more
processors.
Fewer SRD bins than processors in some dimension
This is not allowed. Make your SRD bin size smaller.
File variable could not read value
Check the file assigned to the variable.
Final box dimension due to fix deform is < 0.0
Self-explanatory.
Fix %s does not allow use of dynamic group
Dynamic groups have not yet been enabled for this fix.
Fix ID for compute chunk/atom does not exist
Self-explanatory.
Fix ID for compute erotate/rigid does not exist
Self-explanatory.
Fix ID for compute ke/rigid does not exist
Self-explanatory.
Fix ID for compute reduce does not exist
Self-explanatory.
Fix ID for compute slice does not exist
Self-explanatory.
Fix ID for fix ave/atom does not exist
Self-explanatory.
Fix ID for fix ave/chunk does not exist
Self-explanatory.
Fix ID for fix ave/correlate does not exist
Self-explanatory.
Fix ID for fix ave/histo does not exist
Self-explanatory.
Fix ID for fix ave/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
241

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

LAMMPS Users Manual
Self-explanatory.
Fix ave/chunk compute vector is accessed out-of-range
Self-explanatory.
Fix ave/chunk does not use chunk/atom compute
The specified compute is not for a compute chunk/atom command.
Fix ave/chunk fix does not calculate a per-atom array
Self-explanatory.
Fix ave/chunk fix does not calculate a per-atom vector
Self-explanatory.
Fix ave/chunk fix does not calculate per-atom values
Self-explanatory.
Fix ave/chunk fix vector is accessed out-of-range
Self-explanatory.
Fix ave/chunk variable is not atom-style variable
Self-explanatory.
Fix ave/correlate compute does not calculate a scalar
Self-explanatory.
Fix ave/correlate compute does not calculate a vector
Self-explanatory.
Fix ave/correlate compute vector is accessed out-of-range
The index for the vector is out of bounds.
Fix ave/correlate fix does not calculate a scalar
Self-explanatory.
Fix ave/correlate fix does not calculate a vector
Self-explanatory.
Fix ave/correlate fix vector is accessed out-of-range
The index for the vector is out of bounds.
Fix ave/correlate variable is not equal-style variable
Self-explanatory.
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.
243

LAMMPS Users Manual
Fix ave/histo compute does not calculate per-atom values
Self-explanatory.
Fix ave/histo compute vector is accessed out-of-range
Self-explanatory.
Fix ave/histo fix array is accessed out-of-range
Self-explanatory.
Fix ave/histo fix does not calculate a global array
Self-explanatory.
Fix ave/histo fix does not calculate a global scalar
Self-explanatory.
Fix ave/histo fix does not calculate a global vector
Self-explanatory.
Fix ave/histo fix does not calculate a local array
Self-explanatory.
Fix ave/histo fix does not calculate a local vector
Self-explanatory.
Fix ave/histo fix does not calculate a per-atom array
Self-explanatory.
Fix ave/histo fix does not calculate a per-atom vector
Self-explanatory.
Fix ave/histo fix does not calculate local values
Self-explanatory.
Fix ave/histo fix does not calculate per-atom values
Self-explanatory.
Fix ave/histo fix vector is accessed out-of-range
Self-explanatory.
Fix ave/histo input is invalid compute
Self-explanatory.
Fix ave/histo input is invalid fix
Self-explanatory.
Fix ave/histo input is invalid variable
Self-explanatory.
Fix ave/histo inputs are not all global, peratom, or local
All inputs in a single fix ave/histo command must be of the same style.
Fix ave/histo/weight value and weight vector lengths do not match
Self-explanatory.
Fix ave/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
244

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

LAMMPS Users Manual
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 setting the "extra angle per atom", etc header values to allow
for additional angles, etc 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
The yz setting cannot be a variable if xy deformation is also specified. This is because LAMMPS
cannot determine if the yz setting will induce a box flip which would be invalid if xy is also changing.
Fix deform is changing yz too much with xy
When both yz and xy are changing, it induces changes in xz if the box must flip from one tilt extreme
to another. Thus it is not allowed for yz to grow so much that a flip is induced.
Fix deform tilt factors require triclinic box
Cannot deform the tilt factors of a simulation box unless it is a triclinic (non-orthogonal) box.
Fix deform volume setting is invalid
Cannot use volume style unless other dimensions are being controlled.
Fix deposit and fix rigid/small not using same molecule template ID
Self-explanatory.
Fix deposit and fix shake not using same molecule template ID
Self-explanatory.
Fix deposit molecule must have atom types
The defined molecule does not specify atom types.
Fix deposit molecule must have coordinates
The defined molecule does not specify coordinates.
Fix deposit molecule template ID must be same as atom_style template ID
When using atom_style template, you cannot deposit molecules that are not in that template.
Fix deposit region cannot be dynamic
Only static regions can be used with fix deposit.
Fix deposit region does not support a bounding box
Not all regions represent bounded volumes. You cannot use such a region with the fix deposit
command.
Fix deposit shake fix does not exist
Self-explanatory.
Fix efield requires atom attribute q or mu
The atom style defined does not have this attribute.
Fix efield with dipoles cannot use atom-style variables
246

LAMMPS Users Manual
This option is not supported.
Fix evaporate molecule requires atom attribute molecule
The atom style being used does not define a molecule ID.
Fix external callback function not set
This must be done by an external program in order to use this fix.
Fix for fix ave/atom not computed at compatible time
Fixes generate their values on specific timesteps. Fix ave/atom is requesting a value on a non-allowed
timestep.
Fix for fix ave/chunk not computed at compatible time
Fixes generate their values on specific timesteps. Fix ave/chunk is requesting a value on a
non-allowed timestep.
Fix for fix ave/correlate not computed at compatible time
Fixes generate their values on specific timesteps. Fix ave/correlate is requesting a value on a
non-allowed timestep.
Fix for fix ave/histo not computed at compatible time
Fixes generate their values on specific timesteps. Fix ave/histo is requesting a value on a non-allowed
timestep.
Fix for fix ave/spatial not computed at compatible time
Fixes generate their values on specific timesteps. Fix ave/spatial is requesting a value on a
non-allowed timestep.
Fix for fix ave/time not computed at compatible time
Fixes generate their values on specific timesteps. Fix ave/time is requesting a value on a non-allowed
timestep.
Fix for fix store/state not computed at compatible time
Fixes generate their values on specific timesteps. Fix store/state is requesting a value on a
non-allowed timestep.
Fix for fix vector not computed at compatible time
Fixes generate their values on specific timesteps. Fix vector is requesting a value on a non-allowed
timestep.
Fix freeze requires atom attribute torque
The atom style defined does not have this attribute.
Fix gcmc and fix shake not using same molecule template ID
Self-explanatory.
Fix gcmc atom has charge, but atom style does not
Self-explanatory.
Fix gcmc cannot exchange individual atoms belonging to a molecule
This is an error since you should not delete only one atom of a molecule. The user has specified
atomic (non-molecular) gas exchanges, but an atom belonging to a molecule could be deleted.
Fix gcmc does not (yet) work with atom_style template
Self-explanatory.
Fix gcmc molecule command requires that atoms have molecule attributes
Should not choose the gcmc molecule feature if no molecules are being simulated. The general
molecule flag is off, but gcmc's molecule flag is on.
Fix gcmc molecule has charges, but atom style does not
Self-explanatory.
Fix gcmc molecule must have atom types
The defined molecule does not specify atom types.
Fix gcmc molecule must have coordinates
The defined molecule does not specify coordinates.
Fix gcmc molecule template ID must be same as atom_style template ID
When using atom_style template, you cannot insert molecules that are not in that template.
247

LAMMPS Users Manual
Fix gcmc put atom outside box
This should not normally happen. Contact the developers.
Fix gcmc ran out of available atom IDs
See the setting for tagint in the src/lmptype.h file.
Fix gcmc ran out of available molecule IDs
See the setting for tagint in the src/lmptype.h file.
Fix gcmc region cannot be dynamic
Only static regions can be used with fix gcmc.
Fix gcmc region does not support a bounding box
Not all regions represent bounded volumes. You cannot use such a region with the fix gcmc
command.
Fix gcmc region extends outside simulation box
Self-explanatory.
Fix gcmc shake fix does not exist
Self-explanatory.
Fix gld c coefficients must be >= 0
Self-explanatory.
Fix gld needs more prony series coefficients
Self-explanatory.
Fix gld prony terms must be > 0
Self-explanatory.
Fix gld series type must be pprony for now
Self-explanatory.
Fix gld start temperature must be >= 0
Self-explanatory.
Fix gld stop temperature must be >= 0
Self-explanatory.
Fix gld tau coefficients must be > 0
Self-explanatory.
Fix 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
248

LAMMPS Users Manual
The time window for temperature relaxation must be > 0
Fix langevin variable returned negative temperature
Self-explanatory.
Fix momentum group has no atoms
Self-explanatory.
Fix move cannot define z or vz variable for 2d problem
Self-explanatory.
Fix move cannot rotate aroung non z-axis for 2d problem
Self-explanatory.
Fix move cannot set linear z motion for 2d problem
Self-explanatory.
Fix move cannot set wiggle z motion for 2d problem
Self-explanatory.
Fix msst compute ID does not compute potential energy
Self-explanatory.
Fix msst compute ID does not compute pressure
Self-explanatory.
Fix msst compute ID does not compute temperature
Self-explanatory.
Fix msst requires a periodic box
Self-explanatory.
Fix msst tscale must satisfy 0 <= tscale < 1
Self-explanatory.
Fix npt/nph has tilted box too far in one step - periodic cell is too far from equilibrium state
Self-explanatory. The change in the box tilt is too extreme on a short timescale.
Fix 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.
249

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

LAMMPS Users Manual
Fix property/atom cannot specify mol twice
Self-explanatory.
Fix property/atom cannot specify q twice
Self-explanatory.
Fix property/atom mol when atom_style already has molecule attribute
Self-explanatory.
Fix property/atom q when atom_style already has charge attribute
Self-explanatory.
Fix property/atom vector name already exists
The name for an integer or floating-point vector must be unique.
Fix qeq has negative upper Taper radius cutoff
Self-explanatory.
Fix qeq/comb group has no atoms
Self-explanatory.
Fix qeq/comb requires atom attribute q
An atom style with charge must be used to perform charge equilibration.
Fix qeq/dynamic group has no atoms
Self-explanatory.
Fix qeq/dynamic requires atom attribute q
Self-explanatory.
Fix qeq/fire group has no atoms
Self-explanatory.
Fix qeq/fire requires atom attribute q
Self-explanatory.
Fix qeq/point group has no atoms
Self-explanatory.
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.
251

LAMMPS Users Manual
Fix restrain requires an atom map, see atom_modify
Self-explanatory.
Fix rigid atom has non-zero image flag in a non-periodic dimension
Image flags for non-periodic dimensions should not be set.
Fix rigid file has no lines
Self-explanatory.
Fix rigid langevin period must be > 0.0
Self-explanatory.
Fix rigid molecule requires atom attribute molecule
Self-explanatory.
Fix rigid npt/nph dilate group ID does not exist
Self-explanatory.
Fix rigid npt/nph does not yet allow triclinic box
This is a current restriction in LAMMPS.
Fix rigid npt/nph period must be > 0.0
Self-explanatory.
Fix rigid npt/small t_chain should not be less than 1
Self-explanatory.
Fix rigid npt/small t_order must be 3 or 5
Self-explanatory.
Fix rigid nvt/npt/nph damping parameters must be > 0.0
Self-explanatory.
Fix rigid nvt/small t_chain should not be less than 1
Self-explanatory.
Fix rigid nvt/small t_iter should not be less than 1
Self-explanatory.
Fix rigid nvt/small t_order must be 3 or 5
Self-explanatory.
Fix rigid xy torque cannot be on for 2d simulation
Self-explanatory.
Fix rigid z force cannot be on for 2d simulation
Self-explanatory.
Fix rigid/npt period must be > 0.0
Self-explanatory.
Fix rigid/npt temperature order must be 3 or 5
Self-explanatory.
Fix rigid/npt/small period must be > 0.0
Self-explanatory.
Fix rigid/nvt period must be > 0.0
Self-explanatory.
Fix rigid/nvt temperature order must be 3 or 5
Self-explanatory.
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
252

LAMMPS Users Manual
The defined molecule does not specify coordinates.
Fix rigid/small npt/nph period must be > 0.0
Self-explanatory.
Fix rigid/small nvt/npt/nph damping parameters must be > 0.0
Self-explanatory.
Fix rigid/small nvt/npt/nph dilate group ID does not exist
Self-explanatory.
Fix rigid/small requires an atom map, see atom_modify
Self-explanatory.
Fix rigid/small requires atom attribute molecule
Self-explanatory.
Fix rigid: Bad principal moments
The principal moments of inertia computed for a rigid body are not within the required tolerances.
Fix shake cannot be used with minimization
Cannot use fix shake while doing an energy minimization since it turns off bonds that should
contribute to the energy.
Fix shake molecule template must have shake info
The defined molecule does not specify SHAKE information.
Fix spring couple group ID does not exist
Self-explanatory.
Fix srd can only currently be used with comm_style brick
This is a current restriction in LAMMPS.
Fix srd lamda must be >= 0.6 of SRD grid size
This is a requirement for accuracy reasons.
Fix srd no-slip requires atom attribute torque
This is because the SRD collisions will impart torque to the solute 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
253

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

LAMMPS Users Manual
Fix vector compute does not calculate a scalar
Self-explanatory.
Fix vector compute does not calculate a vector
Self-explanatory.
Fix vector compute vector is accessed out-of-range
Self-explanatory.
Fix vector fix does not calculate a scalar
Self-explanatory.
Fix vector fix does not calculate a vector
Self-explanatory.
Fix vector fix vector is accessed out-of-range
Self-explanatory.
Fix vector variable is not equal-style variable
Self-explanatory.
Fix viscosity swap value must be positive
Self-explanatory.
Fix viscosity vtarget value must be positive
Self-explanatory.
Fix wall cutoff <= 0.0
Self-explanatory.
Fix wall/colloid requires atom style sphere
Self-explanatory.
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.
255

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

LAMMPS Users Manual
One or more of the coefficients defined in the potential file is invalid.
Illegal dump_modify sfactor value (must be > 0.0)
Self-explanatory.
Illegal dump_modify tfactor value (must be > 0.0)
Self-explanatory.
Illegal fix gcmc gas mass <= 0
The computed mass of the designated gas molecule or atom type was less than or equal to zero.
Illegal fix tfmc random seed
Seeds can only be nonzero positive integers.
Illegal fix wall/piston velocity
The piston velocity must be positive.
Illegal integrate style
Self-explanatory.
Illegal nb3b/harmonic parameter
One or more of the coefficients defined in the potential file is invalid.
Illegal number of angle table entries
There must be at least 2 table entries.
Illegal number of bond table entries
There must be at least 2 table entries.
Illegal number of pair table entries
There must be at least 2 table entries.
Illegal or unset periodicity in restart
This error should not normally occur unless the restart file is invalid.
Illegal range increment value
The increment must be >= 1.
Illegal simulation box
The lower bound of the simulation box is greater than the upper bound.
Illegal size double vector read requested
This error should not normally occur unless the restart file is invalid.
Illegal size integer vector read requested
This error should not normally occur unless the restart file is invalid.
Illegal size string or corrupt restart
This error should not normally occur unless the restart file is invalid.
Imageint setting in lmptype.h is invalid
Imageint must be as large or larger than smallint.
Imageint setting in lmptype.h is not compatible
Format of imageint stored in restart file is not consistent with LAMMPS version you are running. See
the settings in src/lmptype.h
Improper atom missing in delete_bonds
The delete_bonds command cannot find one or more atoms in a particular improper on a particular
processor. The pairwise cutoff is too short or the atoms are too far apart to make a valid improper.
Improper atom missing in set command
The set command cannot find one or more atoms in a particular improper on a particular processor.
The pairwise cutoff is too short or the atoms are too far apart to make a valid improper.
Improper atoms %d %d %d %d missing on proc %d at step %ld
One or more of 4 atoms needed to compute a 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
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
257

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

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

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

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

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

LAMMPS Users Manual
of atom types.
Invalid atom type in molecule file
Atom types must range from 1 to specified # of types.
Invalid atom type in neighbor exclusion list
Atom types must range from 1 to Ntypes inclusive.
Invalid atom type index for fix shake
Atom types must range from 1 to Ntypes inclusive.
Invalid atom types in pair_write command
Atom types must range from 1 to Ntypes inclusive.
Invalid atom vector in variable formula
The atom vector is not recognized.
Invalid atom_style body command
No body style argument was provided.
Invalid atom_style command
Self-explanatory.
Invalid attribute in dump custom command
Self-explanatory.
Invalid attribute in dump local command
Self-explanatory.
Invalid attribute in dump modify command
Self-explanatory.
Invalid basis setting in create_atoms command
The basis index must be between 1 to N where N is the number of basis atoms in the lattice. The type
index must be between 1 to N where N is the number of atom types.
Invalid basis setting in fix append/atoms command
The basis index must be between 1 to N where N is the number of basis atoms in the lattice. The type
index must be between 1 to N where N is the number of atom types.
Invalid bin bounds in compute chunk/atom
The lo/hi values are inconsistent.
Invalid bin bounds in fix ave/spatial
The lo/hi values are inconsistent.
Invalid body nparticle command
Arguments in atom-style command are not correct.
Invalid bond count in molecule file
Self-explanatory.
Invalid bond table length
Length must be 2 or greater.
Invalid bond type in Bonds section of data file
Bond type must be positive integer and within range of specified bond types.
Invalid bond type in Bonds section of molecule file
Self-explanatory.
Invalid bond type in create_bonds command
Self-explanatory.
Invalid bond type in fix bond/break command
Self-explanatory.
Invalid bond type in fix bond/create command
Self-explanatory.
Invalid bond type index for fix shake
Self-explanatory. Check the fix shake command in the input script.
Invalid coeffs for this dihedral style
Cannot set class 2 coeffs in data file for this dihedral style.
263

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

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

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

LAMMPS Users Manual
Invalid immediate variable
Syntax of immediate value is incorrect.
Invalid improper count in molecule file
Self-explanatory.
Invalid improper type in Impropers section of data file
Improper type must be positive integer and within range of specified improper types.
Invalid improper type in impropers section of molecule file
Self-explanatory.
Invalid index for non-body particles in compute body/local command
Only indices 1,2,3 can be used for non-body particles.
Invalid index in compute body/local command
Self-explanatory.
Invalid is_active() function in variable formula
Self-explanatory.
Invalid is_available() function in variable formula
Self-explanatory.
Invalid is_defined() function in variable formula
Self-explanatory.
Invalid keyword in angle table parameters
Self-explanatory.
Invalid keyword in bond table parameters
Self-explanatory.
Invalid keyword in compute angle/local command
Self-explanatory.
Invalid keyword in compute bond/local command
Self-explanatory.
Invalid keyword in compute dihedral/local command
Self-explanatory.
Invalid keyword in compute improper/local command
Self-explanatory.
Invalid keyword in compute pair/local command
Self-explanatory.
Invalid keyword in compute property/atom command
Self-explanatory.
Invalid keyword in compute property/chunk command
Self-explanatory.
Invalid keyword in compute property/local command
Self-explanatory.
Invalid keyword in dump cfg command
Self-explanatory.
Invalid keyword in pair table parameters
Keyword used in list of table parameters is not recognized.
Invalid length in set command
Self-explanatory.
Invalid mass in set command
Self-explanatory.
Invalid mass line in data file
Self-explanatory.
Invalid mass value
Self-explanatory.
Invalid math function in variable formula
267

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

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

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

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

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

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

LAMMPS Users Manual
Only one fix deform can be defined at a time.
More than one fix freeze
Only one of these fixes can be defined, since the granular pair potentials access it.
More than one fix shake
Only one fix shake can be defined.
Mu not allowed when not using semi-grand in fix atom/swap command
Self-explanatory.
Must define angle_style before Angle Coeffs
Must use an angle_style command before reading a data file that defines Angle Coeffs.
Must define angle_style before BondAngle Coeffs
Must use an angle_style command before reading a data file that defines Angle Coeffs.
Must define angle_style before BondBond Coeffs
Must use an angle_style command before reading a data file that defines Angle Coeffs.
Must define bond_style before Bond Coeffs
Must use a bond_style command before reading a data file that defines Bond Coeffs.
Must define dihedral_style before AngleAngleTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines AngleAngleTorsion Coeffs.
Must define dihedral_style before AngleTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines AngleTorsion Coeffs.
Must define dihedral_style before BondBond13 Coeffs
Must use a dihedral_style command before reading a data file that defines BondBond13 Coeffs.
Must define dihedral_style before Dihedral Coeffs
Must use a dihedral_style command before reading a data file that defines Dihedral Coeffs.
Must define dihedral_style before EndBondTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines EndBondTorsion Coeffs.
Must define dihedral_style before MiddleBondTorsion Coeffs
Must use a dihedral_style command before reading a data file that defines MiddleBondTorsion
Coeffs.
Must define improper_style before AngleAngle Coeffs
Must use an improper_style command before reading a data file that defines AngleAngle Coeffs.
Must define improper_style before Improper Coeffs
Must use an improper_style command before reading a data file that defines Improper Coeffs.
Must define pair_style before Pair Coeffs
Must use a pair_style command before reading a data file that defines Pair Coeffs.
Must define pair_style before PairIJ Coeffs
Must use a pair_style command before reading a data file that defines PairIJ Coeffs.
Must have more than one processor partition to temper
Cannot use the temper command with only one processor partition. Use the -partition command-line
option.
Must read Atoms before Angles
The Atoms section of a data file must come before an Angles section.
Must read Atoms before Bodies
The Atoms section of a data file must come before a Bodies section.
Must read Atoms before Bonds
The Atoms section of a data file must come before a Bonds section.
Must read Atoms before Dihedrals
The Atoms section of a data file must come before a Dihedrals section.
Must read Atoms before Ellipsoids
The Atoms section of a data file must come before a Ellipsoids section.
Must read Atoms before Impropers
The Atoms section of a data file must come before an Impropers section.
274

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

LAMMPS Users Manual
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
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 setting the "extra bond per atom" header value 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 setting the "extra bond per atom" header value to allow for
additional bonds to be formed.
New bond exceeded special list size in fix bond/create
See the special_bonds extra command for info on how to leave space in the special bonds list to allow
for additional bonds to be formed.
276

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

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

LAMMPS Users Manual
One or zero atoms in rigid body
Any rigid body defined by the fix rigid command must contain 2 or more atoms.
Only 2 types allowed when not using semi-grand in fix atom/swap command
Self-explanatory.
Only one cut-off allowed when requesting all long
Self-explanatory.
Only one cutoff allowed when requesting all long
Self-explanatory.
Only zhi currently implemented for fix append/atoms
Self-explanatory.
Out of range atoms - cannot compute MSM
One or more atoms are attempting to map their charge to a MSM grid point that is not owned by a
processor. This is likely for one of two reasons, both of them bad. First, it may mean that an atom near
the boundary of a processor's sub-domain has moved more than 1/2 the neighbor skin distance
without neighbor lists being rebuilt and atoms being migrated to new processors. This also means you
may be missing pairwise interactions that need to be computed. The solution is to change the
re-neighboring criteria via the neigh_modify command. The safest settings are "delay 0 every 1 check
yes". Second, it may mean that an atom has moved far outside a processor's sub-domain or even the
entire simulation box. This indicates bad physics, e.g. due to highly overlapping atoms, too large a
timestep, etc.
Out of range atoms - cannot compute PPPM
One or more atoms are attempting to map their charge to a PPPM grid point that is not owned by a
processor. This is likely for one of two reasons, both of them bad. First, it may mean that an atom near
the boundary of a processor's sub-domain has moved more than 1/2 the neighbor skin distance
without neighbor lists being rebuilt and atoms being migrated to new processors. This also means you
may be missing pairwise interactions that need to be computed. The solution is to change the
re-neighboring criteria via the neigh_modify command. The safest settings are "delay 0 every 1 check
yes". Second, it may mean that an atom has moved far outside a processor's sub-domain or even the
entire simulation box. This indicates bad physics, e.g. due to highly overlapping atoms, too large a
timestep, etc.
Out of range atoms - cannot compute PPPMDisp
One or more atoms are attempting to map their charge to a PPPM grid point that is not owned by a
processor. This is likely for one of two reasons, both of them bad. First, it may mean that an atom near
the boundary of a processor's sub-domain has moved more than 1/2 the neighbor skin 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
279

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

LAMMPS Users Manual
Pair brownian requires monodisperse particles
All particles must be the same finite size.
Pair brownian/poly requires atom style sphere
Self-explanatory.
Pair brownian/poly requires extended particles
One of the particles has radius 0.0.
Pair brownian/poly requires newton pair off
Self-explanatory.
Pair coeff for hybrid has invalid style
Style in pair coeff must have been listed in pair_style command.
Pair coul/wolf requires atom attribute q
The atom style defined does not have this attribute.
Pair cutoff < Respa interior cutoff
One or more pairwise cutoffs are too short to use with the specified rRESPA 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
281

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

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

LAMMPS Users Manual
Pair style buck/coul/long/gpu requires atom attribute q
The atom style defined does not have this attribute.
Pair style buck/long/coul/long requires atom attribute q
The atom style defined does not have this attribute.
Pair style coul/cut requires atom attribute q
The atom style defined does not have these attributes.
Pair style coul/cut/gpu requires atom attribute q
The atom style defined does not have this attribute.
Pair style coul/debye/gpu requires atom attribute q
The atom style defined does not have this attribute.
Pair style coul/dsf requires atom attribute q
The atom style defined does not have this attribute.
Pair style coul/dsf/gpu requires atom attribute q
The atom style defined does not have this attribute.
Pair style coul/long/gpu requires atom attribute q
The atom style defined does not have these attributes.
Pair style coul/streitz requires atom attribute q
Self-explanatory.
Pair style does not have extra field requested by compute pair/local
The pair style does not support the pN value 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
Self-explanatory.
Pair style is incompatible with KSpace style
284

LAMMPS Users Manual
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
There are no atom IDs defined in the system and the TIP4P potential requires them to find O,H atoms
with a water molecule.
285

LAMMPS Users Manual
Pair style lj/long/tip4p/long requires atom attribute q
The atom style defined does not have these attributes.
Pair style lj/long/tip4p/long requires newton pair on
This is because the computation of constraint forces within a water molecule adds forces to atoms
owned by other processors.
Pair style lj/sdk/coul/long/gpu requires atom attribute q
The atom style defined does not have this attribute.
Pair style nb3b/harmonic requires atom IDs
This is a requirement to use this potential.
Pair style nb3b/harmonic requires newton pair on
See the newton command. This is a restriction to use this potential.
Pair style nm/cut/coul/cut requires atom attribute q
The atom style defined does not have this attribute.
Pair style nm/cut/coul/long requires atom attribute q
The atom style defined does not have this attribute.
Pair style peri requires atom style peri
Self-explanatory.
Pair style polymorphic requires atom IDs
This is a requirement to use the polymorphic potential.
Pair style polymorphic requires newton pair on
See the newton command. This is a restriction to use the polymorphic potential.
Pair style reax requires atom IDs
This is a requirement to use the ReaxFF potential.
Pair style reax requires atom attribute q
The atom style defined does not have this attribute.
Pair style reax requires newton pair on
This is a requirement to use the ReaxFF potential.
Pair style requires a KSpace style
No kspace style is defined.
Pair style requires use of kspace_style ewald/disp
Self-explanatory.
Pair style sw/gpu requires atom IDs
This is a requirement to use this potential.
Pair style sw/gpu requires newton pair off
See the newton command. This is a restriction to use this potential.
Pair style tersoff/gpu requires atom IDs
This is a requirement to use the tersoff/gpu potential.
Pair style tersoff/gpu requires newton pair off
See the newton command. This is a restriction to use this pair style.
Pair style tip4p/cut requires atom IDs
This is a requirement to use this potential.
Pair style tip4p/cut requires atom attribute q
The atom style defined does not have this attribute.
Pair style tip4p/cut requires newton pair on
See the newton command. This is a restriction to use this potential.
Pair style tip4p/long requires atom IDs
There are no atom IDs defined in the system and the TIP4P potential requires them to find O,H atoms
with a water molecule.
Pair style tip4p/long requires atom attribute q
The atom style defined does not have these attributes.
Pair style tip4p/long requires newton pair on
286

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

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

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

LAMMPS Users Manual
This is typically because the box-size specified in the data file is large compared to the actual extent
of atoms in a shrink-wrapped dimension. When LAMMPS shrink-wraps the box atoms will be lost if
the processor they are re-assigned to is too far away. Choose a box size closer to the actual extent of
the atoms.
Read_dump command before simulation box is defined
The read_dump command cannot be used before a read_data, read_restart, or create_box command.
Read_dump field not found in dump file
Self-explanatory.
Read_dump triclinic status does not match simulation
Both the dump snapshot and the current LAMMPS simulation must be using either an orthogonal or
triclinic box.
Read_dump xyz fields do not have consistent scaling/wrapping
Self-explanatory.
Reading from MPI-IO filename when MPIIO package is not installed
Self-explanatory.
Reax_defs.h setting for NATDEF is too small
Edit the setting in the ReaxFF library and re-compile the library and re-build LAMMPS.
Reax_defs.h setting for NNEIGHMAXDEF is too small
Edit the setting in the ReaxFF library and re-compile the library and re-build LAMMPS.
Receiving partition in processors part command is already a receiver
Cannot specify a partition to be a receiver twice.
Region ID for compute chunk/atom does not exist
Self-explanatory.
Region ID for compute reduce/region does not exist
Self-explanatory.
Region ID for compute temp/region does not exist
Self-explanatory.
Region ID for dump custom does not exist
Self-explanatory.
Region ID for fix addforce does not exist
Self-explanatory.
Region ID for fix atom/swap does not exist
Self-explanatory.
Region ID for fix ave/spatial does not exist
Self-explanatory.
Region ID for fix aveforce does not exist
Self-explanatory.
Region ID for fix deposit does not exist
Self-explanatory.
Region ID for fix efield does not exist
Self-explanatory.
Region ID for fix evaporate does not exist
Self-explanatory.
Region ID for fix gcmc does not exist
Self-explanatory.
Region ID for fix heat does not exist
Self-explanatory.
Region ID for fix setforce does not exist
Self-explanatory.
Region ID for fix wall/region does not exist
Self-explanatory.
290

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

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

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

293

LAMMPS Users Manual
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 command for info on setting the "extra special per atom" header value to allow for
additional special values to be stored.
Specified processors != physical processors
The 3d grid of processors defined by the processors command does not match the number of
processors LAMMPS is being run on.
Specified target stress must be uniaxial or hydrostatic
Self-explanatory.
Sqrt of negative value in variable formula
Self-explanatory.
Subsequent read data induced too many angles per atom
See the create_box extra/angle/per/atom or read_data "extra angle per atom" header value to set this
limit larger.
Subsequent read data induced too many bonds per atom
See the create_box extra/bond/per/atom or read_data "extra bond per atom" header value to set this
limit larger.
Subsequent read data induced too many dihedrals per atom
See the create_box extra/dihedral/per/atom or read_data "extra dihedral per atom" header value to set
this limit larger.
Subsequent read data induced too many impropers per atom
See the create_box extra/improper/per/atom or read_data "extra improper per atom" header value 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.
294

LAMMPS Users Manual
Tagint setting in lmptype.h is invalid
Tagint must be as large or larger than smallint.
Tagint setting in lmptype.h is not compatible
Format of tagint stored in restart file is not consistent with LAMMPS version you are running. See the
settings in src/lmptype.h
Target pressure for fix rigid/nph cannot be < 0.0
Self-explanatory.
Target pressure for fix rigid/npt/small cannot be < 0.0
Self-explanatory.
Target temperature for fix nvt/npt/nph cannot be 0.0
Self-explanatory.
Target temperature for fix rigid/npt cannot be 0.0
Self-explanatory.
Target temperature for fix rigid/npt/small cannot be 0.0
Self-explanatory.
Target temperature for fix rigid/nvt cannot be 0.0
Self-explanatory.
Target temperature for fix rigid/nvt/small cannot be 0.0
Self-explanatory.
Temper command before simulation box is defined
The temper command cannot be used before a read_data, read_restart, or create_box command.
Temperature ID for fix bond/swap does not exist
Self-explanatory.
Temperature ID for fix box/relax does not exist
Self-explanatory.
Temperature ID for fix nvt/npt does not exist
Self-explanatory.
Temperature ID for fix press/berendsen does not exist
Self-explanatory.
Temperature ID for fix rigid nvt/npt/nph does not exist
Self-explanatory.
Temperature ID for fix temp/berendsen does not exist
Self-explanatory.
Temperature ID for fix temp/csld does not exist
Self-explanatory.
Temperature ID for fix temp/csvr does not exist
Self-explanatory.
Temperature ID for fix temp/rescale does not exist
Self-explanatory.
Temperature compute degrees of freedom < 0
This should not happen if you are calculating the temperature on a valid set of atoms.
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.
295

LAMMPS Users Manual
Temperature control must be used with fix npt
Self-explanatory.
Temperature control must be used with fix npt/asphere
Self-explanatory.
Temperature control must be used with fix npt/body
Self-explanatory.
Temperature control must be used with fix npt/sphere
Self-explanatory.
Temperature control must be used with fix nvt
Self-explanatory.
Temperature control must be used with fix nvt/asphere
Self-explanatory.
Temperature control must be used with fix nvt/body
Self-explanatory.
Temperature control must be used with fix nvt/sllod
Self-explanatory.
Temperature control must be used with fix nvt/sphere
Self-explanatory.
Temperature control must not be used with fix nph/small
Self-explanatory.
Temperature for fix nvt/sllod does not have a bias
The specified compute must compute temperature with a bias.
Tempering could not find thermo_pe compute
This compute is created by the thermo command. It must have been explicitly deleted by a uncompute
command.
Tempering fix ID is not defined
The fix ID specified by the temper command does not exist.
Tempering temperature fix is not valid
The fix specified by the temper command is not one that controls temperature (nvt or langevin).
Test_descriptor_string already allocated
This is an internal error. Contact the developers.
The package gpu command is required for gpu styles
Self-explanatory.
Thermo and fix not computed at compatible times
Fixes generate values on specific timesteps. The thermo output does not match these timesteps.
Thermo compute array is accessed out-of-range
Self-explanatory.
Thermo compute does not compute array
Self-explanatory.
Thermo compute does not compute scalar
Self-explanatory.
Thermo compute does not compute vector
Self-explanatory.
Thermo compute vector is accessed out-of-range
Self-explanatory.
Thermo custom variable cannot be indexed
Self-explanatory.
Thermo custom variable is not equal-style variable
Only equal-style variables can be output with thermodynamics, not atom-style variables.
Thermo every variable returned a bad timestep
The variable must return a timestep greater than the current timestep.
296

LAMMPS Users Manual
Thermo fix array is accessed out-of-range
Self-explanatory.
Thermo fix does not compute array
Self-explanatory.
Thermo fix does not compute scalar
Self-explanatory.
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
Table size specified via pair_modify command does not work with your machine's floating point
representation.
Too few lines in %s section of data file
Self-explanatory.
297

LAMMPS Users Manual
Too few values in body lines in data file
Self-explanatory.
Too few values in body section of molecule file
Self-explanatory.
Too many -pk arguments in command line
The string formed by concatenating the arguments is too long. Use a package command in the input
script instead.
Too many MSM grid levels
The max number of MSM grid levels is hardwired to 10.
Too many args in variable function
More args are used than any variable function allows.
Too many atom pairs for pair bop
The number of atomic pairs exceeds the expected number. Check your atomic structure to ensure that
it is realistic.
Too many atom sorting bins
This is likely due to an immense simulation box that has blown up to a large size.
Too many atom triplets for pair bop
The number of three atom groups for angle determinations exceeds the expected number. Check your
atomic structure to ensure that it is realistic.
Too many atoms for dump dcd
The system size must fit in a 32-bit integer to use this dump style.
Too many atoms for dump xtc
The system size must fit in a 32-bit integer to use this dump style.
Too many atoms to dump sort
Cannot sort when running with more than 2^31 atoms.
Too many exponent bits for lookup table
Table size specified via pair_modify command does not work with your machine's floating point
representation.
Too many groups
The maximum number of atom groups (including the "all" group) is given by MAX_GROUP in
group.cpp and is 32.
Too many iterations
You must use a number of iterations that fit in a 32-bit integer for minimization.
Too many lines in one body in data file - boost MAXBODY
MAXBODY is a setting at the top of the src/read_data.cpp file. Set it larger and re-compile the code.
Too many local+ghost atoms for neighbor list
The number of nlocal + nghost atoms on a processor is limited by the size of a 32-bit integer with 2
bits removed for masking 1-2, 1-3, 1-4 neighbors.
Too many mantissa bits for lookup table
Table size specified via pair_modify command does not work with your machine's floating point
representation.
Too many masses for fix shake
The fix shake command cannot list more masses than there are atom types.
Too many molecules for fix poems
The limit is 2^31 = ~2 billion molecules.
Too many molecules for fix rigid
The limit is 2^31 = ~2 billion molecules.
Too many neighbor bins
This is likely due to an immense simulation box that has blown up to a large size.
Too many timesteps
The cumulative timesteps must fit in a 64-bit integer.
298

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

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

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

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

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

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

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

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

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

LAMMPS Users Manual
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
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 tally does not account for 'zero yes'
308

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

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

LAMMPS Users Manual
Self-explanatory.
KIM Model does not provide 'forces'; Forces will be zero
Self-explanatory.
KIM Model does not provide 'particleEnergy'; energy per atom will be zero
Self-explanatory.
KIM Model does not provide 'particleVirial'; virial per atom will be zero
Self-explanatory.
Kspace_modify slab param < 2.0 may cause unphysical behavior
The kspace_modify slab parameter should be larger to insure periodic grids padded with empty space
do not overlap.
Less insertions than requested
The fix pour command was unsuccessful at finding open space for as many particles as it tried to
insert.
Library error in lammps_gather_atoms
This library function cannot be used if atom IDs are not defined or are not consecutively numbered.
Library error in lammps_scatter_atoms
This library function cannot be used if atom IDs are not defined or are not consecutively numbered, or
if no atom map is defined. See the atom_modify command for details about atom maps.
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
311

LAMMPS Users Manual
It is not efficient to use compute cna/atom more than once.
More than one compute contact/atom
It is not efficient to use compute contact/atom more than once.
More than one compute coord/atom
It is not efficient to use compute coord/atom more than once.
More than one compute damage/atom
It is not efficient to use compute ke/atom more than once.
More than one compute dilatation/atom
Self-explanatory.
More than one compute erotate/sphere/atom
It is not efficient to use compute erorate/sphere/atom more than once.
More than one compute hexorder/atom
It is not efficient to use compute hexorder/atom more than once.
More than one compute ke/atom
It is not efficient to use compute ke/atom more than once.
More than one compute orientorder/atom
It is not efficient to use compute orientorder/atom more than once.
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
312

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

313

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

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

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

316

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

317

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

318

LAMMPS Users Manual
• F90 + MPI
• spatial-decomposition parallelism
• frictional granular potentials
• NVE integrator
• boundary conditions for granular flow and packing and walls
• particle insertion

319

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

320

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

LAMMPS Users Manual
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 keyword of the special_bonds
command. With our phenol, there is 1 more special neighbor for which space is required. Otherwise
LAMMPS crashes and gives the required value.
special_bonds lj/coul 0.0 0.0 0.5 extra 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

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.

322

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

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

1

1 lj/cut/coul/long

0.0700

3.550

323

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

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
7
7
8

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
7
8
8

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
thole
1.360
2.510
thole
0.926
1.590
thole
0.630
0.670

3.550
3.310
2.985
3.550
3.310
2.985
3.070
2.745
2.420
0.000
0.000

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

324

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

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

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

326

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.

327

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//lammps.git

or, if you have set up your GitHub account for using SSH keys, via SSH:
$ git clone git@github.com:/lammps.git

You can find the proper URL by clicking the "Clone or download"-button:

328

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

329

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

330

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

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
331

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

332

LAMMPS Users Manual

If all is fine, you will see this:

333

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

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

335

LAMMPS Users Manual

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:

336

LAMMPS Users Manual
Be sure to check the changes to see if you agree with them by clicking on the tab button:

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.

337

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:

338

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:

339

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.

340

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

341

PyLammps Tutorial

342

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

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

343

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

344

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

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

345

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

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

346

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

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

x^2 + y^2 - R^2 = 0

description
Cylinder along z-axis, axis going
through (0,0,0)

x^2 + y^2 - r(z)^2 = 0, r(x) = R if | z | > l,
A cylinder with a dent around z = 0
r(z) = R - a*(1 + cos(z/l))/2 otherwise
-( x^2 + y^2 ) * (a^2 - z^2/c^2) * ( 1 +
A dumbbell
dumbbell
aABc
(A*sin(B*z^2))^4) = 0
ellipsoid
abc
(x/a)^2 + (y/b)^2 + (z/c)^2 = 0
An ellipsoid
A plane with normal (a,b,c) going
a b c x0 y0
a*(x-x0) + b*(y-y0) + c*(z-z0) = 0
plane
through point (x0,y0,z0)
z0
A plane with a sinusoidal modulation
plane_wiggle a w
z - a*sin(w*x) = 0
on z along x.
sphere
R
x^2 + y^2 + z^2 - R^2 = 0
A sphere of radius R
supersphere R q
| x |^q + | y |^q + | z |^q - R^q = 0
A supersphere of hyperradius R
-(x^2 + y^2)*(a^2 - z^2/f(z)^2)*(1 +
An approximation to a dendtritic
a, A, B, B2,
(A*sin(g(z)*z^2))^4), f(z) = c if z > 0, 1
spine
spine
c
otherwise; g(z) = B if z > 0, B2 otherwise
-(x^2 + y^2)*(a^2 - z^2/f(z)^2)*(1 +
Another approximation to a dendtritic
a, A, B, B2,
spine_two
(A*sin(g(z)*z^2))^2), f(z) = c if z > 0, 1
c
spine
otherwise; g(z) = B if z > 0, B2 otherwise
A model grana thylakoid consisting of
two block-like compartments
thylakoid
wB LB lB Various, see (Paquay)
connected by a bridge of width wB,
length LB and taper length lB
A torus with large radius R and small
torus
Rr
(R - sqrt( x^2 + y^2 ) )^2 + z^2 - r^2
radius r, centered on (0,0,0)

cylinder_dent R l a

(Paquay) Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at arXiv:1411.3019.

347

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

348

LAMMPS Users Manual
• angle_style none - turn off angle interactions
• angle_style hybrid - define multiple styles of angle interactions
• angle_style charmm - CHARMM angle
• angle_style class2 - COMPASS (class 2) angle
• angle_style cosine - cosine angle potential
• angle_style cosine/delta - difference of cosines angle potential
• angle_style cosine/periodic - DREIDING angle
• angle_style cosine/squared - cosine squared angle potential
• angle_style harmonic - harmonic angle
• angle_style 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

349

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
• angle_style zero - topology but no interactions
• angle_style hybrid - define multiple styles of angle interactions
• angle_style charmm - CHARMM angle
• angle_style class2 - COMPASS (class 2) angle
• angle_style cosine - cosine angle potential
350

LAMMPS Users Manual
• angle_style cosine/delta - difference of cosines angle potential
• angle_style cosine/periodic - DREIDING angle
• angle_style cosine/squared - cosine squared angle potential
• angle_style harmonic - harmonic angle
• angle_style 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

351

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 = 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 hash
atom_modify map array 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 atom ID lookup is done for molecular atom styles. Lookups are performed
by bond (angle, etc) routines in LAMMPS to find the local atom index associated with a global atom ID.
When the array value is used, 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
352

LAMMPS Users Manual
simulations. The hash value uses a hash table to perform the lookups. This can be slightly slower than the
array method, 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.
When this setting is not specified in your input script, LAMMPS creates a map, if one is needed, as an array
or hash. See the discussion of default values below for how LAMMPS chooses which kind of map to build.
Note that atomic systems do not normally need to create a map. However, even in this case some LAMMPS
commands will create a map to find atoms (and then destroy it), or require a permanent map. An example of
the former is the velocity loop all command, which uses a map when looping over all atoms and insuring the
same velocity values are assigned to an atom ID, no matter which processor owns it.
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, 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:
353

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

354

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 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
template args = 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

atomic
bond
full
body nparticle 2 10
hybrid charge bond
hybrid charge body nparticle 2 5
template myMols

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

355

LAMMPS Users Manual
angle
bonds and angles
bead-spring polymers with stiffness
atomic
only the default values
coarse-grain liquids, solids, metals
body
mass, inertia moments, quaternion, angular momentum arbitrary bodies
bond
bonds
bead-spring polymers
charge
charge
atomic system with charges
dipole
charge and dipole moment
system with dipolar particles
dpd
internal temperature and internal energies
DPD particles
electron
charge and spin and eradius
electronic force field
ellipsoid
shape, quaternion, angular momentum
aspherical particles
full
molecular + charge
bio-molecules
line
end points, angular velocity
rigid bodies
meso
rho, e, cv
SPH particles
molecular bonds, angles, dihedrals, impropers
uncharged molecules
peri
mass, volume
mesocopic Peridynamic models
smd
volume, kernel diameter, contact radius, mass
solid and fluid SPH particles
sphere
diameter, mass, angular velocity
granular models
template
template index, template atom
small molecules with fixed topology
tri
corner points, angular momentum
rigid bodies
wavepacket charge, spin, eradius, etag, cs_re, cs_im
AWPMD
NOTE: It is possible to add some attributes, such as a molecule ID, to atom styles that do not have them via
the fix property/atom command. This command also allows new custom attributes consisting of extra integer
or floating-point values to be added to atoms. See the fix property/atom 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.
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.
356

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

LAMMPS Users Manual
Typically, simulations require only a single (non-hybrid) atom style. If some atoms in the simulation do not
have all the properties defined by a particular style, use the simplest style that defines all the needed properties
by any atom. For example, if some atoms in a simulation are charged, but others are not, use the charge style.
If some atoms have bonds, but others do not, use the bond style.
The only scenario where the hybrid style is needed is if there is no single style which defines all needed
properties of all atoms. For example, as mentioned above, if you want dipolar particles which will rotate due
to torque, you need to use "atom_style hybrid sphere dipole". When a hybrid style is used, atoms store and
communicate the union of all quantities implied by the individual styles.
When using the hybrid style, you cannot combine the template style with another molecular style that stores
bond,angle,etc info on a per-atom basis.
LAMMPS can be extended with new atom styles as well as new body styles; see 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.

358

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

359

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 comm
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

360

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

361

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

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
362

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

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

364

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

365

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

366

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

367

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

LAMMPS Users Manual
• bond_style class2 - COMPASS (class 2) bond
• bond_style fene - FENE (finite-extensible non-linear elastic) bond
• bond_style fene/expand - FENE bonds with variable size particles
• bond_style harmonic - harmonic bond
• bond_style morse - Morse bond
• bond_style nonlinear - nonlinear bond
• bond_style quartic - breakable quartic bond
• bond_style 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

369

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

LAMMPS Users Manual
• bond_style zero - topology but no interactions
• bond_style hybrid - define multiple styles of bond interactions
• bond_style class2 - COMPASS (class 2) bond
• bond_style fene - FENE (finite-extensible non-linear elastic) bond
• bond_style fene/expand - FENE bonds with variable size particles
• bond_style harmonic - harmonic bond
• bond_style morse - Morse bond
• bond_style nonlinear - nonlinear bond
• bond_style quartic - breakable quartic bond
• bond_style 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

371

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

372

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

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

374

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.

375

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 rem
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 non-orthogonal box. It can also
be used to change the boundary conditions for the simulation box, similar to the boundary command.
376

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

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

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.

378

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

LAMMPS Users Manual
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:
fix deform, boundary
Default:
The option default is units = lattice.

380

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

381

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 a
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.
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
382

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

383

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

384

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.

385

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 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
386

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

387

LAMMPS Users Manual
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.
• 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
• erotate/sphere/atom - rotational energy for each spherical particle
• event/displace - detect event on atom displacement
• 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
388

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

389

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 t
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
Related commands:
compute

390

LAMMPS Users Manual
Default:
The option defaults are extra/dof = 2 or 3 for 2d or 3d systems and dynamic/dof = no.

391

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 = Rx Ry Rz theta
Rx,Ry,Rz = rotation vector for single molecule
theta = rotation angle for single molecule (degrees)
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 this doc page, a created
atom or molecule is referred to as a "particle".
392

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

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

394

LAMMPS Users Manual
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.
variable
variable
lattice
region
create_box

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

xx equal 0.0
yy equal 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

The rotate keyword can be used with the single style, when adding a single molecule 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
395

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

396

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

create_bonds command
Syntax:
create_bonds 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 = minimum distance between pair of atoms to bond together
Examples:
create_bonds all all 1 1.0 1.2
create_bonds surf solvent 3 2.0 2.4

Description:
Create bonds between pairs of atoms that meet specified distance criteria. The bond interactions can then be
computed during a simulation by the bond potential defined by the bond_style and bond_coeff commands.
This command 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.
Note that 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 create all the bonds that would normally be defined in a
complex system of molecules. Also note that this command does not add any 3-body or 4-body interactions
which, depending on your model, may be induced by added bonds, e.g. angle, dihedral, or improper
interactions.
All created bonds will be 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. This maximum value is set by
the "bond types" field in the header of the data file read by the read_data command, or via the optional
"bond/types" argument of the create_box command.
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 command 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.

397

LAMMPS Users Manual
An additional requirement 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.
NOTE: If the system has no bonds 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. Otherwise an error may occur when too many bonds are added to an atom. If the
read_data command is used to define the system, these 2 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. See
the doc pages for the 2 commands for details.
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
Default: none

398

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

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

LAMMPS Users Manual
Default: none

401

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 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
402

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

403

LAMMPS Users Manual
create_atoms
Default:
The option defaults are compress = yes, bond = no, mol = no.

404

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, 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,
405

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

406

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

407

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

408

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

LAMMPS Users Manual
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 charmm - CHARMM dihedral
• dihedral_style class2 - COMPASS (class 2) dihedral
• dihedral_style harmonic - harmonic dihedral
• dihedral_style helix - helix dihedral
• dihedral_style multi/harmonic - multi-harmonic dihedral
• dihedral_style 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

410

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:

where the I,J,K,L ordering of the 4 atoms that define the dihedral is from left to right.
411

LAMMPS Users Manual
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 charmm - CHARMM dihedral
• dihedral_style class2 - COMPASS (class 2) dihedral
• dihedral_style harmonic - harmonic dihedral
• dihedral_style helix - helix dihedral
• dihedral_style multi/harmonic - multi-harmonic dihedral
• dihedral_style 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 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

412

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

413

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

LAMMPS Users Manual
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 allowed.
Related commands:
lattice, change_box, fix move
Default:
The option defaults are units = lattice.

415

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump command
dump custom/vtk command
dump h5md command
dump image command
dump movie command
dump molfile command
dump nc 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 dcd or xtc or xyz or xyz/gz or
xyz/mpiio or h5md or image or movie or molfile or local or custom or custom/gz or custom/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
dcd args = none
xtc args = none
xyz args = none
xyz/gz args = none
xyz/mpiio args = none
custom/vtk args = similar to custom args below, discussed on dump custom/vtk doc page
h5md args = discussed on dump h5md doc page
image args = discussed on dump image doc page
movie args = discussed on dump image doc page

molfile args = discussed on dump molfile doc page

416

LAMMPS Users Manual
nc args = discussed on dump nc doc page

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 wild
custom or custom/gz or custom/mpiio args = list of atom attributes
possible attributes = id, mol, proc, procp1, type, element, mass,
x, y, z, xs, ys, zs, xu, yu, zu,
xsu, ysu, zsu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz, mu,
radius, diameter, omegax, omegay, omegaz,
angmomx, angmomy, angmomz, tqx, tqy, tqz,
c_ID, c_ID[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 inclu
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 w
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

Examples:
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

417

LAMMPS Users Manual
dump snap all cfg 100 dump.config.*.cfg mass type xs ys zs id type c_Stress[2]
dump 1 all xtc 1000 file.xtc

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

418

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

419

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

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

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

LAMMPS Users Manual
multiple values.
Here is an example of how to dump bond info for a system, including the distance and energy of each bond:
compute 1 all property/local batom1 batom2 btype
compute 2 all bond/local dist eng
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]

This section explains the atom attributes that can be specified as part of the custom and cfg styles.
The id, mol, proc, procp1, type, element, mass, vx, vy, vz, fx, fy, fz, q attributes are self-explanatory.
Id is the atom ID. Mol is the molecule ID, included in the data file for molecular systems. Proc is the ID of the
processor (0 to Nprocs-1) that currently owns the atom. Procp1 is the proc ID+1, which can be convenient in
place of a type attribute (1 to Ntypes) for coloring atoms in a visualization program. Type is the atom type (1
to Ntypes). Element is typically the chemical name of an element, which you must assign to each type via the
dump_modify element command. More generally, it can be any string you wish to associated with an atom
type. Mass is the atom mass. Vx, vy, vz, fx, fy, fz, and q are components of atom velocity and force and atomic
charge.
There are several options for outputting atom coordinates. The x, y, z attributes write atom coordinates
"unscaled", in the appropriate distance units (Angstroms, sigma, etc). Use xs, ys, zs if you want the
coordinates "scaled" to the box size, so that each value is 0.0 to 1.0. If the simulation box is triclinic (tilted),
then all atom coords will still be between 0.0 and 1.0. I.e. actual unscaled (x,y,z) = xs*A + ys*B + zs*C,
where (A,B,C) are the non-orthogonal vectors of the simulation box edges, as discussed 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.
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.

423

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

LAMMPS Users Manual
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. This is because some machines may not support the low-level XDR
data format that XTC files are written with, which will result in a compile-time error when a low-level include
file is not found. Putting this style in a package makes it easy to exclude from a LAMMPS build for those
machines. However, the MISC package also includes two compatibility header files and associated functions,
which should be a suitable substitute on machines that do not have the appropriate native header files. This
option can be invoked at build time by adding -DLAMMPS_XDR to the CCFLAGS variable in the
appropriate low-level Makefile, e.g. src/MAKE/Makefile.foo. This compatibility mode has been tested
successfully on Cray XT3/XT4/XT5 and IBM BlueGene/L machines and should also work on IBM BG/P, and
Windows XP/Vista/7 machines.
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.

425

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump custom/vtk 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 = custom/vtk
• N = dump every this many timesteps
• file = name of file to write dump info to
• args = list of arguments for a particular style
custom/vtk args = list of atom attributes
possible attributes = id, mol, proc, procp1, type, element, mass,
x, y, z, xs, ys, zs, xu, yu, zu,
xsu, ysu, zsu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz, mu,
radius, diameter, omegax, omegay, omegaz,
angmomx, angmomy, angmomz, tqx, tqy, tqz,
c_ID, c_ID[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 inclu
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 w
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

Examples:
dump dmpvtk all custom/vtk 100 dump*.myforce.vtk id type vx fx

426

LAMMPS Users Manual
dump dmpvtp flow custom/vtk 100 dump*.%.displace.vtp id type c_myD[1] c_myD[2] c_myD[3] v_ke

The style custom/vtk is similar to the custom style but uses the VTK library to write data to VTK simple
legacy or XML format depending on the filename extension specified. This can be either *.vtk for the legacy
format or *.vtp and *.vtu, respectively, for the 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), dump_modify binary allows to set the binary flag for this dump style explicitly.
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.
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 data
for a single snapshot is collected from multiple processors, each of which owns a subset of the atoms.
For the custom/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 custom/vtk allows you to specify a list of atom attributes to be written to the dump file for each atom.
Possible attributes are listed above. In contrast to the custom style, the 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.
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/vtk attributes is given below. Since position data is required to write VTK files "x y z" do not have to
be specified explicitly.

427

LAMMPS Users Manual
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 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.
This section explains the atom attributes that can be specified as part of the custom/vtk style.
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,
428

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

429

LAMMPS Users Manual
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 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:
The custom/vtk style does not support writing of gzipped dump files.
The custom/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 custom/vtk dump style neither supports buffering nor 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.

430

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". At least one element must be
given and image may only be present if position is specified first.
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

For the elements position, velocity, force and species, one may specify a sub-interval to write the data
only every N_element iterations of the dump (i.e. every N*N_element time steps). This is specified by
the option
every N_element

that follows directly the element declaration.
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.
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
431

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

432

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)

433

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:

434

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, 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.
435

LAMMPS Users Manual
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 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. This mapping can be changed by the dump_modify acolor command.
If type is specified for the diameter setting then the diameter of each atom is determined by its atom type. By
default all types have diameter 1.0. This mapping can be changed by the dump_modify adiam command.
If element is specified for the color and/or diameter setting, then the color and/or diameter of each atom is
determined by which element it is, which in turn is specified by the element-to-type mapping specified by the
"dump_modify element" command. By default every atom type is C (carbon). Every element has a color and
diameter associated with it, which is the same as the colors and sizes used by the AtomEye visualization
package.
If other atom attributes are used for the color or diameter settings, they are interpreted in the following way.
If "vx", for example, is used as the color setting, then the color of the atom will depend on the x-component of
its velocity. The association of a per-atom value with a specific color is determined by a "color map", which
can be specified via the dump_modify command. The basic idea is that the atom-attribute will be within a
range of values, and every value within the range is mapped to a specific color. Depending on how the color
map is defined, that mapping can take place via interpolation so that a value of -3.2 is halfway between "red"
and "blue", or discretely so that the value of -3.2 is "orange".
If "vx", for example, is used as the diameter setting, then the atom will be rendered using the x-component of
its velocity as the diameter. If the per-atom value <= 0.0, them the atom will not be drawn. Note that
finite-size spherical particles, as defined by atom_style sphere define a per-particle radius or diameter, which
can be used as the diameter setting.
The various keywords listed above control how the image is rendered. As listed below, all of the keywords
have defaults, most of which you will likely not need to change. The dump modify also has options specific to
the dump image style, particularly for assigning colors to atoms, bonds, and other image features.
The atom keyword allow you to turn off the drawing of all atoms, if the specified value is no. Note that this
will not turn off the drawing of particles that are represented as lines, triangles, or bodies, as discussed below.
These particles can be drawn separately if the line, tri, or body keywords are used.

436

LAMMPS Users Manual
The adiam keyword allows you to override the diameter setting to set a single numeric size. All atoms will be
drawn with that diameter, e.g. 1.5, which is in whatever distance units the input script defines, e.g. Angstroms.
The bond keyword allows to you to alter how bonds are drawn. A bond is only drawn if both atoms in the
bond are being drawn due to being in the specified group and due to other selection criteria (e.g. region,
threshold settings of the dump_modify command). By default, bonds are drawn if they are defined in the input
data file as read by the read_data command. Using none for both the bond color and width value will turn off
the drawing of all bonds.
If atom is specified for the bond color value, then each bond is drawn in 2 halves, with the color of each half
being the color of the atom at that end of the bond.
If type is specified for the color value, then the color of each bond is determined by its bond type. By default
the mapping of bond types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for bond types > 6. This mapping can be changed by the dump_modify bcolor command.
The bond width value can be a numeric value or atom or type (or none as indicated above).
If a numeric value is specified, then all bonds will be drawn as cylinders with that diameter, e.g. 1.0, which is
in whatever distance units the input script defines, e.g. Angstroms.
If atom is specified for the width value, then each bond will be drawn with a width corresponding to the
minimum diameter of the 2 atoms in the bond.
If type is specified for the width value then the diameter of each bond is determined by its bond type. By
default all types have diameter 0.5. This mapping can be changed by the dump_modify bdiam command.
The line keyword can be used when atom_style line is used to define particles as line segments, and will draw
them as lines. If this keyword is not used, such particles will be drawn as spheres, the same as if they were
regular atoms. The only setting currently allowed for the color value is type, which will color the lines
according to the atom type of the particle. By default the mapping of types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.
The line width can only be a numeric value, which specifies that all lines will be drawn as cylinders with that
437

LAMMPS Users Manual
diameter, e.g. 1.0, which is in whatever distance units the input script defines, e.g. Angstroms.
The tri keyword can be used when atom_style tri is used to define particles as triangles, and will draw them as
triangles or edges (3 lines) or both, depending on the setting for tflag. If edges are drawn, the width setting
determines the diameters of the line segments. If this keyword is not used, triangle particles will be drawn as
spheres, the same as if they were regular atoms. The only setting currently allowed for the color value is type,
which will color the triangles according to the atom type of the particle. By default the mapping of types to
colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.
The body keyword can be used when atom_style body is used to define body particles with internal state (e.g.
sub-particles), and will drawn them in a manner specific to the body style. If this keyword is not used, such
particles will be drawn as spheres, the same as if they were regular atoms.
The 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 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.
The 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.

438

LAMMPS Users Manual
The only setting currently allowed for the color value is type, which will color the fix objects according to
their type. By default the mapping of types to colors is as follows:
• type 1 = red
• type 2 = green
• type 3 = blue
• type 4 = yellow
• type 5 = aqua
• type 6 = cyan
and repeats itself for types > 6. There is not yet an option to change this via the dump_modify command.
The size keyword sets the width and height of the created images, i.e. the number of pixels in each direction.
The view, center, up, 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
439

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

440

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

441

LAMMPS Users Manual
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
• box = yes 0.02
• axes = no 0.0 0.0
• subbox no 0.0
• shiny = 1.0
• ssao = no

442

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 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
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)
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 = "" or ">=" or "==" or "!=" or "|^"
value = numeric value to compare to, or LAST
these 3 args can be replaced by the word "none" to turn off thresholding
unwrap arg = yes or no

• these keywords apply only to the image and movie styles
• keyword = acolor or adiam or amap or backcolor or bcolor or bdiam or boxcolor or color or bitrate
or framerate
acolor args = type color
type = atom type or range of types (see below)

443

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

444

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. This keyword can only take effect if the dump_modify command is used
after the dump command, but 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.
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
445

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

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

447

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

448

LAMMPS Users Manual
The dump local style cannot be sorted by atom ID, since there are typically multiple lines of output per atom.
Some dump styles, such as dcd and xtc, require sorting by atom ID to format the output file correctly. If
multiple processors are writing the dump file, via the "%" wildcard in the dump filename, then sorting cannot
be performed.
NOTE: Unless it is required by the dump style, sorting dump file output requires extra overhead in terms of
CPU and communication cost, as well as memory, versus unsorted output.
The 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 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.

449

LAMMPS Users Manual

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

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

451

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

452

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

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

antiquewhite = 250, 235,
aqua = 0, 255, 255
215
bisque = 255, 228, 196
brown = 165, 42, 42
coral = 255, 127, 80

black = 0, 0, 0
burlywood = 222, 184,
135
cornflowerblue = 100,
149, 237

cyan = 0, 255, 255 darkblue = 0, 0, 139

darkcyan = 0, 139, 139

darkgreen = 0, 100, darkkhaki = 189, 183,
0
107
darkorchid = 153,
darkred = 139, 0, 0
50, 204
darkslategray = 47, darkturquoise = 0, 206,
79, 79
209
dimgray = 105, 105, dodgerblue = 30, 144,
105
255

darkmagenta = 139, 0,
139
darksalmon = 233,
150, 122
darkviolet = 148, 0,
211
firebrick = 178, 34, 34

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

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

454

LAMMPS Users Manual
fuchsia = 255, 0,
255
gray = 128, 128,
128
indianred = 205, 92,
92
lavenderblush =
255, 240, 245
lightcyan = 224,
255, 255
lightsalmon = 255,
160, 122
lightyellow = 255,
255, 224

gainsboro = 220, 220,
220
green = 0, 128, 0
indigo = 75, 0, 130
lawngreen = 124, 252, 0
lightgoldenrodyellow =
250, 250, 210
lightseagreen = 32, 178,
170
lime = 0, 255, 0

mediumaquamarine =
102, 205, 170
mediumseagreen = mediumslateblue = 123,
60, 179, 113
104, 238
midnightblue = 25, mintcream = 245, 255,
25, 112
250

maroon = 128, 0, 0

navy = 0, 0, 128
orangered = 255,
69, 0
palevioletred = 219,
112, 147
plum = 221, 160,
221
royalblue = 65, 105,
225
seashell = 255, 245,
238
slategray = 112,
128, 144

oldlace = 253, 245, 230
orchid = 218, 112, 214
papayawhip = 255, 239,
213
powderblue = 176, 224,
230
saddlebrown = 139, 69,
19
sienna = 160, 82, 45
snow = 255, 250, 250

teal = 0, 128, 128

thistle = 216, 191, 216

wheat = 245, 222,
179

white = 255, 255, 255

ghostwhite = 248, 248,
goldenrod = 218,
gold = 255, 215, 0
255
165, 32
greenyellow = 173,
honeydew = 240,
hotpink = 255,
255, 47
255, 240
105, 180
khaki = 240, 230,
lavender = 230,
ivory = 255, 240, 240
140
230, 250
lemonchiffon = 255, lightblue = 173, 216, lightcoral = 240,
250, 205
230
128, 128
lightgreen = 144, 238, lightgrey = 211,
lightpink = 255,
144
211, 211
182, 193
lightskyblue = 135,
lightslategray = 119, lightsteelblue =
206, 250
136, 153
176, 196, 222
limegreen = 50, 205, linen = 250, 240,
magenta = 255,
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, 228, moccasin = 255,
navajowhite =
225
228, 181
255, 222, 173
olivedrab = 107,
orange = 255,
olive = 128, 128, 0
142, 35
165, 0
palegoldenrod = 238, palegreen = 152,
paleturquoise =
232, 170
251, 152
175, 238, 238
pink = 255, 192,
peachpuff = 255, 239,
peru = 205, 133, 63
203
213
rosybrown =
purple = 128, 0, 128 red = 255, 0, 0
188, 143, 143
salmon = 250, 128,
sandybrown = 244, seagreen = 46,
114
164, 96
139, 87
skyblue = 135, 206, slateblue = 106,
silver = 192, 192, 192
235
90, 205
springgreen = 0, 255, steelblue = 70, 130, tan = 210, 180,
127
180
140
turquoise = 64, 224, violet = 238,
tomato = 253, 99, 71
208
130, 238
whitesmoke = 245,
yellowgreen =
yellow = 255, 255, 0
245, 245
154, 205, 50

455

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

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

457

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

dump nc command
dump nc/mpiio command
Syntax:
dump ID group-ID nc N file.nc args
dump ID group-ID nc/mpiio N file.nc args

• ID = user-assigned name for the dump
• group-ID = ID of the group of atoms to be imaged
• nc or nc/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.nc = name of file to write to
• args = list of per atom data elements to dump, same as for the 'custom' dump style.
Examples:
dump 1 all nc 100 traj.nc type x y z vx vy vz
dump_modify 1 append yes at -1 global c_thermo_pe c_thermo_temp c_thermo_press
dump 1 all nc/mpiio 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 nc uses the standard NetCDF library all data is collected on one processor and then written to the dump
file. Dump style nc/mpiio used the parallel NetCDF library and MPI-IO; it has better performance on a larger
number of processors. Note that 'nc' outputs all atoms sorted by atom tag while 'nc/mpiio' outputs in order of
the MPI rank.
In addition to per-atom data, also global (i.e. not per atom, but per frame) quantities can be included in the
dump file. This can be variables, output from computes or fixes data prefixed with v_, c_ and f_, respectively.
These properties are included via dump_modify global.
Restrictions:
The nc and nc/mpiio dump styles are part of the USER-NC-DUMP package. It is only enabled if LAMMPS
was built with that package. See the Making LAMMPS section for more info.
Related commands:
dump, dump_modify, undump

458

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

459

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

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

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

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

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

464

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 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
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 t

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.
For fixes that calculate a contribution to the potential energy of the system, the energy keyword will include
that contribution in thermodynamic output of potential energy. This is because the energy yes setting must be
specified to include the fix's global or per-atom energy 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.
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.

465

LAMMPS Users Manual
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, respa = 0.

466

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 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
region args = region-ID
type or id or molecule
args = list of one or more atom types, atom IDs, or molecule IDs
any entry in list can be a sequence formatted as A:B or A:B:C where
A = starting index, B = ending index,
C = increment between indices, 1 if not specified
args = logical value
logical = "" or ">=" or "==" or "!="
value = an atom type or atom ID or molecule ID (depending on style)
args = logical value1 value2
logical = ""
value1,value2 = atom types or atom IDs or molecule IDs (depending on style)
variable args = variable-name
include args = molecule
molecule = add atoms to group with same molecule ID as atoms already in group
subtract args = two or more group IDs
union args = one or more group IDs
intersect args = two or more group IDs
dynamic args = parent-ID keyword value ...
one or more keyword/value pairs may be appended
keyword = region or var or every
region value = region-ID
var value = name of variable
every value = N = update group every this many timesteps
static = no args

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

467

LAMMPS Users Manual
Description:
Identify a collection of atoms as belonging to a group. The group ID can then be used in other commands such
as fix, compute, dump, or velocity to act on those atoms together.
If the group ID already exists, the group command adds the specified atoms to the group.
NOTE: By default groups are static, meaning the atoms are permanently assigned to the group. For example,
if the region style is used to assign atoms to a group, the atoms will remain in the group even if they later
move out of the region. As explained below, the dynamic style can be used to make a group dynamic so that a
periodic determination is made as to which atoms are in the group. Since many LAMMPS commands operate
on groups of atoms, you should think carefully about whether making a group dynamic makes sense for your
model.
A group with the ID all is predefined. All atoms belong to this group. This group cannot be deleted, or made
dynamic.
The delete style removes the named group and un-assigns all atoms that were assigned to that group. Since
there is a restriction (see below) that no more than 32 groups can be defined at any time, the delete style
allows you to remove groups that are no longer needed, so that more can be specified. You cannot delete a
group if it has been used to define a current fix or compute or dump.
The clear style un-assigns all atoms that were assigned to that group. This may be dangerous to do during a
simulation run, e.g. using the run every command if a fix or compute or other operation expects the atoms in
the group to remain constant, but LAMMPS does not check for this.
The 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.

468

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

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

nsteps equal 5000
rad equal 18-(step/v_nsteps)*(18-5)
ss sphere 20 20 0 v_rad
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.

470

LAMMPS Users Manual
Related commands:
dump, fix, region, velocity
Default:
All atoms belong to the "all" group.

471

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
Default: none

472

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 ${eng_previous}" then "jump file1" else "jump file2"

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

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

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):
474

LAMMPS Users Manual
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
Related commands:
variable, print
Default: none

475

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

LAMMPS Users Manual
• improper_style none - turn off improper interactions
• improper_style hybrid - define multiple styles of improper interactions
• improper_style class2 - COMPASS (class 2) improper
• improper_style cvff - CVFF improper
• improper_style harmonic - harmonic improper
• improper_style 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

477

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
• improper_style hybrid - define multiple styles of improper interactions
• improper_style class2 - COMPASS (class 2) improper
• improper_style cvff - CVFF improper
• improper_style harmonic - harmonic improper
478

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

479

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

480

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, 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.
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.
481

LAMMPS Users Manual
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 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:
print
Default:
The out option has the default screen.
The styles option has the default all.

482

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

484

LAMMPS Users Manual
Default: none

485

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 gewa
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 more
minorder value = M
M = min allowed extent of Gaussian when auto-adjusting to minimize grid communication
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.

486

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 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
487

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

LAMMPS Users Manual
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 on by default. If this option is turned off, LAMMPS will not
take the time at the end of a run to give FFT benchmark timings, and will finish a few seconds faster than it
would if this option were on.
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 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.

489

LAMMPS Users Manual
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 (MSM), fftbench = yes (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.

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

490

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

Examples:
kspace_style pppm 1.0e-4
kspace_style pppm/cg 1.0e-5 1.0e-6
kspace style msm 1.0e-4

491

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

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

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

494

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

495

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

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

496

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

497

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. Styles sq or sq2 or hex are for 2d problems. Style
custom can be used for either 2d or 3d problems.

498

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

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

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

1.0
$a
0.0
0.0
0.0
0.5
${1_3}
${5_6}
0.0
0.5
${1_3}
${5_6}

&
0.0
$b
0.0
0.0
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.0
$c
0.0
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.

501

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.7 for details.
Restrictions: none
Related commands: none
Default:
The default LAMMPS log file is named log.lammps

502

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

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

504

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.
Restrictions: none
Related commands:
min_style, minimize
505

LAMMPS Users Manual
Default:
The option defaults are dmax = 0.1 and line = quadratic.

506

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

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

508

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

509

LAMMPS Users Manual
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 change in energy between outer iterations is less than etol
• the 2-norm (length) of the global force vector is less than the ftol
• the line search fails because the step distance backtracks to 0.0
• the number of outer iterations or timesteps exceeds maxiter
• the number of total force evaluations exceeds maxeval
NOTE: You can also use the fix halt command to specify a general criterion for exiting a minimization, that is
a calculation performed on the state of the current system, as defined by an equal-style variable.
For the first criterion, the specified energy tolerance etol is unitless; it is met when the energy change between
successive iterations divided by the energy magnitude is less than or equal to the tolerance. For example, a
setting of 1.0e-4 for etol means an energy tolerance of one part in 10^4. For the damped dynamics minimizers
this check is not performed for a few steps after velocities are reset to 0, otherwise the minimizer would
prematurely converge.
For the second criterion, the specified force tolerance ftol is in force units, since it is the length of the global
force vector for all atoms, e.g. a vector of size 3N for N atoms. Since many of the components will be near
zero after minimization, you can think of ftol as an upper bound on the final force on any component of any
atom. For example, a setting of 1.0e-4 for ftol means no x, y, or z component of force on any atom will be
larger than 1.0e-4 (in force units) after minimization.
Either or both of the etol and ftol values can be set to 0.0, in which case some other criterion will terminate the
minimization.
During a minimization, the outer iteration count is treated as a timestep. Output is triggered by this timestep,
e.g. thermodynamic output or dump and restart files.
Using the thermo_style custom command with the fmax or fnorm keywords can be useful for monitoring the
progress of the minimization. Note that these outputs will be calculated only from forces on the atoms, and
will not include any extra degrees of freedom, such as from the fix box/relax command.
510

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

511

LAMMPS Users Manual
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 addforce
• fix addtorque
• fix efield
• fix enforce2d
• fix indent
• fix lineforce
• fix planeforce
• fix setforce
• fix spring
• fix spring/self
• fix viscous
• fix wall
• fix wall/region
NOTE: Some fixes which are invoked during minimization have an associated potential energy. For that
energy to be included in the total potential energy of the system (the quantity being minimized), you MUST
enable the fix_modify energy option for that fix. The doc pages for individual fix commands specify if this
should be done.
Restrictions:
Features that are not yet implemented are listed here, in case someone knows how they could be coded:
It is an error to use fix shake with minimization because it turns off bonds that should be included in the
potential energy of the system. The effect of a fix shake can be approximated during a minimization by using
stiff spring constants for the bonds and/or angles that would normally be constrained by the SHAKE
algorithm.
Fix rigid is also not supported by minimization. It is not an error to have it defined, but the energy
minimization will not keep the defined body(s) rigid during the minimization. Note that if bonds, angles, etc
internal to a rigid body have been turned off (e.g. via neigh_modify exclude), they will not contribute to the
potential energy which is probably not what is desired.
Pair potentials that produce torque on a particle (e.g. granular potentials or the GayBerne potential for
ellipsoidal particles) are not relaxed by a minimization. More specifically, radial relaxations are induced, but
no rotations are induced by a minimization, so such a system will not fully relax.
Related commands:
min_modify, min_style, run_style
Default: none

512

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

513

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

514

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

515

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

516

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

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

518

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

519

LAMMPS Users Manual
LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

neb command
Syntax:
neb etol ftol N1 N2 Nevery file-style arg

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

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

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 3 papers:
(HenkelmanA), (HenkelmanB), and (Nakano).
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.7 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.
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.

520

LAMMPS Users Manual
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 atom in a replica is connected to the same atom in adjacent replicas by springs,
which induce inter-replica 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 configuration for the first replica should be a state with all the atoms (NEB and
non-NEB) having coordinates on one side of the energy barrier. A perfect energy minimum is not required,
since atoms in the first replica experience no spring forces from the 2nd replica. Thus the damped dynamics
minimization will drive the first replica to an energy minimum if it is not already there. However, you will
typically get better convergence if the initial state is already at a minimum. For example, for a system with a
free surface, the surface should be fully relaxed before attempting a NEB calculation.
Likewise, the initial configuration of the final replica should be a state with all the atoms (NEB and non-NEB)
on the other side of the energy barrier. Again, a perfect energy minimum is not required, since the atoms in
the last replica also experience no spring forces from the next-to-last replica, and thus the damped dynamics
minimization will drive it to an energy minimum.
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 state 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
configuration. 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 this procedure to produce consistent coordinates across all the
replicas, the current coordinates need to be the same in all replicas. LAMMPS does not check for this, but
invalid initial configurations will likely result if it is not the case.

521

LAMMPS Users Manual
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 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 forces between an atom and
its images in adjacent replicas.
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.
522

LAMMPS Users Manual
In the first stage of NEB, the set of replicas should converge toward the minimum energy path (MEP) of
conformational states that transition over the barrier. The MEP for a barrier is defined as a sequence of
3N-dimensional states that cross the barrier at its saddle point, each of which has a potential energy gradient
parallel to the MEP itself. The replica states will also be roughly equally spaced along the MEP due to the
inter-replica spring 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, one of the replicas should be an atomic
configuration at the top or saddle point of the barrier, the potential energies for the set of replicas should
represent the energy profile of the barrier along the MEP, and the configurations of the replicas should be a
sequence of configurations along the MEP.
A few other settings in your input script are required or advised to perform a NEB calculation. See the NOTE
about the choice of timestep at the beginning of this doc page.
An atom map must be defined which it is not by default for atom_style atomic problems. The atom_modify
map command can be used to do this.
The minimizers in LAMMPS operate on all atoms in your system, even non-NEB atoms, as defined above. To
prevent non-NEB atoms from moving during the minimization, you should use the fix setforce command to
set the force on each of those atoms to 0.0. This is not required, and may not even be desired in some cases,
but if those atoms move too far (e.g. because the initial state of your system was not well-minimized), it can
cause problems for the NEB procedure.
The damped dynamics minimizers, such as quickmin and fire), adjust the position and velocity of the atoms
via an Euler integration step. Thus you must define an appropriate timestep to use with NEB. As mentioned
above, NEB will often converge more quickly if you use a timestep about 10x larger than you would normally
use for dynamics simulations.
Each file read by the neb command containing atomic coordinates used to initialize one or more replicas must
be formatted as follows.
The file can be ASCII text or a gzipped text file (detected by a .gz suffix). The file can contain initial blank
lines or comment lines starting with "#" which are ignored. The first non-blank, non-comment line should list
N = the number of lines to follow. The N successive lines contain the following information:
ID1 x1 y1 z1
ID2 x2 y2 z2
...
IDN xN yN zN

The fields are the atom ID, followed by the x,y,z coordinates. The lines can be listed in any order. Additional
trailing information on the line is OK, such as a comment.
Note that for a typical NEB calculation you do not need to specify initial coordinates for very many atoms to
produce differing starting and final replicas whose intermediate replicas will converge to the energy barrier.
Typically only new coordinates for atoms geometrically near the barrier need be specified.
523

LAMMPS Users Manual
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. Note that inter-replica forces are zero in the initial and final
replicas, and only affect the direction in the climbing replica. For this reason, the "maximum force per replica"
is often equal to the potential gradient in the climbing replica. In the first stage of NEB, there is no climbing
replica, and so the potential gradient in the highest energy replica is reported, since this replica will become
the climbing replica in the second stage of NEB.
The "reaction coordinate" (RD) for each replica is the two-norm of the 3N-length vector of distances between
its atoms and the preceding replica's atoms, added to the RD of the preceding replica. The RD of the first
replica RD1 = 0.0; the RD of the final replica RDN = RDT, the total reaction coordinate. The normalized RDs
are divided by RDT, so that they form a monotonically increasing sequence from zero to one. When
computing RD, N only includes the atoms being operated on by the fix neb command.
The forward (reverse) energy barrier is the potential energy of the highest replica minus the energy of the first
(last) replica.
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
524

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

525

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

526

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.
The exclude option turns off pairwise interactions between certain pairs of atoms, by not including them in the
neighbor list. These are sample scenarios where this is useful:
• In crack simulations, pairwise interactions can be shut off between 2 slabs of atoms to effectively
create a crack.
• When a large collection of atoms is treated as frozen, interactions between those atoms can be turned
off to save needless computation. E.g. Using the fix setforce command to freeze a wall or portion of a
bio-molecule.
• When one or more rigid bodies are specified, interactions within each body can be turned off to save
needless computation. See the fix rigid command for more details.
The exclude type option turns off the pairwise interaction if one atom is of type M and the other of type N. M
can equal N. The exclude group option turns off the interaction if one atom is in the first group and the other
is the second. Group1-ID can equal group2-ID. The exclude molecule/intra option turns off the interaction if
both atoms are in the specified group and in the same molecule, as determined by their molecule ID. The
exclude molecule/inter turns off the interaction between pairs of atoms that have different molecule IDs and
are both in the specified group.
Each of the exclude options can be specified multiple times. The exclude type option is the most efficient
option to use; it requires only a single check, no matter how many times it has been specified. The other
exclude options are more expensive if specified multiple times; they require one check for each time they
527

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

528

LAMMPS Users Manual
The option defaults are delay = 10, every = 1, check = yes, once = no, cluster = no, include = all, exclude =
none, page = 100000, one = 2000, and binsize = 0.0.

529

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

530

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

531

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

532

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.
When the next command is used with universe- or uloop-style variables, all universe- or uloop-style variables
must be listed in the next command. This is because of the manner in which the incrementing is done, using a
single lock file for all variables. The next value (for each variable) is assigned to whichever processor
partition executes the command first. All processors in the partition are assigned the same value(s). Running
LAMMPS on multiple partitions of processors via the "-partition" command-line switch is described in this
section of the manual. Universe- and uloop-style variables are incremented using the files
533

LAMMPS Users Manual
"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
if
next
jump
label
variable

loopa
a loop 5
loopb
b loop 5
"A,B = $a,$b"
10000
$b > 2 then "jump in.script break"
b
in.script loopb
break
b delete

next
jump

a
in.script loopa

Restrictions:

534

LAMMPS Users Manual
As described above.
Related commands:
jump, include, shell, variable,
Default: none

535

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 blocksize
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

536

LAMMPS Users Manual

keywords = neigh or neigh/qeq or newton or binsize or comm or comm/exchange or comm/f
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 both comm/exchange and comm/forward
comm/exchange value = no or host or device
comm/forward 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 invoked by other accelerator settings.

537

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

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

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

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

541

LAMMPS Users Manual
The comm and comm/exchange and comm/forward 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. 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 keywords.
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.

542

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

543

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

544

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 in a data file, the line
corresponding to the 1st example above would be listed as
2 1.0 1.0 2.5

545

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

546

LAMMPS Users Manual
Related commands:
pair_style, pair_modify, read_data, read_restart, pair_write
Default: none

547

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

shift yes mix geometric
tail yes
table 12
pair lj/cut compute 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 will be applied to all sub-styles.
The special keyword can only be used in conjunction with the pair keyword and must directly follow it. It
allows to override the special_bonds settings for the specified 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
548

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

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

LAMMPS Users Manual
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.
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:
pair_style, pair_coeff, thermo_style
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).

551

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 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
552

LAMMPS Users Manual
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 none - turn off pairwise interactions
• pair_style hybrid - multiple styles of pairwise interactions
• pair_style hybrid/overlay - multiple styles of superposed pairwise interactions
• pair_style 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
• 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
553

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

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

555

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:
All force field coefficients for pair and other kinds of interactions must be set before this command can be
invoked.
556

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

557

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

LAMMPS Users Manual
run_style verlet/split
Default: none

559

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 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.7 of the manual. Note that if you have MPI installed, you
560

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

LAMMPS Users Manual
In the third stage, the replica on which the event occurred (event replica) continues to run dynamics to search
for correlated events. This is done by running dynamics for t_correlate steps, quenching every t_event steps,
and checking if another event has occurred.
The first time no correlated event occurs, the final state of the event replica is shared with all replicas, the new
basin reference coordinates are updated with the quenched state, and the outer loop begins again. While the
replica event is searching for correlated events, all the other replicas also run dynamics and event checking
with the same schedule, but the final states are always overwritten by the state of the event replica.
The outer loop of the pseudo-code above continues until N steps of dynamics have been performed. Note that
N only includes the dynamics of stages 2 and 3, not the steps taken during dephasing or the minimization
iterations of quenching. The specified N is interpreted in one of two ways, depending on the time keyword. If
the time value is steps, which is the default, then each replica runs for N timesteps. If the time value is clock,
then the simulation runs until N aggregate timesteps across all replicas have elapsed. This aggregate time is
the "clock" time defined below, which typically advances nearly M times faster than the timestepping on a
single replica, where M is the number of replicas.
Four kinds of output can be generated during a PRD run: event statistics, thermodynamic output by each
replica, dump files, and restart files.
When running with multiple partitions (each of which is a replica in this case), the print-out to the screen and
master log.lammps file is limited to event statistics. Note that if a PRD run is performed on only a single
replica then the event statistics will be intermixed with the usual thermodynamic output discussed below.
The quantities printed each time an event occurs are the timestep, CPU time, clock, event number, a
correlation flag, the number of coincident events, and the replica number of the chosen event.
The timestep is the usual LAMMPS timestep, except that time does not advance during dephasing or
quenches, but only during dynamics. Note that are two kinds of dynamics in the PRD loop listed above that
contribute to this timestepping. The first is when all replicas are performing independent dynamics, waiting
for an event to occur. The second is when correlated events are being searched for, but only one replica is
running dynamics.
The CPU time is the total elapsed time on each processor, since the start of the PRD run.
The clock is the same as the timestep except that it advances by M steps per timestep during the first kind of
dynamics when the M replicas are running independently. The clock advances by only 1 step per timestep
during the second kind 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
562

LAMMPS Users Manual
replicas that detected an event. Normally, this value should be 1. If it is often greater than 1, then either the
number of replicas is too large, or t_event is too large.
The replica number is the ID of the replica (from 0 to M-1) in which the event occurred.
When running on multiple partitions, LAMMPS produces additional log files for each partition, e.g.
log.lammps.0, log.lammps.1, etc. For the PRD command, these contain the thermodynamic output for each
replica. You will see short runs and minimizations corresponding to the dynamics and quench operations of
the loop listed above. The timestep will be reset appropriately depending on whether the operation advances
time or not.
After the PRD command completes, timing statistics for the PRD run are printed in each replica's log file,
giving a breakdown of how much CPU time was spent in each stage (dephasing, dynamics, quenching, etc).
Any dump files defined in the input script, will be written to during a PRD run at timesteps corresponding to
both uncorrelated and correlated events. This means the requested dump frequency in the dump command is
ignored. There will be one dump file (per dump command) created for all partitions.
The atom coordinates of the dump snapshot are those of the minimum energy configuration resulting from
quenching following a transition event. The timesteps written into the dump files correspond to the timestep at
which the event occurred and NOT the clock. A dump snapshot corresponding to the initial minimum state
used for event detection is written to the dump file at the beginning of each PRD run.
If the restart command is used, a single restart file for all the partitions is generated, which allows a PRD run
to be continued by a new input script in the usual manner.
The restart file is generated at the end of the loop listed above. If no correlated events are found, this means it
contains a snapshot of the system at time T + t_correlate, where T is the time at which the uncorrelated event
occurred. If correlated events were found, then it contains a snapshot of the system at time T + t_correlate,
where T is the time of the last correlated event.
The restart frequency specified in the restart command is interpreted differently when performing a PRD run.
It does not mean the timestep interval between restart files. Instead it means an event interval for uncorrelated
events. Thus a frequency of 1 means write a restart file every time an uncorrelated event occurs. A frequency
of 10 means write a restart file every 10th uncorrelated event.
When an input script reads a restart file from a previous PRD run, the new script can be run on a different
number of replicas or processors. However, it is assumed that t_correlate in the new PRD command is the
same as it was previously. If not, the calculation of the "clock" value for the first event in the new run will be
slightly off.
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.
563

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

(Voter2002) Voter, Montalenti, Germann, Annual Review of Materials Research 32, 321 (2002).

564

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
file value = filename
append value = filename
screen 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 """
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 you want the print command to be executed multiple times (with changing variable values), there are 3
options. First, consider using the fix print command, which will print a string periodically during a simulation.
Second, the print command can be used as an argument to the every option of the run command. Third, the
print command could appear in a section of the input script that is looped over (see the jump and next
commands).
See the variable command for a description of equal style variables which are typically the most useful ones
to use with the print command. Equal-style variables can calculate formulas involving mathematical
operations, atom properties, group properties, thermodynamic properties, global values calculated by a
compute or fix, or references to other variables.
Restrictions: none
565

LAMMPS Users Manual
Related commands:
fix print, variable
Default:
The option defaults are no file output and screen = yes.

566

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

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

568

LAMMPS Users Manual
NOTE: For the twolevel style to work correctly, it assumes the MPI ranks of processors LAMMPS is running
on are ordered by core and then by node. E.g. if you are running on 2 quad-core nodes, for a total of 8
processors, then it assumes processors 0,1,2,3 are on node 1, and processors 4,5,6,7 are on node 2. This is the
default rank ordering for most MPI implementations, but some MPIs provide options for this ordering, e.g. via
environment variable settings.
The numa style operates similar to the twolevel keyword except that it auto-detects which cores are running on
which nodes. Currently, it does this in only 2 levels, but it may be extended in the future to account for socket
topology and other non-uniform memory access (NUMA) costs. It also uses a different algorithm than the
twolevel keyword for doing the two-level factorization of the simulation box into a 3d processor grid to
minimize off-node communication, and it does its own MPI-based mapping of nodes and cores to the regular
3d grid. Thus it may produce a different layout of the processors than the twolevel options.
The numa style will give an error if the number of MPI processes is not divisible by the number of cores used
per node, or any of the Px or Py of Pz values is greater than 1.
NOTE: Unlike the twolevel style, the numa style does not require any particular ordering of MPI ranks i
norder to work correctly. This is because it auto-detects which processes are running on which nodes.
The custom style uses the file infile to define both the 3d factorization and the mapping of processors to the
grid.
The file should have the following format. Any number of initial blank or comment lines (starting with a "#"
character) can be present. The first non-blank, non-comment line should have 3 values:
Px Py Py

These must be compatible with the total number of processors and the Px, Py, Pz settings of the processors
command.
This line should be immediately followed by P = Px*Py*Pz lines of the form:
ID I J K

where ID is a processor ID (from 0 to P-1) and I,J,K are the processors location in the 3d grid. I must be a
number from 1 to Px (inclusive) and similarly for J and K. The P lines can be listed in any order, but no
processor ID should appear more than once.
The map keyword affects how the P processor IDs (from 0 to P-1) are mapped to the 3d grid of processors. It
is only used by the onelevel and twolevel grid settings.
The cart style uses the family of MPI Cartesian functions to perform the mapping, namely MPI_Cart_create(),
MPI_Cart_get(), MPI_Cart_shift(), and MPI_Cart_rank(). It invokes the MPI_Cart_create() function with its
reorder flag = 0, so that MPI is not free to reorder the processors.
The cart/reorder style does the same thing as the cart style except it sets the reorder flag to 1, so that MPI can
reorder processors if it desires.
The xyz, xzy, yxz, yzx, zxy, and zyx styles are all similar. If the style is IJK, then it maps the P processors to the
grid so that the processor ID in the I direction varies fastest, the processor ID in the J direction varies next
fastest, and the processor ID in the K direction varies slowest. For example, if you select style xyz and you
569

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

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

571

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
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 ass
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

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 -f here """
def loop(lmpptr,N,cut0):
from lammps import lammps
lmp = lammps(ptr=lmpptr)
# loop N times, increasing cutoff each time
for i in range(N):
cut = cut0 + i*0.1
lmp.set_variable("cut",cut)
lmp.command("pair_style lj/cut ${cut}")

# set a variable in LAMMPS
# LAMMPS commands

572

LAMMPS Users Manual
lmp.command("pair_coeff * * 1.0 1.0")
lmp.command("run 100")
"""

Description:
NOTE: It is not currently possible to use the python command described in this section with Python 3, only
with Python 2. The C API changed from Python 2 to 3 and the LAMMPS code is not compatible with both.
Define a Python function or execute a previously defined function. 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.
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.
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.
573

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

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

LAMMPS Users Manual
Third, if your Python code calls back to LAMMPS (discussed in the next section) and causes LAMMPS to
perform an MPI operation requires global communication (e.g. via MPI_Allreduce), such as computing the
global temperature of the system, then you must insure all your Python functions (running independently on
different processors) call back to LAMMPS. Otherwise the code may hang.
Your Python function can "call back" to LAMMPS through its library interface, if you use the SELF input to
pass Python a pointer to LAMMPS. The mechanism for doing this in your Python function is as follows:
def foo(lmpptr,...):
from lammps import lammps
lmp = lammps(ptr=lmpptr)
lmp.command('print "Hello from inside Python"')
...

The function definition must include a variable (lmpptr in this case) which corresponds to SELF in the python
command. The first line of the function imports the 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 thrid 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                      : 1950
Page Layout                     : SinglePage
Page Mode                       : UseNone
Producer                        : htmldoc 1.8.27 Copyright 1997-2006 Easy Software Products, All Rights Reserved.
Create Date                     : 2017:03:30 09:53:37
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