Conventions and implementation notes

This page records the conventions Asymmetry follows, so that a number read off a fit, a plot, or an exported file can be interpreted unambiguously.

Units

Unless a page states otherwise, Asymmetry uses these units throughout the interface, the fitted parameters, and the exported data:

Quantity

Unit

Used for

Time

μs

histogram bins, fit ranges, lifetimes

Frequency

MHz

precession and oscillation frequencies

Magnetic field

Gauss (G)

applied and internal fields

Distance

Å

muon–nucleus distances in dipolar models

Relaxation rate

μs⁻¹

relaxation rates and field-distribution widths

Phase

radians

oscillation phases

The muon gyromagnetic ratio is taken as \(\gamma_\mu / 2\pi = 135.539\) MHz/T.

Physical constants

The physical constants API gives values, units, uncertainties, and sources. Exact defining values follow the 2019 SI; magnetic constants follow CODATA 2018, lifetimes follow PDG 2024, the fluorine-19 ratio follows Stone’s recommended 2019 nuclear moment, and the vacuum muonium hyperfine starting value follows Liu et al. (1999). Derived SI constants use the defining values directly. This fixed reference set keeps calculations independent of the SciPy version installed.

The fluorine ratio is calculated from the recommended nuclear moment and CODATA 2018 nuclear magneton using \(\gamma_F/(2\pi)=2\mu_F/h\) for spin \(I=1/2\). Its standard uncertainty is given in the API alongside the other measured constants. The pion lifetime is rounded to three decimal places in μs, and the proton gyromagnetic ratio is truncated to the stated precision.

Gaussian widths

The width \(\Delta=\gamma_\mu B_c\) is an angular-frequency width (μs⁻¹), where \(B_c\) is the standard deviation of one Cartesian component of an isotropic, zero-mean Gaussian field. Its total vector second moment is \(\langle|\mathbf B|^2\rangle=3B_c^2\). A transverse-field Gaussian frequency distribution and the early-time zero-field polarisation use different mappings to the Gaussian component:

Model

Width convention and relevant limit

Gaussian

\(e^{-\sigma^2t^2}\). Transverse-field envelope: \(\sigma=\gamma_\mu B_c/\sqrt{2}\); zero-field early-time match: \(\sigma=\gamma_\mu B_c\).

StaticGKT_ZF

\(\Delta=\gamma_\mu B_c\); starts as \(1-\Delta^2t^2\) and includes the static dip and \(1/3\) tail.

LongitudinalFieldKT

The same per-component \(\Delta\); its zero-field limit is StaticGKT_ZF.

DynamicGaussianKT

The same per-component \(\Delta\); vanishing fluctuation rate recovers the static KT response.

Abragam

Static transverse-field limit \(e^{-\Delta^2t^2/2}\); Gaussian at \(\sigma=\Delta/\sqrt{2}\).

Keren

At zero applied field and vanishing fluctuation rate, \(e^{-\Delta^2t^2}\); Gaussian at \(\sigma=\Delta\). This limit matches the early-time KT curvature, not its full static tail.

Temperature-dependent SC_*

Width parameters inherit the convention of the input trend; normalised \(\rho_s(T)\) is unchanged by constant width rescaling.

SC_Brandt_* and σ ↔ λ helpers

Second-moment width \(\sigma_2=\gamma_\mu B_\mathrm{rms}\) for \(e^{-\sigma_2^2t^2/2}\). Helpers require width= to select \(\sigma_2\) or \(\sigma_G=\sigma_2/\sqrt{2}\).

VortexLattice and VortexLatticePowder

The field distribution is calibrated to the Brandt second moment; the time signal is its characteristic function, without a Gaussian-width substitution. See Gaussian width convention.

Known Gaussian-component trend sources require an explicit sqrt(2)*x conversion before a Brandt field fit; ordinary temperature laws inherit the input convention. Source-unknown tables remain unknown and usable. See Gaussian widths at second-moment consumers for the request check and historical-data behaviour.

The Gaussian and zero-field KT functions first differ at fourth order: \(G_{\mathrm{KT}}(t)-e^{-\Delta^2t^2}=-\Delta^4t^4/12+O(t^6)\). See Gaussian and StaticGKT_ZF for applicability.

The asymmetry convention

The asymmetry of a forward group \(F(t)\) and a backward group \(B(t)\) is

\[A(t) = \frac{F(t) - \alpha B(t)}{\beta F(t) + \alpha B(t)},\]

with the calibration constant \(\alpha\) applied to the backward group and the optional intrinsic-asymmetry balance \(\beta = A_{0,b}/A_{0,f}\) (default 1, giving the familiar \((F - \alpha B)/(F + \alpha B)\)) applied to the forward group in the denominator — the musrfit asymmetry-fit (fit type 2) correction pair, set in the Grouping window’s Corrections column. \(\beta\) is entered as a fixed scalar or measured from a weak-TF calibration run’s precession fit; see Beta calibration. This convention is used consistently across the interface, the loaders, the grouping tools, and the fitting inputs. Some other programs place \(\alpha\) on the forward group instead. In musrfit type 2, \(\alpha_{\mathrm{musrfit}}=1/\alpha\); \(\beta\) is numerically identical after this conversion. See Asymmetry values, coordinates, and errors for the distinction between corrected curves and raw fitting coordinates. Count-to-ratio primitives return fractions; datasets and time-domain models use percent. Convert errors by the same factor; see Asymmetry units across the API. Signed corrected counts or general \(\beta\) can give estimates outside \([-1,1]\); that range is not a universal validity condition. The standard count-based F/B path applies enabled detector deadtime correction before alignment and grouping, then enabled group background subtraction. Counts are binned before asymmetry is formed. The operation order and calibration dependencies are described in Count reduction and transformed signals.

Errors

For fixed \(\alpha,\beta\), Asymmetry uses first-order propagation through \(A=(F-\alpha B)/D\), where \(D=\beta F+\alpha B\). For independent forward/backward groups with retained count variances \(V_F,V_B\),

\[ \begin{align}\begin{aligned}\frac{\partial A}{\partial F}=\frac{\alpha(1+\beta)B}{D^2},\qquad \frac{\partial A}{\partial B}=-\frac{\alpha(1+\beta)F}{D^2},\\\operatorname{var}(A)\simeq \frac{\alpha^2(1+\beta)^2(B^2V_F+F^2V_B)}{D^4}.\end{aligned}\end{align} \]

This retains the covariance between numerator and denominator. For raw Poisson counts, \(V_F=F,V_B=B\); at unity balances it reduces to \(\operatorname{var}(A)\simeq(1-A^2)/(F+B)\). For example, 6000 forward and 4000 backward counts give 20 % asymmetry with a standard error of 0.979795897 percentage points. This is a local approximation, not an exact finite-count variance or confidence interval; sparse counts and cancellation can make the Gaussian approximation poor. The uncertainty framework is the first-order law in JCGM 100:2008, sections 5.1–5.2.

Corrected count means are not new Poisson observations. Corrections retain measured or supplied variances; count merging includes shared-background and estimation-window overlap terms as described in Uncertainty of a subtracted background. Ordinary Gaussian fits use marginal point errors, not the full between-bin covariance of those corrections.

Calibration conditioning

Ordinary reduced errors condition on the chosen \(\alpha,\beta\). Available calibration errors and covariance remain in the calibration record; they are not added independently to each reduced point or propagated as a full reduced-bin/run covariance into the ordinary fit. A common calibration shifts many observations together. Reusing the same counts for calibration also introduces count–calibration covariance. Fitting calibration coefficients within a count model is a separate treatment; see Alpha calibration and Beta calibration.

Undefined and degenerate bins

For a zero denominator the count-to-ratio display returns a fallback value of zero and error of one fraction (100 percentage points). A defined ratio with zero first-order variance also receives that display error; raw one-sided Poisson counts are an example. These software values are not measured zero asymmetries or calibrated uncertainties.

Asymmetry also checks the mathematical usability of known histogram reductions before assigning display fallbacks. Gaussian fits omit undefined ratios and exactly zero propagated-variance observations, reporting used and omitted counts with the reasons undefined ratio and zero variance. The objective, degrees of freedom, information criteria, and residuals use the same selected observations within the requested fit window. Empty or insufficient usable support produces an explicit fit failure, without rejecting the file. Empty support raises FitInputError; insufficient support returns an unsuccessful fit result so a wizard can still assess simpler candidates.

Full grids and contributing counts remain available for counts-first merging and spectral operations. G+R usability is classified after count pooling, so an individually undefined ratio can contribute to a usable pooled result. G−R requires defined constituent ratios; a defined zero-variance term may contribute to a final difference with positive variance. No new cutoff, error floor, positivity gate, automatic packing, or likelihood switch is applied. Custom, rotated, and legacy curves without verified histogram classification keep strict Gaussian input validation; bare arrays do not acquire classification from sentinel values.

A corrected zero group count can retain positive variance and a usable error. For raw \(F=5,B=10\) with a fixed forward background of 10, the corrected counts are \(-5,10\) with variances \(5,10\), giving \(A=-3\) and \(\sigma_A=\sqrt{4.8}\) in fractions. Finite small denominators are retained, and values are not clipped to \([-1,1]\). Neither \(A=0\) nor an error of 100 percentage points alone diagnoses an unusable observation. See Count-domain fitting (α calibration & single histograms) for supported count-fitting alternatives.

Fit functions

A fit component evaluates a normalised polarisation or relaxation shape scaled by an amplitude, and a fittable model is assembled by combining components with arithmetic and fraction groups. Component notation follows Blundell et al. (2022), and each function cites the original literature for its form. The full catalogue, with the naming and parameter conventions, is Fit functions.

Where the behaviour lives

The analysis engine is pure Python and free of any interface code, so every convention above is exercised identically from the GUI and from a script. The relevant packages are asymmetry.core.transform (grouping, asymmetry, deadtime, background), asymmetry.core.fitting (models and engines), asymmetry.core.fourier (frequency-domain tools), and asymmetry.core.io (loaders). The API reference is API reference.

References

  • R. S. Hayano, Y. J. Uemura, J. Imazato, N. Nishida, T. Yamazaki, and R. Kubo, Phys. Rev. B 20, 850 (1979).

  • A. Abragam, The Principles of Nuclear Magnetism (Clarendon Press, Oxford, 1961).

    1. Keren, Phys. Rev. B 50, 10039 (1994).