gam-linalg 0.3.155

use serde::{Deserialize, Serialize};

/// Structurally valid ways a diagonal ridge may participate in a computation.
///
/// The former public boolean matrix admitted contradictory states such as a
/// quadratic penalty without the corresponding Hessian. This enum has only
/// the coherent inhabitants the engine actually selects.
///
/// # Why there is no approximate-determinant inhabitant (#2670)
///
/// A third variant, `PositivePartApproximateObjective`, used to route the ridged
/// log-determinant through a smooth positive-part spectral approximation
/// (`log|A|_reg = Σ log r_ε(σ_j)`), which is a DIFFERENT estimand from the exact
/// SPD determinant and was named as such. Nothing in production ever selected
/// it: every construction of it lived under `#[cfg(test)]`, so the only thing it
/// bought the library was a second, worse answer a user could opt into by
/// mistake. It is deleted rather than kept as a fallback — a preserved fallback
/// is a second implementation of the same quantity, and this one changed the
/// estimand while doing it.
///
/// The smooth regulariser itself is NOT deleted and was never this enum's
/// business: `spectral_regularize` / `spectral_epsilon` stay live in the REML
/// outer engine's `DenseSpectralOperator`, where a caller genuinely wants the
/// smooth surrogate together with its matching analytic gradient.
///
/// With one determinant semantics left there is no `determinant_mode()` and no
/// `RidgeDeterminantMode`: a query whose answer is a constant is not a query.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum RidgePolicy {
    /// Ridge is an explicit part of the exact objective: quadratic, penalty
    /// normalizer, and Laplace Hessian all include it, using a full SPD logdet.
    ExactFullObjective,
    /// Ridge changes only an inner linear solve and never the fitted objective,
    /// exported Hessian, determinant, covariance, or serialized model.
    SolverOnly,
}

impl RidgePolicy {
    pub const fn exact_full_objective() -> Self {
        Self::ExactFullObjective
    }

    pub const fn solver_only() -> Self {
        Self::SolverOnly
    }

    #[inline]
    pub const fn accounts_for_objective(self) -> bool {
        !matches!(self, Self::SolverOnly)
    }
}

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

    #[test]
    fn exact_policy_accounts_for_the_objective() {
        assert!(RidgePolicy::exact_full_objective().accounts_for_objective());
    }

    #[test]
    fn solver_only_policy_cannot_enter_objective_accounting() {
        assert!(!RidgePolicy::solver_only().accounts_for_objective());
    }

    /// #2670 — the inhabitants are exactly the two the engine selects. A third
    /// would have to be a second answer to the same question, which is what the
    /// deleted positive-part variant was.
    ///
    /// Two checks of the same property, and they fail at different times, which
    /// is why both are here. The irrefutable `let` is a COMPILE-TIME assertion:
    /// re-adding a variant makes the pattern refutable and this file stops
    /// compiling. The runtime assertions below say the constructors between them
    /// still reach BOTH inhabitants and reach each exactly once — a compile-time
    /// check cannot see a constructor that was quietly re-pointed at its
    /// sibling, and the enum would still have two inhabitants while the engine
    /// could only select one (#2818: a test that reaches no runtime assertion
    /// passes for every behaviour of the code it calls).
    #[test]
    fn the_policy_has_no_third_inhabitant() {
        let constructed = [
            RidgePolicy::exact_full_objective(),
            RidgePolicy::solver_only(),
        ];
        let mut exact = 0usize;
        let mut solver = 0usize;
        for policy in constructed {
            let (RidgePolicy::ExactFullObjective | RidgePolicy::SolverOnly) = policy;
            match policy {
                RidgePolicy::ExactFullObjective => exact += 1,
                RidgePolicy::SolverOnly => solver += 1,
            }
        }
        assert_eq!(
            (exact, solver),
            (1, 1),
            "the two constructors must reach the two distinct inhabitants, once each"
        );
        assert_ne!(
            constructed[0], constructed[1],
            "a constructor re-pointed at its sibling leaves the enum's arity intact \
             and the engine with one selectable policy"
        );
    }
}