Module api_specification

API Specification of RSTSR

Table of Contents

• Tensor Structure and Ownership
  • Figure illustration of tensor structure

Notes on API Specification

• “type” column
  • “assoc” is abbreviation for “associated method function”, meaning that it can only be called by something like tensor.foo() instead of rt::foo().
  • “assoc/fn” means that this function is both defined as associated method and usual function.
  • “core ops” refers to core::ops, indicating that it implements rust language’s own operator.
• Function variants
  • Tables in this page will not show function variants. For more details, please see documentation (under construction) of each function / associated methods.
  • Fallible variants:
    • Infallible (panics when error) are not decorated;
    • Fallible (function that returns RSTSR’s own Result) are decorated with _f suffix;
    • For example infallible asarray and fallible asarray_f.
  • Pass-by-value/reference variants:
    • Pass-by-value (consumes the original tensor, foo(self, ...)) are decorated with into_ prefix;
    • Pass-by-reference (does not consumes the original tensor, foo(&self, ...)) may have to_ prefix or none;
    • For example pass-by-value into_transpose or pass-by-reference transpose.
  • TensorCow output type variants:
    • Pass-by-value returning TensorCow, decorated with change_ prefix;
    • Pass-by-value returning Tensor, decorated with into_ prefix;
    • Pass-by-reference returning TensorView, decorated with to_ prefix or none;
    • reshape and to_layout fits into this category.

Tensor Structure and Ownership

Figure illustration of tensor structure

Tensor

Type	Identifier	Minimal Description
module	tensorbase	Defining tensor structs.
struct	TensorBase<S, D>	Basic struct of tensor (storage + layout).
alias	TensorAny<R, T, B, D>	Basic struct of tensor (data with lifetime + device backend + layout).
alias	Tensor<T, B, D>	Tensor that owns its raw data.
alias	TensorView<'l, T, B, D> TensorRef<'l, T, B, D>	Tensor that shares its raw data by reference.
alias	TensorMut<'l, T, B, D> TensorViewMut<'l, T, B, D>	Tensor that shares its raw data by mutable reference.
alias	TensorCow<'l, T, B, D>	Tensor either shares its raw data by reference, or owns its raw data (immutable). Cow refers to copy-on-write.
alias	TensorArc<T, B, D>	Tensor with its raw data wrapped by atomic reference-counter pointer (Arc).

Tensor Layout

Type	Identifier	Minimal Description
module	layout	Defining layout of tensor and dimensionality.
struct	Layout<D>	Layout of tensor.
trait	DimAPI	Main basic interface for dimensionality.
alias	IxD	Dynamic dimensionality (alias to Vec<usize>).
alias	Ix<N>	Fixed dimensionality (alias to [usize; N]).

Device

Type	Identifier	Minimal Description
module	storage::device	Defining storage and device.
struct	DeviceCpuSerial	Basic backend that handles computations in single thread.
struct	DeviceFaer	Backend that applies multi-threaded operations (by rayon) and efficient matmul (by faer).
struct	DeviceCpuRayon	Base backend for rayon paralleled devices (device for developer, not user).
trait	DeviceAPI<T>	Main basic interface for device.

Device is designed to be able extended by other crates. The above devices DeviceCpuSerial and DeviceFaer are only special in that they are realized in rstsr-core. We hope that in future, more devices (backends) can be supported.

Storage

Type	Identifier	Minimal Description
module	storage::device	Defining storage and device.
struct	Storage<R, T, B>	Storage of tensor (data with lifetime + device backend)

Tensor Ownership

Type	Identifier	Minimal Description
module	storage::data	Defining data representations (lifetime or the way raw data are stored).
struct	DataOwned<C>	Struct wrapper for owned raw data.
enum	DataRef<'l, C>	Enum wrapper for reference of raw data (or manually-dropped data).
enum	DataMut<'l, C>	Enum wrapper for mutable reference of raw data (or manually-dropped data).
enum	DataCow<'l, C>	Enum wrapper for mutable reference of raw data (or manually-dropped data).
struct	DataArc<C>	Struct wrapper for atomic reference-counted raw data pointer.
trait	DataAPI	Interface of immutable operations for data representations.
trait	DataMutAPI	Interface of mutable operations for data representations.
trait	DataIntoCowAPI<'l>	Interface for generating DataCow<'l, C>.
trait	DataForceMutAPI	Interface for generating mutable reference, ignoring lifetime and borrow checks.

Indexing

Type	Identifier	Minimal Description
assoc/fn	slice slice_mut	Basic slicing to tensor, generating view of smaller tensor.
assoc	i i_mut	Alias to slice and slice_mut.
core ops	operator [] Index IndexMut	Indexing tensor element, giving reference of scalar value (not efficient due to boundary check).
assoc	index_uncheck index_mut_uncheck	Indexing tensor element, giving reference of scalar value.

RSTSR Specific Identifiers

Ownership change and transfer

Type	Identifier	Minimal Description
module	ownership_conversion
assoc	view	Get a view of tensor.
assoc	view_mut	Get a mutable view of tensor.
assoc	into_cow	Convert current tensor into copy-on-write.
assoc	into_owned	Convert tensor into owned tensor (Tensor). Raw data is try to be moved, or the necessary values cloned.
assoc	into_shared	Convert tensor into shared tensor (TensorArc). Raw data is try to be moved, or the necessary values cloned.
assoc	to_owned	Clone necessary values to owned tensor (Tensor) without destroying original tensor.
assoc	force_mut	Force generate mutable view of tensor, ignoring lifetime and borrow check.
assoc	to_vec	Clone 1-D tensor to Vec<T>.
assoc	into_vec	Move 1-D tensor to Vec<T> if possible, otherwise clone.
assoc	to_scalar	Extract scalar value from tensor that only have one element.
assoc	as_ptr as_mut_ptr	Returns pointer to the first element in tensor.
fn	asarray	Convert input (scalar, Vec<T>, &[T], tensor) to an array, optionally with shape/layout specified.
assoc	TensorBase::into_raw_parts	Destruct tensor into storage and layout.
assoc	Storage::into_raw_parts	Destruct storage into data (with lifetime) and device.
assoc	DataOwned::into_raw	Destruct owned data and get the raw data (Vec<T> for CPU devices).
assoc	TensorBase::raw TensorBase::raw_mut	Get reference of raw data.

Iteration

Type	Identifier	Minimal Description
module	iterator_elem	Tensor iterators that gives elements.
assoc	iter iter_mut	Iterate tensor by default ordering (c-prefer or f-prefer).
assoc	iter_with_order iter_mut_with_order	Iterate tensor with specified order.
assoc	indexed_iter indexed_iter_mut	Enumerate tensor by default ordering (c-prefer or f-prefer).
assoc	indexed_iter_with_order indexed_iter_mut_with_order	Enumerate tensor with specified order.
module	iterator_axes	Axes iterators that gives smaller tensor views.
assoc	axes_iter axes_iter_mut	Iterate tensor by axes by default ordering (c-prefer or f-prefer).
assoc	axes_iter_with_order axes_iter_mut_with_order	Iterate tensor by axes with specified order.
assoc	indexed_axes_iter indexed_axes_iter_mut	Enumerate tensor by axes by default ordering (c-prefer or f-prefer).
assoc	indexed_axes_iter_with_order indexed_axes_iter_mut_with_order	Enumerate tensor by axes with specified order.

Mapping

Type	Identifier	Minimal Description
module	map_elementwise	Elementwise mapping of tensor.
assoc	map map_fnmut	Call function by reference on each element to create a new tensor.
assoc	mapv mapv_fnmut	Call function by value on each element to create a new tensor.
assoc	mapi mapi_fnmut	Modify the tensor in place by calling function by mutable reference on each element.
assoc	mapvi mapvi_fnmut	Modify the tensor in place by calling function by reference on each element.
assoc	mapb mapb_fnmut	Map to another tensor and call function by reference on each element to create a new tensor.
assoc	mapvb mapvb_fnmut	Map to another tensor and call function by value on each element to create a new tensor.

Error handling

Type	Identifier	Minimal Description
module	error	Error handling in RSTSR.
enum	Error	Error type in RSTSR.
alias	Result<E>	Result type in RSTSR.

Flags

Type	Identifier	Minimal Description
flags	flags	Flags for tensor.
enum	TensorIterOrder	The policy of tensor iterator.
enum	TensorOrder	The order of tensor.
enum	FlagDiag	Unit-diagonal of matrix.
enum	FlagSide	Side of matrix operation.
enum	FlagTrans	Transposition of matrix operation.
enum	FlagUpLo	Upper/Lower triangular of matrix operation.
enum	FlagSymm	Symmetric of matrix operation.

Tensor Manuplication

Storage-irrelevent manuplication

Type	Identifier	Minimal Description
fn	broadcast_arrays	Broadcasts any number of arrays against each other.
assoc/fn	to_broadcast	Broadcasts an array to a specified shape.
assoc/fn	expand_dims	Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by axis.
assoc/fn	flip	Reverses the order of elements in an array along the given axis.
assoc/fn	permute_dims transpose	Permutes the axes (dimensions) of an array x.
assoc/fn	reverse_axes	Reverse the order of elements in an array along the given axis.
assoc/fn	swapaxes	Interchange two axes of an array.
assoc/fn	squeeze	Removes singleton dimensions (axes) from x.
assoc/fn	to_dim to_dyn	Convert layout to the other dimension.
assoc/fn	reshape_assume_contig	Assuming contiguous array, reshapes an array without changing its data.

Storage-dependent manuplication

Type	Identifier	Minimal Description
assoc/fn	reshape into_shape change_shape	Reshapes an array without changing its data.
assoc/fn	to_layout into_layout change_layout	Convert tensor to the other layout.

Storage-creation manuplication

These functions are to be realized in future (concat, stack, etc).

Tensor Creation

Type	Identifier	Minimal Description
fn	asarray	Convert input (scalar, Vec<T>, &[T], tensor) to an array, optionally with shape/layout specified.
module	crate::tensor::creation	Creation methods for tensor.
fn	arange	Evenly spaced values within the half-open interval [start, stop) as one-dimensional array.
fn	empty	Uninitialized tensor having a specified shape.
fn	empty_like	Uninitialized tensor with the same shape as an input tensor.
fn	eye	Returns a two-dimensional array with ones on the kth diagonal and zeros elsewhere.
fn	full	New tensor having a specified shape and filled with given value.
fn	full_like	New tensor filled with given value and having the same shape as an input tensor.
fn	linspace	Evenly spaced numbers over a specified interval.
fn	ones	New tensor filled with ones and having a specified shape.
fn	ones_like	New tensor filled with ones and having the same shape as an input tensor.
fn	zeros	New tensor filled with zeros and having a specified shape.
fn	zeros_like	New tensor filled with zeros and having the same shape as an input tensor.

Basic Operations

Unary functions

• Arithmetics: neg, not

Binary functions

• Arithmetics: add, div, mul, sub, rem;
• Arithmetics with assignment: add_assign, div_assign, mul_assign, rem_assign, sub_assign;
• Bitwise: bitand, bitor, bitxor, shl, shr;
• Bitwise with assignment: bitand_assign, bitor_assign, bitxor_assign, shl_assign, shr_assign.

NOTE: rem can be only called by usual function (rt::rem if you have used rstsr_core::prelude::rt), but not trait function Rem::rem or operator % (which is overrided for matmul).

Trait function calls like associated methods, so we also do not recommend usage of tensor.rem(&other).

Matrix Multiply

Matrix multiply is implemented in many ways. The most useful way is function matmul and operator %.

• functions matmul and matmul_with_output;
• associated methods TensorBase::matmul, TensorBase::matmul_from;
• operator %.

NOTE: Matrix multiplication can also called by trait function Rem::rem, but this is strongly not recommended.

Trait function calls like associated methods, so we also do not recommend usage of tensor.rem(&other).

Common Functions

Unary functions

abs, acos, acosh, asin, asinh, atan, atanh, ceil, conj, cos, cosh, exp, expm1, floor, imag, inv, is_finite, is_inf, is_nan, log, log10, log2, real, round, sign, signbit, sin, sinh, sqrt, square, tan, tanh, trunc

Binary functions

atan2, copysign, eq/equal, floor_divide, ge/greater_equal, gt/greater, hypot, le/less_equal, lt/less, log_add_exp, maximum, minimum, ne/not_equal, pow

Statistical functions

max, mean, min, prod, std, sum, var

Developer Area

The above listings of API specifications are mostly for either user usage, or clarafication of most important aspects of the design of RSTSR.

However, there still leaves many public APIs not fully documented or not listed above. Some of them are exposed as developer interfaces.

This part of documentation is under construction.