lammps

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

1. Always minimize before dynamics
2. Check timestep against unit system (real: < 2 fs, metal: < 0.005 ps)
3. Use appropriate thermostats (nvt for NVT, npt for NPT)
4. Monitor convergence during equilibration
5. Set neighbor skin to 2.0 Angstrom (or 0.3 × cutoff)
6. Check DOF conflicts when modifying existing scripts
7. 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