Struct StructuredResidualModel 

pub struct StructuredResidualModel { /* private fields */ }

The fitted structured residual-covariance model: low-rank factor Λ, idiosyncratic diagonal D, and the smooth activity-scale c(z) evaluated at every row. Produces per-row precision factors and the MetricProvenance::WhitenedStructured RowMetric.

Implementations

impl StructuredResidualModel

pub fn fit(input: ResidualFactorInput<'_>) -> Result<Self, String>

Fit the structured residual-covariance model by the deterministic fixed-iteration alternation, selecting the factor rank by the evidence ladder. Returns an error only on shape / non-finite-input violations; the numerical path is total (every floor and solve is guarded).

pub fn factor_rank(&self) -> usize

Selected factor rank r.

pub fn factor(&self) -> ArrayView2<'_, f64>

The fitted interference factor Λ ∈ ℝ^{p×r} (the shared off-isotropic residual subspace). Consumed by the planted-subspace recovery test to compare range(Λ) against the planted interference subspace.

pub fn diagonal(&self) -> ArrayView1<'_, f64>

The idiosyncratic diagonal d ∈ ℝ^p (D = diag(d)).

pub fn row_scale(&self) -> ArrayView1<'_, f64>

The per-row activity scale c(z_n) > 0, length n. Recovers the smooth activity-scale law evaluated at every observed z_n.

pub fn log_evidence(&self) -> f64

The penalized Gaussian log-evidence the rank-selection ladder maximized.

pub fn promotion_candidates( &self, prev: Option<&StructuredResidualModel>, align_min: f64, energy_floor_mult: f64, ) -> Result<Vec<FactorPromotion>, String>

#2021 Λ nursery→promotion: detect persistent, evidence-earning factor directions relative to the previous outer-alternation pass’s model.

A column j of this model’s Λ is a FactorPromotion candidate iff both gates hold:

1. Earns its complexity (evidence gate): its explained energy ‖Λ_:,j‖² ≥ energy_floor_mult · mean(diag(D)). Every column is already inside the evidence-ladder-selected rank (so it cleared the BIC penalty globally); this per-direction floor additionally requires the factor to explain more than an average channel’s idiosyncratic noise, so we never promote a direction that only barely survived rank selection.
2. Persists (nursery gate): its |cos| alignment with the best- matching column of prev’s Λ is ≥ align_min — the direction is the same subspace the previous pass already found, not a new pass-to-pass artifact.

Returns candidates sorted by energy (descending). prev = None (the first structured pass, damping toward I) yields no candidates — a direction must survive at least one pass to enter the nursery. The driver holds the cross-pass persistence count (promote after it clears the direction’s nursery dwell) and does the actual atom birth; this method is the pure, per-pass detector.

Errors on non-finite / out-of-range gates (align_min ∈ [0,1], energy_floor_mult ≥ 0) or a prev with a different output dim p.

pub fn row_metric(&self, n_rows: usize) -> Result<RowMetric, String>

Build the per-row precision factor stack U_n ∈ ℝ^{p×p} with U_n U_nᵀ = Σ_n^{-1} and package it as a MetricProvenance::WhitenedStructured RowMetric. This is the single production site of WhitenedStructured.

The precision is formed in Woodbury form:

  Σ_n^{-1} = D^{-1} − D^{-1} Λ ( c^{-1} I_r + Λᵀ D^{-1} Λ )^{-1} Λᵀ D^{-1},

an r × r capacitance solve (never a p × p inverse). The factor U_n is the lower-Cholesky of the assembled Σ_n^{-1} (rank = p), so whiten_residual_row returns coordinates whose squared norm is the exact Mahalanobis residual r_nᵀ Σ_n^{-1} r_n.

pub fn fit_row_metric( input: ResidualFactorInput<'_>, ) -> Result<RowMetric, String>

Convenience for the #2021 fit-path install seam: fit the structured residual model on input and immediately materialize its per-row WhitenedStructured RowMetric over all input.residuals.nrows() rows. Equivalent to Self::fit(input)?.row_metric(n) — the single call the outer alternation loop consumes when it installs the whitening metric but does not also need the fitted factor (factor() / birth mining).

pub fn row_metric_damped( &self, n_rows: usize, gamma: f64, prev: Option<&StructuredResidualModel>, ) -> Result<RowMetric, String>

Damped per-row metric for the #2021 driver: blend covariances in the covariance domain (before the Woodbury→Cholesky) between this model’s estimate and a previous one,

  Σ_t(row) = (1 − γ) · Σ_prev(row) + γ · Σ̂_t(row),

where Σ̂_t(row) = c_t(z)·ΛΛᵀ + D is this model’s per-row covariance (built from the hoisted-M0 / occupancy-weighted c(z) path), and Σ_prev(row) is prev’s per-row covariance when Some, else I_p. The returned factor U_n satisfies U_n U_nᵀ = Σ_t(row)^{-1}, packaged as a RowMetric.

Endpoints (exact, byte-identical to the undamped producers):

• γ = 1.0 ⇒ this model’s Self::row_metric exactly (Woodbury path);
• γ = 0.0 ⇒ prev’s Self::row_metric when Some, else the Euclidean identity metric.

γ must be finite and in [0, 1]; when prev is Some it must share this model’s p and row count.

Trait Implementations

impl Clone for StructuredResidualModel

fn clone(&self) -> StructuredResidualModel

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StructuredResidualModel

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

Formats the value using the given formatter.