Metadata-Version: 2.4
Name: PyXplore
Version: 2026.10.16
Summary: A powder X-ray diffraction analysis and materials-characterization toolkit
Home-page: https://github.com/Bin-Cao/PyWPEM
Author: Bin Cao
Author-email: binjacobcao@gmail.com
Maintainer: Bin Cao
Maintainer-email: binjacobcao@gmail.com
License: MIT
Project-URL: Homepage, https://github.com/Bin-Cao/PyWPEM
Project-URL: Documentation, https://pyxplore.netlify.app
Project-URL: Source, https://github.com/Bin-Cao/PyWPEM
Project-URL: Tracker, https://github.com/Bin-Cao/PyWPEM/issues
Project-URL: Author, https://bin-cao.github.io
Project-URL: Paper, https://arxiv.org/abs/2602.16372
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy==1.26.4
Requires-Dist: scipy==1.15.3
Requires-Dist: pandas==2.3.3
Requires-Dist: sympy==1.14.0
Requires-Dist: pymatgen==2024.4.13
Requires-Dist: matplotlib==3.7.1
Requires-Dist: plotly==6.6.0
Requires-Dist: monty==2025.3.3
Requires-Dist: spglib==2.7.0
Requires-Dist: tqdm==4.67.3
Requires-Dist: ipywidgets==8.1.8
Requires-Dist: scikit-learn==1.7.2
Requires-Dist: PyWavelets==1.8.0
Requires-Dist: ase==3.26.0
Requires-Dist: tensorflow==2.16.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
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`:

| Function               | Purpose                                                  |
| ---------------------- | -------------------------------------------------------- |
| `XRDfit`               | Whole-pattern XRD refinement (WPEM engine); can save refined CIFs from templates |
| `BackgroundFit`        | Two-stage FFT + Savitzky-Golay background fitting        |
| `FileTypeCovert`       | Convert `.dat` / `.xrdml` files to standard format       |
| `Amorphous_fit`        | Amorphous multi-peak fitting                             |
| `AmorphousRDFun`       | Radial distribution function calculation                 |
| `Plot_Components`      | Plot decomposed-peak components                          |
| `XRDSimulation`        | Single-crystal / supercell XRD simulation from CIF       |
| `CIFpreprocess`        | CIF reading, unit-cell preview, extinction calculation   |
| `SubstitutionalSearch` | Bayesian-optimization-driven solid-solution search       |
| `XPSfit`               | XPS spectrum EM decomposition                            |
| `EXAFSfit`             | EXAFS k-space / R-space processing                       |
| `CryGraph`             | Crystal-graph generation from a folder of CIFs           |
| `StructureSolve`       | Constrained structure pre-solver from background-subtracted XRD and CIF |

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:

```python
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.
