Metadata-Version: 2.4
Name: mattergraph
Version: 0.1.1
Summary: Open-source materials data infrastructure for physics-aware ML and simulation workflows.
Author: MatterGraph contributors
License-Expression: Apache-2.0
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
Keywords: materials-science,materials-informatics,crystal-structure,dft,machine-learning,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
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mattergraph-core~=0.1.1
Requires-Dist: mattergraph-connectors~=0.1.1
Requires-Dist: mattergraph-benchmarks~=0.1.1
Requires-Dist: mattergraph-sim~=0.1.1
Requires-Dist: mattergraph-api~=0.1.1
Provides-Extra: mp
Requires-Dist: mattergraph-connectors[mp]~=0.1.1; extra == "mp"
Provides-Extra: jarvis
Requires-Dist: mattergraph-connectors[jarvis]~=0.1.1; extra == "jarvis"
Provides-Extra: all
Requires-Dist: mattergraph-connectors[all]~=0.1.1; extra == "all"
Dynamic: license-file

# MatterGraph

[![PyPI](https://img.shields.io/pypi/v/mattergraph?cacheSeconds=300)](https://pypi.org/project/mattergraph/)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-Apache--2.0-green)
[![Docs](https://github.com/cyrusmo/MatterGraph/actions/workflows/docs.yml/badge.svg)](https://cyrusmo.github.io/MatterGraph/)
![Status](https://img.shields.io/badge/status-alpha-orange)

MatterGraph is an open-source SDK and workbench for physics-aware materials workflows.

It helps researchers and developers turn standardized materials datasets into graph-ready, benchmark-ready, and candidate-screening artifacts. MatterGraph is dataset-agnostic and supports multi-source workflows across public materials resources.

LeMaterial is a flagship upstream companion: LeMaterial provides standardized materials datasets; MatterGraph provides the downstream workflow surface for inspection, filtering, graph export, slicing, and evaluation.

It is designed for teams building:

- materials screening and comparison tools
- graph-based materials ML models
- simulation-backed discovery workflows
- uncertainty-aware engineering decision support

MatterGraph is **not** a black-box “AI materials scientist.” It is **infrastructure** for transparent, physics-aware materials workflows.

## Why MatterGraph?

Materials data is fragmented across repositories, schemas, units, structures, and property definitions. MatterGraph provides a **common, provenance-aware layer** for turning raw materials records into normalized, ML-ready, simulation-aware material objects.

## What it does

- Ingest public materials datasets
- Normalize formulas, structures, units, and properties
- Convert crystal structures into **crystal graph** representations
- Track property provenance and basic confidence
- Support **transparent baseline** scorecards with auditable ranking behavior
- Provide adapters for benchmarking and **simulation job specs** (e.g. ASE)
- Expose a **small demo API** and **minimal web UI** for end-to-end exploration
- Inspect, validate, graph, rank, and export small local CSV/JSONL datasets without uploading them
- Compile natural-language requirements into confirmed constraints, exact exclusions, and
  index-relative recovery paths with the Constraint-to-Crystal Navigator

## Scope

The public repository focuses on transparent, reusable infrastructure for open materials workflows. Production-specific orchestration, hosting, and organization-specific workflows are out of scope for this demo.

MatterGraph Core focuses on transparent workflow primitives and guardrails. Proprietary ranking, active learning, orchestration, model routing, and customer-specific decision workflows remain private.

## Install

MatterGraph is published on [PyPI](https://pypi.org/project/mattergraph/) for Python 3.10 and
newer. Wheels, source distributions, and provenance are also attached to each
[GitHub release](https://github.com/cyrusmo/MatterGraph/releases).

```bash
pip install mattergraph
```

That installs the public toolkit without provider-specific SDKs. Opt into only the connector
SDKs you need:

```bash
pip install 'mattergraph[mp]'       # Materials Project SDK
pip install 'mattergraph[jarvis]'   # JARVIS SDK
pip install 'mattergraph[all]'      # all optional public connector SDKs
```

Install an individual package for a smaller application surface:

```bash
pip install mattergraph-core         # schema, normalization, graphs, scoring
pip install mattergraph-connectors   # NOMAD, OPTIMADE, local data, LeMat-Bulk
pip install mattergraph-sim          # ASE job specs and runners
pip install mattergraph-benchmarks   # metrics and Matbench adapter
pip install mattergraph-api          # FastAPI demo service
```

## Ten-minute quickstart from PyPI

The attributed 24-record Ti–Al–N example is bundled with `mattergraph-connectors`. It needs no
credentials, network access, repository checkout, or external data path.

```python
from mattergraph_connectors import LeMatBulk

dataset = LeMatBulk.example("spc-tialn-24")
manifest = dataset.metadata["snapshot_manifest"]
candidate_slice = (
    dataset
    .filter_elements(include=["Ti", "Al", "N"])
    .filter_complexity(max_nsites=16, max_nelements=3)
    .create_slice("spc_tialn_candidates_v1", target="energy_above_hull")
)
graphs = dataset.to_graphs()

print(manifest["dataset"], manifest["license"], manifest["snapshot_sha256"])
print(candidate_slice.report())
print(graphs.included_count, graphs.excluded_count)
```

Run the installed API from any working directory:

```bash
python -m uvicorn mattergraph_api.main:app --host 127.0.0.1 --port 8000
```

`GET /demo/preflight` reports the same packaged fixture, graph validation, ranking readiness,
and explicitly labelled cached CHGNet evidence.

## Run the web workbench from source

```bash
git clone https://github.com/cyrusmo/MatterGraph.git
cd MatterGraph
python3 -m venv .venv
source .venv/bin/activate
pip install uv
uv sync --all-packages --group dev --extra all
# Optional: copy .env.example to .env and set MP_API_KEY for Materials Project
export MATTERGRAPH_DEMO_DATA=data/demo/materials_sample.jsonl
uv run uvicorn mattergraph_api.main:app --reload --host 0.0.0.0 --port 8000
```

For the deterministic public capability walkthrough, start the API and UI together:

```bash
./scripts/run_public_demo.sh
```

This runs a preflight-checked, checksummed snapshot of 24 real LeMaterial records at
`http://127.0.0.1:5173` without network calls or API credentials. The snapshot preserves the
upstream revision, immutable IDs, license, citation, and field-level provenance.

The UI opens in **Guided demo** mode. Choose **Local workbench** to inspect a CSV or JSONL file
up to 5 MiB / 5,000 rows. Imported datasets are ephemeral: normalized JSONL remains in memory,
the registry is capped at eight entries and 32 MiB, and only the selected dataset is
materialized. Imported content is never sent to an external service or written to disk.

Choose **Constraint navigator**, or open `/?view=navigator`, for the provenance-backed
constraint-to-crystal workflow. The bundled UI truthfully identifies its 24-record evidence
surface; see [the navigator contract](docs/navigator.md) for the deterministic 25,000-record index
builder and Hugging Face release gate.

Example: rank candidates with a **transparent baseline scorecard** (pool-relative min–max
objectives plus hard constraints).

```python
from mattergraph import Scorecard
from mattergraph_connectors import LeMatBulk

store = LeMatBulk.example("spc-tialn-24").to_material_store()
scorecard = Scorecard(
    objectives={
        "density": {"direction": "minimize", "weight": 0.6},
        "energy_above_hull": {"direction": "minimize", "weight": 0.4},
    },
    constraints={
        "energy_above_hull": {"max": 0.05},
        "max_force": {"max": 0.2},
    },
)
df = scorecard.rank(store.materials)
print(df.head(10))
```

Example: turn LeMaterial-style records into a reproducible candidate slice.

```python
from mattergraph_connectors import LeMatBulk

dataset = LeMatBulk.example("spc-tialn-24")

candidate_slice = (
    dataset
    .filter_elements(include=["Ti", "Al", "N"])
    .filter_complexity(max_nsites=16, max_nelements=3)
    .create_slice("spc_tialn_candidates_v1", target="energy_above_hull")
)

print(candidate_slice.report())
```

## Architecture (conceptual)

```text
Raw dataset → MatterGraphDataset / Material → candidate slice / crystal graph / benchmark frame → scorecard or simulation job
```

## Roadmap

High-level [ROADMAP.md](ROADMAP.md) covers connectors, the unified schema, workflow slicing, graph building, benchmark adapters, simulation interchange, and uncertainty. For the LeMaterial companion layer, see [docs/integrations/lematerial.md](docs/integrations/lematerial.md), and for local data see [docs/local-workbench.md](docs/local-workbench.md).

## Packages

| Package | Role |
|--------|------|
| `mattergraph-core` | Schema, normalization, `MatterGraphDataset`, `CandidateSlice`, crystal graphs, transparent `Scorecard`, `MaterialStore` |
| `mattergraph-connectors` | MP, JARVIS, NOMAD public metadata, OPTIMADE, LeMat-Bulk companion adapter, bounded local CSV/JSONL import, OQMD stub |
| `mattergraph-benchmarks` | Metrics, Matbench-style adapter (optional `matbench` install) |
| `mattergraph-sim` | ASE / stub LAMMPS+QE around job specs |
| `mattergraph-api` | FastAPI demo plus ephemeral local-dataset registry, graph summaries, slicing, audited ranking, export, and labeled CHGNet reference evidence |

## License

Apache 2.0 — see [LICENSE](LICENSE).
