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
Ascales its term and a constant baselinebaselineadds to the model, so both appear to first order asmodel = 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); anf_<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_nameswhose (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).
Nonemeans “derive from role names viadefault_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_Lconversion 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 * widththe longitudinal-field Kubo-Toyabe functions fall back to their exact zero-field form (see_FIELD_DECOUPLING_RATIO), so the objective is exactly flat inB_Lthere: a fit seeded inside this window has no gradient to follow. Callers that must leaveB_Lfree — the fit wizard’s unknown-field case — seed it clear of the returned threshold.width_per_usis the model’s local-field width in µs⁻¹ (Deltafor the Gaussian shapes,a_Lfor 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
Deltawith an applied longitudinal decoupling fieldB_L. AsB_Lis 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_Lin Gauss, converted to Tesla internally). The returned asymmetry is \(A(t) = A_0\,G_z(t) + baseline\). ForB_L = 0it reduces exactly to the zero-field Gaussian Kubo-Toyabe function (static_gkt_zf()); for largeB_Lit 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
omega0andDelta.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_Lis 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 fieldB_L(Gauss), via the closed-form spectral density ofasymmetry.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 allGamma t— no asymptotic branch switch is needed (WiMDA switches forms atGamma t = 20).Gammais used as|Gamma|; WiMDA’s mirrored2 - Gbranch for negative rates is an unphysical fitting convenience and is omitted here.References
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 piin 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
pa Gaussian of meanDeltaand standard deviationw_rel * Delta(w_relis 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’sGau 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 inw_relandw_rel = 0reduces exactly and continuously to the static (LF) Kubo-Toyabe.Note: WiMDA’s
rel widthparameter enters as weightexp(-(i/7)^2)overDelta(1 + w i/7), i.e. a Gaussian of fractional standard deviationw/sqrt(2);w_relhere 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 ratenu(MHz), with optional longitudinal fieldB_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 ratenu(MHz), with optional longitudinal fieldB_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 andG_dis 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 at4 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 energyE.Linearises in
(1/T, log₁₀ k)(the guide’s exact form); the slope is−E/(ln10·R).Eis returned inenergy_unit—"kJ/mol"(default) or"J/mol". Point errorsk_errorsare 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
λ_Mupast the truncation degeneracy.The series is fitted simultaneously (one shared muonium amplitude
A_Muand, by default, one shared phase) whileλ_Muand the diamagnetic background are estimated per run. The slow members pin the sharedA_Mu; that pinned value then forcesλ_Mufor the fast members whose Mu signal decayed before the first good bin — which a free per-run fit cannot do (setshare_amplitude= Falseto reproduce that degenerate baseline).- Parameters:
datasets – 2 G Mu asymmetry datasets at one temperature, ordered by concentration (the result’s
lambda_muis 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
λ_MuwithA_Mufixed to a reference amplitude.The analytic limit of the shared fit: fixing
A_Muto a known muonium amplitude (reference_amplitude, e.g. the shared value fromfit_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_Muat, in percent (0–100) — the same scale asdataset.asymmetryand asshared_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.)