Struct JointPenaltySpec 

pub struct JointPenaltySpec {
    pub label: Option<String>,
    pub matrix: ArrayBase<OwnedRepr<f64>, Dim<[usize; 2]>>,
    pub initial_log_lambda: f64,
    pub nullspace_dim: usize,
    pub group: Option<usize>,
}

A penalty whose support spans the entire compiled parameter vector.

Unlike crate::families::custom_family::PenaltyMatrix, this carries a single dense total_compiled × total_compiled quadratic form — the shape produced by T^T S_j T pullback after the V+M / SMGS-exact compile. The nullspace_dim is the structural dimension of ker(S) as reported by the construction site (rank-revealing on the pulled-back operator, not the pre-pullback S_j), so the REML pseudo-logdet can avoid numerical rank thresholds.

Fields

label: Option<String>

Optional user-visible precision label. Joint penalties that share a label share one smoothing parameter (same convention as crate::families::custom_family::PenaltyMatrix::Labeled).

matrix: ArrayBase<OwnedRepr<f64>, Dim<[usize; 2]>>

Dense symmetric PSD matrix of shape (total_compiled, total_compiled).

initial_log_lambda: f64

Initial value of log λ for this penalty.

nullspace_dim: usize

Structural nullspace dimension of matrix (i.e. total_compiled - rank).

group: Option<usize>

Optional term grouping, declared by the producing family.

Specs sharing a group are the SAME smooth term seen through different class contrasts, so a relabeling permutes them among themselves. Any consumer that needs a reference-INVARIANT quantity per term must aggregate over the group rather than read one spec: an individual spec’s matrix is expressed in the stacked ALR basis, whose meaning depends on which class is the reference (#2579). This is deliberately a declared integer and not something recovered by parsing Self::label — a substring classifier over a formatted name is exactly the failure #2593 was closed for.

None means “stands alone”, which is every family that does not group.

Implementations

impl JointPenaltySpec

pub fn dim(&self) -> usize

Total compiled parameter count this penalty acts on.

pub fn trace(&self) -> f64

Trace of the penalty matrix (Σ_i S[i,i]).

pub fn pseudo_rank(&self) -> usize

Structural pseudo-rank, derived from the declared nullspace_dim. This is the rank used by the REML pseudo-logdet under the no-numerical-thresholds policy in the surrounding code.

pub fn quadratic_form( &self, beta: ArrayBase<ViewRepr<&f64>, Dim<[usize; 1]>>, ) -> f64

Quadratic form βᵀ S β. Mirrors crate::families::custom_family::PenaltyMatrix::quadratic_form for the full-width case.

pub fn validated_root( &self, ) -> Result<ArrayBase<OwnedRepr<f64>, Dim<[usize; 2]>>, JointPenaltyError>

Validate shape, finiteness, symmetry, PSD, and nullspace bookkeeping, returning the invariant thin root R such that matrix = RᵀR.

Joint-penalty strengths vary throughout an outer optimization, but the component matrices do not. Returning the root from the same eigendecomposition that validates the component lets callers retain it as penalty geometry instead of repeating one O(p³) decomposition per component on every objective evaluation.

pub fn validate(&self) -> Result<(), JointPenaltyError>

Validate this joint penalty without retaining its spectral root.

Trait Implementations

impl Clone for JointPenaltySpec

fn clone(&self) -> JointPenaltySpec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for JointPenaltySpec

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

Formats the value using the given formatter.