tenferro_ad/eager/composite.rs
1//! Eager composite operations (activations, normalizations, softmax,
2//! `take_along_axis`) on the borrowed [`EagerSession`].
3//!
4//! The formulation and edge-case policy are shared with the traced and
5//! concrete-session surfaces through `tenferro_runtime::composite`; AD follows
6//! from the recorded primitives.
7
8use tenferro_runtime::composite::{
9 self, scalar_tensor, zero_pad_config, CompositeBinary, CompositeOps, CompositeReduce,
10 CompositeUnary,
11};
12use tenferro_tensor::{ActivationOp, CompareDir, DType, GatherConfig};
13
14use super::{EagerSession, EagerTensor};
15use crate::{Error, Result};
16
17/// [`CompositeOps`] over a borrowed eager session.
18struct EagerComposite<'s, 'a> {
19 session: &'s mut EagerSession<'a>,
20}
21
22impl CompositeOps for EagerComposite<'_, '_> {
23 type Value = EagerTensor;
24 type Error = Error;
25
26 fn dtype(&self, value: &EagerTensor) -> DType {
27 value.dtype()
28 }
29
30 fn shape(&self, value: &EagerTensor) -> Result<Vec<usize>> {
31 Ok(value.shape().to_vec())
32 }
33
34 fn scalar(&mut self, dtype: DType, value: f64) -> Result<EagerTensor> {
35 self.session
36 .constant_from_host(scalar_tensor(dtype, value)?)
37 }
38
39 fn unary(&mut self, op: CompositeUnary, value: &EagerTensor) -> Result<EagerTensor> {
40 let session = &mut *self.session;
41 match op {
42 CompositeUnary::Neg => session.neg(value),
43 CompositeUnary::Exp => session.exp(value),
44 CompositeUnary::Log => session.log(value),
45 CompositeUnary::Log1p => session.log1p(value),
46 CompositeUnary::Tanh => session.tanh(value),
47 CompositeUnary::Erf => session.erf(value),
48 CompositeUnary::Rsqrt => session.rsqrt(value),
49 }
50 }
51
52 fn binary(
53 &mut self,
54 op: CompositeBinary,
55 lhs: &EagerTensor,
56 rhs: &EagerTensor,
57 ) -> Result<EagerTensor> {
58 let session = &mut *self.session;
59 match op {
60 CompositeBinary::Add => session.add(lhs, rhs),
61 CompositeBinary::Sub => session.sub(lhs, rhs),
62 CompositeBinary::Mul => session.mul(lhs, rhs),
63 CompositeBinary::Div => session.div(lhs, rhs),
64 CompositeBinary::Maximum => session.maximum(lhs, rhs),
65 }
66 }
67
68 fn compare(
69 &mut self,
70 lhs: &EagerTensor,
71 rhs: &EagerTensor,
72 dir: CompareDir,
73 ) -> Result<EagerTensor> {
74 self.session.compare(lhs, rhs, dir)
75 }
76
77 fn select(
78 &mut self,
79 condition: &EagerTensor,
80 on_true: &EagerTensor,
81 on_false: &EagerTensor,
82 ) -> Result<EagerTensor> {
83 self.session.where_select(condition, on_true, on_false)
84 }
85
86 fn reduce(
87 &mut self,
88 op: CompositeReduce,
89 value: &EagerTensor,
90 axes: &[usize],
91 ) -> Result<EagerTensor> {
92 // The composites hand over normalized axes; the public methods take
93 // signed axes, and a normalized axis round-trips unchanged.
94 let axes = axes
95 .iter()
96 .map(|&axis| crate::shape_packing::signed_axis(axis))
97 .collect::<Result<Vec<_>>>()?;
98 let axes = Some(axes.as_slice());
99 match op {
100 CompositeReduce::Sum => self.session.reduce_sum(value, axes),
101 CompositeReduce::Max => self.session.reduce_max(value, axes),
102 CompositeReduce::SumSquares => self.session.reduce_sum_squares(value, axes),
103 }
104 }
105
106 fn broadcast_in_dim(
107 &mut self,
108 value: &EagerTensor,
109 shape: &[usize],
110 dims: &[usize],
111 ) -> Result<EagerTensor> {
112 self.session.broadcast_in_dim(value, shape, dims)
113 }
114
115 fn reshape(&mut self, value: &EagerTensor, shape: &[usize]) -> Result<EagerTensor> {
116 self.session.reshape(value, shape.to_vec())
117 }
118
119 fn concatenate(&mut self, values: &[&EagerTensor], axis: usize) -> Result<EagerTensor> {
120 self.session
121 .concatenate(values, crate::shape_packing::signed_axis(axis)?)
122 }
123
124 fn pad(&mut self, value: &EagerTensor, low: &[usize], high: &[usize]) -> Result<EagerTensor> {
125 self.session.pad(value, zero_pad_config(low, high))
126 }
127
128 fn gather(
129 &mut self,
130 operand: &EagerTensor,
131 indices: &EagerTensor,
132 config: GatherConfig,
133 ) -> Result<EagerTensor> {
134 self.session.gather(operand, indices, config)
135 }
136}
137
138impl<'a> EagerSession<'a> {
139 fn composite(&mut self) -> EagerComposite<'_, 'a> {
140 EagerComposite { session: self }
141 }
142
143 /// Run a fused activation through the backend when no AD record is needed.
144 ///
145 /// Returns `Ok(None)` when the operands are tracked, semantic capture is
146 /// active, or the backend declines the fused form; the caller then records
147 /// the shared composite formulation instead.
148 fn fused_activation(
149 &mut self,
150 op: ActivationOp,
151 input: &EagerTensor,
152 ) -> Result<Option<EagerTensor>> {
153 if !crate::eager_ops::untracked_fast_path_allowed(&[input]) {
154 return Ok(None);
155 }
156 // The composite path refuses a tensor from another runtime; the fast path must too,
157 // before the backend runs and the result is bound to the input's runtime.
158 self.ensure_runtime(input)?;
159 let read = input.tensor_read();
160 let Some(output) = self.engine.fused_activation_read(op, read)? else {
161 return Ok(None);
162 };
163 Ok(Some(EagerTensor::new_untracked_result(
164 std::sync::Arc::clone(&input.ctx),
165 output,
166 )?))
167 }
168
169 /// Logistic sigmoid `1 / (1 + exp(-x))`, overflow-free.
170 ///
171 /// Evaluated as `1 / (1 + e)` for `x > 0` and `e / (1 + e)` otherwise, with
172 /// `e = exp(-|x|)`; the derivative is finite everywhere (`sigmoid'(0) = 1/4`).
173 /// Real `F32`/`F64` only.
174 ///
175 /// # Examples
176 /// ```rust
177 /// use tenferro_ad::{EagerRuntime, Tensor};
178 /// let ctx = EagerRuntime::new()?;
179 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
180 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![3], vec![-700.0_f64, 0.0, 1000.0])?)?;
181 /// s.sigmoid(&x)
182 /// })?;
183 /// let y = y.value()?;
184 /// let y = y.as_slice::<f64>()?;
185 /// assert_eq!(y[1], 0.5);
186 /// assert!(y[0] > 0.0 && y[0] < 1e-300);
187 /// assert_eq!(y[2], 1.0);
188 /// # Ok::<(), tenferro_ad::Error>(())
189 /// ```
190 ///
191 /// # Errors
192 ///
193 /// Returns a typed `UnsupportedDType` error for complex, integer, or `Bool`
194 /// input, [`Error::ContextMismatch`] for a tensor from another runtime, or a
195 /// backend error.
196 pub fn sigmoid(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
197 if let Some(out) = self.fused_activation(ActivationOp::Sigmoid, input)? {
198 return Ok(out);
199 }
200 composite::sigmoid(&mut self.composite(), input)
201 }
202
203 /// SiLU (swish) `x * sigmoid(x)`.
204 ///
205 /// Real `F32`/`F64` only.
206 ///
207 /// # Examples
208 /// ```rust
209 /// use tenferro_ad::{EagerRuntime, Tensor};
210 /// let ctx = EagerRuntime::new()?;
211 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
212 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![3], vec![-1.0_f64, 0.0, 1.0])?)?;
213 /// s.silu(&x)
214 /// })?;
215 /// let y = y.value()?;
216 /// let y = y.as_slice::<f64>()?;
217 /// assert_eq!(y[1], 0.0);
218 /// assert!((y[2] - 1.0 / (1.0 + (-1.0_f64).exp())).abs() < 1e-15);
219 /// # Ok::<(), tenferro_ad::Error>(())
220 /// ```
221 ///
222 /// # Errors
223 ///
224 /// Returns a typed `UnsupportedDType` error for complex, integer, or `Bool`
225 /// input, [`Error::ContextMismatch`] for a tensor from another runtime, or a
226 /// backend error.
227 pub fn silu(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
228 if let Some(out) = self.fused_activation(ActivationOp::Silu, input)? {
229 return Ok(out);
230 }
231 composite::silu(&mut self.composite(), input)
232 }
233
234 /// Softplus `log(1 + exp(x))` in the stable form `max(x, 0) + log1p(exp(-|x|))`.
235 ///
236 /// Never overflows; `softplus'(0) = 1/2` and `softplus''(0) = 1/4`. Real `F32`/`F64` only.
237 ///
238 /// # Examples
239 /// ```rust
240 /// use tenferro_ad::{EagerRuntime, Tensor};
241 /// let ctx = EagerRuntime::new()?;
242 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
243 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![3], vec![-1000.0_f64, 0.0, 1000.0])?)?;
244 /// s.softplus(&x)
245 /// })?;
246 /// let y = y.value()?;
247 /// let y = y.as_slice::<f64>()?;
248 /// assert_eq!(y[0], 0.0);
249 /// assert!((y[1] - 2.0_f64.ln()).abs() < 1e-15);
250 /// assert_eq!(y[2], 1000.0);
251 /// # Ok::<(), tenferro_ad::Error>(())
252 /// ```
253 ///
254 /// # Errors
255 ///
256 /// Returns a typed `UnsupportedDType` error for complex, integer, or `Bool`
257 /// input, [`Error::ContextMismatch`] for a tensor from another runtime, or a
258 /// backend error.
259 pub fn softplus(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
260 if let Some(out) = self.fused_activation(ActivationOp::Softplus, input)? {
261 return Ok(out);
262 }
263 composite::softplus(&mut self.composite(), input)
264 }
265
266 /// Exact GELU `x/2 * (1 + erf(x / sqrt(2)))` (PyTorch `approximate="none"`).
267 ///
268 /// Real `F32`/`F64` only.
269 ///
270 /// # Examples
271 /// ```rust
272 /// use tenferro_ad::{EagerRuntime, Tensor};
273 /// let ctx = EagerRuntime::new()?;
274 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
275 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![3], vec![-1.0_f64, 0.0, 1.0])?)?;
276 /// s.gelu(&x)
277 /// })?;
278 /// let y = y.value()?;
279 /// let y = y.as_slice::<f64>()?;
280 /// assert_eq!(y[1], 0.0);
281 /// assert!((y[2] - 0.841_344_746_068_542_9).abs() < 1e-15);
282 /// # Ok::<(), tenferro_ad::Error>(())
283 /// ```
284 ///
285 /// # Errors
286 ///
287 /// Returns a typed `UnsupportedDType` error for complex, integer, or `Bool`
288 /// input, [`Error::ContextMismatch`] for a tensor from another runtime, or a
289 /// backend error.
290 pub fn gelu(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
291 if let Some(out) = self.fused_activation(ActivationOp::Gelu, input)? {
292 return Ok(out);
293 }
294 composite::gelu(&mut self.composite(), input)
295 }
296
297 /// GELU tanh approximation (PyTorch `approximate="tanh"`).
298 ///
299 /// `x/2 * (1 + tanh(sqrt(2/pi) * (x + 0.044715 x^3)))`; real `F32`/`F64` only.
300 ///
301 /// # Examples
302 /// ```rust
303 /// use tenferro_ad::{EagerRuntime, Tensor};
304 /// let ctx = EagerRuntime::new()?;
305 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
306 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![3], vec![-1.0_f64, 0.0, 1.0])?)?;
307 /// s.gelu_tanh(&x)
308 /// })?;
309 /// let y = y.value()?;
310 /// let y = y.as_slice::<f64>()?;
311 /// assert_eq!(y[1], 0.0);
312 /// assert!((y[2] - 0.841_191_990_608_276_8).abs() < 1e-12);
313 /// # Ok::<(), tenferro_ad::Error>(())
314 /// ```
315 ///
316 /// # Errors
317 ///
318 /// Returns a typed `UnsupportedDType` error for complex, integer, or `Bool`
319 /// input, [`Error::ContextMismatch`] for a tensor from another runtime, or a
320 /// backend error.
321 pub fn gelu_tanh(&mut self, input: &EagerTensor) -> Result<EagerTensor> {
322 if let Some(out) = self.fused_activation(ActivationOp::GeluTanh, input)? {
323 return Ok(out);
324 }
325 composite::gelu_tanh(&mut self.composite(), input)
326 }
327
328 /// Arithmetic mean over `axes` (`None` reduces every axis).
329 ///
330 /// Float and complex dtypes. The sum is divided by the element count; a mean
331 /// over zero elements is `NaN`, and `Some(&[])` is the identity.
332 ///
333 /// # Examples
334 /// ```rust
335 /// use tenferro_ad::{EagerRuntime, Tensor};
336 /// let ctx = EagerRuntime::new()?;
337 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
338 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64, 2.0, 3.0, 4.0])?)?;
339 /// s.reduce_mean(&x, Some(&[1]))
340 /// })?;
341 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[2.0, 3.0]);
342 /// # Ok::<(), tenferro_ad::Error>(())
343 /// ```
344 ///
345 /// # Errors
346 ///
347 /// Returns a typed `UnsupportedDType` error for integer or `Bool` input, an
348 /// `AxisOutOfBounds` / `DuplicateAxis` validation error for invalid axes,
349 /// [`Error::ContextMismatch`] for a tensor from another runtime, or a backend error.
350 pub fn reduce_mean(
351 &mut self,
352 input: &EagerTensor,
353 axes: Option<&[isize]>,
354 ) -> Result<EagerTensor> {
355 let axes = axes
356 .map(|axes| {
357 crate::shape_packing::normalize_existing_axes(
358 "EagerSession::reduce_mean",
359 axes,
360 input.shape().len(),
361 )
362 })
363 .transpose()?;
364 let axes = axes.as_deref();
365 // Axes are validated before the dtype dispatch inside the composite, so an
366 // invalid axis list wins over an unsupported dtype here as it does on the
367 // concrete surface.
368 if let Some(axes) = axes {
369 crate::eager_ops::validate_eager_axes(
370 "EagerSession::reduce_mean",
371 input.shape().len(),
372 axes,
373 )?;
374 }
375 composite::reduce_mean(&mut self.composite(), input, axes)
376 }
377
378 /// Max-subtracted softmax along `axis`.
379 ///
380 /// A slice that is entirely `-inf` returns zeros with a finite gradient instead
381 /// of `NaN`; a participating `NaN` or `+inf` makes its slice `NaN`; a
382 /// zero-length `axis` returns an empty result. Real `F32`/`F64` only.
383 ///
384 /// # Examples
385 /// ```rust
386 /// use tenferro_ad::{EagerRuntime, Tensor};
387 /// let ctx = EagerRuntime::new()?;
388 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
389 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![2], vec![0.0_f64, f64::NEG_INFINITY])?)?;
390 /// s.softmax(&x, 0)
391 /// })?;
392 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0, 0.0]);
393 /// # Ok::<(), tenferro_ad::Error>(())
394 /// ```
395 ///
396 /// # Errors
397 ///
398 /// Returns a typed `UnsupportedDType` error for non-real input, an
399 /// `AxisOutOfBounds` validation error for an invalid axis,
400 /// [`Error::ContextMismatch`] for a tensor from another runtime, or a backend error.
401 pub fn softmax(&mut self, input: &EagerTensor, axis: isize) -> Result<EagerTensor> {
402 let axis = crate::shape_packing::normalize_existing_axis(
403 "EagerSession::softmax",
404 axis,
405 input.shape().len(),
406 )?;
407 if crate::eager_ops::untracked_fast_path_allowed(&[input])
408 && let Some(output) = self.engine.softmax_read(input.tensor_read(), axis)?
409 {
410 return EagerTensor::new_untracked_result(std::sync::Arc::clone(&input.ctx), output);
411 }
412 composite::softmax(&mut self.composite(), input, axis)
413 }
414
415 /// Max-subtracted log-softmax along `axis`.
416 ///
417 /// A slice that is entirely `-inf` returns `-inf` with a finite gradient
418 /// instead of `NaN`. Real `F32`/`F64` only.
419 ///
420 /// # Examples
421 /// ```rust
422 /// use tenferro_ad::{EagerRuntime, Tensor};
423 /// let ctx = EagerRuntime::new()?;
424 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
425 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 1.0])?)?;
426 /// s.log_softmax(&x, 0)
427 /// })?;
428 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-std::f64::consts::LN_2; 2]);
429 /// # Ok::<(), tenferro_ad::Error>(())
430 /// ```
431 ///
432 /// # Errors
433 ///
434 /// Returns a typed `UnsupportedDType` error for non-real input, an
435 /// `AxisOutOfBounds` validation error for an invalid axis,
436 /// [`Error::ContextMismatch`] for a tensor from another runtime, or a backend error.
437 pub fn log_softmax(&mut self, input: &EagerTensor, axis: isize) -> Result<EagerTensor> {
438 let axis = crate::shape_packing::normalize_existing_axis(
439 "EagerSession::log_softmax",
440 axis,
441 input.shape().len(),
442 )?;
443 composite::log_softmax(&mut self.composite(), input, axis)
444 }
445
446 /// Softmax along `axis` over the entries where the `Bool` `mask` is true.
447 ///
448 /// `mask` broadcasts to the input shape. Masked-out entries get probability `0`
449 /// and a zero gradient whatever their value; a slice with no unmasked entry
450 /// returns zeros with a zero gradient.
451 ///
452 /// # Examples
453 /// ```rust
454 /// use tenferro_ad::{EagerRuntime, Tensor};
455 /// let ctx = EagerRuntime::new()?;
456 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
457 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![3], vec![1.0_f64, 1.0, f64::NAN])?)?;
458 /// let mask = s.constant_from_host(Tensor::from_vec_col_major(vec![3], vec![true, true, false])?)?;
459 /// s.masked_softmax(&x, &mask, 0)
460 /// })?;
461 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.5, 0.5, 0.0]);
462 /// # Ok::<(), tenferro_ad::Error>(())
463 /// ```
464 ///
465 /// # Errors
466 ///
467 /// Returns a typed `UnsupportedDType` error for non-real input, a
468 /// `DTypeMismatch` validation error for a non-`Bool` mask, `ShapeMismatch` for
469 /// a mask that does not broadcast to the input, `AxisOutOfBounds` for an invalid
470 /// axis, [`Error::ContextMismatch`] for a tensor from another runtime, or a
471 /// backend error.
472 pub fn masked_softmax(
473 &mut self,
474 input: &EagerTensor,
475 mask: &EagerTensor,
476 axis: isize,
477 ) -> Result<EagerTensor> {
478 let axis = crate::shape_packing::normalize_existing_axis(
479 "EagerSession::masked_softmax",
480 axis,
481 input.shape().len(),
482 )?;
483 composite::masked_softmax(&mut self.composite(), input, mask, axis)
484 }
485
486 /// Log-softmax along `axis` over the entries where the `Bool` `mask` is true.
487 ///
488 /// Masked-out entries are `-inf` with a zero gradient; a slice with no unmasked
489 /// entry is all `-inf` with a zero gradient.
490 ///
491 /// # Examples
492 /// ```rust
493 /// use tenferro_ad::{EagerRuntime, Tensor};
494 /// let ctx = EagerRuntime::new()?;
495 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
496 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![2], vec![3.0_f64, 4.0])?)?;
497 /// let mask = s.constant_from_host(Tensor::from_vec_col_major(vec![2], vec![true, false])?)?;
498 /// s.masked_log_softmax(&x, &mask, 0)
499 /// })?;
500 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0, f64::NEG_INFINITY]);
501 /// # Ok::<(), tenferro_ad::Error>(())
502 /// ```
503 ///
504 /// # Errors
505 ///
506 /// Returns a typed `UnsupportedDType` error for non-real input, a
507 /// `DTypeMismatch` validation error for a non-`Bool` mask, `ShapeMismatch` for
508 /// a mask that does not broadcast to the input, `AxisOutOfBounds` for an invalid
509 /// axis, [`Error::ContextMismatch`] for a tensor from another runtime, or a
510 /// backend error.
511 pub fn masked_log_softmax(
512 &mut self,
513 input: &EagerTensor,
514 mask: &EagerTensor,
515 axis: isize,
516 ) -> Result<EagerTensor> {
517 let axis = crate::shape_packing::normalize_existing_axis(
518 "EagerSession::masked_log_softmax",
519 axis,
520 input.shape().len(),
521 )?;
522 composite::masked_log_softmax(&mut self.composite(), input, mask, axis)
523 }
524
525 /// Layer normalization along `axis` with optional affine `weight` / `bias`.
526 ///
527 /// `(x - mean) / sqrt(var + eps) * weight + bias` with the biased variance of the
528 /// centered values; `weight` and `bias` are rank-1 of length `shape[axis]`. A
529 /// zero-variance slice normalizes to `0` (then `bias`) with a finite gradient
530 /// when `eps > 0`. Real `F32`/`F64` only.
531 ///
532 /// # Examples
533 /// ```rust
534 /// use tenferro_ad::{EagerRuntime, Tensor};
535 /// let ctx = EagerRuntime::new()?;
536 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
537 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 3.0])?)?;
538 /// s.layer_norm(&x, 0, None, None, 0.0)
539 /// })?;
540 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[-1.0, 1.0]);
541 /// # Ok::<(), tenferro_ad::Error>(())
542 /// ```
543 ///
544 /// # Errors
545 ///
546 /// Returns a typed `UnsupportedDType` error for non-real input, an
547 /// `AxisOutOfBounds` validation error for an invalid axis, `InvalidArgument` for
548 /// a negative or non-finite `eps`, `DTypeMismatch` / `ShapeMismatch` for a weight
549 /// or bias that is not a same-dtype vector of the axis length,
550 /// [`Error::ContextMismatch`] for a tensor from another runtime, or a backend error.
551 pub fn layer_norm(
552 &mut self,
553 input: &EagerTensor,
554 axis: isize,
555 weight: Option<&EagerTensor>,
556 bias: Option<&EagerTensor>,
557 eps: f64,
558 ) -> Result<EagerTensor> {
559 let axis = crate::shape_packing::normalize_existing_axis(
560 "EagerSession::layer_norm",
561 axis,
562 input.shape().len(),
563 )?;
564 composite::layer_norm(&mut self.composite(), input, axis, weight, bias, eps)
565 }
566
567 /// RMS normalization along `axis` with optional affine `weight` / `bias`.
568 ///
569 /// `x / sqrt(mean(x^2) + eps) * weight + bias`; `weight` and `bias` are rank-1 of
570 /// length `shape[axis]`. An all-zero slice normalizes to `0` (then `bias`) with
571 /// a finite gradient when `eps > 0`. Real `F32`/`F64` only.
572 ///
573 /// # Examples
574 /// ```rust
575 /// use tenferro_ad::{EagerRuntime, Tensor};
576 /// let ctx = EagerRuntime::new()?;
577 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
578 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![2], vec![0.0_f64, 0.0])?)?;
579 /// s.rms_norm(&x, 0, None, None, 1e-6)
580 /// })?;
581 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[0.0, 0.0]);
582 /// # Ok::<(), tenferro_ad::Error>(())
583 /// ```
584 ///
585 /// # Errors
586 ///
587 /// Returns a typed `UnsupportedDType` error for non-real input, an
588 /// `AxisOutOfBounds` validation error for an invalid axis, `InvalidArgument` for
589 /// a negative or non-finite `eps`, `DTypeMismatch` / `ShapeMismatch` for a weight
590 /// or bias that is not a same-dtype vector of the axis length,
591 /// [`Error::ContextMismatch`] for a tensor from another runtime, or a backend error.
592 pub fn rms_norm(
593 &mut self,
594 input: &EagerTensor,
595 axis: isize,
596 weight: Option<&EagerTensor>,
597 bias: Option<&EagerTensor>,
598 eps: f64,
599 ) -> Result<EagerTensor> {
600 let axis = crate::shape_packing::normalize_existing_axis(
601 "EagerSession::rms_norm",
602 axis,
603 input.shape().len(),
604 )?;
605 composite::rms_norm(&mut self.composite(), input, axis, weight, bias, eps)
606 }
607
608 /// NumPy-style `take_along_axis` over `gather`.
609 ///
610 /// `out[.., i, ..] = input[.., indices[.., i, ..], ..]` along `axis`. `indices`
611 /// (I32/I64) has the input's rank; every other dimension is either the input's
612 /// extent (batch-varying indices) or `1` (the whole extent is taken). Indices
613 /// must be in bounds. The gradient flows to `input` only.
614 ///
615 /// # Examples
616 /// ```rust
617 /// use tenferro_ad::{EagerRuntime, Tensor};
618 /// let ctx = EagerRuntime::new()?;
619 /// // Per-batch row gather: out[i, j, b] = x[idx[i, b], j, b].
620 /// let y = ctx.with_eager_session(&mut tenferro_cpu::CpuEngine::serial(), |s| {
621 /// let x = s.constant_from_host(Tensor::from_vec_col_major(vec![2, 2, 2], (0..8).map(f64::from).collect::<Vec<_>>())?)?;
622 /// let idx = s.constant_from_host(Tensor::from_vec_col_major(vec![2, 1, 2], vec![1_i64, 0, 0, 0])?)?;
623 /// s.take_along_axis(&x, &idx, 0)
624 /// })?;
625 /// assert_eq!(y.value()?.as_slice::<f64>()?, &[1.0, 0.0, 3.0, 2.0, 4.0, 4.0, 6.0, 6.0]);
626 /// # Ok::<(), tenferro_ad::Error>(())
627 /// ```
628 ///
629 /// # Errors
630 ///
631 /// Returns a `RankMismatch` / `ShapeMismatch` validation error for incompatible
632 /// index shapes, `AxisOutOfBounds` for an invalid axis, `InvalidArgument` when
633 /// taking from a zero-length axis, a typed `UnsupportedDType` error for a
634 /// non-integer index dtype, [`Error::ContextMismatch`] for a tensor from another
635 /// runtime, or a backend error.
636 pub fn take_along_axis(
637 &mut self,
638 input: &EagerTensor,
639 indices: &EagerTensor,
640 axis: isize,
641 ) -> Result<EagerTensor> {
642 let axis = crate::shape_packing::normalize_existing_axis(
643 "EagerSession::take_along_axis",
644 axis,
645 input.shape().len(),
646 )?;
647 composite::take_along_axis(&mut self.composite(), input, indices, axis)
648 }
649}