Skip to main content

Crate tenferro_einsum

Crate tenferro_einsum 

Source
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 programmatic EinsumNotation

  • Parenthesized notation: "ij,(jk,kl)->il" respects user-specified contraction order via NestedEinsum

  • Integer label notation: using u32 labels

  • 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):

    LayerTraitsSpellings
    concreteEinsumOps 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)
    tracedTracedEinsumOps on TraceContext, TracedTensordotOpstrace.einsum(&[&t1, &t2], spec), t.tensordot(&u, axes)
    eager (autodiff)EagerEinsumOps on EagerSessionsess.einsum(&[&x, &y], spec)

    The spec is text, EinsumNotation or EinsumSubscripts; options (EinsumOptions) select the contraction order and per-operand conjugation. ConcreteEinsumPlan plans once and executes repeatedly.

  • Extension runtime: traced einsum lowers to a registered tenferro extension runtime, keeping core op definitions small.

§Cargo features

FeatureEnables
autodiffThe eager layer (EagerEinsumOps) and AD rules. Adds the tenferro-ad dependency.
cudaCUDA 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§

ConcreteEinsumPlan
Prepared concrete einsum plan for repeated executions with fixed input dtype and shape metadata.
ConjMask
Per-operand conjugation of an einsum: operand i is conjugated when entry i is Conj::Yes. Missing entries are Conj::No; the default conjugates nothing.
ContractionOptimizerOptions
Public options for automatic contraction-path optimization.
ContractionTree
Contraction tree determining pairwise contraction order for N-ary einsum.
EinsumNotation
Rank-unresolved einsum notation.
EinsumOptions
Options of einsum on every layer.
EinsumSubscripts
Canonical N-ary einsum subscripts using integer labels.
Subscripts
Einsum subscripts using integer labels (omeinsum-rs compatible).

Enums§

EinsumAxis
One unresolved axis token in rank-polymorphic einsum notation.
EinsumOptimize
Controls how the contraction path is determined for N-ary einsum.
Error
Errors produced while parsing, planning, lowering, or executing einsum expressions.
NestedEinsum
Recursive einsum tree that preserves parenthesized grouping.
PlanningError
Domain-specific cause of an einsum planning failure.
Spec
An einsum specification: text, parsed notation or integer subscripts.
TensorDotAxes
Axis specification for TensordotOps::tensordot contraction sugar.

Constants§

EINSUM_EXTENSION_FAMILY_ID
Stable family identifier for the standard tenferro einsum extension.

Traits§

EagerEinsumOps
Einsum and tensordot on eager tensors, with the session as receiver. Eager operations execute immediately and record the tape for reverse-mode differentiation.
EinsumInputs
The input list of a concrete einsum: a slice or array of values that implement AsView with one representation. Mix owned tensors and views by borrowing every element ([a.as_read(), b]); that copies no data.
EinsumOps
Einsum on a list of concrete inputs: a slice, array or Vec of anything that implements AsView (owned, borrowed and typed tensors, strided views) with one representation. The result is a Tensor for erased inputs and a typed tensor for typed inputs. The spec comes first, then the options, then the engine.
EinsumSpec
Anything an einsum accepts as its spec argument: str, String, EinsumNotation, EinsumSubscripts or a Spec. Operations take it by reference, so "ij,jk->ik", &notation and &subscripts all work.
TensordotOps
Tensordot of two concrete inputs that implement AsView with one representation; the result has that representation.
TracedEinsumOps
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.
TracedTensordotOps
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.