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.
- What each top-level folder holds and which one becomes the program
- Core code versus packages in src/
- The naming rule: from pair_style lj/cut to src/pair_lj_cut.cpp
- Swap lj/cut for lj/expand, read its 8 lines of maths, and match LAMMPS 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:
| Script | Rule | File |
|---|---|---|
pair_style lj/cut | pair_ + name, with / → _ | src/pair_lj_cut.cpp |
fix 1 all nve | fix_ + the 4th word | src/fix_nve.cpp |
compute 1 all rdf 100 | compute_ + the 4th word | src/compute_rdf.cpp |
atom_style full | atom_vec_ + name | src/MOLECULE/atom_vec_full.cpp |
create_atoms … | the command name | src/create_atoms.cpp |
pair_style lj/cut/omp | an accelerator suffix → the same name + _omp | src/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.)
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.
src/fix_npt.cpp. It is only a few lines long: it sets options and inherits everything from fix_nh.cpp, where the thermostat and barostat maths lives (inheritance: page B.3).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?
src/ (the core plus switched-on packages) is compiled. examples, doc, potentials and tools are never part of lmp.