Skip to main content

Einsum

For choosing between ordinary calls, compatible plan reuse and programmatic labels, start with Ordinary calls and prepared execution.

einsum is a standard extension, not part of tenferro core. Add the tenferro-einsum crate and import its operation traits. The spec is a string ("ij,jk->ik"), an EinsumNotation, or EinsumSubscripts, on every layer:

  • concrete: EinsumOps on a slice or array of inputs, for example [&a, &b].einsum("ij,jk->ik", exec), einsum_with(spec, &EinsumOptions, exec), and einsum_into(spec, &opts, exec, Dest::…) for a preallocated output. Inputs are any Tensor, TensorRead, TypedTensor<T>, or TypedTensorView<T> of one representation. TensordotOps provides a.tensordot(&b, axes, exec). Repeated-shape workloads can use ConcreteEinsumPlan.
  • traced: TracedEinsumOps on TraceContext (trace.einsum(&[&a, &b], "ij,jk->ik")) and TracedTensordotOps on TracedTensor (a.tensordot(&b, axes)).
  • eager (autodiff): EagerEinsumOps on a borrowed EagerSession (sess.einsum(&[&a, &b], spec), sess.tensordot(&a, &b, axes)).

Compiled traced execution also requires explicit runtime registration for einsum extension ops. The generated operation registry states the layout, error, and omission contract of each entry.

When working from a local checkout, use paths that match your project layout. For a scratch crate created directly inside the tenferro-rs checkout, include an empty [workspace] table so Cargo does not try to enroll it in the parent workspace:

[workspace]

Then add the dependencies:

[dependencies]
tenferro-runtime = { path = "../crates/tenferro-runtime" }
tenferro-tensor = { path = "../crates/tenferro-tensor" }
tenferro-cpu = { path = "../crates/tenferro-cpu" }
tenferro-einsum = { path = "../crates/tenferro-einsum", features = ["autodiff"] }

# Only needed for EagerTensor/autodiff examples.
tenferro-ad = { path = "../crates/tenferro-ad" }
num-complex = "0.4"

For published crates, use the same crate set with version requirements:

[dependencies]
tenferro-runtime = "..."
tenferro-tensor = "..."
tenferro-cpu = "..."
tenferro-einsum = { version = "...", features = ["autodiff"] }

# Only needed for EagerTensor/autodiff examples.
tenferro-ad = "..."
num-complex = "0.4"

Concrete and graph-only users can omit tenferro-ad and the autodiff feature. Enable tenferro-einsum’s autodiff feature when using EagerEinsumOps or einsum AD rules. The traced examples below are fragments; copy them into fn main() -> Result<(), Box<dyn std::error::Error>> when turning them into a standalone src/main.rs.

Concrete Tensor And TypedTensor

Use the concrete route when you have Tensor or TypedTensor values and want to run the contraction immediately on an explicit backend without autodiff. Arrays, slices, and vectors such as [&lhs, &rhs] implement EinsumOps directly; their receiver type is the list of borrowed tensor references.

use num_complex::Complex64;
use tenferro_cpu::CpuEngine;
use tenferro_einsum::EinsumOps;
use tenferro_tensor::{
    Tensor, TensorWrite, TypedTensor, TypedTensorView,
    TypedTensorViewMut, TypedTensorWrite};

let lhs = Tensor::from_vec_col_major(
    vec![2, 3],
    vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0],
)?;
let rhs = Tensor::from_vec_col_major(
    vec![3, 2],
    vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0],
)?;
let mut engine = CpuEngine::serial();
let product = [&lhs, &rhs].einsum("ij,jk->ik", &mut engine)?;
assert_eq!(product.as_slice::<f64>()?, &[22.0, 28.0, 49.0, 64.0]);

let mut product_out = Tensor::from_vec_col_major(vec![2, 2], vec![0.0_f64; 4])?;
[&lhs, &rhs].einsum_into("ij,jk->ik", &tenferro_einsum::EinsumOptions::default(), &mut engine, tenferro_tensor::Dest::overwrite(TensorWrite::from_tensor(&mut product_out)))?;
assert_eq!(product_out.as_slice::<f64>()?, &[22.0, 28.0, 49.0, 64.0]);

let complex_lhs = TypedTensor::<Complex64>::from_vec_col_major(
    vec![2, 2],
    vec![
        Complex64::new(1.0, 1.0),
        Complex64::new(2.0, -1.0),
        Complex64::new(3.0, 0.0),
        Complex64::new(4.0, 2.0),
    ],
)?;
let complex_rhs = TypedTensor::<Complex64>::from_vec_col_major(
    vec![2, 1],
    vec![Complex64::new(5.0, 0.0), Complex64::new(6.0, -1.0)],
)?;
let complex = [&complex_lhs, &complex_rhs].einsum("ij,jk->ik", &mut engine)?;
assert_eq!(
    complex.as_slice()?,
    &[Complex64::new(23.0, 2.0), Complex64::new(36.0, 3.0)],
);

let borrowed = TypedTensorView::from_slice([2, 2], [1, 2], 0, complex_lhs.as_slice()?)?;
let borrowed_rhs = complex_rhs.as_view();
let mut borrowed_storage = [Complex64::new(0.0, 0.0); 4];
let borrowed_out =
    TypedTensorViewMut::from_slice([2, 1], [2, 4], 1, &mut borrowed_storage)?;
[borrowed, borrowed_rhs].einsum_into("ij,jk->ik", &tenferro_einsum::EinsumOptions::default(), &mut engine, tenferro_tensor::Dest::overwrite(TypedTensorWrite::from_view(borrowed_out)))?;
assert_eq!(
    [borrowed_storage[1], borrowed_storage[3]],
    [Complex64::new(23.0, 2.0), Complex64::new(36.0, 3.0)],
);

Ellipsis and programmatic notation

Flat string notation supports one NumPy-style ellipsis per term. Ellipsis axes right-align and broadcast dimensions of size one. The programmatic EinsumNotation form resolves to the same canonical labels before planning.

Warning: string equations require exactly one explicit ->. Omitting it returns Error::InvalidSubscripts during parsing. Parenthesized contraction order containing ellipsis is also rejected during parsing; use flat ... notation or EinsumNotation instead.

use tenferro_cpu::CpuEngine;
use tenferro_einsum::{EinsumAxis, EinsumNotation, EinsumOps};
use tenferro_tensor::Tensor;

let lhs = Tensor::from_vec_col_major(vec![2, 2, 3], vec![1.0_f64; 12])?;
let rhs = Tensor::from_vec_col_major(vec![1, 3, 2], vec![1.0_f64; 6])?;
let notation = EinsumNotation::new(
    &[
        &[EinsumAxis::Ellipsis, EinsumAxis::Label(0), EinsumAxis::Label(1)],
        &[EinsumAxis::Ellipsis, EinsumAxis::Label(1), EinsumAxis::Label(2)],
    ],
    &[EinsumAxis::Ellipsis, EinsumAxis::Label(0), EinsumAxis::Label(2)],
);
let mut engine = CpuEngine::serial();
let string_result = [&lhs, &rhs].einsum("...ij,...jk->...ik", &mut engine)?;
let programmatic_result = [&lhs, &rhs].einsum(&notation, &mut engine)?;
assert_eq!(string_result.shape(), &[2, 2, 2]);
assert_eq!(string_result.as_slice::<f64>()?, &[3.0; 8]);
assert_eq!(programmatic_result.as_slice::<f64>()?, &[3.0; 8]);

TensorRead And Prepared Plans

Borrowed inputs use the same einsum method as owned tensors: pass a list of TensorRead values or TypedTensorView<T> values, or borrow every element of a mixed list ([a.as_read(), b]); borrowing copies no data. einsum_into writes into a caller-provided Dest: Dest::overwrite(out), Dest::accumulate(out), or Dest::scaled(out, alpha, beta). A typed destination can be either an owned TypedTensor or a TypedTensorViewMut.

Use ConcreteEinsumPlan when the same subscripts, dtypes, and shapes are executed repeatedly. ConcreteEinsumPlan::prepare(inputs, spec, &EinsumOptions) parses and optimizes the contraction tree once; plan.execute(inputs, exec) and plan.execute_into(inputs, exec, dest) validate the input count, dtype, and shape before running the stored tree. Per-operand conjugation is fixed when the plan is prepared, through EinsumOptions::conj.

use tenferro_cpu::CpuEngine;
use tenferro_einsum::{ConcreteEinsumPlan, EinsumOps};
use tenferro_tensor::{Tensor, TensorRead, TensorView, TensorWrite, TypedTensorView};

let matrix_data = [1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0];
let matrix = TypedTensorView::from_slice([2, 3], [3, 1], 0, &matrix_data)?;
let vector = Tensor::from_vec_col_major(vec![3], vec![10.0_f64, 20.0, 30.0])?;
let inputs = [
    TensorRead::from_view(TensorView::F64(matrix)),
    TensorRead::from_tensor(&vector),
];

let mut engine = CpuEngine::serial();
let result = inputs.einsum("ij,j->i", &mut engine)?;
assert_eq!(result.as_slice::<f64>()?, &[140.0, 320.0]);

let plan = ConcreteEinsumPlan::prepare(&inputs.clone(), "ij,j->i", &tenferro_einsum::EinsumOptions::default())?;
let planned = plan.execute(&inputs, &mut engine)?;
assert_eq!(planned.as_slice::<f64>()?, &[140.0, 320.0]);

let mut planned_out = Tensor::from_vec_col_major(vec![2], vec![0.0_f64; 2])?;
let matrix = TypedTensorView::from_slice([2, 3], [3, 1], 0, &matrix_data)?;
let inputs = [
    TensorRead::from_view(TensorView::F64(matrix)),
    TensorRead::from_tensor(&vector),
];
plan.execute_into(&inputs, &mut engine, tenferro_tensor::Dest::overwrite(TensorWrite::from_tensor(&mut planned_out)))?;
assert_eq!(planned_out.as_slice::<f64>()?, &[140.0, 320.0]);

Traced Matrix Multiply

Use the traced route when einsum should be part of a graph compiled by GraphCompiler, prepared by Runtime::prepare and executed by Runtime::run.

use tenferro_cpu::{runtime_engine_id, runtime_engine_registration, CpuEngine};
use tenferro_einsum::TracedEinsumOps;
use tenferro_runtime::{TraceContext, ExecutionEngine, GraphCompiler, Runtime, Tensor};
let trace = TraceContext::new();

let a = Tensor::from_vec_col_major(
    vec![2, 3],
    vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0],
)?;
let b = Tensor::from_vec_col_major(
    vec![3, 2],
    vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0],
)?;

let a_in = trace.input_concrete_shape(a.dtype(), &[2, 3])?;
let b_in = trace.input_concrete_shape(b.dtype(), &[3, 2])?;
let c = trace.einsum(&[&a_in, &b_in], "ij,jk->ik")?;
let program = GraphCompiler::new().compile(&c)?;

let mut engine = CpuEngine::serial();
let mut builder = Runtime::builder();
builder.register_engine(runtime_engine_registration(&engine)?)?;
builder.install_extension_module(tenferro_einsum::extension_module::<CpuEngine>(
    runtime_engine_id()?,
)?)?;
let runtime = builder.build()?;
let reads = [
    tenferro_runtime::TensorRead::from_tensor(&a),
    tenferro_runtime::TensorRead::from_tensor(&b),
];
let prepared = runtime.prepare(&program, &reads, &[engine.target()])?;
let mut outputs = runtime.run(&mut [&mut engine], &prepared, &reads)?;
let result = outputs.remove(0).into_tensor(&mut engine)?;

assert_eq!(result.shape(), &[2, 2]);
assert_eq!(result.as_slice::<f64>()?, &[22.0, 28.0, 49.0, 64.0]);

EagerTensor

With the autodiff feature, tenferro-einsum also exposes immediate EagerTensor execution through EagerEinsumOps on a borrowed EagerSession; session.tensordot(&a, &b, axes) is available there too. The "i->ii" form embeds a vector on a diagonal. This is a tenferro extension to the common NumPy/PyTorch einsum surface; NumPy rejects repeated output labels in that form.

use tenferro_ad::{EagerRuntime, Tensor};
use tenferro_cpu::CpuEngine;
use tenferro_einsum::EagerEinsumOps;

let ctx = EagerRuntime::new()?;
let mut engine = CpuEngine::serial();
let u = ctx.variable_from(Tensor::from_vec_col_major(
    vec![2],
    vec![1.0_f64, 2.0],
)?)?;
let v = ctx.variable_from(Tensor::from_vec_col_major(
    vec![3],
    vec![3.0_f64, 4.0, 5.0],
)?)?;

let (outer, diag) = ctx.with_eager_session(&mut engine, |s| {
    let outer = s.einsum(&[&u, &v], "i,j->ij")?;
    let diag = s.einsum(&[&v], "i->ii")?;
    Ok::<_, tenferro_einsum::Error>((outer, diag))
})?;

assert_eq!(outer.shape(), &[2, 3]);
let outer_tensor = ctx.with_eager_session(&mut engine, |s| s.duplicate_value(&outer))?;
assert_eq!(
    outer_tensor.as_slice::<f64>()?,
    &[3.0, 6.0, 4.0, 8.0, 5.0, 10.0],
);
assert_eq!(diag.shape(), &[3, 3]);
let diag_tensor = ctx.with_eager_session(&mut engine, |s| s.duplicate_value(&diag))?;
assert_eq!(
    diag_tensor.as_slice::<f64>()?,
    &[3.0, 0.0, 0.0, 0.0, 4.0, 0.0, 0.0, 0.0, 5.0],
);

Tensordot Sugar

Use tensordot when the operation is naturally described as “contract these axis pairs” instead of by writing explicit labels. TensorDotAxes::Count(n) contracts the last n axes of the left tensor with the first n axes of the right tensor. TensorDotAxes::Axes accepts explicit axis pairs, including negative axes.

use tenferro_cpu::{runtime_engine_id, runtime_engine_registration, CpuEngine};
use tenferro_einsum::{TensorDotAxes, TracedTensordotOps};
use tenferro_runtime::{TraceContext, ExecutionEngine, GraphCompiler, Runtime, TracedTensor};
let trace = TraceContext::new();

let lhs = trace.from_vec_col_major(
    vec![2, 3],
    vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0],
)?;
let rhs = trace.from_vec_col_major(
    vec![3, 4],
    vec![
        1.0_f64, 2.0, 3.0,
        4.0, 5.0, 6.0,
        7.0, 8.0, 9.0,
        10.0, 11.0, 12.0,
    ],
)?;
let out = lhs.tensordot(&rhs, TensorDotAxes::Count(1))?;

assert_eq!(out.concrete_shape()?, vec![2, 4]);
let mut compiler = GraphCompiler::new();
let program = compiler.compile(&out)?;
let mut engine = CpuEngine::serial();
let mut builder = Runtime::builder();
builder.register_engine(runtime_engine_registration(&engine)?)?;
builder.install_extension_module(tenferro_einsum::extension_module::<CpuEngine>(
    runtime_engine_id()?,
)?)?;
let runtime = builder.build()?;
let prepared = runtime.prepare(&program, &[], &[engine.target()])?;
let mut outputs = runtime.run(&mut [&mut engine], &prepared, &[])?;
let result = outputs.remove(0).into_tensor(&mut engine)?;

assert_eq!(result.shape(), &[2, 4]);
assert_eq!(
    result.as_slice::<f64>()?,
    &[22.0, 28.0, 49.0, 64.0, 76.0, 100.0, 103.0, 136.0],
);

Optimization Controls

The default policy chooses an N-ary contraction order automatically. Advanced users can pass an explicit strategy through EinsumOptions::optimize on any layer, for example trace.einsum_with(&[&a, &b], spec, &opts). The public optimizer API is limited to the types needed to express that choice: EinsumOptimize, ContractionTree, ContractionOptimizerOptions, Subscripts, NestedEinsum, and EinsumSubscripts.

EinsumOptimize::Path accepts a JAX-style positional path over the current operand list. After each contraction the referenced operands are removed and the result is appended, so [(1, 2), (0, 1)] for ij,jk,kl->il contracts the last two operands first and then contracts that result with the first operand. This path is shape-independent and can be used with symbolic traced inputs. EinsumOptimize::Tree is for concrete or precomputed ContractionTree values; it requires concrete shapes and is converted to fixed contraction pairs when a concrete traced op is built.

EinsumOptimize::False keeps the written order instead: the first step contracts the first two operands, and every later step folds the running result with the next operand. It is predictable, not cheap; the automatic plan is usually much faster.

use tenferro_einsum::{EinsumOptimize, EinsumOptions, TracedEinsumOps};
use tenferro_runtime::{TraceContext, DType};
let trace = TraceContext::new();

let a = trace.input_concrete_shape(DType::F64, &[2, 3])?;
let b = trace.input_concrete_shape(DType::F64, &[3, 2])?;
let c = trace.einsum_with(
    &[&a, &b],
    "ij,jk->ik",
    &EinsumOptions::default().optimize(EinsumOptimize::False),
)?;

assert_eq!(c.rank(), 2);
assert_eq!(c.try_concrete_shape(), Some(vec![2, 2]));

Cache Management

Einsum uses the shared extension cache infrastructure from tenferro-runtime. Compile-time extension caches live on GraphCompiler; runtime contraction-plan caches live on installed runtime cache owners and EagerRuntime. Einsum plan cache identity includes the planning policy or explicit path, not only the subscripts and shapes. Traced extension operation identity also includes those planner options and paths, so two calls with different policies are not treated as identical extension ops.

Use tenferro_einsum::EINSUM_EXTENSION_FAMILY_ID with ExtensionCacheSelector when you need to inspect or clear only einsum cache entries.

Autodiff

With the autodiff feature, einsum VJP rules preserve the primal planning policy. Explicit positional paths are remapped to the VJP operand order so the gradient contraction inherits the caller’s intended plan instead of falling back to an unrelated default.