Struct FactoredFrameKroneckerOp 

pub struct FactoredFrameKroneckerOp {
    pub ranks: Vec<usize>,
    pub basis_sizes: Vec<usize>,
    pub offsets: Vec<usize>,
    pub dim: usize,
    pub blocks: Vec<FactoredFrameGBlock>,
}

Frame-factored data-fit Gauss–Newton β-Hessian operator (#972 / #977 T1): the Σ_k M_k·r_k reduced-border analogue of SparseBlockKroneckerPenaltyOp.

When every atom’s decoder B_k = C_k U_kᵀ is profiled onto a Grassmann frame U_k ∈ St(p, r_k), the border carries only the shape coefficients C_k (M_k · r_k entries) instead of the full B_k (M_k · p). The data Gram in this reduced space is, for the isotropic likelihood, H[(i,li,a),(j,lj,b)] = G_{ij}[li,lj] · (U_iᵀ U_j)[a,b] — within an atom the orthonormal frame gives U_iᵀU_i = I_{r_i} and the block is the clean G ⊗ I_r collapse; across co-active atoms the frames do not share a basis so the output factor is the dense U_iᵀU_j.

The β layout is μ-major / frame-minor with a variable per-atom width r_k: the index of (atom k, basis li, frame coord a) is offset[k] + li·r_k + a, where offset is the prefix sum of M_k · r_k. With every r_k = p and U_k = I_p this reproduces SparseBlockKroneckerPenaltyOp exactly (a unit test pins the reduction), so it is a strict generalization, not a separate code path.

Fields

ranks: Vec<usize>

Per-atom frame rank r_k (the factored output width).

basis_sizes: Vec<usize>

Per-atom basis size M_k.

offsets: Vec<usize>

Per-atom β offset (prefix sum of M_k · r_k); offsets[k] is the start of atom k’s C_k block, offsets[n_atoms] the total dim.

dim: usize

Total reduced β dimension Σ_k M_k · r_k.

blocks: Vec<FactoredFrameGBlock>

Non-empty co-occurring (atom_i, atom_j) blocks.

Implementations

impl FactoredFrameKroneckerOp

pub fn new( ranks: Vec<usize>, basis_sizes: Vec<usize>, blocks: Vec<FactoredFrameGBlock>, ) -> Result<Self, String>

Build from per-atom ranks + basis sizes and the co-occurring blocks. Computes the β offsets (prefix sum of M_k·r_k) and validates that each block’s g/w shapes match the atoms’ (M, r).

pub fn from_frames_and_blocks( frames: &[Option<Array2<f64>>], basis_sizes: &[usize], p: usize, g_blocks: &BTreeMap<(usize, usize), Array2<f64>>, ) -> Result<Self, String>

Convenience constructor that builds the operator directly from per-atom output frames + the basis-space Gram block map, computing the per-pair frame factors W_ij = U_iᵀ U_j itself.

frames[k] is either Some(U_k) — a p × r_k (r_k ≤ p) output frame (a Grassmann representative St(p, r_k) need not be orthonormal here; the W factor carries whatever frame is supplied) — or None, meaning atom k keeps the full ambient output (U_k = I_p, so r_k = p). For each non-empty Gram block (atom_i, atom_j) the factor W is U_iᵀ U_j (r_i × r_j), with the None frame standing in for I_p: a framed×unframed cross gives W = U_iᵀ (r_i × p) and an unframed diagonal gives W = I_p — exactly reproducing the g ⊗ I_p full-B block. The resulting blocks are handed to Self::new, which validates the (M, r) shapes and computes the β offsets.

Trait Implementations

impl BetaPenaltyOp for FactoredFrameKroneckerOp

fn dim(&self) -> usize

Full dimension K of the β vector.

fn matvec(&self, x: &[f64], y: &mut [f64])

y += P x — penalty Hessian-vector product (length K).

fn gradient(&self, beta: &[f64], out: &mut [f64])

Penalty gradient: out += P β.

fn diagonal(&self, diag: &mut [f64])

diag += diag(P) — diagonal entries used by Jacobi preconditioner.

fn block( &self, id: BetaBlockId, offsets: &[Range<usize>], out: &mut Array2<f64>, )

Add the b×b dense penalty sub-block for block id into out (row-major, block size b = offsets[id.0].len()). Used by the block-Jacobi Schur preconditioner (#287).

fn to_dense(&self) -> Array2<f64>

Materialize the full K×K dense penalty matrix (needed by Direct / SqrtBA modes that form the Schur complement explicitly).

fn fingerprint(&self, hasher: &mut Fingerprinter)

Mix the operator’s defining state into hasher for cache-validity fingerprinting. Must change whenever matvec / to_dense would change, so the factorization / evidence cache (cache_matches_system) is invalidated when the β-block content changes. Implementations hash their own compact defining data (e.g. Kronecker factors, block matrices) rather than the full K×K dense form, which would defeat the structured operator’s storage savings.

fn row_abs_sums(&self) -> Array1<f64>

Per-row absolute-value sums out[r] = Σ_c |P[r,c]|, the row contribution to the operator’s ∞-norm. The default folds to_dense(), which costs an O(K²) materialization; structured operators override this to fold their compact factors directly so the backward-error certificate’s arrow_operator_infinity_norm never builds a dense K×K matrix on the SAE LLM-border critical path (#1017). Overrides MUST agree bit-for-bit with the to_dense() row sums (verified by the cross-check tests).