lammps-mdi 0.1.0__tar.gz

lammps_mdi-0.1.0/.github/workflows/BranchCI.yaml

@@ -0,0 +1,50 @@
+name: BranchCI
+
+# Runs on pushes to any branch except main/master.
+# Uses pip (not conda) because lammps-mdi is designed for HPC Python
+# environments, not conda.  Only lightweight tests (no GPU, no torch)
+# are run here; the full runtime tests require an HPC system.
+
+on:
+  push:
+    branches-ignore:
+      - 'main'
+      - 'master'
+
+jobs:
+  lint-and-test:
+    name: Lint & lightweight tests (ubuntu / Py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build tools and linters
+        run: |
+          python -m pip install --upgrade pip
+          pip install black flake8 ruff
+
+      - name: Run linters
+        run: |
+          black --check --diff --extend-exclude '_version.py' src/lammps_mdi tests
+          flake8 src/lammps_mdi tests
+
+      - name: Install package (lightweight deps only — no torch/mace)
+        # pymdi, mace-torch, and torch are intentionally excluded here;
+        # the tests that need them are guarded with pytest.importorskip.
+        run: |
+          pip install pint matscipy
+          pip install --no-deps -e .
+
+      - name: Run lightweight tests
+        run: |
+          pip install pytest pytest-cov
+          pytest -v --cov=lammps_mdi --cov-report=term --color=yes tests/

lammps_mdi-0.1.0/.github/workflows/CI.yaml

@@ -0,0 +1,85 @@
+name: CI
+
+# Runs on PRs to main and on pushes to main.
+# Two jobs:
+#   lint-test  — linting + lightweight tests (no GPU required)
+#   typecheck  — mypy (optional, non-blocking for now)
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+  workflow_dispatch:
+
+jobs:
+  lint-test:
+    name: Lint & lightweight tests (ubuntu / Py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history for setuptools-scm
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build tools and linters
+        run: |
+          python -m pip install --upgrade pip
+          pip install black flake8 ruff
+
+      - name: Run linters
+        run: |
+          black --check --diff --extend-exclude '_version.py' src/lammps_mdi tests
+          flake8 src/lammps_mdi tests
+
+      - name: Install package (lightweight deps only — no torch/mace)
+        # torch, mace-torch, and pymdi are intentionally absent;
+        # runtime tests that need them are guarded with pytest.importorskip.
+        run: |
+          pip install pint matscipy
+          pip install --no-deps -e .
+
+      - name: Run lightweight tests
+        run: |
+          pip install pytest pytest-cov
+          pytest -v --cov=lammps_mdi --cov-report=xml --cov-report=term --color=yes tests/
+
+      - name: Upload coverage report
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-ubuntu-py${{ matrix.python-version }}
+        continue-on-error: true   # don't fail CI if codecov is down
+
+  typecheck:
+    name: mypy type checks
+    runs-on: ubuntu-latest
+    continue-on-error: true   # informational only until typing is complete
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install mypy and stubs
+        run: |
+          pip install mypy pint matscipy
+          pip install --no-deps -e .
+
+      - name: Run mypy (lightweight modules only)
+        run: |
+          mypy src/lammps_mdi/cuda_utils.py src/lammps_mdi/cli.py

lammps_mdi-0.1.0/.github/workflows/CodeQL.yaml

@@ -0,0 +1,12 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  codeql:
+    name: CodeQL
+    uses: molssi-seamm/devops/.github/workflows/CodeQL.yaml@main

lammps_mdi-0.1.0/.github/workflows/Release.yaml

@@ -0,0 +1,108 @@
+name: Release
+
+# Triggered when a GitHub release is published.
+# Runs lint + lightweight tests, then deploys to Test PyPI and PyPI.
+# Documentation deployment is commented out until docs are set up.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  lint-test:
+    name: Lint & lightweight tests (ubuntu / Py3.12)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history for setuptools-scm version tags
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install linters
+        run: |
+          python -m pip install --upgrade pip
+          pip install black flake8
+
+      - name: Run linters
+        run: |
+          black --check --diff --extend-exclude '_version.py' src/lammps_mdi tests
+          flake8 src/lammps_mdi tests
+
+      - name: Install package (lightweight deps only)
+        run: |
+          pip install pint matscipy
+          pip install --no-deps -e .
+
+      - name: Run lightweight tests
+        run: |
+          pip install pytest
+          pytest -v --color=yes tests/
+
+  deploy:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    needs: lint-test
+    environment: pypi   # requires PyPI trusted publisher or secrets configured
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history so setuptools-scm reads the git tag
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build source and wheel
+        run: |
+          python -m build --sdist --wheel --outdir dist/
+          ls -l dist/
+          twine check dist/*
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_PASSWORD }}
+          skip-existing: true
+
+      - name: Publish to PyPI
+        # Skip dev and rc releases (e.g. v0.1.0.dev1, v0.1.0rc1)
+        if: |
+          !contains(github.ref, 'dev') && !contains(github.ref, 'rc')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_PASSWORD }}
+
+  # ---------------------------------------------------------------------------
+  # Documentation deployment — enable once docs/ is set up
+  # ---------------------------------------------------------------------------
+  # docs:
+  #   name: Deploy documentation
+  #   runs-on: ubuntu-latest
+  #   needs: lint-test
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-python@v5
+  #       with:
+  #         python-version: "3.12"
+  #     - name: Install docs dependencies
+  #       run: pip install pint matscipy sphinx sphinx-rtd-theme && pip install --no-deps -e .
+  #     - name: Build HTML docs
+  #       run: make html
+  #     - name: Deploy to GitHub Pages
+  #       uses: peaceiris/actions-gh-pages@v4
+  #       with:
+  #         github_token: ${{ secrets.GITHUB_TOKEN }}
+  #         publish_dir: docs/_build/html

lammps_mdi-0.1.0/.gitignore

@@ -0,0 +1,152 @@
+# -*- mode: gitignore; -*-
+
+## emacs: https://github.com/github/gitignore/blob/master/Global/Emacs.gitignore
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# vcs_versioning
+_version.py
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+
+# directory configuration
+.dir-locals.el
+
+# network security
+/network-security.data
+## end of emacs
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+## macOS useful to ignore https://github.com/github/gitignore/blob/master/Global/macOS.gitignore
+*.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+## end of macOS
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# IntelliJ Idea family of suites
+.idea
+*.iml
+## File-based project format:
+*.ipr
+*.iws
+## mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# PyBuilder
+target/
+
+# Cookiecutter
+output/
+python_boilerplate/

lammps_mdi-0.1.0/HISTORY.md

@@ -0,0 +1,58 @@
+# History
+
+All notable changes to **lammps-mdi** are recorded here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-03-30
+
+First public release.
+
+### Added
+
+- `MACEEngine`: MDI engine that runs MACE-torch models, communicating
+  with a LAMMPS driver process via MPI-MDI.  Bypasses the ASE Calculator
+  interface for lower per-step overhead, building model inputs directly
+  from MDI data.
+- Automatic selection between **vesin-torch** (GPU-accelerated) and
+  **matscipy** (CPU fallback) neighbor list backends.
+- Optional **cuEquivariance** (`--enable-cueq`) and
+  **openEquivariance** (`--enable-oeq`) acceleration for MACE.
+- All heavy runtime dependencies (`torch`, `mdi`, `mpi4py`, `mace`,
+  `numpy`, `vesin`, `matscipy`) are imported lazily so the package is
+  importable on any machine without a GPU.
+- Bundled shell scripts for CPU/GPU resource binding on HPC clusters:
+  - `mdi_bind.sh` — binds engine (rank 0) to GPU + NUMA-local CPUs and
+    driver (rank 1) to adjacent CPUs; starts nvidia-smi monitor.
+    For standalone machines.
+  - `mdi_monitor.sh` — lightweight wrapper for SLURM/PBS managed
+    environments; scheduler handles binding, script adds GPU monitoring.
+  - `gpu_bind.sh` — per-rank GPU binding for native Kokkos LAMMPS.
+  - `cpu_bind.sh` — CPU-only binding using L3 cache groups (EPYC 7763).
+- `lammps-mdi` CLI with subcommands:
+  - `check` — report the runtime environment (CUDA, torch, MDI, mace, …)
+  - `install-scripts` — copy bundled shell scripts to a target directory
+  - `install-torch` — print the correct `pip install torch` command for
+    the detected CUDA driver version
+  - `version` — print the installed package version
+- `mace-mdi` console script as the entry point for the MACE MDI engine.
+- CUDA auto-detection via `nvidia-smi`; maps driver CUDA version to the
+  appropriate PyTorch wheel tag (cu118 … cu128).
+- BSD-3-Clause license.
+
+---
+
+## [Unreleased]
+
+### Planned
+- NequIPEngine: MDI engine for NequIP/Allegro models.
+- SevenNetEngine: MDI engine for SevenNet models.
+- Configurable CPU topology in binding scripts (currently hard-coded for
+  dual-GPU EPYC 7763).
+
+---
+
+[0.1.0]: https://github.com/molssi-seamm/lammps-mdi/releases/tag/v0.1.0
+[Unreleased]: https://github.com/molssi-seamm/lammps-mdi/compare/v0.1.0...HEAD

lammps_mdi-0.1.0/INSTALL.md

@@ -0,0 +1,237 @@
+# Installing lammps-mdi on HPC Systems
+
+lammps-mdi uses the Python environment that ships with your LAMMPS build.
+On HPC clusters managed with EasyBuild or Spack, that Python is provided by
+a module, and its site-packages must not be modified.  The correct approach
+is a virtual environment that **inherits** the module stack.
+
+---
+
+## Quick summary
+
+```
+1. Load your LAMMPS module (sets Python, numpy, mpi4py, MDI, etc.)
+2. Create a venv with --system-site-packages
+3. Activate the venv
+4. pip install torch with the right CUDA wheel
+5. pip install lammps-mdi[gpu]
+6. lammps-mdi install-scripts
+```
+
+---
+
+## Step 1 — Load the LAMMPS module
+
+```bash
+module load LAMMPS/22Jul2025-foss-2024a-kokkos   # adjust to your site
+```
+
+This loads Python, numpy, mpi4py, MDI, and everything else the LAMMPS
+build depends on.  All of these will be visible inside the venv we create
+in the next step.
+
+Verify MDI is accessible:
+
+```bash
+python -c "import mdi; print(mdi.__version__, mdi.__file__)"
+```
+
+If this fails, either the MDI module was not loaded or `pymdi` is not
+installed in the system Python.  If pymdi is not present, install it after
+activating the venv (step 3):
+
+```bash
+pip install pymdi
+```
+
+---
+
+## Step 2 — Create a virtual environment
+
+```bash
+python -m venv --system-site-packages ~/venvs/lammps-mdi
+```
+
+The `--system-site-packages` flag makes the venv see all packages provided
+by the loaded modules (numpy, mpi4py, MDI, lammps, …) **without** copying
+or reinstalling them.
+
+---
+
+## Step 3 — Activate the venv
+
+```bash
+source ~/venvs/lammps-mdi/bin/activate
+```
+
+Add this to your job script or `~/.bashrc` (after the `module load` line).
+
+---
+
+## Step 4 — Install PyTorch with the correct CUDA wheel
+
+PyTorch must be installed **before** lammps-mdi, because mace-torch depends
+on it and pip must find it already present to avoid pulling in a CPU-only
+or wrong-CUDA build.
+
+Use `lammps-mdi` to find the right command for your GPU:
+
+```bash
+# If lammps-mdi is not installed yet, use the helper directly:
+python -c "
+from lammps_mdi.cuda_utils import detect_cuda_version, recommend_torch_tag, torch_install_command
+maj, min_ = detect_cuda_version()
+tag = recommend_torch_tag(maj, min_)
+print(torch_install_command(tag))
+"
+```
+
+Or simply run `nvidia-smi` and look for `CUDA Version: X.Y`, then pick the
+closest matching tag from the table below:
+
+| Driver CUDA ceiling | Use this wheel tag |
+|--------------------|--------------------|
+| ≥ 12.8             | `cu128`            |
+| ≥ 12.6             | `cu126`            |
+| ≥ 12.4             | `cu124`            |
+| ≥ 12.1             | `cu121`            |
+| ≥ 11.8             | `cu118`            |
+
+Example for CUDA 12.2 (driver ceiling) — use cu121:
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cu121
+```
+
+> **Note on bundled CUDA**: modern PyTorch wheels bundle their own CUDA
+> runtime libraries (`nvidia-cuda-runtime-cu12`, etc.).  This means the
+> wheel's CUDA version can be slightly *newer* than the driver's reported
+> CUDA ceiling, as long as the driver version itself is compatible.
+> For CUDA 12.2 drivers the cu121 wheel works correctly.
+
+Verify:
+
+```bash
+python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
+```
+
+---
+
+## Step 5 — Install lammps-mdi
+
+```bash
+# Recommended: with GPU-accelerated neighbor lists
+pip install lammps-mdi[gpu]
+
+# Or with cuEquivariance acceleration (base packages only):
+pip install lammps-mdi[gpu-full]
+
+# Then add the ops kernel matching your CUDA:
+pip install cuequivariance-ops-torch-cu12    # for CUDA 12.x
+# pip install cuequivariance-ops-torch-cu11  # for CUDA 11.x
+```
+
+Run the environment check:
+
+```bash
+lammps-mdi check
+```
+
+Expected output (abbreviated):
+
+```
+============================================================
+lammps-mdi environment report
+============================================================
+
+Python:  3.12.3  (/home/user/venvs/lammps-mdi/bin/python)
+GPU:     CUDA driver 12.2 detected via nvidia-smi
+         Recommended torch wheel tag: cu121
+         pip install torch --index-url .../cu121
+
+torch:   2.x.x  (CUDA 12.1, 2 device(s))
+
+pymdi:   1.4.x  (/path/to/mdi/__init__.py)
+
+mace:    0.3.x
+vesin:   available (GPU neighbor lists enabled)
+cueq:    0.9.x
+```
+
+---
+
+## Step 6 — Install shell scripts
+
+The package bundles `mdi_bind.sh`, `mdi_monitor.sh`, `cpu_bind.sh`, and
+`gpu_bind.sh`.  Install them to `~/SEAMM/bin` (or any directory in PATH):
+
+```bash
+lammps-mdi install-scripts                 # installs to ~/SEAMM/bin
+lammps-mdi install-scripts --dir /opt/bin  # custom directory
+```
+
+---
+
+## Step 7 — Configure lammps.ini
+
+Set the `gpu-code` key in `lammps.ini` to use the installed scripts.
+For a standalone machine with one GPU:
+
+```ini
+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"
+```
+
+For HPC with SLURM (scheduler handles binding):
+
+```ini
+gpu-code = mpirun \
+    -np 1 ~/SEAMM/bin/mdi_monitor.sh \
+    mace-mdi -mdi "-role ENGINE -name MACE -method MPI" \
+    : -np 1 ~/SEAMM/bin/mdi_monitor.sh \
+    lmp -mdi "-role DRIVER -name LAMMPS -method MPI"
+```
+
+Note that `mace-mdi` is now a console script installed into the venv's
+`bin/`, so it is available directly by name once the venv is activated.
+
+---
+
+## Adding the venv activation to job scripts
+
+```bash
+#!/bin/bash
+#SBATCH --gres=gpu:1
+#SBATCH --ntasks=2
+
+module load LAMMPS/22Jul2025-foss-2024a-kokkos
+source ~/venvs/lammps-mdi/bin/activate
+
+# SEAMM or direct mpirun command here
+```
+
+---
+
+## Troubleshooting
+
+**`ImportError: No module named 'mdi'`**
+- The MDI module is not loaded, or `pymdi` is not installed.
+  Check `module list` and try `pip install pymdi`.
+
+**`torch.cuda.is_available()` returns False**
+- The torch wheel was installed without GPU support.
+  Reinstall with the correct `--index-url`.
+
+**`cuequivariance` not found at runtime**
+- Install the base packages: `pip install cuequivariance cuequivariance-torch`
+- Then the ops kernel: `pip install cuequivariance-ops-torch-cu12`
+
+**numpy version conflict**
+- Never install numpy inside the venv with `--system-site-packages`.
+  The system numpy (from the module) takes precedence; a second install
+  in the venv can shadow it with a different version.
+  If pip warns about a numpy conflict from `mace-torch`, this is usually
+  harmless — mace-torch will use the system numpy.