README.md

May 8, 2026 · View on GitHub

XDecomposer: Learning Prior-Free Set Decomposition for Multiphase X-ray Diffraction

Important

XDecomposer is the first deep learning framework for true whole-pattern multiphase XRD decomposition.
Instead of performing conventional search-match or iterative peak subtraction, XDecomposer directly decomposes a mixed diffraction pattern into phase-wise components through query-based blind source separation and physics-consistent reconstruction. This work marks a major shift for AI-driven XRD analysis, moving the field from phase recognition toward genuine diffraction understanding and structure-level decomposition.

Project Overview

XDecomposer is designed to separate complex mixed diffraction signals into interpretable individual phase patterns, enabling automated mineralogical and crystallographic analysis.

The framework integrates:

Self-supervised representation learning
Supervised decomposition modeling
Fine-tuning on real experimental data
Unified training / evaluation pipelines

Pre-trained Models & Dataset

Please download and extract them into your local XDecomposer/ directory.

Installation

git clone https://github.com/your-org/XDecomposer.git
cd XDecomposer
conda create -n xdecomposer python=3.10
conda activate xdecomposer
pip install -r requirements.txt

Configuration

All environment variables and paths are centrally managed in:

configs/paths.sh

This acts as the single source of truth for the project.

Main Settings

Category	Variables
Conda Environment	`CONDA_ACTIVATE_PATH`, `CONDA_ENV_NAME`
Dataset Paths	`PATH_DATA_SINGLEPHASE`, `PATH_DATA_RRUFF`
Checkpoints	`PATH_CKPT_MAE`, `PATH_CKPT_SEP`
Output Folder	`PATH_OUTPUT_TEST`

bash scripts/bash_train/run_pretrain.sh

Separation Backbone Training

The training runner is scripts/python_runners/train_xdecomposer.py.

bash scripts/bash_train/run_xdecomposer.sh --gpus 0,1 --name main

RRUFF Fine-tuning (5-Fold CV)

bash scripts/bash_train/run_rruff_finetune_kfold.sh

2. Evaluation

MP20 Multiphase Benchmark

bash scripts/bash_test/run_mp20_k_test.sh

RRUFF Real-world Evaluation

bash scripts/bash_test/run_rruff_k_test_kfold.sh

Repository Structure

XDecomposer/
├── configs/                 # Path / environment settings
│   ├── ablation_configs/
│   └── paths.sh
│
├── scripts/
│   ├── bash_train/          # Training scripts
│   ├── bash_test/           # Evaluation scripts
│   ├── bash_ablation/       # Ablation studies
│   └── python_runners/      # Python entrypoints
│
├── src/                    # Core model source code
├── tutorial/               # Tutorial examples
└── checkpoints/            # Saved weights

Key Features

End-to-end multiphase XRD decomposition
Self-supervised feature pretraining
Real-world dataset adaptation
Modular research-friendly design
Easy bash-based training pipelines
Benchmark-ready evaluation tools

Citation

If you use XDecomposer in your research, please cite:

@misc{gao2026xdecomposerlearningpriorfreeset,
      title={XDecomposer: Learning Prior-Free Set Decomposition for Multiphase X-ray Diffraction}, 
      author={Hanyu Gao and Bin Cao and Yunyue Su and Tong-Yi Zhang and Qiang Liu},
      year={2026},
      eprint={2605.05866},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.05866}, 
}