Struct HouseholderQr 

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

Opaque compact Householder QR state.

The packed reflector tensors remain private so callers cannot accidentally treat provider state as ordinary tensor values.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_linalg::{QrOptions, TensorLinalgExt};
use tenferro_tensor::{BackendSessionHost, Tensor};

let a = Tensor::from_vec_col_major(
    vec![3, 2],
    vec![1.0_f64, 0.0, 1.0, 0.0, 1.0, 1.0],
)?;
let mut host = CpuBackend::new();
let r = host.with_backend_session(|session| {
    let qr = a.householder_qr(session)?;
    qr.r(QrOptions::default(), session)
})??;
assert_eq!(r.shape(), &[2, 2]);

Implementations

impl HouseholderQr<Tensor>

pub fn from_factors( q: &Tensor, r: &Tensor, session: &mut dyn BackendSession, ) -> Result<Self>

Construct compact state for the product of compatible factors Q * R.

Errors

Returns tenferro_tensor::Error::Validation for incompatible rank, shape, dtype, placement, or a non-trapezoidal R factor; tenferro_tensor::Error::Unsupported when the provider lacks compact QR; or tenferro_tensor::Error::BackendSource for provider failures.

pub fn append_columns( &self, block: &Tensor, session: &mut dyn BackendSession, ) -> Result<Self>

Append a column block without refactorizing existing columns.

Errors

Returns tenferro_tensor::Error::Validation for incompatible shape, dtype, placement, or malformed state; tenferro_tensor::Error::Unsupported when append is unavailable; or tenferro_tensor::Error::BackendSource for reflector or factorization failures.

pub fn r( &self, options: QrOptions, session: &mut dyn BackendSession, ) -> Result<Tensor>

Extract the thin upper-trapezoidal factor.

Errors

Returns tenferro_tensor::Error::Validation for malformed state, tenferro_tensor::Error::Unsupported for an unavailable provider path, or tenferro_tensor::Error::BackendSource for extraction failures.

pub fn q_columns( &self, columns: Range<usize>, options: QrOptions, session: &mut dyn BackendSession, ) -> Result<Tensor>

Materialize a contiguous range of Q columns, up to the full-Q width.

For an m x n input with k = min(m, n), columns 0..k are the thin-Q factor and columns k..m span the orthogonal complement of the input’s column space — the cheaper route to a nullspace basis than a full SVD. QrOptions::gauge is defined by R’s diagonal, so PositiveDiagonal fixes the first k columns only; a complement column has no diagonal to fix and is returned as the reflector product produced it.

Errors

Returns tenferro_tensor::Error::Validation when the range is outside the full-Q width 0..m or state metadata is malformed, tenferro_tensor::Error::Unsupported for an unavailable provider path, or tenferro_tensor::Error::BackendSource for execution failures.

impl HouseholderQr<EagerTensor>

pub fn from_factors( q: &EagerTensor, r: &EagerTensor, session: &mut EagerSession<'_>, ) -> Result<Self>

Construct compact state from compatible eager factors.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_linalg::HouseholderQr;
let ctx = EagerRuntime::new()?;
let state = ctx.with_eager_session(|s| {
    let q = s.constant_from(Tensor::from_vec_col_major([1, 1], vec![1.0_f64])?)?;
    let r = s.constant_from(Tensor::from_vec_col_major([1, 1], vec![2.0_f64])?)?;
    HouseholderQr::<EagerTensor>::from_factors(&q, &r, s)
})?;
assert!(format!("{state:?}").starts_with("HouseholderQr"));

Errors

Returns tenferro_ad::Error::Validation for known invalid metadata, tenferro_ad::Error::Extension for unsupported or provider failures, or tenferro_ad::Error::RuntimeState when eager execution is unavailable.

pub fn append_columns( &self, block: &EagerTensor, session: &mut EagerSession<'_>, ) -> Result<Self>

Append an eager column block functionally.

Examples

use tenferro_ad::{EagerRuntime, Tensor};
use tenferro_linalg::EagerSessionLinalgExt;
let ctx = EagerRuntime::new()?;
let state = ctx.with_eager_session(|s| {
    let a = s.constant_from(Tensor::from_vec_col_major([2, 1], vec![1.0_f64, 0.0])?)?;
    let b = s.constant_from(Tensor::from_vec_col_major([2, 1], vec![0.0_f64, 1.0])?)?;
    s.householder_qr(&a)?.append_columns(&b, s)
})?;
assert!(format!("{state:?}").starts_with("HouseholderQr"));

Errors

Returns tenferro_ad::Error::Validation for known invalid metadata, tenferro_ad::Error::Extension for unsupported or provider failures, or tenferro_ad::Error::RuntimeState when eager execution is unavailable.

pub fn r( &self, options: QrOptions, session: &mut EagerSession<'_>, ) -> Result<EagerTensor>

Extract eager R.

Examples

use tenferro_ad::{EagerRuntime, Tensor};
use tenferro_linalg::{EagerSessionLinalgExt, QrOptions};
let ctx = EagerRuntime::new()?;
let r = ctx.with_eager_session(|s| {
    let a = s.constant_from(Tensor::from_vec_col_major([2, 1], vec![1.0_f64, 2.0])?)?;
    s.householder_qr(&a)?.r(QrOptions::default(), s)
})?;
assert_eq!(r.shape(), &[1, 1]);

Errors

Returns tenferro_ad::Error::Validation for known invalid metadata, tenferro_ad::Error::Extension for unsupported or provider failures, or tenferro_ad::Error::RuntimeState when eager execution is unavailable.

pub fn q_columns( &self, columns: Range<usize>, options: QrOptions, session: &mut EagerSession<'_>, ) -> Result<EagerTensor>

Materialize eager Q columns, up to the full-Q width.

Examples

use tenferro_ad::{EagerRuntime, Tensor};
use tenferro_linalg::{EagerSessionLinalgExt, QrOptions};
let ctx = EagerRuntime::new()?;
let q = ctx.with_eager_session(|s| {
    let a = s.constant_from(Tensor::from_vec_col_major([2, 1], vec![1.0_f64, 2.0])?)?;
    s.householder_qr(&a)?.q_columns(0..1, QrOptions::default(), s)
})?;
assert_eq!(q.shape(), &[2, 1]);

Columns 0..k are the thin-Q factor; columns k..m span the orthogonal complement of the input’s column space. PositiveDiagonal fixes only the first k columns, because the gauge comes from R’s diagonal. Differentiating through a range that reaches past k is unsupported and surfaces a typed AD error rather than a silently wrong derivative.

Errors

Returns tenferro_ad::Error::Validation for known invalid metadata, tenferro_ad::Error::Extension for unsupported or provider failures, or tenferro_ad::Error::RuntimeState when eager execution is unavailable.

impl HouseholderQr<TracedTensor>

pub fn from_factors(q: &TracedTensor, r: &TracedTensor) -> Result<Self>

Construct compact state from compatible traced factors.

Errors

Returns tenferro_runtime::Error::Validation for known invalid metadata or tenferro_runtime::Error::Extension for unsupported operation state.

Deferred errors

Symbolic shape constraints and backend provider failures may be reported during compile or execution.

pub fn append_columns(&self, block: &TracedTensor) -> Result<Self>

Append a traced column block functionally.

Errors

Returns tenferro_runtime::Error::Validation for known invalid metadata or tenferro_runtime::Error::Extension for unsupported operation state.

Deferred errors

Symbolic shape constraints and backend provider failures may be reported during compile or execution.

pub fn r(&self, options: QrOptions) -> Result<TracedTensor>

Extract traced R.

Errors

Returns tenferro_runtime::Error::Validation for known invalid metadata or tenferro_runtime::Error::Extension for unsupported operation state.

Deferred errors

Symbolic shape constraints and backend provider failures may be reported during compile or execution.

pub fn q_columns( &self, columns: Range<usize>, options: QrOptions, ) -> Result<TracedTensor>

Materialize traced Q columns, up to the full-Q width.

Columns 0..k are the thin-Q factor; columns k..m span the orthogonal complement of the input’s column space. PositiveDiagonal fixes only the first k columns, because the gauge comes from R’s diagonal. Differentiating through a range that reaches past k is unsupported and surfaces a typed AD error rather than a silently wrong derivative.

Errors

Returns tenferro_runtime::Error::Validation for known invalid metadata or tenferro_runtime::Error::Extension for unsupported operation state.

Deferred errors

Symbolic shape constraints and backend provider failures may be reported during compile or execution.

Trait Implementations

impl<T: Clone> Clone for HouseholderQr<T>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for HouseholderQr<T>

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

Formats the value using the given formatter.