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.

XRD, XPS, and amorphous fitting share the same profile R-factor calculation. Both select points where observed - background is strictly above 5% of its maximum within the fitting range, and the total observed intensity is positive. The signed net signal is used for selection without absolute values or shifts. Rp and Rwp then compare the background-inclusive observed and fitted profiles, using Poisson weights proportional to 1 / observed without a fixed weight floor. XRD/XPS iteration metrics use the initial background; final metrics use the updated background for both selection and reconstruction of the fitted total. Amorphous fitting restores its removed constant background for the comparison. The background-subtracted inputs to the fitting iterations are unchanged. These percentages describe only the selected subset, not the full profile. Empty/non-finite inputs or no eligible points yield NaN.

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.