lammps-mdi
MDI engine drivers for LAMMPS — run ML forcefields (MACE, and future models) on GPU via the MolSSI Driver Interface, communicating with a standard LAMMPS binary (no Kokkos compilation needed).
Designed for use with SEAMM, but works with any LAMMPS workflow that supports MDI.
How it works
LAMMPS acts as an MDI driver: it handles atom positions, neighbor lists (at the coarse level), and time integration. The lammps-mdi engine process acts as an MDI engine: it receives coordinates from LAMMPS each step, evaluates the ML model on GPU, and returns energies, forces, and (if periodic) the stress tensor.
mpirun -np 1 mace-mdi -mdi "..." ← GPU process: MACE on A100
: -np 1 lmp -mdi "..." -in input.dat ← CPU process: time integration
The two processes communicate over MPI via the MDI protocol.
Supported engines
| Engine | Status | Notes |
|---|---|---|
| MACE | ✅ | MACE-torch ≥ 0.3, vesin-torch neighbor lists, cuEquivariance optional |
| NequIP | Planned | |
| SevenNet | Planned |
Installation
See INSTALL_CONDA.md for full HPC instructions.
Usage
As a console script (recommended)
SEAMM_FF=/path/to/model.model \
mpirun --mca mpi_yield_when_idle 1 \
-np 1 mdi_bind.sh mace-mdi -mdi "-role ENGINE -name MACE -method MPI" \
: -np 1 mdi_bind.sh lmp -mdi "-role DRIVER -name LAMMPS -method MPI" -in input.dat
Install the ML runtime (PyTorch, vesin, cuEquivariance, MACE) into the LAMMPS environment with:
lammps-mdi install-ml # or --dry-run to see the plan first
It picks the PyTorch wheel from the machine's NVIDIA driver. A wheel built for
a newer CUDA than the driver supports imports without complaint and then
reports no GPU, so the first thing to touch the device fails far from the real
cause; install-ml avoids that, and keeps mace-torch from pulling a
different torch from PyPI. Use --tag to force a wheel tag, since the newest
tag a driver supports does not always offer the newest torch for your Python
version.
The mace-mdi command accepts several options:
mace-mdi --help
-mdi MDI_STRING MDI initialization string [required]
--model PATH Path to MACE model (overrides SEAMM_FF)
--device DEVICE PyTorch device (default: cuda:0)
--dtype {float32,float64}
--enable-cueq Enable cuEquivariance acceleration
--enable-oeq Enable openEquivariance acceleration
--max-pairs-per-point N
Neighbour-list capacity per point (default 256).
Raise for dense systems or long cutoffs; the periodic
timing line reports the largest value actually seen
against this limit.
--profile-steps N Profile the first N forward passes with torch.profiler
and write a Chrome trace (chrome://tracing, or
https://ui.perfetto.dev). Default 0 (disabled).
--log-level LEVEL DEBUG / INFO / WARNING / ERROR
From lammps.ini (SEAMM)
[local]
installation = conda # or modules, or local
gpu-code = mpirun --mca mpi_yield_when_idle 1 \
-np 1 ~/SEAMM/bin/mdi_bind.sh \
mace-mdi -mdi "-role ENGINE -name MACE -method MPI" \
: -np 1 ~/SEAMM/bin/mdi_bind.sh \
lmp -mdi "-role DRIVER -name LAMMPS -method MPI"
As a Python library
from lammps_mdi import MACEEngine
engine = MACEEngine(
model_path="/path/to/model.model",
device="cuda:0",
default_dtype="float32",
enable_cueq=True,
)
engine.run("-role ENGINE -name MACE -method MPI")
Shell scripts
The package bundles four helper scripts, installed via lammps-mdi install-scripts:
| Script | Purpose |
|---|---|
mdi_bind.sh |
Binds engine (rank 0) to GPU + NUMA-local CPUs, driver (rank 1) to adjacent CPUs; starts nvidia-smi monitor. For standalone machines. |
mdi_monitor.sh |
Lightweight wrapper for SLURM/PBS: only starts GPU monitoring. Scheduler handles binding. |
gpu_bind.sh |
Per-rank GPU binding for native Kokkos LAMMPS (approach A). |
cpu_bind.sh |
CPU-only binding using L3 cache groups (EPYC 7763). |
The CPU/GPU mappings in mdi_bind.sh, gpu_bind.sh, and cpu_bind.sh are
currently hard-coded for a dual-GPU EPYC 7763 system. They will be made
configurable in a future release.
Requirements
| Package | Source | Notes |
|---|---|---|
| Python ≥ 3.10 | HPC module | |
| numpy | HPC module | Do not reinstall |
| mpi4py | HPC module | |
| pymdi ≥ 1.4 | pip | PyPI package for import mdi |
| torch (CUDA) | pip (special index) | Install before lammps-mdi |
| mace-torch ≥ 0.3 | pip | |
| matscipy ≥ 0.8 | pip | CPU fallback neighbor list |
| pint ≥ 0.20 | pip | Unit conversion |
| vesin-torch ≥ 0.3 | pip (optional) | GPU neighbor lists, strongly recommended |
| cuequivariance* | pip (optional) | NVIDIA cuEquivariance acceleration |
Contributing
Issues and pull requests are welcome at https://github.com/molssi-seamm/lammps-mdi.
License
MIT — see LICENSE.
Metadata
Release files for lammps-mdi 0.1.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lammps_mdi-0.1.12.tar.gz | 49.8 kB | Without provenance | Details for lammps_mdi-0.1.12.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lammps_mdi-0.1.12-py3-none-any.whl | Python 3 | none | any | Details for lammps_mdi-0.1.12-py3-none-any.whl |
Total release size: 84.0 kB
Release files / lammps_mdi-0.1.12.tar.gz
| Download URL | lammps_mdi-0.1.12.tar.gz |
|---|---|
| Size | 49.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8593806dbb481643fe00acbe398876a043133b205eea3ecb5a741722ca59f617
|
|
BLAKE2b-256 checksum How to use checksums |
d0a74cce1ae9a63db0e021ba484e6caf0d4e51f1c9f0176608fc86395bec0b6e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / lammps_mdi-0.1.12-py3-none-any.whl
| Download URL | lammps_mdi-0.1.12-py3-none-any.whl |
|---|---|
| Size | 34.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d32cbfcdb1f8696f91803203c4dab8315e12f8de3587dba7283cab113053da24
|
|
BLAKE2b-256 checksum How to use checksums |
dd6990f5db03ec7242b2def31b0e72f195cf12bba563aa662dc83da474c8c415
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for lammps-mdi 0.1.12
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.