Wyckoff Transformer: Generation of Symmetric Crystals [ICML 2025]

WyFormer generates crystals as Wyckoff representations: a space group plus the occupied Wyckoff positions and their elements. PyXtal then places the atoms, and an ML potential relaxes the result into a 3D structure.

Benchmarking against WyFormer

Figshare hosts the structures generated by WyFormer trained on MP-20 and MPTS-52, along with DiffCSP, DiffCSP++, WyCryst, SymmCD, CrystalFormer, MiAD, MatterGen, Crys-JEPA, and Composition in a unified format, along with Materials Project-compatible DFT relaxations: ~10k structures each for WyFormer, MatterGen and MiAD; 1k each for DiffCSP, SymmCD, Crys-JEPA and Composition.

Installation

pip install "wyckoff-transformer[relax]"

The [relax] extra adds the ML potentials for the 3D step, skip it if you only need the Wyckoff representations.

Inference

Simple de novo generation

Step 1: Generate genes

wyformer-generate genes.json.gz --hf-model SymmetryAdvantage/WyFormer-LeMat

For a higher yield of new metastable structures, ask the e_hull-conditioned model for genes near the hull instead. About 61% of its draws are formally valid at this guidance scale, so draw twice as many as you keep:

wyformer-generate genes.json.gz --hf-model SymmetryAdvantage/WyFormer-LeMat-Ehull \
    --condition energy_above_hull=0.05 --guidance-scale 5 \
    --initial-n-samples 2000 --firm-n-samples 1000

Add --device cuda to the wyformer-generate and wyformer-gene-screen commands when a GPU is available. The pre-trained models are in the HuggingFace collection.

Step 2: Relax

wyformer-cryspr genes.json.gz --mlip orb_conserv_inf --output-dir relaxed --workers 8

Alternatively, the structures can be obtained with GeoCSP, our diffusion model based on DiffCSP++.

Advanced generation, chemical system conditioning

Generate genes that contain only the given elements, rank them by predicted distance to the PBE hull of LeMat-Bulk-fixed, and relax the 100 best distinct ones of at most 40 atoms:

wyformer-generate batio_genes.json.gz --hf-model SymmetryAdvantage/WyFormer-LeMat-Chemsys \
    --chemical-system Ba-Ti-O --initial-n-samples 1100 --firm-n-samples 1000
wyformer-gene-screen batio_genes.json.gz --regressor-hf-model SymmetryAdvantage/WyFormer-LeMat-Energy \
    --hf-reference kazeevn/LeMat-Bulk-fixed \
    --max-atoms 40 --unique --top 100 --out batio_screen.csv --out-genes batio_top100.json.gz
wyformer-cryspr batio_top100.json.gz --mlip orb_conserv_inf --output-dir batio_relaxed --workers 8

--chemical-system Ba-Ti-O asks for compounds that contain all three elements; run TiO2 and the other subsystems separately. --max-atoms 40 drops genes with more than 40 atoms in the conventional cell: the lowest predicted energies favour large cells, which are slow to relax. batio_screen.csv holds the predicted energies, and batio_relaxed/orb_conserv_inf_results.csv the relaxed energy and CIF of each gene. ORB v3 is the potential LeMat-Bulk publishes its MLIP hull for, so those energies compare directly with that hull. See the pipeline notes for timings and outputs.

Documentation

• Generating and relaxing structures: other model sources, generation options, PyXtal placement and MLIP relaxation, CHGNet and DFT.
• Training: installation from source, datasets, tokenization, training.
• Screening and evaluation: DFT and novelty screens, the de novo ranking protocol, reproducing the original ICML paper metrics.