Fitting engine

Asymmetry fits μSR data with an iminuit-based engine that exposes the same machinery through the GUI fit panels and through the Python API. The minimiser is MINUIT [1]: the engine minimises the least-squares cost \(\chi^2 = \sum_i [(A_i - f(t_i))/\sigma_i]^2\) with migrad, and takes its symmetric parameter uncertainties from the HESSE step that migrad runs on convergence. This chapter documents the engine itself — the workflow, the parameter and results objects, the statistics, the global-fit API, and the conventions that apply across every model. The physical-model catalogue is split out into dedicated chapters: see Composite models for the expression grammar that drives the GUI builder, Fit wizard and Global fit wizard for the guided model-selection workflows, and the per-function chapters for the depolarisation forms themselves (Relaxation, Oscillation, Muonium, Kubo–Toyabe, Nuclear dipolar, Frequency domain, Field-dependent transport models (DiffusionLF / BallisticLF), Superconducting penetration depth models).

When fitting through the GUI, the plot panel’s current bunch factor is applied before the dataset is handed to the fitter. If the plot is showing a rebinned dataset, the next GUI fit will use that rebinned dataset. To fit the full-resolution data and only simplify the view afterwards, run the fit with Bunch = 1 and then increase the bunch factor; the fit curve remains overlaid on the plot.

Fixed double-pulse prediction

For a two-pulse source, the populations have different muon ages at one observation time. In Edit… → Build Fit Function, set Time response to Fixed double pulse and supply Pulse separation in µs. Off is the default. The tooltip describes “Two instantaneous pulses with equal incident strengths and muon-survival weighting.” The supplied pulse midpoint is the origin on the resolved observation clock; acquired time zero and good bounds are unchanged. Separation is fixed, with no added fit parameter. Result labels and exports include the consumed separation, midpoint, and weighting convention.

For supplied separation \(d\), births are \(b_j=\pm d/2\) and live ages are \(u_j=t-b_j\geq0\), including age zero. With equal incident strengths, the normalised prediction is

\[P_{\mathrm{eff}}(t)= \frac{\sum_{j:u_j\geq0}\tfrac12 e^{-u_j/\tau_\mu}P(u_j)} {\sum_{j:u_j\geq0}\tfrac12 e^{-u_j/\tau_\mu}}.\]

In symbolic previews, \(\mathcal{D}_d\) denotes this normalised operator. The complete source expression is evaluated at each age. A product of an envelope and an oscillation is transformed together, and an additive constant remains once. After both arrivals the normalised weights are proportional to \(e^{b_j/\tau_\mu}\). There is no extra common lifetime decay in the asymmetry. For ideal calibrated counts \(F=C\sum w_j(1+P_j)\) and \(B=C\sum w_j(1-\beta P_j)/\alpha\), the ratio \((F-\alpha B)/(\beta F+\alpha B)\) gives this prediction for general fixed \(\beta\). Ordinary fitting does not estimate calibration.

from asymmetry.core.fitting import CompositeModel, TimeResponse

model = CompositeModel(
    ["Exponential", "Oscillatory", "Constant"],
    operators=["*", "+"],
    time_response=TimeResponse("double_delta", separation_us=0.324),
)
# Pass model.function and the usual parameter set to FitEngine.
restored = CompositeModel.from_dict(model.to_dict())

TimeResponse.compose(source) also wraps an explicit fractional or percent callable without changing its scale. Composite models, previews, residuals, wizard candidates, batch/global/joint fits, and restored recipes use the same response. Bare component curves retain their component-display semantics; leaves of a product need not sum to the complete transformed product.

Assumptions and limitations

This double-delta approximation has no finite source width or detector-resolution model. It retains ordinary point evaluation at the actual retained times, including merged-bin centres. A ratio of integrated counts across an arrival is a different observation and can differ substantially; a good late-time fit does not validate finite-pulse onset accuracy. Choose the fit window with this approximation in mind. Fixed separation zero gives the single-source prediction on nonnegative times; Off preserves the source model’s existing domain.

Asymmetry also checks that active separation is finite and nonnegative and that requested model points have a live source population. Points before the first arrival receive a model/window diagnosis; inactive negative ages are never evaluated. Dense overlays start at the first supported birth if a literal window edge extends beyond the retained observation centres; this clips only display extrapolation and never drops requested fit observations. These checks concern the requested fit, with no file-format or facility restriction. Selected errors, masks, and objectives stay with the observations. Parameter errors remain conditional on supplied pulse settings and fixed calibration. The count-based Diagnostic… pull test is unavailable for positive pulse separation because its generator does not model the two-birth count population. Off and the zero-separation limit retain that diagnostic; ordinary fitting and conditional fit errors remain available. This time response applies to time-asymmetry source models; it does not transform Fourier, field-scan, trend, or rotated display curves. Lab-frame fitting with frequency offsets retains its lab-frame source prediction.

Compared with other programs

The WiMDA author’s overview lists simulation, without establishing a native match to Asymmetry’s double-pulse fitting or count generator here. In Mantid 6.16 development, DoublePulseFit v1 uses supplied shifted functions and weights. Matching the late normalised model requires the same origin and survival weights; arbitrary equal observed weights or onset extrapolation need not match. An authored shifted-TF composition in musrfit 1.12.1 provides a post-arrival model check, without establishing a generic pulse switch, onset agreement, or equal uncertainties. See Asymmetry in the μSR software landscape for the qualified reference evidence.

A recorded supplied-error constant control compares Mantid 6.16.1 and musrfit 1.12.1 (708f777b, ROOT 6.40.04) on all three values 2, 4, 7 with errors 1, 2, 1. Independent normal equations give mean \(40/9\), standard error \(2/3\), and chi-square \(113/9\) with two degrees of freedom. Both use absolute supplied errors without residual rescaling. The recorded statuses, fit selections, rounded-output tolerances, and optional fresh execution are qualified in Asymmetry in the μSR software landscape. This scalar objective check does not certify nonlinear uncertainty or interval coverage.

Basic workflow

The minimal end-to-end fit is a model from the MODELS registry, a ParameterSet of initial values and bounds, and a FitEngine call:

from asymmetry.core.fitting.engine import FitEngine
from asymmetry.core.fitting.models import MODELS
from asymmetry.core.fitting.parameters import Parameter, ParameterSet
from asymmetry.core.io import load

dataset = load("data.nxs")

model = MODELS["ExponentialRelaxation"]
params = ParameterSet([
    Parameter("A0", value=25.0, min=0.0),
    Parameter("Lambda", value=0.5, min=0.0),
    Parameter("baseline", value=0.0),
])

result = FitEngine().fit(dataset, model.function, params)

print(f"χ²ᵣ = {result.reduced_chi_squared:.3f}")
for p in result.parameters:
    err = result.uncertainties.get(p.name, 0.0)
    print(f"  {p.name} = {p.value:.6f} ± {err:.6f}")

For anything richer than a single-component model — multiple amplitudes, shared baselines across detector groups, multiplicative envelopes, fraction-constrained additive groups — use the composite-model path in Composite models. The MODELS registry is intentionally short and contains only the standalone variants with explicit baselines; composite expressions are the canonical way to assemble realistic muSR models.

The A0 seed above is 25, not 0.25, because a loaded dataset’s asymmetry and every built-in model are on the percent scale, while the low-level reduction primitives return the dimensionless fraction. Crossing the two parks a fit at the wrong minimum, so Asymmetry units across the API maps which scale each part of the API speaks and how the engine’s advisory guard catches the crossing.

Fitting arrays without a dataset

FitEngine.fit takes a MuonDataset, which is the right front door for a run’s own reduced curve. A custom detector pairing, a background-corrected export, or any other \((t, A, \sigma)\) triple that is not a dataset’s default reduction goes through FitEngine.fit_arrays instead:

from asymmetry.core.transform import compute_asymmetry, to_percent

asym, err = compute_asymmetry(forward_counts, backward_counts, alpha)

result = FitEngine().fit_arrays(
    time, to_percent(asym), to_percent(err), model.function, params,
    t_min=0.1, t_max=8.0,
)

fit_arrays accepts the fitting options fit does — t_min / t_max, method, minos, cost_factory, migrad_kwargs, frequency_offsets, error_oversampling, cancel_callback — and runs the same internal engine, so the two paths cannot drift: fitting a dataset’s own arrays through fit_arrays returns a result identical to fit(dataset, …) down to the last digit of every uncertainty.

Two differences are worth knowing. The arrays are expected in percent (fraction × 100), matching the models’ seeds, and nothing rescales them — the reduction primitives return a fraction, hence the to_percent() above; see Asymmetry units across the API. And because bare arrays carry no run metadata, the advisory fixed-frequency guard — which compares a pinned frequency to \(\gamma_\mu B\) from the run’s field — cannot run on this path, although the percent-versus-fraction scale guard does.

Input requirements

Single, array, global and joint Gaussian fits use the same observation boundary. It selects the requested fit window and requires non-empty, equally sized, one-dimensional arrays. Times and values must be finite; stated uncertainties must be finite and strictly positive. These Gaussian objectives treat the stated errors as independent and known; a shared background contributes its marginal variance, without a full correlated likelihood. Ordinary reduced errors condition on the selected alpha/beta; see Calibration conditioning. Known histogram reductions first omit undefined ratios and exactly zero propagated-variance observations; see Undefined and degenerate bins. Invalid points raise FitInputError (a ValueError) before minimization; no replacement weight is inserted.

Likelihood inputs

Input

Requirements

GaussianObservations

Finite times and values; finite positive stated standard deviations.

PoissonCounts

Finite times; finite, non-negative integer counts with CountSource.RAW.

The error identifies the run, zero-based point index and time. A zero error at point 3 of run 7 produces: “run 7, point 3 (t = 0.300 µs): uncertainty 0 is not finite and positive; Gaussian fits need finite positive errors”. fit_arrays(..., run_number=7) supplies this context for bare arrays.

FitResult.observation_report records used, omitted, undefined_ratio, and zero_variance counts for a known histogram reduction. The shared JSON summary exposes these under observation_report; generic and historical results without recorded classification use None. The result’s residual_time pairs each residual with the exact fitted timestamp. The fit results card and CLI print, for example, Gaussian observations: used 2, omitted 3 (undefined ratio 1, zero variance 2). Valid signed values and corrected zeros with positive variance remain eligible. Raw count-domain fits and TF alpha/beta calibration retain their own contracts.

fit(dataset, ...) and fit_arrays are Gaussian entry points. For a Poisson fit, construct PoissonCounts and pass it to FitEngine.fit_observations. These values own read-only array copies, so caller buffer changes cannot alter a fit’s checked observations. Every in-memory FitResult records its objective as Objective.GAUSSIAN or Objective.POISSON. See Count-domain fitting (α calibration & single histograms) for count eligibility.

Parameter control

Bounds, fixing, and initial values are set on individual Parameter objects:

from asymmetry.core.fitting.parameters import Parameter

p = Parameter(name="Lambda", value=0.5, min=0.0, max=10.0)

# Hold a parameter constant during the fit
p_fixed = Parameter(name="A0", value=25.0, fixed=True)

# Or toggle later
p_fixed.fixed = True

In the GUI parameter table, the Fix checkbox does the same job; bounds are entered directly in the Min and Max columns. On the Single and Batch tabs those two columns are shown or hidden together by the Bounds chip above the table (on by default on the Single tab, off by default on the Batch tab; each column is narrow, holding -inf, 1e6 or the ±∞ glyphs), and the ↗ button beside the rail pops the whole table — every column, whatever the chips show — into its own window. Parameter metadata — symbol, unit, default lower bound, physical description — comes from PARAM_INFO_REGISTRY; symbols and units displayed in the GUI, in fit reports, and in exported GLE figures all derive from this registry, so they are guaranteed to be consistent with what the model function actually expects.

Fit statistics

The FitResult exposes the standard goodness-of-fit numbers:

print(f"χ²  = {result.chi_squared:.4f}")
print(f"χ²ᵣ = {result.reduced_chi_squared:.4f}")
print(f"converged: {result.success}")
print(f"message:   {result.message}")

A reduced \(\chi^2\) near 1 is the usual target. Values much greater than 1 indicate that either the model is missing physics, the parameter errors on the input asymmetry are underestimated, or both. Values much less than 1 generally mean the input errors are overestimated. Neither case is automatically fatal — in the first, the next move is usually to add or substitute a component motivated by the physics; in the second, the parameter uncertainties on the fitted values will be inflated correspondingly and should be re-derived against a calibrated error model.

Advisory warnings (result.warnings)

Before it minimises, the engine runs two advisory guards that flag the setup traps most likely to produce a converged-but-wrong fit, and carries their messages on result.warnings (they are also emitted through the Python warnings system). The guards never raise and never change the outcome:

  • AsymmetryScaleWarning — the data and the seeded model sit on different asymmetry scales (the percent-vs-fraction mix-up; a loaded MuonDataset.asymmetry is on the percent scale).

  • FixedFrequencyFieldMismatchWarning — a precession frequency held fixed more than ~2 % from \(\gamma_\mu B\) implied by the run’s field; the misfit then leaks into the damping term and inflates the fitted Gaussian sigma (the vortex-state transverse-field trap).

The GUI fit panel surfaces these beneath the converged summary (deduplicated for a batch/global fit). The science and the fix for each are in the cookbook — see the transverse-field frequency entry and the asymmetry-scale entry.

A stuck χ² ≈ 200? Free the background amplitude (TF data)

A frequent cause of a huge, stubborn reduced \(\chi^2\) (often \(\chi^2_r \approx 200\)) on muSR transverse-field data is a background amplitude pinned at a non-physical lower bound. The constant background term A_bg (and the standalone baseline) defaults to a zero lower bound, but for TF data the fitted background is routinely negative — commonly around \(-20\%\) of the full asymmetry — because of detector-pair imbalance and the asymmetry baseline convention. Clamped at zero, the minimiser cannot reach the true minimum and the fit parks at a large \(\chi^2\).

The fix is to initialise the background unbounded (or with an explicitly negative lower bound) so it can go negative:

from asymmetry.core.fitting.parameters import Parameter

# WRONG for TF data: a zero floor traps A_bg → χ²ᵣ stuck near 200
bad = Parameter("A_bg", value=0.0, min=0.0)

# RIGHT: leave it unbounded so the background can settle negative
bg = Parameter("A_bg", value=0.0)              # min=-inf, max=+inf by default
# ...or pin a generous negative floor if you want some guard rails:
bg = Parameter("A_bg", value=-0.05, min=-0.5, max=0.5)

In the GUI parameter table, clear the min cell for the background row (or set it negative) before fitting TF data. If a TF fit converges with a glued-to-zero background and a \(\chi^2_r\) in the hundreds, this bound is the first thing to check.

Parameter values and Hessian uncertainties come from result.parameters and result.uncertainties:

for p in result.parameters:
    err = result.uncertainties.get(p.name, 0.0)
    print(f"{p.name}: {p.value:.6f} ± {err:.6f}")

Hessian (HESSE) errors assume the local quadratic approximation around the minimum is a good description of the likelihood, i.e. that the parameter uncertainties are symmetric. For well-conditioned fits this holds. For ill-conditioned problems — strongly correlated parameters, fits near a bound, multi-modal likelihoods — the interval is skewed and the symmetric error misrepresents it; use MINUIT’s asymmetric MINOS intervals [1] (Asymmetric (MINOS) errors) or the re-simulation estimate below (Monte Carlo error estimation).

Residuals

Inspecting the residual time series is the most reliable check that the model is structurally appropriate:

import matplotlib.pyplot as plt

fit_values = model.function(
    dataset.time, **{p.name: p.value for p in result.parameters}
)
residuals = (dataset.asymmetry - fit_values) / dataset.error

plt.plot(dataset.time, residuals, "o", alpha=0.6)
plt.axhline(0, color="k", linestyle="--")
plt.xlabel("Time (μs)")
plt.ylabel("Normalised residual (σ)")

A good fit produces residuals that scatter randomly around zero with most points within \(\pm 2\sigma\) and no systematic trend over time. Persistent structure — a slow oscillation, a turn-up at long times, a visible knee — almost always points at a missing component rather than at noise.

Restricting the fit range

The t_min and t_max keyword arguments to FitEngine.fit restrict which time bins enter the cost function:

result = engine.fit(
    dataset, model.function, params, t_min=0.1, t_max=5.0,
)

The two common reasons to clip the range are (a) early-time bins contaminated by deadtime or finite-pulse-width effects, and (b) late-time bins where the signal has decayed into the background and adds only noise to the fit. The same range is honoured by the fit wizard and the global-fit workflow.

Global fitting

The global-fit interface accepts a list of datasets, the model function, and explicit lists of parameter names to treat as global (shared across all runs) or local (independent per run):

from asymmetry.core.fitting.engine import FitEngine
from asymmetry.core.fitting.models import MODELS
from asymmetry.core.fitting.parameters import Parameter, ParameterSet
from asymmetry.core.io import load

datasets = [load(f"run_{i}.nxs") for i in range(1, 4)]
model = MODELS["ExponentialRelaxation"]
engine = FitEngine()

initial_params = {}
for ds in datasets:
    ps = ParameterSet([
        Parameter("A0", value=25.0, min=0.0),
        Parameter("Lambda", value=0.5, min=0.0),
        Parameter("baseline", value=0.0),
    ])
    initial_params[ds.run_number] = ps

results_dict, global_result = engine.global_fit(
    datasets=datasets,
    model_fn=model.function,
    global_params=["A0"],
    local_params=["Lambda", "baseline"],
    initial_params=initial_params,
    t_min=0.1,
    t_max=10.0,
)

for p in global_result:
    print(f"[global] {p.name} = {p.value:.6f}")
for run_number, run_result in results_dict.items():
    print(f"run {run_number}: χ²ᵣ = {run_result.reduced_chi_squared:.3f}")

The GUI Batch tab automates the same workflow: select multiple datasets, mark parameters as Global (shared across runs) or Local (per-run) in the parameter table, and click Run series. A fit where at least one parameter is Global is a global fit; otherwise each run is fitted independently but the results are collected into one trendable series. The classification table’s Min and Max columns — the same pair the Single tab shows — are hidden until the Bounds rail chip above the table is switched on; the ↗ button pops the table out with every column shown. Results land in the Fit Parameters panel where they can be browsed, exported to TSV, or passed into the parameter-trending fit framework documented in Parameter trending.

The same engine is also used in the Frequency workspace for displayed Fourier spectra. In that mode the Fit dock switches labels from A(t) to S(ν), uses MHz fit ranges, and offers peak/background components documented in Frequency-domain fitting.

The Global fit wizard automates model selection on ordered field or temperature series; use that wizard before constructing a hand-built global fit if you do not yet know which composite model the data prefer.

A Global parameter is still scoped to this series — one model, one run of fits. When two series with different models need to share a quantity (an initial asymmetry, a background, an instrumental phase) across a phase transition or similar boundary, see Joint fits, which composes several already-recorded series into one coupled fit with its own Shared scope on top of Global and Local.

Monte Carlo error estimation

For parameters whose Hessian uncertainties are not trustworthy — heavy correlations, fits sitting near a bound, multi-modal likelihoods — re-simulating the data and refitting gives an empirical distribution. The snippet below draws each replica by adding Gaussian noise at the per-bin error to the fitted data (a parametric Monte Carlo), so the spread it reports is only as good as that error model: it inherits the Gaussian-error assumption and will not capture non-Gaussian tails, and with a small replica count the estimated width itself carries appreciable scatter (raise n_bootstrap and seed the generator for a reproducible number). It is an approximation to the error, not an exact interval — for the definitive error-bar check re-simulate at matched statistics and inspect the pull distribution (Conditional simulation: the pull distribution).

import numpy as np
from asymmetry.core.data import MuonDataset

rng = np.random.default_rng(0)
n_bootstrap = 500
bootstrap_results = []
for _ in range(n_bootstrap):
    resampled = dataset.asymmetry + rng.standard_normal(len(dataset.asymmetry)) * dataset.error
    boot_dataset = MuonDataset(
        time=dataset.time, asymmetry=resampled, error=dataset.error,
    )
    bootstrap_results.append(engine.fit(boot_dataset, model.function, params))

lambda_dist = np.array([
    next(p.value for p in r.parameters if p.name == "Lambda")
    for r in bootstrap_results
])
print(f"Lambda = {lambda_dist.mean():.4f} ± {lambda_dist.std():.4f}")

For a single parameter whose likelihood is skewed, the engine’s own asymmetric MINOS interval (FitEngine.fit(..., minos=True), reported in result.minos_errors) is usually the cheaper and more direct check; see Asymmetric (MINOS) errors. The definitive test of whether the reported uncertainties are calibrated is the pull diagnostic (Conditional simulation: the pull distribution).

Custom models

Any callable with signature f(t, **params) -> array is a valid model function:

import numpy as np

def my_model(t, amplitude, tau, frequency):
    return amplitude * np.exp(-t / tau) * np.sin(2 * np.pi * frequency * t)

params = ParameterSet([
    Parameter("amplitude", value=20.0),
    Parameter("tau", value=1.0, min=0.0),
    Parameter("frequency", value=5.0, min=0.0),
])

result = engine.fit(dataset, my_model, params)

Custom callables do not get the symbol/unit metadata that registered components carry, so the GUI parameter table will show raw names and no units. For anything used more than once, a proper component or ModelDefinition registration is preferable.

References

[1] F. James and M. Roos, Comput. Phys. Commun. 10, 343 (1975).

[2] F. L. Pratt, Physica B 289–290, 710 (2000), WiMDA.

[3] Mantid, DoublePulseFit v1, 6.16 development documentation.

See also

Execution compatibility of saved fits

Asymmetry also checks the captured scientific-computation revision alongside the actual fitted observations and objective before verified saved-fit ranking, automatic replacement, or current residuals. Old or unknown executions remain available as historical parameter values and models. Refitting records a new execution; saving or exporting a historical result preserves its revision. This compatibility check changes neither the objective nor the statistical meaning of its uncertainties. See Project files for saved history and Scripting and AI-agent workflow for persistent work-directory recomputation.

Source context and retained fits

Automatic replacement of a saved single fit or series requires matching recorded source context as well as observations and execution. Changed acquisition bytes can produce identical sampled arrays; a new fit then retains the original result separately. Historical curves remain inspectable, while current residuals and verified rankings require matching input context. Unknown legacy input provenance does not prevent an explicit new fit. Project source decisions are described in Project files.

Series with changed, unavailable, or unknown source context report Historical source contents are different, unavailable, or unverified; results remain available. This is a currentness qualifier, not a prohibition on new fitting. A joint refit with changed member source context records fresh member series and a fresh joint record; the original members and joint summary remain intact.