mattergraph-sim 0.1.0__tar.gz

mattergraph_sim-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs build output
+site/
+
+# Env
+.env
+.env.local
+*.local
+
+# Node
+node_modules/
+apps/web/dist/
+apps/web/playwright-report/
+apps/web/test-results/
+*.tsbuildinfo
+.next/
+out/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+
+# Data artifacts (keep demo/ tracked)
+data/cache/
+*.sqlite3
+
+.claude
+apps/private-platform-ui/

mattergraph_sim-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: mattergraph-sim
+Version: 0.1.0
+Summary: ASE/LAMMPS/QE simulation job specs and runners (MVP wrappers).
+Project-URL: Homepage, https://github.com/cyrusmo/MatterGraph
+Project-URL: Repository, https://github.com/cyrusmo/MatterGraph
+Project-URL: Issues, https://github.com/cyrusmo/MatterGraph/issues
+Project-URL: Changelog, https://github.com/cyrusmo/MatterGraph/blob/main/CHANGELOG.md
+Author: MatterGraph contributors
+License-Expression: Apache-2.0
+Keywords: ase,lammps,materials-science,quantum-espresso,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: ase>=3.22
+Requires-Dist: mattergraph-core~=0.1.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pymatgen>=2024.1.1
+Description-Content-Type: text/markdown
+
+# mattergraph-sim
+
+Simulation job specs and runners for [MatterGraph](https://github.com/cyrusmo/MatterGraph).
+
+Structures round-trip through pymatgen, jobs are declared as validated Pydantic specs, and runners return a structured `SimulationJob` with status, log, and result rather than raising — so a failed relaxation is data, not an exception.
+
+## Engines
+
+| Engine | Status |
+|---|---|
+| ASE | Working. Local relaxation via the EMT empirical potential (11 elements: Ag, Al, Au, C, Cu, H, N, Ni, O, Pd, Pt). |
+| LAMMPS | Stub — environment-specific, returns a structured failure |
+| Quantum ESPRESSO | Stub — site-specific paths and pseudopotentials, returns a structured failure |
+
+> **Note on scope.** EMT is a fast empirical potential with narrow element coverage; it is suitable for smoke-testing a workflow end to end, not for producing quantitative results. Universal ML interatomic potentials are the intended path to periodic-table-wide coverage.
+
+Externally produced results can be validated with
+`mattergraph_sim.parsers.parse_result_envelope`. This is result interchange only; it does not
+launch, route, or coordinate simulation engines.
+
+## Install
+
+```bash
+pip install mattergraph-sim
+```
+
+## Example
+
+```python
+from mattergraph_sim import AseJobSpec, SimulationJob, ase_relax
+
+job = SimulationJob(spec=AseJobSpec(fmax=0.05, max_steps=200), input_structure=structure.model_dump())
+done = ase_relax(job)
+print(done.status, done.result.energy if done.result else done.error)
+```
+
+## License
+
+Apache-2.0

mattergraph_sim-0.1.0/README.md

@@ -0,0 +1,39 @@
+# mattergraph-sim
+
+Simulation job specs and runners for [MatterGraph](https://github.com/cyrusmo/MatterGraph).
+
+Structures round-trip through pymatgen, jobs are declared as validated Pydantic specs, and runners return a structured `SimulationJob` with status, log, and result rather than raising — so a failed relaxation is data, not an exception.
+
+## Engines
+
+| Engine | Status |
+|---|---|
+| ASE | Working. Local relaxation via the EMT empirical potential (11 elements: Ag, Al, Au, C, Cu, H, N, Ni, O, Pd, Pt). |
+| LAMMPS | Stub — environment-specific, returns a structured failure |
+| Quantum ESPRESSO | Stub — site-specific paths and pseudopotentials, returns a structured failure |
+
+> **Note on scope.** EMT is a fast empirical potential with narrow element coverage; it is suitable for smoke-testing a workflow end to end, not for producing quantitative results. Universal ML interatomic potentials are the intended path to periodic-table-wide coverage.
+
+Externally produced results can be validated with
+`mattergraph_sim.parsers.parse_result_envelope`. This is result interchange only; it does not
+launch, route, or coordinate simulation engines.
+
+## Install
+
+```bash
+pip install mattergraph-sim
+```
+
+## Example
+
+```python
+from mattergraph_sim import AseJobSpec, SimulationJob, ase_relax
+
+job = SimulationJob(spec=AseJobSpec(fmax=0.05, max_steps=200), input_structure=structure.model_dump())
+done = ase_relax(job)
+print(done.status, done.result.energy if done.result else done.error)
+```
+
+## License
+
+Apache-2.0

mattergraph_sim-0.1.0/mattergraph_sim/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+  from mattergraph_sim.ase_runner import ase_relax
+  from mattergraph_sim.job_spec import AseJobSpec, SimulationJob, SimulationResult
+
+_EXPORTS: dict[str, tuple[str, str, str | None]] = {
+  "AseJobSpec": (
+    "mattergraph_sim.job_spec",
+    "AseJobSpec",
+    None,
+  ),
+  "SimulationJob": (
+    "mattergraph_sim.job_spec",
+    "SimulationJob",
+    None,
+  ),
+  "SimulationResult": (
+    "mattergraph_sim.job_spec",
+    "SimulationResult",
+    None,
+  ),
+  "ase_relax": (
+    "mattergraph_sim.ase_runner",
+    "ase_relax",
+    (
+      "Install the optional `ase` dependency or run "
+      "`uv sync --all-packages --group dev` to use ase_relax."
+    ),
+  ),
+}
+
+__all__ = [
+  "AseJobSpec",
+  "SimulationJob",
+  "SimulationResult",
+  "ase_relax",
+]
+
+
+def __getattr__(name: str) -> Any:
+  if name not in _EXPORTS:
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
+  module_name, attr_name, hint = _EXPORTS[name]
+  try:
+    module = import_module(module_name)
+  except ImportError as e:
+    if hint is None:
+      raise
+    raise ImportError(hint) from e
+  value = getattr(module, attr_name)
+  globals()[name] = value
+  return value
+
+
+def __dir__() -> list[str]:
+  return sorted(set(globals()) | set(__all__))

mattergraph_sim-0.1.0/mattergraph_sim/ase_runner.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import contextlib
+import io
+from typing import Any
+
+import numpy as np
+from mattergraph.schema.structure import CrystalStructure
+
+from mattergraph_sim.job_spec import AseJobSpec, SimulationJob, SimulationResult
+
+EMT_SUPPORTED_SPECIES = (
+  "Ag",
+  "Al",
+  "Au",
+  "C",
+  "Cu",
+  "H",
+  "N",
+  "Ni",
+  "O",
+  "Pd",
+  "Pt",
+)
+
+
+def _load_ase() -> tuple[Any, Any, Any]:
+  try:
+    from ase.calculators.emt import EMT
+    from ase.optimize import BFGS
+    from pymatgen.io.ase import AseAtomsAdaptor
+  except ImportError as e:
+    msg = "Install the optional `ase` dependency to run local ASE relaxations."
+    raise ImportError(msg) from e
+  return EMT, BFGS, AseAtomsAdaptor
+
+
+def _failure(job: SimulationJob, error: str) -> SimulationJob:
+  return job.model_copy(
+    update={
+      "status": "failed",
+      "error": error,
+      "log": error,
+      "result": None,
+    }
+  )
+
+
+def _supported_species_for(calc_name: str) -> tuple[str, ...]:
+  if calc_name == "emt":
+    return EMT_SUPPORTED_SPECIES
+  return ()
+
+
+def _unsupported_species(structure: Any, calc_name: str) -> list[str]:
+  supported = set(_supported_species_for(calc_name))
+  symbols = set(structure.composition.element_composition.as_dict())
+  return sorted(symbols - supported)
+
+
+def ase_relax(job: SimulationJob) -> SimulationJob:
+  """
+  Local relaxation using ASE + EMT (MVP). Swap calculators for your own backend as needed.
+  """
+  EMT, BFGS, _ = _load_ase()
+  running = job.model_copy(update={"status": "running", "error": None})
+
+  try:
+    spec: AseJobSpec = running.spec
+    if running.kind != "relax":
+      return _failure(running, f"ASE runner only supports kind='relax'; got {running.kind!r}")
+
+    structure = CrystalStructure.model_validate(running.input_structure).to_pymatgen()
+    unsupported = _unsupported_species(structure, spec.calc_name)
+    if unsupported:
+      supported = ", ".join(_supported_species_for(spec.calc_name))
+      bad = ", ".join(unsupported)
+      return _failure(
+        running,
+        f"ASE {spec.calc_name} does not support species: {bad}. Supported species: {supported}.",
+      )
+
+    _, _, AseAtomsAdaptor = _load_ase()
+    atoms = AseAtomsAdaptor.get_atoms(structure)  # type: ignore[assignment]
+    atoms.calc = EMT()
+
+    optimizer_log = io.StringIO()
+    with contextlib.redirect_stdout(optimizer_log), contextlib.redirect_stderr(optimizer_log):
+      opt = BFGS(atoms, logfile=optimizer_log)
+      converged = bool(opt.run(fmax=spec.fmax, steps=spec.max_steps))
+
+    forces = atoms.get_forces() if atoms.calc is not None else None
+    energy = float(atoms.get_potential_energy()) if atoms.calc is not None else None
+    max_force = None
+    if forces is not None and len(forces) > 0:
+      max_force = float(np.linalg.norm(forces, axis=1).max())
+
+    relaxed_structure = CrystalStructure.from_pymatgen(AseAtomsAdaptor.get_structure(atoms))
+    steps = int(getattr(opt, "nsteps", 0))
+    summary = (
+      f"calculator={spec.calc_name} energy={energy!s} max_force={max_force!s} "
+      f"steps={steps} converged={converged}"
+    )
+    raw_log = optimizer_log.getvalue().strip()
+    log = summary if not raw_log else f"{summary}\n{raw_log}"
+
+    return running.model_copy(
+      update={
+        "status": "completed",
+        "log": log,
+        "result": SimulationResult(
+          engine=spec.engine,
+          calculator=spec.calc_name,
+          converged=converged,
+          steps=steps,
+          energy=energy,
+          max_force=max_force,
+          relaxed_structure=relaxed_structure,
+        ),
+      }
+    )
+  except ImportError:
+    raise
+  except Exception as e:  # noqa: BLE001
+    return _failure(running, f"{type(e).__name__}: {e}")

mattergraph_sim-0.1.0/mattergraph_sim/job_spec.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import uuid
+from typing import Any, Literal
+
+from mattergraph.schema.structure import CrystalStructure
+from pydantic import BaseModel, Field, field_validator
+
+_SUPPORTED_ASE_CALCULATORS = {"emt"}
+
+
+class AseJobSpec(BaseModel):
+  engine: Literal["ase"] = "ase"
+  calc_name: str = "emt"
+  fmax: float = 0.05
+  max_steps: int = 200
+  n_cores: int = 1
+
+  @field_validator("calc_name")
+  @classmethod
+  def _normalize_calc_name(cls, value: str) -> str:
+    calc_name = value.strip().lower()
+    if calc_name not in _SUPPORTED_ASE_CALCULATORS:
+      supported = ", ".join(sorted(_SUPPORTED_ASE_CALCULATORS))
+      msg = f"unsupported ASE calculator {calc_name!r}; supported calculators: {supported}"
+      raise ValueError(msg)
+    return calc_name
+
+  @field_validator("fmax")
+  @classmethod
+  def _positive_fmax(cls, value: float) -> float:
+    if value <= 0:
+      msg = "fmax must be positive"
+      raise ValueError(msg)
+    return value
+
+  @field_validator("max_steps", "n_cores")
+  @classmethod
+  def _positive_ints(cls, value: int, info: Any) -> int:
+    if value < 1:
+      msg = f"{info.field_name} must be at least 1"
+      raise ValueError(msg)
+    return value
+
+
+class SimulationResult(BaseModel):
+  engine: str
+  calculator: str
+  converged: bool | None = None
+  steps: int | None = None
+  energy: float | None = None
+  max_force: float | None = None
+  relaxed_structure: CrystalStructure | None = None
+
+
+class SimulationJob(BaseModel):
+  job_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+  spec: AseJobSpec
+  input_structure: dict[str, Any] = Field(
+    default_factory=dict,
+    description="Serialized :class:`CrystalStructure` or pymatgen dict",
+  )
+  kind: Literal["relax", "sc", "md"] = "relax"
+  status: Literal["pending", "running", "completed", "failed"] = "pending"
+  result_uri: str | None = None
+  result: SimulationResult | None = None
+  error: str | None = None
+  log: str | None = None

mattergraph_sim-0.1.0/mattergraph_sim/lammps_runner.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from mattergraph_sim.job_spec import SimulationJob
+
+
+def run_lammps(_job: SimulationJob) -> SimulationJob:
+  """Stub: LAMMPS integration is environment-specific. Implement where binaries exist."""
+  return _job.model_copy(
+    update={
+      "status": "failed",
+      "error": "LAMMPS runner not installed (stub).",
+      "log": "LAMMPS runner not installed (stub).",
+      "result": None,
+    }
+  )

mattergraph_sim-0.1.0/mattergraph_sim/parsers/__init__.py

@@ -0,0 +1,5 @@
+"""Validation helpers for externally produced simulation-result evidence."""
+
+from mattergraph_sim.parsers.envelope import parse_result_envelope
+
+__all__ = ["parse_result_envelope"]

mattergraph_sim-0.1.0/mattergraph_sim/parsers/envelope.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from mattergraph import SimulationResultEnvelope
+
+
+def parse_result_envelope(
+  payload: str | bytes | Mapping[str, Any],
+) -> SimulationResultEnvelope:
+  """Validate an external JSON result envelope without launching an engine."""
+  if isinstance(payload, bytes):
+    payload = payload.decode("utf-8")
+  if isinstance(payload, str):
+    value = json.loads(payload)
+  else:
+    value = dict(payload)
+  if not isinstance(value, dict):
+    msg = "simulation result envelope must be a JSON object"
+    raise ValueError(msg)
+  return SimulationResultEnvelope.model_validate(value)
+
+
+__all__ = ["parse_result_envelope"]

mattergraph_sim-0.1.0/mattergraph_sim/qe_runner.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from mattergraph_sim.job_spec import SimulationJob
+
+
+def run_quantum_espresso(_job: SimulationJob) -> SimulationJob:
+  """Stub: QE paths and pseudos are site-specific. Wire up in your environment."""
+  return _job.model_copy(
+    update={
+      "status": "failed",
+      "error": "QE runner not installed (stub).",
+      "log": "QE runner not installed (stub).",
+      "result": None,
+    }
+  )

mattergraph_sim-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "mattergraph-sim"
+version = "0.1.0"
+description = "ASE/LAMMPS/QE simulation job specs and runners (MVP wrappers)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "MatterGraph contributors" }]
+keywords = ["materials-science", "simulation", "ase", "lammps", "quantum-espresso"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Chemistry",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "mattergraph-core~=0.1.0",
+  "pymatgen>=2024.1.1",
+  "pydantic>=2.5",
+  "ase>=3.22",
+]
+
+[project.urls]
+Homepage = "https://github.com/cyrusmo/MatterGraph"
+Repository = "https://github.com/cyrusmo/MatterGraph"
+Issues = "https://github.com/cyrusmo/MatterGraph/issues"
+Changelog = "https://github.com/cyrusmo/MatterGraph/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+mattergraph-core = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["mattergraph_sim"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"

mattergraph_sim-0.1.0/tests/test_ase_runner.py

@@ -0,0 +1,64 @@
+from typing import Literal
+
+from mattergraph.schema.structure import CrystalStructure
+from mattergraph_sim.ase_runner import ase_relax
+from mattergraph_sim.job_spec import AseJobSpec, SimulationJob
+
+
+def _job_for(
+  structure: CrystalStructure,
+  *,
+  kind: Literal["relax", "sc", "md"] = "relax",
+) -> SimulationJob:
+  return SimulationJob(
+    spec=AseJobSpec(),
+    input_structure=structure.to_json_dict(),
+    kind=kind,
+  )
+
+
+def test_ase_relax_returns_structured_result_for_supported_species() -> None:
+  structure = CrystalStructure(
+    lattice=[[4.04, 0.0, 0.0], [0.0, 4.04, 0.0], [0.0, 0.0, 4.04]],
+    species=["Al"],
+    coords=[[0.0, 0.0, 0.0]],
+  )
+
+  out = ase_relax(_job_for(structure))
+
+  assert out.status == "completed"
+  assert out.error is None
+  assert out.result is not None
+  assert out.result.calculator == "emt"
+  assert out.result.energy is not None
+  assert out.result.max_force is not None
+  assert out.result.relaxed_structure is not None
+  assert "calculator=emt" in (out.log or "")
+
+
+def test_ase_relax_fails_gracefully_for_unsupported_species() -> None:
+  structure = CrystalStructure(
+    lattice=[[2.8, 0.0, 0.0], [0.0, 2.8, 0.0], [0.0, 0.0, 2.8]],
+    species=["Fe"],
+    coords=[[0.0, 0.0, 0.0]],
+  )
+
+  out = ase_relax(_job_for(structure))
+
+  assert out.status == "failed"
+  assert out.result is None
+  assert out.error is not None
+  assert "does not support species: Fe" in out.error
+
+
+def test_ase_relax_rejects_non_relax_jobs() -> None:
+  structure = CrystalStructure(
+    lattice=[[4.04, 0.0, 0.0], [0.0, 4.04, 0.0], [0.0, 0.0, 4.04]],
+    species=["Al"],
+    coords=[[0.0, 0.0, 0.0]],
+  )
+
+  out = ase_relax(_job_for(structure, kind="md"))
+
+  assert out.status == "failed"
+  assert out.error == "ASE runner only supports kind='relax'; got 'md'"

mattergraph_sim-0.1.0/tests/test_job_spec.py

@@ -0,0 +1,23 @@
+import pytest
+from mattergraph_sim.job_spec import AseJobSpec, SimulationJob
+from mattergraph_sim.lammps_runner import run_lammps
+
+
+def test_simulation_job_defaults() -> None:
+  job = SimulationJob(spec=AseJobSpec(), input_structure={})
+  assert job.kind == "relax"
+  assert job.status == "pending"
+  assert job.result is None
+  assert job.error is None
+  failed = run_lammps(job)
+  assert failed.status == "failed"
+  assert failed.error == "LAMMPS runner not installed (stub)."
+
+
+def test_job_spec_rejects_invalid_values() -> None:
+  with pytest.raises(ValueError, match="unsupported ASE calculator"):
+    AseJobSpec(calc_name="lj")
+  with pytest.raises(ValueError, match="fmax must be positive"):
+    AseJobSpec(fmax=0.0)
+  with pytest.raises(ValueError, match="max_steps must be at least 1"):
+    AseJobSpec(max_steps=0)

mattergraph_sim-0.1.0/tests/test_result_parser.py

@@ -0,0 +1,31 @@
+import json
+
+import pytest
+from mattergraph_sim.parsers import parse_result_envelope
+
+
+def test_parse_external_result_envelope() -> None:
+  result = parse_result_envelope(
+    json.dumps(
+      {
+        "engine": "lammps",
+        "engine_version": "stable_29Aug2024",
+        "method": "external result import",
+        "parameters": {"units": "metal"},
+        "input_checksum_sha256": "a" * 64,
+        "output_checksum_sha256": "b" * 64,
+        "converged": True,
+      }
+    )
+  )
+  assert result.engine == "lammps"
+  assert result.converged is True
+
+
+def test_parser_rejects_non_object_and_bad_checksum() -> None:
+  with pytest.raises(ValueError, match="JSON object"):
+    parse_result_envelope("[]")
+  with pytest.raises(ValueError, match="64-character"):
+    parse_result_envelope(
+      {"engine": "custom", "method": "import", "input_checksum_sha256": "bad"}
+    )

mattergraph_sim-0.1.0/tests/test_sim_optional_imports.py

@@ -0,0 +1,22 @@
+import importlib
+
+import mattergraph_sim
+import pytest
+
+
+def test_ase_relax_has_helpful_optional_dependency_error(
+  monkeypatch: pytest.MonkeyPatch,
+) -> None:
+  module = importlib.reload(mattergraph_sim)
+  module.__dict__.pop("ase_relax", None)
+  real_import_module = module.import_module
+
+  def fake_import_module(name: str, package: str | None = None) -> object:
+    if name == "mattergraph_sim.ase_runner":
+      raise ImportError("No module named 'ase'")
+    return real_import_module(name, package)
+
+  monkeypatch.setattr(module, "import_module", fake_import_module)
+
+  with pytest.raises(ImportError, match="optional `ase`"):
+    _ = module.ase_relax