Struct Gauge 

pub struct Gauge {
    pub t_full: Array2<f64>,
    pub affine_shift: Array1<f64>,
    pub block_starts_raw: Vec<usize>,
    pub block_starts_reduced: Vec<usize>,
}

The lift T : reduced → raw plus the per-block partitions of both coordinate systems. See the module docs for the lift conventions.

Fields

t_full: Array2<f64>

Global lift matrix, shape (Σ p_b_raw) × (Σ r_b_reduced).

affine_shift: Array1<f64>

Global affine shift in raw coordinates, length Σ p_b_raw.

block_starts_raw: Vec<usize>

Raw-coordinate block partition: block_starts_raw[b]..block_starts_raw[b+1] is block b’s raw row range in t_full. Length n_blocks + 1, starts at 0.

block_starts_reduced: Vec<usize>

Reduced-coordinate block partition (columns of t_full), same layout.

Implementations

impl Gauge

pub fn identity(raw_widths: &[usize]) -> Self

The trivial section: raw == reduced for every block.

pub fn from_block_transforms(transforms: &[Array2<f64>]) -> Self

Block-diagonal section from independent per-block lifts T_b : reduced_b → raw_b (selection matrices from the canonical audit, orthogonalisation V_bs, or their compositions).

pub fn from_block_transforms_with_shift( transforms: &[Array2<f64>], affine_shift: Array1<f64>, ) -> Self

Block-diagonal affine section from independent per-block lifts plus one concatenated raw-coordinate shift.

pub fn from_block_transform_with_shift( transform: Array2<f64>, affine_shift: Array1<f64>, ) -> Self

Single-block affine section.

pub fn from_v_and_r( v_per_term: &[Array2<f64>], r_per_term: &[Option<Array2<f64>>], ) -> Self

Block-upper-triangular section from per-block V_b plus cross-block residualisation stacks R_{a→b} — see assemble_block_triangular_t for the packing convention.

pub fn sum_to_zero(z: Array2<f64>) -> Self

The sum-to-zero (centering) section as a first-class single-block gauge. z is the (k × (k−1)) reparametrisation matrix returned by terms::basis::duchon_thinplate::apply_sum_to_zero_constraint (an orthonormal basis for null(cᵀ), c = Bᵀw the weighted column sums): the constrained design is B_c = B · z, so on the model η = B · β_raw = B_c · θ = B · z · θ the raw coefficients lift back from the reduced (centred) coefficients by exactly β_raw = z · θ.

That is the one Gauge convention with T = z over a single block, so the centring constraint stops being a special-cased outside-the-object transform and becomes a Gauge section like every other reduction: the covariance / penalised-Hessian of the centred fit pushes forward to the raw basis through the SAME z via Gauge::lift_covariance.

z is taken as the section itself (rather than recomputed from a basis) because the constraint matrix is the only gauge-relevant artifact — the basis the column sums were taken over is irrelevant to the lift. The only requirement is the structural one of a centring section: z.ncols() < z.nrows() (at least one direction is removed); an identity z would be Gauge::identity and is rejected so callers do not silently treat an unconstrained block as centred.

pub fn from_t( t_full: Array2<f64>, raw_widths: &[usize], reduced_widths: &[usize], ) -> Self

Wrap an already-assembled global T given the per-block raw and reduced width partitions.

pub fn from_t_with_shift( t_full: Array2<f64>, raw_widths: &[usize], reduced_widths: &[usize], affine_shift: Array1<f64>, ) -> Self

Wrap an already-assembled global affine section β = Tθ + a given the per-block raw and reduced width partitions.

pub fn from_compiled_map<M: CompiledBlockMap, O>( map: &M, ordering: &[O], ) -> Self

Build from a compiled identifiability reparametrisation (see CompiledBlockMap, implemented for the CompiledMap emitted by the identifiability compiler): map.raw_from_compiled() IS the global triangular T, and the block ranges give both partitions. ordering is accepted purely as a length sanity check.

pub fn n_blocks(&self) -> usize

Number of blocks in the partition.

pub fn raw_total(&self) -> usize

Total raw width Σ p_b.

pub fn reduced_total(&self) -> usize

Total reduced width Σ r_b.

pub fn raw_widths(&self) -> Vec<usize>

Per-block raw widths.

pub fn reduced_widths(&self) -> Vec<usize>

Per-block reduced widths.

pub fn block_transform(&self, b: usize) -> Array2<f64>

The diagonal slab T_b = T[raw_b, reduced_b] of block b. For a block-diagonal gauge this is the whole story for the block; for a triangular gauge it omits the cross-block −R.

pub fn restrict_design<S: Data<Elem = f64>>( &self, raw_design: &ArrayBase<S, Ix2>, ) -> Array2<f64>

Compose a raw design with the section: X_reduced = X_raw · T.

pub fn restrict_design_and_offset<S: Data<Elem = f64>>( &self, raw_design: &ArrayBase<S, Ix2>, raw_offset: &Array1<f64>, ) -> (Array2<f64>, Array1<f64>)

Compose a raw design and offset with the affine section: X_raw · (Tθ + a) + o_raw = (X_raw · T)θ + (o_raw + X_raw · a).

pub fn restrict_penalty<S: Data<Elem = f64>>( &self, raw_penalty: &ArrayBase<S, Ix2>, ) -> Array2<f64>

Pull a raw-coordinate quadratic form back to reduced coordinates: S_reduced = Tᵀ · S_raw · T.

pub fn extend_with_identity(&self, extra_raw_widths: &[usize]) -> Self

Append blocks that were never reduced (raw == reduced, identity lift). Used to lift joint objects that span both gauged blocks and untouched ones (e.g. the survival flex blocks alongside the compiled parametric blocks).

pub fn lift_block_betas( &self, reduced_block_betas: &[Array1<f64>], ) -> Vec<Array1<f64>>

Lift per-block reduced coefficients to per-block raw coefficients: concatenate into θ, apply β = T · θ + a, split at the raw partition.

pub fn lift_covariance(&self, m_reduced: &Array2<f64>) -> Array2<f64>

Push a reduced-coordinate symmetric matrix (posterior covariance, penalized Hessian — any symmetric bilinear form on θ) forward to raw coordinates via the exact sandwich M_raw = T · M_θ · Tᵀ.

The result is explicitly symmetrised: T · M · Tᵀ is symmetric for symmetric M, but the two matmuls accumulate independent rounding, so the transpose pair is averaged to land an exactly symmetric matrix for downstream Cholesky / eigensolves.

Trait Implementations

impl Clone for Gauge

fn clone(&self) -> Gauge

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Gauge

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

Formats the value using the given formatter.