Frequency-domain helpers

Frequency-domain fitting helpers.

asymmetry.core.fitting.spectral.append_frequency_field_derived_parameters(parameters, uncertainties=None)[source]

Return a copy with derived centre/width field parameters appended.

The canonical fitted quantities remain nu0 and fwhm in MHz. The derived B0 and Bwid values are appended for trend tables and exports.

asymmetry.core.fitting.spectral.default_frequency_model()[source]

Return the default V1 frequency-domain peak model.

asymmetry.core.fitting.spectral.field_gauss_to_frequency_mhz(value_gauss)[source]

Convert a magnetic field or width in Gauss to MHz.

asymmetry.core.fitting.spectral.frequency_mhz_to_field_gauss(value_mhz)[source]

Convert a muon precession frequency or width in MHz to Gauss.

asymmetry.core.fitting.spectral.seed_peak_parameters_from_dataset(dataset, model, *, guard_bins=3, guard_freq_mhz=2.0)[source]

Return simple peak/background seeds for one displayed Fourier spectrum.

The dominant-magnitude bin of a (Power)^1/2 spectrum is usually the DC/apodisation spike, not the physical precession peak, so the peak search excludes a low-frequency guard band before taking the argmax. The guard width is max(guard_bins * df, guard_freq_mhz), where df is the spectrum’s bin spacing (a proxy for 1/T_obs); it falls back to the unguarded global argmax if the guard would empty the search array.

When the model declares two or more peak components, seeding delegates to asymmetry.core.fitting.spectral._seed_multiple_peaks, which assigns the strongest detected peaks to each component (see there for the under-detection fallback).

Field scan

asymmetry.core.fitting.field_scan.fit_rf_resonance(scan, *, nu_rf, a_mu=515.0, a_p=124.0, fix_nu_rf=True, x_min=None, x_max=None, method='migrad', cancel_check=None)[source]

Fit the RF-µSR muon+proton resonance model to an RF field scan.

Wraps fit_scan_model() for the RF_RESONANCE_COMPONENT model so the GUI and scripts share one seeding + fixing rule. The scan is the (Green − Red) integral asymmetry vs field built by asymmetry.core.io.periods.build_rf_difference_scan(). ν_RF is a known acquisition constant and is held fixed by default; A_µ (mean dip position) and A_p (dip splitting) are the couplings read off the result — check ``result.success`` first. Seeds come from rf_resonance_seeds().

asymmetry.core.fitting.field_scan.fit_scan_baseline(scan, regions, *, model='Linear', parameters=None, method='migrad', cancel_check=None)[source]

Fit a baseline over non-resonant regions and subtract it.

Parameters:
  • scan – The field scan to correct.

  • regions – Inclusive (x_lo, x_hi) windows on the scan’s x-axis marking the non-resonant baseline regions (their union is fitted).

  • model – Baseline model — "Linear" (default), "Constant", or any component/expression.

  • parameters – Optional starting ParameterSet; defaults are used otherwise.

Returns:

ScanBaselineResult – The fitted baseline sampled over all scan points, a corrected FieldScan (value − baseline, marginal propagated errors), and the fit.

Raises:

ValueError – If no valid regions are given; if the regions select fewer usable points (finite value, error > 0) than the baseline has free parameters (an underdetermined fit); or if the baseline fit does not converge. A failed fit never returns a (silently wrong) corrected scan.

asymmetry.core.fitting.field_scan.fit_scan_model(scan, model, *, parameters=None, initial=None, x_min=None, x_max=None, method='migrad', extra_starts=0, cancel_check=None)[source]

Fit a parameter model to a field scan’s (x, value, error).

Amplitude parameters come back on the scan’s own asymmetry scale — a fraction (A ∈ [-1, 1]) for a scan straight out of build_field_scan(), per the module docstring.

The thin adapter that lets a FieldScan flow into the existing fit_parameter_model. Used for the peak-fit step on a (typically baseline-corrected) scan; check ``result.success`` before reading the resonance field and width from parameters (e.g. B0 / Bwid for GaussianLCR) — on a failed fit the parameter set may be empty.

Pass starting values via either an explicit parameters set or an initial override dict, not both. extra_starts is fit_parameter_model()’s multi-start, which also tries the scan’s own data seed.

asymmetry.core.fitting.field_scan.rf_resonance_seeds(scan, *, nu_rf, a_mu=515.0, a_p=124.0, cancel_check=None)[source]

Seed values for an RF_RESONANCE_COMPONENT fit of scan.

The two resonance fields B1, B2 are derived inside the model from A_µ/A_p/ν_RF, so those three seed the position and splitting (defaults 515/124 MHz put the dips near the benzene 866/772 G). The depths, widths and background are seeded from the data by the model’s own estimator in suggest_model_seeds(), so the GUI’s RF fit and a scripted one start from the same place.

asymmetry.core.fitting.field_scan.RF_RESONANCE_COMPONENT

Rrf offset

asymmetry.core.fitting.rrf_offset.apply_rrf_offsets(values, offsets)[source]

Convert fitted rotating-frame values to lab-frame ones for reporting.

lab = δν + ν₀ for each offset parameter; everything else (amplitudes, relaxation rates, phases) is frame-invariant and passes through.

asymmetry.core.fitting.rrf_offset.rrf_frequency_offsets(model, frequency_mhz)[source]

Map each rotation parameter’s unique name to its additive frame offset.

The offsets are what must be added to the fitted (rotating-frame) parameter values to evaluate the model against raw lab-frame data — and, identically, what converts fitted δν back to lab-frame values for reporting (apply_rrf_offsets()).

asymmetry.core.fitting.rrf_offset.rrf_offset_model(model, frequency_mhz)[source]

Wrap model.function so its rotation frequencies read as δν.

The returned callable has the same f(t, **params) contract the fit engine expects; rotation parameters are shifted by ν₀ (or its Gauss equivalent) before delegation, so the data fitted are raw and the fitted values are rotating-frame offsets. The offsets used are attached as rrf_offsets (with rrf_frequency_mhz) for reporting.

The shift itself is offset_model_function(); the GUI fit path instead resolves rrf_frequency_offsets() once and passes them straight to the engine’s frequency_offsets argument, which applies the same seam.

asymmetry.core.fitting.rrf_offset.offset_model_function(base_fn, offsets)[source]

Wrap f(t, **params) so the named parameters are shifted additively.

The returned callable adds offsets[name] to each named parameter before delegating to base_fn — the single shift seam shared by rrf_offset_model() and the engine-level frequency_offsets argument (asymmetry.core.fitting.engine.FitEngine.fit()), so fitting raw data through either path is bit-for-bit identical. A parameter named in offsets but absent from the call raises ValueError.

Spectral window

asymmetry.core.fitting.spectral_window.effective_analysis_window(time, error, *, factor=5.0, min_points=32)[source]

Return the exclusive end index of the noise-truncated analysis window.

μSR error bars grow roughly exponentially with time (dying-muon statistics) and are capped at 100 %; a full-window FFT is then dominated by the late-time pure-noise tail, whitening the spectrum so even clean lines vanish. This truncates the record at the first point whose per-point error exceeds factor times the early-time error — i.e. where the per-point information 1/σ² has fallen below 1/factor² of its early value — keeping the statistically informative early window and shedding the noise tail.

The criterion is strictly per-point, so flat-error records (constant σ, the synthetic/test convention) are never truncated: the returned index is the full length and the reported resolution is unchanged. Returns the full length for short records (≤ min_points) or degenerate error arrays.