Struct RandomEffectOperator 

pub struct RandomEffectOperator {
    pub group_ids: Vec<Option<usize>>,
    pub n: usize,
    pub num_groups: usize,
}

Implicit design operator for random-intercept effects.

Instead of materializing an n × q one-hot matrix, stores only the O(n) integer group-label vector. All matvecs, Gram assembly, and weighted-normal products operate in O(n) time and O(n + q) memory.

Fields

group_ids: Vec<Option<usize>>

For each observation, the column index of its group (0..num_groups), or None if the observation’s level was not in the kept set (prediction with unseen levels).

n: usize

Number of observations.

num_groups: usize

Number of groups (columns).

Implementations

impl RandomEffectOperator

pub fn new(group_ids: Vec<Option<usize>>, num_groups: usize) -> Self

pub fn weighted_cross_with_dense( &self, dense: &Array2<f64>, weights: &Array1<f64>, ) -> Result<Array2<f64>, String>

For a dense block X_dense (n × p_dense) and weights w, compute X_dense’ diag(w) X_re → (p_dense × num_groups) matrix.

Column g of the result = Σ_{i: group[i]=g} w[i] * X_dense.row(i). Total cost: O(n × p_dense).

pub fn weighted_cross_with_re( &self, other: &RandomEffectOperator, weights: &Array1<f64>, ) -> Result<Array2<f64>, String>

For two RE operators, compute X_re_a’ diag(w) X_re_b → (qa × qb). Entry (a, b) = Σ_{i: group_a[i]=a AND group_b[i]=b} w[i]. Cost: O(n).

Trait Implementations

impl Clone for RandomEffectOperator

fn clone(&self) -> RandomEffectOperator

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl DenseDesignOperator for RandomEffectOperator

fn quadratic_form_diag( &self, middle: &Array2<f64>, ) -> Result<Array1<f64>, String>

diag(X M X’) for one-hot X: out[i] = M[group[i], group[i]].

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

Materialize the full n × q one-hot matrix (fallback for diagnostics).

fn compute_xtwy( &self, weights: &Array1<f64>, y: &Array1<f64>, ) -> Result<Array1<f64>, String>

fn row_chunk_into( &self, rows: Range<usize>, out: ArrayViewMut2<'_, f64>, ) -> Result<(), MatrixMaterializationError>

Fill a dense row chunk without materializing the full matrix. Required: every implementor must provide row-local access here.

fn try_row_chunk( &self, rows: Range<usize>, ) -> Result<Array2<f64>, MatrixMaterializationError>

Extract a dense row chunk without materializing the full matrix. Non-panicking owned-chunk API built on top of row_chunk_into.

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

Borrow dense storage when this operator already owns it.

fn materialization_policy(&self) -> Option<MaterializationPolicy>

Materialization contract captured when this operator-backed design was selected. Composite operators propagate the strictest contract of their inputs so a later caller using a more permissive default cannot reverse an upstream streamed-storage decision.

fn apply_columns(&self, cols: &[usize]) -> Array2<f64>

Batched column extraction: returns an nrows × cols.len() dense block whose k-th column is apply(e_{cols[k]}).

fn estimated_dense_bytes(&self) -> usize

fn try_to_dense_with_policy( &self, policy: &MaterializationPolicy, context: &'static str, ) -> Result<Arc<Array2<f64>>, MatrixMaterializationError>

fn try_to_dense_governed_with_policy( &self, policy: &MaterializationPolicy, context: &'static str, ) -> Result<Governed<Array2<f64>>, MatrixMaterializationError>

Materialize through the process-wide governor and couple the returned matrix to its reservation. Unlike the older Arc-returning helper, this cannot release its ledger charge while the dense allocation is live.

fn to_dense_arc(&self) -> Arc<Array2<f64>>

Shared dense materialization via the required row-chunk API.

impl LinearOperator for RandomEffectOperator

fn apply(&self, vector: &Array1<f64>) -> Array1<f64>

Forward: out[i] = β[group[i]], or 0 if unmatched.

fn apply_transpose(&self, vector: &Array1<f64>) -> Array1<f64>

Transpose: out[g] = Σ_{i: group[i]=g} v[i].

fn diag_xtw_x(&self, weights: &Array1<f64>) -> Result<Array2<f64>, String>

X’WX for a one-hot design is diagonal: D[g,g] = Σ_{i: group[i]=g} w[i].

fn diag_gram(&self, weights: &Array1<f64>) -> Result<Array1<f64>, String>

Diagonal of X’WX: per-group weight sums.

fn apply_weighted_normal( &self, weights: FiniteSignedWeightsView<'_>, vector: &Array1<f64>, penalty: Option<&Array2<f64>>, ridge: f64, ) -> Array1<f64>

Fused X’WXβ + Sβ + ridge·β. O(n + q).

fn nrows(&self) -> usize

fn ncols(&self) -> usize

fn uses_matrix_free_pcg(&self) -> bool

fn xt_diag_x_signed_op( &self, weights: FiniteSignedWeightsView<'_>, ) -> Result<Array2<f64>, String>

Observed-Hessian / non-canonical-link Gram: XᵀWX with sign-honest weights. Returns a dense Array2<f64> because the result is symmetric but not guaranteed PSD (so consumers cannot assume the SymmetricMatrix PSD contract). Default impl delegates to diag_xtw_x for legacy operators; overriding impls may take a sign-aware fast path.

fn xt_diag_x_psd_op( &self, weights: PsdWeightsView<'_>, ) -> Result<SymmetricMatrix, String>

PSD-precondition Gram: XᵀWX with w ≥ 0 discharged at the PsdWeightsView constructor. Returns a typed SymmetricMatrix so downstream consumers can route through PSD-only solvers (Cholesky). Default impl wraps the signed path’s Array2 in SymmetricMatrix::Dense.

fn solve_system_matrix_free_pcg_try( &self, weights: &Array1<f64>, rhs: &Array1<f64>, penalty: Option<&Array2<f64>>, baseridge: f64, ) -> Result<Array1<f64>, String>

fn solve_system_matrix_free_pcg_with_info_try( &self, weights: &Array1<f64>, rhs: &Array1<f64>, penalty: Option<&Array2<f64>>, baseridge: f64, ) -> Result<(Array1<f64>, PcgSolveInfo), String>

fn factorize_system( &self, weights: &Array1<f64>, penalty: Option<&Array2<f64>>, ) -> Result<Box<dyn FactorizedSystem>, String>

fn solve_system( &self, weights: &Array1<f64>, rhs: &Array1<f64>, penalty: Option<&Array2<f64>>, ) -> Result<Array1<f64>, String>

fn solve_systemwith_policy( &self, weights: &Array1<f64>, rhs: &Array1<f64>, penalty: Option<&Array2<f64>>, ridge_floor: f64, ridge_policy: RidgePolicy, ) -> Result<Array1<f64>, String>