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;