Struct ParameterBlockSpec 

pub struct ParameterBlockSpec {
    pub name: String,
    pub design: DesignMatrix,
    pub offset: Array1<f64>,
    pub penalties: Vec<PenaltyMatrix>,
    pub nullspace_dims: Vec<usize>,
    pub initial_log_lambdas: Array1<f64>,
    pub initial_beta: Option<Array1<f64>>,
    pub gauge_priority: u8,
    pub jacobian_callback: Option<Arc<dyn BlockEffectiveJacobian>>,
    pub stacked_design: Option<DesignMatrix>,
    pub stacked_offset: Option<Array1<f64>>,
}

Static specification for one parameter block in a custom family.

design and stacked_design are two structurally distinct operators:

• design is the canonical, single-channel, n-observation operator. design.nrows() ALWAYS equals n_obs (one row per training observation). This is the matrix the identifiability audit, the shape policy, and every “what shape is this block?” reader inspect. For most blocks design is also the eta-producing operator used by the solver — see Self::solver_design.
• stacked_design, when Some, is the multi-channel eta-producing operator used by the solver. Survival time-varying blocks stack [exit; entry; deriv] into a (3·n × p) operator here so the solver can produce a 3·n-long eta in one mat-vec; the audit never sees this matrix. When None, the solver uses design (the single-channel default).

The single contract that downstream code can rely on: design.nrows() == n_obs. No more dual semantics on design.

Read access:

• Audit / canonicalize / “n_obs is the row count” code → &spec.design.
• Eta-producing solver code → Self::solver_design.

Fields

name: String

design: DesignMatrix

offset: Array1<f64>

penalties: Vec<PenaltyMatrix>

Block-local penalty matrices (all p_block x p_block).

nullspace_dims: Vec<usize>

Structural nullspace dimension of each penalty matrix (same length as penalties). Used by the penalty pseudo-logdet to determine rank without numerical thresholds. If empty, falls back to eigenvalue-based rank detection.

initial_log_lambdas: Array1<f64>

Initial log-smoothing parameters for this block (same length as penalties).

initial_beta: Option<Array1<f64>>

Optional initial coefficients (defaults to zeros if omitted).

gauge_priority: u8

Gauge ownership priority. Higher = more likely to retain a redundant direction during canonical-gauge reparameterisation. Defaults to 100. Set higher for blocks that should “own” shared affine/null-space directions (e.g. baseline time in survival).

jacobian_callback: Option<Arc<dyn BlockEffectiveJacobian>>

Full β-dependent Jacobian callback. When Some, this is the authoritative source for effective_jacobian_at. For simple single-output row-scaled blocks use RowScaledJacobian.

stacked_design: Option<DesignMatrix>

Optional multi-channel eta-producing operator used by the solver.

When Some, the solver consumes this matrix (typically (k·n × p) for k stacked channels — e.g. survival [exit; entry; deriv] with k = 3) to evaluate eta = stacked · β + stacked_offset. The audit and shape policy NEVER read this field; they only ever inspect design (which always has n_obs rows).

When None, the solver falls back to design — the correct behavior for every single-channel block (i.e. all non-survival time-varying blocks).

Read this field via Self::solver_design, never directly.

Invariant: when stacked_design = Some(_), stacked_offset MUST also be Some(_) and its length MUST equal stacked_design.nrows().

stacked_offset: Option<Array1<f64>>

Optional offset paired with Self::stacked_design. Same Option state as stacked_design (both Some or both None). Read via Self::solver_offset.

Implementations

impl ParameterBlockSpec

pub fn defaults() -> Self

Returns a ParameterBlockSpec with sensible defaults for all optional fields. Callers using struct literal syntax can use ..ParameterBlockSpec::defaults() to fill in any fields added after the literal was written.

pub fn solver_design(&self) -> &DesignMatrix

Returns the eta-producing operator used by the solver.

Resolution order:

1. stacked_design = Some(d) → return d (multi-channel operator, e.g. (3n × p) for survival time-varying blocks).
2. otherwise → return &self.design (the single-channel default).

Solver code that needs eta = D · β MUST call this accessor; reading &self.design directly silently breaks multi-channel (survival LS time-varying) blocks because self.design.nrows() always equals n_obs, never 3·n_obs.

pub fn solver_offset(&self) -> &Array1<f64>

Returns the offset paired with Self::solver_design. When stacked_offset = Some(o) this returns &o; otherwise it falls back to &self.offset.

pub fn effective_design(&self, caller: &str) -> Result<Array2<f64>, String>

Returns the effective design D_eff for this block at β = 0 with no family scalars — a convenience wrapper around Self::effective_jacobian_at for the single-output (n_outputs = 1) case.

Callers that need multi-output Jacobians or β-dependent scalars should call effective_jacobian_at directly with the appropriate state.

Returns Err if the design cannot be densified.

pub fn effective_jacobian_at( &self, caller: &str, state: &FamilyLinearizationState<'_>, ) -> Result<Array2<f64>, String>

Returns the β-dependent stacked Jacobian J(β) for this block.

Shape: (n_rows * n_outputs, p_block). For most blocks n_outputs = 1 and the result is the familiar (n_rows, p_block) effective design.

Dispatch order:

1. jacobian_callback = Some(cb) → cb.effective_jacobian_at(state).
2. jacobian_callback = None → design.clone() (ignores beta and family_scalars).

Returns Err if the design cannot be densified.

Trait Implementations

impl Clone for ParameterBlockSpec

fn clone(&self) -> ParameterBlockSpec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ParameterBlockSpec

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

Formats the value using the given formatter.