tenferro_ad/eager.rs
1use std::cell::{Cell, RefCell};
2use std::cmp::Reverse;
3use std::collections::HashMap;
4use std::env;
5use std::fmt;
6use std::marker::PhantomData;
7use std::mem::{size_of, size_of_val};
8use std::rc::Rc;
9#[cfg(test)]
10use std::sync::atomic::{AtomicUsize, Ordering};
11use std::sync::{Arc, Mutex, MutexGuard, OnceLock, Weak};
12use std::time::{Duration, Instant};
13
14use lru::LruCache;
15use num_complex::Complex64;
16
17use crate::extension::{
18 validate_eager_extension_target, EagerExtensionBackendKind, EagerExtensionTarget,
19};
20
21#[cfg(test)]
22use computegraph::graph::Graph;
23use computegraph::ValueKey;
24#[cfg(test)]
25use computegraph::ValueRef;
26use tenferro_ops::dim_expr::DimExpr;
27#[cfg(test)]
28use tenferro_ops::input_key::TensorInputKey;
29use tenferro_ops::{std_tensor_op::StdTensorOp, SymDim, TensorMeta};
30use tenferro_runtime::ad_support::{ones_tensor, RetainedValue};
31use tenferro_runtime::program::{ProgramValueMetadata, SemanticFingerprint, SemanticProgram};
32use tenferro_runtime::{
33 CompiledGraph, EngineId, EngineTarget, ErrorPhase, ExecutionContextIdentity, ExecutionEngine,
34 ExtensionModule, GraphCompiler, Prepared, Runtime, RuntimeConfigError, RuntimeEpoch,
35};
36use tenferro_tensor::Engine;
37#[cfg(test)]
38use tenferro_tensor::TypedTensor;
39use tenferro_tensor::{
40 AllocationGroup, CacheStats, CompareDir, DType, DescriptorSlot, DotGeneralConfig, GatherConfig,
41 GroupError, IntoShapeVec, PadConfig, ScatterConfig, SliceConfig, Tensor, TensorRead,
42 TensorScalar, TensorValue, TensorView,
43};
44
45use crate::eager_backend::{
46 cpu_host_owned_read, engine_kind_registration, unregisterable_engine_error,
47};
48#[cfg(test)]
49use crate::eager_exec::exec_standard_op_on_tensor_reads_in_session;
50use crate::eager_exec::{eager_input_promotion_plan, exec_extension_op_on_tensor_reads};
51use crate::error::{ContextId, Error, Result};
52use crate::semantic_extension::SemanticExtensionRuleSet;
53use crate::transform_cache::{AdTransformCache, AdTransformCacheLimits};
54use tenferro_runtime::ad_support::next_input_key;
55use tenferro_runtime::ad_support::tensor_meta_from_tensor;
56
57use crate::AdContext;
58
59pub(crate) type GradSlot = Arc<Mutex<Option<Arc<AdValueRecord>>>>;
60pub(crate) type WeakGradSlot = Weak<Mutex<Option<Arc<AdValueRecord>>>>;
61
62mod composite;
63mod residuals;
64mod semantic;
65pub(crate) use residuals::{finish_residuals, EagerTrace};
66use semantic::{replay, SemanticValue};
67
68#[derive(Debug, Default, Clone)]
69struct EagerOpProfileEntry {
70 calls: usize,
71 total_time: Duration,
72}
73
74thread_local! {
75 static EAGER_OP_PROFILE_STATE: RefCell<HashMap<&'static str, EagerOpProfileEntry>> =
76 RefCell::new(HashMap::new());
77 static EAGER_NO_GRAD_DEPTH: Cell<usize> = const { Cell::new(0) };
78 static EAGER_CAPTURE_DEPTH: Cell<usize> = const { Cell::new(0) };
79 #[cfg(test)]
80 static EAGER_OP_PROFILE_ENABLED_OVERRIDE: RefCell<Option<bool>> = const { RefCell::new(None) };
81 #[cfg(test)]
82 static EAGER_OP_PROFILE_PRINT_EVERY_OVERRIDE: RefCell<Option<Option<usize>>> = const { RefCell::new(None) };
83}
84
85#[cfg(test)]
86pub(crate) static EAGER_SEMANTIC_VJP_EXECUTIONS: AtomicUsize = AtomicUsize::new(0);
87
88pub(crate) fn eager_grad_recording_enabled() -> bool {
89 EAGER_NO_GRAD_DEPTH.with(|depth| depth.get() == 0)
90}
91
92pub(crate) fn eager_capture_active() -> bool {
93 EAGER_CAPTURE_DEPTH.with(|depth| depth.get() > 0)
94}
95
96/// Scope guard that temporarily disables eager operation recording.
97///
98/// Values computed while this guard is alive are concrete eager tensors, but
99/// they do not participate in reverse-mode gradient tracking.
100///
101/// # Examples
102///
103/// ```
104/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
105///
106/// let ctx = EagerRuntime::new()?;
107/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap())?;
108/// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
109/// let _guard = ctx.no_grad();
110/// s.mul(&x, &x)
111/// })?;
112/// assert!(!y.tracks_grad());
113/// # Ok::<(), tenferro_ad::Error>(())
114/// ```
115#[derive(Debug)]
116pub struct EagerNoGradGuard {
117 active: bool,
118 // Thread-local depth guard: must not be Send so it cannot be moved to and
119 // dropped on another thread (which would corrupt the creator's depth).
120 _not_send: PhantomData<Rc<()>>,
121}
122
123impl Drop for EagerNoGradGuard {
124 fn drop(&mut self) {
125 if !self.active {
126 return;
127 }
128 EAGER_NO_GRAD_DEPTH.with(|depth| {
129 depth.set(depth.get().saturating_sub(1));
130 });
131 self.active = false;
132 }
133}
134
135/// Scope guard that keeps semantic recording active for untracked
136/// intermediates.
137///
138/// Under active-edge semantics (issue #1665 Def 1), an operation whose inputs
139/// are all untracked produces no autograd nodes and drops its semantic value.
140/// Inside this guard, such operations still record it, so a later functional
141/// JVP/VJP can differentiate with respect to an untracked or detached leaf.
142/// This replaces the pre-Def-1 implicit recording.
143///
144/// # Examples
145///
146/// ```
147/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
148///
149/// let ctx = EagerRuntime::new()?;
150/// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
151/// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
152/// let _capture = ctx.capture_trace();
153/// s.mul(&x, &x)
154/// })?;
155/// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 1.0]).unwrap())?;
156/// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.vjp(&y, &x, &seed))?;
157/// assert_eq!(dx.value()?.as_slice::<f64>().unwrap(), &[2.0, 4.0]);
158/// # Ok::<(), tenferro_ad::Error>(())
159/// ```
160#[derive(Debug)]
161pub struct EagerTraceCaptureGuard {
162 active: bool,
163 // Thread-local depth guard: must not be Send so it cannot be moved to and
164 // dropped on another thread (which would corrupt the creator's depth).
165 _not_send: PhantomData<Rc<()>>,
166}
167
168impl Drop for EagerTraceCaptureGuard {
169 fn drop(&mut self) {
170 if !self.active {
171 return;
172 }
173 EAGER_CAPTURE_DEPTH.with(|depth| {
174 depth.set(depth.get().saturating_sub(1));
175 });
176 self.active = false;
177 }
178}
179
180pub(crate) fn eager_op_profile_enabled() -> bool {
181 #[cfg(test)]
182 if let Some(value) = EAGER_OP_PROFILE_ENABLED_OVERRIDE.with(|state| *state.borrow()) {
183 return value;
184 }
185
186 static ENABLED: OnceLock<bool> = OnceLock::new();
187 *ENABLED.get_or_init(|| env::var("TENFERRO_PROFILE_EAGER_OP_AGG").is_ok())
188}
189
190pub(crate) fn eager_op_profile_start() -> Option<Instant> {
191 eager_op_profile_enabled().then(Instant::now)
192}
193
194pub(crate) fn record_eager_op_profile(section: &'static str, elapsed: Duration) {
195 if !eager_op_profile_enabled() {
196 return;
197 }
198 EAGER_OP_PROFILE_STATE.with(|state| {
199 let mut state = state.borrow_mut();
200 let entry = state.entry(section).or_default();
201 entry.calls += 1;
202 entry.total_time += elapsed;
203 });
204}
205
206pub(crate) fn profile_eager_op_section<T>(section: &'static str, f: impl FnOnce() -> T) -> T {
207 if !eager_op_profile_enabled() {
208 return f();
209 }
210 let started = Instant::now();
211 let result = f();
212 record_eager_op_profile(section, started.elapsed());
213 result
214}
215
216pub(crate) fn maybe_print_eager_op_profile() {
217 if !eager_op_profile_enabled() {
218 return;
219 }
220 let Some(print_every) = eager_op_profile_print_every() else {
221 return;
222 };
223 if print_every == 0 {
224 return;
225 }
226
227 let should_print = EAGER_OP_PROFILE_STATE.with(|state| {
228 state
229 .borrow()
230 .get("nary_op.total")
231 .is_some_and(|entry| entry.calls % print_every == 0)
232 });
233 if should_print {
234 print_and_reset_eager_op_profile();
235 }
236}
237
238fn eager_op_profile_print_every() -> Option<usize> {
239 #[cfg(test)]
240 if let Some(value) = EAGER_OP_PROFILE_PRINT_EVERY_OVERRIDE.with(|state| *state.borrow()) {
241 return value;
242 }
243
244 env::var("TENFERRO_PROFILE_EAGER_OP_PRINT_EVERY")
245 .ok()?
246 .parse()
247 .ok()
248}
249
250pub(crate) fn print_and_reset_eager_op_profile() {
251 EAGER_OP_PROFILE_STATE.with(|state| {
252 let mut entries: Vec<_> = state
253 .borrow()
254 .iter()
255 .map(|(section, entry)| (*section, entry.clone()))
256 .collect();
257 state.borrow_mut().clear();
258 entries.sort_by_key(|(_, entry)| Reverse(entry.total_time));
259
260 eprintln!("=== tenferro eager op profile ===");
261 for (section, entry) in entries {
262 let Some(per_call_us) = eager_op_profile_per_call_us(&entry) else {
263 continue;
264 };
265 eprintln!(
266 "{section}: calls={} total={:.6}ms per_call={:.3}us",
267 entry.calls,
268 entry.total_time.as_secs_f64() * 1.0e3,
269 per_call_us,
270 );
271 }
272 });
273}
274
275fn eager_op_profile_per_call_us(entry: &EagerOpProfileEntry) -> Option<f64> {
276 (entry.calls != 0).then(|| entry.total_time.as_secs_f64() * 1.0e6 / entry.calls as f64)
277}
278
279fn runtime_config_error(op: &'static str, source: RuntimeConfigError) -> Error {
280 Error::runtime_state_source(op, ErrorPhase::Execution, source)
281}
282
283fn runtime_state_source<E>(op: &'static str, source: E) -> Error
284where
285 E: std::error::Error + Send + Sync + 'static,
286{
287 Error::runtime_state_source(op, ErrorPhase::Execution, source)
288}
289
290/// Run `prepared` on `engine` and return owned compact outputs.
291pub(crate) fn run_prepared_on(
292 runtime: &Runtime,
293 engine: &mut dyn ExecutionEngine,
294 prepared: &Prepared,
295 inputs: &[TensorRead<'_>],
296) -> Result<Vec<Tensor>> {
297 let outputs = runtime.run(&mut [&mut *engine], prepared, inputs)?;
298 outputs
299 .into_iter()
300 .map(|output| output.into_tensor(&mut *engine).map_err(Error::from))
301 .collect()
302}
303
304/// Run a session-capable prepared extension executor on `engine`, lending it
305/// the engine's extension caches for the call.
306pub(crate) fn execute_prepared_extension_on(
307 engine: &mut dyn ExecutionEngine,
308 executor: &dyn tenferro_runtime::PreparedOperationExecutor,
309 inputs: &[TensorRead<'_>],
310) -> Result<Vec<Tensor>> {
311 with_lent_extension_caches(engine, |engine, caches| {
312 executor.execute_in_session(engine, caches, inputs)
313 })
314}
315
316/// Lend `engine`'s extension caches to `callback` and restore them on every
317/// exit path, including unwind.
318///
319/// A callback panic also marks the engine broken before it is resumed: the
320/// caches may be half updated, so the engine must not accept more work.
321pub(crate) fn with_lent_extension_caches<R>(
322 engine: &mut dyn ExecutionEngine,
323 callback: impl FnOnce(&mut dyn ExecutionEngine, &mut tenferro_runtime::ExtensionCacheStore) -> R,
324) -> R {
325 let mut caches = engine.take_extension_caches();
326 let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
327 callback(&mut *engine, &mut caches)
328 }));
329 engine.restore_extension_caches(caches);
330 match result {
331 Ok(value) => value,
332 Err(payload) => {
333 engine.mark_broken();
334 std::panic::resume_unwind(payload)
335 }
336 }
337}
338
339/// The eager extension backend kind of an engine target, or `None` for an
340/// engine type without eager extension support.
341pub(crate) fn eager_extension_backend_kind(
342 target: &EngineTarget,
343) -> Option<EagerExtensionBackendKind> {
344 if target.context_identity() == ExecutionContextIdentity::of::<tenferro_cpu::CpuEngine>() {
345 return Some(EagerExtensionBackendKind::Cpu);
346 }
347 #[cfg(feature = "cuda")]
348 if target.context_identity() == ExecutionContextIdentity::of::<tenferro_gpu::cuda::CudaEngine>()
349 {
350 return Some(EagerExtensionBackendKind::Cuda);
351 }
352 None
353}
354
355/// Stats for caches owned by an [`EagerRuntime`].
356///
357/// `retained_bytes` fields are logical payload estimates, not process RSS.
358#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
359pub struct EagerRuntimeCacheStats {
360 /// Eager AD transform memoization cache.
361 pub ad_transforms: CacheStats,
362 /// Prepared eager derivative program cache.
363 pub prepared_derivatives: CacheStats,
364}
365
366#[cfg(test)]
367pub(crate) struct EagerGraphExecution {
368 pub(crate) outputs: Vec<Tensor>,
369}
370
371/// A read-only value view retained by an eager tensor record.
372///
373/// The guard borrows the record's allocation group. It never owns a tensor and
374/// cannot be converted into a mutable view.
375///
376/// # Examples
377///
378/// ```
379/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
380///
381/// let ctx = EagerRuntime::new()?;
382/// let value = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
383/// let view = value.value()?;
384/// assert_eq!(view.shape(), &[2]);
385/// # Ok::<(), tenferro_ad::Error>(())
386/// ```
387#[derive(Debug)]
388pub struct ValueGuard<'a> {
389 view: TensorView<'a>,
390}
391
392impl<'a> ValueGuard<'a> {
393 /// Return the scalar dtype of the retained value.
394 pub fn dtype(&self) -> DType {
395 self.view.dtype()
396 }
397
398 /// Return the logical shape of the retained value.
399 pub fn shape(&self) -> &[usize] {
400 self.view.shape()
401 }
402
403 /// Borrow the dtype-erased tensor view.
404 pub fn as_tensor_view(&self) -> &TensorView<'_> {
405 &self.view
406 }
407
408 /// Borrow compact host bytes through the tensor's explicit scalar type.
409 ///
410 /// Backend-resident values return the backend's typed host-access error;
411 /// this method does not download storage implicitly.
412 ///
413 /// # Errors
414 ///
415 /// Returns [`tenferro_tensor::ValidationError::DTypeMismatch`] when
416 /// `T` does not match the view dtype, [`tenferro_tensor::ValidationError::NonContiguousViewAsSlice`]
417 /// for a non-contiguous view, or [`tenferro_tensor::Error::HostAccess`]
418 /// when backend storage cannot be mapped as a host slice.
419 pub fn as_slice<T: TensorScalar>(&self) -> tenferro_tensor::Result<&'a [T]> {
420 self.view.as_slice()
421 }
422
423 fn duplicate_host_tensor(&self) -> tenferro_tensor::Result<Tensor> {
424 match &self.view {
425 TensorView::F32(view) => {
426 <f32 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
427 }
428 TensorView::F64(view) => {
429 <f64 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
430 }
431 TensorView::I32(view) => {
432 <i32 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
433 }
434 TensorView::I64(view) => {
435 <i64 as TensorScalar>::into_tensor(view.shape().to_vec(), view.as_slice()?.to_vec())
436 }
437 TensorView::Bool(view) => <bool as TensorScalar>::into_tensor(
438 view.shape().to_vec(),
439 view.as_slice()?.to_vec(),
440 ),
441 TensorView::C32(view) => <num_complex::Complex32 as TensorScalar>::into_tensor(
442 view.shape().to_vec(),
443 view.as_slice()?.to_vec(),
444 ),
445 TensorView::C64(view) => <num_complex::Complex64 as TensorScalar>::into_tensor(
446 view.shape().to_vec(),
447 view.as_slice()?.to_vec(),
448 ),
449 }
450 }
451}
452
453/// Read-only retained gradient value.
454///
455/// # Examples
456///
457/// ```
458/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
459///
460/// let ctx = EagerRuntime::new()?;
461/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
462/// let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
463/// let squared = s.mul(&x, &x)?;
464/// s.reduce_sum(&squared, Some(&[0]))
465/// })?;
466/// let _gradients = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss))?;
467/// let gradient = x.grad()?.expect("tracked leaf has a gradient");
468/// assert_eq!(gradient.shape(), &[2]);
469/// # Ok::<(), tenferro_ad::Error>(())
470/// ```
471#[derive(Clone, Debug)]
472pub struct GradientValue {
473 record: Arc<AdValueRecord>,
474}
475
476impl GradientValue {
477 /// Return the scalar dtype of the gradient.
478 pub fn dtype(&self) -> DType {
479 self.record.dtype()
480 }
481
482 /// Return the logical shape of the gradient.
483 pub fn shape(&self) -> &[usize] {
484 self.record.shape()
485 }
486
487 /// Borrow the gradient's value guard.
488 ///
489 /// # Errors
490 ///
491 /// Returns [`Error::RuntimeState`] when the retained gradient record is
492 /// unavailable or its allocation-group descriptor is invalid.
493 pub fn value(&self) -> Result<ValueGuard<'_>> {
494 self.record.value("GradientValue::value")
495 }
496
497 /// Borrow the gradient as a dtype-erased read target.
498 ///
499 /// # Errors
500 ///
501 /// Returns [`Error::RuntimeState`] when the retained gradient record or
502 /// its allocation-group descriptor is unavailable.
503 pub fn tensor_read(&self) -> Result<TensorRead<'_>> {
504 self.record.tensor_read("GradientValue::tensor_read")
505 }
506
507 /// Borrow a compact host slice without downloading backend storage.
508 ///
509 /// # Errors
510 ///
511 /// Returns [`Error::RuntimeState`] when the retained value is unavailable,
512 /// [`tenferro_tensor::ValidationError::DTypeMismatch`] when `T` does
513 /// not match the gradient dtype, or [`tenferro_tensor::Error::HostAccess`]
514 /// when backend storage cannot be mapped as a host slice.
515 pub fn as_slice<T: TensorScalar>(&self) -> tenferro_tensor::Result<&[T]> {
516 self.record
517 .value("GradientValue::as_slice")
518 .map_err(|error| {
519 tenferro_tensor::Error::runtime_state_source("GradientValue::as_slice", error)
520 })?
521 .as_slice()
522 }
523
524 /// Explicitly copy a host-resident gradient into a standalone tensor.
525 ///
526 /// # Errors
527 ///
528 /// Returns [`Error::RuntimeState`] when the retained value or execution
529 /// session is unavailable, or a typed backend/host-access error when the
530 /// gradient cannot be materialized as a contiguous tensor.
531 pub fn to_tensor(&self, engine: &mut dyn Engine) -> Result<Tensor> {
532 let value = self
533 .record
534 .value("GradientValue::to_tensor")
535 .map_err(|error| {
536 Error::runtime_state_source(
537 "GradientValue::to_tensor",
538 ErrorPhase::Execution,
539 error,
540 )
541 })?;
542 match value.duplicate_host_tensor() {
543 Ok(tensor) => Ok(tensor),
544 Err(_) => {
545 let read = self.record.tensor_read("GradientValue::to_tensor")?;
546 engine.to_contiguous_read(read).map_err(Error::from)
547 }
548 }
549 }
550}
551
552/// Move-only accumulated gradient bundle backed by one allocation group.
553///
554/// # Examples
555///
556/// ```
557/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
558///
559/// let ctx = EagerRuntime::new()?;
560/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
561/// let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
562/// let squared = s.mul(&x, &x)?;
563/// s.reduce_sum(&squared, Some(&[0]))
564/// })?;
565/// let gradients = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss))?;
566/// assert!(!gradients.is_empty());
567/// # Ok::<(), tenferro_ad::Error>(())
568/// ```
569#[derive(Debug)]
570pub struct Gradients {
571 group: AllocationGroup,
572 slots: HashMap<ValueKey<StdTensorOp>, DescriptorSlot>,
573}
574
575impl Gradients {
576 fn from_tensors(tensors: HashMap<ValueKey<StdTensorOp>, Tensor>) -> Result<Self> {
577 if tensors.is_empty() {
578 return Err(Error::runtime_state(
579 "backward",
580 ErrorPhase::Execution,
581 "no gradients were produced for reachable tracked leaves; use EagerSession::grad_optional or EagerSession::vjp_optional to observe inactive differentiation",
582 ));
583 }
584 let (keys, values): (Vec<_>, Vec<_>) = tensors.into_iter().unzip();
585 let (group, bindings) = AllocationGroup::from_tensors(values).map_err(|error| {
586 Error::runtime_state_source("Gradients::from_tensors", ErrorPhase::Execution, error)
587 })?;
588 let slots = keys.into_iter().zip(bindings).collect();
589 Ok(Self { group, slots })
590 }
591
592 /// Return the number of retained gradient descriptors.
593 pub fn len(&self) -> usize {
594 self.slots.len()
595 }
596
597 /// Return whether no gradient was produced.
598 pub fn is_empty(&self) -> bool {
599 self.slots.is_empty()
600 }
601
602 /// Borrow one gradient view by its local value key.
603 pub fn grad(&self, key: &ValueKey<StdTensorOp>) -> Option<TensorView<'_>> {
604 let slot = self.slots.get(key).copied()?;
605 let mut reads = self.group.read_views(std::slice::from_ref(&slot)).ok()?;
606 match reads.pop()? {
607 TensorRead::View(view) => Some(view),
608 TensorRead::Tensor(_) => None,
609 }
610 }
611
612 /// Consume one gradient owner while leaving the bundle unchanged on failure.
613 ///
614 /// # Errors
615 ///
616 /// Returns [`tenferro_tensor::Error::RuntimeState`] when the descriptor is
617 /// invalid or its allocation is aliased. A missing key is reported as
618 /// `Ok(None)`.
619 pub fn take_grad(
620 &mut self,
621 key: &ValueKey<StdTensorOp>,
622 ) -> tenferro_tensor::Result<Option<Tensor>> {
623 let Some(&slot) = self.slots.get(key) else {
624 return Ok(None);
625 };
626 let tensor = self.group.take_tensor(slot).map_err(|error| {
627 tenferro_tensor::Error::runtime_state_source("Gradients::take_grad", error)
628 })?;
629 self.slots.remove(key);
630 Ok(Some(tensor))
631 }
632}
633
634/// Error returned when a value cannot be consumed without changing its owner.
635///
636/// # Examples
637///
638/// ```
639/// use tenferro_ad::{EagerRuntime, EagerTensor, IntoValueError, Tensor};
640///
641/// let ctx = EagerRuntime::new()?;
642/// let value = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
643/// let _shared = value.clone();
644/// assert!(matches!(
645/// value.into_value(),
646/// Err(IntoValueError::NotUnique(_))
647/// ));
648/// # Ok::<(), tenferro_ad::Error>(())
649/// ```
650#[derive(Debug)]
651pub enum IntoValueError<H> {
652 /// Another eager handle, tape record, or checkpoint retains the value.
653 NotUnique(H),
654 /// Group extraction failed after the handle was uniquely acquired.
655 Extract { value: H, error: GroupError },
656}
657
658impl<H> std::fmt::Display for IntoValueError<H> {
659 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
660 match self {
661 Self::NotUnique(_) => formatter.write_str("eager value is retained by another handle"),
662 Self::Extract { error, .. } => {
663 write!(formatter, "eager value extraction failed: {error}")
664 }
665 }
666 }
667}
668
669impl<H: std::fmt::Debug + Send + Sync + 'static> std::error::Error for IntoValueError<H> {}
670
671/// What one direct retention container holds.
672// The pooled variant owns an allocation group inline; boxing it would add an
673// allocation to every retained value on the hot path.
674#[allow(clippy::large_enum_variant)]
675#[derive(Debug)]
676enum RetentionContainer {
677 /// Pooled storage owned through an allocation group and one descriptor slot.
678 Pooled {
679 group: AllocationGroup,
680 slot: DescriptorSlot,
681 },
682 /// A caller-owned value the runtime retains without taking pool ownership.
683 ///
684 /// The value returns to its owner when the record drops, and the runtime never
685 /// substitutes it for pooled storage. A caller-owned payload has no typed
686 /// descriptor view, so only its read and consume paths are available.
687 CallerOwned {
688 /// Boxed because a tensor value is much larger than the pooled variant.
689 tensor: Box<Tensor>,
690 },
691 /// An untracked result held directly.
692 ///
693 /// No AD group, residual or gradient will share it, so it needs no
694 /// allocation group: the tensor's own storage returns to its pool when the
695 /// record drops, and a unique handle hands the tensor back unchanged.
696 Owned { tensor: Tensor },
697}
698
699/// Read-only descriptor record used by eager handles and the AD registries.
700#[derive(Debug)]
701pub(crate) struct AdValueRecord {
702 container: Arc<RetentionContainer>,
703 dtype: DType,
704 shape: Box<[usize]>,
705}
706
707impl AdValueRecord {
708 fn from_group(
709 group: AllocationGroup,
710 slot: DescriptorSlot,
711 dtype: DType,
712 shape: Vec<usize>,
713 ) -> Arc<Self> {
714 Arc::new(Self {
715 container: Arc::new(RetentionContainer::Pooled { group, slot }),
716 dtype,
717 shape: shape.into_boxed_slice(),
718 })
719 }
720
721 fn from_tensor(tensor: Tensor, op: &'static str) -> Result<Arc<Self>> {
722 let dtype = tensor.dtype();
723 let shape = tensor.shape().to_vec();
724 if matches!(dtype, DType::External(_)) {
725 // A caller-owned payload is retained directly: it owns no pooled
726 // storage, so there is no group to build and nothing to return to a
727 // pool when the record drops.
728 return Ok(Arc::new(Self {
729 container: Arc::new(RetentionContainer::CallerOwned {
730 tensor: Box::new(tensor),
731 }),
732 dtype,
733 shape: shape.into_boxed_slice(),
734 }));
735 }
736 let (group, bindings) = AllocationGroup::from_tensors(vec![tensor])
737 .map_err(|error| Error::runtime_state_source(op, ErrorPhase::Execution, error))?;
738 let slot = bindings.first().copied().ok_or_else(|| {
739 Error::runtime_state(op, ErrorPhase::Execution, "empty allocation-group binding")
740 })?;
741 Ok(Self::from_group(group, slot, dtype, shape))
742 }
743
744 /// Retain an untracked result without building an allocation group.
745 fn from_untracked_tensor(tensor: Tensor, op: &'static str) -> Result<Arc<Self>> {
746 if matches!(tensor.dtype(), DType::External(_)) {
747 return Self::from_tensor(tensor, op);
748 }
749 let dtype = tensor.dtype();
750 let shape = tensor.shape().to_vec().into_boxed_slice();
751 Ok(Arc::new(Self {
752 container: Arc::new(RetentionContainer::Owned { tensor }),
753 dtype,
754 shape,
755 }))
756 }
757
758 fn tensor_read(&self, op: &'static str) -> Result<TensorRead<'_>> {
759 match self.container.as_ref() {
760 RetentionContainer::Pooled { group, slot } => group.read_view(*slot).map_err(|error| {
761 // One slot, so no `Vec` and no empty-result case: the single-slot
762 // accessor is the whole request (#2079).
763 Error::runtime_state_source(op, ErrorPhase::Execution, error)
764 }),
765 RetentionContainer::CallerOwned { tensor } => Ok(TensorRead::from_tensor(tensor)),
766 RetentionContainer::Owned { tensor } => Ok(TensorRead::from_tensor(tensor)),
767 }
768 }
769
770 fn value(&self, op: &'static str) -> Result<ValueGuard<'_>> {
771 if let RetentionContainer::Owned { tensor } = self.container.as_ref() {
772 // `from_untracked_tensor` routes a caller-owned payload away from
773 // `Owned`, so this has a preset view; a missing one is reported, not
774 // asserted.
775 let view = TensorRead::from_tensor(tensor)
776 .tensor_view()
777 .ok_or_else(|| {
778 Error::runtime_state(
779 op,
780 ErrorPhase::Execution,
781 "an owned caller-owned payload has no typed borrowed view",
782 )
783 })?;
784 return Ok(ValueGuard { view });
785 }
786 match self.tensor_read(op)? {
787 TensorRead::View(view) => Ok(ValueGuard { view }),
788 // A caller-owned payload has no typed descriptor view, so a path that
789 // needs one fails explicitly instead of borrowing the payload as bytes.
790 TensorRead::Tensor(_) => Err(Error::runtime_state(
791 op,
792 ErrorPhase::Execution,
793 "allocation-group value did not produce a borrowed descriptor view",
794 )),
795 }
796 }
797
798 fn dtype(&self) -> DType {
799 self.dtype
800 }
801
802 fn shape(&self) -> &[usize] {
803 &self.shape
804 }
805}
806
807/// Shared eager execution context for tensors on a backend.
808///
809/// Reusing one context lets eager tensors share backend state, extension
810/// runtime caches, and gradient storage across a computation.
811///
812/// # Examples
813///
814/// ```
815/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
816///
817/// let ctx = EagerRuntime::new()?;
818/// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
819/// let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap()).unwrap();
820/// let z = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.add(&x, &y)).unwrap();
821///
822/// assert_eq!(z.value().unwrap().as_slice::<f64>().unwrap(), &[3.0]);
823/// # Ok::<(), tenferro_ad::Error>(())
824/// ```
825pub struct EagerRuntime {
826 id: ContextId,
827 /// Prepared-program runtime. Engine kinds are registered on first use;
828 /// the runtime never stores an engine.
829 runtime: Runtime,
830 /// Serializes runtime reconfiguration (engine-kind registration and
831 /// extension-module installation).
832 extension_install_lock: Mutex<()>,
833 semantic_extension_rules: SemanticExtensionRuleSet,
834 grad_slots: Mutex<HashMap<ValueKey<StdTensorOp>, WeakGradSlot>>,
835 value_records: Mutex<HashMap<ValueKey<StdTensorOp>, Weak<EagerTensorRecord>>>,
836 ad_transform_cache: Arc<AdTransformCache>,
837 /// S2: prepared derivative programs keyed by semantic structure, wrt input,
838 /// and concrete bound input metadata. Avoids re-running freeze+AD
839 /// transform+compile_frozen on warm structure hits.
840 prepared_derivative_cache: Mutex<PreparedDerivativeCache>,
841 /// Test-only count of semantic replays performed for this runtime.
842 #[cfg(test)]
843 semantic_replays: AtomicUsize,
844}
845
846/// An eager runtime and its borrowed backend session for one execution boundary.
847///
848/// Obtain this only through [`EagerRuntime::with_eager_session`]. It rejects
849/// tensors from another eager runtime even if both runtimes use the same backend
850/// type, and it cannot escape the boundary closure.
851///
852/// # Examples
853///
854/// ```rust
855/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
856///
857/// let ctx = EagerRuntime::new()?;
858/// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
859/// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.neg(&x))?;
860/// assert_eq!(y.value()?.as_slice::<f64>()?, &[-3.0]);
861/// # Ok::<(), tenferro_ad::Error>(())
862/// ```
863///
864/// The borrowed session cannot escape its execution boundary:
865///
866/// ```compile_fail
867/// use tenferro_ad::EagerRuntime;
868/// let ctx = EagerRuntime::new().unwrap();
869/// let escaped = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session).unwrap();
870/// let _ = escaped;
871/// ```
872pub struct EagerSession<'a> {
873 runtime: &'a Arc<EagerRuntime>,
874 engine: &'a mut dyn ExecutionEngine,
875}
876
877impl fmt::Debug for EagerSession<'_> {
878 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
879 f.debug_struct("EagerSession")
880 .field("runtime_id", &self.runtime.id())
881 .finish_non_exhaustive()
882 }
883}
884
885impl EagerSession<'_> {
886 /// Negate an eager tensor inside the caller's execution boundary.
887 ///
888 /// # Examples
889 ///
890 /// ```rust
891 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
892 ///
893 /// let ctx = EagerRuntime::new()?;
894 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
895 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.neg(&x))?;
896 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-4.0]);
897 /// # Ok::<(), tenferro_ad::Error>(())
898 /// ```
899 ///
900 /// # Errors
901 ///
902 /// Returns [`Error::ContextMismatch`] for a tensor from another runtime,
903 /// or a typed eager/backend error from the selected operation.
904 pub fn neg(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
905 self.run_unary(input, StdTensorOp::Neg)
906 }
907
908 /// Compute the elementwise exponential inside this eager session.
909 ///
910 /// # Examples
911 ///
912 /// ```rust
913 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
914 /// let ctx = EagerRuntime::new()?;
915 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
916 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.exp(&x))?;
917 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0]);
918 /// # Ok::<(), tenferro_ad::Error>(())
919 /// ```
920 ///
921 /// # Errors
922 ///
923 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
924 /// unsupported/backend error for the input dtype.
925 pub fn exp(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
926 self.run_unary(input, StdTensorOp::Exp)
927 }
928
929 /// Compute the elementwise absolute value inside this eager session.
930 ///
931 /// # Examples
932 ///
933 /// ```rust
934 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
935 /// let ctx = EagerRuntime::new()?;
936 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![-2.0_f64])?)?;
937 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.abs(&x))?;
938 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
939 /// # Ok::<(), tenferro_ad::Error>(())
940 /// ```
941 ///
942 /// # Errors
943 ///
944 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
945 /// unsupported/backend error for the input dtype.
946 pub fn abs(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
947 self.run_unary(input, StdTensorOp::Abs)
948 }
949
950 /// Compute the elementwise conjugate inside this eager session.
951 ///
952 /// # Examples
953 ///
954 /// ```rust
955 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
956 /// let ctx = EagerRuntime::new()?;
957 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
958 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.conj(&x))?;
959 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
960 /// # Ok::<(), tenferro_ad::Error>(())
961 /// ```
962 ///
963 /// # Errors
964 ///
965 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
966 /// unsupported/backend error for the input dtype.
967 pub fn conj(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
968 self.run_unary(input, StdTensorOp::Conj)
969 }
970
971 /// Compute the elementwise sign on this borrowed session.
972 ///
973 /// # Examples
974 /// ```rust
975 /// use tenferro_ad::{EagerRuntime, Tensor};
976 /// let ctx = EagerRuntime::new()?;
977 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
978 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![-2.0_f64])?)?;
979 /// s.sign(&x)
980 /// })?;
981 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-1.0]);
982 /// # Ok::<(), tenferro_ad::Error>(())
983 /// ```
984 /// # Errors
985 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
986 pub fn sign(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
987 self.run_unary(input, StdTensorOp::Sign)
988 }
989
990 /// Compute the elementwise natural logarithm on this borrowed session.
991 ///
992 /// # Examples
993 /// ```rust
994 /// use tenferro_ad::{EagerRuntime, Tensor};
995 /// let ctx = EagerRuntime::new()?;
996 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
997 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
998 /// s.log(&x)
999 /// })?;
1000 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1001 /// # Ok::<(), tenferro_ad::Error>(())
1002 /// ```
1003 /// # Errors
1004 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1005 pub fn log(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1006 self.run_unary(input, StdTensorOp::Log)
1007 }
1008
1009 /// Compute the elementwise square root on this borrowed session.
1010 ///
1011 /// # Examples
1012 /// ```rust
1013 /// use tenferro_ad::{EagerRuntime, Tensor};
1014 /// let ctx = EagerRuntime::new()?;
1015 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1016 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
1017 /// s.sqrt(&x)
1018 /// })?;
1019 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
1020 /// # Ok::<(), tenferro_ad::Error>(())
1021 /// ```
1022 /// # Errors
1023 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1024 pub fn sqrt(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1025 self.run_unary(input, StdTensorOp::Sqrt)
1026 }
1027
1028 /// Compute the elementwise reciprocal square root on this borrowed session.
1029 ///
1030 /// # Examples
1031 /// ```rust
1032 /// use tenferro_ad::{EagerRuntime, Tensor};
1033 /// let ctx = EagerRuntime::new()?;
1034 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1035 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
1036 /// s.rsqrt(&x)
1037 /// })?;
1038 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.5]);
1039 /// # Ok::<(), tenferro_ad::Error>(())
1040 /// ```
1041 /// # Errors
1042 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1043 pub fn rsqrt(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1044 self.run_unary(input, StdTensorOp::Rsqrt)
1045 }
1046
1047 /// Compute the elementwise sine on this borrowed session.
1048 ///
1049 /// # Examples
1050 /// ```rust
1051 /// use tenferro_ad::{EagerRuntime, Tensor};
1052 /// let ctx = EagerRuntime::new()?;
1053 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1054 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1055 /// s.sin(&x)
1056 /// })?;
1057 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1058 /// # Ok::<(), tenferro_ad::Error>(())
1059 /// ```
1060 /// # Errors
1061 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1062 pub fn sin(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1063 self.run_unary(input, StdTensorOp::Sin)
1064 }
1065
1066 /// Compute the elementwise cosine on this borrowed session.
1067 ///
1068 /// # Examples
1069 /// ```rust
1070 /// use tenferro_ad::{EagerRuntime, Tensor};
1071 /// let ctx = EagerRuntime::new()?;
1072 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1073 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1074 /// s.cos(&x)
1075 /// })?;
1076 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0]);
1077 /// # Ok::<(), tenferro_ad::Error>(())
1078 /// ```
1079 /// # Errors
1080 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1081 pub fn cos(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1082 self.run_unary(input, StdTensorOp::Cos)
1083 }
1084
1085 /// Compute the elementwise hyperbolic tangent on this borrowed session.
1086 ///
1087 /// # Examples
1088 /// ```rust
1089 /// use tenferro_ad::{EagerRuntime, Tensor};
1090 /// let ctx = EagerRuntime::new()?;
1091 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1092 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1093 /// s.tanh(&x)
1094 /// })?;
1095 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1096 /// # Ok::<(), tenferro_ad::Error>(())
1097 /// ```
1098 /// # Errors
1099 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1100 pub fn tanh(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1101 self.run_unary(input, StdTensorOp::Tanh)
1102 }
1103
1104 /// Compute `exp(x) - 1` elementwise on this borrowed session.
1105 ///
1106 /// # Examples
1107 /// ```rust
1108 /// use tenferro_ad::{EagerRuntime, Tensor};
1109 /// let ctx = EagerRuntime::new()?;
1110 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1111 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1112 /// s.expm1(&x)
1113 /// })?;
1114 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1115 /// # Ok::<(), tenferro_ad::Error>(())
1116 /// ```
1117 /// # Errors
1118 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1119 pub fn expm1(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1120 self.run_unary(input, StdTensorOp::Expm1)
1121 }
1122
1123 /// Compute `log(1 + x)` elementwise on this borrowed session.
1124 ///
1125 /// # Examples
1126 /// ```rust
1127 /// use tenferro_ad::{EagerRuntime, Tensor};
1128 /// let ctx = EagerRuntime::new()?;
1129 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1130 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?)?;
1131 /// s.log1p(&x)
1132 /// })?;
1133 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
1134 /// # Ok::<(), tenferro_ad::Error>(())
1135 /// ```
1136 /// # Errors
1137 /// Returns a typed foreign-runtime, unsupported-dtype, or backend error.
1138 pub fn log1p(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1139 self.run_unary(input, StdTensorOp::Log1p)
1140 }
1141
1142 /// Compute the error function `erf(x)` elementwise on this borrowed session.
1143 ///
1144 /// Defined for real `F32`/`F64` tensors; `erf(+-0) = +-0`,
1145 /// `erf(+-inf) = +-1`, and `NaN` stays `NaN`. The derivative is
1146 /// `2/sqrt(pi) * exp(-x^2)`.
1147 ///
1148 /// # Examples
1149 /// ```rust
1150 /// use tenferro_ad::{EagerRuntime, Tensor};
1151 /// let ctx = EagerRuntime::new()?;
1152 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1153 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![0.0_f64, 1.0])?)?;
1154 /// s.erf(&x)
1155 /// })?;
1156 /// let y = y.value()?;
1157 /// let y = y.as_slice::<f64>()?;
1158 /// assert_eq!(y[0], 0.0);
1159 /// assert!((y[1] - 0.842_700_792_949_714_9).abs() < 1.0e-15);
1160 /// # Ok::<(), tenferro_ad::Error>(())
1161 /// ```
1162 /// # Errors
1163 /// Returns a typed foreign-runtime error, a typed unsupported-dtype error
1164 /// for complex, integer, or `Bool` input, or a backend error.
1165 pub fn erf(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1166 self.run_unary(input, StdTensorOp::Erf)
1167 }
1168
1169 /// Convert a tensor under the checked dtype-promotion lattice.
1170 /// Use [`Self::cast`] for intentional lossy projection.
1171 ///
1172 /// # Examples
1173 ///
1174 /// ```rust
1175 /// use tenferro_ad::{DType, EagerRuntime, Tensor};
1176 /// let ctx = EagerRuntime::new()?;
1177 /// let converted = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1178 /// let x = session.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
1179 /// session.convert(&x, DType::C64)
1180 /// })?;
1181 /// assert_eq!(converted.dtype(), DType::C64);
1182 /// # Ok::<(), tenferro_ad::Error>(())
1183 /// ```
1184 ///
1185 /// # Errors
1186 ///
1187 /// Returns [`Error::ContextMismatch`] for a foreign runtime or a typed
1188 /// unsupported dtype conversion/backend error.
1189 pub fn convert(&mut self, input: &EagerTensor, to: DType) -> Result<EagerTensor> {
1190 self.ensure_runtime(input)?;
1191 tenferro_tensor::validate::validate_convert_dtype(
1192 "EagerTensor::convert",
1193 input.dtype(),
1194 to,
1195 )
1196 .map_err(Error::TensorRuntime)?;
1197 self.cast(input, to)
1198 }
1199
1200 /// Cast a tensor to a dtype, permitting explicitly lossy projections.
1201 ///
1202 /// # Examples
1203 ///
1204 /// ```rust
1205 /// use tenferro_ad::{DType, EagerRuntime, Tensor};
1206 /// let ctx = EagerRuntime::new()?;
1207 /// let casted = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1208 /// let x = session.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.8_f64])?)?;
1209 /// session.cast(&x, DType::I32)
1210 /// })?;
1211 /// assert_eq!(casted.value()?.as_slice::<i32>()?, &[2]);
1212 /// # Ok::<(), tenferro_ad::Error>(())
1213 /// ```
1214 ///
1215 /// # Errors
1216 ///
1217 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1218 /// unsupported projection/backend error.
1219 pub fn cast(&mut self, input: &EagerTensor, to: DType) -> Result<EagerTensor> {
1220 self.run_unary(
1221 input,
1222 StdTensorOp::Convert {
1223 from: input.dtype(),
1224 to,
1225 },
1226 )
1227 }
1228
1229 /// Permute the axes of an eager tensor while preserving independent ownership.
1230 ///
1231 /// # Examples
1232 ///
1233 /// ```rust
1234 /// use tenferro_ad::{EagerRuntime, Tensor};
1235 /// let ctx = EagerRuntime::new()?;
1236 /// let copied = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1237 /// let x = session.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1238 /// let y = session.transpose(&x, &[1, 0])?;
1239 /// session.duplicate_value(&y)
1240 /// })?;
1241 /// assert_eq!(copied.as_slice::<f64>()?, &[1.0, 3.0, 2.0, 4.0]);
1242 /// # Ok::<(), tenferro_ad::Error>(())
1243 /// ```
1244 ///
1245 /// # Errors
1246 ///
1247 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1248 /// axis/backend error for an invalid permutation or copy.
1249 pub fn transpose(&mut self, input: &EagerTensor, perm: &[isize]) -> Result<EagerTensor> {
1250 self.ensure_runtime(input)?;
1251 let perm = &crate::shape_packing::normalize_existing_axes(
1252 "EagerSession::transpose",
1253 perm,
1254 input.shape().len(),
1255 )?[..];
1256 input.transpose_in_session(perm, &mut *self.engine)
1257 }
1258
1259 /// Reshape an eager tensor while retaining a separate result owner.
1260 ///
1261 /// # Examples
1262 ///
1263 /// ```rust
1264 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1265 /// let ctx = EagerRuntime::new()?;
1266 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1267 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.reshape(&x, [1, 2]))?;
1268 /// assert_eq!(y.shape(), &[1, 2]);
1269 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0, 2.0]);
1270 /// # Ok::<(), tenferro_ad::Error>(())
1271 /// ```
1272 ///
1273 /// # Errors
1274 ///
1275 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1276 /// validation/backend error when the target shape is incompatible.
1277 pub fn reshape(
1278 &mut self,
1279 input: &EagerTensor,
1280 shape: impl IntoShapeVec,
1281 ) -> Result<EagerTensor> {
1282 self.ensure_runtime(input)?;
1283 input.reshape_in_session(&shape.into_shape_vec(), &mut *self.engine)
1284 }
1285
1286 /// Slice an eager tensor with explicit start, limit, and stride per axis.
1287 ///
1288 /// # Examples
1289 ///
1290 /// ```rust
1291 /// use tenferro_ad::{EagerRuntime, SliceConfig, Tensor};
1292 /// let ctx = EagerRuntime::new()?;
1293 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1294 /// let x = session.constant_from(Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1295 /// session.slice(&x, SliceConfig { starts: vec![1], limits: vec![3], strides: vec![1] })
1296 /// })?;
1297 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0, 3.0]);
1298 /// # Ok::<(), tenferro_ad::Error>(())
1299 /// ```
1300 ///
1301 /// # Errors
1302 ///
1303 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1304 /// axis/stride/backend error for an invalid slice or copy.
1305 pub fn slice(&mut self, input: &EagerTensor, config: SliceConfig) -> Result<EagerTensor> {
1306 self.ensure_runtime(input)?;
1307 input.slice_in_session(config, &mut *self.engine)
1308 }
1309
1310 /// Broadcast an eager tensor into a larger shape on this session.
1311 ///
1312 /// # Examples
1313 ///
1314 /// ```rust
1315 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1316 /// let ctx = EagerRuntime::new()?;
1317 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1318 /// let copy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1319 /// let y = session.broadcast_in_dim(&x, &[2, 2], &[0])?;
1320 /// session.duplicate_value(&y)
1321 /// })?;
1322 /// assert_eq!(copy.as_slice::<f64>()?, &[1.0, 2.0, 1.0, 2.0]);
1323 /// # Ok::<(), tenferro_ad::Error>(())
1324 /// ```
1325 ///
1326 /// # Errors
1327 ///
1328 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1329 /// validation/backend error for an invalid broadcast mapping.
1330 pub fn broadcast_in_dim(
1331 &mut self,
1332 input: &EagerTensor,
1333 shape: &[usize],
1334 dims: &[usize],
1335 ) -> Result<EagerTensor> {
1336 self.ensure_runtime(input)?;
1337 input.broadcast_in_dim_in_session(shape, dims, &mut *self.engine)
1338 }
1339
1340 /// Keep the lower triangle of a matrix on this borrowed session.
1341 ///
1342 /// # Examples
1343 /// ```rust
1344 /// use tenferro_ad::{EagerRuntime, Tensor};
1345 /// let ctx = EagerRuntime::new()?;
1346 /// let lower = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1347 /// let matrix = s.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1348 /// s.tril(&matrix, 0)
1349 /// })?;
1350 /// assert_eq!(lower.value()?.as_slice::<f64>()?, &[1.0, 2.0, 0.0, 4.0]);
1351 /// # Ok::<(), tenferro_ad::Error>(())
1352 /// ```
1353 /// # Errors
1354 /// Returns a typed foreign-runtime, rank, unsupported-dtype, or backend error.
1355 pub fn tril(&mut self, input: &EagerTensor, k: i64) -> Result<EagerTensor> {
1356 self.run_unary(input, StdTensorOp::Tril { k })
1357 }
1358
1359 /// Keep the upper triangle of a matrix on this borrowed session.
1360 ///
1361 /// # Examples
1362 /// ```rust
1363 /// use tenferro_ad::{EagerRuntime, Tensor};
1364 /// let ctx = EagerRuntime::new()?;
1365 /// let upper = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1366 /// let matrix = s.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1367 /// s.triu(&matrix, 0)
1368 /// })?;
1369 /// assert_eq!(upper.value()?.as_slice::<f64>()?, &[1.0, 0.0, 3.0, 4.0]);
1370 /// # Ok::<(), tenferro_ad::Error>(())
1371 /// ```
1372 /// # Errors
1373 /// Returns a typed foreign-runtime, rank, unsupported-dtype, or backend error.
1374 pub fn triu(&mut self, input: &EagerTensor, k: i64) -> Result<EagerTensor> {
1375 self.run_unary(input, StdTensorOp::Triu { k })
1376 }
1377
1378 /// Pad an eager tensor with zeros on this borrowed session.
1379 ///
1380 /// # Examples
1381 /// ```rust
1382 /// use tenferro_ad::{EagerRuntime, PadConfig, Tensor};
1383 /// let ctx = EagerRuntime::new()?;
1384 /// let padded = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1385 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1386 /// s.pad(&x, PadConfig {
1387 /// edge_padding_low: vec![1],
1388 /// edge_padding_high: vec![1],
1389 /// interior_padding: vec![1],
1390 /// })
1391 /// })?;
1392 /// assert_eq!(padded.value()?.as_slice::<f64>()?, &[0.0, 1.0, 0.0, 2.0, 0.0]);
1393 /// # Ok::<(), tenferro_ad::Error>(())
1394 /// ```
1395 /// # Errors
1396 /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
1397 /// runtime, a validation error with
1398 /// `ValidationError::InvalidArgument` for a padding configuration whose
1399 /// length or extents do not match the input rank, or
1400 /// [`Error::TensorRuntime`] for a typed backend failure.
1401 pub fn pad(&mut self, input: &EagerTensor, config: PadConfig) -> Result<EagerTensor> {
1402 self.run_unary(input, StdTensorOp::Pad(config))
1403 }
1404
1405 /// Reverse the elements along selected axes on this borrowed session.
1406 ///
1407 /// # Examples
1408 /// ```rust
1409 /// use tenferro_ad::{EagerRuntime, Tensor};
1410 /// let ctx = EagerRuntime::new()?;
1411 /// let reversed = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1412 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?)?;
1413 /// s.reverse(&x, &[0])
1414 /// })?;
1415 /// assert_eq!(reversed.value()?.as_slice::<f64>()?, &[3.0, 2.0, 1.0]);
1416 /// # Ok::<(), tenferro_ad::Error>(())
1417 /// ```
1418 /// # Errors
1419 /// Returns a typed foreign-runtime, invalid-axis, or backend error.
1420 pub fn reverse(&mut self, input: &EagerTensor, axes: &[isize]) -> Result<EagerTensor> {
1421 self.ensure_runtime(input)?;
1422 let axes = &crate::shape_packing::normalize_existing_axes(
1423 "EagerSession::reverse",
1424 axes,
1425 input.shape().len(),
1426 )?[..];
1427 crate::eager_ops::validate_eager_axes("EagerSession::reverse", input.shape().len(), axes)?;
1428 self.run_unary(
1429 input,
1430 StdTensorOp::Reverse {
1431 axes: axes.to_vec(),
1432 },
1433 )
1434 }
1435
1436 /// Slice an eager tensor using runtime start indices in this borrowed session.
1437 ///
1438 /// # Examples
1439 /// ```rust
1440 /// use tenferro_ad::{EagerRuntime, Tensor};
1441 /// let ctx = EagerRuntime::new()?;
1442 /// let selected = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1443 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1444 /// let starts = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![1_i64])?)?;
1445 /// s.dynamic_slice(&x, &starts, &[2])
1446 /// })?;
1447 /// assert_eq!(selected.value()?.as_slice::<f64>()?, &[2.0, 3.0]);
1448 /// # Ok::<(), tenferro_ad::Error>(())
1449 /// ```
1450 /// # Errors
1451 /// Returns a typed foreign-runtime, invalid-index or slice-shape, or backend error.
1452 pub fn dynamic_slice(
1453 &mut self,
1454 input: &EagerTensor,
1455 starts: &EagerTensor,
1456 sizes: &[usize],
1457 ) -> Result<EagerTensor> {
1458 self.ensure_runtime(input)?;
1459 self.ensure_runtime(starts)?;
1460 EagerTensor::nary_op_in_session(
1461 &[input, starts],
1462 StdTensorOp::DynamicSlice {
1463 slice_sizes: sizes.to_vec(),
1464 },
1465 &mut *self.engine,
1466 )
1467 }
1468
1469 /// Gather elements of an eager tensor in this borrowed session.
1470 ///
1471 /// # Examples
1472 /// ```rust
1473 /// use tenferro_ad::{EagerRuntime, GatherConfig, Tensor};
1474 /// let ctx = EagerRuntime::new()?;
1475 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1476 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![3], vec![10.0_f64, 20.0, 30.0])?)?;
1477 /// let indices = s.constant_from(Tensor::from_vec_col_major(vec![2, 1], vec![2_i64, 0])?)?;
1478 /// s.gather(&x, &indices, GatherConfig {
1479 /// offset_dims: vec![], collapsed_slice_dims: vec![0],
1480 /// start_index_map: vec![0], index_vector_dim: 1,
1481 /// slice_sizes: vec![1],
1482 /// })
1483 /// })?;
1484 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[30.0, 10.0]);
1485 /// # Ok::<(), tenferro_ad::Error>(())
1486 /// ```
1487 /// # Errors
1488 /// Returns a typed foreign-runtime, invalid-index/configuration, or backend error.
1489 pub fn gather(
1490 &mut self,
1491 input: &EagerTensor,
1492 indices: &EagerTensor,
1493 config: GatherConfig,
1494 ) -> Result<EagerTensor> {
1495 self.ensure_runtime(input)?;
1496 self.ensure_runtime(indices)?;
1497 EagerTensor::nary_op_in_session(
1498 &[input, indices],
1499 StdTensorOp::Gather(config),
1500 &mut *self.engine,
1501 )
1502 }
1503
1504 /// Concatenate eager tensors along one axis in this borrowed session.
1505 ///
1506 /// # Examples
1507 /// ```rust
1508 /// use tenferro_ad::{EagerRuntime, Tensor};
1509 /// let ctx = EagerRuntime::new()?;
1510 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1511 /// let a = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
1512 /// let b = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
1513 /// s.concatenate(&[&a, &b], 0)
1514 /// })?;
1515 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[1.0, 2.0]);
1516 /// # Ok::<(), tenferro_ad::Error>(())
1517 /// ```
1518 /// # Errors
1519 /// Returns a typed empty-input, foreign-runtime, invalid-axis/shape, or backend error.
1520 pub fn concatenate(&mut self, inputs: &[&EagerTensor], axis: isize) -> Result<EagerTensor> {
1521 for input in inputs {
1522 self.ensure_runtime(input)?;
1523 }
1524 // An empty list is reported by the operation itself (as before #2552);
1525 // only a non-empty list has a rank to normalize the axis against.
1526 let axis = match inputs.first() {
1527 Some(first) => crate::shape_packing::normalize_existing_axis(
1528 "EagerSession::concatenate",
1529 axis,
1530 first.shape().len(),
1531 )?,
1532 None => 0,
1533 };
1534 EagerTensor::nary_op_in_session(
1535 inputs,
1536 StdTensorOp::Concatenate {
1537 axis,
1538 input_count: inputs.len(),
1539 },
1540 &mut *self.engine,
1541 )
1542 }
1543
1544 /// Scatter updates into an eager tensor within this borrowed session.
1545 ///
1546 /// # Examples
1547 /// ```rust
1548 /// use tenferro_ad::{EagerRuntime, ScatterConfig, Tensor};
1549 /// let ctx = EagerRuntime::new()?;
1550 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1551 /// let input = s.constant_from(Tensor::from_vec_col_major(vec![4], vec![0.0_f64; 4])?)?;
1552 /// let indices = s.constant_from(Tensor::from_vec_col_major(vec![2, 1], vec![1_i64, 3])?)?;
1553 /// let updates = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![5.0_f64, 7.0])?)?;
1554 /// s.scatter(&input, &indices, &updates, ScatterConfig {
1555 /// update_window_dims: vec![],
1556 /// inserted_window_dims: vec![0],
1557 /// scatter_dims_to_operand_dims: vec![0],
1558 /// index_vector_dim: 1,
1559 /// })
1560 /// })?;
1561 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[0.0, 5.0, 0.0, 7.0]);
1562 /// # Ok::<(), tenferro_ad::Error>(())
1563 /// ```
1564 /// # Errors
1565 /// Returns a typed foreign-runtime, invalid-index/configuration, or backend error.
1566 pub fn scatter(
1567 &mut self,
1568 input: &EagerTensor,
1569 indices: &EagerTensor,
1570 updates: &EagerTensor,
1571 config: ScatterConfig,
1572 ) -> Result<EagerTensor> {
1573 self.ensure_runtime(input)?;
1574 self.ensure_runtime(indices)?;
1575 self.ensure_runtime(updates)?;
1576 EagerTensor::nary_op_in_session(
1577 &[input, indices, updates],
1578 StdTensorOp::Scatter(config),
1579 &mut *self.engine,
1580 )
1581 }
1582
1583 /// Extract a diagonal along two axes in this borrowed session.
1584 ///
1585 /// # Examples
1586 /// ```rust
1587 /// use tenferro_ad::{EagerRuntime, Tensor};
1588 /// let ctx = EagerRuntime::new()?;
1589 /// let diagonal = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1590 /// let matrix = s.constant_from(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
1591 /// s.extract_diag(&matrix, 0, 1)
1592 /// })?;
1593 /// assert_eq!(diagonal.value()?.as_slice::<f64>()?, &[1.0, 4.0]);
1594 /// # Ok::<(), tenferro_ad::Error>(())
1595 /// ```
1596 /// # Errors
1597 /// Returns a typed foreign-runtime, invalid-axis, or backend error.
1598 pub fn extract_diag(
1599 &mut self,
1600 input: &EagerTensor,
1601 axis_a: isize,
1602 axis_b: isize,
1603 ) -> Result<EagerTensor> {
1604 self.ensure_runtime(input)?;
1605 let rank = input.shape().len();
1606 let axis_a = crate::shape_packing::normalize_existing_axis(
1607 "EagerSession::extract_diag",
1608 axis_a,
1609 rank,
1610 )?;
1611 let axis_b = crate::shape_packing::normalize_existing_axis(
1612 "EagerSession::extract_diag",
1613 axis_b,
1614 rank,
1615 )?;
1616 self.run_unary(input, StdTensorOp::ExtractDiag { axis_a, axis_b })
1617 }
1618
1619 /// Embed the input along a diagonal in this borrowed session.
1620 ///
1621 /// # Examples
1622 /// ```rust
1623 /// use tenferro_ad::{EagerRuntime, Tensor};
1624 /// let ctx = EagerRuntime::new()?;
1625 /// let matrix = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1626 /// let diagonal = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1627 /// s.embed_diag(&diagonal, 0, 1)
1628 /// })?;
1629 /// assert_eq!(matrix.value()?.as_slice::<f64>()?, &[1.0, 0.0, 0.0, 2.0]);
1630 /// # Ok::<(), tenferro_ad::Error>(())
1631 /// ```
1632 /// # Errors
1633 /// Returns a typed foreign-runtime, invalid-axis, or backend error.
1634 pub fn embed_diag(
1635 &mut self,
1636 input: &EagerTensor,
1637 axis_a: isize,
1638 axis_b: isize,
1639 ) -> Result<EagerTensor> {
1640 self.ensure_runtime(input)?;
1641 let rank = input.shape().len();
1642 let axis_a = crate::shape_packing::normalize_existing_axis(
1643 "EagerSession::embed_diag",
1644 axis_a,
1645 rank,
1646 )?;
1647 let axis_b =
1648 crate::shape_packing::normalize_insert_axis("EagerSession::embed_diag", axis_b, rank)?;
1649 self.run_unary(input, StdTensorOp::EmbedDiag { axis_a, axis_b })
1650 }
1651
1652 /// Reduce an eager tensor over selected axes within this borrowed session.
1653 /// `None` reduces all axes, while `Some(&[])` retains the input shape.
1654 ///
1655 /// # Examples
1656 ///
1657 /// ```rust
1658 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1659 /// let ctx = EagerRuntime::new()?;
1660 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1661 /// let sum = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.reduce_sum(&x, None))?;
1662 /// assert_eq!(sum.value()?.as_slice::<f64>()?, &[3.0]);
1663 /// # Ok::<(), tenferro_ad::Error>(())
1664 /// ```
1665 ///
1666 /// # Errors
1667 ///
1668 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1669 /// validation/backend error for invalid axes or unsupported dtypes.
1670 pub fn reduce_sum(
1671 &mut self,
1672 input: &EagerTensor,
1673 axes: Option<&[isize]>,
1674 ) -> Result<EagerTensor> {
1675 self.ensure_runtime(input)?;
1676 let axes = axes
1677 .map(|axes| {
1678 crate::shape_packing::normalize_existing_axes(
1679 "EagerTensor::reduce_sum",
1680 axes,
1681 input.shape().len(),
1682 )
1683 })
1684 .transpose()?;
1685 input.reduce_sum_in_session(axes.as_deref(), &mut *self.engine)
1686 }
1687
1688 /// Sum elementwise squares over the selected axes in this borrowed session.
1689 /// Only `f32` and `f64` are supported. `None` reduces every axis, like the
1690 /// rest of the reduction family; `Some(&[])` squares each value.
1691 ///
1692 /// # Examples
1693 /// ```rust
1694 /// use tenferro_ad::{EagerRuntime, Tensor};
1695 /// let ctx = EagerRuntime::new()?;
1696 /// let (sum, all) = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1697 /// let input = s.constant_from(Tensor::from_vec_col_major([2], vec![3.0_f64, 4.0])?)?;
1698 /// Ok::<_, tenferro_ad::Error>((
1699 /// s.reduce_sum_squares(&input, Some(&[0]))?,
1700 /// s.reduce_sum_squares(&input, None)?,
1701 /// ))
1702 /// })?;
1703 /// assert_eq!(sum.value()?.as_slice::<f64>()?, &[25.0]);
1704 /// assert_eq!(all.value()?.as_slice::<f64>()?, &[25.0]);
1705 /// # Ok::<(), tenferro_ad::Error>(())
1706 /// ```
1707 /// # Errors
1708 /// Returns typed foreign-runtime, invalid-axis, unsupported-dtype, or backend errors.
1709 pub fn reduce_sum_squares(
1710 &mut self,
1711 input: &EagerTensor,
1712 axes: Option<&[isize]>,
1713 ) -> Result<EagerTensor> {
1714 self.ensure_runtime(input)?;
1715 let axes = match axes {
1716 Some(axes) => crate::shape_packing::normalize_existing_axes(
1717 "EagerSession::reduce_sum_squares",
1718 axes,
1719 input.shape().len(),
1720 )?,
1721 None => (0..input.shape().len()).collect(),
1722 };
1723 crate::eager_ops::validate_eager_axes(
1724 "EagerSession::reduce_sum_squares",
1725 input.shape().len(),
1726 &axes,
1727 )?;
1728 self.run_unary(input, StdTensorOp::ReduceSumSquares { axes })
1729 }
1730
1731 /// Reduce the product of selected axes in this borrowed session.
1732 /// `None` reduces every axis.
1733 ///
1734 /// # Examples
1735 /// ```rust
1736 /// use tenferro_ad::{EagerRuntime, Tensor};
1737 /// let ctx = EagerRuntime::new()?;
1738 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1739 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
1740 /// s.reduce_prod(&x, None)
1741 /// })?;
1742 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[6.0]);
1743 /// # Ok::<(), tenferro_ad::Error>(())
1744 /// ```
1745 /// # Errors
1746 /// Returns a typed foreign-runtime, invalid-axis, unsupported-dtype, or backend error.
1747 pub fn reduce_prod(
1748 &mut self,
1749 input: &EagerTensor,
1750 axes: Option<&[isize]>,
1751 ) -> Result<EagerTensor> {
1752 self.ensure_runtime(input)?;
1753 let axes = match axes {
1754 Some(axes) => crate::shape_packing::normalize_existing_axes(
1755 "EagerSession::reduce_prod",
1756 axes,
1757 input.shape().len(),
1758 )?,
1759 None => (0..input.shape().len()).collect(),
1760 };
1761 crate::eager_ops::validate_eager_axes(
1762 "EagerSession::reduce_prod",
1763 input.shape().len(),
1764 &axes,
1765 )?;
1766 self.run_unary(input, StdTensorOp::ReduceProd { axes })
1767 }
1768
1769 /// Reduce the maximum over selected axes in this borrowed session.
1770 /// `None` reduces every axis.
1771 ///
1772 /// # Examples
1773 /// ```rust
1774 /// use tenferro_ad::{EagerRuntime, Tensor};
1775 /// let ctx = EagerRuntime::new()?;
1776 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1777 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
1778 /// s.reduce_max(&x, None)
1779 /// })?;
1780 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[3.0]);
1781 /// # Ok::<(), tenferro_ad::Error>(())
1782 /// ```
1783 /// # Errors
1784 /// Returns a typed foreign-runtime, invalid-axis, unsupported-dtype, or backend error.
1785 pub fn reduce_max(
1786 &mut self,
1787 input: &EagerTensor,
1788 axes: Option<&[isize]>,
1789 ) -> Result<EagerTensor> {
1790 self.ensure_runtime(input)?;
1791 let axes = match axes {
1792 Some(axes) => crate::shape_packing::normalize_existing_axes(
1793 "EagerSession::reduce_max",
1794 axes,
1795 input.shape().len(),
1796 )?,
1797 None => (0..input.shape().len()).collect(),
1798 };
1799 crate::eager_ops::validate_eager_axes(
1800 "EagerSession::reduce_max",
1801 input.shape().len(),
1802 &axes,
1803 )?;
1804 self.run_unary(input, StdTensorOp::ReduceMax { axes })
1805 }
1806
1807 /// Reduce the minimum over selected axes in this borrowed session.
1808 /// `None` reduces every axis.
1809 ///
1810 /// # Examples
1811 /// ```rust
1812 /// use tenferro_ad::{EagerRuntime, Tensor};
1813 /// let ctx = EagerRuntime::new()?;
1814 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1815 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
1816 /// s.reduce_min(&x, None)
1817 /// })?;
1818 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[2.0]);
1819 /// # Ok::<(), tenferro_ad::Error>(())
1820 /// ```
1821 /// # Errors
1822 /// Returns a typed foreign-runtime, invalid-axis, unsupported-dtype, or backend error.
1823 pub fn reduce_min(
1824 &mut self,
1825 input: &EagerTensor,
1826 axes: Option<&[isize]>,
1827 ) -> Result<EagerTensor> {
1828 self.ensure_runtime(input)?;
1829 let axes = match axes {
1830 Some(axes) => crate::shape_packing::normalize_existing_axes(
1831 "EagerSession::reduce_min",
1832 axes,
1833 input.shape().len(),
1834 )?,
1835 None => (0..input.shape().len()).collect(),
1836 };
1837 crate::eager_ops::validate_eager_axes(
1838 "EagerSession::reduce_min",
1839 input.shape().len(),
1840 &axes,
1841 )?;
1842 self.run_unary(input, StdTensorOp::ReduceMin { axes })
1843 }
1844
1845 /// Duplicate an eager value into an independent tensor within the caller's
1846 /// borrowed session, preserving its dtype and placement.
1847 ///
1848 /// # Examples
1849 ///
1850 /// ```rust
1851 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
1852 /// let ctx = EagerRuntime::new()?;
1853 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
1854 /// let copy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.duplicate_value(&x))?;
1855 /// assert_eq!(copy.as_slice::<f64>()?, &[2.0]);
1856 /// # Ok::<(), tenferro_ad::Error>(())
1857 /// ```
1858 ///
1859 /// # Errors
1860 ///
1861 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
1862 /// runtime/backend error when the retained value cannot be duplicated.
1863 pub fn duplicate_value(&mut self, input: &EagerTensor) -> Result<Tensor> {
1864 self.ensure_runtime(input)?;
1865 input.duplicate_value_in_session(&mut *self.engine)
1866 }
1867
1868 /// Import an untracked leaf within this borrowed session.
1869 ///
1870 /// `tensor` must already be usable by this runtime's backend: a host
1871 /// tensor on a CPU runtime, or a tensor already on the device of a CUDA
1872 /// or WebGPU runtime. No host/device transfer happens here. To import host
1873 /// data into a device runtime, use [`Self::constant_from_host`], which
1874 /// uploads first; on a CPU runtime the two are equivalent.
1875 ///
1876 /// # Examples
1877 ///
1878 /// ```rust
1879 /// use tenferro_ad::{EagerRuntime, Tensor};
1880 /// let ctx = EagerRuntime::new()?;
1881 /// let c = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1882 /// session.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)
1883 /// })?;
1884 /// assert_eq!(c.value()?.as_slice::<f64>()?, &[2.0]);
1885 /// # Ok::<(), tenferro_ad::Error>(())
1886 /// ```
1887 ///
1888 /// # Errors
1889 ///
1890 /// Returns [`Error::TensorRuntime`] for a typed backend failure when the value cannot be
1891 /// registered in the session, or [`Error::RuntimeState`] when the runtime's
1892 /// value registry is unavailable.
1893 pub fn constant_from(&mut self, tensor: Tensor) -> Result<EagerTensor> {
1894 EagerTensor::new_leaf_in_session(Arc::clone(self.runtime), tensor, false, &mut *self.engine)
1895 }
1896
1897 /// Upload a host tensor and import it as an untracked leaf in this session.
1898 ///
1899 /// Unlike [`Self::constant_from`], this explicitly crosses the host/device
1900 /// boundary: the host `tensor` is uploaded to this runtime's backend
1901 /// (a host copy on a CPU runtime) and the uploaded value becomes the leaf.
1902 /// Use it whenever the source data lives on the host and the runtime may
1903 /// be a device runtime; use [`Self::constant_from`] for a tensor that is
1904 /// already resident on the backend.
1905 ///
1906 /// # Examples
1907 /// ```rust
1908 /// use tenferro_ad::{EagerRuntime, Tensor};
1909 /// let ctx = EagerRuntime::new()?;
1910 /// let c = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1911 /// s.constant_from_host(Tensor::from_vec_col_major([1], vec![2.0_f64])?)
1912 /// })?;
1913 /// assert_eq!(c.value()?.as_slice::<f64>()?, &[2.0]);
1914 /// # Ok::<(), tenferro_ad::Error>(())
1915 /// ```
1916 /// # Errors
1917 /// Returns [`Error::TensorRuntime`] for a typed backend failure, including a host-tensor
1918 /// upload failure, or [`Error::RuntimeState`] when the runtime's value
1919 /// registry is unavailable.
1920 pub fn constant_from_host(&mut self, tensor: Tensor) -> Result<EagerTensor> {
1921 let uploaded = self
1922 .engine
1923 .upload_host_tensor(TensorRead::from_tensor(&tensor))
1924 .map_err(Error::from)?;
1925 self.constant_from(uploaded)
1926 }
1927
1928 /// Import a trainable leaf within this borrowed session.
1929 ///
1930 /// # Examples
1931 ///
1932 /// ```rust
1933 /// use tenferro_ad::{EagerRuntime, Tensor};
1934 /// let ctx = EagerRuntime::new()?;
1935 /// let x = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
1936 /// session.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)
1937 /// })?;
1938 /// assert!(x.tracks_grad());
1939 /// # Ok::<(), tenferro_ad::Error>(())
1940 /// ```
1941 ///
1942 /// # Errors
1943 ///
1944 /// Returns [`Error::TensorRuntime`] for a typed backend failure when the value cannot be
1945 /// registered, or [`Error::RuntimeState`] when the runtime's value or
1946 /// gradient registry is unavailable.
1947 pub fn variable_from(&mut self, tensor: Tensor) -> Result<EagerTensor> {
1948 EagerTensor::new_leaf_in_session(Arc::clone(self.runtime), tensor, true, &mut *self.engine)
1949 }
1950
1951 /// Detach an eager tensor from the reverse graph within this session.
1952 ///
1953 /// The result keeps the concrete value, belongs to the same runtime and
1954 /// contributes no gradients to the graph that produced `input`. To move a
1955 /// value into another eager runtime, duplicate it here with
1956 /// [`Self::duplicate_value`] and import the owned tensor in the target
1957 /// runtime's session with [`Self::constant_from`].
1958 ///
1959 /// # Examples
1960 ///
1961 /// ```rust
1962 /// use tenferro_ad::{EagerRuntime, Tensor};
1963 ///
1964 /// let ctx = EagerRuntime::new()?;
1965 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
1966 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.detach(&x))?;
1967 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0, 2.0]);
1968 /// assert!(!y.tracks_grad());
1969 /// # Ok::<(), tenferro_ad::Error>(())
1970 /// ```
1971 ///
1972 /// # Errors
1973 ///
1974 /// Returns [`Error::ContextMismatch`] for a tensor from another runtime,
1975 /// [`Error::TensorRuntime`] when the engine cannot materialize the
1976 /// retained value, or [`Error::RuntimeState`] when the value record or its
1977 /// allocation-group descriptor is unavailable.
1978 pub fn detach(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
1979 self.ensure_runtime(input)?;
1980 input.detach_in_session(&mut *self.engine)
1981 }
1982
1983 /// Gradient of a scalar eager output with respect to an eager tensor.
1984 ///
1985 /// Functional eager gradients return ordinary eager tensors and do not
1986 /// write into `grad()` slots. The returned tensor keeps a trace when the
1987 /// derivative computation depends on tracked eager values, so it can be
1988 /// differentiated again (higher-order derivatives).
1989 ///
1990 /// # Examples
1991 ///
1992 /// ```rust
1993 /// use tenferro_ad::{EagerRuntime, Tensor};
1994 ///
1995 /// let ctx = EagerRuntime::new()?;
1996 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
1997 /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
1998 /// let loss = s.mul(&x, &x)?;
1999 /// s.grad(&loss, &x)
2000 /// })?;
2001 /// assert_eq!(dx.value()?.as_slice::<f64>()?, &[6.0]);
2002 /// # Ok::<(), tenferro_ad::Error>(())
2003 /// ```
2004 ///
2005 /// # Errors
2006 ///
2007 /// Returns [`Error::ContextMismatch`] when `output` or `wrt` belongs to
2008 /// another runtime (checked before anything is materialized),
2009 /// [`Error::NonScalarGrad`] for a non-scalar output,
2010 /// [`Error::UnsupportedAdRule`] when an AD rule is unavailable, or a typed
2011 /// validation/backend error from eager execution. An inactive `wrt`
2012 /// returns [`Error::Validation`] with `argument: "wrt"`; use
2013 /// [`Self::grad_optional`] to observe that state.
2014 pub fn grad(&mut self, output: &EagerTensor, wrt: &EagerTensor) -> Result<EagerTensor> {
2015 self.grad_optional(output, wrt)?
2016 .ok_or_else(|| crate::traced::inactive_wrt_error("grad", &wrt.key))
2017 }
2018
2019 /// Gradient that returns `None` when `wrt` is inactive.
2020 ///
2021 /// # Examples
2022 ///
2023 /// ```rust
2024 /// use tenferro_ad::{EagerRuntime, Tensor};
2025 ///
2026 /// let ctx = EagerRuntime::new()?;
2027 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2028 /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![], vec![4.0_f64])?)?;
2029 /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2030 /// let loss = s.mul(&y, &y)?;
2031 /// s.grad_optional(&loss, &x)
2032 /// })?;
2033 /// assert!(dx.is_none());
2034 /// # Ok::<(), tenferro_ad::Error>(())
2035 /// ```
2036 ///
2037 /// # Errors
2038 ///
2039 /// Returns [`Error::ContextMismatch`] when `output` or `wrt` belongs to
2040 /// another runtime (checked before the seed is built),
2041 /// [`Error::NonScalarGrad`] for a non-scalar output, or a typed
2042 /// validation/backend/runtime-state error from eager execution.
2043 pub fn grad_optional(
2044 &mut self,
2045 output: &EagerTensor,
2046 wrt: &EagerTensor,
2047 ) -> Result<Option<EagerTensor>> {
2048 self.ensure_runtime(output)?;
2049 self.ensure_runtime(wrt)?;
2050 let seed = self.unit_seed(output)?;
2051 let seed =
2052 EagerTensor::new_result(Arc::clone(self.runtime), eager_val_key(), seed, false, None)?;
2053 self.vjp_optional(output, wrt, &seed)
2054 }
2055
2056 /// Reverse-mode vector-Jacobian product for eager tensors.
2057 ///
2058 /// # Examples
2059 ///
2060 /// ```rust
2061 /// use tenferro_ad::{EagerRuntime, Tensor};
2062 ///
2063 /// let ctx = EagerRuntime::new()?;
2064 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
2065 /// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 1.0])?)?;
2066 /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2067 /// let y = s.mul(&x, &x)?;
2068 /// s.vjp(&y, &x, &seed)
2069 /// })?;
2070 /// assert_eq!(dx.value()?.as_slice::<f64>()?, &[4.0, 6.0]);
2071 /// # Ok::<(), tenferro_ad::Error>(())
2072 /// ```
2073 ///
2074 /// # Errors
2075 ///
2076 /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `cotangent`
2077 /// belongs to another runtime, [`Error::Validation`] when the cotangent
2078 /// shape or dtype does not match the output, [`Error::UnsupportedAdRule`]
2079 /// when a rule is not registered, or a typed backend/runtime-state error.
2080 /// An inactive `wrt` returns [`Error::Validation`] with `argument: "wrt"`;
2081 /// use [`Self::vjp_optional`] to observe that state.
2082 pub fn vjp(
2083 &mut self,
2084 output: &EagerTensor,
2085 wrt: &EagerTensor,
2086 cotangent: &EagerTensor,
2087 ) -> Result<EagerTensor> {
2088 self.vjp_optional(output, wrt, cotangent)?
2089 .ok_or_else(|| crate::traced::inactive_wrt_error("vjp", &wrt.key))
2090 }
2091
2092 /// Reverse-mode vector-Jacobian product that returns `None` for inactive inputs.
2093 ///
2094 /// `None` means the input is disconnected, its eager computation was not
2095 /// recorded, or the semantic derivative has no cotangent flow (for example,
2096 /// real `sign` or an integer conversion). A present numerical zero is still
2097 /// returned as `Some`. Missing rules and execution failures return errors;
2098 /// semantic differentiation cannot be disabled by an environment variable.
2099 ///
2100 /// # Examples
2101 ///
2102 /// ```rust
2103 /// use tenferro_ad::{EagerRuntime, Tensor};
2104 ///
2105 /// let ctx = EagerRuntime::new()?;
2106 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2107 /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
2108 /// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
2109 /// let dx = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2110 /// let loss = s.mul(&y, &y)?;
2111 /// s.vjp_optional(&loss, &x, &seed)
2112 /// })?;
2113 /// assert!(dx.is_none());
2114 /// # Ok::<(), tenferro_ad::Error>(())
2115 /// ```
2116 ///
2117 /// # Errors
2118 ///
2119 /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `cotangent`
2120 /// belongs to another runtime, [`Error::Validation`] when the cotangent
2121 /// shape or dtype does not match the output, [`Error::UnsupportedAdRule`]
2122 /// when a rule is not registered, or a typed backend/runtime-state error.
2123 pub fn vjp_optional(
2124 &mut self,
2125 output: &EagerTensor,
2126 wrt: &EagerTensor,
2127 cotangent: &EagerTensor,
2128 ) -> Result<Option<EagerTensor>> {
2129 self.ensure_runtime(output)?;
2130 self.ensure_runtime(wrt)?;
2131 self.ensure_runtime(cotangent)?;
2132 validate_seed_tensor("vjp", output, cotangent)?;
2133 Ok(
2134 semantic_eager_vjp_many(self.runtime, &mut *self.engine, output, &[wrt], cotangent)?
2135 .pop()
2136 .flatten(),
2137 )
2138 }
2139
2140 /// Forward-mode Jacobian-vector product for eager tensors.
2141 ///
2142 /// # Examples
2143 ///
2144 /// ```rust
2145 /// use tenferro_ad::{EagerRuntime, Tensor};
2146 ///
2147 /// let ctx = EagerRuntime::new()?;
2148 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
2149 /// let tangent = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
2150 /// let dy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2151 /// let y = s.mul(&x, &x)?;
2152 /// s.jvp(&y, &x, &tangent)
2153 /// })?;
2154 /// assert_eq!(dy.value()?.as_slice::<f64>()?, &[6.0]);
2155 /// # Ok::<(), tenferro_ad::Error>(())
2156 /// ```
2157 ///
2158 /// # Errors
2159 ///
2160 /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `tangent`
2161 /// belongs to another runtime, [`Error::Validation`] when the tangent
2162 /// shape or dtype does not match `wrt`, [`Error::UnsupportedAdRule`] when
2163 /// a rule is unavailable, or a typed backend/runtime-state error. An
2164 /// inactive `wrt` returns [`Error::Validation`] with `argument: "wrt"`;
2165 /// use [`Self::jvp_optional`] to observe that state.
2166 pub fn jvp(
2167 &mut self,
2168 output: &EagerTensor,
2169 wrt: &EagerTensor,
2170 tangent: &EagerTensor,
2171 ) -> Result<EagerTensor> {
2172 self.jvp_optional(output, wrt, tangent)?
2173 .ok_or_else(|| crate::traced::inactive_wrt_error("jvp", &wrt.key))
2174 }
2175
2176 /// Forward-mode Jacobian-vector product that returns `None` for inactive outputs.
2177 ///
2178 /// `None` means `wrt` is disconnected, its eager computation was not
2179 /// recorded, or the semantic derivative has no tangent flow (for example,
2180 /// real `sign` or an integer conversion). A present numerical zero is still
2181 /// returned as `Some`. Missing rules and execution failures return errors;
2182 /// semantic differentiation cannot be disabled by an environment variable.
2183 ///
2184 /// # Examples
2185 ///
2186 /// ```rust
2187 /// use tenferro_ad::{EagerRuntime, Tensor};
2188 ///
2189 /// let ctx = EagerRuntime::new()?;
2190 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2191 /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![4.0_f64])?)?;
2192 /// let tangent = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
2193 /// let dy = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2194 /// let loss = s.mul(&y, &y)?;
2195 /// s.jvp_optional(&loss, &x, &tangent)
2196 /// })?;
2197 /// assert!(dy.is_none());
2198 /// # Ok::<(), tenferro_ad::Error>(())
2199 /// ```
2200 ///
2201 /// # Errors
2202 ///
2203 /// Returns [`Error::ContextMismatch`] when `output`, `wrt` or `tangent`
2204 /// belongs to another runtime, [`Error::Validation`] when the tangent
2205 /// shape or dtype does not match `wrt`, [`Error::UnsupportedAdRule`] when
2206 /// a rule is unavailable, or a typed backend/runtime-state error.
2207 pub fn jvp_optional(
2208 &mut self,
2209 output: &EagerTensor,
2210 wrt: &EagerTensor,
2211 tangent: &EagerTensor,
2212 ) -> Result<Option<EagerTensor>> {
2213 self.ensure_runtime(output)?;
2214 self.ensure_runtime(wrt)?;
2215 self.ensure_runtime(tangent)?;
2216 validate_seed_tensor("jvp", wrt, tangent)?;
2217 semantic_eager_jvp_optional(self.runtime, &mut *self.engine, output, wrt, tangent)
2218 }
2219
2220 /// Run reverse-mode AD from a scalar eager output.
2221 ///
2222 /// Returns the full cotangent map produced by the reverse pass and also
2223 /// accumulates into `grad()` for tracked eager leaves reachable from
2224 /// `output`; repeated calls add to the stored gradients until they are
2225 /// cleared. A pass with no gradients is an error, not an empty successful
2226 /// bundle. If a reachable leaf has no cotangent flow, the pass fails before
2227 /// accumulating any gradients; use [`Self::vjp_optional`] to observe absent
2228 /// flow explicitly.
2229 ///
2230 /// For complex scalar outputs, cotangents use tenferro's Hermitian
2231 /// real-inner-product convention. See
2232 /// <https://tensor4all.org/tenferro-rs/guides/complex-ad.html>.
2233 ///
2234 /// # Examples
2235 ///
2236 /// ```rust
2237 /// use tenferro_ad::{EagerRuntime, Tensor};
2238 ///
2239 /// let ctx = EagerRuntime::new()?;
2240 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0])?)?;
2241 /// for _ in 0..2 {
2242 /// ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2243 /// let doubled = s.add(&x, &x)?;
2244 /// let loss = s.reduce_sum(&doubled, Some(&[0]))?;
2245 /// s.backward(&loss)
2246 /// })?;
2247 /// }
2248 /// assert_eq!(x.grad()?.expect("tracked leaf").as_slice::<f64>()?, &[4.0, 4.0, 4.0]);
2249 /// # Ok::<(), Box<dyn std::error::Error>>(())
2250 /// ```
2251 ///
2252 /// # Errors
2253 ///
2254 /// Returns [`Error::ContextMismatch`] when `output` belongs to another
2255 /// runtime (checked before any gradient slot is written),
2256 /// [`Error::NonScalarGrad`] when `output` is not scalar,
2257 /// [`Error::Validation`] when a reachable tracked leaf has no cotangent,
2258 /// [`Error::RuntimeState`] when no tracked leaf produces a gradient,
2259 /// [`Error::UnsupportedAdRule`] when a graph operation lacks a reverse
2260 /// rule, or a typed validation/backend/runtime-state error during the
2261 /// reverse pass.
2262 pub fn backward(&mut self, output: &EagerTensor) -> Result<Gradients> {
2263 self.ensure_runtime(output)?;
2264 let seed = self.unit_seed(output)?;
2265 output.backward_from_seed(&mut *self.engine, seed)
2266 }
2267
2268 /// Run reverse-mode AD from an eager output with an explicit cotangent seed.
2269 ///
2270 /// The seed is an operand, not an options value: this is the registry's
2271 /// documented seeded form of [`Self::backward`]. Like `backward`, it
2272 /// rejects absent cotangents for reachable tracked leaves before
2273 /// accumulation, accumulates into the reachable leaves' `grad()` slots and
2274 /// never returns an empty successful bundle. Use [`Self::vjp`] when the
2275 /// VJP result should be a composable eager tensor that touches no
2276 /// gradient slot.
2277 ///
2278 /// # Examples
2279 ///
2280 /// ```rust
2281 /// use tenferro_ad::{EagerRuntime, Tensor};
2282 ///
2283 /// let ctx = EagerRuntime::new()?;
2284 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![2.0_f64, 3.0])?)?;
2285 /// let seed = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2286 /// ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2287 /// let y = s.mul(&x, &x)?;
2288 /// s.backward_with(&y, &seed)
2289 /// })?;
2290 /// assert_eq!(x.grad()?.expect("tracked leaf").as_slice::<f64>()?, &[4.0, 12.0]);
2291 /// # Ok::<(), Box<dyn std::error::Error>>(())
2292 /// ```
2293 ///
2294 /// # Errors
2295 ///
2296 /// Returns [`Error::ContextMismatch`] when `output` or `cotangent` belongs
2297 /// to another runtime (checked before the seed is materialized or any
2298 /// gradient slot is written), [`Error::Validation`] when the seed's shape
2299 /// or dtype does not match `output` or a reachable tracked leaf has no
2300 /// cotangent, [`Error::RuntimeState`] when no tracked leaf produces a
2301 /// gradient, [`Error::UnsupportedAdRule`] for an unavailable reverse rule,
2302 /// or a typed backend/runtime-state error during execution.
2303 pub fn backward_with(
2304 &mut self,
2305 output: &EagerTensor,
2306 cotangent: &EagerTensor,
2307 ) -> Result<Gradients> {
2308 self.ensure_runtime(output)?;
2309 self.ensure_runtime(cotangent)?;
2310 validate_seed_tensor("backward", output, cotangent)?;
2311 let seed = cotangent.duplicate_value_in_session(&mut *self.engine)?;
2312 output.backward_from_seed(&mut *self.engine, seed)
2313 }
2314
2315 /// The all-ones seed of a scalar output, after the runtime checks.
2316 fn unit_seed(&mut self, output: &EagerTensor) -> Result<Tensor> {
2317 if !output.shape().is_empty() {
2318 return Err(Error::NonScalarGrad {
2319 shape: output.shape().to_vec(),
2320 });
2321 }
2322 let value = output.duplicate_value_in_session(&mut *self.engine)?;
2323 one_like_tensor(&value, &mut *self.engine)
2324 }
2325
2326 /// Add eager tensors with the same broadcast and AD rules as the eager
2327 /// operation surface, reusing this borrowed execution session.
2328 ///
2329 /// # Examples
2330 ///
2331 /// ```rust
2332 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
2333 /// let ctx = EagerRuntime::new()?;
2334 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2335 /// let scalar = ctx.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2336 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.add(&x, &scalar))?;
2337 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[4.0, 5.0]);
2338 /// # Ok::<(), tenferro_ad::Error>(())
2339 /// ```
2340 ///
2341 /// # Errors
2342 ///
2343 /// Returns [`Error::ContextMismatch`] for a tensor from another runtime,
2344 /// or a typed broadcast/backend error for the operands.
2345 pub fn add(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2346 self.run_binary("add", lhs, rhs, StdTensorOp::Add)
2347 }
2348
2349 /// Subtract eager tensors within this borrowed session.
2350 ///
2351 /// # Examples
2352 ///
2353 /// ```rust
2354 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
2355 /// let ctx = EagerRuntime::new()?;
2356 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
2357 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.sub(&x, &x))?;
2358 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0]);
2359 /// # Ok::<(), tenferro_ad::Error>(())
2360 /// ```
2361 ///
2362 /// # Errors
2363 ///
2364 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
2365 /// broadcast/backend error for the operands.
2366 pub fn sub(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2367 self.run_binary("sub", lhs, rhs, StdTensorOp::Sub)
2368 }
2369
2370 /// Multiply eager tensors within this borrowed session.
2371 ///
2372 /// # Examples
2373 ///
2374 /// ```rust
2375 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
2376 /// let ctx = EagerRuntime::new()?;
2377 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
2378 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| session.mul(&x, &x))?;
2379 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[9.0]);
2380 /// # Ok::<(), tenferro_ad::Error>(())
2381 /// ```
2382 ///
2383 /// # Errors
2384 ///
2385 /// Returns [`Error::ContextMismatch`] for a foreign runtime, or a typed
2386 /// broadcast/backend error for the operands.
2387 pub fn mul(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2388 self.run_binary("mul", lhs, rhs, StdTensorOp::Mul)
2389 }
2390
2391 /// Divide eager tensors elementwise with broadcast rules.
2392 ///
2393 /// # Examples
2394 /// ```rust
2395 /// use tenferro_ad::{EagerRuntime, Tensor};
2396 /// let ctx = EagerRuntime::new()?;
2397 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2398 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![6.0_f64])?)?;
2399 /// let divisor = s.constant_from(Tensor::from_vec_col_major(vec![], vec![2.0_f64])?)?;
2400 /// s.div(&x, &divisor)
2401 /// })?;
2402 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[3.0]);
2403 /// # Ok::<(), tenferro_ad::Error>(())
2404 /// ```
2405 /// # Errors
2406 /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2407 /// runtime, a validation error with
2408 /// `ValidationError::ShapeMismatch` when the operands cannot broadcast, or
2409 /// [`Error::TensorRuntime`] for a typed backend failure (including integer division by
2410 /// zero).
2411 pub fn div(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2412 self.run_binary("div", lhs, rhs, StdTensorOp::Div)
2413 }
2414
2415 /// Compute the elementwise remainder with broadcast rules.
2416 ///
2417 /// # Examples
2418 /// ```rust
2419 /// use tenferro_ad::{EagerRuntime, Tensor};
2420 /// let ctx = EagerRuntime::new()?;
2421 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2422 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![5.0_f64])?)?;
2423 /// let divisor = s.constant_from(Tensor::from_vec_col_major(vec![], vec![2.0_f64])?)?;
2424 /// s.rem(&x, &divisor)
2425 /// })?;
2426 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0]);
2427 /// # Ok::<(), tenferro_ad::Error>(())
2428 /// ```
2429 /// # Errors
2430 /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2431 /// runtime, a validation error with
2432 /// `ValidationError::ShapeMismatch` when the operands cannot broadcast, or
2433 /// [`Error::TensorRuntime`] for a typed backend failure (including an integer remainder by
2434 /// zero).
2435 pub fn rem(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2436 self.run_binary("rem", lhs, rhs, StdTensorOp::Rem)
2437 }
2438
2439 /// Raise eager tensor elements to broadcast exponents.
2440 ///
2441 /// # Examples
2442 /// ```rust
2443 /// use tenferro_ad::{EagerRuntime, Tensor};
2444 /// let ctx = EagerRuntime::new()?;
2445 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2446 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2447 /// let exponent = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2448 /// s.pow(&x, &exponent)
2449 /// })?;
2450 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[8.0]);
2451 /// # Ok::<(), tenferro_ad::Error>(())
2452 /// ```
2453 /// # Errors
2454 /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2455 /// runtime, a validation error with
2456 /// `ValidationError::ShapeMismatch` when the operands cannot broadcast, or
2457 /// [`Error::TensorRuntime`] for a typed backend failure (including a negative integer
2458 /// exponent).
2459 pub fn pow(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2460 self.run_binary("pow", lhs, rhs, StdTensorOp::Pow)
2461 }
2462
2463 /// Compute the elementwise maximum under broadcast rules.
2464 ///
2465 /// # Examples
2466 /// ```rust
2467 /// use tenferro_ad::{EagerRuntime, Tensor};
2468 /// let ctx = EagerRuntime::new()?;
2469 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2470 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2471 /// let bound = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2472 /// s.maximum(&x, &bound)
2473 /// })?;
2474 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[3.0]);
2475 /// # Ok::<(), tenferro_ad::Error>(())
2476 /// ```
2477 /// # Errors
2478 /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2479 pub fn maximum(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2480 self.run_binary("maximum", lhs, rhs, StdTensorOp::Maximum)
2481 }
2482
2483 /// Compute the elementwise minimum under broadcast rules.
2484 ///
2485 /// # Examples
2486 /// ```rust
2487 /// use tenferro_ad::{EagerRuntime, Tensor};
2488 /// let ctx = EagerRuntime::new()?;
2489 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2490 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2491 /// let bound = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2492 /// s.minimum(&x, &bound)
2493 /// })?;
2494 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0]);
2495 /// # Ok::<(), tenferro_ad::Error>(())
2496 /// ```
2497 /// # Errors
2498 /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2499 pub fn minimum(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2500 self.run_binary("minimum", lhs, rhs, StdTensorOp::Minimum)
2501 }
2502
2503 /// Compare eager tensors elementwise under broadcast rules.
2504 ///
2505 /// # Examples
2506 /// ```rust
2507 /// use tenferro_ad::{CompareDir, EagerRuntime, Tensor};
2508 /// let ctx = EagerRuntime::new()?;
2509 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2510 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
2511 /// let bound = s.constant_from(Tensor::from_vec_col_major(vec![], vec![1.0_f64])?)?;
2512 /// s.compare(&x, &bound, CompareDir::Gt)
2513 /// })?;
2514 /// assert_eq!(y.value()?.as_slice::<bool>()?, &[true]);
2515 /// # Ok::<(), tenferro_ad::Error>(())
2516 /// ```
2517 /// # Errors
2518 /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2519 pub fn compare(
2520 &mut self,
2521 lhs: &EagerTensor,
2522 rhs: &EagerTensor,
2523 dir: CompareDir,
2524 ) -> Result<EagerTensor> {
2525 self.run_binary("compare", lhs, rhs, StdTensorOp::Compare(dir))
2526 }
2527
2528 /// Select eager values elementwise using a broadcast boolean condition.
2529 ///
2530 /// # Examples
2531 /// ```rust
2532 /// use tenferro_ad::{EagerRuntime, Tensor};
2533 /// let ctx = EagerRuntime::new()?;
2534 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2535 /// let condition = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![true, false])?)?;
2536 /// let yes = s.constant_from(Tensor::from_vec_col_major(vec![], vec![10.0_f64])?)?;
2537 /// let no = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2538 /// s.where_select(&condition, &yes, &no)
2539 /// })?;
2540 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[10.0, 2.0]);
2541 /// # Ok::<(), tenferro_ad::Error>(())
2542 /// ```
2543 /// # Errors
2544 /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2545 pub fn where_select(
2546 &mut self,
2547 condition: &EagerTensor,
2548 on_true: &EagerTensor,
2549 on_false: &EagerTensor,
2550 ) -> Result<EagerTensor> {
2551 self.run_ternary(
2552 "where_select",
2553 condition,
2554 on_true,
2555 on_false,
2556 StdTensorOp::Select,
2557 )
2558 }
2559
2560 /// Alias for [`Self::where_select`] with the same borrowed-session semantics.
2561 ///
2562 /// # Examples
2563 /// ```rust
2564 /// use tenferro_ad::{EagerRuntime, Tensor};
2565 /// let ctx = EagerRuntime::new()?;
2566 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2567 /// let predicate = s.constant_from(Tensor::from_vec_col_major(vec![], vec![true])?)?;
2568 /// let yes = s.constant_from(Tensor::from_vec_col_major(vec![], vec![3.0_f64])?)?;
2569 /// let no = s.constant_from(Tensor::from_vec_col_major(vec![], vec![4.0_f64])?)?;
2570 /// s.select(&predicate, &yes, &no)
2571 /// })?;
2572 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[3.0]);
2573 /// # Ok::<(), tenferro_ad::Error>(())
2574 /// ```
2575 /// # Errors
2576 /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2577 pub fn select(
2578 &mut self,
2579 condition: &EagerTensor,
2580 on_true: &EagerTensor,
2581 on_false: &EagerTensor,
2582 ) -> Result<EagerTensor> {
2583 self.where_select(condition, on_true, on_false)
2584 }
2585
2586 /// Clamp eager values elementwise between broadcast lower and upper bounds.
2587 ///
2588 /// # Examples
2589 /// ```rust
2590 /// use tenferro_ad::{EagerRuntime, Tensor};
2591 /// let ctx = EagerRuntime::new()?;
2592 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2593 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![-2.0_f64, 5.0])?)?;
2594 /// let lo = s.constant_from(Tensor::from_vec_col_major(vec![], vec![-1.0_f64])?)?;
2595 /// let hi = s.constant_from(Tensor::from_vec_col_major(vec![], vec![4.0_f64])?)?;
2596 /// s.clamp(&x, &lo, &hi)
2597 /// })?;
2598 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-1.0, 4.0]);
2599 /// # Ok::<(), tenferro_ad::Error>(())
2600 /// ```
2601 /// # Errors
2602 /// Returns a typed foreign-runtime, broadcast, unsupported-dtype, or backend error.
2603 pub fn clamp(
2604 &mut self,
2605 input: &EagerTensor,
2606 lower: &EagerTensor,
2607 upper: &EagerTensor,
2608 ) -> Result<EagerTensor> {
2609 self.run_ternary("clamp", input, lower, upper, StdTensorOp::Clamp)
2610 }
2611
2612 /// Contract eager tensors according to a dot-general dimension mapping.
2613 ///
2614 /// The output layout is `[lhs free..., rhs free..., batch...]`: batch axes
2615 /// come last (see [`DotGeneralConfig`](tenferro_runtime::DotGeneralConfig)).
2616 ///
2617 /// # Examples
2618 ///
2619 /// ```rust
2620 /// use tenferro_ad::{DotGeneralConfig, EagerRuntime, Tensor};
2621 /// let ctx = EagerRuntime::new()?;
2622 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
2623 /// let lhs = session.variable_from(Tensor::from_vec_col_major(vec![1, 2], vec![2.0_f64, 3.0])?)?;
2624 /// let rhs = session.constant_from(Tensor::from_vec_col_major(vec![2, 1], vec![4.0_f64, 5.0])?)?;
2625 /// session.dot_general(&lhs, &rhs, DotGeneralConfig {
2626 /// lhs_contracting_dims: [1].as_slice().into(),
2627 /// rhs_contracting_dims: [0].as_slice().into(),
2628 /// lhs_batch_dims: [].as_slice().into(),
2629 /// rhs_batch_dims: [].as_slice().into(),
2630 /// })
2631 /// })?;
2632 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[23.0]);
2633 /// # Ok::<(), tenferro_ad::Error>(())
2634 /// ```
2635 ///
2636 /// # Errors
2637 ///
2638 /// Returns [`Error::ContextMismatch`] for a foreign eager runtime,
2639 /// a typed validation error for incompatible contraction dimensions,
2640 /// or the backend's typed execution error.
2641 pub fn dot_general(
2642 &mut self,
2643 lhs: &EagerTensor,
2644 rhs: &EagerTensor,
2645 config: DotGeneralConfig,
2646 ) -> Result<EagerTensor> {
2647 self.ensure_runtime(lhs)?;
2648 self.ensure_runtime(rhs)?;
2649 config
2650 .validate_dims_with_ranks(lhs.shape().len(), rhs.shape().len())
2651 .map_err(Error::TensorRuntime)?;
2652 EagerTensor::nary_op_in_session(
2653 &[lhs, rhs],
2654 StdTensorOp::DotGeneral { config },
2655 &mut *self.engine,
2656 )
2657 }
2658
2659 /// Scale an eager tensor by a real scalar in this borrowed session.
2660 /// Integer factors are rounded; finite zero maps to `false` for boolean inputs.
2661 ///
2662 /// # Examples
2663 /// ```rust
2664 /// use tenferro_ad::{EagerRuntime, Tensor};
2665 /// let ctx = EagerRuntime::new()?;
2666 /// let scaled = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2667 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2668 /// s.scale_real(&x, 2.0)
2669 /// })?;
2670 /// assert_eq!(scaled.value()?.as_slice::<f64>()?, &[2.0, 4.0]);
2671 /// # Ok::<(), tenferro_ad::Error>(())
2672 /// ```
2673 /// # Errors
2674 /// Returns a typed foreign-runtime, invalid-factor/dtype, or backend error.
2675 pub fn scale_real(&mut self, input: &EagerTensor, factor: f64) -> Result<EagerTensor> {
2676 self.ensure_runtime(input)?;
2677 let scalar = tenferro_runtime::scale::real_scale_scalar(input.dtype(), factor)?;
2678 let scalar = self.constant_from_host(scalar)?;
2679 self.mul(input, &scalar)
2680 }
2681
2682 /// Scale a complex eager tensor by a complex scalar in this borrowed session.
2683 ///
2684 /// # Examples
2685 /// ```rust
2686 /// use num_complex::Complex64;
2687 /// use tenferro_ad::{EagerRuntime, Tensor};
2688 /// let ctx = EagerRuntime::new()?;
2689 /// let scaled = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2690 /// let x = s.constant_from(Tensor::from_vec_col_major(vec![1], vec![Complex64::new(1.0, 2.0)])?)?;
2691 /// s.scale_complex(&x, Complex64::new(0.0, 1.0))
2692 /// })?;
2693 /// assert_eq!(scaled.value()?.as_slice::<Complex64>()?, &[Complex64::new(-2.0, 1.0)]);
2694 /// # Ok::<(), tenferro_ad::Error>(())
2695 /// ```
2696 /// # Errors
2697 /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2698 /// runtime, [`Error::TensorRuntime`] containing
2699 /// `ValidationError::InvalidArgument` when the input dtype is not complex,
2700 /// or [`Error::TensorRuntime`] for a typed backend failure.
2701 pub fn scale_complex(&mut self, input: &EagerTensor, factor: Complex64) -> Result<EagerTensor> {
2702 self.ensure_runtime(input)?;
2703 let scalar = tenferro_runtime::scale::complex_scale_scalar(input.dtype(), factor)?;
2704 let scalar = self.constant_from_host(scalar)?;
2705 self.mul(input, &scalar)
2706 }
2707
2708 /// Multiply two rank-2 eager tensors in this borrowed session.
2709 ///
2710 /// # Examples
2711 /// ```rust
2712 /// use tenferro_ad::{EagerRuntime, Tensor};
2713 /// let ctx = EagerRuntime::new()?;
2714 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2715 /// let a = s.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![2.0_f64])?)?;
2716 /// let b = s.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![3.0_f64])?)?;
2717 /// s.matmul(&a, &b)
2718 /// })?;
2719 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[6.0]);
2720 /// # Ok::<(), tenferro_ad::Error>(())
2721 /// ```
2722 /// # Errors
2723 /// Returns [`Error::ContextMismatch`] when an input belongs to another eager
2724 /// runtime, a validation error with
2725 /// `ValidationError::RankMismatch` or `ValidationError::ShapeMismatch` when
2726 /// the operands are not rank-2 with matching inner dimensions, a dtype
2727 /// mismatch between the operands, or [`Error::TensorRuntime`] for a typed backend failure.
2728 pub fn matmul(&mut self, lhs: &EagerTensor, rhs: &EagerTensor) -> Result<EagerTensor> {
2729 self.ensure_runtime(lhs)?;
2730 self.ensure_runtime(rhs)?;
2731 let lhs_shape = lhs.shape();
2732 let rhs_shape = rhs.shape();
2733 if lhs_shape.len() != 2 {
2734 return Err(tenferro_tensor::Error::rank_mismatch("matmul", 2, lhs_shape.len()).into());
2735 }
2736 if rhs_shape.len() != 2 {
2737 return Err(tenferro_tensor::Error::rank_mismatch("matmul", 2, rhs_shape.len()).into());
2738 }
2739 if lhs_shape[1] != rhs_shape[0] {
2740 return Err(
2741 tenferro_tensor::Error::shape_mismatch("matmul", lhs_shape, rhs_shape).into(),
2742 );
2743 }
2744 self.dot_general(
2745 lhs,
2746 rhs,
2747 DotGeneralConfig {
2748 lhs_contracting_dims: [1].as_slice().into(),
2749 rhs_contracting_dims: [0].as_slice().into(),
2750 lhs_batch_dims: [].as_slice().into(),
2751 rhs_batch_dims: [].as_slice().into(),
2752 },
2753 )
2754 }
2755
2756 /// Contract eagerly with optional conjugation of either operand.
2757 /// Untracked operands use the backend's conjugating contraction directly;
2758 /// tracked operands record explicit conjugations for reverse-mode AD.
2759 ///
2760 /// # Examples
2761 ///
2762 /// ```rust
2763 /// use tenferro_ad::{DotGeneralConfig, EagerRuntime, Tensor};
2764 /// let ctx = EagerRuntime::new()?;
2765 /// let result = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
2766 /// let lhs = session.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![2.0_f64])?)?;
2767 /// let rhs = session.constant_from(Tensor::from_vec_col_major(vec![1, 1], vec![3.0_f64])?)?;
2768 /// let conj_lhs = tenferro_tensor::DotGeneralOptions::default().lhs(tenferro_tensor::Conj::Yes);
2769 /// session.dot_general_with(&lhs, &rhs, DotGeneralConfig {
2770 /// lhs_contracting_dims: [1].as_slice().into(),
2771 /// rhs_contracting_dims: [0].as_slice().into(),
2772 /// lhs_batch_dims: [].as_slice().into(),
2773 /// rhs_batch_dims: [].as_slice().into(),
2774 /// }, &conj_lhs)
2775 /// })?;
2776 /// assert_eq!(result.value()?.as_slice::<f64>()?, &[6.0]);
2777 /// # Ok::<(), tenferro_ad::Error>(())
2778 /// ```
2779 ///
2780 /// # Errors
2781 ///
2782 /// Returns [`Error::ContextMismatch`] for a foreign eager runtime,
2783 /// a typed validation error for invalid dimensions, or a backend error.
2784 pub fn dot_general_with(
2785 &mut self,
2786 lhs: &EagerTensor,
2787 rhs: &EagerTensor,
2788 config: DotGeneralConfig,
2789 options: &tenferro_tensor::DotGeneralOptions,
2790 ) -> Result<EagerTensor> {
2791 let (lhs_conj, rhs_conj) = (options.lhs.is_yes(), options.rhs.is_yes());
2792 self.ensure_runtime(lhs)?;
2793 self.ensure_runtime(rhs)?;
2794 config
2795 .validate_dims_with_ranks(lhs.shape().len(), rhs.shape().len())
2796 .map_err(Error::TensorRuntime)?;
2797 if !lhs.requires_grad && !rhs.requires_grad {
2798 let output = crate::eager_exec::exec_dot_general_with_conj_on_tensor_reads_in_session(
2799 lhs.tensor_read(),
2800 rhs.tensor_read(),
2801 &config,
2802 lhs_conj,
2803 rhs_conj,
2804 &mut *self.engine,
2805 )?;
2806 return EagerTensor::new_untracked_result(Arc::clone(self.runtime), output);
2807 }
2808 let lhs = if lhs_conj {
2809 self.conj(lhs)?
2810 } else {
2811 lhs.clone()
2812 };
2813 let rhs = if rhs_conj {
2814 self.conj(rhs)?
2815 } else {
2816 rhs.clone()
2817 };
2818 self.dot_general(&lhs, &rhs, config)
2819 }
2820
2821 fn run_binary(
2822 &mut self,
2823 name: &'static str,
2824 lhs: &EagerTensor,
2825 rhs: &EagerTensor,
2826 op: StdTensorOp,
2827 ) -> Result<EagerTensor> {
2828 self.ensure_runtime(lhs)?;
2829 self.ensure_runtime(rhs)?;
2830 let (lhs, rhs) = crate::eager_ops::broadcast_binary_in_session(name, lhs, rhs, self)?;
2831 EagerTensor::nary_op_in_session(&[lhs.as_ref(), rhs.as_ref()], op, &mut *self.engine)
2832 }
2833
2834 fn run_ternary(
2835 &mut self,
2836 name: &'static str,
2837 first: &EagerTensor,
2838 second: &EagerTensor,
2839 third: &EagerTensor,
2840 op: StdTensorOp,
2841 ) -> Result<EagerTensor> {
2842 self.ensure_runtime(first)?;
2843 self.ensure_runtime(second)?;
2844 self.ensure_runtime(third)?;
2845 let (first, second, third) =
2846 crate::eager_ops::broadcast_ternary_in_session(name, first, second, third, self)?;
2847 EagerTensor::nary_op_in_session(&[&first, &second, &third], op, &mut *self.engine)
2848 }
2849
2850 /// Apply one standard tensor op in this borrowed session and record it
2851 /// for AD when needed.
2852 ///
2853 /// Extension crates use this when an extension-level eager operation
2854 /// expands into ordinary `StdTensorOp` nodes instead of a custom extension
2855 /// primitive: all of them run in this one backend session.
2856 ///
2857 /// # Examples
2858 ///
2859 /// ```rust
2860 /// use tenferro_ad::{EagerRuntime, Tensor};
2861 /// use tenferro_ops::std_tensor_op::StdTensorOp;
2862 ///
2863 /// let ctx = EagerRuntime::new()?;
2864 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
2865 /// let x = s.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?)?;
2866 /// let negated = s.apply_standard_op(StdTensorOp::Neg, &[&x])?;
2867 /// s.apply_standard_op(StdTensorOp::Mul, &[&negated, &x])
2868 /// })?;
2869 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-1.0, -4.0]);
2870 /// assert!(y.tracks_grad());
2871 /// # Ok::<(), tenferro_ad::Error>(())
2872 /// ```
2873 ///
2874 /// # Errors
2875 ///
2876 /// Returns [`Error::TensorRuntime`] containing
2877 /// [`tenferro_tensor::ValidationError::InvalidArgument`] for an extension
2878 /// op, [`Error::ContextMismatch`] for a tensor from another runtime, a
2879 /// typed input-count error, or the backend's typed execution error.
2880 pub fn apply_standard_op(
2881 &mut self,
2882 op: StdTensorOp,
2883 inputs: &[&EagerTensor],
2884 ) -> Result<EagerTensor> {
2885 if matches!(op, StdTensorOp::Extension(_)) {
2886 return Err(Error::invalid_argument(
2887 "EagerSession::apply_standard_op",
2888 ErrorPhase::Execution,
2889 "op",
2890 "Extension ops must be passed to apply_eager",
2891 ));
2892 }
2893 for input in inputs {
2894 self.ensure_runtime(input)?;
2895 }
2896 EagerTensor::nary_op_in_session(inputs, op, &mut *self.engine)
2897 }
2898
2899 /// Borrow the engine this eager session runs on.
2900 ///
2901 /// # Examples
2902 ///
2903 /// ```rust
2904 /// use tenferro_ad::EagerRuntime;
2905 /// use tenferro_cpu::CpuEngine;
2906 ///
2907 /// let ctx = EagerRuntime::new()?;
2908 /// let mut engine = CpuEngine::serial();
2909 /// let id = ctx.with_eager_session(&mut engine, |s| {
2910 /// Ok::<_, tenferro_ad::Error>(s.engine().target().engine_id().clone())
2911 /// })?;
2912 /// assert_eq!(id, tenferro_cpu::runtime_engine_id()?);
2913 /// # Ok::<(), Box<dyn std::error::Error>>(())
2914 /// ```
2915 pub fn engine(&mut self) -> &mut dyn ExecutionEngine {
2916 &mut *self.engine
2917 }
2918
2919 fn run_unary(&mut self, input: &EagerTensor, op: StdTensorOp) -> Result<EagerTensor> {
2920 self.ensure_runtime(input)?;
2921 EagerTensor::nary_op_in_session(&[input], op, &mut *self.engine)
2922 }
2923
2924 pub(crate) fn record_outputs(
2925 &mut self,
2926 op: &StdTensorOp,
2927 outputs: &[&Tensor],
2928 inputs: &[&EagerTensor],
2929 ) -> Result<RecordedEagerOutputs> {
2930 record_eager_outputs_in_session(op, outputs, inputs, &mut *self.engine)
2931 }
2932
2933 pub(crate) fn ensure_runtime(&self, input: &EagerTensor) -> Result<()> {
2934 if !Arc::ptr_eq(self.runtime, &input.ctx) {
2935 return Err(Error::ContextMismatch {
2936 lhs: self.runtime.id(),
2937 rhs: input.ctx_id(),
2938 });
2939 }
2940 Ok(())
2941 }
2942
2943 pub(crate) fn runtime(&self) -> &Arc<EagerRuntime> {
2944 self.runtime
2945 }
2946
2947 /// Run `f` on this runtime's extension cache store from inside the
2948 /// session.
2949 ///
2950 /// Operation families use this for their own prepared-plan caches without
2951 /// reopening the runtime: the eager owner is already locked, and the cache
2952 /// lock is taken second, as in every extension execution region.
2953 ///
2954 /// # Examples
2955 ///
2956 /// ```rust
2957 /// use tenferro_ad::EagerRuntime;
2958 ///
2959 /// let ctx = EagerRuntime::new()?;
2960 /// let entries = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |session| {
2961 /// session.with_extension_caches(|caches| caches.len())
2962 /// })?;
2963 /// assert_eq!(entries, 0);
2964 /// # Ok::<(), tenferro_ad::Error>(())
2965 /// ```
2966 ///
2967 /// # Errors
2968 ///
2969 /// Returns a runtime-state error when the extension cache lock is
2970 /// poisoned.
2971 pub fn with_extension_caches<R>(
2972 &mut self,
2973 f: impl FnOnce(&mut tenferro_runtime::ExtensionCacheStore) -> R,
2974 ) -> Result<R> {
2975 let result = with_lent_extension_caches(self.engine, |_, caches| f(caches));
2976 Ok(result)
2977 }
2978}
2979
2980impl fmt::Debug for EagerRuntime {
2981 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2982 let mut debug = f.debug_struct("EagerRuntime");
2983 debug.field("id", &self.id);
2984 debug.field("runtime_id", &self.runtime.id());
2985 debug.field("runtime_epoch", &self.runtime.epoch().ok());
2986 match self.extension_install_lock.try_lock() {
2987 Ok(_) => {
2988 debug.field("extension_install_lock", &"<unlocked>");
2989 }
2990 Err(_) => {
2991 debug.field("extension_install_lock", &"<locked>");
2992 }
2993 }
2994 debug.field("semantic_extension_rules", &self.semantic_extension_rules);
2995 match self.grad_slots.try_lock() {
2996 Ok(slots) => {
2997 debug.field("grad_slots_len", &slots.len());
2998 }
2999 Err(_) => {
3000 debug.field("grad_slots_len", &"<locked>");
3001 }
3002 }
3003 match self.value_records.try_lock() {
3004 Ok(records) => {
3005 debug.field("value_records_len", &records.len());
3006 }
3007 Err(_) => {
3008 debug.field("value_records_len", &"<locked>");
3009 }
3010 }
3011 match self.ad_transform_cache.stats() {
3012 Ok(stats) => {
3013 debug.field("ad_transform_cache_stats", &stats);
3014 }
3015 Err(err) => {
3016 debug.field("ad_transform_cache_stats", &format_args!("{err}"));
3017 }
3018 }
3019 match self.prepared_derivative_cache.try_lock() {
3020 Ok(cache) => {
3021 debug.field("prepared_derivative_cache_stats", &cache.stats());
3022 }
3023 Err(_) => {
3024 debug.field("prepared_derivative_cache_stats", &"<locked>");
3025 }
3026 }
3027 debug.finish_non_exhaustive()
3028 }
3029}
3030
3031impl EagerRuntime {
3032 fn lock_extension_install(&self) -> Result<MutexGuard<'_, ()>> {
3033 self.extension_install_lock.lock().map_err(|_| {
3034 Error::runtime_state(
3035 "eager_extension_install",
3036 ErrorPhase::Execution,
3037 "lock poisoned",
3038 )
3039 })
3040 }
3041
3042 fn lock_prepared_derivative_cache(&self) -> Result<MutexGuard<'_, PreparedDerivativeCache>> {
3043 self.prepared_derivative_cache.lock().map_err(|_| {
3044 Error::runtime_state(
3045 "prepared_derivative_cache",
3046 ErrorPhase::Execution,
3047 "lock poisoned",
3048 )
3049 })
3050 }
3051
3052 fn lock_grad_slots(
3053 &self,
3054 ) -> Result<MutexGuard<'_, HashMap<ValueKey<StdTensorOp>, WeakGradSlot>>> {
3055 self.grad_slots.lock().map_err(|_| {
3056 Error::runtime_state(
3057 "eager_gradient_slots",
3058 ErrorPhase::Execution,
3059 "lock poisoned",
3060 )
3061 })
3062 }
3063
3064 fn lock_value_records(
3065 &self,
3066 ) -> Result<MutexGuard<'_, HashMap<ValueKey<StdTensorOp>, Weak<EagerTensorRecord>>>> {
3067 self.value_records.lock().map_err(|_| {
3068 Error::runtime_state(
3069 "eager_value_registry",
3070 ErrorPhase::Execution,
3071 "lock poisoned",
3072 )
3073 })
3074 }
3075
3076 fn with_rules_and_cache(
3077 semantic_extension_rules: SemanticExtensionRuleSet,
3078 ad_transform_cache: Arc<AdTransformCache>,
3079 ) -> Result<Self> {
3080 let runtime = Runtime::builder()
3081 .build()
3082 .map_err(|source| runtime_config_error("EagerRuntime::new", source))?;
3083 Ok(Self {
3084 id: ContextId::fresh(),
3085 runtime,
3086 extension_install_lock: Mutex::new(()),
3087 semantic_extension_rules,
3088 grad_slots: Mutex::new(HashMap::new()),
3089 value_records: Mutex::new(HashMap::new()),
3090 ad_transform_cache,
3091 prepared_derivative_cache: Mutex::new(PreparedDerivativeCache::default()),
3092 #[cfg(test)]
3093 semantic_replays: AtomicUsize::new(0),
3094 })
3095 }
3096
3097 /// Create a shared eager execution context.
3098 ///
3099 /// The context stores no engine: every operation runs on the engine the
3100 /// caller passes in.
3101 ///
3102 /// # Examples
3103 ///
3104 /// ```
3105 /// use tenferro_ad::EagerRuntime;
3106 ///
3107 /// let ctx = EagerRuntime::new()?;
3108 /// assert_eq!(std::sync::Arc::strong_count(&ctx), 1);
3109 /// # Ok::<(), tenferro_ad::Error>(())
3110 /// ```
3111 ///
3112 /// # Errors
3113 ///
3114 /// Returns [`Error::RuntimeStateSource`] when the prepared-program runtime
3115 /// cannot be configured, preserving the underlying [`RuntimeConfigError`].
3116 pub fn new() -> Result<Arc<Self>> {
3117 Ok(Arc::new(Self::with_rules_and_cache(
3118 SemanticExtensionRuleSet::default(),
3119 Arc::new(AdTransformCache::new()),
3120 )?))
3121 }
3122
3123 /// Create a shared eager execution context that uses the semantic
3124 /// extension rules and AD transform cache of `ad`.
3125 ///
3126 /// # Examples
3127 ///
3128 /// ```
3129 /// use tenferro_ad::{AdContext, EagerRuntime};
3130 ///
3131 /// let ad = AdContext::builder().build().unwrap();
3132 /// let ctx = EagerRuntime::with_ad_context(&ad)?;
3133 /// assert_eq!(std::sync::Arc::strong_count(&ctx), 1);
3134 /// # Ok::<(), tenferro_ad::Error>(())
3135 /// ```
3136 ///
3137 /// # Errors
3138 ///
3139 /// Returns [`Error::RuntimeStateSource`] when the prepared-program runtime
3140 /// cannot be configured.
3141 pub fn with_ad_context(ad: &AdContext) -> Result<Arc<Self>> {
3142 Ok(Arc::new(Self::with_rules_and_cache(
3143 ad.semantic_extension_rules().clone(),
3144 ad.ad_transform_cache(),
3145 )?))
3146 }
3147
3148 /// Register the kind of `engine` with this runtime if it is not registered
3149 /// yet, and return its target.
3150 pub(crate) fn ensure_engine(&self, engine: &mut dyn ExecutionEngine) -> Result<EngineTarget> {
3151 let target = engine.target();
3152 let snapshot = self
3153 .runtime
3154 .snapshot()
3155 .map_err(|source| runtime_state_source("EagerRuntime::ensure_engine", source))?;
3156 if let Some(registered) = snapshot.engine(target.engine_id()) {
3157 if registered.context_identity() != target.context_identity() {
3158 return Err(Error::unsupported(
3159 "EagerRuntime::ensure_engine",
3160 ErrorPhase::Execution,
3161 format!(
3162 "engine id {:?} is registered for a different engine type",
3163 target.engine_id()
3164 ),
3165 ));
3166 }
3167 return Ok(target);
3168 }
3169 let registration = engine_kind_registration(engine)
3170 .ok_or_else(|| unregisterable_engine_error(target.engine_id()))?;
3171 let registration = registration
3172 .map_err(|source| runtime_config_error("EagerRuntime::ensure_engine", source))?;
3173 let _install_guard = self.lock_extension_install()?;
3174 let snapshot = self
3175 .runtime
3176 .snapshot()
3177 .map_err(|source| runtime_state_source("EagerRuntime::ensure_engine", source))?;
3178 if snapshot.engine(target.engine_id()).is_none() {
3179 self.runtime
3180 .reconfigure(|edit| {
3181 edit.register_engine(registration)?;
3182 Ok(())
3183 })
3184 .map_err(|source| runtime_state_source("EagerRuntime::ensure_engine", source))?;
3185 }
3186 Ok(target)
3187 }
3188
3189 /// Return an opaque identifier for this context.
3190 ///
3191 /// # Examples
3192 ///
3193 /// ```
3194 /// use tenferro_ad::{EagerRuntime};
3195 ///
3196 /// let ctx = EagerRuntime::new()?;
3197 /// assert_ne!(ctx.id(), EagerRuntime::new()?.id());
3198 /// # Ok::<(), tenferro_ad::Error>(())
3199 /// ```
3200 pub fn id(&self) -> ContextId {
3201 self.id
3202 }
3203
3204 /// Disable eager operation recording on the current thread until the guard is dropped.
3205 ///
3206 /// This is useful for optimizer updates, metric calculations, and other
3207 /// eager computations that should not become part of the AD tape.
3208 ///
3209 /// # Examples
3210 ///
3211 /// ```
3212 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3213 ///
3214 /// let ctx = EagerRuntime::new()?;
3215 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64]).unwrap())?;
3216 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
3217 /// let _guard = ctx.no_grad();
3218 /// s.mul(&x, &x)
3219 /// })?;
3220 /// assert!(!y.tracks_grad());
3221 /// # Ok::<(), tenferro_ad::Error>(())
3222 /// ```
3223 pub fn no_grad(&self) -> EagerNoGradGuard {
3224 EAGER_NO_GRAD_DEPTH.with(|depth| {
3225 depth.set(depth.get().saturating_add(1));
3226 });
3227 EagerNoGradGuard {
3228 active: true,
3229 _not_send: PhantomData,
3230 }
3231 }
3232
3233 /// Keep semantic-trace recording active for untracked intermediates.
3234 ///
3235 /// See [`EagerTraceCaptureGuard`] for the full contract and an example.
3236 pub fn capture_trace(&self) -> EagerTraceCaptureGuard {
3237 EAGER_CAPTURE_DEPTH.with(|depth| {
3238 depth.set(depth.get().saturating_add(1));
3239 });
3240 EagerTraceCaptureGuard {
3241 active: true,
3242 _not_send: PhantomData,
3243 }
3244 }
3245
3246 /// Install or replace one extension module on this eager context's runtime.
3247 ///
3248 /// Eager extension wrappers call this as an idempotent "ensure installed"
3249 /// step. When the exact module instance (same module ID and allocation) is
3250 /// already installed, this is a read-only no-op that returns the current
3251 /// runtime epoch without acquiring the install lock or reconfiguring. The
3252 /// cold or replacement paths keep the transactional install-or-replace
3253 /// behavior, serialized so parallel first-use of the same extension family
3254 /// cannot publish over another thread's base snapshot.
3255 ///
3256 /// # Errors
3257 ///
3258 /// Returns [`tenferro_runtime::Error::RuntimeState`] when runtime
3259 /// reconfiguration fails or the extension module transaction is invalid.
3260 pub fn install_extension_module(
3261 &self,
3262 module: Arc<dyn ExtensionModule>,
3263 ) -> Result<RuntimeEpoch> {
3264 let snapshot = self.runtime.snapshot().map_err(|source| {
3265 runtime_state_source("EagerRuntime::install_extension_module", source)
3266 })?;
3267 if snapshot.has_extension_module_identical(&module) {
3268 return Ok(snapshot.epoch());
3269 }
3270 let _install_guard = self.lock_extension_install()?;
3271 self.runtime
3272 .reconfigure(|edit| {
3273 edit.replace_extension_module(module)?;
3274 Ok(())
3275 })
3276 .map_err(|source| {
3277 runtime_state_source("EagerRuntime::install_extension_module", source)
3278 })
3279 }
3280
3281 pub(crate) fn ensure_extension_module_for_engine(
3282 &self,
3283 module: Arc<dyn ExtensionModule>,
3284 family_id: &'static str,
3285 engine_id: &EngineId,
3286 ) -> Result<RuntimeEpoch> {
3287 let snapshot = self.runtime.snapshot().map_err(|source| {
3288 runtime_state_source("EagerRuntime::ensure_extension_module_for_engine", source)
3289 })?;
3290 if snapshot.has_extension_module_engine(module.module_id(), family_id, engine_id) {
3291 return Ok(snapshot.epoch());
3292 }
3293 let _install_guard = self.lock_extension_install()?;
3294 self.runtime
3295 .reconfigure(|edit| {
3296 edit.ensure_extension_module_for_engine(module, family_id, engine_id)?;
3297 Ok(())
3298 })
3299 .map_err(|source| {
3300 runtime_state_source("EagerRuntime::ensure_extension_module_for_engine", source)
3301 })
3302 }
3303
3304 pub(crate) fn runtime(&self) -> &Runtime {
3305 &self.runtime
3306 }
3307
3308 /// The extension target for `engine`, registering its kind first.
3309 pub(crate) fn eager_extension_target(
3310 &self,
3311 engine: &mut dyn ExecutionEngine,
3312 ) -> Result<EagerExtensionTarget> {
3313 let target = self.ensure_engine(engine)?;
3314 let backend_kind = eager_extension_backend_kind(&target).ok_or_else(|| {
3315 Error::unsupported(
3316 "EagerRuntime::eager_extension_target",
3317 ErrorPhase::Execution,
3318 "this engine kind has no eager extension target",
3319 )
3320 })?;
3321 let target = EagerExtensionTarget {
3322 engine_id: target.engine_id().clone(),
3323 backend_kind,
3324 };
3325 validate_eager_extension_target(&self.runtime, &target)?;
3326 Ok(target)
3327 }
3328
3329 /// Clear every cache owned by this eager context.
3330 ///
3331 /// # Examples
3332 ///
3333 /// ```
3334 /// use tenferro_ad::{EagerRuntime};
3335 ///
3336 /// let ctx = EagerRuntime::new()?;
3337 /// ctx.clear_caches()?;
3338 /// assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);
3339 /// assert_eq!(ctx.cache_stats()?.prepared_derivatives.entries, 0);
3340 /// # Ok::<(), tenferro_ad::Error>(())
3341 /// ```
3342 ///
3343 /// # Errors
3344 ///
3345 /// Returns [`tenferro_runtime::Error::RuntimeState`] when either the
3346 /// extension cache or AD-transform cache is poisoned.
3347 pub fn clear_caches(&self) -> Result<()> {
3348 self.clear_ad_transform_caches()?;
3349 self.clear_prepared_derivative_cache()?;
3350 Ok(())
3351 }
3352
3353 /// Clear prepared derivative program cache entries.
3354 ///
3355 /// # Examples
3356 ///
3357 /// ```rust
3358 /// use tenferro_ad::EagerRuntime;
3359 ///
3360 /// let ctx = EagerRuntime::new()?;
3361 /// ctx.clear_prepared_derivative_cache()?;
3362 /// assert_eq!(ctx.cache_stats()?.prepared_derivatives.entries, 0);
3363 /// # Ok::<(), tenferro_ad::Error>(())
3364 /// ```
3365 ///
3366 /// # Errors
3367 ///
3368 /// Returns [`tenferro_runtime::Error::RuntimeState`] if the prepared
3369 /// derivative cache lock is poisoned.
3370 pub fn clear_prepared_derivative_cache(&self) -> Result<()> {
3371 self.lock_prepared_derivative_cache()?.clear();
3372 Ok(())
3373 }
3374
3375 /// Return eager runtime cache-entry and retained-byte stats.
3376 ///
3377 /// # Examples
3378 ///
3379 /// ```
3380 /// use tenferro_ad::{EagerRuntime};
3381 ///
3382 /// let ctx = EagerRuntime::new()?;
3383 /// let stats = ctx.cache_stats()?;
3384 /// assert_eq!(stats.ad_transforms.entries, 0);
3385 /// assert_eq!(stats.prepared_derivatives.entries, 0);
3386 /// # Ok::<(), tenferro_ad::Error>(())
3387 /// ```
3388 ///
3389 /// # Errors
3390 ///
3391 /// Returns [`tenferro_runtime::Error::RuntimeState`] when a cache or
3392 /// AD-transform cache lock is poisoned.
3393 pub fn cache_stats(&self) -> Result<EagerRuntimeCacheStats> {
3394 Ok(EagerRuntimeCacheStats {
3395 ad_transforms: self.ad_transform_cache.stats()?,
3396 prepared_derivatives: self.lock_prepared_derivative_cache()?.stats(),
3397 })
3398 }
3399
3400 /// Return the AD transform cache retention limits.
3401 ///
3402 /// # Examples
3403 ///
3404 /// ```
3405 /// use tenferro_ad::EagerRuntime;
3406 ///
3407 /// let ctx = EagerRuntime::new()?;
3408 /// assert!(ctx.ad_transform_cache_limits()?.max_entries().get() > 0);
3409 /// # Ok::<(), tenferro_ad::Error>(())
3410 /// ```
3411 ///
3412 /// # Errors
3413 ///
3414 /// Returns [`tenferro_runtime::Error::RuntimeState`] if the AD-transform
3415 /// cache lock is poisoned.
3416 pub fn ad_transform_cache_limits(&self) -> Result<AdTransformCacheLimits> {
3417 self.ad_transform_cache.limits()
3418 }
3419
3420 /// Replace AD transform cache retention limits.
3421 ///
3422 /// # Examples
3423 ///
3424 /// ```
3425 /// use std::num::NonZeroUsize;
3426 /// use tenferro_ad::{AdTransformCacheLimits, EagerRuntime};
3427 ///
3428 /// let ctx = EagerRuntime::new()?;
3429 /// let limits = AdTransformCacheLimits::new(NonZeroUsize::new(1).unwrap());
3430 /// ctx.set_ad_transform_cache_limits(limits)?;
3431 /// assert_eq!(ctx.ad_transform_cache_limits()?, limits);
3432 /// # Ok::<(), tenferro_ad::Error>(())
3433 /// ```
3434 ///
3435 /// # Errors
3436 ///
3437 /// Returns [`tenferro_runtime::Error::RuntimeState`] if the AD-transform
3438 /// cache lock is poisoned while updating limits.
3439 pub fn set_ad_transform_cache_limits(&self, limits: AdTransformCacheLimits) -> Result<()> {
3440 self.ad_transform_cache.set_limits(limits)
3441 }
3442
3443 /// Clear AD transform cache entries visible through this eager runtime.
3444 ///
3445 /// # Examples
3446 ///
3447 /// ```
3448 /// use tenferro_ad::EagerRuntime;
3449 ///
3450 /// let ctx = EagerRuntime::new()?;
3451 /// ctx.clear_ad_transform_caches()?;
3452 /// assert_eq!(ctx.cache_stats()?.ad_transforms.entries, 0);
3453 /// # Ok::<(), tenferro_ad::Error>(())
3454 /// ```
3455 ///
3456 /// # Errors
3457 ///
3458 /// Returns [`tenferro_runtime::Error::RuntimeState`] if the AD-transform
3459 /// cache lock is poisoned while clearing entries.
3460 pub fn clear_ad_transform_caches(&self) -> Result<()> {
3461 self.ad_transform_cache.clear()
3462 }
3463
3464 /// Return prepared derivative cache retention limits.
3465 ///
3466 /// # Examples
3467 ///
3468 /// ```rust
3469 /// use tenferro_ad::EagerRuntime;
3470 ///
3471 /// let ctx = EagerRuntime::new()?;
3472 /// assert!(ctx.prepared_derivative_cache_limits()?.max_entries().get() > 0);
3473 /// # Ok::<(), tenferro_ad::Error>(())
3474 /// ```
3475 ///
3476 /// # Errors
3477 ///
3478 /// Returns [`tenferro_runtime::Error::RuntimeState`] if the prepared
3479 /// derivative cache lock is poisoned.
3480 pub fn prepared_derivative_cache_limits(&self) -> Result<AdTransformCacheLimits> {
3481 Ok(self.lock_prepared_derivative_cache()?.limits())
3482 }
3483
3484 /// Replace prepared derivative cache retention limits.
3485 ///
3486 /// # Examples
3487 ///
3488 /// ```rust
3489 /// use std::num::NonZeroUsize;
3490 /// use tenferro_ad::{AdTransformCacheLimits, EagerRuntime};
3491 ///
3492 /// let ctx = EagerRuntime::new()?;
3493 /// let limits = AdTransformCacheLimits::new(NonZeroUsize::new(1).unwrap());
3494 /// ctx.set_prepared_derivative_cache_limits(limits)?;
3495 /// assert_eq!(ctx.prepared_derivative_cache_limits()?, limits);
3496 /// # Ok::<(), tenferro_ad::Error>(())
3497 /// ```
3498 ///
3499 /// # Errors
3500 ///
3501 /// Returns [`tenferro_runtime::Error::RuntimeState`] if the prepared
3502 /// derivative cache lock is poisoned.
3503 pub fn set_prepared_derivative_cache_limits(
3504 &self,
3505 limits: AdTransformCacheLimits,
3506 ) -> Result<()> {
3507 self.lock_prepared_derivative_cache()?.set_limits(limits);
3508 Ok(())
3509 }
3510
3511 /// Run eager operations on `engine`.
3512 ///
3513 /// The callback receives an [`EagerSession`] that pairs this runtime with
3514 /// the borrowed engine; operations recorded through it are differentiable.
3515 /// Nothing is entered or locked: the engine is simply borrowed for the
3516 /// callback.
3517 ///
3518 /// # Examples
3519 ///
3520 /// ```
3521 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3522 /// use tenferro_cpu::CpuEngine;
3523 ///
3524 /// let ctx = EagerRuntime::new()?;
3525 /// let mut engine = CpuEngine::serial();
3526 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?)?;
3527 /// let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64])?)?;
3528 /// let z = ctx.with_eager_session(&mut engine, |s| s.add(&x, &y))?;
3529 /// assert_eq!(z.value()?.as_slice::<f64>()?, &[3.0]);
3530 /// # Ok::<(), tenferro_ad::Error>(())
3531 /// ```
3532 ///
3533 /// # Errors
3534 ///
3535 /// Returns [`Error::Unsupported`] when the engine kind cannot be registered
3536 /// with this runtime or its context identity conflicts with the existing
3537 /// registration, [`Error::RuntimeStateSource`] when the runtime snapshot or
3538 /// engine registration state is unavailable, and the callback's own error
3539 /// unchanged.
3540 pub fn with_eager_session<T, E: From<Error>>(
3541 self: &Arc<Self>,
3542 engine: &mut dyn ExecutionEngine,
3543 f: impl FnOnce(&mut EagerSession<'_>) -> std::result::Result<T, E>,
3544 ) -> std::result::Result<T, E> {
3545 self.ensure_engine(engine).map_err(E::from)?;
3546 f(&mut EagerSession {
3547 runtime: self,
3548 engine,
3549 })
3550 }
3551
3552 /// Run a compiled program on `engine` through this runtime.
3553 pub(crate) fn run_program(
3554 &self,
3555 engine: &mut dyn ExecutionEngine,
3556 program: &CompiledGraph,
3557 inputs: &[TensorRead<'_>],
3558 ) -> Result<Vec<Tensor>> {
3559 let target = self.ensure_engine(engine)?;
3560 let prepared = self
3561 .runtime
3562 .prepare(program, inputs, std::slice::from_ref(&target))?;
3563 run_prepared_on(&self.runtime, engine, &prepared, inputs)
3564 }
3565
3566 pub(crate) fn exec_extension_outputs_read(
3567 &self,
3568 engine: &mut dyn ExecutionEngine,
3569 op: &Arc<dyn tenferro_ops::ext_op::ExtensionOp>,
3570 inputs: &[TensorRead<'_>],
3571 ) -> Result<Vec<Tensor>> {
3572 self.ensure_engine(engine)?;
3573 profile_eager_op_section("exec_extension_outputs_read.exec_op", || {
3574 exec_extension_op_on_tensor_reads(op, inputs, engine, &self.runtime)
3575 })
3576 }
3577
3578 #[cfg(test)]
3579 pub(crate) fn exec_standard_graph_outputs(
3580 &self,
3581 engine: &mut dyn ExecutionEngine,
3582 graph: &Graph<StdTensorOp>,
3583 initial_data: HashMap<ValueKey<StdTensorOp>, Tensor>,
3584 ) -> Result<EagerGraphExecution> {
3585 let mut all_values = initial_data;
3586
3587 profile_eager_op_section("exec_graph.run", || {
3588 let exec: &mut dyn Engine = engine;
3589 (|| -> Result<()> {
3590 for op_node in graph.operations() {
3591 let outputs = {
3592 let input_values = op_node
3593 .inputs
3594 .iter()
3595 .map(|input| {
3596 let key = match input {
3597 ValueRef::Local(local_id) => &graph.values()[*local_id].key,
3598 ValueRef::External(key) => key,
3599 };
3600 all_values.get(key).ok_or_else(|| {
3601 Error::Internal(format!(
3602 "standard graph eager execution missing value for {key:?}"
3603 ))
3604 })
3605 })
3606 .collect::<Result<Vec<_>>>()?;
3607 let input_reads = input_values
3608 .iter()
3609 .map(|value| TensorRead::from_tensor(value))
3610 .collect::<Vec<_>>();
3611 exec_standard_op_on_tensor_reads_in_session(
3612 &op_node.operation,
3613 &input_reads,
3614 exec,
3615 )?
3616 };
3617
3618 if outputs.len() != op_node.outputs.len() {
3619 return Err(Error::Internal(format!(
3620 "standard graph eager execution expected {} outputs for {:?}, got {}",
3621 op_node.outputs.len(),
3622 op_node.operation,
3623 outputs.len()
3624 )));
3625 }
3626
3627 for (output_id, output) in op_node.outputs.iter().zip(outputs) {
3628 let key = graph.values()[*output_id].key.clone();
3629 all_values.insert(key, output);
3630 }
3631 }
3632 Ok(())
3633 })()
3634 })?;
3635
3636 let outputs = graph
3637 .outputs()
3638 .iter()
3639 .map(|&output_id| {
3640 let key = &graph.values()[output_id].key;
3641 all_values
3642 .get(key)
3643 .ok_or_else(|| {
3644 Error::Internal(format!(
3645 "standard graph eager execution missing graph output {key:?}"
3646 ))
3647 })?
3648 .duplicate()
3649 .map_err(Error::from)
3650 })
3651 .collect::<Result<Vec<_>>>()?;
3652
3653 Ok(EagerGraphExecution { outputs })
3654 }
3655
3656 pub(crate) fn try_register_grad_slot(
3657 &self,
3658 key: &ValueKey<StdTensorOp>,
3659 slot: &GradSlot,
3660 ) -> Result<()> {
3661 insert_pruning_dead(
3662 &mut *self.lock_grad_slots()?,
3663 key.clone(),
3664 Arc::downgrade(slot),
3665 );
3666 Ok(())
3667 }
3668
3669 pub(crate) fn try_register_value_record(
3670 &self,
3671 key: &ValueKey<StdTensorOp>,
3672 record: &Arc<EagerTensorRecord>,
3673 ) -> Result<()> {
3674 insert_pruning_dead(
3675 &mut *self.lock_value_records()?,
3676 key.clone(),
3677 Arc::downgrade(record),
3678 );
3679 Ok(())
3680 }
3681
3682 pub(crate) fn value_record(
3683 &self,
3684 key: &ValueKey<StdTensorOp>,
3685 ) -> Result<Option<Arc<EagerTensorRecord>>> {
3686 let mut records = self.lock_value_records()?;
3687 let Some(record) = records.get(key).cloned() else {
3688 return Ok(None);
3689 };
3690 match record.upgrade() {
3691 Some(record) => Ok(Some(record)),
3692 None => {
3693 records.remove(key);
3694 Ok(None)
3695 }
3696 }
3697 }
3698
3699 /// Clear all live gradient slots tracked by this context.
3700 ///
3701 /// This resets the stored gradients to `None` without unregistering the
3702 /// tensors, so future `EagerSession::backward` calls can accumulate again.
3703 ///
3704 /// # Examples
3705 ///
3706 /// ```
3707 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3708 ///
3709 /// let ctx = EagerRuntime::new()?;
3710 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
3711 /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![4.0_f64, 5.0, 6.0]).unwrap()).unwrap();
3712 /// let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
3713 /// let product = s.mul(&x, &y)?;
3714 /// s.reduce_sum(&product, Some(&[0]))
3715 /// })?;
3716 /// let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
3717 ///
3718 /// ctx.clear_grads()?;
3719 ///
3720 /// assert!(x.grad()?.is_none());
3721 /// assert!(y.grad()?.is_none());
3722 /// # Ok::<(), tenferro_ad::Error>(())
3723 /// ```
3724 ///
3725 /// # Errors
3726 ///
3727 /// Returns [`tenferro_runtime::Error::RuntimeState`] if a gradient-slot
3728 /// lock is poisoned while clearing live gradients.
3729 pub fn clear_grads(&self) -> Result<()> {
3730 let live_slots = {
3731 let mut live_slots = Vec::new();
3732 self.lock_grad_slots()?.retain(|_, slot| {
3733 if let Some(slot) = slot.upgrade() {
3734 live_slots.push(slot);
3735 true
3736 } else {
3737 false
3738 }
3739 });
3740 live_slots
3741 };
3742
3743 let mut poisoned_slot = false;
3744 for slot in live_slots {
3745 match slot.lock() {
3746 Ok(mut current) => {
3747 *current = None;
3748 }
3749 Err(_) => {
3750 poisoned_slot = true;
3751 }
3752 }
3753 }
3754 if poisoned_slot {
3755 return Err(Error::runtime_state(
3756 "eager_gradient_slot",
3757 ErrorPhase::Execution,
3758 "lock poisoned",
3759 ));
3760 }
3761 Ok(())
3762 }
3763
3764 /// Import a concrete tensor into this context as an untracked constant.
3765 ///
3766 /// The returned tensor does not participate in gradient tracking.
3767 /// Use this for fixed masks, quadrature weights, physical constants,
3768 /// and other data that should not receive gradients. Like
3769 /// [`EagerSession::constant_from`], it performs no host/device transfer;
3770 /// use [`EagerSession::constant_from_host`] to upload host data into a
3771 /// device runtime.
3772 ///
3773 /// # Examples
3774 ///
3775 /// ```
3776 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3777 ///
3778 /// let ctx = EagerRuntime::new()?;
3779 /// let c = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
3780 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap())?;
3781 /// let z = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.add(&x, &c))?;
3782 ///
3783 /// assert_eq!(z.value()?.as_slice::<f64>().unwrap(), &[4.0, 6.0]);
3784 /// # Ok::<(), tenferro_ad::Error>(())
3785 /// ```
3786 ///
3787 /// # Errors
3788 ///
3789 /// Returns [`tenferro_runtime::Error::RuntimeState`] when metadata cannot
3790 /// be registered or the backend lock is poisoned.
3791 pub fn constant_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor> {
3792 EagerTensor::new_leaf(Arc::clone(self), tensor, false)
3793 }
3794
3795 /// Import a concrete tensor into this context as a trainable variable.
3796 ///
3797 /// The returned tensor participates in gradient tracking; its gradient
3798 /// slot is registered in this context.
3799 ///
3800 /// # Examples
3801 ///
3802 /// ```
3803 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
3804 ///
3805 /// let ctx = EagerRuntime::new()?;
3806 /// let p = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap())?;
3807 /// let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
3808 /// let y = s.exp(&p)?;
3809 /// s.reduce_sum(&y, Some(&[0]))
3810 /// })?;
3811 /// let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
3812 ///
3813 /// let grad = p.grad().unwrap().unwrap();
3814 /// assert_eq!(grad.shape(), &[2]);
3815 /// # Ok::<(), tenferro_ad::Error>(())
3816 /// ```
3817 ///
3818 /// # Errors
3819 ///
3820 /// Returns [`tenferro_runtime::Error::RuntimeState`] when gradient metadata
3821 /// or the eager backend state cannot be registered.
3822 pub fn variable_from(self: &Arc<Self>, tensor: Tensor) -> Result<EagerTensor> {
3823 EagerTensor::new_leaf(Arc::clone(self), tensor, true)
3824 }
3825
3826 fn store_grads(
3827 &self,
3828 cotangents: &HashMap<ValueKey<StdTensorOp>, Tensor>,
3829 session: &mut dyn Engine,
3830 ) -> Result<()> {
3831 let mut updates = Vec::new();
3832
3833 {
3834 let mut slots = self.lock_grad_slots()?;
3835 slots.retain(|key, slot| {
3836 let Some(slot) = slot.upgrade() else {
3837 return false;
3838 };
3839
3840 if let Some(incoming) = cotangents.get(key) {
3841 updates.push((slot, incoming));
3842 }
3843
3844 true
3845 });
3846 }
3847
3848 for (slot, incoming) in updates {
3849 let mut current = slot.lock().map_err(|_| {
3850 Error::runtime_state(
3851 "eager_gradient_slot",
3852 ErrorPhase::Execution,
3853 "lock poisoned",
3854 )
3855 })?;
3856 let next = match current.as_ref() {
3857 Some(existing) => {
3858 let existing_read = existing.tensor_read("EagerRuntime::store_grads")?;
3859 let incoming_read = TensorRead::from_tensor(incoming);
3860 let tensor = session
3861 .add_read(existing_read, incoming_read)
3862 .map_err(Error::from)?;
3863 AdValueRecord::from_tensor(tensor, "EagerRuntime::store_grads")?
3864 }
3865 None => {
3866 let duplicate = session
3867 .to_contiguous_read(TensorRead::from_tensor(incoming))
3868 .map_err(Error::from)?;
3869 AdValueRecord::from_tensor(duplicate, "EagerRuntime::store_grads")?
3870 }
3871 };
3872 *current = Some(next);
3873 }
3874
3875 Ok(())
3876 }
3877}
3878
3879#[derive(Clone, Debug, PartialEq, Eq, Hash)]
3880struct PreparedDerivativeCacheKey {
3881 /// Engines with the same target share prepared derivative programs.
3882 target: EngineTarget,
3883 semantic_fingerprint: SemanticFingerprint,
3884 runtime_epoch: RuntimeEpoch,
3885 active_inputs: Box<[bool]>,
3886 input_metadata: Box<[ProgramValueMetadata]>,
3887}
3888
3889/// Cached prepared derivative: program + index metadata.
3890#[derive(Debug)]
3891struct PreparedDerivative {
3892 program: Arc<CompiledGraph>,
3893 execution_program: Arc<CompiledGraph>,
3894 saved_input_indices: Vec<usize>,
3895 prepared: Arc<Prepared>,
3896 seed_input_index: usize,
3897 derivative_output_indices: Box<[Option<usize>]>,
3898}
3899
3900#[derive(Debug)]
3901struct PreparedDerivativeCache {
3902 limits: AdTransformCacheLimits,
3903 entries: LruCache<PreparedDerivativeCacheKey, PreparedDerivativeCacheEntry>,
3904 stats: CacheStats,
3905}
3906
3907impl PreparedDerivativeCache {
3908 fn limits(&self) -> AdTransformCacheLimits {
3909 self.limits
3910 }
3911
3912 fn set_limits(&mut self, limits: AdTransformCacheLimits) {
3913 self.limits = limits;
3914 self.evict_to_limits();
3915 }
3916
3917 fn clear(&mut self) {
3918 let clears = self.stats.clears.saturating_add(1);
3919 self.entries.clear();
3920 self.stats = CacheStats {
3921 clears,
3922 ..CacheStats::empty()
3923 };
3924 }
3925
3926 fn stats(&self) -> CacheStats {
3927 self.stats
3928 }
3929
3930 fn get(&mut self, key: &PreparedDerivativeCacheKey) -> Option<Arc<PreparedDerivative>> {
3931 match self.entries.get(key) {
3932 Some(entry) => {
3933 self.stats.hits = self.stats.hits.saturating_add(1);
3934 Some(Arc::clone(&entry.value))
3935 }
3936 None => {
3937 self.stats.misses = self.stats.misses.saturating_add(1);
3938 None
3939 }
3940 }
3941 }
3942
3943 fn insert(&mut self, key: PreparedDerivativeCacheKey, value: Arc<PreparedDerivative>) {
3944 let retained_bytes = prepared_derivative_cache_entry_retained_bytes(&key, value.as_ref());
3945 let entry = PreparedDerivativeCacheEntry {
3946 value,
3947 retained_bytes,
3948 };
3949 self.stats.retained_bytes = self.stats.retained_bytes.saturating_add(retained_bytes);
3950 if let Some((_old_key, old_entry)) = self.entries.push(key, entry) {
3951 self.stats.retained_bytes = self
3952 .stats
3953 .retained_bytes
3954 .saturating_sub(old_entry.retained_bytes);
3955 }
3956 self.stats.entries = self.entries.len();
3957 self.evict_to_limits();
3958 }
3959
3960 fn evict_to_limits(&mut self) {
3961 while self.entries.len() > self.limits.max_entries().get()
3962 || self
3963 .limits
3964 .max_retained_bytes()
3965 .is_some_and(|limit| self.stats.retained_bytes > limit.get())
3966 {
3967 let Some((_key, entry)) = self.entries.pop_lru() else {
3968 break;
3969 };
3970 self.stats.retained_bytes = self
3971 .stats
3972 .retained_bytes
3973 .saturating_sub(entry.retained_bytes);
3974 self.stats.evictions = self.stats.evictions.saturating_add(1);
3975 }
3976 self.stats.entries = self.entries.len();
3977 }
3978}
3979
3980impl Default for PreparedDerivativeCache {
3981 fn default() -> Self {
3982 Self {
3983 limits: AdTransformCacheLimits::default(),
3984 entries: LruCache::unbounded(),
3985 stats: CacheStats::empty(),
3986 }
3987 }
3988}
3989
3990#[derive(Debug)]
3991struct PreparedDerivativeCacheEntry {
3992 value: Arc<PreparedDerivative>,
3993 retained_bytes: usize,
3994}
3995
3996fn prepared_derivative_cache_entry_retained_bytes(
3997 key: &PreparedDerivativeCacheKey,
3998 value: &PreparedDerivative,
3999) -> usize {
4000 size_of::<PreparedDerivativeCacheKey>()
4001 .saturating_add(size_of_val(key.active_inputs.as_ref()))
4002 .saturating_add(size_of_val(value.derivative_output_indices.as_ref()))
4003 .saturating_add(size_of_val(value.saved_input_indices.as_slice()))
4004 .saturating_add(compiled_graph_retained_bytes(
4005 value.execution_program.as_ref(),
4006 ))
4007 .saturating_add(
4008 key.input_metadata
4009 .len()
4010 .saturating_mul(size_of::<ProgramValueMetadata>()),
4011 )
4012 .saturating_add(size_of::<PreparedDerivative>())
4013 .saturating_add(compiled_graph_retained_bytes(value.program.as_ref()))
4014 .saturating_add(prepared_compiled_graph_retained_bytes(
4015 value.prepared.as_ref(),
4016 value.program.as_ref(),
4017 ))
4018}
4019
4020fn prepared_compiled_graph_retained_bytes(
4021 prepared: &Prepared,
4022 derivative_program: &CompiledGraph,
4023) -> usize {
4024 size_of_val(prepared).saturating_add(compiled_graph_retained_bytes(derivative_program))
4025}
4026
4027fn compiled_graph_retained_bytes(program: &CompiledGraph) -> usize {
4028 size_of::<CompiledGraph>()
4029 .saturating_add(size_of_val(program.input_keys()))
4030 .saturating_add(program.bindings().len().saturating_mul(size_of::<usize>()))
4031 .saturating_add(semantic_program_retained_bytes(program.program()))
4032}
4033
4034fn semantic_program_retained_bytes(program: &SemanticProgram) -> usize {
4035 size_of::<SemanticProgram>()
4036 .saturating_add(size_of_val(program.inputs()))
4037 .saturating_add(size_of_val(program.outputs()))
4038 .saturating_add(
4039 program
4040 .operations()
4041 .len()
4042 .saturating_mul(size_of::<usize>()),
4043 )
4044 .saturating_add(
4045 program
4046 .shape_guards()
4047 .len()
4048 .saturating_mul(size_of::<usize>()),
4049 )
4050}
4051
4052fn semantic_eager_vjp_many(
4053 ctx: &Arc<EagerRuntime>,
4054 engine: &mut dyn ExecutionEngine,
4055 output: &EagerTensor,
4056 wrts: &[&EagerTensor],
4057 cotangent: &EagerTensor,
4058) -> Result<Vec<Option<EagerTensor>>> {
4059 if wrts.is_empty() {
4060 return Ok(Vec::new());
4061 }
4062 let Some(output_semantic) = output.semantic.as_ref() else {
4063 return Ok(vec![None; wrts.len()]);
4064 };
4065 let saved = output
4066 .trace
4067 .as_ref()
4068 .map(EagerTrace::collect)
4069 .unwrap_or_default();
4070 // One replay for this backward pass. Residual roots keep the semantic
4071 // producers available to differentiation; only the execution-only
4072 // derivative replaces their numerical values.
4073 let mut roots = Vec::with_capacity(1 + saved.len());
4074 roots.push(output_semantic.clone());
4075 roots.extend(saved.iter().map(|value| value.semantic.clone()));
4076 let source = replay(&roots)?;
4077 #[cfg(test)]
4078 ctx.semantic_replays.fetch_add(1, Ordering::Relaxed);
4079 if source.outputs().len() != roots.len()
4080 || source.leaf_data().len() != source.frozen().program.inputs().len()
4081 {
4082 return Err(Error::Internal(
4083 "semantic eager VJP source has inconsistent inputs or outputs".into(),
4084 ));
4085 }
4086 let wrt_input_indices = wrts
4087 .iter()
4088 .map(|wrt| {
4089 wrt.semantic
4090 .as_ref()
4091 .and_then(|semantic| source.input_index_of(semantic))
4092 })
4093 .collect::<Vec<_>>();
4094 let mut active_inputs = vec![false; source.leaves().len()];
4095 for &index in wrt_input_indices.iter().flatten() {
4096 active_inputs[index] = true;
4097 }
4098 if !active_inputs.iter().any(|&active| active) {
4099 return Ok(vec![None; wrts.len()]);
4100 }
4101
4102 // One transform and execution for the complete active set shares primal
4103 // work and cotangents between leaves instead of replaying them per target.
4104 // S2: check prepared-derivative cache before AD transform + compile_frozen.
4105 let mut compiler = GraphCompiler::new();
4106 let target = ctx.ensure_engine(engine)?;
4107 let cache_key = PreparedDerivativeCacheKey {
4108 target: target.clone(),
4109 semantic_fingerprint: source.frozen().program.semantic_fingerprint(),
4110 runtime_epoch: ctx.runtime.epoch().map_err(|source| {
4111 Error::runtime_state_source("semantic_eager_vjp", ErrorPhase::Execution, source)
4112 })?,
4113 active_inputs: active_inputs.clone().into_boxed_slice(),
4114 input_metadata: source.frozen().input_metadata_with_bound_shapes(),
4115 };
4116 let prepared = { ctx.lock_prepared_derivative_cache()?.get(&cache_key) };
4117 let (
4118 seed_input_index,
4119 derivative_output_indices,
4120 derivative_program,
4121 execution_program,
4122 saved_input_indices,
4123 prepared_runtime,
4124 ) = if let Some(prepared) = prepared {
4125 (
4126 prepared.seed_input_index,
4127 prepared.derivative_output_indices.clone(),
4128 Arc::clone(&prepared.program),
4129 Arc::clone(&prepared.execution_program),
4130 prepared.saved_input_indices.clone(),
4131 Some(Arc::clone(&prepared.prepared)),
4132 )
4133 } else {
4134 let mut active_outputs = vec![false; source.outputs().len()];
4135 active_outputs[0] = true;
4136 let ad = AdContext::with_rules_and_transform_cache(
4137 ctx.semantic_extension_rules.clone(),
4138 Arc::clone(&ctx.ad_transform_cache),
4139 );
4140 let derivative = ad
4141 .vjp_program(source.frozen(), &active_inputs, &active_outputs)
4142 .map_err(|source| {
4143 Error::runtime_state_source("semantic_eager_vjp", ErrorPhase::GraphBuild, source)
4144 })?;
4145 let seed_input_index = derivative
4146 .derivative_input_indices()
4147 .first()
4148 .copied()
4149 .flatten();
4150 let Some(seed_input_index) = seed_input_index else {
4151 return Ok(vec![None; wrts.len()]);
4152 };
4153 let derivative_output_indices = derivative
4154 .derivative_output_indices()
4155 .to_vec()
4156 .into_boxed_slice();
4157 let program = Arc::new(compiler.compile_frozen_program(derivative.frozen())?);
4158 let (execution_program, saved_input_indices) = if saved.is_empty() {
4159 (Arc::clone(&program), Vec::new())
4160 } else {
4161 let (execution, indices) = crate::semantic_transform::semantic_vjp_with_saved_outputs(
4162 source.frozen(),
4163 &active_inputs,
4164 &active_outputs,
4165 &ctx.semantic_extension_rules,
4166 &(1..source.outputs().len()).collect::<Vec<_>>(),
4167 )
4168 .map_err(|source| {
4169 Error::runtime_state_source("semantic_eager_vjp", ErrorPhase::GraphBuild, source)
4170 })?;
4171 (
4172 Arc::new(compiler.compile_frozen_program(execution.frozen())?),
4173 indices,
4174 )
4175 };
4176 (
4177 seed_input_index,
4178 derivative_output_indices,
4179 program,
4180 execution_program,
4181 saved_input_indices,
4182 None,
4183 )
4184 };
4185
4186 let cotangent_tensor = Arc::new(RetainedValue::from_tensor(
4187 cotangent.duplicate_value_in_session(&mut *engine)?,
4188 ));
4189 let input_count = execution_program.input_count();
4190 let mut owned_inputs: Vec<Option<Tensor>> = (0..input_count).map(|_| None).collect();
4191 // Residuals, primal bindings and the seed are staged on the caller's engine.
4192 (|| -> Result<()> {
4193 let session: &mut dyn Engine = &mut *engine;
4194 for (value, &index) in saved.iter().zip(&saved_input_indices) {
4195 let read = value.value.tensor_read("eager residual")?;
4196 let Some(slot) = owned_inputs.get_mut(index) else {
4197 return Err(Error::Internal(format!(
4198 "semantic eager VJP residual index {index} is outside {input_count} inputs"
4199 )));
4200 };
4201 *slot = Some(session.to_contiguous_read(read)?);
4202 }
4203 for (source_input_index, data) in source.leaf_data().iter().enumerate() {
4204 let Some(slot) = owned_inputs.get_mut(source_input_index) else {
4205 return Err(Error::Internal(format!(
4206 "semantic eager VJP derivative program has no primal input slot {source_input_index}"
4207 )));
4208 };
4209 *slot = Some(copy_value_in_session(session, data)?);
4210 }
4211 let Some(slot) = owned_inputs.get_mut(seed_input_index) else {
4212 return Err(Error::Internal(format!(
4213 "semantic eager VJP seed input index {seed_input_index} is outside {input_count} inputs"
4214 )));
4215 };
4216 *slot = Some(copy_value_in_session(session, cotangent_tensor.as_ref())?);
4217 Ok(())
4218 })()?;
4219 let input_refs = owned_inputs
4220 .iter()
4221 .enumerate()
4222 .map(|(index, tensor)| {
4223 tensor.as_ref().ok_or_else(|| {
4224 Error::Internal(format!(
4225 "semantic eager VJP derivative input {index} was not populated"
4226 ))
4227 })
4228 })
4229 .collect::<Result<Vec<_>>>()?;
4230 let input_reads = input_refs
4231 .iter()
4232 .map(|tensor| TensorRead::from_tensor(tensor))
4233 .collect::<Vec<_>>();
4234 let prepared_runtime = if let Some(prepared_runtime) = prepared_runtime {
4235 prepared_runtime
4236 } else {
4237 let prepared_runtime = Arc::new(ctx.runtime.prepare(
4238 &execution_program,
4239 &input_reads,
4240 std::slice::from_ref(&target),
4241 )?);
4242 let entry = Arc::new(PreparedDerivative {
4243 program: Arc::clone(&derivative_program),
4244 execution_program: Arc::clone(&execution_program),
4245 saved_input_indices: saved_input_indices.clone(),
4246 prepared: Arc::clone(&prepared_runtime),
4247 seed_input_index,
4248 derivative_output_indices: derivative_output_indices.clone(),
4249 });
4250 ctx.lock_prepared_derivative_cache()?
4251 .insert(cache_key, entry);
4252 prepared_runtime
4253 };
4254 let mut outputs = run_prepared_on(&ctx.runtime, engine, &prepared_runtime, &input_reads)?
4255 .into_iter()
4256 .map(Some)
4257 .collect::<Vec<_>>();
4258 let cotangent_semantic = SemanticValue::leaf(
4259 next_input_key(),
4260 cotangent_tensor.dtype(),
4261 cotangent_tensor.shape().len(),
4262 Arc::clone(&cotangent_tensor),
4263 );
4264 let derivative_frozen = Arc::new(derivative_program.frozen_program().clone());
4265
4266 #[cfg(test)]
4267 EAGER_SEMANTIC_VJP_EXECUTIONS.fetch_add(1, Ordering::Relaxed);
4268
4269 wrts.iter()
4270 .zip(wrt_input_indices)
4271 .map(|(_wrt, input_index)| {
4272 let Some(derivative_output_index) = input_index
4273 .and_then(|index| derivative_output_indices.get(index).copied().flatten())
4274 else {
4275 return Ok(None);
4276 };
4277 let result = outputs
4278 .get_mut(derivative_output_index)
4279 .and_then(Option::take)
4280 .ok_or_else(|| {
4281 Error::Internal(format!(
4282 "semantic eager VJP derivative output {derivative_output_index} unavailable"
4283 ))
4284 })?;
4285 let semantic = derivative_semantic(
4286 &derivative_frozen,
4287 &source,
4288 &[(seed_input_index, cotangent_semantic.clone())],
4289 derivative_output_index,
4290 "semantic_eager_vjp",
4291 )?;
4292 Ok(Some(EagerTensor::new_result_with_semantic(
4293 Arc::clone(ctx),
4294 eager_val_key(),
4295 result,
4296 true,
4297 output.trace.clone(),
4298 Some(semantic),
4299 )?))
4300 })
4301 .collect()
4302}
4303
4304fn semantic_eager_jvp_optional(
4305 ctx: &Arc<EagerRuntime>,
4306 engine: &mut dyn ExecutionEngine,
4307 output: &EagerTensor,
4308 wrt: &EagerTensor,
4309 tangent: &EagerTensor,
4310) -> Result<Option<EagerTensor>> {
4311 let (Some(output_semantic), Some(wrt_semantic)) =
4312 (output.semantic.as_ref(), wrt.semantic.as_ref())
4313 else {
4314 return Ok(None);
4315 };
4316 if !wrt_semantic.is_leaf() {
4317 return Ok(None);
4318 }
4319
4320 // One replay for this forward-mode pass; it also answers whether `wrt` is an
4321 // input of the output's program.
4322 let source = replay(std::slice::from_ref(output_semantic))?;
4323 #[cfg(test)]
4324 ctx.semantic_replays.fetch_add(1, Ordering::Relaxed);
4325 if source.outputs().len() != 1
4326 || source.leaf_data().len() != source.frozen().program.inputs().len()
4327 {
4328 return Err(Error::Internal(
4329 "semantic eager JVP source has inconsistent inputs or outputs".into(),
4330 ));
4331 }
4332 let Some(wrt_input_index) = source.input_index_of(wrt_semantic) else {
4333 return Ok(None);
4334 };
4335
4336 let mut active_inputs = vec![false; source.leaves().len()];
4337 if let Some(active) = active_inputs.get_mut(wrt_input_index) {
4338 *active = true;
4339 } else {
4340 return Err(Error::Internal(
4341 "semantic eager JVP input index is outside the source inputs".into(),
4342 ));
4343 }
4344 let ad = AdContext::with_rules_and_transform_cache(
4345 ctx.semantic_extension_rules.clone(),
4346 Arc::clone(&ctx.ad_transform_cache),
4347 );
4348 let derivative = ad
4349 .jvp_program(source.frozen(), &active_inputs)
4350 .map_err(|source| {
4351 Error::runtime_state_source("semantic_eager_jvp", ErrorPhase::GraphBuild, source)
4352 })?;
4353 // derivative_input_indices maps source input → derivative seed input.
4354 let Some(seed_input_index) = derivative
4355 .derivative_input_indices()
4356 .get(wrt_input_index)
4357 .copied()
4358 .flatten()
4359 else {
4360 return Ok(None);
4361 };
4362 // derivative_output_indices maps source output → derivative output.
4363 // There is always exactly one source output (guarded above).
4364 let Some(derivative_output_index) = derivative
4365 .derivative_output_indices()
4366 .first()
4367 .copied()
4368 .flatten()
4369 else {
4370 return Ok(None);
4371 };
4372
4373 let mut compiler = GraphCompiler::new();
4374 let derivative_program = compiler.compile_frozen_program(derivative.frozen())?;
4375 let tangent_tensor = Arc::new(RetainedValue::from_tensor(
4376 tangent.duplicate_value_in_session(&mut *engine)?,
4377 ));
4378 let input_count = derivative_program.input_count();
4379 let mut owned_inputs: Vec<Option<Tensor>> = (0..input_count).map(|_| None).collect();
4380 // Primal bindings and the seed are staged on the caller's engine.
4381 (|| -> Result<()> {
4382 let session: &mut dyn Engine = &mut *engine;
4383 for (source_input_index, data) in source.leaf_data().iter().enumerate() {
4384 let Some(slot) = owned_inputs.get_mut(source_input_index) else {
4385 return Err(Error::Internal(format!(
4386 "semantic eager JVP derivative program has no primal input slot {source_input_index}"
4387 )));
4388 };
4389 *slot = Some(copy_value_in_session(session, data)?);
4390 }
4391 let Some(slot) = owned_inputs.get_mut(seed_input_index) else {
4392 return Err(Error::Internal(format!(
4393 "semantic eager JVP seed input index {seed_input_index} is outside {input_count} inputs"
4394 )));
4395 };
4396 *slot = Some(copy_value_in_session(session, tangent_tensor.as_ref())?);
4397 Ok(())
4398 })()?;
4399 let input_refs = owned_inputs
4400 .iter()
4401 .enumerate()
4402 .map(|(index, tensor)| {
4403 tensor.as_ref().ok_or_else(|| {
4404 Error::Internal(format!(
4405 "semantic eager JVP derivative input {index} was not populated"
4406 ))
4407 })
4408 })
4409 .collect::<Result<Vec<_>>>()?;
4410 let input_reads = input_refs
4411 .iter()
4412 .map(|tensor| TensorRead::from_tensor(tensor))
4413 .collect::<Vec<_>>();
4414 let outputs = ctx.run_program(engine, &derivative_program, &input_reads)?;
4415 let output_count = outputs.len();
4416 let Some(result) = outputs.into_iter().nth(derivative_output_index) else {
4417 return Err(Error::Internal(format!(
4418 "semantic eager JVP derivative output index {derivative_output_index} is outside {} outputs",
4419 output_count
4420 )));
4421 };
4422 let tangent_semantic = SemanticValue::leaf(
4423 next_input_key(),
4424 tangent_tensor.dtype(),
4425 tangent_tensor.shape().len(),
4426 Arc::clone(&tangent_tensor),
4427 );
4428 let derivative_frozen = Arc::new(derivative.frozen().clone());
4429 let semantic = derivative_semantic(
4430 &derivative_frozen,
4431 &source,
4432 &[(seed_input_index, tangent_semantic)],
4433 derivative_output_index,
4434 "semantic_eager_jvp",
4435 )?;
4436
4437 Ok(Some(EagerTensor::new_result_with_semantic(
4438 Arc::clone(ctx),
4439 eager_val_key(),
4440 result,
4441 true,
4442 None,
4443 Some(semantic),
4444 )?))
4445}
4446
4447/// Record a derivative value over a frozen derivative program.
4448///
4449/// The derivative program's inputs are the source program's inputs followed by
4450/// the seed inputs the transform introduced, so the recorded edges are the
4451/// replayed leaves plus the seed values.
4452fn derivative_semantic(
4453 derivative_frozen: &Arc<tenferro_runtime::program::FrozenProgram>,
4454 source: &crate::eager::semantic::ReplayedProgram,
4455 seeds: &[(usize, SemanticValue)],
4456 derivative_output_index: usize,
4457 transform: &'static str,
4458) -> Result<SemanticValue> {
4459 let input_count = derivative_frozen.program.inputs().len();
4460 let source_input_count = source.leaves().len();
4461 let mut inputs: Vec<Option<SemanticValue>> = vec![None; input_count];
4462 for (index, leaf) in source.leaves().iter().enumerate() {
4463 if let Some(slot) = inputs.get_mut(index) {
4464 *slot = Some(leaf.clone());
4465 }
4466 }
4467 for (seed_input_index, seed) in seeds {
4468 if *seed_input_index < source_input_count {
4469 return Err(Error::Internal(format!(
4470 "{transform} derivative seed input {seed_input_index} overlaps the {source_input_count} source inputs"
4471 )));
4472 }
4473 let Some(slot) = inputs.get_mut(*seed_input_index) else {
4474 return Err(Error::Internal(format!(
4475 "{transform} derivative seed input {seed_input_index} is outside {input_count} inputs"
4476 )));
4477 };
4478 *slot = Some(seed.clone());
4479 }
4480 let inputs = inputs
4481 .into_iter()
4482 .enumerate()
4483 .map(|(index, value)| {
4484 value.ok_or_else(|| {
4485 Error::Internal(format!(
4486 "{transform} derivative input {index} has no recorded semantic edge"
4487 ))
4488 })
4489 })
4490 .collect::<Result<Vec<_>>>()?;
4491 if derivative_output_index >= derivative_frozen.program.outputs().len() {
4492 return Err(Error::Internal(format!(
4493 "{transform} derivative output index {derivative_output_index} is outside {} outputs",
4494 derivative_frozen.program.outputs().len()
4495 )));
4496 }
4497 Ok(SemanticValue::program(
4498 Arc::clone(derivative_frozen),
4499 derivative_output_index,
4500 inputs.into_boxed_slice(),
4501 ))
4502}
4503
4504fn copy_value_in_session(session: &mut dyn Engine, value: &RetainedValue) -> Result<Tensor> {
4505 let read = value.tensor_read().map_err(|error| {
4506 Error::runtime_state_source("copy_value_for_runtime", ErrorPhase::Execution, error)
4507 })?;
4508 session.to_contiguous_read(read).map_err(Error::from)
4509}
4510
4511fn validate_seed_tensor(op: &'static str, primal: &EagerTensor, seed: &EagerTensor) -> Result<()> {
4512 if primal.dtype() != seed.dtype() {
4513 return Err(
4514 tenferro_tensor::Error::dtype_mismatch(op, primal.dtype(), seed.dtype()).into(),
4515 );
4516 }
4517 if primal.shape() != seed.shape() {
4518 return Err(
4519 tenferro_tensor::Error::shape_mismatch(op, primal.shape(), seed.shape()).into(),
4520 );
4521 }
4522 Ok(())
4523}
4524
4525/// Eager tensor with reverse-mode autodiff over concrete tensor values.
4526///
4527/// This executes each primitive immediately and records a lightweight reverse
4528/// DAG for `EagerSession::backward`. Gradients accumulate across repeated `EagerSession::backward`
4529/// calls until they are cleared explicitly.
4530///
4531/// # Examples
4532///
4533/// ```
4534/// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
4535///
4536/// let ctx = EagerRuntime::new()?;
4537/// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap())?;
4538/// for _ in 0..2 {
4539/// let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
4540/// let squared = s.mul(&x, &x)?;
4541/// s.reduce_sum(&squared, Some(&[0]))
4542/// })?;
4543/// loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss))?;
4544/// }
4545///
4546/// assert_eq!(x.grad()?.unwrap().as_slice::<f64>().unwrap(), &[4.0, 8.0, 12.0]);
4547/// x.clear_grad()?;
4548///
4549/// assert!(x.grad().unwrap().is_none());
4550/// # Ok::<(), tenferro_ad::Error>(())
4551/// ```
4552#[derive(Clone)]
4553pub struct EagerTensor {
4554 pub(crate) key: ValueKey<StdTensorOp>,
4555 pub(crate) trace: Option<EagerTrace>,
4556 pub(crate) semantic: Option<SemanticValue>,
4557 pub(crate) requires_grad: bool,
4558 grad_slot: GradSlot,
4559 pub(crate) ctx: Arc<EagerRuntime>,
4560 _record: Arc<EagerTensorRecord>,
4561}
4562
4563pub(crate) struct EagerTensorRecord {
4564 value: Arc<AdValueRecord>,
4565 key: ValueKey<StdTensorOp>,
4566 trace: Option<EagerTrace>,
4567 semantic: Option<SemanticValue>,
4568 requires_grad: bool,
4569 grad_slot: GradSlot,
4570 ctx: Arc<EagerRuntime>,
4571}
4572
4573struct EagerTensorParts {
4574 ctx: Arc<EagerRuntime>,
4575 key: ValueKey<StdTensorOp>,
4576 requires_grad: bool,
4577 trace: Option<EagerTrace>,
4578 semantic: Option<SemanticValue>,
4579 value: Arc<AdValueRecord>,
4580 register_value: bool,
4581}
4582
4583impl fmt::Debug for EagerTensor {
4584 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4585 f.debug_struct("EagerTensor")
4586 .field("dtype", &self.dtype())
4587 .field("shape", &self.shape())
4588 .field("key", &self.key)
4589 .field("requires_grad", &self.requires_grad)
4590 .field("has_trace", &self.trace.is_some())
4591 .field("has_semantic", &self.semantic.is_some())
4592 .field("ctx_id", &self.ctx_id())
4593 .finish_non_exhaustive()
4594 }
4595}
4596
4597impl EagerTensor {
4598 pub(crate) fn new_leaf(
4599 ctx: Arc<EagerRuntime>,
4600 tensor: Tensor,
4601 requires_grad: bool,
4602 ) -> Result<Self> {
4603 Self::new_leaf_with_session(ctx, tensor, requires_grad, None)
4604 }
4605
4606 pub(crate) fn new_leaf_in_session(
4607 ctx: Arc<EagerRuntime>,
4608 tensor: Tensor,
4609 requires_grad: bool,
4610 session: &mut dyn Engine,
4611 ) -> Result<Self> {
4612 Self::new_leaf_with_session(ctx, tensor, requires_grad, Some(session))
4613 }
4614
4615 fn new_leaf_with_session(
4616 ctx: Arc<EagerRuntime>,
4617 tensor: Tensor,
4618 requires_grad: bool,
4619 session: Option<&mut dyn Engine>,
4620 ) -> Result<Self> {
4621 let key = eager_val_key();
4622 // A host-placement tensor needs no backend session: the CPU backend only
4623 // copies the host buffer for it, so entering a session would add
4624 // admission, provider exclusion, and session construction without doing
4625 // any provider work (#1704). Views and backend-family reads keep the
4626 // session path, and device runtimes keep it for every read.
4627 let read = TensorRead::from_tensor(&tensor);
4628 let semantic_tensor =
4629 match session {
4630 Some(session) => session.to_contiguous_read(read).map_err(Error::from)?,
4631 None => match cpu_host_owned_read(&read) {
4632 Some(materialized) => materialized.map_err(Error::from)?,
4633 None => return Err(Error::unsupported(
4634 "EagerTensor::new_leaf",
4635 ErrorPhase::Execution,
4636 "this tensor needs an engine to become an eager leaf; create it through \
4637 EagerSession::constant_from or EagerSession::variable_from",
4638 )),
4639 },
4640 };
4641 let semantic_value = Arc::new(RetainedValue::from_tensor(semantic_tensor));
4642 let semantic = SemanticValue::leaf(
4643 next_input_key(),
4644 semantic_value.dtype(),
4645 semantic_value.shape().len(),
4646 semantic_value,
4647 );
4648 let value = AdValueRecord::from_tensor(tensor, "EagerTensor::new_leaf")?;
4649 Self::from_parts(EagerTensorParts {
4650 ctx,
4651 key,
4652 requires_grad,
4653 trace: None,
4654 semantic: Some(semantic),
4655 value,
4656 register_value: true,
4657 })
4658 }
4659
4660 pub(crate) fn new_result(
4661 ctx: Arc<EagerRuntime>,
4662 key: ValueKey<StdTensorOp>,
4663 tensor: Tensor,
4664 requires_grad: bool,
4665 trace: Option<EagerTrace>,
4666 ) -> Result<Self> {
4667 Self::new_result_with_semantic(ctx, key, tensor, requires_grad, trace, None)
4668 }
4669
4670 pub(crate) fn new_result_with_semantic(
4671 ctx: Arc<EagerRuntime>,
4672 key: ValueKey<StdTensorOp>,
4673 tensor: Tensor,
4674 requires_grad: bool,
4675 trace: Option<EagerTrace>,
4676 semantic: Option<SemanticValue>,
4677 ) -> Result<Self> {
4678 let value = AdValueRecord::from_tensor(tensor, "EagerTensor::new_result")?;
4679 Self::from_parts(EagerTensorParts {
4680 ctx,
4681 key,
4682 requires_grad,
4683 trace,
4684 semantic,
4685 value,
4686 register_value: true,
4687 })
4688 }
4689
4690 pub(crate) fn new_unregistered_result_with_semantic(
4691 ctx: Arc<EagerRuntime>,
4692 key: ValueKey<StdTensorOp>,
4693 tensor: Tensor,
4694 requires_grad: bool,
4695 trace: Option<EagerTrace>,
4696 semantic: Option<SemanticValue>,
4697 ) -> Result<Self> {
4698 let value = AdValueRecord::from_tensor(tensor, "EagerTensor::new_unregistered_result")?;
4699 Self::from_parts(EagerTensorParts {
4700 ctx,
4701 key,
4702 requires_grad,
4703 trace,
4704 semantic,
4705 value,
4706 register_value: false,
4707 })
4708 }
4709
4710 pub(crate) fn new_result_value(
4711 ctx: Arc<EagerRuntime>,
4712 key: ValueKey<StdTensorOp>,
4713 value: TensorValue,
4714 requires_grad: bool,
4715 trace: Option<EagerTrace>,
4716 semantic: Option<SemanticValue>,
4717 ) -> Result<Self> {
4718 let (group, slot, dtype, shape) = value.try_into_group_parts().map_err(|_| {
4719 Error::runtime_state(
4720 "EagerTensor::new_result_value",
4721 ErrorPhase::Execution,
4722 "a TensorValue could not be transferred into its allocation group",
4723 )
4724 })?;
4725 let value = AdValueRecord::from_group(group, slot, dtype, shape);
4726 Self::from_parts(EagerTensorParts {
4727 ctx,
4728 key,
4729 requires_grad,
4730 trace,
4731 semantic,
4732 value,
4733 register_value: true,
4734 })
4735 }
4736
4737 fn from_parts(parts: EagerTensorParts) -> Result<Self> {
4738 let EagerTensorParts {
4739 ctx,
4740 key,
4741 requires_grad,
4742 trace,
4743 semantic,
4744 value,
4745 register_value,
4746 } = parts;
4747 let grad_slot = Arc::new(Mutex::new(None));
4748 if requires_grad {
4749 ctx.try_register_grad_slot(&key, &grad_slot)?;
4750 }
4751 let record = Arc::new(EagerTensorRecord {
4752 value: Arc::clone(&value),
4753 key: key.clone(),
4754 trace: trace.clone(),
4755 semantic: semantic.clone(),
4756 requires_grad,
4757 grad_slot: Arc::clone(&grad_slot),
4758 ctx: Arc::clone(&ctx),
4759 });
4760 if register_value {
4761 ctx.try_register_value_record(&key, &record)?;
4762 }
4763
4764 Ok(Self {
4765 key,
4766 trace,
4767 semantic,
4768 requires_grad,
4769 grad_slot,
4770 ctx,
4771 _record: record,
4772 })
4773 }
4774
4775 pub(crate) fn new_untracked_result(ctx: Arc<EagerRuntime>, tensor: Tensor) -> Result<Self> {
4776 let value =
4777 AdValueRecord::from_untracked_tensor(tensor, "EagerTensor::new_untracked_result")?;
4778 Ok(Self::new_untracked_value_record(ctx, value, None))
4779 }
4780
4781 pub(crate) fn new_untracked_value_result(
4782 ctx: Arc<EagerRuntime>,
4783 value: TensorValue,
4784 ) -> Result<Self> {
4785 Self::new_untracked_value_result_with_semantic(ctx, value, None)
4786 }
4787
4788 pub(crate) fn new_untracked_value_result_with_semantic(
4789 ctx: Arc<EagerRuntime>,
4790 value: TensorValue,
4791 semantic: Option<SemanticValue>,
4792 ) -> Result<Self> {
4793 let (group, slot, dtype, shape) = value.try_into_group_parts().map_err(|_| {
4794 Error::runtime_state(
4795 "EagerTensor::new_untracked_value_result",
4796 ErrorPhase::Execution,
4797 "a TensorValue could not be transferred into its allocation group",
4798 )
4799 })?;
4800 let value = AdValueRecord::from_group(group, slot, dtype, shape);
4801 Ok(Self::new_untracked_value_record(ctx, value, semantic))
4802 }
4803
4804 fn new_untracked_value_record(
4805 ctx: Arc<EagerRuntime>,
4806 value: Arc<AdValueRecord>,
4807 semantic: Option<SemanticValue>,
4808 ) -> Self {
4809 let key = eager_val_key();
4810 let grad_slot = Arc::new(Mutex::new(None));
4811 let record = Arc::new(EagerTensorRecord {
4812 value,
4813 key: key.clone(),
4814 trace: None,
4815 semantic: semantic.clone(),
4816 requires_grad: false,
4817 grad_slot: Arc::clone(&grad_slot),
4818 ctx: Arc::clone(&ctx),
4819 });
4820 Self {
4821 key,
4822 trace: None,
4823 semantic,
4824 requires_grad: false,
4825 grad_slot,
4826 ctx,
4827 _record: record,
4828 }
4829 }
4830
4831 pub(crate) fn from_record(record: Arc<EagerTensorRecord>) -> Self {
4832 Self {
4833 key: record.key.clone(),
4834 trace: record.trace.clone(),
4835 semantic: record.semantic.clone(),
4836 requires_grad: record.requires_grad,
4837 grad_slot: Arc::clone(&record.grad_slot),
4838 ctx: Arc::clone(&record.ctx),
4839 _record: record,
4840 }
4841 }
4842
4843 /// Borrow the retained value without creating an owner or copy.
4844 ///
4845 /// # Errors
4846 ///
4847 /// Returns [`Error::RuntimeState`] when the retained allocation-group
4848 /// descriptor is unavailable or invalid.
4849 pub fn value(&self) -> Result<ValueGuard<'_>> {
4850 self._record.value.value("EagerTensor::value")
4851 }
4852
4853 fn duplicate_host_value(&self) -> Option<Tensor> {
4854 // A pooled value duplicates through its descriptor view; a caller-owned
4855 // payload has no such view and duplicates through its own read path, which
4856 // copies the value while keeping its element type.
4857 self.value().ok()?.duplicate_host_tensor().ok()
4858 }
4859
4860 /// Detach this value from its graph: same value and runtime, a fresh
4861 /// untracked semantic leaf. The caller has checked the runtime.
4862 fn detach_in_session(&self, session: &mut dyn Engine) -> Result<Self> {
4863 let tensor = self.duplicate_value_in_session(session)?;
4864 let data = Arc::new(RetainedValue::from_tensor(tensor));
4865 let semantic =
4866 SemanticValue::leaf(next_input_key(), data.dtype(), data.shape().len(), data);
4867 Ok(Self::new_untracked_value_record(
4868 self.ctx.clone(),
4869 Arc::clone(&self._record.value),
4870 Some(semantic),
4871 ))
4872 }
4873
4874 pub(crate) fn duplicate_value_in_session(&self, session: &mut dyn Engine) -> Result<Tensor> {
4875 if let Some(tensor) = self.duplicate_host_value() {
4876 return Ok(tensor);
4877 }
4878 let read = self
4879 ._record
4880 .value
4881 .tensor_read("EagerTensor::duplicate_value")?;
4882 session.to_contiguous_read(read).map_err(Error::from)
4883 }
4884
4885 // INVARIANT: the error variants return the unchanged eager handle so a
4886 // caller can retry ownership extraction without an implicit copy.
4887 #[allow(clippy::result_large_err)]
4888 /// Consume this handle and structurally extract its retained allocation.
4889 ///
4890 /// A shared handle is returned unchanged as [`IntoValueError::NotUnique`].
4891 /// Group extraction failures return the unchanged handle and typed group
4892 /// error; no copy or fallback materialization is attempted.
4893 ///
4894 /// # Errors
4895 ///
4896 /// Returns [`IntoValueError::NotUnique`] when another handle retains the
4897 /// value, or [`IntoValueError::Extract`] when structural group extraction
4898 /// fails because the allocation is aliased or its descriptor is invalid.
4899 ///
4900 /// # Examples
4901 ///
4902 /// ```
4903 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
4904 ///
4905 /// let ctx = EagerRuntime::new()?;
4906 /// let value = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?)?;
4907 /// let owner = value
4908 /// .into_value()
4909 /// .expect("a uniquely owned value should be extractable");
4910 /// assert_eq!(owner.as_slice::<f64>()?, &[3.0]);
4911 /// # Ok::<(), tenferro_ad::Error>(())
4912 /// ```
4913 pub fn into_value(self) -> std::result::Result<Tensor, IntoValueError<Self>> {
4914 if Arc::strong_count(&self._record) != 1 {
4915 return Err(IntoValueError::NotUnique(self));
4916 }
4917 let Self { _record, .. } = self;
4918 let record = match Arc::try_unwrap(_record) {
4919 Ok(record) => record,
4920 Err(record) => return Err(IntoValueError::NotUnique(Self::from_record(record))),
4921 };
4922 let EagerTensorRecord {
4923 value,
4924 key,
4925 trace,
4926 semantic,
4927 requires_grad,
4928 grad_slot,
4929 ctx,
4930 } = record;
4931 let value = match Arc::try_unwrap(value) {
4932 Ok(value) => value,
4933 Err(value) => {
4934 let record = Arc::new(EagerTensorRecord {
4935 value,
4936 key,
4937 trace,
4938 semantic,
4939 requires_grad,
4940 grad_slot,
4941 ctx,
4942 });
4943 return Err(IntoValueError::NotUnique(Self::from_record(record)));
4944 }
4945 };
4946 let AdValueRecord {
4947 container,
4948 dtype,
4949 shape,
4950 } = value;
4951 let container = match Arc::try_unwrap(container) {
4952 Ok(container) => container,
4953 Err(container) => {
4954 let record = Arc::new(EagerTensorRecord {
4955 value: Arc::new(AdValueRecord {
4956 container,
4957 dtype,
4958 shape,
4959 }),
4960 key,
4961 trace,
4962 semantic,
4963 requires_grad,
4964 grad_slot,
4965 ctx,
4966 });
4967 return Err(IntoValueError::NotUnique(Self::from_record(record)));
4968 }
4969 };
4970 let (group, slot) = match container {
4971 // A caller-owned payload is handed back to its owner unchanged.
4972 RetentionContainer::CallerOwned { tensor } => return Ok(*tensor),
4973 RetentionContainer::Owned { tensor } => return Ok(tensor),
4974 RetentionContainer::Pooled { group, slot } => (group, slot),
4975 };
4976 match group.into_tensor(slot) {
4977 Ok(tensor) => Ok(tensor),
4978 Err((group, error)) => {
4979 let record = Arc::new(EagerTensorRecord {
4980 value: Arc::new(AdValueRecord {
4981 container: Arc::new(RetentionContainer::Pooled { group, slot }),
4982 dtype,
4983 shape,
4984 }),
4985 key,
4986 trace,
4987 semantic,
4988 requires_grad,
4989 grad_slot,
4990 ctx,
4991 });
4992 Err(IntoValueError::Extract {
4993 value: Self::from_record(record),
4994 error,
4995 })
4996 }
4997 }
4998 }
4999
5000 /// Return this tensor's scalar dtype without materializing through
5001 /// [`value`](Self::value).
5002 pub fn dtype(&self) -> DType {
5003 self._record.value.dtype()
5004 }
5005
5006 /// Return this tensor's logical shape without materializing through
5007 /// [`value`](Self::value).
5008 pub fn shape(&self) -> &[usize] {
5009 self._record.value.shape()
5010 }
5011
5012 /// Borrow this tensor value as a [`TensorRead`].
5013 ///
5014 /// This is the preferred borrowed input boundary for executor calls. It
5015 /// preserves the option to replace eager storage with non-contiguous views
5016 /// without forcing callers through [`value`](Self::value).
5017 ///
5018 /// # Panics
5019 ///
5020 /// Panics if a validated eager value record becomes unavailable, which
5021 /// indicates an internal invariant violation.
5022 pub fn tensor_read(&self) -> TensorRead<'_> {
5023 self._record
5024 .value
5025 .tensor_read("EagerTensor::tensor_read")
5026 .expect("validated eager value record")
5027 }
5028
5029 /// Return the accumulated gradient currently stored for this tensor.
5030 ///
5031 /// The stored gradient accumulates across repeated `EagerSession::backward` calls
5032 /// until it is cleared explicitly.
5033 ///
5034 /// For complex scalar losses, stored gradients use tenferro's
5035 /// Hermitian-adjoint cotangent convention. See
5036 /// <https://tensor4all.org/tenferro-rs/guides/complex-ad.html>.
5037 ///
5038 /// # Examples
5039 ///
5040 /// ```
5041 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5042 ///
5043 /// let ctx = EagerRuntime::new()?;
5044 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap()).unwrap();
5045 /// let loss = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
5046 /// let y = s.exp(&x)?;
5047 /// s.reduce_sum(&y, Some(&[0]))
5048 /// })?;
5049 /// let _cotangents = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
5050 ///
5051 /// let grad = x.grad()?.unwrap();
5052 /// assert_eq!(grad.shape(), &[2]);
5053 /// # Ok::<(), tenferro_ad::Error>(())
5054 /// ```
5055 ///
5056 /// # Errors
5057 ///
5058 /// Returns [`Error::RuntimeState`] if the gradient slot is poisoned or no
5059 /// longer available.
5060 pub fn grad(&self) -> Result<Option<GradientValue>> {
5061 self.grad_slot
5062 .lock()
5063 .map_err(|_| {
5064 Error::runtime_state(
5065 "eager_gradient_slot",
5066 ErrorPhase::Execution,
5067 "lock poisoned",
5068 )
5069 })
5070 .map(|slot| {
5071 slot.as_ref().map(|record| GradientValue {
5072 record: Arc::clone(record),
5073 })
5074 })
5075 }
5076
5077 /// Clear the accumulated gradient stored for this tensor.
5078 ///
5079 /// This only affects this tensor's gradient slot. Other tensors in the
5080 /// same context retain their gradients until they are cleared explicitly or
5081 /// overwritten by later accumulation.
5082 ///
5083 /// # Examples
5084 ///
5085 /// ```
5086 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5087 ///
5088 /// let ctx = EagerRuntime::new()?;
5089 /// let x = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap()).unwrap();
5090 /// let y = ctx.variable_from(Tensor::from_vec_col_major(vec![3], vec![4.0_f64, 5.0, 6.0]).unwrap()).unwrap();
5091 /// let loss = x.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
5092 /// let product = s.mul(&x, &y)?;
5093 /// s.reduce_sum(&product, Some(&[0]))
5094 /// })?;
5095 /// let _ = loss.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.backward(&loss)).unwrap();
5096 ///
5097 /// x.clear_grad()?;
5098 ///
5099 /// assert!(x.grad()?.is_none());
5100 /// assert!(y.grad()?.is_some());
5101 /// # Ok::<(), tenferro_ad::Error>(())
5102 /// ```
5103 ///
5104 /// # Errors
5105 ///
5106 /// Returns [`Error::RuntimeState`] if the gradient slot lock is poisoned.
5107 pub fn clear_grad(&self) -> Result<()> {
5108 *self.grad_slot.lock().map_err(|_| {
5109 Error::runtime_state(
5110 "eager_gradient_slot",
5111 ErrorPhase::Execution,
5112 "lock poisoned",
5113 )
5114 })? = None;
5115 Ok(())
5116 }
5117
5118 /// Report whether this tensor participates in gradient tracking.
5119 ///
5120 /// Tracked tensors keep a gradient slot in their eager context; untracked
5121 /// tensors and detached tensors do not.
5122 ///
5123 /// # Examples
5124 ///
5125 /// ```
5126 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5127 ///
5128 /// let ctx = EagerRuntime::new()?;
5129 /// let plain = ctx.constant_from(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap()).unwrap();
5130 /// let tracked = ctx.variable_from(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap()).unwrap();
5131 /// let detached = tracked.runtime().with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| s.detach(&tracked)).unwrap();
5132 ///
5133 /// assert!(!plain.tracks_grad());
5134 /// assert!(tracked.tracks_grad());
5135 /// assert!(!detached.tracks_grad());
5136 /// # Ok::<(), tenferro_ad::Error>(())
5137 /// ```
5138 pub fn tracks_grad(&self) -> bool {
5139 self.requires_grad
5140 }
5141
5142 #[cfg(test)]
5143 fn debug_trace_saved_value_count(&self) -> Option<usize> {
5144 None
5145 }
5146
5147 /// Return the opaque identifier of the context this tensor belongs to.
5148 ///
5149 /// # Examples
5150 ///
5151 /// ```
5152 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5153 ///
5154 /// let ctx = EagerRuntime::new()?;
5155 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
5156 ///
5157 /// assert_eq!(x.ctx_id(), ctx.id());
5158 /// # Ok::<(), tenferro_ad::Error>(())
5159 /// ```
5160 pub fn ctx_id(&self) -> ContextId {
5161 self.ctx.id()
5162 }
5163
5164 /// Borrow the eager runtime context that owns this tensor.
5165 pub fn runtime(&self) -> &Arc<EagerRuntime> {
5166 &self.ctx
5167 }
5168
5169 /// Check whether two tensors belong to the same eager context.
5170 ///
5171 /// # Examples
5172 ///
5173 /// ```
5174 /// use tenferro_ad::{EagerRuntime, EagerTensor, Tensor};
5175 ///
5176 /// let ctx = EagerRuntime::new()?;
5177 /// let x = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![1.0_f64]).unwrap()).unwrap();
5178 /// let y = ctx.constant_from(Tensor::from_vec_col_major(vec![1], vec![2.0_f64]).unwrap()).unwrap();
5179 ///
5180 /// assert!(x.same_context(&y));
5181 /// # Ok::<(), tenferro_ad::Error>(())
5182 /// ```
5183 pub fn same_context(&self, other: &Self) -> bool {
5184 self.ctx_id() == other.ctx_id()
5185 }
5186
5187 #[cfg(test)]
5188 pub(crate) fn standard_graph_op(
5189 engine: &mut dyn ExecutionEngine,
5190 inputs: &[&Self],
5191 build_graph: impl FnOnce(&[TensorInputKey]) -> Result<Arc<Graph<StdTensorOp>>>,
5192 ) -> Result<Vec<Self>> {
5193 let Some(first) = inputs.first() else {
5194 return Err(Error::Internal(
5195 "standard eager graph op requires at least one input tensor".to_string(),
5196 ));
5197 };
5198 let ctx = Arc::clone(&first.ctx);
5199 for tensor in inputs.iter().skip(1) {
5200 if !first.same_context(tensor) {
5201 return Err(Error::ContextMismatch {
5202 lhs: first.ctx_id(),
5203 rhs: tensor.ctx_id(),
5204 });
5205 }
5206 }
5207
5208 let graph_input_keys = (0..inputs.len())
5209 .map(|_| next_input_key())
5210 .collect::<Vec<_>>();
5211 let graph = build_graph(&graph_input_keys)?;
5212 let initial_data = graph_input_keys
5213 .iter()
5214 .zip(inputs.iter())
5215 .map(|(key, tensor)| {
5216 Ok((
5217 ValueKey::Input(key.clone()),
5218 tensor.duplicate_value_in_session(&mut *engine)?,
5219 ))
5220 })
5221 .collect::<Result<HashMap<_, _>>>()?;
5222 let execution = ctx.exec_standard_graph_outputs(engine, graph.as_ref(), initial_data)?;
5223 if execution.outputs.len() != graph.outputs().len() {
5224 return Err(Error::Internal(format!(
5225 "standard eager graph op expected {} graph outputs, got {}",
5226 graph.outputs().len(),
5227 execution.outputs.len()
5228 )));
5229 }
5230
5231 if !eager_grad_recording_enabled() || !inputs.iter().any(|input| input.requires_grad) {
5232 return execution
5233 .outputs
5234 .into_iter()
5235 .map(|output| {
5236 Self::new_unregistered_result_with_semantic(
5237 Arc::clone(&ctx),
5238 eager_val_key(),
5239 output,
5240 false,
5241 None,
5242 None,
5243 )
5244 })
5245 .collect();
5246 }
5247
5248 let recorded = record_eager_graph_outputs(
5249 graph.as_ref(),
5250 &graph_input_keys,
5251 &execution.outputs,
5252 inputs,
5253 )?;
5254 if recorded.traces.len() != execution.outputs.len() {
5255 return Err(Error::Internal(format!(
5256 "standard eager graph op expected {} eager traces, got {}",
5257 execution.outputs.len(),
5258 recorded.traces.len()
5259 )));
5260 }
5261
5262 recorded
5263 .traces
5264 .into_iter()
5265 .zip(recorded.semantic_values)
5266 .zip(execution.outputs)
5267 .map(|((trace, semantic), output)| {
5268 Self::new_result_with_semantic(
5269 Arc::clone(&ctx),
5270 trace.key,
5271 output,
5272 trace.requires_grad,
5273 trace.trace,
5274 semantic,
5275 )
5276 })
5277 .collect()
5278 }
5279
5280 fn backward_from_seed(
5281 &self,
5282 engine: &mut dyn ExecutionEngine,
5283 seed: Tensor,
5284 ) -> Result<Gradients> {
5285 let cotangent =
5286 EagerTensor::new_result(Arc::clone(&self.ctx), eager_val_key(), seed, false, None)?;
5287 let reachable_leaves = self
5288 .semantic
5289 .as_ref()
5290 .map(crate::eager::semantic::reachable_leaf_nodes)
5291 .unwrap_or_default();
5292 let candidate_keys = {
5293 let mut slots = self.ctx.lock_grad_slots()?;
5294 let mut keys = Vec::new();
5295 slots.retain(|key, slot| {
5296 if slot.upgrade().is_some() {
5297 keys.push(key.clone());
5298 true
5299 } else {
5300 false
5301 }
5302 });
5303 keys
5304 };
5305
5306 let mut targets = Vec::new();
5307 for key in candidate_keys {
5308 let Some(record) = self.ctx.value_record(&key)? else {
5309 continue;
5310 };
5311 if !record.requires_grad {
5312 continue;
5313 }
5314 // Intermediate and unrelated values also have slots; only request
5315 // reachable leaves.
5316 let Some(leaf_id) = record
5317 .semantic
5318 .as_ref()
5319 .filter(|semantic| semantic.is_leaf())
5320 .map(SemanticValue::node_id)
5321 else {
5322 continue;
5323 };
5324 if !reachable_leaves.contains(&leaf_id) {
5325 continue;
5326 }
5327 targets.push((key, EagerTensor::from_record(record)));
5328 }
5329 let wrts = targets.iter().map(|(_, wrt)| wrt).collect::<Vec<_>>();
5330 let gradients = semantic_eager_vjp_many(&self.ctx, engine, self, &wrts, &cotangent)?;
5331 let cotangents = (|| {
5332 let session: &mut dyn Engine = &mut *engine;
5333 let mut cotangents = HashMap::new();
5334 for ((key, _), grad) in targets.into_iter().zip(gradients) {
5335 let grad = grad.ok_or_else(|| {
5336 Error::invalid_argument(
5337 "backward",
5338 ErrorPhase::GraphBuild,
5339 "wrt",
5340 format!(
5341 "no cotangent flow for reachable tracked leaf {key:?}; use EagerSession::vjp_optional to observe absent differentiation"
5342 ),
5343 )
5344 })?;
5345 let tensor = match grad.into_value() {
5346 Ok(tensor) => tensor,
5347 Err(IntoValueError::NotUnique(handle)) => {
5348 handle.duplicate_value_in_session(session)?
5349 }
5350 // A gradient whose retained layout is a view (for example a
5351 // transpose) cannot be extracted as an owned tensor; copy
5352 // it to a compact tensor instead.
5353 Err(IntoValueError::Extract { value, .. }) => {
5354 value.duplicate_value_in_session(session)?
5355 }
5356 };
5357 cotangents.insert(key, tensor);
5358 }
5359 self.ctx.store_grads(&cotangents, session)?;
5360 Ok::<_, Error>(cotangents)
5361 })()?;
5362 Gradients::from_tensors(cotangents)
5363 }
5364}
5365
5366/// Insert a weak registry entry, first dropping dead entries when the insert
5367/// would otherwise grow the table.
5368///
5369/// Dead entries are otherwise removed only when their own key is looked up, so
5370/// a long-running runtime would keep one entry per value it ever created.
5371/// Pruning at the growth point keeps the cost amortized O(1) per insert: a
5372/// sweep runs at most once per capacity doubling.
5373fn insert_pruning_dead<K: std::hash::Hash + Eq, V>(
5374 map: &mut HashMap<K, Weak<V>>,
5375 key: K,
5376 value: Weak<V>,
5377) {
5378 if map.len() == map.capacity() {
5379 map.retain(|_, entry| entry.strong_count() > 0);
5380 }
5381 map.insert(key, value);
5382}
5383
5384#[cfg(test)]
5385impl EagerRuntime {
5386 /// Return how many semantic replays this runtime performed.
5387 pub(crate) fn semantic_replay_count(&self) -> usize {
5388 self.semantic_replays.load(Ordering::Relaxed)
5389 }
5390}
5391
5392pub(crate) fn eager_val_key() -> ValueKey<StdTensorOp> {
5393 ValueKey::Input(next_input_key())
5394}
5395
5396pub(crate) struct RecordedEagerTrace {
5397 pub(crate) key: ValueKey<StdTensorOp>,
5398 pub(crate) trace: Option<EagerTrace>,
5399 pub(crate) requires_grad: bool,
5400}
5401
5402pub(crate) struct RecordedEagerOutputs {
5403 pub(crate) traces: Vec<RecordedEagerTrace>,
5404 pub(crate) semantic_values: Vec<Option<SemanticValue>>,
5405}
5406
5407pub(crate) fn record_eager_outputs_in_session(
5408 op: &StdTensorOp,
5409 outputs: &[&Tensor],
5410 inputs: &[&EagerTensor],
5411 session: &mut dyn Engine,
5412) -> Result<RecordedEagerOutputs> {
5413 let metadata = outputs
5414 .iter()
5415 .map(|output| tensor_meta_from_tensor(output))
5416 .collect();
5417 record_eager_outputs_inner(op, metadata, inputs, Some(session))
5418}
5419
5420pub(crate) fn record_eager_value_outputs_in_session(
5421 op: &StdTensorOp,
5422 outputs: &[&TensorValue],
5423 inputs: &[&EagerTensor],
5424 session: &mut dyn Engine,
5425) -> Result<RecordedEagerOutputs> {
5426 let metadata = outputs
5427 .iter()
5428 .map(|output| tensor_meta_from_value(output))
5429 .collect();
5430 record_eager_outputs_inner(op, metadata, inputs, Some(session))
5431}
5432
5433fn record_eager_outputs_inner(
5434 op: &StdTensorOp,
5435 output_metadata: Vec<TensorMeta>,
5436 inputs: &[&EagerTensor],
5437 session: Option<&mut dyn Engine>,
5438) -> Result<RecordedEagerOutputs> {
5439 let semantic_values = record_semantic_eager_outputs(op, &output_metadata, inputs, session)?;
5440 record_eager_outputs_from_metadata(output_metadata, semantic_values, inputs)
5441}
5442
5443fn record_semantic_eager_outputs(
5444 op: &StdTensorOp,
5445 output_metadata: &[TensorMeta],
5446 inputs: &[&EagerTensor],
5447 mut session: Option<&mut dyn Engine>,
5448) -> Result<Vec<Option<SemanticValue>>> {
5449 // Materialize a constant semantic leaf for any untracked input that lost its
5450 // implicit semantic value on the active-edge fast path. This keeps
5451 // "untracked constant feeds tracked AD" working (PyTorch-style: untracked
5452 // = constant leaf, no gradient flows to it) without re-recording every
5453 // untracked op at creation time.
5454 let mut owned_constants = Vec::<SemanticValue>::new();
5455 for input in inputs {
5456 if input.semantic.is_none() {
5457 let value = match session.as_deref_mut() {
5458 Some(session) => input.duplicate_value_in_session(session)?,
5459 None => input.duplicate_host_value().ok_or_else(|| {
5460 Error::unsupported(
5461 "record_semantic_eager_outputs",
5462 ErrorPhase::Execution,
5463 "a non-host untracked input needs an engine to become a constant leaf",
5464 )
5465 })?,
5466 };
5467 let data = Arc::new(RetainedValue::from_tensor(value));
5468 owned_constants.push(SemanticValue::leaf(
5469 next_input_key(),
5470 data.dtype(),
5471 data.shape().len(),
5472 data,
5473 ));
5474 }
5475 }
5476 let mut constants = owned_constants.into_iter();
5477 let semantic_inputs: Vec<SemanticValue> = inputs
5478 .iter()
5479 .map(|input| {
5480 input
5481 .semantic
5482 .clone()
5483 .unwrap_or_else(|| constants.next().expect("materialized constant"))
5484 })
5485 .collect();
5486 let promotion_plan =
5487 eager_input_promotion_plan(op, inputs.len(), |index| inputs[index].dtype());
5488 // Mirror eager execution in the record only. The concrete tensors have
5489 // already been promoted at the execution boundary, so these casts add
5490 // semantic nodes without an eager copy or backend kernel.
5491 let semantic_inputs: Vec<SemanticValue> = semantic_inputs
5492 .into_iter()
5493 .enumerate()
5494 .map(|(index, semantic)| {
5495 let from = inputs[index].dtype();
5496 let target = promotion_plan.target_dtype(index, from);
5497 if from == target {
5498 semantic
5499 } else {
5500 let concrete = semantic.is_concrete_shape();
5501 SemanticValue::op_with_concreteness(
5502 StdTensorOp::Convert { from, to: target },
5503 vec![semantic].into_boxed_slice(),
5504 1,
5505 concrete,
5506 )
5507 }
5508 })
5509 .collect();
5510 // `Concatenate` needs runtime-extent inputs: its recorded inputs carry
5511 // symbolic extents, so the semantic value is exactified to the concrete
5512 // eager shape unless it is already concretely shaped.
5513 let semantic_inputs: Vec<SemanticValue> = if matches!(op, StdTensorOp::Concatenate { .. }) {
5514 semantic_inputs
5515 .into_iter()
5516 .zip(inputs)
5517 .map(|(semantic, input)| {
5518 if semantic.is_concrete_shape() {
5519 semantic
5520 } else {
5521 let to_shape: Vec<DimExpr> = input
5522 .shape()
5523 .iter()
5524 .map(|&size| DimExpr::Const(size))
5525 .collect();
5526 SemanticValue::op_with_concreteness(
5527 StdTensorOp::Reshape { to_shape },
5528 vec![semantic].into_boxed_slice(),
5529 1,
5530 true,
5531 )
5532 }
5533 })
5534 .collect()
5535 } else {
5536 semantic_inputs
5537 };
5538 let output_count = output_metadata.len();
5539 let node = SemanticValue::op(op.clone(), semantic_inputs.into_boxed_slice(), output_count);
5540 Ok((0..output_count)
5541 .map(|index| Some(node.at_output(index as u8)))
5542 .collect())
5543}
5544
5545#[cfg(test)]
5546fn record_eager_graph_outputs(
5547 graph: &Graph<StdTensorOp>,
5548 graph_input_keys: &[TensorInputKey],
5549 outputs: &[Tensor],
5550 inputs: &[&EagerTensor],
5551) -> Result<RecordedEagerOutputs> {
5552 let semantic_values = record_semantic_eager_graph_outputs(graph, graph_input_keys, inputs)?;
5553 let output_metadata = outputs.iter().map(tensor_meta_from_tensor);
5554 record_eager_outputs_from_metadata(output_metadata, semantic_values, inputs)
5555}
5556
5557#[cfg(test)]
5558fn record_semantic_eager_graph_outputs(
5559 graph: &Graph<StdTensorOp>,
5560 graph_input_keys: &[TensorInputKey],
5561 inputs: &[&EagerTensor],
5562) -> Result<Vec<Option<SemanticValue>>> {
5563 let Some(semantic_inputs) = inputs
5564 .iter()
5565 .map(|input| input.semantic.as_ref())
5566 .collect::<Option<Vec<_>>>()
5567 else {
5568 return Ok(vec![None; graph.outputs().len()]);
5569 };
5570 if graph_input_keys.len() != semantic_inputs.len() {
5571 return Err(Error::Internal(format!(
5572 "semantic graph recording expected {} input keys, got {}",
5573 semantic_inputs.len(),
5574 graph_input_keys.len()
5575 )));
5576 }
5577
5578 let mut values: HashMap<ValueKey<StdTensorOp>, SemanticValue> = HashMap::new();
5579 for (key, semantic) in graph_input_keys.iter().zip(semantic_inputs) {
5580 values.insert(ValueKey::Input(key.clone()), semantic.clone());
5581 }
5582
5583 for op_node in graph.operations() {
5584 let input_values = op_node
5585 .inputs
5586 .iter()
5587 .map(|input| {
5588 let key = match input {
5589 ValueRef::Local(local_id) => &graph.values()[*local_id].key,
5590 ValueRef::External(key) => key,
5591 };
5592 values.get(key).cloned().ok_or_else(|| {
5593 Error::Internal(format!(
5594 "semantic graph recording missing value for {key:?}"
5595 ))
5596 })
5597 })
5598 .collect::<Result<Vec<_>>>()?;
5599 let node = SemanticValue::op(
5600 op_node.operation.clone(),
5601 input_values.into_boxed_slice(),
5602 op_node.outputs.len(),
5603 );
5604 for (index, output_id) in op_node.outputs.iter().copied().enumerate() {
5605 values.insert(
5606 graph.values()[output_id].key.clone(),
5607 node.at_output(index as u8),
5608 );
5609 }
5610 }
5611
5612 graph
5613 .outputs()
5614 .iter()
5615 .map(|&output_id| {
5616 let key = &graph.values()[output_id].key;
5617 values.get(key).cloned().map(Some).ok_or_else(|| {
5618 Error::Internal(format!(
5619 "semantic graph recording missing output for {key:?}"
5620 ))
5621 })
5622 })
5623 .collect()
5624}
5625
5626fn record_eager_outputs_from_metadata(
5627 output_metadata: impl IntoIterator<Item = TensorMeta>,
5628 semantic_values: Vec<Option<SemanticValue>>,
5629 inputs: &[&EagerTensor],
5630) -> Result<RecordedEagerOutputs> {
5631 let output_metadata = output_metadata.into_iter().collect::<Vec<_>>();
5632 if semantic_values.len() != output_metadata.len() {
5633 return Err(Error::Internal(format!(
5634 "eager recording expected {} semantic traces, got {}",
5635 output_metadata.len(),
5636 semantic_values.len()
5637 )));
5638 }
5639 let requires_grad =
5640 eager_grad_recording_enabled() && inputs.iter().any(|input| input.requires_grad);
5641 let trace_count = output_metadata.len();
5642 let residual_trace = EagerTrace::new(inputs);
5643 let traces = (0..trace_count)
5644 .map(|_| RecordedEagerTrace {
5645 key: eager_val_key(),
5646 trace: Some(residual_trace.clone()),
5647 requires_grad,
5648 })
5649 .collect();
5650
5651 Ok(RecordedEagerOutputs {
5652 traces,
5653 semantic_values,
5654 })
5655}
5656
5657fn tensor_meta_from_value(value: &TensorValue) -> TensorMeta {
5658 TensorMeta::exact(
5659 value.dtype(),
5660 value.shape().iter().copied().map(SymDim::from).collect(),
5661 )
5662}
5663
5664#[cfg(test)]
5665pub(crate) fn zero_like_tensor(input: &Tensor, backend: &mut dyn Engine) -> Result<Tensor> {
5666 let host = match input.dtype() {
5667 // A caller-owned payload has no zero-like runtime tensor.
5668 DType::External(type_id) => {
5669 return Err(Error::unsupported(
5670 "zero_like_tensor",
5671 ErrorPhase::GraphBuild,
5672 format!(
5673 "an externally defined payload ({:?}) has no zero-like runtime tensor",
5674 DType::External(type_id)
5675 ),
5676 ));
5677 }
5678 DType::F32 => Tensor::from_typed::<f32>(TypedTensor::zeros(input.shape().to_vec())?),
5679 DType::F64 => Tensor::from_typed::<f64>(TypedTensor::zeros(input.shape().to_vec())?),
5680 DType::I32 => Tensor::from_typed::<i32>(TypedTensor::zeros(input.shape().to_vec())?),
5681 DType::I64 => Tensor::from_typed::<i64>(TypedTensor::zeros(input.shape().to_vec())?),
5682 DType::Bool => Tensor::from_typed::<bool>(TypedTensor::from_vec_col_major(
5683 input.shape().to_vec(),
5684 vec![false; input.shape().iter().product()],
5685 )?),
5686 DType::C32 => Tensor::from_typed::<tenferro_tensor::Complex32>(TypedTensor::zeros(
5687 input.shape().to_vec(),
5688 )?),
5689 DType::C64 => Tensor::from_typed::<tenferro_tensor::Complex64>(TypedTensor::zeros(
5690 input.shape().to_vec(),
5691 )?),
5692 };
5693 backend
5694 .upload_host_tensor(TensorRead::from_tensor(&host))
5695 .map_err(Error::from)
5696}
5697
5698pub(crate) fn one_like_tensor(input: &Tensor, session: &mut dyn Engine) -> Result<Tensor> {
5699 let host = ones_tensor(input.dtype(), input.shape().to_vec())?;
5700 session
5701 .upload_host_tensor(TensorRead::from_tensor(&host))
5702 .map_err(Error::from)
5703}
5704
5705#[cfg(test)]
5706mod tests;