Struct PreparedContraction 

pub struct PreparedContraction { /* private fields */ }

A caller-owned plan for repeated contractions with fixed index metadata.

Prepare this once when repeated operands keep the same ordered indices, dimensions, and axis classes but their values, dtypes, or gradient state may change. Planning reuse applies to N-ary or retained-index execution. A binary call without retained indices preserves the faster pairwise path and does not consume the stored N-ary labels; use contract_pair directly for that case. Fresh index identities require a fresh plan.

Examples

use tensor4all_core::{ContractionOptions, DynIndex, IdxTensor, PreparedContraction};

let i = DynIndex::new_dyn(2);
let j = DynIndex::new_dyn(2);
let k = DynIndex::new_dyn(2);
let a = IdxTensor::from_dense(vec![i.clone(), k.clone()], vec![1.0, 2.0, 3.0, 4.0])?;
let b = IdxTensor::from_dense(vec![k, j.clone()], vec![5.0, 6.0, 7.0, 8.0])?;
let c = IdxTensor::from_dense(vec![j], vec![1.0, 2.0])?;
let plan = PreparedContraction::new(&[&a, &b, &c], ContractionOptions::new())?;
let result = plan.execute(&[&a, &b, &c])?;
assert_eq!(result.indices(), &[i]);
assert_eq!(result.to_vec::<f64>()?, vec![85.0, 126.0]);

Implementations

impl PreparedContraction

pub fn new( tensors: &[&IdxTensor], options: ContractionOptions<'_>, ) -> Result<Self, IdxTensorError>

Prepare index matching, label assignment, and result ordering.

Arguments

• tensors - Representative operands whose ordered index metadata defines the execution contract.
• options - Retained indices to preserve in every execution result.

Returns

An immutable caller-owned plan reusable with compatible operands.

Errors

Returns IdxTensorError when no operands are supplied, retained indices are absent, the index relationships do not form the requested connected network, or the result would contain duplicate output indices.

Examples

use tensor4all_core::{ContractionOptions, DynIndex, IdxTensor, PreparedContraction};

let left = DynIndex::new_dyn(2);
let right = DynIndex::new_dyn(2);
let a = IdxTensor::from_dense(vec![left.clone()], vec![1.0, 2.0])?;
let b = IdxTensor::from_dense(
    vec![left, right.clone()],
    vec![3.0, 0.0, 0.0, 4.0],
)?;
let c = IdxTensor::from_dense(vec![right], vec![5.0, 6.0])?;
let plan = PreparedContraction::new(&[&a, &b, &c], ContractionOptions::new())?;
assert_eq!(plan.execute(&[&a, &b, &c])?.to_vec::<f64>()?, vec![63.0]);

pub fn execute( &self, tensors: &[&IdxTensor], ) -> Result<IdxTensor, IdxTensorError>

Execute this plan with compatible operands.

Operand values, dtypes, and gradient state may differ from preparation; ordered full indices, dimensions, and axis classes must match exactly.

Returns

The contracted tensor in the result-index order fixed at preparation.

Errors

Returns IdxTensorError::ShapeMismatch before backend execution when operand count, indices, dimensions, or axis classes differ. Storage, dtype-promotion, AD, or backend execution failures retain their ordinary IdxTensorError diagnostics.

Examples

use tensor4all_core::{ContractionOptions, DynIndex, IdxTensor, PreparedContraction};

let left = DynIndex::new_dyn(2);
let right = DynIndex::new_dyn(2);
let a = IdxTensor::from_dense(vec![left.clone()], vec![1.0, 2.0])?;
let b = IdxTensor::from_dense(
    vec![left, right.clone()],
    vec![3.0, 0.0, 0.0, 4.0],
)?;
let c = IdxTensor::from_dense(vec![right.clone()], vec![5.0, 6.0])?;
let plan = PreparedContraction::new(&[&a, &b, &c], ContractionOptions::new())?;
let updated = IdxTensor::from_dense(vec![right], vec![1.0, 1.0])?;
assert_eq!(plan.execute(&[&a, &b, &updated])?.to_vec::<f64>()?, vec![11.0]);

Trait Implementations

impl Clone for PreparedContraction

fn clone(&self) -> PreparedContraction

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PreparedContraction

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

Formats the value using the given formatter.