mdarray_linalg_tblis/lib.rs
1//! # mdarray_linalg_tblis
2//!
3//! [TBLIS](https://github.com/devinamatthews/tblis) backend for [`mdarray_linalg`].
4//!
5//! This crate provides the [`Tblis`] struct that implements matrix multiplication and
6//! tensor contraction traits from [`mdarray_linalg`], delegating to the high-performance
7//! C library TBLIS. TBLIS is specifically designed for **dense tensor contractions**
8//! and shines on large, high-rank tensors where BLAS-based backends would need costly
9//! transpositions.
10//!
11//! Backend implementation modules are private. Use [`Tblis`] together with the
12//! operation traits from `mdarray_linalg::prelude::*`.
13//!
14//! ## Scope
15//!
16//! The TBLIS backend covers:
17//!
18//! - **Matrix multiplication** — `matmul`
19//! - **Tensor contraction** — `contract_all`, `contract_n`, `contract_pairs`, `contract` (einsum)
20//!
21//! For vector operations, decompositions, or solving, use another backend
22//! ([`mdarray_linalg_blas`], [`mdarray_linalg_faer`], etc.).
23//!
24//! ## Setup
25//!
26//! This crate binds to TBLIS but does not choose which native TBLIS library to link against.
27//! This is left to the user. For example, to link against an installed TBLIS library:
28//!
29//! ```bash
30//! cargo add mdarray mdarray-linalg mdarray-linalg-tblis
31//! cargo add tblis-src
32//! ```
33//!
34//! In one of your Rust crates, reference the provider so its link directives are
35//! included:
36//!
37//! ```rust
38//! extern crate tblis_src as _;
39//! ```
40//!
41//! If TBLIS is installed outside standard linker paths, set `TBLIS_DIR`,
42//! `LD_LIBRARY_PATH`, or equivalent linker/runtime configuration. If you need
43//! to install TBLIS from source, see the
44//! [upstream build guide](https://github.com/MatthewsResearchGroup/tblis/wiki/Building).
45//! You may also provide equivalent link flags from your application `build.rs`.
46//!
47//! ## Example
48//!
49//! All operations are accessed through the [`Tblis`] backend:
50//!
51//! ```rust
52//! # extern crate tblis_src as _;
53//! use mdarray::array;
54//! use mdarray_linalg::prelude::*;
55//! use mdarray_linalg_tblis::Tblis;
56//!
57//! // ----- Matrix multiplication -----
58//! let a = array![[1., 2.], [3., 4.]];
59//! let b = array![[5., 6.], [7., 8.]];
60//!
61//! let c = Tblis.matmul(&a, &b).eval();
62//! assert_eq!(c, array![[19., 22.], [43., 50.]]);
63//!
64//! // ----- Tensor contraction: contract last n axes -----
65//! let t1 = array![[1., 2.], [3., 4.]].into_dyn();
66//! let t2 = array![[5., 6.], [7., 8.]].into_dyn();
67//!
68//! // Full contraction (contract_all) → scalar
69//! let scalar = Tblis.contract_all(&t1, &t2);
70//! assert_eq!(scalar, 70.0); // 1·5 + 2·6 + 3·7 + 4·8
71//!
72//! // ----- Outer product (contract_n with n=0) -----
73//! let x = array![1., 2.].into_dyn();
74//! let y = array![3., 4.].into_dyn();
75//! let outer = Tblis.contract_n(&x, &y, 0).eval();
76//! assert_eq!(outer, array![[3., 4.], [6., 8.]].into_dyn());
77//!
78//! // ----- Einsum-style contraction -----
79//! // ij,jk->ik (matrix multiplication)
80//! let result = Tblis
81//! .contract(&t1, &t2, &[0, 1], &[1, 2], &[0, 2])
82//! .eval();
83//! assert_eq!(result, array![[19., 22.], [43., 50.]].into_dyn());
84//!
85//! // ij,ij-> (full contraction)
86//! let result = Tblis
87//! .contract(&t1, &t2, &[0, 1], &[0, 1], &[])
88//! .eval();
89//! assert_eq!(result.into_scalar(), 70.0);
90//!
91//! // ij,jk->ki (matmul with transposed output)
92//! let result = Tblis
93//! .contract(&t1, &t2, &[0, 1], &[1, 2], &[2, 0])
94//! .eval();
95//! assert_eq!(result, array![[19., 43.], [22., 50.]].into_dyn());
96//!
97//! // i,j->ij (outer product via einsum)
98//! let result = Tblis
99//! .contract(&x, &y, &[0], &[1], &[0, 1])
100//! .eval();
101//! assert_eq!(result, array![[3., 4.], [6., 8.]].into_dyn());
102//!
103//! // ----- Scaled addition: C = α·A·B + β·C -----
104//! let mut c = array![[1., 1.], [1., 1.]];
105//! Tblis.matmul(&a, &b).add_to_scaled(&mut c, 2.0);
106//! // C = A·B + 2·C = [[19,22],[43,50]] + 2·[[1,1],[1,1]]
107//! ```
108//!
109//! ## Supported types
110//!
111//! `f32`, `f64`, `Complex<f32>`, `Complex<f64>`.
112//!
113//! ## Troubleshooting
114//!
115//! Linking errors usually mean that the native TBLIS library was not linked
116//! into the final binary, or that it is not in the linker/runtime search path.
117//! Add `tblis-src`, reference it from Rust code, or provide equivalent link
118//! flags from your application `build.rs`.
119//!
120// Keep the doc-comment blank line above: these reference definitions must start
121// a separate Markdown block from the preceding paragraph.
122#![cfg_attr(docsrs, doc = concat!(
123 "[`mdarray_linalg`]: https://docs.rs/mdarray-linalg/", env!("CARGO_PKG_VERSION"), "/mdarray_linalg/\n",
124 "[`mdarray_linalg_blas`]: https://docs.rs/mdarray-linalg-blas/", env!("CARGO_PKG_VERSION"), "/mdarray_linalg_blas/\n",
125 "[`mdarray_linalg_faer`]: https://docs.rs/mdarray-linalg-faer/", env!("CARGO_PKG_VERSION"), "/mdarray_linalg_faer/",
126))]
127#![cfg_attr(not(docsrs), doc = "\
128[`mdarray_linalg`]: ../mdarray_linalg/index.html
129[`mdarray_linalg_blas`]: ../mdarray_linalg_blas/index.html
130[`mdarray_linalg_faer`]: ../mdarray_linalg_faer/index.html
131")]
132
133#[cfg(test)]
134extern crate tblis_src as _;
135
136mod contract;
137
138/// TBLIS backend.
139///
140/// Implements matrix multiplication and tensor contraction traits from
141/// [`mdarray_linalg`] by delegating to the TBLIS C library. TBLIS is
142/// particularly efficient for **high-rank tensor contractions** where it
143/// avoids the explicit transpositions required by BLAS-based approaches.
144///
145/// This is a zero-sized marker struct — all state is managed by the
146/// underlying TBLIS library.
147#[derive(Default)]
148pub struct Tblis;