alm-edit/README.md

---
license: apache-2.0
tags:
  - materials
  - diffusion
  - crystal-structure-prediction
  - editing
  - mattergen
---
# ALM Edit · crystal-structure prediction + text-conditioned editing

**ALM Edit** conditions a from-scratch CSP-mode MatterGen decoder (`csp_backbone`) on an
*input structure + text instruction* via a **producer-consumer** bridge: K=8 `[atoms_i]`
soft tokens plus prompt context feed a learnable-query producer (M=16), whose tokens the
cross-attention consumer reads inside the decoder. It performs crystal-structure
prediction and the **ALM Bench** editing tasks.

This is a **full-finetuning** run: it bundles a fully fine-tuned Qwen3-8B
(`llm_full_ft/qwen3_state_dict.pt`, ~16 GB), which the loader auto-detects and uses in
place of any LoRA. Contents: `atoms_mapper.pt` (producer-consumer bridge) + `llm_full_ft/`
+ `projector_and_state.pt` + the `csp_backbone/` decoder dir (config + last.ckpt).

Crystal-structure prediction: match rate MR (%, ↑) and RMSE (Å, ↓) to the MP-20 and
MPTS-52 test sets at K=1 and best-of-K=20 (95% CIs in the paper):

| Model | MP-20 MR@1 | RMSE@1 | MR@20 | RMSE@20 | MPTS-52 MR@1 | RMSE@1 | MR@20 | RMSE@20 |
|---|--:|--:|--:|--:|--:|--:|--:|--:|
| CDVAE | 33.90 | 0.1045 | 66.95 | 0.1026 | 5.34 | 0.2106 | 20.79 | 0.2085 |
| DiffCSP | 51.49 | 0.0631 | 77.93 | 0.0492 | 12.19 | 0.1786 | 34.02 | 0.1749 |
| FlowMM | 61.39 | 0.0566 | n/a | n/a | 17.54 | 0.1726 | n/a | n/a |
| CrystaLLM-large | 58.70 | 0.0408 | 73.97 | 0.0349 | 19.21 | 0.1110 | 33.75 | 0.1059 |
| CrystalFlow | 62.02 | 0.0710 | 78.34 | 0.0577 | 21.00 | 0.1613 | 37.81 | 0.1584 |
| OMatG | 63.75 | 0.0720 | n/a | n/a | 25.15 | 0.1931 | n/a | n/a |
| MCFlow-L | **64.08** | 0.0561 | 76.08 | 0.0383 | **27.16** | 0.1401 | 41.45 | 0.1296 |
| **ALM Edit** | 45.6 | **0.021** | **83.2** | **0.034** | 22.7 | **0.022** | **45.7** | **0.038** |
| **ALM Gen** + T2C-FK | 22.3 | 0.025 | 41.0 | 0.012 | 6.0 | 0.040 | 10.0 | 0.011 |

**ALM Edit** sets SoTA RMSE and best-of-K=20 match rate on both benchmarks (it learns a
valid polymorph distribution); it sees composition + space group at train time, only
composition at inference.

**ALM Bench** directional editing per property (E_f, ρ, V) and direction (↑/↓), plus
polymorph/doping/strain (N=7×1000; every metric scores invalid generations, trivial
lattice rescalings, and unphysical relabelings as failures). Frontier LLMs were prompted
to read/write CIFs:

| Model | E_f↑ | E_f↓ | ρ↑ | ρ↓ | V↑ | V↓ | Polymorph | Doping | Strain |
|---|--:|--:|--:|--:|--:|--:|--:|--:|--:|
| **ALM Edit** | **0.613** | **0.624** | **0.353** | **0.367** | **0.451** | **0.355** | **0.224** | **0.879** | **0.151** |
| GPT-4o | 0.505 | 0.469 | 0.024 | 0.127 | 0.081 | 0.018 | 0.040 | 0.007 | 0.000 |
| GPT-4.1 | 0.465 | 0.496 | 0.007 | 0.239 | 0.276 | 0.040 | 0.083 | 0.003 | 0.000 |
| GPT-5.2 | 0.437 | 0.414 | 0.058 | 0.244 | 0.006 | 0.032 | 0.118 | 0.002 | 0.000 |

Text-conditioned generation (Application = LLM-judged fit; Describe/OOD = composition &
structure consistency, N=7×1000):

| Model | Application | Describe (Comp.) | Describe (Struct.) | OOD (Comp.) | OOD (Struct.) |
|---|--:|--:|--:|--:|--:|
| **ALM Edit** | **0.423** | **0.730** | **0.412** | **0.474** | **0.231** |
| GPT-4o | 0.131 | 0.279 | 0.121 | 0.130 | 0.025 |
| GPT-4.1 | 0.224 | 0.254 | 0.090 | 0.168 | 0.035 |
| GPT-5.2 | 0.252 | 0.356 | 0.162 | 0.263 | 0.075 |

**Edit / generate a structure (inference):**
```bash
# composition/description -> structure, using the CSP-mode backbone
alm-generate generate --alm_checkpoint alm-edit \
    --atoms_mapper alm-edit/atoms_mapper.pt --mattergen_model_path alm-edit/csp_backbone \
    --prompt "An orthorhombic perovskite of calcium and titanium." --num_samples 8 --out_dir gen_out
```

**Evaluate (CSP M@20 / RMSE, and the ALM Bench editing tasks):**
```bash
alm-eval-csp --ckpt_dir alm-edit/csp_backbone \
    --guidance_factor 0.5 --out_dir out/csp
alm-eval-almbench --alm_checkpoint alm-edit \
    --atoms_mapper alm-edit/atoms_mapper.pt --bridge_lora_dir none \
    --mattergen_model_path alm-edit/csp_backbone --guidance_factor 0.5
```

## Links
Paper: [arXiv](https://arxiv.org/abs/2606.21395) · [HuggingFace](https://huggingface.co/papers/2606.21395) · Code: [GitHub](https://github.com/learningmatter-mit/alm)

## License
Apache-2.0.

## Citation
```bibtex
@article{edamadaka2026atomistic,
  title   = {Atomistic Language Models Understand and Generate Materials},
  author  = {Edamadaka, Sathya and Ramesh, Krithik and Li, Ju and G\'omez-Bombarelli, Rafael},
  journal = {arXiv preprint arXiv:2606.21395},
  year    = {2026}
}
```