MatGraph abstracts away the complexity of deep learning for material properties. Designed for both Material Science researchers and ML engineers, it provides a seamless interface to fetch, featurize, predict, and export crystal structures—all powered by modern technologies like PyTorch, GraphQL, and uv.

Key Features (v0.4.0 Update)

• Analytics & Evaluation: New evaluate command computes Mean Absolute Error (MAE) comparing PyTorch predictions directly against Materials Project ground truth.
• Raw Structure Export: Automatically export raw 3D crystal structures to standard .cif (Crystallographic Information File) formats.
• Dual Architecture Support: Integrated PyTorch architecture for both Crystal Graph Convolutional Neural Networks (CGCNN) and MatErials Graph Network (MEGNet).
• Multi-Property Predictions: Now predicts both Band Gap and Formation Energy per atom in real-time.
• Ultra-Fast Engine: Built on top of Astral's uv for lightning-fast environment management.
• Modern Async GraphQL API: Fully asynchronous resolvers via Strawberry & FastAPI, providing rich schemas and nested model metrics.
• Sleek CLI: Beautiful, table-formatted terminal outputs powered by Typer and Rich.

Installation

We recommend using uv for the fastest installation experience.

# Install via uv (Recommended)
uv tool install matgraph-cli

# Or via standard pip
pip install matgraph-cli

Authentication Setup

To fetch high-fidelity data, you need a free API key from the Materials Project.

export MP_API_KEY="your_api_key_here"

Tip: You can verify your setup anytime by running matgraph setup <YOUR_KEY>.

Usage: The Productive CLI

MatGraph's CLI is designed to be highly intuitive.

1. Analytics & Model Evaluation Evaluate the accuracy (MAE) of a specific architecture against true scientific data:

matgraph evaluate LiFePO4 --model megnet

2. Basic Prediction Pipeline (Defaults to CGCNN) Run the end-to-end pipeline (Fetch → Featurize → Predict) for a specific chemical formula:

matgraph predict LiFePO4

3. Use MEGNet Architecture Switch models easily to use the MEGNet architecture for Formation Energy and Band Gap:

matgraph predict LiFePO4 --model megnet

4. Advanced Search & Filtering Filter materials based on physical constraints:

matgraph predict LiFePO4 --min-gap 1.5 --crystal-system Cubic --model megnet

5. Structure & Dataset Export for ML Engineers Save extracted predictions directly to a dataset (CSV/JSON), and optionally export the 3D .cif files for offline processing:

matgraph predict LiFePO4 --min-gap 2.0 --save dataset.csv --format csv --cif

Usage: The Modern GraphQL API

Integrate MatGraph into your own web applications seamlessly using our robust, async GraphQL engine.

Start the Server:

matgraph serve --port 8000

Navigate to http://localhost:8000/graphql to explore the interactive GraphiQL playground.

Example Query:

query {
  predictMaterial(formula: "NaCl", minGap: 1.0, limit: 3, model: "megnet") {
    materialId
    formula
    crystalSystem
    trueBandGap
    predictedBandGap
    trueFormEnergy
    predictedFormEnergy
    features {
      density
      numElements
      volume
    }
    metrics {
      modelName
      confidenceScore
    }
  }
}

Releases & Changelog

v0.3.x (Current - Multi-Property & MEGNet Update)

• Feature: Implemented PyTorch MEGNet model (matgraph/megnet.py).
• Feature: Support for Formation Energy predictions alongside Band Gap.
• Feature: Added --model megnet flag and GraphQL model: "megnet" argument.
• Feature: Integrated PyTorch architecture (CrystalGraphConvNet) replacing legacy dummy models.
• Feature: Advanced CLI filtering (--min-gap, --max-gap, --crystal-system).
• Feature: One-command dataset exporting (--save, --format).
• Improvement: GraphQL schema modernized with detailed ModelMetrics and GraphQL pagination filters.

v0.1.x (Initial Release)

• Initial end-to-end pipeline with MP-API fetching and basic feature extraction.
• GraphQL Server & basic Typer CLI introduced.
• Project migrated to uv build backend for maximum efficiency.

Contributing & Architecture

MatGraph is built on a robust, modern Python stack:

• ML & Science: PyTorch, PyMatGen, Scikit-Learn, MP-API
• API & CLI: FastAPI, Strawberry GraphQL, Typer, Rich
• Packaging: uv (Hatchling)

We welcome contributions! To set up for local development:

git clone https://github.com/Himan-D/matgraph-cli.git
cd matgraph-cli
uv sync
uv run pytest

Please open an issue before submitting major pull requests.