Skip to main content

tenferro_linalg/
lib.rs

1//! Linear algebra operations for tenferro.
2//!
3//! This crate owns the graph-facing linalg op payloads, their runtime
4//! registration, the CPU linalg kernels and the public linalg grammar
5//! (#2552). Every operation is declared once in the operation registry and
6//! offered on three layers with the same three spellings:
7//!
8//! | Layer | Trait | Receiver | Spellings |
9//! |---|---|---|---|
10//! | concrete | [`LinalgOps`] | anything that implements [`AsView`](tenferro_tensor::AsView): `Tensor`, `TensorRead`, `TypedTensor<T>`, `TypedTensorView<T>` | `a.svd(exec)`, `a.svd_with(&opts, exec)`, `a.solve_into(&b, exec, dest)` |
11//! | traced | [`TracedLinalgOps`] | [`TracedTensor`](tenferro_runtime::TracedTensor) | `t.svd()`, `t.svd_with(&opts)` |
12//! | eager (`autodiff`) | `EagerLinalgOps` | `EagerSession` | `sess.svd(&x)`, `sess.svd_with(&x, &opts)` |
13//!
14//! An operation has an options type (`SvdOptions`, `PinvOptions`, ...) only
15//! when it has semantic options; `solve`, `lstsq`, `lu`, `eig`, `det`, `inv`
16//! and the other operations without settings have neither an options type nor
17//! a `_with` form;
18//! factorizations return named structs ([`Svd`], [`Qr`], [`Lu`], ...) that are
19//! destructured by field. The generated registry page
20//! (`docs/spec/generated/api-ops.md`) lists the operations, their layout
21//! handling, errors and omissions.
22//!
23//! An operation without options has no `_with` form and no options type:
24//!
25//! ```compile_fail,E0599
26//! use tenferro_cpu::CpuEngine;
27//! use tenferro_linalg::LinalgOps;
28//! use tenferro_tensor::Tensor;
29//!
30//! let a = Tensor::from_vec_col_major(vec![2, 2], vec![4.0_f64, 2.0, 2.0, 3.0]).unwrap();
31//! let _ = a.solve_with(&a, &mut CpuEngine::serial());
32//! ```
33//!
34//! ```compile_fail,E0432
35//! use tenferro_linalg::SolveOptions;
36//! ```
37//!
38//! # Examples
39//!
40//! Traced: record, compile, run.
41//!
42//! ```
43//! use tenferro_cpu::CpuEngine;
44//! use tenferro_linalg::TracedLinalgOps;
45//! use tenferro_runtime::{ExecutionEngine, GraphCompiler, Runtime, TraceContext};
46//!
47//! let trace = TraceContext::new();
48//! let a = trace.from_vec_col_major(vec![2, 2], vec![4.0_f64, 2.0, 2.0, 3.0])?;
49//! let l = a.cholesky()?;
50//!
51//! let program = GraphCompiler::new().compile(&l)?;
52//! let mut backend = CpuEngine::serial();
53//! let engine_id = tenferro_cpu::runtime_engine_id()?;
54//! let mut builder = Runtime::builder();
55//! builder.register_engine(tenferro_cpu::runtime_engine_registration(&backend)?)?;
56//! builder.install_extension_module(tenferro_linalg::extension_module::<CpuEngine>(engine_id)?)?;
57//! let runtime = builder.build()?;
58//! let prepared = runtime.prepare(&program, &[], &[backend.target()])?;
59//! let out = {
60//!     let mut engines: [&mut dyn ExecutionEngine; 1] = [&mut backend];
61//!     runtime.run(&mut engines, &prepared, &[])?.pop().ok_or("no output")?
62//! }
63//! .into_tensor(&mut backend)?;
64//! assert_eq!(out.shape(), &[2, 2]);
65//! # Ok::<(), Box<dyn std::error::Error>>(())
66//! ```
67//!
68//! Concrete, on a typed tensor; the result is typed too:
69//!
70//! ```
71//! use tenferro_cpu::CpuEngine;
72//! use tenferro_linalg::{LinalgOps, Svd, TriangularSolveOptions};
73//! use tenferro_tensor::TypedTensor;
74//!
75//! let mut engine = CpuEngine::serial();
76//! // Lower-triangular [[2, 0], [1, 1]] (column-major) and right-hand side.
77//! let l = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![2.0, 1.0, 0.0, 1.0])?;
78//! let b = TypedTensor::<f64>::from_vec_col_major(vec![2, 1], vec![4.0, 5.0])?;
79//! let x = l.triangular_solve_with(&b, &TriangularSolveOptions::default(), &mut engine)?;
80//! assert_eq!(x.host_data()?, &[2.0, 3.0]);
81//!
82//! let Svd { s, .. } = l.svd(&mut engine)?;
83//! assert_eq!(s.shape(), &[2]);
84//! # Ok::<(), Box<dyn std::error::Error>>(())
85//! ```
86//!
87//! # Cargo features
88//!
89//! | Feature | Enables |
90//! |---|---|
91//! | `autodiff` | The eager layer (`EagerLinalgOps`) and AD rules. Adds the `tenferro-ad` dependency. |
92//! | `cuda` | CUDA execution through `tenferro-gpu`. |
93//!
94//! `autodiff` is not a heavy dependency switch: `tenferro-ad` is the crate that
95//! owns `EagerSession`/`EagerTensor`, so an eager linalg surface without it
96//! would save nothing and would only produce eager tensors whose linalg ops
97//! fail on backward (#1972). For inference without AD, call the same
98//! operations on concrete tensors through [`LinalgOps`], which needs no
99//! `autodiff`.
100//!
101//! # Lanes
102//!
103//! A caller that splits one engine's threads into lanes and runs a different
104//! factorization in each uses `CpuEngine::with_lanes`: every lane receives a
105//! `&mut dyn Engine` that the ordinary grammar accepts, so the lane call is
106//! `view.svd_with(&opts, lane)`. Each lane runs on its share of the engine's
107//! thread budget and draws every output, workspace and gather buffer from the
108//! caller's pool for that lane, so a lane that keeps its pool reaches zero
109//! steady-state allocation for inputs without negative strides (a
110//! negative-stride input is gathered once into the lane's pool). The dims and
111//! strides of an operand of rank 9 or more are heap metadata, so such an
112//! operand makes a few small allocations outside the pool per call.
113//!
114//! Only svd, svdvals, qr, eigh, eigvalsh and eigvals run in a lane; every other
115//! operation returns `Unsupported` there (see the "Lanes" section of
116//! `docs/guides/cpu-execution.md`).
117//!
118//! ```rust
119//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
120//! use tenferro_cpu::{linalg_interop::BufferPool, CpuEngine, Pool};
121//! use tenferro_linalg::LinalgOps;
122//! use tenferro_tensor::TypedTensor;
123//!
124//! let a = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![4.0, 0.0, 0.0, 9.0])?;
125//! let b = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![3.0, 0.0, 0.0, 2.0])?;
126//! let mut engine = CpuEngine::new(Pool::builder().threads(2).build()?);
127//! let mut pools = [BufferPool::new(), BufferPool::new()];
128//! let out = engine.with_lanes(&[1, 1], &mut pools, |lane_index, lane| {
129//!     let input = if lane_index == 0 { &a } else { &b };
130//!     input.eigvalsh(lane).and_then(|w| Ok(w.host_data()?.to_vec()))
131//! })?;
132//! assert_eq!(out[0].as_ref().ok(), Some(&vec![4.0, 9.0]));
133//! assert_eq!(out[1].as_ref().ok(), Some(&vec![2.0, 3.0]));
134//! # Ok(())
135//! # }
136//! ```
137// A misaligned pointer handed to a CUDA library is undefined behaviour and
138// fails only on some library versions: `cuDoubleComplex` is `double2`, which
139// CUDA declares `__align__(16)`, while `num_complex::Complex64` is 8-aligned,
140// so casting `&Complex64` to `*const cuDoubleComplex` produced a pointer
141// cuBLAS >= 12.9 faults on (issue #1870). Deny the whole cast class at this
142// FFI boundary rather than re-auditing it by hand.
143#![cfg_attr(docsrs, feature(doc_cfg))]
144#![deny(clippy::cast_ptr_alignment)]
145
146#[cfg(feature = "autodiff")]
147mod ad;
148mod api;
149pub mod backend;
150mod cpu;
151#[cfg(feature = "autodiff")]
152mod eager_composites;
153#[cfg(feature = "autodiff")]
154mod eager_ext;
155mod eig_normalize;
156pub mod error;
157mod extension;
158mod flags;
159#[cfg(feature = "cuda")]
160mod gpu;
161mod householder;
162mod lane;
163pub mod prelude;
164mod rank_revealing_qr;
165mod results;
166mod tensor_ext;
167mod traced;
168mod validation;
169
170#[cfg(feature = "autodiff")]
171pub use ad::semantic_ad_rules;
172#[cfg(feature = "autodiff")]
173pub use ad::support::{
174    all_linalg_ad_support, linalg_ad_support, LinalgAdModeSupport, LinalgAdOpKind,
175    LinalgAdOutputSupport, LinalgAdRoute, LinalgAdRuleSupport, LinalgAdSupport,
176};
177#[cfg(feature = "autodiff")]
178#[cfg_attr(docsrs, doc(cfg(feature = "autodiff")))]
179pub use api::EagerLinalgOps;
180pub use api::{
181    CholeskyOptions, EigvalshOptions, LinalgOps, LinalgRepr, NormOptions, NormOrd, PinvOptions,
182    SvdvalsOptions, TracedLinalgOps, TriangularSolveOptions,
183};
184pub use backend::LinalgBackend;
185pub use eig_normalize::normalize_eig_vectors;
186pub use error::{Error, Result};
187pub use extension::{
188    extension_module, EighBatchPolicy, EighDriver, EighGauge, EighOptions, QrGauge, QrOptions,
189    SvdDriver, SvdGauge, SvdOptions, DEFAULT_DECOMPOSITION_DERIVATIVE_EPS,
190    LINALG_EXTENSION_FAMILY_ID,
191};
192
193/// Whether the loaded cuSOLVER can diagonalise a whole batch of Hermitian
194/// matrices in one launch.
195///
196/// This is the capability [`EighBatchPolicy::RequireBatched`] needs, exposed so
197/// a caller can branch before the call instead of catching the error. `Ok(true)`
198/// means `cusolverDnXsyevBatched` is callable for
199/// [`EighDriver::Auto`]/[`EighDriver::DivideAndConquer`] on a batch of more than
200/// one matrix; `Ok(false)` means the loaded cuSOLVER lacks it, and `eigh` keeps
201/// today's per-matrix loop unless the caller asks for
202/// [`EighBatchPolicy::RequireBatched`].
203///
204/// The answer follows the process-wide cuSOLVER library, which is loaded once
205/// and never reloaded, so the same value is reported for the life of the
206/// process.
207///
208/// # Examples
209///
210/// ```rust
211/// # #[cfg(feature = "cuda")] {
212/// use tenferro_linalg::{cuda_batched_eigh_available, EighBatchPolicy, EighOptions};
213///
214/// // Branch ahead of the call: promise one launch per batch only when the
215/// // capability is really there.
216/// let policy = match cuda_batched_eigh_available() {
217///     Ok(true) => EighBatchPolicy::RequireBatched,
218///     // A loaded library without the entry point, or no cuSOLVER at all.
219///     Ok(false) | Err(_) => EighBatchPolicy::AllowPerMatrixFallback,
220/// };
221/// let options = EighOptions::default().batch_policy(policy);
222/// assert_eq!(options.batch_policy, policy);
223/// # }
224/// ```
225///
226/// # Errors
227///
228/// Returns [`tenferro_tensor::Error::IoSource`] (with the typed
229/// `CudaLibraryLoadError`) when the cuSOLVER shared library, or a symbol this
230/// crate requires from it, cannot be loaded, and
231/// [`tenferro_tensor::Error::BackendFailure`] when the loaded library cannot
232/// create its handle — `cusolverDnCreate`, or the parameter object
233/// `cusolverDnCreateParams` — so a driver that is present but unusable is
234/// reported, not hidden behind a capability answer. A missing batched entry
235/// point is not an error: it is the `Ok(false)` answer.
236#[cfg(feature = "cuda")]
237#[cfg_attr(docsrs, doc(cfg(feature = "cuda")))]
238pub fn cuda_batched_eigh_available() -> tenferro_tensor::Result<bool> {
239    gpu::batched_eigh_available()
240}
241pub use flags::{Diag, KeepDims, MatOp, Side, SvdShape, Uplo};
242pub use householder::HouseholderQr;
243pub use rank_revealing_qr::{RankRevealingQrOptions, RankRevealingQrResult};
244pub use results::{Eig, Eigh, FullPivLu, Lu, Qr, Slogdet, Svd};
245pub use tensor_ext::LinalgScalar;
246pub(crate) use tensor_ext::{OwnedLinalg, ReadLinalg};