Struct TypedTensor

pub struct TypedTensor<T, R = DynRank>where
    R: TensorRank,
{ /* private fields */ }

Expand description

Runtime typed tensor storage with compile-time scalar type and rank metadata.

Owned tensors are compact column-major. Arbitrary strides and metadata-only layout changes are represented by TypedTensorView and [TypedTensorViewMut]. The buffer may be host-backed or backend-backed; host-inspection methods do not download backend buffers implicitly.

§Examples

use tenferro_tensor::{Rank, Tensor, TypedTensor};

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0]).unwrap();
assert_eq!(t.shape(), &[2, 2]);

let static_rank = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1.0; 4]).unwrap();
assert_eq!(static_rank.rank(), 2);

let dynamic = Tensor::from_vec_col_major(vec![2, 2], vec![1.0_f64; 4]).unwrap();
assert_eq!(dynamic.shape(), &[2, 2]);

The R parameter stores rank metadata. It defaults to dynamic rank (DynRank); use Rank<N> for compile-time rank validation. The dtype-erased Tensor enum remains dynamic-rank.

Implementations§

§

impl<T, R> TypedTensor<T, R>
where T: Clone, R: TensorRank,

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

Iterate over the contiguous column-major host buffer.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
let sum: f64 = t.iter()?.copied().sum();
assert_eq!(sum, 3.0);

pub fn iter_mut(&mut self) -> Result<IterMut<'_, T>, Error>

Mutably iterate over the contiguous column-major host buffer.

§Examples

use tenferro_tensor::TypedTensor;

let mut t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
for value in t.iter_mut()? {
    *value *= 2.0;
}
assert_eq!(t.as_slice()?, &[2.0, 4.0]);

pub fn linear_offset2(&self, i: usize, j: usize) -> Result<usize, Error>

Compute the linear physical-buffer offset for a rank-2 logical index.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
assert_eq!(t.linear_offset2(1, 2)?, 5);

pub fn linear_offset3( &self, i: usize, j: usize, k: usize, ) -> Result<usize, Error>

Compute the linear physical-buffer offset for a rank-3 logical index.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3, 2], vec![0.0; 12]).unwrap();
assert_eq!(t.linear_offset3(1, 2, 1)?, 11);

pub fn get2(&self, i: usize, j: usize) -> Result<&T, Error>

Borrow a single element by rank-2 logical index.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0]).unwrap();
assert_eq!(t.get2(1, 0)?, &2.0);

pub fn get3(&self, i: usize, j: usize, k: usize) -> Result<&T, Error>

Borrow a single element by rank-3 logical index.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![1, 1, 2], vec![3.0, 4.0]).unwrap();
assert_eq!(t.get3(0, 0, 1)?, &4.0);

pub unsafe fn get_unchecked(&self, indices: &[usize]) -> Result<&T, Error>

Borrow a single element by multi-index without release-mode bounds checks.

Debug builds still validate the rank and bounds.

§Safety

indices must have the same rank as this tensor and every index must be in bounds.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
assert_eq!(unsafe { *t.get_unchecked(&[1])? }, 2.0);

pub fn get_mut2(&mut self, i: usize, j: usize) -> Result<&mut T, Error>

Mutably borrow a single element by rank-2 logical index.

§Examples

use tenferro_tensor::TypedTensor;

let mut t = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0]).unwrap();
*t.get_mut2(1, 0)? = 5.0;
assert_eq!(t.as_slice()?, &[1.0, 5.0, 3.0, 4.0]);

pub fn get_mut3( &mut self, i: usize, j: usize, k: usize, ) -> Result<&mut T, Error>

Mutably borrow a single element by rank-3 logical index.

§Examples

use tenferro_tensor::TypedTensor;

let mut t = TypedTensor::<f64>::from_vec_col_major(vec![1, 1, 2], vec![3.0, 4.0]).unwrap();
*t.get_mut3(0, 0, 1)? = 5.0;
assert_eq!(t.as_slice()?, &[3.0, 5.0]);

pub unsafe fn get_unchecked_mut( &mut self, indices: &[usize], ) -> Result<&mut T, Error>

Mutably borrow a single element by multi-index without release-mode bounds checks.

Debug builds still validate the rank and bounds.

§Safety

indices must have the same rank as this tensor and every index must be in bounds.

§Examples

use tenferro_tensor::TypedTensor;

let mut t = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0]).unwrap();
unsafe {
    *t.get_unchecked_mut(&[0])? = 2.0;
}
assert_eq!(t.as_slice()?, &[2.0]);

§

impl<T, R> TypedTensor<T, R>
where T: Clone + Zero, R: TensorRank,

pub fn zeros( shape: impl Into<<R as TensorRank>::Shape>, ) -> Result<TypedTensor<T, R>, Error>

Allocate a zero-filled tensor.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::zeros(vec![2, 3]).unwrap();
assert_eq!(t.n_elements(), 6);

§

impl<T, R> TypedTensor<T, R>
where T: Clone + One + Zero, R: TensorRank,

pub fn ones( shape: impl Into<<R as TensorRank>::Shape>, ) -> Result<TypedTensor<T, R>, Error>

Allocate a one-filled tensor.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::ones(vec![2]).unwrap();
assert_eq!(t.host_data().unwrap(), &[1.0, 1.0]);

§

impl<T, R> TypedTensor<T, R>
where R: TensorRank,

pub fn from_buffer_col_major( shape: impl Into<<R as TensorRank>::Shape>, buffer: Buffer<T>, placement: Placement, ) -> Result<TypedTensor<T, R>, Error>
where T: 'static,

Create a tensor from an existing buffer and compact column-major layout.

This preserves the owned tensor invariant that layout metadata is compact column-major, including for backend-owned buffers.

§Examples

use tenferro_tensor::{Buffer, Placement, TypedTensor};

let tensor = TypedTensor::<f64>::from_buffer_col_major(
    vec![2],
    Buffer::Host(vec![1.0, 2.0]),
    Placement {
        memory_kind: tenferro_tensor::MemoryKind::UnpinnedHost,
        device: None,
    },
)
.unwrap();
assert_eq!(tensor.shape(), &[2]);

pub fn try_into_rank<const N: usize>( self, ) -> Result<TypedTensor<T, Rank<N>>, Error>

Convert this tensor into static rank metadata after validating its rank.

The buffer and placement are preserved. This method changes only the compile-time rank marker on the owned compact column-major tensor.

§Examples

use tenferro_tensor::{Rank, TypedTensor};

let tensor = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![1.0; 6]).unwrap();
let ranked: TypedTensor<f64, Rank<2>> = tensor.try_into_rank::<2>()?;
assert_eq!(ranked.shape(), &[2, 3]);

pub fn n_elements(&self) -> usize

Number of elements in the tensor.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
assert_eq!(t.n_elements(), 6);

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

Tensor shape.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
assert_eq!(t.shape(), &[2]);

pub fn rank(&self) -> usize

Tensor rank.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
assert_eq!(t.rank(), 2);

pub fn layout(&self) -> &TensorLayout<R>

Tensor layout metadata.

Owned typed tensors are always compact column-major layouts.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
assert_eq!(t.layout().strides(), &[1, 2]);

pub fn buffer(&self) -> &Buffer<T>

Return the storage backing this tensor.

This is an explicit storage-inspection API for backend glue and tests. Host value inspection should prefer TypedTensor::host_data when the caller requires host storage.

§Examples

use tenferro_tensor::{Buffer, TypedTensor};

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
assert!(matches!(t.buffer(), Buffer::Host(_)));

pub fn placement(&self) -> &Placement

Return placement metadata for this tensor.

§Examples

use tenferro_tensor::{MemoryKind, TypedTensor};

let t = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0]).unwrap();
assert_eq!(t.placement().memory_kind, MemoryKind::UnpinnedHost);

pub fn set_placement(&mut self, placement: Placement)

Replace placement metadata without changing the storage buffer.

§Examples

use tenferro_tensor::{MemoryKind, Placement, TypedTensor};

let mut t = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0]).unwrap();
t.set_placement(Placement {
    memory_kind: MemoryKind::PinnedHost,
    device: None,
});
assert_eq!(t.placement().memory_kind, MemoryKind::PinnedHost);

pub fn as_view(&self) -> TypedTensorView<'_, T, R>
where T: 'static,

Borrow this tensor as a typed view preserving rank and layout metadata.

§Examples

use tenferro_tensor::{Rank, TypedTensor};

let tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1.0; 4]).unwrap();
let view = tensor.as_view();
assert_eq!(view.strides(), &[1, 2]);

pub fn as_view_mut(&mut self) -> TypedTensorViewMut<'_, T, R>
where T: 'static,

Mutably borrow this tensor as a typed view preserving rank and layout metadata.

§Examples

use tenferro_tensor::TypedTensor;

let mut tensor = TypedTensor::<i32>::from_vec_col_major(vec![1], vec![1]).unwrap();
*tensor.as_view_mut().get_mut(&[0]).unwrap() = 2;
assert_eq!(tensor.as_slice().unwrap(), &[2]);

pub fn backend_region_view( &self, shape: Vec<usize>, strides: Vec<isize>, offset: isize, ) -> Result<TypedTensorView<'_, T>, Error>
where T: 'static,

Borrow a read-only strided region view over this tensor’s backend (device) buffer from explicit layout metadata.

This is a metadata-only view: no data is copied or transferred. The layout’s reachable element span is validated against the backend buffer’s physical length. Host-backed tensors are rejected with an explicit backend error; host regions are expressed with TypedTensorView::from_slice over host storage instead.

§Examples

use tenferro_tensor::TypedTensor;

// Host tensors are rejected: this constructor is for backend buffers.
let host = TypedTensor::<f64>::from_vec_col_major(vec![4], vec![0.0; 4]).unwrap();
let err = host.backend_region_view(vec![2, 2], vec![1, 2], 0).unwrap_err();
assert!(err.to_string().contains("backend"));

pub fn backend_region_view_mut( &mut self, shape: Vec<usize>, strides: Vec<isize>, offset: isize, ) -> Result<TypedTensorViewMut<'_, T>, Error>
where T: 'static,

Borrow a mutable strided region view over this tensor’s backend (device) buffer from explicit layout metadata.

This is the mutable counterpart of TypedTensor::backend_region_view. The layout’s reachable element span is validated against the backend buffer’s physical length, and layouts whose logical elements alias the same physical element are rejected. Host-backed tensors are rejected with an explicit backend error; mutable host regions must go through [TypedTensorViewMut::try_multi_slice_mut] or host constructors.

Backend buffers are shared handles, so distinct region views over one buffer can coexist; disjointness between regions used concurrently by backend operations is the caller’s contract (as with BLAS-style in-place update APIs).

§Examples

use tenferro_tensor::TypedTensor;

// Host tensors are rejected: this constructor is for backend buffers.
let mut host = TypedTensor::<f64>::from_vec_col_major(vec![4], vec![0.0; 4]).unwrap();
let err = host.backend_region_view_mut(vec![2, 2], vec![1, 2], 0).unwrap_err();
assert!(err.to_string().contains("backend"));

pub fn into_layout(self) -> TensorLayout<R>

Consume this tensor and return its layout metadata.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
assert!(t.into_layout().is_compact_col_major().unwrap());

pub fn into_parts(self) -> (Buffer<T>, TensorLayout<R>, Placement)

Consume this tensor and return its storage, layout, and placement.

§Examples

use tenferro_tensor::{Buffer, TypedTensor};

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
let (buffer, layout, placement) = t.into_parts();
assert!(matches!(buffer, Buffer::Host(_)));
assert_eq!(layout.shape(), &[2]);
assert!(placement.device.is_none());

§

impl<T, R> TypedTensor<T, R>
where T: Clone, R: TensorRank,

pub fn from_vec_col_major( shape: impl Into<<R as TensorRank>::Shape>, data: Vec<T>, ) -> Result<TypedTensor<T, R>, Error>

Create a tensor from a column-major buffer.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0]).unwrap();
assert_eq!(t.get(&[1, 0])?, &2.0);

pub fn into_vec_col_major(self) -> Result<(Vec<usize>, Vec<T>), Error>

Consume this tensor and return its owned column-major host buffer.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
let (shape, data) = t.into_vec_col_major().unwrap();
assert_eq!(shape, vec![2]);
assert_eq!(data, vec![1.0, 2.0]);

pub fn host_data(&self) -> Result<&[T], Error>

Borrow the host buffer.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
assert_eq!(t.host_data()?, &[1.0, 2.0]);

pub fn as_slice(&self) -> Result<&[T], Error>

View the tensor data as a flat slice.

This is an alias for host_data() for API consistency with Tensor::as_slice.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
assert_eq!(t.as_slice()?, &[1.0, 2.0]);

pub fn host_data_mut(&mut self) -> Result<&mut [T], Error>

Mutably borrow the host buffer.

§Examples

use tenferro_tensor::TypedTensor;

let mut t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
t.host_data_mut()?[0] = 3.0;
assert_eq!(t.host_data()?, &[3.0, 0.0]);

pub fn linear_offset(&self, indices: &[usize]) -> Result<usize, Error>

Compute the linear physical-buffer offset for a logical index.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::zeros(vec![2, 3]).unwrap();
assert_eq!(t.linear_offset(&[1, 2])?, 5);

pub fn layout_linear_offset(&self, indices: &[usize]) -> Result<usize, Error>

Compute the physical element offset for a logical index.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::zeros(vec![2, 3]).unwrap();
assert_eq!(t.layout_linear_offset(&[1, 2])?, 5);

pub fn is_col_major_contiguous(&self) -> Result<bool, Error>

Return whether this owned tensor is compact column-major.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
assert!(t.is_col_major_contiguous()?);

pub fn layout_summary(&self) -> String

Return a compact string summary of this tensor’s layout metadata.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
assert!(t.layout_summary().contains("shape=[2]"));

pub fn assert_col_major_contiguous(&self) -> Result<(), Error>

Assert this tensor is compact column-major.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::zeros(vec![2]).unwrap();
t.assert_col_major_contiguous()?;

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

Borrow a single element by multi-index.

§Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0]).unwrap();
assert_eq!(t.get(&[1])?, &2.0);

pub fn get_mut(&mut self, indices: &[usize]) -> Result<&mut T, Error>

Mutably borrow a single element by multi-index.

§Examples

use tenferro_tensor::TypedTensor;

let mut t = TypedTensor::<f64>::zeros(vec![1]).unwrap();
*t.get_mut(&[0])? = 7.0;
assert_eq!(t.host_data()?, &[7.0]);

Trait Implementations§

§

impl<T, R> Clone for TypedTensor<T, R>
where T: Clone, R: Clone + TensorRank,

§

fn clone(&self) -> TypedTensor<T, R>

Returns a duplicate of the value. Read more

1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more

§

impl<T, R> Debug for TypedTensor<T, R>
where T: Debug, R: Debug + TensorRank,

§

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

Formats the value using the given formatter. Read more

§

impl From<TypedTensor<Complex<f32>>> for Tensor

Wrap a Complex32 TypedTensor into the corresponding Tensor variant.

§Examples

use num_complex::Complex32;
use tenferro_tensor::{Tensor, TypedTensor};

let typed = TypedTensor::from_vec_col_major(
    vec![1],
    vec![Complex32::new(1.0, 2.0)],
).unwrap();
let tensor: Tensor = typed.into();
assert_eq!(tensor.shape(), &[1]);

§

fn from(t: TypedTensor<Complex<f32>>) -> Tensor

Converts to this type from the input type.

§

impl From<TypedTensor<Complex<f64>>> for Tensor

Wrap a Complex64 TypedTensor into the corresponding Tensor variant.

§Examples

use num_complex::Complex64;
use tenferro_tensor::{Tensor, TypedTensor};

let typed = TypedTensor::from_vec_col_major(
    vec![1],
    vec![Complex64::new(1.0, 2.0)],
).unwrap();
let tensor: Tensor = typed.into();
assert_eq!(tensor.shape(), &[1]);

§

fn from(t: TypedTensor<Complex<f64>>) -> Tensor

Converts to this type from the input type.

§

impl From<TypedTensor<bool>> for Tensor

Wrap a bool TypedTensor into the corresponding Tensor variant.

§Examples

use tenferro_tensor::{DType, Tensor, TypedTensor};

let typed = TypedTensor::from_vec_col_major(vec![2], vec![true, false]).unwrap();
let tensor: Tensor = typed.into();
assert_eq!(tensor.dtype(), DType::Bool);
assert_eq!(tensor.shape(), &[2]);

§

fn from(t: TypedTensor<bool>) -> Tensor

Converts to this type from the input type.

§

impl From<TypedTensor<f32>> for Tensor

Wrap an f32 TypedTensor into the corresponding Tensor variant.

§Examples

use tenferro_tensor::{Tensor, TypedTensor};

let typed = TypedTensor::from_vec_col_major(vec![2], vec![1.0_f32, 2.0]).unwrap();
let tensor: Tensor = typed.into();
assert_eq!(tensor.shape(), &[2]);

§

fn from(t: TypedTensor<f32>) -> Tensor

Converts to this type from the input type.

§

impl From<TypedTensor<f64>> for Tensor

Wrap an f64 TypedTensor into the corresponding Tensor variant.

§Examples

use tenferro_tensor::{Tensor, TypedTensor};

let typed = TypedTensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
let tensor: Tensor = typed.into();
assert_eq!(tensor.shape(), &[2]);

§

fn from(t: TypedTensor<f64>) -> Tensor

Converts to this type from the input type.

§

impl From<TypedTensor<i32>> for Tensor

Wrap an i32 TypedTensor into the corresponding Tensor variant.

§Examples

use tenferro_tensor::{DType, Tensor, TypedTensor};

let typed = TypedTensor::from_vec_col_major(vec![2], vec![1_i32, 2]).unwrap();
let tensor: Tensor = typed.into();
assert_eq!(tensor.dtype(), DType::I32);
assert_eq!(tensor.shape(), &[2]);

§

fn from(t: TypedTensor<i32>) -> Tensor

Converts to this type from the input type.

§

impl From<TypedTensor<i64>> for Tensor

Wrap an i64 TypedTensor into the corresponding Tensor variant.

§Examples

use tenferro_tensor::{DType, Tensor, TypedTensor};

let typed = TypedTensor::from_vec_col_major(vec![2], vec![1_i64, 2]).unwrap();
let tensor: Tensor = typed.into();
assert_eq!(tensor.dtype(), DType::I64);
assert_eq!(tensor.shape(), &[2]);