Skip to main content

qualia_core_db/q42/science_validation/
uncertainty_ece.rs

1//! Uncertainty calibration, Gaussian coverage factor, covariance rotation, Mahalanobis NEES,
2//! and Expected Calibration Error (ECE) verifiers (C02-C03, C02-C04, C02-C05, Modes 6 & 7).
3//!
4//! All reference calculations are evaluated in independent `f64` arithmetic:
5//! - Target quantity, unit, and uncertainty kind admission (`StandardAbsolute`, `ExpandedAbsolute`, `Relative`).
6//! - One-shot affine calibration $\text{physical} = \text{scale}\cdot\text{raw} + \text{offset}$ with
7//!   idempotence guard against double-scaling already calibrated streams.
8//! - Half-open calibration validity interval $[t_{\text{from}}, t_{\text{until}})$ with exact boundary rejection.
9//! - Exact positive-term Kummer-confluent series $\operatorname{erf}(k/\sqrt{2})$ verifying Gaussian
10//!   coverage factor $k \leftrightarrow p$ consistency ($k=1 \leftrightarrow 68.268949\%$,
11//!   $k=1.959964 \leftrightarrow 95\%$, $k=2 \leftrightarrow 95.449974\%$, $k=3 \leftrightarrow 99.730020\%$).
12//! - $3\times 3$ covariance symmetry, positive-definiteness, frame rotation $\boldsymbol{\Sigma}' = \mathbf{R}\boldsymbol{\Sigma}\mathbf{R}^T$,
13//!   Mahalanobis distance / NEES, ECE, Brier score, and Gaussian NLL.
14
15use crate::q42::science_validation::stokes_mueller::{C02_ROUNDING_FACTOR, F64_EPS};
16
17/// Uncertainty representation kind required by C02-C05 and Modes 6/7.
18#[derive(Debug, Clone, Copy, PartialEq)]
19pub enum UncertaintyKind {
20    /// Standard uncertainty $1\sigma$ in the target quantity's physical units.
21    StandardAbsolute,
22    /// Expanded uncertainty $U = k \cdot u_c$ with explicit coverage factor $k > 0$
23    /// and Gaussian coverage probability $p \in (0, 1)$.
24    ExpandedAbsolute {
25        coverage_factor_k: f64,
26        confidence_probability: f64,
27    },
28    /// Dimensionless relative standard uncertainty $u_r = u(x)/|x|$.
29    Relative,
30}
31
32/// Calibration stage of a sample stream (C02-C05 & QAC Schema 210).
33#[derive(Debug, Clone, Copy, PartialEq, Eq)]
34pub enum CalibrationStage {
35    /// Uncalibrated raw ADC/sensor counts (`raw-counts`).
36    RawCounts,
37    /// Already calibrated physical base units (`physical-base-units`, `units_per_sample == 1.0`).
38    CalibratedPhysical,
39    /// Digital values unrelated to physical pressure/field (`digital-unrelated-to-pressure`).
40    DigitalUnrelated,
41}
42
43/// Uncertainty descriptor bound to a specific quantity and unit (C02-C05).
44#[derive(Debug, Clone, Copy, PartialEq)]
45pub struct UncertaintyDescriptor<'a> {
46    pub target_quantity: &'a str,
47    pub target_unit: &'a str,
48    pub kind: UncertaintyKind,
49    pub value: f64,
50    pub record_has_mixed_units: bool,
51    pub broadcast_across_all_fields: bool,
52}
53
54/// Structured rejection reasons for calibration, uncertainty, and statistical consistency checks.
55#[derive(Debug, Clone, PartialEq)]
56pub enum UncertaintyValidationError {
57    /// Uncertainty value or parameter is NaN, infinite, or negative.
58    InvalidUncertaintyValue { value: f64 },
59    /// Uncertainty lane is marked valid but lacks an explicit target quantity or unit string.
60    MissingTargetQuantityOrUnit,
61    /// A single unlabeled scalar uncertainty was broadcast across a mixed-unit record (C02-C05 / EMF-A05).
62    MixedUnitScalarBroadcastForbidden,
63    /// Coverage factor $k$ and claimed probability $p$ do not satisfy $p = \operatorname{erf}(k/\sqrt{2})$.
64    GaussianCoverageMismatch {
65        k: f64,
66        claimed_probability: f64,
67        expected_probability: f64,
68        abs_diff: f64,
69        tolerance: f64,
70    },
71    /// Affine calibration scale is non-positive or offset/scale is non-finite.
72    InvalidAffineCalibration { scale: f64, offset: f64 },
73    /// Attempted to reapply raw affine calibration to a stream already in `CalibratedPhysical` stage,
74    /// or `CalibratedPhysical` stream has `units_per_sample != 1.0` or `offset != 0.0`.
75    DoubleCalibrationForbidden {
76        stage: CalibrationStage,
77        units_per_sample: f64,
78        offset: f64,
79    },
80    /// Invalid or expired half-open calibration interval `[from_tick, until_tick)`.
81    CalibrationWindowExpiredOrInvalid {
82        sample_tick: i128,
83        from_tick: i128,
84        until_tick: i128,
85    },
86    /// Covariance matrix is non-finite, asymmetric, or not positive definite.
87    InvalidCovarianceMatrix {
88        reason: &'static str,
89        value: f64,
90    },
91    /// Covariance rotation $\mathbf{R}\boldsymbol{\Sigma}\mathbf{R}^T$ violated trace or determinant invariance.
92    CovarianceRotationInvarianceViolation {
93        trace_before: f64,
94        trace_after: f64,
95        det_before: f64,
96        det_after: f64,
97    },
98    /// Invalid probability or empty sample set in ECE / Brier / NLL / NEES evaluation.
99    InvalidStatisticalSample { reason: &'static str },
100    /// Empirical calibration error or NEES exceeded the declared acceptance threshold.
101    StatisticalCalibrationExceeded {
102        metric_name: &'static str,
103        observed: f64,
104        threshold: f64,
105    },
106}
107
108/// Evaluate $\operatorname{erf}(x)$ in independent `f64` arithmetic with zero-cancellation
109/// positive-term Kummer series for $|x| \le 5.5$ and Laplace continued fraction for $|x| > 5.5$.
110pub fn erf_f64(x: f64) -> f64 {
111    if x.is_nan() {
112        return f64::NAN;
113    }
114    if x == 0.0 {
115        return x;
116    }
117    let sign = if x < 0.0 { -1.0 } else { 1.0 };
118    let ax = x.abs();
119    if ax > 6.5 {
120        return sign;
121    }
122    if ax <= 5.5 {
123        // erf(x) = (2 / sqrt(pi)) * exp(-x^2) * sum_{n=0}^\infty (2^n x^{2n+1}) / (2n+1)!!
124        // All terms for ax > 0 are strictly positive, eliminating alternating cancellation.
125        let two_x2 = 2.0 * ax * ax;
126        let mut term = ax;
127        let mut sum = term;
128        for n in 1..140 {
129            term *= two_x2 / ((2 * n + 1) as f64);
130            sum += term;
131            if term <= sum * 1.0e-17 {
132                break;
133            }
134        }
135        let two_over_sqrt_pi = 2.0 / core::f64::consts::PI.sqrt();
136        let val = two_over_sqrt_pi * (-ax * ax).exp() * sum;
137        sign * val.min(1.0)
138    } else {
139        // Laplace continued fraction for erfc(x) = (exp(-x^2) / (sqrt(pi) * x)) * CF
140        let mut f = 1.0e-30;
141        let mut c = f;
142        let mut d = 0.0;
143        for m in 1..60 {
144            let a = 0.5 * (m as f64);
145            let b = if m % 2 == 1 { ax } else { ax };
146            let _ = b;
147            d = ax + a * d;
148            if d.abs() < 1.0e-30 {
149                d = 1.0e-30;
150            }
151            c = ax + a / c;
152            if c.abs() < 1.0e-30 {
153                c = 1.0e-30;
154            }
155            d = 1.0 / d;
156            let delta = c * d;
157            f *= delta;
158            if (delta - 1.0).abs() < 1.0e-16 {
159                break;
160            }
161        }
162        let erfc_approx = ((-ax * ax).exp() / core::f64::consts::PI.sqrt()) * d;
163        let _ = f;
164        sign * (1.0 - erfc_approx).clamp(0.0, 1.0)
165    }
166}
167
168/// Compute two-sided Gaussian coverage probability $p(k) = \operatorname{erf}(k / \sqrt{2})$ for $k > 0$.
169#[inline]
170pub fn gaussian_coverage_probability(k: f64) -> f64 {
171    erf_f64(k / core::f64::consts::SQRT_2)
172}
173
174/// Verify consistency between a Gaussian coverage factor $k > 0$ and claimed confidence probability $p \in (0, 1)$.
175pub fn verify_gaussian_coverage_factor(
176    k: f64,
177    claimed_probability: f64,
178    tolerance: f64,
179) -> Result<f64, UncertaintyValidationError> {
180    if !k.is_finite()
181        || k <= 0.0
182        || !claimed_probability.is_finite()
183        || claimed_probability <= 0.0
184        || claimed_probability >= 1.0
185        || !tolerance.is_finite()
186        || tolerance <= 0.0
187    {
188        return Err(UncertaintyValidationError::InvalidUncertaintyValue { value: k });
189    }
190    let expected = gaussian_coverage_probability(k);
191    let abs_diff = (claimed_probability - expected).abs();
192    if abs_diff > tolerance {
193        return Err(UncertaintyValidationError::GaussianCoverageMismatch {
194            k,
195            claimed_probability,
196            expected_probability: expected,
197            abs_diff,
198            tolerance,
199        });
200    }
201    Ok(expected)
202}
203
204/// Validate a C02-C05 / Mode 6 / Mode 7 uncertainty descriptor.
205pub fn verify_uncertainty_descriptor(
206    desc: &UncertaintyDescriptor<'_>,
207    probability_tolerance: f64,
208) -> Result<(), UncertaintyValidationError> {
209    if !desc.value.is_finite() || desc.value < 0.0 {
210        return Err(UncertaintyValidationError::InvalidUncertaintyValue { value: desc.value });
211    }
212    if desc.target_quantity.trim().is_empty() || desc.target_unit.trim().is_empty() {
213        return Err(UncertaintyValidationError::MissingTargetQuantityOrUnit);
214    }
215    if desc.record_has_mixed_units && desc.broadcast_across_all_fields {
216        return Err(UncertaintyValidationError::MixedUnitScalarBroadcastForbidden);
217    }
218    if let UncertaintyKind::ExpandedAbsolute {
219        coverage_factor_k,
220        confidence_probability,
221    } = desc.kind
222    {
223        verify_gaussian_coverage_factor(
224            coverage_factor_k,
225            confidence_probability,
226            probability_tolerance,
227        )?;
228    }
229    Ok(())
230}
231
232/// Apply one-shot affine calibration $\text{physical} = \text{scale} \cdot \text{raw} + \text{offset}$
233/// to a raw-count sample, or verify that an already calibrated physical stream has
234/// `units_per_sample == 1.0` and `offset == 0.0` without re-scaling (C02-C05).
235pub fn apply_or_verify_affine_calibration(
236    sample: f64,
237    stage: CalibrationStage,
238    units_per_stored_sample: f64,
239    stored_offset: f64,
240    calibration_scale: f64,
241    calibration_offset: f64,
242) -> Result<(f64, CalibrationStage), UncertaintyValidationError> {
243    if !sample.is_finite()
244        || !units_per_stored_sample.is_finite()
245        || !stored_offset.is_finite()
246        || !calibration_scale.is_finite()
247        || !calibration_offset.is_finite()
248        || units_per_stored_sample <= 0.0
249        || calibration_scale <= 0.0
250    {
251        return Err(UncertaintyValidationError::InvalidAffineCalibration {
252            scale: calibration_scale,
253            offset: calibration_offset,
254        });
255    }
256    match stage {
257        CalibrationStage::RawCounts => {
258            if (units_per_stored_sample - 1.0).abs() > F64_EPS || stored_offset != 0.0 {
259                return Err(UncertaintyValidationError::DoubleCalibrationForbidden {
260                    stage,
261                    units_per_sample: units_per_stored_sample,
262                    offset: stored_offset,
263                });
264            }
265            let physical = calibration_scale * sample + calibration_offset;
266            Ok((physical, CalibrationStage::CalibratedPhysical))
267        }
268        CalibrationStage::CalibratedPhysical => {
269            // Already calibrated physical samples must have units_per_sample == 1 and offset == 0;
270            // calibration is retained as lineage only and never re-applied on read.
271            if (units_per_stored_sample - 1.0).abs() > F64_EPS || stored_offset != 0.0 {
272                return Err(UncertaintyValidationError::DoubleCalibrationForbidden {
273                    stage,
274                    units_per_sample: units_per_stored_sample,
275                    offset: stored_offset,
276                });
277            }
278            Ok((sample, CalibrationStage::CalibratedPhysical))
279        }
280        CalibrationStage::DigitalUnrelated => {
281            Err(UncertaintyValidationError::DoubleCalibrationForbidden {
282                stage,
283                units_per_sample: units_per_stored_sample,
284                offset: stored_offset,
285            })
286        }
287    }
288}
289
290/// Verify half-open calibration validity window $[t_{\text{from}}, t_{\text{until}})$ (C02-C03 & C02-C05).
291/// Exact boundary rule: $t_{\text{from}} < t_{\text{until}}$ and $t_{\text{from}} \le t < t_{\text{until}}$.
292pub fn verify_half_open_calibration_window(
293    sample_tick: i128,
294    from_tick: i128,
295    until_tick: i128,
296) -> Result<(), UncertaintyValidationError> {
297    if from_tick >= until_tick || sample_tick < from_tick || sample_tick >= until_tick {
298        return Err(
299            UncertaintyValidationError::CalibrationWindowExpiredOrInvalid {
300                sample_tick,
301                from_tick,
302                until_tick,
303            },
304        );
305    }
306    Ok(())
307}
308
309/// Verify that a $3\times 3$ covariance matrix $\boldsymbol{\Sigma}$ is finite, symmetric, and
310/// strictly positive definite (Sylvester's criterion on all leading principal minors).
311pub fn verify_covariance_3x3_spd(
312    cov: &[[f64; 3]; 3],
313) -> Result<(f64, f64), UncertaintyValidationError> {
314    let mut frob_sq = 0.0f64;
315    for r in 0..3 {
316        for c in 0..3 {
317            let v = cov[r][c];
318            if !v.is_finite() {
319                return Err(UncertaintyValidationError::InvalidCovarianceMatrix {
320                    reason: "non_finite_entry",
321                    value: v,
322                });
323            }
324            frob_sq += v * v;
325        }
326    }
327    let frob = frob_sq.sqrt();
328    let sym_tol = C02_ROUNDING_FACTOR * frob.max(1.0);
329    for r in 0..3 {
330        for c in (r + 1)..3 {
331            let diff = (cov[r][c] - cov[c][r]).abs();
332            if diff > sym_tol {
333                return Err(UncertaintyValidationError::InvalidCovarianceMatrix {
334                    reason: "asymmetric_covariance",
335                    value: diff,
336                });
337            }
338        }
339    }
340    let m1 = cov[0][0];
341    let m2 = cov[0][0] * cov[1][1] - cov[0][1] * cov[1][0];
342    let det = determinant_3x3(cov);
343    if m1 <= 0.0 || m2 <= 0.0 || det <= 0.0 {
344        return Err(UncertaintyValidationError::InvalidCovarianceMatrix {
345            reason: "not_positive_definite",
346            value: det.min(m1).min(m2),
347        });
348    }
349    let trace = cov[0][0] + cov[1][1] + cov[2][2];
350    Ok((trace, det))
351}
352
353/// Rotate a $3\times 3$ covariance or Cauchy stress tensor by a proper rotation matrix $\mathbf{R}$:
354/// $\boldsymbol{\Sigma}' = \mathbf{R}\boldsymbol{\Sigma}\mathbf{R}^T$ (C02-C04 & C02-C05), verifying trace
355/// and determinant invariance.
356pub fn rotate_covariance_3x3(
357    cov: &[[f64; 3]; 3],
358    rot: &[[f64; 3]; 3],
359) -> Result<[[f64; 3]; 3], UncertaintyValidationError> {
360    let (trace_before, det_before) = verify_covariance_3x3_spd(cov)?;
361    let mut temp = [[0.0f64; 3]; 3];
362    for i in 0..3 {
363        for j in 0..3 {
364            temp[i][j] = rot[i][0] * cov[0][j] + rot[i][1] * cov[1][j] + rot[i][2] * cov[2][j];
365        }
366    }
367    let mut out = [[0.0f64; 3]; 3];
368    for i in 0..3 {
369        for j in 0..3 {
370            out[i][j] = temp[i][0] * rot[j][0] + temp[i][1] * rot[j][1] + temp[i][2] * rot[j][2];
371        }
372    }
373    let (trace_after, det_after) = verify_covariance_3x3_spd(&out)?;
374    let trace_tol = C02_ROUNDING_FACTOR * trace_before.abs().max(1.0);
375    let det_tol = C02_ROUNDING_FACTOR * det_before.abs().max(1.0e-18);
376    if (trace_after - trace_before).abs() > trace_tol || (det_after - det_before).abs() > det_tol {
377        return Err(
378            UncertaintyValidationError::CovarianceRotationInvarianceViolation {
379                trace_before,
380                trace_after,
381                det_before,
382                det_after,
383            },
384        );
385    }
386    Ok(out)
387}
388
389/// Compute squared Mahalanobis distance (Normalized Estimation Error Squared, NEES)
390/// $d_M^2 = (\mathbf{x} - \boldsymbol{\mu})^T \boldsymbol{\Sigma}^{-1} (\mathbf{x} - \boldsymbol{\mu})$ in $\mathbb{R}^3$.
391pub fn mahalanobis_nees_3d(
392    observation: [f64; 3],
393    mean: [f64; 3],
394    cov: &[[f64; 3]; 3],
395) -> Result<f64, UncertaintyValidationError> {
396    let (_, det) = verify_covariance_3x3_spd(cov)?;
397    let dx = [
398        observation[0] - mean[0],
399        observation[1] - mean[1],
400        observation[2] - mean[2],
401    ];
402    for &d in &dx {
403        if !d.is_finite() {
404            return Err(UncertaintyValidationError::InvalidUncertaintyValue { value: d });
405        }
406    }
407    // Cofactor inverse of 3x3 symmetric SPD matrix:
408    let c00 = cov[1][1] * cov[2][2] - cov[1][2] * cov[2][1];
409    let c01 = -(cov[1][0] * cov[2][2] - cov[1][2] * cov[2][0]);
410    let c02 = cov[1][0] * cov[2][1] - cov[1][1] * cov[2][0];
411    let c11 = cov[0][0] * cov[2][2] - cov[0][2] * cov[2][0];
412    let c12 = -(cov[0][0] * cov[2][1] - cov[0][1] * cov[2][0]);
413    let c22 = cov[0][0] * cov[1][1] - cov[0][1] * cov[1][0];
414
415    let inv_dx = [
416        (c00 * dx[0] + c01 * dx[1] + c02 * dx[2]) / det,
417        (c01 * dx[0] + c11 * dx[1] + c12 * dx[2]) / det,
418        (c02 * dx[0] + c12 * dx[1] + c22 * dx[2]) / det,
419    ];
420    let nees = dx[0] * inv_dx[0] + dx[1] * inv_dx[1] + dx[2] * inv_dx[2];
421    Ok(nees.max(0.0))
422}
423
424/// Summary of probabilistic calibration metrics (ECE, MCE, Brier score).
425#[derive(Debug, Clone, Copy, PartialEq)]
426pub struct CalibrationMetricsReport {
427    pub expected_calibration_error: f64,
428    pub maximum_calibration_error: f64,
429    pub brier_score: f64,
430    pub sample_count: usize,
431}
432
433/// Compute Expected Calibration Error (ECE), Maximum Calibration Error (MCE), and Brier score
434/// over equal-width probability bins in $[0, 1]$.
435pub fn evaluate_ece_and_brier(
436    predicted_probabilities: &[f64],
437    binary_outcomes: &[bool],
438    num_bins: usize,
439    max_allowed_ece: f64,
440) -> Result<CalibrationMetricsReport, UncertaintyValidationError> {
441    let n = predicted_probabilities.len();
442    if n == 0 || n != binary_outcomes.len() || num_bins == 0 || num_bins > 64 {
443        return Err(UncertaintyValidationError::InvalidStatisticalSample {
444            reason: "invalid_sample_or_bin_count",
445        });
446    }
447    let mut bin_counts = [0usize; 64];
448    let mut bin_prob_sum = [0.0f64; 64];
449    let mut bin_acc_sum = [0.0f64; 64];
450    let mut brier_sum = 0.0f64;
451
452    for (&p, &y) in predicted_probabilities.iter().zip(binary_outcomes.iter()) {
453        if !p.is_finite() || !(0.0..=1.0).contains(&p) {
454            return Err(UncertaintyValidationError::InvalidStatisticalSample {
455                reason: "probability_out_of_unit_interval",
456            });
457        }
458        let outcome = if y { 1.0 } else { 0.0 };
459        let diff = p - outcome;
460        brier_sum += diff * diff;
461
462        let mut bin_idx = (p * (num_bins as f64)).floor() as usize;
463        if bin_idx >= num_bins {
464            bin_idx = num_bins - 1;
465        }
466        bin_counts[bin_idx] += 1;
467        bin_prob_sum[bin_idx] += p;
468        bin_acc_sum[bin_idx] += outcome;
469    }
470
471    let n_f64 = n as f64;
472    let mut ece = 0.0f64;
473    let mut mce = 0.0f64;
474    for b in 0..num_bins {
475        let count = bin_counts[b];
476        if count > 0 {
477            let avg_conf = bin_prob_sum[b] / (count as f64);
478            let avg_acc = bin_acc_sum[b] / (count as f64);
479            let gap = (avg_acc - avg_conf).abs();
480            ece += ((count as f64) / n_f64) * gap;
481            if gap > mce {
482                mce = gap;
483            }
484        }
485    }
486    let brier_score = brier_sum / n_f64;
487    if ece > max_allowed_ece {
488        return Err(UncertaintyValidationError::StatisticalCalibrationExceeded {
489            metric_name: "ECE",
490            observed: ece,
491            threshold: max_allowed_ece,
492        });
493    }
494
495    Ok(CalibrationMetricsReport {
496        expected_calibration_error: ece,
497        maximum_calibration_error: mce,
498        brier_score,
499        sample_count: n,
500    })
501}
502
503/// Compute univariate Gaussian Negative Log-Likelihood (NLL):
504/// $\text{NLL} = \frac{1}{N} \sum_{i=1}^N \left[\frac{1}{2}\ln(2\pi \sigma_i^2) + \frac{(y_i - \mu_i)^2}{2\sigma_i^2}\right]$.
505pub fn evaluate_gaussian_nll(
506    observations: &[f64],
507    means: &[f64],
508    std_devs: &[f64],
509) -> Result<f64, UncertaintyValidationError> {
510    let n = observations.len();
511    if n == 0 || n != means.len() || n != std_devs.len() {
512        return Err(UncertaintyValidationError::InvalidStatisticalSample {
513            reason: "mismatched_nll_slice_lengths",
514        });
515    }
516    let two_pi = 2.0 * core::f64::consts::PI;
517    let mut sum_nll = 0.0f64;
518    for i in 0..n {
519        let y = observations[i];
520        let mu = means[i];
521        let sigma = std_devs[i];
522        if !y.is_finite() || !mu.is_finite() || !sigma.is_finite() || sigma <= 0.0 {
523            return Err(UncertaintyValidationError::InvalidStatisticalSample {
524                reason: "invalid_gaussian_nll_parameters",
525            });
526        }
527        let var = sigma * sigma;
528        let z = (y - mu) / sigma;
529        sum_nll += 0.5 * ((two_pi * var).ln() + z * z);
530    }
531    Ok(sum_nll / (n as f64))
532}
533
534#[inline]
535fn determinant_3x3(m: &[[f64; 3]; 3]) -> f64 {
536    m[0][0] * (m[1][1] * m[2][2] - m[1][2] * m[2][1])
537        - m[0][1] * (m[1][0] * m[2][2] - m[1][2] * m[2][0])
538        + m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0])
539}