pub fn error_budget(
base: &ResolvedSolveRequestV1,
sources: &[(InputAxis, f64)],
ranges_m: &[f64],
) -> Result<ErrorBudgetReportV1, KernelError>Expand description
Propagate each declared per-input uncertainty in sources to impact covariance at every
range in ranges_m, via central differences through the real solver
(central_difference), and rank the sources by their share of impact variance.
sources is (axis, sigma) pairs: sigma is the caller’s one-sigma uncertainty for that
axis, in the axis’s own physical unit (crate::perturbation::axis_meta(axis).kind). Every
sigma must be finite and non-negative and every axis must appear at most once – both are
validated up front, before any solve; see “Sources and ranges are validated up front” and
# Errors below. (Declaring the same axis twice would double-count its variance and make its
own leave-one-out counterfactual ambiguous – which of the two entries would “removing this
source” mean? – so it is rejected rather than given an arbitrary answer.)
§Honesty
ErrorBudgetReportV1::method and ErrorBudgetReportV1::assumptions state, in the
payload itself (not only in prose documentation), that: sources are treated as INDEPENDENT
(no correlation between them is modelled); propagation is FIRST-ORDER/local-linear about the
nominal solution, using the axis’s own small default differencing step regardless of the
declared sigma (not exact for large or non-Gaussian input uncertainty – see “Why the
differencing step ignores the declared sigma” above); the 95% ellipse assumes an
approximately Gaussian impact distribution; a source’s derivative may be one-sided rather
than central; and an unavailable source is not the same fact as a zero-contribution one. See
the_report_declares_independence_and_linearity in this module’s tests.
§Unavailable sources
See this module’s top-level “Unavailable sources” doc section.
§Errors
KernelError::Observationimmediately, before any solve, if anyrange_minranges_mis not finite or falls outside[0, base.shot.max_range_m]– see “Sources and ranges are validated up front” above.KernelError::NonFiniteimmediately if any declaredsigmais not finite or is negative.KernelError::DuplicateAxisimmediately if the same axis appears more than once insources.- Otherwise, propagates any
KernelErrorfromcentral_differencethat is not one of the four structural refusals recorded inErrorBudgetReportV1::unavailable_sourcesinstead – a genuine solver or trajectory failure, not a normal “this input cannot be perturbed here” fact.
A thin wrapper over error_budget_with_target passing None – every row’s p_hit and
every source’s p_hit_gain_if_perfect come back None (never a fabricated number), and
method/assumptions say nothing about hit probability. Call
error_budget_with_target directly to also get those.