Skip to main content

ConcreteEinsumPlan

Struct ConcreteEinsumPlan 

Source
pub struct ConcreteEinsumPlan { /* private fields */ }
Expand description

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::CpuEngine;
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::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", &Default::default())?;

let mut backend = CpuEngine::serial();
let out = plan.execute(&[&lhs, &rhs], &mut backend)?;
assert_eq!(out.shape(), &[2, 4]);

Implementations§

Source§

impl ConcreteEinsumPlan

Source

pub fn prepare<I: EinsumInputs + ?Sized>( inputs: &I, spec: &(impl EinsumSpec + ?Sized), options: &EinsumOptions, ) -> Result<Self>

Plan a concrete einsum once from the inputs’ dtypes and shapes; the element data is not read. The plan honours options.optimize (an explicit path, nested grouping or tree is used as given) and records options.conj for every later execution.

§Examples
use tenferro_cpu::CpuEngine;
use tenferro_einsum::{ConcreteEinsumPlan, EinsumOptions};
use tenferro_tensor::Tensor;

let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?;
let plan = ConcreteEinsumPlan::prepare(&[&a, &a], "ij,jk->ik", &EinsumOptions::default())?;
let out = plan.execute(&[&a, &a], &mut CpuEngine::serial())?;
assert_eq!(out.as_slice::<f64>()?, &[7.0, 10.0, 15.0, 22.0]);
§Errors

Validation for a malformed spec (with a tenferro_einsum::Error source), mismatched ranks or extents, or an invalid order.

Source

pub fn execute<I: EinsumInputs + ?Sized>( &self, inputs: &I, exec: &mut dyn Engine, ) -> Result<<I::Repr as Repr>::Value>

Run the plan on inputs with the prepared dtypes and shapes. The result takes the inputs’ representation (typed inputs give a typed result).

§Examples
use tenferro_cpu::CpuEngine;
use tenferro_einsum::{ConcreteEinsumPlan, EinsumOptions};
use tenferro_tensor::TypedTensor;

let a = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
let plan = ConcreteEinsumPlan::prepare(&[&a, &a], "i,i->", &EinsumOptions::default())?;
let dot: TypedTensor<f64> = plan.execute(&[&a, &a], &mut CpuEngine::serial())?;
assert_eq!(dot.host_data()?, &[5.0]);
§Errors

Validation when an input’s dtype or shape differs from the prepared one; backend failures otherwise.

Source

pub fn execute_into<I: EinsumInputs + ?Sized>( &self, inputs: &I, exec: &mut dyn Engine, dest: Dest<<I::Repr as Repr>::Write<'_>>, ) -> Result<()>

Run the plan into dest: Overwrite, Accumulate (out += r) or Scaled (out = alpha r + beta out; beta = 0 never reads out).

§Examples
use tenferro_cpu::CpuEngine;
use tenferro_einsum::{ConcreteEinsumPlan, EinsumOptions};
use tenferro_tensor::{Dest, Tensor};

let a = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let plan = ConcreteEinsumPlan::prepare(&[&a, &a], "i,i->", &EinsumOptions::default())?;
let mut out = Tensor::from_vec_col_major(Vec::<usize>::new(), vec![10.0_f64])?;
plan.execute_into(&[&a, &a], &mut CpuEngine::serial(), Dest::scaled(&mut out, 2.0, 1.0))?;
assert_eq!(out.as_slice::<f64>()?, &[20.0]);
§Errors

Validation when an input or the destination has another dtype or shape than the plan, or alpha/beta have another dtype; checked before any write.

Source§

impl ConcreteEinsumPlan

Source

pub fn clear_cpu_cache(&mut self)

Release this plan’s retained CPU numerical descriptors.

The semantic contraction tree and the owning backend’s workspaces are unchanged.

§Examples
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::Tensor;
let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
let mut plan =
    ConcreteEinsumPlan::prepare(&[&a, &a, &a], "ij,jk,kl->il", &Default::default())?;
plan.clear_cpu_cache();
assert_eq!(plan.cpu_cache_stats()?.entries, 0);
Source

pub fn cpu_cache_stats(&self) -> Result<CacheStats>

Inspect this plan’s bounded CPU numerical descriptor cache.

Counts exclude backend-owned scratch and allocator RSS. Retained bytes currently describe host layout descriptors and opaque lower plan headers.

§Examples
use tenferro_einsum::ConcreteEinsumPlan;
use tenferro_tensor::Tensor;
let a = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
let plan =
    ConcreteEinsumPlan::prepare(&[&a, &a, &a], "ij,jk,kl->il", &Default::default())?;
assert_eq!(plan.cpu_cache_stats()?.entries, 0);
§Errors

Returns Error when no CPU plan cache exists for this plan.

Trait Implementations§

Source§

impl Debug for ConcreteEinsumPlan

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> ByRef<T> for T

§

fn by_ref(&self) -> &T

§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T, U> Imply<T> for U
where T: ?Sized, U: ?Sized,

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

§

impl<T, S> SimdFrom<T, S> for T
where S: Simd,

§

fn simd_from(_simd: S, value: T) -> T

§

impl<F, T, S> SimdInto<T, S> for F
where T: SimdFrom<F, S>, S: Simd,

§

fn simd_into(self, simd: S) -> T

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V