hirenlimbad/homo_lumo_gap

LL-DFT-GAP: Calibrated Evidential Delta-PaiNN for Quantum Chemistry

Official model checkpoints, inference wrappers, and benchmark split indices for LL-DFT-GAP. The architecture pairs an E(3)-equivariant message-passing neural network (PaiNN) with semi-empirical physics priors (GFN2-xTB Delta-learning), heteroscedastic uncertainty estimation, and split conformal prediction to deliver calibrated HOMO-LUMO gap predictions.

For full methodology, conformal calibration derivations, and active learning analyses, visit our technical article at Levitating Labs:
Calibrated Uncertainty for DFT HOMO-LUMO Gap Prediction, and What Active Learning Did (and Didn't) Add

---

Inference Tiers

Evaluated on an NVIDIA T4 GPU (16 GB VRAM) across 10,000 held-out test molecules (batch size = 128). Users can select the appropriate trade-off between screening throughput and consensus calibration:

Tier	Ensemble Checkpoints	Latency / Mol	Throughput	100k Screening Time	Test MAE	Conformal Multiplier (q)	Recommended Use
fast	Seed [777] (1 model)	0.51 ms	1,951 mol/s	51.3 s	0.1507 eV (3.47 kcal/mol)	2.9816	Large-scale virtual screening (>10^6 molecules)
medium	Seeds [777, 222, 456, 999] (4 models)	1.93 ms	518 mol/s	193.0 s	0.1340 eV (3.09 kcal/mol)	2.2500	Hit-to-lead exploration
full	All 6 seeds	2.98 ms	336 mol/s	297.7 s	0.1308 eV (3.02 kcal/mol)	2.0426	Critical candidate triage and lead optimization

---

Quickstart

1. Download Inference Script

wget https://huggingface.co/hirenlimbad/homo_lumo_gap/raw/main/modeling_painn.py

2. Run Inference in Python

import torch
from modeling_painn import LLDFTPredictor

# Initialize predictor ('fast', 'medium', or 'full')
model = LLDFTPredictor.from_pretrained("hirenlimbad/homo_lumo_gap", tier="fast")

# Input molecular structure (example: Methane, CH4)
z = torch.tensor([6, 1, 1, 1, 1], dtype=torch.long)
pos = torch.tensor([
    [ 0.0000,  0.0000,  0.0000],
    [ 0.6291,  0.6291,  0.6291],
    [-0.6291, -0.6291,  0.6291],
    [-0.6291,  0.6291, -0.6291],
    [ 0.6291, -0.6291, -0.6291],
], dtype=torch.float32)

# Graph connectivity
row, col = [], []
for i in range(5):
    for j in range(5):
        if i != j:
            row.append(i); col.append(j)
edge_index = torch.tensor([row, col], dtype=torch.long)

charges = torch.tensor([[-0.4], [0.1], [0.1], [0.1], [0.1]], dtype=torch.float32)

# GFN2-xTB semi-empirical physics priors
xtb_homo = -10.50
xtb_lumo = -1.20
xtb_gap = xtb_lumo - xtb_homo
xtb_dipole = 0.02

# Run single-pass calibrated inference
res = model.predict(
    z=z, pos=pos, edge_index=edge_index, charges=charges,
    xtb_gap=xtb_gap, xtb_homo=xtb_homo, xtb_lumo=xtb_lumo, xtb_dipole=xtb_dipole
)

print(f"Semi-empirical xTB Gap : {res['xtb_gap_ev']:.4f} eV")
print(f"Delta-ML Correction     : {res['ml_delta_ev']:+.4f} eV")
print(f"Predicted DFT Gap      : {res['predicted_dft_gap_ev']:.4f} eV")
print(f"Total Uncertainty (σ)  : {res['sigma_total_ev']:.4f} eV")
print(f"91.8% Conformal CI     : [{res['conformal_interval_91_8'][0]:.4f}, {res['conformal_interval_91_8'][1]:.4f}] eV")
print(f"Triage Decision        : {res['triage_recommendation']}")

---

End-to-End Prediction from SMILES

For automated conformer generation (RDKit) and ground-state GFN2-xTB singlepoint calculations (tblite) directly from SMILES:

wget https://huggingface.co/hirenlimbad/homo_lumo_gap/raw/main/predict_from_smiles.py
pip install rdkit tblite

Command-Line Execution

python predict_from_smiles.py --smiles "CC(=O)Oc1ccccc1C(=O)O" --tier fast

Python API

from predict_from_smiles import predict_from_molecule

res = predict_from_molecule(smiles="CC(=O)Oc1ccccc1C(=O)O", tier="fast")

print(f"Calculated xTB Gap : {res['xtb_gap_ev']:.4f} eV")
print(f"Predicted DFT Gap  : {res['predicted_dft_gap_ev']:.4f} eV")
print(f"91.8% Conformal CI : [{res['conformal_interval_91_8'][0]:.4f}, {res['conformal_interval_91_8'][1]:.4f}] eV")
print(f"Triage Flag        : {res['triage_recommendation']}")

---

Benchmark Results (PCQM4Mv2 Held-Out Test Set: 32,165 Molecules)

Model Configuration	Test MAE (eV)	Test MAE (kcal/mol)	Pearson r (σ vs error)	Empirical Coverage	Mean Interval Width (eV)	Quantile (q)
Seed 222	0.1506	3.47	0.2843	91.96%	0.7051	4.6001
Seed 999	0.1533	3.53	0.4533	91.36%	0.6841	2.9499
Seed 456	0.1534	3.54	0.4227	91.65%	0.7047	3.0383
Seed 777 (fast)	0.1507	3.47	0.4469	92.02%	0.6795	2.9816
Seed 123	0.1545	3.56	0.4469	91.42%	0.6939	2.7860
Seed 42	0.1515	3.49	0.3328	91.53%	0.7016	4.1113
4-Model Ensemble (medium)	0.1340	3.09	0.4580	91.85%	0.6380	2.2500
6-Model Ensemble (full)	0.1308	3.02	0.4787	91.79%	0.5914	2.0426

---

Dataset Partitions

Partitions are fixed and available in base_split_indices.pt:

• Training Set: 236,634 molecules (ensemble parameter optimization)
• Validation Set: 28,360 molecules (finite-sample split conformal calibration)
• Held-Out Test Set: 32,165 molecules (frozen empirical evaluation)

Zero overlap exists between the training, calibration, and test partitions.