Expand description
High-level einsum with N-ary contraction tree optimization.
This crate provides:
-
String notation:
"ij,jk->ik"(NumPy/PyTorch compatible) -
Ellipsis notation:
"...ij,...jk->...ik"with right-aligned equal-or-one broadcasting, plus programmaticEinsumNotation -
Parenthesized notation:
"ij,(jk,kl)->il"respects user-specified contraction order viaNestedEinsum -
Integer label notation: using
u32labels -
Repeated labels:
"ii->i"extracts diagonals,"ii->"traces, and"i->ii"embeds a vector on a diagonal -
N-ary contraction: Automatic or manual optimization of pairwise contraction order via
ContractionTree -
Tensordot sugar: NumPy-style axis-pair contraction, implemented as contraction sugar rather than as a linear algebra API.
-
One call grammar (#2552) on three layers, declared once in the operation registry (
docs/spec/generated/api-ops.md):Layer Traits Spellings concrete EinsumOpson a slice/array/VecofAsViewinputs,TensordotOps[&a, &b].einsum(spec, exec),.einsum_with(spec, &opts, exec),.einsum_into(spec, &opts, exec, dest)traced TracedEinsumOpsonTraceContext,TracedTensordotOpstrace.einsum(&[&t1, &t2], spec),t.tensordot(&u, axes)eager ( autodiff)EagerEinsumOpsonEagerSessionsess.einsum(&[&x, &y], spec)The spec is text,
EinsumNotationorEinsumSubscripts; options (EinsumOptions) select the contraction order and per-operand conjugation.ConcreteEinsumPlanplans once and executes repeatedly. -
Extension runtime: traced einsum lowers to a registered tenferro extension runtime, keeping core op definitions small.
§Cargo features
| Feature | Enables |
|---|---|
autodiff | The eager layer (EagerEinsumOps) and AD rules. Adds the tenferro-ad dependency. |
cuda | CUDA execution through tenferro-gpu. |
For contractions without AD, use the concrete EinsumOps or
ConcreteEinsumPlan with an engine; they need no autodiff.
§Examples
use tenferro_einsum::{ContractionTree, Subscripts};
let subs = Subscripts::parse("ij,jk->ik").unwrap();
let tree = ContractionTree::optimize(&subs, &[&[2, 3], &[3, 4]]).unwrap();
assert_eq!(tree.step_count(), 1);use tenferro_cpu::CpuEngine;
use tenferro_einsum::EinsumOps;
use tenferro_tensor::Tensor;
let a = Tensor::from_vec_col_major(vec![2, 3], vec![1.0_f64; 6])?;
let b = Tensor::from_vec_col_major(vec![3, 4], vec![1.0_f64; 12])?;
let mut backend = CpuEngine::serial();
let out = [&a, &b].einsum("ij,jk->ik", &mut backend)?;
assert_eq!(out.shape(), &[2, 4]);use tenferro_einsum::Subscripts;
let trace = Subscripts::parse("ii->").unwrap();
let diagonal = Subscripts::parse("ii->i").unwrap();
let embedded = Subscripts::parse("i->ii").unwrap();
let higher_rank = Subscripts::parse("iij->ij").unwrap();
assert!(trace.output.is_empty());
assert_eq!(diagonal.output, vec![b'i' as u32]);
assert_eq!(embedded.output, vec![b'i' as u32, b'i' as u32]);
assert_eq!(higher_rank.inputs[0], vec![b'i' as u32, b'i' as u32, b'j' as u32]);Modules§
- lowering
- Read-only einsum lowering plans.
- prelude
- The einsum and tensordot grammar traits, options and spec types (#2552).
Structs§
- Concrete
Einsum Plan - Prepared concrete einsum plan for repeated executions with fixed input dtype and shape metadata.
- Conj
Mask - Per-operand conjugation of an einsum: operand
iis conjugated when entryiisConj::Yes. Missing entries areConj::No; the default conjugates nothing. - Contraction
Optimizer Options - Public options for automatic contraction-path optimization.
- Contraction
Tree - Contraction tree determining pairwise contraction order for N-ary einsum.
- Einsum
Notation - Rank-unresolved einsum notation.
- Einsum
Options - Options of
einsumon every layer. - Einsum
Subscripts - Canonical N-ary einsum subscripts using integer labels.
- Subscripts
- Einsum subscripts using integer labels (omeinsum-rs compatible).
Enums§
- Einsum
Axis - One unresolved axis token in rank-polymorphic einsum notation.
- Einsum
Optimize - Controls how the contraction path is determined for N-ary einsum.
- Error
- Errors produced while parsing, planning, lowering, or executing einsum expressions.
- Nested
Einsum - Recursive einsum tree that preserves parenthesized grouping.
- Planning
Error - Domain-specific cause of an einsum planning failure.
- Spec
- An einsum specification: text, parsed notation or integer subscripts.
- Tensor
DotAxes - Axis specification for
TensordotOps::tensordotcontraction sugar.
Constants§
- EINSUM_
EXTENSION_ FAMILY_ ID - Stable family identifier for the standard tenferro einsum extension.
Traits§
- Eager
Einsum Ops - Einsum and tensordot on eager tensors, with the session as receiver. Eager operations execute immediately and record the tape for reverse-mode differentiation.
- Einsum
Inputs - The input list of a concrete einsum: a slice or array of values that
implement
AsViewwith one representation. Mix owned tensors and views by borrowing every element ([a.as_read(), b]); that copies no data. - Einsum
Ops - Einsum on a list of concrete inputs: a slice, array or
Vecof anything that implementsAsView(owned, borrowed and typed tensors, strided views) with one representation. The result is aTensorfor erased inputs and a typed tensor for typed inputs. The spec comes first, then the options, then the engine. - Einsum
Spec - Anything an einsum accepts as its spec argument:
str,String,EinsumNotation,EinsumSubscriptsor aSpec. Operations take it by reference, so"ij,jk->ik",¬ationand&subscriptsall work. - Tensordot
Ops - Tensordot of two concrete inputs that implement
AsViewwith one representation; the result has that representation. - Traced
Einsum Ops - Einsum recorded on a trace: the trace is the receiver, the inputs are traced tensors of that trace, and the result is a traced tensor. Execution happens when the graph is prepared and run.
- Traced
Tensordot Ops - Tensordot recorded on traced tensors.
Functions§
- extension_
module - Build this extension module for one runtime engine.
- parse_
einsum_ notation - Parse string notation into rank-unresolved axis tokens.
- parse_
einsum_ subscripts - Parse string einsum notation into canonical integer labels.
- semantic_
ad_ rules - Return the semantic-program einsum extension AD rules.
Type Aliases§
- Result
- Result type alias for einsum parsing, planning, and all public extension APIs.