科研 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.
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
KOKKOSor 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
MACECalculatoris 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 metaldeclares Å 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 useunits realorunits ljwith a physics-trained MLP. - pair_style and pair_coeff:
pair_style mace no_domain_decompositiondeclares 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 inpair_coeffmust match the model's internal species list in the correct order. LAMMPS atom types are integers (1, 2, 3, ...); the mapping* * model El1 El2means 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_decompositiondisables 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. Usingnewton onwith NequIP double-counts force contributions in parallel runs. - TorchScript model format: MACE and NequIP export models as TorchScript
.ptfiles, 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 againstlibtorch; the.ptfile 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 (.pthfor 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_neighborsteps with a skin extendingskinÅ beyond each pair style's declared cutoff. For MACE withr_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 inpair_coeffmust match the model'sr_maxexactly. - 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 withno_domain_decomposition, domain decomposition is disabled so this is not needed. For other pair styles where domain decomposition is active,comm_modify cutoffmust be ≥r_max + skinto 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:
- Workflow 1: LAMMPS compilation and plugin installation —
references/key-workflows/01-workflow-1-lammps-compilation-and-plugin-install.md: Verifying that the installed LAMMPS supports the required MLP pair style at the correct version. This is the first diagnostic step for any deployment failure. - Workflow 2: pair_style configuration and species mapping —
references/key-workflows/02-workflow-2-pair-style-configuration-and-species.md: The most common source of silent errors. The element list inpair_coeffmust match the model's internal species order, not the user's preference. - Workflow 3: Validating LAMMPS forces against ASE before production —
references/key-workflows/03-workflow-3-validating-lammps-forces-against-ase.md: This check must pass before any production run. A mismatch above 1 meV/Å is a deployment error — correct it before proceeding. - Workflow 4: NequIP and Allegro deployment —
references/key-workflows/04-workflow-4-nequip-and-allegro-deployment.md - Workflow 5: DeePMD-kit deployment —
references/key-workflows/05-workflow-5-deepmd-kit-deployment.md - Workflow 6: Parallel execution, GPU deployment, and neighbor list tuning —
references/key-workflows/06-workflow-6-parallel-execution-gpu-deployment-and.md
Common Failure Modes
| Failure | Symptom | Likely Cause | Diagnostic | Fix |
|---|---|---|---|---|
| Wrong species mapping | Forces wrong by large, structure-specific amounts (> 1 eV/Å at equilibrium); energy per atom is wrong by > 0.5 eV but system does not immediately crash | Element 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 file | Run validate_lammps_forces (Workflow 3); forces will disagree with ASE by >> 1 meV/Å for the wrong-mapped types | Re-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 units | Forces 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 incorrectly | units real or units lj declared instead of units metal for an eV/Å-trained MLP | Check: 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 plugin | ERROR: Unknown pair style: mace or Segmentation fault (core dumped) at pair_coeff; or libtorch version mismatch | LAMMPS binary does not have the ML-MACE package compiled in, or was compiled against a different libtorch version than the current Python environment | Run `lmp -help | grep ML-MACE; run ldd $(which lmp) |
| Missing model dependencies | RuntimeError: PytorchStreamReader failed at pair_coeff; or model loads but produces NaN forces; for DeePMD: TF_LoadLibrary failed | TorchScript model file is corrupt, was generated by a different MACE version, or has broken relative paths to auxiliary files | Verify model loads in Python: torch.load("model.pt"); check file model.pt output — should be zip archive; for DeePMD, test with dp test before LAMMPS | Regenerate model file with nequip-deploy build or export from current MACE training code; ensure model version matches LAMMPS plugin version |
| Incorrect neighbor list — cutoff truncation | Forces slightly wrong (2–10 meV/Å at equilibrium) but no crash; errors larger for atoms near dense neighborhoods; parallel and serial runs agree | pair_coeff cutoff declared smaller than model r_max; or comm_modify cutoff insufficient for NequIP/Allegro in parallel | Run validate_lammps_forces with 1 MPI rank and compare to ASE; if single-rank passes but multi-rank fails, comm_modify cutoff is too small | Set 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 missing | LAMMPS 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 worse | pair_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 ranks | Compare forces from 1-rank and 4-rank runs; if they differ by > 1 meV/Å, domain decomposition is corrupting the equivariant message passing | Add 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 error | Single-point force validation passes (< 1 meV/Å vs ASE); short NVE run stable; but production NPT at 1500 K diverges after 100 ps | Model tested at configurations near training distribution; production MD at high temperature samples structures outside the training set; MLP extrapolates into unphysical regions | Run 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 distance | Resume active learning at the target temperature (see active-learning-mlp); add high-temperature AIMD snapshots to the training set |
| Silent force mismatch — float32 vs float64 | Forces 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 precision | Run validation with default_dtype="float32" in ASE to match LAMMPS precision; compare both float32 and float64 ASE results to LAMMPS | For 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_forceson 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 metalfor MLPs trained on ASE extxyz data. There is no automatic unit detection in LAMMPS. A wrongunitsdeclaration produces silently wrong forces with no error message. - Pin the species order at data file creation time using
ase write ... specorder=element_orderand record the order in the project README. Any script that writes a new data file must use the samespecorderas the original. - Always include
no_domain_decompositionfor 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 offfor NequIP and Allegro and verifycomm_modify cutoff ≥ r_cut + skin. Failing to setnewton offis 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 yesrather 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 thecputhermo 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 beforelmp -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.modelcheckpoint) is the primary input to this skill. The architecture choices (r_max, element list,hidden_irreps) made during training determine thepair_coeffcutoff 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-validationevaluated in ASE. All validation performed inmlp-validationis 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_stylesyntax and compilation instructions differ. Consult that skill for universal-potential-specific deployment details.
Key References
- 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
- 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
- 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
- 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
- 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并验证单位一致性。
所属插件
安装该插件会一并获得同领域的 35 个 Skill / MCP。
同插件的其他科研 Skill
- 主动学习构建机器学习势训练集Runs active-learning workflows for ML interatomic potentials: uncertainty-guided MD exploration, DFT oracle labeling, query strategy. Use when expanding an MLP training set.
- AiiDA计算工作流管理Covers AiiDA, a provenance-first Python workflow engine for computational materials science: calculation input generation, remote submission. Use when orchestrating reproducible DFT/MD campaigns.
- ASE原子模拟环境Covers the Atomic Simulation Environment (ASE) as an atomistic workflow hub: Atoms objects, calculators, optimizers, trajectories. Use when scripting or converting structures across DFT/MD codes.
- 粗粒化分子动力学模拟Covers coarse-grained molecular dynamics: mapping atomistic structures to CG beads, parameterizing Martini/IBI/force-matching force fields. Use when atomistic timescales are too short.
- CP2K第一性原理分子动力学Covers end-to-end DFT, AIMD, and atomistic workflows with CP2K using the Gaussian-and-plane-waves method: input construction, convergence testing. Use for CP2K-based simulations.
- 扩散模型生成晶体结构Covers de novo crystal structure generation with score-based diffusion and flow-matching models (MatterGen, DiffCSP, CDVAE). Use when generating candidate structures, not analyzing existing ones.
- 晶体图神经网络性质预测Covers graph neural networks for crystal and periodic-material property prediction: crystal graph construction, periodic neighbor finding. Use when building GNN property predictors for crystals.
- 平面波DFT收敛性测试Covers systematic convergence testing for plane-wave DFT: cutoff energy, k-point mesh density, smearing. Use before trusting DFT energies, forces, or derived properties as converged.
- 机器学习势DFT数据集生成Covers generating DFT-labeled datasets for training ML interatomic potentials: configuration-space coverage. Use when building an MLP training dataset from scratch.
- 点缺陷第一性原理计算Covers first-principles point-defect modeling: vacancy/interstitial/antisite/substitutional construction, charge-state calculations. Use for defect thermodynamics studies.
- 第一性原理声子谱计算Covers lattice dynamics from first principles: phonon dispersion, phonon DOS. Use when computing vibrational or thermodynamic properties from DFT.
- 表面模型DFT计算Covers surface slab model construction and DFT calculation: Miller-index generation, termination selection, slab/vacuum convergence. Use for surface science and catalysis DFT studies.
- 弹性常数计算工作流Computes single-crystal and polycrystalline elastic constants from DFT or MD stress-strain data and checks mechanical stability. Use when deriving stiffness tensors or bulk/shear modulus.
- 增强采样自由能计算Covers enhanced sampling methods for atomistic MD (metadynamics, umbrella sampling. Use for rare-event or slow-transition sampling.
- 状态方程拟合Covers equation-of-state fitting from DFT/ML-potential energy-volume data: Birch-Murnaghan, Vinet, and Murnaghan forms. Use when fitting an EOS to compression data.
- 机器学习势微调迁移训练Covers fine-tuning pretrained universal ML interatomic potentials on system-specific DFT data. Use when adapting a universal MLP to a new system.
- 分子动力学自由能计算Covers quantitative free-energy calculations from MD: alchemical FEP/TI/BAR/MBAR, umbrella-sampling PMF. Use when computing thermodynamic free energies from simulation.
- GROMACS分子动力学工作流Covers end-to-end MD simulations with GROMACS: topology/.mdp construction, energy minimization, NVT/NPT equilibration. Use for GROMACS-based biomolecular or materials MD.
- 高通量DFT自动化筛选Covers automated large-scale DFT screening: workflow graphs with atomate2/jobflow/AiiDA, input-set standardization, custodian error handling. Use for high-throughput DFT screening campaigns.
- LAMMPS分子动力学工作流Covers end-to-end MD simulations with LAMMPS: input script anatomy, force-field deployment, ensemble control, equilibration. Use for LAMMPS-based classical molecular dynamics.
- MACE机器学习势训练Covers training MACE machine-learned interatomic potentials: extxyz dataset preparation, isolated-atom energies, train/val/test splitting. Use for MACE-specific MLP training workflows.
- MatGL图神经网络框架Covers building, applying, validating, and fine-tuning MatGL graph-neural-network models for property prediction and interatomic potentials. Use for pretrained GNN workflows via MatGL.
- 分子动力学轨迹后处理分析Covers quantitative post-processing of atomistic MD trajectories: loading LAMMPS/GROMACS/ASE trajectories and computing RDF, coordination numbers. Use for structural MD trajectory analysis.
- 分子动力学平衡过程设计Covers bringing an atomistic simulation from its initial configuration to a representative equilibrium state before production statistics: ensemble. Use before collecting production MD data.
常见问题
机器学习势部署至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 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。