Predicting Materials Band Gaps from Chemical Composition

A composition-based machine learning framework for predicting electronic band gaps of inorganic materials.

Quick Start · CLI Usage · Results · Contributing · Citation

---

Why This Project?

Band gap — the energy difference between a material's valence and conduction bands — determines whether a compound is a metal, semiconductor, or insulator. Accurate band gap prediction accelerates discovery of:

• Photovoltaic absorbers (optimal ~1.1–1.5 eV)
• LED phosphors and display materials
• Wide-gap power electronics (SiC, GaN replacements)
• Transparent conductors and dielectrics

This repository provides a complete, reproducible pipeline that predicts PBE-level DFT band gaps from chemical composition alone — no crystal structure required.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        INPUT                                     │
│              Chemical formula (e.g., "SrTiO3")                  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    FEATURIZATION                                  │
│         matminer Magpie preset → 132 descriptors                │
│   (electronegativity, atomic radius, valence electrons, ...)    │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                  ML REGRESSION                                    │
│         Random Forest  ·  XGBoost  ·  (extensible)              │
│                StandardScaler preprocessing                      │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                       OUTPUT                                     │
│         Predicted band gap (eV) + feature importance            │
└─────────────────────────────────────────────────────────────────┘

Benchmark Results

Model	R²	MAE (eV)	RMSE (eV)	Training Samples	Features
Random Forest	0.89	0.36	0.56	15,537	132 (Magpie)
XGBoost	0.91	0.32	0.51	15,537	132 (Magpie)

Note: Band gaps are PBE-GGA values from the Materials Project, which systematically underestimate experimental gaps. Relative trends and ranking remain valid.

Quick Start

Prerequisites

• Python 3.10+
• A free Materials Project API key (for data ingestion only)

Installation

# Clone the repository
git clone https://github.com/neweracy/Prediction-model.git
cd Prediction-model

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

Configure API Key

cp .env.example .env
# Edit .env and add your Materials Project API key

Run the Notebook

jupyter notebook bandgap_prediction.ipynb

Or run the full pipeline headlessly:

jupyter nbconvert --to notebook --execute bandgap_prediction.ipynb

CLI / API Usage

Use the trained model as a standalone prediction tool — no notebook required:

Command Line

# Single prediction
python predict.py SrTiO3

# Multiple formulas
python predict.py GaN ZnO CdTe Si3N4

# JSON output (for scripting / pipelines)
python predict.py --format json GaN ZnO

Example output:

Formula          Predicted Band Gap (eV)
─────────────────────────────────────────
SrTiO3           3.21
GaN              2.04
ZnO              1.87

Python API

from predict import BandGapPredictor

predictor = BandGapPredictor()  # Loads saved model from models/

# Single prediction
gap = predictor.predict("SrTiO3")
print(f"Predicted band gap: {gap:.3f} eV")

# Batch prediction
results = predictor.predict_batch(["GaN", "ZnO", "CdTe", "BaTiO3"])
for formula, gap in results.items():
    print(f"  {formula}: {gap:.3f} eV")

Dataset

Property	Value
Source	Materials Project v2024+
Compounds	15,537 thermodynamically stable phases
Filter	is_stable=True, band_gap > 0.1 eV
Target	PBE-GGA band gap (eV)
Features	132 Magpie compositional descriptors
Train/Test	80/20 split, random_state=42

Project Structure

Prediction-model/
├── bandgap_prediction.ipynb    # Full ML pipeline (6-stage notebook)
├── predict.py                  # CLI & Python API entrypoint
├── requirements.txt            # Pinned dependencies
├── .env.example                # API key template
├── CONTRIBUTING.md             # Contribution guide
├── CODE_OF_CONDUCT.md          # Community standards
├── CITATION.cff                # Machine-readable citation
├── LICENSE                     # MIT License
│
├── data/                       # Cached datasets
│   └── mp_bandgap_data.csv     # Materials Project query cache
├── models/                     # Trained model artifacts
│   ├── xgb_model.joblib        # Best model (XGBoost)
│   ├── rf_model.joblib         # Random Forest baseline
│   ├── scaler.joblib           # StandardScaler (fitted)
│   └── featurizer.joblib       # Magpie featurizer (fitted)
├── figures/                    # Publication-quality plots
│   ├── bandgap_distribution.png
│   ├── correlation_heatmap.png
│   ├── feature_importance.png
│   └── parity_plot.png
├── tests/                      # Property-based tests
│   └── test_properties.py
└── .github/                    # GitHub automation
    ├── ISSUE_TEMPLATE/
    └── PULL_REQUEST_TEMPLATE.md

Figures

Click to expand sample outputs

Band Gap Distribution	Parity Plot (XGBoost)

Feature Importance	Correlation Heatmap

Reproduction Checklist

To fully reproduce results from scratch:

• Obtain a Materials Project API key
• Run all cells in bandgap_prediction.ipynb sequentially
• Verify data/mp_bandgap_data.csv contains ~15,500 rows
• Confirm R² > 0.88 for Random Forest, > 0.90 for XGBoost
• Check figures/ directory contains 4 PNG files
• Run pytest tests/ to verify model properties

Contributing

We welcome contributions from materials scientists, ML researchers, and software engineers alike. See CONTRIBUTING.md for:

• Adding new featurizers (e.g., SOAP, orbital-field matrix)
• Implementing additional ML models (e.g., neural networks, Gaussian processes)
• Extending the dataset (multi-fidelity, experimental band gaps)
• Improving documentation or adding tutorials

Quick contribution paths:

Path	Difficulty	Impact
Fix typos / improve docs	Beginner	Medium
Add a new ML model	Intermediate	High
Add structural descriptors	Advanced	High
Multi-fidelity learning	Advanced	Very High

Citation

If you use this code or data in your research, please cite:

@software{bandgap_prediction_2024,
  author       = {Your Name},
  title        = {Predicting Materials Band Gaps from Chemical Composition},
  year         = {2024},
  url          = {https://github.com/neweracy/Prediction-model},
  license      = {MIT}
}

See CITATION.cff for a machine-readable citation file.

License

This project is licensed under the MIT License — see LICENSE for details.

Acknowledgements

• Materials Project for open DFT data
• matminer for featurization tools
• pymatgen for materials analysis infrastructure
• scikit-learn and XGBoost for ML models

---

Report Bug · Request Feature · Ask Question

Made with care for the materials informatics community.