mattergraph-sim 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+mattergraph_sim/__init__.py,sha256=YLiZiLngYEZk8WvrTNY1kGnaQ4t9NCwS5zkjiC03KlI,1374
+mattergraph_sim/ase_runner.py,sha256=4gqh_xRTV9UpyC2SlU6R2rV3xHhnHC0yUkZMYfS7N6I,3709
+mattergraph_sim/job_spec.py,sha256=lSlDz_Tc-4mUwsD4v7XFJ39aqFTCX1JZyd_01inJ8ro,1957
+mattergraph_sim/lammps_runner.py,sha256=mWS0tSQjK9wgHBtjNSioaatiH8bMxxpAgqd68Foe6jk,436
+mattergraph_sim/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mattergraph_sim/qe_runner.py,sha256=a0vcuDVjpSRLJb9HZWWTwcBMSlR9S0ihuNISZkGDQqw,431
+mattergraph_sim/parsers/__init__.py,sha256=ExJnEtf6qEOuT5YnbFxACD5JpFMcmJYr7IB-0chwcYo,182
+mattergraph_sim/parsers/envelope.py,sha256=3gv5x6hXMLM3k8jEqBfKw5r11XtrRaYf288XKXARUOA,723
+mattergraph_sim-0.1.0.dist-info/METADATA,sha256=9DexeHxndclLanAWhnuVHPXAGdIeWQBuOYPKhEU9bz0,2711
+mattergraph_sim-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mattergraph_sim-0.1.0.dist-info/RECORD,,

mattergraph_sim-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any