Skip to main content

tensor4all_tensorbackend/
storage.rs

1use crate::any_scalar::BackendScalar;
2use crate::tensor_element::TensorElement;
3use anyhow::{anyhow, ensure, Result};
4use num_complex::{Complex32, Complex64};
5use std::ops::Mul;
6use std::sync::Arc;
7use tenferro::{DType, TensorScalar};
8
9/// Dispatch a compact-payload body once over every scalar type [`Storage`] holds.
10///
11/// The four erased arms live here and nowhere else; `$ty` names the payload
12/// scalar type inside `$body`, so dtype-agnostic storage methods are written
13/// exactly once. Do not name `$ty` after an enclosing generic parameter: the
14/// expansion introduces a local type alias with that name.
15macro_rules! storage_payload_dispatch {
16    ($repr:expr, $ty:ident => |$payload:ident| $body:expr) => {
17        match $repr {
18            StorageRepr::F32($payload) => {
19                #[allow(unused)] // the body names the payload type only when it needs it
20                type $ty = f32;
21                $body
22            }
23            StorageRepr::F64($payload) => {
24                #[allow(unused)] // the body names the payload type only when it needs it
25                type $ty = f64;
26                $body
27            }
28            StorageRepr::C32($payload) => {
29                #[allow(unused)] // the body names the payload type only when it needs it
30                type $ty = Complex32;
31                $body
32            }
33            StorageRepr::C64($payload) => {
34                #[allow(unused)] // the body names the payload type only when it needs it
35                type $ty = Complex64;
36                $body
37            }
38        }
39    };
40}
41
42/// Dispatch a two-operand body over payloads that share one scalar type.
43///
44/// Elementwise storage algebra is only defined for matching scalar kinds, so
45/// the four same-dtype arms are written once and every other combination falls
46/// through to `else <expr>`.
47macro_rules! storage_payload_same_dtype_dispatch {
48    ($left:expr, $right:expr, $ty:ident => |$a:ident, $b:ident| $body:expr, else $fallback:expr) => {
49        match ($left, $right) {
50            (StorageRepr::F32($a), StorageRepr::F32($b)) => {
51                #[allow(unused)] // the body names the payload type only when it needs it
52                type $ty = f32;
53                $body
54            }
55            (StorageRepr::F64($a), StorageRepr::F64($b)) => {
56                #[allow(unused)] // the body names the payload type only when it needs it
57                type $ty = f64;
58                $body
59            }
60            (StorageRepr::C32($a), StorageRepr::C32($b)) => {
61                #[allow(unused)] // the body names the payload type only when it needs it
62                type $ty = Complex32;
63                $body
64            }
65            (StorageRepr::C64($a), StorageRepr::C64($b)) => {
66                #[allow(unused)] // the body names the payload type only when it needs it
67                type $ty = Complex64;
68                $body
69            }
70            _ => $fallback,
71        }
72    };
73}
74
75/// Dispatch a two-payload body over every scalar-type pair.
76///
77/// The nesting is intentional: each payload keeps its own concrete scalar type,
78/// so cross-dtype algebra (mixed promotion) is written once instead of in
79/// sixteen hand-written arms.
80macro_rules! storage_payload_pair_dispatch {
81    ($left:expr, $right:expr, $left_ty:ident, $right_ty:ident => |$a:ident, $b:ident| $body:expr) => {
82        storage_payload_dispatch!($left, $left_ty => |$a| {
83            storage_payload_dispatch!($right, $right_ty => |$b| $body)
84        })
85    };
86}
87
88/// Dispatch a body over a computed result dtype, binding `$ty` to it.
89///
90/// Used where promotion decides the result scalar type before the payload can
91/// be built, so the arithmetic is written once and narrowed or widened by
92/// [`StorageScalar::from_widened_parts`].
93macro_rules! storage_dtype_dispatch {
94    ($dtype:expr, $ty:ident => $body:expr, else $fallback:expr) => {
95        match $dtype {
96            DType::F32 => {
97                #[allow(unused)] // the body names the payload type only when it needs it
98                type $ty = f32;
99                $body
100            }
101            DType::F64 => {
102                #[allow(unused)] // the body names the payload type only when it needs it
103                type $ty = f64;
104                $body
105            }
106            DType::C32 => {
107                #[allow(unused)] // the body names the payload type only when it needs it
108                type $ty = Complex32;
109                $body
110            }
111            DType::C64 => {
112                #[allow(unused)] // the body names the payload type only when it needs it
113                type $ty = Complex64;
114                $body
115            }
116            _ => $fallback,
117        }
118    };
119}
120
121pub(crate) use storage_dtype_dispatch;
122
123/// Named result of a non-finite scan over stored scalar values.
124///
125/// The two flags are independent: a payload can contain both NaN and infinity,
126/// and `Default` is the all-finite result. Use it instead of a positional
127/// `(has_nan, has_infinity)` pair so call sites name the flag they read.
128///
129/// This reports what the scan found; it does not classify, replace, or mask the
130/// values. See [`Storage::payload_nonfinite_flags`] for the compact-payload
131/// scan and `tensor4all_core` for the native-tensor scan over a different
132/// representation.
133///
134/// # Examples
135///
136/// ```
137/// use tensor4all_tensorbackend::NonfiniteFlags;
138///
139/// let finite = NonfiniteFlags::default();
140/// assert!(!finite.has_nan && !finite.has_infinity);
141///
142/// let flags = NonfiniteFlags {
143///     has_nan: true,
144///     has_infinity: false,
145/// };
146/// assert!(flags.has_nan);
147/// assert_ne!(flags, finite);
148/// ```
149#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
150pub struct NonfiniteFlags {
151    /// At least one scanned real or imaginary component is NaN.
152    pub has_nan: bool,
153    /// At least one scanned real or imaginary component is infinite.
154    pub has_infinity: bool,
155}
156
157/// Trait for scalar types that can be stored in [`Storage`].
158///
159/// This enables generic constructors such as [`Storage::from_dense_col_major`]
160/// and [`Storage::from_diag_col_major`], and it is the single seam through
161/// which dtype-erased storage code reaches a concrete payload. Implemented for
162/// `f64`, `Complex64`, `f32`, and `Complex32`.
163///
164/// Compact storage never widens a payload: `f32` stays `f32` and `Complex32`
165/// stays `Complex32` in memory and on every accessor. The associated items
166/// describe the real/complex structure so that dtype-agnostic scans can be
167/// written once; explicit width promotion happens only in the storage algebra
168/// that documents it ([`Storage::axpby`], [`Storage::scale`]).
169///
170/// # Examples
171///
172/// ```
173/// use tensor4all_tensorbackend::{Storage, StorageScalar};
174///
175/// // Using the generic constructor -- scalar type is inferred from data
176/// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0], &[3]).unwrap();
177/// assert!(s.is_f64());
178///
179/// use num_complex::Complex64;
180/// let c = Storage::from_dense_col_major(
181///     vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 1.0)],
182///     &[2],
183/// ).unwrap();
184/// assert!(c.is_c64());
185///
186/// // Narrow payloads keep their dtype instead of widening.
187/// let narrow = Storage::from_dense_col_major(vec![1.0_f32, 2.0], &[2]).unwrap();
188/// assert!(narrow.is_f32());
189/// assert_eq!(f32::KIND, "f32");
190/// assert_eq!(Complex64::KIND, "Complex64");
191/// ```
192pub trait StorageScalar: TensorElement + Default + PartialEq + num_traits::Num {
193    /// Display name of this scalar type in diagnostics (`"f32"`, `"Complex64"`, ...).
194    const KIND: &'static str;
195    /// Whether values carry an imaginary component.
196    const IS_COMPLEX: bool;
197    /// The complex counterpart of this scalar type (`f32` -> `Complex32`).
198    type Complex: StorageScalar;
199
200    /// Widen this value to `(real, imaginary)` parts for dtype-agnostic scans.
201    fn widened_parts(self) -> (f64, f64);
202
203    /// Narrow widened parts back to this scalar type.
204    fn from_widened_parts(re: f64, im: f64) -> Self;
205
206    /// Real part as this scalar's real counterpart.
207    fn real_part(self) -> Self::Real;
208
209    /// Imaginary part as this scalar's real counterpart (`0` for real scalars).
210    fn imag_part(self) -> Self::Real;
211
212    /// Embed this value, including its imaginary part, in [`Self::Complex`].
213    fn into_complex(self) -> Self::Complex;
214
215    /// The complex conjugate (`self` for real scalars).
216    fn conjugate(self) -> Self;
217
218    /// Wrap a compact payload of this scalar type as a [`Storage`].
219    fn wrap_payload(payload: StructuredStorage<Self>) -> Storage;
220
221    /// Copy this value into a dynamic [`BackendScalar`].
222    fn to_backend_scalar(self) -> BackendScalar;
223
224    /// Copy the compact payload of this scalar type, rejecting other dtypes.
225    /// # Errors
226    ///
227    /// Returns [`StorageError::ScalarKindMismatch`] when `storage` holds a
228    /// different scalar type.
229    fn payload_vec(storage: &Storage) -> StorageResult<Vec<Self>>;
230
231    /// Borrow the compact payload of this scalar type when it is contiguous.
232    /// # Errors
233    ///
234    /// Returns [`StorageError::ScalarKindMismatch`] when `storage` holds a
235    /// different scalar type.
236    fn payload_view(storage: &Storage) -> StorageResult<Option<&[Self]>>;
237
238    /// Materialize the logical dense values of this scalar type.
239    /// # Errors
240    ///
241    /// Returns [`StorageError::ScalarKindMismatch`] when `storage` holds a
242    /// different scalar type, and
243    /// [`StorageError::InvalidStructuredStorage`] when `logical_dims` does not
244    /// match the stored logical dimensions or the logical element count
245    /// overflows `usize`.
246    fn dense_values(storage: &Storage, logical_dims: &[usize]) -> StorageResult<Vec<Self>>;
247
248    /// Build a dense [`Storage`] from column-major data.
249    /// # Errors
250    ///
251    /// Returns an error when the shape product would overflow `usize` or
252    /// `data.len()` does not match the expected shape.
253    ///
254    fn build_dense_storage(data: Vec<Self>, logical_dims: &[usize]) -> Result<Storage> {
255        let label = format!("dense {} payload", Self::KIND);
256        Storage::validate_dense_len(&data, logical_dims, &label)?;
257        Ok(Self::wrap_payload(StructuredStorage::from_dense_col_major(
258            data,
259            logical_dims,
260        )?))
261    }
262    /// Build a diagonal [`Storage`] from diagonal payload data.
263    /// # Errors
264    ///
265    /// Returns an error when the diagonal payload length does not match the
266    /// length required for `logical_rank` or a stride product would overflow
267    /// `usize`.
268    ///
269    fn build_diag_storage(diag_data: Vec<Self>, logical_rank: usize) -> Result<Storage> {
270        Ok(Self::wrap_payload(StructuredStorage::from_diag_col_major(
271            diag_data,
272            logical_rank,
273        )?))
274    }
275    /// Build a structured [`Storage`] from explicit payload metadata.
276    /// # Errors
277    ///
278    /// Returns an error when `axis_classes` is not in canonical
279    /// first-appearance order, when the `payload_dims` or `strides` ranks do
280    /// not match `axis_classes`, when a stride is negative, when a size
281    /// product would overflow `usize`, or when `data.len()` does not match the
282    /// required payload length.
283    ///
284    fn build_structured_storage(
285        data: Vec<Self>,
286        payload_dims: Vec<usize>,
287        strides: Vec<isize>,
288        axis_classes: Vec<usize>,
289    ) -> Result<Storage> {
290        Ok(Self::wrap_payload(StructuredStorage::new(
291            data,
292            payload_dims,
293            strides,
294            axis_classes,
295        )?))
296    }
297}
298
299/// Implement [`StorageScalar`] for one concrete scalar type.
300///
301/// Only the per-dtype algebra (real/imaginary extraction, complex embedding,
302/// conjugation, widening) is spelled per type; payload construction and
303/// dispatch are shared.
304macro_rules! impl_storage_scalar {
305    ($ty:ty, $variant:ident, $complex:ty, $kind:literal, $is_complex:literal,
306     copy_operation: $copy_operation:literal, view_operation: $view_operation:literal,
307     dense_operation: $dense_operation:literal,
308     widened: $widened:expr, from_widened: $from_widened:expr,
309     real: $real:expr, imag: $imag:expr, into_complex: $into_complex:expr,
310     conj: $conj:expr) => {
311        impl StorageScalar for $ty {
312            const KIND: &'static str = $kind;
313            const IS_COMPLEX: bool = $is_complex;
314            type Complex = $complex;
315
316            fn widened_parts(self) -> (f64, f64) {
317                ($widened)(self)
318            }
319
320            fn from_widened_parts(re: f64, im: f64) -> Self {
321                ($from_widened)(re, im)
322            }
323
324            fn real_part(self) -> Self::Real {
325                ($real)(self)
326            }
327
328            fn imag_part(self) -> Self::Real {
329                ($imag)(self)
330            }
331
332            fn into_complex(self) -> Self::Complex {
333                ($into_complex)(self)
334            }
335
336            fn conjugate(self) -> Self {
337                ($conj)(self)
338            }
339
340            fn wrap_payload(payload: StructuredStorage<Self>) -> Storage {
341                Storage(StorageRepr::$variant(payload))
342            }
343
344            fn to_backend_scalar(self) -> BackendScalar {
345                BackendScalar::from_value(self)
346            }
347
348            fn payload_vec(storage: &Storage) -> StorageResult<Vec<Self>> {
349                match &storage.0 {
350                    StorageRepr::$variant(payload) => Ok(payload.payload_col_major_vec()),
351                    _ => Err(StorageError::ScalarKindMismatch {
352                        expected: Self::KIND,
353                        actual: storage.scalar_kind(),
354                        operation: $copy_operation,
355                    }),
356                }
357            }
358
359            fn payload_view(storage: &Storage) -> StorageResult<Option<&[Self]>> {
360                match &storage.0 {
361                    StorageRepr::$variant(payload) => {
362                        Ok(payload.payload_col_major_view_if_contiguous())
363                    }
364                    _ => Err(StorageError::ScalarKindMismatch {
365                        expected: Self::KIND,
366                        actual: storage.scalar_kind(),
367                        operation: $view_operation,
368                    }),
369                }
370            }
371
372            fn dense_values(storage: &Storage, logical_dims: &[usize]) -> StorageResult<Vec<Self>> {
373                match &storage.0 {
374                    StorageRepr::$variant(payload) => checked_dense_payload(payload, logical_dims),
375                    _ => Err(StorageError::ScalarKindMismatch {
376                        expected: Self::KIND,
377                        actual: storage.scalar_kind(),
378                        operation: $dense_operation,
379                    }),
380                }
381            }
382        }
383    };
384}
385
386impl_storage_scalar!(
387    f32,
388    F32,
389    Complex32,
390    "f32",
391    false,
392    copy_operation: "copying f32 payload",
393    view_operation: "borrowing f32 payload",
394    dense_operation: "materializing dense f32 values",
395    widened: |value: f32| (f64::from(value), 0.0),
396    from_widened: |re: f64, _im: f64| re as f32,
397    real: |value: f32| value,
398    imag: |_value: f32| 0.0,
399    into_complex: |value: f32| Complex32::new(value, 0.0),
400    conj: |value: f32| value
401);
402
403impl_storage_scalar!(
404    f64,
405    F64,
406    Complex64,
407    "f64",
408    false,
409    copy_operation: "copying f64 payload",
410    view_operation: "borrowing f64 payload",
411    dense_operation: "materializing dense f64 values",
412    widened: |value: f64| (value, 0.0),
413    from_widened: |re: f64, _im: f64| re,
414    real: |value: f64| value,
415    imag: |_value: f64| 0.0,
416    into_complex: |value: f64| Complex64::new(value, 0.0),
417    conj: |value: f64| value
418);
419
420impl_storage_scalar!(
421    Complex32,
422    C32,
423    Complex32,
424    "Complex32",
425    true,
426    copy_operation: "copying c32 payload",
427    view_operation: "borrowing c32 payload",
428    dense_operation: "materializing dense c32 values",
429    widened: |value: Complex32| (f64::from(value.re), f64::from(value.im)),
430    from_widened: |re: f64, im: f64| Complex32::new(re as f32, im as f32),
431    real: |value: Complex32| value.re,
432    imag: |value: Complex32| value.im,
433    into_complex: |value: Complex32| value,
434    conj: |value: Complex32| value.conj()
435);
436
437impl_storage_scalar!(
438    Complex64,
439    C64,
440    Complex64,
441    "Complex64",
442    true,
443    copy_operation: "copying c64 payload",
444    view_operation: "borrowing c64 payload",
445    dense_operation: "materializing dense c64 values",
446    widened: |value: Complex64| (value.re, value.im),
447    from_widened: |re: f64, im: f64| Complex64::new(re, im),
448    real: |value: Complex64| value.re,
449    imag: |value: Complex64| value.im,
450    into_complex: |value: Complex64| value,
451    conj: |value: Complex64| value.conj()
452);
453
454pub(crate) fn col_major_strides(dims: &[usize]) -> Result<Vec<isize>> {
455    let mut strides = Vec::with_capacity(dims.len());
456    let mut stride = 1isize;
457    for &dim in dims {
458        strides.push(stride);
459        let dim = isize::try_from(dim)
460            .map_err(|_| anyhow!("column-major stride overflow for dims {dims:?}"))?;
461        stride = stride
462            .checked_mul(dim)
463            .ok_or_else(|| anyhow!("column-major stride overflow for dims {dims:?}"))?;
464    }
465    Ok(strides)
466}
467
468/// Whether `strides` are already the column-major strides of `dims`.
469///
470/// Same answer as comparing against [`col_major_strides`], without the temporary
471/// stride vector: the contiguous-view accessors run on every borrowed payload
472/// read, and a temporary allocation there defeats the point of a borrow.
473fn has_col_major_strides(dims: &[usize], strides: &[isize]) -> bool {
474    if dims.len() != strides.len() {
475        return false;
476    }
477    let mut expected = 1isize;
478    for (&dim, &stride) in dims.iter().zip(strides) {
479        if stride != expected {
480            return false;
481        }
482        let Ok(dim) = isize::try_from(dim) else {
483            return false;
484        };
485        let Some(next) = expected.checked_mul(dim) else {
486            return false;
487        };
488        expected = next;
489    }
490    true
491}
492
493fn validate_canonical_axis_classes(axis_classes: &[usize]) -> Result<()> {
494    let mut next_class = 0usize;
495    for &class_id in axis_classes {
496        ensure!(
497            class_id <= next_class,
498            "axis_classes must be canonical first-appearance labels, got {axis_classes:?}"
499        );
500        if class_id == next_class {
501            next_class = next_class
502                .checked_add(1)
503                .ok_or_else(|| anyhow!("axis class index overflow"))?;
504        }
505    }
506    Ok(())
507}
508
509fn required_storage_len(dims: &[usize], strides: &[isize]) -> Result<usize> {
510    ensure!(
511        dims.len() == strides.len(),
512        "payload dims {:?} and strides {:?} must have the same rank",
513        dims,
514        strides
515    );
516
517    // Validate the compact payload product even when a zero stride would make
518    // the referenced backing span look small. Iteration must never begin with
519    // a wrapped payload length.
520    let payload_len = dims.iter().try_fold(1usize, |length, &dim| {
521        length
522            .checked_mul(dim)
523            .ok_or_else(|| anyhow!("payload length overflow for dims {dims:?}"))
524    })?;
525
526    let mut max_offset = 0usize;
527    for (&dim, &stride) in dims.iter().zip(strides.iter()) {
528        ensure!(
529            stride >= 0,
530            "negative strides are not supported in StructuredStorage: {strides:?}"
531        );
532        let stride = usize::try_from(stride)
533            .map_err(|_| anyhow!("payload stride overflow for dims {dims:?}"))?;
534        if dim > 1 {
535            let span = (dim - 1)
536                .checked_mul(stride)
537                .ok_or_else(|| anyhow!("payload stride overflow for dims {dims:?}"))?;
538            max_offset = max_offset
539                .checked_add(span)
540                .ok_or_else(|| anyhow!("payload stride overflow for dims {dims:?}"))?;
541        }
542    }
543    if payload_len == 0 {
544        return Ok(0);
545    }
546    max_offset
547        .checked_add(1)
548        .ok_or_else(|| anyhow!("payload stride overflow for dims {dims:?}"))
549}
550
551fn logical_dims_from_axis_classes(payload_dims: &[usize], axis_classes: &[usize]) -> Vec<usize> {
552    axis_classes
553        .iter()
554        .map(|&class_id| payload_dims[class_id])
555        .collect()
556}
557
558fn col_major_multi_index(mut linear: usize, dims: &[usize]) -> Vec<usize> {
559    let mut index = Vec::with_capacity(dims.len());
560    for &dim in dims {
561        if dim == 0 {
562            index.push(0);
563        } else {
564            index.push(linear % dim);
565            linear /= dim;
566        }
567    }
568    index
569}
570
571fn offset_from_strides(index: &[usize], strides: &[isize]) -> Option<usize> {
572    index
573        .iter()
574        .zip(strides.iter())
575        .try_fold(0usize, |offset, (&value, &stride)| {
576            let stride = usize::try_from(stride).ok()?;
577            let term = value.checked_mul(stride)?;
578            offset.checked_add(term)
579        })
580}
581
582/// Structured tensor snapshot storage.
583///
584/// `data` and `strides` describe the payload tensor, while `axis_classes`
585/// describes how logical axes map onto payload axes. Logical flat-buffer
586/// semantics are column-major. A strided payload may contain unused backing
587/// gaps; reductions and nonfinite scans visit only entries addressed by the
588/// payload dimensions and strides.
589///
590/// A **dense** tensor has `axis_classes = [0, 1, ..., rank-1]` (each logical
591/// axis maps to a distinct payload axis). A **diagonal** tensor has
592/// `axis_classes = [0, 0, ..., 0]` (all logical axes share one payload axis),
593/// storing only the diagonal entries.
594///
595/// # Examples
596///
597/// ```
598/// use tensor4all_tensorbackend::StructuredStorage;
599///
600/// // Dense 2x3 storage, column-major: [[1,3,5],[2,4,6]]
601/// let dense = StructuredStorage::from_dense_col_major(
602///     vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3],
603/// ).unwrap();
604/// assert!(dense.is_dense());
605/// assert!(!dense.is_diag());
606/// assert_eq!(dense.logical_rank(), 2);
607/// assert_eq!(dense.logical_dims(), vec![2, 3]);
608///
609/// // Diagonal 3x3 storage
610/// let diag = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 2).unwrap();
611/// assert!(diag.is_diag());
612/// assert_eq!(diag.logical_dims(), vec![3, 3]);
613/// assert_eq!(diag.len(), 3);
614/// ```
615#[derive(Debug, Clone, PartialEq)]
616pub struct StructuredStorage<T> {
617    data: Vec<T>,
618    payload_dims: Vec<usize>,
619    strides: Vec<isize>,
620    axis_classes: Vec<usize>,
621}
622
623impl<T> StructuredStorage<T> {
624    /// Creates a structured payload snapshot from explicit payload metadata.
625    ///
626    /// `payload_dims` and `strides` describe the compressed payload tensor,
627    /// while `axis_classes` maps logical axes onto payload axes in canonical
628    /// first-appearance order.
629    ///
630    /// # Errors
631    ///
632    /// Returns an error if:
633    /// - `axis_classes` is not in canonical first-appearance form
634    /// - `payload_dims` rank does not match `axis_classes`
635    /// - `strides` rank does not match `payload_dims`
636    /// - `data` length does not match the required storage length
637    ///
638    /// # Examples
639    ///
640    /// ```
641    /// use tensor4all_tensorbackend::StructuredStorage;
642    ///
643    /// // Dense 2x3 with explicit column-major strides
644    /// let s = StructuredStorage::new(
645    ///     vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
646    ///     vec![2, 3],     // payload_dims
647    ///     vec![1, 2],     // column-major strides
648    ///     vec![0, 1],     // axis_classes: each axis is independent
649    /// ).unwrap();
650    /// assert!(s.is_dense());
651    /// assert_eq!(s.len(), 6);
652    /// ```
653    pub fn new(
654        data: Vec<T>,
655        payload_dims: Vec<usize>,
656        strides: Vec<isize>,
657        axis_classes: Vec<usize>,
658    ) -> Result<Self> {
659        let required_len =
660            Storage::validate_structured_metadata(&payload_dims, &strides, &axis_classes)?;
661        ensure!(
662            data.len() == required_len,
663            "payload storage len {} does not match required len {} for dims {:?} and strides {:?}",
664            data.len(),
665            required_len,
666            payload_dims,
667            strides
668        );
669        Ok(Self {
670            data,
671            payload_dims,
672            strides,
673            axis_classes,
674        })
675    }
676
677    /// Creates a dense structured snapshot from column-major logical data.
678    ///
679    /// # Errors
680    ///
681    /// Returns [`StorageError::Operation`] when a column-major stride overflows
682    /// `usize` or when the payload length does not match `logical_dims`.
683    ///
684    /// # Examples
685    ///
686    /// ```
687    /// use tensor4all_tensorbackend::StructuredStorage;
688    ///
689    /// let s = StructuredStorage::from_dense_col_major(vec![10.0, 20.0, 30.0, 40.0], &[2, 2]).unwrap();
690    /// assert!(s.is_dense());
691    /// assert_eq!(s.data(), &[10.0, 20.0, 30.0, 40.0]);
692    /// ```
693    pub fn from_dense_col_major(data: Vec<T>, logical_dims: &[usize]) -> StorageResult<Self> {
694        let payload_dims = logical_dims.to_vec();
695        let strides = col_major_strides(&payload_dims)?;
696        let axis_classes = (0..logical_dims.len()).collect();
697        Self::new(data, payload_dims, strides, axis_classes).map_err(StorageError::from)
698    }
699
700    /// Creates a diagonal structured snapshot from column-major diagonal data.
701    ///
702    /// The resulting tensor has `logical_rank` axes, each of size `diag_data.len()`.
703    /// Only the diagonal entries are stored.
704    ///
705    /// # Errors
706    ///
707    /// Returns [`StorageError::Operation`] when a stride product overflows
708    /// `usize` or when the required payload length does not match
709    /// `diag_data.len()`.
710    ///
711    /// # Examples
712    ///
713    /// ```
714    /// use tensor4all_tensorbackend::StructuredStorage;
715    ///
716    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 2).unwrap();
717    /// assert!(d.is_diag());
718    /// assert_eq!(d.logical_dims(), vec![3, 3]);
719    /// assert_eq!(d.data(), &[1.0, 2.0, 3.0]);
720    /// ```
721    pub fn from_diag_col_major(diag_data: Vec<T>, logical_rank: usize) -> StorageResult<Self> {
722        let payload_dims = if logical_rank == 0 {
723            vec![]
724        } else {
725            vec![diag_data.len()]
726        };
727        let strides = col_major_strides(&payload_dims)?;
728        let axis_classes = vec![0; logical_rank];
729        Self::new(diag_data, payload_dims, strides, axis_classes).map_err(StorageError::from)
730    }
731
732    /// Returns the payload data buffer as a slice.
733    ///
734    /// # Examples
735    ///
736    /// ```
737    /// use tensor4all_tensorbackend::StructuredStorage;
738    ///
739    /// let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0], &[2]).unwrap();
740    /// assert_eq!(s.data(), &[1.0, 2.0]);
741    /// ```
742    pub fn data(&self) -> &[T] {
743        &self.data
744    }
745
746    /// Returns the payload tensor dimensions.
747    ///
748    /// For dense tensors, this equals the logical dimensions. For diagonal
749    /// tensors, this is a single-element slice `[n]` where `n` is the diagonal
750    /// length.
751    ///
752    /// # Examples
753    ///
754    /// ```
755    /// use tensor4all_tensorbackend::StructuredStorage;
756    ///
757    /// let s = StructuredStorage::from_dense_col_major(vec![0.0; 6], &[2, 3]).unwrap();
758    /// assert_eq!(s.payload_dims(), &[2, 3]);
759    ///
760    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 3).unwrap();
761    /// assert_eq!(d.payload_dims(), &[2]);
762    /// ```
763    pub fn payload_dims(&self) -> &[usize] {
764        &self.payload_dims
765    }
766
767    /// Returns the payload tensor strides.
768    ///
769    /// # Examples
770    ///
771    /// ```
772    /// use tensor4all_tensorbackend::StructuredStorage;
773    ///
774    /// // Column-major 2x3: strides are [1, 2]
775    /// let s = StructuredStorage::from_dense_col_major(vec![0.0; 6], &[2, 3]).unwrap();
776    /// assert_eq!(s.strides(), &[1, 2]);
777    /// ```
778    pub fn strides(&self) -> &[isize] {
779        &self.strides
780    }
781
782    /// Returns the canonical logical-to-payload axis classes.
783    ///
784    /// Each entry maps a logical axis to a payload axis index. Repeated values
785    /// indicate axes that share the same payload dimension (e.g., diagonal).
786    ///
787    /// # Examples
788    ///
789    /// ```
790    /// use tensor4all_tensorbackend::StructuredStorage;
791    ///
792    /// let dense = StructuredStorage::from_dense_col_major(vec![0.0; 4], &[2, 2]).unwrap();
793    /// assert_eq!(dense.axis_classes(), &[0, 1]);
794    ///
795    /// let diag = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
796    /// assert_eq!(diag.axis_classes(), &[0, 0]);
797    /// ```
798    pub fn axis_classes(&self) -> &[usize] {
799        &self.axis_classes
800    }
801
802    /// Returns the logical dimensions derived from `payload_dims` and `axis_classes`.
803    ///
804    /// # Examples
805    ///
806    /// ```
807    /// use tensor4all_tensorbackend::StructuredStorage;
808    ///
809    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 3).unwrap();
810    /// assert_eq!(d.logical_dims(), vec![3, 3, 3]);
811    /// ```
812    pub fn logical_dims(&self) -> Vec<usize> {
813        logical_dims_from_axis_classes(&self.payload_dims, &self.axis_classes)
814    }
815
816    /// Returns the logical rank (number of logical axes).
817    ///
818    /// # Examples
819    ///
820    /// ```
821    /// use tensor4all_tensorbackend::StructuredStorage;
822    ///
823    /// let s = StructuredStorage::from_dense_col_major(vec![0.0; 6], &[2, 3]).unwrap();
824    /// assert_eq!(s.logical_rank(), 2);
825    /// ```
826    pub fn logical_rank(&self) -> usize {
827        self.axis_classes.len()
828    }
829
830    /// Returns `true` when the logical tensor is dense (each logical axis maps
831    /// to a unique payload axis).
832    ///
833    /// # Examples
834    ///
835    /// ```
836    /// use tensor4all_tensorbackend::StructuredStorage;
837    ///
838    /// let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0], &[2]).unwrap();
839    /// assert!(s.is_dense());
840    ///
841    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
842    /// assert!(!d.is_dense());
843    /// ```
844    pub fn is_dense(&self) -> bool {
845        self.axis_classes
846            .iter()
847            .copied()
848            .eq(0..self.axis_classes.len())
849    }
850
851    /// Returns `true` when the logical tensor is diagonal (rank >= 2 and all
852    /// logical axes map to the same payload axis).
853    ///
854    /// # Examples
855    ///
856    /// ```
857    /// use tensor4all_tensorbackend::StructuredStorage;
858    ///
859    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
860    /// assert!(d.is_diag());
861    ///
862    /// let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0], &[2]).unwrap();
863    /// assert!(!s.is_diag());
864    /// ```
865    pub fn is_diag(&self) -> bool {
866        self.logical_rank() >= 2 && self.axis_classes.iter().all(|&class_id| class_id == 0)
867    }
868
869    /// Returns the payload buffer length.
870    ///
871    /// # Examples
872    ///
873    /// ```
874    /// use tensor4all_tensorbackend::StructuredStorage;
875    ///
876    /// let dense = StructuredStorage::from_dense_col_major(vec![1.0, 2.0, 3.0], &[3]).unwrap();
877    /// assert_eq!(dense.len(), 3);
878    ///
879    /// let diag = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
880    /// assert_eq!(diag.len(), 2);
881    /// ```
882    pub fn len(&self) -> usize {
883        self.data.len()
884    }
885
886    /// Returns `true` when the payload buffer is empty.
887    ///
888    /// # Examples
889    ///
890    /// ```
891    /// use tensor4all_tensorbackend::StructuredStorage;
892    ///
893    /// let empty = StructuredStorage::from_dense_col_major(Vec::<f64>::new(), &[0]).unwrap();
894    /// assert!(empty.is_empty());
895    ///
896    /// let non_empty = StructuredStorage::from_dense_col_major(vec![1.0], &[1]).unwrap();
897    /// assert!(!non_empty.is_empty());
898    /// ```
899    pub fn is_empty(&self) -> bool {
900        self.data.is_empty()
901    }
902
903    /// Returns a borrowed view when the logical tensor is dense and the
904    /// payload is already stored contiguously in column-major order.
905    ///
906    /// Returns `None` for diagonal or non-contiguous payloads.
907    ///
908    /// # Examples
909    ///
910    /// ```
911    /// use tensor4all_tensorbackend::StructuredStorage;
912    ///
913    /// let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0, 3.0], &[3]).unwrap();
914    /// assert_eq!(s.dense_col_major_view_if_contiguous(), Some(&[1.0, 2.0, 3.0][..]));
915    ///
916    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
917    /// assert_eq!(d.dense_col_major_view_if_contiguous(), None);
918    /// ```
919    pub fn dense_col_major_view_if_contiguous(&self) -> Option<&[T]> {
920        if self.is_dense() && has_col_major_strides(&self.payload_dims, &self.strides) {
921            Some(&self.data)
922        } else {
923            None
924        }
925    }
926
927    /// Returns a borrowed compact-payload view when the payload is already
928    /// stored contiguously in column-major order.
929    pub fn payload_col_major_view_if_contiguous(&self) -> Option<&[T]> {
930        if has_col_major_strides(&self.payload_dims, &self.strides) {
931            Some(&self.data)
932        } else {
933            None
934        }
935    }
936}
937
938impl<T: Clone> StructuredStorage<T> {
939    /// Materializes the payload tensor as a contiguous column-major buffer.
940    ///
941    /// If the payload is already column-major, returns a clone.
942    ///
943    /// # Examples
944    ///
945    /// ```
946    /// use tensor4all_tensorbackend::StructuredStorage;
947    ///
948    /// let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
949    /// assert_eq!(s.payload_col_major_vec(), vec![1.0, 2.0, 3.0, 4.0]);
950    /// ```
951    pub fn payload_col_major_vec(&self) -> Vec<T> {
952        let payload_len = self
953            .payload_dims
954            .iter()
955            .try_fold(1usize, |length, &dim| length.checked_mul(dim))
956            // `StructuredStorage::new` validates this invariant before any
957            // instance can be constructed; return an empty vector rather than
958            // wrapping if an invalid value ever reaches this private state.
959            .unwrap_or(0);
960        if payload_len == 0 {
961            return Vec::new();
962        }
963        if has_col_major_strides(&self.payload_dims, &self.strides) {
964            return self.data.clone();
965        }
966
967        let mut output = Vec::with_capacity(payload_len);
968        for linear in 0..payload_len {
969            let index = col_major_multi_index(linear, &self.payload_dims);
970            let Some(offset) = offset_from_strides(&index, &self.strides) else {
971                return Vec::new();
972            };
973            output.push(self.data[offset].clone());
974        }
975        output
976    }
977
978    /// Returns a copy of the storage with logical axes permuted.
979    ///
980    /// # Errors
981    ///
982    /// Returns [`StorageError::Operation`] when `perm` is not a permutation of
983    /// the logical axes.
984    ///
985    /// # Examples
986    ///
987    /// ```
988    /// use tensor4all_tensorbackend::StructuredStorage;
989    ///
990    /// // Diagonal 3x3x3 tensor; permute axes (identity for diag is always valid)
991    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 3).unwrap();
992    /// let p = d.permute_logical_axes(&[2, 0, 1]).unwrap();
993    /// // Diagonal: all axes share the same dimension, so dims stay the same
994    /// assert_eq!(p.logical_dims(), vec![3, 3, 3]);
995    /// assert!(p.is_diag());
996    /// ```
997    pub fn permute_logical_axes(&self, perm: &[usize]) -> StorageResult<Self> {
998        if perm.len() != self.axis_classes.len() {
999            return Err(StorageError::from(anyhow::anyhow!(
1000                "logical permutation length {} must match logical rank {}",
1001                perm.len(),
1002                self.axis_classes.len()
1003            )));
1004        }
1005        let mut seen = vec![false; self.axis_classes.len()];
1006        let axis_classes = perm
1007            .iter()
1008            .map(|&index| {
1009                if index >= self.axis_classes.len() {
1010                    return Err(anyhow::anyhow!(
1011                        "logical permutation axis {index} is out of range for rank {}",
1012                        self.axis_classes.len()
1013                    ));
1014                }
1015                if seen[index] {
1016                    return Err(anyhow::anyhow!("logical permutation repeats axis {index}"));
1017                }
1018                seen[index] = true;
1019                Ok(self.axis_classes[index])
1020            })
1021            .collect::<Result<Vec<_>>>()
1022            .map_err(StorageError::from)?;
1023        Self::new(
1024            self.data.clone(),
1025            self.payload_dims.clone(),
1026            self.strides.clone(),
1027            axis_classes,
1028        )
1029        .map_err(StorageError::from)
1030    }
1031}
1032
1033impl<T: Copy> StructuredStorage<T> {
1034    /// Wrap this payload as a compact [`Storage`] of the same scalar type.
1035    ///
1036    /// The payload keeps its dtype and metadata; nothing is widened or
1037    /// re-ordered. This is the construction seam used by dtype-generic storage
1038    /// algebra so each operation returns storage of its own scalar type.
1039    ///
1040    /// # Examples
1041    ///
1042    /// ```
1043    /// use tensor4all_tensorbackend::StructuredStorage;
1044    ///
1045    /// let payload = StructuredStorage::from_dense_col_major(vec![1.0_f32, 2.0], &[2]).unwrap();
1046    /// let storage = payload.into_storage();
1047    /// assert!(storage.is_f32());
1048    /// assert_eq!(storage.len(), 2);
1049    /// ```
1050    pub fn into_storage(self) -> Storage
1051    where
1052        T: StorageScalar,
1053    {
1054        T::wrap_payload(self)
1055    }
1056
1057    fn payload_scalar_at(&self, payload_coords: &[usize]) -> StorageResult<T> {
1058        if payload_coords.len() != self.payload_dims.len() {
1059            return Err(StorageError::InvalidStructuredStorage(format!(
1060                "payload coordinate rank {} does not match payload rank {}",
1061                payload_coords.len(),
1062                self.payload_dims.len()
1063            )));
1064        }
1065        let offset = payload_coords
1066            .iter()
1067            .zip(self.payload_dims.iter())
1068            .zip(self.strides.iter())
1069            .try_fold(0usize, |offset, ((&coordinate, &dim), &stride)| {
1070                if coordinate >= dim {
1071                    return Err(StorageError::InvalidStructuredStorage(format!(
1072                        "payload coordinate {coordinate} is out of bounds for dim {dim}"
1073                    )));
1074                }
1075                let stride = usize::try_from(stride).map_err(|_| {
1076                    StorageError::InvalidStructuredStorage("negative stride".into())
1077                })?;
1078                let term = coordinate.checked_mul(stride).ok_or_else(|| {
1079                    StorageError::InvalidStructuredStorage("payload offset overflow".into())
1080                })?;
1081                offset.checked_add(term).ok_or_else(|| {
1082                    StorageError::InvalidStructuredStorage("payload offset overflow".into())
1083                })
1084            })?;
1085        self.data.get(offset).copied().ok_or_else(|| {
1086            StorageError::InvalidStructuredStorage("payload offset outside storage".into())
1087        })
1088    }
1089
1090    /// Maps payload elements while preserving payload metadata and axis classes.
1091    ///
1092    /// # Examples
1093    ///
1094    /// ```
1095    /// use tensor4all_tensorbackend::StructuredStorage;
1096    ///
1097    /// let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0, 3.0], &[3]).unwrap();
1098    /// let doubled = s.map_copy(|x| x * 2.0);
1099    /// assert_eq!(doubled.data(), &[2.0, 4.0, 6.0]);
1100    /// ```
1101    pub fn map_copy<U>(&self, mut f: impl FnMut(T) -> U) -> StructuredStorage<U> {
1102        StructuredStorage {
1103            data: self.data.iter().copied().map(&mut f).collect(),
1104            payload_dims: self.payload_dims.clone(),
1105            strides: self.strides.clone(),
1106            axis_classes: self.axis_classes.clone(),
1107        }
1108    }
1109}
1110
1111impl<T: Copy + Default> StructuredStorage<T> {
1112    /// Returns the checked product of the logical dimensions, rejecting
1113    /// overflow. The fallible dense exporters rely on this so that a logical
1114    /// product that overflows `usize` fails closed instead of being treated
1115    /// as an empty tensor.
1116    fn checked_logical_len(&self) -> StorageResult<usize> {
1117        let dims = self.logical_dims();
1118        dims.iter()
1119            .try_fold(1usize, |length, &dim| length.checked_mul(dim))
1120            .ok_or_else(|| {
1121                StorageError::InvalidStructuredStorage(format!(
1122                    "logical dims product overflow for {dims:?}"
1123                ))
1124            })
1125    }
1126
1127    /// Materializes the logical tensor as a contiguous column-major dense buffer.
1128    ///
1129    /// Repeated entries in `axis_classes` encode equality constraints between
1130    /// logical axes. Logical indices that violate those constraints are
1131    /// structural zeros in the dense materialization.
1132    ///
1133    /// # Errors
1134    ///
1135    /// Returns [`StorageError::InvalidStructuredStorage`] if the logical
1136    /// dimension product overflows `usize`.
1137    ///
1138    /// # Examples
1139    ///
1140    /// ```
1141    /// use tensor4all_tensorbackend::StructuredStorage;
1142    ///
1143    /// // Diagonal [1, 2] in 2x2 becomes [1, 0, 0, 2] column-major
1144    /// let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
1145    /// assert_eq!(d.logical_dense_col_major_vec().unwrap(), vec![1.0, 0.0, 0.0, 2.0]);
1146    /// ```
1147    pub fn logical_dense_col_major_vec(&self) -> StorageResult<Vec<T>> {
1148        let logical_dims = self.logical_dims();
1149        let logical_len = self.checked_logical_len()?;
1150        if logical_len == 0 {
1151            return Ok(Vec::new());
1152        }
1153        if let Some(view) = self.dense_col_major_view_if_contiguous() {
1154            return Ok(view.to_vec());
1155        }
1156        if self.is_dense() {
1157            return Ok(self.payload_col_major_vec());
1158        }
1159
1160        let mut payload_index = vec![0usize; self.payload_dims.len()];
1161        Ok((0..logical_len)
1162            .map(|linear| {
1163                let logical_index = col_major_multi_index(linear, &logical_dims);
1164                self.value_at_with_dims(&logical_index, &logical_dims, &mut payload_index)
1165                    .unwrap_or_default()
1166            })
1167            .collect())
1168    }
1169
1170    fn for_each_payload_value(&self, mut f: impl FnMut(T)) {
1171        if let Some(view) = self.payload_col_major_view_if_contiguous() {
1172            for &value in view {
1173                f(value);
1174            }
1175            return;
1176        }
1177        let payload_len = self
1178            .payload_dims
1179            .iter()
1180            .try_fold(1usize, |length, &dim| length.checked_mul(dim))
1181            .unwrap_or(0);
1182        let mut payload_index = vec![0usize; self.payload_dims.len()];
1183        for _ in 0..payload_len {
1184            let Some(offset) = offset_from_strides(&payload_index, &self.strides) else {
1185                return;
1186            };
1187            f(self.data[offset]);
1188            let mut carry = true;
1189            for (coordinate, &dim) in payload_index.iter_mut().zip(self.payload_dims.iter()) {
1190                if !carry {
1191                    break;
1192                }
1193                *coordinate += 1;
1194                if *coordinate == dim {
1195                    *coordinate = 0;
1196                } else {
1197                    carry = false;
1198                }
1199            }
1200        }
1201    }
1202
1203    fn value_at_with_dims(
1204        &self,
1205        logical_index: &[usize],
1206        logical_dims: &[usize],
1207        payload_index: &mut [usize],
1208    ) -> StorageResult<T> {
1209        if logical_index.len() != logical_dims.len() {
1210            return Err(StorageError::InvalidStructuredStorage(format!(
1211                "logical index rank {} does not match rank {}",
1212                logical_index.len(),
1213                logical_dims.len()
1214            )));
1215        }
1216        if payload_index.len() < self.payload_dims.len() {
1217            return Err(StorageError::InvalidStructuredStorage(format!(
1218                "payload scratch rank {} is smaller than {}",
1219                payload_index.len(),
1220                self.payload_dims.len()
1221            )));
1222        }
1223        payload_index[..self.payload_dims.len()].fill(usize::MAX);
1224        for ((&value, &dim), &class_id) in logical_index
1225            .iter()
1226            .zip(logical_dims.iter())
1227            .zip(self.axis_classes.iter())
1228        {
1229            if value >= dim {
1230                return Err(StorageError::InvalidStructuredStorage(format!(
1231                    "logical index {value} is out of bounds for dim {dim}"
1232                )));
1233            }
1234            if payload_index[class_id] == usize::MAX {
1235                payload_index[class_id] = value;
1236            } else if payload_index[class_id] != value {
1237                return Ok(T::default());
1238            }
1239        }
1240        let offset = payload_index[..self.payload_dims.len()]
1241            .iter()
1242            .zip(self.strides.iter())
1243            .try_fold(0usize, |offset, (&value, &stride)| {
1244                let stride = usize::try_from(stride).map_err(|_| {
1245                    StorageError::InvalidStructuredStorage("negative stride".into())
1246                })?;
1247                let term = value.checked_mul(stride).ok_or_else(|| {
1248                    StorageError::InvalidStructuredStorage("payload offset overflow".into())
1249                })?;
1250                offset.checked_add(term).ok_or_else(|| {
1251                    StorageError::InvalidStructuredStorage("payload offset overflow".into())
1252                })
1253            })?;
1254        self.data.get(offset).copied().ok_or_else(|| {
1255            StorageError::InvalidStructuredStorage("payload offset outside storage".into())
1256        })
1257    }
1258}
1259
1260/// Storage backend for tensor data.
1261///
1262/// Public callers interact with this opaque wrapper through constructors and
1263/// high-level query/materialization methods.
1264///
1265/// # Examples
1266///
1267/// ```
1268/// use tensor4all_tensorbackend::Storage;
1269///
1270/// // Dense 2x3 matrix stored column-major: [[1,2,3],[4,5,6]]
1271/// let data = vec![1.0_f64, 4.0, 2.0, 5.0, 3.0, 6.0];
1272/// let s = Storage::from_dense_col_major(data, &[2, 3]).unwrap();
1273/// assert!(s.is_f64());
1274/// assert!(!s.is_complex());
1275///
1276/// // Diagonal storage: 2x2 identity-like diagonal
1277/// let diag = Storage::new_diag(vec![1.0_f64, 2.0]).unwrap();
1278/// assert!(diag.is_f64());
1279/// ```
1280#[derive(Debug, Clone)]
1281pub struct Storage(pub(crate) StorageRepr);
1282
1283/// Classifies the compact layout used by [`Storage`].
1284///
1285/// Use this to distinguish dense logical payloads from diagonal/copy payloads
1286/// and general structured payloads without exposing the internal storage enum.
1287///
1288/// # Examples
1289///
1290/// ```
1291/// use tensor4all_tensorbackend::{Storage, StorageKind};
1292///
1293/// let dense = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
1294/// assert_eq!(dense.storage_kind(), StorageKind::Dense);
1295///
1296/// let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
1297/// assert_eq!(diag.storage_kind(), StorageKind::Diagonal);
1298/// ```
1299#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1300pub enum StorageKind {
1301    /// Logical dense payload layout.
1302    Dense,
1303    /// Diagonal or copy-tensor payload layout.
1304    Diagonal,
1305    /// General structured payload layout with repeated axis classes.
1306    Structured,
1307}
1308
1309/// Errors returned by storage payload and elementwise operations.
1310///
1311/// Use this to distinguish scalar-kind mismatches, length mismatches, and
1312/// invalid structured-storage metadata from general backend failures.
1313///
1314/// # Examples
1315///
1316/// ```
1317/// use tensor4all_tensorbackend::{Storage, StorageError};
1318///
1319/// let storage = Storage::from_dense_col_major(vec![1.0_f64], &[1]).unwrap();
1320/// let err = storage.payload_c64_col_major_vec().unwrap_err();
1321/// assert!(matches!(err, StorageError::ScalarKindMismatch { .. }));
1322/// ```
1323#[derive(Debug, thiserror::Error)]
1324pub enum StorageError {
1325    /// The storage scalar kind did not match the requested operation.
1326    #[error("expected {expected} storage when {operation}, got {actual}")]
1327    ScalarKindMismatch {
1328        /// The scalar kind that the caller requested.
1329        expected: &'static str,
1330        /// The scalar kind actually stored.
1331        actual: &'static str,
1332        /// Human-readable operation description.
1333        operation: &'static str,
1334    },
1335    /// Two storages had different payload lengths for an elementwise operation.
1336    #[error("storage lengths must match for {operation}: {left} != {right}")]
1337    LengthMismatch {
1338        /// Name of the operation being performed.
1339        operation: &'static str,
1340        /// Left-hand payload length.
1341        left: usize,
1342        /// Right-hand payload length.
1343        right: usize,
1344    },
1345    /// Structured storage metadata was invalid after an operation.
1346    #[error("invalid structured storage: {0}")]
1347    InvalidStructuredStorage(String),
1348    /// The requested operation does not support the provided storage kinds.
1349    #[error("storage types are not supported for {operation}: {left} vs {right}")]
1350    OperationNotSupported {
1351        /// Name of the operation being performed.
1352        operation: &'static str,
1353        /// Left-hand storage kind.
1354        left: &'static str,
1355        /// Right-hand storage kind.
1356        right: &'static str,
1357    },
1358    /// A storage operation failed with an internal diagnostic.
1359    #[error("storage operation failed: {source}")]
1360    Operation {
1361        /// Original internal diagnostic, preserving its source chain.
1362        #[source]
1363        source: anyhow::Error,
1364    },
1365}
1366
1367impl From<anyhow::Error> for StorageError {
1368    fn from(source: anyhow::Error) -> Self {
1369        Self::Operation { source }
1370    }
1371}
1372
1373/// Result type returned by storage methods that can fail with [`StorageError`].
1374pub type StorageResult<T> = std::result::Result<T, StorageError>;
1375
1376#[derive(Debug, Clone)]
1377pub(crate) enum StorageRepr {
1378    /// Storage with f32 elements.
1379    F32(StructuredStorage<f32>),
1380    /// Storage with f64 elements.
1381    F64(StructuredStorage<f64>),
1382    /// Storage with Complex32 elements.
1383    C32(StructuredStorage<Complex32>),
1384    /// Storage with Complex64 elements.
1385    C64(StructuredStorage<Complex64>),
1386}
1387
1388impl StorageRepr {
1389    fn dtype(&self) -> DType {
1390        storage_payload_dispatch!(self, Payload => |_payload| <Payload as TensorScalar>::dtype())
1391    }
1392
1393    fn scalar_kind(&self) -> &'static str {
1394        storage_payload_dispatch!(self, Payload => |_payload| <Payload as StorageScalar>::KIND)
1395    }
1396
1397    fn is_complex(&self) -> bool {
1398        storage_payload_dispatch!(self, Payload => |_payload| <Payload as StorageScalar>::IS_COMPLEX)
1399    }
1400}
1401
1402/// Types that can be computed as the result of a reduction over `Storage`.
1403///
1404/// This lets callers write `let s: T = tensor.sum();` without matching on
1405/// the storage variant. Implemented for `f64`, `Complex64`, `f32`, and
1406/// `Complex32`; every reduction widens compact payload values to the requested
1407/// accumulator, so a narrow payload can be summed without changing its stored
1408/// dtype.
1409///
1410/// # Examples
1411///
1412/// ```
1413/// use tensor4all_tensorbackend::{Storage, SumFromStorage};
1414///
1415/// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0], &[3]).unwrap();
1416/// let total: f64 = f64::sum_from_storage(&s);
1417/// assert!((total - 6.0).abs() < 1e-10);
1418///
1419/// let narrow = Storage::from_dense_col_major(vec![1.0_f32, 2.0], &[2]).unwrap();
1420/// assert_eq!(f32::sum_from_storage(&narrow), 3.0_f32);
1421/// assert_eq!(f64::sum_from_storage(&narrow), 3.0_f64);
1422/// ```
1423pub trait SumFromStorage: Sized {
1424    /// Compute the sum of all elements in the storage.
1425    fn sum_from_storage(storage: &Storage) -> Self;
1426}
1427
1428impl SumFromStorage for f64 {
1429    fn sum_from_storage(storage: &Storage) -> Self {
1430        let mut sum = 0.0_f64;
1431        storage.for_each_payload_parts(|re, _im| sum += re);
1432        sum
1433    }
1434}
1435
1436impl SumFromStorage for Complex64 {
1437    fn sum_from_storage(storage: &Storage) -> Self {
1438        let mut sum = Complex64::new(0.0, 0.0);
1439        storage.for_each_payload_parts(|re, im| sum += Complex64::new(re, im));
1440        sum
1441    }
1442}
1443
1444impl SumFromStorage for f32 {
1445    fn sum_from_storage(storage: &Storage) -> Self {
1446        let mut sum = 0.0_f32;
1447        storage.for_each_payload_parts(|re, _im| sum += re as f32);
1448        sum
1449    }
1450}
1451
1452impl SumFromStorage for Complex32 {
1453    fn sum_from_storage(storage: &Storage) -> Self {
1454        let mut sum = Complex32::new(0.0, 0.0);
1455        storage.for_each_payload_parts(|re, im| sum += Complex32::new(re as f32, im as f32));
1456        sum
1457    }
1458}
1459
1460/// Lattice width of a floating dtype, or `None` for non-floating dtypes.
1461fn float_lattice_width(dtype: DType) -> Option<u8> {
1462    match dtype {
1463        DType::F32 | DType::C32 => Some(32),
1464        DType::F64 | DType::C64 => Some(64),
1465        _ => None,
1466    }
1467}
1468
1469/// Least upper bound dtype of a set of floating dtypes.
1470///
1471/// The lattice is `f32 < f64`, `Complex32 < Complex64`, and real `<` complex, so
1472/// the result takes the widest real component and the complex component as soon
1473/// as any input is complex. Returns `None` when an input is not floating point.
1474fn promote_float_dtypes(dtypes: impl IntoIterator<Item = DType>) -> Option<DType> {
1475    let mut width = 0_u8;
1476    let mut complex = false;
1477    for dtype in dtypes {
1478        width = width.max(float_lattice_width(dtype)?);
1479        complex |= matches!(dtype, DType::C32 | DType::C64);
1480    }
1481    match (width, complex) {
1482        (32, false) => Some(DType::F32),
1483        (64, false) => Some(DType::F64),
1484        (32, true) => Some(DType::C32),
1485        (64, true) => Some(DType::C64),
1486        _ => None,
1487    }
1488}
1489
1490/// Rebuild a compact payload from copied metadata and replacement values.
1491///
1492/// The metadata comes from an already validated payload, so this construction
1493/// cannot introduce invalid strides or lengths; it is used by the infallible
1494/// elementwise operators.
1495fn rebuild_payload<T: StorageScalar>(
1496    payload_dims: &[usize],
1497    strides: &[isize],
1498    axis_classes: &[usize],
1499    data: Vec<T>,
1500) -> Storage {
1501    T::wrap_payload(StructuredStorage {
1502        data,
1503        payload_dims: payload_dims.to_vec(),
1504        strides: strides.to_vec(),
1505        axis_classes: axis_classes.to_vec(),
1506    })
1507}
1508
1509/// Zip two same-scalar payloads, preserving the left payload's metadata.
1510fn zip_payloads<T, U>(
1511    left: &StructuredStorage<T>,
1512    right: &StructuredStorage<T>,
1513    operation: &'static str,
1514    mut combine: impl FnMut(T, T) -> U,
1515) -> StorageResult<Storage>
1516where
1517    T: StorageScalar,
1518    U: StorageScalar,
1519{
1520    if left.len() != right.len() {
1521        return Err(StorageError::LengthMismatch {
1522            operation,
1523            left: left.len(),
1524            right: right.len(),
1525        });
1526    }
1527    let values: Vec<U> = left
1528        .data()
1529        .iter()
1530        .copied()
1531        .zip(right.data().iter().copied())
1532        .map(|(x, y)| combine(x, y))
1533        .collect();
1534    StructuredStorage::new(
1535        values,
1536        left.payload_dims().to_vec(),
1537        left.strides().to_vec(),
1538        left.axis_classes().to_vec(),
1539    )
1540    .map(StructuredStorage::into_storage)
1541    .map_err(StorageError::from)
1542}
1543
1544/// Materialize the logical dense values of one payload, checking the shape.
1545fn checked_dense_payload<T: StorageScalar>(
1546    payload: &StructuredStorage<T>,
1547    logical_dims: &[usize],
1548) -> StorageResult<Vec<T>> {
1549    let structured_dims = payload.logical_dims();
1550    if structured_dims != logical_dims {
1551        return Err(StorageError::InvalidStructuredStorage(format!(
1552            "logical dims {:?} do not match stored logical dims {:?}",
1553            logical_dims, structured_dims
1554        )));
1555    }
1556    payload.logical_dense_col_major_vec()
1557}
1558
1559impl Storage {
1560    #[cfg(test)]
1561    pub(crate) fn from_repr(repr: StorageRepr) -> Self {
1562        Self(repr)
1563    }
1564
1565    /// Visit every referenced compact payload value as widened `(real, imaginary)` parts.
1566    ///
1567    /// Stride gaps and padding in a structured backing buffer are not tensor
1568    /// values and are excluded. This is the single dtype-agnostic payload scan:
1569    /// reductions and elementwise algebra are written once against it.
1570    fn for_each_payload_parts(&self, mut visit: impl FnMut(f64, f64)) {
1571        storage_payload_dispatch!(&self.0, Payload => |payload| {
1572            payload.for_each_payload_value(|value| {
1573                let (re, im) = <Payload as StorageScalar>::widened_parts(value);
1574                visit(re, im);
1575            })
1576        })
1577    }
1578
1579    /// Visit every referenced compact payload entry's magnitude as `f64`.
1580    ///
1581    /// Real payloads visit `|x|`; complex payloads visit `hypot(re, im)`, and a
1582    /// NaN component propagates as `NaN` rather than being masked by the other
1583    /// component. Narrow payloads widen per value for the scan only.
1584    fn for_each_payload_magnitude(&self, mut visit: impl FnMut(f64)) {
1585        storage_payload_dispatch!(&self.0, Payload => |payload| {
1586            payload.for_each_payload_value(|value| {
1587                let (re, im) = <Payload as StorageScalar>::widened_parts(value);
1588                visit(if <Payload as StorageScalar>::IS_COMPLEX {
1589                    if re.is_nan() || im.is_nan() {
1590                        f64::NAN
1591                    } else {
1592                        re.hypot(im)
1593                    }
1594                } else {
1595                    re.abs()
1596                });
1597            })
1598        })
1599    }
1600
1601    fn invalid_storage_error(err: anyhow::Error) -> StorageError {
1602        StorageError::from(err)
1603    }
1604
1605    #[cfg(test)]
1606    pub(crate) fn repr(&self) -> &StorageRepr {
1607        &self.0
1608    }
1609
1610    fn validate_dense_len<T>(data: &[T], logical_dims: &[usize], label: &str) -> Result<()> {
1611        let expected_len = logical_dims.iter().try_fold(1usize, |length, &dim| {
1612            length
1613                .checked_mul(dim)
1614                .ok_or_else(|| anyhow!("{label} dimension product overflows for {logical_dims:?}"))
1615        })?;
1616        ensure!(
1617            data.len() == expected_len,
1618            "{label} len {} does not match logical dims {:?} (expected {})",
1619            data.len(),
1620            logical_dims,
1621            expected_len
1622        );
1623        Ok(())
1624    }
1625
1626    /// Create dense storage from column-major logical values (generic over scalar type).
1627    ///
1628    /// The scalar type is inferred from the `data` argument.
1629    ///
1630    /// # Errors
1631    ///
1632    /// Returns an error when the shape product would overflow `usize` or
1633    /// `data.len()` does not match the expected shape.
1634    ///
1635    /// # Examples
1636    ///
1637    /// ```
1638    /// use tensor4all_tensorbackend::Storage;
1639    ///
1640    /// // 2x2 matrix, column-major: [[1,3],[2,4]]
1641    /// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
1642    /// assert!(s.is_f64());
1643    /// assert!(s.is_dense());
1644    /// assert_eq!(s.len(), 4);
1645    /// ```
1646    pub fn from_dense_col_major<T: StorageScalar>(
1647        data: Vec<T>,
1648        logical_dims: &[usize],
1649    ) -> Result<Self> {
1650        T::build_dense_storage(data, logical_dims)
1651    }
1652
1653    /// Create diagonal storage from column-major diagonal payload values (generic over scalar type).
1654    ///
1655    /// Creates a rank-2 diagonal storage by default. The scalar type is
1656    /// inferred from `diag_data`.
1657    ///
1658    /// # Errors
1659    ///
1660    /// Returns an error when the diagonal payload length does not match the
1661    /// length required for `logical_rank` or a stride product would overflow
1662    /// `usize`.
1663    ///
1664    /// # Examples
1665    ///
1666    /// ```
1667    /// use tensor4all_tensorbackend::Storage;
1668    ///
1669    /// let s = Storage::from_diag_col_major(vec![1.0_f64, 2.0, 3.0], 2).unwrap();
1670    /// assert!(s.is_diag());
1671    /// assert!(s.is_f64());
1672    /// assert_eq!(s.len(), 3);
1673    /// ```
1674    pub fn from_diag_col_major<T: StorageScalar>(
1675        diag_data: Vec<T>,
1676        logical_rank: usize,
1677    ) -> Result<Self> {
1678        T::build_diag_storage(diag_data, logical_rank)
1679    }
1680
1681    /// Create a new 1D zero-initialized dense storage (generic over scalar type).
1682    ///
1683    /// # Examples
1684    ///
1685    /// ```
1686    /// use tensor4all_tensorbackend::Storage;
1687    ///
1688    /// let s = Storage::new_dense::<f64>(5).unwrap();
1689    /// assert!(s.is_dense());
1690    /// assert_eq!(s.len(), 5);
1691    /// assert!((s.max_abs()).abs() < 1e-10);
1692    /// ```
1693    ///
1694    /// # Errors
1695    ///
1696    /// Returns [`StorageError::Operation`] when the dense storage construction
1697    /// or allocation fails.
1698    pub fn new_dense<T: StorageScalar + Default>(size: usize) -> StorageResult<Self> {
1699        Self::from_dense_col_major(vec![T::default(); size], &[size])
1700            .map_err(Self::invalid_storage_error)
1701    }
1702
1703    /// Create a new diagonal storage with the given diagonal data (generic over scalar type).
1704    ///
1705    /// # Errors
1706    ///
1707    /// Returns an error if diagonal metadata is invalid.
1708    ///
1709    /// # Examples
1710    ///
1711    /// ```
1712    /// use tensor4all_tensorbackend::Storage;
1713    ///
1714    /// let s = Storage::new_diag(vec![1.0_f64, 2.0, 3.0]).unwrap();
1715    /// assert!(s.is_diag());
1716    /// assert!(s.is_f64());
1717    /// ```
1718    pub fn new_diag<T: StorageScalar>(diag_data: Vec<T>) -> StorageResult<Self> {
1719        Self::from_diag_col_major(diag_data, 2).map_err(Self::invalid_storage_error)
1720    }
1721
1722    /// Create a new structured storage (generic over scalar type).
1723    ///
1724    /// # Errors
1725    ///
1726    /// Returns an error when `axis_classes` is not in canonical
1727    /// first-appearance order, when the `payload_dims` or `strides` ranks do
1728    /// not match `axis_classes`, when a stride is negative, when a size
1729    /// product would overflow `usize`, or when `data.len()` does not match the
1730    /// required payload length.
1731    ///
1732    /// # Examples
1733    ///
1734    /// ```
1735    /// use tensor4all_tensorbackend::Storage;
1736    ///
1737    /// // Diagonal-like structured storage: axis_classes = [0, 0]
1738    /// let s = Storage::new_structured(
1739    ///     vec![1.0_f64, 2.0],
1740    ///     vec![2],         // payload_dims
1741    ///     vec![1],         // strides
1742    ///     vec![0, 0],      // axis_classes: both axes map to payload axis 0
1743    /// ).unwrap();
1744    /// assert!(s.is_diag());
1745    /// ```
1746    pub fn new_structured<T: StorageScalar>(
1747        data: Vec<T>,
1748        payload_dims: Vec<usize>,
1749        strides: Vec<isize>,
1750        axis_classes: Vec<usize>,
1751    ) -> Result<Self> {
1752        T::build_structured_storage(data, payload_dims, strides, axis_classes)
1753    }
1754
1755    /// Validate structured-storage metadata and return the required payload length.
1756    ///
1757    /// The metadata must be internally consistent: canonical axis classes, a
1758    /// payload rank implied by the axis classes, matching dim/stride ranks,
1759    /// non-negative strides, and size products that fit in `usize`. The
1760    /// returned length is exactly what a constructed [`Storage`] would
1761    /// require, so untrusted payload lengths can be rejected before any
1762    /// allocation.
1763    ///
1764    /// # Errors
1765    ///
1766    /// Returns an error if the metadata is inconsistent or its size products
1767    /// overflow `usize`.
1768    ///
1769    /// # Examples
1770    ///
1771    /// ```
1772    /// use tensor4all_tensorbackend::Storage;
1773    ///
1774    /// let required = Storage::validate_structured_metadata(
1775    ///     &[2],
1776    ///     &[1],
1777    ///     &[0, 0],
1778    /// ).unwrap();
1779    /// assert_eq!(required, 2);
1780    ///
1781    /// assert!(Storage::validate_structured_metadata(&[2], &[-1], &[0]).is_err());
1782    /// ```
1783    pub fn validate_structured_metadata(
1784        payload_dims: &[usize],
1785        strides: &[isize],
1786        axis_classes: &[usize],
1787    ) -> Result<usize> {
1788        validate_canonical_axis_classes(axis_classes)?;
1789        let payload_rank = axis_classes.iter().try_fold(0usize, |rank, &class_id| {
1790            let required_rank = class_id
1791                .checked_add(1)
1792                .ok_or_else(|| anyhow!("axis class index overflow"))?;
1793            Ok::<_, anyhow::Error>(rank.max(required_rank))
1794        })?;
1795        ensure!(
1796            payload_dims.len() == payload_rank,
1797            "payload rank {} does not match axis_classes {:?}",
1798            payload_dims.len(),
1799            axis_classes
1800        );
1801        ensure!(
1802            strides.len() == payload_dims.len(),
1803            "payload dims {:?} and strides {:?} must have the same rank",
1804            payload_dims,
1805            strides
1806        );
1807        required_storage_len(payload_dims, strides)
1808    }
1809
1810    /// Check if this storage is logically dense.
1811    ///
1812    /// # Examples
1813    ///
1814    /// ```
1815    /// use tensor4all_tensorbackend::Storage;
1816    ///
1817    /// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
1818    /// assert!(s.is_dense());
1819    ///
1820    /// let d = Storage::new_diag(vec![1.0_f64, 2.0]).unwrap();
1821    /// assert!(!d.is_dense());
1822    /// ```
1823    pub fn is_dense(&self) -> bool {
1824        storage_payload_dispatch!(&self.0, Payload => |value| value.is_dense())
1825    }
1826
1827    /// Check if this storage is a Diag storage type.
1828    ///
1829    /// # Examples
1830    ///
1831    /// ```
1832    /// use tensor4all_tensorbackend::Storage;
1833    ///
1834    /// let d = Storage::new_diag(vec![1.0_f64, 2.0]).unwrap();
1835    /// assert!(d.is_diag());
1836    /// ```
1837    pub fn is_diag(&self) -> bool {
1838        storage_payload_dispatch!(&self.0, Payload => |value| value.is_diag())
1839    }
1840
1841    /// Returns the compact layout class for this storage.
1842    ///
1843    /// The return value is metadata-only and never materializes dense logical
1844    /// values. Use it to choose whether to read compact payload metadata or
1845    /// dense logical values.
1846    ///
1847    /// # Examples
1848    ///
1849    /// ```
1850    /// use tensor4all_tensorbackend::{Storage, StorageKind};
1851    ///
1852    /// let structured = Storage::new_structured(
1853    ///     vec![1.0_f64, 2.0],
1854    ///     vec![2],
1855    ///     vec![1],
1856    ///     vec![0, 0],
1857    /// ).unwrap();
1858    /// assert_eq!(structured.storage_kind(), StorageKind::Diagonal);
1859    /// ```
1860    pub fn storage_kind(&self) -> StorageKind {
1861        if self.is_dense() {
1862            StorageKind::Dense
1863        } else if self.is_diag() {
1864            StorageKind::Diagonal
1865        } else {
1866            StorageKind::Structured
1867        }
1868    }
1869
1870    /// Returns the logical tensor dimensions represented by this storage.
1871    ///
1872    /// The dimensions are derived from payload dimensions and `axis_classes`.
1873    ///
1874    /// # Examples
1875    ///
1876    /// ```
1877    /// use tensor4all_tensorbackend::Storage;
1878    ///
1879    /// let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
1880    /// assert_eq!(diag.logical_dims(), vec![2, 2]);
1881    /// ```
1882    pub fn logical_dims(&self) -> Vec<usize> {
1883        storage_payload_dispatch!(&self.0, Payload => |value| value.logical_dims())
1884    }
1885
1886    /// Returns the logical tensor rank represented by this storage.
1887    ///
1888    /// This equals `axis_classes().len()`, not necessarily `payload_dims().len()`.
1889    ///
1890    /// # Examples
1891    ///
1892    /// ```
1893    /// use tensor4all_tensorbackend::Storage;
1894    ///
1895    /// let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 3).unwrap();
1896    /// assert_eq!(diag.logical_rank(), 3);
1897    /// assert_eq!(diag.payload_dims(), &[2]);
1898    /// ```
1899    pub fn logical_rank(&self) -> usize {
1900        storage_payload_dispatch!(&self.0, Payload => |value| value.logical_rank())
1901    }
1902
1903    /// Returns the compact payload dimensions.
1904    ///
1905    /// For dense storage these match logical dimensions. For diagonal storage
1906    /// this is rank-1 even when the logical tensor has multiple axes.
1907    ///
1908    /// # Examples
1909    ///
1910    /// ```
1911    /// use tensor4all_tensorbackend::Storage;
1912    ///
1913    /// let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
1914    /// assert_eq!(diag.payload_dims(), &[2]);
1915    /// ```
1916    pub fn payload_dims(&self) -> &[usize] {
1917        storage_payload_dispatch!(&self.0, Payload => |value| value.payload_dims())
1918    }
1919
1920    /// Returns the compact payload strides.
1921    ///
1922    /// Strides are measured in stored scalar elements and describe the compact
1923    /// payload buffer, not the logical dense tensor.
1924    ///
1925    /// # Examples
1926    ///
1927    /// ```
1928    /// use tensor4all_tensorbackend::Storage;
1929    ///
1930    /// let dense = Storage::from_dense_col_major(vec![0.0_f64; 6], &[2, 3]).unwrap();
1931    /// assert_eq!(dense.payload_strides(), &[1, 2]);
1932    /// ```
1933    pub fn payload_strides(&self) -> &[isize] {
1934        storage_payload_dispatch!(&self.0, Payload => |value| value.strides())
1935    }
1936
1937    /// Returns logical-axis equivalence classes for this storage.
1938    ///
1939    /// Repeated class labels mean the corresponding logical axes share one
1940    /// payload axis. Dense storage has `[0, 1, ...]`; diagonal storage has
1941    /// repeated zero labels.
1942    ///
1943    /// # Examples
1944    ///
1945    /// ```
1946    /// use tensor4all_tensorbackend::Storage;
1947    ///
1948    /// let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
1949    /// assert_eq!(diag.axis_classes(), &[0, 0]);
1950    /// ```
1951    pub fn axis_classes(&self) -> &[usize] {
1952        storage_payload_dispatch!(&self.0, Payload => |value| value.axis_classes())
1953    }
1954
1955    /// Returns the number of stored compact payload elements.
1956    ///
1957    /// For dense storage this equals the logical dense length. For diagonal and
1958    /// structured storage this is the compact payload length.
1959    ///
1960    /// # Examples
1961    ///
1962    /// ```
1963    /// use tensor4all_tensorbackend::Storage;
1964    ///
1965    /// let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
1966    /// assert_eq!(diag.payload_len(), 2);
1967    /// ```
1968    pub fn payload_len(&self) -> usize {
1969        self.len()
1970    }
1971
1972    /// Copies the compact `f32` payload in column-major payload order.
1973    ///
1974    /// This does not materialize logical dense values and never widens: a
1975    /// narrow payload stays `f32`.
1976    ///
1977    /// # Errors
1978    ///
1979    /// Returns [`StorageError::ScalarKindMismatch`] if the storage scalar type
1980    /// is not `f32`.
1981    ///
1982    /// # Examples
1983    ///
1984    /// ```
1985    /// use tensor4all_tensorbackend::Storage;
1986    ///
1987    /// let diag = Storage::from_diag_col_major(vec![1.0_f32, 2.0], 2).unwrap();
1988    /// assert_eq!(diag.payload_f32_col_major_vec().unwrap(), vec![1.0_f32, 2.0]);
1989    /// ```
1990    pub fn payload_f32_col_major_vec(&self) -> StorageResult<Vec<f32>> {
1991        <f32 as StorageScalar>::payload_vec(self)
1992    }
1993
1994    /// Borrows the compact `f32` payload when it is already contiguous in
1995    /// column-major payload order.
1996    ///
1997    /// # Errors
1998    ///
1999    /// Returns `StorageError::ScalarKindMismatch` when the storage is not
2000    /// f32-backed (a dtype mismatch).
2001    pub fn payload_f32_col_major_view_if_contiguous(&self) -> StorageResult<Option<&[f32]>> {
2002        <f32 as StorageScalar>::payload_view(self)
2003    }
2004
2005    /// Copies the compact `f64` payload in column-major payload order.
2006    ///
2007    /// This does not materialize logical dense values. For diagonal storage the
2008    /// returned vector contains only diagonal payload values.
2009    ///
2010    /// # Errors
2011    ///
2012    /// Returns [`StorageError::ScalarKindMismatch`] if the storage scalar type
2013    /// is not `f64`.
2014    ///
2015    /// # Examples
2016    ///
2017    /// ```
2018    /// use tensor4all_tensorbackend::Storage;
2019    ///
2020    /// let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
2021    /// assert_eq!(diag.payload_f64_col_major_vec().unwrap(), vec![1.0, 2.0]);
2022    /// ```
2023    pub fn payload_f64_col_major_vec(&self) -> StorageResult<Vec<f64>> {
2024        <f64 as StorageScalar>::payload_vec(self)
2025    }
2026
2027    /// Borrows the compact `f64` payload when it is already contiguous in
2028    /// column-major payload order.
2029    ///
2030    /// # Errors
2031    ///
2032    /// Returns `StorageError::ScalarKindMismatch` when the storage is not
2033    /// f64-backed (a dtype mismatch).
2034    pub fn payload_f64_col_major_view_if_contiguous(&self) -> StorageResult<Option<&[f64]>> {
2035        <f64 as StorageScalar>::payload_view(self)
2036    }
2037
2038    /// Copies the compact `Complex32` payload in column-major payload order.
2039    ///
2040    /// # Errors
2041    ///
2042    /// Returns [`StorageError::ScalarKindMismatch`] if the storage scalar type
2043    /// is not `Complex32`.
2044    ///
2045    /// # Examples
2046    ///
2047    /// ```
2048    /// use num_complex::Complex32;
2049    /// use tensor4all_tensorbackend::Storage;
2050    ///
2051    /// let data = vec![Complex32::new(1.0, -2.0), Complex32::new(0.5, 0.0)];
2052    /// let diag = Storage::from_diag_col_major(data.clone(), 2).unwrap();
2053    /// assert_eq!(diag.payload_c32_col_major_vec().unwrap(), data);
2054    /// ```
2055    pub fn payload_c32_col_major_vec(&self) -> StorageResult<Vec<Complex32>> {
2056        <Complex32 as StorageScalar>::payload_vec(self)
2057    }
2058
2059    /// Borrows the compact `Complex32` payload when it is already contiguous in
2060    /// column-major payload order.
2061    ///
2062    /// # Errors
2063    ///
2064    /// Returns `StorageError::ScalarKindMismatch` when the storage is not
2065    /// c32-backed (a dtype mismatch).
2066    pub fn payload_c32_col_major_view_if_contiguous(&self) -> StorageResult<Option<&[Complex32]>> {
2067        <Complex32 as StorageScalar>::payload_view(self)
2068    }
2069
2070    /// Copies the compact `Complex64` payload in column-major payload order.
2071    ///
2072    /// This does not materialize logical dense values. Complex payloads are
2073    /// returned as native Rust `Complex64` values.
2074    ///
2075    /// # Errors
2076    ///
2077    /// Returns [`StorageError::ScalarKindMismatch`] if the storage scalar type
2078    /// is not `Complex64`.
2079    ///
2080    /// # Examples
2081    ///
2082    /// ```
2083    /// use num_complex::Complex64;
2084    /// use tensor4all_tensorbackend::Storage;
2085    ///
2086    /// let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
2087    /// let diag = Storage::from_diag_col_major(data.clone(), 2).unwrap();
2088    /// assert_eq!(diag.payload_c64_col_major_vec().unwrap(), data);
2089    /// ```
2090    pub fn payload_c64_col_major_vec(&self) -> StorageResult<Vec<Complex64>> {
2091        <Complex64 as StorageScalar>::payload_vec(self)
2092    }
2093
2094    /// Borrows the compact `Complex64` payload when it is already contiguous in
2095    /// column-major payload order.
2096    ///
2097    /// # Errors
2098    ///
2099    /// Returns `StorageError::ScalarKindMismatch` when the storage is not
2100    /// c64-backed (a dtype mismatch).
2101    pub fn payload_c64_col_major_view_if_contiguous(&self) -> StorageResult<Option<&[Complex64]>> {
2102        <Complex64 as StorageScalar>::payload_view(self)
2103    }
2104
2105    /// Check if this storage uses f64 scalar type.
2106    ///
2107    /// # Examples
2108    ///
2109    /// ```
2110    /// use tensor4all_tensorbackend::Storage;
2111    ///
2112    /// let s = Storage::from_dense_col_major(vec![1.0_f64], &[1]).unwrap();
2113    /// assert!(s.is_f64());
2114    /// assert!(!s.is_c64());
2115    /// ```
2116    pub fn is_f64(&self) -> bool {
2117        self.dtype() == DType::F64
2118    }
2119
2120    /// Check if this storage uses f32 scalar type.
2121    ///
2122    /// # Examples
2123    ///
2124    /// ```
2125    /// use tensor4all_tensorbackend::Storage;
2126    ///
2127    /// let s = Storage::from_dense_col_major(vec![1.0_f32], &[1]).unwrap();
2128    /// assert!(s.is_f32());
2129    /// assert!(!s.is_f64());
2130    /// ```
2131    pub fn is_f32(&self) -> bool {
2132        self.dtype() == DType::F32
2133    }
2134
2135    /// Check if this storage uses Complex64 scalar type.
2136    ///
2137    /// # Examples
2138    ///
2139    /// ```
2140    /// use tensor4all_tensorbackend::Storage;
2141    /// use num_complex::Complex64;
2142    ///
2143    /// let s = Storage::from_dense_col_major(
2144    ///     vec![Complex64::new(1.0, 0.0)], &[1],
2145    /// ).unwrap();
2146    /// assert!(s.is_c64());
2147    /// ```
2148    pub fn is_c64(&self) -> bool {
2149        self.dtype() == DType::C64
2150    }
2151
2152    /// Check if this storage uses Complex32 scalar type.
2153    ///
2154    /// # Examples
2155    ///
2156    /// ```
2157    /// use num_complex::Complex32;
2158    /// use tensor4all_tensorbackend::Storage;
2159    ///
2160    /// let s = Storage::from_dense_col_major(
2161    ///     vec![Complex32::new(1.0, -1.0)], &[1],
2162    /// ).unwrap();
2163    /// assert!(s.is_c32());
2164    /// assert!(s.is_complex());
2165    /// ```
2166    pub fn is_c32(&self) -> bool {
2167        self.dtype() == DType::C32
2168    }
2169
2170    /// Check if this storage uses complex scalar type.
2171    ///
2172    /// This is `Complex64` or `Complex32`; it is not an alias for
2173    /// [`is_c64()`](Self::is_c64).
2174    ///
2175    /// # Examples
2176    ///
2177    /// ```
2178    /// use num_complex::Complex32;
2179    /// use tensor4all_tensorbackend::Storage;
2180    ///
2181    /// let s = Storage::from_dense_col_major(vec![Complex32::new(1.0, 0.0)], &[1]).unwrap();
2182    /// assert!(s.is_complex());
2183    ///
2184    /// let r = Storage::from_dense_col_major(vec![1.0_f64], &[1]).unwrap();
2185    /// assert!(!r.is_complex());
2186    /// ```
2187    pub fn is_complex(&self) -> bool {
2188        self.0.is_complex()
2189    }
2190
2191    /// Returns the stored scalar dtype.
2192    ///
2193    /// The dtype is metadata only and never depends on payload contents. It is
2194    /// the value a publication or conversion boundary should compare against
2195    /// instead of assuming the payload is `f64` or `Complex64`.
2196    ///
2197    /// # Examples
2198    ///
2199    /// ```
2200    /// use tensor4all_tensorbackend::Storage;
2201    /// use tenferro::DType;
2202    ///
2203    /// let dense = Storage::from_dense_col_major(vec![1.0_f32, 2.0], &[2]).unwrap();
2204    /// assert_eq!(dense.dtype(), DType::F32);
2205    ///
2206    /// let complex = Storage::from_diag_col_major(
2207    ///     vec![num_complex::Complex64::new(1.0, 0.0)], 2,
2208    /// ).unwrap();
2209    /// assert_eq!(complex.dtype(), DType::C64);
2210    /// ```
2211    pub fn dtype(&self) -> DType {
2212        self.0.dtype()
2213    }
2214
2215    /// Returns this storage's scalar-kind label used in diagnostics.
2216    ///
2217    /// # Examples
2218    ///
2219    /// ```
2220    /// use tensor4all_tensorbackend::Storage;
2221    ///
2222    /// let s = Storage::from_dense_col_major(vec![1.0_f32], &[1]).unwrap();
2223    /// assert_eq!(s.scalar_kind(), "f32");
2224    /// ```
2225    pub fn scalar_kind(&self) -> &'static str {
2226        self.0.scalar_kind()
2227    }
2228
2229    /// Get the length of the storage payload (number of stored elements).
2230    ///
2231    /// For dense storage this equals the product of logical dimensions.
2232    /// For diagonal storage this equals the diagonal length.
2233    ///
2234    /// # Examples
2235    ///
2236    /// ```
2237    /// use tensor4all_tensorbackend::Storage;
2238    ///
2239    /// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0], &[3]).unwrap();
2240    /// assert_eq!(s.len(), 3);
2241    ///
2242    /// let d = Storage::new_diag(vec![1.0_f64, 2.0]).unwrap();
2243    /// assert_eq!(d.len(), 2);
2244    /// ```
2245    pub fn len(&self) -> usize {
2246        storage_payload_dispatch!(&self.0, Payload => |value| value.len())
2247    }
2248
2249    /// Check if the storage is empty.
2250    ///
2251    /// # Examples
2252    ///
2253    /// ```
2254    /// use tensor4all_tensorbackend::Storage;
2255    ///
2256    /// let s = Storage::new_dense::<f64>(0).unwrap();
2257    /// assert!(s.is_empty());
2258    ///
2259    /// let s2 = Storage::new_dense::<f64>(3).unwrap();
2260    /// assert!(!s2.is_empty());
2261    /// ```
2262    pub fn is_empty(&self) -> bool {
2263        self.len() == 0
2264    }
2265
2266    /// Sum all referenced compact payload entries, converting to type `T`.
2267    ///
2268    /// Stride gaps and padding in a structured backing buffer are not tensor
2269    /// values and are excluded from the reduction.
2270    ///
2271    /// # Example
2272    /// ```
2273    /// use tensor4all_tensorbackend::Storage;
2274    /// let s = Storage::from_dense_col_major(vec![1.0, 2.0, 3.0], &[3]).unwrap();
2275    /// assert_eq!(s.sum::<f64>(), 6.0);
2276    /// ```
2277    pub fn sum<T: SumFromStorage>(&self) -> T {
2278        T::sum_from_storage(self)
2279    }
2280
2281    /// Maximum absolute value over all referenced compact payload entries.
2282    ///
2283    /// Stride gaps and padding are excluded. For real storage this is `max(|x|)`, and for complex storage this is
2284    /// `max(hypot(re, im))`. NaN payloads, including a NaN real or imaginary
2285    /// component paired with infinity, propagate to a NaN result; positive
2286    /// infinity is preserved.
2287    ///
2288    /// # Examples
2289    ///
2290    /// ```
2291    /// use tensor4all_tensorbackend::Storage;
2292    ///
2293    /// let s = Storage::from_dense_col_major(vec![-3.0_f64, 1.0, 2.0], &[3]).unwrap();
2294    /// assert!((s.max_abs() - 3.0).abs() < 1e-10);
2295    /// ```
2296    pub fn max_abs(&self) -> f64 {
2297        fn fold_nan_propagating(current: f64, value: f64) -> f64 {
2298            if current.is_nan() || value.is_nan() {
2299                f64::NAN
2300            } else {
2301                current.max(value)
2302            }
2303        }
2304
2305        let mut current = 0.0_f64;
2306        self.for_each_payload_magnitude(|magnitude| {
2307            current = fold_nan_propagating(current, magnitude);
2308        });
2309        current
2310    }
2311
2312    /// Scan the compact payload without copying it.
2313    ///
2314    /// The returned flags describe the stored payload, not the logical dense
2315    /// tensor. Structural zeros cannot introduce non-finite values, so this is
2316    /// sufficient for metric validation while preserving compact memory use.
2317    ///
2318    /// # Examples
2319    ///
2320    /// ```
2321    /// use tensor4all_tensorbackend::Storage;
2322    ///
2323    /// let storage = Storage::from_dense_col_major(vec![1.0_f64, f64::INFINITY], &[2]).unwrap();
2324    /// let flags = storage.payload_nonfinite_flags();
2325    /// assert!(!flags.has_nan);
2326    /// assert!(flags.has_infinity);
2327    /// ```
2328    pub fn payload_nonfinite_flags(&self) -> NonfiniteFlags {
2329        let mut flags = NonfiniteFlags::default();
2330        storage_payload_dispatch!(&self.0, Payload => |payload| {
2331            payload.for_each_payload_value(|value| {
2332                let (re, im) = <Payload as StorageScalar>::widened_parts(value);
2333                flags.has_nan |= re.is_nan() || im.is_nan();
2334                flags.has_infinity |= re.is_infinite() || im.is_infinite();
2335            })
2336        });
2337        flags
2338    }
2339
2340    /// Return one compact payload value as a dynamic [`BackendScalar`].
2341    ///
2342    /// `payload_coords` are column-major payload coordinates, not logical
2343    /// coordinates. Repeated logical axis classes are represented once in the
2344    /// payload, so this lookup performs only rank-bounded stride arithmetic and
2345    /// never allocates coordinates or scans the payload.
2346    ///
2347    /// # Errors
2348    ///
2349    /// Returns [`StorageError`] when the coordinate rank or bounds are invalid
2350    /// or the compact metadata points outside the backing payload.
2351    ///
2352    /// # Examples
2353    ///
2354    /// ```
2355    /// use num_complex::Complex64;
2356    /// use tensor4all_tensorbackend::Storage;
2357    ///
2358    /// let real = Storage::from_diag_col_major(vec![2.0_f64, 3.0], 2).unwrap();
2359    /// assert_eq!(real.scalar_at(&[1]).unwrap().real(), 3.0);
2360    ///
2361    /// let complex = Storage::from_dense_col_major(
2362    ///     vec![Complex64::new(1.0, -2.0)], &[1],
2363    /// ).unwrap();
2364    /// assert_eq!(complex.scalar_at(&[0]).unwrap().as_c64(),
2365    ///     Some(Complex64::new(1.0, -2.0)));
2366    /// ```
2367    pub fn scalar_at(&self, payload_coords: &[usize]) -> StorageResult<BackendScalar> {
2368        storage_payload_dispatch!(&self.0, Payload => |payload| {
2369            payload
2370                .payload_scalar_at(payload_coords)
2371                .map(<Payload as StorageScalar>::to_backend_scalar)
2372        })
2373    }
2374
2375    /// Materialize dense logical values as a column-major `f64` buffer.
2376    ///
2377    /// For diagonal storage, off-diagonal entries are filled with zero.
2378    ///
2379    /// # Errors
2380    ///
2381    /// Returns [`StorageError::ScalarKindMismatch`] if the storage is complex,
2382    /// and [`StorageError::InvalidStructuredStorage`] if `logical_dims` does
2383    /// not match the stored logical dimensions or the logical element count
2384    /// overflows `usize`.
2385    ///
2386    /// # Examples
2387    ///
2388    /// ```
2389    /// use tensor4all_tensorbackend::Storage;
2390    ///
2391    /// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
2392    /// let dense = s.to_dense_f64_col_major_vec(&[2, 2]).unwrap();
2393    /// assert_eq!(dense, vec![1.0, 2.0, 3.0, 4.0]);
2394    /// ```
2395    pub fn to_dense_f64_col_major_vec(&self, logical_dims: &[usize]) -> StorageResult<Vec<f64>> {
2396        <f64 as StorageScalar>::dense_values(self, logical_dims)
2397    }
2398
2399    /// Materialize dense logical values as a column-major `f32` buffer.
2400    ///
2401    /// For diagonal storage, off-diagonal entries are filled with zero.
2402    ///
2403    /// # Errors
2404    ///
2405    /// Returns [`StorageError::ScalarKindMismatch`] unless the storage is
2406    /// `f32`-backed, and [`StorageError::InvalidStructuredStorage`] if
2407    /// `logical_dims` does not match the stored logical dimensions or the
2408    /// logical element count overflows `usize`.
2409    ///
2410    /// # Examples
2411    ///
2412    /// ```
2413    /// use tensor4all_tensorbackend::Storage;
2414    ///
2415    /// let diag = Storage::new_diag(vec![1.0_f32, 2.0]).unwrap();
2416    /// assert_eq!(diag.to_dense_f32_col_major_vec(&[2, 2]).unwrap(), vec![1.0, 0.0, 0.0, 2.0]);
2417    /// ```
2418    pub fn to_dense_f32_col_major_vec(&self, logical_dims: &[usize]) -> StorageResult<Vec<f32>> {
2419        <f32 as StorageScalar>::dense_values(self, logical_dims)
2420    }
2421
2422    /// Materialize dense logical values as a column-major `Complex64` buffer.
2423    ///
2424    /// # Errors
2425    ///
2426    /// Returns [`StorageError::ScalarKindMismatch`] unless the storage is
2427    /// `Complex64`-backed, and [`StorageError::InvalidStructuredStorage`] if
2428    /// `logical_dims` does not match the stored logical dimensions or the
2429    /// logical element count overflows `usize`.
2430    ///
2431    /// # Examples
2432    ///
2433    /// ```
2434    /// use tensor4all_tensorbackend::Storage;
2435    /// use num_complex::Complex64;
2436    ///
2437    /// let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
2438    /// let s = Storage::from_dense_col_major(data.clone(), &[2]).unwrap();
2439    /// let dense = s.to_dense_c64_col_major_vec(&[2]).unwrap();
2440    /// assert_eq!(dense, data);
2441    /// ```
2442    pub fn to_dense_c64_col_major_vec(
2443        &self,
2444        logical_dims: &[usize],
2445    ) -> StorageResult<Vec<Complex64>> {
2446        <Complex64 as StorageScalar>::dense_values(self, logical_dims)
2447    }
2448
2449    /// Materialize dense logical values as a column-major `Complex32` buffer.
2450    ///
2451    /// # Errors
2452    ///
2453    /// Returns [`StorageError::ScalarKindMismatch`] unless the storage is
2454    /// `Complex32`-backed, and [`StorageError::InvalidStructuredStorage`] if
2455    /// `logical_dims` does not match the stored logical dimensions or the
2456    /// logical element count overflows `usize`.
2457    ///
2458    /// # Examples
2459    ///
2460    /// ```
2461    /// use num_complex::Complex32;
2462    /// use tensor4all_tensorbackend::Storage;
2463    ///
2464    /// let data = vec![Complex32::new(1.0, -1.0), Complex32::new(2.0, 0.5)];
2465    /// let s = Storage::from_dense_col_major(data.clone(), &[2]).unwrap();
2466    /// assert_eq!(s.to_dense_c32_col_major_vec(&[2]).unwrap(), data);
2467    /// ```
2468    pub fn to_dense_c32_col_major_vec(
2469        &self,
2470        logical_dims: &[usize],
2471    ) -> StorageResult<Vec<Complex32>> {
2472        <Complex32 as StorageScalar>::dense_values(self, logical_dims)
2473    }
2474
2475    /// Convert this storage to dense storage.
2476    ///
2477    /// For Diag storage, creates a Dense storage with diagonal elements set
2478    /// and off-diagonal elements as zero. For Dense storage, returns a copy.
2479    ///
2480    /// # Errors
2481    ///
2482    /// Returns [`StorageError::InvalidStructuredStorage`] if `dims` does not
2483    /// match the stored logical dimensions or the dense storage cannot be built.
2484    ///
2485    /// # Examples
2486    ///
2487    /// ```
2488    /// use tensor4all_tensorbackend::Storage;
2489    ///
2490    /// let d = Storage::new_diag(vec![1.0_f64, 2.0]).unwrap();
2491    /// let dense = d.to_dense_storage(&[2, 2]).unwrap();
2492    /// assert!(dense.is_dense());
2493    /// let vals = dense.to_dense_f64_col_major_vec(&[2, 2]).unwrap();
2494    /// assert_eq!(vals, vec![1.0, 0.0, 0.0, 2.0]);
2495    /// ```
2496    pub fn to_dense_storage(&self, dims: &[usize]) -> StorageResult<Storage> {
2497        storage_payload_dispatch!(&self.0, Payload => |payload| {
2498            let values = checked_dense_payload(payload, dims)?;
2499            Storage::from_dense_col_major(values, dims).map_err(Self::invalid_storage_error)
2500        })
2501    }
2502
2503    /// Permute the storage data according to the given permutation.
2504    ///
2505    /// The `_dims` parameter is currently unused (reserved for future use).
2506    ///
2507    /// # Examples
2508    ///
2509    /// ```
2510    /// use tensor4all_tensorbackend::Storage;
2511    ///
2512    /// // Diagonal 2x2 tensor, permute axes (identity perm for diag is valid)
2513    /// let d = Storage::new_diag(vec![1.0_f64, 2.0]).unwrap();
2514    /// let t = d.permute_storage(&[2, 2], &[1, 0]).unwrap();
2515    /// assert!(t.is_diag());
2516    /// ```
2517    ///
2518    /// # Errors
2519    ///
2520    /// Returns [`StorageError::Operation`] when `perm` is not a permutation of
2521    /// the logical axes.
2522    pub fn permute_storage(&self, _dims: &[usize], perm: &[usize]) -> StorageResult<Storage> {
2523        storage_payload_dispatch!(&self.0, Payload => |payload| {
2524            Ok(payload.permute_logical_axes(perm)?.into_storage())
2525        })
2526    }
2527
2528    /// Extract real part from Complex64 storage as f64 storage.
2529    /// For f64 storage, returns a copy (clone).
2530    ///
2531    /// # Examples
2532    ///
2533    /// ```
2534    /// use tensor4all_tensorbackend::Storage;
2535    /// use num_complex::Complex64;
2536    ///
2537    /// let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
2538    /// let s = Storage::from_dense_col_major(data, &[2]).unwrap();
2539    /// let re = s.extract_real_part();
2540    /// assert!(re.is_f64());
2541    /// assert_eq!(re.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![1.0, 3.0]);
2542    /// ```
2543    pub fn extract_real_part(&self) -> Storage {
2544        storage_payload_dispatch!(&self.0, Payload => |payload| {
2545            payload
2546                .map_copy(<Payload as StorageScalar>::real_part)
2547                .into_storage()
2548        })
2549    }
2550
2551    /// Extract imaginary part from complex storage as the matching real storage.
2552    ///
2553    /// `Complex64` yields `f64` storage and `Complex32` yields `f32` storage.
2554    /// For real storage, returns zero storage of the same real dtype.
2555    ///
2556    /// # Examples
2557    ///
2558    /// ```
2559    /// use tensor4all_tensorbackend::Storage;
2560    /// use num_complex::Complex64;
2561    ///
2562    /// let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
2563    /// let s = Storage::from_dense_col_major(data, &[2]).unwrap();
2564    /// let im = s.extract_imag_part(&[2]);
2565    /// assert!(im.is_f64());
2566    /// assert_eq!(im.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![2.0, 4.0]);
2567    /// ```
2568    pub fn extract_imag_part(&self, _dims: &[usize]) -> Storage {
2569        storage_payload_dispatch!(&self.0, Payload => |payload| {
2570            payload
2571                .map_copy(<Payload as StorageScalar>::imag_part)
2572                .into_storage()
2573        })
2574    }
2575
2576    /// Convert real storage to its complex counterpart (zero imaginary part).
2577    ///
2578    /// `f64` becomes `Complex64` and `f32` becomes `Complex32`; complex storage
2579    /// returns a clone of the same dtype.
2580    ///
2581    /// # Examples
2582    ///
2583    /// ```
2584    /// use tensor4all_tensorbackend::Storage;
2585    ///
2586    /// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
2587    /// let c = s.to_complex_storage();
2588    /// assert!(c.is_c64());
2589    ///
2590    /// let narrow = Storage::from_dense_col_major(vec![1.0_f32], &[1]).unwrap();
2591    /// assert!(narrow.to_complex_storage().is_c32());
2592    /// ```
2593    pub fn to_complex_storage(&self) -> Storage {
2594        storage_payload_dispatch!(&self.0, Payload => |payload| {
2595            payload
2596                .map_copy(<Payload as StorageScalar>::into_complex)
2597                .into_storage()
2598        })
2599    }
2600
2601    /// Complex conjugate of all elements.
2602    ///
2603    /// For real storage, returns a clone (conjugate of a real number is itself).
2604    /// For complex storage, conjugates each element without changing the dtype.
2605    ///
2606    /// This is inspired by the `conj` operation in ITensorMPS.jl.
2607    ///
2608    /// # Examples
2609    /// ```
2610    /// use tensor4all_tensorbackend::Storage;
2611    /// use num_complex::Complex64;
2612    ///
2613    /// let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, -4.0)];
2614    /// let storage = Storage::from_dense_col_major(data, &[2]).unwrap();
2615    /// let conj_storage = storage.conj();
2616    ///
2617    /// let result = conj_storage.to_dense_c64_col_major_vec(&[2]).unwrap();
2618    /// assert_eq!(result[0], Complex64::new(1.0, -2.0));
2619    /// assert_eq!(result[1], Complex64::new(3.0, 4.0));
2620    /// ```
2621    pub fn conj(&self) -> Self {
2622        storage_payload_dispatch!(&self.0, Payload => |payload| {
2623            payload
2624                .map_copy(<Payload as StorageScalar>::conjugate)
2625                .into_storage()
2626        })
2627    }
2628
2629    /// Combine two real storages into their complex counterpart.
2630    ///
2631    /// `real_storage` becomes the real part and `imag_storage` the imaginary
2632    /// part, so `f64 + f64` yields `Complex64` storage and `f32 + f32` yields
2633    /// `Complex32` storage. Nothing is widened to a wider dtype.
2634    ///
2635    /// # Errors
2636    ///
2637    /// Returns [`StorageError::LengthMismatch`] if the payload lengths differ,
2638    /// [`StorageError::OperationNotSupported`] if the two storages do not share
2639    /// one real scalar kind, and
2640    /// [`StorageError::InvalidStructuredStorage`] if the result layout cannot
2641    /// be built.
2642    ///
2643    /// # Examples
2644    ///
2645    /// ```
2646    /// use tensor4all_tensorbackend::Storage;
2647    /// use num_complex::Complex64;
2648    ///
2649    /// let re = Storage::from_dense_col_major(vec![1.0_f64, 3.0], &[2]).unwrap();
2650    /// let im = Storage::from_dense_col_major(vec![2.0_f64, 4.0], &[2]).unwrap();
2651    /// let c = Storage::combine_to_complex(&re, &im).unwrap();
2652    /// assert!(c.is_c64());
2653    /// let vals = c.to_dense_c64_col_major_vec(&[2]).unwrap();
2654    /// assert_eq!(vals[0], Complex64::new(1.0, 2.0));
2655    /// assert_eq!(vals[1], Complex64::new(3.0, 4.0));
2656    ///
2657    /// let narrow_re = Storage::from_dense_col_major(vec![1.0_f32], &[1]).unwrap();
2658    /// let narrow_im = Storage::from_dense_col_major(vec![2.0_f32], &[1]).unwrap();
2659    /// assert!(Storage::combine_to_complex(&narrow_re, &narrow_im)
2660    ///     .unwrap()
2661    ///     .is_c32());
2662    /// ```
2663    pub fn combine_to_complex(
2664        real_storage: &Storage,
2665        imag_storage: &Storage,
2666    ) -> StorageResult<Storage> {
2667        match (&real_storage.0, &imag_storage.0) {
2668            (StorageRepr::F32(real), StorageRepr::F32(imag)) => {
2669                zip_payloads(real, imag, "combine_to_complex", |re, im| {
2670                    Complex32::new(re, im)
2671                })
2672            }
2673            (StorageRepr::F64(real), StorageRepr::F64(imag)) => {
2674                zip_payloads(real, imag, "combine_to_complex", |re, im| {
2675                    Complex64::new(re, im)
2676                })
2677            }
2678            _ => Err(StorageError::OperationNotSupported {
2679                operation: "combine_to_complex",
2680                left: real_storage.scalar_kind(),
2681                right: imag_storage.scalar_kind(),
2682            }),
2683        }
2684    }
2685
2686    /// Add two storages element-wise, returning `Result` on error instead of panicking.
2687    ///
2688    /// Both storages must have the same scalar type and payload length; mixed
2689    /// scalar kinds are refused rather than promoted.
2690    ///
2691    /// # Errors
2692    ///
2693    /// Returns [`StorageError::LengthMismatch`] if the lengths differ,
2694    /// [`StorageError::OperationNotSupported`] if the scalar types differ, and
2695    /// [`StorageError::InvalidStructuredStorage`] if the result layout cannot be
2696    /// built.
2697    ///
2698    /// # Examples
2699    ///
2700    /// ```
2701    /// use tensor4all_tensorbackend::Storage;
2702    ///
2703    /// let a = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
2704    /// let b = Storage::from_dense_col_major(vec![3.0_f64, 4.0], &[2]).unwrap();
2705    /// let c = a.try_add(&b).unwrap();
2706    /// assert_eq!(c.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![4.0, 6.0]);
2707    ///
2708    /// let narrow = Storage::from_dense_col_major(vec![0.5_f32, 0.5], &[2]).unwrap();
2709    /// let sum = narrow.try_add(&narrow).unwrap();
2710    /// assert!(sum.is_f32());
2711    /// assert_eq!(sum.to_dense_f32_col_major_vec(&[2]).unwrap(), vec![1.0, 1.0]);
2712    /// ```
2713    pub fn try_add(&self, other: &Storage) -> StorageResult<Storage> {
2714        storage_payload_same_dtype_dispatch!(&self.0, &other.0, Payload => |left, right| {
2715            zip_payloads(left, right, "addition", |x, y| x + y)
2716        },
2717        else Err(StorageError::OperationNotSupported {
2718            operation: "addition",
2719            left: self.scalar_kind(),
2720            right: other.scalar_kind(),
2721        }))
2722    }
2723
2724    /// Try to subtract two storages element-wise.
2725    ///
2726    /// Both storages must have the same scalar type and payload length; mixed
2727    /// scalar kinds are refused rather than promoted.
2728    ///
2729    /// # Errors
2730    ///
2731    /// Returns [`StorageError::LengthMismatch`] if the lengths differ,
2732    /// [`StorageError::OperationNotSupported`] if the scalar types differ, and
2733    /// [`StorageError::InvalidStructuredStorage`] if the result layout cannot be
2734    /// built.
2735    ///
2736    /// # Examples
2737    ///
2738    /// ```
2739    /// use tensor4all_tensorbackend::Storage;
2740    ///
2741    /// let a = Storage::from_dense_col_major(vec![5.0_f64, 7.0], &[2]).unwrap();
2742    /// let b = Storage::from_dense_col_major(vec![1.0_f64, 3.0], &[2]).unwrap();
2743    /// let c = a.try_sub(&b).unwrap();
2744    /// assert_eq!(c.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![4.0, 4.0]);
2745    /// ```
2746    pub fn try_sub(&self, other: &Storage) -> StorageResult<Storage> {
2747        storage_payload_same_dtype_dispatch!(&self.0, &other.0, Payload => |left, right| {
2748            zip_payloads(left, right, "subtraction", |x, y| x - y)
2749        },
2750        else Err(StorageError::OperationNotSupported {
2751            operation: "subtraction",
2752            left: self.scalar_kind(),
2753            right: other.scalar_kind(),
2754        }))
2755    }
2756
2757    /// Scale storage by a dynamic scalar value.
2758    ///
2759    /// The payload keeps its width and gains a complex component when the
2760    /// scalar is complex (`f64` -> `Complex64`, `f32` -> `Complex32`), which is
2761    /// exactly [`scale_target_dtype`]. Real scalars never widen a narrow
2762    /// payload.
2763    ///
2764    /// # Examples
2765    ///
2766    /// ```
2767    /// use tensor4all_tensorbackend::{BackendScalar, Storage};
2768    ///
2769    /// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0], &[3]).unwrap();
2770    /// let scaled = s.scale(&BackendScalar::new_real(2.0));
2771    /// assert_eq!(scaled.to_dense_f64_col_major_vec(&[3]).unwrap(), vec![2.0, 4.0, 6.0]);
2772    ///
2773    /// let narrow = Storage::from_dense_col_major(vec![1.0_f32, 2.0], &[2]).unwrap();
2774    /// let complex = narrow.scale(&BackendScalar::new_complex(0.0, 1.0));
2775    /// assert!(complex.is_c32());
2776    /// ```
2777    pub fn scale(&self, scalar: &crate::BackendScalar) -> Storage {
2778        self * scalar.clone()
2779    }
2780
2781    /// Compute linear combination: `a * self + b * other`.
2782    ///
2783    /// Promotion has one rule, shared with [`Storage::scale`]: the two payload
2784    /// dtypes promote along the lattice `f32 < f64`, `Complex32 < Complex64`,
2785    /// real `<` complex, while a scalar never widens the payload dtype - it only
2786    /// adds a complex component at the promoted width. So `f32 + f32` with
2787    /// `f64` scalars stays `f32`, `f32 + f64` becomes `f64`, and a complex
2788    /// scalar turns an `f32` result into `Complex32`.
2789    ///
2790    /// # Errors
2791    ///
2792    /// Returns [`StorageError::LengthMismatch`] if the lengths differ,
2793    /// [`StorageError::OperationNotSupported`] when an operand dtype is not a
2794    /// supported floating or complex floating dtype, and
2795    /// [`StorageError::InvalidStructuredStorage`] if the result layout cannot be
2796    /// built.
2797    ///
2798    /// # Examples
2799    ///
2800    /// ```
2801    /// use tensor4all_tensorbackend::{BackendScalar, Storage};
2802    ///
2803    /// let x = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
2804    /// let y = Storage::from_dense_col_major(vec![3.0_f64, 4.0], &[2]).unwrap();
2805    /// let a = BackendScalar::new_real(2.0);
2806    /// let b = BackendScalar::new_real(3.0);
2807    /// // result = 2*[1,2] + 3*[3,4] = [11, 16]
2808    /// let result = x.axpby(&a, &y, &b).unwrap();
2809    /// assert_eq!(result.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![11.0, 16.0]);
2810    ///
2811    /// // Real scalars do not widen a narrow payload.
2812    /// let narrow = Storage::from_dense_col_major(vec![1.0_f32], &[1]).unwrap();
2813    /// assert!(narrow.axpby(&a, &narrow, &b).unwrap().is_f32());
2814    ///
2815    /// // A complex scalar adds complexity at the payload width.
2816    /// use num_complex::Complex32;
2817    /// let mixed = narrow
2818    ///     .axpby(
2819    ///         &BackendScalar::from(Complex32::new(0.0, 1.0)),
2820    ///         &narrow,
2821    ///         &BackendScalar::from(1.0_f32),
2822    ///     )
2823    ///     .unwrap();
2824    /// assert!(mixed.is_c32());
2825    /// assert_eq!(
2826    ///     mixed.to_dense_c32_col_major_vec(&[1]).unwrap(),
2827    ///     vec![Complex32::new(1.0, 1.0)],
2828    /// );
2829    /// ```
2830    pub fn axpby(
2831        &self,
2832        a: &crate::BackendScalar,
2833        other: &Storage,
2834        b: &crate::BackendScalar,
2835    ) -> StorageResult<Storage> {
2836        if self.len() != other.len() {
2837            return Err(StorageError::LengthMismatch {
2838                operation: "axpby",
2839                left: self.len(),
2840                right: other.len(),
2841            });
2842        }
2843
2844        // One promotion rule with `scale`: the payloads promote along the lattice, then the scalars may
2845        // add a complex component at that width but never widen it.
2846        let payload_dtype =
2847            promote_float_dtypes([self.dtype(), other.dtype()]).ok_or_else(|| {
2848                StorageError::OperationNotSupported {
2849                    operation: "axpby",
2850                    left: self.scalar_kind(),
2851                    right: other.scalar_kind(),
2852                }
2853            })?;
2854        let target = scale_target_dtype(payload_dtype, scalar_dtype(a))
2855            .and_then(|dtype| scale_target_dtype(dtype, scalar_dtype(b)))
2856            .map_err(|_| StorageError::OperationNotSupported {
2857                operation: "axpby",
2858                left: self.scalar_kind(),
2859                right: other.scalar_kind(),
2860            })?;
2861        let (a_re, a_im) = (a.real(), a.imag());
2862        let (b_re, b_im) = (b.real(), b.imag());
2863
2864        storage_dtype_dispatch!(target, Result => {
2865            let values: Vec<Result> =
2866                storage_payload_pair_dispatch!(&self.0, &other.0, Left, Right => |left, right| {
2867                    left.data()
2868                        .iter()
2869                        .zip(right.data().iter())
2870                        .map(|(x, y)| {
2871                            let (x_re, x_im) = <Left as StorageScalar>::widened_parts(*x);
2872                            let (y_re, y_im) = <Right as StorageScalar>::widened_parts(*y);
2873                            <Result as StorageScalar>::from_widened_parts(
2874                                a_re * x_re - a_im * x_im + b_re * y_re - b_im * y_im,
2875                                a_re * x_im + a_im * x_re + b_re * y_im + b_im * y_re,
2876                            )
2877                        })
2878                        .collect()
2879                });
2880            StructuredStorage::new(
2881                values,
2882                self.payload_dims().to_vec(),
2883                self.payload_strides().to_vec(),
2884                self.axis_classes().to_vec(),
2885            )
2886            .map(StructuredStorage::into_storage)
2887            .map_err(StorageError::from)
2888        }, else Err(StorageError::OperationNotSupported {
2889            operation: "axpby",
2890            left: self.scalar_kind(),
2891            right: other.scalar_kind(),
2892        }))
2893    }
2894}
2895
2896/// Result dtype of scaling a compact payload by a dynamic scalar.
2897///
2898/// The payload keeps its width and gains a complex component only when the
2899/// scalar is complex: `f64` scaled by a `Complex32` or `Complex64` scalar stays
2900/// `Complex64`, and `f32` scaled by a complex scalar stays `Complex32`. This is
2901/// the compact-storage counterpart of the eager scaling rule in
2902/// `tensor4all-core`, which delegates here so both surfaces agree.
2903///
2904/// # Errors
2905///
2906/// Returns [`StorageError::OperationNotSupported`] when either dtype is not a
2907/// supported floating or complex floating dtype.
2908///
2909/// # Examples
2910///
2911/// ```
2912/// use tensor4all_tensorbackend::scale_target_dtype;
2913/// use tenferro::DType;
2914///
2915/// assert_eq!(scale_target_dtype(DType::F64, DType::C32).unwrap(), DType::C64);
2916/// assert_eq!(scale_target_dtype(DType::F32, DType::C64).unwrap(), DType::C32);
2917/// assert_eq!(scale_target_dtype(DType::C32, DType::F64).unwrap(), DType::C32);
2918/// assert_eq!(scale_target_dtype(DType::F64, DType::F64).unwrap(), DType::F64);
2919/// assert!(scale_target_dtype(DType::I32, DType::F64).is_err());
2920/// ```
2921pub fn scale_target_dtype(payload: DType, scalar: DType) -> StorageResult<DType> {
2922    let width =
2923        float_lattice_width(payload).ok_or_else(|| StorageError::OperationNotSupported {
2924            operation: "scaling",
2925            left: dtype_label(payload),
2926            right: dtype_label(scalar),
2927        })?;
2928    if float_lattice_width(scalar).is_none() {
2929        return Err(StorageError::OperationNotSupported {
2930            operation: "scaling",
2931            left: dtype_label(payload),
2932            right: dtype_label(scalar),
2933        });
2934    }
2935    let complex =
2936        matches!(payload, DType::C32 | DType::C64) || matches!(scalar, DType::C32 | DType::C64);
2937    Ok(match (width, complex) {
2938        (32, false) => DType::F32,
2939        (64, false) => DType::F64,
2940        (32, true) => DType::C32,
2941        _ => DType::C64,
2942    })
2943}
2944
2945fn dtype_label(dtype: DType) -> &'static str {
2946    match dtype {
2947        DType::F32 => "f32",
2948        DType::F64 => "f64",
2949        DType::I32 => "i32",
2950        DType::I64 => "i64",
2951        DType::Bool => "bool",
2952        DType::C32 => "Complex32",
2953        DType::C64 => "Complex64",
2954        DType::External(_) => "external",
2955    }
2956}
2957
2958fn scalar_dtype(scalar: &BackendScalar) -> DType {
2959    scalar.as_native().dtype()
2960}
2961
2962/// Helper to get a mutable reference to storage, cloning if needed (COW).
2963///
2964/// Uses `Arc::make_mut` semantics: if the `Arc` has only one strong reference,
2965/// returns a mutable reference to the existing allocation. Otherwise clones
2966/// the inner value first.
2967///
2968/// # Examples
2969///
2970/// ```
2971/// use std::sync::Arc;
2972/// use tensor4all_tensorbackend::{make_mut_storage, Storage};
2973///
2974/// let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
2975/// let mut arc = Arc::new(s);
2976/// let s_mut = make_mut_storage(&mut arc);
2977/// // s_mut is now a mutable reference to Storage
2978/// assert!(s_mut.is_f64());
2979/// ```
2980pub fn make_mut_storage(arc: &mut Arc<Storage>) -> &mut Storage {
2981    Arc::make_mut(arc)
2982}
2983
2984/// Get the minimum dimension from a slice of dimensions.
2985///
2986/// Returns 1 for an empty slice. This is used for DiagTensor where all
2987/// indices must have the same dimension.
2988///
2989/// # Examples
2990///
2991/// ```
2992/// use tensor4all_tensorbackend::min_dim;
2993///
2994/// assert_eq!(min_dim(&[2, 3, 4]), 2);
2995/// assert_eq!(min_dim(&[5, 5, 5]), 5);
2996/// assert_eq!(min_dim(&[]), 1);
2997/// ```
2998pub fn min_dim(dims: &[usize]) -> usize {
2999    dims.iter().copied().min().unwrap_or(1)
3000}
3001
3002/// Contract two storage tensors along specified axes.
3003///
3004/// All storage is StructuredStorage; contraction is delegated to the native
3005/// tenferro backend. This is the primary tensor contraction entry point at
3006/// the storage layer.
3007///
3008/// # Arguments
3009///
3010/// * `storage_a` - First tensor storage
3011/// * `dims_a` - Dimensions of the first tensor
3012/// * `axes_a` - Axes of the first tensor to contract
3013/// * `storage_b` - Second tensor storage
3014/// * `dims_b` - Dimensions of the second tensor
3015/// * `axes_b` - Axes of the second tensor to contract
3016/// * `result_dims` - Dimensions of the result tensor (empty for scalar result)
3017///
3018/// # Returns
3019/// A new `Storage` containing the contracted result.
3020///
3021/// # Errors
3022///
3023/// Returns [`StorageError::InvalidStructuredStorage`] if the axis lists differ
3024/// in length, an axis is out of range, contracted dimensions do not match, or
3025/// the native backend rejects the contraction.
3026///
3027/// # Examples
3028///
3029/// ```
3030/// use tensor4all_tensorbackend::{contract_storage, Storage};
3031///
3032/// // Matrix-vector multiply: A(2x3) * v(3) -> result(2)
3033/// let a = Storage::from_dense_col_major(
3034///     vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3],
3035/// ).unwrap();
3036/// let v = Storage::from_dense_col_major(vec![1.0, 1.0, 1.0], &[3]).unwrap();
3037/// let result = contract_storage(&a, &[2, 3], &[1], &v, &[3], &[0], &[2]).unwrap();
3038/// // Row sums: [1+3+5, 2+4+6] = [9, 12]
3039/// let vals = result.to_dense_f64_col_major_vec(&[2]).unwrap();
3040/// assert!((vals[0] - 9.0).abs() < 1e-10);
3041/// assert!((vals[1] - 12.0).abs() < 1e-10);
3042/// ```
3043pub fn contract_storage(
3044    storage_a: &Storage,
3045    dims_a: &[usize],
3046    axes_a: &[usize],
3047    storage_b: &Storage,
3048    dims_b: &[usize],
3049    axes_b: &[usize],
3050    result_dims: &[usize],
3051) -> StorageResult<Storage> {
3052    try_contract_storage(
3053        storage_a,
3054        dims_a,
3055        axes_a,
3056        storage_b,
3057        dims_b,
3058        axes_b,
3059        result_dims,
3060    )
3061}
3062
3063fn try_contract_storage(
3064    storage_a: &Storage,
3065    dims_a: &[usize],
3066    axes_a: &[usize],
3067    storage_b: &Storage,
3068    dims_b: &[usize],
3069    axes_b: &[usize],
3070    result_dims: &[usize],
3071) -> StorageResult<Storage> {
3072    if axes_a.len() != axes_b.len() {
3073        return Err(StorageError::InvalidStructuredStorage(format!(
3074            "contract axes lengths must match: {} != {}",
3075            axes_a.len(),
3076            axes_b.len()
3077        )));
3078    }
3079
3080    for (&a_axis, &b_axis) in axes_a.iter().zip(axes_b.iter()) {
3081        let Some(&a_dim) = dims_a.get(a_axis) else {
3082            return Err(StorageError::InvalidStructuredStorage(format!(
3083                "contract axis {a_axis} is out of range for left dims {dims_a:?}"
3084            )));
3085        };
3086        let Some(&b_dim) = dims_b.get(b_axis) else {
3087            return Err(StorageError::InvalidStructuredStorage(format!(
3088                "contract axis {b_axis} is out of range for right dims {dims_b:?}"
3089            )));
3090        };
3091        if a_dim != b_dim {
3092            return Err(StorageError::InvalidStructuredStorage(format!(
3093                "contracted dimensions must match: dims_a[{a_axis}] = {a_dim} != dims_b[{b_axis}] = {b_dim}"
3094            )));
3095        }
3096    }
3097
3098    crate::tenferro_bridge::contract_storage_native(
3099        storage_a,
3100        dims_a,
3101        axes_a,
3102        storage_b,
3103        dims_b,
3104        axes_b,
3105        result_dims,
3106    )
3107    .map_err(|err| StorageError::InvalidStructuredStorage(err.to_string()))
3108}
3109
3110/// Multiply storage by a real `f64` scalar.
3111///
3112/// The payload keeps its dtype: a narrow payload is not widened, and complex
3113/// payloads scale both components.
3114impl Mul<f64> for &Storage {
3115    type Output = Storage;
3116
3117    fn mul(self, scalar: f64) -> Self::Output {
3118        storage_payload_dispatch!(&self.0, Payload => |payload| {
3119            payload
3120                .map_copy(|value| {
3121                    let (re, im) = <Payload as StorageScalar>::widened_parts(value);
3122                    <Payload as StorageScalar>::from_widened_parts(re * scalar, im * scalar)
3123                })
3124                .into_storage()
3125        })
3126    }
3127}
3128
3129/// Multiply storage by a `Complex64` scalar.
3130///
3131/// A real payload is promoted to its complex counterpart of the same width
3132/// (`f64` -> `Complex64`, `f32` -> `Complex32`); complex payloads keep their
3133/// dtype.
3134impl Mul<Complex64> for &Storage {
3135    type Output = Storage;
3136
3137    fn mul(self, scalar: Complex64) -> Self::Output {
3138        let target = if self.is_complex() {
3139            self.dtype()
3140        } else {
3141            scale_target_dtype(self.dtype(), DType::C64)
3142                .unwrap_or_else(|error| crate::invariant_violated("complex scaling", error))
3143        };
3144        storage_dtype_dispatch!(target, Result => {
3145            let values: Vec<Result> = storage_payload_dispatch!(&self.0, Source => |payload| {
3146                payload
3147                    .data()
3148                    .iter()
3149                    .map(|value| {
3150                        let (re, im) = <Source as StorageScalar>::widened_parts(*value);
3151                        <Result as StorageScalar>::from_widened_parts(
3152                            re * scalar.re - im * scalar.im,
3153                            re * scalar.im + im * scalar.re,
3154                        )
3155                    })
3156                    .collect()
3157            });
3158            rebuild_payload(
3159                self.payload_dims(),
3160                self.payload_strides(),
3161                self.axis_classes(),
3162                values,
3163            )
3164        }, else crate::invariant_violated(
3165            "complex scaling",
3166            anyhow!("unsupported storage dtype {:?}", self.dtype()),
3167        ))
3168    }
3169}
3170
3171/// Multiply storage by a dynamic [`BackendScalar`].
3172///
3173/// A real scalar delegates to the real-scaling implementation, so a complex payload's components scale
3174/// independently and IEEE values propagate as they always have (`inf * 1` stays `inf` instead of turning
3175/// into `inf * 0 = NaN` through the complex product). A complex scalar goes through the complex path,
3176/// which keeps the payload's width and gains a complex component on a real payload.
3177impl Mul<BackendScalar> for &Storage {
3178    type Output = Storage;
3179
3180    fn mul(self, scalar: BackendScalar) -> Self::Output {
3181        if scalar.is_complex() {
3182            self * Complex64::from(scalar)
3183        } else {
3184            self * scalar.real()
3185        }
3186    }
3187}
3188
3189#[cfg(test)]
3190mod tests;