TOPAS#


Version	TOPAS 6. The recipe states `"engine_version": "6"`. TOPAS is installed separately: it has no Python package.
Workflows	`topas.rietveld` (Rietveld refinement), `topas.spf` (single-peak fitting)
Parameters	`[value, flag, min, max]`
Platforms	Validation and input files: Linux, Windows, macOS (not routinely tested). Running TOPAS: Windows, with `tc.exe`.
Run	`pixi run powderline <recipe.json> --topas-version 6 --topas-dir C:/TOPAS6`
Cite	Coelho (2018), see Citing

What you write#

A minimal topas.rietveld recipe for LaB6. It validates as shown; your measured pattern replaces the three data points.

{
  "schema_name": "topas.rietveld",
  "core_schema_version": "0.1.0",
  "engine_schema_version": "0.1.0",
  "engine_version": "6",
  "payload": {
    "xrd_data": {
      "tth": [1.000, 1.004, 1.008],
      "Itth": [30.7, 29.8, 31.2],
      "Itth_weights": [0.0326, 0.0335, 0.0320]
    },
    "instrument": {
      "radiation": {
        "ymin_on_ymax": 0.0001,
        "la": [1.0, false, null, null],
        "lo": [0.1665, false, null, null],
        "lh": [0.0001, false, null, null]
      },
      "broadening": {
        "peak_type": "TCHZ_Peak_Type",
        "parameters": {
          "U": [0.0104, true, null, null], "V": [0.00033, true, null, null],
          "W": [0.00064, true, null, null], "Z": [0.0, false, null, null],
          "X": [0.0001, true, null, null], "Y": [0.0028, true, null, null]
        }
      }
    },
    "phases": {
      "LaB6": {
        "space_group": "P m -3 m",
        "unit_cell": {
          "a": [4.15682, true, null, null], "b": [4.15682, true, null, null],
          "c": [4.15682, true, null, null], "alpha": [90.0, false, null, null],
          "beta": [90.0, false, null, null], "gamma": [90.0, false, null, null]
        },
        "atoms": {
          "La": {"element": "La", "x": [0.0, false, null, null], "y": [0.0, false, null, null],
                 "z": [0.0, false, null, null], "occupancy": [1.0, false, null, null],
                 "ADP": "Uiso", "Uiso": [0.0086, false, null, null]},
          "B": {"element": "B", "x": [0.5, false, null, null], "y": [0.5, false, null, null],
                "z": [0.2021, false, null, null], "occupancy": [1.0, false, null, null],
                "ADP": "Uiso", "Uiso": [0.009, false, null, null]}
        },
        "scale": [2.6e-06, true, null, null]
      }
    },
    "refinement_controls": {"iters": 1000, "chi2_convergence_criteria": 0.001, "x_calculation_step": 0.001}
  }
}

Required in topas.rietveld:

engine_version ("6") at the top level, next to payload.
xrd_data: tth, Itth, Itth_weights.
instrument.radiation (ymin_on_ymax, la, lo, lh) and instrument.broadening (peak_type and exactly that type’s parameters).
At least one phase, with space_group, unit_cell, atoms and scale.
refinement_controls, every control stated: iters, chi2_convergence_criteria, x_calculation_step.

Optional: fit_range, background, instrument.corrections, instrument.geometry, and per phase peak_broadening, scattering_types and preferred_orientation.

topas.spf (single-peak fitting) is the same, with single_peaks instead of phases. single_peaks is a list of peaks, each with xo and I, and optionally gauss_fwhm and lor_fwhm. Start from examples/example_LaB6_singlepeakfit/topas/input.json.

Every field, with its unit: Fields: topas.rietveld and Fields: topas.spf.

Units that differ from other engines#

Quantity	TOPAS unit
`U`, `V`, `W`, `Z` (TCHZ, Gaussian FWHM²)	degree²
`X`, `Y` (TCHZ, Lorentzian FWHM)	degree
`lo` (wavelength)	Å
`lh`, `lg` (emission-line half-widths)	mÅ
`Rp`, `Rs`, slit and sample lengths	mm
`CS_L`, `CS_G`	nm
`Strain_L`, `Strain_G`	degree 2θ
capillary `u_cm_inv`	1/cm
`Uiso`	Å², as in every schema; written to TOPAS as `beq` (EB-24)

The TCHZ letters are not GSAS-II’s. TOPAS’s U, V, W give the Gaussian FWHM² in degree². Its Lorentzian term is X tanθ + Y/cosθ, where GSAS-II’s is X/cosθ + Y tanθ: the roles of X and Y swap.

CS_L, CS_G, Strain_L and Strain_G are not sizes or strains. PowderLine reports LVol-IB and e0, computed by TOPAS, as derived rows (EB-57).

Nothing has a default#

A block you leave out is not modeled. Everything PowderLine would otherwise choose is a required field. A recipe without background has no background.

Bounds#

[value, flag, min, max]: a stated min or max replaces TOPAS’s own default limit on that side. null keeps TOPAS’s default limit (EB-58).

A refined start outside a default limit on a null side is a validation error. State a bound to override TOPAS, or start inside.
TOPAS 6 stops a little past a bound, not on it. A PO ratio with min 0.7 ended at 0.700012. A single-peak position stopped 1e-5° inside the fit window’s start, where TOPAS holds xo.
After a run, every refined value within 1e-4 (relative) of a stated bound or a default limit gets topas_parameter_at_limit. At a limit of 0 the tolerance is 1e-12 absolute.
A single-peak position counts as at the window’s edge when no data point lies between it and the edge, or when it is on or beyond the edge.

Bounds in every engine: Recipe format.

The instrument block#

Block	Fields
`radiation`	One `lam` emission line: `ymin_on_ymax`, `la` (area), `lo` (wavelength, Å), `lh` (mÅ), optionally `lg` (mÅ)
`geometry` (optional)	`Rp`, `Rs` in mm. State them exactly when an axial model reads them.
`corrections` (optional)	Keyed by TOPAS macro: `Zero_Error`; `LP_Factor` or `LP_Factor_Synchrotron`; `Simple_Axial_Model` or `Full_Axial_Model`; `capillary`
`broadening`	`peak_type` and its `parameters`: `TCHZ_Peak_Type` (U, V, W, Z, X, Y), `PV_Peak_Type` or `PVII_Peak_Type`

lh is required. lg is allowed only with it: lg alone crashes TOPAS 6 (EB-64).
Geometry corrections act on every peak, background and single peaks included. Lorentz–polarization acts on Bragg peaks only.
With TCHZ_Peak_Type, the total peak width at the starting values must be positive at every data point of the fit window. A negative Lorentzian part X·tanθ + Y/cosθ is allowed while it is. Otherwise validation fails with topas_tchz_width_not_positive (EB-69).

Background and controls#

background.chebyshev is the shared Chebyshev model: num_coefficients, coefficients, and one refine_flag for all terms. Its basis spans the fit window’s first and last points.
background also takes One_on_X and xo_Is peaks, each peak with its own peak type.
refinement_controls: iters, chi2_convergence_criteria and x_calculation_step, all required. iters: 0 is a simulation: then every refine flag must be false.

Scattering types and preferred orientation#

Ions are stated in the CIF spelling in scattering_types, for example La3+. The writer puts TOPAS’s spelling into the site’s occ: occ La+3 …. TOPAS takes its form factors from ATMSCAT.CPP, which has 113 ions in TOPAS 6. An ion outside that table is a validation error. TOPAS itself stops without results on La3+, on a sign-only Na+ or an unknown symbol, with no neutral fallback. See Scattering types by engine.
Preferred orientation is TOPAS.INC’s PO macro. PO(c, r, , h k l) is GSAS-II’s March–Dollase correction, averaged over the axis’s equivalents with the same r convention. The two agree to 1.4e-7 along 001, 111 and 110. Refined from 0.8 on the textured example, it recovers r = 0.5982(14) against the programmed 0.6.
The PO macro’s default limits are min 0.0001 and max 2r + 0.5. The max follows the value, so a start never exceeds it. The writer emits only the bounds you state. A refined start below 0.0001 with no stated min is a validation error.

How PowderLine runs TOPAS#

        flowchart LR
    R[recipe] --> V[validate]
    V --> W["write INP + .xye"]
    W --> T{tc.exe<br/>declared?}
    T -- no --> G["status: generated<br/>(nothing ran)"]
    T -- yes --> X[run tc.exe]
    X --> B[background-only run]
    B --> O["status: ok"]

PowderLine always writes TOPAS’s input file (<base>.inp) and the data (<base>.xye). Numbers are written to 10 significant digits, in both files.

Where tc.exe is. PowderLine looks only in the folder you give: --topas-dir DIR, or topas.dir in .powderline_config.yaml (in the current folder, or your home folder). It never guesses a folder.
Without tc.exe the run is generate-only. The INP and .xye are written, nothing runs, and the result has status: "generated" with the note topas_generate_only. The command exits 0.
The version is declared, not detected. tc.exe carries no version PowderLine could read (EB-67). A run needs --topas-version 6, or topas.version in the config file.
Success is judged from TOPAS’s output files. tc.exe returns the same exit code on success and failure (EB-60). A missing file fails the run with reason output_missing. Its failure record keeps the INP and data, and whatever tc.exe printed. Otherwise look at TOPAS’s console window and tc.log.
Each tc.exe run has a time limit: --topas-timeout SECONDS, or topas.timeout in the config file. The default is 3600 s; 0 means no limit. Past it, tc.exe is stopped and the run fails with reason timeout. So a TOPAS waiting for input cannot hang a run.
A second, background-only run gives the fitted background, because TOPAS 6 cannot output it (EB-61). If that run writes nothing or hits the time limit, the result is still a success, with an empty y_bkg and topas_background_not_calculated.
converged is always null for TOPAS 6, which writes no convergence signal (EB-85).

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

# .powderline_config.yaml
topas:
  dir: C:/TOPAS6
  version: "6"
  timeout: 3600

Step by step: Run TOPAS.

Folder and file names on Windows#

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

PowderLine passes such a folder to tc.exe in its 8.3 short form, with the file name as written.
If the volume has no short name for the folder, the run is refused before tc.exe starts, with reason backend_error and a message to use an ASCII output folder.
A base name that is not ASCII-safe is replaced by topas, with the warning topas_base_name_sanitized.

TOPAS 7#

topas.* recipes are verified against TOPAS 6 and declare TOPAS 6 only (KI-16). TOPAS 7 needs an explicit widening, with its own compatibility run.

Behaviors#

Each entry says what TOPAS does on its own and what PowderLine does about it. Messages and the changelog cite these IDs.

Space groups#

EB-11 · A bare two-origin symbol is origin choice 1#

handled · TOPAS 6

TOPAS does: TOPAS accepts the symbols of its own table: case-insensitive, spaces allowed, or the number. :2 selects origin choice 2. A bare two-origin symbol is origin choice 1, the opposite of GSAS-II’s default.

PowderLine does: The topas gateway writes TOPAS’s explicit form: :2 kept, :1 dropped.

EB-43 · A bare rhombohedral symbol means hexagonal axes#

handled · TOPAS 6

TOPAS does: TOPAS reads a bare rhombohedral symbol on hexagonal axes. A trailing r gives rhombohedral axes.

PowderLine does: The topas gateway drops :H and writes :R as a trailing r.

EB-68 · Some settings have no TOPAS symbol, and three are misread#

handled · TOPAS 6

TOPAS does: Twenty of gemmi’s settings have no TOPAS symbol. TOPAS 6 reads C 1 21 1, I 1 21 1 and C 4 2 21 as another setting, dropping an origin shift.

PowderLine does: The topas gateway refuses these 23 settings. The other 541 were checked operator by operator against TOPAS 6’s own generated operator files.

You see: validation error

Special positions and sites#

EB-08 · TOPAS compares positions within 1e-15#

handled · TOPAS 6

TOPAS does: TOPAS compares equivalent positions within 1e-15. It treats any decimal third as a general position.

PowderLine does: Core holds derived values exactly. The topas writer emits fixed special coordinates as exact equations, such as = 1/3;.

Cell, ADPs and occupancy#

EB-09 · Cell values are used as given#

handled · TOPAS 6

TOPAS does: TOPAS uses the individual a b c al be ga values as given.

PowderLine does: Core refuses a cell that does not fit the space group, within 1e-9, in every engine.

You see: validation error

EB-10 · The adps keyword applies the Uij constraints#

handled · TOPAS 6

TOPAS does: TOPAS’s adps keyword applies the site-symmetry constraints on Uij.

PowderLine does: Core requires Uij values that respect the site symmetry, before any engine runs.

You see: validation error

Note: Unverified. Recorded from documentation, not from a run.

EB-24 · TOPAS’s isotropic ADP is beq, not Uiso#

handled · TOPAS 6

TOPAS does: TOPAS states the isotropic ADP as beq = 8π²·Uiso.

PowderLine does: The recipe states Uiso in Å², as in every schema. The topas gateway converts the value and its bounds to beq and warns once per atom. Results report Uiso.

You see: topas_adp_converted

EB-21 · Occupancy is limited per iteration#

handled · TOPAS 6

TOPAS does: TOPAS limits occ to 0 … 2·value + 1 per iteration.

PowderLine does: Core requires 0 ≤ occupancy ≤ 1 for every engine.

You see: validation error

Names#

EB-49 · Two parameters with the same name are one parameter#

handled · TOPAS 6

TOPAS does: TOPAS treats two prm of the same name as one parameter, so composed names could collide silently.

PowderLine does: The topas writer uses index-based parameter names. The core name rule also applies.

Note: Unverified beyond TOPAS’s documented model.

Bounds and limits#

EB-58 · Keywords and macros carry default limits#

handled · TOPAS 6

TOPAS does: TOPAS keywords carry default limits: scale ≥ 1e-11, beq in [−10, 20], cell lengths ≥ 1.5 Å, lattice ±0.5 % per iteration, among others. The TOPAS.INC macros add their own: TCHZ U–Z in [−1, 2], X and Y in [1e-4, 2], CS in [0.3, 10000] nm, Strain in [1e-4, 5], and the March–Dollase PO ratio min 1e-4 and max 2r + 0.5. A user min or max overrides the default on that side. A start outside a limit is moved onto it silently.

PowderLine does: A stated bound replaces TOPAS’s limit on that side. A null side keeps TOPAS’s default limit. A refined start outside a fixed default limit on a null side is a validation error: state a bound, or start inside. A refined value within 1e-4 (relative) of a stated bound or a default limit gets a warning. At a limit of 0 the tolerance is 1e-12 absolute.

You see: validation error, topas_parameter_at_limit

EB-62 · The limit markers TOPAS writes are unreliable#

handled · TOPAS 6

TOPAS does: The _LIMIT_MIN and _LIMIT_MAX markers TOPAS 6 writes are mislabeled or spurious.

PowderLine does: The at-limit warning is judged from the final values and the limits the writer knows, not from TOPAS’s markers.

You see: topas_parameter_at_limit

Peak profile and instrument#

EB-55 · TCHZ takes the absolute value of its Gaussian term#

documented · TOPAS 6

TOPAS does: TCHZ computes ΓG = √|U tan²θ + V tanθ + W + Z/cos²θ|. A negative sum is used as its magnitude without a message. The Technical Reference’s formula has no absolute value.

PowderLine does: Documented, not validated. TOPAS carries your value consistently.

EB-69 · A negative TCHZ Lorentzian part is computed as written#

handled · TOPAS 6

TOPAS does: TCHZ_Peak_Type combines a Gaussian width G and a Lorentzian width L = X·tanθ + Y/cosθ into one FWHM. With a fixed X < 0, TOPAS 6 neither takes |X| nor clamps it at 0. X = −0.01 runs, and the profile differs from X = 0. X = −0.1 makes the width negative at the top of the window, and TOPAS writes no results: a negative convolution FWHM stops TOPAS.

PowderLine does: PowderLine honors what TOPAS computes: a negative Lorentzian part passes while the total width is positive. With TCHZ_Peak_Type, the total width at the recipe’s starting values must be positive at every data point of the fit window. Otherwise validation fails and names X, Y and the 2θ where the width is not positive. An output recipe whose refined values break the rule is not valid.

You see: validation error topas_tchz_width_not_positive, output_recipe_not_valid

EB-56 · PVII_Peak_Type differs from the Technical Reference#

documented · TOPAS 7 macro file; the schema targets TOPAS 6

TOPAS does: TOPAS 7’s macro computes h = ha + hb/cosθ + hc·tanθ and m = 0.6 + ma + mb/cosθ + mc·tanθ. The Technical Reference prints the tanθ and 1/cosθ terms the other way round. h1 and h2 are half-widths.

PowderLine does: The schema documents the macro’s formula.

EB-57 · CS and Strain terms are not sizes or strains#

handled · TOPAS 6

TOPAS does: TOPAS’s own documentation says CS_L, CS_G, Strain_L and Strain_G “have no direct physical interpretation and should not be reported”. The interpretable quantities are LVol-IB = k / IB, with IB = Voigt_Integral_Breadth_GL(1/CS_G, 1/CS_L), and e0 = Voigt_FWHM_GL(Strain_G, Strain_L)·0.25·π/360.

PowderLine does: PowderLine reports LVol-IB (k = 1) and e0 as derived rows computed by TOPAS. It documents that the four input terms are not sizes or strains.

EB-64 · An emission line with lg alone crashes TOPAS 6#

handled · TOPAS 6

TOPAS does: A lam line with lg and no lh crashes TOPAS 6.

PowderLine does: The schema requires lh, and allows lg only with it.

You see: validation error

Data and the fit window#

EB-59 · TOPAS fits the points nearest its limits#

handled · TOPAS 6

TOPAS does: TOPAS fits the points nearest start_X and finish_X.

PowderLine does: The gateway hands TOPAS the fit limits moved onto the first and last weighted data points inside the window. TOPAS’s r_wp then equals core’s Rwp.

EB-66 · An xo_Is peak loses part of its value at the last fitted point#

documented · TOPAS 6

TOPAS does: For a background or single peak without an axial convolution, TOPAS 6 loses part of the peak’s value at the last fitted point, wherever the window ends. LaB6’s background peak is 1.35 counts low there, about 4 %. No calculation range, step or exclude avoids it.

PowderLine does: Documented, no workaround. The background-only run carries the same value, so y_bkg is consistent with y_calc.

Note: TOPAS 7 unverified.

Platform and installation#

EB-67 · tc.exe carries no version metadata#

handled · TOPAS 6

TOPAS does: tc.exe carries no version metadata. It prints its version only to its console.

PowderLine does: You declare the installed version (--topas-version, or topas.version in .powderline_config.yaml). A run needs it. The check compares declarations, not the binary.

EB-61 · TOPAS 6 cannot output the fit’s background#

warned · TOPAS 6

TOPAS does: In TOPAS 6, Get(bkg) is 0. phase_out_X exists in TOPAS 7 only.

PowderLine does: PowderLine runs a second, background-only INP at the refined values. Its calculated pattern, every convolution included, is y_bkg. If that run writes nothing or hits the time limit, the result stays a success with an empty y_bkg and a warning. The fit’s values, statistics and output recipe do not depend on it.

You see: topas_background_not_calculated

TOPAS#

What you write#

Units that differ from other engines#

Nothing has a default#

Bounds#

The instrument block#

Background and controls#

Scattering types and preferred orientation#

How PowderLine runs TOPAS#

Folder and file names on Windows#

TOPAS 7#

Behaviors#

Space groups#

EB-11 · A bare two-origin symbol is origin choice 1#

EB-43 · A bare rhombohedral symbol means hexagonal axes#

EB-68 · Some settings have no TOPAS symbol, and three are misread#

Special positions and sites#

EB-08 · TOPAS compares positions within 1e-15#

Cell, ADPs and occupancy#

EB-09 · Cell values are used as given#

EB-10 · The adps keyword applies the Uij constraints#

EB-24 · TOPAS’s isotropic ADP is beq, not Uiso#

EB-21 · Occupancy is limited per iteration#

Names#

EB-49 · Two parameters with the same name are one parameter#

Bounds and limits#

EB-58 · Keywords and macros carry default limits#

EB-62 · The limit markers TOPAS writes are unreliable#

Peak profile and instrument#

EB-55 · TCHZ takes the absolute value of its Gaussian term#

EB-69 · A negative TCHZ Lorentzian part is computed as written#

EB-56 · PVII_Peak_Type differs from the Technical Reference#

EB-57 · CS and Strain terms are not sizes or strains#

EB-64 · An emission line with lg alone crashes TOPAS 6#

Data and the fit window#

EB-59 · TOPAS fits the points nearest its limits#

EB-66 · An xo_Is peak loses part of its value at the last fitted point#

Refinement, convergence and failures#

EB-60 · tc.exe gives the same exit code on success and failure#

EB-85 · TOPAS 6 exposes no convergence signal#

EB-63 · A non-finite term silently zeroes a phase#

EB-65 · The independent-parameter count works but is undocumented#

Platform and installation#

EB-67 · tc.exe carries no version metadata#

EB-61 · TOPAS 6 cannot output the fit’s background#