---
title: PyWPEM
description: >-
  GPU-powered X-ray diffraction refinement, simulation, and spectroscopy
  analysis.
tags:
  - pywpem
---

PyWPEM lets you simulate a theoretical diffraction pattern from a crystal structure and refine experimental XRD data against known structures with GPU-accelerated Rietveld analysis. Reach for it when you have a CIF structure or measured data and need refinement, phase quantification, PDF analysis, or peak fitting. Where [OpXRD](/docs/opxrd) searches a database of experimental patterns for phase identification, PyWPEM computes and fits patterns directly — and it can simulate the diffraction expected from a structure that [XTalNet](/docs/xtalnet) predicts. See the [Materials & Crystals overview](/docs/materials-crystals) for where this fits.

## PyWPEM overview

PyWPEM (PyXplore) provides GPU-accelerated X-ray diffraction analysis through 14 operations. It handles everything from simulating theoretical diffraction patterns to refining experimental data against known crystal structures. Computationally intensive operations run on Modal GPU instances for fast turnaround.

## How it works

 API["PyWPEM API (Modal GPU instance)<br/>14 operations: simulate, refine,<br/>fit, identify, compute PDF, convert"]
    API --> Res[Results: refined parameters,<br/>patterns, diagnostics]`}
  caption="XRD data and a CIF structure are dispatched to the GPU-backed PyWPEM API, which runs the chosen operation and returns refined parameters, patterns, or diagnostics. Full operation list below."
/>

## All 14 operations

| Operation | Description | Required Inputs |
|-----------|-------------|-----------------|
| `fit_background` | Piecewise polynomial background fitting | `xrd_data_url` |
| `simulate_xrd` | Generate a theoretical pattern from a crystal structure | `cif_url` or `cif_content` |
| `refine_xrd` | Whole-pattern refinement (WPEM algorithm) to determine lattice constants — one or more phases via `phases[]` | `xrd_data_url` + `phases` |
| `fit_amorphous` | Fit Gaussian mixtures to amorphous contributions | `xrd_data_url` |
| `preprocess_cif` | Extract lattice parameters and peak positions from a structure | `cif_url` or `cif_content` |
| `calculate_rdf` | Radial distribution function from amorphous XRD data | `xrd_data_url` |
| `generate_crystal_graph` | Build crystal connectivity graphs for GNN input (CGCNN, MEGNet) | `cif_url` or `cif_content` |
| `search_substitutional_sites` | Find energetically favorable substitutional defect sites | `cif_url` + `target_element` + `substitute_element` |
| `fit_xps` | X-ray photoelectron spectroscopy peak fitting | `xps_data_url` + `peaks` |
| `fit_exafs` | Extended X-ray absorption fine structure analysis | `xafs_data_url` |
| `plot_components` | Generate publication-quality component plots | `plot_type` |
| `convert_file_format` | Convert between XRD file formats (CSV, XY, XYE, CIF, JSON, RAW, BRML) | `input_url` + `input_format` + `output_format` |
| `compute_graph_matrix` | Compute adjacency or Laplacian matrices from a crystal structure | `cif_url` or `cif_content` |
| `split_ml_datasets` | Split crystallographic data for ML training/validation/test | `data_url` or `data_urls` |

Multi-phase refinement isn't a separate operation — `refine_xrd`'s `phases` parameter takes an array, so one or more phases refine in the same call.

## When to use PyWPEM

**Use PyWPEM when:**

- You need to simulate a theoretical diffraction pattern from a crystal structure (CIF file)
- You have experimental XRD data and need whole-pattern (WPEM) refinement against one or more phases
- You need XPS or EXAFS spectroscopy peak fitting
- You need a crystal connectivity graph for GNN input, a radial distribution function, or a substitutional-site search
- You need peak-broadening simulation, background subtraction, or XRD file-format conversion

**Use OpXRD instead when:**

- You need to search a database of experimental patterns for phase identification
- You want to find reference patterns for specific element combinations
- You need CrystalNN fingerprint-based similarity search

## Limitations

- CIF files must be well-formed with complete symmetry information. Partial CIFs may cause simulation failures.
- Whole-pattern refinement requires good starting parameters. Poor initial guesses may cause divergence.
- GPU allocation adds ~5-10 seconds of cold-start time for the first job in a session.

## Citations

> Cao B, Zhang Q, Feng Z, Zhang T, Huang J, Weng LT, Zhang TY. AI-Driven Structure Refinement of X-ray Diffraction. 2026. arXiv: [2602.16372](https://arxiv.org/abs/2602.16372) (PyWPEM software: [https://github.com/Bin-Cao/PyWPEM](https://github.com/Bin-Cao/PyWPEM))

> Rietveld HM. A profile refinement method for nuclear and magnetic structures. *J Appl Crystallogr*. 1969;2(2):65-71. doi: [10.1107/S0021889869006558](https://doi.org/10.1107/S0021889869006558)

## FAQ

### What operations does PyWPEM support?

  14 operations including whole-pattern refinement, simulation, background fitting, amorphous fitting, CIF preprocessing, crystal graph generation, substitutional-site search, XPS/EXAFS spectroscopy fitting, and file conversion.

### What input formats are accepted?

  XRD data as an S3 URL to a CSV (`xrd_data_url`), and CIF crystal structures either by URL (`cif_url`, e.g. from the COD) or as inline text (`cif_content`).

### Is GPU acceleration available?

  Yes, computationally intensive operations run on GPU-accelerated Modal instances.

## Read next