Models

Built-in μSR fit functions.

Each model is a callable f(t, **params) -> array plus metadata describing its parameters. Models are collected in the MODELS registry.

Scale

Every asymmetry-valued parameter of every model here — the amplitudes A0 / A and the additive baseline — is in percent (0–100), and so is the curve each model returns. That is the WiMDA-style convention asymmetry.core.data.dataset.MuonDataset.asymmetry uses, which is why the seeds in MODELS default A0 to 25 rather than 0.25, and why PARAM_INFO_REGISTRY gives A/A0/A_bg the unit string "%". Fitting these models against fraction-scale data (what asymmetry.core.transform.asymmetry.compute_asymmetry() and asymmetry.core.transform.rebin.binned_fb_asymmetry() return) converges to the wrong minimum and trips AsymmetryScaleWarning; scale the data with asymmetry.core.transform.units.to_percent() first. The polarization-shape functions that carry no amplitude (risch_kehr(), bessel_oscillation(), and the P(t) kernels in the muonium / muon-fluorine / nuclear-dipole modules) are unit-normalised and therefore scale-free. See “Asymmetry units across the API” in the documentation.

asymmetry.core.fitting.models.LINEAR_PARAM_ROLE_NAMES = frozenset({'A', 'A0', 'A_bg', 'BG', 'a_Dia', 'baseline', 'bg', 'c0', 'c1', 'c2', 'c3', 'c4', 'c5', 'c6'})

Groundwork for the deferred variable-projection (VarPro) follow-up. VarPro is not wired into a fit path yet (see the PR body: it is a constant-factor win once profiled locals already separate the per-dataset solves, and its marginal errors need a final full Hessian), so this metadata is presently consumed only by tests and the follow-up plan — but it is the generic, name-role marking the study asks for, kept here so the follow-up does not re-derive it.

Parameter role names that enter a μSR model linearly — amplitudes and additive constant backgrounds. These are roles, not component names: an amplitude A scales its term and a constant baseline baseline adds to the model, so both appear to first order as model = a·term + .... Variable projection (VarPro) solves such parameters by linear least-squares inside the objective instead of by Minuit. The set is deliberately generic (matched by name, never by which component a parameter belongs to); an f_<Component> fraction weight is not here because a normalised fraction group is not a free linear scale. VarPro always verifies affineness numerically at runtime and falls back to the nonlinear treatment when a flagged name is not actually affine in a given model, so this list only has to be a safe over-approximation of “usually linear”.

asymmetry.core.fitting.models.default_linear_params(param_names)[source]

Role-based linear-parameter guess for a model’s parameter list.

Returns the subset of param_names whose (index-stripped) base name is a known linear role (LINEAR_PARAM_ROLE_NAMES) — i.e. an amplitude or an additive constant background. This is only a candidate set: VarPro verifies affineness numerically before using it, so a false positive is corrected at runtime, never silently trusted.

class asymmetry.core.fitting.models.ModelDefinition(name, description, function, param_names, param_defaults, param_info, domain='time', linear_params=None)[source]

Descriptor for a built-in fit function.

name
description
function
param_names
param_defaults
param_info
domain = 'time'
linear_params = None

Names of parameters that enter the model linearly (amplitudes, constant backgrounds). None means “derive from role names via default_linear_params()”. Variable projection solves these by linear least-squares, but only after a numeric affineness check, so an entry here is a hint, not a guarantee.

resolved_linear_params()[source]

The linear-parameter set for this model (explicit or role-derived).

__init__(name, description, function, param_names, param_defaults, param_info, domain='time', linear_params=None)
asymmetry.core.fitting.models.LARMOR_RAD_PER_US_PER_GAUSS = 0.0851615456403013

Muon Larmor angular frequency per Gauss of applied field, in rad/µs — the omega0 = gamma_mu * B_L conversion every longitudinal-field line shape below performs, hoisted so callers can reason about the decoupling window without re-deriving it (≈ 0.0851 rad µs⁻¹ G⁻¹).

asymmetry.core.fitting.models.field_decoupling_threshold_gauss(width_per_us)[source]

Smallest |B_L| (Gauss) that still moves a Kubo-Toyabe line shape.

Below omega0 < 0.05 * width the longitudinal-field Kubo-Toyabe functions fall back to their exact zero-field form (see _FIELD_DECOUPLING_RATIO), so the objective is exactly flat in B_L there: a fit seeded inside this window has no gradient to follow. Callers that must leave B_L free — the fit wizard’s unknown-field case — seed it clear of the returned threshold.

width_per_us is the model’s local-field width in µs⁻¹ (Delta for the Gaussian shapes, a_L for the Lorentzian one).

asymmetry.core.fitting.models.exponential_relaxation(t, A0, Lambda, baseline=0.0)[source]

Simple exponential: A(t) = A0 exp(−Λt) + baseline.

asymmetry.core.fitting.models.gaussian_relaxation(t, A0, sigma, baseline=0.0)[source]

Gaussian envelope A0 exp(−σ²t²) + baseline.

For per-component angular-field width Delta, sigma = Delta matches the zero-field KT curvature; sigma = Delta/sqrt(2) gives its TF envelope.

asymmetry.core.fitting.models.oscillatory(t, A0, frequency, phase=0.0, Lambda=0.0, baseline=0.0)[source]

Damped oscillation: A0 cos(2πft + φ) exp(−Λt) + baseline.

asymmetry.core.fitting.models.stretched_exponential(t, A0, Lambda, beta=1.0, baseline=0.0)[source]

Stretched exponential: A0 exp(−(Λt)^β) + baseline.

asymmetry.core.fitting.models.static_gkt_zf(t, A0, Delta, baseline=0.0)[source]

Static Gaussian KT, with per-component angular-field width Delta.

GKT = A0 [1/3 + 2/3 (1−Δ²t²) exp(−Δ²t²/2)] + baseline. Its normalised short-time form is 1−Δ²t²+(5/12)Δ⁴t⁴+O(t⁶).

asymmetry.core.fitting.models.longitudinal_field_kubo_toyabe(t, A0, Delta, B_L, baseline=0.0)[source]

Static Gaussian Kubo-Toyabe relaxation in a longitudinal field.

The longitudinal-field depolarisation function for a muon in a static, isotropic Gaussian distribution of local fields of width Delta with an applied longitudinal decoupling field B_L. As B_L is swept through the decoupling crossover the polarisation recovers toward unity, which is the experimental signature of a static (rather than dynamic) local field.

\[G_z(t) = 1 - \frac{2\Delta^2}{\omega_0^2} \left[1 - e^{-\Delta^2 t^2/2}\cos(\omega_0 t)\right] + \frac{2\Delta^4}{\omega_0^3} \int_0^t e^{-\Delta^2\tau^2/2}\sin(\omega_0\tau)\,d\tau ,\]

with \(\omega_0 = \gamma_\mu B_L\) (B_L in Gauss, converted to Tesla internally). The returned asymmetry is \(A(t) = A_0\,G_z(t) + baseline\). For B_L = 0 it reduces exactly to the zero-field Gaussian Kubo-Toyabe function (static_gkt_zf()); for large B_L it tends to 1 (decoupling).

Parameters:
  • t (NDArray) – Time values in microseconds.

  • A0 (float) – Initial asymmetry amplitude at t = 0.

  • Delta (float) – Per-component angular-field width in us^-1: Delta = gamma_mu * B_c.

  • B_L (float) – Applied longitudinal magnetic field in Gauss.

  • baseline (float, optional) – Constant additive baseline.

Notes

The integral uses cumulative trapezoidal integration on a shared fine grid whose step is sized from omega0 and Delta.

References

R. S. Hayano, Y. J. Uemura, J. Imazato, N. Nishida, T. Yamazaki and R. Kubo, “Zero- and low-field spin relaxation studied by positive muons”, Phys. Rev. B 20, 850 (1979).

asymmetry.core.fitting.models.abragam(t, A0, Delta, nu, baseline=0.0)[source]

Abragam relaxation function (Abragam, Principles of Nuclear Magnetism, 1961).

G(t) = A0 exp[ -(Delta^2 / nu^2) (e^{-nu t} - 1 + nu t) ] + baseline

A transverse-field envelope with the Gaussian and motional-narrowing limits:

  • nu -> 0 : G -> A0 exp(-Delta^2 t^2 / 2) (Gaussian)

  • nu >> Delta : G -> A0 exp(-(Delta^2 / nu) t) (exponential)

This transverse-field convention follows Blundell et al., Muon Spectroscopy: An Introduction (OUP, 2022), eqn 5.52: Gaussian at sigma = Delta/sqrt(2).

Parameters:
  • t (NDArray) – Time values in microseconds.

  • A0 (float) – Initial asymmetry amplitude.

  • Delta (float) – Static Gaussian field-distribution width in us^-1.

  • nu (float) – Finite, non-negative field fluctuation (hop) rate in MHz (== us^-1). Zero gives the static Gaussian limit; negative/non-finite rates raise ValueError.

  • baseline (float, optional) – Constant baseline offset.

asymmetry.core.fitting.models.keren(t, A0, Delta, nu, B_L, baseline=0.0)[source]

Keren dynamic Gaussian relaxation in a longitudinal field (Keren, PRB 50, 10039 (1994)).

P(t) = A0 exp[-Gamma(t)] + baseline, with omega0 = gamma_mu * B_L and:

Gamma(t) = (2 Delta^2 / (omega0^2 + nu^2)^2) * [
    (omega0^2 + nu^2) nu t + (omega0^2 - nu^2) (1 - e^{-nu t} cos(omega0 t))
    - 2 nu omega0 e^{-nu t} sin(omega0 t) ]

At B_L = 0 the exponent is twice the transverse-field Abragam exponent. As nu -> 0 the limit is exp(-Delta^2 t^2), matching Gaussian at sigma = Delta and the early-time zero-field KT curvature; the full KT model supplies its tail. Numerical evaluation uses the entire phi2 function, including zero rate and field. Physical validity is perturbative (Delta/nu < 1, or early times); numerical support at nu=0 does not supply the static KT tail. See Eq. (4) of Keren (1994); the exponent here denotes his Gamma(t)*t.

Parameters:
  • t (NDArray) – Time values in microseconds.

  • A0 (float) – Initial asymmetry amplitude.

  • Delta (float) – Static Gaussian field-distribution width in us^-1.

  • nu (float) – Finite, non-negative fluctuation rate in MHz (== us^-1); invalid rates raise ValueError.

  • B_L (float) – Longitudinal magnetic field in Gauss (omega0 = gamma_mu * B_L).

  • baseline (float, optional) – Constant baseline offset.

asymmetry.core.fitting.models.static_lorentzian_kt_zf(t, A0, a_L, baseline=0.0)[source]

Static Lorentzian Kubo-Toyabe, zero field (Uemura et al. PRB 31, 546 (1985)).

G(t) = A0 [1/3 + 2/3 (1 - a t) exp(-a t)] + baseline

For a dilute / Lorentzian distribution of local fields (e.g. spin glasses), where a_L is the half-width of the field distribution expressed as a rate in us^-1.

asymmetry.core.fitting.models.static_lorentzian_kt_lf(t, A0, a_L, B_L, baseline=0.0)[source]

Static Lorentzian Kubo-Toyabe in a longitudinal field (computed numerically).

Blundell, De Renzi, Lancaster & Pratt, Muon Spectroscopy (OUP, 2022), sec 5.3, note that the Kubo-Toyabe function “becomes modified in applied field … [and] must be computed numerically”. This evaluates the stochastic field average (eqn 5.3) over an isotropic Lorentzian local-field distribution of half-width a_L (us^-1) with applied longitudinal field B_L (Gauss), via the closed-form spectral density of asymmetry.core.fitting.models._lorentzian_lf_uniform.

  • B_L -> 0 : reduces to the zero-field Lorentzian KT (eqn 5.47), 1/3 + 2/3 (1 - a_L t) e^{-a_L t}.

  • B_L -> inf : decoupling, G -> 1.

The line shape is evaluated by the closed-form spectral density of asymmetry.core.fitting.models._lorentzian_lf_uniform (accurate to ~1e-6 at any field) on a grid that resolves the Larmor oscillation, linearly interpolated onto the requested times, and cached per (a_L, B_L, tmax); very small fields (omega0 < 0.05 a_L) are treated as zero field, where the eqn 5.47 form is exact.

asymmetry.core.fitting.models.risch_kehr(t, Gamma)[source]

Risch-Kehr relaxation for spin transport by 1D diffusion.

G(t) = e^{Gamma t} erfc(sqrt(Gamma t))

Relaxation of the muon (or muonium) polarisation when the depolarising agent diffuses in one dimension (e.g. a polaron on a conducting-polymer chain): the return probability of a 1D random walk gives a (pi Gamma t)^{-1/2} long-time tail instead of an exponential.

Evaluated as erfcx(sqrt(Gamma t)) (the scaled complementary error function), which is numerically stable for all Gamma t — no asymptotic branch switch is needed (WiMDA switches forms at Gamma t = 20). Gamma is used as |Gamma|; WiMDA’s mirrored 2 - G branch for negative rates is an unphysical fitting convenience and is omitted here.

References

  1. Risch and K. W. Kehr, Phys. Rev. B 46, 5246 (1992).

asymmetry.core.fitting.models.bessel_oscillation(t, frequency, phase=0.0)[source]

Zeroth-order Bessel oscillation J0(2 pi f t + phase).

The polarisation produced by an incommensurate (spin-density-wave) field distribution: an Overhauser distribution of local fields between -B_1 and +B_1 gives P(t) = J0(gamma_mu B_1 t) (Blundell, De Renzi, Lancaster & Pratt, Muon Spectroscopy, OUP 2022, eqn 6.47), which at late times looks like a damped cosine with a -45 degree phase shift (eqn 6.48). Here the field-distribution edge is parameterised as a frequency f = gamma_mu B_1 / 2 pi in MHz.

asymmetry.core.fitting.models.gaussian_broadened_kt(t, Delta, B_L, w_rel)[source]

Static Gaussian Kubo-Toyabe averaged over a Gaussian distribution of Delta.

G(t) = integral dDelta’ p(Delta’) G_KT(t; Delta’, B_L), with p a Gaussian of mean Delta and standard deviation w_rel * Delta (w_rel is the fractional width). Models disordered hosts where a single Kubo-Toyabe width is too sharp — the distribution of static widths fills in the dip and softens the 1/3-tail recovery (cf. the Gaussian-broadened Gaussian of Noakes & Kalvius, Phys. Rev. B 56, 2352 (1997); WiMDA’s Gau broad KT).

Evaluated by Gauss-Hermite quadrature (21 nodes) over the Delta distribution, with negative quadrature widths reflected to |Delta'| (as in WiMDA). The quadrature is evaluated directly at the requested times (vectorised over the nodes, with the Hayano longitudinal-field integral computed once on a shared fine grid for all nodes), so the model is smooth in w_rel and w_rel = 0 reduces exactly and continuously to the static (LF) Kubo-Toyabe.

Note: WiMDA’s rel width parameter enters as weight exp(-(i/7)^2) over Delta(1 + w i/7), i.e. a Gaussian of fractional standard deviation w/sqrt(2); w_rel here is the fractional standard deviation (w_rel = w_WiMDA / sqrt(2)).

asymmetry.core.fitting.models.dynamic_gaussian_kt(t, A0, Delta, nu, B_L=0.0, baseline=0.0)[source]

Dynamic Gaussian Kubo-Toyabe (strong collision; Hayano et al. PRB 20, 850 (1979)).

Strong-collision generalisation of the static Gaussian KT: a Gaussian local field of width Delta (us^-1) fluctuating at rate nu (MHz), with optional longitudinal field B_L (Gauss).

  • nu -> 0 : recovers the static (LF) Gaussian Kubo-Toyabe.

  • nu >> Delta : motional narrowing, G -> exp(-2 Delta^2 t / nu) (B_L = 0).

  • B_L -> inf : decoupling, G -> 1.

asymmetry.core.fitting.models.dynamic_lorentzian_kt(t, A0, a_L, nu, B_L=0.0, baseline=0.0)[source]

Dynamic Lorentzian Kubo-Toyabe (strong collision; Uemura et al. PRB 31, 546 (1985)).

Strong-collision generalisation of the static Lorentzian KT for a dilute / Lorentzian local-field distribution of half-width a_L (us^-1) fluctuating at rate nu (MHz), with optional longitudinal field B_L (Gauss).

In zero field (omega0 < 0.05 a_L) the solution is exact and closed form: the static function is a three-state linear system, so the strong-collision integral equation reduces to a 3x3 eigenproblem and G_d is a sum of three exponentials (asymmetry.core.fitting.models._strong_collision_modes), valid at every rate with no grid, cache or fast-fluctuation switch. In a longitudinal field the static line shape has no finite realisation, and the Volterra equation is solved on a grid (asymmetry.core.fitting.models._dynamic_kt_grid).

  • nu -> 0 : recovers the static Lorentzian KT (zero-field analytic eqn 5.47; longitudinal field computed numerically per Blundell et al. 2022).

  • nu >> a_L : the relaxation rate saturates at 4 a_L / 3 (a Lorentzian distribution has no second moment to narrow).

  • B_L -> inf : decoupling, G -> 1.

Models

asymmetry.core.fitting.models.MODELS

Registry of built-in time-domain models.

Mu kinetics

asymmetry.core.fitting.mu_kinetics.fit_arrhenius(temperatures, k_values, k_errors=None, *, energy_unit='kJ/mol')[source]

Fit log₁₀ k_Mu = log₁₀ A − E/(2.3·R·T) → activation energy E.

Linearises in (1/T, log₁₀ k) (the guide’s exact form); the slope is −E/(ln10·R). E is returned in energy_unit — "kJ/mol" (default) or "J/mol". Point errors k_errors are propagated as σ(log₁₀ k) = σ_k/(k·ln10).

asymmetry.core.fitting.mu_kinetics.fit_mu_relaxation_series(datasets, *, f_mu=2.78, share_amplitude=True, share_phase=True, t_min=None, t_max=None, initial=None, minos=False)[source]

Fit a 2 G Mu series, recovering per-run λ_Mu past the truncation degeneracy.

The series is fitted simultaneously (one shared muonium amplitude A_Mu and, by default, one shared phase) while λ_Mu and the diamagnetic background are estimated per run. The slow members pin the shared A_Mu; that pinned value then forces λ_Mu for the fast members whose Mu signal decayed before the first good bin — which a free per-run fit cannot do (set share_amplitude= False to reproduce that degenerate baseline).

Parameters:
  • datasets – 2 G Mu asymmetry datasets at one temperature, ordered by concentration (the result’s lambda_mu is returned in the same order).

  • f_mu – Mu precession frequency (MHz), held fixed (γ_Mu·B ≈ 2.78 MHz at 2 G).

  • share_amplitude, share_phase – Whether A_Mu / the phase are shared globals (the default) or estimated per run.

  • t_min, t_max – Optional fit-window clip applied to every dataset (default: each dataset’s good-bin window).

  • initial – Optional seed overrides for any of A_1, phase, Lambda_2, A_3, Lambda_3.

  • minos – Run MINOS for asymmetric errors on top of HESSE.

asymmetry.core.fitting.mu_kinetics.mu_relaxation_from_amplitude(dataset, *, reference_amplitude, f_mu=2.78, phase=None, t_min=None, t_max=None)[source]

Single-run λ_Mu with A_Mu fixed to a reference amplitude.

The analytic limit of the shared fit: fixing A_Mu to a known muonium amplitude (reference_amplitude, e.g. the shared value from fit_mu_relaxation_series()) breaks the per-run degeneracy directly, so a single truncated run yields λ_Mu. Returns (λ_Mu, σ_λ) in µs⁻¹. Use as an independent cross-check of the series fit, or as a manual fallback when a full series is unavailable but the Mu amplitude is known.

Parameters:

reference_amplitude – Amplitude to pin A_Mu at, in percent (0–100) — the same scale as dataset.asymmetry and as shared_amplitude, which is what this normally receives. (Earlier wording called it the muonium “fraction”, which reads as the 0–1 scale; the code has always treated it as percent.)

MuRelaxationSeriesResult.shared_amplitude