tannic::Tensor Class Reference

A multidimensional, strided tensor data structure. More...

#include <tensor.hpp>

Public Types
using	rank_type = uint8_t
	Type used for rank (number of dimensions).
using	size_type = std::size_t
	Type used for size and shape dimensions.

Public Member Functions
	Tensor (type dtype, Shape shape)
	Constructs an uninitialized tensor with default (contiguous) strides.
	Tensor (type dtype, Shape shape, Strides strides, std::ptrdiff_t offset=0)
	Constructs an uninitialized tensor with custom strides and offset.
template<Expression Expression>
	Tensor (const Expression &expression)
	Constructs a tensor by forwarding an Expression-like object.
template<Expression Expression>
Tensor &	operator= (const Expression &expression)
	Assigns the result of an expression to the tensor.
	Tensor (type dtype, Shape shape, std::ptrdiff_t offset, std::shared_ptr< Buffer > storage)
	Tensor (type dtype, Shape shape, Strides strides, std::ptrdiff_t offset, std::shared_ptr< Buffer > storage)
Node *	node () const
Metadata Access (May be constexpr in the future.)
type	dtype () const
	Returns the tensor's data type.
rank_type	rank () const
	Returns the number of dimensions (rank) of the tensor.
Shape const &	shape () const
	Returns the tensor's shape (dimension sizes per dimension).
Shape::size_type	size (int dimension) const
	Returns the tensor's size at a given dimension.
Strides const &	strides () const
	Returns the tensor's strides (step sizes per dimension).
std::ptrdiff_t	offset () const
	Returns the offset of the tensor in the current buffer.
std::size_t	nelements () const
	Returns the total number of elements of the tensor.
std::size_t	nbytes () const
	Returns the total number of bytes occupied by the tensor's elements.
bool	is_contiguous () const
	Returns whether the tensor's elements are in contiguous layout or not.
bool	is_singleton () const
Tensor &	forward ()
	Returns a reference to this tensor (const-qualified).
Tensor const &	forward () const
	Returns a reference to this tensor (non-const).
Memory Management (Always runtime.)
void	initialize (Environment environment=Host{}) const
	Allocates the memory buffer for the tensor.
std::byte *	bytes () const
	Returns a pointer to the beginning of the tensor's data (accounting for offset).
bool	is_initialized () const
	Checks whether the tensor has been initialized with memory.
Environment const &	environment () const
	Returns a reference to the environment variant used to allocate this tensor's buffer.
template<typename T >
	Tensor (std::initializer_list< T > const &values)
	@
template<typename T >
	Tensor (std::initializer_list< std::initializer_list< T > > const &values)
	Constructs a 2D tensor from a nested initializer list.
template<typename T >
	Tensor (std::initializer_list< std::initializer_list< std::initializer_list< T > > > const &values)
	Constructs a 3D tensor from a triple-nested initializer list.
template<typename T >
	Tensor (std::initializer_list< std::initializer_list< std::initializer_list< std::initializer_list< T > > > > const &values)
	Constructs a 4D tensor from a quadruple-nested initializer list.
template<typename T >
void	initialize (std::initializer_list< T > values, Environment environment=Host{})
	Assigns values to a 1D tensor from an initializer list.
template<typename T >
void	initialize (std::initializer_list< std::initializer_list< T > > const &values, Environment environment=Host{})
	Assigns values to a 2D tensor from a nested initializer list.
template<typename T >
void	initialize (std::initializer_list< std::initializer_list< std::initializer_list< T > > > const &values, Environment environment=Host{})
	Assigns values to a 3D tensor from a triple-nested initializer list.
template<typename T >
void	initialize (std::initializer_list< std::initializer_list< std::initializer_list< std::initializer_list< T > > > > values, Environment environment=Host{})
	Assigns values to a 4D tensor from a quadruple-nested initializer list.
Indexing, Slicing and Views.
template<Integral Index>
auto	operator[] (Index index) const
	Indexes the tensor with a single integral index.
auto	operator[] (indexing::Range range) const
	Indexes the tensor with a Range object.
template<class ... Indexes>
auto	operator[] (Indexes... indexes) const
	Indexes the tensor with multiple indices (e.g., integers or ranges).
auto	transpose (int first=-1, int second=-2) const
	Returns a view of the tensor with two dimensions transposed.
template<Integral ... Indexes>
auto	permute (Indexes... indexes) const
	Returns a view of the tensor with dimensions permuted.
template<Integral ... Sizes>
auto	view (Sizes... sizes) const
	Returns a view of the tensor with given sizes.
auto	squeeze () const
	Returns a view of the tensor with all dimensions of size 1 removed.
template<Integral... Axes>
auto	unsqueeze (Axes... axes)
	Returns a view of the tensor with a dimension of size 1 inserted at the given axis.

Protected Member Functions
void	assign (std::byte const *, std::ptrdiff_t)
void	assign (bool const *, std::ptrdiff_t)
bool	compare (std::byte const *, std::ptrdiff_t) const

Friends
template<Expression Source, class... Indexes>
class	expression::Slice
template<Expression Source>
class	expression::Transpose
template<Expression Source>
class	expression::View
template<Expression Source>
class	expression::Squeeze
template<Expression Source>
class	expression::Unsqueeze
template<Expression Source, Integral... Indexes>
class	expression::Permutation
template<Expression Source>
class	expression::Expansion
template<Expression Source>
class	expression::Flatten
template<class Coordinates , Expression... Sources>
class	expression::Complexification
template<Expression Source>
class	expression::Realification

Detailed Description

A multidimensional, strided tensor data structure.

The Tensor class is the primary data structure in the Tannic Tensor Library. It represents a dynamic typed intention of a computation. It supports slicing, transposition, and expression composition.

Evaluation Mode:

• Tensors are currently eager : expressions assigned to them are immediately evaluated and stored.
• A lazy constexpr evaluation mode is planned for future versions, enabling compile-time computational graphs.

Memory:

• Host and Device (e.g., CUDA) allocations are supported using environments like Host() or Device().
• Memory can be explicitly allocated via initialize(Host()) or initialize(Device()).

Example:

using namespace tannic; 
 
Tensor X(float32, {2,2}); X.initialize(); // or X.initialize(Device()); for CUDA support   
X[0, range{0,-1}] = 1; 
X[1,0] = 3;
X[1,1] = 4;   
 
Tensor Y(float32, {1,2}); Y.initialize();  // or X.initialize(Device()); for CUDA support   
Y[0,0] = 4;
Y[0,1] = 6;    
 
std::cout << log(X) + Y * Y - exp(X) + matmul(X, Y.transpose());

This example demonstrates eager initialization, advanced indexing, broadcasting, and composite expression evaluation.

Member Typedef Documentation

rank_type

using tannic::Tensor::rank_type = uint8_t

Type used for rank (number of dimensions).

size_type

using tannic::Tensor::size_type = std::size_t

Type used for size and shape dimensions.

Constructor & Destructor Documentation

Tensor() [1/9]

tannic::Tensor::Tensor ( type  dtype, Shape  shape  )

inline

Constructs an uninitialized tensor with default (contiguous) strides.

Parameters

dtype	Data type of the tensor.
shape	Shape (dimensions) of the tensor.

Tensor() [2/9]

tannic::Tensor::Tensor ( type  dtype, Shape  shape, Strides  strides, std::ptrdiff_t  offset = 0  )

inline

Constructs an uninitialized tensor with custom strides and offset.

Parameters

dtype	Data type of the tensor.
shape	Shape of the tensor.
strides	Strides per dimension.
offset	Byte offset from start of underlying memory buffer.

Tensor() [3/9]

template<Expression Expression>

tannic::Tensor::Tensor ( const Expression &  expression )

inline

Constructs a tensor by forwarding an Expression-like object.

Template Parameters

Expression

Expression type satisfying the Expression concept.

Parameters

expression

An expression to evaluate and store as a tensor.

Tensor() [4/9]

template<typename T >

tannic::Tensor::Tensor ( std::initializer_list< T > const &  values )

inline

@

Constructs a 1D tensor from an initializer list.

Template Parameters

T	Element type (deduced from the initializer list).

Parameters

values

A list of values to populate the tensor.

This constructor allows direct construction of 1D tensors using brace-enclosed lists:

Tensor X {1.0f, 2.0f, 3.0f, 4.0f};  // 1D tensor of shape {4}, dtype=float32

The tensor is immediately initialized on host, contiguous in memory, and its dtype is deduced from T.

Tensor() [5/9]

template<typename T >

tannic::Tensor::Tensor ( std::initializer_list< std::initializer_list< T > > const &  values )

inline

Constructs a 2D tensor from a nested initializer list.

Template Parameters

T	Element type (deduced from the nested initializer list).

Parameters

values

A nested list of values (rows) to populate the tensor.

This constructor allows direct construction of 2D tensors:

Tensor Y = {
    {1.0f, 2.0f, 3.0f},
    {4.0f, 5.0f, 6.0f}
};  // 2D tensor of shape {2,3}, dtype=float32

All inner lists (rows) must have the same length. The tensor is contiguous in memory.

Tensor() [6/9]

template<typename T >

tannic::Tensor::Tensor ( std::initializer_list< std::initializer_list< std::initializer_list< T > > > const &  values )

inline

Constructs a 3D tensor from a triple-nested initializer list.

Template Parameters

T	Element type (deduced from the nested lists).

Parameters

values

A triple-nested list of values (matrices) to populate the tensor.

This constructor allows direct construction of 3D tensors:

Tensor Z = {
    {
        {1.0f, 2.0f},
        {3.0f, 4.0f}
    },
    {
        {5.0f, 6.0f},
        {7.0f, 8.0f}
    }
};  // 3D tensor of shape {2,2,2}, dtype=float32

All matrices must have the same number of rows, and all rows must have the same number of columns. The tensor is contiguous in memory.

Tensor() [7/9]

template<typename T >

tannic::Tensor::Tensor ( std::initializer_list< std::initializer_list< std::initializer_list< std::initializer_list< T > > > > const &  values )

inline

Constructs a 4D tensor from a quadruple-nested initializer list.

Template Parameters

T	Element type (deduced from the nested lists).

Parameters

values

A quadruple-nested list of values (tensors) to populate the 4D tensor.

This constructor allows direct construction of 4D tensors:

Tensor X = {
    {
        {
            {1.0f, 2.0f},
            {3.0f, 4.0f}
        },
        {
            {5.0f, 6.0f},
            {7.0f, 8.0f}
        }
    },
    {
        {
            {9.0f, 10.0f},
            {11.0f, 12.0f}
        },
        {
            {13.0f, 14.0f},
            {15.0f, 16.0f}
        }
    }
};  // 4D tensor of shape {2,2,2,2}, dtype=float32

All inner tensors must have consistent dimensions. The tensor is contiguous in memory.

Tensor() [8/9]

tannic::Tensor::Tensor ( type  dtype, Shape  shape, std::ptrdiff_t  offset, std::shared_ptr< Buffer >  storage  )

inline

Tensor() [9/9]

tannic::Tensor::Tensor ( type  dtype, Shape  shape, Strides  strides, std::ptrdiff_t  offset, std::shared_ptr< Buffer >  storage  )

inline

Member Function Documentation

assign() [1/2]

void tannic::Tensor::assign ( bool const *  , std::ptrdiff_t    )

protected

assign() [2/2]

void tannic::Tensor::assign ( std::byte const *  , std::ptrdiff_t    )

protected

bytes()

std::byte * tannic::Tensor::bytes ( ) const

inline

Returns a pointer to the beginning of the tensor's data (accounting for offset).

Returns

Pointer to the tensor's data in bytes.

compare()

bool tannic::Tensor::compare ( std::byte const *  , std::ptrdiff_t    ) const

protected

dtype()

type tannic::Tensor::dtype ( ) const

inline

Returns the tensor's data type.

environment()

Environment const & tannic::Tensor::environment ( ) const

inline

Returns a reference to the environment variant used to allocate this tensor's buffer.

Returns

Environment reference.

Note

Asserts if the tensor is not initialized.

forward() [1/2]

Tensor & tannic::Tensor::forward ( )

inline

Returns a reference to this tensor (const-qualified).

forward() [2/2]

Tensor const & tannic::Tensor::forward ( ) const

inline

Returns a reference to this tensor (non-const).

initialize() [1/5]

void tannic::Tensor::initialize

(

Environment

environment = Host{}

)

const

Allocates the memory buffer for the tensor.

Parameters

environment

Memory environment (defaults to Host{}).

initialize() [2/5]

template<typename T >

void tannic::Tensor::initialize ( std::initializer_list< std::initializer_list< std::initializer_list< std::initializer_list< T > > > >  values, Environment  environment = Host{}  )

inline

Assigns values to a 4D tensor from a quadruple-nested initializer list.

Template Parameters

T	Element type of the nested initializer list.

Parameters

values

A quadruple-nested list of values to assign to the tensor.

This operator assigns values to an existing 4D tensor:

Tensor W(float32, {2, 2, 2, 2});  
W.initialize({
    {
        {
            {1,  2}, {3,  4}
        },
        {
            {5,  6}, {7,  8}
        }
    },
    {
        {
            {9, 10}, {11, 12}
        },
        {
            {13, 14}, {15, 16}
        }
    }
});  // values cast to float32

Requirements:

• The tensor must already be initialized.
• The tensor must be rank-4.
• The tensor must be contiguous.
• All nested dimensions must match the tensor’s shape.

Type conversion:

• Values are cast to the tensor’s existing dtype before being written.

initialize() [3/5]

template<typename T >

void tannic::Tensor::initialize ( std::initializer_list< std::initializer_list< std::initializer_list< T > > > const &  values, Environment  environment = Host{}  )

inline

Assigns values to a 3D tensor from a triple-nested initializer list.

Template Parameters

T	Element type of the nested initializer list.

Parameters

values	A triple-nested list of values (matrices) to assign to the tensor.
environment	Target environment for initialization (default: Host).

This operator assigns values to an existing 3D tensor:

Tensor Z(float32, {2, 1, 3});
Z.initialize({
    { {0.0f, 1.0f, 2.0f} },
    { {3.0f, 4.0f, 5.0f} }
});  // values cast to float32

Requirements:

• The tensor must already be initialized.
• The tensor must be rank-3.
• The tensor must be contiguous.
• All matrices must have the same number of rows, and all rows must have the same number of columns, matching the tensor’s shape.

Type conversion:

• Values are cast to the tensor’s existing dtype before being written.
• This ensures that the tensor’s dtype does not change after assignment.

initialize() [4/5]

template<typename T >

void tannic::Tensor::initialize ( std::initializer_list< std::initializer_list< T > > const &  values, Environment  environment = Host{}  )

inline

Assigns values to a 2D tensor from a nested initializer list.

Template Parameters

T	Element type of the nested initializer list.

Parameters

values

A nested list of values to assign to the tensor (rows).

This operator assigns values to an existing 2D tensor:

Tensor Y(float32, {2, 3});
Y.initialize({
    {1, 2, 3},
    {4, 5, 6}
});  // values cast to float32

Requirements:

• The tensor must already be initialized.
• The tensor must be rank-2.
• The tensor must be contiguous.
• All rows must have the same length, matching the tensor’s second dimension.

Type conversion:

• Values are cast to the tensor’s existing dtype before being written.

initialize() [5/5]

template<typename T >

void tannic::Tensor::initialize ( std::initializer_list< T >  values, Environment  environment = Host{}  )

inline

Assigns values to a 1D tensor from an initializer list.

Template Parameters

T	Element type of the initializer list.

Parameters

values

A list of values to assign to the tensor.

This operator assigns values to an existing 1D tensor:

Tensor X(float32, {3});
X.initialize({1, 2, 3});  // values cast to float32

Requirements:

• The tensor must already be initialized.
• The tensor must be rank-1.
• The tensor must be contiguous.
• The size of values must match the tensor shape.

Type conversion:

• Values are cast to the tensor’s existing dtype before being written.
• This ensures that the tensor’s dtype does not change after assignment.

is_contiguous()

bool tannic::Tensor::is_contiguous ( ) const

inline

Returns whether the tensor's elements are in contiguous layout or not.

is_initialized()

bool tannic::Tensor::is_initialized ( ) const

inline

Checks whether the tensor has been initialized with memory.

Returns

True if initialized, false otherwise.

is_singleton()

bool tannic::Tensor::is_singleton ( ) const

inline

nbytes()

std::size_t tannic::Tensor::nbytes ( ) const

inline

Returns the total number of bytes occupied by the tensor's elements.

nelements()

std::size_t tannic::Tensor::nelements ( ) const

inline

Returns the total number of elements of the tensor.

node()

Node * tannic::Tensor::node ( ) const

inline

offset()

std::ptrdiff_t tannic::Tensor::offset ( ) const

inline

Returns the offset of the tensor in the current buffer.

operator=()

template<Expression Expression>

Tensor & tannic::Tensor::operator= ( const Expression &  expression )

inline

Assigns the result of an expression to the tensor.

Template Parameters

Expression

Expression type satisfying the Expression concept.

Parameters

expression

Expression to evaluate.

Returns

Reference to *this.

operator[]() [1/3]

template<Integral Index>

auto tannic::Tensor::operator[] ( Index  index ) const

inline

Indexes the tensor with a single integral index.

Parameters

index

The index to access.

Returns

A slice expression representing the sub-tensor.

Example:

using namespace tannic; 
 
Tensor X(float32, {2,2,2}); X.initialize(); 
X[0] = 1;    //arbitrary types assignment support.
X[1] = 2.f;
std::cout << X  << std::endl; // Tensor([[[1, 1], [1, 1]], 
                             //          [[2, 2], [2, 2]]] dtype=float32, shape=(2, 2, 2))
 
Tensor Y = X[1]; 
std::cout << Y << std::endl; // Tensor([[2, 2], 
                            //          [2, 2]] dtype=float32, shape=(2, 2))
 
std::cout << Y[0] << std::endl; // Tensor([2, 2] dtype=float32, shape=(2))

operator[]() [2/3]

template<class ... Indexes>

auto tannic::Tensor::operator[] ( Indexes...  indexes ) const

inline

Indexes the tensor with multiple indices (e.g., integers or ranges).

Template Parameters

Indexes

Variadic index types.

Parameters

indexes

Indices to apply.

Returns

A slice expression representing the sub-tensor.

Example:

using namespace tannic; 
 
Tensor X(float32, {2,2}); X.initialize(); // or X.initialize(Device()); for CUDA support   
X[0, range{0,-1}] = 1;  //  fills [0,0] and [0,1] with 1.
X[1,0] = 3;
X[1,1] = 4;       

operator[]() [3/3]

auto tannic::Tensor::operator[] ( indexing::Range  range ) const

inline

Indexes the tensor with a Range object.

Parameters

range

Range to apply to the first dimension.

Returns

A slice expression representing the sub-tensor.

Example:

using namespace tannic; 
 
Tensor X(float32, {2,2,2}); X.initialize();  
X[{0,1}] = 5; // same as X[range{0,1}] = 5

permute()

template<Integral ... Indexes>

auto tannic::Tensor::permute ( Indexes...  indexes ) const

inline

Returns a view of the tensor with dimensions permuted.

Parameters

indexes

Indices to permute

Returns

Permutation expression.

rank()

rank_type tannic::Tensor::rank ( ) const

inline

Returns the number of dimensions (rank) of the tensor.

shape()

Shape const & tannic::Tensor::shape ( ) const

inline

Returns the tensor's shape (dimension sizes per dimension).

size()

Shape::size_type tannic::Tensor::size ( int  dimension ) const

inline

Returns the tensor's size at a given dimension.

squeeze()

auto tannic::Tensor::squeeze ( ) const

inline

Returns a view of the tensor with all dimensions of size 1 removed.

Returns

Squeeze expression.

Example:

using namespace tannic;
 
Tensor X(float32, {1, 3, 1, 5}); X.initialize();
Tensor Y = X.squeeze();     // shape = (3, 5)

strides()

Strides const & tannic::Tensor::strides ( ) const

inline

Returns the tensor's strides (step sizes per dimension).

transpose()

auto tannic::Tensor::transpose ( int  first = -1, int  second = -2  ) const

inline

Returns a view of the tensor with two dimensions transposed.

Parameters

first	First dimension to swap (default: -1).
second	Second dimension to swap (default: -2).

Returns

Transpose expression.

unsqueeze()

template<Integral... Axes>

auto tannic::Tensor::unsqueeze ( Axes...  axes )

inline

Returns a view of the tensor with a dimension of size 1 inserted at the given axis.

Parameters

axis	Dimension index where the new axis is inserted (supports negative indexing).

Returns

Unsqueeze expression.

Example:

using namespace tannic;
 
Tensor X(float32, {3, 5}); X.initialize();
Tensor Y = X.unsqueeze(0);   // shape = (1, 3, 5)
Tensor Z = X.unsqueeze(2);   // shape = (3, 1, 5)

view()

template<Integral ... Sizes>

auto tannic::Tensor::view ( Sizes...  sizes ) const

inline

Returns a view of the tensor with given sizes.

Parameters

sizes

sizes of the new shape of the tensor

Returns

View expression.

Friends And Related Function Documentation

expression::Complexification

template<class Coordinates , Expression... Sources>

friend class expression::Complexification

friend

expression::Expansion

template<Expression Source>

friend class expression::Expansion

friend

expression::Flatten

template<Expression Source>

friend class expression::Flatten

friend

expression::Permutation

template<Expression Source, Integral... Indexes>

friend class expression::Permutation

friend

expression::Realification

template<Expression Source>

friend class expression::Realification

friend

expression::Slice

template<Expression Source, class... Indexes>

friend class expression::Slice

friend

expression::Squeeze

template<Expression Source>

friend class expression::Squeeze

friend

expression::Transpose

template<Expression Source>

friend class expression::Transpose

friend

expression::Unsqueeze

template<Expression Source>

friend class expression::Unsqueeze

friend

expression::View

template<Expression Source>

friend class expression::View

friend

---

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

• include/tannic/tensor.hpp