Command line#

One command runs or validates a recipe with every engine. The engine is the one the recipe’s schema_name names.

Synopsis#

powderline <recipe.json> [--output DIR] [--validate-only] [--verbose]
                         [--use-server | --no-server] [--server-timeout SECONDS]
                         [--topas-dir DIR] [--topas-version V] [--topas-timeout SECONDS]
powderline --doctor

Run it in the pixi environment of the recipe’s engine:

pixi run -e gsasii powderline examples/example_LaB6/input.json --output my_lab6
pixi run -e easydiffraction powderline examples/example_LaB6/easydiffraction/input.json --output my_lab6_ed
pixi run powderline examples/example_LaB6/topas/input.json --topas-version 6 --topas-dir C:/TOPAS6 --output my_lab6_topas
pixi run powderline my_recipe.json --validate-only
pixi run powderline --doctor

Validation needs no engine, so --validate-only works in every environment. The pixi task kicker runs the same command.

Options for every recipe#

Option

Effect

<recipe.json>

The recipe to run, saved as JSON. Required unless --doctor is given. The command also reads a recipe saved as YAML (.yaml, .yml); JSON is the tested form.

--output DIR

The output directory. Default: output/ next to the recipe.

--validate-only

Validate the recipe, print its summary and warnings, and run nothing. No engine needed; nothing is written.

-v, --verbose

Print the engine’s progress, the recipe, the run ID, the informative notes (level: "info") and the disposition counts.

--doctor

Report what this environment can do, and exit. No recipe needed (below).

-h, --help

Print the usage and exit.

Engine options#

Each engine option belongs to one engine. Given for a recipe of another engine, it is an error and the command exits with status 1.

Option

Engine

Effect

(neither server option)

GSAS-II

Try the GSAS-II server, start it if needed, and fall back to running in-process.

--use-server

GSAS-II

Run in the GSAS-II server only. Fail if it cannot be started.

--no-server

GSAS-II

Run in-process only. Skip the server.

--server-timeout SECONDS

GSAS-II

Stop waiting for the server’s answer after this long. Default: no limit; 0 means no limit. The job itself keeps running on the server.

--topas-dir DIR

TOPAS

The directory that holds tc.exe.

--topas-version V

TOPAS

The installed TOPAS version, e.g. 6. A run that executes TOPAS needs it.

--topas-timeout SECONDS

TOPAS

Stop each tc.exe run after this long. Default: 3600; 0 means no limit.

--use-server and --no-server cannot be given together. easydiffraction has no engine options. How the GSAS-II server works is on Run at a beamline. How TOPAS runs are set up is on Run TOPAS recipes.

Note

PowderLine cannot read a version from tc.exe. You declare the installed TOPAS version, and it must equal the recipe’s engine_version. When no tc.exe is found, a TOPAS run writes the input files only and returns status: "generated".

Exit status#

Status

When

0

The run finished with status "ok", or "generated" (TOPAS input written, TOPAS not run).

0

--validate-only: the recipe is valid. Warnings do not change the status.

0

--doctor found no problem, or --help printed the usage.

1

An unreadable or invalid recipe, a template, an engine option for another engine, a missing engine, a failed run, or a problem found by --doctor.

2

A usage error, reported before anything runs: no recipe and no --doctor, both --use-server and --no-server, an unknown option, or a timeout that is not a number.

A failed run prints its failure reason and the files kept for diagnosis. For GSAS-II and TOPAS it also prints the engine’s last console lines.

Templates are refused#

The command refuses to run a recipe that looks like a template:

  • its path contains template (in any case);

  • or its payload is missing, or lacks a block the workflow needs: xrd_data, instrument, refinement_controls, and phases (Rietveld) or single_peaks (single-peak fitting).

Copy a template into your own directory and fill it in before you run it.

Note

Only the command refuses templates. powderline.run() does not check for them: it runs any recipe that validates, whatever its path.

Doctor#

powderline --doctor reports what this environment can do:

  • the PowderLine version, the Python and the platform;

  • every gateway it finds, with its workflows and the engine version it requires;

  • whether that engine is installed here, and at which version;

  • for TOPAS, the version you declared;

  • the GSAS-II server’s state directory, and whether a server is running.

It exits with status 1 when it finds a problem:

  • no gateway at all;

  • an installed engine outside its required version;

  • an engine whose version cannot be read;

  • a gateway that fails to load;

  • a .powderline_config.yaml that cannot be read.

An engine that is not installed is reported but is not a problem. The default environment validates every recipe and runs none by design.

Environment variables#

Variable

Effect

POWDERLINE_NO_SERVER

Set to 1, true, yes or on to never use the GSAS-II server. The default mode then runs in-process, and --use-server is an error.

POWDERLINE_SERVER_PORT

The port the GSAS-II server listens on (1–65535). Default: a free port chosen at start.

Configuration file#

The TOPAS options can also come from .powderline_config.yaml. PowderLine reads the first one it finds: in the current directory, then in your home directory. An option given on the command line wins.

topas:
  dir: C:/TOPAS6      # the directory that holds tc.exe (--topas-dir)
  version: "6"        # the installed TOPAS version (--topas-version)
  timeout: 3600       # seconds per tc.exe run; 0 = no limit (--topas-timeout)

PowderLine looks for tc.exe only in --topas-dir or topas.dir. A malformed file is an error, not an empty configuration.