Struct TypedTensor 

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

Owned compact column-major typed tensor.

T is the element type, R the rank metadata (default DynRank) and D the owned representation (default Dynamic). Shape and placement live on the tensor itself, once, never inside a storage arm.

No bound is imposed on T by the type: plain host adoption only needs the constructor’s own requirements, and T: Clone is required only by the copying constructors. A preset TensorScalar appears only where a dtype identity or a numerical capability is actually used, never for plain host ownership.

Owned tensors are compact column-major. Arbitrary strides and metadata-only layout changes are represented by TypedTensorView and TypedTensorViewMut.

Examples

use tenferro_tensor::{DynRank, Host, 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 host: TypedTensor<i32, DynRank, Host> =
    TypedTensor::from_host_vec_col_major(vec![2], vec![1, 2]).unwrap();
assert_eq!(host.get(&[1])?, &2);

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

Implementations

impl<T, R> TypedTensor<T, R>

where T: TensorScalar, 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);

Errors

Returns crate::Error::RuntimeState when the tensor is backed by a device buffer and has not been downloaded to host memory.

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]);

Errors

Returns crate::Error::RuntimeState when the tensor is backed by a device buffer and has not been downloaded to host memory.

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);

Errors

Returns crate::Error::Validation containing tenferro_tensor_core::ValidationError::RankMismatch when the tensor rank is not two, tenferro_tensor_core::ValidationError::InvalidArgument when i or j is outside its axis extent, or tenferro_tensor_core::ValidationError::IntegerOverflow when checked offset arithmetic overflows.

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);

Errors

Returns crate::Error::Validation containing tenferro_tensor_core::ValidationError::RankMismatch when the tensor rank is not three, tenferro_tensor_core::ValidationError::InvalidArgument when i, j, or k is outside its axis extent, or tenferro_tensor_core::ValidationError::IntegerOverflow when checked offset arithmetic overflows.

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);

Errors

Returns crate::Error::Validation containing tenferro_tensor_core::ValidationError::RankMismatch when the tensor rank is not two, tenferro_tensor_core::ValidationError::InvalidArgument when i or j is outside its axis extent, or tenferro_tensor_core::ValidationError::IntegerOverflow when checked offset arithmetic overflows. It returns crate::Error::RuntimeState when the tensor is backed by a device buffer, or tenferro_tensor_core::ValidationError::InvalidArgument if the computed offset is outside the host buffer.

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);

Errors

Returns crate::Error::Validation containing tenferro_tensor_core::ValidationError::RankMismatch when the tensor rank is not three, tenferro_tensor_core::ValidationError::InvalidArgument when i, j, or k is outside its axis extent, or tenferro_tensor_core::ValidationError::IntegerOverflow when checked offset arithmetic overflows. It returns crate::Error::RuntimeState when the tensor is backed by a device buffer, or tenferro_tensor_core::ValidationError::InvalidArgument if the computed offset is outside the host buffer.

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);

Errors

Returns crate::Error::RuntimeState when the tensor is backed by a device buffer and has not been downloaded to host memory.

Panics

May panic if the unsafe rank/bounds precondition is violated and the checked linear-offset calculation overflows.

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]);

Errors

Returns crate::Error::Validation containing tenferro_tensor_core::ValidationError::RankMismatch when the tensor rank is not two, tenferro_tensor_core::ValidationError::InvalidArgument when i or j is outside its axis extent, or tenferro_tensor_core::ValidationError::IntegerOverflow when checked offset arithmetic overflows. It returns crate::Error::RuntimeState when the tensor is backed by a device buffer, or tenferro_tensor_core::ValidationError::InvalidArgument if the computed offset is outside the host buffer.

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]);

Errors

Returns crate::Error::Validation containing tenferro_tensor_core::ValidationError::RankMismatch when the tensor rank is not three, tenferro_tensor_core::ValidationError::InvalidArgument when i, j, or k is outside its axis extent, or tenferro_tensor_core::ValidationError::IntegerOverflow when checked offset arithmetic overflows. It returns crate::Error::RuntimeState when the tensor is backed by a device buffer, or tenferro_tensor_core::ValidationError::InvalidArgument if the computed offset is outside the host buffer.

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]);

Errors

Returns crate::Error::RuntimeState when the tensor is backed by a device buffer and has not been downloaded to host memory.

Panics

May panic if the unsafe rank/bounds precondition is violated and the checked linear-offset calculation overflows.

impl<T, const N: usize> TypedTensor<T, Rank<N>>

pub fn host_col_major_view(&self) -> Result<ColMajorView<'_, T, N>, Error>

Validate and borrow this owned tensor as a compact column-major host view.

Examples

use tenferro_tensor::{Rank, TypedTensor};
let tensor = TypedTensor::<i32, Rank<2>>::from_vec_col_major([2, 1], vec![1, 2])?;
assert_eq!(tensor.host_col_major_view()?.get([1, 0]), Some(&2));

Errors

Returns crate::Error::RuntimeState when storage is backend-owned, or crate::Error::Validation when compact layout, shape arithmetic, or the logical host range is invalid.

pub fn host_col_major_view_mut( &mut self, ) -> Result<ColMajorViewMut<'_, T, N>, Error>

Validate and mutably borrow this owned tensor as a compact column-major host view.

Examples

use tenferro_tensor::{Rank, TypedTensor};
let mut tensor = TypedTensor::<i32, Rank<1>>::from_vec_col_major([1], vec![1])?;
if let Some(value) = tensor.host_col_major_view_mut()?.get_mut([0]) { *value = 3; }
assert_eq!(tensor.as_slice()?, &[3]);

Errors

Returns crate::Error::RuntimeState when storage is backend-owned, or crate::Error::Validation when compact layout, shape arithmetic, or the logical host range is invalid.

impl<T, const N: usize> TypedTensor<T, Rank<N>, Host>

pub fn host_col_major_view(&self) -> Result<ColMajorView<'_, T, N>, Error>

Validate and borrow this host-marked tensor as a compact column-major host view. The Host marker is kept: no erasure to Dynamic is needed.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
let tensor =
    TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 1], vec![1, 2])?;
assert_eq!(tensor.host_col_major_view()?.get([1, 0]), Some(&2));

Errors

Returns crate::Error::Validation when compact layout, shape arithmetic, or the logical host range is invalid.

pub fn host_col_major_view_mut( &mut self, ) -> Result<ColMajorViewMut<'_, T, N>, Error>

Validate and mutably borrow this host-marked tensor as a compact column-major host view.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
let mut tensor = TypedTensor::<i32, Rank<1>, Host>::from_host_vec_col_major([1], vec![1])?;
if let Some(value) = tensor.host_col_major_view_mut()?.get_mut([0]) { *value = 3; }
assert_eq!(tensor.as_slice(), &[3]);

Errors

Returns crate::Error::Validation when compact layout, shape arithmetic, or the logical host range is invalid.

impl<T, R> TypedTensor<T, R, Host>

where R: TensorRank,

pub fn from_host_vec_col_major( shape: impl IntoRankShape<R>, data: Vec<T>, ) -> Result<TypedTensor<T, R, Host>, Error>

Adopt a column-major host Vec<T> as a statically host-owned tensor.

The payload is the caller’s vector itself; T needs no Copy, TensorScalar or arithmetic bound, and no group, session or device is involved.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
struct Custom(String);
let tensor = TypedTensor::<Custom, Rank<2>, Host>::from_host_vec_col_major(
    [1, 2], vec![Custom("a".into()), Custom("b".into())],
)?;
assert_eq!(tensor[&[0, 1]].0.as_str(), "b");

Errors

Returns crate::Error::Validation for a rank mismatch, shape/data length mismatch or shape/stride arithmetic overflow.

pub fn from_host_vec_row_major( shape: impl IntoRankShape<R>, data: Vec<T>, ) -> Result<TypedTensor<T, R, Host>, Error>

where T: Clone,

Explicitly import row-major host values into column-major storage.

Clones each input element once.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
let tensor = TypedTensor::<i32, Rank<2>, Host>::from_host_vec_row_major(
    [2, 3], vec![1, 2, 3, 4, 5, 6],
)?;
assert_eq!(tensor[&[1, 0]], 4);
assert_eq!(tensor[&[0, 2]], 3);

Errors

Returns crate::Error::Validation for a rank, shape-length or stride overflow, or when the shape product disagrees with the input length.

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

Borrow the owned host elements.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
assert_eq!(tensor.as_slice(), &[1, 2]);

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

Alias of Self::as_slice.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
assert_eq!(tensor.host_data(), &[1, 2]);

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

Exclusively borrow the owned host elements.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
tensor.host_data_mut()[0] = 5;
assert_eq!(tensor.as_slice(), &[5, 2]);

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

Borrow one element by checked column-major multi-index.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2, 2], vec![1, 2, 3, 4])?;
assert_eq!(tensor.get(&[1, 1])?, &4);
assert!(tensor.get(&[2, 0]).is_err());

Errors

Returns crate::Error::Validation for a wrong rank, an out-of-range coordinate or offset arithmetic overflow.

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

Exclusively borrow one element by checked column-major multi-index.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
*tensor.get_mut(&[1])? = 9;
assert_eq!(tensor.as_slice(), &[1, 9]);

Errors

Returns crate::Error::Validation for a wrong rank, an out-of-range coordinate or offset arithmetic overflow.

pub fn into_host_vec(self) -> Vec<T>

Consume this tensor and return the original host vector.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
assert_eq!(tensor.into_host_vec(), vec![1, 2]);

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

Consume this tensor and return its shape and column-major host vector.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2, 1], vec![1, 2])?;
let (shape, data) = tensor.into_vec_col_major();
assert_eq!(shape, vec![2, 1]);
assert_eq!(data, vec![1, 2]);

pub fn duplicate(&self) -> TypedTensor<T, R, Host>

where T: Clone,

Make an explicit independent host copy with the same placement.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<String, DynRank, Host>::from_host_vec_col_major(vec![1], vec!["a".into()])?;
let copy = tensor.clone();
assert_eq!(copy[&[0]], "a");

pub fn into_dynamic(self) -> TypedTensor<T, R>

Move this host owner into the runtime union without copying or regrouping.

Examples

use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
let host = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7])?;
let dynamic: TypedTensor<i32, DynRank, Dynamic> = host.into_dynamic();
assert_eq!(dynamic.host_data()?, &[7]);

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

Borrow this host owner as a typed view.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
let view = tensor.as_view();
assert_eq!(view.shape(), &[2]);
assert_eq!(view.as_host_slice(), &[1, 2]);

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

Exclusively borrow this host owner as a mutable typed view.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
tensor.as_view_mut().as_host_slice_mut()[1] = 4;
assert_eq!(tensor.as_slice(), &[1, 4]);

impl<T, R> TypedTensor<T, R, Host>

where R: TensorRank,

pub fn map_read(&self) -> HostReadGuard<'_, T>

Borrow the owned host elements through one owning read mapping.

The guard retains the exclusive borrow of this owner, so no other access can overlap it while the mapping is alive.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
let guard = tensor.map_read();
assert_eq!(&guard[..], &[1, 2]);

pub fn map_write(&mut self) -> HostWriteGuard<'_, T>

where T: Clone,

Exclusively borrow the owned host elements through one owning write mapping.

Publish data with HostWriteGuard::copy_from_slice; the mapping is released when the guard is dropped.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let mut tensor = TypedTensor::<i32, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1, 2])?;
tensor.map_write().copy_from_slice(&[3, 4]).unwrap();
assert_eq!(tensor.as_slice(), &[3, 4]);

impl<T, R> TypedTensor<T, R, Host>

where T: TensorScalar, R: TensorRank,

pub fn promote(self) -> Result<TypedTensor<T, R, Gpu>, Error>

Promote this plain host owner into a group-backed owner.

The payload is adopted as a provider root: no element is copied and a pooled return target survives the promotion.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?;
let gpu = host.promote()?;
assert_eq!(gpu.host_data()?, &[1.0, 2.0]);

Errors

Returns crate::Error::RuntimeState when the new allocation group rejects the promoted root or its recycler.

impl<T, R> TypedTensor<T, R>

where R: TensorRank,

pub fn map_read(&self) -> Result<HostReadGuard<'_, T>, Error>

Borrow host elements through one owning read mapping.

Examples

use tenferro_tensor::TypedTensor;
let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
let guard = tensor.map_read()?;
assert_eq!(&guard[..], &[1, 2]);

Errors

Returns crate::Error::HostAccess with HostAccessError::Unsupported when the group’s allocation is not host-accessible, or crate::Error::Validation with ValidationError::NonContiguousViewAsSlice or ValidationError::ViewOutOfBounds when the owner has no contiguous logical extent inside its backing storage.

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

where T: Clone,

Exclusively borrow host elements through one owning write mapping.

Publish data with HostWriteGuard::copy_from_slice.

Examples

use tenferro_tensor::{Error, TypedTensor};
let mut tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
tensor
    .map_write()?
    .copy_from_slice(&[3, 4])
    .map_err(|err| Error::host_access("map_write", err))?;
assert_eq!(tensor.host_data()?, &[3, 4]);

Errors

Returns crate::Error::HostAccess with HostAccessError::Unsupported when the group’s allocation is not host-writable, or crate::Error::Validation with ValidationError::NonContiguousViewAsSlice or ValidationError::ViewOutOfBounds when the owner has no contiguous logical extent inside its backing storage.

impl<T, R> TypedTensor<T, R, Gpu>

where R: TensorRank,

pub fn from_backend_buffer_col_major( shape: impl IntoRankShape<R>, buffer: StorageBuffer<T>, placement: Placement, ) -> Result<TypedTensor<T, R, Gpu>, Error>

where T: TensorScalar + Send + Sync + 'static,

Adopt a backend-owned buffer as a statically group-backed owner.

A host buffer belongs to the Host representation; pass it to TypedTensor::<T, R, Host> instead of silently regrouping it here.

Examples

use tenferro_tensor::{BackendStorageHandle, Placement, StorageBuffer, TypedTensor};
let handle = BackendStorageHandle::<f32>::new_with_len(1, 2);
let gpu = TypedTensor::<f32, tenferro_tensor::DynRank, tenferro_tensor::Gpu>::from_backend_buffer_col_major(
    vec![2],
    StorageBuffer::Backend(Box::new(handle)),
    Placement::default(),
)?;
assert!(gpu.is_backend_buffer());

Errors

Returns crate::Error::Validation when the compact shape disagrees with the buffer length, crate::Error::RuntimeState for a host buffer, or a runtime-state error when the allocation group cannot be built.

pub fn into_dynamic(self) -> TypedTensor<T, R>

Move this group-backed owner into the runtime union without rewriting it.

Examples

use tenferro_tensor::{Dynamic, DynRank, Host, TypedTensor};
let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7.0])?.promote()?;
let dynamic: TypedTensor<f64, DynRank, Dynamic> = gpu.into_dynamic();
assert_eq!(dynamic.host_data()?, &[7.0]);

pub fn is_backend_buffer(&self) -> bool

Whether this group’s descriptor names a non-CPU provider.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![7.0])?.promote()?;
// A promoted host payload stays on the CPU provider.
assert!(!gpu.is_backend_buffer());

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

Borrow host elements when the group’s allocation is host-accessible.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?.promote()?;
assert_eq!(gpu.host_data()?, &[1.0, 2.0]);

Errors

Returns crate::Error::RuntimeState for a device-only allocation and the non-compact-descriptor validation error for a strided owner.

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

Exclusively borrow host elements when the group’s allocation is host-accessible.

Examples

use tenferro_tensor::{DynRank, Host, TypedTensor};
let mut gpu = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![2], vec![1.0, 2.0])?.promote()?;
gpu.host_data_mut()?[0] = 3.0;
assert_eq!(gpu.host_data()?, &[3.0, 2.0]);

Errors

Returns crate::Error::RuntimeState for a device-only allocation and the non-compact-descriptor validation error for a strided owner.

impl<T, R> TypedTensor<T, R>

where R: TensorRank,

pub fn into_host( self, ) -> Result<TypedTensor<T, R, Host>, ReinterpretError<TypedTensor<T, R>>>

Checked narrowing to the statically host-owned representation.

Fails without consuming ownership of the source tensor.

Examples

use tenferro_tensor::TypedTensor;
let dynamic = TypedTensor::<i32>::from_vec_col_major(vec![1], vec![7])?;
let host = dynamic.into_host().unwrap();
assert_eq!(host.as_slice(), &[7]);

Errors

Returns ReinterpretError carrying the unchanged tensor when it is group-backed rather than plain host storage.

pub fn into_gpu( self, ) -> Result<TypedTensor<T, R, Gpu>, ReinterpretError<TypedTensor<T, R>>>

Checked narrowing to the group-backed representation.

Fails without consuming ownership of the source tensor.

Examples

use tenferro_tensor::{DynRank, Gpu, Host, TypedTensor};
let host = TypedTensor::<f64, DynRank, Host>::from_host_vec_col_major(vec![1], vec![2.0])?;
let dynamic = host.promote()?.into_dynamic();
let gpu: TypedTensor<f64, DynRank, Gpu> = dynamic.into_gpu().map_err(|f| f.into_parts().1)?;
assert_eq!(gpu.host_data()?, &[2.0]);
let plain = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![2.0])?;
assert!(plain.into_gpu().is_err());

Errors

Returns ReinterpretError carrying the unchanged tensor when it is a plain host owner rather than a group-backed one.

impl<T, R, D> TypedTensor<T, R, D>

where R: TensorRank, D: Representation,

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 strides(&self) -> &[isize]

Column-major element strides of this compact tensor.

The layout is cached at construction, so views of a tensor borrow it rather than computing (and allocating) it once per operation.

Examples

use tenferro_tensor::TypedTensor;

let t = TypedTensor::<f64>::from_vec_col_major(vec![2, 3], vec![0.0; 6]).unwrap();
assert_eq!(t.strides(), &[1, 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 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,
    cpu_affinity: None,
});
assert_eq!(t.placement().memory_kind, MemoryKind::PinnedHost);

pub fn set_cpu_affinity(&mut self, cpu_affinity: Option<CpuDomainId>)

Replace only CPU routing/locality metadata without changing storage.

Device, memory kind, backend allocation domain, and allocation identity remain unchanged.

Examples

use tenferro_tensor::{CpuDomainId, TypedTensor};

let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![1], vec![1.0])?;
tensor.set_cpu_affinity(Some(CpuDomainId::new(4)));
assert_eq!(tensor.placement().cpu_affinity, Some(CpuDomainId::new(4)));

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

Compute the checked compact column-major offset of an element.

Examples

use tenferro_tensor::TypedTensor;
let tensor = TypedTensor::<String>::from_vec_col_major([2, 3], vec![String::new(); 6])?;
assert_eq!(tensor.linear_offset(&[1, 2])?, 5);

Errors

Wrong rank, out-of-range coordinates or arithmetic overflow return crate::Error::Validation.

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 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);

Errors

Returns crate::Error::Validation with tenferro_tensor_core::ValidationError::RankMismatch when indices has the wrong rank, tenferro_tensor_core::ValidationError::InvalidArgument when an index is outside its axis extent, or tenferro_tensor_core::ValidationError::IntegerOverflow when offset arithmetic overflows.

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()?);

Errors

Returns crate::Error::Validation with tenferro_tensor_core::ValidationError::IntegerOverflow when compactness arithmetic overflows.

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()?;

Errors

Returns crate::Error::Validation with tenferro_tensor_core::ValidationError::IntegerOverflow when compactness arithmetic overflows, or tenferro_tensor_core::ValidationError::InvalidArgument when the tensor is not compact column-major.

impl<T, R> TypedTensor<T, R>

where T: TensorScalar + Zero, R: TensorRank,

pub fn zeros(shape: impl IntoRankShape<R>) -> 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);

Errors

Returns crate::Error::Validation with tenferro_tensor_core::ValidationError::IntegerOverflow when shape product or compact-stride arithmetic overflows. A vector or slice with a different static rank returns tenferro_tensor_core::ValidationError::RankMismatch.

impl<T, R> TypedTensor<T, R>

where T: TensorScalar + One + Zero, R: TensorRank,

pub fn ones(shape: impl IntoRankShape<R>) -> 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]);

Errors

Returns crate::Error::Validation with tenferro_tensor_core::ValidationError::IntegerOverflow when shape product or compact-stride arithmetic overflows. A vector or slice with a different static rank returns tenferro_tensor_core::ValidationError::RankMismatch.

impl<T, R> TypedTensor<T, R>

where R: TensorRank,

pub fn from_vec_col_major( shape: impl IntoRankShape<R>, data: Vec<T>, ) -> Result<TypedTensor<T, R>, Error>

Adopt a column-major host Vec<T> with no scalar, copy or thread-safety bound.

Examples

use tenferro_tensor::{Rank, TypedTensor};
struct Custom(String);
let tensor = TypedTensor::<Custom, Rank<2>>::from_vec_col_major(
    [1, 2], vec![Custom("a".into()), Custom("b".into())],
)?;
assert_eq!(tensor.get(&[0, 1])?.0.as_str(), "b");

Errors

Returns crate::Error::Validation for a rank mismatch, shape/data length mismatch or shape/stride arithmetic overflow.

pub fn from_vec_row_major( shape: impl IntoRankShape<R>, data: Vec<T>, ) -> Result<TypedTensor<T, R>, Error>

where T: Clone,

Explicitly import row-major host values into column-major storage.

Clones each input element once; no backend or scalar registration is used.

Examples

use tenferro_tensor::{Rank, TypedTensor};
let tensor = TypedTensor::<i32, Rank<2>>::from_vec_row_major(
    [2, 3], vec![1, 2, 3, 4, 5, 6],
)?;
assert_eq!(tensor.get(&[1, 0])?, &4);
assert_eq!(tensor.get(&[0, 2])?, &3);

Errors

Returns crate::Error::Validation for a rank, shape-length or stride overflow, or when the shape product disagrees with the input length.

pub fn into_host_vec( self, ) -> Result<Vec<T>, ReinterpretError<TypedTensor<T, R>>>

where T: 'static,

Consume this compact tensor and return the original host Vec<T>.

Examples

use tenferro_tensor::TypedTensor;
let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2], vec![1, 2])?;
let data = tensor.into_host_vec().map_err(|failure| failure.into_parts().1)?;
assert_eq!(data, vec![1, 2]);

Errors

Returns ReinterpretError carrying the unchanged tensor when the storage is device-only, the managed root cannot export a host vector, or a group-backed descriptor is not compact column-major (tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice).

pub fn into_vec_col_major( self, ) -> Result<(Vec<usize>, Vec<T>), ReinterpretError<TypedTensor<T, R>>>

where T: 'static,

Consume the original host vector along with its column-major shape.

Examples

use tenferro_tensor::TypedTensor;
let tensor = TypedTensor::<i32>::from_vec_col_major(vec![2, 1], vec![1, 2])?;
let (shape, data) = tensor.into_vec_col_major().map_err(|failure| failure.into_parts().1)?;
assert_eq!(shape, vec![2, 1]);
assert_eq!(data, vec![1, 2]);

Errors

Returns ReinterpretError carrying the unchanged tensor when the storage is device-only, the managed root cannot export a host vector, or a group-backed descriptor is not compact column-major (tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice).

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

Borrow the plain host values of this tensor.

A group-backed owner extracted from a larger root exposes only its logical, compact values; Self::as_view retains the whole backing root when a caller needs to inspect elements outside the extent.

Examples

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

Errors

Returns crate::Error::RuntimeState for device-only storage and the non-compact-descriptor validation error for a strided owner.

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

Borrow the logical host values as a flat column-major slice without copying.

This is the value view of Self::host_data: a root-preserving extraction exposes only its compact logical slice, never the root prefix and never elements outside its extent.

Examples

use tenferro_tensor::TypedTensor;
let tensor = TypedTensor::<String>::from_vec_col_major([2], vec!["a".into(), "b".into()])?;
assert_eq!(tensor.as_slice()?, &["a", "b"]);

Errors

Device-only storage returns crate::Error::RuntimeState.

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

Mutably borrow the plain host values of this tensor.

The exclusive borrow covers exactly the logical, compact values of a root-preserving owner, so writes cannot reach elements outside its extent.

Examples

use tenferro_tensor::TypedTensor;
let mut tensor = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
tensor.host_data_mut()?[0] = 5.0;
assert_eq!(tensor.host_data()?, &[5.0, 2.0]);

Errors

Returns crate::Error::RuntimeState for device-only storage and the non-compact-descriptor validation error for a strided owner.

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

Borrow an element by checked column-major multi-index.

Examples

use tenferro_tensor::TypedTensor;
let tensor = TypedTensor::<String>::from_vec_col_major([2], vec!["a".into(), "b".into()])?;
assert_eq!(tensor.get(&[1])?, "b");

Errors

Invalid rank, coordinates or offset return crate::Error::Validation; device-only storage returns crate::Error::RuntimeState.

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

Exclusively borrow an element by checked column-major multi-index.

Examples

use tenferro_tensor::TypedTensor;
let mut tensor = TypedTensor::<String>::from_vec_col_major([1], vec!["a".into()])?;
*tensor.get_mut(&[0])? = "b".into();
assert_eq!(tensor.get(&[0])?, "b");

Errors

Invalid rank, coordinates or offset return crate::Error::Validation; device-only storage returns crate::Error::RuntimeState.

pub fn duplicate(&self) -> Result<TypedTensor<T, R>, Error>

where T: Clone,

Make an explicit independent host copy with the same shape and placement.

The dynamic TypedTensor does not implement Clone (only the host-only representation does): the copy reads host data, rejects device-only storage, and creates a new owner, so it is fallible. See Tensor::duplicate for the sharing alternatives.

Examples

use tenferro_tensor::TypedTensor;
let tensor = TypedTensor::<String>::from_vec_col_major([1], vec!["a".into()])?;
assert_eq!(tensor.duplicate()?.get(&[0])?, "a");

Errors

Device-only storage returns crate::Error::RuntimeState; invalid host metadata returns crate::Error::Validation.

pub fn from_buffer_col_major( shape: impl IntoRankShape<R>, buffer: StorageBuffer<T>, placement: Placement, ) -> Result<TypedTensor<T, R>, Error>

where T: TensorScalar + Send + Sync + '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::{StorageBuffer, Placement, TypedTensor};

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

Errors

Returns crate::Error::Validation with tenferro_tensor_core::ValidationError::ShapeDataLengthMismatch when the shape product differs from the buffer length, tenferro_tensor_core::ValidationError::IntegerOverflow when shape or stride arithmetic overflows, or tenferro_tensor_core::ValidationError::RankMismatch when a supplied rank-specific shape cannot be represented.

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

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 Ok(ranked) = tensor.try_into_rank::<2>() else {
    panic!("a rank-2 tensor converts to two axes")
};
assert_eq!(ranked.shape(), &[2, 3]);

Errors

Returns ReinterpretError carrying the unchanged tensor when the typed rank does not match the existing shape, with crate::Error::Validation and tenferro_tensor_core::ValidationError::RankMismatch as the cause, or when the compact rank layout overflows.

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

where T: 'static,

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.

Panics

Panics only if the typed descriptor and its single group owner are internally inconsistent.

Examples

use tenferro_tensor::{StorageBuffer, TypedTensor};

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

pub fn allocation_domain(&self) -> Option<AllocationDomainId>

where T: 'static,

Return the shared-allocation domain carried by the backend buffer.

Examples

use tenferro_tensor::TypedTensor;

let tensor = TypedTensor::<f32>::from_vec_col_major(vec![1], vec![1.0])?;
assert_eq!(tensor.allocation_domain(), None);

pub fn allocation_id(&self) -> Option<AllocationId>

where T: 'static,

Return the stable physical backend allocation identity.

Examples

use tenferro_tensor::TypedTensor;

let tensor = TypedTensor::<f32>::from_vec_col_major(vec![1], vec![1.0])?;
assert_eq!(tensor.allocation_id(), None);

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

where T: 'static,

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

The view carries the descriptor’s physical layout, so a root-preserving extraction exposes its full backing allocation with the logical slice at the descriptor offset.

Panics

Panics only if the typed descriptor and its single group owner are internally inconsistent.

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: TensorScalar + 'static,

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

Panics

Panics only if the typed descriptor and its single group owner are internally inconsistent.

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: TensorScalar + '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"));

Errors

Returns crate::Error::RuntimeState when this tensor is host-backed; backend region views require a backend buffer. It returns crate::Error::Validation with tenferro_tensor_core::ValidationError::RankMismatch for incompatible shape/stride ranks, tenferro_tensor_core::ValidationError::ViewOutOfBounds when the region exceeds the backend buffer, or tenferro_tensor_core::ValidationError::IntegerOverflow for layout arithmetic overflow.

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

where T: TensorScalar + '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.

The returned view borrows the tensor’s backend owner exclusively for its lifetime. This keeps write authority tied to the owner; a second mutable region view must be created only after the first borrow ends.

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"));

Errors

Returns crate::Error::RuntimeState when this tensor is host-backed; mutable backend region views require a backend buffer. It returns crate::Error::Validation with tenferro_tensor_core::ValidationError::RankMismatch for incompatible shape/stride ranks, tenferro_tensor_core::ValidationError::ViewOutOfBounds when the region exceeds the backend buffer, tenferro_tensor_core::ValidationError::OverlappingMutableLayout when logical elements alias, or tenferro_tensor_core::ValidationError::IntegerOverflow for layout arithmetic overflow.

pub fn into_parts( self, ) -> Result<(StorageBuffer<T>, TensorLayout<R>, Placement), ReinterpretError<TypedTensor<T, R>>>

where T: TensorScalar,

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

A root-preserving owner exports only its compact logical values, exactly like TypedTensor::into_host_vec.

Examples

use tenferro_tensor::{StorageBuffer, TypedTensor};

let t = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
let Ok((buffer, layout, placement)) = t.into_parts() else {
    panic!("a plain host owner extracts")
};
assert!(matches!(buffer, StorageBuffer::Host(_)));
assert_eq!(layout.shape(), &[2]);
assert!(placement.device.is_none());

Errors

Returns ReinterpretError carrying the unchanged tensor when it uses backend storage (download it before extracting host storage) or when a group-backed descriptor is not compact column-major (tenferro_tensor_core::ValidationError::NonContiguousViewAsSlice).

impl<R> TypedTensor<Complex<f32>, R>

where R: TensorRank,

pub fn as_real_view(&self) -> Result<TypedTensorView<'_, f32>, Error>

Borrow this tensor as an interleaved f32 view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, or ValidationError::ViewOutOfBounds for an invalid tensor layout.

pub fn as_real_view_mut(&mut self) -> Result<TypedTensorViewMut<'_, f32>, Error>

Borrow this tensor mutably as an interleaved f32 view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, ValidationError::OverlappingMutableLayout for a non-injective layout, or ValidationError::ViewOutOfBounds for invalid representation metadata.

pub fn into_real( self, ) -> Result<TypedTensor<f32>, ReinterpretError<TypedTensor<Complex<f32>, R>>>

Consume this tensor and reinterpret its owner as f32 without copying.

A failed operation returns the unchanged owner through ReinterpretError::into_owner.

Errors

Returns ReinterpretError::error containing ValidationError::InvalidArgument or ValidationError::ViewOutOfBounds while retaining the unchanged owner.

impl<R> TypedTensor<Complex<f64>, R>

where R: TensorRank,

pub fn as_real_view(&self) -> Result<TypedTensorView<'_, f64>, Error>

Borrow this tensor as an interleaved f64 view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, or ValidationError::ViewOutOfBounds for an invalid tensor layout.

pub fn as_real_view_mut(&mut self) -> Result<TypedTensorViewMut<'_, f64>, Error>

Borrow this tensor mutably as an interleaved f64 view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, ValidationError::OverlappingMutableLayout for a non-injective layout, or ValidationError::ViewOutOfBounds for invalid representation metadata.

pub fn into_real( self, ) -> Result<TypedTensor<f64>, ReinterpretError<TypedTensor<Complex<f64>, R>>>

Consume this tensor and reinterpret its owner as f64 without copying.

A failed operation returns the unchanged owner through ReinterpretError::into_owner.

Errors

Returns ReinterpretError::error containing ValidationError::InvalidArgument or ValidationError::ViewOutOfBounds while retaining the unchanged owner.

impl<R> TypedTensor<f32, R>

where R: TensorRank,

pub fn as_complex_view( &self, ) -> Result<TypedTensorView<'_, Complex<f32>>, Error>

Borrow this tensor as a complex view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, or ValidationError::ViewOutOfBounds for an invalid tensor layout.

pub fn as_complex_view_mut( &mut self, ) -> Result<TypedTensorViewMut<'_, Complex<f32>>, Error>

Borrow this tensor mutably as a complex view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, ValidationError::OverlappingMutableLayout for a non-injective layout, or ValidationError::ViewOutOfBounds for invalid representation metadata.

pub fn into_complex( self, ) -> Result<TypedTensor<Complex<f32>>, ReinterpretError<TypedTensor<f32, R>>>

Consume this tensor and reinterpret its owner as Complex32 without copying.

The compact source must have an even physical element count. A failed operation returns the unchanged owner through ReinterpretError::into_owner.

Errors

Returns ReinterpretError::error containing ValidationError::InvalidArgument or ValidationError::ViewOutOfBounds while retaining the unchanged owner.

impl<R> TypedTensor<f64, R>

where R: TensorRank,

pub fn as_complex_view( &self, ) -> Result<TypedTensorView<'_, Complex<f64>>, Error>

Borrow this tensor as a complex view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, or ValidationError::ViewOutOfBounds for an invalid tensor layout.

pub fn as_complex_view_mut( &mut self, ) -> Result<TypedTensorViewMut<'_, Complex<f64>>, Error>

Borrow this tensor mutably as a complex view without copying.

Errors

Returns crate::Error::Unsupported for backend reinterpretation that is not supported, ValidationError::OverlappingMutableLayout for a non-injective layout, or ValidationError::ViewOutOfBounds for invalid representation metadata.

pub fn into_complex( self, ) -> Result<TypedTensor<Complex<f64>>, ReinterpretError<TypedTensor<f64, R>>>

Consume this tensor and reinterpret its owner as Complex64 without copying.

The compact source must have an even physical element count. A failed operation returns the unchanged owner through ReinterpretError::into_owner.

Errors

Returns ReinterpretError::error containing ValidationError::InvalidArgument or ValidationError::ViewOutOfBounds while retaining the unchanged owner.

Trait Implementations

impl<T, R> Clone for TypedTensor<T, R, Host>

where T: Clone, R: TensorRank,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T, R, D> Debug for TypedTensor<T, R, D>

where R: TensorRank, D: Representation,

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

Formats the value using the given formatter.

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]);

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

Converts to this type from the input type.

impl<T, const N: usize> Index<&[usize; N]> for TypedTensor<T, Rank<N>, Host>

fn index(&self, indices: &[usize; N]) -> &T

The &[usize; N] spelling, which keeps a bare &[i, j] literal resolving as an integer index rather than forcing usize inference to choose between the slice and array spellings.

Panics

Panics when an index is out of bounds, like any other slice indexing. Use TypedTensor::get for the checked form.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
let tensor =
    TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
assert_eq!(tensor[&[0, 1]], 3);

type Output = T

The returned type after indexing.

impl<T, R> Index<&[usize]> for TypedTensor<T, R, Host>

where R: TensorRank,

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

Panics

Panics when the index has the wrong rank or is out of bounds, like any other slice indexing. Use TypedTensor::get for the checked form.

type Output = T

The returned type after indexing.

impl<T, const N: usize> Index<[usize; N]> for TypedTensor<T, Rank<N>, Host>

fn index(&self, indices: [usize; N]) -> &T

Panics

Panics when an index is out of bounds, like any other slice indexing. Use TypedTensor::get for the checked form.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
let tensor =
    TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
assert_eq!(tensor[[0, 1]], 3);

type Output = T

The returned type after indexing.

impl<T, const N: usize> Index<[usize; N]> for TypedTensor<T, Rank<N>>

fn index(&self, indices: [usize; N]) -> &T

Panics

Panics when an index is out of bounds or when the storage is not host-accessible, like any other slice indexing. Use TypedTensor::get for the checked form.

Examples

use tenferro_tensor::{Rank, TypedTensor};
let tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
assert_eq!(tensor[[0, 1]], 3.);

type Output = T

The returned type after indexing.

impl<T, const N: usize> IndexMut<&[usize; N]> for TypedTensor<T, Rank<N>, Host>

fn index_mut(&mut self, indices: &[usize; N]) -> &mut T

Panics

Panics when an index is out of bounds, like any other slice indexing. Use TypedTensor::get_mut for the checked form.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
let mut tensor =
    TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
tensor[&[1, 0]] = 7;
assert_eq!(tensor.as_slice(), &[1, 7, 3, 4]);

impl<T, R> IndexMut<&[usize]> for TypedTensor<T, R, Host>

where R: TensorRank,

fn index_mut(&mut self, indices: &[usize]) -> &mut T

Panics

Panics when the index has the wrong rank or is out of bounds, like any other slice indexing. Use TypedTensor::get_mut for the checked form.

impl<T, const N: usize> IndexMut<[usize; N]> for TypedTensor<T, Rank<N>, Host>

fn index_mut(&mut self, indices: [usize; N]) -> &mut T

Panics

Panics when an index is out of bounds, like any other slice indexing. Use TypedTensor::get_mut for the checked form.

Examples

use tenferro_tensor::{Host, Rank, TypedTensor};
let mut tensor =
    TypedTensor::<i32, Rank<2>, Host>::from_host_vec_col_major([2, 2], vec![1, 2, 3, 4])?;
tensor[[1, 0]] = 7;
assert_eq!(tensor.as_slice(), &[1, 7, 3, 4]);

impl<T, const N: usize> IndexMut<[usize; N]> for TypedTensor<T, Rank<N>>

fn index_mut(&mut self, indices: [usize; N]) -> &mut T

Panics

Panics when an index is out of bounds or when the storage is not host-accessible, like any other slice indexing. Use TypedTensor::get_mut for the checked form.

Examples

use tenferro_tensor::{Rank, TypedTensor};
let mut tensor = TypedTensor::<f64, Rank<2>>::from_vec_col_major([2, 2], vec![1., 2., 3., 4.])?;
tensor[[1, 0]] = 7.;
assert_eq!(tensor.as_slice()?, &[1., 7., 3., 4.]);

impl TypedTensorMaskSessionOpsExt for TypedTensor<bool>

fn where_select<U: TensorScalar>( &self, on_true: &TypedTensor<U>, on_false: &TypedTensor<U>, session: &mut dyn Engine, ) -> Result<TypedTensor<U>>

Select typed values using this bool tensor as condition.

impl<T: TensorScalar> TypedTensorSessionOpsExt<T> for TypedTensor<T>

fn add( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise addition with NumPy-style broadcasting on an engine.

fn add_into( &self, rhs: &TypedTensor<T>, out: &mut TypedTensor<T>, session: &mut dyn Engine, ) -> Result<()>

Elementwise addition into a caller-owned output on an engine.

fn mul( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise multiplication with NumPy-style broadcasting on an engine.

fn exp(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise exponential on an engine.

fn reduce_sum( &self, axes: Option<&[usize]>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Sum over the selected axes on an engine. None reduces every axis and Some(&[]) keeps the input shape.

fn sub( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise subtraction with NumPy-style broadcasting on an engine.

fn div( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise division with NumPy-style broadcasting on an engine.

fn rem( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise remainder with NumPy-style broadcasting on an engine.

fn pow( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise power with NumPy-style broadcasting on an engine.

fn maximum( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise maximum with NumPy-style broadcasting on an engine.

fn minimum( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Elementwise minimum with NumPy-style broadcasting on an engine.

fn neg(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise negation on an engine.

fn abs(&self, session: &mut dyn Engine) -> Result<TypedTensor<T::Real>>

Elementwise absolute value on an engine.

fn sign(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise sign on an engine.

fn conj(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise complex conjugate on an engine.

fn log(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise natural logarithm on an engine.

fn expm1(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise exp(x) - 1 on an engine.

fn log1p(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise log(1 + x) on an engine.

fn erf(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise error function erf(x) on the engine, for real f32/f64.

fn sin(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise sine on an engine.

fn cos(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise cosine on an engine.

fn tanh(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise hyperbolic tangent on an engine.

fn sqrt(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise square root on an engine.

fn rsqrt(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Elementwise reciprocal square root on an engine.

fn compare( &self, rhs: &TypedTensor<T>, dir: CompareDir, session: &mut dyn Engine, ) -> Result<TypedTensor<bool>>

Elementwise comparison with NumPy-style broadcasting on an engine.

fn clamp( &self, lower: &TypedTensor<T>, upper: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Clamp values elementwise between lower and upper bounds on an engine.

fn matmul( &self, rhs: &TypedTensor<T>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Rank-2 matrix multiplication on an engine.

fn reshape( &self, shape: &[usize], session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Reshape through the backend structural operation on an engine.

fn transpose( &self, perm: &[usize], session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Permute axes through the backend structural operation on an engine.

fn broadcast_in_dim( &self, shape: &[usize], dims: &[usize], session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Broadcast into a larger shape on an engine.

fn reduce_max( &self, axes: Option<&[usize]>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Take the maximum over the selected axes on an engine. None reduces every axis and Some(&[]) keeps the input shape.

fn reduce_min( &self, axes: Option<&[usize]>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Take the minimum over the selected axes on an engine. None reduces every axis and Some(&[]) keeps the input shape.

fn reduce_prod( &self, axes: Option<&[usize]>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Multiply over the selected axes on an engine. None reduces every axis and Some(&[]) keeps the input shape.

fn reduce_sum_squares( &self, axes: Option<&[usize]>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Sum elementwise squares over the selected axes on the engine (f32/f64). None reduces every axis and Some(&[]) keeps the input shape.

fn dot_general( &self, rhs: &TypedTensor<T>, config: DotGeneralConfig, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Contract this tensor with rhs on the engine (StableHLO dot_general).

fn dot_general_with_conj( &self, rhs: &TypedTensor<T>, config: DotGeneralConfig, lhs_conj: bool, rhs_conj: bool, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Contract with optional conjugation of either operand on an engine.

fn scale_real( &self, factor: f64, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Multiply by a real scalar on the engine, with the eager scale_real dtype rules.

fn scale_complex( &self, factor: Complex64, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Multiply a complex tensor by a complex scalar on an engine.

fn sigmoid(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Logistic sigmoid 1 / (1 + exp(-x)) on the engine, overflow-free.

fn silu(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

SiLU (swish) x * sigmoid(x) on an engine.

fn softplus(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Softplus log(1 + exp(x)) on the engine, in the stable form max(x, 0) + log1p(exp(-|x|)).

fn gelu(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Exact GELU x/2 * (1 + erf(x / sqrt(2))) on an engine.

fn gelu_tanh(&self, session: &mut dyn Engine) -> Result<TypedTensor<T>>

GELU tanh approximation on the engine (PyTorch approximate="tanh").

fn reduce_mean( &self, axes: Option<&[usize]>, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Arithmetic mean over axes on the engine (None reduces every axis).

fn softmax( &self, axis: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Max-subtracted softmax along axis on an engine.

fn log_softmax( &self, axis: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Max-subtracted log-softmax along axis on an engine.

fn masked_softmax( &self, mask: &TypedTensor<bool>, axis: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Softmax along axis over the entries where the Bool mask is true.

fn masked_log_softmax( &self, mask: &TypedTensor<bool>, axis: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Log-softmax along axis over the entries where the Bool mask is true.

fn layer_norm( &self, axis: usize, weight: Option<&TypedTensor<T>>, bias: Option<&TypedTensor<T>>, eps: f64, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Layer normalization along axis with optional affine weight / bias, on an engine.

fn rms_norm( &self, axis: usize, weight: Option<&TypedTensor<T>>, bias: Option<&TypedTensor<T>>, eps: f64, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

RMS normalization along axis with optional affine weight / bias, on an engine.

fn gather( &self, indices: &Tensor, config: GatherConfig, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Gather windows of this tensor at indices on an engine (StableHLO gather).

fn scatter( &self, indices: &Tensor, updates: &Tensor, config: ScatterConfig, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Scatter updates into a copy of this tensor at indices on an engine.

fn slice( &self, config: SliceConfig, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Slice this tensor with start, limit and stride per axis on an engine.

fn dynamic_slice( &self, starts: &Tensor, sizes: &[usize], session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Slice at runtime starts with static sizes on an engine.

fn dynamic_update_slice( &self, update: &TypedTensor<T>, starts: &Tensor, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Return this tensor with update written at runtime starts on an engine.

fn pad( &self, config: PadConfig, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Pad this tensor with zeros on an engine.

fn concatenate( inputs: &[&TypedTensor<T>], axis: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Concatenate typed tensors along axis on an engine.

fn reverse( &self, axes: &[usize], session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Reverse the elements along axes on an engine.

fn tril(&self, k: i64, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Zero the elements above the k-th diagonal on an engine (keep the lower triangle).

fn triu(&self, k: i64, session: &mut dyn Engine) -> Result<TypedTensor<T>>

Zero the elements below the k-th diagonal on an engine (keep the upper triangle).

fn extract_diag( &self, axis_a: usize, axis_b: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Extract the diagonal over axis_a and axis_b on an engine.

fn embed_diag( &self, axis_a: usize, axis_b: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

Embed this tensor along the diagonal of axis_a and axis_b on an engine.

fn take_along_axis( &self, indices: &Tensor, axis: usize, session: &mut dyn Engine, ) -> Result<TypedTensor<T>>

NumPy-style take_along_axis over gather, on an engine.