Skip to main content

TensorContractionLike

Trait TensorContractionLike 

Source
pub trait TensorContractionLike: TensorIndex {
    // Required methods
    fn conj(&self) -> Self;
    fn direct_sum(
        &self,
        other: &Self,
        pairs: &[(<Self as TensorIndex>::Index, <Self as TensorIndex>::Index)],
    ) -> Result<DirectSumResult<Self>, Self::Error>;
    fn outer_product(&self, other: &Self) -> Result<Self, Self::Error>;
    fn permuteinds(
        &self,
        new_order: &[<Self as TensorIndex>::Index],
    ) -> Result<Self, Self::Error>;
    fn fuse_indices(
        &self,
        old_indices: &[<Self as TensorIndex>::Index],
        new_index: <Self as TensorIndex>::Index,
        order: LinearizationOrder,
    ) -> Result<Self, Self::Error>;
    fn contract(tensors: &[&Self]) -> Result<Self, Self::Error>;

    // Provided methods
    fn direct_sum_many(
        operands: &[&Self],
        groups: &[Vec<<Self as TensorIndex>::Index>],
    ) -> Result<DirectSumResult<Self>, Self::Error> { ... }
    fn contract_retaining_indices(
        tensors: &[&Self],
        retained_indices: &[<Self as TensorIndex>::Index],
    ) -> Result<Self, Self::Error> { ... }
    fn contract_pair(&self, other: &Self) -> Result<Self, Self::Error> { ... }
    fn validate(&self) -> Result<(), Self::Error> { ... }
}
Expand description

Contraction/einsum-style operations for tensor-like values.

Types that only need vector-space algebra should not implement or require this trait. Tree tensor-network algorithms should use this trait when they truly need index-based contraction.

Required Methods§

Source

fn conj(&self) -> Self

Tensor conjugate operation.

Source

fn direct_sum( &self, other: &Self, pairs: &[(<Self as TensorIndex>::Index, <Self as TensorIndex>::Index)], ) -> Result<DirectSumResult<Self>, Self::Error>

Direct sum of two tensors along specified index pairs.

Each pair (a_index, b_index) becomes one new index of dimension dim(a_index) + dim(b_index); self occupies the first block and other the second. For more than two operands use direct_sum_many.

§Errors

Returns Self::Error when the summed index spaces are incompatible (an index-space mismatch) or the underlying construction reports a failure.

Source

fn outer_product(&self, other: &Self) -> Result<Self, Self::Error>

Outer product (tensor product) of two tensors.

§Errors

Returns Self::Error when the two tensors share contractable indices (a shared-index mismatch) or the underlying construction reports a failure.

Source

fn permuteinds( &self, new_order: &[<Self as TensorIndex>::Index], ) -> Result<Self, Self::Error>

Permute tensor indices to match the specified order.

§Errors

Returns Self::Error when new_order does not contain exactly the tensor’s external indices (an index-set mismatch or a missing-index failure).

Source

fn fuse_indices( &self, old_indices: &[<Self as TensorIndex>::Index], new_index: <Self as TensorIndex>::Index, order: LinearizationOrder, ) -> Result<Self, Self::Error>

Fuse local tensor indices into one replacement index.

§Errors

Returns Self::Error when old_indices is not a subset of the tensor’s external indices (a missing-index failure) or the fused dimension product overflows (an overflow failure).

Source

fn contract(tensors: &[&Self]) -> Result<Self, Self::Error>

Contract a connected tensor network over its contractable indices.

§Errors

Returns Self::Error when the network is disconnected (a disconnected-network failure), when indices are incompatible (an index-space mismatch), or when the underlying contraction reports a failure.

Provided Methods§

Source

fn direct_sum_many( operands: &[&Self], groups: &[Vec<<Self as TensorIndex>::Index>], ) -> Result<DirectSumResult<Self>, Self::Error>

Direct sum of any number of tensors.

Each entry of groups lists one index per operand, in operand order, and becomes one new index whose dimension is the sum of the group’s dimensions. Operand i occupies its own diagonal block, after the blocks of operands 0..i; all other entries are zero. The indices that belong to no group must be the same for every operand. The result lists those common indices in operands[0]’s order, followed by the new indices in groups order.

The provided implementation folds direct_sum from the left, ((t0 (+) t1) (+) t2) ..., which copies the growing partial result at every step. Implementors with a dense layout should override it with a one-pass construction, as IdxTensor does.

§Errors

Returns Self::Error when operands or groups is empty, when a group does not have one index per operand, when the index spaces are incompatible (an index-space mismatch), or when the underlying construction reports a failure. Types without a block construction return an unsupported-operation error.

§Examples
use tensor4all_core::{DynIndex, IdxTensor, IndexLike, TensorContractionLike};

let (b0, b1, b2) = (DynIndex::new_dyn(1), DynIndex::new_dyn(1), DynIndex::new_dyn(2));
let t0 = IdxTensor::from_dense(vec![b0.clone()], vec![1.0_f64]).unwrap();
let t1 = IdxTensor::from_dense(vec![b1.clone()], vec![2.0_f64]).unwrap();
let t2 = IdxTensor::from_dense(vec![b2.clone()], vec![3.0_f64, 4.0]).unwrap();

let result = IdxTensor::direct_sum_many(&[&t0, &t1, &t2], &[vec![b0, b1, b2]]).unwrap();

assert_eq!(result.new_indices[0].dim(), 4);
assert_eq!(result.tensor.to_vec::<f64>().unwrap(), vec![1.0, 2.0, 3.0, 4.0]);
Source

fn contract_retaining_indices( tensors: &[&Self], retained_indices: &[<Self as TensorIndex>::Index], ) -> Result<Self, Self::Error>

Contract tensors while preserving selected shared indices as batch axes.

This seam was introduced for the batched SRC sketch. The paper basis is Algorithm 1’s independent probe columns; the retained-index execution and fallback contract are tensor4all-specific [AI-Supplied] plumbing.

A retained index is matched elementwise across operands instead of being summed. This is useful for evaluating several independent contractions in one backend call, such as a batch of SRC probe columns. Implementations that do not support retained batch axes may return an operation error.

§Arguments
  • tensors - Connected tensor operands to contract.
  • retained_indices - Shared indices to preserve as output batch axes.
§Returns

The contracted tensor with each retained index present once in its output index list. An empty retained_indices list has the same meaning as Self::contract.

§Errors

Returns Self::Error when the operands are disconnected, an operand index is missing or incompatible, or the retained-index operation is unsupported by the tensor type.

§Examples
use tensor4all_core::{DynIndex, IdxTensor, TensorContractionLike};

let batch = DynIndex::new_dyn(2);
let contracted = DynIndex::new_dyn(2);
let left = IdxTensor::from_dense(
    vec![batch.clone(), contracted.clone()],
    vec![1.0_f64, 2.0, 3.0, 4.0],
)
.unwrap();
let right = IdxTensor::from_dense(
    vec![batch.clone(), contracted],
    vec![2.0_f64, 3.0, 4.0, 5.0],
)
.unwrap();
let result = IdxTensor::contract_retaining_indices(&[&left, &right], &[batch]).unwrap();
assert_eq!(result.dims(), vec![2]);
assert_eq!(result.to_vec::<f64>().unwrap(), vec![14.0, 26.0]);
Source

fn contract_pair(&self, other: &Self) -> Result<Self, Self::Error>

Contract this tensor with one other tensor using default pairwise semantics.

§Errors

Returns Self::Error when the pair is disconnected or has incompatible indices (an index-space mismatch); propagates failures from Self::contract.

Source

fn validate(&self) -> Result<(), Self::Error>

Validate structural consistency of this tensor.

§Errors

Returns Self::Error when the tensor’s index space or shape is structurally inconsistent (an index-space mismatch or an invalid internal state). The default implementation always returns Ok(()).

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§