Alpha calibration
The measured forward/backward asymmetry
depends on the calibration constant \(\alpha = N_F^0/N_B^0\), the ratio of the two detector groups’ efficiency × solid-angle products. With the correct \(\alpha\) the asymmetry equals \(a_0 P_z(t)\); with the wrong one, a spurious baseline and a nonlinear distortion of the polarisation enter every fit. Alpha is a property of the instrument configuration and the sample position, so it must be recalibrated per mounting — and, because detector solid angles change with sample environment, ideally per cooldown.
The grouping dialog’s Estimate calibration control uses TF calibration fit for a fresh explicit calibration. It compares undamped, exponential, Gaussian, and stretched common-phase F/B envelopes and shows the selected model. The minimum finite summed cost among usable candidates wins; model selection does not establish physical truth. Calibrate β fits alpha and beta jointly in a single-pair layout; unchecked fixes beta at one. Vector layouts calibrate alpha for each projection with beta fixed at one. Estimate All α publishes the requested projections together after every fit succeeds. Failure or Stop discards the incomplete batch and leaves the draft coefficients unchanged.
Diamagnetic, Decay balance (stored method general), and
Count ratio ΣF/ΣB remain explicit quick choices. Quick methods disable and
uncheck Calibrate β. Diamagnetic and Decay balance return no added uncertainty;
ratio reports first-order errors. TF errors are conditional on the selected
count model, observations, and corrections. An unavailable error is not zero.
The compact result summary identifies the period or mapped set and F/B pair.
TF fits show Poisson deviance/ν or χ²/ν and the number of degrees of
freedom, with conditional errors marked when unavailable or unreliable.
These are diagnostics of the selected fit, without a model-truth verdict.
Quick methods show the bins used and first-order errors or
no error estimate. The calibration-run selector identifies the source;
the complete source context remains in the captured record. Quick records retain
the resolved forward/backward channel members, and quick and TF records retain
authored channel exclusions. These are frozen at execution, independently of
later regrouping or target settings. Older records without these captured facts
leave them unknown rather than infer them from the current groups.
A completed calibration updates the draft alpha and beta spinboxes and the
preview immediately. Fixed-beta operations show beta one. The coefficient’s
method replaces manual until its value is changed by hand. Apply commits
both coefficients and their captured record to the run/project; estimating does
not write saved values. Stop and input changes cancel pending work, and an
obsolete worker cannot overwrite the displayed values. Completed measurements
retain their captured source and assumptions when editing the draft. Loading a
project never starts a calibration. A zero or nonfinite coefficient
cannot be applied as a detector calibration; the source and diagnostic remain
available for inspection.
While running, the status reads Computing calibration…. Stop clears the pending request and restores No calibration result; an error reads Calibration failed: followed by its diagnostic. An input rejected before work starts reads Calibration unavailable: followed by the input diagnostic. A source edit observed during preview refresh also cancels the captured request. Source and reference identity are checked again before queued results update the draft. An obsolete success, error, or cancellation cannot overwrite a newer request.
Cancellation is cooperative: quick Diamagnetic work polls before each objective evaluation, Decay balance before each diagnostic sub-window, and count preparation between detector and bank stages. TF minimisation, HESSE, and optional MINOS retain the solver’s eight-cost-evaluation polling interval; envelope transitions and the final result boundary also check cancellation. A single array operation or native call finishes before its next check, so there is no universal time deadline. Cancellation returns no partial calibration or vector batch. Committed manual coefficients and completed calibration history remain available.
Choosing a method
Use a weak-TF calibration on the same sample and mounting for TF calibration fit
or the quick Diamagnetic cross-check. Use Decay balance for visibly relaxing
LF/ZF data when no TF calibrant is available. The ratio provides a separate
integral-balance check (Mantid AlphaCalc convention). Different objectives
and finite windows can produce different alpha values; their uncertainties do
not describe the same estimator.
Corrections and the estimate
An Estimate result is a stored, one-shot calibration. Changing groups or
corrections preserves its value, method, source and uncertainty; a staleness
warning invites an explicit new estimate. It does not enable automatic fitting.
The separate profile policy per_run_estimate recomputes only the integral
ratio on the target run’s current corrected counts and good window. It requires
finite positive integrals on both sides and a finite positive ratio. Failure
makes the reduction unavailable instead of substituting a coefficient of one.
Fixed unity remains an explicit valid choice. See Detector Grouping and Layout.
For acquired-run arithmetic, an explicit per_run_estimate policy uses one
ratio of the pooled corrected native-good sums. Output packing and time crops
retain the complete calibration dependency. A G−R asymmetry uses the Red
estimate on both conditions; explicit projection coefficients take precedence.
Quick estimates use the corrected forward/backward counts: configured deadtime correction, grouping, and background subtraction precede the estimate. Their native good-bin window is independent of science output packing and time crops. A flat background pedestal need not track the detector efficiency ratio, so background subtraction can change the quick estimate; finite-window and weighting biases can remain. TF calibration instead fits its own count model with separate constant backgrounds, using retained counting variances when supported deadtime correction is applied. The grouping background subtraction does not fix or subtract those fitted model backgrounds. See Stored and automatic calibration policies and Count reduction and transformed signals.
The calibration dialog shows which corrections the estimate reflects beneath the result, and warns when a requested correction could not be applied to the selected calibration run — for example a reference-run background whose reference could not be resolved — so a flattened “after” curve never misrepresents a calibration the reduction will not reproduce.
A fresh count request prepares the retained acquired histograms with its current grouping and corrections. A failed cached asymmetry curve does not block that request after its grouping is repaired; the cached diagnosis remains history. Current unavailable corrections, missing acquired observations, and unsupported count likelihoods still receive their own diagnostics.
Diamagnetic method
Minimises the weighted asymmetry power
where \(\sigma_i\) is a nominal first-order Poisson weight computed from the prepared counts. For corrected input this objective does not model the full correction covariance. In a transverse field the muons in a diamagnetic environment precess, so the true asymmetry oscillates symmetrically about zero — any imbalance shows up as a net offset that inflates \(S\). The minimum of \(S(\alpha)\) is a quick balance estimate; finite windows and the alpha-dependent weights can displace it from the efficiency ratio.
When to use this. A quick cross-check for a weak-TF run on a sample in a diamagnetic (non-magnetic, non-relaxing) state — the standard calibration measurement. A resolved oscillation provides a useful balance reference; precision depends on its amplitude, window, corrections, and count statistics. Avoid it on magnetically ordered samples (spontaneous fields shift the oscillation) and on data where the diamagnetic fraction is small.
Asymmetry uses bounded continuous minimisation on internally packed equal-statistics bins, independently of the display bunching factor. The matched quick-estimate outputs below do not identify WiMDA’s internal search.
General method
The General method uses the lifetime-corrected balanced count
At the correct alpha, the polarisation cancels under a common muon-decay envelope, equal forward/backward polarisation magnitudes (beta = 1), and correct background subtraction. Flatness alone does not uniquely identify alpha: constant polarisation makes every alpha give a flat envelope. Asymmetry equates weighted lifetime-corrected densities in an early and a late equal-statistics window. With densities \(F_1,F_2,B_1,B_2\), this gives \(\alpha=(F_1-F_2)/(B_2-B_1)\). The sums are linear, but their ratio is nonlinear and need not be statistically unbiased.
Use General on relaxing LF/ZF data when no TF calibration is available, provided the two windows have different mean polarisation. Time variation can also come from TF precession. A finite window can give equal window means even for a varying signal. Weak or noisy contrast can give an unstable estimate; no uncertainty or confidence test is supplied by this quick method. Background and deadtime corrections should be applied first. A residual flat background grows after lifetime correction and can bias the late window.
The WiMDA original manual, Appendix A describes a general balance estimate. That method description and the native point controls below do not establish equivalence to Asymmetry’s two-window objective.
Asymmetry also checks for numerical degeneracy before dividing the window differences. Differences no larger than a floating-point accumulation bound scaled by the absolute summands of the densities are treated as zero contrast. The bound scales with the number of terms and double-precision machine epsilon [roundoff]; it is not a statistical significance threshold. Passing it does not establish physical identifiability on noisy or weakly relaxing data.
Goodness gate: the lifetime assumption. The flatness condition holds only if the counts decay at exactly \(\tau_\mu\). Two windows give one equation for one unknown, so counts whose effective lifetime differs slightly from \(\tau_\mu\) — through pile-up rejection, or a background subtracted a little too generously — are indistinguishable from a detector imbalance, and the whole mismatch is absorbed into \(\alpha\). A 0.5 % lifetime error is enough to shift \(\alpha\) by 10 % at a 20 % asymmetry, and by tens of per cent when the asymmetry is small.
Asymmetry also checks the flatness after solving, across eight
equal-statistics sub-windows and with \(\alpha\) re-freed, and reads the
surviving time trend back as an effective lifetime. When that lifetime differs
from \(\tau_\mu\) by more than 0.15 % and the deviation is resolved at
2.5 standard errors, the estimate comes back with ok false and a message
naming the deviation, so a wrong number is not presented as a good one. The
value itself is never altered by the gate, and objective_value carries the
flatness \(\chi^2\) of the sub-window levels for inspection either way. If
your data trips the gate, calibrate \(\alpha\) from a fully depolarised
late-time window with the count ratio instead, if enough counts remain.
Where \(P_z(t) \rightarrow 0\), the ratio of expected counts equals alpha
without a lifetime assumption; a ratio of measured sums still has sampling bias.
The lifetime diagnostic uses approximate Poisson weights on the prepared counts;
it does not propagate all correction uncertainty or certify a valid calibration.
If it cannot form enough usable sub-windows or resolve its fitted parameters,
the result message says the check was not applied.
Count ratio
over the good-bin window — the Mantid AlphaCalc convention, kept for
cross-checks against Mantid workflows and older analyses.
When to use this. Only on transverse-field data spanning many precession cycles, provided the decay-weighted mean polarisation is close to zero. The ratio of expected summed counts then approaches the efficiency ratio. On relaxing LF/ZF data a positive weighted mean polarisation produces an upward relative bias of approximately \(2a_0 \langle P_z \rangle\) at small amplitude, potentially much larger than the statistical uncertainty. The reported uncertainty does not include this bias.
Uncertainty when a background has already been subtracted. The ratio uses first-order propagation of the two independent detector-group sums:
Here \(S_F,S_B\) are corrected sums over the \(n\) selected bins, and the variance and covariance terms are defined in Uncertainty of a subtracted background. For a range mean the overlap term is computed from the actual raw-bin coefficients. A disjoint estimation window has \(\kappa_j=0\) on the signal window and retains the full \(n^2\sigma_\theta^2\) shared contribution.
The typed groups carry their independent variances and shared components:
corrected = corrected_grouped_counts(..., use_background=True)
estimate = estimate_alpha_detailed(
corrected.forward,
corrected.backward,
method="ratio",
first_good_bin=lo,
last_good_bin=hi,
)
The grouping dialog supplies these groups automatically. The uncertainty is propagated from the corrected counts and their recorded noise model; the background is not inferred from the corrected values alone.
Count-fit α
The grouping dialog’s default TF calibration fit already fits both count histograms with the full fitted-nuisance covariance. It measures alpha together with amplitude, backgrounds, and the other free model parameters, and can fit beta in the same operation. Its uncertainty remains conditional on the model and fixed preparation assumptions.
The Multi-Group Fit window also offers Forward + Backward (free α) for a specified count model. This is a separate modelling workflow; its result is not the quick Diamagnetic or Decay balance estimate. Agreement and precision depend on the observations, model, and fitted constraints, rather than on a universal ranking of these methods.
Once the fit converges, Promote α writes the fitted balance into the
grouping with alpha_method="count_fit" provenance and a reference-run
record, the same keys the dialog estimators write — so the reduction picks it
up on the next re-reduce. The promote is suggest-only and reports the
before/after value; see Count-domain fitting (α calibration & single histograms) for the count-fit
controls and the sibling t₀/background promotes.
Uncertainties
The diamagnetic and General quick estimates return alpha_error=None.
Their result display shows the alpha value alone. Repeating Estimate calibration
applies a new result explicitly; existing saved and manual values, including
historically recorded errors, remain intact until replaced.
The count ratio reports first-order propagation of the window sums, including recorded shared background components (see background uncertainty). This statistical uncertainty excludes polarisation bias, a mis-set t0, and unmodelled correction errors. It is not an exact sampling distribution for a ratio, particularly when the denominator is poorly determined.
The diamagnetic estimate additionally carries a small method systematic that no amount of statistics removes. Its stationary point is \(\alpha^4 = \sum F^3/(B(F+B)) \big/ \sum B^3/(F(F+B))\); expanded in the oscillation amplitude \(u = a_0 P_z(t)\), the estimating equation is \(\sum s\,u = \frac{\alpha - 1}{\alpha + 1}\sum s\,u^2 + O(u^3)\). The second-order term survives even for a perfectly zero-mean oscillation, so the estimate is displaced by roughly \(a_0^2 (\alpha-1)/(\alpha+1)\) — a few tenths of a percent at a typical 20 % asymmetry, growing quadratically with the asymmetry and reversing sign for \(\alpha < 1\). In resolved, many-cycle controls this bias need not track frequency. Finite windows, packing, and unresolved oscillations can introduce further dependence; a field-dependent estimate does not by itself locate an instrumental defect.
A standard error describes a local uncertainty scale. Interpreting estimate plus or minus one standard error as an interval uses an approximately normal sampling distribution, with an approximately 68.27 % reference probability, not an exact confidence guarantee [gum]. Boundary, weak-contrast, and skewed cases can violate that approximation. The standard deviation of repeated estimates and half the 15.865–84.135 percentile range are different summaries for a skewed distribution; neither automatically defines an interval for a particular observed calibration.
Compared with other programs
WiMDA 1.326 quick Diamagnetic and General controls compare displayed
point estimates, without establishing calibration uncertainty. Asymmetry’s quick
methods return point estimates without intervals.
On matched rounded synthetic beta = 1 histograms (16 ns bins, raw bins 4–498,
F/B channels 1/2, background and deadtime off, bunch one), its displayed TF
Diamagnetic alpha is 1.237, compared with 1.236610 in Asymmetry. General gives
1.250 on both TF and relaxing controls; Asymmetry gives 1.249827 and 1.250073.
Agreement is within 0.001 absolute alpha, the native search/display step.
These are point checks, not uncertainty coverage or acquired-data validation.
See Asymmetry in the μSR software landscape and the WiMDA overview/manual. Mantid AlphaCalc is the integral-ratio
counterpart; musrfit model fits use a different objective from these quick
estimates.
The closest raw-count counterpart is musrfit’s global histogram likelihood fit, not its type-2 asymmetry fit. Matched musrfit 1.12.1/ROOT 6.40.04 fixed/free-beta controls agree within 0.0001 absolute alpha/beta, after reciprocal alpha and fraction/percent conversion. The installed likelihood route’s differing error scale is documented in Asymmetry in the μSR software landscape; Asymmetry retains the independently checked conventional standard-error scale.
For applied deadtime correction, matched musrfit 1.12.1 type-0 weighted histogram controls agree within 0.0001 absolute alpha/beta only after matching the error convention. Its compared export rebuilds errors from corrected counts; Asymmetry retains measured/supplied variance, consistent with the compared Mantid muon correction. The WiMDA FileBG export is a different error control. These are distinct weights, not full propagation through deadtime correction. Conditions and limits are in Shared TF count calibration.
No matched native WiMDA pulse-calibration or beta-calibration result is established here. Mantid’s DoublePulseFit v1 uses supplied shifted functions and weights, a forward-model analogue rather than the same TF count estimator or covariance calculation. musrfit’s authored count models require reciprocal count-balance and amplitude/phase conventions to be matched. A post-arrival shifted-TF polarisation check does not establish onset integration or calibration uncertainty agreement.
Envelope selection is an Asymmetry convenience, not a shared default of these
programs. The musrfit THEORY documentation
defines simpleGss as
\(\exp[-(\sigma_{\mathrm{native}}t)^2/2]\), requiring
\(\sigma_{\mathrm{native}}=\sqrt{2}\sigma\); generExpo uses the
stretched envelope above. Matched musrfit 1.12.1/ROOT 6.40.04 component fits
on rounded undamped/exponential/Gaussian/stretched controls, with zero fixed
backgrounds, phases 0/180 degrees, 16 ns bins, raw bins 4–498, and fixed/free
beta, agree within 0.0001 absolute alpha/beta after these unit/orientation
conversions. These checks establish component point agreement, not automatic
selection equivalence or uncertainty coverage. No native WiMDA model fit or
Mantid numerical stretched-fit comparison is claimed.
On an owned rounded beta-one TF control, TF alpha is 1.249995 against generating 1.25, while the quick values above are about 1.237. The mean reduced asymmetry changes by about −0.53 percentage points on those same counts. These owned synthetic controls compare estimators, without establishing acquired physical alpha truth, a universal default, or uncertainty coverage.
References
PSI MuSRFit interface, exponential, Gaussian, and Stretch Cosine components.
Mantid StretchExpMuon documentation, stretched relaxation convention.
musrfit Single Histograms tutorial, global histogram calibration and shared geometric parameters.
S. Baker and R. D. Cousins, Nucl. Instrum. Methods Phys. Res. 221, 437 (1984), doi:10.1016/0167-5087(84)90016-4.
CERN Minuit2 manual, function normalisation, HESSE, and MINOS.
S. J. Blundell, R. De Renzi, T. Lancaster, and F. L. Pratt, Muon Spectroscopy: An Introduction (Oxford University Press, Oxford, 2022).
Pratt, Physica B 289–290, 710 (2000).
A. Yaouanc and P. Dalmas de Réotier, Muon Spin Rotation, Relaxation, and Resonance: Applications to Condensed Matter (Oxford University Press, Oxford, 2011).
Joint Committee for Guides in Metrology, Evaluation of measurement data — Guide to the expression of uncertainty in measurement, JCGM 100:2008, Secs. 5.1–5.2 and Annex G, doi:10.59161/JCGM100-2008E.
iminuit documentation, Hesse and Minos, curvature, profile intervals, and asymptotic coverage.
T. P. Morris, I. R. White, and M. J. Crowther, Stat. Med. 38, 2074 (2019), doi:10.1002/sim.8086.
N. J. Higham, Accuracy and Stability of Numerical Algorithms, 2nd ed. (SIAM, Philadelphia, 2002), Sec. 3.1.
Stored calibration meaning
A TF result applied through the core grouping-profile API retains its request, effective model and fitted constraints, native support, correction assumptions, and full covariance in the project. Alpha and beta share a canonical fit record. A usable alpha-only fit with unavailable or unreliable covariance retains alpha without an error. Loading uses stored coefficients even when the calibrant file is absent; it does not fit again. Manual policies and recorded historical quick errors remain authored values, without inferred TF or HESSE provenance. See Project files for the record and conditional uncertainty contract.
Explicit workflow and CLI calibration
Scripts can choose calibration count packing independently of science reduction
through CalibrationOptions.count_packing:
from asymmetry import load
from asymmetry.core.workflow import (
CalibrationOptions, ReductionSettings, calibrate_run, reduce_run,
)
source = load("calibration.nxs")
science_settings = ReductionSettings(rebin=2, t_min=0.5, t_max=5.0)
calibration = calibrate_run(
source, science_settings,
CalibrationOptions(
method="tf_calibration_fit", fit_beta=True,
count_packing=4, period=1,
),
)
# Apply the captured joint coefficients to a separate science run.
from dataclasses import replace
science = load("science.nxs")
reduced = reduce_run(science.run, replace(science_settings, alpha=calibration.record))
The factor must be a positive integer; booleans and non-integral values are
rejected. None (the default) preserves the source profile’s fixed bunching
factor. An explicit factor replaces that factor, with one requesting native
bins; it does not multiply source binning. TF count fitting uses fixed packing,
including when the source has a nonuniform display-binning mode.
ReductionSettings.rebin controls only science reduction and does not compose
with calibration packing. The same option is supported by calibrate_source.
Quick methods, including automatic ratio, reject explicit count_packing and
retain their native-window estimators.
Counts are summed from the selected acquired period’s inclusive good-bin window
before fitting. Incomplete trailing groups are dropped. Times are the mean of
the contributing native centres; t_min, t_max, and exclude select
these packed centres. Correction preflight and fitted-background treatment are
unchanged. The captured domains record the actual native windows and times,
and alpha and beta retain their joint covariance. Different packing can change
a nonlinear fit; compare fitted values and covariance only on identical
observations. Saved results load as captured, without refitting.
The Scripting and AI-agent workflow alpha command and --alpha-from accept
--calibration-method tf_calibration_fit for the shared TF operation.
Omitting options in calibrate_run selects this fresh explicit default;
passing CalibrationOptions() deliberately retains automatic ratio.
--fit-beta enables joint alpha/beta; omission fixes beta at one.
--calibration-pulse-separation US supplies the fixed TF separation;
omission means Off.
--calibration-envelope constrains the requested model, while omission
selects the minimum finite summed cost from all four usable candidates.
Explicit diamagnetic, general, and ratio requests use the same
core estimators as scripts. No-option CLI and survey calculations retain
the distinct per-run integral-ratio policy.
An applied TF result carries both coefficients and the complete canonical record into saved workflow settings. Errors are derived from its full nuisance covariance, conditional on the selected model and supported observations; no model-selection or reduced-signal covariance is added. Quick methods retain no added uncertainty; ratio retains first-order propagation. Missing/unreliable errors and fixed-beta errors are absent. Requested/applied corrections, native support, timing, and acquired source period remain in the record. Explicit quick workflow settings also retain the shared typed result and its method, source period, correction outcomes, and timing/window context. A mapped quick source retains its contributor recipe and selected mapped-set ordinal separately from an acquired-period identity. Asymmetry also checks that calibration has identified source-period histograms; a cached curve or an unidentified multi-period parent cannot supply another period’s counts. TF sources must name an acquired period rather than a nontrivial mapped sum, so a saved ordinal does not misidentify its observations. Routing equivalence establishes the same calculation across entry points; it does not extend the reference comparisons or physical-accuracy claims above.
Run arithmetic and TF calibration
TF calibration requires an original acquisition with its own count model. A co-added or signed run cannot supply one surrogate deadtime/exposure model for its retained acquisitions. Calibrate a source run and apply the resulting shared alpha/beta to the combination. Quick corrected-count preparation and ordinary asymmetry reduction retain each source’s own correction facts.
Matched musrfit 1.12.1/ROOT 6.40.04 global-histogram likelihood controls on rounded double-pulse counts agree within 0.0001 absolute alpha/beta for beta fixed at one and free beta. The comparison uses 16 ns bins, raw bins 13–498, zero fixed backgrounds, fixed lifetime, a shared free phase (native degrees with a 180-degree backward offset), and reciprocal native count balance. The native post-arrival damped-cosine representation absorbs the supplied source into its amplitude, phase, and normalisation. This checks point estimates after both births; it does not test native onset, bin integration, or error equivalence. Independent count and full-nuisance information controls provide the separate scientific targets.