Migrating from 0.1#

This page is for developers who hold recipes or code written for PowderLine 0.1.x, which used the single recipe schema 0.1–0.26.0 (GSASII_Rietveld, GSASII_SPF). PowderLine 0.2.0 refuses those recipes at schema_name.

What changed#

Topic	0.1.x	0.2.0
`schema_name`	`GSASII_Rietveld`, `GSASII_SPF`	`gsasii.rietveld`, `gsasii.spf`, `topas.rietveld`, `topas.spf`, `easydiffraction.rietveld`
Engine choice	`run(recipe, output_dir, engine=...)`, translated from GSAS-II’s terms	The recipe names one engine and is written in its own terms and units; nothing is translated
Schema versions	`"schema_version": "0.26.0"`	`"core_schema_version": "0.1.0"` and `"engine_schema_version": "0.1.0"`
Parameters	`structure` and `parameterization` blocks; optional bounds	One phase block; `[value, flag]` in gsasii (no bounds); `[value, flag, min, max]` in topas and easydiffraction
Unknown keys	Ignored	Errors
Result outcome	`success`, `error` keys	`status` (`ok`, `generated`); a failure raises `EngineExecutionError` or `ExecutionBackendError`
`rwp`	The engine’s own value	PowderLine’s uniform Rwp over the fit window; the engine’s value is under `engine_details`
`validate()`	Returned the model	Returns `ValidationResult` (`.recipe`, `.warnings`)
Command	A separate `topas-kicker` for TOPAS	`powderline` for every engine
Environments	GSAS-II in the default environment; `easydiff`	Default is core-only; `gsasii`, `easydiffraction`, `all`, `dev`. Remove a stale `.pixi/envs/easydiff`; `gsas-server` needs `-e gsasii`
Imports	`powderline.topas`, `powderline.easydiff`, `powderline.RecipeModel`, `powderline.schema`, `powderline.GSASClient`	`powderline.gateways.topas`, `powderline.gateways.easydiffraction`; the recipe models are the gateways’ (`powderline.gateways.gsasii.schema.GsasiiRietveldRecipe`, …), and you normally get one from `validate(...).recipe`; `powderline.gateways.gsasii.client.GSASClient`. There are no compatibility aliases: the old imports raise `ModuleNotFoundError` or `ImportError`
Simulation check	`validate_simulation_mode_parameters()`	Gone: a `gsasii.*` recipe with `refinement_cycles: 1` and a refine flag set fails validation

The full list is in the CHANGELOG entry for 0.2.0. The current schemas are on Versions.

Convert GSAS-II recipes#

scripts/convert_recipe_026.py turns a GSASII_Rietveld or GSASII_SPF recipe into a gsasii.rietveld or gsasii.spf recipe:

pixi run python scripts/convert_recipe_026.py old.json -o new.json

It prints one line per change (<path>: <what changed>) and writes the new recipe. Without -o it only prints the report. It never edits the input.

The converted recipe states explicitly what 0.1.x refined. Refine flags are expanded to the groups GSAS-II refined together, and GSAS-II’s silent defaults are written out.

Important

Where the result would not validate, or the refinement 0.1.x ran cannot be known, the converter stops with exit status 1 and lists every problem. It never guesses. Each message names the field and, where there is one, the value to write.

Typical stops: origin choice :1, an atom near a special position without being on it (a symmetry image 5e-6 to 2e-3 away), a Uaniso with only some of its six components, a Kα doublet, TOF or neutron instrument, non-isotropic broadening, and a value below a GSAS-II floor. The 0.26.0 LaB6 recipes stop on their background peak’s width, which is below GSAS-II’s floor (EB-35).

TOPAS and easydiffraction recipes#

There is no converter for these engines. A topas.* or easydiffraction.* recipe holds that engine’s model of your sample, in its own parameters and units. Write it natively, starting from the engine pages (TOPAS, easydiffraction) and the committed fixtures in tests/data/topas/native/ and tests/data/easydiffraction/native/. Each fixture folder has a README that works through the derivations.

The phase block (space_group, unit_cell, atoms) is identical in every engine. You can paste it from a converted gsasii.* recipe and add the bounds slots the engine expects.

Leftover servers from before 0.1.2#

GSAS-II servers from PowderLine 0.1.1, or from a 0.2.0 checkout older than the 0.1.2 merge, used fixed shared files, port 19471, and accepted unauthenticated requests (KI-14). The current client never uses them. gsas-server status and stop cannot see them, so one may still be running unnoticed, perhaps auto-started. It runs as gsas_server.py (0.1.1) or gateways/gsasii/server.py.

Stop your current server first. Then list your remaining server processes, check the list, and end each one by its process ID.

Linux and macOS

pixi run -e gsasii gsas-server stop
ps -u "$(id -un)" -o pid=,args= | grep -E "python[^ ]* .*(gsas_server\.py|gsasii[/.]server)"
kill <PID>        # for each process listed

Windows

pixi run -e gsasii gsas-server stop
Get-CimInstance Win32_Process -Filter "Name LIKE 'python%'" |
  Where-Object CommandLine -match 'gsas_server\.py|gsasii[/\\.]server' |
  Where-Object { (Invoke-CimMethod -InputObject $_ -MethodName GetOwner).User -eq $env:USERNAME } |
  Select-Object ProcessId, CommandLine
Stop-Process -Id <ProcessId>    # for each process listed

You can also end the python … gsas_server.py start or … server.py start processes in Task Manager.

Checklist#

Run the converter on each GSAS-II recipe. Read every report line: each is a place where 0.1.x did something your recipe did not say.
Where it stops, decide from the message. Never paste a value you can’t justify.
Expect different numbers from 0.1.x, even for a clean conversion: the fit window, the sample-broadening and background defaults, and rwp all differ. GSAS-II’s own statistics are under engine_details.
Write TOPAS and easydiffraction recipes natively.
On an existing checkout, install the engine you use (pixi install --frozen -e gsasii), then run pixi reinstall powderline --all and pixi run powderline --doctor.
In code: drop engine=, read validate(...).recipe, catch the two exceptions instead of checking success, and update the imports in the table above (powderline.gateways.<engine>, GSASClient from powderline.gateways.gsasii.client).