tenferro_tensor/backend.rs
1use crate::config::{
2 CompareDir, DotGeneralConfig, GatherConfig, PadConfig, ScatterConfig, SliceConfig,
3};
4use crate::types::{
5 TensorRank, TensorScalar, TensorView, TypedTensor, TypedTensorView, TypedTensorViewMut,
6};
7use crate::validate::validate_convert_dtype;
8use crate::{
9 AllocationDomainId, AllocationId, DType, Error, ShapeMismatch, ShapeVec, Tensor, TensorRead,
10 TensorValue, TensorWrite, ValidationError,
11};
12use num_complex::{Complex32, Complex64};
13
14#[cfg(test)]
15mod tests;
16
17fn read_boundary_error(op: &'static str) -> crate::Error {
18 crate::Error::unsupported(
19 op,
20 "backend does not accept borrowed tensor views at this execution boundary",
21 )
22}
23
24fn validation(op: &'static str, source: ValidationError) -> crate::Error {
25 Error::validation(op, source)
26}
27
28/// Gather any host-owned view, including strided or offset layouts, into a compact owner.
29///
30/// This backs the default [`TensorStructural::to_contiguous_read`] for host-owned
31/// views. Backend-owned storage must be rejected by the caller first; the typed
32/// `to_col_major` gather is metadata-driven element copying and never transfers.
33fn default_materialize_host_view(view: TensorView<'_>) -> crate::Result<Tensor> {
34 fn typed<T: TensorScalar>(view: &TypedTensorView<'_, T>) -> crate::Result<Tensor> {
35 view.to_col_major().map(Tensor::from_typed)
36 }
37
38 match view {
39 TensorView::F32(view) => typed(&view),
40 TensorView::F64(view) => typed(&view),
41 TensorView::I32(view) => typed(&view),
42 TensorView::I64(view) => typed(&view),
43 TensorView::Bool(view) => typed(&view),
44 TensorView::C32(view) => typed(&view),
45 TensorView::C64(view) => typed(&view),
46 }
47}
48
49fn invalid_argument(op: &'static str, argument: &'static str, message: impl Into<String>) -> Error {
50 Error::invalid_argument(op, argument, message)
51}
52
53fn read_tensor<'a>(op: &'static str, input: TensorRead<'a>) -> crate::Result<&'a Tensor> {
54 input.as_tensor().ok_or_else(|| read_boundary_error(op))
55}
56
57/// Return the owned tensor behind `input`, or the read-boundary error for a borrowed view.
58///
59/// This is the read-half default a backend receives when it implements only the
60/// one-shot form of an operation: an owned tensor is delegated to the one-shot
61/// method, and a borrowed view is rejected with [`Error::Unsupported`] instead
62/// of being silently materialized.
63///
64/// Issue #1926 makes the `_read` halves required, so an implementor that relied
65/// on the previous default reproduces it by calling this function:
66///
67/// ```text
68/// fn reduce_sum_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> Result<Tensor> {
69/// self.reduce_sum(read_owned_tensor("reduce_sum", input)?, axes)
70/// }
71/// ```
72#[doc(hidden)]
73pub fn read_owned_tensor<'a>(op: &'static str, input: TensorRead<'a>) -> crate::Result<&'a Tensor> {
74 read_tensor(op, input)
75}
76
77fn validate_axis_list(
78 op: &'static str,
79 role: &'static str,
80 axes: &[usize],
81 rank: usize,
82) -> crate::Result<()> {
83 // A linear scan over the axes already seen keeps this path free of a
84 // rank-sized scratch allocation; the axis lists here are short.
85 for (index, &axis) in axes.iter().enumerate() {
86 if axis >= rank {
87 return Err(validation(
88 op,
89 ValidationError::AxisOutOfBounds {
90 axis: isize::try_from(axis).unwrap_or(isize::MAX),
91 rank,
92 },
93 ));
94 }
95 if axes[..index].contains(&axis) {
96 return Err(validation(
97 op,
98 ValidationError::DuplicateAxis { axis, role },
99 ));
100 }
101 }
102 Ok(())
103}
104
105fn validate_role_disjoint(
106 op: &'static str,
107 first_role: &'static str,
108 first_axes: &[usize],
109 second_role: &'static str,
110 second_axes: &[usize],
111) -> crate::Result<()> {
112 for &axis in first_axes {
113 if second_axes.contains(&axis) {
114 return Err(validation(
115 op,
116 ValidationError::AxisRoleConflict {
117 axis,
118 first_role,
119 second_role,
120 },
121 ));
122 }
123 }
124 Ok(())
125}
126
127/// Infer the output shape for a validated dot-general operation.
128#[doc(hidden)]
129pub fn dot_general_output_shape(
130 lhs_shape: &[usize],
131 rhs_shape: &[usize],
132 config: &DotGeneralConfig,
133 op: &'static str,
134) -> crate::Result<ShapeVec> {
135 if config.lhs_contracting_dims.len() != config.rhs_contracting_dims.len() {
136 return Err(invalid_argument(
137 op,
138 "contracting_dims",
139 "lhs/rhs contracting dim counts differ",
140 ));
141 }
142 if config.lhs_batch_dims.len() != config.rhs_batch_dims.len() {
143 return Err(invalid_argument(
144 op,
145 "batch_dims",
146 "lhs/rhs batch dim counts differ",
147 ));
148 }
149
150 let lhs_rank = lhs_shape.len();
151 let rhs_rank = rhs_shape.len();
152 validate_axis_list(
153 op,
154 "lhs_contracting",
155 &config.lhs_contracting_dims,
156 lhs_rank,
157 )?;
158 validate_axis_list(
159 op,
160 "rhs_contracting",
161 &config.rhs_contracting_dims,
162 rhs_rank,
163 )?;
164 validate_axis_list(op, "lhs_batch", &config.lhs_batch_dims, lhs_rank)?;
165 validate_axis_list(op, "rhs_batch", &config.rhs_batch_dims, rhs_rank)?;
166 validate_role_disjoint(
167 op,
168 "lhs_contracting",
169 &config.lhs_contracting_dims,
170 "lhs_batch",
171 &config.lhs_batch_dims,
172 )?;
173 validate_role_disjoint(
174 op,
175 "rhs_contracting",
176 &config.rhs_contracting_dims,
177 "rhs_batch",
178 &config.rhs_batch_dims,
179 )?;
180
181 for (&lhs_axis, &rhs_axis) in config
182 .lhs_contracting_dims
183 .iter()
184 .zip(&config.rhs_contracting_dims)
185 {
186 if lhs_shape[lhs_axis] != rhs_shape[rhs_axis] {
187 return Err(validation(
188 op,
189 ShapeMismatch::ContractedDimensions {
190 lhs_axis,
191 lhs_size: lhs_shape[lhs_axis],
192 rhs_axis,
193 rhs_size: rhs_shape[rhs_axis],
194 }
195 .into(),
196 ));
197 }
198 }
199 for (&lhs_axis, &rhs_axis) in config.lhs_batch_dims.iter().zip(&config.rhs_batch_dims) {
200 if lhs_shape[lhs_axis] != rhs_shape[rhs_axis] {
201 return Err(validation(
202 op,
203 ShapeMismatch::ContractedDimensions {
204 lhs_axis,
205 lhs_size: lhs_shape[lhs_axis],
206 rhs_axis,
207 rhs_size: rhs_shape[rhs_axis],
208 }
209 .into(),
210 ));
211 }
212 }
213
214 let lhs_free = (0..lhs_rank)
215 .filter(|axis| {
216 !config.lhs_contracting_dims.contains(axis) && !config.lhs_batch_dims.contains(axis)
217 })
218 .map(|axis| lhs_shape[axis]);
219 let rhs_free = (0..rhs_rank)
220 .filter(|axis| {
221 !config.rhs_contracting_dims.contains(axis) && !config.rhs_batch_dims.contains(axis)
222 })
223 .map(|axis| rhs_shape[axis]);
224 let batch = config.lhs_batch_dims.iter().map(|&axis| lhs_shape[axis]);
225
226 // Inline for common ranks: the eager dot entry builds this on every call.
227 Ok(lhs_free.chain(rhs_free).chain(batch).collect())
228}
229
230/// Validate output dtype and shape for dot-general read-into dispatch.
231#[doc(hidden)]
232pub fn validate_dot_general_read_into(
233 lhs: &TensorRead<'_>,
234 rhs: &TensorRead<'_>,
235 config: &DotGeneralConfig,
236 out: &TensorWrite<'_>,
237 op: &'static str,
238) -> crate::Result<ShapeVec> {
239 if lhs.dtype() != rhs.dtype() {
240 return Err(validation(
241 op,
242 ValidationError::DTypeMismatch {
243 expected: lhs.dtype(),
244 actual: rhs.dtype(),
245 },
246 ));
247 }
248 if lhs.dtype() != out.dtype() {
249 return Err(validation(
250 op,
251 ValidationError::DTypeMismatch {
252 expected: lhs.dtype(),
253 actual: out.dtype(),
254 },
255 ));
256 }
257 let expected = dot_general_output_shape(lhs.shape(), rhs.shape(), config, op)?;
258 if out.shape() != expected.as_slice() {
259 return Err(validation(
260 op,
261 ShapeMismatch::ExpectedActual {
262 expected: expected.clone(),
263 actual: out.shape().iter().copied().collect(),
264 }
265 .into(),
266 ));
267 }
268 Ok(expected)
269}
270
271/// Scalar coefficient accepted by contraction accumulation backends.
272///
273/// `ContractionScalar` is intentionally narrower than [`crate::TensorScalar`]:
274/// dot-general accumulation is only defined for floating and complex tensor
275/// dtypes.
276///
277/// # Examples
278///
279/// ```rust
280/// use tenferro_tensor::{ContractionScalar, DType};
281///
282/// let alpha = ContractionScalar::F64(2.0);
283/// assert_eq!(alpha.dtype(), DType::F64);
284/// ```
285#[derive(Clone, Copy, Debug, PartialEq)]
286pub enum ContractionScalar {
287 F32(f32),
288 F64(f64),
289 C32(Complex32),
290 C64(Complex64),
291}
292
293impl ContractionScalar {
294 /// Return this scalar's tensor dtype.
295 ///
296 /// # Examples
297 ///
298 /// ```rust
299 /// use tenferro_tensor::{ContractionScalar, DType};
300 ///
301 /// assert_eq!(ContractionScalar::F32(1.0).dtype(), DType::F32);
302 /// ```
303 pub fn dtype(self) -> DType {
304 match self {
305 Self::F32(_) => DType::F32,
306 Self::F64(_) => DType::F64,
307 Self::C32(_) => DType::C32,
308 Self::C64(_) => DType::C64,
309 }
310 }
311
312 /// Return the multiplicative identity for a supported contraction dtype.
313 ///
314 /// # Examples
315 ///
316 /// ```rust
317 /// use tenferro_tensor::{ContractionScalar, DType};
318 ///
319 /// assert_eq!(ContractionScalar::one(DType::F64).unwrap(), ContractionScalar::F64(1.0));
320 /// assert!(ContractionScalar::one(DType::I32).is_err());
321 /// ```
322 /// # Errors
323 ///
324 /// Returns [`crate::Error::Validation`] with a
325 /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` is `I32`,
326 /// `I64`, or `Bool`, which do not support contraction scalar identities.
327 pub fn one(dtype: DType) -> crate::Result<Self> {
328 match dtype {
329 DType::F32 => Ok(Self::F32(1.0)),
330 DType::F64 => Ok(Self::F64(1.0)),
331 DType::C32 => Ok(Self::C32(Complex32::new(1.0, 0.0))),
332 DType::C64 => Ok(Self::C64(Complex64::new(1.0, 0.0))),
333 DType::I32 | DType::I64 | DType::Bool | DType::External(_) => Err(validation(
334 "ContractionScalar::one",
335 ValidationError::DTypeMismatch {
336 expected: dtype,
337 actual: DType::F32,
338 },
339 )),
340 }
341 }
342
343 /// Return the additive identity for a supported contraction dtype.
344 ///
345 /// # Examples
346 ///
347 /// ```rust
348 /// use tenferro_tensor::{ContractionScalar, DType};
349 ///
350 /// assert_eq!(ContractionScalar::zero(DType::F64).unwrap(), ContractionScalar::F64(0.0));
351 /// ```
352 /// # Errors
353 ///
354 /// Returns [`crate::Error::Validation`] with a
355 /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` is `I32`,
356 /// `I64`, or `Bool`, which do not support contraction scalar identities.
357 pub fn zero(dtype: DType) -> crate::Result<Self> {
358 match dtype {
359 DType::F32 => Ok(Self::F32(0.0)),
360 DType::F64 => Ok(Self::F64(0.0)),
361 DType::C32 => Ok(Self::C32(Complex32::new(0.0, 0.0))),
362 DType::C64 => Ok(Self::C64(Complex64::new(0.0, 0.0))),
363 DType::I32 | DType::I64 | DType::Bool | DType::External(_) => Err(validation(
364 "ContractionScalar::zero",
365 ValidationError::DTypeMismatch {
366 expected: dtype,
367 actual: DType::F32,
368 },
369 )),
370 }
371 }
372}
373
374/// Output-update semantics for dot-general accumulation.
375///
376/// This keeps contraction axes in [`DotGeneralConfig`] and output update
377/// semantics here, so cached and non-cached backend traits can share the same
378/// accumulation contract.
379///
380/// # Examples
381///
382/// ```rust
383/// use tenferro_tensor::{ContractionScalar, DotGeneralAccumulation, DType};
384///
385/// let accum = DotGeneralAccumulation::overwrite(DType::F64).unwrap();
386/// assert_eq!(accum.alpha, ContractionScalar::F64(1.0));
387/// assert_eq!(accum.beta, ContractionScalar::F64(0.0));
388/// ```
389#[derive(Clone, Copy, Debug, PartialEq)]
390pub struct DotGeneralAccumulation {
391 pub lhs_conj: bool,
392 pub rhs_conj: bool,
393 pub alpha: ContractionScalar,
394 pub beta: ContractionScalar,
395}
396
397impl DotGeneralAccumulation {
398 fn identity(
399 op: &'static str,
400 dtype: DType,
401 multiplicative: bool,
402 ) -> crate::Result<ContractionScalar> {
403 let result = if multiplicative {
404 ContractionScalar::one(dtype)
405 } else {
406 ContractionScalar::zero(dtype)
407 };
408 result.map_err(|error| match error {
409 Error::Validation { source, .. } => validation(op, source),
410 error => error,
411 })
412 }
413
414 /// Return overwrite semantics, `out = lhs dot rhs`, for `dtype`.
415 ///
416 /// # Examples
417 ///
418 /// ```rust
419 /// use tenferro_tensor::{ContractionScalar, DotGeneralAccumulation, DType};
420 ///
421 /// let accum = DotGeneralAccumulation::overwrite(DType::F64).unwrap();
422 /// assert_eq!(accum.alpha, ContractionScalar::F64(1.0));
423 /// assert_eq!(accum.beta, ContractionScalar::F64(0.0));
424 /// ```
425 ///
426 /// # Errors
427 ///
428 /// Returns [`crate::Error::Validation`] with a
429 /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` does not
430 /// support contraction scalar identities.
431 pub fn overwrite(dtype: DType) -> crate::Result<Self> {
432 Ok(Self {
433 lhs_conj: false,
434 rhs_conj: false,
435 alpha: Self::identity("DotGeneralAccumulation::overwrite", dtype, true)?,
436 beta: Self::identity("DotGeneralAccumulation::overwrite", dtype, false)?,
437 })
438 }
439
440 /// Return additive update semantics, `out += lhs dot rhs`, for `dtype`.
441 ///
442 /// # Examples
443 ///
444 /// ```rust
445 /// use tenferro_tensor::{ContractionScalar, DType, DotGeneralAccumulation};
446 ///
447 /// let accum = DotGeneralAccumulation::add_to(DType::F64)?;
448 /// assert_eq!(accum.alpha, ContractionScalar::F64(1.0));
449 /// assert_eq!(accum.beta, ContractionScalar::F64(1.0));
450 /// # Ok::<(), tenferro_tensor::Error>(())
451 /// ```
452 /// # Errors
453 ///
454 /// Returns [`crate::Error::Validation`] with a
455 /// [`crate::ValidationError::DTypeMismatch`] source when `dtype` does not
456 /// support contraction scalar identities.
457 pub fn add_to(dtype: DType) -> crate::Result<Self> {
458 Ok(Self {
459 lhs_conj: false,
460 rhs_conj: false,
461 alpha: Self::identity("DotGeneralAccumulation::add_to", dtype, true)?,
462 beta: Self::identity("DotGeneralAccumulation::add_to", dtype, true)?,
463 })
464 }
465
466 /// Return scaled update semantics, `out = alpha * lhs dot rhs + beta * out`.
467 ///
468 /// # Examples
469 ///
470 /// ```rust
471 /// use tenferro_tensor::{ContractionScalar, DotGeneralAccumulation};
472 ///
473 /// let accum = DotGeneralAccumulation::scaled(
474 /// ContractionScalar::F32(0.5),
475 /// ContractionScalar::F32(2.0),
476 /// )?;
477 /// assert_eq!(accum.alpha, ContractionScalar::F32(0.5));
478 /// # Ok::<(), tenferro_tensor::Error>(())
479 /// ```
480 /// # Errors
481 ///
482 /// Returns [`crate::Error::Validation`] with a
483 /// [`crate::ValidationError::DTypeMismatch`] source when `alpha` and `beta`
484 /// have different dtypes.
485 pub fn scaled(alpha: ContractionScalar, beta: ContractionScalar) -> crate::Result<Self> {
486 if alpha.dtype() != beta.dtype() {
487 return Err(validation(
488 "DotGeneralAccumulation::scaled",
489 ValidationError::DTypeMismatch {
490 expected: alpha.dtype(),
491 actual: beta.dtype(),
492 },
493 ));
494 }
495 Ok(Self {
496 lhs_conj: false,
497 rhs_conj: false,
498 alpha,
499 beta,
500 })
501 }
502
503 fn validate_for_dtype(self, dtype: DType) -> crate::Result<()> {
504 for scalar in [self.alpha, self.beta] {
505 if scalar.dtype() != dtype {
506 return Err(validation(
507 "dot_general",
508 ValidationError::DTypeMismatch {
509 expected: scalar.dtype(),
510 actual: dtype,
511 },
512 ));
513 }
514 }
515 Ok(())
516 }
517}
518
519#[doc(hidden)]
520pub fn validate_dot_general_accumulation(
521 lhs: &TensorRead<'_>,
522 rhs: &TensorRead<'_>,
523 config: &DotGeneralConfig,
524 accumulation: DotGeneralAccumulation,
525 out: &TensorWrite<'_>,
526 op: &'static str,
527) -> crate::Result<ShapeVec> {
528 let shape = validate_dot_general_read_into(lhs, rhs, config, out, op)?;
529 accumulation.validate_for_dtype(lhs.dtype())?;
530 Ok(shape)
531}
532
533#[doc(hidden)]
534pub fn dot_general_accum_via_temp<B: TensorDot + ?Sized>(
535 backend: &mut B,
536 lhs: TensorRead<'_>,
537 rhs: TensorRead<'_>,
538 config: &DotGeneralConfig,
539 accumulation: DotGeneralAccumulation,
540 mut out: TensorWrite<'_>,
541) -> crate::Result<()> {
542 validate_dot_general_accumulation(&lhs, &rhs, config, accumulation, &out, "dot_general")?;
543 let dot = backend.dot_general_with_conj_read(
544 lhs,
545 rhs,
546 config,
547 accumulation.lhs_conj,
548 accumulation.rhs_conj,
549 )?;
550 accumulate_dot_result_into(&dot, accumulation, &mut out)
551}
552
553#[doc(hidden)]
554pub fn accumulate_dot_result_into(
555 dot: &Tensor,
556 accumulation: DotGeneralAccumulation,
557 out: &mut TensorWrite<'_>,
558) -> crate::Result<()> {
559 macro_rules! dispatch {
560 ($variant:ident, $ty:ty) => {
561 if dot.dtype() == <$ty as crate::TensorScalar>::dtype() {
562 let (ContractionScalar::$variant(alpha), ContractionScalar::$variant(beta)) =
563 (accumulation.alpha, accumulation.beta)
564 else {
565 return Err(validation(
566 "dot_general",
567 ValidationError::DTypeMismatch {
568 expected: dot.dtype(),
569 actual: accumulation.alpha.dtype(),
570 },
571 ));
572 };
573 let dot = dot
574 .as_typed::<$ty>()
575 .expect("the dtype guard selects this arm");
576 match out {
577 TensorWrite::Tensor(out) => {
578 let out = out
579 .as_typed_mut::<$ty>()
580 .expect("the dtype guard selects this arm");
581 let mut out = out.as_view_mut();
582 accumulate_typed(dot.as_slice()?, alpha, beta, &mut out)?;
583 return Ok(());
584 }
585 TensorWrite::View(crate::TensorViewMut::$variant(out)) => {
586 accumulate_typed(dot.as_slice()?, alpha, beta, out)?;
587 return Ok(());
588 }
589 _ => {}
590 }
591 }
592 };
593 }
594
595 dispatch!(F32, f32);
596 dispatch!(F64, f64);
597 dispatch!(C32, Complex32);
598 dispatch!(C64, Complex64);
599
600 Err(validation(
601 "dot_general",
602 ValidationError::DTypeMismatch {
603 expected: accumulation.alpha.dtype(),
604 actual: dot.dtype(),
605 },
606 ))
607}
608
609fn accumulate_typed<T>(
610 dot: &[T],
611 alpha: T,
612 beta: T,
613 out: &mut TypedTensorViewMut<'_, T>,
614) -> crate::Result<()>
615where
616 T: Copy
617 + PartialEq
618 + std::ops::Add<Output = T>
619 + std::ops::Mul<Output = T>
620 + num_traits::Zero
621 + 'static,
622{
623 let beta_is_zero = beta == T::zero();
624 if let Some(output) = compact_host_accumulation_slice(out, dot.len())? {
625 for (output, dot_value) in output.iter_mut().zip(dot.iter().copied()) {
626 // INVARIANT: beta == 0 follows BLAS GEMM semantics and does not read
627 // the existing output element; beta != 0 requires an initialized
628 // TensorWrite target and performs a read-modify-write update.
629 *output = if beta_is_zero {
630 alpha * dot_value
631 } else {
632 alpha * dot_value + beta * *output
633 };
634 }
635 return Ok(());
636 }
637
638 for (linear, dot_value) in dot.iter().copied().enumerate() {
639 let indices = flat_to_multi_for_shape(out.shape(), linear);
640 let output = out.get_mut(&indices).ok_or_else(|| {
641 invalid_argument(
642 "dot_general",
643 "output",
644 format!("index {indices:?} is outside accumulation target"),
645 )
646 })?;
647 // INVARIANT: beta == 0 follows BLAS GEMM semantics and does not read
648 // the existing output element; beta != 0 requires an initialized
649 // TensorWrite target and performs a read-modify-write update.
650 *output = if beta_is_zero {
651 alpha * dot_value
652 } else {
653 alpha * dot_value + beta * *output
654 };
655 }
656 Ok(())
657}
658
659fn compact_host_accumulation_slice<'a, T: 'static>(
660 out: &'a mut TypedTensorViewMut<'_, T>,
661 expected_len: usize,
662) -> crate::Result<Option<&'a mut [T]>> {
663 if out.backend_buffer().is_some()
664 || out.n_elements() != expected_len
665 || !out.is_col_major_contiguous()?
666 {
667 return Ok(None);
668 }
669
670 let start = usize::try_from(out.offset()).map_err(|_| {
671 invalid_argument("dot_general", "output", "compact output offset is negative")
672 })?;
673 let end = start
674 .checked_add(expected_len)
675 .ok_or_else(|| validation("dot_general", ValidationError::IntegerOverflow))?;
676 out.host_storage_mut()?
677 .get_mut(start..end)
678 .map(Some)
679 .ok_or_else(|| {
680 invalid_argument(
681 "dot_general",
682 "output",
683 "compact output is outside its backing storage",
684 )
685 })
686}
687
688fn flat_to_multi_for_shape(shape: &[usize], mut linear: usize) -> Vec<usize> {
689 let mut indices = Vec::with_capacity(shape.len());
690 for &dim in shape {
691 if dim == 0 {
692 indices.push(0);
693 } else {
694 indices.push(linear % dim);
695 linear /= dim;
696 }
697 }
698 indices
699}
700
701/// Canonical elementwise fusion plan shared between segmented execution and backends.
702#[doc(hidden)]
703#[derive(Clone, Debug, Hash, PartialEq, Eq)]
704pub struct ElementwiseFusionPlan {
705 dtype: crate::DType,
706 input_count: usize,
707 // Keep view metadata in Vecs. A/B benchmarking on the broadcast_mul
708 // path showed SmallVec made this metadata path about 6-7% slower.
709 input_views: Vec<ElementwiseFusionInputView>,
710 outputs: Vec<usize>,
711 ops: Vec<ElementwiseFusionInst>,
712}
713
714/// Metadata-only view applied to one backend fusion input.
715#[doc(hidden)]
716#[derive(Clone, Debug, Hash, PartialEq, Eq)]
717pub enum ElementwiseFusionInputView {
718 Identity,
719 BroadcastInDim {
720 // Vec is intentional here; see ElementwiseFusionPlan::input_views.
721 shape: Vec<usize>,
722 dims: Vec<usize>,
723 },
724}
725
726/// One node in a canonical elementwise fusion plan.
727#[doc(hidden)]
728#[derive(Clone, Debug, Hash, PartialEq, Eq)]
729pub struct ElementwiseFusionInst {
730 op: ElementwiseFusionOp,
731 inputs: Vec<usize>,
732}
733
734tenferro_core_ops::define_elementwise_fusion_op!();
735
736impl ElementwiseFusionPlan {
737 /// Build a backend elementwise fusion plan.
738 ///
739 /// # Examples
740 ///
741 /// ```rust
742 /// use tenferro_tensor::backend::{
743 /// ElementwiseFusionInst, ElementwiseFusionOp, ElementwiseFusionPlan,
744 /// };
745 /// use tenferro_tensor::DType;
746 ///
747 /// let plan = ElementwiseFusionPlan::new(
748 /// DType::F64,
749 /// 2,
750 /// vec![2],
751 /// vec![ElementwiseFusionInst::new(ElementwiseFusionOp::Add, vec![0, 1])],
752 /// );
753 /// assert_eq!(plan.input_count(), 2);
754 /// ```
755 pub fn new(
756 dtype: crate::DType,
757 input_count: usize,
758 outputs: Vec<usize>,
759 ops: Vec<ElementwiseFusionInst>,
760 ) -> Self {
761 Self::with_input_views(
762 dtype,
763 vec![ElementwiseFusionInputView::Identity; input_count],
764 outputs,
765 ops,
766 )
767 }
768
769 /// Build a backend elementwise fusion plan with input view metadata.
770 ///
771 /// # Examples
772 ///
773 /// ```rust
774 /// use tenferro_tensor::backend::{
775 /// ElementwiseFusionInputView, ElementwiseFusionInst, ElementwiseFusionOp,
776 /// ElementwiseFusionPlan,
777 /// };
778 /// use tenferro_tensor::DType;
779 ///
780 /// let plan = ElementwiseFusionPlan::with_input_views(
781 /// DType::F64,
782 /// vec![ElementwiseFusionInputView::broadcast_in_dim(vec![2, 3], vec![0])],
783 /// vec![1],
784 /// vec![ElementwiseFusionInst::new(ElementwiseFusionOp::Negate, vec![0])],
785 /// );
786 /// assert_eq!(plan.input_count(), 1);
787 /// ```
788 pub fn with_input_views(
789 dtype: crate::DType,
790 input_views: impl IntoIterator<Item = ElementwiseFusionInputView>,
791 outputs: Vec<usize>,
792 ops: Vec<ElementwiseFusionInst>,
793 ) -> Self {
794 let input_views = input_views.into_iter().collect::<Vec<_>>();
795 let input_count = input_views.len();
796 Self {
797 dtype,
798 input_count,
799 input_views,
800 outputs,
801 ops,
802 }
803 }
804
805 /// Return the scalar dtype expected by this fusion plan.
806 ///
807 /// # Examples
808 ///
809 /// ```rust
810 /// use tenferro_tensor::backend::ElementwiseFusionPlan;
811 /// use tenferro_tensor::DType;
812 ///
813 /// let plan = ElementwiseFusionPlan::new(DType::F32, 0, Vec::new(), Vec::new());
814 /// assert_eq!(plan.dtype(), DType::F32);
815 /// ```
816 pub fn dtype(&self) -> crate::DType {
817 self.dtype
818 }
819
820 /// Return the number of input tensors expected by this plan.
821 ///
822 /// # Examples
823 ///
824 /// ```rust
825 /// use tenferro_tensor::backend::ElementwiseFusionPlan;
826 /// use tenferro_tensor::DType;
827 ///
828 /// let plan = ElementwiseFusionPlan::new(DType::F64, 3, Vec::new(), Vec::new());
829 /// assert_eq!(plan.input_count(), 3);
830 /// ```
831 pub fn input_count(&self) -> usize {
832 self.input_count
833 }
834
835 /// Return metadata views applied to fusion inputs before executing ops.
836 ///
837 /// # Examples
838 ///
839 /// ```rust
840 /// use tenferro_tensor::backend::ElementwiseFusionPlan;
841 /// use tenferro_tensor::DType;
842 ///
843 /// let plan = ElementwiseFusionPlan::new(DType::F64, 2, Vec::new(), Vec::new());
844 /// assert_eq!(plan.input_views().len(), 2);
845 /// ```
846 pub fn input_views(&self) -> &[ElementwiseFusionInputView] {
847 &self.input_views
848 }
849
850 /// Return the value ids selected as fusion outputs.
851 ///
852 /// # Examples
853 ///
854 /// ```rust
855 /// use tenferro_tensor::backend::ElementwiseFusionPlan;
856 /// use tenferro_tensor::DType;
857 ///
858 /// let plan = ElementwiseFusionPlan::new(DType::F64, 0, vec![0], Vec::new());
859 /// assert_eq!(plan.outputs(), &[0]);
860 /// ```
861 pub fn outputs(&self) -> &[usize] {
862 &self.outputs
863 }
864
865 /// Return the fused elementwise instruction sequence.
866 ///
867 /// # Examples
868 ///
869 /// ```rust
870 /// use tenferro_tensor::backend::{
871 /// ElementwiseFusionInst, ElementwiseFusionOp, ElementwiseFusionPlan,
872 /// };
873 /// use tenferro_tensor::DType;
874 ///
875 /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Negate, vec![0]);
876 /// let plan = ElementwiseFusionPlan::new(DType::F64, 1, vec![1], vec![inst]);
877 /// assert_eq!(plan.ops().len(), 1);
878 /// ```
879 pub fn ops(&self) -> &[ElementwiseFusionInst] {
880 &self.ops
881 }
882}
883
884impl ElementwiseFusionInputView {
885 /// Build metadata for a `BroadcastInDim` fusion input view.
886 ///
887 /// # Examples
888 ///
889 /// ```rust
890 /// use tenferro_tensor::backend::ElementwiseFusionInputView;
891 ///
892 /// let view = ElementwiseFusionInputView::broadcast_in_dim(vec![2, 3], vec![0]);
893 /// assert!(matches!(view, ElementwiseFusionInputView::BroadcastInDim { .. }));
894 /// ```
895 pub fn broadcast_in_dim(
896 shape: impl IntoIterator<Item = usize>,
897 dims: impl IntoIterator<Item = usize>,
898 ) -> Self {
899 Self::BroadcastInDim {
900 shape: shape.into_iter().collect(),
901 dims: dims.into_iter().collect(),
902 }
903 }
904
905 /// Return true when this fusion input is an identity view.
906 ///
907 /// # Examples
908 ///
909 /// ```rust
910 /// use tenferro_tensor::backend::ElementwiseFusionInputView;
911 ///
912 /// assert!(ElementwiseFusionInputView::Identity.is_identity());
913 /// ```
914 pub fn is_identity(&self) -> bool {
915 matches!(self, Self::Identity)
916 }
917}
918
919impl ElementwiseFusionInst {
920 /// Build a backend elementwise fusion instruction.
921 ///
922 /// # Examples
923 ///
924 /// ```rust
925 /// use tenferro_tensor::backend::{ElementwiseFusionInst, ElementwiseFusionOp};
926 ///
927 /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Add, vec![0, 1]);
928 /// assert_eq!(inst.inputs(), &[0, 1]);
929 /// ```
930 pub fn new(op: ElementwiseFusionOp, inputs: Vec<usize>) -> Self {
931 Self { op, inputs }
932 }
933
934 /// Return the elementwise op executed by this instruction.
935 ///
936 /// # Examples
937 ///
938 /// ```rust
939 /// use tenferro_tensor::backend::{ElementwiseFusionInst, ElementwiseFusionOp};
940 ///
941 /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Negate, vec![0]);
942 /// assert_eq!(inst.op(), ElementwiseFusionOp::Negate);
943 /// ```
944 pub fn op(&self) -> ElementwiseFusionOp {
945 self.op
946 }
947
948 /// Return this instruction's input value ids.
949 ///
950 /// # Examples
951 ///
952 /// ```rust
953 /// use tenferro_tensor::backend::{ElementwiseFusionInst, ElementwiseFusionOp};
954 ///
955 /// let inst = ElementwiseFusionInst::new(ElementwiseFusionOp::Multiply, vec![2, 0]);
956 /// assert_eq!(inst.inputs(), &[2, 0]);
957 /// ```
958 pub fn inputs(&self) -> &[usize] {
959 &self.inputs
960 }
961}
962
963/// Runtime operation selected by [`TensorElementwise::elementwise_read_into`].
964#[non_exhaustive]
965#[derive(Clone, Copy, Debug, Eq, PartialEq)]
966pub enum ElementwiseReadOp {
967 /// Binary addition.
968 Add,
969 /// Binary subtraction.
970 Subtract,
971 /// Binary multiplication.
972 Multiply,
973 /// Unary negation.
974 Negate,
975 /// Unary conjugation.
976 Conj,
977 /// Binary division.
978 Divide,
979}
980
981/// Fused real-float activation applied in one elementwise pass.
982///
983/// The variants name the same functions the composite activation vocabulary
984/// exposes; a backend that supports the fused form computes the whole
985/// expression in one traversal instead of materializing every intermediate.
986///
987/// # Examples
988///
989/// ```
990/// use tenferro_tensor::ActivationOp;
991/// assert_eq!(ActivationOp::Sigmoid.label(), "sigmoid");
992/// ```
993#[derive(Clone, Copy, Debug, PartialEq, Eq)]
994pub enum ActivationOp {
995 /// Logistic sigmoid `1 / (1 + exp(-x))`, overflow-free.
996 Sigmoid,
997 /// SiLU / swish `x * sigmoid(x)`.
998 Silu,
999 /// Softplus `max(x, 0) + log1p(exp(-|x|))`.
1000 Softplus,
1001 /// Exact GELU `x/2 * (1 + erf(x / sqrt(2)))`.
1002 Gelu,
1003 /// GELU tanh approximation `x/2 * (1 + tanh(sqrt(2/pi) * (x + 0.044715 x^3)))`.
1004 GeluTanh,
1005}
1006
1007impl ActivationOp {
1008 /// Stable operation label used in errors and profiling.
1009 #[doc(hidden)]
1010 pub fn label(self) -> &'static str {
1011 match self {
1012 Self::Sigmoid => "sigmoid",
1013 Self::Silu => "silu",
1014 Self::Softplus => "softplus",
1015 Self::Gelu => "gelu",
1016 Self::GeluTanh => "gelu_tanh",
1017 }
1018 }
1019}
1020
1021impl ElementwiseReadOp {
1022 #[doc(hidden)]
1023 pub fn label(self) -> &'static str {
1024 match self {
1025 Self::Add => "add",
1026 Self::Subtract => "sub",
1027 Self::Multiply => "mul",
1028 Self::Negate => "neg",
1029 Self::Conj => "conj",
1030 Self::Divide => "div",
1031 }
1032 }
1033
1034 #[doc(hidden)]
1035 pub fn arity(self) -> usize {
1036 match self {
1037 Self::Negate | Self::Conj => 1,
1038 Self::Add | Self::Subtract | Self::Multiply | Self::Divide => 2,
1039 }
1040 }
1041}
1042
1043#[derive(Clone, Copy, Debug)]
1044enum StorageIdentity {
1045 Host {
1046 start: usize,
1047 end: usize,
1048 },
1049 Backend {
1050 domain: Option<AllocationDomainId>,
1051 allocation: Option<AllocationId>,
1052 family: &'static str,
1053 object: usize,
1054 },
1055}
1056
1057fn host_storage_identity<T>(data: &[T]) -> StorageIdentity {
1058 let start = data.as_ptr() as usize;
1059 let bytes = std::mem::size_of_val(data);
1060 StorageIdentity::Host {
1061 start,
1062 end: start.saturating_add(bytes),
1063 }
1064}
1065
1066fn backend_storage_identity<T: 'static>(buffer: &dyn crate::BackendStorage<T>) -> StorageIdentity {
1067 StorageIdentity::Backend {
1068 domain: buffer.allocation_domain(),
1069 allocation: buffer.allocation_id(),
1070 family: buffer.backend_family(),
1071 // INVARIANT: every backend buffer is borrowed from the single Box-owned
1072 // root allocation; the data pointer of this trait object is stable for
1073 // that owner and is used only as a fallback when provider identity is
1074 // unavailable.
1075 object: buffer as *const dyn crate::BackendStorage<T> as *const () as usize,
1076 }
1077}
1078
1079fn typed_tensor_storage_identity<T: crate::TensorScalar>(
1080 tensor: &TypedTensor<T>,
1081) -> crate::Result<StorageIdentity> {
1082 if tensor.backend_buffer().is_some() {
1083 let buffer = tensor.backend_buffer().ok_or_else(|| {
1084 crate::Error::runtime_state("typed_tensor_storage_identity", "backend buffer missing")
1085 })?;
1086 Ok(backend_storage_identity(buffer))
1087 } else {
1088 Ok(host_storage_identity(tensor.host_data()?))
1089 }
1090}
1091
1092fn typed_view_storage_identity<T: crate::TensorScalar + 'static>(
1093 view: &TypedTensorView<'_, T>,
1094) -> crate::Result<StorageIdentity> {
1095 match view.backend_buffer() {
1096 Some(buffer) => Ok(backend_storage_identity(buffer)),
1097 None => view.host_storage().map(host_storage_identity),
1098 }
1099}
1100
1101/// The typed tensor behind `value`, or the refusal this module reports for one.
1102///
1103/// Callers reach this from a match on the dtype, so `None` means the tag and the runtime dtype
1104/// disagree rather than a caller mistake.
1105fn identity_operand<T: TensorScalar>(value: &Tensor) -> crate::Result<&TypedTensor<T>> {
1106 value.as_typed::<T>().ok_or_else(|| {
1107 crate::Error::unsupported_dtype(
1108 "storage_identity",
1109 value.dtype(),
1110 "an externally defined payload has no storage identity",
1111 )
1112 })
1113}
1114
1115fn tensor_read_storage_identity(input: &TensorRead<'_>) -> crate::Result<StorageIdentity> {
1116 macro_rules! typed_identity {
1117 ($value:expr) => {
1118 match $value.dtype() {
1119 DType::F32 => typed_tensor_storage_identity(identity_operand::<f32>($value)?),
1120 DType::F64 => typed_tensor_storage_identity(identity_operand::<f64>($value)?),
1121 DType::I32 => typed_tensor_storage_identity(identity_operand::<i32>($value)?),
1122 DType::I64 => typed_tensor_storage_identity(identity_operand::<i64>($value)?),
1123 DType::Bool => typed_tensor_storage_identity(identity_operand::<bool>($value)?),
1124 DType::C32 => typed_tensor_storage_identity(identity_operand::<Complex32>($value)?),
1125 DType::C64 => typed_tensor_storage_identity(identity_operand::<Complex64>($value)?),
1126 // A caller-owned payload has no allocation identity, so it cannot
1127 // take part in an aliasing check.
1128 DType::External(_) => {
1129 return Err(crate::Error::unsupported_dtype(
1130 "storage_identity",
1131 $value.dtype(),
1132 "an externally defined payload has no storage identity",
1133 ));
1134 }
1135 }
1136 };
1137 }
1138 macro_rules! view_identity {
1139 ($value:expr) => {
1140 match $value {
1141 TensorView::F32(value) => typed_view_storage_identity(value),
1142 TensorView::F64(value) => typed_view_storage_identity(value),
1143 TensorView::I32(value) => typed_view_storage_identity(value),
1144 TensorView::I64(value) => typed_view_storage_identity(value),
1145 TensorView::Bool(value) => typed_view_storage_identity(value),
1146 TensorView::C32(value) => typed_view_storage_identity(value),
1147 TensorView::C64(value) => typed_view_storage_identity(value),
1148 }
1149 };
1150 }
1151
1152 match input {
1153 TensorRead::Tensor(tensor) => typed_identity!(tensor),
1154 TensorRead::View(view) => view_identity!(view),
1155 }
1156}
1157
1158fn storage_overlaps(lhs: StorageIdentity, rhs: StorageIdentity) -> bool {
1159 match (lhs, rhs) {
1160 (
1161 StorageIdentity::Host {
1162 start: lhs_start,
1163 end: lhs_end,
1164 },
1165 StorageIdentity::Host {
1166 start: rhs_start,
1167 end: rhs_end,
1168 },
1169 ) => lhs_start < rhs_end && rhs_start < lhs_end,
1170 (
1171 StorageIdentity::Backend {
1172 domain: lhs_domain,
1173 allocation: lhs_allocation,
1174 family: lhs_family,
1175 object: lhs_object,
1176 },
1177 StorageIdentity::Backend {
1178 domain: rhs_domain,
1179 allocation: rhs_allocation,
1180 family: rhs_family,
1181 object: rhs_object,
1182 },
1183 ) => {
1184 lhs_object == rhs_object
1185 || matches!(
1186 (lhs_domain, rhs_domain, lhs_allocation, rhs_allocation),
1187 (Some(lhs_domain), Some(rhs_domain), Some(lhs), Some(rhs))
1188 if lhs_domain == rhs_domain && lhs == rhs
1189 )
1190 || matches!(
1191 (lhs_domain, rhs_domain, lhs_allocation, rhs_allocation),
1192 (None, None, Some(lhs), Some(rhs)) if lhs_family == rhs_family && lhs == rhs
1193 )
1194 }
1195 _ => false,
1196 }
1197}
1198
1199/// Validate that a caller-owned destination does not overlap any read input.
1200///
1201/// The check is intentionally conservative for host views: two views backed by
1202/// the same host allocation are treated as overlapping because the allocation
1203/// identity is the only stable boundary contract available to erased backend
1204/// code. Backend allocations use their domain/allocation identity when the
1205/// provider exposes it.
1206///
1207/// # Errors
1208///
1209/// Returns `tenferro_tensor_core::ValidationError::InvalidArgument` when the
1210/// destination storage overlaps an input, or `Error::RuntimeState` when
1211/// storage identity cannot be established safely.
1212///
1213/// # Examples
1214///
1215/// ```rust
1216/// use tenferro_tensor::{Tensor, TensorRead, TensorWrite};
1217/// use tenferro_tensor::backend::validate_read_into_destination;
1218///
1219/// let input = Tensor::from_vec_col_major(vec![1], vec![1.0_f64])?;
1220/// let mut output = Tensor::from_vec_col_major(vec![1], vec![0.0_f64])?;
1221/// validate_read_into_destination(
1222/// "example",
1223/// &[TensorRead::from_tensor(&input)],
1224/// &TensorWrite::from_tensor(&mut output),
1225/// )?;
1226/// # Ok::<(), tenferro_tensor::Error>(())
1227/// ```
1228pub fn validate_read_into_destination(
1229 op: &'static str,
1230 inputs: &[TensorRead<'_>],
1231 out: &TensorWrite<'_>,
1232) -> crate::Result<()> {
1233 let output_identity = tensor_read_storage_identity(&out.as_read())?;
1234 for (index, input) in inputs.iter().enumerate() {
1235 if storage_overlaps(tensor_read_storage_identity(input)?, output_identity) {
1236 return Err(Error::invalid_argument(
1237 op,
1238 "out",
1239 format!("destination storage overlaps input {index}"),
1240 ));
1241 }
1242 }
1243 Ok(())
1244}
1245
1246/// Execute a read-into elementwise operation through a backend's allocating operations.
1247///
1248/// Backend implementations use this helper when their device-native operation
1249/// APIs already provide the correct placement and copy semantics. It deliberately
1250/// does not inspect or transfer storage across devices.
1251///
1252/// # Errors
1253///
1254/// Returns [`Error::Validation`] for wrong arity or overlapping output storage,
1255/// and propagates the selected backend operation and copy errors.
1256#[doc(hidden)]
1257pub fn elementwise_read_into_via_allocating_ops<B: TensorElementwise + ?Sized>(
1258 backend: &mut B,
1259 op: ElementwiseReadOp,
1260 inputs: &[TensorRead<'_>],
1261 out: TensorWrite<'_>,
1262) -> crate::Result<()> {
1263 if inputs.len() != op.arity() {
1264 return Err(Error::invalid_argument(
1265 op.label(),
1266 "inputs",
1267 format!("expected {} inputs, got {}", op.arity(), inputs.len()),
1268 ));
1269 }
1270 validate_read_into_destination(op.label(), inputs, &out)?;
1271 let result = match op {
1272 ElementwiseReadOp::Add => backend.add_read(inputs[0].clone(), inputs[1].clone())?,
1273 ElementwiseReadOp::Subtract => backend.sub_read(inputs[0].clone(), inputs[1].clone())?,
1274 ElementwiseReadOp::Multiply => backend.mul_read(inputs[0].clone(), inputs[1].clone())?,
1275 ElementwiseReadOp::Negate => backend.neg_read(inputs[0].clone())?,
1276 ElementwiseReadOp::Conj => backend.conj_read(inputs[0].clone())?,
1277 ElementwiseReadOp::Divide => backend.div_read(inputs[0].clone(), inputs[1].clone())?,
1278 };
1279 backend.copy_read_into(TensorRead::from_tensor(&result), out)
1280}
1281
1282/// Elementwise tensor operations.
1283///
1284/// # Examples
1285///
1286/// ```rust
1287/// use tenferro_tensor::TensorElementwise;
1288///
1289/// fn accepts_elementwise<B: TensorElementwise>(_backend: &mut B) {}
1290/// ```
1291pub trait TensorElementwise: TensorStructural {
1292 /// Execute an elementwise operation into caller-owned storage.
1293 ///
1294 /// Every backend must implement this hook with its explicit execution
1295 /// context, placement checks, and output-storage policy. The hook is the
1296 /// backend boundary for borrowed inputs and caller-owned output; it must not
1297 /// silently transfer data between devices.
1298 ///
1299 /// # Examples
1300 ///
1301 /// ```rust
1302 /// use tenferro_tensor::{ElementwiseReadOp, TensorElementwise, TensorRead, TensorWrite};
1303 ///
1304 /// fn run_into<B: TensorElementwise>(
1305 /// backend: &mut B,
1306 /// input: TensorRead<'_>,
1307 /// out: TensorWrite<'_>,
1308 /// ) -> tenferro_tensor::Result<()> {
1309 /// backend.elementwise_read_into(ElementwiseReadOp::Conj, &[input], out)
1310 /// }
1311 /// ```
1312 ///
1313 /// # Errors
1314 ///
1315 /// Returns [`crate::Error::Validation`] for invalid arity, metadata, or
1316 /// overlapping storage. Backend-specific placement, unsupported-operation,
1317 /// and execution errors are returned unchanged by the implementation.
1318 fn elementwise_read_into(
1319 &mut self,
1320 op: ElementwiseReadOp,
1321 inputs: &[TensorRead<'_>],
1322 out: TensorWrite<'_>,
1323 ) -> crate::Result<()>;
1324
1325 /// Elementwise addition accepting either owned tensors or borrowed views.
1326 ///
1327 /// Backends that implement this method must not silently move data across
1328 /// devices. A backend that cannot consume views should return an explicit
1329 /// backend error rather than materializing or transferring implicitly.
1330 ///
1331 /// # Examples
1332 ///
1333 /// ```rust
1334 /// use tenferro_tensor::{Tensor, TensorElementwise, TensorRead};
1335 ///
1336 /// fn add_owned<B: TensorElementwise>(
1337 /// backend: &mut B,
1338 /// lhs: &Tensor,
1339 /// rhs: &Tensor,
1340 /// ) -> tenferro_tensor::Result<Tensor> {
1341 /// backend.add_read(TensorRead::from_tensor(lhs), TensorRead::from_tensor(rhs))
1342 /// }
1343 /// ```
1344 /// # Errors
1345 ///
1346 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1347 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1348 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1349 /// backend execution or storage access cannot provide the requested result.
1350 fn add_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;
1351
1352 /// Overwrite caller-provided output with elementwise addition.
1353 ///
1354 /// `_into` methods never accumulate into the previous output value.
1355 ///
1356 /// # Examples
1357 ///
1358 /// ```rust
1359 /// use tenferro_tensor::{Tensor, TensorElementwise, TensorWrite};
1360 ///
1361 /// fn add_into<B: TensorElementwise>(
1362 /// backend: &mut B,
1363 /// lhs: &Tensor,
1364 /// rhs: &Tensor,
1365 /// mut out: Tensor,
1366 /// ) -> tenferro_tensor::Result<Tensor> {
1367 /// backend.add_into(lhs, rhs, TensorWrite::from_tensor(&mut out))?;
1368 /// Ok(out)
1369 /// }
1370 /// ```
1371 /// # Errors
1372 ///
1373 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1374 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1375 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1376 /// backend execution or storage access cannot provide the requested result.
1377 fn add_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
1378 self.add_read_into(
1379 TensorRead::from_tensor(lhs),
1380 TensorRead::from_tensor(rhs),
1381 out,
1382 )
1383 }
1384
1385 /// Overwrite caller-provided output with elementwise addition from reads.
1386 ///
1387 /// # Examples
1388 ///
1389 /// ```rust
1390 /// use tenferro_tensor::{TensorElementwise, TensorRead, TensorWrite};
1391 ///
1392 /// fn add_read_into<B: TensorElementwise>(
1393 /// backend: &mut B,
1394 /// lhs: TensorRead<'_>,
1395 /// rhs: TensorRead<'_>,
1396 /// out: TensorWrite<'_>,
1397 /// ) -> tenferro_tensor::Result<()> {
1398 /// backend.add_read_into(lhs, rhs, out)
1399 /// }
1400 /// ```
1401 /// # Errors
1402 ///
1403 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1404 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1405 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1406 /// backend execution or storage access cannot provide the requested result.
1407 fn add_read_into(
1408 &mut self,
1409 lhs: TensorRead<'_>,
1410 rhs: TensorRead<'_>,
1411 out: TensorWrite<'_>,
1412 ) -> crate::Result<()> {
1413 self.elementwise_read_into(ElementwiseReadOp::Add, &[lhs, rhs], out)
1414 }
1415
1416 /// Elementwise subtraction accepting either owned tensors or borrowed views.
1417 ///
1418 /// # Examples
1419 ///
1420 /// ```rust
1421 /// use tenferro_tensor::{Tensor, TensorElementwise, TensorRead};
1422 ///
1423 /// fn sub_owned<B: TensorElementwise>(
1424 /// backend: &mut B,
1425 /// lhs: &Tensor,
1426 /// rhs: &Tensor,
1427 /// ) -> tenferro_tensor::Result<Tensor> {
1428 /// backend.sub_read(TensorRead::from_tensor(lhs), TensorRead::from_tensor(rhs))
1429 /// }
1430 /// ```
1431 /// # Errors
1432 ///
1433 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1434 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1435 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1436 /// backend execution or storage access cannot provide the requested result.
1437 fn sub_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;
1438
1439 /// Overwrite caller-provided output with elementwise subtraction.
1440 /// # Errors
1441 ///
1442 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1443 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1444 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1445 /// backend execution or storage access cannot provide the requested result.
1446 fn sub_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
1447 self.sub_read_into(
1448 TensorRead::from_tensor(lhs),
1449 TensorRead::from_tensor(rhs),
1450 out,
1451 )
1452 }
1453
1454 /// Overwrite caller-provided output with elementwise subtraction from reads.
1455 /// # Errors
1456 ///
1457 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1458 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1459 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1460 /// backend execution or storage access cannot provide the requested result.
1461 fn sub_read_into(
1462 &mut self,
1463 lhs: TensorRead<'_>,
1464 rhs: TensorRead<'_>,
1465 out: TensorWrite<'_>,
1466 ) -> crate::Result<()> {
1467 self.elementwise_read_into(ElementwiseReadOp::Subtract, &[lhs, rhs], out)
1468 }
1469
1470 /// # Examples
1471 ///
1472 /// ```rust
1473 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1474 ///
1475 /// fn mul_read_in_session<B: TensorElementwise>(
1476 /// backend: &mut B,
1477 /// lhs: TensorRead<'_>,
1478 /// rhs: TensorRead<'_>,
1479 /// ) -> tenferro_tensor::Result<Tensor> {
1480 /// backend.mul_read(lhs, rhs)
1481 /// }
1482 /// ```
1483 ///
1484 /// # Errors
1485 ///
1486 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1487 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1488 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1489 /// backend execution or storage access cannot provide the requested result.
1490 fn mul_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;
1491
1492 /// Overwrite caller-provided output with elementwise multiplication.
1493 /// # Errors
1494 ///
1495 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1496 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1497 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1498 /// backend execution or storage access cannot provide the requested result.
1499 fn mul_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
1500 self.mul_read_into(
1501 TensorRead::from_tensor(lhs),
1502 TensorRead::from_tensor(rhs),
1503 out,
1504 )
1505 }
1506
1507 /// Overwrite caller-provided output with elementwise multiplication from reads.
1508 /// # Errors
1509 ///
1510 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1511 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1512 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1513 /// backend execution or storage access cannot provide the requested result.
1514 fn mul_read_into(
1515 &mut self,
1516 lhs: TensorRead<'_>,
1517 rhs: TensorRead<'_>,
1518 out: TensorWrite<'_>,
1519 ) -> crate::Result<()> {
1520 self.elementwise_read_into(ElementwiseReadOp::Multiply, &[lhs, rhs], out)
1521 }
1522
1523 /// # Examples
1524 ///
1525 /// ```rust
1526 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1527 ///
1528 /// fn neg_read_in_session<B: TensorElementwise>(
1529 /// backend: &mut B,
1530 /// input: TensorRead<'_>,
1531 /// ) -> tenferro_tensor::Result<Tensor> {
1532 /// backend.neg_read(input)
1533 /// }
1534 /// ```
1535 ///
1536 /// # Errors
1537 ///
1538 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1539 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1540 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1541 /// backend execution or storage access cannot provide the requested result.
1542 fn neg_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1543
1544 /// Overwrite caller-provided output with elementwise negation.
1545 /// # Errors
1546 ///
1547 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1548 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1549 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1550 /// backend execution or storage access cannot provide the requested result.
1551 fn neg_into(&mut self, input: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
1552 self.neg_read_into(TensorRead::from_tensor(input), out)
1553 }
1554
1555 /// Overwrite caller-provided output with elementwise negation from a read.
1556 /// # Errors
1557 ///
1558 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1559 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1560 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1561 /// backend execution or storage access cannot provide the requested result.
1562 fn neg_read_into(&mut self, input: TensorRead<'_>, out: TensorWrite<'_>) -> crate::Result<()> {
1563 self.elementwise_read_into(ElementwiseReadOp::Negate, &[input], out)
1564 }
1565
1566 /// # Examples
1567 ///
1568 /// ```rust
1569 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1570 ///
1571 /// fn conj_read_in_session<B: TensorElementwise>(
1572 /// backend: &mut B,
1573 /// input: TensorRead<'_>,
1574 /// ) -> tenferro_tensor::Result<Tensor> {
1575 /// backend.conj_read(input)
1576 /// }
1577 /// ```
1578 ///
1579 /// # Errors
1580 ///
1581 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1582 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1583 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1584 /// backend execution or storage access cannot provide the requested result.
1585 fn conj_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1586
1587 /// Overwrite caller-provided output with elementwise conjugation.
1588 /// # Errors
1589 ///
1590 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1591 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1592 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1593 /// backend execution or storage access cannot provide the requested result.
1594 fn conj_into(&mut self, input: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
1595 self.conj_read_into(TensorRead::from_tensor(input), out)
1596 }
1597
1598 /// Overwrite caller-provided output with elementwise conjugation from a read.
1599 /// # Errors
1600 ///
1601 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1602 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1603 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1604 /// backend execution or storage access cannot provide the requested result.
1605 fn conj_read_into(&mut self, input: TensorRead<'_>, out: TensorWrite<'_>) -> crate::Result<()> {
1606 self.elementwise_read_into(ElementwiseReadOp::Conj, &[input], out)
1607 }
1608
1609 /// # Examples
1610 ///
1611 /// ```rust
1612 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1613 ///
1614 /// fn div_read_in_session<B: TensorElementwise>(
1615 /// backend: &mut B,
1616 /// lhs: TensorRead<'_>,
1617 /// rhs: TensorRead<'_>,
1618 /// ) -> tenferro_tensor::Result<Tensor> {
1619 /// backend.div_read(lhs, rhs)
1620 /// }
1621 /// ```
1622 ///
1623 /// # Errors
1624 ///
1625 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1626 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1627 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1628 /// backend execution or storage access cannot provide the requested result.
1629 fn div_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;
1630
1631 /// Overwrite caller-provided output with elementwise division.
1632 /// # Errors
1633 ///
1634 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1635 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1636 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1637 /// backend execution or storage access cannot provide the requested result.
1638 fn div_into(&mut self, lhs: &Tensor, rhs: &Tensor, out: TensorWrite<'_>) -> crate::Result<()> {
1639 self.div_read_into(
1640 TensorRead::from_tensor(lhs),
1641 TensorRead::from_tensor(rhs),
1642 out,
1643 )
1644 }
1645
1646 /// Overwrite caller-provided output with elementwise division from reads.
1647 /// # Errors
1648 ///
1649 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1650 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1651 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1652 /// backend execution or storage access cannot provide the requested result.
1653 fn div_read_into(
1654 &mut self,
1655 lhs: TensorRead<'_>,
1656 rhs: TensorRead<'_>,
1657 out: TensorWrite<'_>,
1658 ) -> crate::Result<()> {
1659 self.elementwise_read_into(ElementwiseReadOp::Divide, &[lhs, rhs], out)
1660 }
1661
1662 /// Elementwise remainder.
1663 ///
1664 /// The default is an explicit unsupported error so backend implementors can
1665 /// opt in without silent fallback.
1666 ///
1667 /// # Examples
1668 ///
1669 /// ```rust
1670 /// use tenferro_tensor::{Tensor, TensorElementwise};
1671 ///
1672 /// fn rem_owned<B: TensorElementwise>(
1673 /// backend: &mut B,
1674 /// lhs: &Tensor,
1675 /// rhs: &Tensor,
1676 /// ) -> tenferro_tensor::Result<Tensor> {
1677 /// backend.rem(lhs, rhs)
1678 /// }
1679 /// ```
1680 /// # Errors
1681 ///
1682 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1683 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1684 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1685 /// backend execution or storage access cannot provide the requested result.
1686 fn rem(&mut self, lhs: &Tensor, _rhs: &Tensor) -> crate::Result<Tensor> {
1687 Err(crate::Error::unsupported(
1688 "rem",
1689 format!("backend does not implement rem for dtype {:?}", lhs.dtype()),
1690 ))
1691 }
1692
1693 /// Elementwise remainder accepting owned tensors or borrowed views.
1694 ///
1695 /// # Examples
1696 ///
1697 /// ```rust
1698 /// use tenferro_tensor::{Tensor, TensorElementwise, TensorRead};
1699 ///
1700 /// fn rem_read<B: TensorElementwise>(
1701 /// backend: &mut B,
1702 /// lhs: &Tensor,
1703 /// rhs: &Tensor,
1704 /// ) -> tenferro_tensor::Result<Tensor> {
1705 /// backend.rem_read(TensorRead::from_tensor(lhs), TensorRead::from_tensor(rhs))
1706 /// }
1707 /// ```
1708 /// # Errors
1709 ///
1710 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1711 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1712 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1713 /// backend execution or storage access cannot provide the requested result.
1714 fn rem_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor> {
1715 self.rem(read_tensor("rem", lhs)?, read_tensor("rem", rhs)?)
1716 }
1717
1718 /// # Examples
1719 ///
1720 /// ```rust
1721 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1722 ///
1723 /// fn abs_read_in_session<B: TensorElementwise>(
1724 /// backend: &mut B,
1725 /// input: TensorRead<'_>,
1726 /// ) -> tenferro_tensor::Result<Tensor> {
1727 /// backend.abs_read(input)
1728 /// }
1729 /// ```
1730 ///
1731 /// # Errors
1732 ///
1733 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1734 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1735 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1736 /// backend execution or storage access cannot provide the requested result.
1737 fn abs_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1738
1739 /// # Examples
1740 ///
1741 /// ```rust
1742 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1743 ///
1744 /// fn sign_read_in_session<B: TensorElementwise>(
1745 /// backend: &mut B,
1746 /// input: TensorRead<'_>,
1747 /// ) -> tenferro_tensor::Result<Tensor> {
1748 /// backend.sign_read(input)
1749 /// }
1750 /// ```
1751 ///
1752 /// # Errors
1753 ///
1754 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1755 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1756 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1757 /// backend execution or storage access cannot provide the requested result.
1758 fn sign_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1759
1760 /// # Examples
1761 ///
1762 /// ```rust
1763 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1764 ///
1765 /// fn maximum_read_in_session<B: TensorElementwise>(
1766 /// backend: &mut B,
1767 /// lhs: TensorRead<'_>,
1768 /// rhs: TensorRead<'_>,
1769 /// ) -> tenferro_tensor::Result<Tensor> {
1770 /// backend.maximum_read(lhs, rhs)
1771 /// }
1772 /// ```
1773 ///
1774 /// # Errors
1775 ///
1776 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1777 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1778 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1779 /// backend execution or storage access cannot provide the requested result.
1780 fn maximum_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;
1781
1782 /// # Examples
1783 ///
1784 /// ```rust
1785 /// use tenferro_tensor::{TensorElementwise, Tensor, TensorRead};
1786 ///
1787 /// fn minimum_read_in_session<B: TensorElementwise>(
1788 /// backend: &mut B,
1789 /// lhs: TensorRead<'_>,
1790 /// rhs: TensorRead<'_>,
1791 /// ) -> tenferro_tensor::Result<Tensor> {
1792 /// backend.minimum_read(lhs, rhs)
1793 /// }
1794 /// ```
1795 ///
1796 /// # Errors
1797 ///
1798 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1799 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1800 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1801 /// backend execution or storage access cannot provide the requested result.
1802 fn minimum_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;
1803
1804 /// # Errors
1805 ///
1806 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1807 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1808 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1809 /// backend execution or storage access cannot provide the requested result.
1810 fn compare_read(
1811 &mut self,
1812 lhs: TensorRead<'_>,
1813 rhs: TensorRead<'_>,
1814 dir: &CompareDir,
1815 ) -> crate::Result<Tensor>;
1816
1817 /// # Errors
1818 ///
1819 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1820 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1821 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1822 /// backend execution or storage access cannot provide the requested result.
1823 fn select_read(
1824 &mut self,
1825 pred: TensorRead<'_>,
1826 on_true: TensorRead<'_>,
1827 on_false: TensorRead<'_>,
1828 ) -> crate::Result<Tensor>;
1829
1830 /// # Errors
1831 ///
1832 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1833 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1834 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1835 /// backend execution or storage access cannot provide the requested result.
1836 fn clamp_read(
1837 &mut self,
1838 input: TensorRead<'_>,
1839 lower: TensorRead<'_>,
1840 upper: TensorRead<'_>,
1841 ) -> crate::Result<Tensor>;
1842}
1843
1844/// Analytic unary and binary tensor operations.
1845///
1846/// # Examples
1847///
1848/// ```rust
1849/// use tenferro_tensor::TensorAnalytic;
1850///
1851/// fn accepts_analytic<B: TensorAnalytic>(_backend: &mut B) {}
1852/// ```
1853pub trait TensorAnalytic {
1854 /// # Examples
1855 ///
1856 /// ```rust
1857 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
1858 ///
1859 /// fn exp_read_in_session<B: TensorAnalytic>(
1860 /// backend: &mut B,
1861 /// input: TensorRead<'_>,
1862 /// ) -> tenferro_tensor::Result<Tensor> {
1863 /// backend.exp_read(input)
1864 /// }
1865 /// ```
1866 ///
1867 /// # Errors
1868 ///
1869 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1870 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1871 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1872 /// backend execution or storage access cannot provide the requested result.
1873 fn exp_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1874
1875 /// # Examples
1876 ///
1877 /// ```rust
1878 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
1879 ///
1880 /// fn log_read_in_session<B: TensorAnalytic>(
1881 /// backend: &mut B,
1882 /// input: TensorRead<'_>,
1883 /// ) -> tenferro_tensor::Result<Tensor> {
1884 /// backend.log_read(input)
1885 /// }
1886 /// ```
1887 ///
1888 /// # Errors
1889 ///
1890 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1891 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1892 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1893 /// backend execution or storage access cannot provide the requested result.
1894 fn log_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1895
1896 /// # Examples
1897 ///
1898 /// ```rust
1899 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
1900 ///
1901 /// fn sin_read_in_session<B: TensorAnalytic>(
1902 /// backend: &mut B,
1903 /// input: TensorRead<'_>,
1904 /// ) -> tenferro_tensor::Result<Tensor> {
1905 /// backend.sin_read(input)
1906 /// }
1907 /// ```
1908 ///
1909 /// # Errors
1910 ///
1911 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1912 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1913 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1914 /// backend execution or storage access cannot provide the requested result.
1915 fn sin_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1916
1917 /// # Examples
1918 ///
1919 /// ```rust
1920 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
1921 ///
1922 /// fn cos_read_in_session<B: TensorAnalytic>(
1923 /// backend: &mut B,
1924 /// input: TensorRead<'_>,
1925 /// ) -> tenferro_tensor::Result<Tensor> {
1926 /// backend.cos_read(input)
1927 /// }
1928 /// ```
1929 ///
1930 /// # Errors
1931 ///
1932 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1933 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1934 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1935 /// backend execution or storage access cannot provide the requested result.
1936 fn cos_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1937
1938 /// # Examples
1939 ///
1940 /// ```rust
1941 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
1942 ///
1943 /// fn tanh_read_in_session<B: TensorAnalytic>(
1944 /// backend: &mut B,
1945 /// input: TensorRead<'_>,
1946 /// ) -> tenferro_tensor::Result<Tensor> {
1947 /// backend.tanh_read(input)
1948 /// }
1949 /// ```
1950 ///
1951 /// # Errors
1952 ///
1953 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1954 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1955 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1956 /// backend execution or storage access cannot provide the requested result.
1957 fn tanh_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1958
1959 /// # Examples
1960 ///
1961 /// ```rust
1962 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
1963 ///
1964 /// fn sqrt_read_in_session<B: TensorAnalytic>(
1965 /// backend: &mut B,
1966 /// input: TensorRead<'_>,
1967 /// ) -> tenferro_tensor::Result<Tensor> {
1968 /// backend.sqrt_read(input)
1969 /// }
1970 /// ```
1971 ///
1972 /// # Errors
1973 ///
1974 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1975 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1976 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1977 /// backend execution or storage access cannot provide the requested result.
1978 fn sqrt_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
1979
1980 /// # Examples
1981 ///
1982 /// ```rust
1983 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
1984 ///
1985 /// fn rsqrt_read_in_session<B: TensorAnalytic>(
1986 /// backend: &mut B,
1987 /// input: TensorRead<'_>,
1988 /// ) -> tenferro_tensor::Result<Tensor> {
1989 /// backend.rsqrt_read(input)
1990 /// }
1991 /// ```
1992 ///
1993 /// # Errors
1994 ///
1995 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
1996 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
1997 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
1998 /// backend execution or storage access cannot provide the requested result.
1999 fn rsqrt_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
2000
2001 /// # Examples
2002 ///
2003 /// ```rust
2004 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
2005 ///
2006 /// fn pow_read_in_session<B: TensorAnalytic>(
2007 /// backend: &mut B,
2008 /// lhs: TensorRead<'_>,
2009 /// rhs: TensorRead<'_>,
2010 /// ) -> tenferro_tensor::Result<Tensor> {
2011 /// backend.pow_read(lhs, rhs)
2012 /// }
2013 /// ```
2014 ///
2015 /// # Errors
2016 ///
2017 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2018 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2019 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2020 /// backend execution or storage access cannot provide the requested result.
2021 fn pow_read(&mut self, lhs: TensorRead<'_>, rhs: TensorRead<'_>) -> crate::Result<Tensor>;
2022
2023 /// # Examples
2024 ///
2025 /// ```rust
2026 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
2027 ///
2028 /// fn expm1_read_in_session<B: TensorAnalytic>(
2029 /// backend: &mut B,
2030 /// input: TensorRead<'_>,
2031 /// ) -> tenferro_tensor::Result<Tensor> {
2032 /// backend.expm1_read(input)
2033 /// }
2034 /// ```
2035 ///
2036 /// # Errors
2037 ///
2038 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2039 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2040 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2041 /// backend execution or storage access cannot provide the requested result.
2042 fn expm1_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
2043
2044 /// # Examples
2045 ///
2046 /// ```rust
2047 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
2048 ///
2049 /// fn log1p_read_in_session<B: TensorAnalytic>(
2050 /// backend: &mut B,
2051 /// input: TensorRead<'_>,
2052 /// ) -> tenferro_tensor::Result<Tensor> {
2053 /// backend.log1p_read(input)
2054 /// }
2055 /// ```
2056 ///
2057 /// # Errors
2058 ///
2059 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2060 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2061 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2062 /// backend execution or storage access cannot provide the requested result.
2063 fn log1p_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
2064
2065 /// Elementwise error function `erf(x) = 2/sqrt(pi) * integral_0^x exp(-t^2) dt`.
2066 ///
2067 /// Defined for real `F32` and `F64` input only; the result has the input
2068 /// dtype and shape. `erf(+-0) = +-0`, `erf(+-inf) = +-1`, and `NaN` stays
2069 /// `NaN`.
2070 ///
2071 /// # Examples
2072 ///
2073 /// ```rust
2074 /// use tenferro_tensor::{TensorAnalytic, Tensor, TensorRead};
2075 ///
2076 /// fn erf_read_in_session<B: TensorAnalytic>(
2077 /// backend: &mut B,
2078 /// input: TensorRead<'_>,
2079 /// ) -> tenferro_tensor::Result<Tensor> {
2080 /// backend.erf_read(input)
2081 /// }
2082 /// ```
2083 ///
2084 /// # Errors
2085 ///
2086 /// Returns [`crate::Error::UnsupportedDType`] for a complex, integer, or `Bool`
2087 /// input dtype, [`crate::Error::Validation`] with a typed `ValidationError`
2088 /// source for invalid shapes or output metadata, and
2089 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2090 /// backend execution or storage access cannot provide the requested result.
2091 fn erf_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor>;
2092}
2093
2094/// Shape, layout, and dtype transformation operations.
2095///
2096/// # Examples
2097///
2098/// ```rust
2099/// use tenferro_tensor::TensorStructural;
2100///
2101/// fn accepts_structural<B: TensorStructural>(_backend: &mut B) {}
2102/// ```
2103pub trait TensorStructural {
2104 /// Materialize an owned tensor or borrowed view into fresh compact storage.
2105 ///
2106 /// The result has the input's shape and dtype, uses compact column-major
2107 /// layout, and remains in the input's placement. This operation is a
2108 /// same-placement canonicalization boundary, never an implicit host/device
2109 /// transfer. The conservative default accepts host-owned tensors and host
2110 /// views; a view is gathered over its layout, so transposed, sliced, and
2111 /// negative-stride views materialize. It rejects backend buffers and device
2112 /// placement because only an owning backend can materialize those safely.
2113 ///
2114 /// Backend overrides may also accept backend-owned strided views. CUDA
2115 /// accepts numeric and complex views on its active device, including
2116 /// arbitrary valid strides; for `Bool` it copies owned tensors but
2117 /// reports an explicit unsupported-dtype error for strided views.
2118 ///
2119 /// # Examples
2120 ///
2121 /// ```rust
2122 /// use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural};
2123 ///
2124 /// struct HostDefaults;
2125 /// impl TensorStructural for HostDefaults {
2126 /// fn transpose_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2127 /// fn reshape_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2128 /// fn broadcast_in_dim_read(&mut self, _: TensorRead<'_>, _: &[usize], _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2129 /// fn cast(&mut self, _: &Tensor, _: DType) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2130 /// fn extract_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2131 /// fn embed_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2132 /// fn tril(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2133 /// fn triu(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2134 /// }
2135 ///
2136 /// let input = Tensor::from_vec_col_major(vec![2], vec![1_i32, 2])?;
2137 /// let mut backend = HostDefaults;
2138 /// let structural: &mut dyn TensorStructural = &mut backend;
2139 /// let output = structural.to_contiguous_read(TensorRead::from_tensor(&input))?;
2140 /// assert_eq!(output.shape(), &[2]);
2141 /// assert_eq!(output.as_slice::<i32>()?, &[1, 2]);
2142 /// # Ok::<(), tenferro_tensor::Error>(())
2143 /// ```
2144 /// # Errors
2145 ///
2146 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2147 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2148 /// [`crate::Error::RuntimeState`] for backend-owned or device-placed input,
2149 /// which only the owning backend can materialize, or
2150 /// [`crate::Error::BackendFailure`] / [`crate::Error::BackendSource`] when
2151 /// backend execution or storage access cannot provide the requested result.
2152 fn to_contiguous_read(&mut self, input: TensorRead<'_>) -> crate::Result<Tensor> {
2153 match input {
2154 TensorRead::Tensor(input) => {
2155 if input.is_backend_buffer()
2156 || !matches!(
2157 input.placement().memory_kind,
2158 crate::MemoryKind::PinnedHost | crate::MemoryKind::UnpinnedHost
2159 )
2160 {
2161 return Err(crate::Error::runtime_state(
2162 "to_contiguous_read",
2163 "default materialization accepts only host-owned tensors; use the storage's owning backend",
2164 ));
2165 }
2166 input.duplicate()
2167 }
2168 TensorRead::View(view) => {
2169 if view.backend_family().is_some()
2170 || !matches!(
2171 view.placement().memory_kind,
2172 crate::MemoryKind::PinnedHost | crate::MemoryKind::UnpinnedHost
2173 )
2174 {
2175 return Err(crate::Error::runtime_state(
2176 "to_contiguous_read",
2177 "default materialization accepts only host-owned tensors; use the storage's owning backend",
2178 ));
2179 }
2180 default_materialize_host_view(view)
2181 }
2182 }
2183 }
2184
2185 /// Overwrite caller-provided storage from a readable tensor or view.
2186 ///
2187 /// Source and destination must have identical dtype and shape and belong to
2188 /// the executing backend's placement. The destination is not resized, and
2189 /// every logical destination element is overwritten without reading its old
2190 /// value. Source and destination allocations must not alias. Implementations
2191 /// must not materialize through host memory or perform an implicit transfer.
2192 ///
2193 /// CPU and CUDA accept arbitrary valid source and destination strides: the
2194 /// source is read where it lives and a destination region is written in
2195 /// place, so neither side is copied. CUDA stages only a source view wider
2196 /// than its catalogue's by-value layout rank, through one compact copy. A
2197 /// destination *view* wider than that rank is a typed refusal there, while
2198 /// an owned destination of the same rank is served. The conservative
2199 /// default is explicitly unsupported.
2200 ///
2201 /// # Examples
2202 ///
2203 /// ```rust
2204 /// use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural, TensorWrite};
2205 ///
2206 /// struct ConservativeDefaults;
2207 /// impl TensorStructural for ConservativeDefaults {
2208 /// fn transpose_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2209 /// fn reshape_read(&mut self, _: TensorRead<'_>, _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2210 /// fn broadcast_in_dim_read(&mut self, _: TensorRead<'_>, _: &[usize], _: &[usize]) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2211 /// fn cast(&mut self, _: &Tensor, _: DType) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2212 /// fn extract_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2213 /// fn embed_diagonal(&mut self, _: &Tensor, _: usize, _: usize) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2214 /// fn tril(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2215 /// fn triu(&mut self, _: &Tensor, _: i64) -> tenferro_tensor::Result<Tensor> { unimplemented!() }
2216 /// }
2217 ///
2218 /// let src = Tensor::from_vec_col_major(vec![2], vec![1_i32, 2])?;
2219 /// let mut dst = Tensor::from_vec_col_major(vec![2], vec![0_i32, 0])?;
2220 /// let mut backend = ConservativeDefaults;
2221 /// let structural: &mut dyn TensorStructural = &mut backend;
2222 /// let error = structural.copy_read_into(
2223 /// TensorRead::from_tensor(&src),
2224 /// TensorWrite::from_tensor(&mut dst),
2225 /// ).unwrap_err();
2226 /// assert!(error.to_string().contains("unsupported"));
2227 /// assert_eq!(dst.as_slice::<i32>()?, &[0, 0]);
2228 /// # Ok::<(), tenferro_tensor::Error>(())
2229 /// ```
2230 /// # Errors
2231 ///
2232 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2233 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2234 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2235 /// backend execution or storage access cannot provide the requested result.
2236 fn copy_read_into(&mut self, _src: TensorRead<'_>, _dst: TensorWrite<'_>) -> crate::Result<()> {
2237 Err(crate::Error::unsupported(
2238 "copy_read_into",
2239 "backend-owned runtime copy is unsupported by this backend",
2240 ))
2241 }
2242
2243 /// # Examples
2244 ///
2245 /// ```rust
2246 /// use tenferro_tensor::{TensorStructural, Tensor, TensorRead};
2247 ///
2248 /// fn transpose_read_in_session<B: TensorStructural>(
2249 /// backend: &mut B,
2250 /// input: TensorRead<'_>,
2251 /// perm: &[usize],
2252 /// ) -> tenferro_tensor::Result<Tensor> {
2253 /// backend.transpose_read(input, perm)
2254 /// }
2255 /// ```
2256 ///
2257 /// # Errors
2258 ///
2259 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2260 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2261 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2262 /// backend execution or storage access cannot provide the requested result.
2263 fn transpose_read(&mut self, input: TensorRead<'_>, perm: &[usize]) -> crate::Result<Tensor>;
2264
2265 /// # Examples
2266 ///
2267 /// ```rust
2268 /// use tenferro_tensor::{TensorStructural, Tensor, TensorRead};
2269 ///
2270 /// fn reshape_read_in_session<B: TensorStructural>(
2271 /// backend: &mut B,
2272 /// input: TensorRead<'_>,
2273 /// shape: &[usize],
2274 /// ) -> tenferro_tensor::Result<Tensor> {
2275 /// backend.reshape_read(input, shape)
2276 /// }
2277 /// ```
2278 ///
2279 /// # Errors
2280 ///
2281 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2282 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2283 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2284 /// backend execution or storage access cannot provide the requested result.
2285 fn reshape_read(&mut self, input: TensorRead<'_>, shape: &[usize]) -> crate::Result<Tensor>;
2286
2287 /// # Errors
2288 ///
2289 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2290 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2291 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2292 /// backend execution or storage access cannot provide the requested result.
2293 fn broadcast_in_dim_read(
2294 &mut self,
2295 input: TensorRead<'_>,
2296 shape: &[usize],
2297 dims: &[usize],
2298 ) -> crate::Result<Tensor>;
2299
2300 /// Cast a tensor to another dtype using explicit dtype projection.
2301 ///
2302 /// Backends may truncate, narrow precision, project complex values, or use
2303 /// boolean truthiness according to their documented cast support.
2304 ///
2305 /// # Examples
2306 ///
2307 /// ```rust
2308 /// use tenferro_tensor::{DType, Tensor, TensorStructural};
2309 ///
2310 /// fn cast_to_i32<B: TensorStructural>(
2311 /// backend: &mut B,
2312 /// input: &Tensor,
2313 /// ) -> tenferro_tensor::Result<Tensor> {
2314 /// backend.cast(input, DType::I32)
2315 /// }
2316 /// ```
2317 /// # Errors
2318 ///
2319 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2320 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2321 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2322 /// backend execution or storage access cannot provide the requested result.
2323 fn cast(&mut self, input: &Tensor, to: crate::DType) -> crate::Result<Tensor>;
2324
2325 /// Convert a tensor to another dtype using checked dtype conversion.
2326 ///
2327 /// `convert` accepts only conversions allowed by tenferro's dtype-promotion
2328 /// lattice. Use [`TensorStructural::cast`] for explicit lossy projection.
2329 ///
2330 /// # Examples
2331 ///
2332 /// ```rust
2333 /// use tenferro_tensor::{DType, Tensor, TensorStructural};
2334 ///
2335 /// fn convert_to_f64<B: TensorStructural>(
2336 /// backend: &mut B,
2337 /// input: &Tensor,
2338 /// ) -> tenferro_tensor::Result<Tensor> {
2339 /// backend.convert(input, DType::F64)
2340 /// }
2341 /// ```
2342 /// # Errors
2343 ///
2344 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2345 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2346 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2347 /// backend execution or storage access cannot provide the requested result.
2348 fn convert(&mut self, input: &Tensor, to: crate::DType) -> crate::Result<Tensor> {
2349 validate_convert_dtype("convert", input.dtype(), to)?;
2350 self.cast(input, to)
2351 }
2352
2353 /// Cast the read's logical elements to another dtype using explicit dtype projection.
2354 ///
2355 /// This is the read form of [`TensorStructural::cast`]: a backend that can address a
2356 /// borrowed operand's own layout should override it so a view is not staged. The
2357 /// default stages each borrowed view into compact storage (an owned tensor is passed
2358 /// through) and delegates to the owned-input method (#2223).
2359 ///
2360 /// # Examples
2361 ///
2362 /// ```rust
2363 /// use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural};
2364 ///
2365 /// fn cast_read_to_i32<B: TensorStructural>(
2366 /// backend: &mut B,
2367 /// input: TensorRead<'_>,
2368 /// ) -> tenferro_tensor::Result<Tensor> {
2369 /// backend.cast_read(input, DType::I32)
2370 /// }
2371 /// ```
2372 /// # Errors
2373 ///
2374 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2375 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2376 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2377 /// backend execution or storage access cannot provide the requested result.
2378 fn cast_read(&mut self, input: TensorRead<'_>, to: crate::DType) -> crate::Result<Tensor> {
2379 // shortcut: the staging default goes away with the owned `cast` in #2223 PR 3.
2380 let input = stage_view(self, input)?;
2381 self.cast(&input, to)
2382 }
2383
2384 /// Convert the read's logical elements using checked dtype conversion.
2385 ///
2386 /// `convert_read` accepts only conversions allowed by tenferro's dtype-promotion
2387 /// lattice; the check runs before any backend work. Use
2388 /// [`TensorStructural::cast_read`] for explicit lossy projection. This is a
2389 /// provided method, not a backend hook: a backend implements `cast_read`.
2390 ///
2391 /// # Examples
2392 ///
2393 /// ```rust
2394 /// use tenferro_tensor::{DType, Tensor, TensorRead, TensorStructural};
2395 ///
2396 /// fn convert_read_to_f64<B: TensorStructural>(
2397 /// backend: &mut B,
2398 /// input: TensorRead<'_>,
2399 /// ) -> tenferro_tensor::Result<Tensor> {
2400 /// backend.convert_read(input, DType::F64)
2401 /// }
2402 /// ```
2403 /// # Errors
2404 ///
2405 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2406 /// when the requested conversion is outside the checked dtype-promotion lattice,
2407 /// and the same errors [`TensorStructural::cast_read`] reports.
2408 fn convert_read(&mut self, input: TensorRead<'_>, to: crate::DType) -> crate::Result<Tensor> {
2409 validate_convert_dtype("convert", input.dtype(), to)?;
2410 self.cast_read(input, to)
2411 }
2412
2413 /// # Errors
2414 ///
2415 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2416 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2417 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2418 /// backend execution or storage access cannot provide the requested result.
2419 fn extract_diagonal(
2420 &mut self,
2421 input: &Tensor,
2422 axis_a: usize,
2423 axis_b: usize,
2424 ) -> crate::Result<Tensor>;
2425 /// Extract the diagonal with the input taken as a read.
2426 ///
2427 /// The default stages each borrowed view into compact storage (an owned
2428 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
2429 /// should override this so a view is not copied (#2214).
2430 ///
2431 /// # Examples
2432 ///
2433 /// ```rust
2434 /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
2435 ///
2436 /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
2437 /// -> tenferro_tensor::Result<Tensor>
2438 /// {
2439 /// session.extract_diagonal_read(x, 0, 1)
2440 /// }
2441 /// ```
2442 ///
2443 /// # Errors
2444 ///
2445 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2446 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2447 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2448 /// backend execution or storage access cannot provide the requested result.
2449 fn extract_diagonal_read(
2450 &mut self,
2451 input: TensorRead<'_>,
2452 axis_a: usize,
2453 axis_b: usize,
2454 ) -> crate::Result<Tensor> {
2455 let input = stage_view(self, input)?;
2456 self.extract_diagonal(&input, axis_a, axis_b)
2457 }
2458
2459 /// # Errors
2460 ///
2461 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2462 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2463 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2464 /// backend execution or storage access cannot provide the requested result.
2465 fn embed_diagonal(
2466 &mut self,
2467 input: &Tensor,
2468 axis_a: usize,
2469 axis_b: usize,
2470 ) -> crate::Result<Tensor>;
2471 /// Embed the input as a diagonal with the input taken as a read.
2472 ///
2473 /// The default stages each borrowed view into compact storage (an owned
2474 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
2475 /// should override this so a view is not copied (#2214).
2476 ///
2477 /// # Examples
2478 ///
2479 /// ```rust
2480 /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
2481 ///
2482 /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
2483 /// -> tenferro_tensor::Result<Tensor>
2484 /// {
2485 /// session.embed_diagonal_read(x, 0, 1)
2486 /// }
2487 /// ```
2488 ///
2489 /// # Errors
2490 ///
2491 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2492 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2493 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2494 /// backend execution or storage access cannot provide the requested result.
2495 fn embed_diagonal_read(
2496 &mut self,
2497 input: TensorRead<'_>,
2498 axis_a: usize,
2499 axis_b: usize,
2500 ) -> crate::Result<Tensor> {
2501 let input = stage_view(self, input)?;
2502 self.embed_diagonal(&input, axis_a, axis_b)
2503 }
2504
2505 /// # Errors
2506 ///
2507 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2508 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2509 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2510 /// backend execution or storage access cannot provide the requested result.
2511 fn tril(&mut self, input: &Tensor, k: i64) -> crate::Result<Tensor>;
2512 /// Lower-triangular mask with the input taken as a read.
2513 ///
2514 /// The default stages each borrowed view into compact storage (an owned
2515 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
2516 /// should override this so a view is not copied (#2214).
2517 ///
2518 /// # Examples
2519 ///
2520 /// ```rust
2521 /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
2522 ///
2523 /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
2524 /// -> tenferro_tensor::Result<Tensor>
2525 /// {
2526 /// session.tril_read(x, 0)
2527 /// }
2528 /// ```
2529 ///
2530 /// # Errors
2531 ///
2532 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2533 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2534 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2535 /// backend execution or storage access cannot provide the requested result.
2536 fn tril_read(&mut self, input: TensorRead<'_>, k: i64) -> crate::Result<Tensor> {
2537 let input = stage_view(self, input)?;
2538 self.tril(&input, k)
2539 }
2540
2541 /// # Errors
2542 ///
2543 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2544 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2545 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2546 /// backend execution or storage access cannot provide the requested result.
2547 fn triu(&mut self, input: &Tensor, k: i64) -> crate::Result<Tensor>;
2548 /// Upper-triangular mask with the input taken as a read.
2549 ///
2550 /// The default stages each borrowed view into compact storage (an owned
2551 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
2552 /// should override this so a view is not copied (#2214).
2553 ///
2554 /// # Examples
2555 ///
2556 /// ```rust
2557 /// use tenferro_tensor::{Tensor, TensorStructural, TensorRead};
2558 ///
2559 /// fn run(session: &mut dyn TensorStructural, x: TensorRead<'_>)
2560 /// -> tenferro_tensor::Result<Tensor>
2561 /// {
2562 /// session.triu_read(x, 0)
2563 /// }
2564 /// ```
2565 ///
2566 /// # Errors
2567 ///
2568 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2569 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2570 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2571 /// backend execution or storage access cannot provide the requested result.
2572 fn triu_read(&mut self, input: TensorRead<'_>, k: i64) -> crate::Result<Tensor> {
2573 let input = stage_view(self, input)?;
2574 self.triu(&input, k)
2575 }
2576}
2577
2578/// Reduction operations.
2579///
2580/// Reducing over an axis whose extent is zero returns an error for every
2581/// reduction operation. Passing an empty `axes` slice is a no-op for the public
2582/// reductions and returns the input values unchanged. Internal mapped
2583/// reductions document their own empty-axis semantics.
2584///
2585/// # Examples
2586///
2587/// ```rust
2588/// use tenferro_tensor::TensorReduction;
2589///
2590/// fn accepts_reduction<B: TensorReduction>(_backend: &mut B) {}
2591/// ```
2592pub trait TensorReduction {
2593 /// Sum elements across axes from an owned tensor or borrowed view.
2594 ///
2595 /// # Examples
2596 ///
2597 /// ```rust
2598 /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
2599 ///
2600 /// fn sum_owned<B: TensorReduction>(
2601 /// backend: &mut B,
2602 /// input: &Tensor,
2603 /// ) -> tenferro_tensor::Result<Tensor> {
2604 /// backend.reduce_sum_read(TensorRead::from_tensor(input), &[0])
2605 /// }
2606 /// ```
2607 /// # Errors
2608 ///
2609 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2610 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2611 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2612 /// backend execution or storage access cannot provide the requested result.
2613 fn reduce_sum_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;
2614
2615 /// Sum elementwise squares across axes.
2616 ///
2617 /// This execution hook is used by composite operations that avoid a
2618 /// materialized square. Empty axes produce an elementwise square. Backends
2619 /// that support this optimized path must override the hook directly.
2620 ///
2621 /// # Errors
2622 ///
2623 /// Returns the typed validation, unsupported, runtime-state, or backend
2624 /// error produced by multiplication or reduction.
2625 #[doc(hidden)]
2626 fn reduce_sum_squares_read(
2627 &mut self,
2628 _input: TensorRead<'_>,
2629 _axes: &[usize],
2630 ) -> crate::Result<Tensor> {
2631 Err(crate::Error::unsupported(
2632 "reduce_sum_squares",
2633 "backend does not implement fused sum-of-squares reduction",
2634 ))
2635 }
2636
2637 /// Multiply elements across axes from an owned tensor or borrowed view.
2638 ///
2639 /// # Overflow policy
2640 ///
2641 /// Backends may reassociate a floating-point or complex product across
2642 /// lanes, chunks and threads, and the CPU and CUDA kernels do so
2643 /// differently. Rounding and range behaviour therefore depend on the
2644 /// backend, the layout and the thread count: a partial product can overflow
2645 /// to `inf` or underflow to `0`, and combining the partials can then give
2646 /// `inf`, `0` or `NaN` even where the sequential product is representable.
2647 /// The `#2150` alternating `2.0, 0.5` axis is one example: an `f32`
2648 /// sequential product is exactly `1.0`, while a reassociated one may return
2649 /// `NaN`. This is the same trade-off `torch.prod` makes. Integer products
2650 /// are exact and wrap on overflow.
2651 ///
2652 /// # Examples
2653 ///
2654 /// ```rust
2655 /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
2656 ///
2657 /// fn prod_owned<B: TensorReduction>(
2658 /// backend: &mut B,
2659 /// input: &Tensor,
2660 /// ) -> tenferro_tensor::Result<Tensor> {
2661 /// backend.reduce_prod_read(TensorRead::from_tensor(input), &[0])
2662 /// }
2663 /// ```
2664 /// # Errors
2665 ///
2666 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2667 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2668 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2669 /// backend execution or storage access cannot provide the requested result.
2670 fn reduce_prod_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;
2671
2672 /// Take maximum values across axes from an owned tensor or borrowed view.
2673 ///
2674 /// # Examples
2675 ///
2676 /// ```rust
2677 /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
2678 ///
2679 /// fn max_owned<B: TensorReduction>(
2680 /// backend: &mut B,
2681 /// input: &Tensor,
2682 /// ) -> tenferro_tensor::Result<Tensor> {
2683 /// backend.reduce_max_read(TensorRead::from_tensor(input), &[0])
2684 /// }
2685 /// ```
2686 /// # Errors
2687 ///
2688 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2689 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2690 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2691 /// backend execution or storage access cannot provide the requested result.
2692 fn reduce_max_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;
2693
2694 /// Take minimum values across axes from an owned tensor or borrowed view.
2695 ///
2696 /// # Examples
2697 ///
2698 /// ```rust
2699 /// use tenferro_tensor::{Tensor, TensorRead, TensorReduction};
2700 ///
2701 /// fn min_owned<B: TensorReduction>(
2702 /// backend: &mut B,
2703 /// input: &Tensor,
2704 /// ) -> tenferro_tensor::Result<Tensor> {
2705 /// backend.reduce_min_read(TensorRead::from_tensor(input), &[0])
2706 /// }
2707 /// ```
2708 /// # Errors
2709 ///
2710 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2711 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2712 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2713 /// backend execution or storage access cannot provide the requested result.
2714 fn reduce_min_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor>;
2715}
2716
2717/// Dot-general operations.
2718///
2719/// # Examples
2720///
2721/// ```rust
2722/// use tenferro_tensor::TensorDot;
2723///
2724/// fn accepts_dot<B: TensorDot>(_backend: &mut B) {}
2725/// ```
2726pub trait TensorDot: TensorElementwise {
2727 #[doc(hidden)]
2728 fn dot_general_read(
2729 &mut self,
2730 lhs: TensorRead<'_>,
2731 rhs: TensorRead<'_>,
2732 config: &DotGeneralConfig,
2733 ) -> crate::Result<Tensor>;
2734
2735 /// Overwrite caller-provided output with dot-general from read inputs.
2736 ///
2737 /// This is the dot/GEMM spelling of `_into`: the previous output value is
2738 /// not read. Use [`TensorDot::dot_general_read_into_accum`] for explicit
2739 /// read-modify-write accumulation.
2740 ///
2741 /// # Examples
2742 ///
2743 /// ```rust
2744 /// use tenferro_tensor::{DotGeneralConfig, TensorDot, TensorRead, TensorWrite};
2745 ///
2746 /// fn dot_into<B: TensorDot>(
2747 /// backend: &mut B,
2748 /// lhs: TensorRead<'_>,
2749 /// rhs: TensorRead<'_>,
2750 /// config: &DotGeneralConfig,
2751 /// out: TensorWrite<'_>,
2752 /// ) -> tenferro_tensor::Result<()> {
2753 /// backend.dot_general_read_into(lhs, rhs, config, out)
2754 /// }
2755 /// ```
2756 /// # Errors
2757 ///
2758 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2759 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2760 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2761 /// backend execution or storage access cannot provide the requested result.
2762 fn dot_general_read_into(
2763 &mut self,
2764 lhs: TensorRead<'_>,
2765 rhs: TensorRead<'_>,
2766 config: &DotGeneralConfig,
2767 out: TensorWrite<'_>,
2768 ) -> crate::Result<()> {
2769 let accumulation = DotGeneralAccumulation::overwrite(lhs.dtype())?;
2770 self.dot_general_read_into_accum(lhs, rhs, config, accumulation, out)
2771 }
2772
2773 #[doc(hidden)]
2774 fn dot_general_with_conj(
2775 &mut self,
2776 lhs: &Tensor,
2777 rhs: &Tensor,
2778 config: &DotGeneralConfig,
2779 lhs_conj: bool,
2780 rhs_conj: bool,
2781 ) -> crate::Result<Tensor> {
2782 if !lhs_conj && !rhs_conj {
2783 return self.dot_general_read(
2784 TensorRead::from_tensor(lhs),
2785 TensorRead::from_tensor(rhs),
2786 config,
2787 );
2788 }
2789
2790 let lhs_tmp;
2791 let lhs_ref = if lhs_conj {
2792 lhs_tmp = self.conj_read(TensorRead::from_tensor(lhs))?;
2793 &lhs_tmp
2794 } else {
2795 lhs
2796 };
2797 let rhs_tmp;
2798 let rhs_ref = if rhs_conj {
2799 rhs_tmp = self.conj_read(TensorRead::from_tensor(rhs))?;
2800 &rhs_tmp
2801 } else {
2802 rhs
2803 };
2804 self.dot_general_read(
2805 TensorRead::from_tensor(lhs_ref),
2806 TensorRead::from_tensor(rhs_ref),
2807 config,
2808 )
2809 }
2810
2811 #[allow(clippy::too_many_arguments)]
2812 #[doc(hidden)]
2813 fn dot_general_with_conj_read(
2814 &mut self,
2815 lhs: TensorRead<'_>,
2816 rhs: TensorRead<'_>,
2817 config: &DotGeneralConfig,
2818 lhs_conj: bool,
2819 rhs_conj: bool,
2820 ) -> crate::Result<Tensor> {
2821 if !lhs_conj && !rhs_conj {
2822 return self.dot_general_read(lhs, rhs, config);
2823 }
2824
2825 let lhs_tmp;
2826 let lhs_ref = if let Some(tensor) = lhs.as_tensor() {
2827 tensor
2828 } else {
2829 lhs_tmp = self.to_contiguous_read(lhs)?;
2830 &lhs_tmp
2831 };
2832 let rhs_tmp;
2833 let rhs_ref = if let Some(tensor) = rhs.as_tensor() {
2834 tensor
2835 } else {
2836 rhs_tmp = self.to_contiguous_read(rhs)?;
2837 &rhs_tmp
2838 };
2839 self.dot_general_with_conj(lhs_ref, rhs_ref, config, lhs_conj, rhs_conj)
2840 }
2841
2842 /// Apply scaled dot-general accumulation into caller-provided output.
2843 ///
2844 /// This is explicitly read-modify-write when `accumulation.beta` is nonzero:
2845 /// `out = alpha * dot_general(lhs, rhs) + beta * out`.
2846 ///
2847 /// # Examples
2848 ///
2849 /// ```rust
2850 /// use tenferro_tensor::{
2851 /// DotGeneralAccumulation, DotGeneralConfig, TensorDot, TensorRead, TensorWrite,
2852 /// };
2853 ///
2854 /// fn dot_add_to<B: TensorDot>(
2855 /// backend: &mut B,
2856 /// lhs: TensorRead<'_>,
2857 /// rhs: TensorRead<'_>,
2858 /// config: &DotGeneralConfig,
2859 /// out: TensorWrite<'_>,
2860 /// ) -> tenferro_tensor::Result<()> {
2861 /// let accumulation = DotGeneralAccumulation::add_to(lhs.dtype())?;
2862 /// backend.dot_general_read_into_accum(lhs, rhs, config, accumulation, out)
2863 /// }
2864 /// ```
2865 /// # Errors
2866 ///
2867 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
2868 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
2869 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
2870 /// backend execution or storage access cannot provide the requested result.
2871 fn dot_general_read_into_accum(
2872 &mut self,
2873 lhs: TensorRead<'_>,
2874 rhs: TensorRead<'_>,
2875 config: &DotGeneralConfig,
2876 accumulation: DotGeneralAccumulation,
2877 out: TensorWrite<'_>,
2878 ) -> crate::Result<()> {
2879 dot_general_accum_via_temp(self, lhs, rhs, config, accumulation, out)
2880 }
2881}
2882
2883/// Session-scoped cached dot-general operations.
2884///
2885/// # Examples
2886///
2887/// ```rust
2888/// use tenferro_tensor::Engine;
2889///
2890/// fn accepts_session_dot<S: Engine + ?Sized>(_session: &mut S) {}
2891/// ```
2892pub trait SessionCachedDot: TensorDot {
2893 #[doc(hidden)]
2894 fn dot_general_cached(
2895 &mut self,
2896 _cache_slot: Option<usize>,
2897 lhs: &Tensor,
2898 rhs: &Tensor,
2899 config: &DotGeneralConfig,
2900 ) -> crate::Result<Tensor> {
2901 self.dot_general_read(
2902 TensorRead::from_tensor(lhs),
2903 TensorRead::from_tensor(rhs),
2904 config,
2905 )
2906 }
2907
2908 #[doc(hidden)]
2909 fn dot_general_read_cached(
2910 &mut self,
2911 cache_slot: Option<usize>,
2912 lhs: TensorRead<'_>,
2913 rhs: TensorRead<'_>,
2914 config: &DotGeneralConfig,
2915 ) -> crate::Result<Tensor> {
2916 match (lhs.as_tensor(), rhs.as_tensor()) {
2917 (Some(lhs), Some(rhs)) => self.dot_general_cached(cache_slot, lhs, rhs, config),
2918 _ => {
2919 let lhs = self.to_contiguous_read(lhs)?;
2920 let rhs = self.to_contiguous_read(rhs)?;
2921 self.dot_general_cached(cache_slot, &lhs, &rhs, config)
2922 }
2923 }
2924 }
2925
2926 // Mirrors the dot-general signature plus runtime-cache metadata.
2927 #[allow(clippy::too_many_arguments)]
2928 #[doc(hidden)]
2929 fn dot_general_with_conj_cached(
2930 &mut self,
2931 _cache_slot: Option<usize>,
2932 lhs: &Tensor,
2933 rhs: &Tensor,
2934 config: &DotGeneralConfig,
2935 lhs_conj: bool,
2936 rhs_conj: bool,
2937 ) -> crate::Result<Tensor> {
2938 self.dot_general_with_conj(lhs, rhs, config, lhs_conj, rhs_conj)
2939 }
2940
2941 // Mirrors the dot-general read signature plus runtime-cache metadata.
2942 #[allow(clippy::too_many_arguments)]
2943 #[doc(hidden)]
2944 fn dot_general_with_conj_read_cached(
2945 &mut self,
2946 cache_slot: Option<usize>,
2947 lhs: TensorRead<'_>,
2948 rhs: TensorRead<'_>,
2949 config: &DotGeneralConfig,
2950 lhs_conj: bool,
2951 rhs_conj: bool,
2952 ) -> crate::Result<Tensor> {
2953 if !lhs_conj && !rhs_conj {
2954 return self.dot_general_read_cached(cache_slot, lhs, rhs, config);
2955 }
2956
2957 let lhs_tmp;
2958 let lhs_ref = if let Some(tensor) = lhs.as_tensor() {
2959 tensor
2960 } else {
2961 lhs_tmp = self.to_contiguous_read(lhs)?;
2962 &lhs_tmp
2963 };
2964 let rhs_tmp;
2965 let rhs_ref = if let Some(tensor) = rhs.as_tensor() {
2966 tensor
2967 } else {
2968 rhs_tmp = self.to_contiguous_read(rhs)?;
2969 &rhs_tmp
2970 };
2971 self.dot_general_with_conj_cached(cache_slot, lhs_ref, rhs_ref, config, lhs_conj, rhs_conj)
2972 }
2973
2974 /// Apply session-cached scaled dot-general accumulation into output.
2975 ///
2976 /// The cache slot is session-local metadata; `accumulation` still controls
2977 /// overwrite versus read-modify-write semantics.
2978 ///
2979 /// # Examples
2980 ///
2981 /// ```rust
2982 /// use tenferro_tensor::{
2983 /// DotGeneralAccumulation, DotGeneralConfig, SessionCachedDot, TensorRead, TensorWrite,
2984 /// };
2985 ///
2986 /// fn session_cached_dot_add_to<S: SessionCachedDot + ?Sized>(
2987 /// session: &mut S,
2988 /// lhs: TensorRead<'_>,
2989 /// rhs: TensorRead<'_>,
2990 /// config: &DotGeneralConfig,
2991 /// out: TensorWrite<'_>,
2992 /// ) -> tenferro_tensor::Result<()> {
2993 /// let accumulation = DotGeneralAccumulation::add_to(lhs.dtype())?;
2994 /// session.dot_general_read_into_accum_cached(
2995 /// Some(0),
2996 /// lhs,
2997 /// rhs,
2998 /// config,
2999 /// accumulation,
3000 /// out,
3001 /// )
3002 /// }
3003 /// ```
3004 /// # Errors
3005 ///
3006 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3007 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3008 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3009 /// backend execution or storage access cannot provide the requested result.
3010 fn dot_general_read_into_accum_cached(
3011 &mut self,
3012 _cache_slot: Option<usize>,
3013 lhs: TensorRead<'_>,
3014 rhs: TensorRead<'_>,
3015 config: &DotGeneralConfig,
3016 accumulation: DotGeneralAccumulation,
3017 out: TensorWrite<'_>,
3018 ) -> crate::Result<()> {
3019 self.dot_general_read_into_accum(lhs, rhs, config, accumulation, out)
3020 }
3021}
3022
3023/// Indexing, slicing, and padding operations.
3024///
3025/// # Examples
3026///
3027/// ```rust
3028/// use tenferro_tensor::TensorIndexing;
3029///
3030/// fn accepts_indexing<B: TensorIndexing>(_backend: &mut B) {}
3031/// ```
3032pub trait TensorIndexing: TensorStructural {
3033 /// # Errors
3034 ///
3035 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3036 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3037 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3038 /// backend execution or storage access cannot provide the requested result.
3039 fn gather(
3040 &mut self,
3041 operand: &Tensor,
3042 start_indices: &Tensor,
3043 config: &GatherConfig,
3044 ) -> crate::Result<Tensor>;
3045 /// # Errors
3046 ///
3047 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3048 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3049 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3050 /// backend execution or storage access cannot provide the requested result.
3051 fn scatter(
3052 &mut self,
3053 operand: &Tensor,
3054 scatter_indices: &Tensor,
3055 updates: &Tensor,
3056 config: &ScatterConfig,
3057 ) -> crate::Result<Tensor>;
3058 /// Scatter with every input taken as a read.
3059 ///
3060 /// The default stages each borrowed view into compact storage (an owned
3061 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
3062 /// should override this so a view is not copied (#2214).
3063 ///
3064 /// # Examples
3065 ///
3066 /// ```rust
3067 /// use tenferro_tensor::{Tensor, TensorIndexing, ScatterConfig, TensorRead};
3068 ///
3069 /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, idx: TensorRead<'_>, updates: TensorRead<'_>, config: &ScatterConfig)
3070 /// -> tenferro_tensor::Result<Tensor>
3071 /// {
3072 /// session.scatter_read(x, idx, updates, config)
3073 /// }
3074 /// ```
3075 ///
3076 /// # Errors
3077 ///
3078 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3079 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3080 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3081 /// backend execution or storage access cannot provide the requested result.
3082 fn scatter_read(
3083 &mut self,
3084 operand: TensorRead<'_>,
3085 scatter_indices: TensorRead<'_>,
3086 updates: TensorRead<'_>,
3087 config: &ScatterConfig,
3088 ) -> crate::Result<Tensor> {
3089 let operand = stage_view(self, operand)?;
3090 let scatter_indices = stage_view(self, scatter_indices)?;
3091 let updates = stage_view(self, updates)?;
3092 self.scatter(&operand, &scatter_indices, &updates, config)
3093 }
3094
3095 /// # Errors
3096 ///
3097 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3098 /// for invalid shapes, ranks, axes, dtypes, or output metadata. In
3099 /// particular, a limit greater than the corresponding input dimension is
3100 /// reported as [`crate::ValidationError::InvalidArgument`] with the
3101 /// `"configuration"` argument. It returns [`crate::Error::BackendFailure`]
3102 /// or [`crate::Error::BackendSource`] when backend execution or storage
3103 /// access cannot provide the requested result.
3104 fn slice(&mut self, input: &Tensor, config: &SliceConfig) -> crate::Result<Tensor>;
3105 /// Slice with the input taken as a read.
3106 ///
3107 /// The default stages each borrowed view into compact storage (an owned
3108 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
3109 /// should override this so a view is not copied (#2214).
3110 ///
3111 /// # Examples
3112 ///
3113 /// ```rust
3114 /// use tenferro_tensor::{Tensor, TensorIndexing, SliceConfig, TensorRead};
3115 ///
3116 /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, config: &SliceConfig)
3117 /// -> tenferro_tensor::Result<Tensor>
3118 /// {
3119 /// session.slice_read(x, config)
3120 /// }
3121 /// ```
3122 ///
3123 /// # Errors
3124 ///
3125 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3126 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3127 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3128 /// backend execution or storage access cannot provide the requested result.
3129 fn slice_read(&mut self, input: TensorRead<'_>, config: &SliceConfig) -> crate::Result<Tensor> {
3130 let input = stage_view(self, input)?;
3131 self.slice(&input, config)
3132 }
3133
3134 /// # Errors
3135 ///
3136 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3137 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3138 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3139 /// backend execution or storage access cannot provide the requested result.
3140 fn dynamic_slice(
3141 &mut self,
3142 input: &Tensor,
3143 starts: &Tensor,
3144 slice_sizes: &[usize],
3145 ) -> crate::Result<Tensor>;
3146 /// Dynamic slice with every input taken as a read.
3147 ///
3148 /// The default stages each borrowed view into compact storage (an owned
3149 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
3150 /// should override this so a view is not copied (#2214).
3151 ///
3152 /// # Examples
3153 ///
3154 /// ```rust
3155 /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
3156 ///
3157 /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, starts: TensorRead<'_>)
3158 /// -> tenferro_tensor::Result<Tensor>
3159 /// {
3160 /// session.dynamic_slice_read(x, starts, &[2])
3161 /// }
3162 /// ```
3163 ///
3164 /// # Errors
3165 ///
3166 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3167 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3168 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3169 /// backend execution or storage access cannot provide the requested result.
3170 fn dynamic_slice_read(
3171 &mut self,
3172 input: TensorRead<'_>,
3173 starts: TensorRead<'_>,
3174 slice_sizes: &[usize],
3175 ) -> crate::Result<Tensor> {
3176 let input = stage_view(self, input)?;
3177 let starts = stage_view(self, starts)?;
3178 self.dynamic_slice(&input, &starts, slice_sizes)
3179 }
3180
3181 /// # Errors
3182 ///
3183 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3184 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3185 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3186 /// backend execution or storage access cannot provide the requested result.
3187 fn dynamic_update_slice(
3188 &mut self,
3189 operand: &Tensor,
3190 update: &Tensor,
3191 starts: &Tensor,
3192 ) -> crate::Result<Tensor>;
3193 /// Dynamic-update-slice with every input taken as a read.
3194 ///
3195 /// The default stages each borrowed view into compact storage (an owned
3196 /// tensor is passed through) and delegates to the owned-input method; a
3197 /// backend whose kernel consumes a borrowed operand should override this so
3198 /// a view is not copied (#2214).
3199 ///
3200 /// # Examples
3201 ///
3202 /// ```rust
3203 /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
3204 ///
3205 /// fn run(
3206 /// session: &mut dyn TensorIndexing,
3207 /// x: TensorRead<'_>,
3208 /// update: TensorRead<'_>,
3209 /// starts: TensorRead<'_>,
3210 /// ) -> tenferro_tensor::Result<Tensor> {
3211 /// session.dynamic_update_slice_read(x, update, starts)
3212 /// }
3213 /// ```
3214 ///
3215 /// # Errors
3216 ///
3217 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3218 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3219 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3220 /// backend execution or storage access cannot provide the requested result.
3221 fn dynamic_update_slice_read(
3222 &mut self,
3223 operand: TensorRead<'_>,
3224 update: TensorRead<'_>,
3225 starts: TensorRead<'_>,
3226 ) -> crate::Result<Tensor> {
3227 let operand = stage_view(self, operand)?;
3228 let update = stage_view(self, update)?;
3229 let starts = stage_view(self, starts)?;
3230 self.dynamic_update_slice(&operand, &update, &starts)
3231 }
3232 /// # Errors
3233 ///
3234 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3235 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3236 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3237 /// backend execution or storage access cannot provide the requested result.
3238 fn pad(&mut self, input: &Tensor, config: &PadConfig) -> crate::Result<Tensor>;
3239 /// Pad with the input taken as a read.
3240 ///
3241 /// The default stages each borrowed view into compact storage (an owned
3242 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
3243 /// should override this so a view is not copied (#2214).
3244 ///
3245 /// # Examples
3246 ///
3247 /// ```rust
3248 /// use tenferro_tensor::{Tensor, TensorIndexing, PadConfig, TensorRead};
3249 ///
3250 /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>, config: &PadConfig)
3251 /// -> tenferro_tensor::Result<Tensor>
3252 /// {
3253 /// session.pad_read(x, config)
3254 /// }
3255 /// ```
3256 ///
3257 /// # Errors
3258 ///
3259 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3260 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3261 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3262 /// backend execution or storage access cannot provide the requested result.
3263 fn pad_read(&mut self, input: TensorRead<'_>, config: &PadConfig) -> crate::Result<Tensor> {
3264 let input = stage_view(self, input)?;
3265 self.pad(&input, config)
3266 }
3267
3268 /// # Errors
3269 ///
3270 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3271 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3272 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3273 /// backend execution or storage access cannot provide the requested result.
3274 fn concatenate(&mut self, inputs: &[&Tensor], axis: usize) -> crate::Result<Tensor>;
3275 /// Concatenate with every input taken as a read.
3276 ///
3277 /// The default stages each borrowed view into compact storage (an owned
3278 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
3279 /// should override this so a view is not copied (#2214).
3280 ///
3281 /// # Examples
3282 ///
3283 /// ```rust
3284 /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
3285 ///
3286 /// fn run(session: &mut dyn TensorIndexing, a: TensorRead<'_>, b: TensorRead<'_>)
3287 /// -> tenferro_tensor::Result<Tensor>
3288 /// {
3289 /// session.concatenate_read(&[a, b], 0)
3290 /// }
3291 /// ```
3292 ///
3293 /// # Errors
3294 ///
3295 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3296 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3297 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3298 /// backend execution or storage access cannot provide the requested result.
3299 fn concatenate_read(
3300 &mut self,
3301 inputs: &[TensorRead<'_>],
3302 axis: usize,
3303 ) -> crate::Result<Tensor> {
3304 let staged = inputs
3305 .iter()
3306 .map(|input| stage_view(self, input.clone()))
3307 .collect::<crate::Result<Vec<_>>>()?;
3308 let refs: Vec<&Tensor> = staged.iter().map(|input| &**input).collect();
3309 self.concatenate(&refs, axis)
3310 }
3311
3312 /// # Errors
3313 ///
3314 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3315 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3316 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3317 /// backend execution or storage access cannot provide the requested result.
3318 fn reverse(&mut self, input: &Tensor, axes: &[usize]) -> crate::Result<Tensor>;
3319 /// Reverse with the input taken as a read.
3320 ///
3321 /// The default stages each borrowed view into compact storage (an owned
3322 /// tensor is passed through) and delegates to the owned-input method; a backend whose kernel consumes a borrowed operand
3323 /// should override this so a view is not copied (#2214).
3324 ///
3325 /// # Examples
3326 ///
3327 /// ```rust
3328 /// use tenferro_tensor::{Tensor, TensorIndexing, TensorRead};
3329 ///
3330 /// fn run(session: &mut dyn TensorIndexing, x: TensorRead<'_>)
3331 /// -> tenferro_tensor::Result<Tensor>
3332 /// {
3333 /// session.reverse_read(x, &[0])
3334 /// }
3335 /// ```
3336 ///
3337 /// # Errors
3338 ///
3339 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3340 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3341 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3342 /// backend execution or storage access cannot provide the requested result.
3343 fn reverse_read(&mut self, input: TensorRead<'_>, axes: &[usize]) -> crate::Result<Tensor> {
3344 let input = stage_view(self, input)?;
3345 self.reverse(&input, axes)
3346 }
3347}
3348
3349/// Backend-owned canonicalization for typed tensor views.
3350///
3351/// Implementations must preserve the input placement family. CPU backends
3352/// canonicalize host views through explicit host copies and reject backend
3353/// buffers with a diagnostic that asks the caller to download first. GPU
3354/// backends canonicalize GPU-resident views on the same device and reject host
3355/// buffers with an upload hint.
3356///
3357/// [`TensorViewCanonicalization::copy_into`] requires source and destination
3358/// shapes, scalar dtypes, and placement families to match. The destination
3359/// view must be internally non-overlapping, and source and destination backing
3360/// allocations must not alias unless an implementation explicitly documents
3361/// and supports that case. Implementations may reject layouts their native
3362/// kernels cannot consume.
3363///
3364/// CUDA currently accepts only a compact column-major source view with offset
3365/// zero that covers its full allocation; arbitrary-stride destinations remain
3366/// supported. Canonicalization and copying are same-placement operations: they
3367/// must not perform hidden host/device transfers or silently materialize an
3368/// unsupported source layout.
3369///
3370/// This trait is intentionally separate from [`Engine`] so generic
3371/// typed methods do not change the object-safety contract of `dyn Engine`.
3372///
3373/// # Examples
3374///
3375/// ```rust
3376/// use tenferro_tensor::{DynRank, TensorViewCanonicalization, TypedTensor};
3377///
3378/// fn compact_i32<B: TensorViewCanonicalization<i32, DynRank>>(
3379/// backend: &mut B,
3380/// tensor: &TypedTensor<i32>,
3381/// ) -> tenferro_tensor::Result<TypedTensor<i32>> {
3382/// backend.to_contiguous(&tensor.as_view())
3383/// }
3384///
3385/// fn copy_i32<B: TensorViewCanonicalization<i32, DynRank>>(
3386/// backend: &mut B,
3387/// src: &TypedTensor<i32>,
3388/// dst: &mut TypedTensor<i32>,
3389/// ) -> tenferro_tensor::Result<()> {
3390/// backend.copy_into(&src.as_view(), &mut dst.as_view_mut())
3391/// }
3392/// ```
3393pub trait TensorViewCanonicalization<T: TensorScalar, R: TensorRank> {
3394 /// # Errors
3395 ///
3396 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3397 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3398 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3399 /// backend execution or storage access cannot provide the requested result.
3400 fn to_contiguous(
3401 &mut self,
3402 view: &TypedTensorView<'_, T, R>,
3403 ) -> crate::Result<TypedTensor<T, R>>;
3404
3405 /// # Errors
3406 ///
3407 /// Returns [`crate::Error::Validation`] with a typed `ValidationError` source
3408 /// for invalid shapes, ranks, axes, dtypes, or output metadata. It returns
3409 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3410 /// backend execution or storage access cannot provide the requested result.
3411 fn copy_into(
3412 &mut self,
3413 src: &TypedTensorView<'_, T, R>,
3414 dst: &mut TypedTensorViewMut<'_, T, R>,
3415 ) -> crate::Result<()>;
3416}
3417
3418/// Optional elementwise fusion execution.
3419///
3420/// # Examples
3421///
3422/// ```rust
3423/// use tenferro_tensor::TensorFusion;
3424///
3425/// fn accepts_fusion<B: TensorFusion>(_backend: &mut B) {}
3426/// ```
3427pub trait TensorFusion {
3428 #[doc(hidden)]
3429 fn execute_elementwise_fusion(
3430 &mut self,
3431 _inputs: &[&Tensor],
3432 _plan: &ElementwiseFusionPlan,
3433 ) -> crate::Result<Option<Vec<Tensor>>> {
3434 Ok(None)
3435 }
3436
3437 #[doc(hidden)]
3438 #[allow(clippy::too_many_arguments)]
3439 fn execute_broadcast_multiply(
3440 &mut self,
3441 _lhs: TensorRead<'_>,
3442 _lhs_shape: &[usize],
3443 _lhs_dims: &[usize],
3444 _rhs: TensorRead<'_>,
3445 _rhs_shape: &[usize],
3446 _rhs_dims: &[usize],
3447 ) -> crate::Result<Option<Tensor>> {
3448 Ok(None)
3449 }
3450
3451 #[doc(hidden)]
3452 #[allow(clippy::too_many_arguments)]
3453 fn execute_broadcast_multiply_value(
3454 &mut self,
3455 lhs: TensorRead<'_>,
3456 lhs_shape: &[usize],
3457 lhs_dims: &[usize],
3458 rhs: TensorRead<'_>,
3459 rhs_shape: &[usize],
3460 rhs_dims: &[usize],
3461 ) -> crate::Result<Option<TensorValue>> {
3462 self.execute_broadcast_multiply(lhs, lhs_shape, lhs_dims, rhs, rhs_shape, rhs_dims)
3463 .map(|tensor| tensor.map(TensorValue::from_tensor))
3464 }
3465}
3466
3467/// Backend buffer lifecycle operations.
3468///
3469/// # Examples
3470///
3471/// ```rust
3472/// use tenferro_tensor::TensorBuffer;
3473///
3474/// fn accepts_buffer<B: TensorBuffer>(_backend: &mut B) {}
3475/// ```
3476pub trait TensorBuffer {
3477 fn reclaim_buffer(&mut self, _tensor: Tensor) {}
3478}
3479
3480/// Device transfer operations on backend boundaries.
3481///
3482/// # Examples
3483///
3484/// ```rust
3485/// use tenferro_tensor::TensorDeviceTransfer;
3486///
3487/// fn accepts_transfer<B: TensorDeviceTransfer>(_backend: &mut B) {}
3488/// ```
3489pub trait TensorDeviceTransfer {
3490 /// Explicitly copy a provider-owned read target into host storage.
3491 ///
3492 /// Implementations must not return the input unchanged or stage through an
3493 /// unrelated provider. A backend that cannot transfer the requested read
3494 /// target returns a typed unsupported error.
3495 ///
3496 /// # Errors
3497 ///
3498 /// Returns [`crate::Error::Unsupported`] when the implementation cannot
3499 /// perform the requested transfer, or a typed validation/backend error when
3500 /// the source cannot be read.
3501 fn download_to_host(&mut self, tensor: TensorRead<'_>) -> crate::Result<Tensor>;
3502
3503 /// Explicitly copy a host read target into provider storage.
3504 ///
3505 /// # Errors
3506 ///
3507 /// Returns [`crate::Error::Unsupported`] when the implementation cannot
3508 /// perform the requested transfer, or a typed validation/backend error when
3509 /// the source cannot be read.
3510 fn upload_host_tensor(&mut self, tensor: TensorRead<'_>) -> crate::Result<Tensor>;
3511}
3512
3513#[doc(hidden)]
3514pub trait TensorBackendOps:
3515 TensorElementwise
3516 + TensorAnalytic
3517 + TensorStructural
3518 + TensorReduction
3519 + TensorIndexing
3520 + TensorDot
3521 + TensorFusion
3522 + TensorBuffer
3523{
3524}
3525
3526impl<T> TensorBackendOps for T where
3527 T: TensorElementwise
3528 + TensorAnalytic
3529 + TensorStructural
3530 + TensorReduction
3531 + TensorIndexing
3532 + TensorDot
3533 + TensorFusion
3534 + TensorBuffer
3535 + ?Sized
3536{
3537}
3538
3539/// Validate the shared input contract for [`Engine::vdot_read`].
3540#[doc(hidden)]
3541pub fn validate_vdot_read(lhs: &TensorRead<'_>, rhs: &TensorRead<'_>) -> crate::Result<()> {
3542 let op = "Engine::vdot_read";
3543 validate_supported_blas1_dtype(op, lhs.dtype())?;
3544 if rhs.dtype() != lhs.dtype() {
3545 return Err(Error::dtype_mismatch(op, lhs.dtype(), rhs.dtype()));
3546 }
3547 if lhs.shape() != rhs.shape() {
3548 return Err(Error::shape_mismatch(
3549 op,
3550 lhs.shape().to_vec(),
3551 rhs.shape().to_vec(),
3552 ));
3553 }
3554 validate_shape_product(op, lhs.shape())?;
3555 validate_compatible_placement(op, lhs, rhs)
3556}
3557
3558/// Validate the shared input contract for [`Engine::norm_squared_read`].
3559#[doc(hidden)]
3560pub fn validate_norm_squared_read(input: &TensorRead<'_>) -> crate::Result<()> {
3561 validate_supported_blas1_dtype("Engine::norm_squared_read", input.dtype())?;
3562 validate_shape_product("Engine::norm_squared_read", input.shape()).map(|_| ())
3563}
3564
3565/// Validate the shared input and destination contract for
3566/// [`Engine::axpby_read_into_accum`].
3567#[doc(hidden)]
3568pub fn validate_axpby_read_into_accum(
3569 alpha: ContractionScalar,
3570 x: &TensorRead<'_>,
3571 beta: ContractionScalar,
3572 y: &TensorWrite<'_>,
3573) -> crate::Result<()> {
3574 let op = "Engine::axpby_read_into_accum";
3575 validate_supported_blas1_dtype(op, x.dtype())?;
3576 if y.dtype() != x.dtype() {
3577 return Err(Error::dtype_mismatch(op, x.dtype(), y.dtype()));
3578 }
3579 if alpha.dtype() != x.dtype() {
3580 return Err(Error::dtype_mismatch(op, x.dtype(), alpha.dtype()));
3581 }
3582 if beta.dtype() != x.dtype() {
3583 return Err(Error::dtype_mismatch(op, x.dtype(), beta.dtype()));
3584 }
3585 if x.shape() != y.shape() {
3586 return Err(Error::shape_mismatch(
3587 op,
3588 x.shape().to_vec(),
3589 y.shape().to_vec(),
3590 ));
3591 }
3592 validate_shape_product(op, x.shape())?;
3593 // INVARIANT: write-injectivity is already proved when a destination view is
3594 // constructed (`validate_mutable_no_overlap`), and an owned destination is
3595 // compact by construction, so no element-wise re-check is needed here. Only
3596 // the `x`/`y` alias rejection below remains.
3597 validate_compatible_placement(op, x, &y.as_read())?;
3598 validate_read_into_destination(op, std::slice::from_ref(x), y)
3599}
3600
3601/// # Errors
3602///
3603/// Returns [`Error::Unsupported`] when `dtype` is not floating or complex.
3604fn validate_supported_blas1_dtype(op: &'static str, dtype: DType) -> crate::Result<()> {
3605 if matches!(dtype, DType::F32 | DType::F64 | DType::C32 | DType::C64) {
3606 Ok(())
3607 } else {
3608 Err(Error::unsupported(
3609 op,
3610 format!("unsupported dtype {dtype:?}; supported dtypes: F32/F64/C32/C64"),
3611 ))
3612 }
3613}
3614
3615/// # Errors
3616///
3617/// Returns [`Error::Validation`] with [`ValidationError::IntegerOverflow`] when
3618/// the checked shape product overflows.
3619fn validate_shape_product(op: &'static str, shape: &[usize]) -> crate::Result<usize> {
3620 crate::validate::checked_shape_product(op, "shape", shape)
3621}
3622
3623/// # Errors
3624///
3625/// Returns [`Error::Validation`] with [`ValidationError::InvalidArgument`] when
3626/// placements differ.
3627fn validate_compatible_placement(
3628 op: &'static str,
3629 lhs: &TensorRead<'_>,
3630 rhs: &TensorRead<'_>,
3631) -> crate::Result<()> {
3632 if lhs.placement() != rhs.placement() {
3633 return Err(Error::invalid_argument(
3634 op,
3635 "placement",
3636 "tensor inputs must have compatible placement",
3637 ));
3638 }
3639 Ok(())
3640}
3641
3642/// The execution trait every tensor operation runs on.
3643///
3644/// An engine is a caller-held value (a CPU engine owns a Rayon pool and a
3645/// workspace; a GPU engine owns a stream and a workspace). Operations take
3646/// `&mut` of the engine, so one computation uses an engine at a time without
3647/// any runtime lock. There is no separate session object.
3648///
3649/// # Examples
3650///
3651/// ```rust
3652/// use tenferro_tensor::{Engine, Tensor, TensorRead};
3653///
3654/// fn add_on(engine: &mut dyn Engine, a: &Tensor, b: &Tensor) -> tenferro_tensor::Result<Tensor> {
3655/// engine.add_read(TensorRead::from_tensor(a), TensorRead::from_tensor(b))
3656/// }
3657/// ```
3658///
3659/// The operation one-shot spelling is gone; an engine only answers to the read
3660/// form:
3661///
3662/// ```compile_fail
3663/// use tenferro_tensor::{Engine, Tensor};
3664///
3665/// fn add_on(engine: &mut dyn Engine, a: &Tensor, b: &Tensor) {
3666/// let _ = engine.add(a, b);
3667/// }
3668/// ```
3669pub trait Engine: TensorBackendOps + SessionCachedDot + TensorDeviceTransfer {
3670 /// Gather with both operands taken as reads.
3671 ///
3672 /// The default stages each borrowed view (an owned tensor is passed
3673 /// through) and delegates to [`TensorIndexing::gather`]; a backend whose gather kernel consumes the
3674 /// operand's strides overrides this so a borrowed operand needs no copy
3675 /// (invariant I1: the runtime must not materialize by default).
3676 ///
3677 /// # Errors
3678 ///
3679 /// Returns [`crate::Error::Validation`] with a typed `ValidationError`
3680 /// source for invalid shapes, ranks, axes, dtypes or output metadata, and
3681 /// [`crate::Error::BackendFailure`] or [`crate::Error::BackendSource`] when
3682 /// backend execution or storage access cannot provide the requested result.
3683 /// The default implementation stages a view first, so it also returns
3684 /// whatever [`TensorStructural::to_contiguous_read`] reports for a view the backend
3685 /// cannot materialize.
3686 fn gather_read(
3687 &mut self,
3688 operand: TensorRead<'_>,
3689 start_indices: TensorRead<'_>,
3690 config: &GatherConfig,
3691 ) -> crate::Result<Tensor> {
3692 let operand = stage_view(self, operand)?;
3693 let start_indices = stage_view(self, start_indices)?;
3694 self.gather(&operand, &start_indices, config)
3695 }
3696
3697 /// Compute the all-axis conjugating dot product without transferring either input.
3698 ///
3699 /// The result is a rank-0 tensor with the input dtype and has the value
3700 /// `sum(conj(lhs) * rhs)`. Borrowed views remain borrowed through the
3701 /// backend's existing same-placement planning boundary.
3702 ///
3703 /// # Examples
3704 ///
3705 /// ```rust
3706 /// use tenferro_tensor::{Engine, TensorRead};
3707 ///
3708 /// fn vdot(session: &mut dyn Engine, x: TensorRead<'_>, y: TensorRead<'_>)
3709 /// -> tenferro_tensor::Result<tenferro_tensor::Tensor>
3710 /// {
3711 /// session.vdot_read(x, y)
3712 /// }
3713 /// ```
3714 ///
3715 /// # Errors
3716 ///
3717 /// Returns [`Error::Unsupported`] when the backend does not override this
3718 /// capability or the dtype is unsupported; [`Error::Validation`] with
3719 /// `DTypeMismatch`, `ShapeMismatch`, or `InvalidArgument` when dtype, shape,
3720 /// or placement differs; [`Error::RuntimeState`] for inaccessible backend
3721 /// storage; or [`Error::BackendSource`] when provider execution fails.
3722 fn vdot_read(&mut self, _lhs: TensorRead<'_>, _rhs: TensorRead<'_>) -> crate::Result<Tensor> {
3723 Err(Error::unsupported(
3724 "Engine::vdot_read",
3725 "backend session does not implement vdot_read",
3726 ))
3727 }
3728
3729 /// Compute the all-axis sum of squared magnitudes without taking a square root.
3730 ///
3731 /// The result is rank 0 and is F32 for F32/C32 input or F64 for F64/C64
3732 /// input. No transfer or full-size algebra temporary is implied by this
3733 /// session contract.
3734 ///
3735 /// # Examples
3736 ///
3737 /// ```rust
3738 /// use tenferro_tensor::{Engine, TensorRead};
3739 ///
3740 /// fn norm_squared(session: &mut dyn Engine, x: TensorRead<'_>)
3741 /// -> tenferro_tensor::Result<tenferro_tensor::Tensor>
3742 /// {
3743 /// session.norm_squared_read(x)
3744 /// }
3745 /// ```
3746 ///
3747 /// # Errors
3748 ///
3749 /// Returns [`Error::Unsupported`] when the backend does not override this
3750 /// capability or the dtype is unsupported, [`Error::RuntimeState`] when
3751 /// backend storage is not host-accessible, or [`Error::BackendSource`] when
3752 /// reduction execution fails.
3753 fn norm_squared_read(&mut self, _input: TensorRead<'_>) -> crate::Result<Tensor> {
3754 Err(Error::unsupported(
3755 "Engine::norm_squared_read",
3756 "backend session does not implement norm_squared_read",
3757 ))
3758 }
3759
3760 /// Compute a fused activation in one pass, or decline with `Ok(None)`.
3761 ///
3762 /// This is an optional fast path. A backend that returns `Ok(None)` keeps
3763 /// the shared composite formulation of the same function, so declining is
3764 /// always correct. A backend that returns `Ok(Some(output))` must produce
3765 /// the value
3766 /// defined by [`ActivationOp`] for an `F32`/`F64` input in one elementwise
3767 /// traversal.
3768 ///
3769 /// # Examples
3770 ///
3771 /// ```
3772 /// use tenferro_tensor::{ActivationOp, Engine, TensorRead};
3773 ///
3774 /// fn fused(session: &mut dyn Engine, x: TensorRead<'_>)
3775 /// -> tenferro_tensor::Result<Option<tenferro_tensor::Tensor>>
3776 /// {
3777 /// session.fused_activation_read(ActivationOp::Sigmoid, x)
3778 /// }
3779 /// ```
3780 ///
3781 /// # Errors
3782 ///
3783 /// Returns a typed validation error for an unsupported dtype, a backend
3784 /// error when storage cannot be read, or a kernel error from the fused
3785 /// traversal. Returning `Ok(None)` declines the fast path.
3786 fn fused_activation_read(
3787 &mut self,
3788 op: ActivationOp,
3789 input: TensorRead<'_>,
3790 ) -> crate::Result<Option<Tensor>> {
3791 let _ = (op, input);
3792 Ok(None)
3793 }
3794
3795 /// Fused real-float softmax along `axis`.
3796 ///
3797 /// This is an optional fast path for the shared runtime composite
3798 /// formulation. A backend that returns `Ok(Some(output))` must produce the
3799 /// same value as the composite: a max-subtracted softmax over `axis`, with
3800 /// an all-`-inf` slice yielding zeros and NaN propagating.
3801 ///
3802 /// # Examples
3803 ///
3804 /// ```
3805 /// use tenferro_tensor::{Engine, TensorRead};
3806 ///
3807 /// fn softmax(session: &mut dyn Engine, x: TensorRead<'_>, axis: usize)
3808 /// -> tenferro_tensor::Result<Option<tenferro_tensor::Tensor>>
3809 /// {
3810 /// session.softmax_read(x, axis)
3811 /// }
3812 /// ```
3813 ///
3814 /// # Errors
3815 ///
3816 /// Returns a typed validation error for an invalid axis or unsupported
3817 /// dtype, a backend error when storage cannot be read, or a kernel error.
3818 /// Returning `Ok(None)` declines the fast path.
3819 fn softmax_read(
3820 &mut self,
3821 input: TensorRead<'_>,
3822 axis: usize,
3823 ) -> crate::Result<Option<Tensor>> {
3824 let _ = (input, axis);
3825 Ok(None)
3826 }
3827
3828 /// Apply `y <- alpha * x + beta * y` in one pass into caller-owned storage.
3829 ///
3830 /// Scalars must have the exact tensor dtype; real coefficients for complex
3831 /// vectors are represented as complex values with zero imaginary part. The
3832 /// destination must be write-injective and disjoint from `x`; any x/y
3833 /// storage overlap is rejected before mutation. A strided or offset
3834 /// destination view is accepted, so a caller can accumulate into a region
3835 /// of a larger allocation.
3836 ///
3837 /// # Examples
3838 ///
3839 /// ```rust
3840 /// use tenferro_tensor::{Engine, ContractionScalar, TensorRead, TensorWrite};
3841 ///
3842 /// fn axpby(session: &mut dyn Engine, x: TensorRead<'_>, y: TensorWrite<'_>)
3843 /// -> tenferro_tensor::Result<()>
3844 /// {
3845 /// session.axpby_read_into_accum(
3846 /// ContractionScalar::F64(1.0), x, ContractionScalar::F64(0.0), y,
3847 /// )
3848 /// }
3849 /// ```
3850 ///
3851 /// # Errors
3852 ///
3853 /// Returns [`Error::Unsupported`] when the backend does not override this
3854 /// capability or the dtype is unsupported; [`Error::Validation`] with
3855 /// `DTypeMismatch`, `ShapeMismatch`, or `InvalidArgument` for scalar/dtype,
3856 /// shape, placement, injectivity, or overlap failures; or
3857 /// [`Error::RuntimeState`] for inaccessible backend storage. Invalid
3858 /// requests leave the destination unchanged.
3859 fn axpby_read_into_accum(
3860 &mut self,
3861 _alpha: ContractionScalar,
3862 _x: TensorRead<'_>,
3863 _beta: ContractionScalar,
3864 _y: TensorWrite<'_>,
3865 ) -> crate::Result<()> {
3866 Err(Error::unsupported(
3867 "Engine::axpby_read_into_accum",
3868 "backend session does not implement axpby_read_into_accum",
3869 ))
3870 }
3871
3872 /// Return this engine's backend-leaf native capability, if it has one.
3873 ///
3874 /// The standard engines return a token that their own safe visitors
3875 /// (`with_cpu_engine`, `with_cuda_engine`) recover. The default is `None`:
3876 /// a custom engine has no native services unless it forwards the token of a
3877 /// standard engine it owns. A wrapper that overrides operation dispatch
3878 /// (for example a custom GEMM) should keep the default, because an
3879 /// operation family that finds a native token may call the delegate's
3880 /// native services directly and so bypass the wrapper's override.
3881 ///
3882 /// # Examples
3883 ///
3884 /// ```rust
3885 /// use tenferro_tensor::Engine;
3886 ///
3887 /// fn native_services_available(session: &mut dyn Engine) -> bool {
3888 /// session.native_engine().is_some()
3889 /// }
3890 /// ```
3891 fn native_engine(&mut self) -> Option<crate::NativeSessionRef<'_>> {
3892 None
3893 }
3894}
3895
3896/// A read handed to an owned-input method by a materializing `*_read` default.
3897///
3898/// An owned tensor is already compact, so it is borrowed as is; only a view is
3899/// staged.
3900enum StagedRead<'a> {
3901 Borrowed(&'a Tensor),
3902 Staged(Box<Tensor>),
3903}
3904
3905impl std::ops::Deref for StagedRead<'_> {
3906 type Target = Tensor;
3907
3908 fn deref(&self) -> &Tensor {
3909 match self {
3910 Self::Borrowed(tensor) => tensor,
3911 Self::Staged(tensor) => tensor,
3912 }
3913 }
3914}
3915
3916/// Stage `read` for an owned-input method, copying only when it is a view.
3917fn stage_view<'a, S: TensorStructural + ?Sized>(
3918 session: &mut S,
3919 read: TensorRead<'a>,
3920) -> crate::Result<StagedRead<'a>> {
3921 match read {
3922 TensorRead::Tensor(tensor) => Ok(StagedRead::Borrowed(tensor)),
3923 view => Ok(StagedRead::Staged(Box::new(
3924 session.to_contiguous_read(view)?,
3925 ))),
3926 }
3927}