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
impl ConcreteEinsumPlan
Sourcepub fn prepare<I: EinsumInputs + ?Sized>(
inputs: &I,
spec: &(impl EinsumSpec + ?Sized),
options: &EinsumOptions,
) -> Result<Self>
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.
Sourcepub fn execute<I: EinsumInputs + ?Sized>(
&self,
inputs: &I,
exec: &mut dyn Engine,
) -> Result<<I::Repr as Repr>::Value>
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.
Sourcepub fn execute_into<I: EinsumInputs + ?Sized>(
&self,
inputs: &I,
exec: &mut dyn Engine,
dest: Dest<<I::Repr as Repr>::Write<'_>>,
) -> Result<()>
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
impl ConcreteEinsumPlan
Sourcepub fn clear_cpu_cache(&mut self)
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);Sourcepub fn cpu_cache_stats(&self) -> Result<CacheStats>
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§
Auto Trait Implementations§
impl !Freeze for ConcreteEinsumPlan
impl RefUnwindSafe for ConcreteEinsumPlan
impl Send for ConcreteEinsumPlan
impl Sync for ConcreteEinsumPlan
impl Unpin for ConcreteEinsumPlan
impl UnsafeUnpin for ConcreteEinsumPlan
impl UnwindSafe for ConcreteEinsumPlan
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
impl<T, U> Imply<T> for U
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
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 moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
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