Struct Layout

pub struct Layout<D>
where
    D: DimBaseAPI,
{ /* private fields */ }

Layout of tensor.

Layout is a struct that contains shape, stride, and offset of tensor.

• Shape is the size of each dimension of tensor.
• Stride is the number of elements to skip to get to the next element in each dimension.
• Offset is the starting position of tensor.

Layout API document

Layout defines how elements will be accessed alongwith vector of data.

Definition

We use notation $n$ as number of dimension, and $0 \leqslant k < n$ as a specific dimension.

Layout $L(\bm{d}, \bm{t}, s)$ contains three components:

• shape $\bm{d} = (d_0, d_1, \cdots, d_{n - 1})$, where $d_k \geqslant 0$, getter function Layout::shape.
• stride $\bm{t} = (t_0, t_1, \cdots, t_{n - 1})$, where $t_k \neq 0$, getter function Layout::stride.
• offset $s$, where $s \geqslant 0$, getter function Layout::offset.

For index computation, indices will also be involved:

• indices $\bm{i} = (i_0, i_1, \cdots, i_{n - 1})$, where $0 \leqslant i_k < d_k$

For a tensor, we generally use an array ($m_z$, $z \geqslant 0$) to store data in memory. With layout $L(\bm{d}, \bm{t}, s)$, the memory pointer for element at index $\bm{i}$ should be $$ z(\bm{i}) = s + \bm{i} \cdot \bm{t} = s + \sum_{k = 0}^{n - 1} i_k t_k $$

Note that in actual program, it is allowed to have negative indices $\tilde i_k \in [-d_k, d_k)$: $$ i_k = \begin{cases} \tilde i_k & i_k \in [0, d_k) \\ \tilde i_k + d_k & i_k \in [-d_k, 0) \end{cases} $$

Implementations

impl<D> Layout<D>

where D: DimBaseAPI,

pub fn size_non_broadcast(&self) -> usize

Get the size of the non-broadcasted part.

Equivalent to size() if there is no broadcast (setting axis size = 1 where stride = 0).

pub fn is_broadcasted(&self) -> bool

Check whether current layout has been broadcasted.

This check is done by checking whether any stride of axis is zero.

impl<D> Layout<D>

where D: DimBaseAPI,

Getter/setter functions for layout.

pub fn shape(&self) -> &D

Shape of tensor. Getter function.

pub fn stride(&self) -> &<D as DimBaseAPI>::Stride

Stride of tensor. Getter function.

pub fn offset(&self) -> usize

Starting offset of tensor. Getter function.

pub fn ndim(&self) -> usize

Number of dimensions of tensor.

pub fn size(&self) -> usize

Total number of elements in tensor.

Note

This function uses cached size, instead of evaluating from shape.

pub unsafe fn set_offset(&mut self, offset: usize) -> &mut Layout<D>

Manually set offset.

Safety

We will not check whether this offset is valid or not. In most cases, it is not intended to be used by user.

impl<D> Layout<D>

where D: DimBaseAPI + DimShapeAPI + DimStrideAPI,

Properties of layout.

pub fn f_prefer(&self) -> bool

Whether this tensor is f-preferred.

pub fn c_prefer(&self) -> bool

Whether this tensor is c-preferred.

pub fn ndim_of_f_contig(&self) -> usize

Least number of dimensions that is f-contiguous for layout.

This function can be useful determining when to iterate by contiguous, and when to iterate by index.

pub fn ndim_of_c_contig(&self) -> usize

Least number of dimensions that is c-contiguous for layout.

This function can be useful determining when to iterate by contiguous, and when to iterate by index.

pub fn f_contig(&self) -> bool

Whether this tensor is f-contiguous.

Special cases

• When length of a dimension is one, then stride to that dimension is not important.
• When length of a dimension is zero, then tensor contains no elements, thus f-contiguous.

pub fn c_contig(&self) -> bool

Whether this tensor is c-contiguous.

Special cases

• When length of a dimension is one, then stride to that dimension is not important.
• When length of a dimension is zero, then tensor contains no elements, thus c-contiguous.

pub fn index_f(&self, index: &[isize]) -> Result<usize, Error>

Index of tensor by list of indexes to dimensions.

This function does not optimized for performance.

pub fn index(&self, index: &[isize]) -> usize

Index of tensor by list of indexes to dimensions.

This function does not optimized for performance. Negative index allowed.

Panics

• Index greater than shape

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

Index range bounds of current layout. This bound is [min, max), which could be feed into range (min..max). If min == max, then this layout should not contains any element.

This function will raise error when minimum index is smaller than zero.

pub fn check_strides(&self) -> Result<(), Error>

Check if strides is correct (no elemenets can overlap).

This will check if all number of elements in dimension of small strides is less than larger strides. For example of valid stride:

shape:  (3,    2,  6)  -> sorted ->  ( 3,   6,   2)
stride: (3, -300, 15)  -> sorted ->  ( 3,  15, 300)
number of elements:                    9,  90,
stride of next dimension              15, 300,
number of elem < stride of next dim?   +,   +,

Special cases

• if length of tensor is zero, then strides will always be correct.
• if certain dimension is one, then check for this stride will be ignored.

TODO

Correctness of this function is not fully ensured.

pub fn diagonal( &self, offset: Option<isize>, axis1: Option<isize>, axis2: Option<isize>, ) -> Result<Layout<<D as DimSmallerOneAPI>::SmallerOne>, Error>

where D: DimSmallerOneAPI,

impl<D> Layout<D>

where D: DimBaseAPI,

Constructors of layout. See also DimLayoutContigAPI layout from shape directly.

pub fn new( shape: D, stride: <D as DimBaseAPI>::Stride, offset: usize, ) -> Result<Layout<D>, Error>

where D: DimShapeAPI + DimStrideAPI,

Generate new layout by providing everything.

Error when

• Shape and stride length mismatch
• Strides is correct (no elements can overlap)
• Minimum bound is not negative

pub unsafe fn new_unchecked( shape: D, stride: <D as DimBaseAPI>::Stride, offset: usize, ) -> Layout<D>

Generate new layout by providing everything, without checking bounds and strides.

Safety

This function does not check whether layout is valid.

pub fn new_shape(&self) -> D

New zero shape, which number of dimensions are the same to current layout.

pub fn new_stride(&self) -> <D as DimBaseAPI>::Stride

New zero stride, which number of dimensions are the same to current layout.

impl<D> Layout<D>

where D: DimBaseAPI + DimShapeAPI + DimStrideAPI,

Manuplation of layout.

pub fn transpose(&self, axes: &[isize]) -> Result<Layout<D>, Error>

Transpose layout by permutation.

See also

• numpy.transpose
• Python array API: permute_dims

pub fn permute_dims(&self, axes: &[isize]) -> Result<Layout<D>, Error>

Transpose layout by permutation.

This is the same function to Layout::transpose

pub fn reverse_axes(&self) -> Layout<D>

Reverse axes of layout.

pub fn swapaxes(&self, axis1: isize, axis2: isize) -> Result<Layout<D>, Error>

Swap axes of layout.

impl<D> Layout<D>

where D: DimBaseAPI + DimShapeAPI + DimStrideAPI,

Fast indexing and utilities of layout.

These functions are mostly internal to this crate.

pub unsafe fn index_uncheck(&self, index: &[usize]) -> isize

Index of tensor by list of indexes to dimensions.

Safety

This function does not check for bounds, including

• Negative index
• Index greater than shape

Due to these reasons, this function may well give index smaller than zero, which may occur in iterator; so this function returns isize.

impl<D> Layout<D>

where D: DimBaseAPI,

pub fn into_dim<D2>(self) -> Result<Layout<D2>, Error>

where D2: DimBaseAPI, D: DimIntoAPI<D2>,

Convert layout to another dimension.

pub fn to_dim<D2>(&self) -> Result<Layout<D2>, Error>

where D2: DimBaseAPI, D: DimIntoAPI<D2>,

Convert layout to another dimension.

Trait Implementations

impl<D> Clone for Layout<D>

where D: Clone + DimBaseAPI, <D as DimBaseAPI>::Stride: Clone,

fn clone(&self) -> Layout<D>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<D> Debug for Layout<D>

where D: DimDevAPI,

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

Formats the value using the given formatter.

impl<T, D> EmptyAPI<(T, D)> for Layout<D>

where D: DimAPI,

type Out = TensorBase<Storage<DataOwned<<DeviceFaer as DeviceRawAPI<T>>::Raw>, T, DeviceFaer>, Vec<usize>>

unsafe fn empty_f(self) -> Result<Self::Out>

Safety

unsafe fn empty(self) -> Self::Out

where Self: Sized,

Safety

impl<const N: usize> From<[usize; N]> for Layout<[usize; N]>

fn from(shape: [usize; N]) -> Layout<[usize; N]>

Converts to this type from the input type.

impl From<Vec<usize>> for Layout<Vec<usize>>

fn from(shape: Vec<usize>) -> Layout<Vec<usize>>

Converts to this type from the input type.

impl<D> IndexerDynamicAPI for Layout<D>

where D: DimDevAPI,

fn dim_slice(&self, indexers: &[Indexer]) -> Result<Layout<Vec<usize>>, Error>

Index tensor by a list of indexers.

fn dim_split_at( &self, axis: isize, ) -> Result<(Layout<Vec<usize>>, Layout<Vec<usize>>), Error>

Split current layout into two layouts at axis, with offset unchanged.

fn dim_split_axes( &self, axes: &[isize], ) -> Result<(Layout<Vec<usize>>, Layout<Vec<usize>>), Error>

impl<D> IndexerLargerOneAPI for Layout<D>

where D: DimDevAPI + DimLargerOneAPI, <D as DimLargerOneAPI>::LargerOne: DimDevAPI,

type DOut = <D as DimLargerOneAPI>::LargerOne

fn dim_insert( &self, axis: isize, ) -> Result<Layout<<Layout<D> as IndexerLargerOneAPI>::DOut>, Error>

Insert dimension after, with shape 1. Number of dimension will increase by 1.

impl<D> IndexerPreserveAPI for Layout<D>

where D: DimDevAPI,

fn dim_narrow( &self, axis: isize, slice: Slice<isize>, ) -> Result<Layout<D>, Error>

Narrowing tensor by slicing at a specific axis.

impl<D> IndexerSmallerOneAPI for Layout<D>

where D: DimDevAPI + DimSmallerOneAPI, <D as DimSmallerOneAPI>::SmallerOne: DimDevAPI,

type DOut = <D as DimSmallerOneAPI>::SmallerOne

fn dim_select( &self, axis: isize, index: isize, ) -> Result<Layout<<Layout<D> as IndexerSmallerOneAPI>::DOut>, Error>

Select dimension at index. Number of dimension will decrease by 1.

fn dim_eliminate( &self, axis: isize, ) -> Result<Layout<<Layout<D> as IndexerSmallerOneAPI>::DOut>, Error>

Eliminate dimension at index. Number of dimension will decrease by 1.

impl<T, D> OnesAPI<(T, D)> for Layout<D>

where T: Num + Clone, D: DimAPI,

type Out = TensorBase<Storage<DataOwned<<DeviceFaer as DeviceRawAPI<T>>::Raw>, T, DeviceFaer>, Vec<usize>>

fn ones_f(self) -> Result<Self::Out>

fn ones(self) -> Self::Out

where Self: Sized,

impl<D> PartialEq for Layout<D>

where D: DimBaseAPI,

fn eq(&self, other: &Layout<D>) -> bool

For layout, shape must be the same, while stride should be the same when shape is not zero or one, but can be arbitary otherwise.

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, D> ZerosAPI<(T, D)> for Layout<D>

where T: Num + Clone, D: DimAPI,

type Out = TensorBase<Storage<DataOwned<<DeviceFaer as DeviceRawAPI<T>>::Raw>, T, DeviceFaer>, Vec<usize>>

fn zeros_f(self) -> Result<Self::Out>

fn zeros(self) -> Self::Out

where Self: Sized,

impl<D> Send for Layout<D>

where D: DimBaseAPI,

impl<D> Sync for Layout<D>

where D: DimBaseAPI,