The Script Can Still Start: Why Units Come First in a LAMMPS Input Script

A crash is a gift. It stops the run, prints a line number, and tells you where to look. The more expensive failure in a first LAMMPS input script is the one that does not crash at all. You write a mass that you meant in grams per mole, a cutoff you meant in Ångstroms, and a timestep you meant in femtoseconds. You never issue a units command. LAMMPS reads the file, builds the box, and integrates happily — in Lennard-Jones reduced units, because the official default unit style is lj. The thermo output scrolls. Nothing is red. Every number on the screen means something other than what you intended.

That is the problem worth solving first, before potentials, before data files, before a long production run: making sure the script means what you wrote. Input Script Anatomy and Units First (for LAMMPS) is built around exactly that. It gives you the official four-part script anatomy, a checklist that puts two official ordering rules on the page before you type a box command, and four original input scripts — a commented template plus first runs in lj, real, and metal — every one of which was run to completion on official LAMMPS stable 30 Sep 2026 Update 1.

Get it here: Input Script Anatomy and Units First (for LAMMPS)

What, exactly, goes wrong in a first input script?

Five problems show up with enough regularity that they deserve plain names. Each one has a specific shape, and each one has a specific fix.

**1. The script never issues units.** The official documentation for the units command lists the default as units lj. If your script never says otherwise, every mass, distance, energy, and time in it is read as a reduced quantity. A mass 1 39.9 intended as argon in grams per mole becomes a particle 39.9 times the reference mass. The script runs. It runs the wrong simulation.

**2. units is issued after the box exists.** The official restriction is blunt: the command “cannot be used after the simulation box is defined by a read_data or create_box command.” Moving units below create_box while tidying a script is an easy edit to make and an annoying one to discover.

**3. Coefficients arrive before pair_style.** The official restriction on pair_style says it “must be used before any coefficients are set by the pair_coeff, read_data, or read_restart commands.” That last part catches people the first time they add a data file that carries pair coefficients: the read_data line has to sit below pair_style, not above it.

4. There is no agreed anatomy. Initialization, box creation, settings, and the run end up interleaved in the order they were thought of. The script works until someone else — or you, in three weeks — has to change it. Then every edit is archaeology.

5. The timestep and neighbor skin were guessed. The units command also sets a default timestep and neighbor skin for each style. For lj those are 0.005 τ and 0.3 σ; for real, 1.0 fs and 2.0 Å; for metal, 0.001 ps and 2.0 Å. A first script that invents its own values has given up a sensible, documented starting point for no reason.

None of these are exotic. They are ordinary mistakes made by capable people working quickly, which is exactly why they deserve a checklist rather than a lecture.

Why is “it ran” not the same as “it is right”?

Units mistakes have a long and humbling history, and the pattern is consistent: the system accepted the numbers, did its job, and delivered a result nobody had meant to ask for.

In 1983, Air Canada Flight 143 — the Boeing 767 later nicknamed the Gimli Glider — ran out of fuel at cruising altitude because the fuel load had been calculated with a conversion factor for pounds where kilograms were needed. The aircraft was fueled. The paperwork was filled in. The arithmetic was internally consistent. It was consistent in the wrong unit, and the crew finished the flight as glider pilots.

In 1999, NASA lost the Mars Climate Orbiter because one piece of ground software reported thruster impulse in pound-force seconds while the navigation software expected newton-seconds. Nothing crashed on the ground. Data flowed, trajectories were computed, corrections were made. The spacecraft approached Mars far lower than planned and was lost.

The fix, historically, has never been “be more careful.” It has been to agree on the unit explicitly and write it down where it cannot be skipped. The Metre Convention of 1875, signed by seventeen nations, did not make anyone smarter. It made a kilogram in one laboratory mean the same thing as a kilogram in another, by declaration, in advance.

A LAMMPS input script is a small version of the same arrangement. The units line is the declaration. Write it first, write it on purpose, and the rest of the file has a fixed meaning. Skip it, and LAMMPS supplies one for you — politely, silently, and possibly wrongly.

What is the official anatomy, and why use it as a spine?

The official LAMMPS documentation describes a typical input script as having four parts: Initialization, System definition, Simulation settings, and Run a simulation. It also notes that the last two parts can be repeated as many times as you like — run, change settings, run some more.

This kit takes those four official parts and makes them the visible structure of every shipped file:

  • Initialization — units first, then atom_style, boundary, and pair_style. The official structure puts force-field style commands here, because they set parameters that must be defined before atoms are created or read in.
  • System definition — lattice, region, create_box, create_atoms, and mass.
  • Simulation settings — pair_coeff, neighbor settings, timestep, velocities, and fixes.
  • Run — run, plus any output you need once integration has started.

The value of a fixed spine is not elegance. It is that every later edit has an obvious home. When you add a data file, you know it belongs in System definition, below a pair_style that is already set in Initialization. When you change a potential’s coefficients, you know pair_coeff lives in Simulation settings. When you lengthen the run, you touch only the last block. When a colleague opens your script, they read it in the same order LAMMPS executes it.

The template makes the ordering rules impossible to miss. The units lj line carries the comment “first command that sets a unit style.” The create_box line carries the comment “after this line, units cannot be changed.” The pair_style line, sitting in Initialization, reminds you that the style comes before the box and before pair_coeff or any later read_data. These are small marks, and they are the difference between a rule you know and a rule you see every time you open the file.

What is in the kit?

The zip contains a 4-page guide, four original input scripts, an Excel checklist, and a README.

The guide covers the official anatomy, the units-first rule, pair_style before coefficients, a table of the official default timestep and skin for every official unit style (lj, real, metal, si, cgs, electron, micro, and nano), a description of each shipped script, and a first-hour path. It also tells you what to change first and what to leave alone, which is the advice people usually only get by breaking something.

The four scripts:

  • 00-anatomy-template.in — a commented lj template that walks the four parts. It is also a complete, runnable script: a 4×4×4 fcc lattice, 200 steps, official lj defaults.
  • 01-units-lj-first.in — a first lj run: fcc at reduced density 0.8, 5×5×5, T* = 1.0, official dt and skin, with neighbor checks every step so a first run stays clean.
  • 02-units-real-first.in — a first real run with illustrative argon-like teaching values (mass 39.9 g/mol, ε 0.24 kcal/mol, σ 3.40 Å, cutoff 8.5 Å, 80 K), labelled in the file as teaching values.
  • 03-units-metal-first.in — a first metal run with illustrative teaching values (ε 0.010 eV, σ 3.40 Å), labelled the same way.

All four were run to completion on official LAMMPS stable 30 Sep 2026 Update 1 (git tag stable_30Sep2026_update1), and the neighbor list reported zero dangerous builds on every run. The teaching coefficients are there so your first script has numbers that will run. They are not a cited potential, and the kit is clear about that inside the files themselves. When you have a potential you actually intend to use, you obtain it from official LAMMPS sources and swap it in.

**Units-First-Checklist.xlsx** has five sheets: Start Here, a Pre-run checklist of ten checks drawn from official documentation, the official unit styles with their default dt and skin, the Anatomy, and a Run record. The Run record already holds the four kit-build rows; the blank rows are for yours. Writing down the LAMMPS version you ran is a small habit that pays for itself the first time a result needs to be reproduced on a different machine.

Why three unit styles side by side?

Because the fastest way to understand a unit style is to see the same kind of system expressed in two others.

Put 02-units-real-first.in and 03-units-metal-first.in next to each other. The lattice, mass, σ, and cutoff are identical. What changes is what the numbers mean: ε is 0.24 in kcal/mol in one file and 0.010 in eV in the other; the timestep is 1.0 fs in one and 0.001 ps in the other — the same physical femtosecond, written in a different unit. Then open the lj script and see everything collapse to ones and reduced quantities. Ten minutes of reading those three files side by side teaches more about unit styles than an afternoon of skimming tables.

It also makes the guide’s central rule concrete: if you switch style, switch the entire script — mass, lattice, coefficients, temperature, timestep, and skin. A real mass inside an lj box is not a rounding error. It is a different universe.

What does the first hour look like?

Install LAMMPS from official sources and note the version. Open the checklist on Start Here, then read the Pre-run checklist so the rules are fresh. Open 00-anatomy-template.in in a text editor and read it top to bottom against the four parts.

Run 01-units-lj-first.in with your executable — a common form is lmp -in 01-units-lj-first.in — and let it finish. Run the real script, then the metal script. Write the version and the completion on the Run record sheet.

Only then start a script of your own. Copy the template for the unit style you have chosen, change one thing, and run that short script to completion before making the next change. One change, one short run, one line on the record. It is not glamorous. It is how you end the hour with a script you trust instead of a script you hope about.

What should you leave alone, and what should you change first?

The guide’s advice here is short enough to memorize, and it is the advice that saves the most time:

  • Leave units at the top.
  • Leave pair_style above pair_coeff, and above read_data once you add a data file.
  • Keep the official default timestep and neighbor skin on a first run unless you already know why you are changing them.
  • Replace the teaching coefficients when you have a potential you actually mean to use.
  • Lengthen run only after a short run has finished cleanly on your machine.

That last one deserves emphasis. A short run that finishes tells you the script is coherent. A long run that finishes tells you the same thing, two days later.

Who is this for?

Practitioners writing, or about to write, a first LAMMPS input script — graduate students, engineers coming over from another simulation package, and researchers who have run other people’s scripts and are now writing their own. It is equally useful for anyone who has inherited a script whose unit style and command order nobody has checked recently. Running a script you did not write is an act of trust; the checklist turns it into an act of verification.

You install LAMMPS from official LAMMPS sources. This kit ships original input scripts, a checklist, and a guide. It does not include the LAMMPS application or official potential files, and the thermo output from the build runs stays out of the zip, because a build check is not a result.

LAMMPS is a trademark of LF Projects, LLC. This is an independent set of original input scripts, a checklist, and a guide for people who use LAMMPS. It is not an official LAMMPS or LF Projects product.

A script that means what you wrote

You are not paying for a lecture on reduced units. You are paying for the official four-part anatomy laid out as a working template, three first scripts already run to completion on the current official stable, a checklist that catches a missing units line or an early pair_coeff before you lose an afternoon to it, and a guide that tells you what to change first and what to leave alone.

Get Input Script Anatomy and Units First (for LAMMPS): Input Script Anatomy and Units First (for LAMMPS)

It will be listed on our Tools for LAMMPS page (Tools for LAMMPS) alongside the rest of the tools in that line. You can browse every Organa Obscura tool on the Products page.

Leave a Reply