Enum EinsumOptimize 

pub enum EinsumOptimize {
    Auto(ContractionOptimizerOptions),
    False,
    Nested(NestedEinsum),
    Path(Vec<(usize, usize)>),
    Tree(ContractionTree),
}

Controls how the contraction path is determined for N-ary einsum.

Variants

Auto – Automatic optimization (default: FLOPS-first)

Uses omeco’s TreeSA optimizer. The default scoring prioritizes time complexity (FLOPS). Customize via ContractionOptimizerOptions.

use omeco::ScoreFunction;
use tenferro_einsum::ContractionOptimizerOptions;
use tenferro::einsum::{einsum_with, EinsumOptimize};

// Default: FLOPS-first (minimize computation time)
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::default());

// Space-optimized (minimize peak intermediate tensor size)
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Auto(ContractionOptimizerOptions {
        score: ScoreFunction::space_optimized(20.0),
        ..Default::default()
    }));

// Balanced (FLOPS + space, omeco default)
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Auto(ContractionOptimizerOptions {
        score: ScoreFunction::default(),
        ..Default::default()
    }));

// Custom: space-heavy with FLOPS tiebreaker
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Auto(ContractionOptimizerOptions {
        score: ScoreFunction::new(
            0.1,   // tc_weight (FLOPS, low priority)
            1.0,   // sc_weight (space, high priority)
            0.0,   // rw_weight (read-write, ignored)
            15.0,  // sc_target (no penalty below 2^15 elements)
        ),
        ..Default::default()
    }));

// Full TreeSA: multiple trials with annealing
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Auto(ContractionOptimizerOptions {
        score: ScoreFunction::time_optimized(),
        ntrials: 10,
        niters: 50,
        betas: vec![0.01, 0.1, 1.0, 10.0],
        ..Default::default()
    }));

False – No optimization

Contracts operands left-to-right in the order given. Useful for debugging or when the input order is already optimal.

einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::False);

Nested – Parenthesized notation

Specifies contraction order using a pre-parsed NestedEinsum tree. Most human-readable way to control order.

use tenferro_einsum::NestedEinsum;

// "Contract A*B first, then result with C"
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Nested(NestedEinsum::parse("(ij,jk),kl->il").unwrap()));

// "Contract B*C first, then A with result"
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Nested(NestedEinsum::parse("ij,(jk,kl)->il").unwrap()));

Path – JAX-compatible explicit path

Each pair specifies positions in a shrinking operand list. After each step, the two contracted operands are removed and the result is appended to the end.

Compatible with jax.numpy.einsum(optimize=path) and opt_einsum.contract_path output.

// 3 operands: A(0), B(1), C(2)
// Step 1: contract positions 1,2 (B,C) -> T. List: [A, T]
// Step 2: contract positions 0,1 (A,T) -> result
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Path(vec![(1, 2), (0, 1)]));

// Step 1: contract positions 0,1 (A,B) -> T. List: [C, T]
// Step 2: contract positions 0,1 (C,T) -> result
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Path(vec![(0, 1), (0, 1)]));

Tree – Pre-computed ContractionTree

Pass a tree obtained from ContractionTree::optimize or other optimization tools. Skips all path computation.

use tenferro_einsum::{ContractionTree, Subscripts};

let subs = Subscripts::parse("ij,jk,kl->il").unwrap();
let shapes = [&[2, 3][..], &[3, 4], &[4, 5]];
let tree = ContractionTree::optimize(&subs, &shapes).unwrap();
einsum_with(&mut engine, &[&a, &b, &c], "ij,jk,kl->il",
    EinsumOptimize::Tree(tree));

Variants

Auto(ContractionOptimizerOptions)

Automatic optimization via omeco TreeSA.

False

No optimization – contract left-to-right.

Nested(NestedEinsum)

Parenthesized notation specifying contraction order.

Path(Vec<(usize, usize)>)

JAX-compatible position-based contraction path.

Tree(ContractionTree)

Pre-computed contraction tree.

Trait Implementations

impl Default for EinsumOptimize

fn default() -> Self

Default: FLOPS-first automatic optimization.

Uses ScoreFunction::time_optimized():

• tc_weight = 1.0 (minimize FLOPS)
• sc_weight = 0.0 (ignore space)