Crate tenferro_linalg

Expand description

Linear algebra extension operations for tenferro.

This crate owns the graph-facing linalg op payloads and runtime registration. Tensor-facing operations are exposed through extension traits. CPU backend kernels live in this crate behind the linalg backend trait. A CPU backend paired by tenferro_gpu::apple::AppleContext additionally supports guarded rank-2 Cholesky on matching Apple managed F32, F64, C32, and C64 tensors. This is an explicit CPU selection and is not a general managed-memory fallback for other linalg operations.

§Examples

use tenferro_linalg::TracedTensorLinalgExt;
use tenferro_cpu::CpuBackend;
use tenferro_runtime::{GraphCompiler, Runtime, TracedTensor};

let a = TracedTensor::from_vec_col_major(
    vec![2, 2],
    vec![4.0_f64, 2.0, 2.0, 3.0],
)
.unwrap();
let l = a.cholesky().unwrap();

let mut compiler = GraphCompiler::new();
let program = compiler.compile(&l).unwrap();
let backend = CpuBackend::new();
let engine_id = tenferro_cpu::runtime_engine_id().unwrap();
let mut builder = Runtime::builder();
builder
    .register_engine(tenferro_cpu::runtime_engine_registration(&backend).unwrap())
    .unwrap();
builder
    .install_extension_module(tenferro_linalg::extension_module::<CpuBackend>(engine_id).unwrap())
    .unwrap();
let runtime = builder.build().unwrap();
let out = runtime.run_compiled(&program, &[]).unwrap().pop().unwrap();
assert_eq!(out.shape(), &[2, 2]);

§Cargo features

Feature	Enables
`cpu-faer` (default) and the other CPU provider features	Forwarded to `tenferro-cpu`; see its documentation.
`autodiff`	The eager surface (`EagerSessionLinalgExt`, `EagerTensorLinalgExt`) and AD rules. Adds the `tenferro-ad` dependency.
`cuda`	CUDA execution through `tenferro-gpu`.
`webgpu`	WebGPU/Metal execution through `tenferro-gpu` (a subset of operations).
`rocm`	Placeholder; HIP/ROCm is not implemented.

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 inside a backend session through TensorLinalgExt / TypedTensorLinalgExt, which need no autodiff:

use tenferro_cpu::CpuBackend;
use tenferro_linalg::TypedTensorLinalgExt;
use tenferro_tensor::{BackendSessionHost, TypedTensor};

let mut backend = CpuBackend::new();
// 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 = backend.with_backend_session(|session| {
    // left_side, lower, transpose_a, unit_diagonal
    l.triangular_solve(&b, true, true, false, false, session)
})??;
assert_eq!(x.host_data()?, &[2.0, 3.0]);

Re-exports§

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

Modules§

backend
cpu_kernels: Injectable CPU linear-algebra kernels.
error: Domain errors owned by the linear-algebra extension.
prelude: Linear algebra extension traits and their method-resolution types.

Structs§

EighOptions: Options for Hermitian eigenvalue decomposition.
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.
QrOptions: Options for QR decomposition.
RankRevealingQrOptions: Options for column-pivoted rank-revealing QR.
RankRevealingQrResult: Four fixed-shape outputs of a rank-revealing QR factorization.
SvdOptions: Options for singular value decomposition.

Enums§

EighDriver: cuSOLVER Hermitian eigensolver selection used by EighOptions on the CUDA backend.
EighGauge: Eigenvector gauge convention used by EighOptions.
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.
QrGauge: QR factor gauge convention used by QrOptions.
SvdDriver: cuSOLVER SVD routine selection used by SvdOptions on the CUDA backend.
SvdGauge: Singular-vector gauge convention used by SvdOptions.

Constants§

DEFAULT_DECOMPOSITION_DERIVATIVE_EPS: Default derivative regularization used by decomposition AD rules.
LINALG_EXTENSION_FAMILY_ID

Traits§

EagerSessionLinalgExt: Linear algebra operations on a runtime-bound borrowed eager session.
EagerTensorLinalgExt: Tensor-owned linear solve. Other eager linear-algebra operations use EagerSessionLinalgExt inside tenferro_ad::EagerRuntime::with_eager_session.
LinalgScalar: Scalar types supported by statically typed linear algebra methods.
TensorLinalgExt: Linear algebra methods for dtype-erased owned tensors.
TensorReadLinalgExt: Linear algebra methods for borrowed tensor reads.
TracedTensorLinalgExt: Linear algebra extension methods for TracedTensor.
TypedTensorLinalgExt: Linear algebra methods with statically typed inputs and outputs.

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.
semantic_ad_rules: Return the linalg semantic-program AD rule set.

Type Aliases§

TypedEig: Fixed typed output tuple for general eigendecomposition.
TypedFullPivLu: Fixed typed output tuple for complete-pivot LU decomposition.
TypedLu: Fixed typed output tuple for LU decomposition.
TypedRankRevealingQrResult: Fixed typed output for rank-revealing QR.
TypedSvd: Fixed typed output tuple for singular value decomposition.