lammps-deepmd

name	lammps-deepmd
description	A tool and knowledge base for running molecular dynamics (MD) simulations in LAMMPS with the DeePMD-kit plugin. It handles input script preparation, ensemble selection (NVE/NVT/NPT), and job execution via `uv` or offline binaries. USE WHEN you need to set up, write, explain, or execute a LAMMPS molecular dynamics simulation using a DeePMD machine learning potential (e.g., `graph.pb`).
compatibility	Requires LAMMPS with DeePMD-kit support. Online mode prefers `uvx --from lammps --with deepmd-kit[gpu,torch,lmp] lmp`; offline mode requires a user-provided LAMMPS executable or module.
license	LGPL-3.0-or-later
metadata	{"author":"OpenClaw","version":"1.0","repository":"https://github.com/deepmodeling/deepmd-kit","lammps_docs":"https://docs.lammps.org/"}

LAMMPS + DeePMD-kit

Use this skill when the user wants to run molecular dynamics in LAMMPS with a DeePMD-kit potential, prepare or explain an input.lammps file, or switch between common ensembles such as NVE, NVT, and NPT.

Agent responsibilities

1. Confirm the available execution mode:
   • Online mode: if internet access is available and uv is installed, prefer uvx --from lammps --with deepmd-kit[gpu,torch,lmp] lmp ...
   • Offline mode: do not guess the executable. Ask the user which LAMMPS command, module, or container should be used.
2. Confirm the minimum simulation inputs:
   • structure/data file (for example data.system)
   • DeePMD model file (for example graph.pb or compressed model)
   • atom type to element mapping, including required per-type masses if the data file does not define them
   • target ensemble (NVE, NVT, NPT, or another explicitly requested setup)
   • temperature, pressure if applicable, timestep, and total number of steps
3. Write the LAMMPS input script yourself instead of asking the user to hand-write it.
4. Keep the example readable and fully explained. If you include an example input script, explain what every command does.
5. When possible, validate command availability against the LAMMPS docs or local lmp -h output before execution.
6. Report clearly which command was run, which files were used, and where outputs were written.

Decide the execution mode

Online mode (preferred when internet access is available)

Use:

uvx --from lammps --with deepmd-kit[gpu,torch,lmp] lmp -in input.lammps

If you need to inspect the local command-line help:

uvx --from lammps --with deepmd-kit[gpu,torch,lmp] lmp -h | tee /dev/tty

Notes:

• This is the preferred path because it can provision LAMMPS and DeePMD-kit on demand.
• The gpu,torch,lmp extras match the requested runtime pattern from the user.
• If the environment is slow or the packages are large, warn the user that the first run may take time.

Offline mode

If internet access is unavailable or the user explicitly wants a site-installed binary, ask a concrete question such as:

• "Which LAMMPS executable should I use, for example lmp, lmp_mpi, mpirun -np 8 lmp, or an HPC module command?"
• "Do you already have a DeePMD-enabled LAMMPS build on this machine or cluster?"

Do not invent a binary name or module name.

Minimal information to collect

Ask only for what is missing:

• DeePMD model path
• LAMMPS data file path
• ensemble
• target temperature
• target pressure if using NPT
• timestep
• run length in steps
• whether velocities should be generated from scratch
• preferred execution command if offline

Recommended workflow

1. Inspect available files in the working directory.
2. Draft input.lammps.
3. Explain the script to the user if they asked for an explanation or if the script is nontrivial.
4. Run a short smoke test first when reasonable.
5. Run the full simulation.
6. Summarize outputs such as log.lammps, dump trajectories, restart files, and thermodynamic data.

Example: annotated NVT input

The following example is adapted from the user-provided tutorial pattern and slightly generalized. See also assets/input.nvt.lammps.

variable        NSTEPS          equal 1000000
variable        THERMO_FREQ     equal 1000
variable        DUMP_FREQ       equal 1000
variable        TEMP            equal 300.0
variable        TAU_T           equal 0.1

units           metal
boundary        p p p
atom_style      atomic

neighbor        1.0 bin

read_data       data.system
mass            1 28.0855
mass            2 15.999
pair_style      deepmd graph_compressed.pb
pair_coeff      * *

thermo_style    custom step temp pe ke etotal press vol lx ly lz xy xz yz
thermo          ${THERMO_FREQ}
dump            1 all custom ${DUMP_FREQ} traj.lammpstrj id type x y z

velocity        all create ${TEMP} 743574
fix             1 all nvt temp ${TEMP} ${TEMP} ${TAU_T}

timestep        0.0005
run             ${NSTEPS}

What every command means

• variable NSTEPS equal 1000000

  • Defines a numeric variable called NSTEPS with value 1000000.
  • Used later by run ${NSTEPS} so the run length is easy to modify in one place.

• variable THERMO_FREQ equal 1000

  • Defines how often LAMMPS prints thermodynamic information.
  • Used by thermo ${THERMO_FREQ}.

• variable DUMP_FREQ equal 1000

  • Defines how often coordinates are written to the trajectory dump.

• variable TEMP equal 300.0

  • Sets the target temperature in the current unit system.
  • Because units metal is used below, this temperature is interpreted in kelvin.

• variable TAU_T equal 0.1

  • Sets the thermostat damping parameter used by the NVT fix.
  • In metal units this is in picoseconds.

• units metal

  • Selects the LAMMPS metal unit system.
  • This determines the physical meaning of timestep, temperature, pressure, energy, distance, and time.
  • In this unit system, distances are in angstrom, time is in picoseconds, and the timestep should be chosen accordingly.

• boundary p p p

  • Applies periodic boundary conditions in x, y, and z.
  • Suitable for bulk condensed-phase simulations.

• atom_style atomic

  • Uses the atomic atom style, appropriate when atoms have no explicit bonds, angles, or molecular topology in the force field description.
  • Common for DeePMD simulations of condensed phases when the structure is provided as atoms in a box.

• neighbor 1.0 bin

  • Sets the neighbor-list skin distance to 1.0 in the current distance unit.
  • Uses the bin neighbor-building method.
  • Neighbor lists help LAMMPS efficiently find nearby atoms for force evaluation.

• read_data data.system

Common ensemble modifications

NVE

Replace the NVT thermostat line with:

fix 1 all nve

Meaning:

• integrates Newton's equations in the microcanonical ensemble
• no thermostat or barostat is applied
• useful for short stability checks or production runs after equilibration

NPT

A typical isotropic NPT alternative is:

variable        PRESS           equal 1.0
variable        TAU_P           equal 1.0
fix             1 all npt temp ${TEMP} ${TEMP} ${TAU_T} iso ${PRESS} ${PRESS} ${TAU_P}

Meaning:

• PRESS is the target pressure
• TAU_P is the barostat damping constant
• iso applies isotropic pressure control to the simulation box
• this simultaneously thermostats and barostats the system

When using NPT, it is often useful to keep vol, lx, ly, and lz in the thermo output.

Execution templates

Online run

uvx --from lammps --with deepmd-kit[gpu,torch,lmp] lmp -in input.lammps

Online help

uvx --from lammps --with deepmd-kit[gpu,torch,lmp] lmp -h | tee /dev/tty

Offline run

Only after the user specifies the executable, use a command such as one of these exact patterns:

lmp -in input.lammps
mpirun -np 8 lmp_mpi -in input.lammps
srun lmp -in input.lammps

The agent must not choose one of these on its own without user guidance in offline mode.

Output checklist

After a run, report at least:

• executed command
• input script path
• data file path
• model path
• main log path
• trajectory path if any
• whether the run completed successfully
• any obvious warnings or errors from the log

References

• LAMMPS command categories: https://docs.lammps.org/Commands_category.html
• LAMMPS command index: https://docs.lammps.org/Commands_all.html
• DeePMD-kit: https://github.com/deepmodeling/deepmd-kit
• User-provided tutorial reference: https://github.com/tongzhugroup/Chapter13-tutorial/blob/master/input.lammps
• Detailed notes: references/commands-and-workflow.md