Skip to main content

Crate tenferro_linalg

Crate tenferro_linalg 

Source
Expand description

Linear algebra operations for tenferro.

This crate owns the graph-facing linalg op payloads, their runtime registration, the CPU linalg kernels and the public linalg grammar (#2552). Every operation is declared once in the operation registry and offered on three layers with the same three spellings:

LayerTraitReceiverSpellings
concreteLinalgOpsanything that implements AsView: Tensor, TensorRead, TypedTensor<T>, TypedTensorView<T>a.svd(exec), a.svd_with(&opts, exec), a.solve_into(&b, exec, dest)
tracedTracedLinalgOpsTracedTensort.svd(), t.svd_with(&opts)
eager (autodiff)EagerLinalgOpsEagerSessionsess.svd(&x), sess.svd_with(&x, &opts)

An operation has an options type (SvdOptions, PinvOptions, …) only when it has semantic options; solve, lstsq, lu, eig, det, inv and the other operations without settings have neither an options type nor a _with form; factorizations return named structs (Svd, Qr, Lu, …) that are destructured by field. The generated registry page (docs/spec/generated/api-ops.md) lists the operations, their layout handling, errors and omissions.

An operation without options has no _with form and no options type:

ⓘ
use tenferro_cpu::CpuEngine;
use tenferro_linalg::LinalgOps;
use tenferro_tensor::Tensor;

let a = Tensor::from_vec_col_major(vec![2, 2], vec![4.0_f64, 2.0, 2.0, 3.0]).unwrap();
let _ = a.solve_with(&a, &mut CpuEngine::serial());
ⓘ
use tenferro_linalg::SolveOptions;

§Examples

Traced: record, compile, run.

use tenferro_cpu::CpuEngine;
use tenferro_linalg::TracedLinalgOps;
use tenferro_runtime::{ExecutionEngine, GraphCompiler, Runtime, TraceContext};

let trace = TraceContext::new();
let a = trace.from_vec_col_major(vec![2, 2], vec![4.0_f64, 2.0, 2.0, 3.0])?;
let l = a.cholesky()?;

let program = GraphCompiler::new().compile(&l)?;
let mut backend = CpuEngine::serial();
let engine_id = tenferro_cpu::runtime_engine_id()?;
let mut builder = Runtime::builder();
builder.register_engine(tenferro_cpu::runtime_engine_registration(&backend)?)?;
builder.install_extension_module(tenferro_linalg::extension_module::<CpuEngine>(engine_id)?)?;
let runtime = builder.build()?;
let prepared = runtime.prepare(&program, &[], &[backend.target()])?;
let out = {
    let mut engines: [&mut dyn ExecutionEngine; 1] = [&mut backend];
    runtime.run(&mut engines, &prepared, &[])?.pop().ok_or("no output")?
}
.into_tensor(&mut backend)?;
assert_eq!(out.shape(), &[2, 2]);

Concrete, on a typed tensor; the result is typed too:

use tenferro_cpu::CpuEngine;
use tenferro_linalg::{LinalgOps, Svd, TriangularSolveOptions};
use tenferro_tensor::TypedTensor;

let mut engine = CpuEngine::serial();
// Lower-triangular [[2, 0], [1, 1]] (column-major) and right-hand side.
let l = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![2.0, 1.0, 0.0, 1.0])?;
let b = TypedTensor::<f64>::from_vec_col_major(vec![2, 1], vec![4.0, 5.0])?;
let x = l.triangular_solve_with(&b, &TriangularSolveOptions::default(), &mut engine)?;
assert_eq!(x.host_data()?, &[2.0, 3.0]);

let Svd { s, .. } = l.svd(&mut engine)?;
assert_eq!(s.shape(), &[2]);

§Cargo features

FeatureEnables
autodiffThe eager layer (EagerLinalgOps) and AD rules. Adds the tenferro-ad dependency.
cudaCUDA execution through tenferro-gpu.

autodiff is not a heavy dependency switch: tenferro-ad is the crate that owns EagerSession/EagerTensor, so an eager linalg surface without it would save nothing and would only produce eager tensors whose linalg ops fail on backward (#1972). For inference without AD, call the same operations on concrete tensors through LinalgOps, which needs no autodiff.

§Lanes

A caller that splits one engine’s threads into lanes and runs a different factorization in each uses CpuEngine::with_lanes: every lane receives a &mut dyn Engine that the ordinary grammar accepts, so the lane call is view.svd_with(&opts, lane). Each lane runs on its share of the engine’s thread budget and draws every output, workspace and gather buffer from the caller’s pool for that lane, so a lane that keeps its pool reaches zero steady-state allocation for inputs without negative strides (a negative-stride input is gathered once into the lane’s pool). The dims and strides of an operand of rank 9 or more are heap metadata, so such an operand makes a few small allocations outside the pool per call.

Only svd, svdvals, qr, eigh, eigvalsh and eigvals run in a lane; every other operation returns Unsupported there (see the “Lanes” section of docs/guides/cpu-execution.md).

use tenferro_cpu::{linalg_interop::BufferPool, CpuEngine, Pool};
use tenferro_linalg::LinalgOps;
use tenferro_tensor::TypedTensor;

let a = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![4.0, 0.0, 0.0, 9.0])?;
let b = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![3.0, 0.0, 0.0, 2.0])?;
let mut engine = CpuEngine::new(Pool::builder().threads(2).build()?);
let mut pools = [BufferPool::new(), BufferPool::new()];
let out = engine.with_lanes(&[1, 1], &mut pools, |lane_index, lane| {
    let input = if lane_index == 0 { &a } else { &b };
    input.eigvalsh(lane).and_then(|w| Ok(w.host_data()?.to_vec()))
})?;
assert_eq!(out[0].as_ref().ok(), Some(&vec![4.0, 9.0]));
assert_eq!(out[1].as_ref().ok(), Some(&vec![2.0, 3.0]));

Re-exports§

pub use backend::LinalgBackend;
pub use error::Error;
pub use error::Result;

Modules§

backend
error
Domain errors owned by the linear-algebra extension.
prelude
The linear algebra grammar traits, options and result types (#2552).

Structs§

CholeskyOptions
Options for a Cholesky factorization.
Eig
General eigendecomposition.
Eigh
Hermitian/symmetric eigendecomposition.
EighOptions
Options for Hermitian eigenvalue decomposition.
EigvalshOptions
Options for Hermitian eigenvalues only.
FullPivLu
Full-pivot LU decomposition P A Q = L U.
HouseholderQr
Opaque compact Householder QR state.
LinalgAdModeSupport
User-visible AD support for one mode.
LinalgAdOutputSupport
AD support status for one output of a linalg operation.
LinalgAdSupport
AD support manifest entry for one linalg operation.
Lu
Partial-pivot LU decomposition P A = L U.
NormOptions
Options for a norm.
PinvOptions
Options for the Moore-Penrose pseudoinverse.
Qr
QR decomposition A = Q R.
QrOptions
Options for QR decomposition.
RankRevealingQrOptions
Options for column-pivoted rank-revealing QR.
RankRevealingQrResult
Four fixed-shape outputs of a rank-revealing QR factorization.
Slogdet
Sign and log-absolute-value of the determinant.
Svd
Thin or full singular value decomposition A = U diag(S) Vh.
SvdOptions
Options for singular value decomposition.
SvdvalsOptions
Options for singular values only.
TriangularSolveOptions
Options for a triangular solve.

Enums§

Diag
Whether a triangular matrix has an implicit unit diagonal.
EighBatchPolicy
Whether a batched EighOptions call may fall back to one launch per matrix.
EighDriver
Algorithm family used by EighOptions.
EighGauge
Eigenvector gauge convention used by EighOptions.
KeepDims
Whether a reduction keeps reduced axes as size-one axes.
LinalgAdOpKind
Operation keys covered by the linalg AD support manifest.
LinalgAdRoute
Implementation route used for a user-visible AD mode.
LinalgAdRuleSupport
AD rule support status for a linalg operation or output.
MatOp
Transformation applied to a matrix operand.
NormOrd
The order of a norm.
QrGauge
QR factor gauge convention used by QrOptions.
Side
Which side the matrix operand acts from.
SvdDriver
Algorithm family used by SvdOptions.
SvdGauge
Singular-vector gauge convention used by SvdOptions.
SvdShape
Whether an SVD returns the thin or the full-matrices factors.
Uplo
Which triangle of a matrix is referenced.

Constants§

DEFAULT_DECOMPOSITION_DERIVATIVE_EPS
Default derivative regularization used by decomposition AD rules.
LINALG_EXTENSION_FAMILY_ID

Traits§

EagerLinalgOps
Linear algebra on eager tensors, with the session as receiver. Eager operations execute immediately and record the tape for reverse-mode differentiation.
LinalgOps
Linear algebra on anything that implements AsView: owned and borrowed tensors, typed tensors and strided views. Results are Tensors for erased inputs and typed tensors for typed inputs. Every operation takes the options last-but-one and the engine last.
LinalgRepr
A Repr that can also name the real, complex and index results of a linalg operation.
LinalgScalar
Scalar types supported by statically typed linear algebra methods: f32, f64, Complex32 and Complex64.
TracedLinalgOps
Linear algebra on traced tensors: each call records graph nodes and returns traced results; execution happens when the graph is prepared and run. Shape and dtype problems that are known at record time are reported by the call; the rest surface when the graph is compiled or run.

Functions§

all_linalg_ad_support
Return the complete linalg AD support manifest.
extension_module
Build this extension module for one runtime engine.
linalg_ad_support
Return the support manifest entry for one linalg operation kind.
normalize_eig_vectors
Normalize the eigenvector columns of a batch of n x n column-major blocks in place.
semantic_ad_rules
Return the linalg semantic-program AD rule set.