---
title: PyWPEM troubleshooting
description: 'Fix a CIF missing _cell_length_a or _atom_site_fract_x, a refinement whose rwp climbs with convergence_flag not 1, and a simulation with peak_count 0.'
tags:
  - pywpem
  - troubleshooting
---

This page helps you diagnose the most common [PyWPEM](/docs/pywpem) failures — CIF files that will not parse, Rietveld refinements that diverge, and simulations that produce no peaks — most of which trace back to structure, parameter, or wavelength mismatches.

## PyWPEM troubleshooting

## CIF file fails to parse

**Symptom**: "Invalid CIF" or "Missing required CIF fields" error.

**Causes and fixes**:

- **Missing cell parameters**: Ensure `_cell_length_a/b/c` and `_cell_angle_alpha/beta/gamma` are present
- **Missing atom sites**: The CIF must include `_atom_site_fract_x/y/z` coordinates
- **Missing space group**: Include `_symmetry_space_group_name_H-M` or `_space_group_name_H-M_alt`
- **Encoding issues**: CIF files must be ASCII or UTF-8. Remove any non-ASCII characters from comments.
- **Syntax errors**: Validate your CIF file with [checkCIF](https://checkcif.iucr.org/) before uploading.

## Refinement diverges

**Symptom**: `rwp` increases with iterations, `convergence_flag` isn't 1, or the job reports a divergence message.

**Fixes**:

- **Wrong starting structure**: Ensure the CIF matches the actual phase. Compare a `simulate_xrd` prediction against your data first if you're unsure.
- **Poor background model**: Run `fit_background` first and pass its `variance`, `background_url`, and `no_background_url` into `refine_xrd` — `refine_xrd` requires all three and a bad background destabilizes the fit.
- **Rigid lattice needed**: Set `fixed: true` on a phase entry in `phases` to keep its lattice constants fixed instead of refining them.
- **Wavelength mismatch**: Verify `wavelength_preset` (or `custom_wavelengths`) matches your instrument (Cu vs Mo vs Co K-alpha).
- **Data quality**: Noisy or truncated data can destabilize refinement. Ensure good counting statistics and sufficient angular range.

## Simulation produces no peaks

**Symptom**: `simulate_xrd` returns a pattern with `peak_count: 0` or a flat plot.

**Causes**:

- **Two-theta range mismatch**: The expected peaks may fall outside your specified range. Widen `two_theta_min`/`two_theta_max`.
- **Wrong wavelength**: A very short wavelength shifts all peaks to low angles. Check `wavelength_preset` (or `custom_wavelengths` if using `"custom"`).
- **Extinct reflections**: Some space groups have systematic absences. This is correct behavior -- those reflections genuinely have zero intensity.

## Job times out on GPU

**Symptom**: Job exceeds the timeout limit.

**Fixes**:

- Narrow the two-theta range or increase `two_theta_step` for faster computation
- A `refine_xrd` call with many entries in `phases` takes longer — start with the dominant phase and add others once that converges
- Large datasets increase computation time roughly proportionally
- If timeouts persist, the GPU instance may need cold-start time. Retry after a few minutes.

## Radial distribution function looks wrong

**Symptom**: `calculate_rdf` produces spurious oscillations or an implausible `first_neighbor_distance`/`coordination_number`.

**Fixes**:

- **Missing density/scattering inputs**: Set `density_atoms_per_cc` and `scattering_factor` — without them the normalization can be off
- **`r_max` too small**: Increase `r_max` if you expect coordination shells beyond the default 10 Å
- **Background contamination**: Subtract background (`fit_background`) before computing the RDF

## Getting help

If issues persist:

1. Check the job logs for specific error messages
2. Validate CIF files externally before uploading
3. Start with `simulate_xrd` to verify the structure before attempting refinement
4. Describe the issue to Ivy

## Read next