Skip to main content

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}