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 HuarXiv 2026 · arXiv

TL;DR

TCSP3.0 revitalizes template-based crystal structure prediction (CSP) by fixing fundamental mapping errors in its predecessor and introducing structural deduplication. It achieves a 72.2% Top-1 match rate on the T180 benchmark, outperforming state-of-the-art deep generative models like CrystalFlow while being roughly ten times faster.

What Problem Does This Paper Address?

Predicting how atoms arrange themselves into a crystal lattice based solely on a chemical formula is a "holy grail" of materials science. While deep generative models (using diffusion or flow matching) are currently trendy, template-based methods—which "borrow" the structure of a known, chemically similar material—remain a powerful, computationally efficient alternative.

However, the authors discovered that the previous iteration, TCSP2.0, had a major "silent" failure mode: roughly 20% of its predictions had the wrong chemical composition. This happened because the algorithm ignored stoichiometry during element mapping and used buggy sequential string replacement in CIF files (e.g., accidentally replacing the 'F' inside an 'Fe' symbol). TCSP3.0 aims to fix these correctness issues while adding modern scoring and retrieval features to compete with deep learning baselines.

Methods

The TCSP3.0 workflow follows a five-stage pipeline:

  1. Retrieve: It identifies potential template formulas using two routes: element embeddings (Matscholar) and periodic-number (PN) neighborhoods.
  2. Map: It uses the Hungarian algorithm to find the best element assignments but—crucially—restricts mappings to pairs with equal stoichiometric coefficients.
  3. Validate & Substitute: Instead of risky text-based find-and-replace, it performs simultaneous species substitution on parsed structures and validates that the output matches the target composition and atom count.
  4. Rank & Select: Candidates are ranked using a combination of chemical similarity, soft oxidation-state evidence (via the BERTOS model), and radius-compatibility scoring. It then applies structural deduplication to ensure the Top-20 list contains diverse prototypes.
  5. Refine (Default): The final stage uses the ORB-v3 machine learning potential to relax the structures and rank them by energy.
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.

Datasets

The authors evaluated the model on three primary benchmarks:

  • T46 & T180: Revised versions of existing benchmarks, cleaned to ensure high-quality reference structures and to eliminate overlap with training data from the machine learning potentials used.
  • T800: A newly introduced, independent cohort of 800 targets. These are generally more complex, containing 4–52 atoms per cell, compared to the 2–28 atoms in T180.

Key Insights and Ideas

  • Correctness is the Biggest Lever: Ablation studies revealed that the massive jump in performance (from 28% to 72% Top-1) was primarily due to fixing the mapping and substitution logic. In CSP, "boring" software engineering and data validation can be more impactful than complex new scoring functions.
  • Deduplication Boosts Success: Without deduplication, the candidate pool often fills up with slight variations of the same structure. Removing these redundancies significantly improves the Top-5 match rate by making room for different structural prototypes.
  • Templates Still Beat Generative Models: Despite not being able to "invent" entirely new prototypes, TCSP3.0's ability to accurately transfer known frameworks allows it to beat leading generative models like CrystalFlow and MaskGXT in both accuracy and speed.
  • Speed vs. Accuracy Trade-off: Even without the expensive relaxation step (the "native" mode), TCSP3.0 achieves a 67.8% Top-1 match rate in just 28 seconds per target on a standard CPU—making it an excellent tool for high-throughput screening.

Key Results

  • Accuracy: On the T180 benchmark, TCSP3.0 achieved a 72.2% Top-1 and 90.6% Top-20 match rate. This is more than double the performance of TCSP2.0 (28.3% Top-1).
  • Comparison: It outperformed the deep learning-based CrystalFlow (63.9%) and MaskGXT (62.8%) on the same T180 targets.
  • Efficiency: The template generation stage is roughly 10x faster than the generative stage of CrystalFlow.
  • Generalization: On the new, larger T800 benchmark, it maintained a strong Top-20 match rate of 74.0%, proving it scales well to more complex compositions.

Limitations and Future Work

  • Template Dependency: As a template-based method, it cannot predict truly novel crystal prototypes that don't already exist in its library.
  • Single Reference Matching: The current evaluation only checks if the model finds one specific reference structure; it doesn't yet account for the prediction of all possible stable polymorphs.
  • Future Directions: The authors suggest incorporating bond-valence validation and site-resolved mixed valence to better handle complex local chemical environments. They also propose a hybrid approach: using template-based methods where analogues exist and generative models only when they don't.

Summary updated

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.
BibTeX
@misc{feng2026tcsp,
  author = {Ying Feng and Jeffrey Hu and Lai Wei and Liang Tao and Madeline Miklos and Dipannoy Das Gupta and Hossein Erfanshekooh and Jianjun Hu},
  title = {{TCSP3.0: Template-Based Crystal Structure Prediction with Coefficient-Preserving Element Substitution and Structural Diversity}},
  year = {2026},
  eprint = {2610.34029},
  archivePrefix = {arXiv},
  url = {https://arxiv.org/abs/2610.34029},
}
Figure