Metadata-Version: 2.4
Name: lammps-mdi
Version: 0.1.2
Summary: MDI engine drivers for LAMMPS — MACE and other ML forcefields via MolSSI Driver Interface
Author-email: Paul Saxe <psaxe@molssi.org>
License: BSD 3-Clause License
        
        Copyright (c) 2026, The Molecular Sciences Software Institute (MolSSI)
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
           this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the Molecular Sciences Software Institute nor the
           names of its contributors may be used to endorse or promote products
           derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/molssi-seamm/lammps-mdi
Project-URL: Documentation, https://lammps-mdi.readthedocs.io
Project-URL: Repository, https://github.com/molssi-seamm/lammps-mdi
Project-URL: Bug Tracker, https://github.com/molssi-seamm/lammps-mdi/issues
Project-URL: Changelog, https://github.com/molssi-seamm/lammps-mdi/blob/main/HISTORY.md
Keywords: lammps,mdi,mace,machine learning,forcefield,molecular dynamics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: GPU :: NVIDIA CUDA
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymdi>=1.4
Requires-Dist: pint>=0.20
Requires-Dist: mace-torch>=0.3
Requires-Dist: matscipy>=0.8
Requires-Dist: numpy<2
Provides-Extra: gpu
Requires-Dist: vesin-torch>=0.3; extra == "gpu"
Provides-Extra: cueq
Requires-Dist: cuequivariance>=0.3; extra == "cueq"
Requires-Dist: cuequivariance-torch>=0.3; extra == "cueq"
Provides-Extra: gpu-full
Requires-Dist: lammps-mdi[gpu]; extra == "gpu-full"
Requires-Dist: lammps-mdi[cueq]; extra == "gpu-full"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Dynamic: license-file

# lammps-mdi

MDI engine drivers for LAMMPS — run ML forcefields (MACE, and future models)
on GPU via the [MolSSI Driver Interface](https://molssi-mdi.github.io/MDI_Library/),
communicating with a standard LAMMPS binary (no Kokkos compilation needed).

Designed for use with [SEAMM](https://github.com/molssi-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.md](INSTALL.md) for full HPC instructions.  Short version:

```bash
# 1. Load your LAMMPS module (provides Python, numpy, mpi4py, MDI)
module load LAMMPS/...

# 2. Create a venv that inherits the module stack
python -m venv --system-site-packages ~/venvs/lammps-mdi
source ~/venvs/lammps-mdi/bin/activate

# 3. Install PyTorch with the right CUDA wheel (check your CUDA version first)
lammps-mdi install-torch    # prints the correct command
# e.g.:
pip install torch --index-url https://download.pytorch.org/whl/cu121

# 4. Install lammps-mdi
pip install lammps-mdi[gpu]

# 5. Install bundled shell scripts
lammps-mdi install-scripts

# 6. Verify
lammps-mdi check
```

## Usage

### As a console script (recommended)

```bash
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
```

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
  --log-level LEVEL    DEBUG / INFO / WARNING / ERROR
```

### From lammps.ini (SEAMM)

```ini
[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

```python
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](LICENSE).
