README.md

---
license: mit
tags: [crystal-structure-prediction, materials-science, transformer, coordination-chemistry]
library_name: pytorch
---

# TopG — a coordination-conditioned generator of periodic cation frameworks

**Status: research artifact, mid-project. Read the limitations before using any number.**

Given a *coordination query* — for each inequivalent metal site, its site symmetry, coordination
sequence and shell-distance ratios — the model emits a **complete crystal structure**: space group,
Wyckoff positions, free coordinates and free cell-shape parameters. Nothing downstream re-derives
any of it.

## Model

| | |
|---|---|
| architecture | causal transformer decoder, 4 layers, d=256, 8 heads, FFN 1024 |
| parameters | **4.5 M** |
| conditioning | one prefix token per site + one global token (so k is a sequence length, not a weight shape) |
| vocabulary | 2,317 tokens — per-space-group Wyckoff labels, coarse/fine coordinate and cell grids |
| training | 69,190 enumerated records, 100 epochs, ~100 min on a Quadro RTX 4000 |

## ⚠ CHECKPOINT / CODE COMPATIBILITY — READ BEFORE LOADING

The conditioning vector changed on 2026-08-08 (WP-018 added a per-shell **SPECIFIED** bit so partial
queries could be expressed). That is a **breaking representation change**:

| arms | conditioning | load with |
|---|---|---|
| `H_pq*` | `PER_SITE_DIM=68`, `COND_DIM=1020` | **current `main`** (commit `74dae8f` or later) |
| `G_100*` | `PER_SITE_DIM=62`, `COND_DIM=948` | **commit `203c036`** (the parent of the change) |

Loading a `G` checkpoint with current code raises
`size mismatch for site_proj.0.weight: [256, 62] vs [256, 68]`. That is the expected, loud failure —
not a corrupted download.

Two families, three seeds each:
- **`G_100*`** — full-depth queries (all six shells specified).
- **`H_pq*`** — partial queries: trained with the query depth truncated to 2–6 shells from a declared,
  seeded distribution, so a user can ask for less than six shells.
- **`I_full*`** — the control for the above: identical to `H_pq*` in every respect **except** the
  truncation. Included so the partial-query claim can be checked rather than taken on trust.

Two checkpoints per arm, because **the two halves of the task peak at different times**:
- `ckpt_00020.pt` — best validation loss, best **skeleton** accuracy.
- `ckpt_00100.pt` — best **geometry** (r3). Measured, paired, 3 seeds: r3 1.50%→2.50% (p=0.017) and
  1.02%→2.86% (p=0.0005) between these two points, while skeleton-exact falls.

**There is no single best checkpoint. Select per metric and say which you used.**

## ⭐ Partial queries: ask for less than six shells

A user rarely knows six coordination shells. They know the first one or two. The `H_pq*` arms are
trained with the query depth truncated to 2–6 shells, so a **partial** query is both expressible and
answerable — and the control shows the *training*, not just the encoding, is what makes it work.

Both families trained identically under the same conditioning; only the truncation differs
[3 seeds, 400 queries × 3, K=24]:

| query depth | applicable rung | `I_full` (full-query trained) | `H_pq` (partial-query trained) |
|---|---|---|---|
| **2 shells** | r0 | 19.4% · skeleton 10.2% | **61.5% · skeleton 49.6%** |
| **3 shells** | r2 (3sh + 4%) | 1.0% · skeleton 15.8% | **4.2% · skeleton 50.2%** |
| 6 shells | r3 (6sh + 4%) | 2.4% · skeleton 54.2% | 2.4% · skeleton 53.6% |

**At full depth the families are identical** — partial support is free. **At shallow depth a
full-query model collapses**: shown an input pattern it never saw (`specified=[1,1,0,0,0,0]`), its
skeleton accuracy falls to 10.2%, worse than anywhere on its own training curve.

⚠ **r0 is a weak criterion** (two shells, no ratio test) and **10.8% of 2-shell queries admit ≥2
distinct structures** — so the absolute 61.5% is against a weak bar. What carries weight is the
*paired contrast*: same bar, same queries, 19.4% vs 61.5%.

**Use `H_pq*` if you want to send partial queries. Use either family at full depth.**

## What it does well

| capability | measured [per-QUERY unless stated] |
|---|---|
| emits a valid parseable structure | **99%** of beams; every death diagnosed as a model choice |
| predicts N without being told | **92% per candidate**, 98.75% per query |
| predicts k without being told | **97% per candidate** |
| names the exact skeleton (sg + Wyckoff labels + N) | **58.8%** |
| satisfies a **2-shell** query (r0) | **61.5%** |

Skeleton accuracy is roughly flat from N=2 to N=192 and k=2 to k=11.

## What it does not do

**Metric precision.** r3 (six shells + 4% distance tolerance — the project's historical criterion) is
**2.5–3.1%**. Loosening the tolerance to 15% reaches only ~5.5%: the distances are wrong, not nearly
right. Structure:

- **Below ndim ≈ 9 the CELL is the binding constraint.** In cubic, where symmetry fixes the cell
  entirely, r3 is **18.75% vs 0.25%** — matched on N and k, and on ndim.
- **Above ndim ≈ 9 the COORDINATES bind.** Cubic scores zero there too.
- Every r3 success in the evaluation sits at **ndim ≤ 9 and k ≤ 4**.

## Honest instrument facts

- **Grid ceiling 95.67%** — a *perfect* model scores 95.67%, not 100%, on this evaluation set at this
  emission grid. Ground truth round-tripped through encode→decode→rebuild.
- **Model-free control: 0/400.** Oracle skeleton + the training split's median geometry scores zero.
- **Train-seed noise floor: 2–4 pp** on skeleton, **0.5 pp** on r3, from 3 cold starts differing only
  in the seed. **No discrete claim below ~9 pp is interpretable from a single run at a long epoch
  budget.**

## Limitations

- Trained on **enumerated (synthetic) structures only**. Materials Project data is held out for
  evaluation and never trained on (enforced in code).
- Space groups 3–230; **triclinic is thin** (348 corpus records) and cubic external validation is
  effectively absent (7 MP queries survive rebuild).
- Queries are **scale-free** — the model emits cell *shape*, never absolute length.
- No refinement step exists yet, so the "model output as a starting point" question is open.

## Provenance

Code, every preregistration, every result and every correction:
**https://github.com/rgpalgrave/TopG**. `SHA256SUMS.json` here matches the checkpoints; each
`arm_meta.json` records the corpus hash, split hashes, seed, vocab hash, tokenizer version and git
commit.