GSAS-II#

Version

5.7.9, installed by pixi install --frozen -e gsasii

Workflows

gsasii.rietveld (Rietveld refinement), gsasii.spf (single-peak fitting)

Parameters

[value, flag], no bounds

Platforms

Linux, Windows; macOS expected to work, not routinely tested

Run

pixi run -e gsasii powderline <recipe.json>

Cite

Toby & Von Dreele (2013) and O’Donnell et al. (2018), see Citing

What you write#

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

{
  "schema_name": "gsasii.rietveld",
  "core_schema_version": "0.1.0",
  "engine_schema_version": "0.1.0",
  "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": {"type": "PXC", "wavelength": [0.1665, false]},
      "geometry": {"bank": 1, "azimuth": 0.0},
      "corrections": {
        "zero_shift": [0.0, false],
        "polarization": [0.99, false],
        "axial_divergence": [0.002, false]
      },
      "broadening": {
        "U": [18.7, true], "V": [0.60, true], "W": [1.15, true],
        "X": [0.28, true], "Y": [0.001, false], "Z": [0.0, false]
      }
    },
    "phases": {
      "LaB6": {
        "space_group": "P m -3 m",
        "unit_cell": {
          "a": [4.15682, true], "b": [4.15682, true], "c": [4.15682, true],
          "alpha": [90.0, false], "beta": [90.0, false], "gamma": [90.0, false]
        },
        "atoms": {
          "La": {"element": "La", "x": [0.0, false], "y": [0.0, false], "z": [0.0, false],
                 "occupancy": [1.0, false], "ADP": "Uiso", "Uiso": [0.0086, false]},
          "B": {"element": "B", "x": [0.5, false], "y": [0.5, false], "z": [0.2021, false],
                "occupancy": [1.0, false], "ADP": "Uiso", "Uiso": [0.009, false]}
        },
        "scale": [1.0, true]
      }
    },
    "refinement_controls": {"refinement_cycles": 5}
  }
}

Required in gsasii.rietveld:

  • xrd_data: tth, Itth, Itth_weights.

  • instrument with all four blocks: radiation, geometry, corrections, broadening.

  • At least one phase in phases, each with space_group, unit_cell, atoms and scale. scale is ≥ 0. A scale of 0 is accepted, so a recipe can be reused with its scale still to be set.

  • refinement_controls.

Optional: fit_range; background; instrument.description; and per phase peak_broadening, scattering_types and preferred_orientation. The recipe above leaves out background and peak_broadening, so it validates with three default warnings: one for the background, and one each for size and strain broadening (see Defaults).

gsasii.spf (single-peak fitting) has no phases. It needs xrd_data, instrument as above, single_peaks and refinement_controls with single_peak_fitting_mode.use_instrument_profile. single_peaks holds four lists of the same length: positions, intensities, pv_gaussian_sigma_sq and pv_lorentzian_gamma. fit_range and background are optional. Start from examples/example_LaB6_singlepeakfit/input.json.

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

Units that differ from other engines#

Quantity

GSAS-II unit

U, V, W (Gaussian variance)

centidegree²

X, Y, Z

centidegree

axial_divergence (SH/L)

dimensionless

pv_gaussian_sigma_sq (peak σ²)

centidegree²

pv_lorentzian_gamma (peak γ)

centidegree

crystallite size

µm

microstrain

Δd/d × 10⁶

GSAS-II’s Lorentzian width is X/cosθ + Y tanθ. In TOPAS and easydiffraction it is X tanθ + Y/cosθ: the roles of X and Y swap.

Defaults#

GSAS-II recipes are the only ones with defaults. A new GSAS-II project would add sample broadening and a background you did not ask for (EB-36). PowderLine applies its own defaults instead, each with a warning, so you always know one was used.

Left out

Used instead

Warning

peak_broadening (size or strain)

10 µm size, 0 microstrain, isotropic, fixed

gsasii_broadening_default_applied

background (or its chebyshev)

no background: one fixed Chebyshev term 0.0

gsasii_background_default_applied

refinement_cycles

5

gsasii_refinement_cycles_default_applied

State the block to silence its warning.

Bounds#

gsasii.* recipes have no bounds. GSAS-II applies a limit only after all cycles, and freezes the value for the next call (EB-30, EB-31, KI-06). A 4-element parameter list is a validation error. Bounds in every engine: Recipe format.

The instrument block#

instrument is the only source of GSAS-II’s instrument parameters. The gateway builds GSAS-II’s own parameter dictionary from it. There is no pasted GSAS-II parameter block, and no null that means “take the engine’s value”.

Block

Fields

radiation

type: "PXC", wavelength

geometry

bank, azimuth

corrections

zero_shift, polarization (GSAS-II’s P), axial_divergence (SH/L)

broadening

U, V, W, X, Y, Z

description

optional free text

  • axial_divergence must be at least 0.002, GSAS-II’s own evaluation floor (EB-37).

  • type is "PXC" only. Kα doublets, time-of-flight and neutron data are not supported.

  • A wavelength ≤ 0 is a validation error. GSAS-II itself would fail with “no reflections”.

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.single_peaks adds pseudo-Voigt background peaks. Each must lie inside the fit window (EB-38), with values at or above GSAS-II’s floors (EB-35).

  • refinement_controls.refinement_cycles sets the number of cycles. 1 is a simulation: then every refine flag must be false, including polarization and the Peak List flags.

Preferred orientation#

preferred_orientation is March–Dollase, per phase:

"preferred_orientation": {"model": "march_dollase", "hkl": [0, 0, 1], "ratio": [0.8, true]}

  • hkl holds integers, not all zero. The ratio r must be > 0.

  • GSAS-II’s convention: r = 1 is random, r < 1 platy, r > 1 needle. The correction is averaged over the symmetry equivalents of the axis.

  • The refined ratio maps back to …preferred_orientation.ratio in the output recipe.

Warning

Don’t start the ratio at exactly 1.0 in a cubic phase There the correction is stationary, so no step lowers χ². GSAS-II aborts, and PowderLine reports the run as failed, reason diverged (EB-99). On the textured LaB6 example, a start at 0.9 goes non-finite and a start at 1.2 settles on the needle-side minimum, r = 1.73. Start on the side of 1 you expect.

How PowderLine runs GSAS-II#

        flowchart LR
    R[recipe] --> M{execution mode}
    M -- "auto (default)" --> S{server running<br/>or startable?}
    S -- yes --> SV["GSAS-II server<br/>(stays loaded)"]
    S -- no --> IP[in-process run]
    M -- "server" --> SV
    M -- "subprocess" --> IP

A GSAS-II recipe runs in one of three execution modes. auto, the default, uses a persistent GSAS-II server that stays loaded between runs, and falls back to an in-process run. server (--use-server) uses the server only, and subprocess (--no-server) runs in PowderLine’s own process. Both paths produce the same files and results.

result = powderline.run(recipe, "output", execution_mode="subprocess")

How to start, check and secure the server, and how to limit the wait for it: Run at a beamline.

Convergence and failures#

  • GSAS-II’s convergence flag becomes the result’s converged. When the last cycle’s χ² change was above GSAS-II’s tolerance, the result warns gsasii_fit_not_converged and keeps the values. A Peak List fit keeps no flag, so converged is None there. The committed DRX_33 examples report converged: false after their five cycles.

  • A crystallite size ≤ 0 is a validation error. GSAS-II itself would fail with an SVD failure.

  • After phase setup, the gateway checks GSAS-II’s reading of every site. A site it misreads stops the run with reason unusable_site, naming a position to write instead (EB-40, EB-05).

  • A run that fails raises an error. Its directory keeps failure.json and the console text GSAS-II printed (KI-05). Details: Outputs.

Behaviors#

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

Space groups#

EB-03 · Origin choice 1 is silently ignored#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II’s own space-group lookup tolerates :H and :2 and silently ignores :1. A recipe meant in origin choice 1 runs in origin choice 2, on a different structure.

PowderLine does: The gsasii gateway refuses every origin-choice-1 setting (33 settings). To use one, transform the structure to a standard setting.

You see: validation error

EB-04 · A rhombohedral symbol means hexagonal axes unless it ends in R#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II reads R -3 m and R -3 m:H on hexagonal axes. R -3 m R or :R gives rhombohedral axes.

PowderLine does: Core requires the canonical name, which states :H or :R explicitly. A bare rhombohedral symbol is an error that lists both choices. The gsasii gateway writes a trailing R for :R and drops :H.

You see: validation error

EB-41 · Some spellings are not found, and two settings are read as another#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II reads spaced symbols. Its lookup returns nothing for spellings such as R-3m:H or Fd-3m:2. It reads P 21 n m and A b a m as another setting, whose general position has a different orbit.

PowderLine does: The gsasii gateway translates the canonical name: a spaced symbol, R for :R, :H and :2 dropped. It refuses 9 settings beyond origin choice 1: 7 that GSAS-II does not parse and 2 that it misreads. A general-position orbit test over every accepted setting proves the translation.

You see: validation error

Special positions and sites#

EB-01 · GSAS-II uses its own special-position tolerance#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II compares symmetry images within 2e-5 + 1e-5·|x|, and not modulo 1.

PowderLine does: Core decides special positions, not the engine. A symmetry image within 5e-6 (fractional) of the atom means it sits on that symmetry element. An image 5e-6 to 2e-3 away is a validation error. Derived values are held exactly in the validated model, so GSAS-II’s tolerance never matters.

You see: symmetry_value_derived, validation error

EB-02 · A coordinate next to a cell edge gets a wrong multiplicity#

handled · GSAS-II 5.7.9

GSAS-II does: A coordinate just below an integer gets multiplicity 0. A coordinate just above 0 gets an invalid multiplicity.

PowderLine does: This cannot be reached: such coordinates are exact constants in the validated model.

EB-40 · Some 2-fold sites in R32, R-3m and R-3c are misread#

handled · GSAS-II 5.7.9

GSAS-II does: On hexagonal axes, GSAS-II reads some orientations of these 2-fold sites, such as (0, 1/3, 1/6), as a general position with doubled multiplicity. With nothing refined, it computes four times the Bragg intensity of the equivalent (1/3, 0, 1/6).

PowderLine does: After phase setup, the gsasii gateway compares GSAS-II’s site symmetry and multiplicity with core’s for every atom. A wrong multiplicity always stops the run, even in a simulation. The error names an equivalent position GSAS-II reads correctly. PowderLine never substitutes the position silently, because refined coordinates would then differ from the recipe.

You see: unusable_site

EB-05 · Some site symmetries cannot be named, and refining them crashes#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II cannot name the symmetry of some site orientations ('sp'), for example F432 at (0, y, 0). It crashes when a coordinate or Uaniso of such an atom is refined.

PowderLine does: After phase setup, the gsasii gateway stops with an error naming an equivalent position GSAS-II can name. It does so only when a coordinate or Uaniso of that atom is refined.

You see: unusable_site

Cell, ADPs and occupancy#

EB-06 · A fixed cell is not checked against its symmetry#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II enforces cell symmetry only while the cell is refined. A fixed, inconsistent cell is used as given and gives wrong peak positions.

PowderLine does: Core refuses a cell that does not fit the space group, within 1e-9, in every engine. The error gives the value to write (KI-01).

You see: validation error

EB-07 · Uij site-symmetry constraints apply only while refining#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II applies the site-symmetry constraints on Uij when refining. It stores the values as given.

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

You see: validation error

EB-51 · Negative ADPs are carried and refined#

documented · GSAS-II 5.7.9

GSAS-II does: GSAS-II carries negative Uiso and Uij values and refines from them.

PowderLine does: Core has no sign rule for ADPs: a negative ADP can compensate for an unmodeled effect.

EB-20 · Any occupancy is accepted#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II accepts any occupancy value.

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

You see: validation error

Scattering types#

EB-94 · An ion in CIF spelling is read as hydrogen#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II reads the CIF spelling La3+ as hydrogen (Z = 1), silently. Its own spelling is La+3. Its form-factor table has 114 ions.

PowderLine does: You write La3+ in scattering_types. The gsasii gateway writes GSAS-II’s spelling into the atom record. It refuses an ion GSAS-II has no form factor for.

You see: validation error

Seen in: example_LaB6_ionic

Names#

EB-44 · GSAS-II rewrites phase names#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II strips surrounding whitespace from a phase name and replaces non-ASCII characters with _. The settings of a renamed phase are then skipped silently. A / in the name breaks the report file write.

PowderLine does: The core name rule makes every such name invalid before an engine runs: ^[A-Za-z][A-Za-z0-9_]*$, at most 64 characters, no Python keyword, distinct ignoring case.

You see: validation error

Bounds and limits#

EB-30 · Parameter limits apply only after all cycles#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II applies parameter limits only after all cycles of a Refine call. An out-of-range value is set to the limit with ESD 0 and frozen for the next call. The reported values, ESDs and Rwp belong to the unclamped fit.

PowderLine does: gsasii.* recipes expose no bounds. A 4-element parameter list is a validation error (KI-06).

You see: validation error

EB-31 · Cell limits act on the reciprocal metric#

handled · GSAS-II 5.7.9

GSAS-II does: Cell limits must be set on the reciprocal-metric terms. They map exactly onto direct-cell boxes for only four of the seven crystal systems.

PowderLine does: gsasii.* recipes expose no bounds. A 4-element parameter list is a validation error.

You see: validation error

Defaults#

EB-36 · A new project adds broadening and background you did not ask for#

warned · GSAS-II 5.7.9

GSAS-II does: A new GSAS-II project gets isotropic size 1 µm, microstrain 1000 and a constant 1.0 Chebyshev background, all fixed.

PowderLine does: Size and strain left out mean 10 µm and 0 microstrain, isotropic, fixed: no sample broadening. A background left out means none: one fixed Chebyshev term 0.0. Each default comes with a warning naming the phase and the values. State the blocks to silence the warning.

You see: gsasii_broadening_default_applied, gsasii_background_default_applied

Peak profile and instrument#

EB-37 · SH/L and Peak List widths are floored silently#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II floors SH/L at 0.002 in the Rietveld and Peak List profile calculations. It floors it at 0.0005 in GetFobsSq, and background peaks use it as stored. Peak List peaks floor σ² and γ at 0.001.

PowderLine does: axial_divergence below 0.002 is a validation error. So is a Peak List width below its floor.

You see: validation error

EB-35 · Background peaks are evaluated with silent floors#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II evaluates background peaks with floors: intensity 0.1, σ² 0.01 centideg², γ 0.1 centideg.

PowderLine does: A stated value below a floor is a validation error. A refined value below a floor makes the output recipe invalid (KI-15).

You see: validation error, output_recipe_not_valid

Seen in: example_LaB6_singlepeakfit

EB-34 · The background-peak width is a variance#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II’s BkPksig is σ² in centideg², although its GUI calls it sig and its prose calls it “Gaussian width”.

PowderLine does: The recipe field is named pv_gaussian_sigma_sq.

EB-39 · Exported peak widths use other units, and some formulas are wrong#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II’s peak int is an integrated area. Its exporters write σ in degrees while the project holds σ² in centideg², and several exporter formulas are wrong.

PowderLine does: PowderLine reads the project directly and uses none of those exporters.

Data and the fit window#

EB-54 · GSAS-II fits one point past the upper limit#

handled · GSAS-II 5.7.9

GSAS-II does: When the upper limit falls between data points, GSAS-II fits and scores one point past it. With no limit, it starts at the first data point, weighted or not. Its Nobs counts the extra point.

PowderLine does: The gateway hands GSAS-II the fit limits moved onto the first and last weighted data points inside the window. GSAS-II then fits exactly the points core scores, and its own Rwp equals core’s.

Refinement, convergence and failures#

EB-32 · Refinement messages are only printed and stored#

warned · GSAS-II 5.7.9

GSAS-II does: Refine returns nothing on success. Its messages about frozen limits, parameters dropped as singular and SVD are only printed and stored in the project.

PowderLine does: The gateway reads the stored messages into warnings.

You see: gsasii_refinement_message

EB-33 · The parameter count includes parameters dropped as singular#

warned · GSAS-II 5.7.9

GSAS-II does: GSAS-II’s Nvars includes parameters it dropped as singular.

PowderLine does: PowderLine reports the drop as a warning and does not subtract it. In a single-peak fit, the count is taken after the drops.

You see: gsasii_refinement_message

EB-53 · Single-peak fitting ignores some refine flags silently#

handled · GSAS-II 5.7.9

GSAS-II does: With the instrument profile in use, a peak’s own σ² and γ flags are ignored. With per-peak widths, the U … Z flags are ignored. Refining any σ² clears the U, V, W flags. Singular parameters are dropped without a message.

PowderLine does: A refine flag on the width source not in use is a validation error. Any remaining silent drop gets a warning.

You see: validation error, gsasii_parameters_not_varied

EB-92 · A peak fit fills no covariance block#

handled · GSAS-II 5.7.9

GSAS-II does: DoPeakFit keeps its varied names and ESDs in the Peak List’s own record, and writes the refined values in place. A peak fit therefore has no refined-parameter rows.

PowderLine does: The result’s peak_fit block reads the values and ESDs from there. The output recipe is built from it.

EB-38 · A peak outside the fit window makes the peak fit fail with a bare TypeError#

handled · GSAS-II 5.7.9

GSAS-II does: A Peak List or background peak outside the fit window makes GSAS-II’s peak fit fail with a bare TypeError.

PowderLine does: A peak outside the fit window is a validation error. A peak fit that still fails raises EngineExecutionError with a clear reason.

You see: validation error, peak_fit_failed

EB-99 · An aborted refinement keeps a worthless pattern#

handled · GSAS-II 5.7.9

GSAS-II does: When no damped step lowers χ², GSAS-II aborts the refinement. It keeps the last accepted values but stores the rejected step’s pattern and a wR at its 100 % cap. No statistic belongs to the parameters. GSAS-II’s GUI shows this only as “Minimizer halted because chi**2 increased”. A March–Dollase ratio started at exactly 1.0 in a cubic phase triggers it.

PowderLine does: PowderLine is deliberately stricter: an aborted Rietveld refinement is a failure, reason diverged. Simulations are exempt.

You see: diverged

Statistics#

EB-52 · GOF has two meanings, and R values are capped at 100 %#

handled · GSAS-II 5.7.9

GSAS-II does: GSAS-II’s GOF is √(reduced χ²) in a Rietveld refinement and the reduced χ² itself in a Peak List fit. GSAS-II caps R and wR at 100 %, so a simulation against placeholder data and a diverged refinement both read 100 %. A non-finite pattern prints wR nan and reports 100 %.

PowderLine does: The result’s rwp, r_exp, gof and chi2_red are PowderLine’s, with one formula for every engine. GSAS-II’s own values stay under engine_details. A non-finite calculated pattern is a failure, reason diverged. A poor fit at the cap is still reported, with core’s uncapped Rwp beside it.

You see: diverged

On this page
Show Source