1use crate::q42::science_validation::stokes_mueller::{C02_ROUNDING_FACTOR, F64_EPS};
16
17#[derive(Debug, Clone, Copy, PartialEq)]
19pub enum UncertaintyKind {
20 StandardAbsolute,
22 ExpandedAbsolute {
25 coverage_factor_k: f64,
26 confidence_probability: f64,
27 },
28 Relative,
30}
31
32#[derive(Debug, Clone, Copy, PartialEq, Eq)]
34pub enum CalibrationStage {
35 RawCounts,
37 CalibratedPhysical,
39 DigitalUnrelated,
41}
42
43#[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#[derive(Debug, Clone, PartialEq)]
56pub enum UncertaintyValidationError {
57 InvalidUncertaintyValue { value: f64 },
59 MissingTargetQuantityOrUnit,
61 MixedUnitScalarBroadcastForbidden,
63 GaussianCoverageMismatch {
65 k: f64,
66 claimed_probability: f64,
67 expected_probability: f64,
68 abs_diff: f64,
69 tolerance: f64,
70 },
71 InvalidAffineCalibration { scale: f64, offset: f64 },
73 DoubleCalibrationForbidden {
76 stage: CalibrationStage,
77 units_per_sample: f64,
78 offset: f64,
79 },
80 CalibrationWindowExpiredOrInvalid {
82 sample_tick: i128,
83 from_tick: i128,
84 until_tick: i128,
85 },
86 InvalidCovarianceMatrix {
88 reason: &'static str,
89 value: f64,
90 },
91 CovarianceRotationInvarianceViolation {
93 trace_before: f64,
94 trace_after: f64,
95 det_before: f64,
96 det_after: f64,
97 },
98 InvalidStatisticalSample { reason: &'static str },
100 StatisticalCalibrationExceeded {
102 metric_name: &'static str,
103 observed: f64,
104 threshold: f64,
105 },
106}
107
108pub 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 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 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#[inline]
170pub fn gaussian_coverage_probability(k: f64) -> f64 {
171 erf_f64(k / core::f64::consts::SQRT_2)
172}
173
174pub 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
204pub 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
232pub 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 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
290pub 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
309pub 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
353pub 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
389pub 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 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#[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
433pub 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
503pub 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}