Struct ConcreteEinsumPlan 

pub struct ConcreteEinsumPlan { /* private fields */ }

Prepared concrete einsum plan for repeated executions with fixed input dtype and shape metadata.

Preparing a plan parses and optimizes the contraction tree once. Execution validates the later inputs against the prepared dtype and shape contract, then runs the stored tree without re-planning.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{BackendSessionHost, Tensor};

let lhs = Tensor::from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
let rhs = Tensor::from_vec_col_major(vec![3, 4], vec![1.0_f64; 12]).unwrap();
let plan = ConcreteEinsumPlan::prepare([&lhs, &rhs], "ij,jk->ik")?;

let mut backend = CpuBackend::new();
let out = backend
    .with_backend_session(|session| plan.execute([&lhs, &rhs], session))?;
assert_eq!(out.shape(), &[2, 4]);

Implementations

impl ConcreteEinsumPlan

pub fn prepare<'a, I>(inputs: I, subscripts: &str) -> Result<Self>

where I: AsRef<[&'a Tensor]>,

Prepare a plan from dtype-erased concrete tensor inputs and string notation.

Errors

Returns Error::InvalidSubscripts for malformed notation, Error::Validation for rank, shape, or dtype contract violations, or Error::Planning when no valid contraction tree can be built.

pub fn prepare_subscripts<'a, I>( inputs: I, subscripts: &EinsumSubscripts, ) -> Result<Self>

where I: AsRef<[&'a Tensor]>,

Prepare a plan from dtype-erased concrete tensor inputs and parsed integer-label subscripts.

Errors

Returns Error::Validation for rank, shape, or dtype contract violations, or Error::Planning when no valid contraction tree can be built.

pub fn prepare_notation<'a, I>( inputs: I, notation: &EinsumNotation, ) -> Result<Self>

where I: AsRef<[&'a Tensor]>,

Prepare a plan from rank-unresolved notation and concrete tensor inputs.

Errors

Returns Error::InvalidSubscripts for malformed axis tokens, Error::Validation for rank, shape, or dtype violations, or Error::Planning when no contraction tree can be built.

pub fn prepare_typed<'a, T, I>(inputs: I, subscripts: &str) -> Result<Self>

where T: TensorScalar, I: AsRef<[&'a TypedTensor<T>]>,

Prepare a plan from typed concrete tensor inputs and string notation.

Errors

Returns Error::InvalidSubscripts for malformed notation, Error::Validation for rank or shape contract violations, or Error::Planning when no valid contraction tree can be built.

pub fn prepare_typed_subscripts<'a, T, I>( inputs: I, subscripts: &EinsumSubscripts, ) -> Result<Self>

where T: TensorScalar, I: AsRef<[&'a TypedTensor<T>]>,

Prepare a plan from typed concrete tensor inputs and parsed integer-label subscripts.

Errors

Returns Error::Validation for rank or shape contract violations, or Error::Planning when no valid contraction tree can be built.

pub fn prepare_typed_notation<'a, T, I>( inputs: I, notation: &EinsumNotation, ) -> Result<Self>

where T: TensorScalar, I: AsRef<[&'a TypedTensor<T>]>,

Prepare a plan from rank-unresolved notation and typed concrete inputs.

Errors

Returns Error::InvalidSubscripts for malformed axis tokens, Error::Validation for rank or shape violations, or Error::Planning when no contraction tree can be built.

pub fn prepare_read<'a, I>(inputs: I, subscripts: &str) -> Result<Self>

where I: AsRef<[TensorRead<'a>]>,

Prepare a plan from read-only tensor inputs and string notation.

Errors

Returns Error::InvalidSubscripts for malformed notation, Error::Validation for rank, shape, or dtype contract violations, or Error::Planning when no valid contraction tree can be built.

pub fn prepare_read_subscripts<'a, I>( inputs: I, subscripts: &EinsumSubscripts, ) -> Result<Self>

where I: AsRef<[TensorRead<'a>]>,

Prepare a plan from read-only tensor inputs and parsed integer-label subscripts.

Errors

Returns Error::Validation for rank, shape, or dtype contract violations, or Error::Planning when no valid contraction tree can be built.

pub fn prepare_read_notation<'a, I>( inputs: I, notation: &EinsumNotation, ) -> Result<Self>

where I: AsRef<[TensorRead<'a>]>,

Prepare a plan from rank-unresolved notation and read-only inputs.

Errors

Returns Error::InvalidSubscripts for malformed axis tokens, Error::Validation for rank, shape, or dtype violations, or Error::Planning when no contraction tree can be built.

pub fn execute<'a, I>( &self, inputs: I, session: &mut dyn BackendSession, ) -> Result<Tensor>

where I: AsRef<[&'a Tensor]>,

Execute this plan on dtype-erased concrete tensor inputs inside a borrowed backend session.

Validation and the contraction itself run in the caller’s session; this method never enters a new backend session.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{BackendSessionHost, Tensor};

let lhs = Tensor::from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
let rhs = Tensor::from_vec_col_major(vec![3, 4], vec![1.0_f64; 12]).unwrap();
let plan = ConcreteEinsumPlan::prepare([&lhs, &rhs], "ij,jk->ik")?;

let mut backend = CpuBackend::new();
let out = backend
    .with_backend_session(|session| plan.execute([&lhs, &rhs], session))?;
assert_eq!(out.shape(), &[2, 4]);

Errors

Returns Error::Validation when inputs violate the prepared rank, shape, or input-count contract, Error::Tensor with a tenferro_tensor::Error::Validation DTypeMismatch payload when an input dtype differs from the prepared contract, or Error::Tensor for a typed backend failure.

pub fn execute_typed<'a, T, I>( &self, inputs: I, session: &mut dyn BackendSession, ) -> Result<TypedTensor<T>>

where T: TensorScalar, I: AsRef<[&'a TypedTensor<T>]>,

Execute this plan on typed concrete tensor inputs inside a borrowed backend session.

Validation and the contraction itself run in the caller’s session; this method never enters a new backend session.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{BackendSessionHost, TypedTensor};

let lhs = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![1.0; 6]).unwrap();
let rhs = TypedTensor::<f64>::from_vec_col_major(vec![3, 4], vec![1.0; 12]).unwrap();
let plan = ConcreteEinsumPlan::prepare_typed([&lhs, &rhs], "ij,jk->ik")?;

let mut backend = CpuBackend::new();
let out = backend
    .with_backend_session(|session| plan.execute_typed([&lhs, &rhs], session))?;
assert_eq!(out.shape(), &[2, 4]);

Errors

Returns Error::Validation when inputs violate the prepared rank, shape, or input-count contract, Error::Tensor with a tenferro_tensor::Error::Validation DTypeMismatch payload when the prepared dtype differs from T or the eager result dtype, or Error::Tensor for a typed backend failure.

pub fn execute_read<'a, I>( &self, inputs: I, session: &mut dyn BackendSession, ) -> Result<Tensor>

where I: AsRef<[TensorRead<'a>]>,

Execute this plan on read-only tensor inputs inside a borrowed backend session.

Validation and the contraction itself run in the caller’s session; this method never enters a new backend session.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{BackendSessionHost, Tensor, TensorRead};

let lhs = Tensor::from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
let rhs = Tensor::from_vec_col_major(vec![3, 4], vec![1.0_f64; 12]).unwrap();
let plan = ConcreteEinsumPlan::prepare_read(
    [TensorRead::from_tensor(&lhs), TensorRead::from_tensor(&rhs)],
    "ij,jk->ik",
)?;

let mut backend = CpuBackend::new();
let reads = [TensorRead::from_tensor(&lhs), TensorRead::from_tensor(&rhs)];
let out = backend
    .with_backend_session(|session| plan.execute_read(reads, session))?;
assert_eq!(out.shape(), &[2, 4]);

Errors

Returns Error::Validation when inputs violate the prepared rank, shape, or input-count contract, Error::Tensor with a tenferro_tensor::Error::Validation DTypeMismatch payload when an input dtype differs from the prepared contract, or Error::Tensor for a typed backend failure.

pub fn execute_into<'a, I>( &self, inputs: I, session: &mut dyn BackendSession, out: TensorWrite<'_>, ) -> Result<()>

where I: AsRef<[&'a Tensor]>,

Execute this plan on dtype-erased concrete tensor inputs into caller-provided output inside a borrowed backend session.

Validation and the contraction itself run in the caller’s session; this method never enters a new backend session.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{BackendSessionHost, Tensor, TensorWrite};

let lhs = Tensor::from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
let rhs = Tensor::from_vec_col_major(vec![3, 4], vec![1.0_f64; 12]).unwrap();
let plan = ConcreteEinsumPlan::prepare([&lhs, &rhs], "ij,jk->ik")?;

let mut backend = CpuBackend::new();
let mut out = Tensor::from_vec_col_major(vec![2, 4], vec![0.0_f64; 8]).unwrap();
backend.with_backend_session(|session| {
    plan.execute_into(
        [&lhs, &rhs],
        session,
        TensorWrite::from_tensor(&mut out),
    )
})?;
assert_eq!(out.as_slice::<f64>()?, vec![3.0_f64; 8].as_slice());

Errors

Returns Error::Validation for input or output rank, shape, or input-count contract violations, Error::Tensor with a tenferro_tensor::Error::Validation DTypeMismatch payload for dtype mismatches, or Error::Tensor for a typed backend failure.

pub fn execute_typed_into<'a, 'out, T, I, O>( &self, inputs: I, session: &mut dyn BackendSession, out: O, ) -> Result<()>

where T: TensorScalar, I: AsRef<[&'a TypedTensor<T>]>, O: Into<TypedTensorWrite<'out, T>>,

Execute this plan on typed concrete tensor inputs into caller-provided output inside a borrowed backend session.

Validation and the contraction itself run in the caller’s session; this method never enters a new backend session.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{BackendSessionHost, TypedTensor};

let lhs = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![1.0; 6]).unwrap();
let rhs = TypedTensor::<f64>::from_vec_col_major(vec![3, 4], vec![1.0; 12]).unwrap();
let plan = ConcreteEinsumPlan::prepare_typed([&lhs, &rhs], "ij,jk->ik")?;

let mut backend = CpuBackend::new();
let mut out = TypedTensor::<f64>::from_vec_col_major(vec![2, 4], vec![0.0; 8]).unwrap();
backend.with_backend_session(|session| {
    plan.execute_typed_into([&lhs, &rhs], session, &mut out)
})?;
assert_eq!(out.as_slice()?, vec![3.0_f64; 8].as_slice());

Errors

Returns Error::Validation for input or output rank, shape, or input-count contract violations, Error::Tensor with a tenferro_tensor::Error::Validation DTypeMismatch payload when the prepared dtype differs from T or the output dtype, or Error::Tensor for a typed backend failure.

pub fn execute_read_into<'a, I>( &self, inputs: I, session: &mut dyn BackendSession, out: TensorWrite<'_>, ) -> Result<()>

where I: AsRef<[TensorRead<'a>]>,

Execute this plan on read-only tensor inputs into caller-provided output inside a borrowed backend session.

Validation and the contraction itself run in the caller’s session; this method never enters a new backend session.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{BackendSessionHost, Tensor, TensorRead, TensorWrite};

let lhs = Tensor::from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
let rhs = Tensor::from_vec_col_major(vec![3, 4], vec![1.0_f64; 12]).unwrap();
let plan = ConcreteEinsumPlan::prepare_read(
    [TensorRead::from_tensor(&lhs), TensorRead::from_tensor(&rhs)],
    "ij,jk->ik",
)?;

let mut backend = CpuBackend::new();
let mut out = Tensor::from_vec_col_major(vec![2, 4], vec![0.0_f64; 8]).unwrap();
let reads = [TensorRead::from_tensor(&lhs), TensorRead::from_tensor(&rhs)];
backend.with_backend_session(|session| {
    plan.execute_read_into(reads, session, TensorWrite::from_tensor(&mut out))
})?;
assert_eq!(out.as_slice::<f64>()?, vec![3.0_f64; 8].as_slice());

Errors

Returns Error::Validation for input or output rank, shape, or input-count contract violations, Error::Tensor with a tenferro_tensor::Error::Validation DTypeMismatch payload for dtype mismatches, or Error::Tensor for a typed backend failure.

pub fn execute_read_into_accum<'a, I>( &self, inputs: I, session: &mut dyn BackendSession, accumulation: DotGeneralAccumulation, out: TensorWrite<'_>, ) -> Result<()>

where I: AsRef<[TensorRead<'a>]>,

Execute this plan on read-only inputs with scaled output accumulation inside a borrowed backend session.

accumulation follows the dot-general contract: out = alpha * einsum(inputs) + beta * out.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::{
    BackendSessionHost, DotGeneralAccumulation, DType, Tensor, TensorRead, TensorWrite,
};

let lhs = Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?;
let rhs = Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?;
let mut out = Tensor::from_vec_col_major(vec![], vec![1.0_f64])?;
let plan = ConcreteEinsumPlan::prepare([&lhs, &rhs], "i,i->")?;
let mut backend = CpuBackend::new();
backend.with_backend_session(|session| {
    plan.execute_read_into_accum(
        [TensorRead::from_tensor(&lhs), TensorRead::from_tensor(&rhs)],
        session,
        DotGeneralAccumulation::add_to(DType::F64)?,
        TensorWrite::from_tensor(&mut out),
    )
})?;
assert_eq!(out.as_slice::<f64>()?, &[7.0]);

Errors

Returns Error::Validation for input or output rank, shape, or input-count contract violations, Error::Tensor with a tenferro_tensor::Error::Validation DTypeMismatch payload for dtype mismatches, Error::Numerical for an invalid accumulation, or Error::Tensor for a typed backend failure.

Trait Implementations

impl Debug for ConcreteEinsumPlan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.