Simulate a pattern from a CIF with simulate_xrd, then run fit_background before refine_xrd, which needs its variance and both background CSVs.

PyWPEM quickstart

This guide covers two workflows: simulating a theoretical XRD pattern from a crystal structure, and refining experimental data against a known structure.

Workflow 1: Simulate an XRD pattern

Open PyWPEM

Navigate to Tools > PyWPEM in .bloom*, or ask Ivy:

Simulate an XRD pattern from this CIF file for Cu K-alpha radiation

Configure the simulation

Parameter	Value
Operation	`simulate_xrd`
CIF input	`cif_url` (e.g. a COD URL) or `cif_content` (paste the CIF text)
Wavelength preset	`CuKa1Ka2` (default)
Two-theta range	`two_theta_min: 10`, `two_theta_max: 90` (defaults)

Review the simulated pattern

The result includes:

Pattern and peak artifacts: pattern_csv_url and peaks_csv_url, plus a plot_url for a quick visual check
Peak count and range: peak_count, two_theta_min/two_theta_max
Structure info: formula and space_group, when extractable from the CIF

Download the pattern

Follow pattern_csv_url to export the simulated pattern as CSV for comparison against experimental data, or use it as a reference when running OpXRD similarity search.

Fit and subtract the background first

refine_xrd requires a background variance and a background-subtracted dataset, so run fit_background before it:

Parameter	Value
Operation	`fit_background`
`xrd_data_url`	S3 URL to your experimental XRD CSV
`background_segments`	`5` (default)

Take the variance, background_csv_url (→ background_url), and no_background_csv_url (→ no_background_url) from the result — refine_xrd needs all three.

Parameter	Value
Operation	`refine_xrd`
`xrd_data_url`	Your original experimental data
`background_url` / `no_background_url` / `variance`	From step 1's `fit_background` result
`phases`	`[{"name": "rutile", "cif_url": "..."}]` — add more entries here for a multi-phase refinement
`max_iterations`	`40` (default)

Or ask Ivy:

Refine my XRD data against the rutile TiO2 structure

Check the quality indicators in the result:

Metric	Field	Target
Weighted profile R-factor	`rwp`	< 10%
Convergence	`convergence_flag` = 1, `convergence_message`	Converged

rp and rwp are computed from the fit and can come back null if the solver couldn't compute them for a given run — check metrics_available and metrics_unavailable_reason before trusting a missing value. Goodness-of-fit / chi² isn't computed by this tool — gof is always null. Review the residual_plot_url for systematic deviations that may indicate an unmodeled phase or an incorrect structure.

Iterate if needed

If the refinement quality is poor:

Check that the CIF file matches the actual phase
Re-check the background fit — a poor fit_background result destabilizes refine_xrd
Add a second phase entry to phases if the residual plot shows unmodeled peaks

Workflow 3: Extract structure info from a CIF

To pull lattice parameters and peak positions straight from a structure file, without simulating a full pattern:

Preprocess this CIF file and extract its lattice parameters

This runs preprocess_cif, returning lattice_constants, space_group, formula, density, and the predicted peak list — useful before deciding whether a candidate structure is worth simulating or refining against.

Next steps

See inputs for all 14 operations and their parameters
See outputs for R-factor interpretation and result fields
Use OpXRD to search for reference patterns before refinement

PyWPEM quickstart