--- 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 execution with a verified DeePMD-enabled runtime. USE WHEN you need to set up, write, explain, or execute a LAMMPS molecular dynamics simulation using a DeePMD machine learning potential (for example `.pb`, `.pth`, or DPA4/SeZM `.pt2`). compatibility: Requires a user-provided, containerized, or source-built LAMMPS runtime with DeePMD-kit support. Verify capabilities in the target environment. license: LGPL-3.0-or-later metadata: author: OpenClaw version: '1.1' 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 runtime: - For a build from the current checkout, record the resolved Git commit SHA. - For an installed binary, module, or container, record the exact command and runtime versions. - Do not infer capabilities from a future release or an artifact suffix. 1. Confirm the minimum simulation inputs: - structure/data file (for example `data.system`) - DeePMD model artifact; read `references/model-deployment.md` for a training checkpoint, DPA4/SeZM, or an unclear export path - 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 1. Write the LAMMPS input script yourself instead of asking the user to hand-write it. 1. Keep the example readable and fully explained. If you include an example input script, explain what **every command** does. 1. When possible, validate command availability against the LAMMPS docs or local `lmp -h` output before execution. 1. Report clearly which command was run, which files were used, and where outputs were written. ## Verify the execution runtime Use an existing site-installed binary, container, or build from the current checkout. Before execution: - record `git rev-parse HEAD` for a source checkout, or record `dp --version` and the exact installed package/container identity; - inspect the selected LAMMPS command with `-h` and confirm that it provides the required DeePMD pair style and model-artifact route; - follow `references/model-deployment.md` for DPA4 `.pt2` and multi-rank capability gates; - do not install or upgrade packages silently, and do not claim support from an unreleased version number. If no verified runtime is available, 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 or container on this machine or cluster?" Do not invent a binary, module, container, or package version. ## 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 - execution command, module, container, or source checkout ## Recommended workflow 1. Inspect available files in the working directory. 1. Read `references/model-deployment.md` when the model needs export, its artifact type is unclear, or explicit element mapping is required. 1. Draft `input.lammps`. 1. Explain the script to the user if they asked for an explanation or if the script is nontrivial. 1. Follow the staged canary in `references/commands-and-workflow.md` before production. 1. Run the full simulation. 1. 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`. ```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 atom_modify map yes read_data data.system mass 1 28.0855 mass 2 15.999 pair_style deepmd graph_compressed.pb pair_coeff * * Si O 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 element x y z dump_modify 1 element Si O sort id 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. - `atom_modify map yes` - Creates an atom-ID map required by the documented DPA4 route. - It must appear before `read_data`. - `read_data data.system` - Reads the initial atomic structure, atom types, simulation box, and related information from the LAMMPS data file `data.system`. - The data file's first line is a skipped title; actual header counts begin after it. - Replace this filename with the actual user file. - `mass 1 28.0855`, `mass 2 15.999` - Defines per-type atomic masses when the data file does not contain a `Masses` section. - These example values correspond to a two-type Si/O mapping; adjust them to the actual atom type to element mapping. LAMMPS velocity creation and thermostats require masses; without them, runs can fail with `Not all per-type masses are set`. - `pair_style deepmd graph_compressed.pb` - Selects the DeePMD pair style. - Loads the DeePMD model from `graph_compressed.pb`. - Replace the model filename with the actual model path, for example `graph.pb`, `graph-compress.pb`, or another supported exported model. - `pair_coeff * * Si O` - Activates the pair style for all local atom types. - Maps LAMMPS type 1 to `Si` and type 2 to `O`, matching the masses and dump labels. - Inspect the actual model type map and replace this example order; do not infer it from integer type IDs. - `thermo_style custom step temp pe ke etotal press vol lx ly lz xy xz yz` - Chooses exactly which thermodynamic quantities to print. - `step`: timestep index. - `temp`: instantaneous temperature. - `pe`: potential energy. - `ke`: kinetic energy. - `etotal`: total energy. - `press`: pressure. - `vol`: box volume. - `lx ly lz`: box lengths. - `xy xz yz`: triclinic tilt factors, which are harmless to print even for an orthogonal box. - `thermo ${THERMO_FREQ}` - Prints the thermo block every `THERMO_FREQ` timesteps. - `dump 1 all custom ${DUMP_FREQ} traj.lammpstrj id type element x y z` - Creates dump ID `1` and writes every `DUMP_FREQ` steps. - Saves `id`, local type, mapped element, and coordinates to `traj.lammpstrj`. - `dump_modify 1 element Si O sort id` - Uses the same local type-to-element order as `pair_coeff`. - Sorts each frame by stable atom ID, not by element or model type-map position. - `velocity all create ${TEMP} 743574` - Assigns random initial velocities to all atoms. - The target temperature is `TEMP`. - `743574` is the random seed. - Use this when starting a fresh MD trajectory. If restarting from a previous equilibrated state, this command may be unnecessary. - `fix 1 all nvt temp ${TEMP} ${TEMP} ${TAU_T}` - Creates fix ID `1` on group `all`. - Applies the Nose-Hoover NVT thermostat. - The target temperature is ramped from `${TEMP}` to `${TEMP}`, meaning constant temperature here. - `${TAU_T}` is the thermostat damping constant. - `timestep 0.0005` - Sets the MD timestep. - In `metal` units, `0.0005` means `0.0005 ps = 0.5 fs`. - The safe choice depends on the system and model quality. - `run ${NSTEPS}` - Runs molecular dynamics for `NSTEPS` timesteps. ## Common ensemble modifications ### NVE Replace the NVT thermostat line with: ```lammps 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: ```lammps 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 ### Verified run Only after the runtime is identified, use the matching command, for example: ```bash lmp -in input.lammps mpirun -np 8 lmp_mpi -in input.lammps srun lmp -in input.lammps ``` Do not choose one of these without evidence that it is the verified runtime. ## 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` - Model artifact, export, and type-mapping notes: `references/model-deployment.md`