Skip to main content

tenferro_runtime/traced/
composite_ops.rs

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