Struct rten_tensor::DynLayout

pub struct DynLayout { /* private fields */ }

Defines the valid indices for an N-dimensional array and how to map them to offsets in a linear buffer, where N can be varied at runtime.

The layout specifies the size of each dimension of the tensor (the shape) and the stride (gap) between offsets in each dimension.

Safety and internal overlap

Rust requires that only one mutable reference can exist for any value. To ensure this, mutable iteration over a tensor must visit each element only once. This means that in the tensor’s Layout, every valid index must map to a unique offset. Verifying this for the general case of arbitrary shape and strides is non-trivial. See notes in mem_overlap.c in the NumPy source. In this library the problem is simplified by limiting the stride patterns that can be constructed. All Layout functions must uphold the invariant:

Every Layout either has one or more strides set to zero, or every valid index must map to a unique offset.

Zero-strides are used for broadcasting, which is widely used and easy to check for.

Implementations

impl DynLayout

pub fn from_shape(shape: &[usize]) -> DynLayout

Construct a layout with dimension sizes given by shape and default (contiguous) strides.

pub fn try_from_shape_and_strides( shape: &[usize], strides: &[usize], overlap: OverlapPolicy, ) -> Result<DynLayout, FromDataError>

Construct a layout with dimension sizes given by shape and given strides.

Panics if strides may lead to internal overlap (multiple indices map to the same data offset), unless strides contains a 0. See struct notes.

pub fn from_layout<L: Layout>(layout: &L) -> DynLayout

Create a new DynLayout with the same shape and strides as layout.

pub fn broadcast(&self, to_shape: &[usize]) -> DynLayout

Construct a layout which broadcasts elements to to_shape by setting the stride to 0 in broadcasted dimensions.

pub fn move_axis(&mut self, from: usize, to: usize)

Move the index at axis from to to, keeping the relative order of other dimensions the same. This is like NumPy’s moveaxis function.

pub fn slice(&self, range: &[SliceItem]) -> (Range<usize>, DynLayout)

Compute the new layout and offset of the first element for a slice into an existing tensor view.

Returns a tuple of (offset_range, layout) for the sliced view.

Panics if the range is invalid for the current layout.

pub fn try_slice( &self, range: &[SliceItem], ) -> Result<(Range<usize>, DynLayout), SliceError>

Compute the new layout and offset of the first element for a slice into an existing tensor view.

Returns a tuple of (offset_range, layout) for the sliced view, or an error if the range is invalid.

pub fn resize_dim(&mut self, dim: usize, new_size: usize)

pub fn make_contiguous(&mut self)

pub fn permute(&mut self, dims: &[usize])

Swap the order of dimensions in this layout to the order described by dims.

pub fn permuted(&self, dims: &[usize]) -> DynLayout

Return a copy of this layout with dimensions re-ordered according to dims.

pub fn transpose(&mut self)

Reverse the order of dimensions in this layout.

pub fn transposed(&self) -> DynLayout

Return a copy of this layout with the order of dimensions reversed.

pub fn insert_dim(&mut self, dim: usize)

Insert a dimension of size one at index dim.

pub fn slice_offset<Idx: AsRef<[usize]>>(&self, index: Idx) -> usize

Return the offset of the slice that begins at the given index.

pub fn squeezed(&self) -> DynLayout

Return a copy of this layout with dimensions of size 1 removed.

pub fn dims<const N: usize>(&self) -> [usize; N]

Trait Implementations

impl Clone for DynLayout

fn clone(&self) -> DynLayout

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DynLayout

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

Formats the value using the given formatter.

impl<const N: usize> From<&NdLayout<N>> for DynLayout

fn from(value: &NdLayout<N>) -> DynLayout

Converts to this type from the input type.

impl<const N: usize> From<NdLayout<N>> for DynLayout

fn from(value: NdLayout<N>) -> DynLayout

Converts to this type from the input type.

impl Layout for DynLayout

fn len(&self) -> usize

Return the number of elements in the tensor shape described by this layout.

fn ndim(&self) -> usize

Return the number of dimensions.

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

Return the sizes of each dimension.

fn size(&self, dim: usize) -> usize

Returns the size of the dimension dim.

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

Return the stride (offset between elements) in the tensor’s element array.

fn stride(&self, dim: usize) -> usize

Return the stride for a specific dimension.

type Index<'a> = &'a [usize]

Type used to represent indices.

type Indices = DynIndices

Iterator over indices in this tensor.

fn try_offset(&self, index: Self::Index<'_>) -> Option<usize>

Map an index to a storage offset, or return None if the index is out of bounds along any dimension.

fn is_empty(&self) -> bool

Returns true if the array has no elements.

fn indices(&self) -> DynIndices

Return an iterator over all valid indices in this tensor.

fn offset(&self, index: Self::Index<'_>) -> usize

Map an index to a storage offset.

fn offset_unchecked(&self, index: Self::Index<'_>) -> usize

Map an index to a storage offset, without checking if it is valid for the tensor’s shape.

fn is_contiguous(&self) -> bool

Return true if this layout describes a contiguous tensor, where the logical order of elements matches the order in which they are stored.

fn is_broadcast(&self) -> bool

Return true if iterating over elements in this layout will visit elements multiple times.

fn can_broadcast_to(&self, target_shape: &[usize]) -> bool

Return true if this layout’s shape can be broadcast to the given shape.

fn can_broadcast_with(&self, shape: &[usize]) -> bool

Return true if the tensor/view can be broadcast with another tensor or view with a given shape as part of a binary operation.

fn min_data_len(&self) -> usize

Return the minimum length required for the element data buffer used with this layout.

impl MutLayout for DynLayout

fn from_shape(shape: &[usize]) -> Self

Create a new contiguous layout with a given shape.

fn from_shape_and_strides( shape: &[usize], strides: &[usize], overlap: OverlapPolicy, ) -> Result<Self, FromDataError>

Create a layout with custom strides.

fn move_axis(&mut self, from: usize, to: usize)

Move the axis at position from to to by swapping their strides.

fn permuted(&self, order: &[usize]) -> DynLayout

Return a layout with the axes permuted according to the given order.

fn resize_dim(&mut self, dim: usize, size: usize)

fn transposed(&self) -> DynLayout

Reverse the order of dimensions. This is equivalent to self.permuted([N-1, N-2, ... 0]).

fn slice<const M: usize>( &self, range: &[SliceItem], ) -> (Range<usize>, NdLayout<M>)

Slice the layout.

fn slice_dyn(&self, range: &[SliceItem]) -> (Range<usize>, DynLayout)

Slice the layout and return a dynamic rank layout.

fn squeezed(&self) -> DynLayout

Return a layout with all size-one dimensions removed.

fn split( &self, axis: usize, mid: usize, ) -> ((Range<usize>, Self), (Range<usize>, Self))

Split the layout along the given axis into two.

fn try_slice<R: IntoSliceItems>( &self, range: R, ) -> Result<(Range<usize>, DynLayout), SliceError>

Attempt to slice the layout or return an error if the range is invalid for the layout’s shape.

fn index_axis( &self, axis: usize, index: usize, ) -> (Range<usize>, <Self as RemoveDim>::Output)

where Self: RemoveDim,

Slice a layout by selecting a single entry from a given axis.

fn reshaped_for_view<S: IntoLayout>( &self, shape: S, ) -> Result<S::Layout, ReshapeError>

Return a new layout formed by reshaping this one to shape.

fn reshaped_for_copy<S: IntoLayout>( &self, shape: S, ) -> Result<S::Layout, ReshapeError>

Return a new layout formed by reshaping this one to shape.

fn slice_axis(&self, axis: usize, range: Range<usize>) -> (Range<usize>, Self)

Slice the layout along a given axis.

impl PartialEq for DynLayout

fn eq(&self, other: &DynLayout) -> 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, const N: usize> TryFrom<&'a DynLayout> for NdLayout<N>

fn try_from(value: &'a DynLayout) -> Result<NdLayout<N>, DimensionError>

Convert a dynamic layout into a static layout with N dims. Fails if value.ndim() != N.

type Error = DimensionError

The type returned in the event of a conversion error.

impl StructuralPartialEq for DynLayout