科研 Skill

机器学习势部署至LAMMPS

mlp-to-lammps

Covers deploying trained ML interatomic potentials into LAMMPS for production MD: LAMMPS compilation with MLP plugins, pair_style/pair_coeff setup. Use when putting a trained MLP into production.

发布者 Codar安全审核通过v0.1.0更新于 2026-11-18

SKILL.md

MLP to LAMMPS Deployment

Description

This skill covers the full pipeline for deploying trained ML interatomic potentials into LAMMPS for production molecular dynamics: LAMMPS compilation with MLP plugins, pair_style and pair_coeff configuration, species-to-atom-type mapping, unit consistency verification, neighbor list tuning, GPU and MPI parallelism considerations, and validation of LAMMPS inference against the Python/ASE reference before any production run. Covers MACE, NequIP/Allegro, and DeePMD-kit deployment patterns. Invoke this skill after passing mlp-validation and before running production LAMMPS simulations with an ML potential.

Domain Context

LAMMPS is the standard platform for large-scale MLP-driven MD because it handles periodic boundary conditions, neighbor list management, ensemble integrators, and output efficiently for systems of thousands to millions of atoms. However, LAMMPS was designed around classical pair potentials; MLP pair styles are added as plugins that wrap TorchScript, TensorFlow, or custom C++ backends. This creates several non-obvious deployment hazards:

The LAMMPS/Python interface is not automatically consistent. The same model file evaluated via MACECalculator (Python/ASE) and via pair_style mace (LAMMPS C++ plugin) should produce identical forces, but will not if: the element ordering in the LAMMPS data file does not match the model's internal species list; the unit system is set incorrectly; or the plugin was compiled against a different version of the model's backend library than the Python environment uses.

LAMMPS units are explicit, not inferred. units metal uses Å, eV, ps, K, bar. A model trained in eV/Å (ASE convention) must be deployed under units metal. units real uses kcal/mol, Å, fs — correct for AMBER/CHARMM classical force fields but fatal for MLPs trained in eV. There is no automatic conversion; LAMMPS passes atom coordinates to the pair style and receives forces back, and if the units declaration does not match what the model expects, forces are silently wrong by a factor of 23.06 (eV vs kcal/mol) with no error message.

The neighbor list must be set correctly. LAMMPS manages the neighbor list; the MLP pair style reads neighbors within the model's cutoff. The skin distance (neigh_modify delay 0 every 1 check yes) must allow the pair style to see all atoms within its cutoff. An insufficient skin distance truncates the neighbor list and silently reduces accuracy; an excessively large skin distance wastes memory. For MACE, the neighbor list must include all atoms within r_max + skin; the default LAMMPS skin of 2.0 Å is usually adequate. [EXPERT REVIEW NEEDED]

Equivariant MLPs and domain decomposition. MACE and NequIP/Allegro use equivariant message passing. Their LAMMPS implementations require no_domain_decomposition (MACE) or newton off with specific MPI protocols (NequIP) because the equivariant operations require access to the full ghost-atom environment, which standard domain decomposition does not guarantee. Running these pair styles without the required flags produces silent, incorrect forces in multi-MPI runs — single-rank runs are correct, but any multi-rank run is corrupted.

Model file versioning. A MACE model file (.model or TorchScript .pt) is generated by a specific version of the MACE Python package. The LAMMPS plugin must be compiled against the same MACE version. Upgrading the Python environment without recompiling LAMMPS (or vice versa) typically produces a libtorch version mismatch error at pair_coeff time, but may silently succeed with subtly wrong behavior in some version combinations.

When to Use This Skill

  • Deploying any trained MACE, NequIP, Allegro, or DeePMD-kit model to LAMMPS for production MD at scales (> 10,000 atoms or > 1 ns) that are impractical in ASE.
  • Setting up LAMMPS for active learning exploration MD with a provisional MLP committee.
  • Verifying that a pre-compiled HPC LAMMPS installation supports the required MLP pair style at the correct version.
  • Debugging a force mismatch or energy discrepancy between LAMMPS and the Python training environment.
  • Configuring GPU-accelerated MLP MD on NVIDIA GPUs via the LAMMPS KOKKOS or ML-MACE packages.
  • Migrating a production simulation from one MLP version or architecture to another and confirming numerical equivalence.

When Not to Use This Skill

  • For system sizes < 1,000 atoms and run times < 1 ns — ASE's MACECalculator is simpler, requires no C++ compilation, and avoids the deployment hazards described above. Use LAMMPS only when scale demands it.
  • Before passing mlp-validation — deploying an unvalidated model to LAMMPS adds a layer of complexity that obscures whether failures originate from the MLP itself or from the LAMMPS deployment. Always validate the model in ASE first.
  • For universal potentials that provide their own LAMMPS interface — MACE-MP-0, CHGNet, and M3GNet have maintained LAMMPS interfaces; use the upstream documentation rather than this skill for those specific models.
  • For LAMMPS workflows that do not require an MLP — this skill is specific to MLP pair styles. Standard classical pair style deployment is covered in lammps-workflow.

Core Concepts

  • LAMMPS units metal: units metal declares Å for distance, eV for energy, ps for time, K for temperature, bar for pressure. This is the correct unit system for any MLP trained on ASE extxyz data (which stores energy in eV and distances in Å). Forces are in eV/Å. Never use units real or units lj with a physics-trained MLP.
  • pair_style and pair_coeff: pair_style mace no_domain_decomposition declares the interaction model; pair_coeff * * model.pt El1 El2 ... specifies the model file and the element assigned to each LAMMPS atom type. The element list in pair_coeff must match the model's internal species list in the correct order. LAMMPS atom types are integers (1, 2, 3, ...); the mapping * * model El1 El2 means type 1 → El1, type 2 → El2, etc.
  • no_domain_decomposition (MACE): Required flag for pair_style mace. With standard domain decomposition, each MPI rank handles a spatial subdomain and only knows about its local atoms and a layer of ghost atoms. MACE's equivariant message passing requires the full 2-hop neighborhood of each atom, which may extend beyond one ghost layer in large parallel runs. no_domain_decomposition disables spatial decomposition entirely and replicates the full atom list across all ranks — correct but limits parallel scaling. See Parallel Execution section.
  • newton off (NequIP/Allegro): NequIP and Allegro LAMMPS pair styles require newton off (disabled Newton's third law), because their internal force summation scheme already handles action-reaction pairs explicitly. Using newton on with NequIP double-counts force contributions in parallel runs.
  • TorchScript model format: MACE and NequIP export models as TorchScript .pt files, which encode the model architecture and weights into a single portable binary that PyTorch's C++ frontend (libtorch) can load without the Python package. The LAMMPS plugin links against libtorch; the .pt file must have been generated by a compatible PyTorch version.
  • DeePMD frozen graph: DeePMD-kit exports a TensorFlow frozen graph (.pb) or a new-format compressed model (.pth for DP2.x). The LAMMPS plugin links against TensorFlow C++ and requires the same TF version at runtime.
  • Neighbor list skin distance: LAMMPS builds neighbor lists every N_neighbor steps with a skin extending skin Å beyond each pair style's declared cutoff. For MACE with r_max=5.5 Å, the pair style declares cutoff 5.5 Å; the neighbor list includes atoms within 5.5 + skin Å. Default LAMMPS skin is 2.0 Å. Increasing skin reduces rebuilds but increases memory. The cutoff declared in pair_coeff must match the model's r_max exactly.
  • Ghost atom communication (comm_modify cutoff): In multi-rank runs, LAMMPS must communicate ghost atom data far enough to build the correct neighbor list. For MACE with no_domain_decomposition, domain decomposition is disabled so this is not needed. For other pair styles where domain decomposition is active, comm_modify cutoff must be ≥ r_max + skin to ensure all required neighbors are available to each rank.
  • Model file checksum: Every LAMMPS run script should record the model file path and its SHA-256 hash. Models are large binary files; a corrupted or accidentally overwritten model file can produce subtly wrong results without any error.

Key Workflows

Full steps for each part are in references/key-workflows/; open the one you need:

Common Failure Modes

FailureSymptomLikely CauseDiagnosticFix
Wrong species mappingForces wrong by large, structure-specific amounts (> 1 eV/Å at equilibrium); energy per atom is wrong by > 0.5 eV but system does not immediately crashElement list in pair_coeff does not match atom type order in the LAMMPS data file; type 1 = W in pair_coeff but type 1 = Ta in data fileRun validate_lammps_forces (Workflow 3); forces will disagree with ASE by >> 1 meV/Å for the wrong-mapped typesRe-generate the LAMMPS data file with ase write ... specorder=[...] matching the pair_coeff element list exactly; verify with python -c "print(atoms.get_chemical_symbols()[:5])" after read_data
Wrong LAMMPS unitsForces uniformly off by a constant factor (×23.06 for real→metal or ×0.043 for metal→real); energy offset but force direction correct; LAMMPS runs but thermostat behaves incorrectlyunits real or units lj declared instead of units metal for an eV/Å-trained MLPCheck: at equilibrium, pair_style mace forces should be ≈ 0 meV/Å; if they are 23 eV/Å for a near-equilibrium bulk structure, units are real (kcal/mol factor)Change units metal in input script; regenerate LAMMPS data file (ASE write lammps-data defaults to metal units)
Incompatible LAMMPS pluginERROR: Unknown pair style: mace or Segmentation fault (core dumped) at pair_coeff; or libtorch version mismatchLAMMPS binary does not have the ML-MACE package compiled in, or was compiled against a different libtorch version than the current Python environmentRun `lmp -helpgrep ML-MACE; run ldd $(which lmp)
Missing model dependenciesRuntimeError: PytorchStreamReader failed at pair_coeff; or model loads but produces NaN forces; for DeePMD: TF_LoadLibrary failedTorchScript model file is corrupt, was generated by a different MACE version, or has broken relative paths to auxiliary filesVerify model loads in Python: torch.load("model.pt"); check file model.pt output — should be zip archive; for DeePMD, test with dp test before LAMMPSRegenerate model file with nequip-deploy build or export from current MACE training code; ensure model version matches LAMMPS plugin version
Incorrect neighbor list — cutoff truncationForces slightly wrong (2–10 meV/Å at equilibrium) but no crash; errors larger for atoms near dense neighborhoods; parallel and serial runs agreepair_coeff cutoff declared smaller than model r_max; or comm_modify cutoff insufficient for NequIP/Allegro in parallelRun validate_lammps_forces with 1 MPI rank and compare to ASE; if single-rank passes but multi-rank fails, comm_modify cutoff is too smallSet neighbor skin to 2.0 Å and comm_modify cutoff r_cut + 2.0 for NequIP; never override the cutoff in pair_style to a value smaller than the model's r_max
Parallel-domain artifacts — no_domain_decomposition missingLAMMPS runs with multiple MPI ranks; forces differ from ASE by 5–100 meV/Å; energy fluctuates with number of MPI ranks; increasing MPI ranks makes errors worsepair_style mace used without no_domain_decomposition flag in a multi-rank run; each rank only has local ghost atoms and misses neighbors from non-adjacent ranksCompare forces from 1-rank and 4-rank runs; if they differ by > 1 meV/Å, domain decomposition is corrupting the equivariant message passingAdd no_domain_decomposition to the pair_style mace declaration; for NequIP use newton off and comm_modify cutoff; for DeePMD standard domain decomposition is correct
Unstable MD despite low static errorSingle-point force validation passes (< 1 meV/Å vs ASE); short NVE run stable; but production NPT at 1500 K diverges after 100 psModel tested at configurations near training distribution; production MD at high temperature samples structures outside the training set; MLP extrapolates into unphysical regionsRun NVE at the target temperature for 50 ps; monitor max force; extract frames with max force > 20 eV/Å and compare to training distribution via SOAP distanceResume active learning at the target temperature (see active-learning-mlp); add high-temperature AIMD snapshots to the training set
Silent force mismatch — float32 vs float64Forces appear to agree at float32 precision but disagree at float64; energy drift in long NVE runs; subtle NPT density error (< 1%)LAMMPS plugin uses float32 internally; ASE validation used float64; 0.1–1 meV/Å systematic difference hidden by float32 precisionRun validation with default_dtype="float32" in ASE to match LAMMPS precision; compare both float32 and float64 ASE results to LAMMPSFor production: use float64 throughout (slower but correct); or accept float32 and verify that the induced force error is below the physical tolerance required for the target property

Best Practices

  • Run validate_lammps_forces on every new deployment before any production simulation. This is a 5-minute check that catches species mapping errors, unit errors, and plugin version mismatches. Record the model SHA-256 and the max force difference in the project log.
  • Always set units metal for MLPs trained on ASE extxyz data. There is no automatic unit detection in LAMMPS. A wrong units declaration produces silently wrong forces with no error message.
  • Pin the species order at data file creation time using ase write ... specorder=element_order and record the order in the project README. Any script that writes a new data file must use the same specorder as the original.
  • Always include no_domain_decomposition for MACE pair_style in every input script, even for single-rank runs. The flag is harmless on a single rank and prevents a critical error if the script is later run with multiple ranks.
  • Set newton off for NequIP and Allegro and verify comm_modify cutoff ≥ r_cut + skin. Failing to set newton off is silent on a single rank but produces wrong forces with multiple MPI ranks.
  • Validate on the production hardware, not just the development workstation. CUDA version, libtorch version, and MKL library configurations differ between workstations and HPC nodes. A deployment that passes locally may fail or produce wrong forces on the cluster due to library version mismatches.
  • Set neigh_modify check yes rather than fixed-interval rebuilds. It avoids both stale neighbor lists (which truncate cutoffs and corrupt forces) and unnecessary rebuilds (which waste compute). Monitor the rebuild frequency via the cpu thermo column.
  • Log the model file path and SHA-256 in every LAMMPS log file. LAMMPS does not automatically record which model file was used in a run. Add a print "Model SHA-256: $(sha256sum /path/to/model.pt | cut -d' ' -f1)" to the submission script before lmp -in ....
  • Test the deployment at the target temperature and pressure with a short (10 ps) equilibration run before committing to production. A model that passes static validation at 300 K may fail at 2000 K or 10 GPa if those conditions were not covered in training.

Integration with Other Skills

  • mace-training: The MACE model file exported from training (the _stagetwo.model checkpoint) is the primary input to this skill. The architecture choices (r_max, element list, hidden_irreps) made during training determine the pair_coeff cutoff and element mapping required here.
  • active-learning-mlp: Exploration MD in the active learning loop uses LAMMPS with a provisional MACE committee. This skill's deployment verification (Workflow 3) should be applied to each committee member before starting exploration runs; a wrong deployment here silently corrupts the uncertainty estimates.
  • mlp-validation: This skill's Workflow 3 (ASE vs. LAMMPS force comparison) is the final gate before the production deployment that mlp-validation evaluated in ASE. All validation performed in mlp-validation is post-training but pre-LAMMPS; this skill adds the LAMMPS-specific layer.
  • lammps-workflow: LAMMPS input script structure, thermostat/barostat settings, thermo output configuration, and restart mechanics from that skill apply directly to MLP-driven runs. This skill focuses on the pair style layer; the simulation setup layer is covered there.
  • md-equilibration: After passing Workflow 3 (force validation) and Workflow 6 (NVE stability), the equilibration protocol from that skill is applied using the LAMMPS MLP pair style. The flying-ice-cube check and multi-stage equilibration sequence are especially important for MLP MD because undetected equilibration artifacts can bias the configurations that trigger active learning.
  • dft-dataset-generation: When LAMMPS deployment reveals that the MLP fails at a new temperature or pressure regime, the remedy is always to generate more DFT data at those conditions and retrain. That skill covers how to design the supplementary DFT calculations.
  • dft-convergence: The model's DFT training settings must be identical to those used for any new DFT reference calculations generated to expand the training set. When a LAMMPS run fails due to model extrapolation, the new DFT oracle calculations must use the frozen settings from the original training campaign.
  • uncertainty-mlp: Running a committee of MACE models in LAMMPS for active learning exploration requires deploying N separate LAMMPS instances or using a custom uncertainty-aware pair style. That skill covers when and how to integrate uncertainty quantification into production LAMMPS runs beyond the simple committee approach shown in active-learning-mlp.
  • universal-potentials: MACE-MP-0, CHGNet, and M3GNet each have their own LAMMPS interfaces and model file formats. This skill's principles (species mapping, unit verification, force validation) apply to those deployments too, but the specific pair_style syntax and compilation instructions differ. Consult that skill for universal-potential-specific deployment details.

Key References

  1. Thompson, A. P., et al. (2022). LAMMPS — A flexible simulation tool for particle-based materials modeling. Computer Physics Communications, 271, 108171. https://doi.org/10.1016/j.cpc.2021.108171
  2. Batatia, I., et al. (2022). MACE: Higher order equivariant message passing neural networks for fast and accurate force fields. Advances in Neural Information Processing Systems, 35. https://arxiv.org/abs/2206.07697
  3. Batzner, S., et al. (2022). E(3)-equivariant graph neural networks for data-efficient and accurate interatomic potentials. Nature Communications, 13, 2453. https://doi.org/10.1038/s41467-022-29939-5
  4. Zeng, J., et al. (2023). DeePMD-kit v2: A software package for deep potential models. Journal of Chemical Physics, 159, 054801. https://doi.org/10.1063/5.0155600
  5. Musaelian, A., et al. (2023). Learning local equivariant representations for large-scale atomistic dynamics. Nature Communications, 14, 579. https://doi.org/10.1038/s41467-023-36329-y

示例提示词

帮我把训练好的机器学习势接入LAMMPS配置pair_style并验证单位一致性。

所属插件

计算材料学:第一性原理与原子模拟面向计算材料研究:DFT 与第一性原理(VASP、Quantum ESPRESSO、CP2K、AiiDA)、缺陷/表面/声子/弹性常数、机器学习势函数训练与验证、分子动力学与增强采样、晶体性质图神经网络与生成模型。

安装该插件会一并获得同领域的 35 个 Skill / MCP。

同插件的其他科研 Skill

常见问题

机器学习势部署至LAMMPS能做什么?

Covers deploying trained ML interatomic potentials into LAMMPS for production MD: LAMMPS compilation with MLP plugins, pair_style/pair_coeff setup. Use when putting a trained MLP into production。

如何安装机器学习势部署至LAMMPS?

在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「机器学习势部署至LAMMPS」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。

机器学习势部署至LAMMPS需要哪些权限?

该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。

机器学习势部署至LAMMPS经过官方审核吗?

是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。