Enum PenaltyMatrix 

pub enum PenaltyMatrix {
    Dense(Array2<f64>),
    KroneckerFactored {
        left: Array2<f64>,
        right: Array2<f64>,
    },
    Blockwise {
        local: Array2<f64>,
        col_range: Range<usize>,
        total_dim: usize,
    },
    Labeled {
        label: String,
        inner: Box<PenaltyMatrix>,
    },
    Fixed {
        log_lambda: f64,
        inner: Box<PenaltyMatrix>,
    },
}

A penalty matrix that may be stored in Kronecker-factored form.

For tensor-product terms (e.g. time-varying survival covariates), the penalty has the structure S = left ⊗ right (Kronecker product). Keeping this factored avoids materializing (p_left × p_right)² dense entries and enables exact log-determinant computation via log|A ⊗ B| = n_B log|A| + n_A log|B|.

Dense penalties are stored as-is. Callers that need a raw Array2<f64> can call as_dense() (zero-cost for Dense, lazy-materialized for KroneckerFactored).

Variants

Dense(Array2<f64>)

KroneckerFactored

Fields

left: Array2<f64>

right: Array2<f64>

Blockwise

Block-local penalty: local is block_dim × block_dim, embedded at col_range in the full parameter space of dimension total_dim. Avoids materializing the full total_dim × total_dim matrix.

Fields

local: Array2<f64>

col_range: Range<usize>

total_dim: usize

Labeled

Wrapper assigning this penalty component to a user-visible precision label. Components with the same label share one smoothing parameter.

Fields

label: String

inner: Box<PenaltyMatrix>

Fixed

Wrapper fixing this penalty component at a physical log-precision. Fixed components remain in the block-local physical penalty layout but are removed from the REML outer coordinate vector.

Fields

log_lambda: f64

inner: Box<PenaltyMatrix>

Implementations

impl PenaltyMatrix

pub fn dim(&self) -> usize

Number of rows (= number of columns, since penalties are square).

pub fn shape(&self) -> (usize, usize)

Returns (nrows, ncols) like Array2::dim().

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

Materialize the full dense matrix.

pub fn as_dense_cow(&self) -> Cow<'_, Array2<f64>>

Borrow the inner dense matrix if Dense, otherwise materialize.

pub fn as_dense_ref(&self) -> Option<&Array2<f64>>

Returns a reference to the inner matrix if this is a Dense variant.

pub fn with_precision_label(self, label: impl Into<String>) -> Self

pub fn precision_label(&self) -> Option<&str>

pub fn with_fixed_log_lambda(self, log_lambda: f64) -> Self

pub fn fixed_log_lambda(&self) -> Option<f64>

pub fn dot(&self, v: &Array1<f64>) -> Array1<f64>

Compute S * v using the row-major Kronecker vec trick when factored: (A ⊗ B) vec_rm(V) = vec_rm(A V Bᵀ) where V = reshape(v, (p_left, p_right)).

pub fn add_scaled_to(&self, lambda: f64, target: &mut Array2<f64>)

Add λ * self to a mutable dense accumulator.

pub fn add_scaled_diag_to(&self, lambda: f64, target: &mut Array1<f64>)

Add λ * diag(self) to a mutable diagonal accumulator.

pub fn quadratic_form(&self, beta: &Array1<f64>) -> f64

Compute the quadratic form β’ S β.

pub fn nrows(&self) -> usize

Access dimensions like an Array2.

pub fn ncols(&self) -> usize

Trait Implementations

impl Clone for PenaltyMatrix

fn clone(&self) -> PenaltyMatrix

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PenaltyMatrix

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

Formats the value using the given formatter.

impl From<ArrayBase<OwnedRepr<f64>, Dim<[usize; 2]>>> for PenaltyMatrix

fn from(m: Array2<f64>) -> Self

Converts to this type from the input type.