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;