Skip to main content

tenferro_runtime/
traced.rs

1use std::fmt;
2use std::sync::atomic::{AtomicU64, Ordering};
3use std::sync::Arc;
4
5use num_complex::{Complex32, Complex64};
6use tenferro_ops::broadcast::{
7    broadcast_error_to_validation, broadcast_in_dim_extent_error, broadcast_input_plan,
8    broadcast_shape, broadcast_shapes, BroadcastError,
9};
10use tenferro_ops::dim_expr::DimExpr;
11use tenferro_ops::input_key::TensorInputKey;
12use tenferro_ops::std_tensor_op::StdTensorOp;
13use tenferro_tensor::{
14    CompareDir, DType, DotGeneralConfig, Error as TensorError, GatherConfig, IntoShapeVec,
15    PadConfig, ScatterConfig, ShapeMismatch, SliceConfig, ValidationError,
16};
17
18use super::error::{Error, ErrorPhase, Result};
19use super::sym_dim::SymDim;
20use crate::checkpoint::RetainedValue;
21use crate::scalar_semantics::{bool_from_real_for_op, round_real_to_i32_for_op, round_real_to_i64};
22use crate::trace::{TraceContext, TraceValue};
23use crate::trace_ops::{append_core, finish_value};
24
25static NEXT_INPUT_ID: AtomicU64 = AtomicU64::new(0);
26
27pub(crate) fn next_input_key() -> TensorInputKey {
28    TensorInputKey::User {
29        id: NEXT_INPUT_ID.fetch_add(1, Ordering::Relaxed),
30    }
31}
32
33/// A typed view of one semantic value inside a [`TraceContext`].
34///
35/// `rank`, `dtype` and `shape_hint` are an immutable cache of the context
36/// metadata this value was appended with; the context keeps the authoritative
37/// metadata.
38#[derive(Clone)]
39pub struct TracedTensor {
40    pub(crate) ctx: TraceContext,
41    pub(crate) value: TraceValue,
42    pub(crate) rank: usize,
43    pub(crate) dtype: DType,
44    pub(crate) shape_hint: Option<Vec<SymDim>>,
45    pub(crate) data: Option<Arc<RetainedValue>>,
46    /// Identity this tensor's axes use in `shape_hint`, unique per handle.
47    pub(crate) symbolic_id: u64,
48}
49
50impl fmt::Debug for TracedTensor {
51    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
52        f.debug_struct("TracedTensor")
53            .field("rank", &self.rank)
54            .field("dtype", &self.dtype)
55            .field("shape_hint", &self.shape_hint)
56            .field("has_data", &self.data.is_some())
57            .finish_non_exhaustive()
58    }
59}
60
61pub(crate) fn try_concrete_shape(tensor: &TracedTensor) -> Option<Vec<usize>> {
62    tensor
63        .shape_hint
64        .as_ref()?
65        .iter()
66        .map(SymDim::constant_value)
67        .collect()
68}
69
70fn graph_validation(op: &'static str, source: impl Into<ValidationError>) -> Error {
71    Error::validation(op, ErrorPhase::GraphBuild, source.into())
72}
73
74fn graph_invalid_argument(
75    op: &'static str,
76    argument: &'static str,
77    message: impl Into<String>,
78) -> Error {
79    graph_validation(
80        op,
81        ValidationError::InvalidArgument {
82            argument,
83            message: message.into(),
84        },
85    )
86}
87
88fn graph_broadcast_error(op: &'static str, error: BroadcastError) -> Error {
89    graph_validation(op, broadcast_error_to_validation(error))
90}
91
92fn graph_tensor_error(op: &'static str, error: TensorError) -> Error {
93    match error {
94        TensorError::Validation { source, .. } => graph_validation(op, source),
95        other => Error::TensorRuntime(other),
96    }
97}
98
99fn graph_error_with_context(op: &'static str, error: Error) -> Error {
100    match error {
101        Error::Validation { source, .. } => graph_validation(op, source),
102        other => other,
103    }
104}
105
106pub(crate) fn concrete_shape(tensor: &TracedTensor) -> Result<Vec<usize>> {
107    tensor
108        .shape_hint
109        .as_ref()
110        .ok_or_else(|| {
111            graph_invalid_argument(
112                "TracedTensor::concrete_shape",
113                "shape",
114                format!(
115                    "missing shape hint for traced tensor at rank {}",
116                    tensor.rank
117                ),
118            )
119        })?
120        .iter()
121        .map(|dim| {
122            dim.constant_value().ok_or_else(|| {
123                graph_invalid_argument(
124                    "TracedTensor::concrete_shape",
125                    "shape",
126                    format!(
127                        "symbolic dimension in shape hint for tensor at rank {}",
128                        tensor.rank
129                    ),
130                )
131            })
132        })
133        .collect()
134}
135
136/// Broadcast a traced tensor to `target_shape`.
137///
138/// Expanding singleton axes are first reshaped away so the existing
139/// `BroadcastInDim` transpose rule reduces them correctly during VJP.
140pub(crate) fn broadcast_to(tensor: &TracedTensor, target_shape: &[usize]) -> Result<TracedTensor> {
141    let tensor_shape = concrete_shape(tensor)?;
142    if tensor_shape == target_shape {
143        return Ok(tensor.clone());
144    }
145
146    let plan = broadcast_input_plan(&tensor_shape, target_shape)
147        .map_err(|err| graph_broadcast_error("broadcast_to", err))?;
148
149    let source = if plan.source_shape == tensor_shape {
150        tensor.clone()
151    } else {
152        tensor.reshape(&plan.source_shape)?
153    };
154    source.broadcast_in_dim(target_shape, &plan.dims)
155}
156
157/// Broadcast two tensors to a common shape.
158pub(crate) fn broadcast_binary(
159    a: &TracedTensor,
160    b: &TracedTensor,
161) -> Result<(TracedTensor, TracedTensor)> {
162    if a.shape_hint == b.shape_hint && a.rank == b.rank {
163        return Ok((a.clone(), b.clone()));
164    }
165    if (try_concrete_shape(a).is_none() || try_concrete_shape(b).is_none()) && a.rank == b.rank {
166        return Ok((a.clone(), b.clone()));
167    }
168    let a_shape = concrete_shape(a)?;
169    let b_shape = concrete_shape(b)?;
170    let target = broadcast_shape(&a_shape, &b_shape)
171        .map_err(|err| graph_broadcast_error("broadcast_binary", err))?;
172    Ok((broadcast_to(a, &target)?, broadcast_to(b, &target)?))
173}
174
175pub(crate) fn broadcast_ternary(
176    a: &TracedTensor,
177    b: &TracedTensor,
178    c: &TracedTensor,
179) -> Result<(TracedTensor, TracedTensor, TracedTensor)> {
180    let a_shape = concrete_shape(a)?;
181    let b_shape = concrete_shape(b)?;
182    let c_shape = concrete_shape(c)?;
183    let target = broadcast_shapes([a_shape.as_slice(), b_shape.as_slice(), c_shape.as_slice()])
184        .map_err(|err| graph_broadcast_error("broadcast_ternary", err))?;
185    Ok((
186        broadcast_to(a, &target)?,
187        broadcast_to(b, &target)?,
188        broadcast_to(c, &target)?,
189    ))
190}
191
192fn scale_with_constant(input: &TracedTensor, op: StdTensorOp) -> Result<TracedTensor> {
193    let scalar = apply_nullary(op, 0, input.dtype, Some(vec![]), &input.ctx)?;
194    // A binary op applies to operands of one shape, so the rank-0 factor has to be
195    // broadcast here, exactly as `TracedTensor::add`/`mul` do through
196    // `broadcast_binary`. Without it the graph carries a rank-0 `Mul` operand: the
197    // CPU backend happens to accept one, the CUDA backend rejects it with
198    // `incompatible shapes: lhs=[], rhs=<input shape>`, so the same graph would run
199    // on one backend and not the other.
200    let (input, scalar) = broadcast_binary(input, &scalar)?;
201    apply_binary(
202        StdTensorOp::Mul,
203        &input,
204        &scalar,
205        input.rank,
206        input.shape_hint.clone(),
207    )
208}
209
210fn try_inferred_output_dtype(
211    op: &StdTensorOp,
212    inputs: &[DType],
213    context: &'static str,
214) -> Result<DType> {
215    crate::shape_infer::infer_output_dtype_at(op, inputs, ErrorPhase::GraphBuild)
216        .map_err(|err| graph_error_with_context(context, err))
217}
218
219fn checked_shape_product_for_graph_build(
220    shape: &[usize],
221    context: &'static str,
222    _role: &'static str,
223) -> Result<usize> {
224    shape.iter().copied().try_fold(1usize, |acc, dim| {
225        acc.checked_mul(dim)
226            .ok_or_else(|| graph_validation(context, ValidationError::IntegerOverflow))
227    })
228}
229
230fn validate_concrete_reshape_shape(input: &TracedTensor, shape: &[usize]) -> Result<()> {
231    let to = checked_shape_product_for_graph_build(shape, "TracedTensor::reshape", "target")?;
232    let Some(input_shape) = try_concrete_shape(input) else {
233        return Ok(());
234    };
235    let from =
236        checked_shape_product_for_graph_build(&input_shape, "TracedTensor::reshape", "input")?;
237    if from != to {
238        return Err(graph_validation(
239            "TracedTensor::reshape",
240            ShapeMismatch::ReshapeElementCount { from, to },
241        ));
242    }
243    Ok(())
244}
245
246fn traced_input_shape_exprs(input_idx: usize, tensor: &TracedTensor) -> Vec<DimExpr> {
247    match tensor.shape_hint.as_ref() {
248        Some(shape) => shape
249            .iter()
250            .enumerate()
251            .map(|(axis, dim)| {
252                dim.constant_value()
253                    .map_or(DimExpr::InputDim { input_idx, axis }, DimExpr::Const)
254            })
255            .collect(),
256        None => (0..tensor.rank)
257            .map(|axis| DimExpr::InputDim { input_idx, axis })
258            .collect(),
259    }
260}
261
262fn traced_input_sym_shape(tensor: &TracedTensor) -> Vec<SymDim> {
263    tensor.shape_hint.clone().unwrap_or_else(|| {
264        (0..tensor.rank)
265            .map(|axis| SymDim::tensor_axis(tensor.symbolic_id(), axis))
266            .collect()
267    })
268}
269
270pub(crate) fn infer_traced_single_output_shape(
271    op_name: &'static str,
272    op: &StdTensorOp,
273    inputs: &[&TracedTensor],
274) -> Result<(usize, Option<Vec<SymDim>>)> {
275    let input_shape_exprs: Vec<Vec<DimExpr>> = inputs
276        .iter()
277        .enumerate()
278        .map(|(input_idx, tensor)| traced_input_shape_exprs(input_idx, tensor))
279        .collect();
280    let input_shape_refs: Vec<&[DimExpr]> = input_shape_exprs.iter().map(Vec::as_slice).collect();
281    let output_shapes = crate::shape_infer::infer_output_shapes(op, &input_shape_refs)
282        .map_err(|err| graph_error_with_context(op_name, err))?;
283    let output_shape = output_shapes.first().ok_or_else(|| {
284        Error::Internal(format!("{op_name}: shape inference returned no outputs"))
285    })?;
286    if output_shapes.len() != 1 {
287        return Err(Error::Internal(format!(
288            "{op_name}: expected single-output shape inference, got {} outputs",
289            output_shapes.len()
290        )));
291    }
292
293    let input_sym_shapes: Vec<Vec<SymDim>> = inputs
294        .iter()
295        .map(|tensor| traced_input_sym_shape(tensor))
296        .collect();
297    let input_sym_refs: Vec<&[SymDim]> = input_sym_shapes.iter().map(Vec::as_slice).collect();
298    let out_shape_hint = output_shape
299        .iter()
300        .map(|dim| SymDim::from_dim_expr(dim, &input_sym_refs))
301        .collect();
302    Ok((output_shape.len(), Some(out_shape_hint)))
303}
304
305fn reduction_output_meta(
306    tensor: &TracedTensor,
307    axes: &[usize],
308    op: &'static str,
309) -> Result<(usize, Option<Vec<SymDim>>)> {
310    validate_traced_axes(tensor.rank, axes, op)?;
311
312    let out_shape_hint = tensor.shape_hint.as_ref().map(|shape| {
313        (0..shape.len())
314            .filter(|d| !axes.contains(d))
315            .map(|d| shape[d].clone())
316            .collect()
317    });
318    Ok((tensor.rank - axes.len(), out_shape_hint))
319}
320
321fn validate_traced_axis(tensor: &TracedTensor, axis: usize, op: &'static str) -> Result<()> {
322    if axis >= tensor.rank {
323        return Err(graph_validation(
324            op,
325            ValidationError::AxisOutOfBounds {
326                axis: isize::try_from(axis).unwrap_or(isize::MAX),
327                rank: tensor.rank,
328            },
329        ));
330    }
331    Ok(())
332}
333
334fn validate_traced_axes(rank: usize, axes: &[usize], op: &'static str) -> Result<()> {
335    let mut seen = vec![false; rank];
336    for &axis in axes {
337        if axis >= rank {
338            return Err(graph_validation(
339                op,
340                ValidationError::AxisOutOfBounds {
341                    axis: isize::try_from(axis).unwrap_or(isize::MAX),
342                    rank,
343                },
344            ));
345        }
346        if seen[axis] {
347            return Err(graph_validation(
348                op,
349                ValidationError::DuplicateAxis { axis, role: "axes" },
350            ));
351        }
352        seen[axis] = true;
353    }
354    Ok(())
355}
356
357fn validate_traced_insert_axis(rank: usize, axis: usize, op: &'static str) -> Result<()> {
358    if axis > rank {
359        return Err(graph_invalid_argument(
360            op,
361            "axis",
362            format!("axis {axis} out of bounds for rank {rank} insertion"),
363        ));
364    }
365    Ok(())
366}
367
368fn validate_traced_perm(rank: usize, perm: &[usize], op: &'static str) -> Result<()> {
369    if perm.len() != rank {
370        return Err(graph_validation(
371            op,
372            ValidationError::InvalidPermutationLength {
373                expected: rank,
374                actual: perm.len(),
375            },
376        ));
377    }
378    let mut seen = vec![false; rank];
379    for &axis in perm {
380        if axis >= rank {
381            return Err(graph_validation(
382                op,
383                ValidationError::AxisOutOfBounds {
384                    axis: isize::try_from(axis).unwrap_or(isize::MAX),
385                    rank,
386                },
387            ));
388        }
389        if seen[axis] {
390            return Err(graph_validation(
391                op,
392                ValidationError::DuplicateAxis {
393                    axis,
394                    role: "permutation",
395                },
396            ));
397        }
398        seen[axis] = true;
399    }
400    Ok(())
401}
402
403fn validate_broadcast_in_dim_args(
404    input: &TracedTensor,
405    output_shape: &[SymDim],
406    dims: &[usize],
407    op: &'static str,
408) -> Result<()> {
409    if dims.len() != input.rank {
410        return Err(graph_validation(
411            op,
412            ValidationError::RankMismatch {
413                expected: input.rank,
414                actual: dims.len(),
415            },
416        ));
417    }
418
419    let concrete_input_shape: Option<Vec<usize>> = input
420        .shape_hint
421        .as_ref()
422        .and_then(|shape| shape.iter().map(SymDim::constant_value).collect());
423    let concrete_output_shape = output_shape
424        .iter()
425        .map(SymDim::constant_value)
426        .collect::<Option<Vec<_>>>();
427    if let (Some(input_shape), Some(output_shape)) = (
428        concrete_input_shape.as_deref(),
429        concrete_output_shape.as_deref(),
430    ) && let Some(error) = broadcast_in_dim_extent_error(input_shape, output_shape, dims)
431    {
432        return Err(graph_broadcast_error(op, error));
433    }
434
435    let mut seen = vec![false; output_shape.len()];
436    for &dim in dims {
437        if dim >= output_shape.len() {
438            return Err(graph_validation(
439                op,
440                ValidationError::AxisOutOfBounds {
441                    axis: isize::try_from(dim).unwrap_or(isize::MAX),
442                    rank: output_shape.len(),
443                },
444            ));
445        }
446        if seen[dim] {
447            return Err(graph_validation(
448                op,
449                ValidationError::DuplicateAxis {
450                    axis: dim,
451                    role: "broadcast",
452                },
453            ));
454        }
455        seen[dim] = true;
456    }
457
458    Ok(())
459}
460
461impl std::ops::Add for &TracedTensor {
462    type Output = Result<TracedTensor>;
463
464    fn add(self, rhs: &TracedTensor) -> Result<TracedTensor> {
465        TracedTensor::add(self, rhs)
466    }
467}
468
469impl std::ops::Sub for &TracedTensor {
470    type Output = Result<TracedTensor>;
471
472    fn sub(self, rhs: &TracedTensor) -> Result<TracedTensor> {
473        TracedTensor::sub(self, rhs)
474    }
475}
476
477impl std::ops::Mul for &TracedTensor {
478    type Output = Result<TracedTensor>;
479
480    fn mul(self, rhs: &TracedTensor) -> Result<TracedTensor> {
481        TracedTensor::mul(self, rhs)
482    }
483}
484
485impl std::ops::Mul<f64> for &TracedTensor {
486    type Output = Result<TracedTensor>;
487
488    fn mul(self, rhs: f64) -> Result<TracedTensor> {
489        self.scale_real(rhs)
490    }
491}
492
493impl std::ops::Mul<&TracedTensor> for f64 {
494    type Output = Result<TracedTensor>;
495
496    fn mul(self, rhs: &TracedTensor) -> Result<TracedTensor> {
497        rhs.scale_real(self)
498    }
499}
500
501impl std::ops::Neg for &TracedTensor {
502    type Output = Result<TracedTensor>;
503
504    fn neg(self) -> Self::Output {
505        TracedTensor::neg(self)
506    }
507}
508
509impl std::ops::Div for &TracedTensor {
510    type Output = Result<TracedTensor>;
511
512    fn div(self, rhs: &TracedTensor) -> Result<TracedTensor> {
513        TracedTensor::div(self, rhs)
514    }
515}
516
517impl std::ops::Rem for &TracedTensor {
518    type Output = Result<TracedTensor>;
519
520    fn rem(self, rhs: &TracedTensor) -> Result<TracedTensor> {
521        TracedTensor::rem(self, rhs)
522    }
523}
524
525impl TracedTensor {
526    /// Return the concrete tensor data attached to this traced value, if any.
527    ///
528    /// Placeholder tensors created with `input_concrete_shape` or
529    /// `input_symbolic_shape` have no attached data until execution bindings
530    /// provide it.
531    ///
532    /// # Examples
533    ///
534    /// ```
535    /// use tenferro_runtime::{TraceContext, DType, TracedTensor};
536    ///
537    /// let trace = TraceContext::new();
538    /// let concrete = trace.from_vec_col_major(vec![1], vec![1.0_f64]).unwrap();
539    /// assert!(concrete.attached_value().is_some());
540    ///
541    /// let placeholder = trace.input_symbolic_shape(DType::F64, 1).unwrap();
542    /// assert!(placeholder.attached_value().is_none());
543    /// ```
544    pub fn attached_value(&self) -> Option<&Arc<RetainedValue>> {
545        self.data.as_ref()
546    }
547
548    /// Return the tensor element dtype recorded for this traced value.
549    ///
550    /// # Examples
551    ///
552    /// ```
553    /// use tenferro_runtime::{DType, TraceContext};
554    ///
555    /// let trace = TraceContext::new();
556    /// let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
557    /// assert_eq!(x.dtype(), DType::F64);
558    /// # Ok::<(), Box<dyn std::error::Error>>(())
559    /// ```
560    pub fn dtype(&self) -> DType {
561        self.dtype
562    }
563
564    /// Return the rank recorded for this traced value.
565    ///
566    /// # Examples
567    ///
568    /// ```
569    /// use tenferro_runtime::TraceContext;
570    ///
571    /// let trace = TraceContext::new();
572    /// let matrix = trace.from_vec_col_major(vec![2, 3], vec![0.0_f64; 6])?;
573    /// assert_eq!(matrix.rank(), 2);
574    /// assert_eq!(matrix.neg()?.rank(), 2);
575    /// # Ok::<(), Box<dyn std::error::Error>>(())
576    /// ```
577    pub fn rank(&self) -> usize {
578        self.rank
579    }
580
581    /// Borrow the trace context this value belongs to.
582    ///
583    /// # Examples
584    ///
585    /// ```
586    /// use tenferro_runtime::TraceContext;
587    ///
588    /// let trace = TraceContext::new();
589    /// let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
590    /// let y = x.neg()?;
591    ///
592    /// // A derived value stays in its producer's context.
593    /// assert!(y.context().same_context(&trace));
594    /// # Ok::<(), Box<dyn std::error::Error>>(())
595    /// ```
596    pub fn context(&self) -> &TraceContext {
597        &self.ctx
598    }
599
600    /// Return the context value behind this tensor.
601    #[doc(hidden)]
602    pub fn trace_value(&self) -> TraceValue {
603        self.value
604    }
605
606    /// Replace this tensor's value with a bound input of the same context.
607    ///
608    /// Used by checkpointing, which rebinds the traced value to the input that
609    /// holds the evaluated data.
610    #[doc(hidden)]
611    pub fn rebind_bound(&mut self, value: TraceValue, data: Arc<RetainedValue>) -> Result<()> {
612        let rebased = crate::trace_ops::finish_bound_value(&self.ctx, value, data)?;
613        *self = rebased;
614        Ok(())
615    }
616
617    /// Symbolic tensor id used for rank-only shape hints.
618    fn symbolic_id(&self) -> u64 {
619        self.symbolic_id
620    }
621
622    /// Returns `true` iff every dim of this tensor's `shape_hint` is a
623    /// constant `SymDim` (i.e. the shape is fully known at graph-build time).
624    ///
625    /// # Examples
626    ///
627    /// ```
628    /// use tenferro_tensor::DType;
629    /// use tenferro_runtime::{TracedTensor};
630    ///
631    /// use tenferro_runtime::TraceContext;
632    /// let trace = TraceContext::new();
633    /// let a = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
634    /// let b = trace.input_symbolic_shape(DType::F64, 2).unwrap();
635    /// assert!(a.is_concrete_shape());
636    /// assert!(!b.is_concrete_shape());
637    /// ```
638    pub fn is_concrete_shape(&self) -> bool {
639        try_concrete_shape(self).is_some()
640    }
641
642    /// Return the fully-concrete shape of this tensor, if every dim of
643    /// its shape-hint is a constant `SymDim`. Returns `None` if any
644    /// dimension is symbolic.
645    ///
646    /// This is the counterpart to [`Self::is_concrete_shape`] for callers
647    /// that need to *use* the concrete shape (e.g. external composition
648    /// wrappers building `broadcast_in_dim` payloads from known shapes).
649    ///
650    /// # Examples
651    ///
652    /// ```
653    /// use tenferro_tensor::DType;
654    /// use tenferro_runtime::{TracedTensor};
655    ///
656    /// use tenferro_runtime::TraceContext;
657    /// let trace = TraceContext::new();
658    /// let a = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
659    /// assert_eq!(a.try_concrete_shape(), Some(vec![2, 3]));
660    ///
661    /// let b = trace.input_symbolic_shape(DType::F64, 2).unwrap();
662    /// assert!(b.try_concrete_shape().is_none());
663    /// ```
664    pub fn try_concrete_shape(&self) -> Option<Vec<usize>> {
665        try_concrete_shape(self)
666    }
667
668    /// Return the concrete tensor shape.
669    ///
670    /// Returns an error when a shape hint is missing or any dimension is
671    /// symbolic. Composite traced ops that require concrete sizes should
672    /// propagate this error instead of panicking.
673    ///
674    /// # Errors
675    ///
676    /// Returns [`Error::Validation`] with `InvalidArgument` when this tensor
677    /// has no shape hint or any dimension is symbolic.
678    pub fn concrete_shape(&self) -> Result<Vec<usize>> {
679        concrete_shape(self)
680    }
681
682    /// If this `TracedTensor` is a leaf (single-node input graph),
683    /// return its input key. Computed tensors return `None`.
684    pub fn input_key(&self) -> Option<TensorInputKey> {
685        self.ctx.input_key(self.value)
686    }
687
688    /// Elementwise addition with NumPy-style broadcasting.
689    ///
690    /// Prefer using the `+` operator when it reads naturally.
691    ///
692    /// A longer expression such as `a + b + c` does not compose because the
693    /// first `+` returns `Result<TracedTensor, Error>`, so the second `+`
694    /// would receive a result rather than a tensor. Use `?` at each step or
695    /// the explicit fallible method chain shown below when the operation
696    /// sequence is more important than notation:
697    ///
698    /// # Examples
699    ///
700    /// ```rust
701    /// # use tenferro_runtime::{Error, TracedTensor};
702    /// use tenferro_runtime::TraceContext;
703    /// let trace = TraceContext::new();
704    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
705    /// # let z = trace.from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap();
706    /// let y = x.add(&z);
707    /// let y2 = &x + &z;
708    /// # fn add_three(
709    /// #     a: &TracedTensor,
710    /// #     b: &TracedTensor,
711    /// #     c: &TracedTensor,
712    /// # ) -> Result<TracedTensor, Error> {
713    /// let ab = (a + b)?;
714    /// let sum = (&ab + c)?;
715    /// let method_chain = a.add(b)?.add(c)?;
716    /// let _ = method_chain;
717    /// # Ok(sum)
718    /// # }
719    /// ```
720    ///
721    /// Tenferro prioritizes robust error handling over the conciseness of
722    /// chained operator notation; the explicit fallible methods are the
723    /// canonical form for longer sequences.
724    ///
725    /// # Errors
726    ///
727    /// Returns [`Error::Validation`] with `ShapeMismatch` when operand shapes
728    /// cannot be broadcast, or [`Error::RuntimeStateSource`] when graph
729    /// metadata registration fails.
730    ///
731    /// # Deferred errors
732    ///
733    /// If symbolic dimensions prevent shape comparison during graph
734    /// construction, the same `ShapeMismatch` can be reported during
735    /// compilation or execution, with the corresponding [`ErrorPhase`].
736    pub fn add(&self, other: &TracedTensor) -> Result<TracedTensor> {
737        let (lhs, rhs) = broadcast_binary(self, other)?;
738        apply_binary(
739            StdTensorOp::Add,
740            &lhs,
741            &rhs,
742            lhs.rank,
743            lhs.shape_hint.clone(),
744        )
745    }
746
747    /// Elementwise subtraction with NumPy-style broadcasting.
748    ///
749    /// Prefer using the `-` operator when it reads naturally.
750    ///
751    /// # Errors
752    ///
753    /// Returns [`Error::Validation`] with `ShapeMismatch` when operand shapes
754    /// cannot be broadcast, or [`Error::RuntimeStateSource`] when graph
755    /// metadata registration fails.
756    ///
757    /// # Deferred errors
758    ///
759    /// If symbolic dimensions prevent shape comparison during graph
760    /// construction, the same `ShapeMismatch` can be reported during
761    /// compilation or execution, with the corresponding [`ErrorPhase`].
762    pub fn sub(&self, other: &TracedTensor) -> Result<TracedTensor> {
763        let (lhs, rhs) = broadcast_binary(self, other)?;
764        apply_binary(
765            StdTensorOp::Sub,
766            &lhs,
767            &rhs,
768            lhs.rank,
769            lhs.shape_hint.clone(),
770        )
771    }
772
773    /// Elementwise multiplication with NumPy-style broadcasting.
774    ///
775    /// Prefer using the `*` operator when it reads naturally.
776    ///
777    /// # Examples
778    ///
779    /// ```rust
780    /// # use tenferro_runtime::{TracedTensor};
781    /// use tenferro_runtime::TraceContext;
782    /// let trace = TraceContext::new();
783    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
784    /// # let z = trace.from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap();
785    /// let y = x.mul(&z);
786    /// let y2 = &x * &z;
787    /// ```
788    ///
789    /// # Errors
790    ///
791    /// Returns [`Error::Validation`] with `ShapeMismatch` when operand shapes
792    /// cannot be broadcast, or [`Error::RuntimeStateSource`] when graph
793    /// metadata registration fails.
794    ///
795    /// # Deferred errors
796    ///
797    /// If symbolic ranks prevent shape comparison during graph construction,
798    /// the same `ShapeMismatch` can be reported during compilation or
799    /// execution, with the corresponding [`ErrorPhase`].
800    pub fn mul(&self, other: &TracedTensor) -> Result<TracedTensor> {
801        let (lhs, rhs) = broadcast_binary(self, other)?;
802        apply_binary(
803            StdTensorOp::Mul,
804            &lhs,
805            &rhs,
806            lhs.rank,
807            lhs.shape_hint.clone(),
808        )
809    }
810
811    /// Elementwise division with NumPy-style broadcasting.
812    ///
813    /// Prefer using the `/` operator when it reads naturally.
814    ///
815    /// # Examples
816    ///
817    /// ```rust
818    /// # use tenferro_runtime::{TracedTensor};
819    /// use tenferro_runtime::TraceContext;
820    /// let trace = TraceContext::new();
821    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
822    /// # let z = trace.from_vec_col_major(vec![2], vec![3.0_f64, 4.0]).unwrap();
823    /// let y = x.div(&z);
824    /// let y2 = &x / &z;
825    /// ```
826    ///
827    /// # Errors
828    ///
829    /// Returns [`Error::Validation`] with `ShapeMismatch` when operand shapes
830    /// cannot be broadcast, or [`Error::RuntimeStateSource`] when graph
831    /// metadata registration fails.
832    ///
833    /// # Deferred errors
834    ///
835    /// If symbolic ranks prevent shape comparison during graph construction,
836    /// the same `ShapeMismatch` can be reported during compilation or
837    /// execution, with the corresponding [`ErrorPhase`]. For integer inputs,
838    /// a zero divisor is reported during execution as
839    /// [`Error::TensorRuntime`] containing a
840    /// [`tenferro_tensor::Error::Extension`] classified as
841    /// `tenferro_tensor::ErrorKind::NumericalFailure` and retaining the typed
842    /// backend source; floating-point and complex zero divisors follow their
843    /// numeric semantics instead.
844    pub fn div(&self, other: &TracedTensor) -> Result<TracedTensor> {
845        let (lhs, rhs) = broadcast_binary(self, other)?;
846        apply_binary(
847            StdTensorOp::Div,
848            &lhs,
849            &rhs,
850            lhs.rank,
851            lhs.shape_hint.clone(),
852        )
853    }
854
855    /// Elementwise remainder with NumPy-style broadcasting.
856    ///
857    /// Prefer using the `%` operator when it reads naturally.
858    ///
859    /// # Errors
860    ///
861    /// Returns [`Error::Validation`] with `ShapeMismatch` when operand shapes
862    /// cannot be broadcast, [`Error::Unsupported`] at
863    /// [`ErrorPhase::GraphBuild`] when either operand has a complex dtype, or
864    /// [`Error::RuntimeStateSource`] when graph metadata registration fails.
865    ///
866    /// # Deferred errors
867    ///
868    /// If symbolic ranks prevent shape comparison during graph construction,
869    /// the same `ShapeMismatch` can be reported during compilation or
870    /// execution, with the corresponding [`ErrorPhase`]. For integer inputs,
871    /// a zero divisor is reported during execution as
872    /// [`Error::TensorRuntime`] containing a
873    /// [`tenferro_tensor::Error::Extension`] classified as
874    /// `tenferro_tensor::ErrorKind::NumericalFailure` and retaining the typed
875    /// backend source; floating-point zero divisors follow their numeric
876    /// semantics.
877    pub fn rem(&self, other: &TracedTensor) -> Result<TracedTensor> {
878        let (lhs, rhs) = broadcast_binary(self, other)?;
879        apply_binary(
880            StdTensorOp::Rem,
881            &lhs,
882            &rhs,
883            lhs.rank,
884            lhs.shape_hint.clone(),
885        )
886    }
887
888    /// Elementwise comparison with NumPy-style broadcasting.
889    ///
890    /// # Errors
891    ///
892    /// Returns [`Error::Validation`] with `ShapeMismatch` when the concrete
893    /// operands cannot be broadcast, [`Error::Unsupported`] when ordered
894    /// comparison rejects a complex dtype, or [`Error::RuntimeStateSource`]
895    /// when result metadata cannot be registered.
896    ///
897    /// # Deferred errors
898    ///
899    /// With same-rank symbolic operands, shape compatibility is retained as a
900    /// graph constraint. A concrete mismatch is reported later as
901    /// [`Error::TensorRuntime`] containing a typed validation source, with the
902    /// failure phase identifying compilation or execution.
903    pub fn compare(&self, other: &TracedTensor, dir: CompareDir) -> Result<TracedTensor> {
904        apply_broadcast_binary_op(StdTensorOp::Compare(dir), self, other)
905    }
906
907    /// Elementwise maximum with NumPy-style broadcasting.
908    ///
909    /// # Errors
910    ///
911    /// Returns [`Error::Validation`] with `ShapeMismatch` when the concrete
912    /// operands cannot be broadcast, [`Error::Unsupported`] when ordered
913    /// maximum rejects a complex dtype, or [`Error::RuntimeStateSource`] when
914    /// result metadata cannot be registered.
915    ///
916    /// # Deferred errors
917    ///
918    /// With same-rank symbolic operands, the broadcast constraint may fail at
919    /// compile or execution and is returned as [`Error::TensorRuntime`] with
920    /// its typed validation source.
921    pub fn maximum(&self, other: &TracedTensor) -> Result<TracedTensor> {
922        apply_broadcast_binary_op(StdTensorOp::Maximum, self, other)
923    }
924
925    /// Elementwise minimum with NumPy-style broadcasting.
926    ///
927    /// # Errors
928    ///
929    /// Returns [`Error::Validation`] with `ShapeMismatch` when the concrete
930    /// operands cannot be broadcast, [`Error::Unsupported`] when ordered
931    /// minimum rejects a complex dtype, or [`Error::RuntimeStateSource`] when
932    /// result metadata cannot be registered.
933    ///
934    /// # Deferred errors
935    ///
936    /// With same-rank symbolic operands, the broadcast constraint may fail at
937    /// compile or execution and is returned as [`Error::TensorRuntime`] with
938    /// its typed validation source.
939    pub fn minimum(&self, other: &TracedTensor) -> Result<TracedTensor> {
940        apply_broadcast_binary_op(StdTensorOp::Minimum, self, other)
941    }
942
943    /// Select values from `on_true` or `on_false` using `condition`.
944    ///
945    /// # Errors
946    ///
947    /// Returns [`Error::Validation`] with `InvalidArgument` when an operand
948    /// lacks concrete shape metadata, or `ShapeMismatch` when the concrete
949    /// condition and branches cannot share a broadcast shape. Dtype promotion
950    /// failures are returned as [`Error::TensorRuntime`] with the typed
951    /// `UnsupportedDTypeConversion` source; metadata failures retain
952    /// [`Error::RuntimeStateSource`].
953    pub fn where_select(
954        condition: &TracedTensor,
955        on_true: &TracedTensor,
956        on_false: &TracedTensor,
957    ) -> Result<TracedTensor> {
958        apply_broadcast_ternary_op(StdTensorOp::Select, condition, on_true, on_false)
959    }
960
961    /// Alias for [`Self::where_select`].
962    ///
963    /// # Errors
964    ///
965    /// Returns the same concrete failures as [`Self::where_select`]:
966    /// [`Error::Validation`] with `InvalidArgument`/`ShapeMismatch` for shape
967    /// metadata or broadcasting, [`Error::TensorRuntime`] with
968    /// `UnsupportedDTypeConversion` for failed promotion, and
969    /// [`Error::RuntimeStateSource`] for metadata registration.
970    pub fn select(
971        condition: &TracedTensor,
972        on_true: &TracedTensor,
973        on_false: &TracedTensor,
974    ) -> Result<TracedTensor> {
975        Self::where_select(condition, on_true, on_false)
976    }
977
978    /// Clamp values elementwise between lower and upper bounds.
979    ///
980    /// # Errors
981    ///
982    /// Returns [`Error::Validation`] with `InvalidArgument` when an operand
983    /// lacks concrete shape metadata, `ShapeMismatch` when bounds cannot be
984    /// broadcast with the input, [`Error::Unsupported`] for an ordered
985    /// complex dtype, or [`Error::RuntimeStateSource`] when metadata cannot be
986    /// registered.
987    pub fn clamp(&self, lower: &TracedTensor, upper: &TracedTensor) -> Result<TracedTensor> {
988        apply_broadcast_ternary_op(StdTensorOp::Clamp, self, lower, upper)
989    }
990
991    fn apply_same_shape_unary(&self, op: StdTensorOp) -> Result<TracedTensor> {
992        apply_unary(op, self, self.rank, self.shape_hint.clone())
993    }
994
995    /// Elementwise negation.
996    ///
997    /// Prefer using the unary `-` operator when it reads naturally.
998    ///
999    /// # Examples
1000    ///
1001    /// ```rust
1002    /// # use tenferro_runtime::{TracedTensor};
1003    /// use tenferro_runtime::TraceContext;
1004    /// let trace = TraceContext::new();
1005    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1006    /// let y = x.neg().unwrap();
1007    /// let y2 = (-&x).unwrap();
1008    /// ```
1009    ///
1010    /// # Errors
1011    ///
1012    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1013    /// is unavailable or poisoned while recording the unary result.
1014    pub fn neg(&self) -> Result<TracedTensor> {
1015        self.apply_same_shape_unary(StdTensorOp::Neg)
1016    }
1017
1018    /// Elementwise complex conjugate.
1019    ///
1020    /// # Examples
1021    ///
1022    /// ```rust
1023    /// # use num_complex::Complex64;
1024    /// # use tenferro_runtime::{TracedTensor};
1025    /// use tenferro_runtime::TraceContext;
1026    /// let trace = TraceContext::new();
1027    /// # let x = trace.from_vec_col_major(
1028    /// #     vec![2],
1029    /// #     vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)],
1030    /// # )
1031    /// # .unwrap();
1032    /// let y = x.conj().unwrap();
1033    /// ```
1034    ///
1035    /// # Errors
1036    ///
1037    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1038    /// is unavailable or poisoned while recording the unary result.
1039    pub fn conj(&self) -> Result<TracedTensor> {
1040        self.apply_same_shape_unary(StdTensorOp::Conj)
1041    }
1042
1043    /// Elementwise absolute value.
1044    ///
1045    /// Complex inputs return real magnitudes (`C32 -> F32`, `C64 -> F64`).
1046    ///
1047    /// # Examples
1048    ///
1049    /// ```rust
1050    /// # use tenferro_runtime::{TracedTensor};
1051    /// use tenferro_runtime::TraceContext;
1052    /// let trace = TraceContext::new();
1053    /// # let x = trace.from_vec_col_major(vec![2], vec![-1.0_f64, 2.0]).unwrap();
1054    /// let y = x.abs().unwrap();
1055    /// ```
1056    ///
1057    /// # Errors
1058    ///
1059    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1060    /// is unavailable or poisoned while recording the unary result.
1061    pub fn abs(&self) -> Result<TracedTensor> {
1062        self.apply_same_shape_unary(StdTensorOp::Abs)
1063    }
1064
1065    /// Elementwise sign.
1066    ///
1067    /// # Examples
1068    ///
1069    /// ```rust
1070    /// # use tenferro_runtime::{TracedTensor};
1071    /// use tenferro_runtime::TraceContext;
1072    /// let trace = TraceContext::new();
1073    /// # let x = trace.from_vec_col_major(vec![2], vec![-1.0_f64, 2.0]).unwrap();
1074    /// let y = x.sign().unwrap();
1075    /// ```
1076    ///
1077    /// # Errors
1078    ///
1079    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1080    /// is unavailable or poisoned while recording the unary result.
1081    pub fn sign(&self) -> Result<TracedTensor> {
1082        self.apply_same_shape_unary(StdTensorOp::Sign)
1083    }
1084
1085    /// Scale by a real scalar: `y = factor * x`.
1086    ///
1087    /// # Examples
1088    ///
1089    /// ```rust
1090    /// # use tenferro_runtime::{TracedTensor};
1091    /// use tenferro_runtime::TraceContext;
1092    /// let trace = TraceContext::new();
1093    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1094    /// let y = x.scale_real(2.0)?;
1095    /// # Ok::<(), tenferro_runtime::Error>(())
1096    /// ```
1097    ///
1098    /// # Errors
1099    ///
1100    /// Returns [`Error::Validation`] with `InvalidArgument` when an integer or
1101    /// boolean factor is non-finite or out of range for the input dtype, or
1102    /// [`Error::RuntimeStateSource`] when output metadata registration fails.
1103    pub fn scale_real(&self, factor: f64) -> Result<TracedTensor> {
1104        let op = match self.dtype {
1105            DType::F64 => StdTensorOp::constant(factor),
1106            DType::F32 => StdTensorOp::constant(factor as f32),
1107            DType::I32 => StdTensorOp::constant(round_real_to_i32_for_op("scale_real", factor)?),
1108            DType::I64 => StdTensorOp::constant(round_real_to_i64(factor)?),
1109            DType::Bool => StdTensorOp::constant(bool_from_real_for_op("scale_real", factor)?),
1110            DType::C64 => StdTensorOp::constant(Complex64::new(factor, 0.0)),
1111            DType::C32 => StdTensorOp::constant(Complex32::new(factor as f32, 0.0)),
1112            // An externally defined scalar has no traced constant, so the closure
1113            // rejects it instead of guessing one.
1114            DType::External(_) => {
1115                return Err(graph_invalid_argument(
1116                    "scale_real",
1117                    "dtype",
1118                    format!("requires a preset tensor dtype, got {:?}", self.dtype),
1119                ));
1120            }
1121        };
1122        scale_with_constant(self, op)
1123    }
1124
1125    /// Scale by a complex scalar: `y = factor * x`.
1126    ///
1127    /// Only complex tensors support complex scaling. For a real scalar factor
1128    /// that should preserve the input dtype, prefer [`scale_real`](Self::scale_real).
1129    ///
1130    /// # Examples
1131    ///
1132    /// ```rust
1133    /// use num_complex::Complex64;
1134    /// # use tenferro_runtime::{TracedTensor};
1135    /// use tenferro_runtime::TraceContext;
1136    /// let trace = TraceContext::new();
1137    /// # let x = trace.from_vec_col_major(
1138    /// #     vec![2],
1139    /// #     vec![Complex64::new(1.0, 0.0), Complex64::new(2.0, 0.0)],
1140    /// # )
1141    /// # .unwrap();
1142    /// let y = x.scale_complex(Complex64::new(0.0, 1.0)).unwrap(); // multiply by i
1143    /// ```
1144    ///
1145    /// # Errors
1146    ///
1147    /// Returns [`Error::Validation`] with `InvalidArgument` when a complex
1148    /// factor is applied to a non-complex dtype, or
1149    /// [`Error::RuntimeStateSource`] when output metadata registration fails.
1150    pub fn scale_complex(&self, factor: Complex64) -> Result<TracedTensor> {
1151        match self.dtype {
1152            DType::C64 => scale_with_constant(self, StdTensorOp::constant(factor)),
1153            DType::C32 => scale_with_constant(
1154                self,
1155                StdTensorOp::constant(Complex32::new(factor.re as f32, factor.im as f32)),
1156            ),
1157            DType::F32
1158            | DType::F64
1159            | DType::I32
1160            | DType::I64
1161            | DType::Bool
1162            | DType::External(_) => Err(graph_invalid_argument(
1163                "scale_complex",
1164                "dtype",
1165                format!("requires complex tensor dtype, got {:?}", self.dtype),
1166            )),
1167        }
1168    }
1169
1170    /// Elementwise exponential.
1171    ///
1172    /// # Examples
1173    ///
1174    /// ```rust
1175    /// # use tenferro_runtime::{TracedTensor};
1176    /// use tenferro_runtime::TraceContext;
1177    /// let trace = TraceContext::new();
1178    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1179    /// let y = x.exp().unwrap();
1180    /// ```
1181    ///
1182    /// # Errors
1183    ///
1184    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1185    /// is unavailable or poisoned while recording the unary result.
1186    pub fn exp(&self) -> Result<TracedTensor> {
1187        self.apply_same_shape_unary(StdTensorOp::Exp)
1188    }
1189
1190    /// Elementwise natural logarithm.
1191    ///
1192    /// # Examples
1193    ///
1194    /// ```rust
1195    /// # use tenferro_runtime::{TracedTensor};
1196    /// use tenferro_runtime::TraceContext;
1197    /// let trace = TraceContext::new();
1198    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1199    /// let y = x.log().unwrap();
1200    /// ```
1201    ///
1202    /// # Errors
1203    ///
1204    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1205    /// is unavailable or poisoned while recording the unary result.
1206    pub fn log(&self) -> Result<TracedTensor> {
1207        self.apply_same_shape_unary(StdTensorOp::Log)
1208    }
1209
1210    /// Elementwise sine.
1211    ///
1212    /// # Examples
1213    ///
1214    /// ```rust
1215    /// # use tenferro_runtime::{TracedTensor};
1216    /// use tenferro_runtime::TraceContext;
1217    /// let trace = TraceContext::new();
1218    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1219    /// let y = x.sin().unwrap();
1220    /// ```
1221    ///
1222    /// # Errors
1223    ///
1224    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1225    /// is unavailable or poisoned while recording the unary result.
1226    pub fn sin(&self) -> Result<TracedTensor> {
1227        self.apply_same_shape_unary(StdTensorOp::Sin)
1228    }
1229
1230    /// Elementwise cosine.
1231    ///
1232    /// # Examples
1233    ///
1234    /// ```rust
1235    /// # use tenferro_runtime::{TracedTensor};
1236    /// use tenferro_runtime::TraceContext;
1237    /// let trace = TraceContext::new();
1238    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1239    /// let y = x.cos().unwrap();
1240    /// ```
1241    ///
1242    /// # Errors
1243    ///
1244    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1245    /// is unavailable or poisoned while recording the unary result.
1246    pub fn cos(&self) -> Result<TracedTensor> {
1247        self.apply_same_shape_unary(StdTensorOp::Cos)
1248    }
1249
1250    /// Elementwise hyperbolic tangent.
1251    ///
1252    /// # Examples
1253    ///
1254    /// ```rust
1255    /// # use tenferro_runtime::{TracedTensor};
1256    /// use tenferro_runtime::TraceContext;
1257    /// let trace = TraceContext::new();
1258    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1259    /// let y = x.tanh().unwrap();
1260    /// ```
1261    ///
1262    /// # Errors
1263    ///
1264    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1265    /// is unavailable or poisoned while recording the unary result.
1266    pub fn tanh(&self) -> Result<TracedTensor> {
1267        self.apply_same_shape_unary(StdTensorOp::Tanh)
1268    }
1269
1270    /// Elementwise square root.
1271    ///
1272    /// # Examples
1273    ///
1274    /// ```rust
1275    /// # use tenferro_runtime::{TracedTensor};
1276    /// use tenferro_runtime::TraceContext;
1277    /// let trace = TraceContext::new();
1278    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 4.0]).unwrap();
1279    /// let y = x.sqrt().unwrap();
1280    /// ```
1281    ///
1282    /// # Errors
1283    ///
1284    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1285    /// is unavailable or poisoned while recording the unary result.
1286    pub fn sqrt(&self) -> Result<TracedTensor> {
1287        self.apply_same_shape_unary(StdTensorOp::Sqrt)
1288    }
1289
1290    /// Elementwise reciprocal square root.
1291    ///
1292    /// # Examples
1293    ///
1294    /// ```rust
1295    /// # use tenferro_runtime::{TracedTensor};
1296    /// use tenferro_runtime::TraceContext;
1297    /// let trace = TraceContext::new();
1298    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 4.0]).unwrap();
1299    /// let y = x.rsqrt().unwrap();
1300    /// ```
1301    ///
1302    /// # Errors
1303    ///
1304    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1305    /// is unavailable or poisoned while recording the unary result.
1306    pub fn rsqrt(&self) -> Result<TracedTensor> {
1307        self.apply_same_shape_unary(StdTensorOp::Rsqrt)
1308    }
1309
1310    /// Elementwise power with NumPy-style broadcasting.
1311    ///
1312    /// # Examples
1313    ///
1314    /// ```rust
1315    /// # use tenferro_runtime::{TracedTensor};
1316    /// use tenferro_runtime::TraceContext;
1317    /// let trace = TraceContext::new();
1318    /// # let base = trace.from_vec_col_major(vec![2], vec![2.0_f64, 3.0]).unwrap();
1319    /// # let exp = trace.from_vec_col_major(vec![2], vec![3.0_f64, 2.0]).unwrap();
1320    /// let y = base.pow(&exp);
1321    /// ```
1322    ///
1323    /// # Errors
1324    ///
1325    /// Returns [`Error::Validation`] with `ShapeMismatch` when the concrete
1326    /// operands cannot be broadcast, or [`Error::RuntimeStateSource`] when
1327    /// result metadata cannot be registered.
1328    ///
1329    /// # Deferred errors
1330    ///
1331    /// A symbolic broadcast mismatch or integer negative exponent is
1332    /// discovered at compile or execution and is returned as
1333    /// [`Error::TensorRuntime`] with a typed `ShapeMismatch` or
1334    /// `NegativeIntegerExponent` numerical source and the corresponding
1335    /// [`ErrorPhase`].
1336    pub fn pow(&self, other: &TracedTensor) -> Result<TracedTensor> {
1337        let (lhs, rhs) = broadcast_binary(self, other)?;
1338        apply_binary(
1339            StdTensorOp::Pow,
1340            &lhs,
1341            &rhs,
1342            lhs.rank,
1343            lhs.shape_hint.clone(),
1344        )
1345    }
1346
1347    /// Elementwise `exp(x) - 1`.
1348    ///
1349    /// # Examples
1350    ///
1351    /// ```rust
1352    /// # use tenferro_runtime::{TracedTensor};
1353    /// use tenferro_runtime::TraceContext;
1354    /// let trace = TraceContext::new();
1355    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1356    /// let y = x.expm1().unwrap();
1357    /// ```
1358    ///
1359    /// # Errors
1360    ///
1361    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1362    /// is unavailable or poisoned while recording the unary result.
1363    pub fn expm1(&self) -> Result<TracedTensor> {
1364        self.apply_same_shape_unary(StdTensorOp::Expm1)
1365    }
1366
1367    /// Elementwise `log(1 + x)`.
1368    ///
1369    /// # Examples
1370    ///
1371    /// ```rust
1372    /// # use tenferro_runtime::{TracedTensor};
1373    /// use tenferro_runtime::TraceContext;
1374    /// let trace = TraceContext::new();
1375    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1376    /// let y = x.log1p().unwrap();
1377    /// ```
1378    ///
1379    /// # Errors
1380    ///
1381    /// Returns [`Error::RuntimeStateSource`] when the graph metadata registry
1382    /// is unavailable or poisoned while recording the unary result.
1383    pub fn log1p(&self) -> Result<TracedTensor> {
1384        self.apply_same_shape_unary(StdTensorOp::Log1p)
1385    }
1386
1387    /// Elementwise error function `erf(x)`, for real `F32`/`F64` tensors.
1388    ///
1389    /// `erf(+-0) = +-0`, `erf(+-inf) = +-1`, and `NaN` stays `NaN`. The
1390    /// derivative is `2/sqrt(pi) * exp(-x^2)`.
1391    ///
1392    /// # Examples
1393    ///
1394    /// ```rust
1395    /// # use tenferro_runtime::{TracedTensor};
1396    /// use tenferro_runtime::TraceContext;
1397    /// let trace = TraceContext::new();
1398    /// let x = trace.from_vec_col_major(vec![2], vec![0.0_f64, 1.0])?;
1399    /// let y = x.erf()?;
1400    /// assert_eq!(y.dtype(), tenferro_runtime::DType::F64);
1401    /// # Ok::<(), tenferro_runtime::Error>(())
1402    /// ```
1403    ///
1404    /// # Errors
1405    ///
1406    /// Returns [`Error::Unsupported`] (phase `GraphBuild`) for complex,
1407    /// integer, or `Bool` input, or [`Error::RuntimeStateSource`] when the
1408    /// graph metadata registry is unavailable or poisoned while recording the
1409    /// unary result.
1410    pub fn erf(&self) -> Result<TracedTensor> {
1411        if !matches!(self.dtype, DType::F32 | DType::F64) {
1412            return Err(Error::unsupported(
1413                "TracedTensor::erf",
1414                ErrorPhase::GraphBuild,
1415                format!(
1416                    "erf is defined for real F32/F64 tensors, got {:?}",
1417                    self.dtype
1418                ),
1419            ));
1420        }
1421        self.apply_same_shape_unary(StdTensorOp::Erf)
1422    }
1423
1424    /// Convert the tensor to a different dtype using checked conversion.
1425    ///
1426    /// Use [`cast`](Self::cast) when a lossy dtype projection is intended.
1427    ///
1428    /// # Examples
1429    ///
1430    /// ```rust
1431    /// use tenferro_runtime::DType;
1432    /// use tenferro_runtime::TraceContext;
1433    /// # use tenferro_runtime::{TracedTensor};
1434    /// let trace = TraceContext::new();
1435    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
1436    ///
1437    /// let y = x.convert(DType::C64)?;
1438    /// # Ok::<(), tenferro_runtime::Error>(())
1439    /// ```
1440    ///
1441    /// # Errors
1442    ///
1443    /// Returns [`tenferro_tensor::Error::UnsupportedDTypeConversion`] when the
1444    /// requested pair is outside tenferro's checked dtype-promotion lattice,
1445    /// or [`Error::Validation`] when graph metadata rejects the conversion.
1446    /// Use [`cast`](Self::cast) for explicit lossy dtype projection.
1447    pub fn convert(&self, to: DType) -> Result<TracedTensor> {
1448        tenferro_tensor::validate::validate_convert_dtype("TracedTensor::convert", self.dtype, to)?;
1449        self.cast(to)
1450    }
1451
1452    /// Cast the tensor to a different dtype using explicit dtype projection.
1453    ///
1454    /// `cast` may truncate, narrow precision, project complex values to their
1455    /// real component, or use boolean truthiness where the backend supports the
1456    /// requested projection.
1457    ///
1458    /// # Examples
1459    ///
1460    /// ```rust
1461    /// use tenferro_runtime::DType;
1462    /// use tenferro_runtime::TraceContext;
1463    /// # use tenferro_runtime::{TracedTensor};
1464    /// let trace = TraceContext::new();
1465    /// # let x = trace.from_vec_col_major(vec![2], vec![1.2_f64, -2.8]).unwrap();
1466    ///
1467    /// let y = x.cast(DType::I32).unwrap();
1468    /// ```
1469    ///
1470    /// # Errors
1471    ///
1472    /// Returns [`Error::TensorRuntime`] containing
1473    /// `UnsupportedDTypeConversion` when the requested input-to-target
1474    /// projection is not supported, or [`Error::RuntimeStateSource`] when
1475    /// converted-output metadata cannot be registered.
1476    pub fn cast(&self, to: DType) -> Result<TracedTensor> {
1477        if self.dtype == to {
1478            return Ok(self.clone());
1479        }
1480
1481        apply_unary_with_dtype(
1482            StdTensorOp::Convert {
1483                from: self.dtype,
1484                to,
1485            },
1486            self,
1487            self.rank,
1488            self.shape_hint.clone(),
1489            to,
1490        )
1491    }
1492
1493    /// Generalized tensor contraction.
1494    ///
1495    /// The output layout is `[lhs free..., rhs free..., batch...]`: batch axes
1496    /// come last (see [`DotGeneralConfig`]).
1497    ///
1498    /// # Examples
1499    ///
1500    /// ```rust
1501    /// # use tenferro_runtime::{DotGeneralConfig, TracedTensor};
1502    /// use tenferro_runtime::TraceContext;
1503    /// let trace = TraceContext::new();
1504    /// # let a = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
1505    /// # let b = trace.from_vec_col_major(vec![3, 4], vec![1.0_f64; 12]).unwrap();
1506    /// # let config = DotGeneralConfig {
1507    /// #     lhs_contracting_dims: [1].as_slice().into(),
1508    /// #     rhs_contracting_dims: [0].as_slice().into(),
1509    /// #     lhs_batch_dims: [].as_slice().into(),
1510    /// #     rhs_batch_dims: [].as_slice().into(),
1511    /// # };
1512    /// let y = a.dot_general(&b, config)?;
1513    /// # Ok::<(), tenferro_runtime::Error>(())
1514    /// ```
1515    ///
1516    /// # Errors
1517    ///
1518    /// Returns [`Error::Validation`] with `RankMismatch`, `AxisOutOfBounds`,
1519    /// `DuplicateAxis`, or `AxisRoleConflict` when dimension numbers are
1520    /// invalid for the operand ranks, and [`Error::RuntimeStateSource`] when
1521    /// output metadata cannot be registered.
1522    ///
1523    /// # Deferred errors
1524    ///
1525    /// Contracting or batch dimensions whose sizes are symbolic are checked
1526    /// when concrete inputs reach compilation or execution. A mismatch is
1527    /// returned as [`Error::TensorRuntime`] with a typed `ShapeMismatch`
1528    /// source and its corresponding [`ErrorPhase`].
1529    pub fn dot_general(
1530        &self,
1531        other: &TracedTensor,
1532        config: DotGeneralConfig,
1533    ) -> Result<TracedTensor> {
1534        config
1535            .validate_dims_with_ranks(self.rank, other.rank)
1536            .map_err(|err| graph_tensor_error("dot_general", err))?;
1537        let lhs_free: Vec<usize> = (0..self.rank)
1538            .filter(|d| {
1539                !config.lhs_contracting_dims.contains(d) && !config.lhs_batch_dims.contains(d)
1540            })
1541            .collect();
1542        let rhs_free: Vec<usize> = (0..other.rank)
1543            .filter(|d| {
1544                !config.rhs_contracting_dims.contains(d) && !config.rhs_batch_dims.contains(d)
1545            })
1546            .collect();
1547        let out_rank = config.lhs_batch_dims.len() + lhs_free.len() + rhs_free.len();
1548        let out_shape_hint = match (&self.shape_hint, &other.shape_hint) {
1549            (Some(lhs_shape), Some(rhs_shape)) => {
1550                let mut out_shape = Vec::with_capacity(out_rank);
1551                for &d in &lhs_free {
1552                    out_shape.push(lhs_shape[d].clone());
1553                }
1554                for &d in &rhs_free {
1555                    out_shape.push(rhs_shape[d].clone());
1556                }
1557                for &d in &config.lhs_batch_dims {
1558                    out_shape.push(lhs_shape[d].clone());
1559                }
1560                Some(out_shape)
1561            }
1562            _ => None,
1563        };
1564
1565        apply_binary(
1566            StdTensorOp::DotGeneral { config },
1567            self,
1568            other,
1569            out_rank,
1570            out_shape_hint,
1571        )
1572    }
1573
1574    /// Matrix multiplication for rank-2 tensors.
1575    ///
1576    /// # Errors
1577    ///
1578    /// Returns [`Error::Validation`] with `RankMismatch` when either operand is
1579    /// not rank 2, `ShapeMismatch::ContractedDimensions` when known matrix
1580    /// dimensions differ, or [`Error::RuntimeStateSource`] when output
1581    /// metadata cannot be registered.
1582    ///
1583    /// # Deferred errors
1584    ///
1585    /// If either contracted dimension is symbolic, the mismatch is discovered
1586    /// at compilation or execution and returned as [`Error::TensorRuntime`]
1587    /// with its typed `ShapeMismatch` source.
1588    pub fn matmul(&self, other: &TracedTensor) -> Result<TracedTensor> {
1589        if self.rank != 2 {
1590            return Err(graph_validation(
1591                "TracedTensor::matmul",
1592                ValidationError::RankMismatch {
1593                    expected: 2,
1594                    actual: self.rank,
1595                },
1596            ));
1597        }
1598        if other.rank != 2 {
1599            return Err(graph_validation(
1600                "TracedTensor::matmul",
1601                ValidationError::RankMismatch {
1602                    expected: 2,
1603                    actual: other.rank,
1604                },
1605            ));
1606        }
1607        if let (Some(lhs_shape), Some(rhs_shape)) = (&self.shape_hint, &other.shape_hint)
1608            && let (Some(lhs_cols), Some(rhs_rows)) =
1609                (lhs_shape[1].constant_value(), rhs_shape[0].constant_value())
1610            && lhs_cols != rhs_rows
1611        {
1612            return Err(graph_validation(
1613                "TracedTensor::matmul",
1614                ShapeMismatch::ContractedDimensions {
1615                    lhs_axis: 1,
1616                    lhs_size: lhs_cols,
1617                    rhs_axis: 0,
1618                    rhs_size: rhs_rows,
1619                },
1620            ));
1621        }
1622        self.dot_general(
1623            other,
1624            DotGeneralConfig {
1625                lhs_contracting_dims: [1].as_slice().into(),
1626                rhs_contracting_dims: [0].as_slice().into(),
1627                lhs_batch_dims: [].as_slice().into(),
1628                rhs_batch_dims: [].as_slice().into(),
1629            },
1630        )
1631    }
1632
1633    /// Sum over the given axes.
1634    ///
1635    /// # Examples
1636    ///
1637    /// ```rust
1638    /// # use tenferro_runtime::{TracedTensor};
1639    /// use tenferro_runtime::TraceContext;
1640    /// let trace = TraceContext::new();
1641    /// # let x = trace.from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
1642    /// let total = x.reduce_sum(None)?;
1643    /// let rows = x.reduce_sum(Some(&[1]))?;
1644    /// let identity = x.reduce_sum(Some(&[]))?;
1645    /// assert_eq!(total.rank(), 0);
1646    /// assert_eq!(rows.rank(), 1);
1647    /// assert_eq!(identity.rank(), 2);
1648    /// # Ok::<(), tenferro_runtime::Error>(())
1649    /// ```
1650    ///
1651    /// # Errors
1652    ///
1653    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when an axis is
1654    /// outside the input rank or `DuplicateAxis` when `axes` repeats an axis,
1655    /// or [`Error::RuntimeStateSource`] when output metadata cannot be
1656    /// registered.
1657    pub fn reduce_sum(&self, axes: Option<&[isize]>) -> Result<TracedTensor> {
1658        let axes = match axes {
1659            Some(axes) => crate::shape_packing::normalize_existing_axes(
1660                "TracedTensor::reduce_sum",
1661                axes,
1662                self.rank,
1663            )?,
1664            None => (0..self.rank).collect(),
1665        };
1666        let (out_rank, out_shape_hint) =
1667            reduction_output_meta(self, &axes, "TracedTensor::reduce_sum")?;
1668        apply_unary(
1669            StdTensorOp::ReduceSum { axes },
1670            self,
1671            out_rank,
1672            out_shape_hint,
1673        )
1674    }
1675
1676    /// Sum elementwise squares over the requested axes.
1677    ///
1678    /// Each value is squared in its input dtype before reduction. The initial
1679    /// supported dtypes are `f32` and `f64`; other dtypes return a typed
1680    /// unsupported error during execution. `None` reduces every axis, like
1681    /// the rest of the reduction family; `Some(&[])` returns the elementwise
1682    /// square without reducing rank.
1683    ///
1684    /// This operation is useful when the squared sum is needed directly. Use
1685    /// the linalg norm APIs when a square root or complex magnitude semantics
1686    /// are required.
1687    ///
1688    /// # Errors
1689    ///
1690    /// Returns a typed validation error for invalid axes or a typed
1691    /// runtime-state error while registering output metadata.
1692    ///
1693    /// # Deferred errors
1694    ///
1695    /// Unsupported dtypes and backend execution failures are reported when the
1696    /// compiled graph is executed.
1697    /// # Examples
1698    ///
1699    /// ```rust
1700    /// # use tenferro_runtime::{TracedTensor};
1701    /// use tenferro_runtime::TraceContext;
1702    /// let trace = TraceContext::new();
1703    /// # let x = trace.from_vec_col_major(
1704    /// #     vec![2, 2],
1705    /// #     vec![1.0_f64, 2.0, 3.0, 4.0],
1706    /// # )?;
1707    /// let squares = x.reduce_sum_squares(Some(&[1]))?;
1708    /// assert_eq!(squares.rank(), 1);
1709    /// let total = x.reduce_sum_squares(None)?;
1710    /// assert_eq!(total.rank(), 0);
1711    /// # Ok::<(), tenferro_runtime::Error>(())
1712    /// ```
1713    pub fn reduce_sum_squares(&self, axes: Option<&[isize]>) -> Result<TracedTensor> {
1714        let axes = match axes {
1715            Some(axes) => crate::shape_packing::normalize_existing_axes(
1716                "TracedTensor::reduce_sum_squares",
1717                axes,
1718                self.rank,
1719            )?,
1720            None => (0..self.rank).collect(),
1721        };
1722        let (out_rank, out_shape_hint) =
1723            reduction_output_meta(self, &axes, "TracedTensor::reduce_sum_squares")?;
1724        apply_unary(
1725            StdTensorOp::ReduceSumSquares { axes },
1726            self,
1727            out_rank,
1728            out_shape_hint,
1729        )
1730    }
1731
1732    /// Reduce by taking the maximum along the given axes.
1733    ///
1734    /// Used by tropical (max-plus) compositions: a max-plus reduction over
1735    /// an axis is `ReduceMax` on that axis.
1736    ///
1737    /// # Examples
1738    ///
1739    /// ```rust
1740    /// # use tenferro_runtime::{TracedTensor};
1741    /// use tenferro_runtime::TraceContext;
1742    /// let trace = TraceContext::new();
1743    /// # let x = trace.from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
1744    /// let y = x.reduce_max(Some(&[0]))?;
1745    /// # Ok::<(), tenferro_runtime::Error>(())
1746    /// ```
1747    ///
1748    /// # Errors
1749    ///
1750    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when an axis is
1751    /// outside the input rank or `DuplicateAxis` when `axes` repeats an axis,
1752    /// [`Error::Unsupported`] when a non-empty maximum reduction receives a
1753    /// complex dtype, or [`Error::RuntimeStateSource`] when output metadata
1754    /// cannot be registered.
1755    pub fn reduce_max(&self, axes: Option<&[isize]>) -> Result<TracedTensor> {
1756        let axes = match axes {
1757            Some(axes) => crate::shape_packing::normalize_existing_axes(
1758                "TracedTensor::reduce_max",
1759                axes,
1760                self.rank,
1761            )?,
1762            None => (0..self.rank).collect(),
1763        };
1764        let (out_rank, out_shape_hint) =
1765            reduction_output_meta(self, &axes, "TracedTensor::reduce_max")?;
1766        try_apply_unary(
1767            StdTensorOp::ReduceMax { axes },
1768            self,
1769            out_rank,
1770            out_shape_hint,
1771            "TracedTensor::reduce_max",
1772        )
1773    }
1774
1775    /// Reduce by taking the minimum along the given axes.
1776    ///
1777    /// Used by tropical (min-plus) compositions: a min-plus reduction over
1778    /// an axis is `ReduceMin` on that axis.
1779    ///
1780    /// # Examples
1781    ///
1782    /// ```rust
1783    /// # use tenferro_runtime::{TracedTensor};
1784    /// use tenferro_runtime::TraceContext;
1785    /// let trace = TraceContext::new();
1786    /// # let x = trace.from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
1787    /// let y = x.reduce_min(Some(&[0]))?;
1788    /// # Ok::<(), tenferro_runtime::Error>(())
1789    /// ```
1790    ///
1791    /// # Errors
1792    ///
1793    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when an axis is
1794    /// outside the input rank or `DuplicateAxis` when `axes` repeats an axis,
1795    /// [`Error::Unsupported`] when a non-empty minimum reduction receives a
1796    /// complex dtype, or [`Error::RuntimeStateSource`] when output metadata
1797    /// cannot be registered.
1798    pub fn reduce_min(&self, axes: Option<&[isize]>) -> Result<TracedTensor> {
1799        let axes = match axes {
1800            Some(axes) => crate::shape_packing::normalize_existing_axes(
1801                "TracedTensor::reduce_min",
1802                axes,
1803                self.rank,
1804            )?,
1805            None => (0..self.rank).collect(),
1806        };
1807        let (out_rank, out_shape_hint) =
1808            reduction_output_meta(self, &axes, "TracedTensor::reduce_min")?;
1809        try_apply_unary(
1810            StdTensorOp::ReduceMin { axes },
1811            self,
1812            out_rank,
1813            out_shape_hint,
1814            "TracedTensor::reduce_min",
1815        )
1816    }
1817
1818    /// Reduce by taking the product along the given axes.
1819    ///
1820    /// # Examples
1821    ///
1822    /// ```rust
1823    /// # use tenferro_runtime::{TracedTensor};
1824    /// use tenferro_runtime::TraceContext;
1825    /// let trace = TraceContext::new();
1826    /// # let x = trace.from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
1827    /// let y = x.reduce_prod(Some(&[0]))?;
1828    /// # Ok::<(), tenferro_runtime::Error>(())
1829    /// ```
1830    ///
1831    /// # Errors
1832    ///
1833    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when an axis is
1834    /// outside the input rank or `DuplicateAxis` when `axes` repeats an axis,
1835    /// or [`Error::RuntimeStateSource`] when output metadata cannot be
1836    /// registered.
1837    pub fn reduce_prod(&self, axes: Option<&[isize]>) -> Result<TracedTensor> {
1838        let axes = match axes {
1839            Some(axes) => crate::shape_packing::normalize_existing_axes(
1840                "TracedTensor::reduce_prod",
1841                axes,
1842                self.rank,
1843            )?,
1844            None => (0..self.rank).collect(),
1845        };
1846        let (out_rank, out_shape_hint) =
1847            reduction_output_meta(self, &axes, "TracedTensor::reduce_prod")?;
1848        apply_unary(
1849            StdTensorOp::ReduceProd { axes },
1850            self,
1851            out_rank,
1852            out_shape_hint,
1853        )
1854    }
1855
1856    /// Reshape without changing element order.
1857    ///
1858    /// # Examples
1859    ///
1860    /// ```rust
1861    /// # use tenferro_runtime::{TracedTensor};
1862    /// use tenferro_runtime::TraceContext;
1863    /// let trace = TraceContext::new();
1864    /// # let x = trace.from_vec_col_major(vec![4], vec![1.0_f64; 4]).unwrap();
1865    /// for y in [x.reshape([2, 2])?, x.reshape(vec![2, 2])?, x.reshape(&[2, 2][..])?] {
1866    ///     assert_eq!(y.try_concrete_shape(), Some(vec![2, 2]));
1867    /// }
1868    /// assert!(x.reshape([3]).is_err());
1869    /// # Ok::<(), tenferro_runtime::Error>(())
1870    /// ```
1871    ///
1872    /// # Errors
1873    ///
1874    /// Returns [`Error::Validation`] with `ShapeMismatch::ReshapeElementCount`
1875    /// when a concrete input has a different element count, or
1876    /// `IntegerOverflow` when the target shape product overflows `usize`.
1877    pub fn reshape(&self, shape: impl IntoShapeVec) -> Result<TracedTensor> {
1878        let shape = shape.into_shape_vec();
1879        validate_concrete_reshape_shape(self, &shape)?;
1880        apply_unary_with_dtype(
1881            StdTensorOp::Reshape {
1882                to_shape: DimExpr::from_concrete(&shape),
1883            },
1884            self,
1885            shape.len(),
1886            Some(shape.iter().copied().map(SymDim::from).collect()),
1887            self.dtype,
1888        )
1889    }
1890
1891    /// Return a symbolic expression for the size of one axis, suitable as
1892    /// an `InputDim`-style reference when composing with
1893    /// [`TracedTensor::reshape_sym`].
1894    ///
1895    /// Semantics: if this tensor's `shape_hint` has a symbolic
1896    /// (non-constant) entry for `axis`, that entry is returned
1897    /// verbatim. Otherwise — including when `shape_hint[axis]` is a
1898    /// concrete `SymDim::Concrete(n)` — a
1899    /// `SymDim::tensor_axis(self.symbolic_id(), axis)` reference is returned so the
1900    /// resulting graph remains shape-polymorphic if the same graph is
1901    /// later evaluated against a differently-shaped binding.
1902    ///
1903    /// For a canonical "what is the size of this axis?" query that
1904    /// reports the concrete size when it is known, prefer
1905    /// [`Self::axis_sym_dim`].
1906    ///
1907    /// # Examples
1908    ///
1909    /// ```rust
1910    /// # use tenferro_runtime::{TracedTensor};
1911    /// use tenferro_runtime::TraceContext;
1912    /// let trace = TraceContext::new();
1913    /// # let x = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
1914    /// let rows = x.sym_size(0)?;
1915    /// let cols = x.sym_size(1)?;
1916    /// let y = x.reshape_sym(&[rows * cols]).unwrap();
1917    /// # Ok::<(), tenferro_runtime::Error>(())
1918    /// ```
1919    ///
1920    /// # Errors
1921    ///
1922    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when `axis` is
1923    /// outside this tensor's rank.
1924    pub fn sym_size(&self, axis: isize) -> Result<SymDim> {
1925        let axis = crate::shape_packing::normalize_existing_axis(
1926            "TracedTensor::sym_size",
1927            axis,
1928            self.rank,
1929        )?;
1930        validate_traced_axis(self, axis, "TracedTensor::sym_size")?;
1931        Ok(self
1932            .shape_hint
1933            .as_ref()
1934            .and_then(|shape| shape.get(axis))
1935            .filter(|dim| dim.constant_value().is_none())
1936            .cloned()
1937            .unwrap_or_else(|| SymDim::tensor_axis(self.symbolic_id(), axis)))
1938    }
1939
1940    /// Return the canonical `SymDim` for `axis` — the concrete
1941    /// `SymDim::Concrete(n)` when the size is known, otherwise a symbolic
1942    /// expression identifying this tensor's axis.
1943    ///
1944    /// Unlike [`Self::sym_size`], this method does **not** rewrite
1945    /// concrete axes into `TensorAxis` references. It is the accessor
1946    /// external composition wrappers should use when building mixed
1947    /// concrete/symbolic target shapes for operations like
1948    /// [`Self::broadcast_in_dim_sym`].
1949    ///
1950    /// # Examples
1951    ///
1952    /// ```
1953    /// use tenferro_tensor::DType;
1954    /// use tenferro_runtime::{TracedTensor};
1955    ///
1956    /// use tenferro_runtime::TraceContext;
1957    /// let trace = TraceContext::new();
1958    /// let a = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
1959    /// // Concrete axis: reports the constant size.
1960    /// assert_eq!(a.axis_sym_dim(0).unwrap().constant_value(), Some(2));
1961    ///
1962    /// let b = trace.input_symbolic_shape(DType::F64, 2).unwrap();
1963    /// // Fully symbolic leaf: reports a TensorAxis reference.
1964    /// assert!(b.axis_sym_dim(0).unwrap().constant_value().is_none());
1965    /// ```
1966    ///
1967    /// # Errors
1968    ///
1969    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when `axis` is
1970    /// outside this tensor's rank.
1971    pub fn axis_sym_dim(&self, axis: isize) -> Result<SymDim> {
1972        let axis = crate::shape_packing::normalize_existing_axis(
1973            "TracedTensor::axis_sym_dim",
1974            axis,
1975            self.rank,
1976        )?;
1977        validate_traced_axis(self, axis, "TracedTensor::axis_sym_dim")?;
1978        match self.shape_hint.as_ref().and_then(|shape| shape.get(axis)) {
1979            Some(dim) => Ok(dim.clone()),
1980            None => Ok(SymDim::tensor_axis(self.symbolic_id(), axis)),
1981        }
1982    }
1983
1984    /// Return the full symbolic shape of this tensor when it is known.
1985    ///
1986    /// Every traced value carries its symbolic extents: a constant axis reports
1987    /// its constant size, and every other axis reports a [`SymDim::tensor_axis`]
1988    /// naming this handle's own axis, whatever the builder inferred, so a shape
1989    /// built from several handles can be converted without confusing them. `None`
1990    /// only appears for a value whose extents the builder left unknown; build
1991    /// those axis-by-axis via [`Self::axis_sym_dim`].
1992    ///
1993    /// # Examples
1994    ///
1995    /// ```
1996    /// use tenferro_tensor::DType;
1997    /// use tenferro_runtime::TraceContext;
1998    ///
1999    /// let trace = TraceContext::new();
2000    /// let a = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
2001    /// assert!(a.sym_shape().is_some());
2002    /// assert_eq!(a.sym_shape().unwrap().len(), 2);
2003    ///
2004    /// // A symbolic placeholder reports its symbolic extents, not `None`.
2005    /// let b = trace.input_symbolic_shape(DType::F64, 2).unwrap();
2006    /// assert_eq!(b.sym_shape().map(<[_]>::len), Some(2));
2007    /// assert!(b.sym_shape().unwrap().iter().all(|dim| dim.constant_value().is_none()));
2008    /// ```
2009    pub fn sym_shape(&self) -> Option<&[SymDim]> {
2010        self.shape_hint.as_deref()
2011    }
2012
2013    /// Reshape using symbolic dimensions derived from traced tensor axes.
2014    ///
2015    /// # Examples
2016    ///
2017    /// ```rust
2018    /// # use tenferro_runtime::{TracedTensor};
2019    /// use tenferro_runtime::TraceContext;
2020    /// let trace = TraceContext::new();
2021    /// # let x = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
2022    /// let rows = x.sym_size(0)?;
2023    /// let cols = x.sym_size(1)?;
2024    /// let y = x.reshape_sym(&[rows * cols]).unwrap();
2025    /// # Ok::<(), tenferro_runtime::Error>(())
2026    /// ```
2027    ///
2028    /// # Errors
2029    ///
2030    /// Returns [`Error::SymbolicShapeConversion`] when a supplied symbolic
2031    /// dimension cannot be mapped to this graph, or [`Error::RuntimeStateSource`]
2032    /// when result metadata cannot be registered.
2033    ///
2034    /// # Deferred errors
2035    ///
2036    /// Element-count compatibility for symbolic dimensions is checked when
2037    /// concrete inputs reach compilation or execution. A mismatch is returned
2038    /// as [`Error::TensorRuntime`] with a typed `ShapeMismatch` source.
2039    pub fn reshape_sym(&self, shape: &[SymDim]) -> Result<TracedTensor> {
2040        let tensor_map = [(self.symbolic_id(), 0usize)];
2041        let to_shape = shape
2042            .iter()
2043            .map(|dim| {
2044                dim.to_dim_expr(&tensor_map)
2045                    .map_err(|source| Error::SymbolicShapeConversion {
2046                        op: "TracedTensor::reshape_sym",
2047                        phase: ErrorPhase::GraphBuild,
2048                        source,
2049                    })
2050            })
2051            .collect::<Result<Vec<_>>>()?;
2052        let out_shape_hint = Some(shape.to_vec());
2053        apply_unary(
2054            StdTensorOp::Reshape { to_shape },
2055            self,
2056            shape.len(),
2057            out_shape_hint,
2058        )
2059    }
2060
2061    /// Broadcast into a larger shape with explicit dimension placement.
2062    ///
2063    /// # Examples
2064    ///
2065    /// ```rust
2066    /// # use tenferro_runtime::{TracedTensor};
2067    /// use tenferro_runtime::TraceContext;
2068    /// let trace = TraceContext::new();
2069    /// # let x = trace.from_vec_col_major(vec![3], vec![1.0_f64; 3]).unwrap();
2070    /// let y = x.broadcast_in_dim(&[2, 3], &[1])?;
2071    /// # Ok::<(), tenferro_runtime::Error>(())
2072    /// ```
2073    ///
2074    /// # Errors
2075    ///
2076    /// Returns [`Error::Validation`] with `RankMismatch` when `dims` does not
2077    /// have one entry per input axis, `AxisOutOfBounds` or `DuplicateAxis` for
2078    /// an invalid output mapping, or `InvalidArgument` when known dimensions
2079    /// cannot broadcast. [`Error::RuntimeStateSource`] reports failure to
2080    /// register the result metadata.
2081    pub fn broadcast_in_dim(&self, shape: &[usize], dims: &[usize]) -> Result<TracedTensor> {
2082        let out_shape_hint: Vec<SymDim> = shape.iter().copied().map(SymDim::from).collect();
2083        validate_broadcast_in_dim_args(
2084            self,
2085            &out_shape_hint,
2086            dims,
2087            "TracedTensor::broadcast_in_dim",
2088        )?;
2089        apply_unary(
2090            StdTensorOp::BroadcastInDim {
2091                shape: DimExpr::from_concrete(shape),
2092                dims: dims.to_vec(),
2093            },
2094            self,
2095            shape.len(),
2096            Some(out_shape_hint),
2097        )
2098    }
2099
2100    /// Broadcast into a symbolic target shape with explicit dimension
2101    /// placement.
2102    ///
2103    /// Unlike [`Self::broadcast_in_dim`], each axis of `shape` is a
2104    /// [`SymDim`], so the target shape can mix concrete sizes (via
2105    /// `SymDim::from(n)`) with symbolic references to this tensor's axes
2106    /// (via [`Self::axis_sym_dim`]) or to axes of other traced tensors.
2107    ///
2108    /// When `shape` contains a `SymDim` that references a traced tensor
2109    /// other than `self`, the referenced tensor(s) must be supplied in
2110    /// `shape_refs`. They are wired into the built op as auxiliary
2111    /// shape-reference inputs — the op does not read their data, only
2112    /// their runtime shape. `shape_refs` must be listed in the same order
2113    /// in which their tensor IDs first appear when walking `shape` after
2114    /// any references to `self`. Usually the simplest correct thing is to
2115    /// pass each unique non-self reference tensor once.
2116    ///
2117    /// # Examples
2118    ///
2119    /// ```
2120    /// use tenferro_runtime::{TracedTensor};
2121    ///
2122    /// use tenferro_runtime::TraceContext;
2123    /// let trace = TraceContext::new();
2124    /// let a = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
2125    /// let b = trace.from_vec_col_major(vec![3, 4], vec![1.0_f64; 12]).unwrap();
2126    /// let m = a.axis_sym_dim(0)?;
2127    /// let k = a.axis_sym_dim(1)?;
2128    /// let n = b.axis_sym_dim(1)?;
2129    /// // Broadcast `a[m, k]` to `[m, k, n]`, placing `a`'s axes at 0, 1
2130    /// // and taking `n` from `b` as an auxiliary shape reference.
2131    /// let a_b = a.broadcast_in_dim_sym(&[m, k, n], &[0, 1], &[&b])?;
2132    /// assert_eq!(a_b.rank(), 3);
2133    /// # Ok::<(), tenferro_runtime::Error>(())
2134    /// ```
2135    ///
2136    /// # Errors
2137    ///
2138    /// Returns [`Error::Validation`] with `RankMismatch`, `AxisOutOfBounds`,
2139    /// `DuplicateAxis`, or `InvalidArgument` when the output mapping or shape
2140    /// references are invalid, [`Error::SymbolicShapeConversion`] for an
2141    /// unmappable symbolic dimension, or [`Error::RuntimeStateSource`] when
2142    /// metadata cannot be registered.
2143    ///
2144    /// # Deferred errors
2145    ///
2146    /// If a symbolic output dimension is smaller than a non-unit input axis,
2147    /// the concrete broadcast check is deferred to compilation or execution
2148    /// and is returned as [`Error::TensorRuntime`] with a typed validation
2149    /// source.
2150    pub fn broadcast_in_dim_sym(
2151        &self,
2152        shape: &[SymDim],
2153        dims: &[usize],
2154        shape_refs: &[&TracedTensor],
2155    ) -> Result<TracedTensor> {
2156        validate_broadcast_in_dim_args(self, shape, dims, "TracedTensor::broadcast_in_dim_sym")?;
2157
2158        // Build a dedup'd list of shape-reference tensors (first occurrence
2159        // wins) and index them starting at 1 — the primary input `self`
2160        // is at 0.
2161        let mut dedup_refs: Vec<&TracedTensor> = Vec::with_capacity(shape_refs.len());
2162        let mut tensor_map: Vec<(u64, usize)> = vec![(self.symbolic_id(), 0)];
2163        for &t in shape_refs {
2164            if !tensor_map.iter().any(|(id, _)| *id == t.symbolic_id()) {
2165                let idx = tensor_map.len();
2166                tensor_map.push((t.symbolic_id(), idx));
2167                dedup_refs.push(t);
2168            }
2169        }
2170
2171        let to_shape: Vec<DimExpr> = shape
2172            .iter()
2173            .map(|dim| {
2174                dim.to_dim_expr(&tensor_map)
2175                    .map_err(|source| Error::SymbolicShapeConversion {
2176                        op: "broadcast_in_dim_sym",
2177                        phase: ErrorPhase::GraphBuild,
2178                        source,
2179                    })
2180            })
2181            .collect::<Result<Vec<_>>>()?;
2182
2183        // Trim auxiliary shape-reference inputs down to those actually
2184        // used by the generated `DimExpr`s. If the target shape resolved
2185        // to all constants (the concrete-shape case) the op is a plain
2186        // unary broadcast with no extra parents. Otherwise the op needs
2187        // a contiguous prefix of shape-ref inputs covering every
2188        // referenced `input_idx`.
2189        let max_used_idx = DimExpr::max_input_idx_all(&to_shape).unwrap_or(0);
2190        let used_refs: Vec<&TracedTensor> = dedup_refs.into_iter().take(max_used_idx).collect();
2191
2192        let out_shape_hint = Some(shape.to_vec());
2193        apply_unary_with_shape_refs(
2194            StdTensorOp::BroadcastInDim {
2195                shape: to_shape,
2196                dims: dims.to_vec(),
2197            },
2198            self,
2199            &used_refs,
2200            shape.len(),
2201            out_shape_hint,
2202        )
2203    }
2204
2205    /// Slice with explicit start, limit, and stride per axis.
2206    ///
2207    /// # Errors
2208    ///
2209    /// Returns [`Error::Validation`] with `RankMismatch` when the start/limit/
2210    /// stride vectors do not match the input rank, `InvalidSliceStep` when a
2211    /// stride is zero, `InvalidSliceBounds` when a limit precedes its start or
2212    /// exceeds a concrete input extent, or [`Error::RuntimeStateSource`] when
2213    /// output metadata cannot be registered.
2214    pub fn slice(&self, config: SliceConfig) -> Result<TracedTensor> {
2215        let op = StdTensorOp::Slice(config);
2216        let (out_rank, out_shape_hint) =
2217            infer_traced_single_output_shape("TracedTensor::slice", &op, &[self])?;
2218        apply_unary(op, self, out_rank, out_shape_hint)
2219    }
2220
2221    /// Pad with zeros using StableHLO-style edge and interior padding.
2222    ///
2223    /// # Errors
2224    ///
2225    /// Returns [`Error::Validation`] with `RankMismatch` when padding vectors
2226    /// do not match the input rank, `InvalidArgument` for negative interior
2227    /// padding, or `IntegerOverflow` when the padded extent exceeds `usize`.
2228    /// [`Error::RuntimeStateSource`] is returned when output metadata cannot be
2229    /// registered.
2230    pub fn pad(&self, config: PadConfig) -> Result<TracedTensor> {
2231        let op = StdTensorOp::Pad(config);
2232        let (out_rank, out_shape_hint) =
2233            infer_traced_single_output_shape("TracedTensor::pad", &op, &[self])?;
2234        apply_unary(op, self, out_rank, out_shape_hint)
2235    }
2236
2237    /// Reverse the order of elements along the requested axes.
2238    ///
2239    /// # Examples
2240    ///
2241    /// ```
2242    /// use tenferro_cpu::CpuEngine;
2243    /// use tenferro_runtime::{ExecutionEngine, GraphCompiler, Runtime, TraceContext};
2244    ///
2245    /// let trace = TraceContext::new();
2246    /// let x = trace.from_vec_col_major(vec![3], vec![1.0_f64, 2.0, 3.0]).unwrap();
2247    /// let y = x.reverse(&[-1])?;
2248    /// let mut compiler = GraphCompiler::new();
2249    /// let program = compiler.compile(&y).unwrap();
2250    /// let mut engine = CpuEngine::serial();
2251    /// let mut builder = Runtime::builder();
2252    /// builder
2253    ///     .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
2254    ///     .unwrap();
2255    /// let runtime = builder.build().unwrap();
2256    /// let prepared = runtime
2257    ///     .prepare(&program, &[], &[engine.target()])
2258    ///     .unwrap();
2259    /// let mut outputs = runtime
2260    ///     .run(&mut [&mut engine], &prepared, &[])
2261    ///     .unwrap();
2262    /// let out = outputs.remove(0).into_tensor(&mut engine).unwrap();
2263    /// assert_eq!(out.as_slice::<f64>().unwrap(), &[3.0, 2.0, 1.0]);
2264    /// # Ok::<(), tenferro_runtime::Error>(())
2265    /// ```
2266    ///
2267    /// # Errors
2268    ///
2269    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when an axis is
2270    /// outside the input rank or `DuplicateAxis` when `axes` repeats one, or
2271    /// [`Error::RuntimeStateSource`] when result metadata cannot be
2272    /// registered.
2273    pub fn reverse(&self, axes: &[isize]) -> Result<TracedTensor> {
2274        let axes = &crate::shape_packing::normalize_existing_axes(
2275            "TracedTensor::reverse",
2276            axes,
2277            self.rank,
2278        )?[..];
2279        validate_traced_axes(self.rank, axes, "TracedTensor::reverse")?;
2280        apply_unary(
2281            StdTensorOp::Reverse {
2282                axes: axes.to_vec(),
2283            },
2284            self,
2285            self.rank,
2286            self.shape_hint.clone(),
2287        )
2288    }
2289
2290    /// Gather slices from `self` using integer start indices.
2291    ///
2292    /// # Errors
2293    ///
2294    /// Returns [`Error::Validation`] with `RankMismatch`, `AxisOutOfBounds`,
2295    /// `DuplicateAxis`, or `ShapeMismatch` when indices or the gather
2296    /// configuration is incompatible with the input, and
2297    /// [`Error::RuntimeStateSource`] when output metadata cannot be
2298    /// registered.
2299    ///
2300    /// # Clamping
2301    ///
2302    /// Index values are clamped with StableHLO gather clamp semantics: an
2303    /// out-of-range or negative index is clamped into `[0, dim - window]` rather than rejected.
2304    /// Only a `slice_sizes` window that exceeds its operand dimension is rejected,
2305    /// which is a graph-build failure.
2306    pub fn gather(&self, indices: &TracedTensor, config: GatherConfig) -> Result<TracedTensor> {
2307        let op = StdTensorOp::Gather(config);
2308        let (out_rank, out_shape_hint) =
2309            infer_traced_single_output_shape("TracedTensor::gather", &op, &[self, indices])?;
2310        apply_binary_preserve_input_dtypes(op, self, indices, out_rank, out_shape_hint, self.dtype)
2311    }
2312
2313    /// Scatter updates into `self` using StableHLO scatter semantics.
2314    ///
2315    /// # Errors
2316    ///
2317    /// Returns [`Error::Validation`] with `RankMismatch`, `AxisOutOfBounds`,
2318    /// `DuplicateAxis`, or `ShapeMismatch` when indices, updates, or the
2319    /// scatter configuration is incompatible, [`Error::TensorRuntime`] with
2320    /// `UnsupportedDTypeConversion` when dtype promotion cannot be
2321    /// represented, or [`Error::RuntimeStateSource`] when output metadata
2322    /// cannot be registered.
2323    ///
2324    /// # Clamping
2325    ///
2326    /// Index *values* clamp with StableHLO scatter semantics: an out-of-range or
2327    /// negative index is clamped rather than rejected, into the operand's extent.
2328    ///
2329    /// # Deferred errors
2330    ///
2331    /// The index and update *shapes* and the scatter configuration are checked
2332    /// after binding: an incompatible one is returned as [`Error::TensorRuntime`]
2333    /// with its typed validation source and [`ErrorPhase::Execution`]. An update
2334    /// window that exceeds the operand is the one exception: the CPU backend
2335    /// rejects it, while the CUDA kernel drops the update, so it is not part of
2336    /// this contract.
2337    pub fn scatter(
2338        &self,
2339        indices: &TracedTensor,
2340        updates: &TracedTensor,
2341        config: ScatterConfig,
2342    ) -> Result<TracedTensor> {
2343        let op = StdTensorOp::Scatter(config);
2344        let (out_rank, out_shape_hint) = infer_traced_single_output_shape(
2345            "TracedTensor::scatter",
2346            &op,
2347            &[self, indices, updates],
2348        )?;
2349        let out_dtype = crate::shape_infer::promote_dtype(self.dtype, updates.dtype);
2350        let operand = if self.dtype != out_dtype {
2351            self.cast(out_dtype)?
2352        } else {
2353            self.clone()
2354        };
2355        let updates = if updates.dtype != out_dtype {
2356            updates.cast(out_dtype)?
2357        } else {
2358            updates.clone()
2359        };
2360        apply_ternary_with_output_dtype(
2361            op,
2362            &operand,
2363            indices,
2364            &updates,
2365            out_rank,
2366            out_shape_hint,
2367            out_dtype,
2368        )
2369    }
2370
2371    /// Slice using runtime start indices.
2372    ///
2373    /// # Errors
2374    ///
2375    /// Returns [`Error::Validation`] with `RankMismatch` when `sizes` has a rank
2376    /// other than the operand's, with `ShapeMismatch` when a `sizes` window
2377    /// exceeds a concrete operand dimension, and with `InvalidArgument` when
2378    /// `starts` is not a rank-1 vector holding one entry per operand axis. These
2379    /// are graph-build checks (`ErrorPhase::GraphBuild`, #2160) mirroring the
2380    /// `gather` sibling. The eager surface reaches the same conditions at
2381    /// execution, where the backends name the oversized window `InvalidArgument`
2382    /// (`"configuration"` on CPU, `"slice_sizes"` on CUDA) rather than
2383    /// `ShapeMismatch`. Also returns [`Error::RuntimeStateSource`] when output
2384    /// metadata cannot be registered.
2385    ///
2386    /// # Clamping
2387    ///
2388    /// Start *values* clamp with StableHLO `DynamicSlice` semantics: an
2389    /// out-of-range or negative start is clamped rather than rejected, into
2390    /// `[0, dim - window]`. Only the `slice_sizes` window itself is rejected, and
2391    /// it is rejected when the graph is built. An operand extent or a `starts`
2392    /// length that is still symbolic at that point defers its check to the phase
2393    /// that supplies the extent, and the reported [`ErrorPhase`] says which.
2394    pub fn dynamic_slice(&self, starts: &TracedTensor, sizes: &[usize]) -> Result<TracedTensor> {
2395        let op = StdTensorOp::DynamicSlice {
2396            slice_sizes: sizes.to_vec(),
2397        };
2398        let (out_rank, out_shape_hint) =
2399            infer_traced_single_output_shape("TracedTensor::dynamic_slice", &op, &[self, starts])?;
2400        apply_binary_preserve_input_dtypes(op, self, starts, out_rank, out_shape_hint, self.dtype)
2401    }
2402
2403    /// Keep the lower triangle and zero the rest.
2404    ///
2405    /// # Examples
2406    ///
2407    /// ```rust
2408    /// # use tenferro_runtime::{TracedTensor};
2409    /// use tenferro_runtime::TraceContext;
2410    /// let trace = TraceContext::new();
2411    /// let matrix = trace.from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
2412    /// let lower = matrix.tril(0)?;
2413    /// assert_eq!(lower.rank(), 2);
2414    /// # Ok::<(), tenferro_runtime::Error>(())
2415    /// ```
2416    ///
2417    /// # Errors
2418    ///
2419    /// Returns [`Error::RuntimeStateSource`] when traced output metadata
2420    /// registration is unavailable or inconsistent with the graph.
2421    pub fn tril(&self, k: i64) -> Result<TracedTensor> {
2422        apply_unary(
2423            StdTensorOp::Tril { k },
2424            self,
2425            self.rank,
2426            self.shape_hint.clone(),
2427        )
2428    }
2429
2430    /// Keep the upper triangle and zero the rest.
2431    ///
2432    /// # Examples
2433    ///
2434    /// ```rust
2435    /// # use tenferro_runtime::{TracedTensor};
2436    /// use tenferro_runtime::TraceContext;
2437    /// let trace = TraceContext::new();
2438    /// let matrix = trace.from_vec_col_major(vec![2, 2], vec![1.0_f64; 4])?;
2439    /// let upper = matrix.triu(0)?;
2440    /// assert_eq!(upper.rank(), 2);
2441    /// # Ok::<(), tenferro_runtime::Error>(())
2442    /// ```
2443    ///
2444    /// # Errors
2445    ///
2446    /// Returns [`Error::RuntimeStateSource`] when traced output metadata
2447    /// registration is unavailable or inconsistent with the graph.
2448    pub fn triu(&self, k: i64) -> Result<TracedTensor> {
2449        apply_unary(
2450            StdTensorOp::Triu { k },
2451            self,
2452            self.rank,
2453            self.shape_hint.clone(),
2454        )
2455    }
2456
2457    /// Permute tensor axes.
2458    ///
2459    /// # Examples
2460    ///
2461    /// ```rust
2462    /// # use tenferro_runtime::{TracedTensor};
2463    /// use tenferro_runtime::TraceContext;
2464    /// let trace = TraceContext::new();
2465    /// # let x = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64; 6]).unwrap();
2466    /// let y = x.transpose(&[1, 0])?;
2467    /// # Ok::<(), tenferro_runtime::Error>(())
2468    /// ```
2469    ///
2470    /// # Errors
2471    ///
2472    /// Returns [`Error::Validation`] with `InvalidPermutationLength`,
2473    /// `AxisOutOfBounds`, or `DuplicateAxis` when `perm` is not a valid
2474    /// permutation of the tensor axes, or [`Error::RuntimeStateSource`] when
2475    /// output metadata registration fails.
2476    pub fn transpose(&self, perm: &[isize]) -> Result<TracedTensor> {
2477        let perm = &crate::shape_packing::normalize_existing_axes(
2478            "TracedTensor::transpose",
2479            perm,
2480            self.rank,
2481        )?[..];
2482        validate_traced_perm(self.rank, perm, "TracedTensor::transpose")?;
2483        let out_shape_hint = self
2484            .shape_hint
2485            .as_ref()
2486            .map(|shape| perm.iter().map(|&p| shape[p].clone()).collect());
2487        apply_unary(
2488            StdTensorOp::Transpose {
2489                perm: perm.to_vec(),
2490            },
2491            self,
2492            self.rank,
2493            out_shape_hint,
2494        )
2495    }
2496
2497    /// Extract the diagonal along two axes.
2498    ///
2499    /// # Examples
2500    ///
2501    /// ```rust
2502    /// # use tenferro_runtime::{TracedTensor};
2503    /// use tenferro_runtime::TraceContext;
2504    /// let trace = TraceContext::new();
2505    /// # let x = trace.from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
2506    /// let y = x.extract_diag(0, 1)?;
2507    /// # Ok::<(), tenferro_runtime::Error>(())
2508    /// ```
2509    ///
2510    /// # Errors
2511    ///
2512    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when either axis
2513    /// is outside the input rank or `InvalidArgument` when `axis_a == axis_b`.
2514    pub fn extract_diag(&self, axis_a: isize, axis_b: isize) -> Result<TracedTensor> {
2515        let axis_a = crate::shape_packing::normalize_existing_axis(
2516            "TracedTensor::extract_diag",
2517            axis_a,
2518            self.rank,
2519        )?;
2520        let axis_b = crate::shape_packing::normalize_existing_axis(
2521            "TracedTensor::extract_diag",
2522            axis_b,
2523            self.rank,
2524        )?;
2525        validate_traced_axis(self, axis_a, "TracedTensor::extract_diag")?;
2526        validate_traced_axis(self, axis_b, "TracedTensor::extract_diag")?;
2527        if axis_a == axis_b {
2528            return Err(graph_invalid_argument(
2529                "TracedTensor::extract_diag",
2530                "axes",
2531                "diagonal axes must be distinct",
2532            ));
2533        }
2534        let op = StdTensorOp::ExtractDiag { axis_a, axis_b };
2535        let (out_rank, out_shape_hint) =
2536            infer_traced_single_output_shape("TracedTensor::extract_diag", &op, &[self])?;
2537        apply_unary(op, self, out_rank, out_shape_hint)
2538    }
2539
2540    /// Embed a vector or lower-rank tensor along a diagonal.
2541    ///
2542    /// # Examples
2543    ///
2544    /// ```rust
2545    /// # use tenferro_runtime::{TracedTensor};
2546    /// use tenferro_runtime::TraceContext;
2547    /// let trace = TraceContext::new();
2548    /// # let x = trace.from_vec_col_major(vec![2], vec![1.0_f64; 2]).unwrap();
2549    /// let y = x.embed_diag(0, 1)?;
2550    /// # Ok::<(), tenferro_runtime::Error>(())
2551    /// ```
2552    ///
2553    /// # Errors
2554    ///
2555    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when `axis_a` is
2556    /// outside the input rank or `InvalidArgument` when `axis_b` is not a
2557    /// valid insertion axis.
2558    pub fn embed_diag(&self, axis_a: isize, axis_b: isize) -> Result<TracedTensor> {
2559        let axis_a = crate::shape_packing::normalize_existing_axis(
2560            "TracedTensor::embed_diag",
2561            axis_a,
2562            self.rank,
2563        )?;
2564        let axis_b = crate::shape_packing::normalize_insert_axis(
2565            "TracedTensor::embed_diag",
2566            axis_b,
2567            self.rank,
2568        )?;
2569        validate_traced_axis(self, axis_a, "TracedTensor::embed_diag")?;
2570        validate_traced_insert_axis(self.rank, axis_b, "TracedTensor::embed_diag")?;
2571        let out_shape_hint = self.shape_hint.as_ref().map(|shape| {
2572            let mut out_shape = shape.clone();
2573            out_shape.insert(axis_b, shape[axis_a].clone());
2574            out_shape
2575        });
2576        apply_unary(
2577            StdTensorOp::EmbedDiag { axis_a, axis_b },
2578            self,
2579            self.rank + 1,
2580            out_shape_hint,
2581        )
2582    }
2583
2584    /// Return the runtime size of one axis as a scalar `f64` tensor.
2585    ///
2586    /// The result is metadata-derived and therefore has no gradient.
2587    ///
2588    /// # Examples
2589    ///
2590    /// ```
2591    /// use tenferro_cpu::CpuEngine;
2592    /// use tenferro_runtime::{ExecutionEngine, GraphCompiler, Runtime, TracedTensor};
2593    ///
2594    /// use tenferro_runtime::TraceContext;
2595    /// let trace = TraceContext::new();
2596    /// let x = trace.from_vec_col_major(vec![2, 3], vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0]).unwrap();
2597    /// let cols = x.shape_of(1)?;
2598    /// let mut compiler = GraphCompiler::new();
2599    /// let program = compiler.compile(&cols).unwrap();
2600    /// let mut engine = CpuEngine::serial();
2601    /// let mut builder = Runtime::builder();
2602    /// builder
2603    ///     .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
2604    ///     .unwrap();
2605    /// let runtime = builder.build().unwrap();
2606    /// let prepared = runtime
2607    ///     .prepare(&program, &[], &[engine.target()])
2608    ///     .unwrap();
2609    /// let mut outputs = runtime
2610    ///     .run(&mut [&mut engine], &prepared, &[])
2611    ///     .unwrap();
2612    /// let out = outputs.remove(0).into_tensor(&mut engine).unwrap();
2613    /// assert_eq!(out.shape(), &[] as &[usize]);
2614    /// # Ok::<(), tenferro_runtime::Error>(())
2615    /// ```
2616    ///
2617    /// # Errors
2618    ///
2619    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when `axis` is
2620    /// outside the input rank, or [`Error::RuntimeStateSource`] when scalar
2621    /// output metadata cannot be registered.
2622    pub fn shape_of(&self, axis: isize) -> Result<TracedTensor> {
2623        let axis = crate::shape_packing::normalize_existing_axis(
2624            "TracedTensor::shape_of",
2625            axis,
2626            self.rank,
2627        )?;
2628        validate_traced_axis(self, axis, "TracedTensor::shape_of")?;
2629        apply_unary_with_dtype(
2630            StdTensorOp::ShapeOf { axis },
2631            self,
2632            0,
2633            Some(vec![]),
2634            DType::F64,
2635        )
2636    }
2637
2638    /// Truncate this tensor along `axis` to the first `size` elements.
2639    ///
2640    /// `size` is read at runtime from a scalar traced tensor. Values are
2641    /// rounded to the nearest integer, clamped to `[0, self.shape[axis]]`,
2642    /// and the output keeps the same element dtype as the input.
2643    ///
2644    /// # Examples
2645    ///
2646    /// ```
2647    /// use tenferro_cpu::CpuEngine;
2648    /// use tenferro_runtime::{ExecutionEngine, GraphCompiler, Runtime, TracedTensor};
2649    ///
2650    /// use tenferro_runtime::TraceContext;
2651    /// let trace = TraceContext::new();
2652    /// let x = trace.from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0]).unwrap();
2653    /// let size = trace.from_vec_col_major(vec![], vec![2.0_f64]).unwrap();
2654    /// let y = x.dynamic_truncate(&size, 0)?;
2655    /// let mut compiler = GraphCompiler::new();
2656    /// let program = compiler.compile(&y).unwrap();
2657    /// let mut engine = CpuEngine::serial();
2658    /// let mut builder = Runtime::builder();
2659    /// builder
2660    ///     .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
2661    ///     .unwrap();
2662    /// let runtime = builder.build().unwrap();
2663    /// let prepared = runtime
2664    ///     .prepare(&program, &[], &[engine.target()])
2665    ///     .unwrap();
2666    /// let mut outputs = runtime
2667    ///     .run(&mut [&mut engine], &prepared, &[])
2668    ///     .unwrap();
2669    /// let out = outputs.remove(0).into_tensor(&mut engine).unwrap();
2670    /// assert_eq!(out.shape(), &[2]);
2671    /// # Ok::<(), tenferro_runtime::Error>(())
2672    /// ```
2673    ///
2674    /// # Errors
2675    ///
2676    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when `axis` is
2677    /// outside the input rank or `RankMismatch` when `size` is not scalar.
2678    ///
2679    /// # Deferred errors
2680    ///
2681    /// At execution, non-`f32`/`f64`/`i64` size dtypes return
2682    /// [`Error::TensorRuntime`] with `Unsupported`, non-finite size values
2683    /// return a typed `InvalidArgument`, and an empty scalar buffer returns a
2684    /// typed runtime-state source.
2685    pub fn dynamic_truncate(&self, size: &TracedTensor, axis: isize) -> Result<TracedTensor> {
2686        let axis = crate::shape_packing::normalize_existing_axis(
2687            "TracedTensor::dynamic_truncate",
2688            axis,
2689            self.rank,
2690        )?;
2691        validate_traced_axis(self, axis, "TracedTensor::dynamic_truncate")?;
2692        if size.rank != 0 {
2693            return Err(graph_validation(
2694                "TracedTensor::dynamic_truncate",
2695                ValidationError::RankMismatch {
2696                    expected: 0,
2697                    actual: size.rank,
2698                },
2699            ));
2700        }
2701        apply_binary_preserve_input_dtypes(
2702            StdTensorOp::DynamicTruncate { axis },
2703            self,
2704            size,
2705            self.rank,
2706            None,
2707            self.dtype,
2708        )
2709    }
2710
2711    /// Pad this tensor with zeros along `axis` to match `reference.shape[axis]`.
2712    ///
2713    /// If `reference` is smaller along that axis, this is a no-op.
2714    ///
2715    /// # Examples
2716    ///
2717    /// ```
2718    /// use tenferro_cpu::CpuEngine;
2719    /// use tenferro_runtime::{ExecutionEngine, GraphCompiler, Runtime, TracedTensor};
2720    ///
2721    /// use tenferro_runtime::TraceContext;
2722    /// let trace = TraceContext::new();
2723    /// let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
2724    /// let reference = trace.from_vec_col_major(vec![4], vec![0.0_f64, 0.0, 0.0, 0.0]).unwrap();
2725    /// let y = x.pad_to_match(&reference, 0)?;
2726    /// let mut compiler = GraphCompiler::new();
2727    /// let program = compiler.compile(&y).unwrap();
2728    /// let mut engine = CpuEngine::serial();
2729    /// let mut builder = Runtime::builder();
2730    /// builder
2731    ///     .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
2732    ///     .unwrap();
2733    /// let runtime = builder.build().unwrap();
2734    /// let prepared = runtime
2735    ///     .prepare(&program, &[], &[engine.target()])
2736    ///     .unwrap();
2737    /// let mut outputs = runtime
2738    ///     .run(&mut [&mut engine], &prepared, &[])
2739    ///     .unwrap();
2740    /// let out = outputs.remove(0).into_tensor(&mut engine).unwrap();
2741    /// assert_eq!(out.shape(), &[4]);
2742    /// # Ok::<(), tenferro_runtime::Error>(())
2743    /// ```
2744    ///
2745    /// # Errors
2746    ///
2747    /// Returns [`Error::Validation`] with `AxisOutOfBounds` when `axis` is
2748    /// outside either tensor's rank, or [`Error::RuntimeStateSource`] when
2749    /// output metadata cannot be registered.
2750    pub fn pad_to_match(&self, reference: &TracedTensor, axis: isize) -> Result<TracedTensor> {
2751        let axis = crate::shape_packing::normalize_existing_axis(
2752            "TracedTensor::pad_to_match",
2753            axis,
2754            self.rank,
2755        )?;
2756        validate_traced_axis(self, axis, "TracedTensor::pad_to_match")?;
2757        validate_traced_axis(reference, axis, "TracedTensor::pad_to_match")?;
2758        let op = StdTensorOp::PadToMatch { axis };
2759        let (out_rank, out_shape_hint) = infer_traced_single_output_shape(
2760            "TracedTensor::pad_to_match",
2761            &op,
2762            &[self, reference],
2763        )?;
2764        apply_binary_preserve_input_dtypes(
2765            op,
2766            self,
2767            reference,
2768            out_rank,
2769            out_shape_hint,
2770            self.dtype,
2771        )
2772    }
2773}
2774
2775pub(crate) fn apply_unary(
2776    op: StdTensorOp,
2777    input: &TracedTensor,
2778    out_rank: usize,
2779    out_shape_hint: Option<Vec<SymDim>>,
2780) -> Result<TracedTensor> {
2781    let out_dtype = try_inferred_output_dtype(&op, &[input.dtype], "apply_unary")?;
2782    apply_unary_with_dtype(op, input, out_rank, out_shape_hint, out_dtype)
2783}
2784
2785fn try_apply_unary(
2786    op: StdTensorOp,
2787    input: &TracedTensor,
2788    out_rank: usize,
2789    out_shape_hint: Option<Vec<SymDim>>,
2790    context: &'static str,
2791) -> Result<TracedTensor> {
2792    let out_dtype = try_inferred_output_dtype(&op, &[input.dtype], context)?;
2793    apply_unary_with_dtype(op, input, out_rank, out_shape_hint, out_dtype)
2794}
2795
2796pub(crate) fn apply_unary_with_dtype(
2797    op: StdTensorOp,
2798    input: &TracedTensor,
2799    out_rank: usize,
2800    out_shape_hint: Option<Vec<SymDim>>,
2801    out_dtype: DType,
2802) -> Result<TracedTensor> {
2803    let outputs = append_core(&input.ctx, &op, &[input.value])?;
2804    finish_value(&input.ctx, outputs[0], out_rank, out_dtype, out_shape_hint)
2805}
2806
2807/// Apply a unary-primary op that additionally references one or more
2808/// tensors for shape resolution only.
2809///
2810/// The primary `input` becomes op input 0; each tensor in `shape_refs`
2811/// becomes op input 1, 2, … in order. Used by
2812/// [`TracedTensor::broadcast_in_dim_sym`] when the target shape
2813/// references axes of tensors other than the primary input; the op
2814/// reads only their runtime shape, not their data.
2815pub(crate) fn apply_unary_with_shape_refs(
2816    op: StdTensorOp,
2817    input: &TracedTensor,
2818    shape_refs: &[&TracedTensor],
2819    out_rank: usize,
2820    out_shape_hint: Option<Vec<SymDim>>,
2821) -> Result<TracedTensor> {
2822    let mut inputs = Vec::with_capacity(1 + shape_refs.len());
2823    inputs.push(input.value);
2824    for tensor in shape_refs {
2825        ensure_same_context(input, tensor)?;
2826        inputs.push(tensor.value);
2827    }
2828    let outputs = append_core(&input.ctx, &op, &inputs)?;
2829    finish_value(
2830        &input.ctx,
2831        outputs[0],
2832        out_rank,
2833        input.dtype,
2834        out_shape_hint,
2835    )
2836}
2837
2838pub(crate) fn apply_nullary(
2839    op: StdTensorOp,
2840    rank: usize,
2841    dtype: DType,
2842    shape_hint: Option<Vec<SymDim>>,
2843    ctx: &TraceContext,
2844) -> Result<TracedTensor> {
2845    let outputs = append_core(ctx, &op, &[])?;
2846    finish_value(ctx, outputs[0], rank, dtype, shape_hint)
2847}
2848
2849pub(crate) fn apply_binary(
2850    op: StdTensorOp,
2851    lhs: &TracedTensor,
2852    rhs: &TracedTensor,
2853    out_rank: usize,
2854    out_shape_hint: Option<Vec<SymDim>>,
2855) -> Result<TracedTensor> {
2856    let input_dtype = crate::shape_infer::promote_dtype_for_binary_op(&op, lhs.dtype, rhs.dtype);
2857    let out_dtype = try_inferred_output_dtype(&op, &[lhs.dtype, rhs.dtype], "apply_binary")?;
2858
2859    // Insert Convert ops when an input dtype differs from the primitive input dtype.
2860    let lhs = if lhs.dtype != input_dtype {
2861        lhs.cast(input_dtype)?
2862    } else {
2863        lhs.clone()
2864    };
2865    let rhs = if rhs.dtype != input_dtype {
2866        rhs.cast(input_dtype)?
2867    } else {
2868        rhs.clone()
2869    };
2870
2871    apply_binary_with_output_dtype(op, &lhs, &rhs, out_rank, out_shape_hint, out_dtype)
2872}
2873
2874fn try_apply_binary(
2875    op: StdTensorOp,
2876    lhs: &TracedTensor,
2877    rhs: &TracedTensor,
2878    out_rank: usize,
2879    out_shape_hint: Option<Vec<SymDim>>,
2880    context: &'static str,
2881) -> Result<TracedTensor> {
2882    let input_dtype = crate::shape_infer::promote_dtype_for_binary_op(&op, lhs.dtype, rhs.dtype);
2883    let out_dtype = try_inferred_output_dtype(&op, &[lhs.dtype, rhs.dtype], context)?;
2884
2885    let lhs = if lhs.dtype != input_dtype {
2886        lhs.cast(input_dtype)?
2887    } else {
2888        lhs.clone()
2889    };
2890    let rhs = if rhs.dtype != input_dtype {
2891        rhs.cast(input_dtype)?
2892    } else {
2893        rhs.clone()
2894    };
2895
2896    apply_binary_with_output_dtype(op, &lhs, &rhs, out_rank, out_shape_hint, out_dtype)
2897}
2898
2899pub(crate) fn apply_binary_preserve_input_dtypes(
2900    op: StdTensorOp,
2901    lhs: &TracedTensor,
2902    rhs: &TracedTensor,
2903    out_rank: usize,
2904    out_shape_hint: Option<Vec<SymDim>>,
2905    out_dtype: DType,
2906) -> Result<TracedTensor> {
2907    apply_binary_with_output_dtype(op, lhs, rhs, out_rank, out_shape_hint, out_dtype)
2908}
2909
2910pub(crate) fn apply_broadcast_binary_op(
2911    op: StdTensorOp,
2912    lhs: &TracedTensor,
2913    rhs: &TracedTensor,
2914) -> Result<TracedTensor> {
2915    let (lhs, rhs) = broadcast_binary(lhs, rhs)?;
2916    try_apply_binary(
2917        op,
2918        &lhs,
2919        &rhs,
2920        lhs.rank,
2921        lhs.shape_hint.clone(),
2922        "broadcast_binary",
2923    )
2924}
2925
2926pub(crate) fn apply_broadcast_ternary_op(
2927    op: StdTensorOp,
2928    first: &TracedTensor,
2929    second: &TracedTensor,
2930    third: &TracedTensor,
2931) -> Result<TracedTensor> {
2932    let (first, second, third) = broadcast_ternary(first, second, third)?;
2933    try_apply_ternary(
2934        op,
2935        &first,
2936        &second,
2937        &third,
2938        first.rank,
2939        first.shape_hint.clone(),
2940        "broadcast_ternary",
2941    )
2942}
2943
2944fn try_apply_ternary(
2945    op: StdTensorOp,
2946    first: &TracedTensor,
2947    second: &TracedTensor,
2948    third: &TracedTensor,
2949    out_rank: usize,
2950    out_shape_hint: Option<Vec<SymDim>>,
2951    context: &'static str,
2952) -> Result<TracedTensor> {
2953    let out_dtype =
2954        try_inferred_output_dtype(&op, &[first.dtype, second.dtype, third.dtype], context)?;
2955    let (first, second, third) = match op {
2956        StdTensorOp::Select => {
2957            let value_dtype = crate::shape_infer::promote_dtype(second.dtype, third.dtype);
2958            let second = if second.dtype != value_dtype {
2959                second.cast(value_dtype)?
2960            } else {
2961                second.clone()
2962            };
2963            let third = if third.dtype != value_dtype {
2964                third.cast(value_dtype)?
2965            } else {
2966                third.clone()
2967            };
2968            (first.clone(), second, third)
2969        }
2970        _ => {
2971            let input_dtype =
2972                crate::shape_infer::promote_dtypes([first.dtype, second.dtype, third.dtype]);
2973            let first = if first.dtype != input_dtype {
2974                first.cast(input_dtype)?
2975            } else {
2976                first.clone()
2977            };
2978            let second = if second.dtype != input_dtype {
2979                second.cast(input_dtype)?
2980            } else {
2981                second.clone()
2982            };
2983            let third = if third.dtype != input_dtype {
2984                third.cast(input_dtype)?
2985            } else {
2986                third.clone()
2987            };
2988            (first, second, third)
2989        }
2990    };
2991    apply_ternary_with_output_dtype(
2992        op,
2993        &first,
2994        &second,
2995        &third,
2996        out_rank,
2997        out_shape_hint,
2998        out_dtype,
2999    )
3000}
3001
3002fn apply_binary_with_output_dtype(
3003    op: StdTensorOp,
3004    lhs: &TracedTensor,
3005    rhs: &TracedTensor,
3006    out_rank: usize,
3007    out_shape_hint: Option<Vec<SymDim>>,
3008    out_dtype: DType,
3009) -> Result<TracedTensor> {
3010    ensure_same_context(lhs, rhs)?;
3011    let outputs = append_core(&lhs.ctx, &op, &[lhs.value, rhs.value])?;
3012    finish_value(&lhs.ctx, outputs[0], out_rank, out_dtype, out_shape_hint)
3013}
3014
3015fn apply_ternary_with_output_dtype(
3016    op: StdTensorOp,
3017    first: &TracedTensor,
3018    second: &TracedTensor,
3019    third: &TracedTensor,
3020    out_rank: usize,
3021    out_shape_hint: Option<Vec<SymDim>>,
3022    out_dtype: DType,
3023) -> Result<TracedTensor> {
3024    ensure_same_context(first, second)?;
3025    ensure_same_context(first, third)?;
3026    let outputs = append_core(&first.ctx, &op, &[first.value, second.value, third.value])?;
3027    finish_value(&first.ctx, outputs[0], out_rank, out_dtype, out_shape_hint)
3028}
3029
3030/// Reject a combination of traced values that belong to different contexts.
3031pub(crate) fn ensure_same_context(lhs: &TracedTensor, rhs: &TracedTensor) -> Result<()> {
3032    if lhs.ctx.same_context(&rhs.ctx) {
3033        return Ok(());
3034    }
3035    Err(Error::invalid_argument(
3036        "TracedTensor",
3037        ErrorPhase::GraphBuild,
3038        "context",
3039        "traced values from different contexts cannot be combined; build both in the same trace",
3040    ))
3041}
3042
3043mod composite_ops;
3044
3045#[cfg(test)]
3046mod tests;