Struct PenaltyNullSplit 

pub struct PenaltyNullSplit { /* private fields */ }

The λ-invariant declared-null subspace of a penalty reparameterization, materialized in both coefficient frames (#2454).

The invariant this type exists to hold

gam.reparam keeps only balanced-penalty eigendirections above a relative rank tolerance and rebuilds the penalty the model applies as S̃(λ) = E(λ)ᵀE(λ) on that subspace alone. Everything the criterion is made of is a function of S̃: the inner solve minimizes −ℓ + ½βᵀS̃β, H = −∇²ℓ + S̃, and the reported penalty energy is ‖E β̂‖².

A per-block S_k whose own root rank exceeds the split’s penalized rank therefore describes a DIFFERENT penalty. Two things go wrong if one is used anywhere the criterion is differentiated or normalized:

1. ½ λ_k β̂ᵀS_kβ̂ charges β̂’s energy in directions S̃ never penalized — and β̂ is free there, so that energy is O(1) and ∂/∂ρ_k multiplies it by λ_k. That is an additive c·λ in the outer gradient, invisible at ‖ρ‖ ≤ 1 and sign-flipping it a dozen e-folds up.
2. −½log|Σ_k λ_k S_k|₊ charges MORE directions than ½log|H| can ever inflate, because H’s penalty part is S̃. The two halves of the LAML ratio then saturate at different rates and the criterion acquires an asymptotic slope of ½(rank(S̃) − rank(S)) per unit ρ — unbounded below, with no interior optimum and no certifiable λ=∞ rail.

Projecting restores the identity every outer derivative is built on: Σ_k λ_k (Π S_k Π) = Π (Σ_k λ_k S_k) Π = S̃(λ), and because Π is λ-invariant by construction, ∂S̃/∂ρ_k = λ_k · Π S_k Π exactly. One penalty object then serves the value, the quadratic, the per-block scores, the tr(H⁻¹Ḣ_k) drift, the log|S|₊ and its rank, and the outer Hessian.

A None basis means “nothing declared null” and every project is the identity, which is the case for any penalty whose numerical rank agrees with the split’s.

Implementations

impl PenaltyNullSplit

pub fn identity() -> Self

The identity split: nothing is declared null, every projection is a no-op. This is what a penalty system with no dense reparameterization (Kronecker marginal grids, sparse-native identity frames) carries.

pub fn declared_null_dim(&self) -> usize

The number of declared-null directions, or 0 for the identity split.

pub fn basis(&self, frame: PenaltyFrame) -> Option<&Array2<f64>>

The declared-null basis in frame, if this split declares anything.

pub fn project_canonical( &self, penalty: &CanonicalPenalty, frame: PenaltyFrame, ) -> Result<CanonicalPenalty, EstimationError>

Π S_k Π for a canonical penalty expressed in frame.

The penalty is returned unchanged when this split declares nothing null, or when the basis does not match the penalty’s dimension — a shape disagreement the projection must not paper over by guessing.

pub fn project_coordinate( &self, coord: &PenaltyCoordinate, frame: PenaltyFrame, ) -> PenaltyCoordinate

Π S_k Π for a solver-side penalty coordinate expressed in frame.

Trait Implementations

impl Clone for PenaltyNullSplit

fn clone(&self) -> PenaltyNullSplit

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PenaltyNullSplit

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.