Grouped time-domain fitting

class asymmetry.core.fitting.grouped_time_domain.GroupedTimeDomainFitResult(success, group_results, shared_parameters, message='', joint_fit=None)[source]

Grouped results, with a complete F/B solution when available.

asymmetry.core.fitting.grouped_time_domain.build_count_group(dataset, group_id, *, t_min=None, t_max=None, lifetime_corrected=True, exclude=None)[source]

Build one named detector group’s count-domain trace.

Unlike build_grouped_time_domain_groups() this does not require two included groups: it serves single-histogram count fits, which select a specific detector group regardless of the included_groups map. exclude drops an interior time window of bins.

asymmetry.core.fitting.grouped_time_domain.build_grouped_count_model(polarization_model_fn)[source]
asymmetry.core.fitting.grouped_time_domain.build_grouped_time_domain_groups(dataset, *, t_min=None, t_max=None, lifetime_corrected=True, exclude=None)[source]

Build grouped count domains from one dataset (all included groups).

asymmetry.core.fitting.grouped_time_domain.fit_grouped_series(relationship, members, polarization_model_fn, global_params, local_params, initial_params, *, fit_engine=None, t_min=None, t_max=None, method='migrad', max_calls=10000, minos=False, cancel_callback=None, seeding='as_provided', order_key=None, cost='poisson', cross_run_local_params=None, max_workers=None, block_separable=False, profile_shared_errors=False)[source]

Fit a series of grouped runs with one of three member relationships.

The physics (fit-function) parameters in global_params are always shared across the detector groups within a run. The relationship governs how they relate across runs (members):

  • "individual" / "batch" – each run is fit independently (its physics values are not shared with other runs). Both run the same engine path; they differ only in how the caller records the resulting series.

  • "global" – the physics parameters are shared across all runs and groups via a single simultaneous fit.

The per-group nuisance block (local_params ⊆ GROUP_NUISANCE_PARAMS) is always estimated separately for each (run, group).

Parameters:
  • members – Mapping of run number → that run’s included GroupedTimeDomainGroup list (group order is the trend order).

  • initial_params – Nested mapping run -> {group_id -> ParameterSet}. Every set must include the nuisance block plus the model parameters referenced by global_params / local_params.

Notes

A mixed fit (some physics shared across runs, others fitted per run) is expressed by routing through "global" and listing the per-run physics in cross_run_local_params: those become engine local parameters grouped by source run, while the rest stay shared across all runs.

max_workers opts into process-level parallelism of the independent ("as_provided") batch path, where each run’s joint fit is fully independent. None (the default) keeps the sequential, in-process path; a positive count dispatches up to min(max_workers, n_runs) runs across a spawn-based pool (the GUI passes os.cpu_count()). For a "global" series it instead parallelises the inner per-run fits of the block-separable solver (see block_separable); for chained seeding it has no effect (each run depends on the previous, so the chain is inherently sequential).

block_separable permits the "global" path to solve large mixed fits by alternating block minimisation instead of one monolithic Minuit problem: the runs are independent except for the handful of cross-run-shared physics params, so the solver alternates between fitting each run independently (the shared params held — the same per-run work the batch path parallelises) and a small fit of just the shared params. This scales linearly in run count where the monolithic fit blows up superlinearly. It engages only above a free-parameter threshold (small global fits keep the monolithic path and its exact joint covariance); the shared-parameter uncertainties it reports are conditional on the fitted locals.

asymmetry.core.fitting.grouped_time_domain.fit_grouped_time_domain(groups, polarization_model_fn, global_params, local_params, initial_params, *, fit_engine=None, t_min=None, t_max=None, method='migrad', max_calls=10000, minos=False, cancel_callback=None, cost='poisson')[source]

Fit one shared polarization model across several grouped count traces.

The first-slice contract is intentionally strict:

  • each group is a separate fitting domain

  • model-function parameters may be global or fixed only

  • local parameters may only come from the group nuisance block

  • the observed signal is assumed to be lifetime-corrected grouped counts

cost selects the fit objective, matching the count-domain modes’ convention:

  • "poisson" (default) — the Cash statistic on the raw Poisson counts (built without a lifetime correction; the model is multiplied by e^(−t/τ_μ) to predict raw counts). This is the statistically faithful objective: at low counts the √N-Gaussian weight biases the fit, and Cash removes that bias. Reported chi_squared is the Cash value (asymptotically χ²-distributed).

  • "gaussian" — √N-weighted least squares on the lifetime-corrected counts, WiMDA’s weighting, kept byte-for-byte as the historical baseline. (√N weighting is invariant to the lifetime correction, so this is exactly the pre-cost-factory grouped fit.)

Parameters:
  • groups – Included groups from one active dataset.

  • polarization_model_fn – Callable returning a normalized polarization-like signal.

  • global_params – Shared free parameters across all groups. These may include both physical model parameters and nuisance parameters selected as global.

  • local_params – Per-group free parameters. These are restricted to GROUP_NUISANCE_PARAMS.

  • initial_params – Parameter sets keyed by group_id. Every set must include the group nuisance parameters and any model parameters referenced by global_params.

asymmetry.core.fitting.grouped_time_domain.GROUP_NUISANCE_PARAMS
class asymmetry.core.fitting.grouped_time_domain.GroupedTimeDomainGroup(group_id, group_name, time, counts, error, source_run_number=None, metadata=<factory>, detector_counts=None, deadtime=CorrectionOutcome(name='deadtime', requested='off', status=<CorrectionStatus.OFF: 'off'>, reason=None, effective=None, uncertainty=None), detector_indices=())[source]

One grouped-count domain.