Skip to content

Add pygraspa backend for ML-potential GCMC#13

Merged
tdpham2 merged 4 commits into
mainfrom
feature/add-single-mixture-mode
Jun 3, 2026
Merged

Add pygraspa backend for ML-potential GCMC#13
tdpham2 merged 4 commits into
mainfrom
feature/add-single-mixture-mode

Conversation

@tdpham2

@tdpham2 tdpham2 commented Jun 3, 2026

Copy link
Copy Markdown
Owner

Summary

  • Adds a new `matkit.pygraspa` backend that produces simulation directories ready to run with pygRASPA — gRASPA Monte Carlo driven by ML interatomic potentials (FAIRChem eSEN/UMA/AllScAIP, MACE-Polar, Allegro) instead of classical force fields.
  • API mirrors `matkit.graspa`: `setup_simulation`, `setup_batch`, `get_output_data`, plus a `compute_ecomp` helper for the per-adsorbate reference energy pygRASPA needs in its Metropolis criterion.
  • Setup-only integration — matkit writes a small `run.py` launcher into each sim dir and does not import pygRASPA / torch / CUDA at install time. No GPU dependency added to matkit itself.
  • Includes single + batch setup, a single/mixture isotherm orchestrator in `scripts/pygraspa/`, `matkit pygraspa` CLI commands, and a no-GPU pytest suite.

What's in here

Area Files
Core `src/matkit/pygraspa/{init.py,pygraspa.py}`
Templates `src/matkit/pygraspa/files/{template,template_mixture,template_mixture_isotherm}/` (duplicated from `matkit.graspa` — same gRASPA input format)
CLI `matkit pygraspa setup|batch-setup|compute-ecomp|analyze` added to `src/matkit/cli.py`
Isotherm `scripts/pygraspa/{setup_isotherms.py,isotherm_config.yaml}` (single + mixture modes, parallel to `scripts/graspa/`)
Packaging New `pygraspa` extra + 3 `package-data` entries in `pyproject.toml`
Tests `tests/test_pygraspa.py` (17 tests, no GPU/torch required)

Modes supported

  • `mode='run'` → renders a `run.py` calling `pygRASPA.main.run` (plain ML MC).
  • `mode='run-auto'` (default) → renders a `run.py` calling `pygRASPA.auto.main.run_auto` (JSON checkpoint + STOP_FLAG for preemptible cluster jobs).
  • `run-classic` is intentionally omitted — `matkit.graspa` already covers that use case.

Test plan

  • `pytest tests/test_pygraspa.py` — 17 new tests pass
  • `pytest` (full suite, ignoring GPU-only test_uma) — 164 passed, 1 skipped, no regressions
  • `ruff check` clean on all new/modified files
  • CLI smoke: `matkit pygraspa setup …` produces a sim dir with rendered `simulation.input` (no placeholders left) and a syntactically valid `run.py` (`python -m py_compile run.py`)
  • CLI smoke: `matkit pygraspa batch-setup …` produces correct `simulations.jsonl` and `cif_mapping.json` for 2 CIFs × 2 T × 2 P = 8 sims
  • Isotherm orchestrator dry-run, single mode: 4 pressures × 1 T × 2 adsorbates = 8 sims in adsorbate-split subdirs
  • Isotherm orchestrator dry-run, mixture mode: `MolFraction` overrides propagate into `Component` blocks, `E_comps` matched in order in `run.py`
  • Run an actual `pygraspa run-auto` job on a GPU box and confirm `matkit pygraspa analyze` parses the resulting JSON-lines log. The parser is built against the schema described in pygRASPA's README and uses tolerant field-name matching, but should be validated against a real `output.log` before relying on it in production.

tdpham2 and others added 4 commits June 2, 2026 22:02
Adds a new matkit.pygraspa backend that produces simulation directories
ready to run with pygRASPA (https://github.com/tdpham2/pygRASPA), which
runs gRASPA Monte Carlo with ML interatomic potentials (FAIRChem,
MACE-Polar, Allegro) instead of classical force fields.

API mirrors matkit.graspa: setup_simulation, setup_batch, get_output_data,
plus a compute_ecomp helper for the per-adsorbate reference energy that
pygRASPA needs for the Metropolis criterion. Setup-only integration -
matkit writes a run.py launcher into each sim dir and does not import
pygRASPA or torch at install time, so the new package adds no GPU
dependencies to matkit itself.

Includes single + batch setup, single/mixture isotherm orchestrator,
matkit pygraspa CLI commands, and a no-GPU pytest suite covering the
template rendering, batch manifest, and JSON-lines log parser.
Add pygraspa backend for ML-potential GCMC
Drop an unused ase.io.write import and rename the ambiguous `l`
loop variable (E741) in test_utils.py, and wrap the long assertion
in test_batch_writes_mapping_only_for_renamed (E501).
Brings the two new files into line with the rest of src/ so
`ruff format --check src/` passes in CI.
@tdpham2 tdpham2 merged commit 63f909b into main Jun 3, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant