feat: add unified simulation API, CLI, and MCP tools

.github/workflows/ci.yml

@@ -24,6 +24,10 @@ jobs:
         run: |
           ruff check tests/test_mlip*.py tests/test_cli.py examples/mlip_gpu.py alcf/polaris/mlip/smoke.py
           ruff format --check tests/test_mlip*.py tests/test_cli.py examples/mlip_gpu.py alcf/polaris/mlip/smoke.py
+      - name: Check unified API tests and recipes
+        run: |
+          ruff check tests/test_api*.py tests/test_foundations.py tests/test_operation_cli.py tests/test_mcp_api.py tests/test_packaged_resources.py tests/test_unified_smoke.py tests/fixtures/fake_engine.py examples/unified_smoke.py
+          ruff format --check tests/test_api*.py tests/test_foundations.py tests/test_operation_cli.py tests/test_mcp_api.py tests/test_packaged_resources.py tests/test_unified_smoke.py tests/fixtures/fake_engine.py examples/unified_smoke.py
 
   test:
     runs-on: ubuntu-latest
@@ -36,9 +40,30 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
-        run: pip install -e ".[dev]"
+        run: |
+          pip install build pytest
+          python -m build --wheel
+          pip install dist/*.whl
       - name: Run tests
-        run: pytest tests/ -v
+        env:
+          MATKIT_WHEEL_TEST: "1"
+        run: |
+          mkdir -p "$RUNNER_TEMP/matkit-wheel-tests"
+          cp -R tests examples alcf "$RUNNER_TEMP/matkit-wheel-tests/"
+          cd "$RUNNER_TEMP/matkit-wheel-tests"
+          pytest tests/ -v
+
+  mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install optional MCP environment
+        run: pip install ".[dev,mcp]"
+      - name: Test local stdio and worker cancellation
+        run: pytest tests/test_mcp_api.py -v
 
   build:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Experimental unified scientific API, versioned requests/results, structure
+  lineage, relocatable run bundles, and supervised local execution
+- Shared operation CLI and optional bounded stdio MCP tools with artifact
+  retrieval, plus installed-wheel and deterministic transport tests
+- Single-component gRASPA CUDA prepare/run/analyze path, capability inventory,
+  and opt-in execution evidence recorder
 - MLIP numerical validation, strict CLI outcomes, incremental atomic batch
   persistence, and an explicit experimental GPU validation recipe
 - Separate PR hardening and future development handoff plans in `docs/plans`
@@ -28,6 +34,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `conftest.py` for pytest configuration
 
 ### Fixed
+- Custom cutoff propagation through GCMC unit-cell replication and cached
+  batch setup, and successful RASPA2 parsing incorrectly reporting failure
 - **MACE optimizer bug**: `geo_opt_cell_opt` mode called `dyn1.run()` instead of `dyn.run()` for cell optimization step, meaning the cell was never actually optimized
 - **Missing f-string**: `raspa2.py` error message `"Unit {unit} is not supported"` was missing `f` prefix
 - **Unreachable code**: Removed dead `return result` after `raise ValueError` in `graspa.py` and `graspa_sycl.py`

README.md

@@ -165,6 +165,12 @@ combining these stacks. The `all` extra does not include Rootstock or ALCHEMI.
 
 ## Python API
 
+The experimental [unified operation API](docs/unified-api.md) provides shared
+Python/CLI requests, relocatable calculation bundles, and optional MCP tools.
+It covers MLIP evaluation/relaxation, Zeo++ analysis, and single-component
+gRASPA CUDA execution. See the [capability inventory](docs/capabilities.md)
+for implementation status, environment requirements, and validation limits.
+
 ```python
 from matkit.graspa import setup_simulation, get_output_data
 from matkit.utils import calculate_cell_size, remove_solvent, sample_cifs

alcf/polaris/unified/run.pbs

@@ -0,0 +1,16 @@
+#!/bin/bash
+#PBS -N matkit-unified
+#PBS -l select=1:system=polaris
+#PBS -l place=scatter
+#PBS -l walltime=01:00:00
+#PBS -q debug
+
+# Supply your account with qsub -A ACCOUNT and export the three variables below.
+# This script executes an already prepared bundle inside the allocated node.
+set -euo pipefail
+: "${MATKIT_PYTHON:?Set an absolute MatKit environment Python path}"
+: "${MATKIT_BUNDLE:?Set the absolute prepared-bundle path}"
+: "${MATKIT_EXECUTION_PROFILE:?Set the absolute execution-profile JSON path}"
+cd "${PBS_O_WORKDIR:?}"
+exec "$MATKIT_PYTHON" -m matkit.cli execute "$MATKIT_BUNDLE" \
+    --execution "$MATKIT_EXECUTION_PROFILE"

docs/capabilities.md

@@ -0,0 +1,38 @@
+# Capability inventory
+
+This inventory distinguishes implemented interfaces from scientific validation.
+No GPU or external-engine capability has been promoted by CPU fixtures. The
+unified API remains experimental; record real execution for each capability,
+model, and environment before promotion.
+
+| Interface | Implemented capability | Environment | Evidence/status |
+| --- | --- | --- | --- |
+| Unified direct MACE | Energy, requested forces/stress, fixed-cell relaxation, sequential batches | MACE + compatible CPU/CUDA stack; model-dependent properties/species | CPU adapter contracts; experimental |
+| Unified Rootstock | Energy, requested forces/stress, fixed-cell relaxation, sequential batches | Rootstock client and separately installed deployment | CPU adapter contracts; worker evidence required |
+| Unified ALCHEMI MACE | Energy, requested forces/stress, fixed-cell FIRE, native batches | Compatible ALCHEMI/CUDA environment | Mocked native contracts; GPU evidence required |
+| Unified Zeo++ | Diameter, area, volume, PSD, channels | `network` binary and radii definitions | Parser/subprocess fixtures; real execution required |
+| Unified gRASPA CUDA | Pure-component preparation, execution, absolute uptake and heat parsing | Charged periodic CIF; templates; CUDA executable for execution | Synthetic output/subprocess fixtures; real execution required |
+| Legacy gRASPA/pygRASPA | Pure/mixture and grid setup; existing parsers; pygRASPA reference-energy helper | Core for preparation; engine-specific environment for execution | Setup/parser fixtures; mixtures outside unified result contract |
+| Legacy gRASPA SYCL | Setup and parsing | Core for preparation; Intel GPU environment for execution | Cutoff regressions; Aurora recipe; execution evidence required |
+| Legacy RASPA2 | Setup and parsing | Core for preparation; RASPA2 for execution | Cutoff and success-reporting regressions; execution evidence required |
+| RASPA3 | Force-field conversion only | Core | Conversion fixtures; simulation execution not implemented |
+| Legacy MACE optimization | Geometry, cell, sequential geometry/cell optimization | MACE with required forces/stress | Existing interface; outside unified validation contract |
+| Legacy UMA | Single point, geometry/cell optimization, MD and batch optimization | FAIRChem/UMA installation | Existing interfaces; outside unified validation contract |
+| PACMOF2 | Charge-prediction wrapper | PACMOF2 installation | Existing interface; per-output scientific validation not yet unified |
+| Structure utilities/ToBaCCo | Solvent removal, sampling, linker/conversion helpers | Core; optional RDKit/Open Babel as applicable | Legacy compatibility; future structural operations belong in MOFforge |
+| Isotherm plotting | Single/mixture plots and selectivity from existing data | Matplotlib extra | Parser/plot fixtures; does not establish input scientific accuracy |
+| ORCA | Stub | Not applicable | No supported execution capability |
+| CLI/MCP | Unified requests, results, artifacts; bounded stdio tools | Core CLI; optional MCP SDK 2 | Deterministic subprocess and local stdio integration tests |
+
+Availability in `matkit capabilities` is a caller-side installation check, not a
+model suitability or GPU compatibility claim. Preparation needs no engine
+binary. Generic energy evaluation needs only its requested properties;
+relaxation needs forces, and cell optimization is not advertised by the unified
+API. Native ALCHEMI rejects unsupported atom arrays/constraints. Model aliases
+whose content cannot be resolved are identified as such in provenance.
+
+Promotion requires interface documentation, licensed reference fixtures,
+failure tests, reproducible installation, and reviewed real execution. Numerical
+parity uses matching checkpoints/settings; scientific accuracy requires
+independent reference data. Record benchmark startup, warm execution, throughput,
+memory, and failures separately.