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:
objectUtility curve and recommendation for the next measurement.
utilityisDeltaVar_k(variance reduction of the target parameter) in c-optimal mode, or the information gainIGin D-optimal mode (target is None). Two degenerate shapes exist, both explained bywarnings: unusable inputs (bad covariance, no noise model, …) yield empty arrays withbest_xNaN, while a valid setup where no candidate carries information keeps the full curve (all-zeroutility) withbest_xNaN.- x_candidates
- utility
- extrapolated
- best_x
- target
- sigma_new
- predicted_post_sigma = None
Predicted post-measurement sigma of the target at
best_xfor 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_xto reachsigma_goal(rank-one estimate).0.0means 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).
Truewhere two series’ predicted values lie within_ASSIGNMENT_RISK_Ksigma of each other, so a new datum there may attach to the wrong curve.Nonefor 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:
objectMonte-Carlo check of a suggestion: simulate the point, refit, measure.
realized_post_sigmais the median post-fit sigma of the target over the successful trials; the p16/p84 band shows its spread.calibration_ratiois 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.
covarianceis the(names, matrix)pair fromParameterModelFitResult.covariance;x_data/y_errare the measured series (the per-point errors define the empirical noise model for the hypothetical new point at reference statistics).targetselects c-optimality for that parameter;Nonemeans 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 withcalibrate_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:
objectOne series’ inputs to a multi-series acquisition.
Mirrors
suggest_next_point()’s per-series argument types: a fittedmodel/parameterspair, the(names, matrix)fitcovariance(Nonewhen the fit produced none), and the measuredx_data/y_errthat define the empirical new-point noise model. One physical measurement at a candidatexis 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
seriesis a fittedSeriesSpec; one measurement atxadds one datum to every series. Withtarget is Nonethe 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 forparam_name— the other series still receive the datum but do not enter the objective — and thesigma_goal/event-count solve applies to the target exactly as insuggest_next_point(). Either way the returned suggestion carries a per-candidateNextPointSuggestion.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 (bylabelswhen 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 by1/sqrt(events_factor)), appends it to the measured series, refits from the fitted values, and records the post-fit sigma oftarget. The median over trials is the calibrated post-measurement sigma — the honest counterpart of the rank-onepredicted_post_sigma, which is known to be optimistic near critical points (seedocs/studies/prototype-results.md).y_errmust 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-oneevents_factor_to_targetwhen 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 isNonewhen the goal is not met bymax_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 inalternatives(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
NextPointSuggestionwithtarget=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 candidatexthe two hypotheses’ predictedN-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 seriesiof 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. ForN = 1it reduces exactly to the labelled discrimination integrand ofsuggest_discriminating_point().Returns
U(x)overx_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 byinformation_weights()(a non-finite AIC gets weight0.0). BIC is deliberately not used here — itsp * ln(n)penalty drifts under the sequential-n growth of an in-progress trend series (§4 of the study). RaisesValueErrorif 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)forx > x_current, elsedown_rate * (x_current - x); all rates/times share a unit (hours). Returnsclip(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-finitex_current) must not silently distort the ranking, so the originalutilityis returned unchanged in that case. The GUI is responsible for validating these inputs before calling; this function does not emit warnings.