README.md

---
license: mit
language: en
tags:
  - materials-science
  - machine-learning
  - pytorch
  - matbench
  - small-data
  - attention
  - recursive
  - crystal
  - gradio
datasets:
  - matbench
metrics:
  - mae
  - roc_auc
model-index:
  - name: TRIADS
    results:
      - task:
          type: regression
          name: Yield Strength Prediction (MPa)
        dataset:
          name: matbench_steels
          type: matbench
        metrics:
          - type: mae
            value: 91.20
            name: MAE (MPa)
      - task:
          type: regression
          name: Band Gap Prediction (eV)
        dataset:
          name: matbench_expt_gap
          type: matbench
        metrics:
          - type: mae
            value: 0.3068
            name: MAE (eV)
      - task:
          type: classification
          name: Metallicity Classification
        dataset:
          name: matbench_expt_ismetal
          type: matbench
        metrics:
          - type: roc_auc
            value: 0.9655
            name: ROC-AUC
      - task:
          type: classification
          name: Glass Forming Ability
        dataset:
          name: matbench_glass
          type: matbench
        metrics:
          - type: roc_auc
            value: 0.9285
            name: ROC-AUC
      - task:
          type: regression
          name: Exfoliation Energy (meV/atom)
        dataset:
          name: matbench_jdft2d
          type: matbench
        metrics:
          - type: mae
            value: 35.89
            name: MAE (meV/atom)
      - task:
          type: regression
          name: Peak Phonon Frequency (cm⁻¹)
        dataset:
          name: matbench_phonons
          type: matbench
        metrics:
          - type: mae
            value: 41.91
            name: MAE (cm⁻¹)
---

# TRIADS — Materials Property Prediction Across 6 Matbench Benchmarks

**TRIADS (Tiny Recursive Information-Attention with Deep Supervision)** is a parameter-efficient recursive architecture for materials property prediction, purpose-built for the **small-data regime** (312–5,680 samples).

[![GitHub](https://img.shields.io/badge/GitHub-Code-black?logo=github)](https://github.com/Rtx09x/TRIADS)
[![Paper](https://img.shields.io/badge/Paper-PDF-red)](https://github.com/Rtx09x/TRIADS/raw/main/TRIADS_Final.pdf)

## Live Demo

Try the interactive demo with all 6 benchmarks → **[Launch App](https://huggingface.co/spaces/Rtx09/TRIADS)**

## Results Summary

| Task | N | TRIADS | Params | Rank |
|---|---|---|---|---|
| `matbench_steels` (yield strength) | 312 | **91.20 MPa** | 225K | #3 |
| `matbench_expt_gap` (band gap) | 4,604 | **0.3068 eV** | 100K | #2 composition-only |
| `matbench_expt_ismetal` (metal?) | 4,921 | **0.9655 ROC-AUC** | 100K | **#1** composition-only |
| `matbench_glass` (glass forming) | 5,680 | **0.9285 ROC-AUC** | 44K | #2 |
| `matbench_jdft2d` (exfol. energy) | 636 | **35.89 meV/atom** | 75K | **#1** no-pretraining |
| `matbench_phonons` (phonon freq.) | 1,265 | **41.91 cm⁻¹** | 247K | **#1** no-pretraining |

## Two Model Variants

### HybridTRIADS (composition tasks: steels, gap, ismetal, glass, jdft2d)
Input: Chemical formula → Magpie + Mat2Vec (composition tokens)  
Core: 2-layer self-attention cell, iterated T=16-20 times with shared weights  
Training: Per-cycle deep supervision (w_t ∝ t)

### GraphTRIADS (structural task: phonons)
Input: CIF/structure → 3-order hierarchical crystal graph (atoms, bonds, triplet angles, dihedral angles)  
Core: Hierarchical GNN message-passing stack inside the shared recursive cell  
Halting: Gate-based adaptive halting (4–16 cycles per sample)

## Pretrained Checkpoints

Weights are organized by benchmark. Download via `huggingface_hub`:

```python
from huggingface_hub import hf_hub_download
import torch

# Download one benchmark's weights (contains all folds compiled)
ckpt = torch.load(
    hf_hub_download("Rtx09/TRIADS", "steels/weights.pt"),
    map_location="cpu"
)
# ckpt['folds']   -> list of fold dicts, each with 'model_state' and 'test_mae'
# ckpt['n_extra'] -> int  (needed for model init)
# ckpt['config']  -> dict (d_attn, d_hidden, ff_dim, dropout, max_steps)
```

### Checkpoint Index

| Benchmark | File | Folds | Notes |
|---|---|---|---|
| matbench_steels | `steels/weights.pt` | 5 | HybridTRIADS V13A · 225K · 5-seed ensemble compiled |
| matbench_expt_gap | `expt_gap/weights.pt` | 5 | HybridTRIADS V3 · 100K |
| matbench_expt_ismetal | `is_metal/weights.pt` | 5 | HybridTRIADS · 100K |
| matbench_glass | `glass/weights.pt` | 5 | HybridTRIADS · 44K |
| matbench_jdft2d | `jdft2d/weights.pt` | 5 | HybridTRIADS V4 · 75K · 5-seed ensemble compiled |
| matbench_phonons | `phonons/weights.pt` | 5 | GraphTRIADS V6 · 247K · also needs `phonons/dataset.pt` |

## Citation

```bibtex
@article{tiwari2026triads,
  author  = {Rudra Tiwari},
  title   = {TRIADS: Tiny Recursive Information-Attention with Deep Supervision},
  year    = {2026},
  doi     = {10.5281/zenodo.19200579},
  url     = {https://doi.org/10.5281/zenodo.19200579},
  note    = {Code: https://github.com/Rtx09x/TRIADS; Models: https://huggingface.co/Rtx09/TRIADS}
}
```

## License

MIT License — see [GitHub repository](https://github.com/Rtx09x/TRIADS/blob/main/LICENSE).