PyXplore

PyXplore is a Python toolkit for powder X-ray diffraction (XRD) analysis and broader materials characterization.

It bundles the WPEM (Whole-Pattern Expectation-Maximization) refinement engine together with utilities for XRD simulation, background fitting, peak decomposition, XPS / EXAFS spectrum analysis, amorphous-material RDF calculation, and crystal-graph generation for machine-learning workflows.

Paper: https://arxiv.org/abs/2602.16372

Features

• WPEM XRD refinement — Whole-pattern EM solver for crystallographic refinement, lattice-constant optimization, and quantitative phase analysis.
• XRD simulation — Simulate diffraction patterns from CIF files; supports supercells, solid solutions, vacancies, grain-size broadening, preferred orientation, thermal vibration, and zero-shift.
• Background fitting — FFT + Savitzky-Golay two-stage filter for XRD / XPS / Raman background removal.
• Extinction analysis — Compute systematic extinctions and multiplicity factors for all seven crystal systems.
• Amorphous materials — Multi-peak amorphous fitting and radial-distribution-function (RDF) calculation.
• XPS decomposition — EM-based decomposition of X-ray photoelectron spectra with satellite-peak handling.
• EXAFS analysis — k-space / R-space EXAFS data processing with wavelet & Fourier inverse transforms.
• Crystal graphs — Convert CIF batches into node/edge graph representations for GNN training.
• Structure relaxation — Optional M3GNet-based geometry relaxation.
• Substitutional search — Bayesian-optimization-driven solid-solution composition search.

Installation

pip install PyXplore

Requirements

• Python ≥ 3.8
• numpy, scipy, pandas, matplotlib, sympy, scikit-learn, tqdm
• pymatgen, monty
• ipywidgets, ipython, plotly, PyWavelets
• (Optional) tensorflow, ase — required only for the m3gnet extra

Public API

All high-level entry points are exposed under PyXplore.WPEM:

Utility helpers — ToMatrix, ToAdj, split_datasets, Laplacian — are also available under PyXplore.WPEM.

CIFpreprocess now saves a binary structure record alongside its generated HKL file, including the CIF space group and symmetry operations. After XRDfit, the corresponding CIF is found from the HKL set; initial lattice parameters are not compared because refinement can change them. The output is written to WPEMFittingResults by default (or cif_output_dir), retaining atom sites and symmetry while changing only the refined unit-cell parameters. If multiple candidates match, CIF export is stopped rather than risking a wrong phase assignment. cif_files can optionally restrict the candidate templates, but their order is not used.

Structure pre-solver

Use StructureSolve after background deduction and before XRDfit to obtain a stronger starting structure for refinement:

from PyXplore import WPEM

result = WPEM.StructureSolve(
    "ConvertedDocuments/no_bac_intensity.csv",
    "starting_structure.cif",
    wavelength="CuKa",
    num_peaks=None,  # automatic strong-peak selection; e.g. set 10 to fix it
    coordinate_window=0.01,  # retain atom positions locally
    cell_window=0.35,        # allow a broader lattice-constant search
)
print(result["accepted"], result["reason"])

The solver constrains the unit-cell metric to the input crystal system and optimizes asymmetric-unit fractional coordinates in a local window. It accepts an update only when the detected space group/crystal system is unchanged, at least 70% of selected strong peaks match calculated reflections, and the score improves by at least 2%. On acceptance it saves the original CIF in WPEMFittingResults and replaces the supplied CIF; on rejection the supplied CIF is untouched. In both cases, the best numerical candidate is retained as *_structure_solver_best.cif in WPEMFittingResults, and structure_solver_report.json records the selected peaks, scores, and decision.

Citation

If you use PyXplore in your research, please cite:

@article{cao2026wpem, title={AI-Driven Structure Refinement of X-ray Diffraction}, author={Bin Cao, Qian Zhang, Zhenjie Feng, Taolue Zhang, Jiaqiang Huang, Lu-Tao Weng, Tong-Yi Zhang}, journal={arXiv preprint}, year={2026}, url={https://arxiv.org/abs/2602.16372v1} }

About

Developed and maintained by Bin Cao, PhD of the Hong Kong University of Science and Technology (Guangzhou).

• Personal page : https://bin-cao.github.io
• Repository : https://github.com/Bin-Cao/PyWPEM
• Contact : binjacobcao@gmail.com

Please open an issue on GitHub for bug reports, feature requests, or general questions.

License

Released under the MIT License.