Struct BasisBuildResult 

pub struct BasisBuildResult {
    pub design: DesignMatrix,
    pub penalties: Vec<Array2<f64>>,
    pub nullspace_dims: Vec<usize>,
    pub penaltyinfo: Vec<PenaltyInfo>,
    pub metadata: BasisMetadata,
    pub kronecker_factored: Option<KroneckerFactoredBasis>,
    pub ops: Vec<Option<Arc<dyn PenaltyOp>>>,
    pub null_eigenvectors: Vec<Option<Array2<f64>>>,
    pub joint_null_rotation: Option<JointNullRotation>,
}

Standardized basis build result for engine-level composition.

Fields

design: DesignMatrix

penalties: Vec<Array2<f64>>

nullspace_dims: Vec<usize>

penaltyinfo: Vec<PenaltyInfo>

metadata: BasisMetadata

kronecker_factored: Option<KroneckerFactoredBasis>

Optional factored rowwise-Kronecker representation for tensor-product bases. When present, downstream code can keep the design operator-backed instead of forcing a fully materialized n x prod(q_j) block.

ops: Vec<Option<Arc<dyn PenaltyOp>>>

Per-active-penalty operator handles (parallel to penalties). Each entry is Some(op) when the closed-form factory emitted an op-form penalty bit-equivalent to the dense matrix, None for ordinary dense penalties. Downstream consumers route through the Some entries to avoid materializing dense p x p Grams in exact operator algebra.

null_eigenvectors: Vec<Option<Array2<f64>>>

Per-active-penalty null-space eigenvector matrices (parallel to penalties). Each entry is Some(U_null) with U_null.ncols() == nullspace_dims[k] when the active block has a non-trivial null space (eigenvalues ≤ spectral tolerance), and None when the block is already full-rank. The columns of U_null are the eigenvectors of sym_penalty at the (near-)zero eigenvalues — i.e., an orthonormal basis of null(S_block) in the block’s own coordinate system.

This is the raw spectral data that the construction pipeline uses to absorb each smooth’s penalty null space into the parametric block (reparameterize-and-split). Without absorption the inner Newton solve cannot converge on data whose unpenalized signal lies along a null direction of S (phantom-multiplier refusal at the KKT certificate).

joint_null_rotation: Option<JointNullRotation>

Joint-null absorption rotation for this basis, when the basis carries any penalties with a non-trivial joint null space.

Some(rotation) records Q = [U_range | U_null] where U_null spans the joint null space null(Σ_k S_k) over this basis’s active penalties (unscaled — the structural joint null is independent of λ). After the basis pipeline applies this rotation, the design becomes X · Q and each penalty becomes Qᵀ S_k Q, block-diagonal with a guaranteed-zero null tail. The same Q must be replayed at prediction time, so it is persisted in the fitted model. None indicates either no penalties on this basis, or a full-rank joint penalty (joint nullity = 0). A Some value is never recorded with joint_nullity == 0 — the None discriminant is canonical for “nothing to absorb”.

Stage-2 commit A: this field is plumbed into the struct but neither computed nor applied yet. Stage-2 commit B populates it; Stage-2 commit D applies the rotation to design and penalties.

Trait Implementations

impl Clone for BasisBuildResult

fn clone(&self) -> BasisBuildResult

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BasisBuildResult

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

Formats the value using the given formatter.