Struct Tensor 

pub struct Tensor<R>
where
    R: Runtime,
{ /* private fields */ }

N-dimensional array stored on a compute device

Tensor is the fundamental data structure in numr. It consists of:

• Storage: Reference-counted device memory
• Layout: Shape, strides, and offset defining the view into storage
• DType: Element type (determined at runtime)

Zero-Copy Views

Operations like transpose, slice, and reshape create new tensors that share the same underlying storage. This is achieved through:

• Arc-wrapped storage (reference counting)
• Modified layout (different strides/offset)

Example

let a = Tensor::<CpuRuntime>::from_slice(&[1.0f32, 2.0, 3.0, 4.0], &[2, 2], &device);
let b = a.transpose(-1, -2); // Zero-copy, shares storage with a

Implementations

impl<R> Tensor<R>

where R: Runtime,

pub fn from_parts(storage: Storage<R>, layout: Layout) -> Tensor<R>

Create a tensor from storage and layout

pub fn empty( shape: &[usize], dtype: <R as Runtime>::DType, device: &<R as Runtime>::Device, ) -> Tensor<R>

Create an uninitialized tensor

Safety

The contents are uninitialized. Reading before writing is undefined behavior.

Panics

Panics if allocation fails. Use Self::try_empty in fallible contexts.

pub fn try_empty( shape: &[usize], dtype: <R as Runtime>::DType, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create an uninitialized tensor (fallible version)

pub fn id(&self) -> TensorId

Get the internal tensor ID for autograd graph tracking.

pub fn storage(&self) -> &Storage<R>

Get the storage

pub fn layout(&self) -> &Layout

Get the layout

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

Get the shape

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

Get the strides

pub fn ndim(&self) -> usize

Get the number of dimensions (rank)

pub fn numel(&self) -> usize

Get the total number of elements

pub fn dtype(&self) -> <R as Runtime>::DType

Get the element type

pub fn device(&self) -> &<R as Runtime>::Device

Get the device

pub fn is_contiguous(&self) -> bool

Check if the tensor is contiguous in memory

pub fn is_scalar(&self) -> bool

Check if this is a scalar (0-dimensional tensor)

pub fn size(&self, dim: isize) -> Option<usize>

Get size along a dimension (supports negative indexing)

pub fn dim(&self, index: isize) -> Result<usize, Error>

Get size along a dimension, returning error on invalid index

pub fn rank(&self) -> usize

Number of dimensions (alias for ndim)

pub fn elem_count(&self) -> usize

Total number of elements (alias for numel)

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

Shape as slice (alias for shape)

pub fn len(&self) -> usize

Total number of elements (alias for numel)

pub fn is_empty(&self) -> bool

Whether the tensor has zero elements

pub fn offset(&self) -> usize

Layout offset into storage (in elements)

pub fn ptr(&self) -> u64

Data pointer adjusted for layout offset. This is the pointer to the first element of this tensor’s view.

pub fn owns_memory(&self) -> bool

Whether the underlying storage is owned (will deallocate on drop)

pub fn shares_storage_with(&self, other: &Tensor<R>) -> bool

Check if two tensors share the same storage

pub fn ref_count(&self) -> usize

Storage reference count

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

Unpack shape of a 1D tensor

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

Unpack shape of a 2D tensor

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

Unpack shape of a 3D tensor

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

Unpack shape of a 4D tensor

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

Unpack shape of a 5D tensor

pub fn from_storage_contiguous( storage: Storage<R>, shape: &[usize], ) -> Tensor<R>

Create tensor from storage and contiguous layout

pub fn transpose(&self, dim0: isize, dim1: isize) -> Result<Tensor<R>, Error>

Transpose two dimensions (zero-copy)

pub fn t(&self) -> Result<Tensor<R>, Error>

Transpose last two dimensions (matrix transpose)

pub fn reshape(&self, shape: &[usize]) -> Result<Tensor<R>, Error>

Reshape to a new shape (zero-copy if contiguous)

pub fn flatten(&self) -> Result<Tensor<R>, Error>

Flatten to 1D (zero-copy if contiguous)

pub fn squeeze(&self, dim: Option<isize>) -> Tensor<R>

Remove dimensions of size 1

pub fn unsqueeze(&self, dim: isize) -> Result<Tensor<R>, Error>

Add a dimension of size 1

pub fn view(&self, shape: &[usize]) -> Result<Tensor<R>, Error>

View tensor with different shape (alias for reshape)

pub fn permute(&self, dims: &[usize]) -> Result<Tensor<R>, Error>

Permute dimensions (zero-copy)

Reorders the dimensions of the tensor according to the given permutation. This is a view operation - no data is copied.

Arguments

• dims - New order of dimensions. Must be a permutation of 0..ndim.

Example

let tensor = Tensor::<CpuRuntime>::from_slice(&data, &[2, 3, 4], &device);
let permuted = tensor.permute(&[2, 0, 1])?; // Shape becomes [4, 2, 3]

pub fn narrow( &self, dim: isize, start: usize, length: usize, ) -> Result<Tensor<R>, Error>

Narrow a dimension (zero-copy slice)

Returns a view of the tensor narrowed to a contiguous subset of elements along a single dimension. This is a view operation - no data is copied.

Arguments

• dim - Dimension to narrow (supports negative indexing)
• start - Starting index in that dimension
• length - Number of elements to keep

Example

let tensor = Tensor::<CpuRuntime>::from_slice(&data, &[4, 5, 6], &device);
let narrowed = tensor.narrow(1, 1, 3)?; // Shape becomes [4, 3, 6]

pub fn broadcast_to(&self, shape: &[usize]) -> Result<Tensor<R>, Error>

Broadcast to a target shape (zero-copy)

pub fn flip(&self, dim: isize) -> Result<Tensor<R>, Error>

Flip (reverse) tensor along a dimension (zero-copy)

Reverses the order of elements along the specified dimension. This is a view operation - no data is copied.

Arguments

• dim - Dimension to flip (supports negative indexing)

Example

let tensor = Tensor::<CpuRuntime>::from_slice(&[1.0, 2.0, 3.0, 4.0], &[2, 2], &device);
let flipped = tensor.flip(0)?; // Reverse rows: [[3, 4], [1, 2]]
let flipped = tensor.flip(-1)?; // Reverse columns: [[2, 1], [4, 3]]

pub fn flip_dims(&self, dims: &[isize]) -> Result<Tensor<R>, Error>

Flip (reverse) tensor along multiple dimensions (zero-copy)

Arguments

• dims - Dimensions to flip (supports negative indexing)

Example

let tensor = Tensor::<CpuRuntime>::from_slice(&data, &[2, 3, 4], &device);
let flipped = tensor.flip_dims(&[0, 2])?; // Flip first and last dimensions

pub fn contiguous(&self) -> Tensor<R>

Make tensor contiguous (copy if needed)

If the tensor is already contiguous, returns a view (zero-copy). Otherwise, allocates new storage and copies the data to a contiguous layout.

Backend Support

This method uses Runtime::copy_strided which handles strided copies correctly for each backend:

• CPU/CUDA: Uses pointer arithmetic (handles can be offset directly)
• WGPU: Uses compute shader (buffer IDs don’t support arithmetic)

pub fn detach(&self) -> Tensor<R>

Detach from computation graph (for autograd)

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

where T: Pod,

Copy tensor data to a Vec on the host

For contiguous tensors, this copies only the viewed portion of the storage, respecting the tensor’s shape and offset.

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

Record an event on the compute stream for this tensor’s device.

Call this BEFORE launching additional compute work, then pass the event to to_vec_pipelined AFTER launching the compute work. This allows the copy to proceed as soon as the event fires, while compute continues.

pub fn to_vec_pipelined<T>(&self, event: u64) -> Result<Vec<T>, Error>

where T: Pod,

Copy tensor data to a Vec using the pipelined copy stream, synchronized via a previously recorded event.

On CUDA, syncs only the copy stream — compute stream keeps running.

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

where T: Pod + Copy,

Extract the scalar value from a single-element tensor

This is the idiomatic way to get a scalar value from a tensor for use in Rust control flow (convergence checks, comparisons, etc.).

Returns

The single element as type T, or an error if the tensor doesn’t contain exactly one element.

Example

let loss_val: f32 = loss.item()?;
if loss_val < 1.0 {
    // training converged
}

impl<R> Tensor<R>

where R: Runtime,

pub fn try_zeros_generic( shape: &[usize], dtype: <R as Runtime>::DType, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create a tensor filled with zeros (generic, works with any DType)

pub fn try_ones_generic( shape: &[usize], dtype: <R as Runtime>::DType, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create a tensor filled with ones (generic, works with any DType)

pub fn try_full_scalar_generic( shape: &[usize], dtype: <R as Runtime>::DType, value: f64, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create a tensor filled with a scalar value (generic, works with any DType)

Uses DataType::fill_bytes to generate the fill pattern, so it works with any DType that implements the trait (including boostr’s quantized types).

pub fn try_from_bytes( bytes: &[u8], shape: &[usize], dtype: <R as Runtime>::DType, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create a tensor from raw bytes with specified dtype (generic)

impl<R> Tensor<R>

where R: Runtime<DType = DType>,

pub fn from_slice<T>( data: &[T], shape: &[usize], device: &<R as Runtime>::Device, ) -> Tensor<R>

where T: Element,

Create a tensor from a slice of data

Panics

Panics if data.len() does not equal the product of the shape dimensions. For a fallible alternative, use Self::try_from_slice.

Example

let tensor = Tensor::<CpuRuntime>::from_slice(&[1.0f32, 2.0, 3.0, 4.0], &[2, 2], &device);

pub fn try_from_slice<T>( data: &[T], shape: &[usize], device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

where T: Element,

Create a tensor from a slice of data (fallible version)

Returns an error if data.len() does not equal the product of the shape dimensions, or if memory allocation fails.

Example

let tensor = Tensor::<CpuRuntime>::try_from_slice(&[1.0f32, 2.0, 3.0, 4.0], &[2, 2], &device)?;

pub fn zeros( shape: &[usize], dtype: DType, device: &<R as Runtime>::Device, ) -> Tensor<R>

Create a tensor filled with zeros

This properly initializes memory to zero on all backends (CPU and GPU).

pub fn try_zeros( shape: &[usize], dtype: DType, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create a tensor filled with zeros (fallible version)

pub fn ones( shape: &[usize], dtype: DType, device: &<R as Runtime>::Device, ) -> Tensor<R>

Create a tensor filled with ones

pub fn try_ones( shape: &[usize], dtype: DType, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create a tensor filled with ones (fallible version)

pub fn full_scalar( shape: &[usize], dtype: DType, value: f64, device: &<R as Runtime>::Device, ) -> Tensor<R>

Create a tensor filled with a scalar value

The scalar is converted to the target dtype.

pub fn try_full_scalar( shape: &[usize], dtype: DType, value: f64, device: &<R as Runtime>::Device, ) -> Result<Tensor<R>, Error>

Create a tensor filled with a scalar value (fallible version)

impl<R> Tensor<R>

where R: Runtime,

pub fn to_bytes(&self) -> Result<Vec<u8>, Error>

Serialize tensor data to raw bytes

Makes tensor contiguous first if needed, then copies raw bytes from device.

pub fn clone_deep(&self) -> Result<Tensor<R>, Error>

Clone tensor with new storage (deep copy)

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: BinaryOps<R>,

pub fn add(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise addition: self + other

pub fn sub(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise subtraction: self - other

pub fn mul(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise multiplication: self * other

pub fn div(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise division: self / other

pub fn pow(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise power: self ^ other

pub fn maximum(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise maximum: max(self, other)

pub fn minimum(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise minimum: min(self, other)

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: UnaryOps<R>,

pub fn neg(&self) -> Result<Tensor<R>, Error>

Element-wise negation

pub fn abs(&self) -> Result<Tensor<R>, Error>

Element-wise absolute value

pub fn sqrt(&self) -> Result<Tensor<R>, Error>

Element-wise square root

pub fn exp(&self) -> Result<Tensor<R>, Error>

Element-wise exponential

pub fn log(&self) -> Result<Tensor<R>, Error>

Element-wise natural log

pub fn sin(&self) -> Result<Tensor<R>, Error>

Element-wise sine

pub fn cos(&self) -> Result<Tensor<R>, Error>

Element-wise cosine

pub fn tan(&self) -> Result<Tensor<R>, Error>

Element-wise tangent

pub fn tanh(&self) -> Result<Tensor<R>, Error>

Element-wise hyperbolic tangent

pub fn recip(&self) -> Result<Tensor<R>, Error>

Element-wise reciprocal (1/x)

pub fn floor(&self) -> Result<Tensor<R>, Error>

Element-wise floor

pub fn ceil(&self) -> Result<Tensor<R>, Error>

Element-wise ceil

pub fn round(&self) -> Result<Tensor<R>, Error>

Element-wise round

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: ScalarOps<R>,

pub fn add_scalar(&self, scalar: f64) -> Result<Tensor<R>, Error>

Add scalar: self + scalar

pub fn mul_scalar(&self, scalar: f64) -> Result<Tensor<R>, Error>

Multiply by scalar: self * scalar

pub fn scale(&self, scalar: f64) -> Result<Tensor<R>, Error>

Scale alias for mul_scalar

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: ActivationOps<R>,

pub fn relu(&self) -> Result<Tensor<R>, Error>

ReLU activation: max(0, x)

pub fn sigmoid(&self) -> Result<Tensor<R>, Error>

Sigmoid activation: 1 / (1 + exp(-x))

pub fn gelu(&self) -> Result<Tensor<R>, Error>

GELU activation

pub fn silu(&self) -> Result<Tensor<R>, Error>

SiLU/Swish activation: x * sigmoid(x)

pub fn softmax(&self, dim: isize) -> Result<Tensor<R>, Error>

Softmax along dimension

pub fn log_softmax(&self, dim: isize) -> Result<Tensor<R>, Error>

Log-softmax along dimension: log(softmax(x, dim))

pub fn dropout(&self, p: f64, training: bool) -> Result<Tensor<R>, Error>

Dropout: randomly zero elements with probability p during training

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: ReduceOps<R>,

pub fn sum(&self, dims: &[usize], keepdim: bool) -> Result<Tensor<R>, Error>

Sum along dimensions

pub fn mean(&self, dims: &[usize], keepdim: bool) -> Result<Tensor<R>, Error>

Mean along dimensions

pub fn max(&self, dims: &[usize], keepdim: bool) -> Result<Tensor<R>, Error>

Max along dimensions

pub fn min(&self, dims: &[usize], keepdim: bool) -> Result<Tensor<R>, Error>

Min along dimensions

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: MatmulOps<R>,

pub fn matmul(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Matrix multiplication: self @ other

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: NormalizationOps<R>,

pub fn rms_norm(&self, weight: &Tensor<R>, eps: f32) -> Result<Tensor<R>, Error>

RMS normalization: x / RMS(x) * weight

pub fn layer_norm( &self, weight: &Tensor<R>, bias: &Tensor<R>, eps: f32, ) -> Result<Tensor<R>, Error>

Layer normalization: (x - mean) / sqrt(var + eps) * weight + bias

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: CompareOps<R>,

pub fn eq(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise equality

pub fn gt(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise greater than

pub fn lt(&self, other: &Tensor<R>) -> Result<Tensor<R>, Error>

Element-wise less than

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: IndexingOps<R>,

pub fn index_select( &self, dim: usize, indices: &Tensor<R>, ) -> Result<Tensor<R>, Error>

Select elements along a dimension using indices

pub fn argmax(&self, dim: usize, keepdim: bool) -> Result<Tensor<R>, Error>

Argmax along a dimension

pub fn argmin(&self, dim: usize, keepdim: bool) -> Result<Tensor<R>, Error>

Argmin along a dimension

pub fn masked_fill( &self, mask: &Tensor<R>, value: f64, ) -> Result<Tensor<R>, Error>

Fill tensor with value where mask is true

pub fn slice_assign( &self, src: &Tensor<R>, dim: usize, start: usize, ) -> Result<Tensor<R>, Error>

Assign src into a slice of self along dim starting at start.

Returns a new tensor with the slice region replaced by src.

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: ShapeOps<R>,

pub fn cat(tensors: &[&Tensor<R>], dim: isize) -> Result<Tensor<R>, Error>

Concatenate tensors along a dimension

pub fn stack(tensors: &[&Tensor<R>], dim: isize) -> Result<Tensor<R>, Error>

Stack tensors along a new dimension

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: CumulativeOps<R>,

pub fn cumsum(&self, dim: isize) -> Result<Tensor<R>, Error>

Cumulative sum along a dimension

pub fn cumprod(&self, dim: isize) -> Result<Tensor<R>, Error>

Cumulative product along a dimension

pub fn logsumexp( &self, dims: &[usize], keepdim: bool, ) -> Result<Tensor<R>, Error>

Log-sum-exp along specified dimensions (numerically stable)

Computes log(sum(exp(x))) in a numerically stable way: logsumexp(x) = max(x) + log(sum(exp(x - max(x))))

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: TypeConversionOps<R>,

pub fn to_dtype(&self, dtype: DType) -> Result<Tensor<R>, Error>

Convert tensor to a different dtype

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: UtilityOps<R>,

pub fn clamp(&self, min: f64, max: f64) -> Result<Tensor<R>, Error>

Clamp values to [min, max]

pub fn one_hot(&self, num_classes: usize) -> Result<Tensor<R>, Error>

One-hot encode indices

impl<R> Tensor<R>

where R: Runtime, <R as Runtime>::Client: ConvOps<R>,

pub fn conv1d( &self, weight: &Tensor<R>, bias: Option<&Tensor<R>>, stride: usize, padding: PaddingMode, dilation: usize, groups: usize, ) -> Result<Tensor<R>, Error>

1D convolution

Trait Implementations

impl<R> Clone for Tensor<R>

where R: Runtime,

fn clone(&self) -> Tensor<R>

Clone creates a new tensor sharing the same storage (zero-copy)

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

Performs copy-assignment from source.

impl<R> Debug for Tensor<R>

where R: Runtime,

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

Formats the value using the given formatter.

impl<R> Display for Tensor<R>

where R: Runtime,

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

Formats the value using the given formatter.