name	lammps
description	Create and validate LAMMPS input scripts with physics-aware validation and educational feedback
version	2.0.0
author	Claude Code
tags	["lammps","molecular-dynamics","simulation","physics","validation"]

LAMMPS Input Script Skill

Generate and validate LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) input scripts with physics-aware validation.

Quick Start

Validate a LAMMPS Input Script

# Check syntax, physics, and protocol
python scripts/validate_syntax.py path/to/input.in
python scripts/validate_physics.py path/to/input.in
python scripts/validate_protocol.py path/to/input.in --explain

Generate a New LAMMPS Input Script

from scripts.generate_input import LAMMPSInputGenerator

generator = LAMMPSInputGenerator()
script = generator.generate(
    units="real",
    atom_style="full",
    system_type="liquid",
    temperature=300,
    pressure=1
)

Search LAMMPS Documentation

from scripts.search_docs import DocumentationSearcher

searcher = DocumentationSearcher()
info = searcher.find_command("fix nvt")

Important Constraints

DO NOT generate files in the examples/ directory. The examples/ folder contains curated reference examples that should remain unchanged. Always output generated scripts to:

The user's current working directory
A user-specified path via -o or --output flag
Or prompt the user for an output location

Command Syntax References

Generated scripts can include inline syntax documentation for each LAMMPS command:

from scripts.generate_input import LAMMPSInputGenerator

# Create generator with syntax comments enabled
generator = LAMMPSInputGenerator(include_syntax=True)

generator.add_units("lj")
generator.add_fix("1", "all", "nvt", temp="300", "300", "100")

Output format:

# Set the simulation units
# Syntax: units style
# https://docs.lammps.org/units.html
units    lj

# NVT integration with Nose/Hoover thermostat
# Syntax: fix ID group-ID nvt temp Tstart Tstop damp
# https://docs.lammps.org/fix_nvt.html
fix     1 all nvt temp 300 300 100

Updating the Syntax Database

The syntax database (scripts/commands_syntax.json) contains 250+ commands with:

Command signature (syntax pattern)
Brief one-line description
Link to official LAMMPS documentation

To update the database:

# Parse local LAMMPS HTML documentation
python scripts/lammps_docs_parser.py --local /path/to/lammps/doc/html

# Or use the built-in database (covers most common commands)
python scripts/lammps_docs_parser.py

Command-Line Generator

Generate pre-built scripts from the command line:

# Basic LJ melt script
python scripts/generate_input.py --type basic -o output.in

# NVT equilibration script
python scripts/generate_input.py --type nvt -T 300 -o nvt_eq.in

# Deformation script
python scripts/generate_input.py --type deform --strain-rate 0.001 -o deform.in

# Without syntax comments
python scripts/generate_input.py --type basic --no-syntax -o output.in

LAMMPS Input Script Structure

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

1. Initialization

units    real          # Unit system (real, metal, lj, si, cgs, electron, micro, nano)
atom_style full        # Atom attributes
boundary  p p p        # Periodic boundaries

2. System Definition

read_data    system.data      # Read atom coordinates
pair_style   lj/cut 10.0      # Force field
pair_coeff   * * 0.155 3.166  # Parameters

3. Settings

neighbor     2.0 bin          # Neighbor list
timestep     1.0              # Time step (fs for real units)
thermo_style custom step temp pe ke etotal press

4. Simulation

minimize     1.0e-4 1.0e-6 100 1000   # Energy minimization
fix    1 all nvt temp 300 300 100     # NVT equilibration
run    10000                           # Production run

Core Concepts

Unit Styles

Style	Time	Distance	Energy	Max dt
real	fs	Angstrom	kcal/mol	5.0
metal	ps	Angstrom	eV	0.010
lj	τ	σ	ε	0.02
si	s	m	J	1e-14

Atom Styles

atomic: Point atoms (no bonds)
charge: Atoms with charge
bond: Atoms with bonds
molecular: Atoms with bonds/angles
full: Molecular + bonds/angles/dihedrals/impropers + charge

Common Force Fields

lj/cut - Lennard-Jones
lj/cut/coul/long - LJ with PPPM electrostatics
eam - Embedded Atom Method (metals)
reax - ReaxFF reactive force field
charmm - CHARMM force field

Simulation Phases

1. Minimization

Required before dynamics to relax high-energy overlaps.

minimize    1.0e-4 1.0e-6 100 1000

2. Equilibration (NVT or NPT)

Bring system to target temperature/pressure.

fix    1 all nvt temp 300 300 100
run    50000    # 50 ps with dt=1.0 fs

3. Production

Collect data for analysis.

unfix  1
fix    1 all nve
run    100000   # 100 ps production

Validation Levels

Level 1: Syntax

Command existence check
Argument validation
Variable definitions

Level 2: Physics

Timestep appropriateness
Unit consistency
- units used in fix command consistent with System Unit
Thermostat/barostat settings

Level 3: Protocol

Phase sequence (minimize → equilibrate → produce)
Duration adequacy
Convergence criteria

Examples

The examples/ directory contains 354 input scripts across 20 categories:

Core Simulation Workflows

examples/basic/ - Fundamental simulations (pour, flow, deposit, indent, LJ argon)
- minimal_with_syntax.in - Example with inline syntax documentation
examples/minimization/ - Energy minimization (CG, steepest descent, NEB, structural optimization)
examples/equilibration/ - System equilibration to target T/P
examples/production/ - Production data collection runs

Deformation & Rheology

examples/shear/ - Shear flow, SLLOD equations, viscosity calculations
examples/uef/ - Unsteady Extensional Flow (uniaxial/biaxial extension)
examples/deformation/ - Mechanical tensile deformation (fix deform)

Transport Properties

examples/viscosity/ - Viscosity measurement (Green-Kubo, non-equilibrium methods)
examples/thermal/ - Thermal conductivity and heat flux
examples/diffusion/ - MSD and VACF diffusion analysis

Materials & Properties

examples/elasticity/ - Elastic constant calculations, stress-strain relations
examples/aspherical/ - Non-spherical particles (ellipsoids, Gay-Berne potential)
examples/magnetic/ - Magnetic spin systems

Advanced & Specialized

examples/packages/ - 133 examples across 59 LAMMPS packages (EFF, MEAM, FEP, Drude, CGDNA)
examples/uncategorized/ - 62 diverse examples (NEB, GCMC, AIMD, balance)
examples/coupling/ - Multi-physics coupling
examples/python/ - Python integration examples
examples/reaction/ - Chemical reaction modeling

Choosing a Deformation Method

Need to deform your system? Use this decision guide:

Need to deform your system?
│
├─ Studying flow/rheology (polymer melts, extensional flow)?
│  └─ Use UEF (examples/uef/)
│     - Volume-preserving (traceless strain rate)
│     - Requires triclinic box and periodic boundaries
│     - fix nvt/uef thermostat
│
├─ Mechanical deformation/tension?
│  ├─ Need volume control (Poisson effect)?
│  │  └─ Use fix deform + fix npt (examples/deformation/)
│  │     - Transverse directions free to contract
│  │     - Volume can change
│  │     - Tensile testing, fracture studies
│  │
│  └─ Fixed transverse dimensions?
│     └─ Use fix deform + fix nvt (examples/deformation/)
│
└─ Shear deformation?
   └─ Use SLLOD (examples/shear/)
      - fix deform with erate
      - fix nvt/sllod thermostat

Key Distinction: UEF vs Mechanical Tension

Property	UEF (Extensional Flow)	Fix Deform (Tension)
Purpose	Rheology (flow behavior)	Mechanical deformation
Volume	Preserved (traceless)	Can change (Poisson effect)
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
Boundary	Periodic required	Non-periodic OK
Primary Application	Polymer melts in flow	Tensile testing, fracture

Templates

Ready-to-use templates in templates/:

minimal_template.inp - Basic script structure
minimization_template.inp - Energy minimization
equilibration_template.inp - NVT equilibration
production_template.inp - NVE production
full_simulation_template.inp - Complete workflow

Best Practices

Always minimize before dynamics
Check timestep against unit system (real: < 2 fs, metal: < 0.005 ps)
Use appropriate thermostats (nvt for NVT, npt for NPT)
Monitor convergence during equilibration
Set neighbor skin to 2.0 Angstrom (or 0.3 × cutoff)
Check DOF conflicts when modifying existing scripts
Understand command coupling - commands work in groups

Educational Mode

Enable detailed explanations with --explain flag:

python scripts/validate_protocol.py input.in --explain

This provides pedagogical context for each validation issue.

Documentation Search

Search local LAMMPS documentation (Jun 2022) via indexed JSON:

Fast command lookup (< 0.1s)
516 commands indexed
8 categories: fix, compute, pair_style, bond_style, etc.

References

dof-validation.md - DOF conflict detection guide
best-practices.md - LAMMPS simulation best practices
troubleshooting.md - Error resolution guide

External Resources

LAMMPS Manual - Official documentation
LAMMPS Examples - Example scripts

Version

v2.0.0 - Symbolic Tolerance, Units-Aware Physics, Educational Mode

name	lammps
description	Create and validate LAMMPS input scripts with physics-aware validation and educational feedback
version	2.0.0
author	Claude Code
tags	["lammps","molecular-dynamics","simulation","physics","validation"]