Skip to main content

EinsumOps

Trait EinsumOps 

Source
pub trait EinsumOps: EinsumInputs {
    // Required methods
    fn einsum(
        &self,
        spec: &(impl EinsumSpec + ?Sized),
        exec: &mut dyn Engine,
    ) -> Result<<Self::Repr as Repr>::Value>;
    fn einsum_with(
        &self,
        spec: &(impl EinsumSpec + ?Sized),
        options: &EinsumOptions,
        exec: &mut dyn Engine,
    ) -> Result<<Self::Repr as Repr>::Value>;
    fn einsum_into(
        &self,
        spec: &(impl EinsumSpec + ?Sized),
        options: &EinsumOptions,
        exec: &mut dyn Engine,
        dest: Dest<<Self::Repr as Repr>::Write<'_>>,
    ) -> Result<()>;
}
Expand description

Einsum on a list of concrete inputs: a slice, array or Vec of anything that implements AsView (owned, borrowed and typed tensors, strided views) with one representation. The result is a Tensor for erased inputs and a typed tensor for typed inputs. The spec comes first, then the options, then the engine.

Generated by api_ops! from the einsum registry.

Required Methods§

Source

fn einsum( &self, spec: &(impl EinsumSpec + ?Sized), exec: &mut dyn Engine, ) -> Result<<Self::Repr as Repr>::Value>

Einstein summation over N inputs: contract, trace, transpose, reduce and broadcast as the spec says.

Uses the default EinsumOptions; same as einsum_with with &EinsumOptions::default().

§Layout

Strided inputs are read in place by the contraction kernels (any strides, including transposed and negative-stride views); an operand that a kernel cannot read is packed once into a compact buffer of the same placement and dtype. A two-input contraction that maps to one dot_general writes straight into the destination. Inputs stay on their device. _into checks the destination’s dtype and shape before any write; Accumulate and Scaled read the destination, Overwrite and Scaled with beta = 0 never read it.

§Errors

Returns an error of kind:

  • Validation
  • Unsupported
  • RuntimeState
§Omissions
  • _into is concrete only: traced and eager results are new values
  • lanes (CpuEngine::with_lanes): einsum is unsupported in a lane
  • Scaled needs alpha and beta of the input dtype
§Examples
use tenferro_cpu::CpuEngine;
use tenferro_einsum::{ConjMask, EinsumOps, EinsumOptions};
use tenferro_tensor::{Conj, Dest, Tensor};

let mut engine = CpuEngine::serial();
let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
let b = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 0.0, 0.0, 1.0])?;
let c = [&a, &b].einsum("ij,jk->ik", &mut engine)?;
assert_eq!(c.as_slice::<f64>()?, &[1.0, 2.0, 3.0, 4.0]);

// Options: conjugate the first operand (a no-op for real data).
let opts = EinsumOptions::default().conj(ConjMask::new([Conj::Yes]));
let d = [&a, &b].einsum_with("ij,jk->ik", &opts, &mut engine)?;
assert_eq!(d.as_slice::<f64>()?, c.as_slice::<f64>()?);

// Accumulate into an existing result: out = a b + out.
let mut out = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
[&a, &b].einsum_into("ij,jk->ik", &EinsumOptions::default(), &mut engine, Dest::accumulate(&mut out))?;
assert_eq!(out.as_slice::<f64>()?, &[2.0, 3.0, 4.0, 5.0]);
Source

fn einsum_with( &self, spec: &(impl EinsumSpec + ?Sized), options: &EinsumOptions, exec: &mut dyn Engine, ) -> Result<<Self::Repr as Repr>::Value>

Einstein summation over N inputs: contract, trace, transpose, reduce and broadcast as the spec says.

With explicit EinsumOptions.

§Layout

Strided inputs are read in place by the contraction kernels (any strides, including transposed and negative-stride views); an operand that a kernel cannot read is packed once into a compact buffer of the same placement and dtype. A two-input contraction that maps to one dot_general writes straight into the destination. Inputs stay on their device. _into checks the destination’s dtype and shape before any write; Accumulate and Scaled read the destination, Overwrite and Scaled with beta = 0 never read it.

§Errors

Returns an error of kind:

  • Validation
  • Unsupported
  • RuntimeState
§Omissions
  • _into is concrete only: traced and eager results are new values
  • lanes (CpuEngine::with_lanes): einsum is unsupported in a lane
  • Scaled needs alpha and beta of the input dtype
§Examples
use tenferro_cpu::CpuEngine;
use tenferro_einsum::{ConjMask, EinsumOps, EinsumOptions};
use tenferro_tensor::{Conj, Dest, Tensor};

let mut engine = CpuEngine::serial();
let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
let b = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 0.0, 0.0, 1.0])?;
let c = [&a, &b].einsum("ij,jk->ik", &mut engine)?;
assert_eq!(c.as_slice::<f64>()?, &[1.0, 2.0, 3.0, 4.0]);

// Options: conjugate the first operand (a no-op for real data).
let opts = EinsumOptions::default().conj(ConjMask::new([Conj::Yes]));
let d = [&a, &b].einsum_with("ij,jk->ik", &opts, &mut engine)?;
assert_eq!(d.as_slice::<f64>()?, c.as_slice::<f64>()?);

// Accumulate into an existing result: out = a b + out.
let mut out = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
[&a, &b].einsum_into("ij,jk->ik", &EinsumOptions::default(), &mut engine, Dest::accumulate(&mut out))?;
assert_eq!(out.as_slice::<f64>()?, &[2.0, 3.0, 4.0, 5.0]);
Source

fn einsum_into( &self, spec: &(impl EinsumSpec + ?Sized), options: &EinsumOptions, exec: &mut dyn Engine, dest: Dest<<Self::Repr as Repr>::Write<'_>>, ) -> Result<()>

Einstein summation over N inputs: contract, trace, transpose, reduce and broadcast as the spec says.

Writes into dest instead of returning a new tensor. Accepted destination modes: Overwrite, Accumulate, Scaled; any other mode returns an Unsupported error before any data is read or written.

§Layout

Strided inputs are read in place by the contraction kernels (any strides, including transposed and negative-stride views); an operand that a kernel cannot read is packed once into a compact buffer of the same placement and dtype. A two-input contraction that maps to one dot_general writes straight into the destination. Inputs stay on their device. _into checks the destination’s dtype and shape before any write; Accumulate and Scaled read the destination, Overwrite and Scaled with beta = 0 never read it.

§Errors

Returns an error of kind:

  • Validation
  • Unsupported
  • RuntimeState
§Omissions
  • _into is concrete only: traced and eager results are new values
  • lanes (CpuEngine::with_lanes): einsum is unsupported in a lane
  • Scaled needs alpha and beta of the input dtype
§Examples
use tenferro_cpu::CpuEngine;
use tenferro_einsum::{ConjMask, EinsumOps, EinsumOptions};
use tenferro_tensor::{Conj, Dest, Tensor};

let mut engine = CpuEngine::serial();
let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
let b = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 0.0, 0.0, 1.0])?;
let c = [&a, &b].einsum("ij,jk->ik", &mut engine)?;
assert_eq!(c.as_slice::<f64>()?, &[1.0, 2.0, 3.0, 4.0]);

// Options: conjugate the first operand (a no-op for real data).
let opts = EinsumOptions::default().conj(ConjMask::new([Conj::Yes]));
let d = [&a, &b].einsum_with("ij,jk->ik", &opts, &mut engine)?;
assert_eq!(d.as_slice::<f64>()?, c.as_slice::<f64>()?);

// Accumulate into an existing result: out = a b + out.
let mut out = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
[&a, &b].einsum_into("ij,jk->ik", &EinsumOptions::default(), &mut engine, Dest::accumulate(&mut out))?;
assert_eq!(out.as_slice::<f64>()?, &[2.0, 3.0, 4.0, 5.0]);

Dyn Compatibility§

This trait is not dyn compatible.

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

Implementors§