Struct Tensor 

pub struct Tensor { /* private fields */ }

A tensor: shared storage viewed through a layout.

Cloning a tensor is cheap — it clones the layout and bumps the storage refcount, never the data. View operations (reshape, permute, narrow, …) produce new tensors over the same storage whenever the layout arithmetic allows it.

Implementations

impl Tensor

pub fn eye(n: usize) -> Tensor

The n × n identity matrix on the CPU.

Panics

Panics if n * n overflows usize. Unchecked, this wrapped to a short allocation and surfaced as an index-out-of-bounds below.

pub fn eye_on(n: usize, device: Device) -> Result<Tensor>

The n × n identity matrix on device.

pub fn diag(&self) -> Result<Tensor>

The diagonal of every matrix in a [.., n, n] tensor, as [.., n]. Differentiable.

pub fn diag_embed(&self) -> Result<Tensor>

Matrices with the vectors of a [.., n] tensor on their diagonals, as [.., n, n]. Differentiable.

pub fn trace(&self) -> Result<Tensor>

The trace of every matrix in a [.., n, n] tensor, as [..]. Differentiable.

pub fn cholesky(&self) -> Result<Tensor>

Lower-triangular Cholesky factor L of every symmetric positive-definite matrix in a [.., n, n] tensor, L Lᵀ = A.

Reads the lower triangle. A matrix that is not positive definite is a typed Error::InvalidArgument naming the batch index and pivot. The backward pass runs on the host and returns to the input’s device; its intermediates are f64, but it takes its inputs as f32, so an f64 gradient carries f32 precision.

Gradient convention

The gradient (Murray 2016) is taken with respect to symmetric perturbations of the input: d logdet/dA = A⁻¹, which is the standard result and what PyTorch returns. Because the forward reads only the lower triangle, an elementwise finite difference — which perturbs one entry and so breaks symmetry — does not agree with it, and oxmera_autograd::gradcheck cannot be used on cholesky, logdet or det directly. Check them through a symmetrizer ((X + Xᵀ)/2), as tests/gradcheck.rs does, or against A⁻¹.

The practical consequence: feed these ops a symmetric matrix. Given an asymmetric one the forward silently uses the lower triangle while the gradient describes a symmetric matrix, and the two disagree.

pub fn logdet(&self) -> Result<Tensor>

ln det A of every SPD matrix in a [.., n, n] tensor, as [..], through the Cholesky factor: 2 Σ ln diag(L). Differentiable (the gradient is A⁻¹, symmetrized).

pub fn det(&self) -> Result<Tensor>

det A of every SPD matrix in a [.., n, n] tensor, as [..], through the Cholesky factor. Differentiable. For an indefinite matrix use eigh — this is the SPD determinant.

pub fn eigh(&self) -> Result<(Tensor, Tensor)>

Eigen-decomposition of every symmetric matrix in a [.., n, n] tensor: eigenvalues ascending as [.., n] and orthonormal eigenvectors as the columns of [.., n, n] (A V = V Λ). Not differentiable.

The input must be symmetric to within EIGH_SYMMETRY_TOL (relative); anything further is a typed Error::InvalidArgument naming the batch index and the worst offending pair.

Before 0.4.0 the full matrix was read and silently symmetrized, so a non-symmetric input returned the eigenpairs of (A + Aᵀ)/2 — a different matrix — with no error: [[1, 2], [5, 1]] answered [-2.5, 4.5] where the true eigenvalues are 1 ± √10, and the returned pair did not satisfy A v = λ v for the A that was passed. The tolerance keeps the case the check exists to permit — a covariance or Gram matrix assembled as XᵀX / n in f32, which is symmetric in intent and asymmetric in the last few bits — while refusing a transpose that was actually missed.

impl Tensor

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

Elementwise negation.

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

Elementwise e^x.

pub fn ln(&self) -> Result<Tensor>

Elementwise natural logarithm.

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

Elementwise absolute value.

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

Elementwise square root.

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

Elementwise sine.

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

Elementwise cosine.

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

Elementwise hyperbolic tangent.

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

Elementwise rectified linear unit.

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

Elementwise GELU (tanh approximation).

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

Elementwise logistic sigmoid.

pub fn scalar_on(like: &Tensor, value: f32) -> Result<Tensor>

A scalar constant with the dtype and device of like (plumbing for VJPs and scalar operator overloads).

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

This tensor’s elements converted to dtype (F32 ↔ F64, or I64 → float). A no-op clone for the same dtype. CPU only for F64; differentiable (the gradient converts back).

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

Elementwise addition, broadcasting.

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

Elementwise subtraction, broadcasting.

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

Elementwise multiplication, broadcasting.

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

Elementwise division, broadcasting.

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

Elementwise power, broadcasting.

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

Elementwise maximum, broadcasting.

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

Elementwise minimum, broadcasting.

pub fn gt_mask(&self, rhs: &Tensor) -> Result<Tensor>

Elementwise a > b as a 0.0/1.0 mask. Not differentiable.

pub fn eq_mask(&self, rhs: &Tensor) -> Result<Tensor>

Elementwise a == b as a 0.0/1.0 mask. Not differentiable.

pub fn add_scalar(&self, s: f32) -> Result<Tensor>

Add a scalar, broadcasting.

pub fn mul_scalar(&self, s: f32) -> Result<Tensor>

Multiply by a scalar, broadcasting.

pub fn matmul(&self, rhs: &Tensor) -> Result<Tensor>

Matrix product with NumPy/PyTorch batch semantics.

The last two dimensions are the matrix ([.., m, k] x [.., k, n] → [.., m, n]); every leading dimension is a batch dimension, and batch dimensions broadcast against each other (1 against b, and a missing leading dimension counts as 1). A rank-2 operand is one matrix for every batch of the other. The result is rank 2 only when both operands are: [2, 2, 3] x [1, 3, 2] is [2, 2, 2], [m, k] x [b, k, n] is [b, m, n], [2, 1, 3, 4] x [5, 4, 6] is [2, 5, 3, 6].

Backends implement the rank-2/rank-3 contract of plan_matmul; higher ranks are lowered here — the batch dimensions are broadcast (a zero-stride view, materialized only when an operand’s batch really has to be repeated), flattened to one batch axis, multiplied, and unflattened — and every step is a recorded op, so the gradient needs no VJP of its own.

pub fn sum(&self, axes: &[usize]) -> Result<Tensor>

Sum over axes (empty means all), removing them from the shape.

pub fn sum_keepdim(&self, axes: &[usize], keepdim: bool) -> Result<Tensor>

Sum over axes with explicit keepdim.

pub fn max(&self, axes: &[usize]) -> Result<Tensor>

Maximum over axes (empty means all).

pub fn max_keepdim(&self, axes: &[usize], keepdim: bool) -> Result<Tensor>

Maximum over axes with explicit keepdim.

pub fn min(&self, axes: &[usize]) -> Result<Tensor>

Minimum over axes (empty means all).

pub fn mean(&self, axes: &[usize]) -> Result<Tensor>

Mean over axes (empty means all) — composite, so its gradient flows through sum and scalar multiply.

Reducing over a zero-length extent is a typed error; see Tensor::mean_keepdim.

pub fn mean_keepdim(&self, axes: &[usize], keepdim: bool) -> Result<Tensor>

Mean over axes with explicit keepdim.

Errors

Reducing over a zero-length extent is an Error::InvalidArgument: the mean of nothing is 0/0, and there is no value that is the right answer.

Until 0.4.0 this returned NaN, which is not an answer either but looks like one. A NaN from an empty last batch does not fail — it flows into the loss, then into every gradient, and surfaces an epoch later as a model that stopped learning for no visible reason. argmax already refused the same input for the same reason; this is the pair being made consistent.

sum and max still return their identities (0 and -inf) over an empty extent, and deliberately: those compose correctly under further reduction, and mean does not. The whole family is tabulated in docs/LIMITATIONS.md.

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

Index of the maximum along dim, as an I64 tensor. Not differentiable.

pub fn softmax(&self, dim: usize) -> Result<Tensor>

Numerically stable softmax along dim — composite.

pub fn log_softmax(&self, dim: usize) -> Result<Tensor>

Numerically stable log-softmax along dim — composite.

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

Rows of self along dim selected by indices (I64, on the CPU).

pub fn index_add( &self, dim: usize, indices: &Tensor, src: &Tensor, ) -> Result<Tensor>

out[indices[i]] += src[i] along dim, on a fresh copy of self. indices is I64 on the CPU; src lives on self’s device.

pub fn to_device(&self, device: Device) -> Result<Tensor>

This tensor’s data on device (a cheap clone when already there). F64 tensors are CPU-only: moving one to a GPU is a typed error.

impl Tensor

pub fn from_storage(storage: Arc<Storage>, layout: Layout) -> Result<Self>

A tensor over existing storage with an explicit layout.

Errors when the layout addresses elements outside the storage.

pub fn from_vec_f32(data: Vec<f32>, shape: impl Into<Shape>) -> Result<Self>

A contiguous CPU tensor holding data with shape shape.

Errors when data.len() does not equal shape.numel().

pub fn from_slice(data: &[f32], shape: impl Into<Shape>) -> Result<Self>

A contiguous CPU tensor copying data with shape shape.

pub fn from_vec_f64(data: Vec<f64>, shape: impl Into<Shape>) -> Result<Self>

A contiguous CPU F64 tensor holding data. f64 tensors live on the CPU (the GPU backends carry f32); every op the CPU backend implements accepts them, and Tensor::to_dtype converts.

pub fn from_vec_i64(data: Vec<i64>, shape: impl Into<Shape>) -> Result<Self>

A contiguous CPU I64 tensor holding data (indices, targets).

pub fn zeros(shape: impl Into<Shape>) -> Self

A CPU tensor of zeros.

Panics

Panics if the shape’s element count overflows usize. Build the shape from untrusted input through Tensor::try_zeros for a typed error instead.

pub fn try_zeros(shape: impl Into<Shape>) -> Result<Self>

A CPU tensor of zeros, or Error::InvalidArgument when the shape’s element count overflows usize.

pub fn ones(shape: impl Into<Shape>) -> Self

A CPU tensor of ones.

Panics

Panics if the shape’s element count overflows usize; see Tensor::try_ones.

pub fn try_ones(shape: impl Into<Shape>) -> Result<Self>

A CPU tensor of ones, or Error::InvalidArgument when the shape’s element count overflows usize.

pub fn full(shape: impl Into<Shape>, value: f32) -> Self

A CPU tensor filled with value.

Panics

Panics if the shape’s element count overflows usize; see Tensor::try_full.

pub fn try_full(shape: impl Into<Shape>, value: f32) -> Result<Self>

A CPU tensor filled with value, or Error::InvalidArgument when the shape’s element count overflows usize.

pub fn scalar(value: f32) -> Self

A rank-0 scalar tensor.

pub fn randn(shape: impl Into<Shape>) -> Self

Standard-normal random CPU tensor, seeded from the OS.

pub fn randn_with_seed(shape: impl Into<Shape>, seed: u64) -> Self

Standard-normal random CPU tensor with a fixed seed, for reproducible tests and examples.

pub fn shape(&self) -> &Shape

The shape of this view.

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

The dimension extents, outermost first.

pub fn ndim(&self) -> usize

The rank (number of dimensions).

pub fn numel(&self) -> usize

The total number of elements.

pub fn layout(&self) -> &Layout

The full layout of this view.

pub fn dtype(&self) -> DType

The element type.

pub fn device(&self) -> Device

The device the storage lives on.

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

The shared storage behind this view.

pub fn get_f32(&self, index: &[usize]) -> Result<f32>

The element at a logical index, as f32.

Errors on rank mismatch, out-of-bounds, non-float dtype, or non-CPU storage.

pub fn get_f64(&self, index: &[usize]) -> Result<f64>

The element at a logical index, as f64 (from an F64 tensor).

pub fn get_i64(&self, index: &[usize]) -> Result<i64>

The element at a logical index, as i64.

pub fn to_vec_f32(&self) -> Result<Vec<f32>>

Every element in logical (row-major) order, as f32, from CPU storage.

pub fn to_vec_f64(&self) -> Result<Vec<f64>>

Every element in logical (row-major) order, as f64, from an F64 CPU tensor (use Tensor::to_dtype first for an f32 one).

pub fn to_vec_i64(&self) -> Result<Vec<i64>>

Every element in logical (row-major) order, as i64.

pub fn reshape(&self, shape: impl Into<Shape>) -> Result<Self>

A view (or copy, when this view is not contiguous) with the same elements in a new shape.

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

A view with dimensions reordered by perm (a permutation of 0..ndim).

pub fn transpose(&self, d0: usize, d1: usize) -> Result<Self>

A view with dimensions d0 and d1 swapped.

pub fn t(&self) -> Result<Self>

The matrix transpose: the last two dimensions swapped.

pub fn narrow(&self, dim: usize, start: usize, len: usize) -> Result<Self>

A view of len elements of dimension dim starting at start.

pub fn slice(&self, dim: usize, range: Range<usize>) -> Result<Self>

A view of range along dim — sugar over Tensor::narrow.

pub fn broadcast_to(&self, shape: impl Into<Shape>) -> Result<Self>

A zero-copy broadcast view to shape (stride 0 on expanded axes).

pub fn broadcast_view(&self, shape: &Shape) -> Result<Self>

A broadcast view that records nothing on the tape — backend plumbing; prefer Tensor::broadcast_to in user code.

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

A view with a new size-1 dimension inserted at dim.

pub fn contiguous(&self) -> Result<Self>

This tensor’s elements, in logical order, in fresh contiguous storage on the same device. A no-op clone when already contiguous.

pub fn contiguous_untracked(&self) -> Result<Self>

The contiguous copy without autograd recording — backend plumbing; prefer Tensor::contiguous in user code.

pub fn requires_grad_(self, requires: bool) -> Self

Mark (or unmark) this tensor as a gradient-accumulating leaf, in place, returning it for chaining.

pub fn requires_grad(&self) -> bool

Whether gradients accumulate on this tensor during backward — true for leaves marked with requires_grad_.

This answers a narrower question than PyTorch’s requires_grad: a tensor computed from such a leaf is on the tape but does not accumulate a gradient of its own, so it reports false here. Ask is_tracked for “is this on the graph at all”.

pub fn is_tracked(&self) -> bool

Whether this tensor participates in the autograd tape at all — true for a leaf that requires grad and for anything computed from one while recording was enabled; false for constants and for everything produced under no_grad.

This is the predicate that observes no_grad:

use oxmera_tensor::tensor::Tensor;
use oxmera_tensor::autograd::no_grad;

let a = Tensor::from_slice(&[1.0, 2.0], [2]).unwrap().requires_grad_(true);
assert!(a.mul_scalar(3.0).unwrap().is_tracked());
assert!(!no_grad(|| a.mul_scalar(3.0).unwrap()).is_tracked());

pub fn grad(&self) -> Option<Tensor>

The accumulated gradient, if a backward pass has produced one.

pub fn zero_grad(&self)

Clear this tensor’s accumulated gradient.

pub fn detach(&self) -> Self

The same view without any tape connection.

pub fn backward(&self) -> Result<()>

Propagate gradients from this scalar through the recorded tape.

Errors when the tensor is not a scalar; use Tensor::backward_with to seed a non-scalar output.

pub fn backward_with(&self, seed: Tensor) -> Result<()>

Propagate gradients seeding this tensor’s gradient with seed.

Trait Implementations

impl Add for Tensor

type Output = Tensor

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<&Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<&Tensor> for Tensor

type Output = Tensor

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<&Tensor> for f32

type Output = Tensor

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Tensor> for f32

type Output = Tensor

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<f32> for &Tensor

type Output = Tensor

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<f32> for Tensor

type Output = Tensor

The resulting type after applying the + operator.

fn add(self, rhs: f32) -> 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

Prints only the tensor’s metadata — shape, dtype, device and whether it tracks gradients. Never the storage contents: a tensor can hold gigabytes, and a derived Debug dumped all of it into every log line and panic message.

impl Div for Tensor

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<&Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<&Tensor> for Tensor

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<&Tensor> for f32

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<Tensor> for f32

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<f32> for &Tensor

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<f32> for Tensor

type Output = Tensor

The resulting type after applying the / operator.

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

Performs the / operation.

impl Mul for Tensor

type Output = Tensor

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<&Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<&Tensor> for Tensor

type Output = Tensor

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<&Tensor> for f32

type Output = Tensor

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<Tensor> for f32

type Output = Tensor

The resulting type after applying the * operator.

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

Performs the * operation.

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<f32> for Tensor

type Output = Tensor

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> 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 Sub for Tensor

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<&Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<&Tensor> for Tensor

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<&Tensor> for f32

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Tensor> for &Tensor

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Tensor> for f32

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<f32> for &Tensor

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<f32> for Tensor

type Output = Tensor

The resulting type after applying the - operator.

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

Performs the - operation.