Tensor¶
Flashlight’s Tensor abstraction is itself an API. See the README in flashlight/fl/tensor for more on implementing a Tensor backend. The below documentation documents Tensor functions and usage of the Tensor class.
A Tensor in FLashlight is a multidimensional container for data that has a shape. Memory locations and operations on Tensors are defined in per a backend’s implementation.
The Tensor class¶
-
class
Tensor¶ A Tensor on which computation can be performed.
Underlying implementations of tensor operations are implemented via types derived from
TensorAdapterBase; these implementations also store state associated with the tensor. Tensor stores a pointer to the implementation, which can be swapped out if the implementation of backend changes.TensorAdapterBaseimplementations may differ across tensor libraries, hardware-specific libraries or compilers and DSLs.TODO:fl::Tensor {doc} more documentation. NOTE: this API will break frequently and is not yet stable.
Public Functions
-
Tensor(const Tensor &tensor)¶ Copy constructor - calls the implementation-defined copy constructor for the TensorAdapter.
-
Tensor(Tensor &&tensor)¶ Move constructor - moves the pointer to the TensorAdapter - performs no other operations.
-
Tensor()¶ Construct an empty tensor with the default tensor backend’s tensor adapter.
-
Tensor(const Shape &shape, fl::dtype type = fl::dtype::f32)¶ Construct a tensor of a given shape (and optionally type) without populating its data.
- Parameters
[in] shape: the shape of the tensor[in] type: (optional) the type of the tensor
-
Tensor(fl::dtype type)¶ Construct an empty tensor of a given type.
- Parameters
[in] type: (optional) the type of the tensor
-
Tensor(const Dim nRows, const Dim nCols, const Tensor &values, const Tensor &rowIdx, const Tensor &colIdx, StorageType storageType)¶ Construct a sparse tensor.
TODO(jacobkahn): expand this API with getters,
isSparse() as needed, etc.- Parameters
[in] nRows: the number of rows of the tensor[in] nCols: the number of columns of the tensor[in] values: the values associated with the tensor[in] rowIdx: the row indices of the sparse array[in] colIdx: the the column indices of the sparse array[in] storageType: the storage type of the underlying tensor
-
const Shape &
shape() const¶ Get the shape of a tensor.
- Return
the shape of the tensor
-
Location
location() const¶ Get a tensor’s location, host or some device.
- Return
the tensor’s location
-
size_t
elements() const¶ Get the number of elements in the tensor.
- Return
the size of the tensor in elements.
-
Dim
dim(const size_t dim) const¶ Get the size of a given dimension of a tensor in the number of arguments.
Throws if the given dimension is larger than the number of tensor dimensions.
- Return
the number of elements at the given dimension
-
int
ndim() const¶ Get the number of directions of the tensor.
- Return
the number of dimensions
-
bool
isEmpty() const¶ Returns true if the tensor has zero elements, else false.
- Return
true if the tensor is empty
-
bool
hasAdapter() const¶ Returns true if the tensor has an associated underlying adapter.
- Return
true if the tensor has a valid adapter
-
size_t
bytes() const¶ Get the tensor size in bytes.
- Return
the size of the tensor in bytes.
-
dtype
type() const¶ Get the data type of tensor.
- Return
the dtype of the tensor
-
bool
isSparse() const¶ Returns whether or not the tensor is sparse.
- Return
true if the tensor is a sparse tensor, else false
-
Shape
strides() const¶ Get this tensor’s strides - the number of elements/coefficients to step when moving along each dimension when traversing the tensor.
- Return
a Shape containing strides in each dimension.
-
virtual const Stream &
stream() const¶ Get the stream which contains(ed) the computation required to realize an up-to-date value for this tensor.
For instance,
device()may not yield a pointer to the up-to-date value to use this pointer,Stream::syncorStream::relativeSyncis required.- Return
an immutable reference to the stream that contains(ed) the computations which create this tensor.
-
Tensor
astype(const dtype type) const¶ Returns a tensor with elements cast as a particular type.
- Return
a tensor with element-wise cast to the new type
- Parameters
[in] type: the type to which to cast the tensor
-
Tensor
operator()(const std::vector<Index> &indices) const¶ Index into a tensor using a vector of fl::Index references.
- Return
an indexed tensor
- Parameters
[in] indices: a vector of fl::Index references with which to index.
-
template<typename ...
Ts>
Tensoroperator()(const Ts&... args) const¶ Index into a tensor using a variable number of fl::Index.
- Return
an indexed tensor
- Parameters
[in] args: fl::Index instances to use
-
Tensor
flatten() const¶ Returns a representation of the tensor in 1 dimension.
- Return
a 1D version of this tensor 1D-indexed with the given index.
-
Tensor
flat(const Index &idx) const¶ Returns a tensor indexed from this tensor but indexed as a 1D/flattened tensor.
- Return
an indexed, 1D version of this tensor.
-
Tensor
asContiguousTensor() const¶ Return a copy (depending on copy-on-write behavior of the underlying implementation) of this tensor that is contigous in memory.
- Return
an identical tensor that is contiguous in memory
-
TensorBackendType
backendType() const¶ Gets the backend enum from the underlying TensorAdapter.
- Return
the backend in question
-
template<typename
T>
T &getAdapter() const¶ Gets the underlying tensor adapter implementation.
- Return
the tensor adapter.
-
TensorBackend &
backend() const¶ Return the TensorBackend associated with this tensor.
- Return
a TensorBackend.
-
template<typename
T>
Tscalar() const¶ Return a scalar of a specified type for the tensor.
If the tensor has more than one element, returns the first element as a scalar.
Throws an exception if the specified type does not match the dtype trait of the underlying tensor. To implicitly cast the scalar regardless of the underlying Tensor’s dtype, use
asScalar.- Return
a scalar of the first element in the tensor.
-
template<typename
T>
TasScalar() const¶ Return a scalar of the specified type of the tensor.
If the specified type does not match the tensor’s underlying dtype, the scalar value is implicitly cast.
- Return
a scalar of the first element in the tensor cast to the specified type.
-
template<typename
T>
T *device() const¶ Return a pointer to the tensor’s underlying data per a certain type.
This pointer exists on the computation device.
-
template<typename
T>
voiddevice(T **ptr) const¶ Populate a pointer value with the address of a Tensor’s underlying buffer on the computation device.
-
template<typename
T>
T *host() const¶ Returns a pointer to the tensor’s underlying data, but on the host.
If the tensor is located on a device, makes a copy of device memory and returns a buffer on the host containing the relevant memory.
- Return
the requested pointer on the host.
-
template<typename
T>
voidhost(T *ptr) const¶ Populates an existing buffer with the tensor’s underlying data, but on the host.
If the tensor is located on a device, makes a copy of device memory and returns a buffer on the host containing the relevant memory.
- Parameters
[in] ptr: a pointer to the region of memory to populate with tensor values
-
template<typename
T>
std::vector<T>toHostVector() const¶ Returns a vector on the host contaning a flat representation of the tensor.
The resulting vector is a copy of the underlying tensor memory, even if on the host.
- Return
a vector in host memory containing
-
void
unlock() const¶ Unlocks any device memory associated with the tensor that was acquired with Tensor::device(), making it eligible to be freed.
-
bool
isLocked() const¶ Returns true if the tensor has been memory-locked per a call to Tensor::device<T>().
After unlocking via Tensor::unlock(), the tensor is no longer locked.
- Return
true if the tensor is locked and a device pointer is active.
-
bool
isContiguous() const¶ Returns if the Tensor is contiguous in its memory-based representation.
- Return
a bool denoting Tensor contiguousness
-
void
setContext(void *data)¶ Stores arbitrary data on a tensor.
For internal use/benchmarking only. This may be a no-op for some backends.
- Parameters
[in] data: a pointer to arbitrary data to pass to a tensor impl.
-
void *
getContext() const¶ Gets arbitrary data stored on a tensor.
For internal use/benchmarking only. This may be a no-op for some backends.
- Return
a pointer to some implementation-defined data, else nullptr if a no-op.
Public Static Functions
-
template<typename
T>
static TensorfromVector(Shape s, std::vector<T> v)¶ Create a tensor from a vector of values.
- Return
a tensor with values and shape as given.
- Parameters
[in] s: the shape of the resulting tensor.[in] v: values with which to populate the tensor.
-
template<typename
T>
static TensorfromBuffer(Shape s, const T *ptr, Location memoryLocation)¶ Create a tensor from an existing buffer.
- Return
a tensor with values and shape as given.
- Parameters
[in] s: the shape of the resulting tensor.[in] ptr: the buffer containing the data[in] memoryLocation: the location in memory where the input buffer with which to create the tensor resides.
-
static Tensor
fromBuffer(Shape s, fl::dtype t, const uint8_t *ptr, Location memoryLocation)¶ Create a tensor from an existing byte buffer given a type.
- Return
a tensor with values and shape as given.
- Parameters
[in] s: the shape of the resulting tensor.[in] t: the type of the underlying tensor[in] ptr: the buffer of bytes containing the data[in] memoryLocation: the location in memory where the input buffer with which to create the tensor resides.
-
Indexing¶
Flashlight Tensors can be indexed by index literal values, ranges, spans (fl::span) or other Tensors (advanced indexing).
-
class
range¶ An entity representing a contiguous or strided sequence of indices.
Assuming an axis has N elements, this is the mapping from negative to positive indices:
| -N | -N+1 | … | -1 |
| 0 | 1 | … | N-1 |
Public Functions
-
range()¶ Default ctor.
-
range(const Dim &idx)¶ Construct a range with the indices [0, idx) (i.e.
[0, idx - 1])
- Parameters
[in] idx: the end index of the range, which will start from 0
-
range(const Dim &start, const idx &end)¶ Construct a range with the indices [start, end) (i.e.
[start, end - 1])
- Parameters
[in] start: the starting index of the range[in] end: the end index of the range, which will start from 0
-
range(const Dim &start, const idx &end, const Dim stride)¶ Construct a range with the indices [start, end) (i.e.
[start, end - 1]) with the given stride.
- Parameters
[in] start: the starting index of the range[in] end: the end index of the range, which will start from 0[in] stride: the interval over which successive range elements appear
-
-
struct
Index¶ An entity used to index a tensor.
An index can be of a few different types, which are implicitly converted via Index’s constructors:
fl::Tensor if doing advanced indexing, where elements from a tensor are indexed based on values in the indexing tensor
fl::range which refers to a contiguous (or strided) sequence of indices.
An index literal, which refers to a single subtensor of the tensor being indexed.
Functions on Tensors¶
-
enum
tensor_functions::PadType¶ Padding types for the pad operator.
Values:
-
Constant¶ pad with a constant zero value.
-
Edge¶ pad with the values at the edges of the tensor
-
Symmetric¶ pad with a reflection of the tensor mirrored along each edge
-
-
enum
tensor_functions::SortMode¶ Sorting mode for sorting-related functions.
Values:
-
Descending= 0¶
-
Ascending= 1¶
-
-
enum
tensor_functions::MatrixProperty¶ Transformations to apply to Tensors (i.e. matrices) before applying certain operations (i.e. matmul).
Values:
-
None= 0¶
-
Transpose= 1¶
-
-
template<typename
T>
Tensorfl::fromScalar(const T &val, const dtype type = dtype_traits<T>::ctype)¶ Creates a new scalar Tensor with a particular value.
Scalar tensors have an empty Shape and 1 element by definition.
- Return
a tensor of the specified shape filled with the specified value
- Parameters
[in] val: the value with which to fill the tensor[in] type: the type of the tensor to create. Defaults to a value based on the value type
-
template<typename
T>
Tensorfl::full(const Shape &dims, const T &val, const dtype type = dtype_traits<T>::ctype)¶ Creates a new Tensor with a given Shape and filled with a particular value.
- Return
a tensor of the specified shape filled with the specified value
- Parameters
[in] dims: the shape of the tensor to create[in] val: the value with which to fill the tensor[in] type: the type of the tensor to create. Defaults to a value based on the value type
-
Tensor
fl::identity(const Dim dim, const dtype type = dtype::f32)¶ Return a the identity tensor of a given size and type.
- Parameters
[in] dim: the size of the dimension of the matrix (dim x dim)[in] type: the type of the resulting matrix
-
template<typename
T>
Tensorfl::arange(const T &start, const T &end, const T &step = 1, const dtype type = dtype_traits<T>::ctype)¶ Return evenly-spaced values in a given interval.
Generate values in the interval
[start, stop)steppping each element by the passed step.- Return
a tensor containing the evenly-spaced values
- Parameters
[in] start: the start of the range[in] end: the end of the range, inclusive[in] step: the increment for each consecutive value in the range[in] type: the dtype of the resulting tensor
-
Tensor
fl::arange(const Shape &shape, const Dim seqDim = 0, const dtype type = dtype::f32)¶ Create a tensor with [0, N] values along dimension given by seqDim and tiled along the other dimensions.
N is equal to the size of the shape along the seqDim dimension.
- Return
a tensor with the given shape with the sequence along the given dimension, tiled along other dimensions.
- Parameters
[in] shape: the shape of the output tensor.[in] seqDim: (optional) the dimension along which the sequence increases[in] type: (optional) the dtype of the resulting tensor
-
Tensor
fl::iota(const Shape &dims, const Shape &tileDims = {1}, const dtype type = dtype::f32)¶ Creates a sequence with the range
[0, dims.elements())sequentially in the shape given by dims, then tiles the result along the specified tile dimensions.TODO: this is an AF-specific function.
- Return
- Parameters
[in] dims: the dimensions of the range[in] tileDims: the dimensions along which to tile[in] type: the dtype of the resulting tensoe
-
Tensor
fl::reshape(const Tensor &tensor, const Shape &shape)¶ Change a tensor’s shape without changing its underlying data.
- Return
the reshaped tensor
- Parameters
[in] tensor: the tensor to reshape[in] shape: the new shape for the tensor
-
Tensor
fl::transpose(const Tensor &tensor, const Shape &axes = {})¶ Permute the axes of a tensor.
If no arguments are given, reverses the axes of a tensor.
- Return
the permuted tensor
- Parameters
[in] tensor: the tensor to transpose[in] axes: (optional) the permuted indices of the tensor the kth access of the output tensor will correspond to dims[k] in the input tensor. If this argument is not passed, the axes of the input tensor will be reversed.
-
Tensor
fl::tile(const Tensor &tensor, const Shape &shape)¶ Repeat the contents of a tensor a given number of times along specified dimensions.
- Return
the tiled tensor
- Parameters
[in] tensor: the tensor to tile[in] shape: the number of times, along each dimension, which to tile the tensor
-
Tensor
fl::concatenate(const std::vector<Tensor> &tensors, const unsigned axis = 0)¶ Join or concatenate tensors together along a particular axis.
- Return
a concatenated tensor
- Parameters
[in] tensors: a vector of tensors to concatenate[in] axis: the axis along which to concatenate tensors
-
template<typename ...
Ts>
Tensorfl::concatenate(unsigned axis, const Ts&... args)¶ Join or concatenate tensors together along a particular axis.
- Return
a concatenated tensor
- Parameters
[in] axis: the axis along which to concatenate tensors[in] args: tensors to concatenate
-
Tensor
fl::nonzero(const Tensor &tensor)¶ Return the indices of elements that are non-zero.
Indices correspond to a flattened version of the input tensor.
- Return
a tensor containing the indices of the nonzero elements
- Parameters
[in] tensor: input tensor
-
Tensor
fl::pad(const Tensor &input, const std::vector<std::pair<int, int>> &padWidths, const PadType type = PadType::Constant)¶ Pad a tensor with zeros.
- Return
the padded tensor
- Parameters
[in] input: the input tensor to pad[in] padWidths: a vector of tuples representing padding (before, after) tuples for each axis[in] type: the padding mode with which to pad the tensor - seePadType
-
Tensor
fl::negative(const Tensor &tensor)¶ Element-wise negation of a tensor.
- Return
a tensor with elements negated.
- Parameters
[in] tensor: the input tensor to negate.
-
Tensor
fl::logicalNot(const Tensor &tensor)¶ Performs element-wise logical-not on the elements of a tensor.
- Return
a tensor with element-wise logical not of the input
- Parameters
[in] tensor: the tensor on which to perform logical not
-
Tensor
fl::exp(const Tensor &tensor)¶ Compute the element-wise exponential of a tensor.
- Return
the exponentiated tensor
- Parameters
[in] tensor: the tensor to exponentiate
-
Tensor
fl::log(const Tensor &tensor)¶ Compute the element-wise natural logarithm of a tensor.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::log1p(const Tensor &tensor)¶ Returns the natural logarithm of one plus the input, element-wise.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::sin(const Tensor &tensor)¶ Returns the element-wise sine of the input.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::cos(const Tensor &tensor)¶ Returns the element-wise cosine of the input.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::sqrt(const Tensor &tensor)¶ Returns the element-wise non-negative square root of the input.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::tanh(const Tensor &tensor)¶ Returns the element-wise hyperbolic tangent of the input.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::floor(const Tensor &tensor)¶ Returns the element-wise floor of the input.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute the floor
-
Tensor
fl::ceil(const Tensor &tensor)¶ Returns the element-wise ceiling of the input.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute the ceiling
-
Tensor
fl::rint(const Tensor &tensor)¶ Returns the tensor with element-wise rounding to the nearest integer.
- Return
the resulting tensor
- Parameters
[in] tensor: the input tensor
-
Tensor
fl::absolute(const Tensor &tensor)¶ Returns the element-wise absolute value of the input.
- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::sigmoid(const Tensor &tensor)¶ Returns the element-wise sigmoid the input:
\[ out_i = \frac{1}{1 + \exp(-var_i)} \].- Return
the resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::erf(const Tensor &tensor)¶ Computes the element-wise error function the input: see here for details.
- Return
ther resulting tensor
- Parameters
[in] tensor: the tensor on which to compute
-
Tensor
fl::flip(const Tensor &tensor, const unsigned dim)¶ Flip a Tensor along a specified dimension.
- Return
the resulting flipped tensor
- Parameters
[in] tensor: the tensor on which to compute[in] dim: the dimension along which to flip the tensor
-
Tensor
fl::clip(const Tensor &tensor, const Tensor &low, const Tensor &high)¶ Clip (limit) the values of a tensor.
Given some interval of values, set values outside of that interval to be the boundaries of the interval. All values larger than the max become the max, and all values smaller than the min become the min.
TODO: consider requiring broadcasting behavior/enforcing in a test
- Return
a tensor with all values clipped between high and low
- Parameters
[in] tensor: the tensor to clip[in] low: a tensor containing[in] high:
-
Tensor
fl::roll(const Tensor &tensor, const int shift, const unsigned axis)¶ Rolls (or shifts) a tensor by a certain amount along a given axis, moving elements that would be shifted out of bounds to the beginning of the axis in a circular fashion.
- Return
a tensor with values shifted by the given amount in a circular fashion
- Parameters
[in] tensor: the tensor to roll shift[in] shift: the amount by which to shift[in] axis: the axis along which to perform the shift
-
Tensor
fl::isnan(const Tensor &tensor)¶ Returns a boolean tensor which is true where the input tensor was NaN, and false otherwise.
- Return
a boolean tensor with true in positions that contained NaN in the input tensor
- Parameters
[in] tensor: the input tensor
-
Tensor
fl::isinf(const Tensor &tensor)¶ Returns a boolean tensor which is true where the input tensor was infinity, and false otherwise.
- Return
a boolean tensor with true in positions that contained Inf in the input tensor
- Parameters
[in] tensor: the input tensor
-
Tensor
fl::sign(const Tensor &tensor)¶ Returns a tensor that contains -1 if an element is less than 0, 0 if an element is 0, and 1 if an element is greater than zero.
Returns NaN for NaN values.
- Return
a tensor containing element-wise sign values.
- Parameters
[in] tensor: the input tensor
-
Tensor
fl::tril(const Tensor &tensor)¶ Returns an upper triangular version of the tensor.
For tensors that have greater than two dimensions, this function outputs a tensor with lower triangular submatrices along the last two dimensions of the input tensor.
- Return
a copy of the input tensor with elements above the diagonal zeroed out
- Parameters
[in] tensor: the input tensor
-
Tensor
fl::triu(const Tensor &tensor)¶ Returns an upper triangular version of the tensor.
For tensors that have greater than two dimensions, this function outputs a tensor with upper triangular submatrices along the last two dimensions of the input tensor.
- Return
a copy of the input tensor with elements below the diagonal zeroed out
- Parameters
[in] tensor: the input tensor
-
Tensor
fl::where(const Tensor &condition, const Tensor &x, const Tensor &y)¶ Conditionally return elements from one of two tensors based on a condition.
- Return
the resulting tensor that contains elements of x where condition is true and elements of y where condition is false.
- Parameters
[in] condition: a tensor that, where true, uses values from x positionally, else values from y. This tensor must be of type dtype::b8 else an exception is thrown.[in] x: the tensor from which values are chosen for true values in condition[in] y: the tensor from which values are chosen for false values in condition
-
void
fl::topk(Tensor &values, Tensor &indices, const Tensor &input, const unsigned k, const Dim axis, const SortMode sortMode = SortMode::Descending)¶ Get the top-k values and indices from a Tensor.
- Parameters
[out] values: the sorted tensor[out] indices: the indices corresponding to the sorted ordering[in] input: the input tensor to sort[in] k: the top number of elements to return[in] axis: the axis along which to sort.[in] sortMode: the ordering with which to sort. In descending mode, the topk highest values are returned; else the topk lowest values are returned. Defaults to descending.
-
Tensor
fl::sort(const Tensor &input, const Dim axis, const SortMode sortMode = SortMode::Ascending)¶ Sort the values of a tensor, and return the sorted tensor.
- Parameters
[in] input: the input Tensor[in] axis: the axis along which to sort[in] sortMode: the ordering with which to sort. Defaults to ascending
-
void
fl::sort(Tensor &values, Tensor &indices, const Tensor &input, const Dim axis, const SortMode sortMode = SortMode::Ascending)¶ Sort the values of a tensor, and return the sorted tensor and sorted indices.
- Parameters
[out] values: the sorted tensor[out] indices: the indices corresponding to the sorted ordering[in] input: the input Tensor[in] axis: the axis along which to sort[in] sortMode: the ordering with which to sort. Defaults to ascending
-
Tensor
fl::argsort(const Tensor &input, const Dim axis, const SortMode sortMode = SortMode::Ascending)¶ Sort the values of a tensor and return the sorted indices.
- Parameters
[in] input: the input Tensor[in] axis: the axis along which to sort[in] sortMode: the ordering with which to sort. Defaults to ascending
-
Tensor
fl::minimum(const Tensor &lhs, const Tensor &rhs)¶ Returns the element-wise minimum of tensor elements.
TODO: consider requiring broadcasting behavior/enforcing in a test
- Return
a tensor containing the minimum values in each tensor
- Parameters
[in] lhs: left hand side tensor for the minimum[in] rhs: right hand side tensor for the minimum
-
Tensor
fl::maximum(const Tensor &lhs, const Tensor &rhs)¶ Returns the element-wise maximum of tensor elements.
TODO: consider requiring broadcasting behavior/enforcing in a test
- Return
a tensor containing the maximum values in each tensor
- Parameters
[in] lhs: left hand side tensor for the minimum[in] rhs: right hand side tensor for the minimum
-
Tensor
fl::power(const Tensor &lhs, const Tensor &rhs)¶ Returns the element-wise exponentiation of tensors; the left hand tensor is exponentiated to the power of the right hand tensor, element-wise.
- Return
a tensor containing the exponentiated values
- Parameters
[in] lhs: the base tensor[in] rhs: the exponent tensor
-
Tensor
fl::matmul(const Tensor &lhs, const Tensor &rhs, MatrixProperty lhsProp = MatrixProperty::None, MatrixProperty rhsProp = MatrixProperty::None)¶ Perform matrix multiplication between two tensors.
- Return
an output tensor containing the matrix product.
- Parameters
-
Tensor
fl::amin(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Compute the minimum value along multiple axes.
If axes is left empty, computes the minumum along all axes.
- Return
a tensor containing the max(es)
- Parameters
[in] input: the input along which to operate[in] axes: the dimension along which to reduce. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::amax(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Compute the maximum value along multiple axes.
If axes is left empty, computes the maximum along all axes.
- Return
a tensor containing the max(es)
- Parameters
[in] input: the input along which to operate[in] axes: the dimension along which to reduce. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
void
fl::min(Tensor &values, Tensor &indices, const Tensor &input, const unsigned axis, const bool keepDims = false)¶ Compute the maximum value along multiple axes for a tensor, returning both the maximum values and the indices of the input tensor in which they appear.
- Parameters
[out] values: a Tensor into which to populate the max values from the tensor along the specified axes[out] indices: a Tensor into which to populate the indices of the max values from the tensor along the specified axes[in] input: the input tensor[in] axis: the axis along which to find minimum values[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
void
fl::max(Tensor &values, Tensor &indices, const Tensor &input, const unsigned axis, const bool keepDims = false)¶ Compute the maximum value along multiple axes for a tensor, returning both the maximum values and the indices of the input tensor in which they appear.
- Parameters
[out] values: a Tensor into which to populate the max values from the tensor along the specified axes[out] indices: a Tensor into which to populate the indices of the max values from the tensor along the specified axes[in] input: the input tensor[in] axis: the axis along which to find maximum values[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::argmax(const Tensor &input, const unsigned axis, const bool keepDims = false)¶ Return the indices of the maximum values along an axis.
- Return
a tensor containing the indices of the max values along each axis
- Parameters
[in] input: the input tensor[in] axis: the axis along which to find maximum values[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::argmin(const Tensor &input, const unsigned axis, const bool keepDims = false)¶ Return the indices of the minimum values along an axis.
- Return
a tensor containing the indices of the max values along each axis
- Parameters
[in] input: the input tensor[in] axis: the axis along which to find minimum values[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::sum(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Sum of tensor over given axes.
If axes is left empty, computes the sum along all axes.
- Return
a tensor containing the sum(s)
- Parameters
[in] input: the input along which to operate[in] axes: the dimension along which to reduce. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::cumsum(const Tensor &input, const unsigned axis)¶ Compute the cumulative sum (or the prefix sum, scan, or inclusive scan) of a tensor along a given axis.
- Return
a tensor of the same shape containing the accumulated sum
- Parameters
[in] input: the input tensor[in] axis: the axis along which to accumulate
-
Tensor
fl::mean(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Mean of tensor over given axes.
If axes is left empty, computes the mean along all axes.
- Return
a tensor containing the mean(s)
- Parameters
[in] input: the input along which to operate[in] axes: the dimension along which to reduce. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::median(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Median of tensor over given axes.
If axes is left empty, computes the median along all axes.
- Return
a tensor containing the median(s)
- Parameters
[in] input: the input along which to operate[in] axes: the dimension along which to reduce. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::var(const Tensor &input, const std::vector<int> &axes = {}, const bool bias = false, const bool keepDims = false)¶ Variance of an tensor over given axes.
If axes is left empty, computes the variance along all axes.
- Return
a tensor containing the variance(s)
- Parameters
[in] input: the input along which to operate[in] axes: the dimension along which to reduce. If empty, computes along all axes[in] bias: defaults false. Compute biased or unbiased variance[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::std(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Standard deviation of an tensor over given axes.
If axes is left empty, computes the standard deviation along all axes.
- Return
a tensor containing the standard deviation(s)
- Parameters
[in] input: the input along which to operate[in] axes: the dimension along which to reduce. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::norm(const Tensor &input, const std::vector<int> &axes = {}, double p = 2, const bool keepDims = false)¶ Perform Lp-norm computation, reduced over specified dimensions.
If axes is left blank, computes the norm along all dimensions.
- Return
a tensor containing the norm(s)
- Parameters
[in] input: tensor on which the Lp norm is going to be computed.[in] p: the p value of the Lp norm.[in] axes: dimensions over which the reduction is performed.[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::countNonzero(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Counts the number of nonzero elements in a tensor.
If k axes are passed, returns a tensor of size k with element-wise nonzero counts along each axis.
- Return
a tensor containing the number of nonzero elements along each axis or over the entire tensor.
- Parameters
[in] input: the tensor on which to operate.[in] axes: (optional) the axis along which to give nonzeros.[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::any(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Checks for any true values in a tensor along one or more axes; returns true if any exist.
If k axes are passed, returns a tensor of size k with truthiness checks along each axis. If axes is left empty, computes the variance along all axes.
- Return
a bool tensor containing axis-wise values denoting truthy values along that axis in the input tensor.
- Parameters
[in] input: the input tensor[in] axes: the axes along which to check for truthy values. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
Tensor
fl::all(const Tensor &input, const std::vector<int> &axes = {}, const bool keepDims = false)¶ Checks if all values are true in a tensor along one or more axes; returns true if all are true and false otherwise.
If k axes are passed, returns a tensor of size k with all-true checks along each axis. If axes is left empty, computes the variance along all axes.
- Return
a bool tensor containing axis-wise values with true along axes that contain only true values.
- Parameters
[in] input: the input tensor[in] axes: the axes along which to check. If empty, computes along all axes[in] keepDims: defaults false. Keeps the dimensions being reduced over as singleton dimensions rather than collapsing them
-
std::ostream &
fl::operator<<(std::ostream &ostr, const Tensor &t)¶ Write a string representation of a tensor to an output stream.
-
void
fl::print(const Tensor &tensor)¶ Print a string representation of a tensor to standard out.
- Parameters
[in] tensor: the tensor to print
-
bool
fl::allClose(const fl::Tensor &a, const fl::Tensor &b, const double absTolerance = 1e-5)¶ Returns of two tensors are close.
Checks:
- Parameters
[in] a: lhs tensor[in] b: rhs tensor[in] absTolerance: the maximum-allowable distance between the tensors
-
std::string
fl::tensorBackendTypeToString(const TensorBackendType type)¶ Get a string representation of a tensor backend type.
- Return
a string representing the given tensor backend type.
- Parameters
[in] type: the tensor backend type.
-
std::ostream &
fl::operator<<(std::ostream &os, const TensorBackendType type)¶ Write a string representation of a tensor backend type to an output stream.
- Return
the output stream.
- Parameters
[out] os: the output stream.[in] type: the tensor backend type.
-
template<typename
T>
Tensorfl::to(Tensor &&t)¶ Convert a tensor from one type to another.
Requires moving the input Tensor
destroys the resulting tensor and creates another tensor of the desired tensor type.
- Return
a tensor backed by the specified compile time type
- Parameters
[in] t: the tensor to convert
-
FL_BINARY_OP_LITERAL_TYPE_DECL(OP, FUNC, TYPE)¶
-
FL_BINARY_OP_LITERALS_DECL(OP, FUNC)¶
-
FL_BINARY_OP_DECL(OP, FUNC)¶