---
tags:
  - crystallography
  - x-ray-diffraction
  - single-crystal-structure-analysis
  - chemistry
  - pytorch
---

# CrystalX: High-accuracy Crystal Structure Analysis Using Deep Learning

**Accepted by the *Journal of the American Chemical Society* (JACS)**
**Invited for a journal cover feature**

## Overview

CrystalX is an AI system for routine single-crystal structure analysis from real experimental X-ray diffraction (XRD) data.

Designed specifically for everyday single-crystal structure solution, CrystalX uses geometric deep learning to model electron density and capture underlying three-dimensional geometric interactions directly from large-scale experimental XRD datasets. Compared with traditional rule-based approaches for automatic elemental determination, such as those used in **SHELXT** and **Olex2**, CrystalX delivers substantially improved accuracy and robustness.

In prospective, deployment-style evaluations, CrystalX was also compared with **AutoChem** under practical experimental conditions. Because AutoChem requires a real instrument-generated metadata file (`.cif_od`) produced by the **CrysAlisPro** data-reduction workflow, the comparison was performed on real-world cases that satisfied this requirement. CrystalX successfully solved **3/3** test cases, whereas AutoChem solved **1/3**.

CrystalX provides the following capabilities:

* Accurate discrimination between non-hydrogen atoms with similar atomic numbers, including challenging pairs such as **C/N/O** and **P/S/Cl**
* Fast and fully correct solution of large organometallic structures containing up to **370 non-hydrogen atoms**
* Detection of **9 verified expert interpretation errors** among **1,559** held-out structures published in **JCR Q1 journals**, including subtle cases that triggered no **CheckCIF A/B** alerts
* Confidence scores for both heavy-atom and hydrogen predictions
* Natural integration into standard crystallographic workflows

---

## Model Architecture

CrystalX adopts a two-stage geometric deep learning pipeline to predict both non-hydrogen and hydrogen atoms.

Both public checkpoints are built on an Equivariant Transformer backbone, specifically TorchMD-NET.

For hydrogen prediction, CrystalX leverages both intramolecular and intermolecular context by incorporating symmetry-equivalent neighbors within 3.2 Å. This design yields more than a 7% improvement over using intramolecular information alone.

---

## Available Checkpoints

This repository provides the two official inference checkpoints used in the CrystalX pipeline:

- `crystalx-heavy.pth`
- `crystalx-hydro.pth`

### `crystalx-heavy.pth`

Predicts **non-hydrogen element types** from coarse electron-density peaks generated by automatic phasing tools such as **SHELXT**, and outputs a **confidence score** for each prediction.

### `crystalx-hydro.pth`

Predicts the **number of hydrogens attached to each heavy atom** after heavy-atom determination, and also provides a **confidence score**.

---

## Intended Use

In practice, CrystalX can be inserted at different stages of the pipeline for both **heavy-atom** and **hydrogen** prediction seamlessly. The official codebase provides a lightweight integration with the **SHELX** suite, enabling a simple **`.res`-to-`.res`** workflow.

### Current Limitation: Disorder

CrystalX does not currently support the resolution of crystallographic disorder, largely because high-quality annotated training data for these cases are scarce. At the same time, disorder prediction is closely connected to the accurate detection and interpretation of residual electron density, making it a natural future extension of the current framework.

We view disorder modeling as a particularly promising direction for further development. Interpreting disorder is inherently a sequential, multi-step reasoning task: it involves iterative analysis, hypothesis generation, testing, and refinement rather than a single-pass prediction. In this context, agentic AI and reinforcement learning may offer a compelling path forward, as they could enable models to learn from sequential refinement processes and better capture the stepwise reasoning needed for robust disorder resolution.

---

## Minimal End-to-End Workflow

A typical wrapper pipeline is:

`SHELXT -> CrystalX Heavy -> SHELXL refinement -> CrystalX Hydro -> HFIX/AFIX placement -> SHELXL refinement -> weight refinement -> PLATON / CheckCIF`

1. **SHELXT** generates coarse electron-density peaks.
2. **CrystalX Heavy** predicts non-hydrogen atom types from geometric peak interactions.
3. **SHELXL** refines the heavy-atom framework.
4. **CrystalX Hydro** predicts how many hydrogens are attached to each heavy atom.
5. **HFIX/AFIX** placement and subsequent refinement produce the final all-atom structure.

Demo: `https://crystalx.intern-ai.org.cn/`

## Code

- GitHub: `https://github.com/kaipengm2/CrystalX`

## Citation

If you find this repository useful, please cite:

```bibtex
@article{doi:10.1021/jacs.5c21832,
  author  = {Zheng, Kaipeng and Huang, Weiran and Ouyang, Wanli and Zhong, Han-Sen and Li, Yuqiang},
  title   = {CrystalX: High-Accuracy Crystal Structure Analysis Using Deep Learning},
  journal = {Journal of the American Chemical Society},
  volume  = {0},
  number  = {0},
  pages   = {null},
  year    = {0},
  doi     = {10.1021/jacs.5c21832}
}
```