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:
| Layer | Trait | Receiver | Spellings |
|---|---|---|---|
| concrete | LinalgOps | anything that implements AsView: Tensor, TensorRead, TypedTensor<T>, TypedTensorView<T> | a.svd(exec), a.svd_with(&opts, exec), a.solve_into(&b, exec, dest) |
| traced | TracedLinalgOps | TracedTensor | t.svd(), t.svd_with(&opts) |
eager (autodiff) | EagerLinalgOps | EagerSession | sess.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
| Feature | Enables |
|---|---|
autodiff | The eager layer (EagerLinalgOps) and AD rules. Adds the tenferro-ad dependency. |
cuda | CUDA 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§
- Cholesky
Options - Options for a Cholesky factorization.
- Eig
- General eigendecomposition.
- Eigh
- Hermitian/symmetric eigendecomposition.
- Eigh
Options - Options for Hermitian eigenvalue decomposition.
- Eigvalsh
Options - Options for Hermitian eigenvalues only.
- Full
PivLu - Full-pivot LU decomposition
P A Q = L U. - Householder
Qr - Opaque compact Householder QR state.
- Linalg
AdMode Support - User-visible AD support for one mode.
- Linalg
AdOutput Support - AD support status for one output of a linalg operation.
- Linalg
AdSupport - AD support manifest entry for one linalg operation.
- Lu
- Partial-pivot LU decomposition
P A = L U. - Norm
Options - Options for a norm.
- Pinv
Options - Options for the Moore-Penrose pseudoinverse.
- Qr
- QR decomposition
A = Q R. - QrOptions
- Options for QR decomposition.
- Rank
Revealing QrOptions - Options for column-pivoted rank-revealing QR.
- Rank
Revealing QrResult - 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.
- Svdvals
Options - Options for singular values only.
- Triangular
Solve Options - Options for a triangular solve.
Enums§
- Diag
- Whether a triangular matrix has an implicit unit diagonal.
- Eigh
Batch Policy - Whether a batched
EighOptionscall may fall back to one launch per matrix. - Eigh
Driver - Algorithm family used by
EighOptions. - Eigh
Gauge - Eigenvector gauge convention used by
EighOptions. - Keep
Dims - Whether a reduction keeps reduced axes as size-one axes.
- Linalg
AdOp Kind - Operation keys covered by the linalg AD support manifest.
- Linalg
AdRoute - Implementation route used for a user-visible AD mode.
- Linalg
AdRule Support - 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§
- Eager
Linalg Ops - Linear algebra on eager tensors, with the session as receiver. Eager operations execute immediately and record the tape for reverse-mode differentiation.
- Linalg
Ops - Linear algebra on anything that implements
AsView: owned and borrowed tensors, typed tensors and strided views. Results areTensors for erased inputs and typed tensors for typed inputs. Every operation takes the options last-but-one and the engine last. - Linalg
Repr - A
Reprthat can also name the real, complex and index results of a linalg operation. - Linalg
Scalar - Scalar types supported by statically typed linear algebra methods:
f32,f64,Complex32andComplex64. - Traced
Linalg Ops - 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 ncolumn-major blocks in place. - semantic_
ad_ rules - Return the linalg semantic-program AD rule set.