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.2.0 Update)

• 🧠 PyTorch CGCNN Integrated: Leverages a custom PyTorch architecture inspired by Crystal Graph Convolutional Neural Networks (CGCNN) for advanced property predictions.
• ⚡ Ultra-Fast Engine: Built on top of Astral's uv for lightning-fast environment management.
• 📊 Advanced Filtering & Export: Filter structures by Band Gap and Crystal System, and instantly export feature-rich datasets to CSV or JSON.
• 🌐 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.

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

matgraph predict LiFePO4

Advanced Search & Filtering Filter materials based on physical constraints:

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

Dataset Export for ML Engineers Save extracted structural features and predictions directly into a dataset for offline training:

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

🌐 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) {
    materialId
    formula
    crystalSystem
    trueBandGap
    predictedBandGap
    features {
      density
      numElements
      volume
    }
    metrics {
      modelName
      confidenceScore
    }
  }
}

📦 Releases & Changelog

v0.2.x (Current - Advanced ML Update)

• 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.