PyWPEM troubleshooting

This page helps you diagnose the most common 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 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