lammps

name	lammps
description	Use when writing, reviewing, or debugging LAMMPS input scripts, choosing simulation methods (deformation, equilibration, transport), validating physics parameters (timestep, thermostat, units), or encountering LAMMPS runtime errors (lost atoms, DOF conflicts, fix ID not unique)

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.