Struct StructuredStorage 

pub struct StructuredStorage<T> { /* private fields */ }

Structured tensor snapshot storage.

data and strides describe the payload tensor, while axis_classes describes how logical axes map onto payload axes. Logical flat-buffer semantics are column-major. A strided payload may contain unused backing gaps; reductions and nonfinite scans visit only entries addressed by the payload dimensions and strides.

A dense tensor has axis_classes = [0, 1, ..., rank-1] (each logical axis maps to a distinct payload axis). A diagonal tensor has axis_classes = [0, 0, ..., 0] (all logical axes share one payload axis), storing only the diagonal entries.

Examples

use tensor4all_tensorbackend::StructuredStorage;

// Dense 2x3 storage, column-major: [[1,3,5],[2,4,6]]
let dense = StructuredStorage::from_dense_col_major(
    vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3],
).unwrap();
assert!(dense.is_dense());
assert!(!dense.is_diag());
assert_eq!(dense.logical_rank(), 2);
assert_eq!(dense.logical_dims(), vec![2, 3]);

// Diagonal 3x3 storage
let diag = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 2).unwrap();
assert!(diag.is_diag());
assert_eq!(diag.logical_dims(), vec![3, 3]);
assert_eq!(diag.len(), 3);

Implementations

impl<T> StructuredStorage<T>

pub fn new( data: Vec<T>, payload_dims: Vec<usize>, strides: Vec<isize>, axis_classes: Vec<usize>, ) -> Result<Self>

Creates a structured payload snapshot from explicit payload metadata.

payload_dims and strides describe the compressed payload tensor, while axis_classes maps logical axes onto payload axes in canonical first-appearance order.

Errors

Returns an error if:

• axis_classes is not in canonical first-appearance form
• payload_dims rank does not match axis_classes
• strides rank does not match payload_dims
• data length does not match the required storage length

Examples

use tensor4all_tensorbackend::StructuredStorage;

// Dense 2x3 with explicit column-major strides
let s = StructuredStorage::new(
    vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
    vec![2, 3],     // payload_dims
    vec![1, 2],     // column-major strides
    vec![0, 1],     // axis_classes: each axis is independent
).unwrap();
assert!(s.is_dense());
assert_eq!(s.len(), 6);

pub fn from_dense_col_major( data: Vec<T>, logical_dims: &[usize], ) -> StorageResult<Self>

Creates a dense structured snapshot from column-major logical data.

Errors

Returns an error when the data length does not match the logical dimension /// product (a shape mismatch).

Examples

use tensor4all_tensorbackend::StructuredStorage;

let s = StructuredStorage::from_dense_col_major(vec![10.0, 20.0, 30.0, 40.0], &[2, 2]).unwrap();
assert!(s.is_dense());
assert_eq!(s.data(), &[10.0, 20.0, 30.0, 40.0]);

pub fn from_diag_col_major( diag_data: Vec<T>, logical_rank: usize, ) -> StorageResult<Self>

Creates a diagonal structured snapshot from column-major diagonal data.

The resulting tensor has logical_rank axes, each of size diag_data.len(). Only the diagonal entries are stored.

Errors

Returns an error when the diagonal payload is incompatible with the logical /// rank (a shape mismatch).

Examples

use tensor4all_tensorbackend::StructuredStorage;

let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 2).unwrap();
assert!(d.is_diag());
assert_eq!(d.logical_dims(), vec![3, 3]);
assert_eq!(d.data(), &[1.0, 2.0, 3.0]);

pub fn data(&self) -> &[T]

Returns the payload data buffer as a slice.

Examples

use tensor4all_tensorbackend::StructuredStorage;

let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0], &[2]).unwrap();
assert_eq!(s.data(), &[1.0, 2.0]);

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

Returns the payload tensor dimensions.

For dense tensors, this equals the logical dimensions. For diagonal tensors, this is a single-element slice [n] where n is the diagonal length.

Examples

use tensor4all_tensorbackend::StructuredStorage;

let s = StructuredStorage::from_dense_col_major(vec![0.0; 6], &[2, 3]).unwrap();
assert_eq!(s.payload_dims(), &[2, 3]);

let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 3).unwrap();
assert_eq!(d.payload_dims(), &[2]);

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

Returns the payload tensor strides.

Examples

use tensor4all_tensorbackend::StructuredStorage;

// Column-major 2x3: strides are [1, 2]
let s = StructuredStorage::from_dense_col_major(vec![0.0; 6], &[2, 3]).unwrap();
assert_eq!(s.strides(), &[1, 2]);

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

Returns the canonical logical-to-payload axis classes.

Each entry maps a logical axis to a payload axis index. Repeated values indicate axes that share the same payload dimension (e.g., diagonal).

Examples

use tensor4all_tensorbackend::StructuredStorage;

let dense = StructuredStorage::from_dense_col_major(vec![0.0; 4], &[2, 2]).unwrap();
assert_eq!(dense.axis_classes(), &[0, 1]);

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

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

Returns the logical dimensions derived from payload_dims and axis_classes.

Examples

use tensor4all_tensorbackend::StructuredStorage;

let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 3).unwrap();
assert_eq!(d.logical_dims(), vec![3, 3, 3]);

pub fn logical_rank(&self) -> usize

Returns the logical rank (number of logical axes).

Examples

use tensor4all_tensorbackend::StructuredStorage;

let s = StructuredStorage::from_dense_col_major(vec![0.0; 6], &[2, 3]).unwrap();
assert_eq!(s.logical_rank(), 2);

pub fn is_dense(&self) -> bool

Returns true when the logical tensor is dense (each logical axis maps to a unique payload axis).

Examples

use tensor4all_tensorbackend::StructuredStorage;

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

let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
assert!(!d.is_dense());

pub fn is_diag(&self) -> bool

Returns true when the logical tensor is diagonal (rank >= 2 and all logical axes map to the same payload axis).

Examples

use tensor4all_tensorbackend::StructuredStorage;

let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
assert!(d.is_diag());

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

pub fn len(&self) -> usize

Returns the payload buffer length.

Examples

use tensor4all_tensorbackend::StructuredStorage;

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

let diag = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
assert_eq!(diag.len(), 2);

pub fn is_empty(&self) -> bool

Returns true when the payload buffer is empty.

Examples

use tensor4all_tensorbackend::StructuredStorage;

let empty = StructuredStorage::from_dense_col_major(Vec::<f64>::new(), &[0]).unwrap();
assert!(empty.is_empty());

let non_empty = StructuredStorage::from_dense_col_major(vec![1.0], &[1]).unwrap();
assert!(!non_empty.is_empty());

pub fn dense_col_major_view_if_contiguous(&self) -> Option<&[T]>

Returns a borrowed view when the logical tensor is dense and the payload is already stored contiguously in column-major order.

Returns None for diagonal or non-contiguous payloads.

Examples

use tensor4all_tensorbackend::StructuredStorage;

let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0, 3.0], &[3]).unwrap();
assert_eq!(s.dense_col_major_view_if_contiguous(), Some(&[1.0, 2.0, 3.0][..]));

let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
assert_eq!(d.dense_col_major_view_if_contiguous(), None);

pub fn payload_col_major_view_if_contiguous(&self) -> Option<&[T]>

Returns a borrowed compact-payload view when the payload is already stored contiguously in column-major order.

impl<T: Clone> StructuredStorage<T>

pub fn payload_col_major_vec(&self) -> Vec<T>

Materializes the payload tensor as a contiguous column-major buffer.

If the payload is already column-major, returns a clone.

Examples

use tensor4all_tensorbackend::StructuredStorage;

let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]).unwrap();
assert_eq!(s.payload_col_major_vec(), vec![1.0, 2.0, 3.0, 4.0]);

pub fn permute_logical_axes(&self, perm: &[usize]) -> StorageResult<Self>

Returns a copy of the storage with logical axes permuted.

Errors

Returns an error when the permutation is not a valid reordering of the axes /// (an invalid-index failure).

Examples

use tensor4all_tensorbackend::StructuredStorage;

// Diagonal 3x3x3 tensor; permute axes (identity for diag is always valid)
let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0, 3.0], 3).unwrap();
let p = d.permute_logical_axes(&[2, 0, 1]).unwrap();
// Diagonal: all axes share the same dimension, so dims stay the same
assert_eq!(p.logical_dims(), vec![3, 3, 3]);
assert!(p.is_diag());

impl<T: Copy> StructuredStorage<T>

pub fn map_copy<U>(&self, f: impl FnMut(T) -> U) -> StructuredStorage<U>

Maps payload elements while preserving payload metadata and axis classes.

Examples

use tensor4all_tensorbackend::StructuredStorage;

let s = StructuredStorage::from_dense_col_major(vec![1.0, 2.0, 3.0], &[3]).unwrap();
let doubled = s.map_copy(|x| x * 2.0);
assert_eq!(doubled.data(), &[2.0, 4.0, 6.0]);

impl<T: Copy + Default> StructuredStorage<T>

pub fn logical_dense_col_major_vec(&self) -> StorageResult<Vec<T>>

Materializes the logical tensor as a contiguous column-major dense buffer.

Repeated entries in axis_classes encode equality constraints between logical axes. Logical indices that violate those constraints are structural zeros in the dense materialization.

Errors

Returns an error if the logical dimension product overflows usize.

Examples

use tensor4all_tensorbackend::StructuredStorage;

// Diagonal [1, 2] in 2x2 becomes [1, 0, 0, 2] column-major
let d = StructuredStorage::from_diag_col_major(vec![1.0, 2.0], 2).unwrap();
assert_eq!(d.logical_dense_col_major_vec().unwrap(), vec![1.0, 0.0, 0.0, 2.0]);

Trait Implementations

impl<T: Clone> Clone for StructuredStorage<T>

fn clone(&self) -> StructuredStorage<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for StructuredStorage<T>

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

Formats the value using the given formatter.

impl<T: PartialEq> PartialEq for StructuredStorage<T>

fn eq(&self, other: &StructuredStorage<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq> StructuralPartialEq for StructuredStorage<T>