Engines#

An engine is the refinement program that computes the pattern and runs the least squares: GSAS-II, TOPAS or easydiffraction. PowderLine does not refine anything itself. For each engine, a gateway checks a recipe in that engine’s own terms and units, runs the engine, and returns the results in one standard form. A recipe names one engine and one workflow in its schema_name, and nothing is translated between engines. The whole picture is in How PowderLine works.

Engine	Page
GSAS-II 5.7.9	GSAS-II
TOPAS 6	TOPAS
easydiffraction 0.21.1 (CrysPy 0.13.0, CrysFML 0.8.0)	easydiffraction

The five schemas#

`schema_name`	Engine	Workflow	Parameters	Run with
`gsasii.rietveld`	GSAS-II 5.7.9	Rietveld refinement, one or more phases	`[value, flag]`, no bounds	`pixi run -e gsasii powderline <recipe.json>`
`gsasii.spf`	GSAS-II 5.7.9	Single-peak fitting (GSAS-II’s Peak List), no phases	`[value, flag]`, no bounds	`pixi run -e gsasii powderline <recipe.json>`
`topas.rietveld`	TOPAS 6	Rietveld refinement, one or more phases	`[value, flag, min, max]`	`pixi run powderline <recipe.json> --topas-version 6 --topas-dir C:/TOPAS6`
`topas.spf`	TOPAS 6	Single-peak fitting (`xo_Is` peaks), no phases	`[value, flag, min, max]`	`pixi run powderline <recipe.json> --topas-version 6 --topas-dir C:/TOPAS6`
`easydiffraction.rietveld`	easydiffraction 0.21.1	Rietveld refinement; calculator `cryspy` or `crysfml`	`[value, flag, min, max]`	`pixi run -e easydiffraction powderline <recipe.json>`

easydiffraction has no single-peak-fitting workflow.

You can validate any recipe in any environment, with no engine installed:

pixi run powderline <recipe.json> --validate-only

A TOPAS run needs tc.exe, on Windows. Without it, PowderLine writes TOPAS’s input files and stops there (see TOPAS).

Fill-in templates are in examples/example_template/: input.json for GSAS-II, and topas/input.json and easydiffraction/input.json. Copy one into your own folder before you fill it in. The command line refuses to run a recipe whose path contains template.

Features by schema#

Feature	`gsasii.rietveld`	`gsasii.spf`	`topas.rietveld`	`topas.spf`	`easydiffraction.rietveld`
Phases	one or more	none	one or more	none	one or more
Parameter bounds	no	no	yes (TOPAS limits)	yes	yes (physical limits)
Refinable cell, coordinates, occupancy, `Uiso`, `Uaniso`	yes	—	yes (`Uiso` written as `beq`)	—	yes (`Uaniso` with CrysPy only)
Sample size/strain broadening	isotropic (µm, microstrain)	—	`CS_L`/`CS_G`, `Strain_L`/`Strain_G`	—	none (the profile is the instrument’s)
Instrument profile	TCH U, V, W, X, Y, Z (GSAS-II letters)	same	`TCHZ_Peak_Type`, `PV_Peak_Type` or `PVII_Peak_Type`	same	`cwl-pseudo-voigt`, Bérar–Baldinozzi (CrysPy), Thompson–Cox–Hastings with FCJ (CrysFML)
Axial asymmetry	SH/L (≥ 0.002)	SH/L	`Simple_Axial_Model` / `Full_Axial_Model`	same	FCJ (CrysFML) or Bérar–Baldinozzi (CrysPy)
Zero shift	yes	yes	`Zero_Error`	yes	`calib_twotheta_offset`
Polarization	`polarization` (GSAS-II’s P)	yes	`LP_Factor` or `LP_Factor_Synchrotron`	yes	fixed `setup_polarization_coefficient` (p = 1 − P)
Other corrections	—	—	capillary absorption	same	displacement, transparency, cylinder absorption, Kα2 line
Background	Chebyshev + pseudo-Voigt peaks	same	Chebyshev, `One_on_X`, `xo_Is` peaks	same	Chebyshev
Simulation	`refinement_cycles: 1`, no flag set	same	`iters: 0`, no flag set	same	no flag set
Ionic scattering types (`scattering_types`, CIF spelling)	yes (GSAS-II’s 114 ions)	—	yes (TOPAS 6’s 113 ions, `occ La+3`)	—	cryspy only (111 ions)
Preferred orientation (`preferred_orientation`, March–Dollase)	yes	—	yes (`PO` macro)	—	cryspy only, with `march_random_fract`
Engine version in the recipe	no (pinned by pixi)	no	`engine_version: "6"`	yes	no (pinned by pixi)

Every field of every schema, with its unit, is in Fields.

Scattering types by engine#

element is always the neutral atom, so a phase block means the same thing in every engine. You state an ion per atom label, in the engine’s phase block:

"scattering_types": {"La": "La3+"}

You always write ions in the CIF spelling, La3+, whatever the engine. An atom left out of scattering_types scatters as its neutral element.

	GSAS-II 5.7.9 (`gsasii.*`)	easydiffraction 0.21.1, CrysPy (`calculator: "cryspy"`)	easydiffraction 0.21.1, CrysFML (`calculator: "crysfml"`)	TOPAS 6 (`topas.*`)
Engine’s own spelling	`La+3`	`La3+`	none (charges stripped)	`La+3`
Ions with a form factor	114	111	none	113 (`ATMSCAT.CPP`)
What the engine does with a wrong or unknown ion	reads `La3+` as hydrogen, silently (EB-94)	uses the neutral atom, with a log warning only (EB-95)	uses the neutral atom for every ion (EB-96)	stops without results; the reason appears only in its console window
What PowderLine does	writes GSAS-II’s spelling into the atom record; refuses an ion GSAS-II has no form factor for	passes the CIF spelling through; refuses an ion CrysPy has no form factor for	refuses `scattering_types` (use the cryspy calculator)	writes TOPAS’s spelling into the site’s `occ` (`occ La+3 …`); refuses an ion TOPAS has no form factor for

For LaB6 with La3+, the per-reflection ion-to-neutral intensity ratios agree between GSAS-II and CrysPy within 1 %. Between GSAS-II and TOPAS 6, measured directly, they agree within 0.07 %.

Edge cases:

Coverage differs between engines. O2-, D1- and T1- are in GSAS-II’s table but not in CrysPy’s. TOPAS’s table is the ATMSCAT.CPP shipped with TOPAS 6: every GSAS-II ion except T1-. An oxide stated with O2- therefore validates for gsasii.* and topas.* but not for easydiffraction, which has only O1-. The error names the forms CrysPy has.
T1- cannot be stated at all, because gemmi has no element T.
Some atoms have no ion in any engine. LaB6 is La3+ with neutral B, because no engine has a boron ion.
Ions are per atom label. State mixed valence on different sites per site. A mixed site, with two species at one position, is two atoms, each with its own label and type.
Spelling rules:
- a charge of 1–8, with an explicit sign;
- Fe+3 is an error that names Fe3+;
- Na+, with no number, is an error: write Na1+;
- element must be the ion’s element.
A phase moved to another engine is validated by that engine’s schema, so an ion it has no form factor for is an error there. What carries over is on Move a structure between engines.
TOPAS’s table can be edited. ATMSCAT.CPP sits in the TOPAS folder, and you can change it. PowderLine checks against the file as shipped with TOPAS 6.

Special positions by engine#

Each engine has its own tolerance for deciding whether an atom sits on a special position, and the engines disagree. PowderLine applies one rule for every engine. The table in Model disorder near special positions compares what each engine would do with what PowderLine does.

Choosing an engine#

PowderLine does not rank the engines. What each one needs and offers:

GSAS-II runs on Linux and Windows, installed by pixi, and is expected to work on macOS (not routinely tested). It does Rietveld refinement and single-peak fitting. Its recipes have no bounds, and a few documented defaults.
TOPAS recipes validate, and generate TOPAS’s input files, on any platform. Running them needs TOPAS 6 and its tc.exe, on Windows. TOPAS does Rietveld refinement and single-peak fitting, with bounds.
easydiffraction runs on Linux and Windows, installed by pixi, with Python 3.12 or later, and is expected to work on macOS (not routinely tested). It does Rietveld refinement only, with bounds, and you choose one of two calculators.

The same data fitted in every engine, and why the numbers differ, is in Comparing engines.

How PowderLine treats engine quirks#

Every refinement program has quirks: values it silently rounds, settings it misreads, defaults it applies without saying so. PowderLine follows one rule:

If an engine would silently change what your recipe means, PowderLine refuses the recipe and tells you what to write instead.
If an engine does something you should know about but your model is unchanged, PowderLine runs and adds a warning to the result.

The pages for GSAS-II, TOPAS and easydiffraction list each behavior PowderLine has found, with what it does about it. Each behavior has a permanent ID, EB-NN, that messages and the changelog cite. Every ID is listed in the ID index, and every warning code in Messages.

Each entry carries a status:

Status	Meaning
handled	PowderLine prevents or corrects it: a validation error, a translation, or a check that stops the run.
warned	The run goes ahead, and the result carries a warning that names it.
documented	Documented only. The engine’s behavior stands, and the entry tells you what to expect.
fixed upstream	Fixed in the engine version PowderLine pins.

The behaviors were established on GSAS-II 5.7.9, TOPAS 6 (TOPAS 7 where noted) and easydiffraction 0.21.1 with CrysPy 0.13.0 and CrysFML 0.8.0. An entry marked unverified is recorded from documentation or a model, not from a run. How PowderLine decides a policy is in Policies.

Behaviors that concern every engine#

Cell, ADPs and occupancy#

EB-50 · A Uaniso that is not positive definite is used as given#

warned · GSAS-II 5.7.9; easydiffraction 0.21.1; TOPAS 6 unverified

What happens: GSAS-II has no positive-definiteness check. easydiffraction computes a finite pattern for such a tensor, with no message. TOPAS is unverified.

PowderLine does: Core uses the tensor as stated and warns when it has a principal value ≤ 0.

You see: uaniso_not_positive_definite

Scattering types#

EB-13 · gemmi strips the charge from an element symbol#

handled · gemmi 0.7.5

What happens: gemmi, which core uses for symmetry and elements, strips the charge from a symbol: Fe3+ becomes Fe.

PowderLine does: element takes a bare element symbol only. An ion in element is refused, never stripped. Ions are stated in scattering_types, in the CIF spelling.

You see: validation error

EB-25 · Each engine spells ions its own way#

handled · GSAS-II 5.7.9; TOPAS 6; easydiffraction 0.21.1 (CrysPy 0.13.0)

What happens: GSAS-II and TOPAS spell an ion Fe+3. CrysPy spells it Fe3+, the CIF spelling.

PowderLine does: You write every ion in the CIF spelling, in scattering_types. Each gateway writes its engine’s spelling. Fe+3 in a recipe is an error that names Fe3+.

You see: validation error

Statistics#

EB-88 · A symmetric profile shifts the refined cell#

documented · GSAS-II 5.7.9; easydiffraction 0.21.1 (CrysPy 0.13.0, CrysFML 0.8.0)

What happens: Lattice parameters agree between GSAS-II and easydiffraction when axial asymmetry is modeled physically (FCJ). With a symmetric profile they shift by +67 to +91 ppm, whichever calculator runs it.

PowderLine does: Documented on the cross-engine comparison. Rwp compares models fitted to the same points, not engines.