NumericAL
A header-only C++20 lexer built on REAL
Loading...
Searching...
No Matches
Classes | Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
numerical::tensor< T > Class Template Reference

A dense N-dimensional tensor of T with value semantics, read row-major. Its elements are immutable once built, so tensors share them: a copy, a tensor of another shape over the same elements (reshaped), one with its axes permuted (transposed) and a slice of them (sliced), views reading them along other strides, hold the one buffer, freed with the last of them. A view's elements in row-major order (data) are copied out on first need, once, and shared with the view's copies. More...

#include <tensor.hpp>

Classes

struct  row_major_copy
 A view's elements in row-major order, copied out by the first data call and shared with the view's copies. More...
 

Public Member Functions

 tensor (std::vector< std::size_t > shape, buffer< T > elements)
 From a shape and a flat row-major buffer.
 
 tensor (std::vector< std::size_t > shape, const std::vector< T > &elements)
 From a shape and a flat row-major std::vector, copied into the storage (a buffer moves in instead).
 
 tensor (std::vector< std::size_t > shape, std::initializer_list< T > elements)
 From a shape and a braced list of the elements, row-major.
 
 tensor (const vector< T > &v)
 A rank-1 tensor from a vector.
 
 tensor (matrix< T > &&m)
 A rank-2 tensor taking over an expiring matrix's elements, without a copy.
 
 tensor (const matrix< T > &m)
 A rank-2 tensor from a matrix.
 
tensor reshaped (std::vector< std::size_t > shape) const
 This tensor's elements in shape, without a copy: the new tensor shares the buffer, as NumPy's reshape of a contiguous array is a view. A view's are read where they lie where NumPy's reshape of it is a view too (reshaped_strides; axes of extent 1 put in or taken out, an axis split, axes whose elements lie one stride from the next joined); else they are its row-major copy (data), made if not yet made.
 
tensor transposed (const std::vector< std::size_t > &axes) const
 This tensor with its axes in the order axes (axis k of the result is axis axes[k] of this one), without a copy, as NumPy's transpose: a view over the same elements, whose row-major copy (data) is made on first need. A permutation that leaves them row-major (one that moves only axes of extent 1, or undoes an earlier one) gives a tensor that shares them as they lie.
 
template<typename Keep = std::vector<bool>>
tensor sliced (const std::vector< std::size_t > &starts, const std::vector< std::ptrdiff_t > &steps, const std::vector< std::size_t > &counts, const Keep &keep) const
 The elements starts[a] + i·steps[a] for i < counts[a] along each axis a, without a copy, as NumPy's basic slicing: a view over the same elements, whose row-major copy (data) is made on first need. An axis whose keep is false (an integer index, its count 1) is dropped from the result's shape. A step may be negative (::-1); a count of 0 gives an empty tensor.
 
tensor diagonal_view (std::size_t row, std::size_t column, std::size_t length) const
 The length elements from (row, column) down the diagonal of each matrix (the last two axes), without a copy: a view over the same elements, the batch's axes then the diagonal's, whose row-major copy (data) is made on first need; a few elements copied at once, as sliced.
 
std::optional< std::pair< tensor, std::vector< std::size_t > > > laid_out () const
 Where this view reaches each of its elements once from the first (a transpose's, transposed): its axes in the order the elements lie (the widest stride first), with the tensor over those elements row-major in that order, no element copied; nothing for a tensor laid out row-major or any other view. Along each axis the elements are the same, in the same order: what is computed line by line along an axis of this view is computed along the matching axis of the laid out tensor.
 
tensor transposed () const
 transposed with the axes reversed: a matrix's transpose, NumPy's .T.
 
std::size_t rank () const noexcept
 The number of axes (0 for a scalar).
 
std::size_t size () const noexcept
 The total number of elements.
 
const std::vector< std::size_t > & shape () const noexcept
 The size of each axis.
 
const T * origin () const noexcept
 The first element where the elements are held (index 0 along every axis): a view (transposed, sliced) reads the others along strides from it. Past the end of nothing for an empty tensor.
 
const std::vector< std::ptrdiff_t > & strides () const noexcept
 Each axis's step, in elements, from the first element (origin), row-major unless a view, negative along an axis a view reverses.
 
bool contiguous () const noexcept
 Whether the elements lie row-major where they are held: data then copies nothing.
 
tensor materialized () const
 This tensor holding its own elements row-major and nothing more: itself where they lie so, else its row-major copy (data) without the view's base, which no longer stays alive through it (a copy of a slice of a large array frees that array, as ndarray.copy's does).
 
const buffer< T > & data () const
 The elements, row-major. A view's (transposed) are copied out by the first call, one thread copying while any other waits, and kept for the later calls and for the view's copies.
 
const T & operator() (const std::vector< std::size_t > &index) const
 The element at a multi-index, read where it lies.
 
bool operator== (const tensor &other) const
 Exact equality (same shape and equal elements).
 

Private Member Functions

std::vector< std::size_t > lying_order () const
 This view's axes from the widest stride to the narrowest, ties in their order.
 
bool permutes_elements () const
 Whether this view reaches every element of its buffer once, from the first: its axes longer than 1, from the widest stride to the narrowest, have the strides of a row-major tensor of those extents (a transpose's). A slice that only starts at the first element and counts as many (a step of 0 repeating a row, a reversed axis of extent 1 beside a longer one) reaches some elements twice and others never: not one.
 
 tensor (std::vector< std::size_t > shape, std::shared_ptr< const buffer< T > > elements)
 Over the shared row-major elements elements, in shape (reshaped).
 
 tensor (std::vector< std::size_t > shape, std::vector< std::ptrdiff_t > strides, std::size_t offset, std::shared_ptr< const buffer< T > > elements)
 Over the shared elements elements, read along strides from the element at offset (transposed, sliced): a view, unless they are the whole of elements, row-major along the axes longer than 1, or none.
 
std::optional< std::vector< std::ptrdiff_t > > reshaped_strides (const std::vector< std::size_t > &shape) const
 The strides that read this view's elements, in row-major order, under shape (as many elements), as NumPy's reshape without a copy finds them; nothing where none do. The axes longer than 1 of each, in order, are cut into runs of equal counts of elements: a run of this view's axes is read as one where each axis but its last steps by the next one's whole extent, the run of shape's axes then row-major over the last one's stride. An axis of extent 1 moves nothing: any stride.
 
const buffer< T > & copied_out () const
 A view's elements in row-major order, copied out on the first call.
 
void finalize ()
 Computes row-major strides and checks the buffer against the shape.
 

Static Private Member Functions

static buffer< T > gathered (const std::vector< std::size_t > &shape, const std::vector< std::ptrdiff_t > &strides, std::size_t offset, const buffer< T > &data)
 The elements of data in shape, read along strides from offset, in row-major order: row after row along the last axis (a run as it lies copied as one), the rows on the threads where they are many.
 

Private Attributes

std::vector< std::size_t > shape_
 The size of each axis.
 
std::vector< std::ptrdiff_t > strides_
 Each axis's step from origin_: row-major unless a view.
 
std::shared_ptr< const buffer< T > > data_
 The elements, shared with the tensors that hold them.
 
std::size_t offset_ {0}
 Where in data_ the first element lies (a view's, sliced).
 
std::size_t count_ {0}
 The number of elements: data_'s, unless a view.
 
std::shared_ptr< row_major_copy > copy_
 A view's row-major copy; null where the elements lie row-major.
 

Detailed Description

template<typename T>
class numerical::tensor< T >

A dense N-dimensional tensor of T with value semantics, read row-major. Its elements are immutable once built, so tensors share them: a copy, a tensor of another shape over the same elements (reshaped), one with its axes permuted (transposed) and a slice of them (sliced), views reading them along other strides, hold the one buffer, freed with the last of them. A view's elements in row-major order (data) are copied out on first need, once, and shared with the view's copies.

Template Parameters
TThe scalar element type.

Definition at line 87 of file tensor.hpp.

Constructor & Destructor Documentation

◆ tensor() [1/8]

template<typename T >
numerical::tensor< T >::tensor ( std::vector< std::size_t >  shape,
buffer< T >  elements 
)
inline

From a shape and a flat row-major buffer.

Parameters
[in]shapeThe size of each axis (empty ⇒ a rank-0 scalar).
[in]elementsThe prod(shape) elements, row-major (moved in).
Exceptions
dimension_errorIf elements.size() is not prod(shape).

Definition at line 97 of file tensor.hpp.

◆ tensor() [2/8]

template<typename T >
numerical::tensor< T >::tensor ( std::vector< std::size_t >  shape,
const std::vector< T > &  elements 
)
inline

From a shape and a flat row-major std::vector, copied into the storage (a buffer moves in instead).

Parameters
[in]shapeThe size of each axis.
[in]elementsThe prod(shape) elements, row-major.
Exceptions
dimension_errorIf elements.size() is not prod(shape).

Definition at line 110 of file tensor.hpp.

◆ tensor() [3/8]

template<typename T >
numerical::tensor< T >::tensor ( std::vector< std::size_t >  shape,
std::initializer_list< T >  elements 
)
inline

From a shape and a braced list of the elements, row-major.

Definition at line 117 of file tensor.hpp.

◆ tensor() [4/8]

template<typename T >
numerical::tensor< T >::tensor ( const vector< T > &  v)
inlineexplicit

A rank-1 tensor from a vector.

Parameters
[in]vThe vector.

Definition at line 124 of file tensor.hpp.

◆ tensor() [5/8]

template<typename T >
numerical::tensor< T >::tensor ( matrix< T > &&  m)
inlineexplicit

A rank-2 tensor taking over an expiring matrix's elements, without a copy.

Parameters
[in]mThe matrix. The members are initialised in their order, the extents before the elements move: a call's arguments, and MSVC's braced lists, have none.

Definition at line 132 of file tensor.hpp.

◆ tensor() [6/8]

template<typename T >
numerical::tensor< T >::tensor ( const matrix< T > &  m)
inlineexplicit

A rank-2 tensor from a matrix.

Parameters
[in]mThe matrix.

Definition at line 139 of file tensor.hpp.

◆ tensor() [7/8]

template<typename T >
numerical::tensor< T >::tensor ( std::vector< std::size_t >  shape,
std::shared_ptr< const buffer< T > >  elements 
)
inlineprivate

Over the shared row-major elements elements, in shape (reshaped).

Definition at line 435 of file tensor.hpp.

◆ tensor() [8/8]

template<typename T >
numerical::tensor< T >::tensor ( std::vector< std::size_t >  shape,
std::vector< std::ptrdiff_t >  strides,
std::size_t  offset,
std::shared_ptr< const buffer< T > >  elements 
)
inlineprivate

Over the shared elements elements, read along strides from the element at offset (transposed, sliced): a view, unless they are the whole of elements, row-major along the axes longer than 1, or none.

Definition at line 445 of file tensor.hpp.

Member Function Documentation

◆ contiguous()

template<typename T >
bool numerical::tensor< T >::contiguous ( ) const
inlinenoexcept

Whether the elements lie row-major where they are held: data then copies nothing.

Definition at line 346 of file tensor.hpp.

◆ copied_out()

template<typename T >
const buffer< T > & numerical::tensor< T >::copied_out ( ) const
inlineprivate

A view's elements in row-major order, copied out on the first call.

Definition at line 522 of file tensor.hpp.

◆ data()

template<typename T >
const buffer< T > & numerical::tensor< T >::data ( ) const
inline

The elements, row-major. A view's (transposed) are copied out by the first call, one thread copying while any other waits, and kept for the later calls and for the view's copies.

Exceptions
std::bad_allocIf a view finds no memory for its copy (a later call tries again).

Definition at line 370 of file tensor.hpp.

◆ diagonal_view()

template<typename T >
tensor numerical::tensor< T >::diagonal_view ( std::size_t  row,
std::size_t  column,
std::size_t  length 
) const
inline

The length elements from (row, column) down the diagonal of each matrix (the last two axes), without a copy: a view over the same elements, the batch's axes then the diagonal's, whose row-major copy (data) is made on first need; a few elements copied at once, as sliced.

Precondition
The rank is at least 2, and length elements from (row, column) lie in each matrix (any start for a length of 0).

Definition at line 258 of file tensor.hpp.

◆ finalize()

template<typename T >
void numerical::tensor< T >::finalize ( )
inlineprivate

Computes row-major strides and checks the buffer against the shape.

Definition at line 599 of file tensor.hpp.

◆ gathered()

template<typename T >
static buffer< T > numerical::tensor< T >::gathered ( const std::vector< std::size_t > &  shape,
const std::vector< std::ptrdiff_t > &  strides,
std::size_t  offset,
const buffer< T > &  data 
)
inlinestaticprivate

The elements of data in shape, read along strides from offset, in row-major order: row after row along the last axis (a run as it lies copied as one), the rows on the threads where they are many.

Definition at line 563 of file tensor.hpp.

◆ laid_out()

template<typename T >
std::optional< std::pair< tensor, std::vector< std::size_t > > > numerical::tensor< T >::laid_out ( ) const
inline

Where this view reaches each of its elements once from the first (a transpose's, transposed): its axes in the order the elements lie (the widest stride first), with the tensor over those elements row-major in that order, no element copied; nothing for a tensor laid out row-major or any other view. Along each axis the elements are the same, in the same order: what is computed line by line along an axis of this view is computed along the matching axis of the laid out tensor.

Definition at line 291 of file tensor.hpp.

◆ lying_order()

template<typename T >
std::vector< std::size_t > numerical::tensor< T >::lying_order ( ) const
inlineprivate

This view's axes from the widest stride to the narrowest, ties in their order.

Definition at line 394 of file tensor.hpp.

◆ materialized()

template<typename T >
tensor numerical::tensor< T >::materialized ( ) const
inline

This tensor holding its own elements row-major and nothing more: itself where they lie so, else its row-major copy (data) without the view's base, which no longer stays alive through it (a copy of a slice of a large array frees that array, as ndarray.copy's does).

Exceptions
std::bad_allocIf a view finds no memory for its copy.

Definition at line 357 of file tensor.hpp.

◆ operator()()

template<typename T >
const T & numerical::tensor< T >::operator() ( const std::vector< std::size_t > &  index) const
inline

The element at a multi-index, read where it lies.

Precondition
Its length is rank, in bounds.

Definition at line 376 of file tensor.hpp.

◆ operator==()

template<typename T >
bool numerical::tensor< T >::operator== ( const tensor< T > &  other) const
inline

Exact equality (same shape and equal elements).

Definition at line 386 of file tensor.hpp.

◆ origin()

template<typename T >
const T * numerical::tensor< T >::origin ( ) const
inlinenoexcept

The first element where the elements are held (index 0 along every axis): a view (transposed, sliced) reads the others along strides from it. Past the end of nothing for an empty tensor.

Definition at line 333 of file tensor.hpp.

◆ permutes_elements()

template<typename T >
bool numerical::tensor< T >::permutes_elements ( ) const
inlineprivate

Whether this view reaches every element of its buffer once, from the first: its axes longer than 1, from the widest stride to the narrowest, have the strides of a row-major tensor of those extents (a transpose's). A slice that only starts at the first element and counts as many (a step of 0 repeating a row, a reversed axis of extent 1 beside a longer one) reaches some elements twice and others never: not one.

Definition at line 408 of file tensor.hpp.

◆ rank()

template<typename T >
std::size_t numerical::tensor< T >::rank ( ) const
inlinenoexcept

The number of axes (0 for a scalar).

Definition at line 314 of file tensor.hpp.

◆ reshaped()

template<typename T >
tensor numerical::tensor< T >::reshaped ( std::vector< std::size_t >  shape) const
inline

This tensor's elements in shape, without a copy: the new tensor shares the buffer, as NumPy's reshape of a contiguous array is a view. A view's are read where they lie where NumPy's reshape of it is a view too (reshaped_strides; axes of extent 1 put in or taken out, an axis split, axes whose elements lie one stride from the next joined); else they are its row-major copy (data), made if not yet made.

Exceptions
dimension_errorIf shape holds another number of elements.

Definition at line 152 of file tensor.hpp.

◆ reshaped_strides()

template<typename T >
std::optional< std::vector< std::ptrdiff_t > > numerical::tensor< T >::reshaped_strides ( const std::vector< std::size_t > &  shape) const
inlineprivate

The strides that read this view's elements, in row-major order, under shape (as many elements), as NumPy's reshape without a copy finds them; nothing where none do. The axes longer than 1 of each, in order, are cut into runs of equal counts of elements: a run of this view's axes is read as one where each axis but its last steps by the next one's whole extent, the run of shape's axes then row-major over the last one's stride. An axis of extent 1 moves nothing: any stride.

Definition at line 480 of file tensor.hpp.

◆ shape()

template<typename T >
const std::vector< std::size_t > & numerical::tensor< T >::shape ( ) const
inlinenoexcept

The size of each axis.

Definition at line 326 of file tensor.hpp.

◆ size()

template<typename T >
std::size_t numerical::tensor< T >::size ( ) const
inlinenoexcept

The total number of elements.

Definition at line 320 of file tensor.hpp.

◆ sliced()

template<typename T >
template<typename Keep = std::vector<bool>>
tensor numerical::tensor< T >::sliced ( const std::vector< std::size_t > &  starts,
const std::vector< std::ptrdiff_t > &  steps,
const std::vector< std::size_t > &  counts,
const Keep &  keep 
) const
inline

The elements starts[a] + i·steps[a] for i < counts[a] along each axis a, without a copy, as NumPy's basic slicing: a view over the same elements, whose row-major copy (data) is made on first need. An axis whose keep is false (an integer index, its count 1) is dropped from the result's shape. A step may be negative (::-1); a count of 0 gives an empty tensor.

Exceptions
dimension_errorIf the arguments do not hold one entry per axis, or a dropped axis's count is not 1.
index_errorIf a range of a nonzero count leaves its axis.

Definition at line 209 of file tensor.hpp.

◆ strides()

template<typename T >
const std::vector< std::ptrdiff_t > & numerical::tensor< T >::strides ( ) const
inlinenoexcept

Each axis's step, in elements, from the first element (origin), row-major unless a view, negative along an axis a view reverses.

Definition at line 340 of file tensor.hpp.

◆ transposed() [1/2]

template<typename T >
tensor numerical::tensor< T >::transposed ( ) const
inline

transposed with the axes reversed: a matrix's transpose, NumPy's .T.

Definition at line 306 of file tensor.hpp.

◆ transposed() [2/2]

template<typename T >
tensor numerical::tensor< T >::transposed ( const std::vector< std::size_t > &  axes) const
inline

This tensor with its axes in the order axes (axis k of the result is axis axes[k] of this one), without a copy, as NumPy's transpose: a view over the same elements, whose row-major copy (data) is made on first need. A permutation that leaves them row-major (one that moves only axes of extent 1, or undoes an earlier one) gives a tensor that shares them as they lie.

Exceptions
dimension_errorIf axes is not a permutation of the axes.

Definition at line 178 of file tensor.hpp.

Member Data Documentation

◆ copy_

template<typename T >
std::shared_ptr<row_major_copy> numerical::tensor< T >::copy_
private

A view's row-major copy; null where the elements lie row-major.

Definition at line 619 of file tensor.hpp.

◆ count_

template<typename T >
std::size_t numerical::tensor< T >::count_ {0}
private

The number of elements: data_'s, unless a view.

Definition at line 618 of file tensor.hpp.

◆ data_

template<typename T >
std::shared_ptr<const buffer<T> > numerical::tensor< T >::data_
private

The elements, shared with the tensors that hold them.

Definition at line 616 of file tensor.hpp.

◆ offset_

template<typename T >
std::size_t numerical::tensor< T >::offset_ {0}
private

Where in data_ the first element lies (a view's, sliced).

Definition at line 617 of file tensor.hpp.

◆ shape_

template<typename T >
std::vector<std::size_t> numerical::tensor< T >::shape_
private

The size of each axis.

Definition at line 614 of file tensor.hpp.

◆ strides_

template<typename T >
std::vector<std::ptrdiff_t> numerical::tensor< T >::strides_
private

Each axis's step from origin_: row-major unless a view.

Definition at line 615 of file tensor.hpp.


The documentation for this class was generated from the following file: