Struct Storage 

pub struct Storage(/* private fields */);

Storage backend for tensor data.

Public callers interact with this opaque wrapper through constructors and high-level query/materialization methods.

Examples

use tensor4all_tensorbackend::Storage;

// Dense 2x3 matrix stored column-major: [[1,2,3],[4,5,6]]
let data = vec![1.0_f64, 4.0, 2.0, 5.0, 3.0, 6.0];
let s = Storage::from_dense_col_major(data, &[2, 3]).unwrap();
assert!(s.is_f64());
assert!(!s.is_complex());

// Diagonal storage: 2x2 identity-like diagonal
let diag = Storage::new_diag(vec![1.0_f64, 2.0]);
assert!(diag.is_f64());

Implementations

impl Storage

pub fn from_dense_col_major<T>( data: Vec<T>, logical_dims: &[usize], ) -> Result<Storage, Error>

where T: StorageScalar,

Create dense storage from column-major logical values (generic over scalar type).

The scalar type is inferred from the data argument.

Examples

use tensor4all_tensorbackend::Storage;

// 2x2 matrix, column-major: [[1,3],[2,4]]
let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
assert!(s.is_f64());
assert!(s.is_dense());
assert_eq!(s.len(), 4);

pub fn from_diag_col_major<T>( diag_data: Vec<T>, logical_rank: usize, ) -> Result<Storage, Error>

where T: StorageScalar,

Create diagonal storage from column-major diagonal payload values (generic over scalar type).

Creates a rank-2 diagonal storage by default. The scalar type is inferred from diag_data.

Errors

Currently infallible for valid data, but returns Result for consistency.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_diag_col_major(vec![1.0_f64, 2.0, 3.0], 2).unwrap();
assert!(s.is_diag());
assert!(s.is_f64());
assert_eq!(s.len(), 3);

pub fn new_dense<T>(size: usize) -> Storage

where T: StorageScalar + Default,

Create a new 1D zero-initialized dense storage (generic over scalar type).

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::new_dense::<f64>(5);
assert!(s.is_dense());
assert_eq!(s.len(), 5);
assert!((s.max_abs()).abs() < 1e-10);

pub fn new_diag<T>(diag_data: Vec<T>) -> Storage

where T: StorageScalar,

Create a new diagonal storage with the given diagonal data (generic over scalar type).

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::new_diag(vec![1.0_f64, 2.0, 3.0]);
assert!(s.is_diag());
assert!(s.is_f64());

pub fn new_structured<T>( data: Vec<T>, payload_dims: Vec<usize>, strides: Vec<isize>, axis_classes: Vec<usize>, ) -> Result<Storage, Error>

where T: StorageScalar,

Create a new structured storage (generic over scalar type).

Errors

Returns an error if the structured metadata is inconsistent (see StructuredStorage::new for details).

Examples

use tensor4all_tensorbackend::Storage;

// Diagonal-like structured storage: axis_classes = [0, 0]
let s = Storage::new_structured(
    vec![1.0_f64, 2.0],
    vec![2],         // payload_dims
    vec![1],         // strides
    vec![0, 0],      // axis_classes: both axes map to payload axis 0
).unwrap();
assert!(s.is_diag());

pub fn from_dense_f64_col_major( data: Vec<f64>, logical_dims: &[usize], ) -> Result<Storage, Error>

Create dense f64 storage from column-major logical values.

Errors

Returns an error if data.len() does not match the product of logical_dims.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_dense_f64_col_major(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
assert!(s.is_f64());
assert!(s.is_dense());

pub fn from_dense_c64_col_major( data: Vec<Complex<f64>>, logical_dims: &[usize], ) -> Result<Storage, Error>

Create dense Complex64 storage from column-major logical values.

Errors

Returns an error if data.len() does not match the product of logical_dims.

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let data = vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 1.0)];
let s = Storage::from_dense_c64_col_major(data, &[2]).unwrap();
assert!(s.is_c64());
assert!(s.is_dense());

pub fn from_diag_f64_col_major( diag_data: Vec<f64>, logical_rank: usize, ) -> Result<Storage, Error>

Create diagonal f64 storage from column-major diagonal payload values.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_diag_f64_col_major(vec![1.0, 2.0], 2).unwrap();
assert!(s.is_diag());
assert!(s.is_f64());

pub fn from_diag_c64_col_major( diag_data: Vec<Complex<f64>>, logical_rank: usize, ) -> Result<Storage, Error>

Create diagonal Complex64 storage from column-major diagonal payload values.

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let data = vec![Complex64::new(1.0, 0.0), Complex64::new(0.0, 1.0)];
let s = Storage::from_diag_c64_col_major(data, 2).unwrap();
assert!(s.is_diag());
assert!(s.is_c64());

pub fn is_dense(&self) -> bool

Check if this storage is logically dense.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
assert!(s.is_dense());

let d = Storage::new_diag(vec![1.0_f64, 2.0]);
assert!(!d.is_dense());

pub fn is_diag(&self) -> bool

Check if this storage is a Diag storage type.

Examples

use tensor4all_tensorbackend::Storage;

let d = Storage::new_diag(vec![1.0_f64, 2.0]);
assert!(d.is_diag());

pub fn storage_kind(&self) -> StorageKind

Returns the compact layout class for this storage.

The return value is metadata-only and never materializes dense logical values. Use it to choose whether to read compact payload metadata or dense logical values.

Examples

use tensor4all_tensorbackend::{Storage, StorageKind};

let structured = Storage::new_structured(
    vec![1.0_f64, 2.0],
    vec![2],
    vec![1],
    vec![0, 0],
).unwrap();
assert_eq!(structured.storage_kind(), StorageKind::Diagonal);

pub fn logical_dims(&self) -> Vec<usize>

Returns the logical tensor dimensions represented by this storage.

The dimensions are derived from payload dimensions and axis_classes.

Examples

use tensor4all_tensorbackend::Storage;

let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
assert_eq!(diag.logical_dims(), vec![2, 2]);

pub fn logical_rank(&self) -> usize

Returns the logical tensor rank represented by this storage.

This equals axis_classes().len(), not necessarily payload_dims().len().

Examples

use tensor4all_tensorbackend::Storage;

let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 3).unwrap();
assert_eq!(diag.logical_rank(), 3);
assert_eq!(diag.payload_dims(), &[2]);

pub fn payload_dims(&self) -> &[usize]

Returns the compact payload dimensions.

For dense storage these match logical dimensions. For diagonal storage this is rank-1 even when the logical tensor has multiple axes.

Examples

use tensor4all_tensorbackend::Storage;

let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
assert_eq!(diag.payload_dims(), &[2]);

pub fn payload_strides(&self) -> &[isize]

Returns the compact payload strides.

Strides are measured in stored scalar elements and describe the compact payload buffer, not the logical dense tensor.

Examples

use tensor4all_tensorbackend::Storage;

let dense = Storage::from_dense_col_major(vec![0.0_f64; 6], &[2, 3]).unwrap();
assert_eq!(dense.payload_strides(), &[1, 2]);

pub fn axis_classes(&self) -> &[usize]

Returns logical-axis equivalence classes for this storage.

Repeated class labels mean the corresponding logical axes share one payload axis. Dense storage has [0, 1, ...]; diagonal storage has repeated zero labels.

Examples

use tensor4all_tensorbackend::Storage;

let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
assert_eq!(diag.axis_classes(), &[0, 0]);

pub fn payload_len(&self) -> usize

Returns the number of stored compact payload elements.

For dense storage this equals the logical dense length. For diagonal and structured storage this is the compact payload length.

Examples

use tensor4all_tensorbackend::Storage;

let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
assert_eq!(diag.payload_len(), 2);

pub fn payload_f64_col_major_vec(&self) -> Result<Vec<f64>, String>

Copies the compact f64 payload in column-major payload order.

This does not materialize logical dense values. For diagonal storage the returned vector contains only diagonal payload values.

Errors

Returns an error if the storage scalar type is not f64.

Examples

use tensor4all_tensorbackend::Storage;

let diag = Storage::from_diag_col_major(vec![1.0_f64, 2.0], 2).unwrap();
assert_eq!(diag.payload_f64_col_major_vec().unwrap(), vec![1.0, 2.0]);

pub fn payload_c64_col_major_vec(&self) -> Result<Vec<Complex<f64>>, String>

Copies the compact Complex64 payload in column-major payload order.

This does not materialize logical dense values. Complex payloads are returned as native Rust Complex64 values.

Errors

Returns an error if the storage scalar type is not Complex64.

Examples

use num_complex::Complex64;
use tensor4all_tensorbackend::Storage;

let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
let diag = Storage::from_diag_col_major(data.clone(), 2).unwrap();
assert_eq!(diag.payload_c64_col_major_vec().unwrap(), data);

pub fn is_f64(&self) -> bool

Check if this storage uses f64 scalar type.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_dense_col_major(vec![1.0_f64], &[1]).unwrap();
assert!(s.is_f64());
assert!(!s.is_c64());

pub fn is_c64(&self) -> bool

Check if this storage uses Complex64 scalar type.

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let s = Storage::from_dense_col_major(
    vec![Complex64::new(1.0, 0.0)], &[1],
).unwrap();
assert!(s.is_c64());

pub fn is_complex(&self) -> bool

Check if this storage uses complex scalar type.

This is an alias for is_c64().

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let s = Storage::from_dense_col_major(
    vec![Complex64::new(1.0, 0.0)], &[1],
).unwrap();
assert!(s.is_complex());

let r = Storage::from_dense_col_major(vec![1.0_f64], &[1]).unwrap();
assert!(!r.is_complex());

pub fn len(&self) -> usize

Get the length of the storage payload (number of stored elements).

For dense storage this equals the product of logical dimensions. For diagonal storage this equals the diagonal length.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0], &[3]).unwrap();
assert_eq!(s.len(), 3);

let d = Storage::new_diag(vec![1.0_f64, 2.0]);
assert_eq!(d.len(), 2);

pub fn is_empty(&self) -> bool

Check if the storage is empty.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::new_dense::<f64>(0);
assert!(s.is_empty());

let s2 = Storage::new_dense::<f64>(3);
assert!(!s2.is_empty());

pub fn sum<T>(&self) -> T

where T: SumFromStorage,

Sum all elements, converting to type T.

Example

use tensor4all_tensorbackend::Storage;
let s = Storage::from_dense_col_major(vec![1.0, 2.0, 3.0], &[3]).unwrap();
assert_eq!(s.sum::<f64>(), 6.0);

pub fn max_abs(&self) -> f64

Maximum absolute value over all stored elements.

For real storage this is max(|x|), and for complex storage this is max(norm(z)).

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_dense_col_major(vec![-3.0_f64, 1.0, 2.0], &[3]).unwrap();
assert!((s.max_abs() - 3.0).abs() < 1e-10);

pub fn to_dense_f64_col_major_vec( &self, logical_dims: &[usize], ) -> Result<Vec<f64>, String>

Materialize dense logical values as a column-major f64 buffer.

For diagonal storage, off-diagonal entries are filled with zero.

Errors

Returns an error if the storage is complex or logical_dims does not match the stored logical dimensions.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
let dense = s.to_dense_f64_col_major_vec(&[2, 2]).unwrap();
assert_eq!(dense, vec![1.0, 2.0, 3.0, 4.0]);

pub fn to_dense_c64_col_major_vec( &self, logical_dims: &[usize], ) -> Result<Vec<Complex<f64>>, String>

Materialize dense logical values as a column-major Complex64 buffer.

Errors

Returns an error if the storage is real or logical_dims does not match the stored logical dimensions.

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
let s = Storage::from_dense_col_major(data.clone(), &[2]).unwrap();
let dense = s.to_dense_c64_col_major_vec(&[2]).unwrap();
assert_eq!(dense, data);

pub fn to_dense_storage(&self, dims: &[usize]) -> Storage

Convert this storage to dense storage.

For Diag storage, creates a Dense storage with diagonal elements set and off-diagonal elements as zero. For Dense storage, returns a copy.

Panics

Panics if dims does not match the stored logical dimensions.

Examples

use tensor4all_tensorbackend::Storage;

let d = Storage::new_diag(vec![1.0_f64, 2.0]);
let dense = d.to_dense_storage(&[2, 2]);
assert!(dense.is_dense());
let vals = dense.to_dense_f64_col_major_vec(&[2, 2]).unwrap();
assert_eq!(vals, vec![1.0, 0.0, 0.0, 2.0]);

pub fn permute_storage(&self, _dims: &[usize], perm: &[usize]) -> Storage

Permute the storage data according to the given permutation.

The _dims parameter is currently unused (reserved for future use).

Examples

use tensor4all_tensorbackend::Storage;

// Diagonal 2x2 tensor, permute axes (identity perm for diag is valid)
let d = Storage::new_diag(vec![1.0_f64, 2.0]);
let t = d.permute_storage(&[2, 2], &[1, 0]);
assert!(t.is_diag());

pub fn extract_real_part(&self) -> Storage

Extract real part from Complex64 storage as f64 storage. For f64 storage, returns a copy (clone).

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
let s = Storage::from_dense_col_major(data, &[2]).unwrap();
let re = s.extract_real_part();
assert!(re.is_f64());
assert_eq!(re.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![1.0, 3.0]);

pub fn extract_imag_part(&self, _dims: &[usize]) -> Storage

Extract imaginary part from Complex64 storage as f64 storage. For f64 storage, returns zero storage.

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)];
let s = Storage::from_dense_col_major(data, &[2]).unwrap();
let im = s.extract_imag_part(&[2]);
assert!(im.is_f64());
assert_eq!(im.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![2.0, 4.0]);

pub fn to_complex_storage(&self) -> Storage

Convert f64 storage to Complex64 storage (real part only, imaginary part is zero). For Complex64 storage, returns a clone.

Examples

use tensor4all_tensorbackend::Storage;

let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
let c = s.to_complex_storage();
assert!(c.is_c64());

pub fn conj(&self) -> Storage

Complex conjugate of all elements.

For real (f64) storage, returns a clone (conjugate of real is identity). For complex (Complex64) storage, conjugates each element.

This is inspired by the conj operation in ITensorMPS.jl.

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let data = vec![Complex64::new(1.0, 2.0), Complex64::new(3.0, -4.0)];
let storage = Storage::from_dense_col_major(data, &[2]).unwrap();
let conj_storage = storage.conj();

let result = conj_storage.to_dense_c64_col_major_vec(&[2]).unwrap();
assert_eq!(result[0], Complex64::new(1.0, -2.0));
assert_eq!(result[1], Complex64::new(3.0, 4.0));

pub fn combine_to_complex( real_storage: &Storage, imag_storage: &Storage, ) -> Storage

Combine two f64 storages into Complex64 storage.

real_storage becomes the real part, imag_storage becomes the imaginary part. Formula: real + i * imag.

Panics

Panics if either storage is not f64, or if their lengths differ.

Examples

use tensor4all_tensorbackend::Storage;
use num_complex::Complex64;

let re = Storage::from_dense_col_major(vec![1.0_f64, 3.0], &[2]).unwrap();
let im = Storage::from_dense_col_major(vec![2.0_f64, 4.0], &[2]).unwrap();
let c = Storage::combine_to_complex(&re, &im);
assert!(c.is_c64());
let vals = c.to_dense_c64_col_major_vec(&[2]).unwrap();
assert_eq!(vals[0], Complex64::new(1.0, 2.0));
assert_eq!(vals[1], Complex64::new(3.0, 4.0));

pub fn try_add(&self, other: &Storage) -> Result<Storage, String>

Add two storages element-wise, returning Result on error instead of panicking.

Both storages must have the same type and length.

Errors

Returns an error if storage types or lengths don’t match.

Examples

use tensor4all_tensorbackend::Storage;

let a = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
let b = Storage::from_dense_col_major(vec![3.0_f64, 4.0], &[2]).unwrap();
let c = a.try_add(&b).unwrap();
assert_eq!(c.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![4.0, 6.0]);

pub fn try_sub(&self, other: &Storage) -> Result<Storage, String>

Try to subtract two storages element-wise.

Errors

Returns an error if the storages have different types or lengths.

Examples

use tensor4all_tensorbackend::Storage;

let a = Storage::from_dense_col_major(vec![5.0_f64, 7.0], &[2]).unwrap();
let b = Storage::from_dense_col_major(vec![1.0_f64, 3.0], &[2]).unwrap();
let c = a.try_sub(&b).unwrap();
assert_eq!(c.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![4.0, 4.0]);

pub fn scale(&self, scalar: &Scalar) -> Storage

Scale storage by a scalar value.

If the scalar is complex but the storage is real, the storage is promoted to complex.

Examples

use tensor4all_tensorbackend::{AnyScalar, Storage};

let s = Storage::from_dense_col_major(vec![1.0_f64, 2.0, 3.0], &[3]).unwrap();
let scaled = s.scale(&AnyScalar::new_real(2.0));
assert_eq!(scaled.to_dense_f64_col_major_vec(&[3]).unwrap(), vec![2.0, 4.0, 6.0]);

pub fn axpby( &self, a: &Scalar, other: &Storage, b: &Scalar, ) -> Result<Storage, String>

Compute linear combination: a * self + b * other.

Errors

Returns an error if the storages have different types or lengths. If any scalar is complex, the result is promoted to complex.

Examples

use tensor4all_tensorbackend::{AnyScalar, Storage};

let x = Storage::from_dense_col_major(vec![1.0_f64, 2.0], &[2]).unwrap();
let y = Storage::from_dense_col_major(vec![3.0_f64, 4.0], &[2]).unwrap();
let a = AnyScalar::new_real(2.0);
let b = AnyScalar::new_real(3.0);
// result = 2*[1,2] + 3*[3,4] = [11, 16]
let result = x.axpby(&a, &y, &b).unwrap();
assert_eq!(result.to_dense_f64_col_major_vec(&[2]).unwrap(), vec![11.0, 16.0]);

Trait Implementations

impl Add<&Storage> for &Storage

Add two storages element-wise. Both storages must have the same type and length.

Panics

Panics if storage types don’t match or lengths differ.

Note

Prefer using Storage::try_add which returns a Result instead of panicking. This trait implementation is kept for convenience but may panic on invalid inputs.

type Output = Storage

The resulting type after applying the + operator.

fn add(self, rhs: &Storage) -> <&Storage as Add<&Storage>>::Output

Performs the + operation.

impl Clone for Storage

fn clone(&self) -> Storage

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Storage

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Mul<Complex<f64>> for &Storage

Multiply storage by a scalar (Complex64).

type Output = Storage

The resulting type after applying the * operator.

fn mul(self, scalar: Complex<f64>) -> <&Storage as Mul<Complex<f64>>>::Output

Performs the * operation.

impl Mul<Scalar> for &Storage

Multiply storage by a scalar (AnyScalar). May promote f64 storage to Complex64 when scalar is complex.

type Output = Storage

The resulting type after applying the * operator.

fn mul(self, scalar: Scalar) -> <&Storage as Mul<Scalar>>::Output

Performs the * operation.

impl Mul<f64> for &Storage

Multiply storage by a scalar (f64). For Complex64 storage, multiplies each element by the scalar (treated as real).

type Output = Storage

The resulting type after applying the * operator.

fn mul(self, scalar: f64) -> <&Storage as Mul<f64>>::Output

Performs the * operation.