Integral scan mode (avoided-level-crossing field scans)

The Integral scan mode turns a set of runs taken at different fields (or temperatures) into a single field scan: one integral-asymmetry value per run, plotted against the swept variable. It is the workflow for avoided level crossing (ALC), repolarisation / decoupling, and quadrupolar level-crossing resonance (QLCR) measurements, where a resonance appears as a dip or step in the asymmetry as the field is stepped through the crossing. The technique is often called an ALC scan, and the mode is labelled Integral scan (ALC) in the interface.

Unlike the time-domain fitting workflows, the Integral scan mode does not fit a model to each spectrum. It reduces every run to one number — the asymmetry integrated over a time window — and then lets you fit a baseline and resonance peaks to the resulting scan. Ordinary and RF scans use the same count-integral estimator. Mantid’s documented asymmetry-versus-log workflow is a related scan analysis; matched observations, windows, and errors must be established separately.

Every integral reduction uses the independent F/B pair contract in Detector Grouping and Layout: effective sides must be nonempty and disjoint after exclusions. An overlapping saved request remains editable with its fixed correction settings and raw histograms, but cannot produce an integral value.

Run-level integral preparation shares detector deadtime correction, whole-bin alignment, and grouping with the standard Count reduction and transformed signals. Enabled background correction uses the same prepared observations as the time-domain reduction, including an explicitly resolved reference-run background. A verified histogram observation retains the effective pair, timing, α/β, correction settings, and reference used to produce it. Asymmetry also checks count-replay provenance for a new integral request: attaching a Run to an arbitrary curve does not establish it. Missing or incomplete File deadtimes leave the entire deadtime operation unapplied with a warning and permit integral preparation. An unavailable or failed correction prevents an integral value rather than silently integrating unsubtracted counts; raw histograms and the grouping remain available for repair.

Deadtime correction uses only the selected F/B detectors and native samples inside the requested integral window, together with any active background estimator samples. Unused detectors, prefixes, and gaps cannot block the inverse or suppress File correction. Required poles remain errors, and missing required File coefficients keep the whole-operation warned skip. The acquired histograms, original timing, and measured/supplied variance remain unchanged.

The integral-asymmetry observable

For each run, the forward and backward counts are summed over the integration window \([t_\mathrm{min}, t_\mathrm{max}]\) and combined into a single asymmetry value:

\[A = \frac{\sum F - \alpha \sum B}{\beta \sum F + \alpha \sum B},\]

where the sums run over the good bins inside the window, \(F\) and \(B\) are the corrected forward and backward grouped counts, and \(\alpha\) and \(\beta\) are the chosen detector balances. There is no division by window length. Errors propagate the prepared count variances, conditional on the chosen calibration; this is not a calibration-uncertainty calculation.

The API and CLI also offer method="differential" / --method differential: the explicit equal-time-bin mean of pointwise asymmetries. It is a distinct observable, not dA/dB. For example, red counts F=[6000, 10], B=[4000, 90] and green counts F=[6000, 90], B=[4000, 10], with α=β=1, give a count-integral G−R of 0.015841584158415828 fraction, while the explicit time-bin mean is 0.8. Native-bin counts determine the integral independently of display bunching.

Counting uncertainty and usable observations

Count integration includes every selected corrected count before classifying its aggregate ratio. For example, F=[0, 10] and B=[10, 0] give A=0 with standard error 0.223606797749979, although neither native ratio has usable first-order variance. A zero aggregate denominator is undefined. A defined ratio with zero first-order variance remains inspectable, but carries no Gaussian fit weight; no finite placeholder uncertainty is assigned. Signed corrected counts with supplied variance remain supported.

The explicit time-bin mean uses only defined ratios with positive retained variance. For G−R, the pointwise contrast is classified on the common time support before averaging: both ratios must be defined, but a defined zero-variance constituent can contribute to a usable contrast. Omissions have exclusive undefined-ratio and zero-variance counts. No surviving observations makes that requested mean unavailable. Curve-only means use supplied validity and counting responses when retained; otherwise they honour the supplied finite-error contract and omit explicit zero errors. They do not infer unknown correlations or count-correction provenance.

At fixed α and β, the gradients of a count ratio are

\[\frac{\partial A}{\partial F} = \frac{\alpha(1+\beta)B}{(\beta F+\alpha B)^2},\qquad \frac{\partial A}{\partial B} = -\frac{\alpha(1+\beta)F}{(\beta F+\alpha B)^2}.\]

These responses act after count summation for an integral and before averaging for a mean. Retained responses to the same acquired bins are combined before variance contraction, including shared reference subtraction and background estimation-window overlap. Equal common-reference responses cancel in G−R; unequal responses retain their remaining uncertainty. Errors remain conditional on calibration and the selected correction settings. This does not supply a general joint covariance or calibration-uncertainty model.

Asymmetry also checks the actual Gaussian fit selection before seeding or weighting. It omits unusable scalar observations and reports Gaussian observations: used N, omitted M (undefined ratio U, zero variance Z). Known nonzero covariance between selected scan points prevents only the requested independent-error fit. The explanation is Independent-error scan fit unavailable: selected points reuse counting observations with nonzero covariance. Inspect/export the scan or select an independent subset. The scan, export, individual reductions, and independent subsets remain available. Unknown source identity retains the recorded assumption Unknown acquisition identity is assumed distinct. Distinct acquired periods, equal counts, and matching run numbers alone do not establish reuse.

The scan provenance shows N without Gaussian uncertainty and N omitted observations when applicable, with exclusive counts in its tooltip. It shows Shared counting observations: independent-error fit unavailable for a dependent selection. These facts survive axis changes, exclusions, and project reload. Stored historical results keep their values and estimator identity without inferred mathematical status or source sharing.

Each value is plotted against the run’s swept variable to form the scan. A resonance shifts the time-averaged asymmetry, so it shows up directly as a feature in \(A\) versus field. The dA/dB view (see below) plots the field-derivative of the scan — WiMDA’s differential ALC — which sharpens a resonance into a peak–trough signature.

Entering the Integral scan representation

ALC mode is the Integral scan representation, a button in the Time domain cluster of the main toolbar (alongside F-B asymmetry and Individual groups). Click it to enter — no separate toggle. It is always available; the two-or-more-runs requirement is checked when you build the scan, not when you select the representation.

When it is active:

  • the central plot area shows the field scan itself (the ALC curve), with a slim integration-window strip beneath it (see the integration window below);

  • the Fit dock shows the Integral scan (ALC) build panel — the Integration window spinboxes, the RF resonance option, and the Build Scan button;

  • the Parameters dock shows the scan’s analysis controls — the Baseline, Peaks, and RF resonance sections.

The central workspace displays the scan. In scan mode you no longer interact with the per-run time spectra — they are only integrated — so the scan occupies the centre and the analysis controls stay to the side.

Switching to another representation keeps your scan and its analysis; they reappear when you return to Integral scan.

The ALC workflow

Step 1 — Build the scan

  1. Load and multi-select the runs. Load the field-scan runs, then select them all in the Data Browser: click the first row and Shift-click the last (the scan is built from the current selection, exactly like a batch fit). The Data Browser resolves the B (G) column from each run’s field; that column becomes the scan’s field axis.

  2. Select the Integral scan representation. Click Integral scan in the toolbar’s Time-domain cluster. The central area switches to the scan view (empty until you build), and the Fit dock shows the build panel.

  3. Set the integration window. The window is the time-spectrum fit range. Drag the shaded window on the integration-window strip below the scan, or type precise \(t_\mathrm{min}\) and \(t_\mathrm{max}\) values (in μs) into the spinboxes in the Integration window group of the build panel. The strip, the spinboxes, and the F-B time plot all stay in sync.

  4. Press Build Scan.

Each selected run is integrated over the window to one point, and the scan appears in the central plot area. A provenance line beneath the scan reports how many runs contribute and, when relevant, how many were dropped and why (see which runs are in the scan). Runs missing the chosen x-axis log (for example, a run with no recorded field on a field scan) are dropped and named there. Re-pressing Build Scan after changing the window rebuilds the scan in place — it does not accumulate copies.

Build Scan opens an Integral scan progress dialog with Cancel. Count preparation runs on a worker while the interface remains responsive. Cancellation, failure, or a changed request retains the displayed result; a superseded request cannot publish a stale scan. Baseline, peak, and RF fitting retain their own execution behaviour.

New scans save their estimator and requested time window with the computed results. Stored scans without evidenced estimator identity remain labelled Stored scan (estimator unspecified) and retain their values. Curve-only historical inputs support the explicit G−R time-bin mean through the API. A new count-integral or pooled G+R request needs verified count replay; its reload explanation applies to that operation and does not prevent loading or inspecting the input or its saved results.

The integration window (time strip)

Because the scan now occupies the centre, the draggable integration window has its own home: a slim, collapsible time-spectrum strip directly beneath the scan. It previews the current run’s time spectrum with the integration window shaded, and you drag the window edges on it exactly as you would on the full time plot. The strip, the build panel’s spinboxes, and the F-B asymmetry time plot are three views of the same window and always agree. Collapse the strip with the arrow in its header when you want the scan to fill the space.

As a worked example, the TCNQ ALC scan (31 runs at 350 K, stepped over 2000–5000 G) with an integration window of roughly 0.2–8 μs resolves a clean D1 dip at \(B_0 \approx 3100\) G. See ALC field scan in TCNQ.

Step 2 — Choose the x-axis and (optionally) the differential view

Above the scan plot:

  • the x-axis selector chooses what the scan is plotted against — B (G) (field, the usual ALC axis), T (K) (temperature), or Run;

  • the dA/dB checkbox switches the plot to the field-derivative of the scan (relabelled dA/dT or dA/d(run) to match the chosen axis). This is the differential ALC view. Each point is a midpoint slope between adjacent included observations; duplicate or decreasing coordinates are skipped;

  • the Data table… button opens the per-point values (run, x, asymmetry, error) in a separate window, keeping the plot itself uncluttered;

  • the X / Y range fields with Auto X / Auto Y toggles set the axis limits, following the same per-axis Auto/Held contract as the other representations (see Axis limits). With Auto on, the axis frames the data and the fields track it; typing a limit pins that axis (and turns its Auto off). Building a scan or changing the x-axis / derivative view reframes both axes.

For adjacent observations the derivative is \(d_i=(A_{i+1}-A_i)/(x_{i+1}-x_i)\) at \((x_i+x_{i+1})/2\). Only positive spacing is used. The API’s optional max_gap skips larger steps; there is no automatic gap threshold, interpolation, or padding. Values and errors retain the input asymmetry scale per axis unit: fractional/G, fractional/K, or fractional/run in an ordinary core scan, and %/G, %/K, or %/run in the GUI. Independent input errors give marginal error \(\sqrt{\sigma_i^2+\sigma_{i+1}^2}/\Delta x\). A known dependent input pair retains its derivative value with unavailable uncertainty (NaN in the API, null in JSON); its covariance cannot be replaced by independent quadrature. Undefined source ratios remain undefined. A derivative is a transformed observation, with no new histogram-ratio status. The original scan retains the scalar reports and positional source-sharing facts.

Adjacent differences share their middle observation, even for independent original points. For equally spaced inputs with error 0.01 and unit spacing, neighbour covariance is −0.0001. The mean of four such differences has error 0.003535533906, whereas diagonal quadrature gives 0.007071067812. Asymmetry also checks derivative identity at its shared fit-input boundary: fit the original scan. Derivatives support display/export; marginal errors do not specify an independent likelihood. This support limit applies to API and restored workflow scans, not only GUI controls, and is not a restriction attributed to other programs. Derivative identity survives selection and workflow serialization. Legacy payloads without the flag retain original-observable identity.

Changing the axis or derivative view clears baseline, peaks, and RF overlays. Baseline and RF fitting require the original view; peak fitting requires its baseline. The GUI explains Turn off dA/dB to fit a baseline on the scan. and Turn off dA/dB to fit the RF resonance.

Synthetic count-integral field scan shown as midpoint derivatives in percent per gauss, with the derivative view enabled and fit overlays cleared.

Derivative display of the synthetic scan; fit original observations.

Which runs are in the scan — excluding an outlier

Every selected run that can be integrated contributes one point. A run is dropped only if it cannot be reduced (no grouping), or — in RF mode — is not a two-period run. The provenance line beneath the scan makes this visible rather than log-only: it reads, for example, “29 runs in scan · 1 without B (G) · 1 dropped at build”, and its tooltip lists the dropped runs with the reason for each.

To drop a single bad point — a spurious run, an outlier that distorts the baseline — click it on the scan. The point turns grey and hollow, the provenance line gains a “… excluded by click” entry, and the run is skipped by the baseline, peak, and RF fits (which run only on the remaining points). Click the greyed point again to restore it. Exclusions are kept per run, so they survive a rebuild over the same selection and are saved with the project.

This click-to-exclude is available on the scan itself (the B/T/Run view). In the dA/dB differential view the points are pair-midpoints with no greyed marker to restore, so clicking there does not exclude — switch the derivative off, exclude the point, and switch back.

Step 3 — Fit a baseline

The Baseline section subtracts the non-resonant background so that only the resonance remains. The workflow mirrors Mantid’s two-step ALC analysis:

  • choose a baseline Model — Linear or Constant;

  • mark the non-resonant regions (the parts of the scan away from the resonance). Press + region to add a row, then either type the start/end values or drag the shaded region edges directly on the plot. Add as many regions as you need; − region removes the selected one;

  • press Fit baseline.

The fitted baseline is drawn over the scan (red line) and stored as the baseline-corrected curve used for peak fitting. Editing a region — by typing or by dragging an edge — marks the baseline stale and removes the overlay, so you always know when a re-fit is needed.

Step 4 — Fit the resonance peaks

The Peaks section fits one or more centred peaks to the baseline-corrected scan:

  • press + Gaussian or + Lorentzian to add a peak. Each peak row carries an initial B0 (centre), Width, and Amp (amplitude) guess; edit them in the table, or drag the peak-centre marker (the dashed line) on the plot to position \(B_0\). − peak removes the selected peak;

  • press Fit peaks.

The two shapes share the same parameters,

\[\mathrm{Gaussian:}\; f\,e^{-(B-B_0)^2 / 2B_\mathrm{wid}^2} \qquad \mathrm{Lorentzian:}\; \frac{f}{1 + \left((B-B_0)/B_\mathrm{wid}\right)^2},\]

so peaks of either shape can be mixed in one fit. The total fit (baseline plus all peaks) is overlaid on the scan, and the peaks table updates to the fitted values.

Reading off the results

Below the peaks table, a summary line reports, for each peak, the resonance field \(B_0\) with its uncertainty, the full width at half maximum, and the amplitude — for example:

Peak 1 (Gaussian): B₀ = 3104 ± 0.11 G, FWHM = 563.4 ± 0.21 G, amp = -8.96 ± 0.0038 %
Uncertainties include the fitted baseline.

The position, FWHM, and amplitude uncertainties include the fitted baseline through first-order covariance propagation. The baseline model and its fitting regions are held fixed; uncertainty in their choice is excluded. The regions must exclude resonance signal, since peak tails can bias the estimated baseline. For a Lorentzian, the remaining depth at a distance of \(k\) widths is \(1/(1+k^2)\) of its central depth.

The FWHM is derived from the fitted width per shape (\(\mathrm{FWHM} = 2\sqrt{2\ln 2}\,B_\mathrm{wid} \approx 2.355\,B_\mathrm{wid}\) for a Gaussian; \(2\,B_\mathrm{wid}\) for a Lorentzian).

Fitting a scan from the API: single and multiple resonances

The GUI peak fitter above fits centred Gaussian/Lorentzian peaks on a baseline-corrected scan. The same scan can also be fit programmatically with fit_scan_model(), which fits a model and its background to the raw scan in a single call. The model argument is flexible:

fit_scan_model(scan, model, *, parameters=None, initial=None,
               x_min=None, x_max=None, method="migrad")
  • model accepts a str, a list[str], or a ParameterCompositeModel — so it is not limited to one resonance. Several resonances plus a polynomial background can be fit simultaneously; fitting overlapping peaks one at a time is neither necessary nor reliable.

  • initial is an override dict ({name: value}) layered on the model’s defaults; parameters is a full ParameterSet. The two are mutually exclusive — pass one or the other, not both.

The integral-scan --baseline CLI workflow uses the same propagation. Its JSON fit payload records uncertainty_basis="baseline_propagated", the reported uncertainties and full covariance, and conditional_uncertainties from the fixed-baseline fit. Fits without baseline subtraction record uncertainty_basis="joint_fit"; their baseline and peaks, when included in the expression, are fitted together. The parameter table prints uncertainty basis: baseline_propagated or uncertainty basis: joint_fit. A stored result without this field prints uncertainty basis: unrecorded. CLI errors are scaled by \(\sqrt{\max(\chi^2_\mathrm{red},1)}\); the baseline-first reduced statistic uses the effective residual degrees of freedom.

For baseline-first inference in scripts, retain the baseline result and pass it to fit_scan_peaks():

from asymmetry.core.fitting import fit_scan_baseline, fit_scan_peaks

baseline = fit_scan_baseline(scan, [(0, 25), (75, 100)], model="Linear")
peaks = fit_scan_peaks(baseline, "GaussianLCR",
                       initial={"f": -0.02, "B0": 50, "Bwid": 4})
amplitude_error = peaks.uncertainties["f"]

baseline.corrected.error contains the marginal propagated standard uncertainties. Its points are correlated: the complete matrix is baseline.corrected_covariance. Fitting that curve with diagonal errors alone does not propagate the baseline correctly. peaks.fit retains the conditional Minuit result; peaks.covariance and peaks.uncertainties include the baseline. peaks.effective_dof is the expected residual sum of squares under the linearised model, used by peaks.reduced_chi_squared.

Baseline-first covariance in the API

Write the source covariance as \(\Sigma=\operatorname{diag}(\sigma_i^2)\). With baseline Jacobian \(X\), fitted covariance \(V_b\), region selection \(S\), and baseline weights \(W_S\), the correction is \(R=I-XV_bX_S^T W_S S\). The corrected covariance is \(C=R\Sigma R^T\). This includes correlation with observations used to estimate the baseline; overlap can reduce marginal uncertainties.

For peak Jacobian \(J\), weights \(W\), and \(L=(J^TWJ)^{-1}J^TW\), the reported covariance is \(V=V_c+L(C-\Sigma)L^T\), where \(V_c\) is the conditional Minuit covariance. This additive correction preserves Minuit’s covariance when the baseline is fixed. It is the linear two-stage estimating-equation correction [Murphy1985] [Stefanski2002]; nonlinear peak fits use first-order propagation. Rank-deficient peak Jacobians, missing fit covariances, or non-positive- semidefinite propagated covariances raise an explicit error.

Parameter-model fits apply a floor of half the median positive point error when constructing weights. Propagation uses those same weights, with the stated source errors in \(\Sigma\). When the floor is active, the conditional Minuit covariance is an approximation to sampling uncertainty.

The expected residual statistic is \(\operatorname{tr}(WM\Sigma M^T)\) with \(M=(I-JL)R\). It need not equal the number of points minus the number of peak parameters. The baseline model and regions are held fixed. The baseline must describe the signal across the peak and its fitting regions must exclude resonance signal; covariance propagation cannot remove bias from peak tails in those regions. Calibration uncertainty and uncertainty in baseline-model choice are excluded.

Single resonance:

from asymmetry.core.fitting import fit_scan_model

# scan is a FieldScan (e.g. built by the ALC mode "Build Scan" step,
# or constructed directly from per-run integral-asymmetry values).
result = fit_scan_model(scan, "LorentzianLCR")

Multiple resonances share a single fit. The component parameters are numbered across the expression (f_1/B0_1/Bwid_1 for the first peak, f_2/B0_2/Bwid_2 for the second, …) and the Polynomial background contributes c0 … c5:

from asymmetry.core.fitting import ParameterCompositeModel, fit_scan_model

# Two Lorentzians on a polynomial background, fit together:
pcm = ParameterCompositeModel.from_expression(
    "LorentzianLCR + LorentzianLCR + Polynomial"
)
print(pcm.param_names)
# ['f_1', 'B0_1', 'Bwid_1', 'f_2', 'B0_2', 'Bwid_2',
#  'c0', 'c1', 'c2', 'c3', 'c4', 'c5']

result = fit_scan_model(
    scan,
    "LorentzianLCR + LorentzianLCR + Polynomial",
    initial={"B0_1": 3000.0, "B0_2": 3300.0},
)

The motivating case is a multi-resonance ALC spectrum such as the corannulene-style four-resonance scan, which fits cleanly as one mixed Gaussian/Lorentzian model on a polynomial background:

"GaussianLCR + LorentzianLCR + LorentzianLCR + LorentzianLCR + Polynomial"

Because every resonance and the background share one minimisation, overlapping peaks are deconvolved correctly — which sequential single-peak fits cannot do. The component parameter names follow the composite-model scheme documented in Composite models; call .param_names (as above) before building an initial override or a ParameterSet so the names always match.

Differential (red/green) ALC: LorentzianLCRPair

An ALC scan is sometimes recorded as two interleaved periods — red and green — that sit at slightly different fields rather than as one period per run, and the resonance is fitted to the difference of the two (green − red), not to either period alone: a step in the raw scan that a single-period model would have to absorb into its background instead cancels between the periods, and a genuine resonance survives the subtraction as a derivative-like feature — the line at its true field, and a copy of it at the other period’s field, with the opposite sign. The line shape for this observable is LorentzianLCRPair:

\[y(B) = f \left[ \frac{1}{1 + \left((B - B_0)/B_\mathrm{wid}\right)^2} - \frac{1}{1 + \left((B - B_0 - \Delta B)/B_\mathrm{wid}\right)^2} \right],\]

The model uses dB = B_green − B_red in gauss for the G−R convention. Its two algebraic terms are centred at B0 and B0+dB; interpreting those centres requires the experiment’s definition of the scan coordinate. The fitted amplitude carries the sign of the contrast. A small step and a large amplitude can trade off in a sparsely sampled pair, so an independently known physical step can be held with the existing CLI input:

asymmetry integral-scan data --runs 1-20 --period green-red \
    --model 'LorentzianLCRPair + Linear' --fix dB=45

Here 45 G is an illustrative supplied experimental value, not a value inferred from the files. A documented red-minus-green step changes sign once before being supplied as dB. Raw Hall logs and their declared units remain metadata; a cross-run Hall/main-field regression is not a physical calibration.

A period contrast does not itself identify the switched quantity. Missing field-step metadata does not establish RF-on/off acquisition, and retained integral asymmetry does not determine geometry or invalidate a declared TF label. Choose a physical model from the experimental context. For a justified RF contrast with known frequency the existing choice is --model RFResonanceMuP --fix nu_RF=<MHz>. Loading, inspection and explicit model choices remain available without automatic geometry relabelling or a facility restriction.

References

      1. Kreitzman et al., Phys. Rev. Lett. 56, 181 (1986).

Building a scan from one period or run type

A field scan must not mix distinct measurement periods or run types recorded at the same field, or the resonance positions shift and the fitted hyperfine constants are biased. Two cases are common:

  • Period mode (RF-on / RF-off, light-on / light-off, ALC steps): a single file holds several periods, and the swept observable is one period — or the difference of two.

  • Interleaved calibration runs: a repolarisation or ALC scan often has reference runs (for example a 100 G α-calibration) repeated through the sweep; they sit at a different asymmetry level and pollute the scan.

build_field_scan() takes a filter predicate run -> bool for exactly this. It is called with each resolved run before reduction; runs for which it returns false are dropped and listed in scan.excluded (reason "excluded by filter") so nothing is silently lost. The default filter=None keeps every run — the historical behaviour.

To split a multi-period file into its periods first, select each period upstream with asymmetry.core.io.periods.select_period() (period extraction lives in io; the scan transform stays free of it).

RF-μSR resonance (Green − Red): GUI and API

RF-μSR resonance is the (Green − Red) integral-asymmetry observable of a muoniated radical (Green = RF-off, Red = RF-on, recorded as two periods of each run): a W-shaped double dip whose two resonance fields give the muon (\(A_\mu\)) and proton (\(A_p\)) hyperfine couplings from one field scan. It has first-class support on the integral-scan path:

  • In ALC mode, tick RF resonance (Green − Red) in the build panel before Build Scan. Each period’s corrected counts are integrated over the window, then the green ratio is reduced by the red ratio using the shared chosen calibration.

  • In the Parameters dock, open the RF resonance (A_µ, A_p) section, set ν_RF (the RF frequency, held fixed) and the A_µ₀ / A_p₀ starting guesses, and press Fit RF resonance. The fit uses the exact muon + electron + proton spin Hamiltonian (RFResonanceMuP) and reports \(A_\mu\) (mean dip position) and \(A_p\) (dip splitting) with uncertainties.

The same two steps from a script use build_rf_difference_scan() (the Green − Red scan builder) and fit_rf_resonance() (which seeds the amplitudes/widths/background from the data and holds ν_RF fixed) — worked example: the benzene scan, DEVA runs 56426–56462:

from asymmetry.core.io import load
from asymmetry.core.io.periods import build_rf_difference_scan
from asymmetry.core.fitting import fit_rf_resonance

combined = [load(f) for f in rf_files]  # 2-period (red/green) files
# Green − Red integral scan vs field; non-two-period runs land in `excluded`.
scan = build_rf_difference_scan(combined, order_key="field", t_min=0.0, t_max=1.0)
result = fit_rf_resonance(scan, nu_rf=218.5)  # A_µ₀/A_p₀ default to 515/124

The fit’s inferred couplings depend on the chosen time window, calibration, and acquisition conditions. An estimator-consistency check does not establish those quantities as experimental truth. Keep the within-run period contrast when that is the measured RF observable.

The lower-level route — reducing each period separately with select_period() and subtracting two build_field_scan results — provides the individual red and green values. Use build_rf_difference_scan for the combined observable with supported shared-reference propagation; marginal errors of separately stored scans cannot recover unknown covariance.

When the periods appear as separate runs or datasets in the series (rather than periods of one file), filter selects one directly — for example filter=lambda run: run.metadata.get("period_label") == "red". And to drop interleaved calibration runs from a repolarisation scan:

scan = build_field_scan(
    runs, order_key="field",
    filter=lambda run: run.run_number not in calibration_run_numbers,
)

Responsive fitting and Stop

Fit baseline, Fit peaks, and Fit RF resonance run the solve, model prediction, and any baseline-error propagation in a background task. The scan remains editable. An indeterminate progress bar shows Fitting baseline…, Fitting peaks…, or Fitting rf resonance…; peak and RF curve sampling shows Sampling fitted prediction…. Press Stop to request cooperative cancellation. The status becomes Stopping fit… until the current numerical unit returns, then Fit stopped.. A current failure shows Fit failed. and its diagnostic; a complete current success shows Fit complete..

A new fit request replaces the pending request and shows Stopping fit; replacement queued…. There is at most one running solve and one replacement waiting for its exit. Editing the relevant inputs, rebuilding the scan, or opening or clearing a project cancels affected work. Baseline edits also cancel dependent peaks; a peak keeps the exact baseline execution it used. Obsolete progress, errors, and results cannot replace a newer result. Only a complete applicable success updates fitted controls, overlays, project history, and the unsaved-changes indicator. A stopped or failed fit can be retried.

Cancellation is checked at solver model evaluations, RF seed detuning evaluations, seed/multi-start transitions, each finite-difference Jacobian sample, covariance stages, and prediction/capture boundaries. Individual model evaluations, array operations, matrix products, and native solves finish before the next check; there is no fixed millisecond response guarantee. Building a scan retains its separate window-modal Cancel progress dialog.

Synthetic integral scan during a baseline refit with indeterminate progress and Stop

Saving and reopening

The project (.asymp) retains the scalar observations, x-axis choice, baseline regions, peak settings, and per-point exclusions. Completed baseline, peak, and RF fits retain their numerical parameters, available errors and statistics, fitted support, sampled overlays, and computation revisions. Reopening restores these results without running an optimiser or evaluating a new model curve, and returns to Integral scan if it was active when saved. Opening, relocating sources, and saving do not turn an old or unknown execution into a current one. See Project files.

A settings-only historical fit has no numerical result to restore. Its controls and any retained values remain available, with the guidance Saved fit settings have no captured numerical result. Use Fit baseline, Fit peaks, or Fit RF resonance explicitly to obtain a new result. No parameters, errors, or covariance are inferred to fill that gap.

Reopened settings-only scan with guidance to fit explicitly for a new numerical result

Use Fit baseline, Fit peaks, or Fit RF resonance explicitly for a new result. Each completed execution keeps its own attribution and the older captured executions remain in project history. Editing the axis, exclusions, derivative option, baseline regions/model, peak settings, or RF frequency/seeds detaches the affected overlay; it cannot apply a saved fit to the edited inputs. File → New Project clears the scan observations and their fit dependencies. Peak uncertainties include first-order fitted-baseline propagation, conditional on the chosen baseline model and regions. Retaining that covariance does not add calibration uncertainty, model-selection uncertainty, or a general cross-run covariance model.

Worked example: a synthetic scan

You can exercise the whole ALC workflow without a beamline, on a synthetic longitudinal-field scan whose integral asymmetry dips at an avoided level crossing. The figure below was produced from such a scan — 31 runs stepped from 2000 to 5000 G, with a resonance built in near 3100 G.

ALC field scan with a fitted baseline and Gaussian resonance peak

The steps mirror a real analysis:

  1. Load the field-stepped runs and select them all.

  2. Switch the toolbar to the Integral scan representation and, in the Fit dock, press Build Scan — each run is integrated over the time window to a single point, and the scan of integral asymmetry against field appears in the central plot area.

  3. Mark two non-resonant field regions either side of the dip and press Fit baseline (a straight line here).

  4. Add a Gaussian peak and press Fit peaks. The fit recovers the resonance field — \(B_0 \approx 3104\) G, against the 3100 G the scan was built with — along with its width and amplitude.

For the same workflow on real data, see ALC field scan in TCNQ.

Common pitfalls

  • The scan area is empty after entering the representation. The scan is built, not automatic: multi-select the runs, set the integration window, and press Build Scan in the Fit dock. Until then the central area shows the “Build a scan to see the ALC curve” placeholder.

  • A run is missing from the scan. Field-axis scans drop runs with no recorded field (and likewise for temperature); the provenance line beneath the scan names them (and its tooltip gives the reason), or switch the x-axis to Run.

  • A point is greyed and hollow. You (or a saved project) excluded that run by clicking it — click it again to restore it. The provenance line tells you how many points are excluded this way.

  • “Add at least one non-resonant region”. The baseline needs at least one region, and a Linear baseline needs at least two usable points across the marked regions. Widen the regions or use a Constant baseline.

  • Regions or peaks disappeared. Changing the x-axis clears them, because they are expressed in the units of the axis they were drawn on.

  • The baseline or fit overlay vanished after an edit. Editing a region or dragging a handle marks the fit stale on purpose; press Fit baseline (and then Fit peaks) again.

References

[Murphy1985]

K. M. Murphy and R. H. Topel, J. Bus. Econ. Stat. 3, 370 (1985), https://doi.org/10.1080/07350015.1985.10509471.

[Stefanski2002]

L. A. Stefanski and D. D. Boos, Am. Stat. 56, 29 (2002), https://doi.org/10.1198/000313002753631330.

Compared with other programs

Pair validation follows Asymmetry’s independent-count uncertainty assumption. Native Mantid 6.16.1 rejects tested identical pair lists but accepts partial overlap; native musrfit 1.12.1 accepts the tested overlaps. WiMDA documentation does not establish the same disjointness contract for this operation. These input checks do not establish agreement of integral endpoints or timing conventions. See Detector Grouping and Layout and Asymmetry in the μSR software landscape for the versioned grouping observations and sources.

Mantid 6.16.1 Fit linear-background/Gaussian controls on matching owned scalar observations agree within 0.005 supplied point standard errors in the sampled predictions, with peak Height/Sigma matched to amplitude/Gaussian width. This is a matched least-squares control; it does not reproduce the specialised RF model or the two-stage fitted-baseline covariance. See Asymmetry in the μSR software landscape for conditions and limits.

Captured scan-fit history and no-refit reopening are Asymmetry project safeguards. They do not assert identical project-restoration behaviour in WiMDA, Mantid, or musrfit, and introduce no new estimator comparison.

Mantid’s documented PlotAsymmetryByLogValue provides a related asymmetry versus sample-log workflow. No matched native execution establishes identical integral/dual-period observables, endpoints, or errors here. WiMDA’s original manual, Sec. 11.1, describes time-window LCR scans using histogram bunching, cursor selection, and batch fit tables. That is a documented method, rather than a native WiMDA 1.326 ALC/RF comparison or a specification of its dedicated ALC-column/derivative operations. Asymmetry’s table derivative uses positive steps, optional max_gap, and selected-axis units. musrfit 1.12.1 packs counts before its fitting ratio. Checked packed controls agree only on 22 interior points per case at export precision; first/endpoint differences remain unresolved. No complete packed-output, fresh native WiMDA ALC/RF, full Mantid, or four-program numerical agreement is claimed. See Asymmetry in the μSR software landscape for the public method references and limits.

See also

Period statistics

G+R pools prepared corrected counts before the selected estimator, preserving each acquired period’s correction and timing before pooling. G−R subtracts the two period asymmetries with one shared chosen α/β and common observed native support. Red and Green select their own acquired periods. Inclusive time-window bounds select whole bins by native centres in µs; omitted bounds use the good-bin window. Core scan values/errors are fractions; the GUI displays and saves scan values in percent. Red and Green labels alone do not identify the RF acquisition conditions.