LAMMPS from scratch · 20 min

A tour of the source tree

What is inside the LAMMPS download, folder by folder, with real file counts; which small part is actually compiled; and the naming rule that takes you from any line of an input script to the C++ file that carries it out. Then you swap one pair style for another, find its file, read its maths and check the new energy by hand.

1 · Understand: what you downloaded

The LAMMPS download (stable_22Jul2025_update6) has twelve folders. Only one of them, src, becomes the program; the rest are the manual, examples, tests and helpers.

Loading the real counts…

2 · Inside src: a core and packages

Files directly in src/ are the core: always compiled. Each upper-case folder inside src/ is a package, compiled only if you switch it on (page 0.4, and B.5). A build is the core plus the packages you chose.

3 · The naming rule: from a script line to a file

Every command works the same way. The first word is looked up in src/input.cpp. If the command chooses a style (pair_style, fix, compute …), the style name is then looked up in a list of registered styles, and the matching class does the work. Its file name follows a rule:

ScriptRuleFile
pair_style lj/cutpair_ + name, with / → _src/pair_lj_cut.cpp
fix 1 all nvefix_ + the 4th wordsrc/fix_nve.cpp
compute 1 all rdf 100compute_ + the 4th wordsrc/compute_rdf.cpp
atom_style fullatom_vec_ + namesrc/MOLECULE/atom_vec_full.cpp
create_atoms …the command namesrc/create_atoms.cpp
pair_style lj/cut/ompan accelerator suffix → the same name + _ompsrc/OPENMP/pair_lj_cut_omp.cpp

4 · Modify: swap lj/cut for lj/expand

lj/expand is LJ with the whole curve moved outwards by a distance Δ: E(r) = 4ε[(σ/(r−Δ))¹² − (σ/(r−Δ))⁶], with the cutoff also moved to rc + Δ. It is used for particles of different sizes. Δ is the 5th word of pair_coeff. With Δ = 0 it must give exactly the lj/cut numbers.

Its file (section 3 rule: src/pair_lj_expand.cpp) is 90 % the same as pair_lj_cut.cpp. The maths inside the double loop over atoms i and their neighbours j:

106  if (rsq < cutsq[itype][jtype]) {          // r² below (rc + Δ)²
107    r = sqrt(rsq);
108    rshift = r - shift[itype][jtype];       // r − Δ   ← the only new idea
109    rshiftsq = rshift * rshift;
110    r2inv = 1.0 / rshiftsq;
111    r6inv = r2inv * r2inv * r2inv;          // 1/(r−Δ)⁶
112    forcelj = r6inv * (lj1 * r6inv - lj2);  // lj1 = 48εσ¹², lj2 = 24εσ⁶
113    fpair = factor_lj * forcelj / rshift / r;
       …
125    evdwl = r6inv * (lj3 * r6inv - lj4) - offset;   // lj3 = 4εσ¹², lj4 = 4εσ⁶

src/pair_lj_expand.cpp:106. Lines 112–113 are the force F = 24ε[2σ¹²/(r−Δ)¹³ − σ⁶/(r−Δ)⁷], divided by r so it can be multiplied by Δx, Δy, Δz. (The [itype][jtype] after lj1 … lj4 is dropped here for space.)

try 0, 0.1, 0.2

  

5 · Predict by hand, then run

At step 0 the atoms sit on the FCC crystal (page A.5), so every atom has the same neighbours: shells of 12, 6, 24, 12, 24 … atoms. Energy per atom = ½ Σ n·E(r) (the ½ because each pair is shared by two atoms).

6 · Observe: a style that is not in this build

lj/smooth/linear is a real LAMMPS pair style. Find its file in section 3 first, then run it here.

The file is in the EXTRA-PAIR package, and the LAMMPS in this browser was built without it. Same command, same syntax: whether it works depends on how the program was built. On your own computer: cmake -D PKG_EXTRA-PAIR=on and build again (page 0.4).

Your turn

1. Which file carries out fix 2 all npt temp 1 1 0.5 iso 0 0 5? Predict, then check with the finder.

2. With Δ = 0.2, E_pair rises from −7.47 to −0.62 and the pressure from 5 to 58. Which shell causes it? Use the shell table.

3. The examples folder is the largest (about 217 MB). Does it make the program bigger?