pub struct EagerTensor { /* private fields */ }Expand description
Eager tensor with reverse-mode autodiff over concrete tensor values.
This executes each primitive immediately and records a lightweight reverse
DAG for EagerSession::backward. Gradients accumulate across repeated EagerSession::backward
calls until they are cleared explicitly.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap())?;
for _ in 0..2 {
let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
let squared = s.mul(&x, &x)?;
s.reduce_sum(&squared, Some(&[0]))
})?;
loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss))?;
}
assert_eq!(x.grad()?.unwrap().as_slice::<f64>().unwrap(), &[4.0, 8.0, 12.0]);
x.clear_grad()?;
assert!(x.grad().unwrap().is_none());Implementations§
Source§impl EagerTensor
impl EagerTensor
Sourcepub fn value(&self) -> Result<ValueGuard<'_>, Error>
pub fn value(&self) -> Result<ValueGuard<'_>, Error>
Borrow the retained value without creating an owner or copy.
§Errors
Returns Error::RuntimeState when the retained allocation-group
descriptor is unavailable or invalid.
Sourcepub fn into_value(self) -> Result<Tensor, IntoValueError<EagerTensor>>
pub fn into_value(self) -> Result<Tensor, IntoValueError<EagerTensor>>
Consume this handle and structurally extract its retained allocation.
A shared handle is returned unchanged as IntoValueError::NotUnique.
Group extraction failures return the unchanged handle and typed group
error; no copy or fallback materialization is attempted.
§Errors
Returns IntoValueError::NotUnique when another handle retains the
value, or IntoValueError::Extract when structural group extraction
fails because the allocation is aliased or its descriptor is invalid.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let value = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
let owner = value
.into_value()
.expect("a uniquely owned value should be extractable");
assert_eq!(owner.as_slice::<f64>()?, &[3.0]);Sourcepub fn dtype(&self) -> DType
pub fn dtype(&self) -> DType
Return this tensor’s scalar dtype without materializing through
value.
Sourcepub fn shape(&self) -> &[usize]
pub fn shape(&self) -> &[usize]
Return this tensor’s logical shape without materializing through
value.
Sourcepub fn tensor_read(&self) -> TensorRead<'_>
pub fn tensor_read(&self) -> TensorRead<'_>
Borrow this tensor value as a TensorRead.
This is the preferred borrowed input boundary for executor calls. It
preserves the option to replace eager storage with non-contiguous views
without forcing callers through value.
§Panics
Panics if a validated eager value record becomes unavailable, which indicates an internal invariant violation.
Sourcepub fn grad(&self) -> Result<Option<GradientValue>, Error>
pub fn grad(&self) -> Result<Option<GradientValue>, Error>
Return the accumulated gradient currently stored for this tensor.
The stored gradient accumulates across repeated EagerSession::backward calls
until it is cleared explicitly.
For complex scalar losses, stored gradients use tenferro’s Hermitian-adjoint cotangent convention. See https://tensor4all.org/tenferro-rs/guides/complex-ad.html.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap()).unwrap();
let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
let y = s.exp(&x)?;
s.reduce_sum(&y, Some(&[0]))
})?;
let _cotangents = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
let grad = x.grad()?.unwrap();
assert_eq!(grad.shape(), &[2]);§Errors
Returns Error::RuntimeState if the gradient slot is poisoned or no
longer available.
Sourcepub fn clear_grad(&self) -> Result<(), Error>
pub fn clear_grad(&self) -> Result<(), Error>
Clear the accumulated gradient stored for this tensor.
This only affects this tensor’s gradient slot. Other tensors in the same context retain their gradients until they are cleared explicitly or overwritten by later accumulation.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
let y = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![4.0_f64, 5.0, 6.0]).unwrap()).unwrap();
let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
let product = s.mul(&x, &y)?;
s.reduce_sum(&product, Some(&[0]))
})?;
let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
x.clear_grad()?;
assert!(x.grad()?.is_none());
assert!(y.grad()?.is_some());§Errors
Returns Error::RuntimeState if the gradient slot lock is poisoned.
Sourcepub fn tracks_grad(&self) -> bool
pub fn tracks_grad(&self) -> bool
Report whether this tensor participates in gradient tracking.
Tracked tensors keep a gradient slot in their eager context; untracked tensors and detached tensors do not.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let plain = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap()).unwrap();
let tracked = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap()).unwrap();
let detached = tracked.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.detach(&tracked)).unwrap();
assert!(!plain.tracks_grad());
assert!(tracked.tracks_grad());
assert!(!detached.tracks_grad());Sourcepub fn ctx_id(&self) -> ContextId
pub fn ctx_id(&self) -> ContextId
Return the opaque identifier of the context this tensor belongs to.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
assert_eq!(x.ctx_id(), ctx.id());Sourcepub fn runtime(&self) -> &Arc<EagerRuntime> ⓘ
pub fn runtime(&self) -> &Arc<EagerRuntime> ⓘ
Borrow the eager runtime context that owns this tensor.
Sourcepub fn same_context(&self, other: &EagerTensor) -> bool
pub fn same_context(&self, other: &EagerTensor) -> bool
Check whether two tensors belong to the same eager context.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap()).unwrap();
assert!(x.same_context(&y));Source§impl EagerTensor
impl EagerTensor
Sourcepub fn slice_builder(&self) -> EagerSliceBuilder<'_>
pub fn slice_builder(&self) -> EagerSliceBuilder<'_>
Start a rank-preserving slicing builder for this tensor.
§Examples
use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
let ctx = EagerRuntime::new()?;
let x = ctx.constant_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
let y = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| x.slice_builder().axis(0, 0..2).apply(s))?;
assert_eq!(y.shape(), &[2]);Trait Implementations§
Source§impl Clone for EagerTensor
impl Clone for EagerTensor
Source§fn clone(&self) -> EagerTensor
fn clone(&self) -> EagerTensor
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreAuto Trait Implementations§
impl !RefUnwindSafe for EagerTensor
impl !UnwindSafe for EagerTensor
impl Freeze for EagerTensor
impl Send for EagerTensor
impl Sync for EagerTensor
impl Unpin for EagerTensor
impl UnsafeUnpin for EagerTensor
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
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
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