Skip to main content

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}