Struct Tensor 

pub struct Tensor<'a, T: TensorDataType> { /* private fields */ }

Implementations

impl<'a, T: TensorDataType> Tensor<'a, T>

pub fn value(&self) -> T

Retrieves the single value contained within a tensor with a singular element.

Panics

If the tensor contains more than one element (i.e., it is not a scalar or a tensor with a single element)

Example

let tensor = Tensor::scalar(50.0);
let value = tensor.value();
assert_eq!(value, 50.0);

Notes

This function is only meant for arrays that are guaranteed to have exactly one element. For arrays with multiple elements, consider using appropriate methods to access individual elements or slices safely.

pub fn ndarray(&self) -> &NdArray<'a, T>

Returns a reference to the underlying NdArray of the tensor

pub fn get_ndarray(&self) -> Rc<NdArray<'static, T>>

Returns a reference-counted pointer to the underlying NdArray of the tensor

pub fn into_ndarray(self) -> NdArray<'static, T>

Converts the tensor to an NdArray

impl<'a, T: TensorDataType> Tensor<'a, T>

pub fn is_leaf(&self) -> bool

Checks if the tensor is a leaf.

A tensor is considered a leaf node if requires_grad = true and it was explicitly created by the user, or if requires_grad = false.

Examples

let mut tensor = Tensor::new([1.0, 2.0, 3.0]);
tensor.set_requires_grad(true);
assert!(tensor.is_leaf());

let tensor2 = -tensor;
assert!(!tensor2.is_leaf());

pub fn requires_grad(&self) -> bool

Returns whether gradients must be computed for this tensor.

A tensor is marked with the requires_grad flag if it was explicitly specified by the user through the set_requires_grad() method or if the tensor was created using operations on other tensors which were marked requires_grad.

Examples

let mut tensor = Tensor::new([1.0, 2.0, 3.0]);
tensor.set_requires_grad(true);

let tensor2 = -tensor;
assert!(tensor2.requires_grad());

pub fn set_requires_grad(&mut self, requires_grad: bool) -> &mut Self

Sets whether gradients must be computed for this tensor.

pub fn gradient(&'a self) -> Option<NdArray<'a, T>>

Returns the gradient of the differentiated tensor with respect to self.

This method returns a view into the gradient.

Examples

let mut a = Tensor::scalar(2.0f32);
let b = Tensor::scalar(3.0);

a.set_requires_grad(true);

let c = &a * &b;
c.backward();

// dc/da = b
assert_eq!(a.gradient().unwrap(), b);

pub fn zero_gradient(&self)

Sets the gradient of this tensor to zero.

Examples

let mut a = Tensor::scalar(2.0f32);
let b = Tensor::scalar(3.0);

a.set_requires_grad(true);

let c = &a * &b;
c.backward();

a.zero_gradient();
assert_eq!(a.gradient().unwrap(), Tensor::scalar(0.0));

pub fn backward_with(&self, gradient: impl AsRef<NdArray<'a, T>>)

Computes the gradient of the self with respect to its leaf tensors.

Parameters

• gradient: the gradient of the tensor being differentiated with respect to self.

Examples

let mut a = Tensor::full(2.0, [3]);  // [2, 2, 2]
let b = Tensor::new([3.0, 1.0, -1.0]);

a.set_requires_grad(true);

let c = &a * &b;
c.backward_with(NdArray::new([2.0, 1.0, 1.0]));

// dc/da = b
assert_eq!(a.gradient().unwrap(), Tensor::new([6.0, 1.0, -1.0]));

pub fn backward(&self)

Computes the gradient of the self with respect to its leaf tensors.

Examples

let mut a = Tensor::full(2.0, [3]);  // [2, 2, 2]
let b = Tensor::new([3.0, 1.0, -1.0]);

a.set_requires_grad(true);

let c = &a * &b;
c.backward();

// dc/da = b
assert_eq!(a.gradient().unwrap(), Tensor::new([3.0, 1.0, -1.0]));

pub fn detach(&self) -> NdArray<'static, T>

Detaches the tensor from the computation graph and returns an NdArray.

Examples

let mut a = Tensor::full(2.0, [3]);
a.set_requires_grad(true);

let c = &a * 5.0;

let d = c.detach();
assert_eq!(d, NdArray::new([10.0, 10.0, 10.0]));

impl<'a, T: TensorDataType> Tensor<'a, T>

pub fn dot<'b, 'r>(&self, other: impl AsRef<Tensor<'b, T>>) -> Tensor<'r, T>

Calculates the dot product of two 1D tensors.

Panics

• Panics if either tensor is not 1D
• Panics if the lengths of the two tensors are not equal

Examples

let tensor1 = Tensor::new([1.0, 2.0, 3.0]);
let tensor2 = Tensor::new([4.0, 5.0, 6.0]);
let result = tensor1.dot(tensor2);
assert_eq!(result.value(), 32.0); // 1*4 + 2*5 + 3*6 = 32

pub fn matmul<'r>(&self, other: impl AsRef<Tensor<'a, T>>) -> Tensor<'r, T>

Calculates the matrix product of two tensors.

• If both tensors are 1D, then their dot product is returned.
• If both tensors are 2D, then their matrix product is returned.
• If the first tensor is 2D and the second tensor is 1D, then the matrix-vector product is returned.

Panics

• If the dimensions/shape of the tensors are incompatible

Example

let a = Tensor::new(vec![
    [1.0, 2.0, 3.0],
    [4.0, 5.0, 6.0],
]);

let b = Tensor::new(vec![
    [7.0, 8.0],
    [9.0, 10.0],
    [11.0, 12.0],
]);

let result = a.matmul(&b);
assert_eq!(result, Tensor::new([
    [58.0, 64.0],
    [139.0, 154.0],
]));

pub fn bmm<'r>(&self, other: impl AsRef<Tensor<'a, T>>) -> Tensor<'r, T>

Performs batch matrix multiplication on 3D tensors.

The shape of the resulting ndarray will be [batch_size, self.shape()[1], other.shape()[2]], where batch_size is the shared first dimension of both input tensors.

Panics

• If either tensor is not 3D
• If the tensors do not have dimensions compatible for batch matrix multiplication.

Example

let arr1 = Tensor::<f32>::rand([3, 2, 4]); // 3 batches of 2x4 matrices
let arr2 = Tensor::<f32>::rand([3, 4, 5]); // 3 batches of 4x5 matrices
let result = arr1.bmm(&arr2);
assert_eq!(result.shape(), [3, 2, 5]); // result is 3 batches of 2x5 matrices

Trait Implementations

impl<T: TensorDataType> Add<&Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the + operator.

fn add(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the + operation.

impl<T: TensorDataType> Add<&Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the + operator.

fn add(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the + operation.

impl<T: TensorDataType> Add<T> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<T: TensorDataType> Add<T> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<T: TensorDataType> Add<Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the + operator.

fn add(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the + operation.

impl<T: TensorDataType> Add<Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the + operator.

fn add(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the + operation.

impl<'a, T: TensorDataType> AsRef<Tensor<'a, T>> for Tensor<'a, T>

fn as_ref(&self) -> &Tensor<'a, T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'a, T: TensorDataType> Constructors<T> for Tensor<'a, T>

unsafe fn from_contiguous_owned_buffer(shape: Vec<usize>, data: Vec<T>) -> Self

Constructs a new ndarray from the given data buffer and shape assuming a contiguous layout

fn new<const D: usize>(data: impl Flatten<T> + Shape + Nested<D>) -> Self

Constructs an n-dimensional NdArray from input data such as a vector or array.

fn full(n: T, shape: impl ToVec<usize>) -> Self

Creates an ndarray filled with a specified value and given shape.

fn zeros(shape: impl ToVec<usize>) -> Self

where T: From<bool>,

Creates a new ndarray filled with zeros with the given shape.

fn ones(shape: impl ToVec<usize>) -> Self

where T: From<bool>,

Creates a new ndarray filled with ones with the given shape.

fn scalar(n: T) -> Self

Creates a 0-dimensional (shapeless) ndarray containing a single value.

fn arange(start: T, stop: T) -> Self

where T: NumericDataType,

Generates a 1D ndarray with evenly spaced values within a specified range.

fn arange_with_step(start: T, stop: T, step: T) -> Self

where T: NumericDataType,

Generates a 1D ndarray with evenly spaced values within a specified range.

fn linspace(start: T, stop: T, num: usize) -> Self

where T: FloatDataType,

Generates a 1-dimensional ndarray with num evenly spaced values between start and stop (inclusive).

fn linspace_exclusive(start: T, stop: T, num: usize) -> Self

where T: FloatDataType,

Generates a 1-dimensional ndarray with num evenly spaced values between start and stop (exclusive).

impl<T: TensorDataType> Debug for Tensor<'_, T>

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

Formats the value using the given formatter.

impl<T: TensorDataType> Div<&Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the / operator.

fn div(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the / operation.

impl<T: TensorDataType> Div<&Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the / operator.

fn div(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the / operation.

impl<T: TensorDataType> Div<T> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the / operator.

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

Performs the / operation.

impl<T: TensorDataType> Div<T> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the / operator.

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

Performs the / operation.

impl<T: TensorDataType> Div<Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the / operator.

fn div(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the / operation.

impl<T: TensorDataType> Div<Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the / operator.

fn div(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the / operation.

impl<T: TensorDataType> Mul<&Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the * operator.

fn mul(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the * operation.

impl<T: TensorDataType> Mul<&Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the * operator.

fn mul(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the * operation.

impl<T: TensorDataType> Mul<T> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the * operator.

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

Performs the * operation.

impl<T: TensorDataType> Mul<T> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the * operator.

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

Performs the * operation.

impl<T: TensorDataType> Mul<Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the * operator.

fn mul(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the * operation.

impl<T: TensorDataType> Mul<Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the * operator.

fn mul(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the * operation.

impl<T: TensorDataType> Neg for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T: TensorDataType> Neg for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T: TensorDataType> PartialEq<&Tensor<'_, T>> for NdArray<'_, T>

fn eq(&self, other: &&Tensor<'_, T>) -> 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<T: TensorDataType> PartialEq<NdArray<'_, T>> for Tensor<'_, T>

fn eq(&self, other: &NdArray<'_, T>) -> 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<T: TensorDataType> PartialEq<Tensor<'_, T>> for &NdArray<'_, T>

fn eq(&self, other: &Tensor<'_, T>) -> 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<T: TensorDataType> PartialEq<Tensor<'_, T>> for NdArray<'_, T>

fn eq(&self, other: &Tensor<'_, T>) -> 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<T: TensorDataType> PartialEq<Tensor<'_, T>> for Tensor<'_, T>

fn eq(&self, other: &Tensor<'_, T>) -> 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<'a, T: TensorDataType> RandomConstructors<T> for Tensor<'a, T>

fn randn(shape: impl ToVec<usize>) -> Self

where T: FloatDataType,

Samples an NdArray with the specified shape from a standard normal distribution (0 mean, unit standard deviation).

fn rand(shape: impl ToVec<usize>) -> Self

where T: FloatDataType,

Samples an NdArray with the specified shape with values uniformly distributed in [0, 1).

fn uniform(shape: impl ToVec<usize>, low: T, high: T) -> Self

where T: FloatDataType,

Samples an NdArray with the specified shape with values uniformly distributed in [low, high).

fn randint(shape: impl ToVec<usize>, low: T, high: T) -> Self

where T: NumericDataType,

Samples an NdArray with the specified shape with integer values uniformly distributed between low (inclusive) and high (exclusive).

impl<'a, T: TensorDataType> Reshape<T> for &'a Tensor<'a, T>

unsafe fn reshaped_view( self, shape: Vec<usize>, stride: Vec<usize>, ) -> Self::Output

Provides a non-owning view of the tensor with the specified shape and stride. The data pointed to by the view is shared with the original tensor.

Safety

• Ensure the memory layout referenced by shape, and stride is valid and owned by the original tensor.

fn view(self) -> Self::Output

Provides a non-owning view of the tensor that shares its data with the original tensor.

Example

let tensor = Tensor::new([1.0, 2.0, 3.0, 4.0]);
let view = (&tensor).view();
assert!(view.is_view())

fn transpose(self, axis1: impl AxisType, axis2: impl AxisType) -> Self::Output

Returns a transposed version of the tensor, swapping the specified axes.

Panics

• If axis1 or axis2 are out of bounds

Examples

let array = Tensor::new([[2.0, 3.0, 4.0], [10.0, 20.0, 30.0]]);

let transposed = array.transpose(0, 1);
assert_eq!(transposed, Tensor::new([[2.0, 10.0], [3.0, 20.0], [4.0, 30.0]]));

type Output = Tensor<'a, T>

fn reshape(self, new_shape: impl ToVec<usize>) -> Self::Output

Reshapes the ndarray into the specified shape.

fn squeeze(self) -> Self::Output

Removes all singleton dimensions (dimensions of size 1) from the ndarray’s shape.

fn unsqueeze(self, axis: impl AxisType) -> Self::Output

Adds a singleton dimension (dimensions of size 1) to the ndarray at the specified axis.

fn T(self) -> Self::Output

Transposes the array along the first 2 dimensions.

impl<T: TensorDataType> Reshape<T> for Tensor<'_, T>

unsafe fn reshaped_view( self, shape: Vec<usize>, stride: Vec<usize>, ) -> Self::Output

Provides a non-owning view of the tensor with the specified shape and stride. The data pointed to by the view is shared with the original tensor.

Safety

• Ensure the memory layout referenced by shape, and stride is valid and owned by the original tensor.

fn view(self) -> Self::Output

Provides a non-owning view of the tensor that shares its data with the original tensor.

Example

let tensor = Tensor::new([1.0, 2.0, 3.0, 4.0]);
let view = (&tensor).view();
assert!(view.is_view())

fn transpose(self, axis1: impl AxisType, axis2: impl AxisType) -> Self::Output

Returns a transposed version of the tensor, swapping the specified axes.

Panics

• If axis1 or axis2 are out of bounds

Examples

let array = Tensor::new([[2.0, 3.0, 4.0], [10.0, 20.0, 30.0]]);

let transposed = array.transpose(0, 1);
assert_eq!(transposed, Tensor::new([[2.0, 10.0], [3.0, 20.0], [4.0, 30.0]]));

type Output = Tensor<'static, T>

fn reshape(self, new_shape: impl ToVec<usize>) -> Self::Output

Reshapes the ndarray into the specified shape.

fn squeeze(self) -> Self::Output

Removes all singleton dimensions (dimensions of size 1) from the ndarray’s shape.

fn unsqueeze(self, axis: impl AxisType) -> Self::Output

Adds a singleton dimension (dimensions of size 1) to the ndarray at the specified axis.

fn T(self) -> Self::Output

Transposes the array along the first 2 dimensions.

impl<T: TensorDataType> StridedMemory for &Tensor<'_, T>

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

Returns the dimensions of the tensor along each axis.

let a = Tensor::new([3.0, 4.0, 5.0]);
assert_eq!(a.shape(), &[3]);

let b = Tensor::new([[3.0], [5.0]]);
assert_eq!(b.shape(), &[2, 1]);

let c = Tensor::scalar(0.0);
assert_eq!(c.shape(), &[]);

fn stride(&self) -> &[usize]

Returns the stride of the tensor.

The stride represents the distance in memory between elements in a tensor along each axis.

let a = Tensor::new([[3.0, 4.0], [5.0, 6.0]]);
assert_eq!(a.stride(), &[2, 1]);

fn flags(&self) -> NdArrayFlags

Returns flags containing information about various tensor metadata.

fn ndims(&self) -> usize

Returns the number of dimensions in the ndarray.

fn len(&self) -> usize

Returns the length along the first dimension of the ndarray. If the ndarray is a scalar, this returns 0.

fn size(&self) -> usize

Returns the total number of elements in the ndarray.

fn is_contiguous(&self) -> bool

Returns whether this ndarray is stored contiguously in memory.

fn is_view(&self) -> bool

Returns whether this ndarray is slice of another ndarray.

fn is_uniformly_strided(&self) -> bool

Whether the elements of this ndarray are stored in memory with a uniform distance between them.

fn has_uniform_stride(&self) -> Option<usize>

If the elements of this ndarray are stored in memory with a uniform distance between them, returns this distance.

impl<'a, T: TensorDataType> StridedMemory for Tensor<'a, T>

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

Returns the dimensions of the tensor along each axis.

let a = Tensor::new([3.0, 4.0, 5.0]);
assert_eq!(a.shape(), &[3]);

let b = Tensor::new([[3.0], [5.0]]);
assert_eq!(b.shape(), &[2, 1]);

let c = Tensor::scalar(0.0);
assert_eq!(c.shape(), &[]);

fn stride(&self) -> &[usize]

Returns the stride of the tensor.

The stride represents the distance in memory between elements in a tensor along each axis.

let a = Tensor::new([[3.0, 4.0], [5.0, 6.0]]);
assert_eq!(a.stride(), &[2, 1]);

fn flags(&self) -> NdArrayFlags

Returns flags containing information about various tensor metadata.

fn ndims(&self) -> usize

Returns the number of dimensions in the ndarray.

fn len(&self) -> usize

Returns the length along the first dimension of the ndarray. If the ndarray is a scalar, this returns 0.

fn size(&self) -> usize

Returns the total number of elements in the ndarray.

fn is_contiguous(&self) -> bool

Returns whether this ndarray is stored contiguously in memory.

fn is_view(&self) -> bool

Returns whether this ndarray is slice of another ndarray.

fn is_uniformly_strided(&self) -> bool

Whether the elements of this ndarray are stored in memory with a uniform distance between them.

fn has_uniform_stride(&self) -> Option<usize>

If the elements of this ndarray are stored in memory with a uniform distance between them, returns this distance.

impl<T: TensorDataType> Sub<&Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

fn sub(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the - operation.

impl<T: TensorDataType> Sub<&Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

fn sub(self, rhs: &Tensor<'_, T>) -> Self::Output

Performs the - operation.

impl<T: TensorDataType> Sub<T> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<T: TensorDataType> Sub<T> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<T: TensorDataType> Sub<Tensor<'_, T>> for &Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

fn sub(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the - operation.

impl<T: TensorDataType> Sub<Tensor<'_, T>> for Tensor<'_, T>

type Output = Tensor<'static, T>

The resulting type after applying the - operator.

fn sub(self, rhs: Tensor<'_, T>) -> Self::Output

Performs the - operation.