Run TOPAS recipes#

Goal: run a topas.rietveld or topas.spf recipe with TOPAS 6, or write TOPAS’s input on any machine and run it later.

You need:

  • A recipe that states "engine_version": "6" at its top level.

  • To run TOPAS: a Windows machine with TOPAS 6 installed, and the folder that holds tc.exe.

  • To write the input only: any PowderLine environment, on any platform.

TOPAS has no Python package. PowderLine writes TOPAS’s input file (.inp) and data file (.xye), runs tc.exe and reads what TOPAS writes back.

1. Validate#

pixi run powderline my_sample/input.json --validate-only

Validation needs no TOPAS. It works in every environment, on every platform.

2. Tell PowderLine where TOPAS is and which version it is#

PowderLine never searches for TOPAS. tc.exe carries no version PowderLine could read, so you declare both the folder and the version. Give them on the command line:

pixi run powderline my_sample/input.json --topas-version 6 --topas-dir C:/TOPAS6

Or set them once in .powderline_config.yaml, in the folder you run from or in your home folder:

topas:
  dir: "C:/TOPAS6"
  version: 6
  timeout: 3600

The command-line flags win over the file. PowderLine reads only the first file it finds: a file in the folder you run from replaces the one in your home folder. The template .powderline_config.yaml.example in the repository shows the block.

The declared version must equal the recipe’s engine_version, written as the release number: 6, not 6.0. PowderLine 0.2.0 supports TOPAS 6 only.

In Python:

result = powderline.run(recipe, Path("out"), topas_version="6", topas_dir=Path(r"C:\TOPAS6"))

3. Run#

pixi run powderline my_sample/input.json --topas-version 6 --topas-dir C:/TOPAS6

When the recipe models a background, tc.exe runs twice: once for the fit, then once for the background alone, at the refined values. TOPAS 6 cannot output the fit’s background, so the second run provides the y_bkg column of fit_profile.txt. The second run is skipped when the fit’s values are not finite.

Check: the command line ends with Refinement complete. Final Rwp: …, and output/ holds fit_profile.txt and the other report files.

Write the input only, anywhere#

With no TOPAS folder declared, or none holding tc.exe, PowderLine writes TOPAS’s input and stops. This works on Linux and macOS too:

pixi run powderline my_sample/input.json

ℹ️ Generated the engine input only (topas_generate_only, 0.0s):
   my_sample/output/my_sample.inp
   my_sample/output/my_sample.xye
   my_sample/output/output_recipe.json
   my_sample/output/parameter_dispositions.csv

This is not a failure. The result has status: "generated", the command exits 0, and the topas_generate_only note says how to run it. Run the .inp on the TOPAS machine yourself, or run the recipe there.

Set a time limit#

Each tc.exe run is stopped after 3600 seconds by default, so a TOPAS waiting for input (a license dialog, for example) cannot hang a run. Change the limit with --topas-timeout SECONDS, topas.timeout in .powderline_config.yaml, or topas_timeout in Python. 0 means no limit.

Past the limit, the run fails with ExecutionBackendError, reason timeout. If only the background run is stopped, the fit still succeeds. y_bkg is then empty, with the warning topas_background_not_calculated.

Use plain folder names#

TOPAS reads file paths in the Windows ANSI code page. A folder name that code page cannot hold, such as Greek on a Western-European Windows, makes TOPAS write nothing. Latin-1 names and spaces work.

PowderLine handles this for you where it can. It passes such a folder to tc.exe by its short 8.3 name. If the drive has no short names, the run stops before TOPAS starts, with reason backend_error and a message to use an ASCII output folder (--output DIR).

What a run writes#

Beside the report files every engine writes, a TOPAS run keeps TOPAS’s own files. When the output path ends in a folder named output, <base> is the name of the folder above it (my_sample/output gives my_sample). Otherwise it is topas.

File

What it is

<base>.inp, <base>.xye

what TOPAS was given

<base>_results.csv

TOPAS’s refined values and statistics

<base>_profile.txt

TOPAS’s calculated pattern

<base>_p<n>_peaks.txt

the reflection list of phase n

<base>_bkg.inp, <base>_bkg_profile.txt

the background-only run

A base name that is not ASCII is replaced by topas, with the warning topas_base_name_sanitized.

Outputs describes the report files and the result.

What to expect in the result#

  • converged is always null: TOPAS 6 writes no convergence signal (EB-85).

  • engine_details["tc_path"] names the tc.exe that ran.

  • TOPAS reports success and failure with the same exit code, so PowderLine judges a run by its output files. If TOPAS wrote none, the run fails with reason output_missing. Whatever tc.exe printed is in failure.json, under failure.console_tail. Otherwise its messages are in its console window and in tc.log, in the TOPAS folder.

  • A file TOPAS wrote that PowderLine cannot read strictly fails with reason output_malformed.

The TOPAS page lists what TOPAS does with a recipe and what PowderLine refuses on its behalf.

Next: Troubleshoot, Run at a beamline.