Struct TensorData 

pub struct TensorData<St, L>
where
    St: Storage + StorageFor<L>,
    L: TensorLayout,
{ /* private fields */ }

Joined storage + layout bundle.

Construction goes through new, which asserts storage.flat_len() == layout.storage_extent(). The bound St: StorageFor<L> enforces flavor compatibility at the type level (only DenseStorage ⇔ DenseLayout, BlockSparseStorage ⇔ BlockSparseLayout).

Implementations

impl<T, S: Sector> TensorData<BlockSparseStorage<T>, BlockSparseLayout<S>>

pub fn zeros(indices: Vec<QNIndex<S>>, flux: S, order: MemoryOrder) -> Self

where T: Clone + Zero,

Construct a zero-filled BlockSparseTensorData with all flux-allowed blocks.

Cross-crate: the user-facing constructor is BlockSparseTensor::zeros, which pins memory order to the active backend. Direct callers (notably ariadnetor-linalg BSp kernel output-construction sites) that need an explicit order go through this helper or build TensorData::new(storage, layout) directly.

pub fn from_block_fn<F>( indices: Vec<QNIndex<S>>, flux: S, order: MemoryOrder, f: F, ) -> Self

where T: Clone + Zero, F: FnMut(&BlockCoord, &[usize]) -> Vec<T>,

Construct by populating each flux-allowed block from a closure.

The closure receives the block coordinate and its dense block shape (one entry per leg) and must return the block’s flat data in the layout’s memory order. Forbidden blocks are not queried. Block coordinates are visited in the layout’s lexicographic enumeration order.

Cross-crate: the user-facing constructor is BlockSparseTensor::from_block_fn, which pins memory order to the active backend.

Panics

Panics if the closure returns a Vec<T> whose length differs from product(block_shape) (the per-block element count).

pub fn random<R: Rng>( indices: Vec<QNIndex<S>>, flux: S, order: MemoryOrder, rng: &mut R, ) -> Self

where StandardUniform: Distribution<T>,

Construct with all flux-allowed blocks filled with random values from the standard distribution.

Cross-crate: the user-facing constructor is BlockSparseTensor::random, which pins memory order to the active backend.

pub fn block_data(&self, coord: &BlockCoord) -> Option<&[T]>

Data slice for a block identified by coordinate.

Returns None if the block is not stored (zero by symmetry).

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

Logical shape (total dimension per leg). Forwards to the layout.

pub fn rank(&self) -> usize

Rank (number of legs). Forwards to the layout.

pub fn flux(&self) -> &S

Conserved flux (total quantum number). Forwards to the layout.

pub fn indices(&self) -> &[QNIndex<S>]

Per-leg QN indices. Forwards to the layout.

pub fn num_blocks(&self) -> usize

Number of stored (non-zero) blocks. Forwards to the layout.

pub fn block_metas(&self) -> &[BlockMeta]

Block metadata (sorted by coordinate). Forwards to the layout.

pub fn is_allowed_block(&self, coord: &BlockCoord) -> bool

Check whether a block coordinate satisfies the flux conservation law. Forwards to the layout.

pub fn order(&self) -> MemoryOrder

Memory order the paired storage is laid out in. Forwards to the layout.

pub fn block_data_mut(&mut self, coord: &BlockCoord) -> Option<&mut [T]>

where T: Clone,

Mutable data slice for a block identified by coordinate (triggers CoW on the storage half if shared).

impl<T, S: Sector> TensorData<BlockSparseStorage<T>, BlockSparseLayout<S>>

where T: Scalar,

pub fn dagger(&self) -> Self

Hermitian adjoint: element-wise conjugation of the data, flip of every QNIndex direction (Out↔In), and dualization of the flux.

Block coordinates and packed offsets are preserved (BlockSparseLayout::dagger_layout reuses them). Involution: x.dagger().dagger() == x.

pub fn conj(&self) -> Self

Element-wise complex conjugate. Layout (including directions and flux) is preserved; use dagger when the adjoint structure is required for inner products.

pub fn stored_len(&self) -> usize

Total number of stored elements across all blocks. Forwards to the storage half.

pub fn norm_frobenius(&self) -> T::Real

Frobenius norm: √(Σ |element|²). Forwards to the storage half.

pub fn norm(&self) -> T::Real

Frobenius norm (alias for norm_frobenius).

pub fn normalize(&mut self) -> T::Real

Normalize to unit Frobenius norm in place. Returns the norm before normalization. Panics if the tensor has zero norm.

pub fn normalized(&self) -> (Self, T::Real)

Normalize and return a new tensor (out-of-place). Returns (normalized_tensor, original_norm). Panics if the tensor has zero norm.

impl<T, S: Sector> TensorData<BlockSparseStorage<T>, BlockSparseLayout<S>>

where T: Clone,

pub fn scale<F>(&mut self, factor: F)

where T: Mul<F, Output = T>, F: Clone,

Scale every stored element by a scalar factor in place (triggers CoW if shared).

pub fn scaled<F>(&self, factor: F) -> Self

where T: Mul<F, Output = T>, F: Clone,

Scale every stored element and return a new tensor (out-of-place).

impl<T> TensorData<DenseStorage<T>, DenseLayout>

where T: Clone,

pub fn get(&self, indices: &[usize]) -> T

Get element at multi-dimensional indices.

The flat index is computed using self.order().

Panics

Panics if indices are out of bounds.

pub fn set(&mut self, indices: &[usize], value: T)

Set element at multi-dimensional indices (triggers CoW on the storage half if shared).

The flat index is computed using self.order().

Panics

Panics if indices are out of bounds.

pub fn data_mut(&mut self) -> &mut [T]

Mutable reference to the underlying contiguous data buffer (triggers CoW on the storage half if shared).

pub fn iter(&self) -> Iter<'_, T>

Iterate over the flat storage in flat (storage) order.

pub fn fill(&mut self, value: T)

Fill every element with a constant value (triggers CoW if shared). Forwards to the storage half.

pub fn scale<S>(&mut self, factor: S)

where T: Mul<S, Output = T>, S: Clone,

Scale every element by a scalar factor in place (triggers CoW if shared).

pub fn map_mut<F>(&mut self, f: F)

where F: Fn(&T) -> T,

Apply a function to each element in place (triggers CoW if shared).

impl<T> TensorData<DenseStorage<T>, DenseLayout>

where T: Clone,

pub fn zeros_in_order(shape: Vec<usize>, order: MemoryOrder) -> Self

where T: Zero,

Zero-filled tensor in the requested memory order.

pub fn ones_in_order(shape: Vec<usize>, order: MemoryOrder) -> Self

where T: One + Zero,

Ones-filled tensor in the requested memory order.

pub fn filled_in_order(shape: Vec<usize>, value: T, order: MemoryOrder) -> Self

Tensor filled with value in the requested memory order.

pub fn eye_in_order(n: usize, order: MemoryOrder) -> Self

where T: Zero + One,

n × n identity matrix in the requested memory order.

The identity matrix is symmetric, so the flat buffer is the same under either memory order; only the layout’s order() differs.

pub fn random_in_order<R: Rng>( shape: Vec<usize>, order: MemoryOrder, rng: &mut R, ) -> Self

where StandardUniform: Distribution<T>,

Random-filled tensor (standard distribution) in the requested memory order. Random values are layout-invariant; only the layout’s order() tag matters for downstream interpretation.

impl<T> TensorData<DenseStorage<T>, DenseLayout>

where T: Clone,

pub fn concatenate(tensors: &[&DenseTensorData<T>], axis: usize) -> Self

Concatenate tensors along an existing axis.

All tensors must have the same rank, the same order(), and matching sizes on all axes except axis. The output preserves the shared order().

pub fn stack(tensors: &[&DenseTensorData<T>], axis: usize) -> Self

Stack tensors along a new axis.

All tensors must have the same shape and the same order(). The output preserves the shared order().

impl<T> TensorData<DenseStorage<T>, DenseLayout>

where T: Clone,

pub fn reshape(&self, new_shape: Vec<usize>) -> Self

Reshape the tensor to a new shape (zero-copy: shares the underlying storage Arc).

The flat data is not rearranged — only the layout’s shape changes. The output preserves self.order(). Reshape semantics depend on the order: adjacent-axis fusion is zero-copy under both row-major and column-major for contiguous tensors, but non-adjacent fusion produces a different logical mapping under each order.

Panics

Panics if the new shape has a different total number of elements.

pub fn map<U, F>(&self, f: F) -> DenseTensorData<U>

where F: Fn(&T) -> U, U: Clone + 'static,

Apply a function to each element.

Iterates flat data directly. The result preserves self.order().

pub fn map_with_index<U, F>(&self, f: F) -> DenseTensorData<U>

where F: Fn(&[usize], &T) -> U, U: Clone + 'static,

Apply a function with multi-dimensional coordinates to each element.

Iterates coordinates in self.order() while reading storage linearly, so the coordinate-to-value mapping always matches the storage’s layout. The output preserves self.order().

pub fn scaled<S>(&self, factor: S) -> Self

where T: Mul<S, Output = T>, S: Clone,

Scale all elements and return a new tensor (out-of-place).

impl<T> TensorData<DenseStorage<T>, DenseLayout>

where T: Clone,

pub fn add_all( tensors: &[&DenseTensorData<T>], ) -> Result<DenseTensorData<T>, TensorError>

where T: Zero + One + Add<Output = T> + Mul<Output = T>,

Add all tensors (coefficients all = 1).

pub fn linear_combine( tensors: &[&DenseTensorData<T>], coefs: &[T], ) -> Result<DenseTensorData<T>, TensorError>

where T: Zero + Add<Output = T> + Mul<Output = T>,

Linear combination: Σ coefs[i] * tensors[i].

All input tensors must share the same order(); the result preserves that order.

Errors

Returns an error if tensors have different shapes, different orders, the list is empty, or tensors and coefficients have different lengths.

impl<T> TensorData<DenseStorage<T>, DenseLayout>

where T: Scalar,

pub fn conj(&self) -> Self

Element-wise complex conjugate.

pub fn to_complex(&self) -> DenseTensorData<T::Complex>

Convert each element to its complex representation.

pub fn real(&self) -> DenseTensorData<T::Real>

Extract the real part of each element.

pub fn imag(&self) -> DenseTensorData<T::Real>

Extract the imaginary part of each element.

pub fn norm_frobenius(&self) -> T::Real

Compute Frobenius norm: √(Σ |element|²).

pub fn norm(&self) -> T::Real

Compute Frobenius norm (alias for norm_frobenius).

pub fn normalize(&mut self) -> T::Real

Normalize to unit Frobenius norm (in-place).

Returns the norm before normalization. Panics if the tensor has zero norm.

pub fn normalized(&self) -> (Self, T::Real)

Normalize and return a new tensor (out-of-place).

Returns (normalized_tensor, original_norm). Panics if the tensor has zero norm.

impl<T> TensorData<DenseStorage<T>, DenseLayout>

where T: Clone,

pub fn slice(&self, ranges: &[(usize, usize)]) -> Self

Extract a sub-tensor by specifying a (start, end) range for each axis (exclusive end).

The flat-data interpretation follows self.order(), and the output preserves the same order.

Panics

Panics if ranges length doesn’t match rank, or any range is out of bounds.

pub fn expand(&self, padding: &[(usize, usize)]) -> Self

where T: Zero,

Expand tensor by adding zero-padding at the boundaries.

The flat-data interpretation follows self.order(), and the output preserves the same order.

pub fn replace_slice(&mut self, sub: &Self, begin: &[usize])

Write a sub-tensor into this tensor starting at the given position (triggers CoW on the storage half if shared).

The flat-data interpretation follows self.order().

Panics

Panics if sub.rank() or begin.len() does not match self.rank(), or any sub-tensor extent exceeds the destination’s bounds. Also panics if sub.order() differs from self.order() at rank ≥ 2.

impl<T> TensorData<DenseStorage<T>, DenseLayout>

pub fn from_raw_parts( data: Vec<T>, shape: Vec<usize>, order: MemoryOrder, ) -> Self

where T: Clone,

Construct from flat data, shape, and the memory order the data is laid out in.

Panics

Panics if data.len() does not equal shape.iter().product().

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

Reference to the flat data buffer.

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

Logical shape.

pub fn order(&self) -> MemoryOrder

Memory order the flat data is laid out in.

pub fn rank(&self) -> usize

Rank (number of dimensions).

pub fn len(&self) -> usize

Total number of logical elements (shape().iter().product()).

pub fn is_empty(&self) -> bool

Whether the tensor has zero logical elements.

impl<St, L> TensorData<St, L>

where St: Storage + StorageFor<L>, L: TensorLayout,

pub fn new(storage: St, layout: L) -> Self

Construct from a Storage half and a paired TensorLayout half. Asserts the storage-layout boundary: the storage’s flat length must match the layout’s expected storage extent.

pub fn storage(&self) -> &St

Reference to the storage half.

pub fn layout(&self) -> &L

Reference to the layout half.

pub fn into_parts(self) -> (St, L)

Consume and return both halves.

Trait Implementations

impl<St, L> Clone for TensorData<St, L>

where St: Storage + StorageFor<L> + Clone, L: TensorLayout + Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.