Struct StructuredTensor

Source

pub struct StructuredTensor<T: Scalar> { /* private fields */ }

Expand description

Structured tensor payload with logical axis metadata.

This stores logical tensor metadata separately from the compressed payload. Dense and diagonal tensors are representation cases of the same type.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
assert_eq!(x.logical_dims(), &[2, 2]);
assert!(x.is_diag());

Implementations§

Source §

impl<T: Scalar> StructuredTensor<T>

Source

pub fn to_dense(&self) -> Result<Tensor<T>>

Materialize this structured tensor into a dense tensor.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
let dense = x.to_dense().unwrap();
assert_eq!(dense.dims(), &[2, 2]);
assert_eq!(dense.get(&[0, 0]), Some(&1.0));
assert_eq!(dense.get(&[0, 1]), Some(&0.0));

Source

pub fn into_dense(self) -> Result<Tensor<T>>

Consume this structured tensor and return a dense tensor.

Returns the payload directly when the layout is already dense.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
let dense = x.into_dense().unwrap();
assert_eq!(dense.dims(), &[2, 2]);

Source §

impl<T: Scalar> StructuredTensor<T>

Source

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

Returns the same logical tensor with permuted logical axes.

This permutes both the logical axes and the compressed payload class order, then rebuilds the canonical axis-class representation.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let dense = Tensor::<f64>::from_slice(
    &[1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
    &[2, 3],
    MemoryOrder::ColumnMajor,
)
.unwrap();
let x = StructuredTensor::from_dense(dense);
let y = x.permute_logical(&[1, 0]).unwrap();
assert_eq!(y.logical_dims(), &[3, 2]);

Source

pub fn conj(&self) -> Self
where T: Conjugate,

Returns the same structured tensor with payload conjugation toggled.

§Examples

use num_complex::Complex64;
use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload = Tensor::<Complex64>::from_slice(
    &[Complex64::new(1.0, 2.0), Complex64::new(3.0, 4.0)],
    &[2],
    MemoryOrder::ColumnMajor,
)
.unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
let y = x.conj();
assert_eq!(y.logical_dims(), x.logical_dims());

Source §

impl<T: Scalar> StructuredTensor<T>

Source

pub fn new( logical_dims: Vec<usize>, axis_classes: Vec<usize>, payload: Tensor<T>, ) -> Result<Self>

Construct a structured tensor from logical metadata and compressed payload.

Axis classes are canonicalized to first-appearance order.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::new(vec![2, 2], vec![9, 9], payload).unwrap();
assert_eq!(x.axis_classes(), &[0, 0]);

Source

pub fn from_dense(payload: Tensor<T>) -> Self

Construct a dense structured tensor.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let dense = Tensor::<f64>::from_slice(
    &[1.0, 2.0, 3.0, 4.0],
    &[2, 2],
    MemoryOrder::ColumnMajor,
)
.unwrap();
let x = StructuredTensor::from_dense(dense);
assert!(x.is_dense());

Source

pub fn from_diagonal_vector( payload: Tensor<T>, logical_rank: usize, ) -> Result<Self>

Construct a diagonal structured tensor from a rank-1 payload.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
assert!(x.is_diag());

Source

pub fn payload(&self) -> &Tensor<T>

Borrow the compressed payload tensor.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let dense =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_dense(dense);
assert_eq!(x.payload().dims(), &[2]);

Source

pub fn into_payload(self) -> Tensor<T>

Consume the structured tensor and return the compressed payload tensor.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let dense =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_dense(dense);
let payload = x.into_payload();
assert_eq!(payload.dims(), &[2]);

Source

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

Returns logical dimensions.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
assert_eq!(x.logical_dims(), &[2, 2]);

Source

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

Returns axis classes for logical axes.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
assert_eq!(x.axis_classes(), &[0, 0]);

Source

pub fn class_count(&self) -> usize

Returns the number of distinct axis classes.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 3).unwrap();
assert_eq!(x.class_count(), 1);

Source

pub fn is_dense(&self) -> bool

Returns true when the layout is dense.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let dense = Tensor::<f64>::from_slice(
    &[1.0, 2.0, 3.0, 4.0],
    &[2, 2],
    MemoryOrder::ColumnMajor,
)
.unwrap();
let x = StructuredTensor::from_dense(dense);
assert!(x.is_dense());

Source

pub fn is_diag(&self) -> bool

Returns true when the layout is a pure diagonal.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
assert!(x.is_diag());

Source

pub fn with_payload_like(&self, payload: Tensor<T>) -> Result<Self>

Rebuild the same structured layout with a different payload tensor.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let layout = StructuredTensor::from_diagonal_vector(payload, 2).unwrap();
let replacement =
    Tensor::<f64>::from_slice(&[3.0, 4.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let updated = layout.with_payload_like(replacement).unwrap();
assert!(updated.is_diag());

Source

pub fn from_validated_parts( logical_dims: Vec<usize>, axis_classes: Vec<usize>, payload: Tensor<T>, ) -> Self

Construct a structured tensor without re-validating the metadata.

§Safety

Callers must ensure that logical_dims, axis_classes, and payload already satisfy the invariants enforced by StructuredTensor::new.

§Examples

use tenferro_tensor::{MemoryOrder, StructuredTensor, Tensor};

let payload =
    Tensor::<f64>::from_slice(&[1.0, 2.0], &[2], MemoryOrder::ColumnMajor).unwrap();
let x = StructuredTensor::from_validated_parts(vec![2, 2], vec![0, 0], payload);
assert!(x.is_diag());