Struct Tensor 

pub struct Tensor<Element> { /* private fields */ }

A dense tensor with an immutable, runtime-defined Shape and a shared element buffer read through a strided layout.

The elements are held behind a Storage representation: an Arc-shared row-major buffer addressed by strides and an offset, or a non-allocating constant. Cloning shares the buffer and clones only the metadata; it does not clone the elements. Because tensors are immutable and buffer-shared, view operations that alias a buffer (transpose and broadcast) are always safe: no operation ever writes through an alias.

Arithmetic and the elementwise maps operate in logical row-major order. Binary elementwise operations require identical shapes and never broadcast implicitly. Broadcasting is available only through broadcast_like and broadcast_along, and it produces a view rather than copying.

matmul requires rank-2 or batched higher-rank operands, and transpose accepts ranks 0 through 2, returning a view. Reductions, explicit broadcasts, and reshaping are rank-general.

Implementations

impl<Element> Tensor<Element>

pub fn shape(&self) -> Shape

Returns the shape of this tensor: its extent along every axis.

It is what record-time shape inference seeds leaves with. A scalar is rank 0.

pub fn as_slice(&self) -> Option<&[Element]>

Returns the elements as a contiguous slice when the tensor is stored as a contiguous dense buffer, or None for a strided view or a constant.

impl<Element: Clone> Tensor<Element>

pub fn iter(&self) -> impl Iterator<Item = Element> + '_

Returns the elements in logical row-major order.

A contiguous dense buffer iterates its slice directly; a strided view walks its layout with an odometer; a constant repeats its single value across the shape’s volume.

It yields owned elements rather than references because a representation that computes its elements has nothing to lend, and for the numeric payloads a clone is the same load a borrow-then-copy compiles to.

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

Returns the elements in logical row-major order as an owned vector.

pub fn convert<Target: From<Element>>(&self) -> Tensor<Target>

Returns this tensor with every element converted into Target through its From conversion, preserving the storage representation: a constant stays a constant, a selection stays a selection, and a dense view keeps its layout, so a broadcast converts only its distinct buffer elements.

It is the precision boundary for mixed-precision work — loading an f32 checkpoint into a Tensor<Bf16> model, or widening bf16 results back — priced at one conversion per stored element.

pub fn scalar(&self) -> Element

Returns the rank-0 tensor’s single element: the scalar projection, and the read-back the teaching examples end on.

It is deliberately loud — one call, rank-checked — rather than a Deref to the element: a silent projection is the kind of magic the explicitness rule forbids. A rank-1 tensor of one element does not qualify; reshape it first.

Panics

Panics if this tensor is not rank 0.

impl<Element: Differentiable> Tensor<Element>

pub fn new(shape: impl Into<Shape>, elements: impl Into<Vec<Element>>) -> Self

Creates a tensor of shape from elements in row-major order.

Panics

Panics if the shape’s volume overflows usize, the number of elements differs from that volume, or the shape holds no elements. Empty tensors are unsupported because reductions initialize their accumulator from an existing element.

pub fn filled(shape: impl Into<Shape>, element: Element) -> Self

Creates a tensor of shape with every element set to element, stored as a non-allocating constant.

Panics

Panics if the shape’s volume overflows usize or the shape holds no elements, as documented on Tensor::new.

pub fn selection( indices: impl Into<Vec<usize>>, vocab: usize, one: Element, ) -> Self

Creates the one-hot [indices.len(), vocab] selection matrix whose row i is one at column indices[i] and zero elsewhere, stored as its indices rather than a dense buffer.

It carries the token indices of an embedding lookup: feed it as a per-run input and read it with Recordable::gather. one is the value placed at each selected position (the multiplicative identity, e.g. 1.0); the zero is derived from it.

Panics

Panics if vocab is zero, indices is empty, any index is not below vocab, or the [indices.len(), vocab] volume overflows usize.

impl<Element: Differentiable> Tensor<Element>

pub fn zero_like(&self) -> Self

Returns a zero shaped like self, stored as a constant: the seed of gradient accumulators.

pub fn one_like(&self) -> Self

Returns a one shaped like self, stored as a constant: the seed of the output gradient.

pub fn counted(shape: Shape, count: usize) -> Self

Returns the count spread across shape, stored as a constant; the element value comes from the element type’s own from_count.

It is the constructor behind size-derived constants: a composed formula that divides by an axis extent (a mean, a normalization) mints that extent here. Counts convert exactly as long as the element type can represent them.

Panics

Panics if the shape’s volume overflows usize or the shape holds no elements, as documented on Tensor::new.

pub fn is_counted(&self, shape: &Shape, count: usize) -> bool

Returns whether this tensor is exactly what counted mints for shape and count: the recognizer pattern matchers use to certify a recorded size-derived constant before raising a formula around it.

impl<Element: Elementary> Tensor<Element>

pub fn exp(&self) -> Self

Returns e raised to each element.

pub fn ln(&self) -> Self

Returns the natural logarithm of each element.

pub fn sqrt(&self) -> Self

Returns the square root of each element.

pub fn tanh(&self) -> Self

Returns the hyperbolic tangent of each element.

pub fn sin(&self) -> Self

Returns the sine of each element.

pub fn cos(&self) -> Self

Returns the cosine of each element.

pub fn log1p(&self) -> Self

Returns the natural logarithm of one plus each element, accurate near zero.

pub fn expm1(&self) -> Self

Returns e raised to each element, minus one, accurate near zero.

pub fn erf(&self) -> Self

Returns the error function of each element.

pub fn erf_derivative(&self) -> Self

Returns the derivative of the error function of each element: the scaled Gaussian (2/sqrt(pi)) * e^(-x^2).

pub fn powf(&self, exponent: Self) -> Self

Returns each element raised to the matching element of exponent.

Panics

Panics if the tensors have different shapes.

pub fn maximum(&self, other: &Self) -> Self

Returns the elementwise maximum of self and other.

Panics

Panics if the tensors have different shapes.

pub fn step(&self, threshold: &Self) -> Self

Returns the elementwise 0/1 indicator of self >= threshold: the Heaviside step, ties answering one.

Panics

Panics if the tensors have different shapes.

impl<Element: Elementary> Tensor<Element>

pub fn batch_normalized( &self, scale: &Self, shift: &Self, epsilon: &Self, ) -> (Self, Self, Self)

Returns the batch normalization through the payload seam: when every operand is a contiguous dense buffer the whole group is offered to the backend chain as one task, and the composed bitwise reference computes when the chain declines or an operand is a view or constant.

Panics

Panics if self is not rank 2 [batch, features], the affine operands do not hold features values, or epsilon holds more than one value.

pub fn max_pooled(&self, size: usize, stride: usize) -> Self

Returns the max pool through a direct window walk: each output element folds its window with maximum in the same row-major lane order as the recorded formula, so the walk is bit-identical to the composed fold while materializing no lane views. Non-contiguous inputs and non-dense storages take the composed reference path.

Panics

Panics if self is not rank 4, size or stride is zero, or a window does not fit the spatial extents.

pub fn matmul(&self, rhs: &Self) -> Self

Returns the matrix product of two rank-2 tensors.

Dense operands, including strided views (a transposed operand, most often), multiply on a slice path that reads their buffers through the layout strides directly; other storages read through logical access. Both paths accumulate every output element in the same order, so their results are bit-identical.

Panics

Panics if either operand is not rank 2, the inner dimensions do not agree, or any dimension is empty.

pub fn transpose(&self) -> Self

Returns the tensor with its two axes swapped as a view over the same buffer.

Rank-0 and rank-1 tensors are returned unchanged.

Panics

Panics if the tensor’s rank exceeds 2.

pub fn sum(&self) -> Self

Returns the sum of every element as a rank-0 constant.

Elements are accumulated in logical order from left to right without pairwise or compensated summation.

pub fn sum_along(&self, axis: usize) -> Self

Returns the tensor with axis reduced by summation.

The reduction is rank-general: the elements are viewed as [outer, axis, inner] in logical order and summed over the middle extent.

Panics

Panics if axis is out of rank.

pub fn max_along(&self, axis: usize) -> Self

Returns the tensor with axis reduced to its largest element by the elementwise Elementary::maximum.

The reduction is rank-general and mirrors Recordable::sum_along: the elements are viewed as [outer, axis, inner] in logical order and folded over the middle extent.

Panics

Panics if axis is out of rank.

pub fn broadcast(&self, shape: Shape) -> Self

Returns this tensor’s single element spread across shape as a constant: the whole-shape form of explicit broadcasting.

Panics

Panics if self holds more than one element.

pub fn broadcast_like(&self, reference: &Self) -> Self

Returns this tensor’s single element spread across reference’s shape: broadcast reading the reference for its shape alone.

Panics

Panics if self holds more than one element.

pub fn broadcast_along(&self, axis: usize, extent: usize) -> Self

Returns the tensor repeated along a new axis of extent inserted at axis, as a stride-0 view: the named-axis form of explicit broadcasting.

Panics

Panics if axis exceeds this tensor’s rank or extent is zero.

pub fn broadcast_along_like(&self, axis: usize, reference: &Self) -> Self

Returns the tensor repeated along axis to match reference’s shape: broadcast_along reading the reference for its shape alone.

Panics

Panics if axis is out of reference’s rank or self’s shape differs from reference’s with that axis removed.

pub fn reshape(&self, shape: Shape) -> Self

Returns self reinterpreted with shape in logical row-major order.

A contiguous dense tensor and a constant reshape into an O(1) view over the same buffer, and so does a strided view when only extent-1 axes are inserted or removed; any other strided reshape is first materialized.

Panics

Panics if shape’s volume differs from self’s.

pub fn permute(&self, order: &[usize]) -> Self

Returns self with its axes reordered by order as a view over the same buffer.

Panics

Panics if order is not a permutation of 0..rank.

pub fn narrow(&self, axis: usize, start: usize, len: usize) -> Self

Returns the window of len elements from start along axis as a view over the same buffer.

Panics

Panics if axis is out of rank, len is zero (tensors cannot be empty), or start + len overflows or exceeds the axis extent.

pub fn pad(&self, axis: usize, start: usize, full_extent: usize) -> Self

Returns self placed at start .. along axis inside a tensor whose axis has extent full_extent, with zeros elsewhere.

Panics

Panics if axis is out of rank or the window overflows or exceeds full_extent.

pub fn unfold( &self, axis: usize, size: usize, step: usize, dilation: usize, ) -> Self

Returns the sliding windows of self along axis as a strided view over the same buffer: the axis becomes a (count, size) pair where window w starts at w * step and takes every dilation-th element. Overlapping windows alias elements read-only, which immutability makes safe.

Panics

Panics if axis is out of rank, size, step, or dilation is zero, or the dilated window span dilation * (size - 1) + 1 overflows or exceeds the axis extent.

pub fn fold( &self, axis: usize, size: usize, step: usize, dilation: usize, extent: usize, ) -> Self

Returns the (count, size) window pair at axis, axis + 1 folded back onto an axis of extent: the adjoint of unfold and its gradient rule.

The accumulation is output-centric: each source position sums, in window order, the window elements that were read from it, so the result is deterministic under any evaluation strategy. Positions no window reaches fold to zero.

Panics

Panics if axis + 1 is out of rank, size, step, or dilation is zero, the dilated window span overflows or exceeds extent, or the shape at axis, axis + 1 disagrees with the windows unfold would produce for extent.

pub fn windowed_patches( &self, kernel_height: usize, kernel_width: usize, stride: usize, padding: usize, ) -> Self

Returns the im2col matrix through a specialized patch fill: contiguous runs of kernel_width copied per channel and kernel row, zero runs where the padding window leaves the input, and no per-element odometer arithmetic — the measured cost the fused window-GEMM pattern exists to remove. Non-contiguous inputs and non-dense storages take the composed reference path.

Panics

Panics if self is not rank 4, stride is zero, or a kernel window does not fit the padded extents.

pub fn gather(&self, selection: &Self) -> Self

Returns the rows of self selected by selection, a one-hot [count, vocab] whose vocabulary must equal self’s first axis; the result is [count, ...self.shape[1..]] with row i equal to self’s row selection_index(i).

Panics

Panics if selection is not a [count, vocab] selection, self has no axes, or the vocabulary does not match self’s first axis.

pub fn scatter(&self, selection: &Self) -> Self

Scatter-adds the rows of self (a [count, ...] gradient) into a zero payload with one row per entry of selection’s vocabulary, by its indices: the adjoint of gather and its gradient rule. Rows selected more than once accumulate.

impl<Element: Elementary> Tensor<Element>

pub fn windowed_product( &self, kernel: &Self, kernel_height: usize, kernel_width: usize, stride: usize, padding: usize, ) -> Self

Returns the im2col product of self with the GEMM-shaped kernel: the window rows of the padded, strided sliding windows, matrix-multiplied in one call. It is the fused executor behind the plan tier’s window-GEMM pattern; the composed reference is composed_windowed_patches followed by the plain product.

impl<E: Element + Emittable> Tensor<E>

where f64: From<E>,

pub fn to_html(&self, theme: Theme) -> String

Renders the tensor as a self-contained HTML card: shape, element type, and extremes, then the values — an exact table while they are few, a chart once they are many.

Rendering is pure and deterministic for a given tensor and theme.

pub fn evcxr_display(&self)

Displays the tensor when it is the last expression in an Evcxr cell.

Trait Implementations

impl<Element: Differentiable> Add for Tensor<Element>

type Output = Tensor<Element>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<'tape, E: Element> Add<Tensor<E>> for Value<'tape, E>

type Output = Value<'tape, E>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<'tape, E: Element> Add<Value<'tape, E>> for Tensor<E>

type Output = Value<'tape, E>

The resulting type after applying the + operator.

fn add(self, rhs: Value<'tape, E>) -> Self::Output

Performs the + operation.

impl<Element: Clone> Clone for Tensor<Element>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Element: Debug> Debug for Tensor<Element>

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

Formats the value using the given formatter.

impl<Element: Clone + Display> Display for Tensor<Element>

Renders rank 0 as the bare element and higher ranks as nested row-major bracket lists, so a scalar read prints as the number it is.

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

Formats the value using the given formatter.

impl<Element: Differentiable> Div for Tensor<Element>

type Output = Tensor<Element>

The resulting type after applying the / operator.

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

Performs the / operation.

impl<'tape, E: Element> Div<Tensor<E>> for Value<'tape, E>

type Output = Value<'tape, E>

The resulting type after applying the / operator.

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

Performs the / operation.

impl<'tape, E: Element> Div<Value<'tape, E>> for Tensor<E>

type Output = Value<'tape, E>

The resulting type after applying the / operator.

fn div(self, rhs: Value<'tape, E>) -> Self::Output

Performs the / operation.

impl<E: Element> From<E> for Tensor<E>

The rank-0 conversion: one element becomes the tensor of shape []. It is what lets tape.parameter(0.0_f64) and payload literals in operator position stay scalar-looking while the graph is always tensors. The bound is the Element seam marker rather than Differentiable so a tensor can never be mistaken for an element of a deeper tensor by inference.

fn from(element: E) -> Self

Converts to this type from the input type.

impl<Element: Differentiable> Mul for Tensor<Element>

type Output = Tensor<Element>

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'tape, E: Element> Mul<Tensor<E>> for Value<'tape, E>

type Output = Value<'tape, E>

The resulting type after applying the * operator.

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

Performs the * operation.

impl<'tape, E: Element> Mul<Value<'tape, E>> for Tensor<E>

type Output = Value<'tape, E>

The resulting type after applying the * operator.

fn mul(self, rhs: Value<'tape, E>) -> Self::Output

Performs the * operation.

impl<Element: Differentiable> Neg for Tensor<Element>

type Output = Tensor<Element>

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl<Element: PartialEq + Clone> PartialEq for Tensor<Element>

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

Compares two tensors by logical value: equal shapes and equal elements in logical order, independent of storage representation, so a view compares equal to its materialized twin.

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

Inequality operator !=.

impl<E: Element> Recordable for Tensor<E>

The compute interpretation of the recordable vocabulary: every rule operation is the inherent tensor method of the same name, so running a derivative rule over tensors is running it over the engine’s one payload.

fn shape(&self) -> Shape

Returns the shape of this value: its extent along every axis.

fn zero_like(&self) -> Self

Returns a zero shaped like self, seeding gradient accumulators.

fn one_like(&self) -> Self

Returns a one shaped like self, seeding the output gradient.

fn exp(&self) -> Self

Returns e raised elementwise to self.

fn ln(&self) -> Self

Returns the elementwise natural logarithm of self.

fn sqrt(&self) -> Self

Returns the elementwise square root of self.

fn tanh(&self) -> Self

Returns the elementwise hyperbolic tangent of self.

fn sin(&self) -> Self

Returns the elementwise sine of self.

fn cos(&self) -> Self

Returns the elementwise cosine of self.

fn log1p(&self) -> Self

Returns the elementwise natural logarithm of one plus self, accurate near zero.

fn expm1(&self) -> Self

Returns e raised elementwise to self, minus one, accurate near zero.

fn erf(&self) -> Self

Returns the elementwise error function of self.

fn erf_derivative(&self) -> Self

Returns the elementwise derivative of the error function of self: the scaled Gaussian (2/sqrt(pi)) * e^(-x^2), the operation erf’s derivative rule speaks.

fn powf(&self, exponent: Self) -> Self

Returns self raised elementwise to the power of exponent.

fn maximum(&self, other: &Self) -> Self

Returns the elementwise maximum of self and other.

fn step(&self, threshold: &Self) -> Self

Returns the elementwise 0/1 indicator of self >= threshold: the Heaviside step, ties answering one. It carries the derivative of the maximum family.

fn matmul(&self, rhs: &Self) -> Self

Returns the matrix product of self and rhs; ranks above two multiply batched over identical leading axes.

fn sum(&self) -> Self

Returns the sum of every value in self, shaped as a single value.

fn sum_along(&self, axis: usize) -> Self

Returns self with axis reduced by summation.

fn broadcast(&self, shape: Shape) -> Self

Returns this value’s single element spread across shape.

fn broadcast_along(&self, axis: usize, extent: usize) -> Self

Returns self repeated along a new axis of extent inserted at axis.

fn reshape(&self, shape: Shape) -> Self

Returns self reinterpreted with shape, preserving logical row-major order.

fn permute(&self, order: &[usize]) -> Self

Returns self with its axes reordered so that axis i of the result takes axis order[i] of self.

fn narrow(&self, axis: usize, start: usize, len: usize) -> Self

Returns the window of len elements from start along axis.

fn pad(&self, axis: usize, start: usize, full_extent: usize) -> Self

Returns self placed into zeros whose axis has extent full_extent, at start ..: the adjoint of narrow.

fn unfold(&self, axis: usize, size: usize, step: usize, dilation: usize) -> Self

Returns the sliding windows of self along axis: the axis becomes a (count, size) pair.

fn fold( &self, axis: usize, size: usize, step: usize, dilation: usize, extent: usize, ) -> Self

Returns the (count, size) window pair at axis, axis + 1 folded back onto an axis of extent: the adjoint of unfold.

fn gather(&self, selection: &Self) -> Self

Returns the rows of self selected by the one-hot selection.

fn scatter(&self, selection: &Self) -> Self

Scatter-adds the rows of self into one row per entry of selection’s vocabulary, by its indices: the adjoint of gather.

impl<Element: Differentiable> Sub for Tensor<Element>

type Output = Tensor<Element>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<'tape, E: Element> Sub<Tensor<E>> for Value<'tape, E>

type Output = Value<'tape, E>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<'tape, E: Element> Sub<Value<'tape, E>> for Tensor<E>

type Output = Value<'tape, E>

The resulting type after applying the - operator.

fn sub(self, rhs: Value<'tape, E>) -> Self::Output

Performs the - operation.