MatterGraph

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 for Python 3.10 and newer. Wheels, source distributions, and provenance are also attached to each GitHub release.

pip install mattergraph

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

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:

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.

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:

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

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:

./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 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).

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.

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)

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

Roadmap

High-level 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, and for local data see docs/local-workbench.md.

Packages

License

Apache 2.0 — see LICENSE.