TCSP3.0: Template-Based Crystal Structure Prediction with Coefficient-Preserving Element Substitution and Structural Diversity

Ying Feng; Jeffrey Hu; Lai Wei; Liang Tao; Madeline Miklos; Dipannoy Das Gupta; Hossein Erfanshekooh; Jianjun Hu

cond-mat.mtrl-sciOct 25, 2026

TCSP3.0: Template-Based Crystal Structure Prediction with Coefficient-Preserving Element Substitution and Structural Diversity

Authors: Ying Feng, Jeffrey Hu, Lai Wei, Liang Tao, Madeline Miklos, Dipannoy Das Gupta, Hossein Erfanshekooh, Jianjun Hu

Organizations: Department of Computer Science and Engineering, University of South Carolina, Columbia, SC 29201, USA · Department of Materials Science and Engineering, University of Illinois Urbana-Champaign, IL, USA · Department of Computer Science and Cybersecurity, University of North Georgia, Dahlonega, GA 30597, USA

Abstract

Template-based crystal structure prediction (CSP) transfers a known crystal structure to a new composition by element substitution, so its accuracy depends on retrieving suitable templates, mapping elements and ranking the resulting candidates correctly. Auditing the original TCSP2.0 implementation on the T180 benchmark, we found that 469 of its 2,347 selected structures (20%) have the wrong composition, caused by element mappings that ignore stoichiometric coefficients and by sequential text substitution that cascades or corrupts element symbols. We propose TCSP3.0, which enforces coefficient-preserving mappings, substitutes species simultaneously on parsed structures and validates every candidate's composition and cell. It further adds periodic-number retrieval, soft oxidation-state evidence, radius-compatibility scoring, structural deduplication, and ORB-v3 machine-learning-potential relaxation and energy ranking of its candidates, as used by deep generative CSP baselines. TCSP3.0 achieves Top-1 and Top-20 match rates of 72.2% and 90.6% on T180, compared with 28.3% and 45.6% for TCSP2.0, and a Top-20 match rate of 74.0% on a new 800-target benchmark (T800). On T180 it also outperforms PNcsp+ and deep generative models CrystalFlow and MaskGXT (Top-1 72.2% versus at most 63.9%). Even without relaxation, TCSP3.0 reaches 67.8% at Top-1 and 90.6% at Top-20 in a median of 28 s per target on two CPU cores, about ten times faster than CrystalFlow. Paired ten-arm ablations on T180 and T800 show that most of the improvement comes from the correctness fixes; structural deduplication significantly improves the Top-5 match rate, embedding-based retrieval is required for coverage, and the remaining scoring features have small or null effects.

Figures & tables

Figure 1: TCSP3.0 workflow. Retrieval and mapping use composition alone; geometry comes from a source template. Up to 100 valid candidates are reranked by chemical and geometric scores and deduplicated. Green boxes mark V3 changes tested by the feature switches of the “Ablation Study” section, and the blue boxes are the default final stage; the correctness safeguards in the grey source-check box are shared by all configurations. Reference structures are used only in evaluation.

Cohort	Top-1	Top-5	Top-20
T46 ( $n=46$ )	35 (76.1%)	41 (89.1%)	41 (89.1%)
95% interval	[63.0,87.0]	[80.4,97.8]	[80.4,97.8]
T180 ( $n=180$ )	130 (72.2%)	159 (88.3%)	163 (90.6%)
95% interval	[65.6,78.3]	[83.3,92.8]	[86.1,94.4]
T180 disjoint ( $n=147$ )	103 (70.1%)	129 (87.8%)	133 (90.5%)
95% interval	[62.6,77.6]	[82.3,92.5]	[85.7,95.2]

Table 1: Top-

k

structure match rate of TCSP3.0 with ORB-v3 relaxation and energy ranking. Brackets are 95% bootstrap intervals. The disjoint subset removes the 33 targets shared with T46.

Figure 2: TCSP3.0 performance. (a) Top-

k

match rate with 95% bootstrap intervals. (b) Number of candidates per target. (c) T180 match rate by number of elements (60 targets each).

Implementation	Criterion	Top-1	Top-5	Top-20
Original TCSP2.0 (CPU)	Structure	51 (28.3%)	74 (41.1%)	82 (45.6%)
	SG	56 (31.1%)	82 (45.6%)	90 (50.0%)
	Consensus	48 (26.7%)	71 (39.4%)	79 (43.9%)
TCSP3.0 (ORB-v3 relax and rank)	Structure	130 (72.2%)	159 (88.3%)	163 (90.6%)
	SG	128 (71.1%)	155 (86.1%)	160 (88.9%)
	Consensus	126 (70.0%)	151 (83.9%)	156 (86.7%)

Table 2: Counts and match rates on all 180 T180 targets for the original TCSP2.0 code and TCSP3.0. Cells give matched-target counts with percentages in parentheses (denominator 180). TCSP3.0 is shown in its default configuration (ORB-v3 relaxation and energy ranking) and with its candidates in the native chemical order, which isolates the stage before relaxation and is the closer counterpart of the chemical-score selection of TCSP2.0. Failed runs and wrong-composition candidates count as misses. “(CPU)” denotes the original code as run on CPU hardware; the crash-repaired comparator was run on different hardware (Supplementary Section S3.2). SG is computed from each output CIF at 0.1 Å; consensus requires one candidate to match both structure and SG.

Figure 3: Match rate of the original TCSP2.0 code and TCSP3.0 (ORB-v3 relaxed and ranked) on the 180 T180 targets. Numbers give matched targets; failed runs and wrong-composition candidates count as misses.

Metric	Rank	TCSP3.0 (ORB-v3)	PNcsp+ full	PNcsp+ SG-best
Structure	Top-1	130 (72.2%)	71 (39.4%)	71 (39.4%)
Structure	Top-5	159 (88.3%)	96 (53.3%)	106 (58.9%)
Structure	Top-20	163 (90.6%)	108 (60.0%)	108 (60.0%)
Space group	Top-1	128 (71.1%)	68 (37.8%)	68 (37.8%)
Space group	Top-5	155 (86.1%)	93 (51.7%)	110 (61.1%)
Space group	Top-20	160 (88.9%)	111 (61.7%)	118 (65.6%)

Table 3: T180 comparison of TCSP3.0 and PNcsp+ under the common reference evaluator. Cells show matched targets (percent), with all 180 targets retained. PNcsp+ uses the LeMat-derived OQMD adaptation and official supported no-formation-energy-filter mode; SG-best retains one candidate per derived source-SG label. Template eligibility, cell sizes and candidate/physical budgets differ.

Figure 4: Paired structure match-rate differences of PNcsp+ relative to TCSP3.0 on all 180 T180 targets, with nominal 95% paired bootstrap intervals; negative values favor TCSP3.0. Full is the full energy ranking and SG-best the SG-best list of Table 3 .

Arm	Change relative to full V3
Full V3	Native configuration (all V3 features, no relaxation); explicit configuration checked for default parity
Embedding only	Remove PN retrieval route; retain V3 scoring and mapping
PN only	Remove embedding route; retain V3 scoring and mapping
One mapping	Single Hungarian base-cost assignment; combined-score choice can differ
Single OS	Retain first (most probable) neutral assignment; evidence mass held fixed
No OS	Remove OS assignment-scoring term; geometry evidence unchanged

Table 4: Ablation configurations. All share the same template index, inputs, query-composition exclusion, 100-candidate cap, matcher and correctness safeguards; none uses relaxation.

Arm	Top-1	Top-5	Top-20	Pool oracle	Top-5 $+/-$
Full V3	122	154	163	165	–
Embedding only	122	154	163	165	0/0
PN only	118	148	154	154	1/7
One mapping	122	154	163	165	0/0
Single OS	122	154	163	165	0/0
No OS	123	153	162	165	0/1

Table 5: Controlled feature outcomes on T180 (180 targets); Full V3 is the native TCSP3.0 configuration. Entries are StructureMatcher reference-match counts; every arm retains the full denominator. Pool oracle means at least one valid candidate in the capped pool matches the reference. Top-5 gains/losses compare the ablation with full V3 on paired targets.

Figure 5: Paired ablation-minus-full differences on T180 with 95% bootstrap intervals; negative values favor the full configuration.

Chemical family	$n$	Top-1	Top-20	$n$	Top-1	Top-20	$n$	Top-1	Top-20
	T46			T180			T800
Contains oxygen	16	75.0	81.2	40	62.5	87.5	408	58.6	70.1
Intermetallic	14	85.7	100.0	46	78.3	91.3	83	80.7	83.1
Contains a rare earth	15	86.7	100.0	52	78.8	96.2	241	81.7	90.9
Contains a d-block metal	36	77.8	88.9	137	76.6	92.0	452	66.8	75.9
Contains a halogen	6	66.7	100.0	26	57.7	84.6	146	54.8	63.0

Table 6: TCSP3.0 recovery by chemical family (default configuration, ORB-v3 relaxation and energy ranking). Entries are the percentage of the family’s targets recovered within the Top-1 and Top-20 candidates;

n

is the number of targets in the family. Families are those of Supplementary Table S7 and overlap, so rows are not additive.

Appendix figures & tables1 asset

Supplementary material from the paper’s appendix.

Appendix

Method	Retrieval or similarity	Mapping or ranking	Physical budget / comparison caution
Hautier / pymatgen	Data-mined ionic pair probabilities; supplied templates	Conditional-product threshold, charge checks, optional duplicate filtering	Substitution routines do not themselves relax candidates
CSPML	Learned composition-pair classification selects templates	Coefficient-preserving and descriptor-resolved transfer; DFT refinement	Pair-classification accuracy differs from the CSP match rate
ShotgunCSP	Template generator GT (with template-free generator GW)	Equal-coefficient substitution and descriptor assignment; learned CGCNN screening and physical assessment of selected candidates	GT/GW generation, target-specific DFT learning and refinement; task-specific budget
TCSP1/2	Composition templates, inherited embedding/chemistry	Oxidation evidence and chemistry; optional physical stages	Prior rates use their own references, exclusions and relaxation
PNcsp+	PN neighbors in OQMD	Two-potential single-point mean; separate SG best list	Unrelaxed benchmark; different library and candidate counts
TCSP3.0	Embedding and PN routes	Multiple mappings, soft neutral evidence, radius score, structural diversity	Pool cap 100; default ORB-v3 relaxation and energy ranking of the top 20 (native order: no relaxation)

Appendix

Table 7: Element-substitution lineage and the stage emphasized by each method. Physical assessment and reported budgets depend on the original publication protocol; these descriptions are not a controlled accuracy comparison.

Crystal Structure Prediction

Crystal structure prediction seeks stable atomic arrangements from composition, molecular identity, or experimental measurements.

See all 34 papers

Sep 22, 2026

Deep Generative Crystal Structure Prediction: A Benchmark Study and a Controlled Test of Prototype Dependence

Deep generative models are widely reported to enable de novo crystal structure prediction (CSP), but their capability has not been measured consistently against template-based methods. We evaluate 12 representative generative CSP models, spanning latent-variable, diffusion, flow-matching, autoregressive, and manifold random-walk architectures, against TCSP 2.0 on 180 test structures and a leakage-controlled subset of 46. All methods use identical structure-matching, symmetry, and consensus criteria. Template retrieval is the strongest single method, reaching 68.3% top-1 success; symmetry-aware EquiCSP (66.4%) and Uni-3DAR (62.9%) form the next tier. However, comparison with TCSP 2.0 shows that most structures correctly predicted by generative models are also correctly predicted by template substitution. Thus, the set of structures uniquely reachable by generation is small, limiting its practical advantage for discovering structures outside existing prototype libraries. To test the source of this performance, we removed entire stoichiometric prototype families from the training set and retrained the strongest generative model. Accuracy declined by 50-78% across four families, establishing that performance is substantially prototype-dependent. A small minority of structures survived removal of their prototype family, demonstrating a real but limited retrieval-independent predictive capacity. Present generative CSP models therefore function largely as implicit, softer-edged prototype libraries rather than genuinely de novo predictors. Enlarging this residual capacity, rather than aggregate match rate alone, is the central open problem.

Lai Wei, Rongzhi Dong, Ying Feng +2

Department of Computer Science and Engineering, University of South Carolina, Columbia, SC 29201 · Department of Computer Science and Cybersecurity, University of North Georgia, Dahlonega, GA 30597

Crystal Structure Prediction Generative Modeling Crystal Structure Generation

Ask PDF

Sep 9, 2026

uFlowCSP: Crystal Structure Prediction using Mean flow generative models

Crystal structure prediction (CSP) is fundamental to computational materials discovery. Generative models including CDVAE, DiffCSP, FlowMM, and CrystalFlow learn stable-crystal distributions directly, but diffusion and flow-matching inference requires tens to thousands of sequential network evaluations per candidate. We introduce uFlowCSP, a MeanFlow-based CSP model that learns the average, rather than instantaneous, probability-flow velocity. It generates a complete structure in one to five evaluations, delivering 5x-58x faster inference with equal or better performance. A chemistry- and symmetry-aware Transformer uses canonical atom ordering, global composition, and per-token chemistry embeddings. A coarse crystal-system token is used only during training; it provides additive gains, particularly improving space-group agreement despite being absent at inference, which remains formula-only. On MP-20 with 20 candidates per target, one step matches CrystalFlow (78.38% vs. 78.34%) with 100x fewer evaluations and about 10x lower wall-clock time. Five steps reach 83.64%, exceeding CrystalFlow (78.34% at 2,000 evaluations) and DiffCSP (77.93% at about 20,000), while using 20x fewer evaluations. uFlowCSP generates 10,000 structures in 0.39-1.31 minutes, versus 6.5 for CrystalFlow and 76.1 for DiffCSP. Under CSPBench's energy-ranked top-five structure-and-space-group criterion, five-step uFlowCSP reaches 72%/72%/65% structure, space-group, and consensus match rates. CrystalFlow reaches 78%/73%/68% at 100 steps but falls to 49%/32%/31% at five. Thus, uFlowCSP improves accuracy per network evaluation, not merely peak accuracy.

Sourin Dey, Dipannoy Das Gupta, Lai Wei +2

Department of Computer Science and Engineering University of South Carolina Columbia, SC 29201 · Department of Computer Science and Cybersecurity University of North Georgia Columbia, SC 29201

Crystal Structure Prediction One-Step Generative Modeling Crystal Structure Generation Flow-Based Generative Modeling Conditional Generative Modeling Computational Materials Science

Ask PDF

Aug 4, 2025

FastCSP: Accelerated Molecular Crystal Structure Prediction with Universal Model for Atoms

Molecular crystal structure prediction (CSP) is essential for applications in pharmaceuticals and organic electronics. However, CSP remains challenging and computationally intensive due to the need to explore a large search space with sub-kJ/mol accuracy to distinguish between competing polymorphs. While dispersion-inclusive density functional theory (DFT) offers the necessary precision, its computational cost is impractical for a large number of putative structures. Here, we present FastCSP, an open-source, end-to-end CSP workflow driven entirely by a single pretrained universal machine learning interatomic potential (MLIP), the Universal Model for Atoms (UMA), without any system-specific fine-tuning or DFT calculations. FastCSP integrates conformer generation, random structure generation via Genarris 3, geometry optimization, free energy evaluation, and conformer energy corrections, all powered by UMA. Benchmarked on 28 semi-rigid and 10 flexible molecules spanning 74 experimental polymorphs, FastCSP reliably recovers all known structures, ranking them within 9 kJ/mol of the global minimum. UMA reproduces dispersion-inclusive DFT results with high fidelity across chemically diverse compounds. Conformer corrections are particularly beneficial for flexible compounds with conformational polymorphism, such as ROY. UMA's accuracy, transferability, and computational cost thus eliminate the need for classical force fields in early-stage screening and DFT-based re-ranking in CSP workflows. The open-source release of the entire FastCSP workflow lowers the barrier to accessing CSP, enabling both pharmaceutical-grade and high-throughput polymorph screening within practical computational reach.

Vahe Gharakhanyan, Yi Yang, Luis Barroso-Luque +24

Fundamental AI Research at Meta · Department of Materials Science and Engineering, Carnegie Mellon University, Pittsburgh, PA, USA · Department of Chemistry, University of California Riverside, Riverside, CA, USA +3

Crystal Structure Prediction

Ask PDF

Abstract

Crystal Structure Prediction

Explore similar work

Deep Generative Crystal Structure Prediction: A Benchmark Study and a Controlled Test of Prototype Dependence

uFlowCSP: Crystal Structure Prediction using Mean flow generative models

FastCSP: Accelerated Molecular Crystal Structure Prediction with Universal Model for Atoms