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

bash

# 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

python

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

python

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:

python

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:

lammps

# 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:

bash

# 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:

bash

# 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

code

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

code

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

3. Settings

code

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

code

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.

code

minimize    1.0e-4 1.0e-6 100 1000

2. Equilibration (NVT or NPT)

Bring system to target temperature/pressure.

code

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

3. Production

Collect data for analysis.

code

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:

code

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:

bash

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