Metadata-Version: 2.4
Name: mattergraph-core
Version: 0.1.0
Summary: Core schema, normalization, and crystal graphs for MatterGraph.
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: crystal-structure,dft,materials-informatics,materials-science,pymatgen
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: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.5
Requires-Dist: pymatgen>=2024.1.1
Description-Content-Type: text/markdown

# mattergraph-core

Core schema, normalization, and crystal graphs for [MatterGraph](https://github.com/cyrusmo/MatterGraph) — an open-source SDK for physics-aware, provenance-aware materials workflows.

## What's in here

- **Schema** — `Material`, `MaterialProperty`, `ProvenanceRecord`, `CrystalStructure`, `SimulationJobRef`. Pydantic v2 models with strict validation (`extra="forbid"`), designed so multiple sources can report the same property without collapsing provenance.
- **Normalization** — unit conversion (energy, length, pressure, density, temperature), formula standardization, and canonical property names.
- **Crystal graphs** — `CrystalGraphBuilder` turns a pymatgen `Structure` into a periodic neighbor graph with atom and edge features. Emits plain NumPy, so there is no PyG/DGL dependency.
- **Workflow layer** — `MatterGraphDataset` and `CandidateSlice`: chainable, audited filters that produce reproducible, content-hashed candidate slices.
- **Scoring** — a deliberately transparent `Scorecard` baseline (min–max normalized objectives plus hard constraints). Not a production decision engine.

## Install

```bash
pip install mattergraph-core
```

## Example

```python
from mattergraph import MaterialStore, Scorecard

store = MaterialStore.from_demo()
scorecard = Scorecard(
    objectives={"density": "minimize", "bulk_modulus": "maximize"},
    constraints={"energy_above_hull": {"max": 0.05}},
)
print(scorecard.rank(store.materials).head())
```

## License

Apache-2.0
