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§
Sourcefn direct_sum(
&self,
other: &Self,
pairs: &[(<Self as TensorIndex>::Index, <Self as TensorIndex>::Index)],
) -> Result<DirectSumResult<Self>, Self::Error>
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.
Sourcefn outer_product(&self, other: &Self) -> Result<Self, Self::Error>
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.
Sourcefn permuteinds(
&self,
new_order: &[<Self as TensorIndex>::Index],
) -> Result<Self, Self::Error>
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).
Sourcefn fuse_indices(
&self,
old_indices: &[<Self as TensorIndex>::Index],
new_index: <Self as TensorIndex>::Index,
order: LinearizationOrder,
) -> 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>
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).
Sourcefn contract(tensors: &[&Self]) -> Result<Self, Self::Error>
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§
Sourcefn direct_sum_many(
operands: &[&Self],
groups: &[Vec<<Self as TensorIndex>::Index>],
) -> Result<DirectSumResult<Self>, Self::Error>
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]);Sourcefn contract_retaining_indices(
tensors: &[&Self],
retained_indices: &[<Self as TensorIndex>::Index],
) -> Result<Self, Self::Error>
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]);Sourcefn contract_pair(&self, other: &Self) -> Result<Self, Self::Error>
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.
Sourcefn validate(&self) -> Result<(), Self::Error>
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".