Model Card for CrystaLLM-cXRD_ranker

Model Details

Model Description

CrystaLLM-cXRD_ranker is a learned XRD ranker that picks one structure from the candidates a CrystaLLM-cXRD model generates for a powder X-ray Diffraction (XRD) pattern. It predicts each candidate's RMSD to the true structure, and the lowest prediction is kept. It replaces ranking by model perplexity or by a fixed profile residual such as $R_{wp}$.

The ranker is a small 1D convolutional network that reads three channels on the same fixed 1000-point grid, arange(0, 10, 0.01) Å⁻¹:

1. Measured profile, the (1000, 2) [Q, I] input pattern, max-normalised to $[0, 1]$
2. Candidate peaks, the candidate CIF's simulated diffraction peaks binned onto the Q grid without broadening
3. Q, the grid position scaled to $[0, 1]$, so the network knows where each feature sits

Six dilated residual convolution blocks run over all three channels together, mean and max pooling reduce the result to one vector, and a linear head returns the predicted RMSD. Non-matching candidates are trained towards an RMSD of 0.5.

• Developed by: Bone et al. (University College London)
• Model type: 1D convolutional regressor (~159K parameters)
• License: MIT
• Trained on: candidate pools from c-bone/CrystaLLM-cXRD_alex-mp-20 for the 67,518 structures of the c-bone/cxrd_alex-mp-20 validation split, 20 candidates each

Model Sources

• Repository: GitHub: CrystaLLM-cXRD (training and benchmarks)
• Paper: To add
• Dataset: HuggingFace: c-bone/cxrd_alex-mp-20

Uses

Direct Use

Choosing one structure from a pool of CrystaLLM-cXRD candidates for the same powder XRD pattern. It is the default ranking for continuous-XRD Z searches (--scoring_mode LEARNED), and rerank_xrd.py re-ranks an existing pool.

Keeping one candidate per material on the MP-20 test split, the match rate is 62.78% with perplexity ranking, 68.04% with $R_{wp}$ and 70.75% with the ranker. On the CHILI-100K test split it is 48.93%, 55.00% and 58.00%. No MP-20 or CHILI-100K structure was seen in training, and finetuning on CHILI-100K does not improve it.

Out-of-Scope Use

• Standalone structure scoring: The prediction ranks candidates for one pattern against each other. It is not a calibrated RMSD for a single structure.
• Peak-list models: The ranker reads a continuous profile, so it does not apply to the top-20 peak models.
• 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.
• Bounded by the pool: The ranker can only pick from the candidates it is given. When no candidate matches, it still returns one.

Getting started

For training and the CHILI-100K transfer check, see B4_learned_ranker.ipynb. For the benchmark re-ranking, see B1_mp20_benchmark.ipynb and B2_chili100k_benchmark.ipynb.

Citation

Papers to cite:

@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