---
title: PyWPEM quickstart
description: Simulate a pattern from a CIF with simulate_xrd, then run fit_background before refine_xrd, which needs its variance and both background CSVs.
tags:
  - pywpem
  - quickstart
---

## 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

### Step 1: Open PyWPEM

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

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

### Step 2: 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) |

### Step 3: 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

### Step 4: 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](/docs/opxrd) similarity search.

## Workflow 2: Whole-pattern (WPEM) refinement

### Step 1: 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.

### Step 2: Configure the refinement

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

### Step 3: Evaluate the refinement

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.

### Step 4: 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](/docs/pywpem/inputs) for all 14 operations and their parameters
- See [outputs](/docs/pywpem/outputs) for R-factor interpretation and result fields
- Use [OpXRD](/docs/opxrd) to search for reference patterns before refinement

## Read next