Messages#

PowderLine speaks to you in three ways:

a validation error stops a recipe before anything runs;
a warning comes with a valid recipe or a finished run;
a failure reason names why a run failed.

Validation errors#

An invalid recipe raises pydantic’s ValidationError. It lists every problem at once, each at its field path. Most messages name the value to write.

$ pixi run powderline my_recipe.json --validate-only

❌ Recipe validation failed: my_recipe.json

Validation errors:
  • payload -> instrument -> radiation: Field required
  • payload -> instrument -> radiaton: Extra inputs are not permitted
  • payload -> phases -> LaB6 -> unit_cell: Value error, unit cell is inconsistent with 'P m -3 m' (cubic): stated b = 4.2, but by symmetry b = a; write b = 4.15682

Please fix the errors above and try again.
See examples/example_LaB6/input.json for a working example.

The command exits with status 1.

In Python, catch the error and read its list:

from pydantic import ValidationError

try:
    powderline.validate(recipe)
except ValidationError as e:
    for problem in e.errors():
        print(problem["loc"], problem["msg"])

loc is the field path as a tuple, e.g. ('payload', 'phases', 'LaB6', 'unit_cell').
Structural checks (the cell against the space group, special positions, tie groups) run once the individual fields are valid. Fix the first errors and validate again to see them.
Validation needs no engine. It works in every environment.

Why the checks are strict, and what they check, is on Validation.

Warning codes#

A warning is a dict {code, message, field_path[, level]}. It comes back in result["warnings"], in powderline.validate(recipe).warnings, and in the validate-only summary.

level: "warning": act on it, or decide about it. The CLI prints these.
level: "info": a record of something PowderLine did that changes no outcome. The CLI counts these, and lists them with --verbose.
No level key means "warning".

Code	Engine	Level	Meaning
`gsasii_broadening_default_applied`	gsasii	warning	Sample size or strain left out: 10 µm and 0 microstrain applied, fixed.
`gsasii_background_default_applied`	gsasii	warning	`background` (or its `chebyshev`) left out: one fixed Chebyshev term 0.0 applied, instead of GSAS-II’s own default, a fixed constant 1.0.
`gsasii_refinement_cycles_default_applied`	gsasii	warning	`refinement_cycles` left out: the default 5 cycles run.
`gsasii_refinement_message`	gsasii	warning	A message GSAS-II stored with the refinement: correlations, singular parameters, SVD.
`gsasii_fit_not_converged`	gsasii	warning	The last cycle’s χ² change was above GSAS-II’s tolerance. The values are kept.
`gsasii_parameters_not_varied`	gsasii	warning	GSAS-II varied fewer parameters than the recipe refines.
`uaniso_not_positive_definite`	core	warning	The stated `Uaniso` has a principal value ≤ 0. It is used as stated.
`symmetry_value_derived`	core	info	A coordinate, cell value or Uij stated within tolerance of its exact symmetry-derived value is held in that form. The message gives both values. An exactly stated value gets no note.
`output_recipe_not_valid`	core	warning	The output recipe does not validate as written: an engine returned a value the schema refuses, or a symmetry tie came back inconsistent. It is still returned and written, with `output_recipe_valid: false`.
`topas_adp_converted`	topas	warning	`Uiso` was written to TOPAS as `beq = 8π²·Uiso`.
`topas_parameter_at_limit`	topas	warning	A refined value ended at a stated bound or a TOPAS default limit.
`topas_parameters_not_varied`	topas	warning	TOPAS varied fewer parameters than the recipe refines.
`topas_phase_contributes_nothing`	topas	info	A phase’s calculated intensities are all zero: its scale is 0, or TOPAS discarded a non-finite calculation.
`topas_base_name_sanitized`	topas	warning	The base name is not ASCII-safe for TOPAS, so the files are written as `topas.*`.
`topas_background_not_calculated`	topas	warning	The background-only run wrote nothing or was stopped at the time limit. `y_bkg` is empty.
`topas_generate_only`	topas	info	No `tc.exe` declared: the INP and `.xye` were written and TOPAS did not run (`status: "generated"`).
`easydiffraction_parameter_at_limit`	easydiffraction	warning	A refined value ended at a bound or a physical limit.
`easydiffraction_parameters_not_varied`	easydiffraction	warning	lmfit varied fewer parameters than the recipe refines.
`easydiffraction_phase_contributes_nothing`	easydiffraction	info	A phase’s calculated intensities are all zero.
`easydiffraction_fit_not_converged`	easydiffraction	warning	lmfit stopped without success. The values are reported.
`easydiffraction_negative_width`	easydiffraction	warning	The refined profile makes a peak width negative near the fit window.
`easydiffraction_reflections_not_available`	easydiffraction	warning	The CrysFML calculator reports no reflection list, so there are no peak lists.
`easydiffraction_position_translated`	easydiffraction	warning	easydiffraction holds an atom in another writing of the same position. Bounds and reports stay in the recipe’s writing.
`easydiffraction_crysfml_start_dependent`	easydiffraction	warning	Every CrysFML refinement: CrysFML computes in single precision, so the result can depend on the starting values.

This table lists the same codes as powderline.exceptions.WARNING_CODES, with the same engine and level. What each engine does, and why PowderLine warns, is on the engine pages: GSAS-II, TOPAS and easydiffraction.

Failure reasons#

A failed run raises EngineExecutionError (kind engine: the engine ran and failed) or ExecutionBackendError (kind backend: the engine never ran). The reason is e.reason on the error and failure.reason in the failed envelope and in failure.json (Outputs).

Reason	Kind	Meaning
`diverged`	engine	A non-finite calculated pattern or value inside the fit window. For GSAS-II also a refinement GSAS-II itself aborted because no damped step lowered χ² (EB-99). Simulations are exempt.
`unusable_site`	engine	The engine reads an atom’s site or a symmetry tie differently from PowderLine’s core (EB-40, EB-05 for GSAS-II; EB-47 for easydiffraction). The run stops before refining.
`peak_fit_failed`	engine	GSAS-II’s peak fit returned nothing (EB-38).
`engine_crashed`	engine	The engine raised or exited abnormally: a GSAS-II crash, an lmfit, CrysPy or CrysFML error, or a `tc.exe` that could not start.
`output_missing`	engine	TOPAS wrote none of its expected files.
`output_malformed`	engine	An engine file could not be read strictly: a non-numeric token, a ragged row, missing points, or a pattern on other 2θ values.
`server_unavailable`	backend	Server mode: no GSAS-II server was running and none could be started.
`server_disabled`	backend	Server mode was requested while `POWDERLINE_NO_SERVER` is set.
`communication_failed`	backend	An HTTP or transport error after a GSAS-II server was found.
`timeout`	backend	GSAS-II: the server’s answer took longer than `server_timeout`. The job is still running on the server, so there is no in-process fallback. TOPAS: `tc.exe` took longer than `topas_timeout` and was stopped.
`backend_error`	backend	Anything else on the execution path before the engine ran, such as a recipe the server could not validate.

Note

A TOPAS background-only run stopped at the time limit is not a failure. The result has an empty y_bkg column and the warning topas_background_not_calculated.

The reason codes are powderline.results.REASONS, split into ENGINE_REASONS and BACKEND_REASONS. Error messages by symptom, with their fixes, are on Troubleshooting.