Troubleshooting & Validation

This page helps you diagnose common XTalNet problems across both tools — de novo crystal structure prediction from a SMILES string or PXRD pattern (xtalnet_csp_predict), and polymorph/co-crystal screening (xtalnet_polymorph_predict) — and walks through the validation steps and inputs to re-check before filing a ticket.

Prediction issues

• Job will not submit: provide either a SMILES string, or PXRD data plus a compound formula — one of the two is required. See inputs & restraints.
• PXRD file rejected or misparsed: files must contain angle (2θ), intensity pairs — comma, semicolon, or whitespace separated, with #/// comment lines. Check the data-point count and first-rows preview the tool shows after upload.
• Too few or too many candidates: the number of generated structures is set by Number of Candidates — 1–50 (default 10) for Crystal Structure Prediction, 10–50 (default 25) for Polymorph Screening. Raise the count if a single run misses the form you expect.
• All predictions filtered out: the Min Confidence Threshold (0–1, default 0.5) may be too strict for a noisy pattern — lower it to see more candidates, then triage manually.
• Wrong crystal system: constrain results with the optional crystal-system preference (cubic, tetragonal, monoclinic, and so on) when you already know the expected symmetry.
• Co-crystal prediction fails: coformer_smiles is only accepted by xtalnet_polymorph_predict, not xtalnet_csp_predict — run polymorph screening for co-crystal candidates.

Validation steps

• Sort xtalnet_csp_predict results by energy_kcal in energy_landscape_json/summary_csv — the lowest-energy candidates are the most thermodynamically favorable.
• For polymorph screening, check stability_rank and is_metastable in stability_ranking_json before treating a form as viable long-term.
• Sanity-check the unit-cell atom count against Max Atoms per Unit Cell (default 400) — organic structures up to ~400 atoms are supported.
• Cross-check a predicted structure against reality by simulating its diffraction pattern with PyWPEM's simulate_xrd and comparing it to any experimental data you have.

Inputs to re-check

• SMILES path: the SMILES string parses (it must use a restricted ASCII alphabet — letters, digits, brackets, ring-closure digits, bond and charge symbols).
• PXRD path: the compound formula matches the molecule, and the pattern's 2θ range and wavelength (pxrd_metadata.wavelength, default Cu K-alpha) are correct.
• Polymorph path: num_candidates is within 10–50, and polymorph_similarity_threshold (default 0.85) isn't so low that distinct forms collapse into one.

Ticket checklist

• SMILES string, or PXRD data + compound formula.
• Tool used (xtalnet_csp_predict or xtalnet_polymorph_predict), candidate count, confidence threshold, and any crystal-system or coformer constraint used.
• The job's jobId and status, and any error message returned.

Read next