Trait TensorLinalgExt 

pub trait TensorLinalgExt {
    // Required methods
    fn svd(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor, Tensor)>;
    fn svdvals(&self, session: &mut dyn Engine) -> Result<Tensor>;
    fn svd_with_options(
        &self,
        options: SvdOptions,
        session: &mut dyn Engine,
    ) -> Result<(Tensor, Tensor, Tensor)>;
    fn svd_full(
        &self,
        session: &mut dyn Engine,
    ) -> Result<(Tensor, Tensor, Tensor)>;
    fn qr(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>;
    fn householder_qr(
        &self,
        session: &mut dyn Engine,
    ) -> Result<HouseholderQr<Tensor>>;
    fn qr_with_options(
        &self,
        options: QrOptions,
        session: &mut dyn Engine,
    ) -> Result<(Tensor, Tensor)>;
    fn rank_revealing_qr(
        &self,
        options: RankRevealingQrOptions,
        session: &mut dyn Engine,
    ) -> Result<RankRevealingQrResult<Tensor>>;
    fn lu(
        &self,
        session: &mut dyn Engine,
    ) -> Result<(Tensor, Tensor, Tensor, Tensor)>;
    fn full_piv_lu(
        &self,
        session: &mut dyn Engine,
    ) -> Result<(Tensor, Tensor, Tensor, Tensor, Tensor)>;
    fn full_piv_lu_solve(
        &self,
        b: &Tensor,
        session: &mut dyn Engine,
    ) -> Result<Tensor>;
    fn solve(&self, b: &Tensor, session: &mut dyn Engine) -> Result<Tensor>;
    fn cholesky(&self, session: &mut dyn Engine) -> Result<Tensor>;
    fn eigh(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>;
    fn eigh_with_options(
        &self,
        options: EighOptions,
        session: &mut dyn Engine,
    ) -> Result<(Tensor, Tensor)>;
    fn eig(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>;
    fn triangular_solve(
        &self,
        b: &Tensor,
        left_side: bool,
        lower: bool,
        transpose_a: bool,
        unit_diagonal: bool,
        session: &mut dyn Engine,
    ) -> Result<Tensor>;
    fn slogdet(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>;
    fn det(&self, session: &mut dyn Engine) -> Result<Tensor>;
    fn inv(&self, session: &mut dyn Engine) -> Result<Tensor>;
    fn eigvalsh(&self, session: &mut dyn Engine) -> Result<Tensor>;
    fn eigvals(&self, session: &mut dyn Engine) -> Result<Tensor>;
    fn pinv(&self, session: &mut dyn Engine) -> Result<Tensor>;
    fn pinv_with_rtol(
        &self,
        rtol: f64,
        session: &mut dyn Engine,
    ) -> Result<Tensor>;
    fn norm(
        &self,
        ord: Option<f64>,
        dim: Option<&[usize]>,
        keepdim: bool,
        session: &mut dyn Engine,
    ) -> Result<Tensor>;
}

Linear algebra methods for dtype-erased owned tensors.

Examples

use tenferro_cpu::CpuEngine;
use tenferro_linalg::TensorLinalgExt;
use tenferro_tensor::Tensor;

let a = Tensor::from_vec_col_major(vec![2, 2], vec![2.0_f64, 0.0, 0.0, 4.0])?;
let mut host = tenferro_cpu::CpuEngine::serial();
let (_u, singular_values, _vt) = a.svd(&mut host)?;
assert_eq!(singular_values.as_slice::<f64>()?, &[4.0, 2.0]);

Required Methods

fn svd(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, numerical, or output-contract errors.

Examples

let (_u, s, _vt) = a.svd(&mut host)?;
assert_eq!(s.shape(), &[2]);

fn svdvals(&self, session: &mut dyn Engine) -> Result<Tensor>

Compute singular values without allocating singular-vector outputs.

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend has no values-only capability, rather than silently computing a full decomposition and discarding its vectors.

Examples

let values = a.svdvals(&mut host)?;
assert_eq!(values.as_slice::<f64>()?, &[4.0, 2.0]);

fn svd_with_options( &self, options: SvdOptions, session: &mut dyn Engine, ) -> Result<(Tensor, Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for matrix metadata or options, plus SVD backend errors.

Examples

let (_u, s, _vt) = { a.svd_with_options(SvdOptions::default(), &mut host) }?;
assert_eq!(s.shape(), &[2]);

fn svd_full(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor, Tensor)>

Compute the full-matrices SVD (U, S, Vt) with U shaped m x m and Vt shaped n x n, so the trailing Vt rows span the input’s right nullspace and the trailing U columns span its left nullspace.

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend or CPU provider has no full-matrices kernel; the thin decomposition is never substituted for it. Returns validation errors for an unsupported rank or dtype, plus backend, numerical, or output-contract errors.

Examples

let (u, s, vt) = a.svd_full(&mut host)?;
assert_eq!(u.shape(), &[1, 1]);
assert_eq!(s.shape(), &[1]);
assert_eq!(vt.shape(), &[2, 2]);

fn qr(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, numerical, or output-contract errors.

Examples

let (q, r) = a.qr(&mut host)?;
assert_eq!(q.shape(), &[2, 2]);
assert_eq!(r.shape(), &[2, 2]);

fn householder_qr( &self, session: &mut dyn Engine, ) -> Result<HouseholderQr<Tensor>>

Initialize opaque compact Householder QR state.

Errors

Returns validation errors for non-matrix or unsupported-dtype input and typed provider errors when compact QR is unavailable.

Examples

use tenferro_cpu::CpuEngine;
use tenferro_linalg::TensorLinalgExt;
use tenferro_tensor::Tensor;
let a = Tensor::from_vec_col_major(vec![2, 1], vec![1.0_f64, 2.0])?;
let mut host = tenferro_cpu::CpuEngine::serial();
let qr = a.householder_qr(&mut host)?;
assert!(format!("{qr:?}").starts_with("HouseholderQr"));

fn qr_with_options( &self, options: QrOptions, session: &mut dyn Engine, ) -> Result<(Tensor, Tensor)>

The CUDA provider does not read the cuSOLVER geqrf/orgqr status flags, so forward QR reports neither a vendor parameter error nor a rank deficiency: shapes and dtypes are validated up front, and a rank-deficient input still yields its valid factors.

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for matrix metadata or options, plus QR backend errors.

Examples

let (q, r) = { a.qr_with_options(QrOptions::default(), &mut host) }?;
assert_eq!(q.shape(), &[2, 2]);
assert_eq!(r.shape(), &[2, 2]);

fn rank_revealing_qr( &self, options: RankRevealingQrOptions, session: &mut dyn Engine, ) -> Result<RankRevealingQrResult<Tensor>>

Compute column-pivoted rank-revealing QR with fixed-shape tensor metadata.

Errors

Returns validation errors for rank, dtype, or invalid tolerances; numerical failure for non-finite input or diagonal values; and explicit unsupported/backend errors when the selected provider cannot execute RRQR.

Examples

let result = {
    a.rank_revealing_qr(RankRevealingQrOptions::default().rtol(1e-12), &mut host)
}?;
assert_eq!(result.column_permutation.shape(), &[2]);
assert_eq!(result.rank.shape(), &[] as &[usize]);

fn lu( &self, session: &mut dyn Engine, ) -> Result<(Tensor, Tensor, Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, numerical, or output-contract errors.

Examples

let (_p, l, u, parity) = a.lu(&mut host)?;
assert_eq!(l.shape(), &[2, 2]);
assert_eq!(u.shape(), &[2, 2]);
assert_eq!(parity.shape(), &[] as &[usize]);

fn full_piv_lu( &self, session: &mut dyn Engine, ) -> Result<(Tensor, Tensor, Tensor, Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, numerical, or output-contract errors.

Examples

let (p, _l, _u, q, parity) = a.full_piv_lu(&mut host)?;
assert_eq!(p.shape(), &[2, 2]);
assert_eq!(q.shape(), &[2, 2]);
assert_eq!(parity.shape(), &[] as &[usize]);

fn full_piv_lu_solve( &self, b: &Tensor, session: &mut dyn Engine, ) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for incompatible inputs or a backend/singular-system error.

Examples

let x = a.full_piv_lu_solve(&b, &mut host)?;
assert_eq!(x.shape(), &[2, 1]);

fn solve(&self, b: &Tensor, session: &mut dyn Engine) -> Result<Tensor>

The CUDA provider does not inspect the cuSOLVER getrf status flag on the forward solve path, so it performs no per-call non-singularity check and issues no host round trip. An exactly singular input is left to the caller’s verification, as in torch.linalg.solve. CPU providers may still report their own exactly singular factor as Error::Singular.

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for incompatible inputs or a backend/singular-system error.

Examples

let x = a.solve(&b, &mut host)?;
assert_eq!(x.as_slice::<f64>()?, &[2.0, 2.0]);

fn cholesky(&self, session: &mut dyn Engine) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for a non-square input or backend/numerical errors.

Examples

let l = a.cholesky(&mut host)?;
assert_eq!(l.shape(), &[2, 2]);

fn eigh(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, convergence, or output-contract errors.

Examples

let (values, vectors) = a.eigh(&mut host)?;
assert_eq!(values.as_slice::<f64>()?, &[1.0, 3.0]);
assert_eq!(vectors.shape(), &[2, 2]);

fn eigh_with_options( &self, options: EighOptions, session: &mut dyn Engine, ) -> Result<(Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for matrix metadata or options, plus Eigh backend errors.

Examples

let (values, vectors) = { a.eigh_with_options(EighOptions::default(), &mut host) }?;
assert_eq!(values.shape(), &[2]);
assert_eq!(vectors.shape(), &[2, 2]);

fn eig(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, convergence, or output-contract errors.

Examples

let (values, vectors) = a.eig(&mut host)?;
assert_eq!(values.shape(), &[2]);
assert_eq!(vectors.shape(), &[2, 2]);

Eigenvectors come back with unit 2-norm columns, whichever provider computed them; a column the provider left non-finite is reported as a numerical failure instead of being returned as NaN (#2148).

fn triangular_solve( &self, b: &Tensor, left_side: bool, lower: bool, transpose_a: bool, unit_diagonal: bool, session: &mut dyn Engine, ) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for incompatible inputs/flags or backend/numerical errors.

Examples

let x = { a.triangular_solve(&b, true, false, false, false, &mut host) }?;
assert_eq!(x.shape(), &[2, 1]);

fn slogdet(&self, session: &mut dyn Engine) -> Result<(Tensor, Tensor)>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, numerical, or LU output-contract errors.

Examples

let (sign, logabsdet) = a.slogdet(&mut host)?;
assert_eq!(sign.as_slice::<f64>()?, &[1.0]);
assert_eq!(logabsdet.shape(), &[] as &[usize]);

fn det(&self, session: &mut dyn Engine) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns the validation, backend, numerical, or contract errors from Self::slogdet.

Examples

let determinant = a.det(&mut host)?;
assert!((determinant.as_slice::<f64>()?[0] - 8.0).abs() < 1.0e-12);

fn inv(&self, session: &mut dyn Engine) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, or singular-solve numerical errors.

Examples

let inverse = a.inv(&mut host)?;
assert_eq!(inverse.as_slice::<f64>()?, &[0.5, 0.0, 0.0, 0.25]);

fn eigvalsh(&self, session: &mut dyn Engine) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns the validation, backend, convergence, or contract errors from Self::eigh.

Examples

let values = a.eigvalsh(&mut host)?;
assert_eq!(values.as_slice::<f64>()?, &[1.0, 3.0]);

fn eigvals(&self, session: &mut dyn Engine) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns the validation, backend, convergence, or contract errors from Self::eig.

Examples

let values = a.eigvals(&mut host)?;
assert_eq!(values.shape(), &[2]);

fn pinv(&self, session: &mut dyn Engine) -> Result<Tensor>

Compute the Moore-Penrose pseudoinverse with the dtype-default cutoff.

The cutoff thresholds an SVD whose default driver is accuracy-preserving (SvdDriver::Auto), so a rank-deficient rank is retained or dropped the same way as on CPU. CPU providers and CUDA share this contract.

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation, unsupported-backend, numerical, or SVD contract errors.

Examples

let pseudoinverse = a.pinv(&mut host)?;
assert_eq!(pseudoinverse.shape(), &[2, 2]);

fn pinv_with_rtol(&self, rtol: f64, session: &mut dyn Engine) -> Result<Tensor>

Compute the Moore-Penrose pseudoinverse with an explicit relative cutoff.

Like Self::pinv, the threshold is applied to an accuracy-preserving default SVD (SvdDriver::Auto), so the retained rank matches the CPU reference.

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns a validation error for invalid rtol, plus errors from Self::pinv.

Examples

let pseudoinverse = a.pinv_with_rtol(1.0e-12, &mut host)?;
assert_eq!(pseudoinverse.shape(), &[2, 2]);

fn norm( &self, ord: Option<f64>, dim: Option<&[usize]>, keepdim: bool, session: &mut dyn Engine, ) -> Result<Tensor>

Errors

Returns tenferro_tensor::Error::Unsupported when the selected backend does not support the operation. Returns validation errors for axes/order combinations or required backend operations.

Examples

let frobenius = a.norm(None, None, false, &mut host)?;
assert_eq!(frobenius.shape(), &[] as &[usize]);

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl TensorLinalgExt for Tensor