blr-active 0.1.0

//! Precision-tier definitions for noise-aware calibration goals.
//!
//! Precision tiers frame calibration targets as multiples of the sensor's
//! inherent noise floor (σ_noise). Four tiers are provided:
//!
//! | Tier     | Factor | Samples (est.) | Use case                        |
//! |----------|--------|----------------|---------------------------------|
//! | Low      | 5.0×   | 10             | Rapid commissioning             |
//! | Moderate | 3.0×   | 25             | Typical production calibration  |
//! | High     | 1.5×   | 60             | Demanding applications          |
//! | Max      | 1.0×   | 200            | Theoretical sensor limit        |
//!
//! **Factor rationale:**
//! - 5× ensures a comfortable margin well above the noise floor; achievable
//!   with very few samples.
//! - 3× is the classical rule-of-thumb ("3-sigma") margin used in measurement
//!   science to separate signal from noise reliably.
//! - 1.5× provides a tight margin; requires significantly more data and is
//!   statistically risky near the noise ceiling.
//! - 1× is the theoretical sensor limit; rarely achievable in practice with
//!   finite data.
//!
//! Sample estimates use the heuristic `ceil(50 / factor²)`, which is derived
//! empirically from typical active Learning convergence rates in BLR+ARD.
//!
//! # Example
//!
//! ```rust
//! use blr_active::precision_tiers::{PrecisionLevel, compute_precision_tiers};
//!
//! let sigma_noise = 0.008; // V
//! let tiers = compute_precision_tiers(sigma_noise);
//!
//! // Low tier: ±0.040 V (5.0×)
//! assert!((tiers[0].absolute_tolerance - 0.040).abs() < 1e-10);
//! // Moderate tier: ±0.024 V (3.0×)
//! assert!((tiers[1].absolute_tolerance - 0.024).abs() < 1e-10);
//! // High tier: ±0.012 V (1.5×)
//! assert!((tiers[2].absolute_tolerance - 0.012).abs() < 1e-10);
//! // Max tier: ±0.008 V (1.0×)
//! assert!((tiers[3].absolute_tolerance - 0.008).abs() < 1e-10);
//! ```

use serde::{Deserialize, Serialize};
use std::fmt;

// ─── PrecisionLevel ───────────────────────────────────────────────────────────

/// Calibration precision goal expressed as a multiple of the sensor noise floor.
///
/// Choose based on the application's tolerance for measurement uncertainty:
/// - **Low** — fastest, coarsest; suitable for rapid commissioning.
/// - **Moderate** — balanced; covers most production use cases.
/// - **High** — demanding; requires substantially more measurements.
/// - **Max** — theoretical limit; rarely achievable with finite data.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum PrecisionLevel {
    /// Target precision = 5× sensor noise. Low accuracy; fast convergence.
    Low,
    /// Target precision = 3× sensor noise. Balanced accuracy and sample cost.
    Moderate,
    /// Target precision = 1.5× sensor noise. High accuracy; significant sample cost.
    High,
    /// Target precision = 1× sensor noise. Sensor-limited; theoretical maximum.
    Max,
}

impl PrecisionLevel {
    /// Noise multiplier for this tier (absolute_tolerance = σ_noise × factor).
    pub fn factor(self) -> f64 {
        match self {
            PrecisionLevel::Low => 5.0,
            PrecisionLevel::Moderate => 3.0,
            PrecisionLevel::High => 1.5,
            PrecisionLevel::Max => 1.0,
        }
    }

    /// Human-readable description of this tier.
    pub fn description(self) -> &'static str {
        match self {
            PrecisionLevel::Low => "Low (5× noise — easy, few samples)",
            PrecisionLevel::Moderate => "Moderate (3× noise — balanced, typical)",
            PrecisionLevel::High => "High (1.5× noise — challenging, many samples)",
            PrecisionLevel::Max => "Maximum (1× noise — sensor-limited, theoretical)",
        }
    }

    /// Heuristic number of samples estimated to reach this tier.
    ///
    /// Derived from the approximation `ceil(50 / factor²)`, calibrated against
    /// typical BLR+ARD active learning convergence rates.
    pub fn estimated_samples(self) -> usize {
        match self {
            PrecisionLevel::Low => 10,
            PrecisionLevel::Moderate => 25,
            PrecisionLevel::High => 60,
            PrecisionLevel::Max => 200,
        }
    }
}

impl fmt::Display for PrecisionLevel {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.description())
    }
}

// ─── Feasibility ──────────────────────────────────────────────────────────────

/// Whether a precision goal is generically reachable given sensor hardware.
///
/// Used in `PrecisionTierInfo` to flag tiers that are inherently at or below
/// the noise floor (Max tier always returns `Marginal` in `compute_precision_tiers`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum Feasibility {
    /// Goal is comfortably above the sensor noise floor. Achievable with data.
    Achievable,
    /// Goal is very close to the noise floor. Risky; may not converge.
    Marginal,
    /// Goal is at or below the noise floor. Impossible with this sensor.
    Unachievable,
}

impl fmt::Display for Feasibility {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Feasibility::Achievable => write!(f, "Achievable"),
            Feasibility::Marginal => write!(f, "Marginal (close to noise floor)"),
            Feasibility::Unachievable => write!(f, "Unachievable (below noise floor)"),
        }
    }
}

// ─── PrecisionTierInfo ────────────────────────────────────────────────────────

/// Computed information for one precision tier given a specific σ_noise.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PrecisionTierInfo {
    /// Which tier this entry describes.
    pub level: PrecisionLevel,
    /// Absolute std target in signal units (σ_noise × factor).
    pub absolute_tolerance: f64,
    /// Heuristic number of samples required to reach this tier.
    pub estimated_samples: usize,
    /// Whether this tier is generically reachable given the noise floor.
    pub feasibility: Feasibility,
}

impl fmt::Display for PrecisionTierInfo {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{:<10} ±{:.4}  ~{:>3} samples  [{}]",
            format!("{:?}", self.level),
            self.absolute_tolerance,
            self.estimated_samples,
            self.feasibility,
        )
    }
}

// ─── compute_precision_tiers ─────────────────────────────────────────────────

/// Compute all four precision tiers for a given sensor noise level.
///
/// Returns an array of four [`PrecisionTierInfo`] structs ordered from loosest
/// (Low) to tightest (Max).
///
/// The Max tier is always marked `Marginal` because achieving 1× noise
/// precision requires an impractically large number of samples and the posterior
/// variance asymptotically approaches (but rarely reaches) the noise floor.
///
/// # Example
///
/// ```rust
/// use blr_active::precision_tiers::{PrecisionLevel, compute_precision_tiers};
///
/// let tiers = compute_precision_tiers(0.008);
/// assert!((tiers[1].absolute_tolerance - 0.024).abs() < 1e-10,
///         "Moderate tier: 3.0 × 0.008 = 0.024");
/// ```
pub fn compute_precision_tiers(sigma_noise: f64) -> [PrecisionTierInfo; 4] {
    let make_tier = |level: PrecisionLevel, feasibility: Feasibility| -> PrecisionTierInfo {
        PrecisionTierInfo {
            absolute_tolerance: sigma_noise * level.factor(),
            estimated_samples: level.estimated_samples(),
            level,
            feasibility,
        }
    };

    [
        make_tier(PrecisionLevel::Low, Feasibility::Achievable),
        make_tier(PrecisionLevel::Moderate, Feasibility::Achievable),
        make_tier(PrecisionLevel::High, Feasibility::Achievable),
        make_tier(PrecisionLevel::Max, Feasibility::Marginal),
    ]
}

// ─── Tests ────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    const SIGMA: f64 = 0.008;

    #[test]
    fn test_precision_tier_low() {
        let tiers = compute_precision_tiers(SIGMA);
        assert!(
            (tiers[0].absolute_tolerance - SIGMA * 5.0).abs() < 1e-10,
            "Low tier factor 5.0"
        );
        assert_eq!(tiers[0].level, PrecisionLevel::Low);
    }

    #[test]
    fn test_precision_tier_moderate() {
        let tiers = compute_precision_tiers(SIGMA);
        assert!(
            (tiers[1].absolute_tolerance - SIGMA * 3.0).abs() < 1e-10,
            "Moderate: 3.0 × 0.008 = 0.024"
        );
        assert_eq!(tiers[1].level, PrecisionLevel::Moderate);
    }

    #[test]
    fn test_precision_tier_high() {
        let tiers = compute_precision_tiers(SIGMA);
        assert!(
            (tiers[2].absolute_tolerance - SIGMA * 1.5).abs() < 1e-10,
            "High tier factor 1.5"
        );
        assert_eq!(tiers[2].level, PrecisionLevel::High);
    }

    #[test]
    fn test_precision_tier_max() {
        let tiers = compute_precision_tiers(SIGMA);
        assert!(
            (tiers[3].absolute_tolerance - SIGMA * 1.0).abs() < 1e-10,
            "Max tier factor 1.0"
        );
        assert_eq!(tiers[3].level, PrecisionLevel::Max);
    }

    #[test]
    fn test_precision_tier_max_is_marginal() {
        let tiers = compute_precision_tiers(SIGMA);
        assert_eq!(
            tiers[3].feasibility,
            Feasibility::Marginal,
            "Max tier is inherently marginal (at noise floor)"
        );
    }

    #[test]
    fn test_precision_tiers_are_monotonically_decreasing() {
        let tiers = compute_precision_tiers(SIGMA);
        for i in 0..3 {
            assert!(
                tiers[i].absolute_tolerance > tiers[i + 1].absolute_tolerance,
                "Tiers should be ordered from loosest to tightest"
            );
        }
    }

    #[test]
    fn test_precision_tier_estimated_samples() {
        assert_eq!(PrecisionLevel::Low.estimated_samples(), 10);
        assert_eq!(PrecisionLevel::Moderate.estimated_samples(), 25);
        assert_eq!(PrecisionLevel::High.estimated_samples(), 60);
        assert_eq!(PrecisionLevel::Max.estimated_samples(), 200);
    }

    #[test]
    fn test_factor_values() {
        assert!((PrecisionLevel::Low.factor() - 5.0).abs() < 1e-10);
        assert!((PrecisionLevel::Moderate.factor() - 3.0).abs() < 1e-10);
        assert!((PrecisionLevel::High.factor() - 1.5).abs() < 1e-10);
        assert!((PrecisionLevel::Max.factor() - 1.0).abs() < 1e-10);
    }
}