rten_tensor/
lib.rs

1//! rten_tensor provides multi-dimensional arrays, commonly referred to as
2//! _tensors_ in a machine learning context.
3//!
4//! # Storage and layout
5//!
6//! A tensor is a combination of data storage and a layout. The data storage
7//! determines the element type and how the data is owned. A tensor can be:
8//!
9//! - Owned (like `Vec<T>`)
10//! - Borrowed (like `&[T]` or `&mut [T]`)
11//! - Maybe-owned (like `Cow[T]`)
12//! - Shared / reference-counted (like `Arc<[T]>`)
13//!
14//! The layout determines the number of dimensions (the _rank_) and size of each
15//! (the _shape_) and how indices map to offsets in the storage. The dimension
16//! count can be static (fixed at compile time) or dynamic (variable at
17//! runtime).
18//!
19//! # Tensor types and traits
20//!
21//! The base type for all tensors is [TensorBase]. This is not normally used
22//! directly but instead via a type alias which specifies the data ownership
23//! and layout:
24//!
25//! | Rank    | Owned | Borrowed | Mutably borrowed | Owned or borrowed | Reference counted |
26//! | ----    | ----- | -------- | ---------------- | ----------------- | ----------------- |
27//! | Static  | [NdTensor] | [NdTensorView] | [NdTensorViewMut] | [CowNdTensor] | [ArcNdTensor] |
28//! | Dynamic | [Tensor]   | [TensorView]   | [TensorViewMut]   | [CowTensor]   | [ArcTensor]   |
29//!
30//! All tensors implement the [Layout] trait, which provide methods to query
31//! the shape, dimension count and strides of the tensor. Tensor views provide
32//! various methods for indexing, iterating, slicing and transforming them.
33//! The [AsView] trait provides access to these methods for owned and mutably
34//! borrowed tensors. Conceptually it is similar to how [Deref](std::ops::Deref)
35//! allows accesing methods for `&[T]` on a `Vec<T>`. The preferred way to
36//! import the traits is via the prelude:
37//!
38//! ```
39//! use rten_tensor::prelude::*;
40//! use rten_tensor::NdTensor;
41//!
42//! let tensor = NdTensor::from([[1, 2], [3, 4]]);
43//!
44//! let transposed_elems: Vec<_> = tensor.transposed().iter().copied().collect();
45//! assert_eq!(transposed_elems, [1, 3, 2, 4]);
46//! ```
47//!
48//! # Serialization
49//!
50//! Tensors can be serialized and deserialized using [serde](https://serde.rs)
51//! if the `serde` feature is enabled. The serialized representation of a
52//! tensor includes its shape and elements in row-major (C) order. The JSON
53//! serialization of a matrix (`NdTensor<f32, 2>`) looks like this for example:
54//!
55//! ```json
56//! {
57//!   "shape": [2, 2],
58//!   "data": [0.5, 1.0, 1.5, 2.0]
59//! }
60//! ```
61
62mod assume_init;
63mod contiguous;
64mod copy;
65pub mod errors;
66mod index_iterator;
67pub mod iterators;
68pub mod layout;
69mod overlap;
70pub mod slice_range;
71pub mod storage;
72pub mod type_num;
73
74mod impl_debug;
75#[cfg(feature = "serde")]
76mod impl_serialize;
77mod tensor;
78
79/// Trait for sources of random data for tensors, for use with [`Tensor::rand`].
80pub trait RandomSource<T> {
81    /// Generate the next random value.
82    fn next(&mut self) -> T;
83}
84
85// Re-exports for convenience.
86pub use assume_init::AssumeInit;
87pub use contiguous::Contiguous;
88pub use index_iterator::{DynIndices, Indices, NdIndices};
89pub use layout::{DynLayout, Layout, MatrixLayout, NdLayout};
90pub use slice_range::{SliceItem, SliceRange};
91pub use storage::Storage;
92pub use tensor::{
93    ArcNdTensor, ArcTensor, AsView, CowNdTensor, CowTensor, Matrix, MatrixMut, NdTensor,
94    NdTensorView, NdTensorViewMut, Scalar, Tensor, TensorBase, TensorView, TensorViewMut,
95    WeaklyCheckedView,
96};
97
98/// This module provides a convenient way to import the most common traits
99/// from this library via a glob import.
100pub mod prelude {
101    pub use super::{AsView, Layout};
102}
103
104// These modules are public for use by other crates in this repo, but
105// currently considered internal to the project.
106#[doc(hidden)]
107pub mod rng;
108#[doc(hidden)]
109pub mod test_util;
rten_tensor/lib.rs

rten_tensor/
lib.rs
