lammps

LAMMPS Input Script Skill

Reference for generating and validating LAMMPS input scripts with physics-aware checks.

Quick Start

Validate an Input Script

# Syntax check (command existence, argument validation)
python scripts/validate_syntax.py path/to/input.in

# Physics check (timestep, units, thermostat/barostat settings)
python scripts/validate_physics.py path/to/input.in
python scripts/validate_physics.py path/to/input.in --explain   # with educational context

# Comprehensive validation (syntax + physics + feature profiles)
python scripts/universal_validator.py path/to/input.in --json

All script paths are relative to the skill directory (.claude/skills/lammps/). Run commands from that directory, or use full paths from the repo root (e.g., python .claude/skills/lammps/scripts/validate_physics.py input.in).

Generate an Input Script (CLI)

python scripts/generate_input.py --type basic -o output.in
python scripts/generate_input.py --type nvt -T 300 -o nvt_eq.in
python scripts/generate_input.py --type deform --strain-rate 0.001 -o deform.in
python scripts/generate_input.py --type basic --no-syntax -o output.in

Generate an Input Script (Python API)

The generator uses a builder pattern — add commands one at a time, then export:

The Python import requires scripts/ to be on the path. Run from the skill directory, or add it to sys.path:

import sys; sys.path.insert(0, "/path/to/.claude/skills/lammps")
from scripts.generate_input import LAMMPSInputGenerator

gen = LAMMPSInputGenerator(include_syntax=True)
gen.add_units("real")
gen.add_command("atom_style", ["full"])
gen.add_boundary("p", "p", "p")
gen.add_command("read_data", ["polymer.data"])
gen.add_fix("1", "all", "nvt", "temp", "300", "300", "100")
gen.save_script("output.in")

Important Constraints

DO NOT generate files in the examples/ directory. Always output to the user's working directory or a user-specified path.

---

Input Script Structure

A well-structured LAMMPS input script follows this 4-section pattern:

1. Initialization

units    real          # real, metal, lj, si, cgs, electron, micro, nano
atom_style full        # atomic, charge, bond, molecular, full
boundary  p p p        # p=periodic, f=fixed, s=shrink-wrap

2. System Definition

read_data    system.data
pair_style   lj/cut 10.0
pair_coeff   * * 0.155 3.166

3. Settings

neighbor     2.0 bin
timestep     1.0              # fs for real units
thermo_style custom step temp pe ke etotal press

4. Simulation

minimize     1.0e-4 1.0e-6 100 1000
fix    1 all nvt temp 300 300 100
run    10000

---

Unit Styles Quick Reference

Values from scripts/constants.py — the source of truth for validation.

Style	Time	Distance	Energy	dt_max
real	fs	Angstrom	kcal/mol	2.0 fs
metal	ps	Angstrom	eV	0.005 ps
lj	τ	σ	ε	0.005 τ
si	s	m	J	1e-14 s
cgs	fs	Angstrom	erg	2.0 fs
electron	fs	Angstrom	Hartree	0.5 fs

---

Simulation Workflow

0. Structure Generation

Generate initial structure with AutoPoly or other tools. Consult the autopoly skill for polymer structure generation from Complement SMILES.

1. Minimization — required before dynamics

minimize    1.0e-4 1.0e-6 100 1000

2. Equilibration

Multi-stage: NVT first (temperature only), then NPT (add pressure control) if volume/density matters.

# Stage 1: NVT — stabilize temperature
fix    1 all nvt temp 300 300 100
run    50000

# Stage 2: NPT — stabilize pressure and density (if needed)
unfix  1
fix    1 all npt temp 300 300 100 iso 0 0 1000
run    50000

Thermostat selection (summary — consult references/best-practices.md §Temperature Coupling for full guidance):

Thermostat	Use for	Notes
NHC (nvt/npt)	Production runs	Correct canonical ensemble
Langevin	CG models, implicit solvent	Add fix nve; damps dynamics
Berendsen	Initial equil only	Wrong ensemble — never for production

Default damping (real units):

• Tdamp: 100 fs (range 10–500)
• Pdamp: 1000 fs (range 500–5000)

Verify convergence before production — temperature, volume, and energy must stabilize (std < 1% of mean over a window). Consult references/best-practices.md §Convergence Checking for methodology.

3. Production

Choose ensemble based on what you're measuring:

• NVT: most simulations (R_g, structure, dynamics under thermostat)
• NPT: when volume/density matters (equation of state, thermal expansion)
• NVE: transport properties (diffusion, viscosity, thermal conductivity) — avoids thermostat interference

# NVT production (default for most simulations)
unfix  1
fix    1 all nvt temp 300 300 100
run    100000

Minimum run lengths — consult references/best-practices.md §Production Run Length for property-specific guidance. Rule of thumb: production ≥ 10× equilibration time.

---

Choosing a Deformation Method

digraph deformation {
    rankdir=TB;
    node [shape=diamond];

    start [label="What type of\ndeformation?" shape=ellipse];
    flow [label="Studying flow/\nrheology?"];
    mech [label="Mechanical\ntension?"];
    vol [label="Need volume\ncontrol (Poisson)?"];

    node [shape=box];
    uef [label="UEF\n(examples/uef/)\nfix nvt/uef\ntriclinic box required\nvolume-preserving"];
    deform_npt [label="fix deform + fix npt\n(examples/deformation/)\ntransverse dirs free\nvolume can change"];
    deform_nvt [label="fix deform + fix nvt\n(examples/deformation/)\nfixed transverse dims"];
    sllod [label="SLLOD\n(examples/shear/)\nfix deform + erate\nfix nvt/sllod"];

    start -> flow [label="yes"];
    flow -> uef [label="extensional"];
    start -> mech [label="tension"];
    mech -> vol;
    vol -> deform_npt [label="yes"];
    vol -> deform_nvt [label="no"];
    start -> sllod [label="shear"];
}

UEF vs Mechanical Tension

Property	UEF (Extensional Flow)	Fix Deform (Tension)
Purpose	Rheology (flow behavior)	Mechanical deformation
Volume	Preserved (traceless)	Can change (Poisson)
Strain Rate	ε_xx + ε_yy + ε_zz = 0	No traceless requirement
Box Type	Must be triclinic	Can be orthogonal
Thermostat	fix nvt/uef	fix nvt/npt + fix deform
Primary Use	Polymer melts in flow	Tensile testing, fracture

---

Validation

Two working validators

Tool	Checks	Usage
validate_syntax.py	Command existence, argument counts, variable defs	python scripts/validate_syntax.py input.in
validate_physics.py	Timestep vs dt_max, unit consistency, thermostat/barostat ranges, missing minimization	python scripts/validate_physics.py input.in --explain
universal_validator.py	Combined syntax + physics + feature profiles (shear, thermal, UEF)	python scripts/universal_validator.py input.in --json

Known limitations

• Minimal DOF conflict detection: catches multiple thermostats/barostats on same group, but does not do per-axis tracking (e.g., two fixes controlling the same axis independently)
• neighbor_skin_min thresholds flag values below half the typical skin (e.g., < 1.0 Å for real units). Values between the minimum and typical may still be suboptimal.

Feature Profiles

Specialized validation for specific simulation types in scripts/profiles/:

• shear — SLLOD equations, momentum correction
• thermal — thermal conductivity, heat flux checks
• uef — traceless strain rate, triclinic box requirements

See scripts/profiles/README.md for creating custom profiles.

For runtime errors (lost atoms, system explosions, fix ID conflicts), consult references/troubleshooting.md.

---

Examples

The examples/ directory contains 262 input scripts across categories:

Core Workflows: basic/ (11), minimization/ (10), equilibration/ (1), production/ (3)

Deformation & Rheology: shear/ (5), uef/ (3), deformation/ (2)

Transport: viscosity/ (6), thermal/ (4), diffusion/ (2)

Materials: elasticity/ (5), aspherical/ (8), magnetic/ (3)

Advanced: packages/ (133 across 59 LAMMPS packages), uncategorized/ (62), coupling/ (2), python/ (1), reaction/ (1)

---

Command Syntax Database

scripts/commands_syntax.json — 250+ commands with syntax patterns, descriptions, and doc links. scripts/commands_index.json — 516 commands indexed across 8 categories for fast lookup.

Update with: python scripts/lammps_docs_parser.py --local /path/to/lammps/doc/html

---

Best Practices

1. Always minimize before dynamics
2. Check timestep against unit system (see dt_max table above)
3. Never combine nvt + npt on the same atoms (DOF conflict)
4. Monitor convergence during equilibration before production
5. Set neighbor skin to 2.0 Å (real/metal) or 0.3σ (LJ)
6. Check DOF conflicts when modifying existing scripts — see references/dof-validation.md

For parameter selection (strain rates, damping, temperature), convergence methodology, and common pitfalls, consult references/best-practices.md.

---

References

• best-practices.md — Parameter selection, convergence, common pitfalls
• dof-validation.md — DOF conflict detection algorithm and patterns. Note: references src/dof_validator.py which is not yet implemented; use the concepts for manual review.
• troubleshooting.md — Runtime error patterns (Lost atoms, Fix ID not unique, system explosions). Note: code examples reference generate_mechanism.py and mechanisms/ which are not implemented; the error descriptions and LAMMPS-level fixes remain accurate.