Asymmetry units across the API
The μSR asymmetry is a ratio, so it has no physical unit — but it does have a
scale, and Asymmetry’s public API uses two of them. The low-level primitives
return a dimensionless fraction; the loaders, the reductions, and every
built-in time-domain asymmetry model work in percent (fraction × 100),
the WiMDA-style convention in which a 16 % asymmetry is the number 16.0. Both conventions are internally consistent, and
each is the natural one where it is used: a fraction composes cleanly with
polarisation functions, while percent is what a fitted amplitude is quoted as in
a paper.
These are scales, not bounds: signed corrected counts and general beta can produce estimates outside \([-1,1]\) in fractions. Errors in percent are percentage points. See Errors for propagation, calibration conditioning, and current sparse-bin fallbacks.
The cost of having two is that mixing them is a silent factor of 100. It does not raise, and it rarely looks like an error: a 20 % transverse-field amplitude fitted against fraction-scale data reads as 0.2 %, which is a perfectly plausible number for a paramagnet. This page is the map of which scale each part of the API speaks, so no call site has to guess.
The short version
Counts in, fraction out. Anything that forms an asymmetry from histograms —
compute_asymmetry(),binned_fb_asymmetry(),integrate_asymmetry()— returns a fraction.Anything that hands you a dataset or a reduction is percent.
asymmetry,reduce_grouped_asymmetry(), every loader.Fit amplitudes follow the data. The engine never rescales, and the built-in models seed
A0at25because they expect percent.The field-scan / ALC surface is the exception: a
FieldScanis fraction-scale, and so are the amplitudes fitted to it.
The binned primitive accepts a
ForwardBackwardCounts value,
which carries counts, variances, the good-bin window and the time grid.
Its result remains fraction-scale; validation does not rescale the counts
or the resulting asymmetry.
The integral primitive and detailed α estimator accept two
GroupCounts values, including
independent variances and shared correction components. For example,
integrate_asymmetry(corrected.forward, corrected.backward) returns one
fractional asymmetry and its marginal error.
Naming a scale in code
asymmetry.core.transform.units gives the distinction a name, so a call
site can state a scale rather than leave a reader to infer it:
from asymmetry.core.transform import (
ASYMMETRY_FRACTION,
ASYMMETRY_PERCENT,
AsymmetryUnit,
convert_asymmetry,
to_fraction,
to_percent,
)
asym, err = compute_asymmetry(forward, backward, alpha) # a fraction
result = FitEngine().fit_arrays( # percent expected
time, to_percent(asym), to_percent(err), model.function, params
)
reduction.units is ASYMMETRY_PERCENT # the reduction states its own scale
scan.units is ASYMMETRY_FRACTION # and so does a field scan
AsymmetryUnit has exactly two members,
FRACTION and PERCENT, with the module-level aliases
ASYMMETRY_FRACTION and
ASYMMETRY_PERCENT. There is deliberately
no “automatic” member: a scale is a property of the function that produced the
values, never something to be guessed from their magnitude, since guessing is the
failure this distinction exists to prevent. Use
to_percent() and
to_fraction() for the common direction, or
convert_asymmetry() when both ends are
named explicitly.
None of this changes any existing return value. The two result containers that sit
on opposite sides of the divide now record their scale —
GroupedAsymmetryReduction.units is always ASYMMETRY_PERCENT and
FieldScan.units always ASYMMETRY_FRACTION for a scan built by
build_field_scan() — so downstream code can assert
the convention it assumed instead of trusting a comment.
The table
“Preserves” means the function is linear in the asymmetry and returns whatever scale it was given: it is safe on either, and never converts.
Function or attribute |
Scale |
Notes |
|---|---|---|
fraction |
The textbook primitive; the error is on the same scale. |
|
fraction |
As above, with supplied count uncertainties. |
|
fraction |
Accepts validated grouped counts; bins counts before forming the ratio. |
|
percent |
The one step on the reduction path that applies the |
|
fraction |
Integral (ALC) observable, both reduction methods. |
|
fraction |
Reduces the run’s counts, so a |
|
preserves |
Averages a curve you supply; percent in, percent out. |
|
fraction |
|
|
preserves |
Dividing by \(\Delta x\) leaves the asymmetry scale alone. |
|
preserves |
A mean of values with errors in quadrature. |
|
preserves |
Demodulation is linear, so the components carry the input’s scale. |
|
|
n/a |
Count domain, or dimensionless ratios — no asymmetry scale. |
Function or attribute |
Scale |
Notes |
|---|---|---|
percent |
The stored convention; the loaders apply the |
|
percent |
Explicit views, for when the scale should be stated at the call site. |
|
fraction |
As above, on the other scale. |
|
percent |
Take a |
|
percent expected |
Takes bare arrays and rescales nothing, so the scale is the caller’s to state; percent matches the built-in models’ seeds. |
|
|
follows the data |
Percent for a normal time-domain fit. Fit fraction-scale arrays and the amplitudes come back as fractions. |
The built-in models’ |
percent |
Why |
percent parameters |
The data is raw counts; the physics amplitude is still percent, divided down internally. |
|
|
percent |
Including |
fraction |
They fit a |
|
The polarisation kernels |
scale-free |
Unit-normalised: |
When it bites, and how it is caught
The two scales meet most often at the boundary between a custom reduction and a
fit. Forming an asymmetry from a non-default detector pairing gives a fraction;
handing it to fit_arrays() with the
models’ default seeds fits percent-scale amplitudes against it.
Asymmetry guards that specific case at run time. When the data and the seeded
model curve straddle the fraction/percent boundary — one peak at or below 1.5,
a heuristic fraction-scale region, and the other above that region — the engine
emits an AsymmetryScaleWarning before minimising.
This magnitude heuristic does not establish a physical range or prove a scale
mismatch. It is advisory only: it never raises and never changes the fit, and the message is
carried on FitResult.warnings and shown in the GUI fit panel’s result box (see
Advisory warnings (result.warnings)). A merely badly-guessed amplitude on the right scale
is deliberately not flagged — the guard is about scale confusion, not seed quality.
The guard cannot catch everything, since a genuinely small amplitude on the
percent scale is indistinguishable from a large one on the fraction scale. The
reliable habit is the explicit one: use
asymmetry_percent /
asymmetry_fraction when reading
from a dataset, and to_percent() /
to_fraction() when moving a primitive’s
output across the boundary.
See also Match the asymmetry scale (percent vs fraction) for the worked seeding recipe, and Fitting engine for the fit engine’s own entry points.
Compared with other programs
WiMDA 1.326 uses percent for ordinary asymmetry curves. musrfit 1.12.1
(708f777b, ROOT 6.40.04) type-2 ASCII data/errors in the matched controls
are in the raw fitting coordinate; multiply both by 100 only after any needed
conversion to corrected asymmetry. Mantid’s reviewed AsymmetryCalc v1 returns
a fraction with a different error approximation. See
Asymmetry values, coordinates, and errors for sources, settings, tolerances, and
the distinction between documented arithmetic and native comparisons.