Struct EagerRuntime 

pub struct EagerRuntime { /* private fields */ }

Shared eager execution context for tensors on a backend.

Reusing one context lets eager tensors share backend state, extension runtime caches, and gradient storage across a computation.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::from_tensor_in(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap(), ctx.clone()).unwrap();
let y = EagerTensor::from_tensor_in(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap(), ctx).unwrap();
let z = x.add(&y).unwrap();

assert_eq!(z.materialized().unwrap().as_slice::<f64>().unwrap(), &[3.0]);

Implementations

impl EagerRuntime

pub fn new() -> Arc<Self>

Create a shared CPU eager execution context.

Examples

use tenferro_ad::EagerRuntime;

let ctx = EagerRuntime::new();
assert_eq!(std::sync::Arc::strong_count(&ctx), 1);

pub fn with_cpu_backend(backend: CpuBackend) -> Arc<Self>

Create a shared eager execution context from a configured CPU backend.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::with_threads(1).unwrap());
assert_eq!(std::sync::Arc::strong_count(&ctx), 1);

pub fn with_cpu_backend_and_ad_context( backend: CpuBackend, ad: &AdContext, ) -> Arc<Self>

Create a shared CPU eager context with explicit AD extension rules.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{AdContext, EagerRuntime};

let ad = AdContext::builder().build().unwrap();
let ctx = EagerRuntime::with_cpu_backend_and_ad_context(CpuBackend::new(), &ad);
assert_eq!(std::sync::Arc::strong_count(&ctx), 1);

pub fn id(&self) -> ContextId

Return an opaque identifier for this context.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
assert_ne!(ctx.id(), EagerRuntime::with_cpu_backend(CpuBackend::new()).id());

pub fn no_grad(&self) -> EagerNoGradGuard

Disable eager operation recording on the current thread until the guard is dropped.

This is useful for optimizer updates, metric calculations, and other eager computations that should not become part of the AD tape.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![1], vec![3.0_f64]).unwrap(),
    ctx.clone(),
)?;
let y = {
    let _guard = ctx.no_grad();
    x.mul(&x)?
};
assert!(!y.tracks_grad());

pub fn register_extension( &self, register: impl FnOnce(&mut ExtensionExecutor<EagerBackend>) -> Result<(), ExtensionRuntimeRegistryError>, ) -> Result<(), ExtensionRuntimeRegistryError>

Register one extension runtime on this eager context.

pub fn clear_extension_caches(&self) -> Result<()>

Clear generic extension runtime cache entries.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
ctx.clear_extension_caches()?;
assert_eq!(ctx.cache_stats()?.extensions.entries, 0);

pub fn clear_caches(&self) -> Result<()>

Clear every cache owned by this eager context.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
ctx.clear_caches()?;
assert_eq!(ctx.cache_stats()?.extensions.entries, 0);
assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);

pub fn cache_stats(&self) -> Result<EagerRuntimeCacheStats>

Return eager runtime cache-entry and retained-byte stats.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let stats = ctx.cache_stats()?;
assert_eq!(stats.extensions.entries, 0);
assert_eq!(stats.ad_transforms.entries, 0);

pub fn ad_transform_cache_limits(&self) -> Result<AdTransformCacheLimits>

Return the AD transform cache retention limits.

Examples

use tenferro_ad::EagerRuntime;
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
assert!(ctx.ad_transform_cache_limits()?.max_entries().get() > 0);

pub fn set_ad_transform_cache_limits( &self, limits: AdTransformCacheLimits, ) -> Result<()>

Replace AD transform cache retention limits.

Examples

use std::num::NonZeroUsize;
use tenferro_ad::{AdTransformCacheLimits, EagerRuntime};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let limits = AdTransformCacheLimits::new(NonZeroUsize::new(1).unwrap());
ctx.set_ad_transform_cache_limits(limits)?;
assert_eq!(ctx.ad_transform_cache_limits()?, limits);

pub fn clear_ad_transform_caches(&self) -> Result<()>

Clear AD transform cache entries visible through this eager runtime.

Examples

use tenferro_ad::EagerRuntime;
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
ctx.clear_ad_transform_caches()?;
assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);

pub fn extension_cache_limits(&self) -> Result<ExtensionCacheLimits>

Return the extension cache retention limits.

pub fn set_extension_cache_limits( &self, limits: ExtensionCacheLimits, ) -> Result<()>

Replace extension cache retention limits.

pub fn with_extension_caches_mut<R>( &self, f: impl FnOnce(&mut ExtensionCacheStore) -> R, ) -> Result<R>

Mutably borrow generic extension runtime cache storage.

This hook is for standard extension crates that need cache entries owned by an eager runtime while preserving eager value semantics outside a registered extension execution boundary.

Examples

use tenferro_ad::EagerRuntime;
use tenferro_cpu::CpuBackend;
use tenferro_runtime::ExtensionCacheKey;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let key = ExtensionCacheKey::new("example.cache.v1", "plans", 1);

ctx.with_extension_caches_mut(|caches| {
    caches.put(key, 7_usize, std::mem::size_of::<usize>());
});

assert_eq!(ctx.cache_stats().unwrap().extensions.entries, 1);

pub fn with_backend_mut<R>( &self, f: impl FnOnce(&mut EagerBackend) -> R, ) -> Result<R>

Mutably borrow this runtime’s backend.

This hook lets standard extension crates run a whole contraction program in a single backend session (instead of one eager op per step) while preserving eager value semantics for untracked tensors.

Examples

use tenferro_ad::EagerRuntime;
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
// The closure receives `&mut EagerBackend`; standard extension crates
// use it to open one backend session for a whole contraction program.
let answer = ctx.with_backend_mut(|_backend| 42).unwrap();
assert_eq!(answer, 42);

pub fn synchronize(&self) -> Result<()>

Block the current thread until backend work submitted by this eager runtime completes.

CPU runtimes return immediately. CUDA and WebGPU runtimes synchronize their current backend work queue.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::EagerRuntime;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
ctx.synchronize().unwrap();

pub fn clear_grads(&self) -> Result<()>

Clear all live gradient slots tracked by this context.

This resets the stored gradients to None without unregistering the tensors, so future backward() calls can accumulate again.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap(), ctx.clone()).unwrap();
let y = EagerTensor::requires_grad_in(Tensor::from_vec_col_major(vec![3], vec![4.0_f64, 5.0, 6.0]).unwrap(), ctx.clone()).unwrap();
let loss = x.mul(&y).unwrap().reduce_sum(&[0]).unwrap();
let _ = loss.backward().unwrap();

ctx.clear_grads()?;

assert!(x.grad()?.is_none());
assert!(y.grad()?.is_none());

pub fn constant_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor>

Import a concrete tensor into this context as an untracked constant.

The returned tensor does not participate in gradient tracking. Use this for fixed masks, quadrature weights, physical constants, and other data that should not receive gradients.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let c = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
let x = EagerTensor::requires_grad_in(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap(), ctx)?;
let z = x.add(&c).unwrap();

assert_eq!(z.materialized()?.as_slice::<f64>().unwrap(), &[4.0, 6.0]);

pub fn variable_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor>

Import a concrete tensor into this context as a trainable variable.

The returned tensor participates in gradient tracking; its gradient slot is registered in this context.

Examples

use tenferro_cpu::CpuBackend;
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let p = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
let loss = p.exp().unwrap().reduce_sum(&[0]).unwrap();
let _ = loss.backward().unwrap();

let grad = p.grad().unwrap().unwrap();
assert_eq!(grad.shape(), &[2]);

pub fn grad( self: &Arc<Self>, output: &EagerTensor, wrt: &EagerTensor, ) -> Result<EagerTensor>

Gradient of a scalar eager output with respect to an eager tensor.

Functional eager gradients return ordinary eager tensors and do not write into grad() slots. The returned tensor keeps a trace when the derivative computation depends on tracked eager values.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![], vec![3.0_f64]).unwrap(),
    ctx.clone(),
)?;
let loss = x.mul(&x)?;
let dx = ctx.grad(&loss, &x)?;
assert_eq!(dx.materialized()?.as_slice::<f64>().unwrap(), &[6.0]);

pub fn grad_optional( self: &Arc<Self>, output: &EagerTensor, wrt: &EagerTensor, ) -> Result<Option<EagerTensor>>

Gradient that returns None when wrt is inactive.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![], vec![3.0_f64]).unwrap(),
    ctx.clone(),
)?;
let y = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![], vec![4.0_f64]).unwrap(),
    ctx.clone(),
)?;
let loss = y.mul(&y)?;
assert!(ctx.grad_optional(&loss, &x)?.is_none());

pub fn vjp( self: &Arc<Self>, output: &EagerTensor, wrt: &EagerTensor, cotangent: &EagerTensor, ) -> Result<EagerTensor>

Reverse-mode vector-Jacobian product for eager tensors.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0]).unwrap(),
    ctx.clone(),
)?;
let y = x.mul(&x)?;
let seed = EagerTensor::from_tensor_in(
    Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 1.0]).unwrap(),
    ctx.clone(),
)?;
let dx = ctx.vjp(&y, &x, &seed)?;
assert_eq!(dx.materialized()?.as_slice::<f64>().unwrap(), &[4.0, 6.0]);

pub fn vjp_optional( self: &Arc<Self>, output: &EagerTensor, wrt: &EagerTensor, cotangent: &EagerTensor, ) -> Result<Option<EagerTensor>>

Reverse-mode vector-Jacobian product that returns None for inactive inputs.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap(),
    ctx.clone(),
)?;
let y = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![1], vec![4.0_f64]).unwrap(),
    ctx.clone(),
)?;
let seed = EagerTensor::from_tensor_in(
    Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap(),
    ctx.clone(),
)?;
let loss = y.mul(&y)?;
assert!(ctx.vjp_optional(&loss, &x, &seed)?.is_none());

pub fn jvp( self: &Arc<Self>, output: &EagerTensor, wrt: &EagerTensor, tangent: &EagerTensor, ) -> Result<EagerTensor>

Forward-mode Jacobian-vector product for eager tensors.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![1], vec![3.0_f64]).unwrap(),
    ctx.clone(),
)?;
let tangent = EagerTensor::from_tensor_in(
    Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap(),
    ctx.clone(),
)?;
let y = x.mul(&x)?;
let dy = ctx.jvp(&y, &x, &tangent)?;
assert_eq!(dy.materialized()?.as_slice::<f64>().unwrap(), &[6.0]);

pub fn jvp_optional( self: &Arc<Self>, output: &EagerTensor, wrt: &EagerTensor, tangent: &EagerTensor, ) -> Result<Option<EagerTensor>>

Forward-mode Jacobian-vector product that returns None for inactive outputs.

Examples

use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
use tenferro_cpu::CpuBackend;

let ctx = EagerRuntime::with_cpu_backend(CpuBackend::new());
let x = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap(),
    ctx.clone(),
)?;
let y = EagerTensor::requires_grad_in(
    Tensor::from_vec_col_major(vec![1], vec![4.0_f64]).unwrap(),
    ctx.clone(),
)?;
let tangent = EagerTensor::from_tensor_in(
    Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap(),
    ctx.clone(),
)?;
let loss = y.mul(&y)?;
assert!(ctx.jvp_optional(&loss, &x, &tangent)?.is_none());

Trait Implementations

impl Debug for EagerRuntime

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

Formats the value using the given formatter.