Struct TensorChain

pub struct TensorChain<T, S, const D: usize> { /* private fields */ }

Combines two or more tensors along an existing dimension in their shapes to create a Tensor with a length in that dimension equal to the sum of the sources together along that dimension. All other dimensions in the tensors’ shapes must be the same.

This can be framed as an D dimensional version of std::iter::Iterator::chain

Note: TensorChain only supports tuple combinations for 2 to 4. If you need to stack more than four tensors together, you can stack any number with the [S; N] implementation, though note this requires that all the tensors are the same type so you may need to box and erase the types to Box<dyn TensorRef<T, D>>.

use easy_ml::tensors::Tensor;
use easy_ml::tensors::views::{TensorView, TensorChain, TensorRef};
let sample1 = Tensor::from([("sample", 1), ("data", 5)], vec![0, 1, 2, 3, 4]);
let sample2 = Tensor::from([("sample", 1), ("data", 5)], vec![2, 4, 8, 16, 32]);
// Because there are 4 variants of `TensorChain::from` you may need to use the turbofish
// to tell the Rust compiler which variant you're using, but the actual type of `S` can be
// left unspecified by using an underscore.
let matrix = TensorChain::<i32, [_; 2], 2>::from([&sample1, &sample2], "sample");
let equal_matrix = Tensor::from([("sample", 2), ("data", 5)], vec![
    0, 1, 2, 3, 4,
    2, 4, 8, 16, 32
 ]);
assert_eq!(equal_matrix, TensorView::from(matrix));

let also_matrix = TensorChain::<i32, (_, _), 2>::from((sample1, sample2), "sample");
assert_eq!(equal_matrix, TensorView::from(&also_matrix));

// To stack `equal_matrix` and `also_matrix` using the `[S; N]` implementation we have to first
// make them the same type, which we can do by boxing and erasing.
let matrix_erased: Box<dyn TensorRef<i32, 2>> = Box::new(also_matrix);
let equal_matrix_erased: Box<dyn TensorRef<i32, 2>> = Box::new(equal_matrix);
let repeated_data = TensorChain::<i32, [_; 2], 2>::from(
    [matrix_erased, equal_matrix_erased], "data"
);
assert!(
    TensorView::from(repeated_data).eq(
        &Tensor::from([("sample", 2), ("data", 10)], vec![
            0, 1, 2,  3,  4, 0, 1, 2,  3,  4,
            2, 4, 8, 16, 32, 2, 4, 8, 16, 32
        ])
    ),
);

Implementations

impl<T, S, const D: usize, const N: usize> TensorChain<T, [S; N], D>

where S: TensorRef<T, D>,

pub fn from(sources: [S; N], along: Dimension) -> Self

Creates a TensorChain from an array of sources of the same type and the dimension name to chain the sources along. The sources must all have an identical shape, including the provided dimension, except for the dimension lengths of the provided dimension name which may be different.

Panics

If N == 0, D == 0, the shapes of the sources are not identical*, or the dimension for chaining is not in sources’ shape.

*except for the lengths along the provided dimension.

pub fn sources(self) -> [S; N]

Consumes the TensorChain, yielding the sources it was created from in the same order.

pub fn sources_ref(&self) -> &[S; N]

Gives a reference to all the TensorChain’s sources it was created from in the same order

impl<T, S1, S2, const D: usize> TensorChain<T, (S1, S2), D>

where S1: TensorRef<T, D>, S2: TensorRef<T, D>,

pub fn from(sources: (S1, S2), along: Dimension) -> Self

Creates a TensorChain from two sources and the dimension name to chain the sources along. The sources must all have an identical shape, including the provided dimension, except for the dimension lengths of the provided dimension name which may be different.

Panics

If D == 0, the shapes of the sources are not identical*, or the dimension for chaining is not in sources’ shape.

*except for the lengths along the provided dimension.

pub fn sources(self) -> (S1, S2)

Consumes the TensorChain, yielding the sources it was created from in the same order.

pub fn sources_ref(&self) -> &(S1, S2)

Gives a reference to all the TensorChain’s sources it was created from in the same order

impl<T, S1, S2, S3, const D: usize> TensorChain<T, (S1, S2, S3), D>

where S1: TensorRef<T, D>, S2: TensorRef<T, D>, S3: TensorRef<T, D>,

pub fn from(sources: (S1, S2, S3), along: Dimension) -> Self

Creates a TensorChain from three sources and the dimension name to chain the sources along. The sources must all have an identical shape, including the provided dimension, except for the dimension lengths of the provided dimension name which may be different.

Panics

If D == 0, the shapes of the sources are not identical*, or the dimension for chaining is not in sources’ shape.

*except for the lengths along the provided dimension.

pub fn sources(self) -> (S1, S2, S3)

Consumes the TensorChain, yielding the sources it was created from in the same order.

pub fn sources_ref(&self) -> &(S1, S2, S3)

Gives a reference to all the TensorChain’s sources it was created from in the same order

impl<T, S1, S2, S3, S4, const D: usize> TensorChain<T, (S1, S2, S3, S4), D>

where S1: TensorRef<T, D>, S2: TensorRef<T, D>, S3: TensorRef<T, D>, S4: TensorRef<T, D>,

pub fn from(sources: (S1, S2, S3, S4), along: Dimension) -> Self

Creates a TensorChain from four sources and the dimension name to chain the sources along. The sources must all have an identical shape, including the provided dimension, except for the dimension lengths of the provided dimension name which may be different.

Panics

If D == 0, the shapes of the sources are not identical*, or the dimension for chaining is not in sources’ shape.

*except for the lengths along the provided dimension.

pub fn sources(self) -> (S1, S2, S3, S4)

Consumes the TensorChain, yielding the sources it was created from in the same order.

pub fn sources_ref(&self) -> &(S1, S2, S3, S4)

Gives a reference to all the TensorChain’s sources it was created from in the same order

Trait Implementations

impl<T: Clone, S: Clone, const D: usize> Clone for TensorChain<T, S, D>

fn clone(&self) -> TensorChain<T, S, D>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug, S: Debug, const D: usize> Debug for TensorChain<T, S, D>

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

Formats the value using the given formatter.

impl<T, S, const D: usize, const N: usize> TensorMut<T, D> for TensorChain<T, [S; N], D>

where S: TensorMut<T, D>,

fn get_reference_mut(&mut self, indexes: [usize; D]) -> Option<&mut T>

Gets a mutable reference to the value at the index, if the index is in range. Otherwise returns None.

unsafe fn get_reference_unchecked_mut(&mut self, indexes: [usize; D]) -> &mut T

Gets a mutable reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference_mut.

impl<T, S1, S2, const D: usize> TensorMut<T, D> for TensorChain<T, (S1, S2), D>

where S1: TensorMut<T, D>, S2: TensorMut<T, D>,

fn get_reference_mut(&mut self, indexes: [usize; D]) -> Option<&mut T>

Gets a mutable reference to the value at the index, if the index is in range. Otherwise returns None.

unsafe fn get_reference_unchecked_mut(&mut self, indexes: [usize; D]) -> &mut T

Gets a mutable reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference_mut.

impl<T, S1, S2, S3, const D: usize> TensorMut<T, D> for TensorChain<T, (S1, S2, S3), D>

where S1: TensorMut<T, D>, S2: TensorMut<T, D>, S3: TensorMut<T, D>,

fn get_reference_mut(&mut self, indexes: [usize; D]) -> Option<&mut T>

Gets a mutable reference to the value at the index, if the index is in range. Otherwise returns None.

unsafe fn get_reference_unchecked_mut(&mut self, indexes: [usize; D]) -> &mut T

Gets a mutable reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference_mut.

impl<T, S1, S2, S3, S4, const D: usize> TensorMut<T, D> for TensorChain<T, (S1, S2, S3, S4), D>

where S1: TensorMut<T, D>, S2: TensorMut<T, D>, S3: TensorMut<T, D>, S4: TensorMut<T, D>,

fn get_reference_mut(&mut self, indexes: [usize; D]) -> Option<&mut T>

Gets a mutable reference to the value at the index, if the index is in range. Otherwise returns None.

unsafe fn get_reference_unchecked_mut(&mut self, indexes: [usize; D]) -> &mut T

Gets a mutable reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference_mut.

impl<T, S, const D: usize, const N: usize> TensorRef<T, D> for TensorChain<T, [S; N], D>

where S: TensorRef<T, D>,

fn get_reference(&self, indexes: [usize; D]) -> Option<&T>

Gets a reference to the value at the index if the index is in range. Otherwise returns None.

fn view_shape(&self) -> [(Dimension, usize); D]

The shape this tensor has. See dimensions for an overview. The product of the lengths in the pairs define how many elements are in the tensor (or the portion of it that is visible).

unsafe fn get_reference_unchecked(&self, indexes: [usize; D]) -> &T

Gets a reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference.

fn data_layout(&self) -> DataLayout<D>

The way the data in this tensor is laid out in memory. In particular, Linear has several requirements on what is returned that must be upheld by implementations of this trait.

impl<T, S1, S2, const D: usize> TensorRef<T, D> for TensorChain<T, (S1, S2), D>

where S1: TensorRef<T, D>, S2: TensorRef<T, D>,

fn get_reference(&self, indexes: [usize; D]) -> Option<&T>

Gets a reference to the value at the index if the index is in range. Otherwise returns None.

fn view_shape(&self) -> [(Dimension, usize); D]

The shape this tensor has. See dimensions for an overview. The product of the lengths in the pairs define how many elements are in the tensor (or the portion of it that is visible).

unsafe fn get_reference_unchecked(&self, indexes: [usize; D]) -> &T

Gets a reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference.

fn data_layout(&self) -> DataLayout<D>

The way the data in this tensor is laid out in memory. In particular, Linear has several requirements on what is returned that must be upheld by implementations of this trait.

impl<T, S1, S2, S3, const D: usize> TensorRef<T, D> for TensorChain<T, (S1, S2, S3), D>

where S1: TensorRef<T, D>, S2: TensorRef<T, D>, S3: TensorRef<T, D>,

fn get_reference(&self, indexes: [usize; D]) -> Option<&T>

Gets a reference to the value at the index if the index is in range. Otherwise returns None.

fn view_shape(&self) -> [(Dimension, usize); D]

The shape this tensor has. See dimensions for an overview. The product of the lengths in the pairs define how many elements are in the tensor (or the portion of it that is visible).

unsafe fn get_reference_unchecked(&self, indexes: [usize; D]) -> &T

Gets a reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference.

fn data_layout(&self) -> DataLayout<D>

The way the data in this tensor is laid out in memory. In particular, Linear has several requirements on what is returned that must be upheld by implementations of this trait.

impl<T, S1, S2, S3, S4, const D: usize> TensorRef<T, D> for TensorChain<T, (S1, S2, S3, S4), D>

where S1: TensorRef<T, D>, S2: TensorRef<T, D>, S3: TensorRef<T, D>, S4: TensorRef<T, D>,

fn get_reference(&self, indexes: [usize; D]) -> Option<&T>

Gets a reference to the value at the index if the index is in range. Otherwise returns None.

fn view_shape(&self) -> [(Dimension, usize); D]

The shape this tensor has. See dimensions for an overview. The product of the lengths in the pairs define how many elements are in the tensor (or the portion of it that is visible).

unsafe fn get_reference_unchecked(&self, indexes: [usize; D]) -> &T

Gets a reference to the value at the index without doing any bounds checking. For a safe alternative see get_reference.

fn data_layout(&self) -> DataLayout<D>

The way the data in this tensor is laid out in memory. In particular, Linear has several requirements on what is returned that must be upheld by implementations of this trait.