Struct LazyMatrix 

pub struct LazyMatrix<M, F = f64> { /* private fields */ }

A matrix presented with lazy column normalization X̃ = (X − 1cᵀ)S⁻¹.

The underlying matrix data is never modified or densified; the centers and scales are folded into the matrix–vector products on the fly. See the crate-level documentation for the math.

centers and scales are each None when that axis of normalization is inactive. When present, each has length ncols, and no scale equals zero. Negative scales and nonfinite normalization parameters are allowed.

Implementations

impl<M, F: Scalar> LazyMatrix<M, F>

where M: MatrixShape,

pub fn from_parts( data: M, centers: Option<Vec<F>>, scales: Option<Vec<F>>, ) -> Self

Construct from an explicit center and/or scale vector.

Parameters are preserved unchanged, including negative scales and nonfinite values. Unlike Self::new, this constructor rejects exact zero scales rather than replacing them with one.

Panics

Panics if a provided centers/scales vector does not have length ncols, or if a scale is +0.0 or -0.0. The zero-scale panic reports the zero-based column index.

pub fn from_normalization( data: M, normalization: NormalizationParams<F>, ) -> Self

Wrap raw data using previously fitted parameters.

Panics

Panics if the matrix column count differs from the fitted column count.

pub fn normalization(&self) -> &NormalizationParams<F>

Borrow fitted parameters for reuse on prediction data.

pub fn with_centers(data: M, centers: Vec<F>) -> Self

Wrap a matrix with column centering only.

Centers are preserved unchanged, including nonfinite values.

Panics

Panics if centers.len() != ncols.

pub fn with_scales(data: M, scales: Vec<F>) -> Self

Wrap a matrix with column scaling only.

Scales are preserved unchanged, including negative and nonfinite values. Exact zero scales are rejected, as in Self::from_parts.

Panics

Panics if scales.len() != ncols, or if a scale is +0.0 or -0.0. The zero-scale panic reports the zero-based column index.

pub fn nrows(&self) -> usize

Number of rows of the logical normalized matrix.

pub fn ncols(&self) -> usize

Number of columns of the logical normalized matrix.

pub fn centers(&self) -> Option<&[F]>

The column centers c, if centering is active.

pub fn scales(&self) -> Option<&[F]>

The column scales s, if scaling is active.

pub fn data(&self) -> &M

Borrow the underlying (un-normalized) matrix.

pub fn column(&self, j: usize) -> LazyColumn<M::Column<'_>, F>

where M: RawColumns<F>,

Borrow one lazily normalized column without copying.

pub fn sparse_column(&self, j: usize) -> LazySparseColumn<'_, F>

where M: SparseColumns<F>,

Borrow one lazily normalized CSC column with its sparse representation.

pub fn row(&self, i: usize) -> LazyRow<'_, F>

where M: SparseRows<F>,

Borrow one lazily normalized sparse row without copying.

This takes O(1) time and allocates nothing. The view borrows the raw stored column indices and values and the full normalization slices. Centering generally makes the logical row dense; LazyRow exposes its sparse-plus-affine representation explicitly.

use lazymatrix::{LazyMatrix, SprsCsr};
use sprs::CsMat;

let x = CsMat::new((1, 3), vec![0, 2], vec![0, 2], vec![1.0, 0.0]);
let csr = SprsCsr::try_new(x.view()).unwrap();
let lazy = LazyMatrix::from_parts(csr, Some(vec![0.5, -1.0, 2.0]), Some(vec![2.0; 3]));
let row = lazy.row(0);
assert_eq!(row.len(), 3);
assert_eq!(row.column_indices(), &[0, 2]);
assert_eq!(row.values(), &[1.0, 0.0]);
assert_eq!(row.implicit_value(1), 0.5);
assert_eq!(row.stored_corrections().collect::<Vec<_>>(), vec![(0, 0.5), (2, 0.0)]);

Row access requires contiguous sparse-row storage:

use lazymatrix::{LazyMatrix, MatrixShape};

fn row_without_sparse_rows<M: MatrixShape>(matrix: &LazyMatrix<M>) {
    let _ = matrix.row(0);
}

Panics

Panics if i >= self.nrows().

pub fn into_parts(self) -> (M, Option<Vec<F>>, Option<Vec<F>>)

Consume the wrapper, returning the underlying matrix and the center/scale vectors.

impl<M, F: Scalar> LazyMatrix<M, F>

where M: ColumnStats<F> + MatrixShape,

pub fn new(data: M, spec: Normalization) -> Result<Self, M::Error>

Construct by computing the centers and scales from data according to spec.

When both centering and scaling are requested, scales are computed from the centered columns. Standard deviation and range are centering-invariant; L1, L2, and MaxAbs use sparse closed-form centered variants.

An exact zero scale (e.g. a constant column whose standard deviation is zero) is replaced with 1, so the resulting operator never divides by zero. Nonfinite statistics retain their IEEE values and propagate through subsequent operations.

Errors

Returns the backend error if computing normalization statistics fails.

impl<M, F: Scalar> LazyMatrix<M, F>

where M: MatrixShape,

pub fn matvec_scaled_with_workspace<X, Y>( &self, alpha: F, x: &X, beta: F, out: &mut Y, scratch: &mut X::Owned, ) -> Result<(), M::Error>

where X: VectorOwned<F>, Y: VectorViewMut<F>, M: MatVecScaledInto<X, Y, F> + MatVecScaledInto<X::Owned, Y, F>,

Apply out = alpha * X̃ * x + beta * out using caller-owned coefficient scratch.

scratch must have length ncols. It is used when column scaling is active, and its contents after the call are unspecified on error.

pub fn mat_transpose_vec_scaled_with_workspace<X, Y>( &self, alpha: F, x: &X, beta: F, out: &mut Y, scratch: &mut Y::Owned, ) -> Result<(), M::Error>

where X: VectorView<F>, Y: VectorOwned<F> + VectorViewMut<F>, M: MatTransposeVecScaledInto<X, Y, F> + MatTransposeVecScaledInto<X, Y::Owned, F>,

Apply out = alpha * X̃ᵀ * x + beta * out using caller-owned scratch.

scratch must have length ncols. Scaling with nonzero alpha uses this buffer to keep the previous out values separate from the raw transpose product.

impl<M: MaterializeDense<F>, F: Scalar> LazyMatrix<M, F>

pub fn to_eager<D: MatrixOwned<F>>(&self) -> Result<EagerMatrix<D, F>, M::Error>

Allocate normalized dense storage in the selected backend.

Sparse and storage-backed inputs are explicitly materialized. Fitted statistics are retained without recomputation. This requires O(nrows * ncols) output storage, plus backend workspace. Allocation size overflow panics; allocation failures follow the selected backend’s behavior.

Errors

Returns the source error if reading the matrix fails.

pub fn to_eager_into<'a, D: MatrixWrite<F> + ?Sized>( &self, out: &'a mut D, ) -> Result<EagerMatrix<&'a mut D, F>, M::Error>

Overwrite dense storage and return a normalized operator borrowing it.

No matrix allocation is made. Fitted parameters are cloned, and the backend may allocate workspace. The wrapper borrows only the output.

The output remains exclusively borrowed while the wrapper is in use:

use lazymatrix::{LazyMatrix, MaterializeDense, MatrixWrite};
fn cannot_reuse_output<M: MaterializeDense<f64>, D: MatrixWrite<f64>>(
    matrix: &LazyMatrix<M>, out: &mut D,
) {
    let eager = matrix.to_eager_into(out).unwrap();
    out.set(0, 0, 0.0);
    let _ = eager.nrows();
}

Errors

On a source error, output may be partial and no wrapper is returned.

Panics

Panics before writing if the output shape differs from the input shape.

impl<M: DenseNormalize<F>, F: Scalar> LazyMatrix<M, F>

pub fn into_eager(self) -> EagerMatrix<M, F>

Consume writable dense data, normalizing it in its existing allocation.

Mutable views modify their borrowed storage. All statistics have already been fitted, and no new statistics or full matrix allocation are needed.

Borrowed immutable and sparse storage do not support in-place conversion:

use lazymatrix::{LazyMatrix, MatrixShape};
fn needs_writable_dense_storage<M: MatrixShape>(matrix: LazyMatrix<M>) {
    let _ = matrix.into_eager();
}

Trait Implementations

impl<M: Clone, F: Clone> Clone for LazyMatrix<M, F>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<M, F> Columns<F> for LazyMatrix<M, F>

where F: Scalar, M: RawColumns<F>,

type Column<'a> = LazyColumn<<M as RawColumns<F>>::Column<'a>, F> where Self: 'a

fn column(&self, j: usize) -> Self::Column<'_>

impl<M: Debug, F: Debug> Debug for LazyMatrix<M, F>

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

Formats the value using the given formatter.

impl<M, V, F> MatTransposeVec<V> for LazyMatrix<M, F>

where F: Scalar, M: MatTransposeVec<V>, V: SumEntries<F> + ScaledSubSlice<F> + ElemDivAssign<F>,

fn mat_transpose_vec(&self, u: &V) -> Result<V, Self::Error>

X̃ᵀ u = S⁻¹ (Xᵀ u − c · Σu).

impl<M, X, Y, F> MatTransposeVecInto<X, Y> for LazyMatrix<M, F>

where F: Scalar, M: MatTransposeVecInto<X, Y>, X: SumEntries<F>, Y: ScaledSubSlice<F> + ElemDivAssign<F>,

fn mat_transpose_vec_into(&self, u: &X, out: &mut Y) -> Result<(), Self::Error>

out = X̃ᵀ u = S⁻¹ (Xᵀ u − c · Σu).

fn mat_transpose_vec_normalized_into<F: Scalar>( &self, x: &X, centers: Option<&[F]>, scales: Option<&[F]>, out: &mut Y, ) -> Result<(), Self::Error>

where X: SumEntries<F>, Y: ScaledSubSlice<F> + ElemDivAssign<F>,

Apply the transpose of the optionally normalized matrix.

impl<M, X, Y, F> MatTransposeVecScaledInto<X, Y, F> for LazyMatrix<M, F>

where F: Scalar, X: VectorView<F>, Y: VectorOwned<F> + VectorViewMut<F>, M: MatTransposeVecScaledInto<X, Y, F> + MatTransposeVecScaledInto<X, Y::Owned, F>,

fn mat_transpose_vec_scaled_into( &self, alpha: F, x: &X, beta: F, out: &mut Y, ) -> Result<(), Self::Error>

impl<M, V, F> MatVec<V> for LazyMatrix<M, F>

where F: Scalar, M: MatVec<V>, V: Clone + ElemDivAssign<F> + DotSlice<F> + SubScalarAssign<F>,

fn matvec(&self, v: &V) -> Result<V, Self::Error>

X̃ v = X (S⁻¹ v) − 1 · (cᵀ S⁻¹ v).

impl<M, X, Y, F> MatVecInto<X, Y> for LazyMatrix<M, F>

where F: Scalar, M: MatVecInto<X, Y>, X: Clone + ElemDivAssign<F> + DotSlice<F>, Y: SubScalarAssign<F>,

fn matvec_into(&self, v: &X, out: &mut Y) -> Result<(), Self::Error>

out = X̃ v = X (S⁻¹ v) − 1 · (cᵀ S⁻¹ v).

fn matvec_normalized_into<F: Scalar>( &self, x: &X, centers: Option<&[F]>, scales: Option<&[F]>, out: &mut Y, ) -> Result<(), Self::Error>

where X: Clone + ElemDivAssign<F> + DotSlice<F>, Y: SubScalarAssign<F>,

Apply optional column normalization without materializing the matrix.

impl<M, X, Y, F> MatVecScaledInto<X, Y, F> for LazyMatrix<M, F>

where F: Scalar, X: VectorOwned<F>, Y: VectorViewMut<F>, M: MatVecScaledInto<X, Y, F> + MatVecScaledInto<X::Owned, Y, F>,

fn matvec_scaled_into( &self, alpha: F, x: &X, beta: F, out: &mut Y, ) -> Result<(), Self::Error>

impl<M: MatrixErrorType, F> MatrixErrorType for LazyMatrix<M, F>

type Error = <M as MatrixErrorType>::Error

An operational failure while reading or processing matrix data.

impl<M, F> MatrixShape for LazyMatrix<M, F>

where M: MatrixShape,

fn nrows(&self) -> usize

fn ncols(&self) -> usize

impl<M, F> WeightedColumnSumsInto<F> for LazyMatrix<M, F>

where F: Scalar, M: WeightedColumnSumsKernel<F>,

fn weighted_column_sums_into<W, O>( &self, weights: &W, out: &mut O, ) -> Result<(), Self::Error>

where W: VectorView<F> + ?Sized, O: VectorViewMut<F> + ?Sized,

impl<M, F> WeightedGramInto<F> for LazyMatrix<M, F>

where F: Scalar, M: WeightedGramKernel<F>,

fn weighted_gram_into<W, O>( &self, weights: &W, out: &mut O, ) -> Result<(), Self::Error>

where W: VectorView<F> + ?Sized, O: MatrixWrite<F> + ?Sized,