tenferro_einsum/lib.rs
1//! High-level einsum with N-ary contraction tree optimization.
2//!
3//! This crate provides:
4//!
5//! - **String notation**: `"ij,jk->ik"` (NumPy/PyTorch compatible)
6//! - **Ellipsis notation**: `"...ij,...jk->...ik"` with right-aligned
7//! equal-or-one broadcasting, plus programmatic [`EinsumNotation`]
8//! - **Parenthesized notation**: `"ij,(jk,kl)->il"` respects user-specified
9//! contraction order via [`NestedEinsum`]
10//! - **Integer label notation**: using `u32` labels
11//! - **Repeated labels**: `"ii->i"` extracts diagonals, `"ii->"` traces, and
12//! `"i->ii"` embeds a vector on a diagonal
13//! - **N-ary contraction**: Automatic or manual optimization of pairwise
14//! contraction order via [`ContractionTree`]
15//! - **Tensordot sugar**: NumPy-style axis-pair contraction, implemented as
16//! contraction sugar rather than as a linear algebra API.
17//! - **One call grammar (#2552)** on three layers, declared once in the
18//! operation registry (`docs/spec/generated/api-ops.md`):
19//!
20//! | Layer | Traits | Spellings |
21//! |---|---|---|
22//! | concrete | [`EinsumOps`] on a slice/array/`Vec` of `AsView` inputs, [`TensordotOps`] | `[&a, &b].einsum(spec, exec)`, `.einsum_with(spec, &opts, exec)`, `.einsum_into(spec, &opts, exec, dest)` |
23//! | traced | [`TracedEinsumOps`] on `TraceContext`, [`TracedTensordotOps`] | `trace.einsum(&[&t1, &t2], spec)`, `t.tensordot(&u, axes)` |
24//! | eager (`autodiff`) | `EagerEinsumOps` on `EagerSession` | `sess.einsum(&[&x, &y], spec)` |
25//!
26//! The spec is text, [`EinsumNotation`] or [`EinsumSubscripts`]; options
27//! ([`EinsumOptions`]) select the contraction order and per-operand
28//! conjugation. [`ConcreteEinsumPlan`] plans once and executes repeatedly.
29//! - **Extension runtime**: traced einsum lowers to a registered tenferro
30//! extension runtime, keeping core op definitions small.
31//!
32//! # Cargo features
33//!
34//! | Feature | Enables |
35//! |---|---|
36//! | `autodiff` | The eager layer (`EagerEinsumOps`) and AD rules. Adds the `tenferro-ad` dependency. |
37//! | `cuda` | CUDA execution through `tenferro-gpu`. |
38//!
39//! For contractions without AD, use the concrete [`EinsumOps`] or
40//! [`ConcreteEinsumPlan`] with an engine; they need no `autodiff`.
41//!
42//! # Examples
43//!
44//! ```
45//! use tenferro_einsum::{ContractionTree, Subscripts};
46//!
47//! let subs = Subscripts::parse("ij,jk->ik").unwrap();
48//! let tree = ContractionTree::optimize(&subs, &[&[2, 3], &[3, 4]]).unwrap();
49//! assert_eq!(tree.step_count(), 1);
50//! ```
51//!
52//! ```
53//! use tenferro_cpu::CpuEngine;
54//! use tenferro_einsum::EinsumOps;
55//! use tenferro_tensor::Tensor;
56//!
57//! let a = Tensor::from_vec_col_major(vec![2, 3], vec![1.0_f64; 6])?;
58//! let b = Tensor::from_vec_col_major(vec![3, 4], vec![1.0_f64; 12])?;
59//! let mut backend = CpuEngine::serial();
60//!
61//! let out = [&a, &b].einsum("ij,jk->ik", &mut backend)?;
62//! assert_eq!(out.shape(), &[2, 4]);
63//! # Ok::<(), tenferro_tensor::Error>(())
64//! ```
65//!
66//! ```
67//! use tenferro_einsum::Subscripts;
68//!
69//! let trace = Subscripts::parse("ii->").unwrap();
70//! let diagonal = Subscripts::parse("ii->i").unwrap();
71//! let embedded = Subscripts::parse("i->ii").unwrap();
72//! let higher_rank = Subscripts::parse("iij->ij").unwrap();
73//!
74//! assert!(trace.output.is_empty());
75//! assert_eq!(diagonal.output, vec![b'i' as u32]);
76//! assert_eq!(embedded.output, vec![b'i' as u32, b'i' as u32]);
77//! assert_eq!(higher_rank.inputs[0], vec![b'i' as u32, b'i' as u32, b'j' as u32]);
78//! ```
79#![cfg_attr(docsrs, feature(doc_cfg))]
80mod api;
81mod binary_dot;
82mod broadcast;
83mod builder;
84mod cache;
85mod concrete;
86mod cpu_concrete;
87mod eager;
88#[cfg(feature = "autodiff")]
89mod eager_ad;
90mod ellipsis;
91mod error;
92mod extension;
93pub mod lowering;
94mod optimize;
95mod planning;
96pub mod prelude;
97mod subscripts;
98mod syntax;
99mod tensordot;
100mod traced;
101#[cfg(test)]
102mod typed_eager;
103pub(crate) mod util;
104
105#[cfg(feature = "autodiff")]
106#[cfg_attr(docsrs, doc(cfg(feature = "autodiff")))]
107pub use api::EagerEinsumOps;
108pub use api::{
109 ConjMask, EinsumInputs, EinsumOps, EinsumOptions, EinsumSpec, Spec, TensordotOps,
110 TracedEinsumOps, TracedTensordotOps,
111};
112pub use cache::EINSUM_EXTENSION_FAMILY_ID;
113pub use concrete::ConcreteEinsumPlan;
114pub use error::{Error, PlanningError, Result};
115pub use extension::extension_module;
116#[cfg(feature = "autodiff")]
117pub use extension::semantic_ad_rules;
118pub use optimize::EinsumOptimize;
119pub use planning::tree::{ContractionOptimizerOptions, ContractionTree};
120pub use subscripts::{
121 parse_einsum_notation, parse_einsum_subscripts, EinsumAxis, EinsumNotation, EinsumSubscripts,
122};
123pub use syntax::nested::NestedEinsum;
124pub use syntax::subscripts::Subscripts;
125pub use tensordot::TensorDotAxes;
126
127#[cfg(test)]
128mod concrete_tests;
129#[cfg(test)]
130mod tests;
131#[cfg(test)]
132mod typed_eager_tests;