Struct Var

pub struct Var(/* private fields */);

A variable is a wrapper around a tensor, however variables can have their content modified whereas tensors are immutable.

Implementations

impl Var

pub fn zeros<S: Into<Shape>>( shape: S, dtype: DType, device: &Device, ) -> Result<Self>

pub fn ones<S: Into<Shape>>( shape: S, dtype: DType, device: &Device, ) -> Result<Self>

pub fn from_tensor(t: &Tensor) -> Result<Self>

pub fn rand_f64<S: Into<Shape>>( lo: f64, up: f64, s: S, dtype: DType, device: &Device, ) -> Result<Self>

pub fn randn_f64<S: Into<Shape>>( mean: f64, std: f64, s: S, dtype: DType, device: &Device, ) -> Result<Self>

pub fn rand<S: Into<Shape>, T: FloatDType>( lo: T, up: T, s: S, device: &Device, ) -> Result<Self>

pub fn randn<S: Into<Shape>, T: FloatDType>( mean: T, std: T, s: S, device: &Device, ) -> Result<Self>

pub fn new<A: NdArray>(array: A, device: &Device) -> Result<Self>

Creates a new tensor on the specified device using the content and shape of the input. This is similar to new but the resulting tensor is a variable.

pub fn from_vec<S: Into<Shape>, D: WithDType>( data: Vec<D>, shape: S, device: &Device, ) -> Result<Self>

pub fn from_slice<S: Into<Shape>, D: WithDType>( array: &[D], shape: S, device: &Device, ) -> Result<Self>

pub fn as_detached_tensor(&self) -> Tensor

pub fn as_tensor(&self) -> &Tensor

pub fn into_inner(self) -> Tensor

Consumes this Var and return the underlying tensor.

pub fn set(&self, src: &Tensor) -> Result<()>

Sets the content of the inner tensor, this does not require a mutable reference as inner mutability is used.

Methods from Deref<Target = Tensor>

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

pub fn conv1d( &self, kernel: &Self, padding: usize, stride: usize, dilation: usize, groups: usize, ) -> Result<Self>

Applies a 1D convolution over the input tensor.

pub fn conv_transpose1d( &self, kernel: &Self, padding: usize, output_padding: usize, stride: usize, dilation: usize, groups: usize, ) -> Result<Self>

Applies a 1D transposed convolution over the input tensor.

pub fn conv2d( &self, kernel: &Self, padding: usize, stride: usize, dilation: usize, groups: usize, ) -> Result<Self>

Applies a 2D convolution over the input tensor.

pub fn conv_transpose2d( &self, kernel: &Self, padding: usize, output_padding: usize, stride: usize, dilation: usize, ) -> Result<Self>

Applies a 2D transposed convolution over the input tensor.

pub fn write_bytes<W: Write>(&self, f: &mut W) -> Result<()>

pub fn apply_op1_no_bwd<C: CustomOp1>(&self, c: &C) -> Result<Self>

Applies a unary custom op without backward support

pub fn apply_op2_no_bwd<C: CustomOp2>(&self, rhs: &Self, c: &C) -> Result<Self>

Applies a binary custom op without backward support

pub fn apply_op3_no_bwd<C: CustomOp3>( &self, t2: &Self, t3: &Self, c: &C, ) -> Result<Self>

Applies a ternary custom op without backward support

pub fn apply_op1_arc( &self, c: Arc<Box<dyn CustomOp1 + Send + Sync>>, ) -> Result<Self>

Applies a unary custom op.

pub fn apply_op1<C: 'static + CustomOp1 + Send + Sync>( &self, c: C, ) -> Result<Self>

pub fn apply_op2_arc( &self, rhs: &Self, c: Arc<Box<dyn CustomOp2 + Send + Sync>>, ) -> Result<Self>

Applies a binary custom op.

pub fn apply_op2<C: 'static + CustomOp2 + Send + Sync>( &self, r: &Self, c: C, ) -> Result<Self>

pub fn apply_op3_arc( &self, t2: &Self, t3: &Self, c: Arc<Box<dyn CustomOp3 + Send + Sync>>, ) -> Result<Self>

Applies a ternary custom op.

pub fn apply_op3<C: 'static + CustomOp3 + Send + Sync>( &self, t2: &Self, t3: &Self, c: C, ) -> Result<Self>

pub fn inplace_op1<C: InplaceOp1>(&self, c: &C) -> Result<()>

Applies a unary custom op in place.

pub fn inplace_op2<C: InplaceOp2>(&self, rhs: &Self, c: &C) -> Result<()>

Applies a unary custom op in place (for the first tensor).

pub fn inplace_op3<C: InplaceOp3>( &self, t2: &Self, t3: &Self, c: &C, ) -> Result<()>

Applies a ternary custom op in place (for the first tensor).

pub fn write_npy<T: AsRef<Path>>(&self, path: T) -> Result<()>

Writes a multi-dimensional array in the npy format.

pub fn save_safetensors<P: AsRef<Path>>( &self, name: &str, filename: P, ) -> Result<()>

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

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

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

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

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

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

pub fn arg_sort_last_dim(&self, asc: bool) -> Result<Tensor>

Returns the indices that sort the tensor along the last dimension.

If asc is true, sorting is in ascending order. Otherwise sorting is performed in descending order. The sort is unstable so there is no guarantees on the final order when it comes to ties.

pub fn sort_last_dim(&self, asc: bool) -> Result<(Tensor, Tensor)>

Sorts the tensor along the last dimension, returns the sorted tensor together with the sorted indexes.

If asc is true, sorting is in ascending order. Otherwise sorting is performed in descending order. The sort is unstable so there is no guarantees on the final order when it comes to ties.

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

Creates a new tensor filled with ones with same shape, dtype, and device as the other tensor.

use candle_core::{Tensor, DType, Device};
let a = Tensor::zeros((2, 3), DType::F32, &Device::Cpu)?;
let b = a.ones_like()?;
// b == a + 1

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

Creates a new tensor filled with ones with same shape, dtype, and device as the other tensor.

use candle_core::{Tensor, DType, Device};
let a = Tensor::zeros((2, 3), DType::F32, &Device::Cpu)?;
let b = a.zeros_like()?;
// b is on CPU f32.

pub fn rand_like(&self, lo: f64, up: f64) -> Result<Self>

pub fn randn_like(&self, mean: f64, stdev: f64) -> Result<Self>

pub fn track_op(&self) -> bool

Returns true if the computation graph should track this op, that is if it is a variable or if it has some variable as dependencies.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

pub fn round_to(&self, decimals: i32) -> Result<Self>

Round element of the input tensor to the nearest integer.

If the number of decimals is negative, it specifies the number of positions to the left of the decimal point.

pub fn to_scalar<S: WithDType>(&self) -> Result<S>

Retrieves the single scalar value hold in the tensor. If the tensor contains multiple dimensions, an error is returned instead.

pub fn to_vec0<S: WithDType>(&self) -> Result<S>

An alias for to_scalar.

pub fn repeat<S: Into<Shape>>(&self, shape: S) -> Result<Tensor>

Repeat this tensor along the specified dimensions.

pub fn affine(&self, mul: f64, add: f64) -> Result<Self>

This operation multiplies the input tensor by mul then adds add and return the result. The input values mul and add are casted to the appropriate type so some rounding might be performed.

use candle_core::{Tensor, Device};
let a = Tensor::new(&[[0f32, 1.], [2., 3.]], &Device::Cpu)?;
let a = a.affine(4., -2.)?;
assert_eq!(a.to_vec2::<f32>()?, &[[-2.0, 2.0], [6.0, 10.0]]);

pub fn elu(&self, alpha: f64) -> Result<Self>

Applies the Exponential Linear Unit (ELU) function on each element of the input tensor.

pub fn powf(&self, e: f64) -> Result<Self>

Raise the tensor to some float exponent e.

pub fn chunk<D: Dim>(&self, chunks: usize, dim: D) -> Result<Vec<Self>>

Split a tensor into the specified number of chunks, this may return less chunks than specified.

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

Returns a new tensor that is a narrowed version of the input, the dimension dim ranges from start to start + len.

use candle_core::{Tensor, Device};
let a = Tensor::new(&[
    [0f32, 1., 2.],
    [3.  , 4., 5.],
    [6.  , 7., 8.]
], &Device::Cpu)?;

let b = a.narrow(0, 1, 2)?;
assert_eq!(b.shape().dims(), &[2, 3]);
assert_eq!(b.to_vec2::<f32>()?, &[
    [3., 4., 5.],
    [6., 7., 8.]
]);

let c = a.narrow(1, 1, 1)?;
assert_eq!(c.shape().dims(), &[3, 1]);
assert_eq!(c.to_vec2::<f32>()?, &[
    [1.],
    [4.],
    [7.]
]);

pub fn roll<D>(&self, shift: i32, dim: D) -> Result<Self>

where D: Dim + Clone,

Roll the tensor input along the given dimension. Elements that are shifted beyond the last position are re-introduced at the first position.

let tensor = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let tensor = tensor.roll(1, 0)?;
assert_eq!(tensor.to_vec2::<f32>()?, &[[4., 5.], [0., 1.], [2., 3.]]);
let tensor = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let tensor = tensor.roll(-1, 0)?;
assert_eq!(tensor.to_vec2::<f32>()?, &[[2., 3.], [4., 5.], [0., 1.]]);

pub fn sum_keepdim<D: Dims>(&self, sum_dims: D) -> Result<Self>

Returns the sum of all elements in the input tensor. The sum is performed over all the input dimensions.

The resulting tensor has a shape that is similar to the shape of the input tensor, except that the number of elements for each dimension index in sum_dims is 1.

use candle_core::{Tensor, Device};
let a = Tensor::new(&[[0f32, 1.], [2., 3.]], &Device::Cpu)?;
let s = a.sum_keepdim(0)?;
assert_eq!(s.to_vec2::<f32>()?, &[[2., 4.]]);
let s = a.sum_keepdim(1)?;
assert_eq!(s.to_vec2::<f32>()?, &[[1.], [5.]]);
let s = a.sum_keepdim((0, 1))?;
assert_eq!(s.to_vec2::<f32>()?, &[[6.]]);

pub fn sum<D: Dims>(&self, sum_dims: D) -> Result<Self>

Returns the sum of all elements in the input tensor. The sum is performed over all the input dimensions and compared to sum_keepdim these dimensions are squeezed rather than kept.

pub fn mean_keepdim<D: Dims>(&self, mean_dims: D) -> Result<Self>

Returns the mean of all elements in the input tensor. The mean is performed over all the input dimensions.

The resulting tensor has a shape that is similar to the shape of the input tensor, except that the number of elements for each dimension index in mean_dims is 1.

use candle_core::{Tensor, Device};
let a = Tensor::new(&[[0f32, 1.], [2., 3.]], &Device::Cpu)?;
let s = a.mean_keepdim(0)?;
assert_eq!(s.to_vec2::<f32>()?, &[[1., 2.]]);
let s = a.mean_keepdim(1)?;
assert_eq!(s.to_vec2::<f32>()?, &[[0.5], [2.5]]);
let s = a.mean_keepdim((0, 1))?;
assert_eq!(s.to_vec2::<f32>()?, &[[1.5]]);

pub fn mean<D: Dims>(&self, mean_dims: D) -> Result<Self>

Returns the mean of all elements in the input tensor. The mean is performed over all the input dimensions and compared to mean_keepdim these dimensions are squeezed rather than kept.

pub fn var_keepdim<D: Dim>(&self, dim: D) -> Result<Self>

Returns the unbiased variance over the selected dimension.

pub fn var<D: Dim>(&self, dim: D) -> Result<Self>

Returns the unbiased variance over the selected dimension.

pub fn max_keepdim<D: Dim>(&self, dim: D) -> Result<Self>

Gathers the maximum value across the selected dimension. The resulting shape has the same number of dimensions as the original tensor and the select dimension has a single element.

pub fn max<D: Dim>(&self, dim: D) -> Result<Self>

Similar to max_keepdim but the target dimension is squeezed.

pub fn min_keepdim<D: Dim>(&self, dim: D) -> Result<Self>

Gathers the minimum value across the selected dimension. The resulting shape has the same number of dimensions as the original tensor and the select dimension has a single element.

pub fn min<D: Dim>(&self, dim: D) -> Result<Self>

Similar to min_keepdim but the target dimension is squeezed.

pub fn argmax_keepdim<D: Dim>(&self, dim: D) -> Result<Self>

pub fn argmax<D: Dim>(&self, dim: D) -> Result<Self>

Similar to argmax_keepdim but the target dimension is squeezed.

pub fn argmin_keepdim<D: Dim>(&self, dim: D) -> Result<Self>

pub fn argmin<D: Dim>(&self, dim: D) -> Result<Self>

Similar to argmin_keepdim but the target dimension is squeezed.

pub fn cmp<T: TensorOrScalar>(&self, rhs: T, op: CmpOp) -> Result<Self>

Element-wise comparison between two tensors, e.g. equality, greater than, … The actual comparison operation is specified by the op argument.

The returned tensor has the same shape as the original tensors and uses u8 elements.

pub fn eq<T: TensorOrScalar>(&self, rhs: T) -> Result<Self>

Element-wise equality.

pub fn ne<T: TensorOrScalar>(&self, rhs: T) -> Result<Self>

Element-wise non-equality.

pub fn lt<T: TensorOrScalar>(&self, rhs: T) -> Result<Self>

Element-wise comparison with lower-than, the returned tensor uses value 1 where self < rhs and 0 otherwise.

pub fn gt<T: TensorOrScalar>(&self, rhs: T) -> Result<Self>

Element-wise comparison with greater-than, the returned tensor uses value 1 where self > rhs and 0 otherwise.

pub fn ge<T: TensorOrScalar>(&self, rhs: T) -> Result<Self>

Element-wise comparison with greater-equal, the returned tensor uses value 1 where self >= rhs and 0 otherwise.

pub fn le<T: TensorOrScalar>(&self, rhs: T) -> Result<Self>

Element-wise comparison with lower-equal, the returned tensor uses value 1 where self <= rhs and 0 otherwise.

pub fn clamp<T1: TensorOrScalar, T2: TensorOrScalar>( &self, min: T1, max: T2, ) -> Result<Self>

Clamp the tensor values to be between min and max.

pub fn interpolate1d(&self, target_size: usize) -> Result<Self>

Interpolate the input tensor to the target_size size, taking the value of the nearest element.

The input tensor should have three dimensions, (batch, channels, l), the returned tensor also has three dimensions, (batch, channels, target_size).

pub fn upsample_nearest1d(&self, target_size: usize) -> Result<Self>

Alias for interpolate1d.

pub fn interpolate2d(&self, target_h: usize, target_w: usize) -> Result<Self>

Interpolate the input tensor to the (target_h, target_w) size, taking the value of the nearest element.

The input tensor should have four dimensions, (batch, channels, h, w), the returned tensor also has four dimensions, (batch, channels, target_h, target_w).

pub fn upsample_nearest2d( &self, target_h: usize, target_w: usize, ) -> Result<Self>

Alias for interpolate2d.

pub fn avg_pool2d<T: ToUsize2>(&self, sz: T) -> Result<Self>

2D average pooling over an input tensor with multiple channels.

The input tensor should have four dimensions, (batch, channels, h, w), the returned tensor also has four dimensions, (batch, channels, h', w'). The pooling is performed on the two last dimensions using a kernel of size sz. The returned element is the average value over the kernel window.

pub fn avg_pool2d_with_stride<T: ToUsize2>( &self, kernel_size: T, stride: T, ) -> Result<Self>

Same as avg_pool2d but with a stride that can be set to a value different from the kernel size.

pub fn max_pool2d<T: ToUsize2>(&self, sz: T) -> Result<Self>

2D max pooling over an input tensor with multiple channels.

The input tensor should have four dimensions, (batch, channels, h, w), the returned tensor also has four dimensions, (batch, channels, h', w'). The pooling is performed on the two last dimensions using a kernel of size sz, the returned element is the maximum value over the kernel window.

pub fn max_pool2d_with_stride<T: ToUsize2>( &self, kernel_size: T, stride: T, ) -> Result<Self>

Same as max_pool2d but with a stride that can be set to a value different from the kernel size.

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

Returns the matrix-multiplication of the input tensor with the other provided tensor.

Arguments

• self - A tensor with dimensions b1, b2, ..., bi, m, k.
• rhs - A tensor with dimensions b1, b2, ..., bi, k, n.

The resulting tensor has dimensions b1, b2, ..., bi, m, n.

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

Matrix-multiplication with broadcasting support.

Compared to matmul the two matrixes are allowed to have different dimensions as long as they are compatible for broadcast. E.g. if self has shape (j, 1, n, k) and rhs has shape (l, k, m), the output will have shape (j, l, n, m).

pub fn where_cond(&self, on_true: &Self, on_false: &Self) -> Result<Self>

Returns a tensor with the same shape as the input tensor, the values are taken from on_true if the input tensor value is not zero, and on_false at the positions where the input tensor is equal to zero.

pub fn embedding(&self, ids: &Self) -> Result<Self>

Returns a tensor with the values from the self tensor at the index corresponding to the values hold in the ids tensor.

Arguments

• self - A tensor with dimensions v, h.
• ids - A tensor with dimensions s and with integer values between 0 and v (exclusive).

The resulting tensor has dimensions s, h. s is called the sequence length, v the vocabulary size, and h the hidden size.

use candle_core::{Tensor, Device};
let values = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let ids = Tensor::new(&[2u32, 1u32, 2u32], &Device::Cpu)?;
let emb = values.embedding(&ids)?;
assert_eq!(emb.to_vec2::<f32>()?, &[[4., 5.], [2., 3.], [4., 5.]]);

pub fn scatter_add<D: Dim>( &self, indexes: &Self, source: &Self, dim: D, ) -> Result<Self>

pub fn slice_scatter<D: Dim>( &self, src: &Self, dim: D, start: usize, ) -> Result<Self>

Embeds the values of the src tensor into the self tensor on the specified dimension.

pub fn slice_scatter0(&self, src: &Self, start: usize) -> Result<Self>

Embeds the values of the src tensor into the self tensor on the first dimension.

pub fn index_add<D: Dim>( &self, indexes: &Self, source: &Self, dim: D, ) -> Result<Self>

Accumulate element from source at indexes indexes and add them to self.

pub fn gather<D: Dim>(&self, indexes: &Self, dim: D) -> Result<Self>

Gather values across the target dimension.

Arguments

• self - The input tensor.
• indexes - The indices of elements to gather, this should have same number of dimensions as self and indexes.dims()[d] <= self.dims()[d] for all dimensions d != dim
• dim - the target dimension.

The resulting tensor has the same shape as indexes and use values from self indexed on dimension dim by the values in indexes.

pub fn index_select<D: Dim>(&self, indexes: &Self, dim: D) -> Result<Self>

Select values for the input tensor at the target indexes across the specified dimension.

The indexes is argument is an int tensor with a single dimension. The output has the same number of dimension as the self input. The target dimension of the output has length the length of indexes and the values are taken from self using the index from indexes. Other dimensions have the same number of elements as the input tensor.

pub fn strided_index(&self) -> StridedIndex<'_>

Returns an iterator over position of the elements in the storage when ranging over the index tuples in lexicographic order.

pub fn strided_blocks(&self) -> StridedBlocks<'_>

Similar to strided_index but returns the position of the start of each contiguous block as well as the length of the contiguous blocks. For a contiguous tensor, the index iterator will only return the start offset and the size would be the number of elements in the tensor.

pub fn to_vec1<S: WithDType>(&self) -> Result<Vec<S>>

Returns the data contained in a 1D tensor as a vector of scalar values.

pub fn to_vec2<S: WithDType>(&self) -> Result<Vec<Vec<S>>>

Returns the data contained in a 2D tensor as a vector of vector of scalar values.

pub fn to_vec3<S: WithDType>(&self) -> Result<Vec<Vec<Vec<S>>>>

Returns the data contained in a 3D tensor.

pub fn dtype(&self) -> DType

The dtype for the elements stored in the input tensor.

pub fn device(&self) -> &Device

The device on which the input tensor is located.

pub fn shape(&self) -> &Shape

The tensor shape, i.e. dimension sizes on each axis.

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

The dimension size for this tensor on each axis.

pub fn dim<D: Dim>(&self, dim: D) -> Result<usize>

The dimension size for a specified dimension index.

pub fn layout(&self) -> &Layout

The layout of the input tensor, this stores both the shape of the tensor as well as the strides and the start offset to apply to the underlying storage.

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

pub fn rank(&self) -> usize

The number of dimensions for this tensor, 0 for a scalar tensor, 1 for a 1D tensor, etc.

pub fn elem_count(&self) -> usize

The number of elements stored in this tensor.

pub fn id(&self) -> TensorId

The unique identifier for this tensor.

pub fn is_variable(&self) -> bool

Whether this tensor is a variable or not. A variable is a tensor for which gradient is tracked and on which backpropagation can be performed.

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

Computes the sum of all the elements in this tensor and returns a tensor holding this scalar with zero dimensions.

use candle_core::{Tensor, Device};
let tensor = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let tensor = tensor.sum_all()?;
assert_eq!(tensor.to_scalar::<f32>()?, 15.);

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

pub fn flatten<D1: Dim, D2: Dim>( &self, start_dim: D1, end_dim: D2, ) -> Result<Tensor>

Flattens the input tensor on the dimension indexes from start_dim to end_dim (both inclusive).

pub fn flatten_to<D: Dim>(&self, end_dim: D) -> Result<Tensor>

Flattens the input tensor on the dimension indexes from 0 to end_dim (inclusive).

pub fn flatten_from<D: Dim>(&self, start_dim: D) -> Result<Tensor>

Flattens the input tensor on the dimension indexes from start_dim (inclusive) to the last dimension.

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

Flattens the input tensor by reshaping it into a one dimension tensor.

use candle_core::{Tensor, Device};
let tensor = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let tensor = tensor.flatten_all()?;
assert_eq!(tensor.to_vec1::<f32>()?, &[0., 1., 2., 3., 4., 5.]);

pub fn get(&self, i: usize) -> Result<Tensor>

Returns the sub-tensor fixing the index at i on the first dimension.

use candle_core::{Tensor, Device};
let tensor = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let t = tensor.get(0)?;
assert_eq!(t.to_vec1::<f32>()?, &[0., 1.]);
let t = tensor.get(1)?;
assert_eq!(t.to_vec1::<f32>()?, &[2., 3.]);

pub fn get_on_dim<D: Dim>(&self, dim: D, index: usize) -> Result<Tensor>

Returns the sub-tensor fixing the index at index on the dimension dim.

use candle_core::{Tensor, Device};
let tensor = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let t = tensor.get_on_dim(1, 0)?;
assert_eq!(t.to_vec1::<f32>()?, &[0., 2., 4.]);
let t = tensor.get_on_dim(1, 1)?;
assert_eq!(t.to_vec1::<f32>()?, &[1., 3., 5.]);
let t = tensor.get_on_dim(0, 1)?;
assert_eq!(t.to_vec1::<f32>()?, &[2., 3.]);

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

Returns a tensor that is a transposed version of the input, the two last dimensions of the input are swapped.

use candle_core::{Tensor, Device};
let tensor = Tensor::new(&[[0f32, 1.], [2., 3.], [4., 5.]], &Device::Cpu)?;
let tensor = tensor.t()?;
assert_eq!(tensor.to_vec2::<f32>()?, &[[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]]);

pub fn transpose<D1: Dim, D2: Dim>(&self, dim1: D1, dim2: D2) -> Result<Tensor>

Returns a tensor that is a transposed version of the input, the given dimensions are swapped.

pub fn permute<D: Dims>(&self, dims: D) -> Result<Tensor>

Returns a tensor with the same data as the input where the dimensions have been permuted. dims must be a permutation, i.e. include each dimension index exactly once.

use candle_core::{Tensor, Device};
let tensor = Tensor::arange(0u32, 120u32, &Device::Cpu)?.reshape((2, 3, 4, 5))?;
assert_eq!(tensor.dims(), &[2, 3, 4, 5]);
let tensor = tensor.permute((2, 3, 1, 0))?;
assert_eq!(tensor.dims(), &[4, 5, 3, 2]);

pub fn is_contiguous(&self) -> bool

Returns true if the data is stored in a C contiguous (aka row major) way.

pub fn is_fortran_contiguous(&self) -> bool

Returns true if the data is stored in a Fortran contiguous (aka column major) way.

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

Compared to clone, this copies the actual storage but may fail because of running out of memory.

pub fn detach(&self) -> Tensor

Returns a new tensor detached from the current graph, gradient are not propagated through this new node. The storage of this tensor is shared with the initial tensor.

If the tensor is already detached from the computation graph, the same tensor is returned.

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

If the target device is the same as the tensor device, only a shallow copy is performed.

pub fn broadcast_left<S: Into<Shape>>(&self, left_shape: S) -> Result<Self>

Returns a new tensor duplicating data from the original tensor. New dimensions are inserted on the left.

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

Broadcast the input tensor to the target shape. This returns an error if the input shape is not compatible with the target shape.

If the input shape is i_1, i_2, ... i_k, the target shape has to have k dimensions or more and shape j_1, ..., j_l, t_1, t_2, ..., t_k. The dimensions j_1 to j_l can have any value, the dimension t_a must be equal to i_a if i_a is different from 1. If i_a is equal to 1, any value can be used.

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

An alias for broadcast_as.

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

Casts the input tensor to the target dtype.

use candle_core::{Tensor, Device};
let tensor = Tensor::new(3.14159265358979f64, &Device::Cpu)?;
assert_eq!(tensor.to_scalar::<f64>()?, 3.14159265358979);
let tensor = tensor.to_dtype(candle_core::DType::F32)?;
assert_eq!(tensor.to_scalar::<f32>()?, 3.1415927);

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

Returns a tensor that is in row major order. This is the same as the original tensor if it was already contiguous, otherwise a copy is triggered.

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

Returns a tensor that is in row major order. This always makes a copy.

pub fn reshape<S: ShapeWithOneHole>(&self, s: S) -> Result<Tensor>

Reshape returns a tensor with the target shape provided that the number of elements of the original tensor is the same. If the input tensor is contiguous, this is a view on the original data. Otherwise this uses a new storage and copies the data over, the returned tensor is always contiguous.

The shape can be specified using a tuple of usize and at most one () in which case the behavior is the same as when using -1 in PyTorch: this dimension size is adjusted so as to match the number of elements in the tensor.

let a = Tensor::zeros((2, 3), DType::F32, &Device::Cpu)?;

let c = a.reshape((1, 6))?;
assert_eq!(c.shape().dims(), &[1, 6]);

let c = a.reshape((3, 2))?;
assert_eq!(c.shape().dims(), &[3, 2]);

let c = a.reshape((2, (), 1))?;
assert_eq!(c.shape().dims(), &[2, 3, 1]);

pub fn squeeze<D: Dim>(&self, dim: D) -> Result<Self>

Creates a new tensor with the specified dimension removed if its size was one.

let a = Tensor::zeros((2, 3, 1), DType::F32, &Device::Cpu)?;

let c = a.squeeze(2)?;
assert_eq!(c.shape().dims(), &[2, 3]);

let c = a.squeeze(D::Minus1)?;
assert_eq!(c.shape().dims(), &[2, 3]);

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

Creates a new tensor with a dimension of size one inserted at the specified position.

let a = Tensor::zeros((2, 3), DType::F32, &Device::Cpu)?;

let c = a.unsqueeze(0)?;
assert_eq!(c.shape().dims(), &[1, 2, 3]);

let c = a.unsqueeze(D::Minus1)?;
assert_eq!(c.shape().dims(), &[2, 3, 1]);

pub fn pad_with_zeros<D: Dim>( &self, dim: D, left: usize, right: usize, ) -> Result<Self>

Pad the input tensor using 0s along dimension dim. This adds left elements before the input tensor values and right elements after.

pub fn pad_with_same<D: Dim>( &self, dim: D, left: usize, right: usize, ) -> Result<Self>

Pad the input tensor using same values along dimension dim. This adds left elements before the input tensor values and right elements after.

pub fn apply<M: Module>(&self, m: &M) -> Result<Self>

Run the forward method of m on self.

pub fn apply_t<M: ModuleT>(&self, m: &M, train: bool) -> Result<Self>

Run the forward method of m on self.

pub fn storage_and_layout(&self) -> (RwLockReadGuard<'_, Storage>, &Layout)

The storage used by this tensor, together with the layout to use to access it safely.

pub fn normalize_axis(&self, axis: i64) -> Result<usize>

Normalize a ‘relative’ axis value: positive values are kept, negative values means counting the dimensions from the back.

pub fn cumsum<D: Dim>(&self, dim: D) -> Result<Self>

Returns the cumulative sum of elements of the input tensor summed over the specified dimension.

This operation is most efficient when dim is the last dimension of the tensor.

pub fn slice_assign<D: RangeBounds<usize>>( &self, ranges: &[D], src: &Tensor, ) -> Result<Self>

Returns a copy of self where the values within ranges have been replaced with the content of src.

pub fn log_sum_exp<D: Dims>(&self, sum_dims: D) -> Result<Self>

Returns log(sum(exp(tensor), dim)).

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

Pointwise pow operation.

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

Broadcasting version of pow.

pub fn slice_set<D: Dim>(&self, src: &Self, dim: D, offset: usize) -> Result<()>

Set the values on self using values from src. The copy starts at the specified offset for the target dimension dim on self. self and src must have the same shape except on dimension dim where the self size has to be greater than or equal to offset plus the src size.

Note that this modifies self in place and as such is not compatibel with back-propagation.

Trait Implementations

impl Clone for Var

fn clone(&self) -> Var

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Var

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

Formats the value using the given formatter.

impl Deref for Var

type Target = Tensor

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for Var

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

Formats the value using the given formatter.