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 A0 at 25 because they expect percent.

  • The field-scan / ALC surface is the exception: a FieldScan is 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.

Asymmetry-valued surfaces in core.transform

Function or attribute

Scale

Notes

compute_asymmetry()

fraction

The textbook primitive; the error is on the same scale.

compute_asymmetry_with_count_errors()

fraction

As above, with supplied count uncertainties.

binned_fb_asymmetry()

fraction

Accepts validated grouped counts; bins counts before forming the ratio.

reduce_grouped_asymmetry()

percent

The one step on the reduction path that applies the ×100; units records it.

integrate_asymmetry()

fraction

Integral (ALC) observable, both reduction methods.

integrate_run()

fraction

Reduces the run’s counts, so a MuonDataset argument’s own percent-scale curve is never involved.

integrate_curve()

preserves

Averages a curve you supply; percent in, percent out.

build_field_scan(), FieldScan, FieldScanPoint

fraction

units records it; the ALC parameter models expect this scale.

differentiate_scan()

preserves

Dividing by \(\Delta x\) leaves the asymmetry scale alone.

rebin(), merge_curve_bins()

preserves

A mean of values with errors in quadrature.

rrf_demodulate(), rrf_demodulate_values(), RRFCurve

preserves

Demodulation is linear, so the components carry the input’s scale.

estimate_alpha(), estimate_alpha_detailed(), corrected_grouped_counts(), the background and deadtime corrections

n/a

Count domain, or dimensionless ratios — no asymmetry scale.

Asymmetry-valued surfaces in core.data and core.fitting

Function or attribute

Scale

Notes

asymmetry, error

percent

The stored convention; the loaders apply the ×100.

asymmetry_percent, error_percent

percent

Explicit views, for when the scale should be stated at the call site.

asymmetry_fraction, error_fraction

fraction

As above, on the other scale.

fit(), global_fit()

percent

Take a MuonDataset, so percent by its convention. A global fit’s datasets must all be on one scale.

fit_arrays()

percent expected

Takes bare arrays and rescales nothing, so the scale is the caller’s to state; percent matches the built-in models’ seeds.

FitResult — residuals, and the amplitude entries of parameters / uncertainties

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’ A0 / A / baseline (MODELS, the composite COMPONENTS)

percent

Why A0 seeds at 25, and why PARAM_INFO_REGISTRY labels A with %.

fit_single_histogram(), fit_fb_alpha()

percent parameters

The data is raw counts; the physics amplitude is still percent, divided down internally.

fit_mu_relaxation_series(), MuRelaxationSeriesResult.shared_amplitude, mu_relaxation_from_amplitude()

percent

Including reference_amplitude.

fit_scan_model(), fit_scan_baseline(), rf_resonance_seeds()

fraction

They fit a FieldScan, so amplitudes come back fraction-scale. The one fraction-scale corner of the fitting layer.

The polarisation kernels P(t) — risch_kehr, bessel_oscillation, and the muonium, muon-fluorine and nuclear-dipole modules

scale-free

Unit-normalised: P(0) = 1, with the amplitude supplied by whichever component scales them.

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.