Struct Tensor 

pub struct Tensor { /* private fields */ }

A compact, contiguous multi-dtype tensor representation.

Default dtype is F32. FP16 and BF16 dtypes are stored natively as u16 bit patterns and can be created via from_f16 / from_bf16 or converted via to_dtype.

Implementations

impl Tensor

pub fn trace(&self) -> Result<f32, TensorError>

Sum of diagonal elements of a 2D square matrix.

pub fn dot(&self, rhs: &Self) -> Result<f32, TensorError>

Dot product of two 1D tensors.

pub fn cross(&self, rhs: &Self) -> Result<Self, TensorError>

Cross product of two 3-element 1D tensors.

pub fn norm(&self, p: f32) -> f32

Lp norm of all elements. p=1 for L1, p=2 for L2.

pub fn det(&self) -> Result<f32, TensorError>

Determinant of a square matrix (LU-based).

pub fn inv(&self) -> Result<Self, TensorError>

Inverse of a square matrix (Gauss-Jordan elimination).

pub fn solve(&self, b: &Self) -> Result<Self, TensorError>

Solve linear system Ax = b. self is A, rhs is b.

pub fn qr(&self) -> Result<(Self, Self), TensorError>

QR decomposition via Householder reflections. Returns (Q, R).

pub fn cholesky(&self) -> Result<Self, TensorError>

Cholesky decomposition of a symmetric positive-definite matrix. Returns lower triangular L.

impl Tensor

pub fn add(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise addition with NumPy-style broadcasting.

pub fn sub(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise subtraction with NumPy-style broadcasting.

pub fn mul(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise multiplication with NumPy-style broadcasting.

pub fn div(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise division with NumPy-style broadcasting.

pub fn pow(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise power with NumPy-style broadcasting.

Fast paths:

• Constant exponent 2.0 → mul(x, x) (SIMD-accelerated).
• Constant exponent 0.5 → sqrt(x) (SIMD-accelerated).
• Same-shape general case → SIMD exp(exp * ln(base)).

pub fn atan2(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise atan2(self, other), with broadcasting.

Same-shape case uses a SIMD-friendly polynomial approximation of atan with quadrant correction, avoiding scalar f32::atan2.

pub fn minimum(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise minimum with NumPy-style broadcasting.

pub fn maximum(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise maximum with NumPy-style broadcasting.

pub fn neg(&self) -> Self

Element-wise negation.

pub fn abs(&self) -> Self

Element-wise absolute value.

pub fn exp(&self) -> Self

Element-wise natural exponential.

pub fn ln(&self) -> Self

Element-wise natural logarithm.

pub fn sqrt(&self) -> Self

Element-wise square root.

pub fn reciprocal(&self) -> Self

Element-wise reciprocal (1 / x).

pub fn sign(&self) -> Self

Element-wise sign (-1, 0, or 1).

pub fn floor(&self) -> Self

Element-wise floor.

pub fn ceil(&self) -> Self

Element-wise ceil.

pub fn round(&self) -> Self

Element-wise round.

pub fn sin(&self) -> Self

Element-wise sine (SIMD-accelerated polynomial approximation).

pub fn cos(&self) -> Self

Element-wise cosine (SIMD-accelerated polynomial approximation).

pub fn tan(&self) -> Self

Element-wise tangent (SIMD-accelerated via sin/cos).

pub fn asin(&self) -> Self

Element-wise arcsine.

pub fn acos(&self) -> Self

Element-wise arccosine.

pub fn atan(&self) -> Self

Element-wise arctangent.

pub fn sinh(&self) -> Self

Element-wise hyperbolic sine.

pub fn cosh(&self) -> Self

Element-wise hyperbolic cosine.

pub fn log2(&self) -> Self

Element-wise base-2 logarithm.

pub fn log10(&self) -> Self

Element-wise base-10 logarithm.

pub fn degrees(&self) -> Self

Convert radians to degrees.

pub fn radians(&self) -> Self

Convert degrees to radians.

pub fn clamp(&self, min: f32, max: f32) -> Self

Clamp all elements to [min, max].

pub fn scale(&self, factor: f32) -> Self

Scalar multiplication (broadcast multiply by a constant).

pub fn add_scalar(&self, value: f32) -> Self

Add a scalar to all elements.

pub fn sum(&self) -> f32

Sum reduction over all elements.

pub fn mean(&self) -> f32

Mean reduction over all elements.

pub fn max_value(&self) -> f32

Global max reduction. Returns f32::NEG_INFINITY for empty tensors.

pub fn min_value(&self) -> f32

Global min reduction. Returns f32::INFINITY for empty tensors.

pub fn argmax(&self) -> Option<usize>

Global argmax (flat index of maximum value).

pub fn argmin(&self) -> Option<usize>

Global argmin (flat index of minimum value).

pub fn var(&self) -> f32

Variance over all elements (population variance).

pub fn std_dev(&self) -> f32

Standard deviation over all elements (population).

pub fn sum_axis(&self, axis: usize) -> Result<Self, TensorError>

Sum reduction over one axis. Reduced axis is removed from output shape.

pub fn mean_axis(&self, axis: usize) -> Result<Self, TensorError>

Mean reduction over one axis. Reduced axis is removed from output shape.

pub fn max_axis(&self, axis: usize) -> Result<Self, TensorError>

Max reduction over one axis. Reduced axis is removed from output shape.

pub fn min_axis(&self, axis: usize) -> Result<Self, TensorError>

Min reduction over one axis. Reduced axis is removed from output shape.

pub fn var_axis(&self, axis: usize) -> Result<Self, TensorError>

Variance reduction over one axis (population variance).

pub fn median(&self) -> f32

Global median of all elements.

pub fn median_axis(&self, axis: usize) -> Result<Self, TensorError>

Median along a given axis.

pub fn any(&self) -> bool

Returns true if any element is non-zero.

pub fn all(&self) -> bool

Returns true if all elements are non-zero.

pub fn quantile(&self, q: f32) -> f32

Quantile of all elements. q must be in [0, 1].

pub fn transpose_2d(&self) -> Result<Self, TensorError>

2D matrix transpose. Requires rank-2 input.

Safety

AlignedVec::uninitialized allocates without zeroing. The tiled loop writes every element before anything reads from the buffer.

pub fn permute(&self, axes: &[usize]) -> Result<Self, TensorError>

General axis permutation (like NumPy transpose/permute).

pub fn unsqueeze(&self, axis: usize) -> Result<Self, TensorError>

Insert a length-1 dimension at the given axis.

pub fn squeeze(&self, axis: usize) -> Result<Self, TensorError>

Remove a length-1 dimension at the given axis.

pub fn cat(tensors: &[&Self], axis: usize) -> Result<Self, TensorError>

Concatenate tensors along an axis. All tensors must have the same shape except along the concatenation axis.

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

Stack tensors along a new axis. All tensors must have identical shapes.

pub fn select(&self, axis: usize, index: usize) -> Result<Self, TensorError>

Select a single slice along an axis, removing that axis from the output.

pub fn narrow( &self, axis: usize, start: usize, length: usize, ) -> Result<Self, TensorError>

Narrow (slice) along an axis: extract elements start..start+length.

pub fn eq_tensor(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise equality check: 1.0 where equal, 0.0 otherwise.

pub fn gt_tensor(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise greater-than: 1.0 where self > rhs, 0.0 otherwise.

pub fn lt_tensor(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise less-than: 1.0 where self < rhs, 0.0 otherwise.

pub fn gt_tensor_into(&self, rhs: &Self, output: &mut Self)

Element-wise greater-than writing into a pre-allocated output tensor. self, rhs, and output must all have the same shape.

pub fn eq_tensor_into(&self, rhs: &Self, output: &mut Self)

Element-wise equality check writing into a pre-allocated output tensor. self, rhs, and output must all have the same shape.

pub fn lt_tensor_into(&self, rhs: &Self, output: &mut Self)

Element-wise less-than writing into a pre-allocated output tensor. self, rhs, and output must all have the same shape.

pub fn ne_tensor(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise not-equal: 1.0 where not equal (diff.abs() >= 1e-7), 0.0 otherwise.

pub fn le_tensor(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise less-than-or-equal: 1.0 where self <= rhs, 0.0 otherwise.

pub fn ge_tensor(&self, rhs: &Self) -> Result<Self, TensorError>

Element-wise greater-than-or-equal: 1.0 where self >= rhs, 0.0 otherwise.

pub fn all_finite(&self) -> bool

Returns true if all elements are finite (no NaN or Inf).

pub fn where_cond( &self, condition: &Self, other: &Self, ) -> Result<Self, TensorError>

Element-wise where: condition ? self : other. condition has 1.0 for true, 0.0 for false.

pub fn masked_fill(&self, mask: &Self, value: f32) -> Result<Self, TensorError>

Replace elements where mask != 0 with value.

pub fn scatter( &self, axis: usize, index: &Self, src: &Self, ) -> Result<Self, TensorError>

Scatter values into self along axis at positions given by index. src provides the values. index has same shape as src.

pub fn gather(&self, axis: usize, index: &Self) -> Result<Self, TensorError>

Gather elements along axis at positions given by index.

pub fn topk(&self, k: usize) -> Result<(Self, Self), TensorError>

Returns the top-k values and their indices along the last axis.

pub fn triu(&self, diagonal: i64) -> Result<Self, TensorError>

Upper triangular mask: zero below diagonal, keep above. diagonal shifts: 0 = main, positive = above, negative = below.

pub fn tril(&self, diagonal: i64) -> Result<Self, TensorError>

Lower triangular mask: zero above diagonal, keep below.

pub fn eye(n: usize) -> Result<Self, TensorError>

Identity matrix [n, n].

pub fn diag(vector: &Tensor) -> Result<Self, TensorError>

Create a diagonal matrix from a 1D vector.

pub fn diag_extract(&self) -> Result<Self, TensorError>

Extract the diagonal of a 2D matrix as a 1D vector.

pub fn pad( &self, padding: &[(usize, usize)], value: f32, ) -> Result<Self, TensorError>

Pad the tensor with a constant value. padding is a slice of (before, after) per dimension.

pub fn repeat(&self, counts: &[usize]) -> Result<Self, TensorError>

Repeat tensor along each axis by the given counts.

pub fn cumsum(&self, axis: usize) -> Result<Self, TensorError>

Cumulative sum along an axis.

pub fn cumprod(&self, axis: usize) -> Result<Self, TensorError>

Cumulative product along an axis.

pub fn to_fp16(&self) -> Vec<u16>

Convert all elements to IEEE 754 half-precision (FP16) bytes. Returns Vec<u16> where each u16 is an FP16 bit pattern.

pub fn from_fp16( shape: Vec<usize>, fp16_data: &[u16], ) -> Result<Self, TensorError>

Create a tensor from FP16 bit patterns.

pub fn relu_inplace(&mut self)

In-place ReLU: clamp negative values to zero.

pub fn add_inplace(&mut self, rhs: &Self)

In-place element-wise add from another tensor (must have same shape).

pub fn add_scalar_inplace(&mut self, s: f32)

In-place add scalar to all elements.

pub fn mul_scalar_inplace(&mut self, s: f32)

In-place multiply all elements by scalar.

pub fn add_into(output: &mut Self, lhs: &Self, rhs: &Self)

Element-wise addition writing into a pre-allocated output tensor. output, lhs, and rhs must all have the same shape.

pub fn sub_into(output: &mut Self, lhs: &Self, rhs: &Self)

Element-wise subtraction writing into a pre-allocated output tensor. output, lhs, and rhs must all have the same shape.

pub fn mul_into(output: &mut Self, lhs: &Self, rhs: &Self)

Element-wise multiplication writing into a pre-allocated output tensor. output, lhs, and rhs must all have the same shape.

impl Tensor

pub fn sort( &self, dim: usize, descending: bool, ) -> Result<(Self, Self), TensorError>

Sort along dim. Returns (sorted_values, sorted_indices).

If descending is true, values are sorted largest-first.

pub fn argsort(&self, dim: usize, descending: bool) -> Result<Self, TensorError>

Return indices that would sort along dim.

pub fn unique(&self) -> (Self, Self, Self)

Return unique elements (sorted), inverse indices, and counts.

pub fn nonzero(&self) -> Self

Return coordinates of nonzero elements as a 2D tensor [N, rank].

pub fn flip(&self, dims: &[usize]) -> Result<Self, TensorError>

Reverse elements along the given dimensions.

pub fn roll(&self, shift: i64, dim: usize) -> Result<Self, TensorError>

Circular shift elements along dim by shift positions.

pub fn linspace(start: f32, end: f32, steps: usize) -> Result<Self, TensorError>

Create a 1-D tensor of steps evenly spaced values from start to end (inclusive).

pub fn arange(start: f32, end: f32, step: f32) -> Result<Self, TensorError>

Create a 1-D tensor with values in [start, end) with given step.

pub fn meshgrid(tensors: &[Self]) -> Result<Vec<Self>, TensorError>

Create coordinate grids from 1-D tensors (numpy-style meshgrid with indexing='ij').

pub fn boolean_mask(&self, mask: &Self) -> Result<Self, TensorError>

Select elements where mask (f32, nonzero = true) is true, returned as 1-D.

pub fn index_select( &self, dim: usize, indices: &Self, ) -> Result<Self, TensorError>

Select slices along dim using integer indices tensor (1-D).

pub fn rand(shape: Vec<usize>, seed: u64) -> Result<Self, TensorError>

Create a tensor filled with uniform random values in [0, 1).

pub fn randn(shape: Vec<usize>, seed: u64) -> Result<Self, TensorError>

Create a tensor filled with normally distributed random values (mean=0, std=1). Uses Box-Muller transform.

pub fn randint( shape: Vec<usize>, low: i64, high: i64, seed: u64, ) -> Result<Self, TensorError>

Create a tensor filled with random integers in [low, high).

pub fn randperm(n: usize, seed: u64) -> Result<Self, TensorError>

Create a random permutation of integers [0, n).

impl Tensor

pub fn step_slice( &self, dim: usize, start: usize, end: usize, step: usize, ) -> Result<Self, TensorError>

Slice with step: extract every step-th element along dim from start to end.

pub fn einsum( equation: &str, tensors: &[&Tensor], ) -> Result<Tensor, TensorError>

Einstein summation for common patterns.

Supported equations:

• "ij,jk->ik" — matrix multiply
• "ij->ji" — transpose
• "ii->i" — diagonal
• "ij->i" — row sum
• "ij->j" — column sum
• "ij->" — total sum
• "i,i->" — dot product
• "ij,ij->" — Frobenius inner product

pub fn chunk( &self, n_chunks: usize, axis: usize, ) -> Result<Vec<Self>, TensorError>

Split tensor into n_chunks pieces along axis. Last chunk may be smaller.

pub fn histogram( &self, bins: usize, min: f32, max: f32, ) -> Result<Self, TensorError>

Counts elements in each bin, returns 1D tensor of shape [bins]. Bins are evenly spaced between min and max.

pub fn bincount(&self, num_bins: usize) -> Result<Self, TensorError>

Treats values as integer indices, counts occurrences. Returns 1D tensor of shape [num_bins].

pub fn item(&self) -> Result<f32, TensorError>

Returns the single scalar value if tensor has exactly one element. Errors if tensor has more than one element.

pub fn is_scalar(&self) -> bool

Returns true if tensor has exactly one element.

pub fn scatter_add( &self, dim: usize, index: &Self, src: &Self, ) -> Result<Self, TensorError>

Like scatter but adds instead of replacing values.

For dim=1: self[i][index[i][j][k]][k] += src[i][j][k]

impl Tensor

pub fn scalar(value: f32) -> Self

Builds a scalar tensor from one value.

pub fn from_raw_parts( shape: &[usize], strides: &[usize], data: AlignedVec<f32>, ) -> Self

Creates a tensor from pre-validated shape, strides, and data. No validation, no heap allocation (shape/strides stored inline for ≤6D).

pub fn from_aligned( shape: Vec<usize>, data: AlignedVec<f32>, ) -> Result<Self, TensorError>

Builds a tensor from shape and a pre-filled AlignedVec.

This avoids the extra copy that from_vec performs when converting a Vec<f32> into aligned storage. Use this when the output buffer was already allocated as an AlignedVec (e.g. via AlignedVec::uninitialized filled by a BLAS/SIMD kernel).

pub fn from_vec(shape: Vec<usize>, data: Vec<f32>) -> Result<Self, TensorError>

Builds a tensor from shape and raw contiguous f32 data.

pub fn from_f16(shape: Vec<usize>, data: Vec<u16>) -> Result<Self, TensorError>

Builds a tensor from shape and raw FP16 bit patterns (u16).

pub fn from_bf16(shape: Vec<usize>, data: Vec<u16>) -> Result<Self, TensorError>

Builds a tensor from shape and raw BF16 bit patterns (u16).

pub fn from_slice(data: &[f32]) -> Self

Builds a 1-D tensor from a slice. Equivalent to from_vec(vec![data.len()], data.to_vec()).

pub fn filled(shape: Vec<usize>, value: f32) -> Result<Self, TensorError>

Builds a value-initialized tensor for a given shape.

Alias: full is provided as a more familiar name.

pub fn zeros(shape: Vec<usize>) -> Result<Self, TensorError>

Builds a zero-initialized tensor for a given shape.

Uses alloc_zeroed under the hood so the OS can provide pre-zeroed pages without writing every byte — significantly faster for large tensors.

pub fn ones(shape: Vec<usize>) -> Result<Self, TensorError>

Builds a one-initialized tensor for a given shape.

pub fn full(shape: Vec<usize>, value: f32) -> Result<Self, TensorError>

Builds a tensor filled with value. Alias for filled.

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

Returns the tensor shape.

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

Returns the tensor strides.

pub fn rank(&self) -> usize

Returns tensor rank (number of axes).

pub fn len(&self) -> usize

Returns element count.

pub fn is_empty(&self) -> bool

Returns true if tensor contains zero elements.

pub fn dtype(&self) -> DType

Returns the element data type.

pub fn device(&self) -> Device

Returns the logical device this tensor is associated with.

pub fn to_device(&self, device: Device) -> Self

Returns a copy of this tensor tagged with the given device.

This is currently a metadata-only operation — no actual data transfer occurs. GPU data movement is handled by GpuSession in yscv-kernels.

pub fn is_f32(&self) -> bool

Returns true if the tensor stores f32 data.

pub fn try_data(&self) -> Result<&[f32], TensorError>

Fallible version of data() — returns an error for non-F32 tensors.

pub fn try_data_mut(&mut self) -> Result<&mut [f32], TensorError>

Fallible version of data_mut() — returns an error for non-F32 tensors.

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

Returns an immutable view over contiguous f32 storage.

Panics

Panics if the tensor dtype is not F32. Use try_data() for a fallible version.

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

Returns a mutable view over contiguous f32 storage.

Panics

Panics if the tensor dtype is not F32. Use try_data_mut() for a fallible version.

pub fn try_data_f32(&self) -> Result<&[f32], TensorError>

Alias for try_data() for backward compatibility.

pub fn data_f16(&self) -> Result<&[u16], TensorError>

Returns raw FP16 bit-pattern data if dtype is F16.

pub fn data_bf16(&self) -> Result<&[u16], TensorError>

Returns raw BF16 bit-pattern data if dtype is BF16.

pub fn to_dtype(&self, target: DType) -> Self

Converts this tensor to the specified dtype, returning a new tensor. Converting to the same dtype is a no-op clone.

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

Reads one element by multi-dimensional index (always returns f32).

pub fn set(&mut self, indices: &[usize], value: f32) -> Result<(), TensorError>

Writes one element by multi-dimensional index (stores as native dtype).

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

Returns a reshaped tensor view with copied metadata and data.

pub fn into_reshape(self, new_shape: Vec<usize>) -> Result<Self, TensorError>

Consumes the tensor and returns a reshaped version without copying data.

Trait Implementations

impl Add for &Tensor

fn add(self, rhs: Self) -> Tensor

Element-wise addition. Panics on shape mismatch.

type Output = Tensor

The resulting type after applying the + operator.

impl Add for Tensor

type Output = Tensor

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Tensor

Performs the + operation.

impl Clone for Tensor

fn clone(&self) -> Tensor

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Tensor

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

Formats the value using the given formatter.

impl Display for Tensor

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

Formats the value using the given formatter.

impl Div for &Tensor

type Output = Tensor

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Tensor

Performs the / operation.

impl Div for Tensor

type Output = Tensor

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Tensor

Performs the / operation.

impl Mul<f32> for &Tensor

fn mul(self, rhs: f32) -> Tensor

Scalar multiplication.

type Output = Tensor

The resulting type after applying the * operator.

impl Mul<f32> for Tensor

type Output = Tensor

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Tensor

Performs the * operation.

impl Mul for &Tensor

fn mul(self, rhs: Self) -> Tensor

Element-wise multiplication. Panics on shape mismatch.

type Output = Tensor

The resulting type after applying the * operator.

impl Mul for Tensor

type Output = Tensor

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Tensor

Performs the * operation.

impl Neg for &Tensor

type Output = Tensor

The resulting type after applying the - operator.

fn neg(self) -> Tensor

Performs the unary - operation.

impl Neg for Tensor

type Output = Tensor

The resulting type after applying the - operator.

fn neg(self) -> Tensor

Performs the unary - operation.

impl PartialEq for Tensor

fn eq(&self, other: &Tensor) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub for &Tensor

type Output = Tensor

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Tensor

Performs the - operation.

impl Sub for Tensor

type Output = Tensor

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Tensor

Performs the - operation.

impl StructuralPartialEq for Tensor