Experiment design

The Laplace/Fisher “where to measure next” acquisition shared by Suggest next point (a scalar trend) and the Knight-shift window’s Suggest next angle (see Knight shift and Parameter trending) — expected information gain, model discrimination, and the Hungarian set-matching utility used when a candidate’s components are unlabelled.

Bayesian experimental design for parameter trending.

Given a converged trend-model fit (fit_parameter_model), suggest where the next measurement should go — and how many events it should collect — to most constrain the model’s parameters. The acquisition is the Laplace (Gaussian-posterior) expected information gain for a single new datum:

IG(x) = 1/2 log[1 + g(x)^T Sigma g(x) / sigma_new^2(x)] (D-optimal)

DeltaVar_k(x) = (Sigma g(x))_k^2 / (sigma_new^2(x) + g(x)^T Sigma g(x))

(c-optimal)

where g(x) is the model’s parameter sensitivity at the fitted values and Sigma the fit covariance. The rank-one c-optimal update is exact for a linear model; for strongly nonlinear models (critical exponents) it ranks candidates correctly but underestimates the realised post-fit variance — see docs/studies/prototype-results.md — so the counting recommendation must be calibrated with calibrate_suggestion before being shown to a user.

Everything here is GUI-free and pure numpy; refits happen only inside calibrate_suggestion.

class asymmetry.core.fitting.experiment_design.NextPointSuggestion(x_candidates, utility, extrapolated, best_x, target, sigma_new, predicted_post_sigma=None, events_factor_to_target=None, target_unreachable=False, floor_sigma=None, risk_mask=None, warnings=())[source]

Bases: object

Utility curve and recommendation for the next measurement.

utility is DeltaVar_k (variance reduction of the target parameter) in c-optimal mode, or the information gain IG in D-optimal mode (target is None). Two degenerate shapes exist, both explained by warnings: unusable inputs (bad covariance, no noise model, …) yield empty arrays with best_x NaN, while a valid setup where no candidate carries information keeps the full curve (all-zero utility) with best_x NaN.

x_candidates
utility
extrapolated
best_x
target
sigma_new
predicted_post_sigma = None

Predicted post-measurement sigma of the target at best_x for a reference-statistics point (c-optimal mode only). Rank-one estimate — optimistic near critical points; calibrate before display.

events_factor_to_target = None

N/N_ref needed at best_x to reach sigma_goal (rank-one estimate). 0.0 means the goal is already met without a new point.

target_unreachable = False
floor_sigma = None

sigma of the target in the N -> infinity limit of a single new point at best_x — the floor set by the other parameters’ uncertainty.

risk_mask = None

Per-candidate assignment-risk flag (multi-series acquisition only). True where two series’ predicted values lie within _ASSIGNMENT_RISK_K sigma of each other, so a new datum there may attach to the wrong curve. None for single-series suggestions, which have no crossing to worry about.

warnings = ()
__init__(x_candidates, utility, extrapolated, best_x, target, sigma_new, predicted_post_sigma=None, events_factor_to_target=None, target_unreachable=False, floor_sigma=None, risk_mask=None, warnings=())
class asymmetry.core.fitting.experiment_design.SuggestionCalibration(x_new, events_factor, target, n_trials, n_failed, realized_post_sigma, realized_post_sigma_p16, realized_post_sigma_p84, predicted_post_sigma=None, calibration_ratio=None, warnings=())[source]

Bases: object

Monte-Carlo check of a suggestion: simulate the point, refit, measure.

realized_post_sigma is the median post-fit sigma of the target over the successful trials; the p16/p84 band shows its spread. calibration_ratio is realised variance / rank-one predicted variance (> 1 means the analytic figure was optimistic).

x_new
events_factor
target
n_trials
n_failed
realized_post_sigma
realized_post_sigma_p16
realized_post_sigma_p84
predicted_post_sigma = None
calibration_ratio = None
warnings = ()
__init__(x_new, events_factor, target, n_trials, n_failed, realized_post_sigma, realized_post_sigma_p16, realized_post_sigma_p84, predicted_post_sigma=None, calibration_ratio=None, warnings=())
asymmetry.core.fitting.experiment_design.suggest_next_point(model, parameters, covariance, x_data, y_err, x_min, x_max, *, target=None, sigma_goal=None, n_candidates=257)[source]

Rank candidate x values by how much a new point there constrains the fit.

covariance is the (names, matrix) pair from ParameterModelFitResult.covariance; x_data/y_err are the measured series (the per-point errors define the empirical noise model for the hypothetical new point at reference statistics). target selects c-optimality for that parameter; None means D-optimal. sigma_goal (c-optimal only) additionally solves for the event-count factor N/N_ref needed at the best x — a rank-one planning figure that should be calibrated with calibrate_suggestion() before display.

Never raises on degenerate inputs: returns an empty suggestion with an explanatory warning instead.

class asymmetry.core.fitting.experiment_design.SeriesSpec(model, parameters, covariance, x_data, y_err)[source]

Bases: object

One series’ inputs to a multi-series acquisition.

Mirrors suggest_next_point()’s per-series argument types: a fitted model/parameters pair, the (names, matrix) fit covariance (None when the fit produced none), and the measured x_data/y_err that define the empirical new-point noise model. One physical measurement at a candidate x is assumed to yield one datum for every series (§3.1).

model
parameters
covariance
x_data
y_err
__init__(model, parameters, covariance, x_data, y_err)
asymmetry.core.fitting.experiment_design.suggest_next_point_multi(series, x_min, x_max, *, target=None, sigma_goal=None, n_candidates=257, labels=None)[source]

Rank candidate x by how much a shared new point constrains several series.

Each entry of series is a fitted SeriesSpec; one measurement at x adds one datum to every series. With target is None the utility is the D-optimal information-gain sum over series (§3.1):

U(x) = Σ_m ½ log[1 + g_m(x)ᵀ Σ_m g_m(x) / σ_m²(x)]

With target = (series_index, param_name) the objective is that one series’ c-optimal variance reduction for param_name — the other series still receive the datum but do not enter the objective — and the sigma_goal/event-count solve applies to the target exactly as in suggest_next_point(). Either way the returned suggestion carries a per-candidate NextPointSuggestion.risk_mask (§3.1): the rank-one update assumes the new datum attaches to the right curve, so candidates near a predicted crossing are flagged.

A series whose covariance is invalid (asymmetry.core.fitting.experiment_design._validated_covariance) contributes nothing to the utility and adds a warning naming it (by labels when supplied, else by index); the suggestion still succeeds if at least one series is usable. All-unusable inputs degrade to an empty suggestion. Never raises.

asymmetry.core.fitting.experiment_design.calibrate_suggestion(model, parameters, x_data, y_data, y_err, x_new, *, target, events_factor=1.0, n_trials=50, seed=0, predicted_post_sigma=None)[source]

Monte-Carlo-calibrate a suggestion by simulating the point and refitting.

Each trial draws the hypothetical new datum from the fitted model plus Gaussian noise at the empirical sigma for x_new (scaled by 1/sqrt(events_factor)), appends it to the measured series, refits from the fitted values, and records the post-fit sigma of target. The median over trials is the calibrated post-measurement sigma — the honest counterpart of the rank-one predicted_post_sigma, which is known to be optimistic near critical points (see docs/studies/prototype-results.md).

y_err must be the effective per-point sigmas the trend fit was weighted with (already resolved through the fit’s error mode).

asymmetry.core.fitting.experiment_design.calibrate_events_for_goal(model, parameters, x_data, y_data, y_err, x_new, *, target, sigma_goal, initial_events_factor=1.0, n_trials=30, seed=0, max_events_factor=1024.0, max_iterations=6)[source]

Find the event-count factor whose calibrated post-sigma meets the goal.

Multiplicative search starting from initial_events_factor (use the rank-one events_factor_to_target when available): each step scales the factor by the shortfall (median/goal)^2 — exact if the new point’s variance dominates, conservative otherwise. Returns (factor, last_calibration); factor is None when the goal is not met by max_events_factor (the single-point floor applies).

asymmetry.core.fitting.experiment_design.suggest_discriminating_point(lead_model, lead_parameters, alternatives, x_data, y_err, x_min, x_max, *, n_candidates=257)[source]

Rank candidate x values by how well they discriminate between models.

Scores the lead_model (the currently favoured fit) against every entry in alternatives (each a fitted (model, parameters) pair over the same series), taking the elementwise max over alternatives — per the TAS-AI lock-in lesson (§4/§8.1 of the study), a leader must be tested against all live competitors, not just the runner-up:

U_disc(x) = max_i [f_lead(x) - f_i(x)]^2 / (2 sigma_new^2(x))

Returns a NextPointSuggestion with target=None (this mode has no single target parameter) and no event-count/goal fields set. Never raises: degenerate inputs (no alternatives, no noise model, bad range) degrade to an empty suggestion with an explanatory warning, and a utility that is everywhere within noise of zero is flagged rather than silently returning a meaningless argmax.

asymmetry.core.fitting.experiment_design.set_matching_divergence(hypothesis_a, hypothesis_b, sigma, x_candidates)[source]

Per-candidate min-cost set-matching divergence between two hypotheses (§3.3).

Each hypothesis is an equal-length list of (model, parameters) curves. At every candidate x the two hypotheses’ predicted N-vectors are matched one-to-one (Hungarian) to minimise the total weighted cost, with per-pair cost

[f_i^A(x) − f_j^B(x)]² / (2 σ_i²(x))

(sigma[i] is series i of hypothesis A’s per-candidate noise). Because a new run’s components are unlabelled, two assignment hypotheses are only distinguishable through the sets of values they predict — this is that set-level discrepancy. It is zero where the hypotheses predict the same value set (e.g. at a crossing where the labellings coincide) and peaks where they imply genuinely different curve sets. For N = 1 it reduces exactly to the labelled discrimination integrand of suggest_discriminating_point().

Returns U(x) over x_candidates. Non-finite predictions or zero sigmas are treated as a large finite cost so the matching stays well-posed.

asymmetry.core.fitting.experiment_design.aic_weights(chi_squareds, n_free_params)[source]

Akaike-weight a set of candidate models from their fit chi-squareds.

AIC_i = chi2_i + 2 p_i, weighted by information_weights() (a non-finite AIC gets weight 0.0). BIC is deliberately not used here — its p * ln(n) penalty drifts under the sequential-n growth of an in-progress trend series (§4 of the study). Raises ValueError if the two input lists differ in length — a mismatch here is a programming error, not a user-data problem.

asymmetry.core.fitting.experiment_design.cost_weighted_utility(x_candidates, utility, x_current, *, count_time, up_rate, down_rate, gamma=0.7)[source]

Weight a utility curve by movement + counting cost (TAS-AI’s IG^gamma/t).

move_time(x) = up_rate * (x - x_current) for x > x_current, else down_rate * (x_current - x); all rates/times share a unit (hours). Returns clip(utility, 0)**gamma / (count_time + move_time).

Pure array-in/array-out with defensive guards rather than raising: an invalid cost model (count_time <= 0, a negative rate, or a non-finite x_current) must not silently distort the ranking, so the original utility is returned unchanged in that case. The GUI is responsible for validating these inputs before calling; this function does not emit warnings.