CrystaLLM-cXRD_mp20 / README.md
c-bone's picture
Fix citation (current arXiv author list, plain url)
c355a5e verified
|
Raw History Blame Contribute Delete
4.64 kB
---
language:
- en
license: mit
library_name: transformers
tags:
- materials-science
- crystallography
- generative-ai
- inverse-design
- chemistry
- xrd
datasets:
- c-bone/cxrd_mp20
pipeline_tag: text-generation
---
# Model Card for CrystaLLM-cXRD\_mp20
## Model Details
### Model Description
**CrystaLLM-cXRD\_mp20** is a conditional generative model for crystal structure generation from powder X-ray Diffraction (XRD) data. It is a GPT-2 decoder-only model that conditions the generation of Crystallographic Information Files (CIFs) on a **continuous diffraction profile** rather than a peak list, using a **Perceiver Resampler prefix** (`PrefixXRD`) that compresses the pattern into learned key-value tokens injected at every transformer layer.
The model consumes the **whole pattern**:
1. **Scattering vector** (Q) on a fixed 1000-point grid, `arange(0, 10, 0.01)` Å⁻¹
2. **Intensity** (I), max-normalised to $[0, 1]$
This removes the peak-picking step from the workflow: a raw diffractometer scan is converted to the `(1000, 2)` `[Q, I]` profile automatically at generation time. Because Q is wavelength-independent, patterns from any anode can be used as long as the wavelength is supplied.
Trained from scratch on MP-20, this is the **benchmark** model behind the MP-20 XRD-guided structure prediction comparison. For application use, [`c-bone/CrystaLLM-cXRD_chili100k`](https://huggingface.co/c-bone/CrystaLLM-cXRD_chili100k) (experimental nanomaterials) or [`c-bone/CrystaLLM-cXRD_alex-mp-20`](https://huggingface.co/c-bone/CrystaLLM-cXRD_alex-mp-20) (broad computed distribution) are the better choices.
- **Developed by:** Bone et al. (University College London)
- **Model type:** Autoregressive Transformer with Perceiver prefix conditioning (~36.5M parameters)
- **Language(s):** CIF (Crystallographic Information File) syntax
- **License:** MIT
- **Finetuned from model:** none, trained from random initialisation
### Model Sources
- **Repository:** [GitHub: CrystaLLM-pi](https://github.com/C-Bone-UCL/CrystaLLM-pi) (generation), [GitHub: CrystaLLM-cXRD](https://github.com/C-Bone-UCL/CrystaLLM-cXRD) (training and benchmarks)
- **Paper:** To add
- **Dataset:** [HuggingFace: c-bone/cxrd\_mp20](https://huggingface.co/datasets/c-bone/cxrd_mp20)
## Uses
### Direct Use
Structure generation from powder XRD on the MP-20 distribution, and the reference point for the MP-20 benchmark. Pass a raw two-column scan and a target composition; the model proposes candidate structures consistent with the diffraction signature.
### Out-of-Scope Use
- **Disordered Systems:** No native handling of partial occupancies or significant disorder.
- **Experimental nanomaterials:** MP-20 is a computed, fully ordered distribution. Use the CHILI-100K model for experimental patterns.
- **Unconditional generation:** The model requires a diffraction profile at every forward pass and has no missing-conditioning fallback.
- **Non-CuKα data without a declared wavelength:** CuKα1 is assumed when none is given, which silently misplaces every peak in Q.
## Bias, Risks, and Limitations
- **Computed-data bias:** Training patterns are simulated from relaxed DFT structures, so peak shapes are cleaner and more ordered than laboratory scans.
- **Preprocessing sensitivity:** Recovery depends on the background subtraction and wavelength used to build the profile. Inspect the conversion (`--save_plot`) before trusting a result.
- **Measured range:** Regions of the Q grid outside the measured scan are zero-filled; short scans give the model less to work with.
- **Context window:** 1024 tokens (plus 8 prefix tokens), so very large unit cells will not fit.
## Getting started
For generation from a scan, use [`T4_XRD_continuous.ipynb`](https://github.com/C-Bone-UCL/CrystaLLM-pi/blob/main/notebooks/T4_XRD_continuous.ipynb) in CrystaLLM-pi. For the benchmark this model was trained on, see [`B1_mp20_benchmark.ipynb`](https://github.com/C-Bone-UCL/CrystaLLM-cXRD/blob/main/notebooks/B1_mp20_benchmark.ipynb).
## Citation
**Papers to cite:**
```bibtex
@misc{bone2025discoveryrecoverycrystallinematerials,
title={Discovery and recovery of crystalline materials with property-conditioned transformers},
author={Cyprien Bone and Matthew Walker and Bradley A. A. Martin and Kuangdai Leng and Luis M. Antunes and Ricardo Grau-Crespo and Amil Aligayev and Javier Dominguez and Keith T. Butler},
year={2025},
eprint={2511.21299},
archivePrefix={arXiv},
primaryClass={cond-mat.mtrl-sci},
url={https://arxiv.org/abs/2511.21299},
}
```
and
To add