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
