Linear Algebra
tenferro exposes linear algebra through the tenferro-linalg operation crate. Every operation has the same name and options on three layers: LinalgOps for direct execution without autodiff (a.svd(exec), a.svd_with(&opts, exec); the receiver is any Tensor, TensorRead, TypedTensor<T>, or TypedTensorView<T>), EagerLinalgOps on the EagerSession borrowed inside EagerRuntime::with_eager_session for eager backward() / functional transform workflows (sess.svd(&x)), and TracedLinalgOps on TracedTensor when the operation should be part of a graph, grad/vjp/jvp, or repeated compile/run workflow (t.svd()). The generated operation registry lists every operation with its options type, layout handling, errors, and omissions.
Setup
When working from a local checkout, use paths that match your project layout. For a scratch crate created directly inside the tenferro-rs checkout, include an empty [workspace] table:
[workspace]Then add the dependencies:
[dependencies]
tenferro-runtime = { path = "../crates/tenferro-runtime" }
tenferro-cpu = { path = "../crates/tenferro-cpu" }
tenferro-ad = { path = "../crates/tenferro-ad" }
tenferro-linalg = { path = "../crates/tenferro-linalg", features = ["autodiff"] }For published crates, use the same crate set with version requirements:
[dependencies]
tenferro-runtime = "..."
tenferro-cpu = "..."
tenferro-ad = "..."
tenferro-linalg = { version = "...", features = ["autodiff"] }Concrete graph/runtime users can omit tenferro-ad and the autodiff feature when they do not need eager linalg helpers or linalg AD rules. For inference-only code, call the operations on Tensor/TypedTensor inside a backend session (LinalgOps, for example triangular_solve, solve, cholesky); that route needs no autodiff. There is no separate eager-without-AD feature: EagerSession lives in tenferro-ad, which is all that autodiff adds, so such a feature would save no dependency. The examples below are Rust fragments; copy them into fn main() -> Result<(), Box<dyn std::error::Error>> for a standalone binary.
Layer Coverage
| Layer | Linear algebra style |
|---|---|
Concrete Tensor / TensorRead / TypedTensor<T> / TypedTensorView<T> |
LinalgOps methods; the caller’s &mut dyn Engine is the last argument |
EagerTensor |
EagerLinalgOps methods on a borrowed EagerSession behind autodiff (sess.solve(&a, &b)); tracked variables support backward() and functional transforms where AD rules support the operation |
TracedTensor |
TracedLinalgOps methods for graph execution and grad/vjp/jvp workflows |
CUDA is a backend/device choice for supported Tensor, EagerTensor, and TracedTensor paths. It is not a separate linear algebra layer. See Devices and GPU for the CUDA support table.
Operation Surface
Each operation below exists on all three layers (LinalgOps, EagerLinalgOps, TracedLinalgOps) as op with default options and op_with(&XxxOptions) with explicit options. An operation without options (solve, lstsq, householder_qr, lu, full_piv_lu, full_piv_lu_solve, eig, eigvals, slogdet, det, inv) has only op and has no Options type or _with form. Multi-output operations return named structs: Svd { u, s, vh }, Qr { q, r }, Lu { p, l, u, parity }, FullPivLu { p, l, u, q, parity }, Eig { values, vectors }, Eigh { values, vectors }, and Slogdet { sign, log_abs_det }.
| Operation family | Operations | Options |
|---|---|---|
| Dense solve | solve; concrete solve_into (overwrite) |
none |
| Least squares | lstsq |
none |
| Triangular solve | triangular_solve, triangular_solve_with |
TriangularSolveOptions (side, uplo, op, diag) |
| Cholesky | cholesky, cholesky_with |
CholeskyOptions |
| SVD | svd, svd_with, svdvals, svdvals_with |
SvdOptions (shape(SvdShape::Full) for full factors, gauge, derivative_eps, driver), SvdvalsOptions |
| QR | qr, qr_with |
QrOptions |
| Incremental compact QR | householder_qr; state methods HouseholderQr::from_factors, append_columns, r, q_columns (eager: with &mut EagerSession; traced: on TracedTensor state) |
none |
| Rank-revealing QR | rank_revealing_qr, rank_revealing_qr_with |
RankRevealingQrOptions |
| Hermitian eigen | eigh, eigh_with, eigvalsh, eigvalsh_with |
EighOptions, EigvalshOptions |
| General eigen | eig, eigvals |
none |
| LU | lu |
none |
| Complete-pivot LU | full_piv_lu, full_piv_lu_solve |
none |
| Pseudoinverse | pinv, pinv_with |
PinvOptions (rtol) |
| Determinants | det, slogdet |
none |
| Matrix inverse | inv |
none |
| Norms | norm, norm_with |
NormOptions (ord: NormOrd, axes, keep_dims) |
Options types are #[non_exhaustive]; build them with XxxOptions::default() and the setters, for example PinvOptions::default().rtol(Some(1e-12)). Axis arguments such as NormOptions::axes are signed: -1 is the last axis.
Eager decompositions take the &mut EagerSession from EagerRuntime::with_eager_session as the receiver. Concrete methods take the caller-held &mut dyn Engine as the last argument. Borrowed inputs (TensorRead, TypedTensorView<T>, transposed or negative-stride views) use the same method names as owned tensors. A provider may consume the borrowed view without copying it when its own layout rules allow, and otherwise materializes it once inside its own boundary; no zero-copy guarantee is made, the borrowed source is never modified, and a provider that cannot read the view returns a typed error instead of a narrowed result. The registry’s Layout entry states the rule per operation. A values-only backend capability (svdvals, eigvalsh, eigvals) returns only the values tensor and does not allocate singular/eigenvectors; unsupported providers return a typed error rather than computing a full decomposition and discarding its factors. LinalgBackend is the SPI provider contract used by backend implementations and lower-level session tests, not by ordinary callers.
Batch And Inner Parallelism
Batched decompositions have two independent kinds of parallel work:
- Outer batch parallelism runs independent matrices from the batch on the selected CPU domain or device execution context. The engine owns this scheduling and its resource budget.
- Inner decomposition parallelism partitions the factorization of one matrix. The selected provider owns this algorithmic decomposition, subject to the execution context passed by the engine.
For SVD, QR, Hermitian eigenvalue, and other batched linalg calls, the engine must choose the outer fan-out and the provider must respect the selected inner policy. A faer-backed CPU context can pass Par::Seq or Par::Team while preserving one domain budget. The CPU backend owns no worker pool of its own, so the engine’s pool is the only thread count that applies and no inner thread set can oversubscribe the outer batch; see Choosing A Backend for the policy. Providers must report unsupported decomposition or dtype requests rather than silently changing the algorithm or execution backend.
Concrete Solve
use tenferro_cpu::CpuEngine;
use tenferro_linalg::LinalgOps;
use tenferro_runtime::Tensor;
let a = Tensor::from_vec_col_major(vec![2, 2], vec![4.0_f64, 0.0, 0.0, 9.0])?;
let b = Tensor::from_vec_col_major(vec![2, 1], vec![8.0_f64, 27.0])?;
let mut engine = CpuEngine::serial();
let x = a.solve(&b, &mut engine)?;
assert_eq!(x.shape(), &[2, 1]);
assert_eq!(x.as_slice::<f64>()?, &[2.0, 3.0]);Concrete Cholesky
use tenferro_cpu::CpuEngine;
use tenferro_linalg::LinalgOps;
use tenferro_runtime::{Tensor, CoreOps};
fn max_abs_diff(lhs: &Tensor, rhs: &Tensor) -> Result<f64, tenferro_tensor::Error> {
let lhs = lhs.as_slice::<f64>()?;
let rhs = rhs.as_slice::<f64>()?;
Ok(lhs
.iter()
.zip(rhs.iter())
.map(|(lhs, rhs)| (lhs - rhs).abs())
.fold(0.0, f64::max))
}
let a = Tensor::from_vec_col_major(vec![2, 2], vec![4.0_f64, 1.0, 1.0, 3.0])?;
let mut engine = CpuEngine::serial();
let factor = a.cholesky(&mut engine)?;
let factor_t = factor.transpose(&[1, 0], &mut engine)?;
let reconstructed = factor.matmul(&factor_t, &mut engine)?;
assert_eq!(factor.shape(), &[2, 2]);
assert_eq!(a.shape(), &[2, 2]);
assert!(max_abs_diff(&reconstructed, &a)? < 1.0e-12);Direct Decompositions
The same operation families are available outside traced graphs. Use concrete or typed tensors for direct execution without autodiff, eager tensors when the result should be produced immediately under an EagerRuntime, and traced helpers when the operation belongs in a reusable graph. Use tracked eager tensors when the result should remain connected to a scalar loss backward() pass or to functional eager grad/vjp/jvp transforms. For linalg eager helpers or linalg AD rules, add the tenferro-ad dependency and enable tenferro-linalg’s autodiff feature.
When traced graph AD must linearize through linalg extension ops, include the owned rule set in an explicit context:
use tenferro_ad::AdContext;
let ad = AdContext::builder()
.with_semantic_extension_rules(tenferro_linalg::semantic_ad_rules()?)?
.build()?;Singular value decomposition
use tenferro_cpu::CpuEngine;
use tenferro_linalg::{LinalgOps, Svd};
use tenferro_runtime::{Tensor, CoreOps};
fn max_abs_diff(lhs: &Tensor, rhs: &Tensor) -> Result<f64, tenferro_tensor::Error> {
let lhs = lhs.as_slice::<f64>()?;
let rhs = rhs.as_slice::<f64>()?;
Ok(lhs
.iter()
.zip(rhs.iter())
.map(|(lhs, rhs)| (lhs - rhs).abs())
.fold(0.0, f64::max))
}
let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 3.0, 2.0, 4.0])?;
let mut engine = CpuEngine::serial();
let Svd { u, s, vh: vt } = a.svd(&mut engine)?;
assert_eq!(u.shape(), &[2, 2]);
assert_eq!(vt.shape(), &[2, 2]);
let s_values = s.as_slice::<f64>()?;
let sigma = Tensor::from_vec_col_major(
vec![2, 2],
vec![s_values[0], 0.0, 0.0, s_values[1]],
)?;
let us = u.matmul(&sigma, &mut engine)?;
let reconstructed = us.matmul(&vt, &mut engine)?;
assert_eq!(a.shape(), &[2, 2]);
assert!(max_abs_diff(&reconstructed, &a)? < 1.0e-12);Decomposition Options And SVD Truncation
SVD, QR, and Hermitian eigen decomposition expose options when you need an opt-in deterministic sign or phase convention. The default remains the backend’s raw gauge. SVD and Hermitian eigen options also expose derivative_eps, which regularizes AD formulas for repeated or nearly repeated singular values or eigenvalues. It is not a backend solver tolerance and does not change the forward decomposition algorithm.
use tenferro_linalg::{Svd, SvdGauge, SvdOptions, TracedLinalgOps};
use tenferro_runtime::{TraceContext, TracedTensor};
let trace = TraceContext::new();
let a = trace.from_vec_col_major(
vec![3, 3],
vec![
3.0_f64, 0.0, 0.0,
0.0, 2.0, 0.0,
0.0, 0.0, 1.0,
],
)?;
let Svd { u, s, vh: vt } = a
.svd_with(&SvdOptions::default()
.gauge(SvdGauge::CanonicalPivot)
.derivative_eps(1.0e-10))?;
let rank = 2;
let u_rank2 = u.slice_axis(1, 0..rank)?;
let s_rank2 = s.slice_axis(0, 0..rank)?;
let vt_rank2 = vt.slice_axis(0, 0..rank)?;
assert_eq!(u_rank2.concrete_shape()?, vec![3, 2]);
assert_eq!(s_rank2.concrete_shape()?, vec![2]);
assert_eq!(vt_rank2.concrete_shape()?, vec![2, 3]);SvdOptions::driver selects an algorithm family. A provider may ignore it and run its single SVD kernel, which is what the CPU providers do. SvdDriver::Auto (the default) is the accuracy-preserving family choice: on the CUDA backend it matches JAX, taking Jacobi gesvdj when both matrix dimensions are at most 1024 and QR-based gesvd beyond that. SvdDriver::QrBased or SvdDriver::Jacobi forces one family regardless of size; which one is faster depends on the singular-value spectrum, so measure on your workload. SvdDriver::Polar is opt-in: it is the fastest family for min(m, n) >= 256 (see the cuda_svd_driver benchmark), but its small singular values are only accurate to about 1e-6 of the largest, so do not combine it with an eps-scale truncation (a pseudoinverse or tensor-network truncation at 1e-12..1e-14) - the retained rank can change. Its accuracy is also input-dependent: it was the most accurate of the three families on ten-decade spectra and lost about two digits against QrBased on a circulant-like matrix with the same spectrum. On the CUDA backend, tenferro reads cuSOLVER’s h_err_sigma perturbation bound and returns a typed backend failure rather than silently wrong factors when the perturbation is not small relative to the largest singular value; that is what rejects a rank-deficient F32/C32 explicit request.
use tenferro_linalg::{Svd, SvdDriver, SvdOptions, TracedLinalgOps};
use tenferro_runtime::{TraceContext, TracedTensor};
let trace = TraceContext::new();
let a = trace.from_vec_col_major(
vec![3, 2],
vec![
3.0_f64, 1.0, 0.5,
-2.0, 0.25, 1.5,
],
)?;
// Forces cuSOLVER `gesvd` on CUDA; CPU providers ignore the driver.
let Svd { u, s, vh: vt } = a.svd_with(&SvdOptions::default().driver(SvdDriver::QrBased))?;
assert_eq!(u.concrete_shape()?, vec![3, 2]);
assert_eq!(s.concrete_shape()?, vec![2]);
assert_eq!(vt.concrete_shape()?, vec![2, 2]);EighOptions::driver is the same knob for the Hermitian eigensolver, but you will rarely need it. EighDriver::Auto (the default) picks the fastest divide-and-conquer family available; on the CUDA backend a single matrix goes to syevd/heevd and a batch goes to cusolverDnXsyevBatched, which diagonalises the whole batch in one launch at the same accuracy. EighDriver::DivideAndConquer is the explicit spelling of that same choice. On an A100 that is 1024 batched 8x8 f64 matrices in 0.37 ms against 105 ms for the per-matrix loop this default used before, and 0.69 ms against 70 ms for 256 batched 32x32.
EighDriver::Jacobi selects the Jacobi eigensolver instead, batched the same way. It is worth asking for only on batches of small matrices: on that A100 it is slightly ahead at order 8 and 32 (0.27 ms and 0.38 ms) and behind from there, by about 4x at order 128, and much further on wide spectra where it is also the less accurate of the two. Measure your own shapes. CPU providers ignore the driver.
EighOptions::batch_policy decides whether a real batch may fall back to one launch per matrix. The default, EighBatchPolicy::AllowPerMatrixFallback, is the routing above: a batched cuSOLVER routine when the loaded library provides one and a per-matrix loop when it does not. If you promised your caller one launch per batch, set EighBatchPolicy::RequireBatched instead and the loop becomes a typed Unsupported error that names cusolverDnXsyevBatched, the missing fact (cuSOLVER older than 11.7.1, or either batched symbol unresolved) and the loop it declined. A single matrix is one call either way, so RequireBatched never refuses one matrix or a batch of one.
The policy binds the two-output eigh. A traced graph that keeps only the eigenvalues is pruned to the values-only operation, which carries the driver but not the batch policy, so its recompute may take the per-matrix loop; keep both outputs alive (or check the result) when the launch count has to survive tracing.
To branch before the call, use tenferro_linalg::cuda_batched_eigh_available() on a cuda build: it reports the capability of the loaded cuSOLVER, and a cuSOLVER that cannot be loaded is its typed load error rather than false. CPU providers have no batched eigensolver at all, so they refuse RequireBatched for a real batch; that is the same error, with the same advice.
use tenferro_linalg::{Eigh, EighDriver, EighOptions, TracedLinalgOps};
use tenferro_runtime::{TraceContext, TracedTensor};
let trace = TraceContext::new();
// A batch of two 2x2 symmetric matrices, batch on the trailing axis.
let a = trace.from_vec_col_major(
vec![2, 2, 2],
vec![
2.0_f64, 0.5, 0.5, 3.0,
4.0, -0.25, -0.25, 1.0,
],
)?;
// On CUDA this reaches `syevjBatched`: one launch for the whole batch.
// CPU providers ignore the driver.
let Eigh { values, vectors } =
a.eigh_with(&EighOptions::default().driver(EighDriver::Jacobi))?;
assert_eq!(values.concrete_shape()?, vec![2, 2]);
assert_eq!(vectors.concrete_shape()?, vec![2, 2, 2]);Use slice_axis for rank-preserving contiguous ranges and take_axis when the selected axis needs repeated or reordered indices:
use tenferro_linalg::{Svd, TracedLinalgOps};
use tenferro_runtime::{TraceContext, TracedTensor};
let trace = TraceContext::new();
let a = trace.from_vec_col_major(
vec![3, 3],
vec![
3.0_f64, 0.0, 0.0,
0.0, 2.0, 0.0,
0.0, 0.0, 1.0,
],
)?;
let Svd { u: _u, s, vh: _vt } = a.svd()?;
let repeated = s.take_axis(0, &[0, 1, 0])?;
assert_eq!(repeated.concrete_shape()?, vec![3]);QR decomposition
use tenferro_cpu::CpuEngine;
use tenferro_linalg::{LinalgOps, Qr, QrGauge, QrOptions};
use tenferro_runtime::{Tensor, CoreOps};
fn max_abs_diff(lhs: &Tensor, rhs: &Tensor) -> Result<f64, tenferro_tensor::Error> {
let lhs = lhs.as_slice::<f64>()?;
let rhs = rhs.as_slice::<f64>()?;
Ok(lhs
.iter()
.zip(rhs.iter())
.map(|(lhs, rhs)| (lhs - rhs).abs())
.fold(0.0, f64::max))
}
let a = Tensor::from_vec_col_major(
vec![4, 3],
vec![
1.0_f64, 4.0, 7.0, 2.0,
2.0, 5.0, 8.0, 3.0,
3.0, 6.0, 10.0, 5.0,
],
)?;
let mut engine = CpuEngine::serial();
let Qr { q, r } = a.qr_with(&QrOptions::default().gauge(QrGauge::PositiveDiagonal), &mut engine)?;
let identity = Tensor::from_vec_col_major(
vec![3, 3],
vec![1.0_f64, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0],
)?;
let reconstructed = q.matmul(&r, &mut engine)?;
let qt = q.transpose(&[1, 0], &mut engine)?;
let qtq = qt.matmul(&q, &mut engine)?;
assert_eq!(q.shape(), &[4, 3]);
assert_eq!(r.shape(), &[3, 3]);
assert_eq!(identity.shape(), &[3, 3]);
assert!(max_abs_diff(&reconstructed, &a)? < 1.0e-12);
assert!(max_abs_diff(&qtq, &identity)? < 1.0e-12);Incremental compact Householder QR
Use compact Householder state when columns arrive in blocks and retaining an explicit Q would be wasteful. The state owns private packed reflectors and coefficients on the input device. append_columns factors only the new trailing residual; it never refactorizes old columns. Materialize R or only the Q columns you need:
use tenferro_cpu::CpuEngine;
use tenferro_linalg::{QrGauge, QrOptions, LinalgOps};
use tenferro_runtime::{Tensor, CoreOps};
let initial = Tensor::from_vec_col_major(
vec![3, 2],
vec![1.0_f64, 2.0, 0.5, -1.0, 0.2, 2.0],
)?;
let block = Tensor::from_vec_col_major(vec![3, 1], vec![0.5_f64, 1.0, -2.0])?;
let accumulated = Tensor::from_vec_col_major(
vec![3, 3],
vec![1.0_f64, 2.0, 0.5, -1.0, 0.2, 2.0, 0.5, 1.0, -2.0],
)?;
let options = QrOptions::default().gauge(QrGauge::PositiveDiagonal);
let mut engine = CpuEngine::serial();
let state = initial
.householder_qr(&mut engine)?
.append_columns(&block, &mut engine)?;
let q = state.q_columns(0..3, options, &mut engine)?;
let r = state.r(options, &mut engine)?;
let reconstructed = q.matmul(&r, &mut engine)?;
assert_eq!(q.shape(), &[3, 3]);
assert_eq!(r.shape(), &[3, 3]);
let error = reconstructed
.as_slice::<f64>()?
.iter()
.zip(accumulated.as_slice::<f64>()?)
.map(|(actual, expected)| (actual - expected).abs())
.fold(0.0_f64, f64::max);
assert!(error < 1.0e-12);The API is rank-2 and supports F32, F64, C32, and C64. Inputs in one state must share dtype, placement, and row count. from_factors requires an exactly upper- trapezoidal R. Rank-deficient primal states are supported, while AD is defined on the full-rank differentiable domain. JVP/VJP propagate to the initial matrix, factors, and every appended block through the accumulated-matrix tangent.
CUDA follows the normal explicit transfer rule: upload all inputs before state construction and download only outputs you need. Compact state, append, selected-Q extraction, R extraction, and positive-diagonal gauge remain on the device; no CPU fallback is used. CUDA requires the same vendor-library setup as other linalg operations. See Devices and GPU.
The frozen benchmark scope and acceptance thresholds are documented in the Phase-5 performance gate. They describe SRC-derived F64 matrices and do not imply equal speedups for every shape, dtype, provider, or thread count.
Hermitian eigenvalue decomposition
use tenferro_cpu::CpuEngine;
use tenferro_linalg::{Eigh, LinalgOps};
use tenferro_runtime::{Tensor, CoreOps};
fn max_abs_diff(lhs: &Tensor, rhs: &Tensor) -> Result<f64, tenferro_tensor::Error> {
let lhs = lhs.as_slice::<f64>()?;
let rhs = rhs.as_slice::<f64>()?;
Ok(lhs
.iter()
.zip(rhs.iter())
.map(|(lhs, rhs)| (lhs - rhs).abs())
.fold(0.0, f64::max))
}
let a = Tensor::from_vec_col_major(vec![2, 2], vec![2.0_f64, 1.0, 1.0, 2.0])?;
let mut engine = CpuEngine::serial();
let Eigh { values, vectors } = a.eigh(&mut engine)?;
assert_eq!(values.shape(), &[2]);
assert_eq!(vectors.shape(), &[2, 2]);
let value_slice = values.as_slice::<f64>()?;
let diagonal = Tensor::from_vec_col_major(
vec![2, 2],
vec![value_slice[0], 0.0, 0.0, value_slice[1]],
)?;
let vd = vectors.matmul(&diagonal, &mut engine)?;
let vt = vectors.transpose(&[1, 0], &mut engine)?;
let reconstructed = vd.matmul(&vt, &mut engine)?;
assert_eq!(a.shape(), &[2, 2]);
assert!(max_abs_diff(&reconstructed, &a)? < 1.0e-12);Traced Cholesky Factorization
use tenferro_cpu::{runtime_engine_id, runtime_engine_registration, CpuEngine};
use tenferro_runtime::{TraceContext, ExecutionEngine, GraphCompiler, Runtime, TracedTensor};
use tenferro_linalg::TracedLinalgOps;
let trace = TraceContext::new();
let a = trace.from_vec_col_major(vec![2, 2], vec![4.0_f64, 0.0, 0.0, 9.0])?;
let factor = a.cholesky()?;
let mut compiler = GraphCompiler::new();
let program = compiler.compile(&factor)?;
let mut engine = CpuEngine::serial();
let mut builder = Runtime::builder();
builder
.register_engine(runtime_engine_registration(&engine)?)?;
builder
.install_extension_module(
tenferro_linalg::extension_module::<CpuEngine>(runtime_engine_id()?)?,
)?;
let runtime = builder.build()?;
let prepared = runtime.prepare(&program, &[], &[engine.target()])?;
let mut outputs = runtime.run(&mut [&mut engine], &prepared, &[])?;
let result = outputs.remove(0).into_tensor(&mut engine)?;
assert_eq!(result.shape(), &[2, 2]);
assert_eq!(result.as_slice::<f64>()?, &[2.0, 0.0, 0.0, 3.0]);Traced Solve In A Graph
use tenferro_cpu::{runtime_engine_id, runtime_engine_registration, CpuEngine};
use tenferro_runtime::{TraceContext, ExecutionEngine, GraphCompiler, Runtime, TracedTensor};
use tenferro_linalg::TracedLinalgOps;
let trace = TraceContext::new();
let a = trace.from_vec_col_major(vec![2, 2], vec![4.0_f64, 0.0, 0.0, 9.0])?;
let b = trace.from_vec_col_major(vec![2, 1], vec![8.0_f64, 27.0])?;
let x = a.solve(&b)?;
let mut compiler = GraphCompiler::new();
let program = compiler.compile(&x)?;
let mut engine = CpuEngine::serial();
let mut builder = Runtime::builder();
builder
.register_engine(runtime_engine_registration(&engine)?)?;
builder
.install_extension_module(
tenferro_linalg::extension_module::<CpuEngine>(runtime_engine_id()?)?,
)?;
let runtime = builder.build()?;
let prepared = runtime.prepare(&program, &[], &[engine.target()])?;
let mut outputs = runtime.run(&mut [&mut engine], &prepared, &[])?;
let result = outputs.remove(0).into_tensor(&mut engine)?;
assert_eq!(result.shape(), &[2, 1]);
assert_eq!(result.as_slice::<f64>()?, &[2.0, 3.0]);Complete-Pivot LU Solve
full_piv_lu returns FullPivLu { p, l, u, q, parity } with the reconstruction convention A = P^T * L * U * Q, equivalently P * A * Q^T = L * U. The parity output is a scalar tensor containing +1 or -1. On an owned Tensor it is real (F32 for F32/C32 inputs and F64 for F64/C64 inputs); the borrowed route returns it in the input dtype, and a typed complex call returns Unsupported until the two routes agree (#2552 Q21). full_piv_lu_solve solves A * x = b; the lower-level backend contract also exposes an explicit transpose flag.
use tenferro_cpu::CpuEngine;
use tenferro_linalg::{FullPivLu, LinalgOps};
use tenferro_runtime::{Tensor, CoreOps};
fn max_abs_diff(lhs: &Tensor, rhs: &Tensor) -> Result<f64, tenferro_tensor::Error> {
let lhs = lhs.as_slice::<f64>()?;
let rhs = rhs.as_slice::<f64>()?;
Ok(lhs
.iter()
.zip(rhs.iter())
.map(|(lhs, rhs)| (lhs - rhs).abs())
.fold(0.0, f64::max))
}
let mut engine = CpuEngine::serial();
let a = Tensor::from_vec_col_major(
vec![4, 4],
vec![
0.0_f64, 4.0, 7.0, 1.0,
2.0, 5.0, 8.0, 0.0,
3.0, 6.0, 10.0, 2.0,
1.0, 2.0, 3.0, 4.0,
],
)?;
let b = Tensor::from_vec_col_major(vec![4, 1], vec![1.0_f64, 2.0, 3.0, 4.0])?;
let FullPivLu { p, l, u, q, parity } = a.full_piv_lu(&mut engine)?;
let pt = p.transpose(&[1, 0], &mut engine)?;
let pt_l = pt.matmul(&l, &mut engine)?;
let pt_lu = pt_l.matmul(&u, &mut engine)?;
let reconstructed = pt_lu.matmul(&q, &mut engine)?;
let x = a.full_piv_lu_solve(&b, &mut engine)?;
assert_eq!(p.shape(), &[4, 4]);
assert_eq!(a.shape(), &[4, 4]);
assert!(max_abs_diff(&reconstructed, &a)? < 1.0e-12);
assert_eq!(parity.shape(), &[] as &[usize]);
let parity_value = parity
.as_slice::<f64>()?
.first()
.copied()
.ok_or_else(|| tenferro_tensor::Error::Internal("missing LU parity value".to_owned()))?;
assert!(parity_value == 1.0 || parity_value == -1.0);
assert_eq!(x.shape(), &[4, 1]);