Struct IncrementalQr 

pub struct IncrementalQr<T> { /* private fields */ }

Thin QR state that can append columns without refactorizing the old block.

The state stores an explicit thin Q factor and an upper-trapezoidal R factor. Appending a full-rank block uses two backend matrix-product projection passes, factorizes only the residual block through the configured QR backend, and updates the block-triangular R.

The matrix layout is column-major throughout. The current state must have at least as many rows as columns, and appends are accepted only while the resulting factorization remains thin.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix, mat_mul};

let first = Matrix::from_col_major_vec(3, 1, vec![1.0_f64, 2.0, 3.0]);
let appended = Matrix::from_col_major_vec(3, 1, vec![2.0, 0.0, 1.0]);
let mut qr = IncrementalQr::new(first).unwrap();
qr.append(&appended).unwrap();
let reconstructed = mat_mul(&qr.q(), &qr.r()).unwrap();
assert!(reconstructed
    .as_col_major_slice()
    .iter()
    .zip([1.0, 2.0, 3.0, 2.0, 0.0, 1.0])
    .all(|(actual, expected)| (actual - expected).abs() < 1.0e-12));

Implementations

impl<T> IncrementalQr<T>

where T: IncrementalQrScalar,

pub fn from_factors( q: Matrix<T>, r: Matrix<T>, ) -> Result<Self, BackendLinalgError>

Resume an incremental QR update from compatible thin factors.

Arguments

• q - Existing column-major m × p thin factor.
• r - Existing column-major p × n upper-trapezoidal factor, where n >= p.

Returns

An update state whose next append extends the represented factorization.

Errors

Returns a backend error when the factors are empty, have incompatible dimensions, are not thin, or backend QR/multiplication fails.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let state = IncrementalQr::from_factors(
    Matrix::from_col_major_vec(2, 1, vec![1.0_f64, 0.0]),
    Matrix::from_col_major_vec(1, 1, vec![2.0]),
)
.unwrap();
assert_eq!(state.q().ncols(), 1);
assert_eq!(state.r().nrows(), 1);

pub fn new(input: Matrix<T>) -> Result<Self, BackendLinalgError>

Factorize a non-empty tall-or-square matrix into thin Q and square R.

Arguments

• input - Column-major m × n matrix with m >= n and n > 0.

Returns

A state containing factors satisfying input = Q R up to backend floating-point error.

Errors

Returns a backend error when the input dimensions are invalid because the matrix is empty or wide, or when backend QR conversion or factorization fails.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let qr = IncrementalQr::new(Matrix::from_col_major_vec(
    2,
    1,
    vec![1.0_f64, 2.0],
))
.unwrap();
assert_eq!(qr.q().nrows(), 2);
assert_eq!(qr.r().ncols(), 1);

pub fn append( &mut self, new_columns: &Matrix<T>, ) -> Result<(), BackendLinalgError>

Append a column block using the existing QR state.

Arguments

• new_columns - Column-major m × k block with the same row count as the initial matrix and k > 0.

Returns

Updates this state in place so that Q R represents the original matrix followed by new_columns.

Errors

Returns a backend error when the input dimensions are invalid because row counts differ, the append is empty, or the resulting matrix would be wide; when a rank or column count overflows; or when backend matrix multiplication, conversion, or QR factorization fails.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let mut qr = IncrementalQr::new(Matrix::from_col_major_vec(
    3,
    1,
    vec![1.0_f64, 2.0, 3.0],
))
.unwrap();
qr.append(&Matrix::from_col_major_vec(
    3,
    1,
    vec![3.0_f64, 2.0, 1.0],
))
.unwrap();
assert_eq!(qr.r().ncols(), 2);

pub fn q(&self) -> Matrix<T>

Return a copy of the current thin Q factor.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let qr = IncrementalQr::new(Matrix::from_col_major_vec(
    2,
    1,
    vec![1.0_f64, 0.0],
))
.unwrap();
assert_eq!(qr.q().ncols(), 1);

pub fn rank(&self) -> usize

Return the current thin factor width.

This is the number of columns in both Q and the row count of R.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let qr = IncrementalQr::new(Matrix::from_col_major_vec(
    2,
    1,
    vec![1.0_f64, 0.0],
))
.unwrap();
assert_eq!(qr.rank(), 1);

pub fn q_columns( &self, start: usize, count: usize, ) -> Result<Matrix<T>, BackendLinalgError>

Return a contiguous range of columns from the current thin Q factor.

Arguments

• start - Zero-based column in the current Q factor.
• count - Number of columns to materialize.

Returns

The requested column-major m × count block of Q.

Errors

Returns a backend error when the requested range overflows or is out of bounds for the current thin-factor width, or when the output shape is invalid because its element count overflows.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let qr = IncrementalQr::new(Matrix::from_col_major_vec(
    3,
    2,
    vec![1.0_f64, 0.0, 0.0, 0.0, 1.0, 0.0],
))
.unwrap();
let second = qr.q_columns(1, 1).unwrap();
assert_eq!(second.nrows(), 3);
assert_eq!(second.ncols(), 1);
assert!((second[[1, 0]].abs() - 1.0).abs() < 1.0e-12);

pub fn r(&self) -> Matrix<T>

Return a copy of the current upper-trapezoidal R factor.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let qr = IncrementalQr::new(Matrix::from_col_major_vec(
    2,
    1,
    vec![1.0_f64, 0.0],
))
.unwrap();
assert_eq!(qr.r().nrows(), 1);

pub fn error_estimate(&self) -> Result<SrcErrorEstimate, BackendLinalgError>

Compute the Appendix C SRC estimate from the current R factor.

Returns

The randomized residual and norm estimates associated with the current sketch width.

Errors

Returns a backend error when the current factor is singular or contains invalid values.

Examples

use tensor4all_tensorbackend::{IncrementalQr, Matrix};

let qr = IncrementalQr::new(Matrix::from_col_major_vec(
    2,
    1,
    vec![1.0_f64, 0.0],
))
.unwrap();
let estimate = qr.error_estimate().unwrap();
assert!(estimate.error.is_finite());
assert!(estimate.norm.is_finite());

Trait Implementations

impl<T: Clone> Clone for IncrementalQr<T>

fn clone(&self) -> IncrementalQr<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for IncrementalQr<T>

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

Formats the value using the given formatter.