CrystalMind

Scientific machine learning system predicting physical and thermodynamic properties of solid-state crystalline materials directly from Crystallographic Information Files (CIF) using Crystal Graph Convolutional Neural Networks (CGCNN).

---

Overview

Traditional materials discovery relies on computationally demanding Density Functional Theory (DFT) calculations, requiring hours to days of compute per crystal structure.

CrystalMind refactors and packages the Crystal Graph Convolutional Neural Network (CGCNN) framework (pioneered by Xie & Grossman) into an offline prediction and visualization suite. By representing infinite periodic crystal lattices as multigraphs with atom-level feature vectors and distance-expanded edge tensors, the system maps crystal geometry directly to 8 fundamental physical, mechanical, and electronic properties in milliseconds.

---

Architecture & Graph Construction

flowchart TD
    CIF[".cif Structure File (Lattice Vectors & Fractional Coordinates)"] --> Parser[pymatgen Structure Parser]
    
    subgraph Graph Construction
        Parser --> Nodes[Atom Nodes: Initialized with 92-dim Feature Vectors]
        Parser --> Periodic[Periodic Boundary Neighbor Search: r <= 8.0 Angstroms]
        Periodic --> Edges[Edge Tensors: 41 Gaussian Expanded Distance Bins]
    end

    Nodes & Edges --> ConvLayers[Gated Graph Convolutional Layers: 3-5 Layers]
    
    subgraph CGCNN Forward Pass
        ConvLayers --> GatedConv["v_i^(t+1) = v_i^(t) + Sum( σ(z_ij W_f + b_f) ⊙ g(z_ij W_s + b_s) )"]
        GatedConv --> Pool[Global Normalized Mean Pooling]
    end

    Pool --> Hidden[Hidden Dense Layer: 128-dim + Softplus]
    Hidden --> MultiHead{8 Pretrained Target Heads}

    subgraph Predicted Properties
        MultiHead --> P1[Band Gap in eV]
        MultiHead --> P2[Formation Energy per Atom in eV]
        MultiHead --> P3[Final Energy per Atom in eV]
        MultiHead --> P4[Fermi Energy in eV]
        MultiHead --> P5[Bulk Modulus in GPa]
        MultiHead --> P6[Shear Modulus in GPa]
        MultiHead --> P7[Poisson Ratio]
        MultiHead --> P8[Semi-Metal Binary Classification]
    end

Loading

---

Predicted Physical Properties

The pipeline interfaces with 8 distinct model checkpoints targeting different physical domains:

Property	Symbol	Units	Prediction Type
Band Gap	$E_g$	eV	Regression
Formation Energy per Atom	$E_f$	eV/atom	Regression
Final Energy per Atom	$E_{\text{total}}$	eV/atom	Regression
Fermi Energy	$E_F$	eV	Regression
Bulk Modulus (Voigt-Reuss-Hill)	$K_{VRH}$	GPa	Regression
Shear Modulus (Voigt-Reuss-Hill)	$G_{VRH}$	GPa	Regression
Poisson Ratio	$\nu$	Dimensionless	Regression
Semi-Metal Classification	-	Binary	Classification (Softmax Logits)

---

Example Inference Outputs

Outputs generated from sample CIF structures during validation:

• Silicon (mp-149):
  • Formation energy per atom: 1.6944 eV/atom (Example inference output)
  • Successfully parsed lattice with 41-bin distance expansion.
• Batch Processing: Evaluated across multiple mineral and semiconductor CIFs (Alumina, Rutile, Nickel, MoS2) demonstrating sub-second forward-pass throughput per structure.

Note: Because published model weights were trained on normalized target distributions without embedded normalizer parameters in the checkpoints, raw modulus values reflect normalized scales unless denormalization offsets are provided.

---

Engineering Enhancements Over Baseline

1. Classification Logit Handling: Resolved a fatal PyTorch crash (RuntimeError: a Tensor with 2 elements cannot be converted to Scalar) by replacing .item() with torch.softmax() and torch.argmax() evaluation.
2. Model Caching: Refactored the inference loop to preload and cache all 8 model checkpoints into memory at server startup rather than reading .pth.tar weights from disk on every prediction.
3. Removed Heuristic NLP: Cleaned out pseudo-random text analysis routines present in exploratory notebooks, maintaining strict scientific integrity.

---

Technical Stack

• Deep Learning: PyTorch
• Materials Informatics: pymatgen (Python Materials Genomics), ase (Atomic Simulation Environment)
• 3D Molecular Graphics: py3Dmol, Matplotlib
• Web Interface: Gradio
• Language: Python 3.10+

---

Project Structure

crystalmind/
├── README.md
├── LICENSE
├── .gitignore
├── requirements.txt
├── app.py                          # Gradio web application
├── configs/
│   └── atom_init.json              # 92-dimensional elemental feature embeddings
├── src/
│   └── crystalmind/
│       ├── __init__.py
│       ├── model.py                # CrystalGraphConvNet & ConvLayer architecture
│       ├── data.py                 # CIFData parser, GaussianDistance, collate_pool
│       ├── predictor.py            # ModelManager service with memory caching
│       └── visualizer.py           # 3D structure rendering via ASE and py3Dmol
├── notebooks/
│   └── crystalmind_experiments.ipynb
└── tests/
    └── test_data.py                # Unit tests for CIF parsing and feature vectors

---

Installation & Setup

# Clone the repository
git clone https://github.com/Ayush-Sharma99/crystalmind.git
cd crystalmind

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download atomic feature definitions
curl -o configs/atom_init.json https://raw.githubusercontent.com/txie-93/cgcnn/master/data/sample-regression/atom_init.json

---

Usage

Run the Web Interface

python app.py

Run Tests

pytest tests/

---

Known Limitations

• Checkpoints Dependency: The repository contains the complete network architecture and data ingestion pipeline; execution requires pointing CRYSTALMIND_MODEL_DIR to the pretrained .pth.tar weights.
• Normalization Inversion: Modulus models output raw normalized predictions because normalization statistics (mean/std) were external to the original serialized checkpoints.
• Syntactic Parsing: Irregular or non-standard CIF formatting lacking fractional atomic coordinates may require pre-cleaning via pymatgen.io.cif.

---

License

MIT License. See LICENSE for details.

Author

Developed by Ayush Sharma.