openmaterials.ai / codes / DiffCSP
DiffCSP: crystal structure prediction by joint equivariant diffusion
Given a composition, a diffusion model denoises the lattice and the fractional coordinates together under periodic E(3) invariance and returns candidate structures in seconds.
What it is and how it works
Lattice and coordinates together
The lattice follows a denoising diffusion with a Gaussian prior and an O(3)-equivariant score. Fractional coordinates follow score matching with a wrapped normal, which builds periodicity into the model.
Fractional coordinates
Positions live in [0,1)^3 and enter the network through a Fourier transform of relative fractional vectors, invariant to periodic translation with no multi-graph edges.
Denoising network
EGNN-style message passing on the fully connected graph, with L^T L for O(3) invariance. Six layers, 512 hidden states, 256 Fourier features on MP-20 (Jiao 2023).
Sampling
1,000 diffusion steps, an ancestral predictor with a Langevin corrector for the coordinates, and k candidates per composition, k = 1 or 20 in the benchmarks (Jiao 2023).
Ab initio generation
A discrete diffusion on atom types lets the same model generate compositions too, with 100% structural validity on Perov-5, Carbon-24 and MP-20 (Jiao 2023).
What people do with it
- 77.93%match rate on MP-20 with 20 samplesJiao 2023
- 10 sfor 20 candidates per compound, USPEX 12.5 hJiao 2023
- 0.0492normalised RMSE of matched MP-20 structuresJiao 2023
Kagome and Lieb lattice quantum materials
SCIGEN steered DiffCSP to 10 million Archimedean and Lieb lattice compounds. Of 26,000 relaxed with DFT, 53% were structurally stable, and two predicted materials were synthesised. Okabe 2025
Superconductors by guided diffusion
A DiffCSP model pretrained on Alexandria and fine-tuned on 7183 superconductors gave 34,027 unique candidates from 200,000 samples, 773 with a DFT Tc above 5 K. Prakash 2026
Fifteen compounds against USPEX
In the DiffCSP paper, it matched 73.33% of 15 MP-20 compounds with 20 candidates in about 10 s each, against 53.33% for the USPEX evolutionary search at 12.5 h. Jiao 2023
How it is used
Give a composition
The atom types of one unit cell, as one-hot vectors, fix the conditional p(L, F | A).
Sample candidates
Draw the lattice from N(0, I) and coordinates from U(0, 1), then denoise for 1,000 steps.
Match or relax
Compare with pymatgen StructureMatcher (stol 0.5, angle_tol 10, ltol 0.3) or relax.
Evaluate
Rank the k candidates by energy with DFT or a potential and keep the best structure.
What DiffCSP is
DiffCSP generates crystal structures with a diffusion model that denoises lattice and fractional coordinates together, keeping the periodic and rotational symmetries of the crystal. Given a composition it proposes candidate structures for later evaluation. On the map it serves the generated-structure quantity.
WebsiteOn the mapAll codesLicense: MIT
In more detail
Periodic E(3) invariance
The distribution p(L, F | A) must be invariant to permutations, to orthogonal transformations of the lattice and to periodic translations of the fractional coordinates. DiffCSP builds in each separately. The lattice L follows a DDPM with a cosine variance schedule and a prior N(0, I). The coordinates F follow score matching with a wrapped normal transition and an exponential noise schedule from 0.005 to 0.5, initialised from U(0, 1). The denoising network takes L^T L and the Fourier transform of relative fractional coordinates. It outputs the lattice score as L times an MLP of pooled features, and one score per node. Three propositions prove the result periodic E(3) invariant (Jiao 2023).
Numerics and scale
The MP-20 model has 6 layers and 512 hidden states with 256 Fourier features and trains for 1,000 epochs, 5.2 hours on a GeForce RTX 3090. Generating 20 candidates for every MP-20 test structure takes 18.4 GPU hours against 95.2 for CDVAE, because DiffCSP needs 1,000 steps where CDVAE needs 5,000. With 20 samples the match rates are 98.60% on Perov-5, 88.47% on Carbon-24, 77.93% on MP-20 and 34.02% on MPTS-52, with RMSE 0.0128, 0.2192, 0.0492 and 0.1749 (Jiao 2023).
Data and interfaces
Training and test data are the CDVAE splits of Perov-5 (18,928 perovskites), Carbon-24 (10,153 carbon structures), MP-20 (45,231 Materials Project structures) and the chronological MPTS-52 (40,476 structures). Lattices are Niggli reduced before training. The StructureMatcher of pymatgen scores the matches. The code is at github.com/jiaor17/DiffCSP (Jiao 2023). On the map DiffCSP serves the generated-structure quantity, candidate cells written as CIF files for later evaluation.
Validation
Ablations on MP-20 with one sample test each component. Joint diffusion gives a 51.49% match rate, generating the lattice first then coordinates 50.03%, coordinates first 36.73%. Removing the L^T L inner product drops the rate to 1.66%. Replacing the wrapped normal by a Gaussian gives 34.09% and dropping the Fourier transform 29.15%. Multi-graph edges in place of the fully connected graph give 25.85% to 28.05%. In ab initio generation DiffCSP matches CDVAE on validity and coverage and lowers the property statistic distances on MP-20 from 0.6875 to 0.3502 for density and from 0.2778 to 0.1247 for formation energy (Jiao 2023).
What it computes on the map
1 quantity, drawn by tier with the data flow between them. Dashed boxes are intermediate quantities. Select one for its formula and the other codes that compute it.
Embed this submap
<iframe src="https://openmaterials.ai/m/c56731602651/00000000000001?embed=1" title="DiffCSP on the OpenMaterials map" width="100%" height="480" loading="lazy" style="border:1px solid #EBEBEB;border-radius:6px"></iframe>
Each quantity with the interface the representation records.
- StructureDiffCSP++ generate_structures_with_symmetry(spacegroup, wyckoff_letters, atom_types, model_name='mp_csp', step_lr=1e-5) -> CIFs (diffcsp_server.py:54-107); dimensionless generated artifact
References
The code
The papers that describe the code; cite them when you use it.
- R. Jiao, W. Huang, P. Lin et al., Crystal Structure Prediction by Joint Equivariant Diffusion, Advances in Neural Information Processing Systems 36, 2023. doi.org/10.52202/075280-0767
Applications
Highly cited studies that cite the code, with a few picked by hand.
- R. Okabe, M. Cheng, A. Chotrattanapituk et al., Structural constraint integration in a generative model for the discovery of quantum materials, Nature Materials, 2025. doi.org/10.1038/s41563-025-02355-y
- S. Kim, G. Jeon, S. Hwang et al., Are diffusion models ready for materials discovery in unexplored chemical space?, Patterns, 2026. doi.org/10.1016/j.patter.2026.101537
- P. Prakash, J. B. Gibson, Z. Li et al., Guided diffusion for the discovery of new superconductors, npj Computational Materials, 2026. doi.org/10.1038/s41524-026-02117-7
How to cite
R. Jiao, W. Huang, P. Lin, J. Han, P. Chen, Y. Lu, Y. Liu, Crystal Structure Prediction by Joint Equivariant Diffusion (DiffCSP), NeurIPS 36 (2023), arXiv:2309.04475; space-group-constrained variant DiffCSP++ arXiv:2402.03992