xerus a general purpose tensor library
xerus::Tensor Class Referencefinal

Class that handles simple (non-decomposed) tensors in a dense or sparse representation. More...

#include <tensor.h>

Collaboration diagram for xerus::Tensor:

## Public Types

typedef std::vector< size_t > DimensionTuple
: Represention of the dimensions of a Tensor. More...

enum  Initialisation : bool { Initialisation::None, Initialisation::Zero }
Flags determining the initialisation of the data of Tensor objects. More...

typedef std::vector< size_t > MultiIndex
: Represention of a MultiIndex, i.e. the tuple of positions for each dimension determining a single position in a Tensor. More...

enum  Representation : bool { Representation::Dense, Representation::Sparse }
Flags indicating the internal representation of the data of Tensor objects. More...

## Public Member Functions

Tensor (const Representation _representation=Representation::Sparse)
Constructs an order zero Tensor with the given inital representation. More...

Tensor (const Tensor &_other)=default
Tensors are default copy constructable. More...

Tensor (Tensor &&_other) noexcept=default
Tensors are default move constructable. More...

Tensor (DimensionTuple _dimensions, const Representation _representation=Representation::Sparse, const Initialisation _init=Initialisation::Zero)
: Creates a new tensor with the given dimensions. More...

Tensor (Vec &&_dimensions, SPtr &&_data)
: Creates a new (dense) tensor with the given dimensions, using a provided data. More...

Tensor (DimensionTuple _dimensions, std::unique_ptr< value_t[]> &&_data)
: Creates a new (dense) tensor with the given dimensions, using a provided data. More...

Tensor (DimensionTuple _dimensions, const std::function< value_t()> &_f)
Constructs a Tensor with the given dimensions and uses the given function to assign the values to the entries. More...

Tensor (DimensionTuple _dimensions, const std::function< value_t(const size_t)> &_f)
Constructs a Tensor with the given dimensions and uses the given function to assign the values to the entries. More...

Tensor (DimensionTuple _dimensions, const std::function< value_t(const MultiIndex &)> &_f)
Constructs a Tensor with the given dimensions and uses the given function to assign the values to the entries. More...

Tensor (DimensionTuple _dimensions, const size_t _N, const std::function< std::pair< size_t, value_t >(size_t, size_t)> &_f)
Constructs a Tensor with the given dimensions and uses the given function _f to create _N non zero entries. More...

bool all_entries_valid () const
Checks the tensor for illegal entries, e.g. nan, inf,... More...

void apply_factor ()
Checks whether there is a non-trivial scaling factor and applies it if nessecary. More...

value_tat (const size_t _position)

value_t cat (const size_t _position) const

size_t count_non_zero_entries (const value_t _eps=std::numeric_limits< value_t >::epsilon()) const
Determines the number of non-zero entries. More...

size_t degree () const
Returns the degree of the tensor. More...

Tensor dense_copy () const
Returns a copy of this Tensor that uses a dense representation. More...

void ensure_own_data ()
Ensures that this tensor is the sole owner of its data. If needed new space is allocated and all entries are copied. More...

void ensure_own_data_and_apply_factor ()
Checks whether there is a non-trivial factor and applies it. Even if no factor is applied ensure_own_data() is called. More...

void ensure_own_data_no_copy ()
Ensures that this tensor is the sole owner of its data space. If needed new space is allocated with entries left undefined. More...

void fix_mode (const size_t _mode, const size_t _slatePosition)
Fixes a specific mode to a specific value, effectively reducing the order by one. More...

value_t frob_norm () const
Calculates the frobenious norm of the tensor. More...

value_tget_dense_data ()
Returns a pointer for direct access to the dense data array in row major order. More...

const std::shared_ptr< value_t > & get_internal_dense_data ()
Gives access to the internal shared data pointer, without any checks. More...

const std::shared_ptr< std::map< size_t, value_t > > & get_internal_sparse_data ()
Gives access to the internal shared sparse data pointer, without any checks. More...

std::map< size_t, value_t > & get_sparse_data ()
Returns a reference for direct access to the sparse data map. More...

value_tget_unsanitized_dense_data ()

const value_tget_unsanitized_dense_data () const

std::map< size_t, value_t > & get_unsanitized_sparse_data ()

const std::map< size_t, value_t > & get_unsanitized_sparse_data () const

bool has_factor () const
Checks whether the tensor has a non-trivial global scaling factor. More...

bool is_dense () const
Returns whether the current representation is dense. More...

bool is_sparse () const
Returns whether the current representation is sparse. More...

void modify_diagonal_entries (const std::function< void(value_t &)> &_f)
Modifies the diagonal entries according to the given function. More...

void modify_diagonal_entries (const std::function< void(value_t &, const size_t)> &_f)
Modifies the diagonal entries according to the given function. More...

void modify_entries (const std::function< void(value_t &)> &_f)
Modifies every entry according to the given function. More...

void modify_entries (const std::function< void(value_t &, const size_t)> &_f)
Modifies every entry according to the given function. More...

void modify_entries (const std::function< void(value_t &, const MultiIndex &)> &_f)
Modifies every entry according to the given function. More...

void offset_add (const Tensor &_other, const std::vector< size_t > &_offsets)
Adds the given Tensor with the given offsets to this one. More...

value_t one_norm () const
Calculates the 1-norm of the tensor. More...

template<typename... args>
internal::IndexedTensor< Tensoroperator() (args... _args)
Indexes the Tensor for read/write use. More...

template<typename... args>
Indexes the Tensor for read only use. More...

internal::IndexedTensor< Tensoroperator() (const std::vector< Index > &_indices)
Indexes the tensor for read/write use. More...

internal::IndexedTensor< Tensoroperator() (std::vector< Index > &&_indices)
Indexes the tensor for read/write use. More...

internal::IndexedTensorReadOnly< Tensoroperator() (const std::vector< Index > &_indices) const
Indexes the tensor for read only use. More...

internal::IndexedTensorReadOnly< Tensoroperator() (std::vector< Index > &&_indices) const
Indexes the tensor for read only use. More...

Tensoroperator*= (const value_t _factor)
Performs the entrywise multiplication with a constant _factor. More...

Tensoroperator+= (const Tensor &_other)
Adds the _other Tensor entrywise to this one. More...

Tensoroperator-= (const Tensor &_other)
Subtracts the _other Tensor entrywise from this one. More...

Tensoroperator/= (const value_t _divisor)
Performs the entrywise divison by a constant _divisor. More...

Tensoroperator= (const Tensor &_other)=default
Standard assignment operator. More...

Tensoroperator= (Tensor &&_other)=default
Standard move-assignment operator. More...

Tensoroperator= (const TensorNetwork &_network)
Assigns the given TensorNetwork to this Tensor by completely contracting the network. More...

value_toperator[] (const size_t _position)
Read/Write access a single entry. More...

value_t operator[] (const size_t _position) const
Read access a single entry. More...

value_toperator[] (const MultiIndex &_positions)
Read/Write access a single entry. More...

value_t operator[] (const MultiIndex &_positions) const
Read access a single entry. More...

value_toverride_dense_data ()
Returns a pointer to the internal dense data array for complete rewrite purpose ONLY. More...

std::map< size_t, value_t > & override_sparse_data ()
Returns a pointer to the internal sparse data map for complete rewrite purpose ONLY. More...

void perform_trace (size_t _firstMode, size_t _secondMode)
Performs the trace over the given modes. More...

void reinterpret_dimensions (DimensionTuple _newDimensions)
Reinterprets the dimensions of the tensor. More...

void remove_slate (const size_t _mode, const size_t _pos)
Removes a single slate from the Tensor, reducing dimension[_mode] by one. More...

size_t reorder_cost () const
Approximates the cost to reorder the tensor. More...

void reset (DimensionTuple _newDim, const Representation _representation, const Initialisation _init=Initialisation::Zero)
Resets the tensor to the given dimensions and representation. More...

void reset (DimensionTuple _newDim, const Initialisation _init=Initialisation::Zero)
Resets the tensor to the given dimensions, preserving the current representation. More...

void reset ()
Resets the tensor as if default initialized. More...

void reset (DimensionTuple _newDim, const std::shared_ptr< value_t > &_newData)
Resets the tensor to the given dimensions and uses the given data. More...

void reset (DimensionTuple _newDim, std::unique_ptr< value_t[]> &&_newData)
Resets the tensor to the given dimensions with data _newData. More...

void reset (DimensionTuple _newDim, std::map< size_t, value_t > &&_newData)
Resets the tensor to a given dimensionstuple with sparse data _newData. More...

void resize_mode (const size_t _mode, const size_t _newDim, size_t _cutPos=~0ul)
Resizes a specific mode of the Tensor. More...

Tensor sparse_copy () const
Returns a copy of this Tensor that uses a sparse representation. More...

size_t sparsity () const
Returns the number currently saved entries. More...

std::string to_string () const
Creates a string representation of the Tensor. More...

void use_dense_representation ()
Converts the Tensor to a dense representation. More...

void use_dense_representation_if_desirable ()
Converts the Tensor to a dense representation if sparsity * sparsityFactor >= size. More...

void use_sparse_representation (const value_t _eps=std::numeric_limits< value_t >::epsilon())
Converts the Tensor to a sparse representation. More...

## Static Public Member Functions

static Tensor XERUS_warn_unused dirac (DimensionTuple _dimensions, const MultiIndex &_position)
: Returns a Tensor with a single entry equals one and all other zero. More...

static Tensor XERUS_warn_unused dirac (DimensionTuple _dimensions, const size_t _position)
: Returns a Tensor with a single entry equals one and all other zero. More...

static Tensor XERUS_warn_unused identity (DimensionTuple _dimensions)
: Returns a Tensor representation of the identity operator with the given dimensions. More...

static Tensor XERUS_warn_unused kronecker (DimensionTuple _dimensions)
: Returns a Tensor representation of the kronecker delta. More...

static size_t multiIndex_to_position (const MultiIndex &_multiIndex, const DimensionTuple &_dimensions)

static Tensor XERUS_warn_unused ones (DimensionTuple _dimensions)
: Returns a Tensor with all entries equal to one. More...

static MultiIndex position_to_multiIndex (size_t _position, const DimensionTuple &_dimensions)

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
static Tensor XERUS_warn_unused random (DimensionTuple _dimensions, distribution &_dist=xerus::misc::defaultNormalDistribution, generator &_rnd=xerus::misc::randomEngine)
Constructs a dense Tensor with the given dimensions and uses the given random generator and distribution to assign the values to the entries. More...

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
static XERUS_force_inline Tensor XERUS_warn_unused random (std::initializer_list< size_t > &&_dimensions, distribution &_dist=xerus::misc::defaultNormalDistribution, generator &_rnd=xerus::misc::randomEngine)
Constructs a dense Tensor with the given dimensions and uses the given random generator and distribution to assign the values to the entries. More...

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
static Tensor XERUS_warn_unused random (DimensionTuple _dimensions, const size_t _N, distribution &_dist=xerus::misc::defaultNormalDistribution, generator &_rnd=xerus::misc::randomEngine)
Constructs a random sparse Tensor with the given dimensions. More...

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
static XERUS_force_inline Tensor XERUS_warn_unused random (std::initializer_list< size_t > &&_dimensions, const size_t _N, distribution &_dist, generator &_rnd)
Constructs a random sparse Tensor with the given dimensions. More...

template<class generator = std::mt19937_64>
static Tensor XERUS_warn_unused random_orthogonal (DimensionTuple _dimensions1, DimensionTuple _dimensions2, generator &_rnd=xerus::misc::randomEngine)
Constructs a dense Tensor with the given dimensions and uses the given random generator and distribution to assign the values to the entries. More...

## Public Attributes

DimensionTuple dimensions
Vector containing the individual dimensions of the tensor. More...

value_t factor = 1.0
Single value representing a constant scaling factor. More...

Representation representation = Representation::Sparse
The current representation of the Tensor (i.e Dense or Sparse) More...

size_t size = 1
Size of the Tensor – always equal to the product of the dimensions. More...

## Static Public Attributes

static size_t sparsityFactor = 4

## Static Protected Member Functions

static void add_sparse_to_full (const std::shared_ptr< value_t > &_denseData, const value_t _factor, const std::shared_ptr< const std::map< size_t, value_t >> &_sparseData)
Adds the given sparse data to the given full data. More...

static void add_sparse_to_sparse (const std::shared_ptr< std::map< size_t, value_t >> &_sum, const value_t _factor, const std::shared_ptr< const std::map< size_t, value_t >> &_summand)
Adds the given sparse data to the given sparse data. More...

template<int sign>
static void plus_minus_equal (Tensor &_me, const Tensor &_other)

## Detailed Description

Class that handles simple (non-decomposed) tensors in a dense or sparse representation.

Definition at line 70 of file tensor.h.

## ◆ DimensionTuple

 typedef std::vector xerus::Tensor::DimensionTuple

: Represention of the dimensions of a Tensor.

Definition at line 92 of file tensor.h.

## ◆ MultiIndex

 typedef std::vector xerus::Tensor::MultiIndex

: Represention of a MultiIndex, i.e. the tuple of positions for each dimension determining a single position in a Tensor.

Definition at line 95 of file tensor.h.

## ◆ Initialisation

 enum xerus::Tensor::Initialisation : bool
strong

Flags determining the initialisation of the data of Tensor objects.

None means that no initialisation is performed, i.e. the data can be random. Zero means that the data is zero initialized.

Enumerator
None
Zero

Definition at line 81 of file tensor.h.

## ◆ Representation

 enum xerus::Tensor::Representation : bool
strong

Flags indicating the internal representation of the data of Tensor objects.

Dense means that an value_t array of 'size' is used to store each entry individually, using row-major order. Sparse means that only the non-zero entries are stored explicitly in a set containing their value and position.

Enumerator
Dense
Sparse

Definition at line 89 of file tensor.h.

## ◆ Tensor() [1/10]

 xerus::Tensor::Tensor ( const Representation _representation = Representation::Sparse )
explicit

Constructs an order zero Tensor with the given inital representation.

Definition at line 49 of file tensor.cpp.

## ◆ Tensor() [2/10]

 xerus::Tensor::Tensor ( const Tensor & _other )
default

Tensors are default copy constructable.

## ◆ Tensor() [3/10]

 xerus::Tensor::Tensor ( Tensor && _other )
defaultnoexcept

Tensors are default move constructable.

## ◆ Tensor() [4/10]

 xerus::Tensor::Tensor ( DimensionTuple _dimensions, const Representation _representation = Representation::Sparse, const Initialisation _init = Initialisation::Zero )
explicit

: Creates a new tensor with the given dimensions.

Parameters
 _dimensions the dimensions of the new tensor. _representation (optional) the initial representation of the tensor. _init (optional) inital data treatment, i.e. whether the tensor is to be zero Initialized.

Definition at line 52 of file tensor.cpp.

## ◆ Tensor() [5/10]

 xerus::Tensor::Tensor ( Vec && _dimensions, SPtr && _data )
inlineexplicit

: Creates a new (dense) tensor with the given dimensions, using a provided data.

Parameters
 _dimensions the dimensions of the new tensor. _data inital dense data in row-major order.

Definition at line 154 of file tensor.h.

## ◆ Tensor() [6/10]

 xerus::Tensor::Tensor ( DimensionTuple _dimensions, std::unique_ptr< value_t[]> && _data )
explicit

: Creates a new (dense) tensor with the given dimensions, using a provided data.

Parameters
 _dimensions the dimensions of the new tensor. _data inital dense data in row-major order.

Definition at line 68 of file tensor.cpp.

## ◆ Tensor() [7/10]

 xerus::Tensor::Tensor ( DimensionTuple _dimensions, const std::function< value_t()> & _f )
explicit

Constructs a Tensor with the given dimensions and uses the given function to assign the values to the entries.

In this overload no value is passed to _f, i.e. _f must determine the values of the entries independend of their position, or keep track of the position itself. _f may assume that it is called for the entries in the order they are stored (i.e. row-major order)

Parameters
 _dimensions the future dimensions of the Tensor. _f the function to use to set the entries of the Tensor.

Definition at line 74 of file tensor.cpp.

## ◆ Tensor() [8/10]

 xerus::Tensor::Tensor ( DimensionTuple _dimensions, const std::function< value_t(const size_t)> & _f )
explicit

Constructs a Tensor with the given dimensions and uses the given function to assign the values to the entries.

In this overload the position of each entry assuming row-major order is passed to _f.

Parameters
 _dimensions the future dimensions of the Tensor. _f the function to use to set the entries of the Tensor.

Definition at line 82 of file tensor.cpp.

## ◆ Tensor() [9/10]

 xerus::Tensor::Tensor ( DimensionTuple _dimensions, const std::function< value_t(const MultiIndex &)> & _f )
explicit

Constructs a Tensor with the given dimensions and uses the given function to assign the values to the entries.

In this overload the complete position of each entry is passed to _f.

Parameters
 _dimensions the future dimensions of the Tensor. _f the function to use to set the entries of the Tensor.

Definition at line 90 of file tensor.cpp.

## ◆ Tensor() [10/10]

 xerus::Tensor::Tensor ( DimensionTuple _dimensions, const size_t _N, const std::function< std::pair< size_t, value_t >(size_t, size_t)> & _f )

Constructs a Tensor with the given dimensions and uses the given function _f to create _N non zero entries.

_f is called with the current number of entries present and the number of possible entries (i.e. size). _f shall return a pair containg the position and value of the next entry. _f is required not to return a position twice.

Parameters
 _dimensions the future dimensions of the Tensor. _N the number of non-zero entries to be created. _f the function to be used to create each non zero entry.

Definition at line 111 of file tensor.cpp.

## Member Function Documentation

 void xerus::Tensor::add_sparse_to_full ( const std::shared_ptr< value_t > & _denseData, const value_t _factor, const std::shared_ptr< const std::map< size_t, value_t >> & _sparseData )
staticprotected

Adds the given sparse data to the given full data.

Definition at line 1114 of file tensor.cpp.

 void xerus::Tensor::add_sparse_to_sparse ( const std::shared_ptr< std::map< size_t, value_t >> & _sum, const value_t _factor, const std::shared_ptr< const std::map< size_t, value_t >> & _summand )
staticprotected

Adds the given sparse data to the given sparse data.

Definition at line 1121 of file tensor.cpp.

## ◆ all_entries_valid()

 bool xerus::Tensor::all_entries_valid ( ) const

Checks the tensor for illegal entries, e.g. nan, inf,...

Returns
TRUE there are no invalid entries, FALSE otherwise.

Definition at line 256 of file tensor.cpp.

## ◆ apply_factor()

 void xerus::Tensor::apply_factor ( )

Checks whether there is a non-trivial scaling factor and applies it if nessecary.

Definition at line 1186 of file tensor.cpp.

## ◆ at()

 value_t & xerus::Tensor::at ( const size_t _position )

Parameters
 _position the position of the desired entry, assuming row-major ordering.
Returns
the value of the selected entry.

Definition at line 365 of file tensor.cpp.

## ◆ cat()

 value_t xerus::Tensor::cat ( const size_t _position ) const

Parameters
 _position the position of the desired entry, assuming row-major ordering.
Returns
the value of the selected entry.

Definition at line 384 of file tensor.cpp.

## ◆ count_non_zero_entries()

 size_t xerus::Tensor::count_non_zero_entries ( const value_t _eps = std::numeric_limits::epsilon() ) const

Determines the number of non-zero entries.

Parameters
 _eps (optional) epsilon detrmining the maximal value, that is still assumed to be zero.
Returns
the number of non-zero entries found.

Definition at line 240 of file tensor.cpp.

## ◆ degree()

 size_t xerus::Tensor::degree ( ) const

Returns the degree of the tensor.

The degree is always equals to dimensions.size()

Returns
the degree of the tensor

Definition at line 206 of file tensor.cpp.

## ◆ dense_copy()

 Tensor xerus::Tensor::dense_copy ( ) const

Returns a copy of this Tensor that uses a dense representation.

Definition at line 187 of file tensor.cpp.

## ◆ dirac() [1/2]

 Tensor xerus::Tensor::dirac ( DimensionTuple _dimensions, const MultiIndex & _position )
static

: Returns a Tensor with a single entry equals one and all other zero.

Parameters
 _dimensions the dimensions of the new tensor. _position The position of the one

Definition at line 173 of file tensor.cpp.

## ◆ dirac() [2/2]

 Tensor xerus::Tensor::dirac ( DimensionTuple _dimensions, const size_t _position )
static

: Returns a Tensor with a single entry equals one and all other zero.

Parameters
 _dimensions the dimensions of the new tensor. _position The position of the one

Definition at line 180 of file tensor.cpp.

## ◆ ensure_own_data()

 void xerus::Tensor::ensure_own_data ( )

Ensures that this tensor is the sole owner of its data. If needed new space is allocated and all entries are copied.

Definition at line 1158 of file tensor.cpp.

## ◆ ensure_own_data_and_apply_factor()

 void xerus::Tensor::ensure_own_data_and_apply_factor ( )

Checks whether there is a non-trivial factor and applies it. Even if no factor is applied ensure_own_data() is called.

Definition at line 1210 of file tensor.cpp.

## ◆ ensure_own_data_no_copy()

 void xerus::Tensor::ensure_own_data_no_copy ( )

Ensures that this tensor is the sole owner of its data space. If needed new space is allocated with entries left undefined.

Definition at line 1173 of file tensor.cpp.

## ◆ fix_mode()

 void xerus::Tensor::fix_mode ( const size_t _mode, const size_t _slatePosition )

Fixes a specific mode to a specific value, effectively reducing the order by one.

Parameters
 _mode the mode in which the slate shall be fixed, e.g. 0 to fix the first mode. _slatePosition the position in the corresponding mode that shall be used. 0 <= _slatePosition < dimension[_mode]

Definition at line 732 of file tensor.cpp.

## ◆ frob_norm()

 value_t xerus::Tensor::frob_norm ( ) const

Calculates the frobenious norm of the tensor.

Returns
the frobenious norm.

Definition at line 286 of file tensor.cpp.

## ◆ get_dense_data()

 value_t * xerus::Tensor::get_dense_data ( )

Returns a pointer for direct access to the dense data array in row major order.

Also takes care that this direct access is safe, i.e. that this tensor is using a dense representation, is the sole owner of the data and that no non trivial factor exists.

Returns
pointer to the dense data array.

Definition at line 401 of file tensor.cpp.

## ◆ get_internal_dense_data()

 const std::shared_ptr< value_t > & xerus::Tensor::get_internal_dense_data ( )

Note that the data array might be shared with other tensors or has to be interpreted considering a global factor. Both can be avoid if using get_dense_data(). The tensor data itself is stored in row-major ordering.

Returns
The internal shared pointer to the data array.

Definition at line 431 of file tensor.cpp.

## ◆ get_internal_sparse_data()

 const std::shared_ptr< std::map< size_t, value_t > > & xerus::Tensor::get_internal_sparse_data ( )

Gives access to the internal shared sparse data pointer, without any checks.

Note that the sparse data map might not exist because no sparse representation is used, may shared with other tensors or has to be interpreted considering a gloal factor. Both can be avoid if using get_sparse_data().

Returns
The internal shared pointer to the sparse data map.

Definition at line 472 of file tensor.cpp.

## ◆ get_sparse_data()

 std::map< size_t, value_t > & xerus::Tensor::get_sparse_data ( )

Also takes care that this direct access is safe, i.e. that this tensor is using a dense representation, is the sole owner of the data and that no non trivial factor exists.

Returns
reference to the sparse data map.

Definition at line 437 of file tensor.cpp.

## ◆ get_unsanitized_dense_data() [1/2]

 value_t * xerus::Tensor::get_unsanitized_dense_data ( )

Note that the dense data array might not exist because a sparse representation is used, may shared with other tensors or has to be interpreted considering a gloal factor. Both can be avoid if using get_dense_data(). The tensor data itself is stored in row-major ordering.

Returns
pointer to the internal dense data array.

Definition at line 408 of file tensor.cpp.

## ◆ get_unsanitized_dense_data() [2/2]

 const value_t * xerus::Tensor::get_unsanitized_dense_data ( ) const

Note that the dense data array might not exist because a sparse representation is used, may shared with other tensors or has to be interpreted considering a gloal factor. Both can be avoid if using get_dense_data(). The tensor data itself is stored in row-major ordering.

Returns
pointer to the internal dense data array.

Definition at line 414 of file tensor.cpp.

## ◆ get_unsanitized_sparse_data() [1/2]

 std::map< size_t, value_t > & xerus::Tensor::get_unsanitized_sparse_data ( )

Note that the sparse data map might not exist because no sparse representation is used, may shared with other tensors or has to be interpreted considering a gloal factor. Both can be avoid if using get_sparse_data().

Returns
reference to the internal sparse data map.

Definition at line 445 of file tensor.cpp.

## ◆ get_unsanitized_sparse_data() [2/2]

 const std::map< size_t, value_t > & xerus::Tensor::get_unsanitized_sparse_data ( ) const

Note that the sparse data map might not exist because no sparse representation is used, may shared with other tensors or has to be interpreted considering a gloal factor. Both can be avoid if using get_sparse_data().

Returns
reference to the internal sparse data map.

Definition at line 451 of file tensor.cpp.

## ◆ has_factor()

 bool xerus::Tensor::has_factor ( ) const

Checks whether the tensor has a non-trivial global scaling factor.

Returns
true if there is a non-trivial factor, false if not.

Definition at line 211 of file tensor.cpp.

## ◆ identity()

 Tensor xerus::Tensor::identity ( DimensionTuple _dimensions )
static

: Returns a Tensor representation of the identity operator with the given dimensions.

That is combining the first half of the dimensions and the second half of the dimensions results in an identity matrix.

Parameters
 _dimensions the dimensions of the new tensor. It is required that _dimensions[i] = _dimensions[d/2+i], otherwise this cannot be the identity operator.

Definition at line 131 of file tensor.cpp.

## ◆ is_dense()

 bool xerus::Tensor::is_dense ( ) const

Returns whether the current representation is dense.

Definition at line 220 of file tensor.cpp.

## ◆ is_sparse()

 bool xerus::Tensor::is_sparse ( ) const

Returns whether the current representation is sparse.

Definition at line 226 of file tensor.cpp.

## ◆ kronecker()

 Tensor xerus::Tensor::kronecker ( DimensionTuple _dimensions )
static

: Returns a Tensor representation of the kronecker delta.

That is each entry is one if all indices are equal and zero otherwise. Note iff d=2 this coincides with identity.

Parameters
 _dimensions the dimensions of the new tensor.

Definition at line 160 of file tensor.cpp.

## ◆ modify_diagonal_entries() [1/2]

 void xerus::Tensor::modify_diagonal_entries ( const std::function< void(value_t &)> & _f )

Modifies the diagonal entries according to the given function.

In this overload only the current diagonal entries are passed to _f, one at a time. At the moment this is only defined for matricies.

Parameters
 _f the function to call to modify each entry.

Definition at line 841 of file tensor.cpp.

## ◆ modify_diagonal_entries() [2/2]

 void xerus::Tensor::modify_diagonal_entries ( const std::function< void(value_t &, const size_t)> & _f )

Modifies the diagonal entries according to the given function.

In this overload the current diagonal entries are passed to _f, one at a time, together with their position on the diagonal. At the moment this is only defined for matricies.

Parameters
 _f the function to call to modify each entry.

Definition at line 862 of file tensor.cpp.

## ◆ modify_entries() [1/3]

 void xerus::Tensor::modify_entries ( const std::function< void(value_t &)> & _f )

Modifies every entry according to the given function.

In this overload only the current entry is passed to _f.

Parameters
 _f the function to call to modify each entry.

Definition at line 883 of file tensor.cpp.

## ◆ modify_entries() [2/3]

 void xerus::Tensor::modify_entries ( const std::function< void(value_t &, const size_t)> & _f )

Modifies every entry according to the given function.

In this overload the current entry together with its position, assuming row-major ordering is passed to _f.

Parameters
 _f the function to call to modify each entry.

Definition at line 903 of file tensor.cpp.

## ◆ modify_entries() [3/3]

 void xerus::Tensor::modify_entries ( const std::function< void(value_t &, const MultiIndex &)> & _f )

Modifies every entry according to the given function.

In this overload the current entry together with its complete position is passed to _f.

Parameters
 _f the function to call to modify each entry.

Definition at line 923 of file tensor.cpp.

## ◆ multiIndex_to_position()

 size_t xerus::Tensor::multiIndex_to_position ( const MultiIndex & _multiIndex, const DimensionTuple & _dimensions )
static

Definition at line 1131 of file tensor.cpp.

 void xerus::Tensor::offset_add ( const Tensor & _other, const std::vector< size_t > & _offsets )

Adds the given Tensor with the given offsets to this one.

Parameters
 _other Tensor that shall be added to this one, the orders must coincide. _offsets the offsets to be used.

Definition at line 969 of file tensor.cpp.

## ◆ one_norm()

 value_t xerus::Tensor::one_norm ( ) const

Calculates the 1-norm of the tensor.

Returns
the 1-norm.

Definition at line 275 of file tensor.cpp.

## ◆ ones()

 Tensor xerus::Tensor::ones ( DimensionTuple _dimensions )
static

: Returns a Tensor with all entries equal to one.

Parameters
 _dimensions the dimensions of the new tensor.

Definition at line 122 of file tensor.cpp.

## ◆ operator()() [1/6]

template<typename... args>
 internal::IndexedTensor xerus::Tensor::operator() ( args... _args )
inline

Indexes the Tensor for read/write use.

Parameters
 _args several indices determining the desired index order.
Returns
an internal representation of an IndexedTensor.

Definition at line 613 of file tensor.h.

## ◆ operator()() [2/6]

template<typename... args>
 internal::IndexedTensorReadOnly xerus::Tensor::operator() ( args... _args ) const
inline

Indexes the Tensor for read only use.

Parameters
 _args several indices determining the desired index order.
Returns
an internal representation of an IndexedTensor.

Definition at line 624 of file tensor.h.

## ◆ operator()() [3/6]

 internal::IndexedTensor< Tensor > xerus::Tensor::operator() ( const std::vector< Index > & _indices )

Indexes the tensor for read/write use.

Parameters
 _indices several indices determining the desired index order.
Returns
an internal representation of an IndexedTensor.

Definition at line 479 of file tensor.cpp.

## ◆ operator()() [4/6]

 internal::IndexedTensor< Tensor > xerus::Tensor::operator() ( std::vector< Index > && _indices )

Indexes the tensor for read/write use.

Parameters
 _indices several indices determining the desired index order.
Returns
an internal representation of an IndexedTensor.

Definition at line 484 of file tensor.cpp.

## ◆ operator()() [5/6]

 internal::IndexedTensorReadOnly< Tensor > xerus::Tensor::operator() ( const std::vector< Index > & _indices ) const

Indexes the tensor for read only use.

Parameters
 _indices several indices determining the desired index order.
Returns
an internal representation of an IndexedTensor.

Definition at line 489 of file tensor.cpp.

## ◆ operator()() [6/6]

 internal::IndexedTensorReadOnly< Tensor > xerus::Tensor::operator() ( std::vector< Index > && _indices ) const

Indexes the tensor for read only use.

Parameters
 _indices Several indices determining the desired index order.
Returns
an internal representation of an IndexedTensor.

Definition at line 494 of file tensor.cpp.

## ◆ operator*=()

 Tensor & xerus::Tensor::operator*= ( const value_t _factor )

Performs the entrywise multiplication with a constant _factor.

Internally this only results in a change in the global factor.

Parameters
 _factor the factor,
Returns
a reference to this Tensor.

Definition at line 311 of file tensor.cpp.

## ◆ operator+=()

 Tensor & xerus::Tensor::operator+= ( const Tensor & _other )

Adds the _other Tensor entrywise to this one.

To be well-defined it is required that the dimensions of this and _other coincide.

Parameters
 _other the Tensor to be added to this one.
Returns
a reference to this Tensor.

Definition at line 299 of file tensor.cpp.

## ◆ operator-=()

 Tensor & xerus::Tensor::operator-= ( const Tensor & _other )

Subtracts the _other Tensor entrywise from this one.

To be well-defined it is required that the dimensions of this and _other coincide.

Parameters
 _other the Tensor to be subtracted to this one.
Returns
a reference to this Tensor.

Definition at line 305 of file tensor.cpp.

## ◆ operator/=()

 Tensor & xerus::Tensor::operator/= ( const value_t _divisor )

Performs the entrywise divison by a constant _divisor.

Internally this only results in a change in the global factor.

Parameters
 _divisor the divisor,
Returns
a reference to this Tensor.

Definition at line 317 of file tensor.cpp.

## ◆ operator=() [1/3]

 Tensor& xerus::Tensor::operator= ( const Tensor & _other )
default

Standard assignment operator.

Parameters
 _other the Tensor to be assinged to this one.
Returns
a reference to this Tensor.

## ◆ operator=() [2/3]

 Tensor& xerus::Tensor::operator= ( Tensor && _other )
default

Standard move-assignment operator.

Parameters
 _other the Tensor to be move-assinged to this one.
Returns
a reference to this Tensor.

## ◆ operator=() [3/3]

 Tensor & xerus::Tensor::operator= ( const TensorNetwork & _network )

Assigns the given TensorNetwork to this Tensor by completely contracting the network.

Parameters
 _other the TensorNetwork to be to this Tensor.
Returns
a reference to this Tensor.

Definition at line 200 of file tensor.cpp.

## ◆ operator[]() [1/4]

 value_t & xerus::Tensor::operator[] ( const size_t _position )

Parameters
 _position the position of the desired entry, assuming row-major ordering.
Returns
a reference to the selected entry.

Definition at line 324 of file tensor.cpp.

## ◆ operator[]() [2/4]

 value_t xerus::Tensor::operator[] ( const size_t _position ) const

Parameters
 _position the position of the desired entry, assuming row-major ordering.
Returns
the value of the selected entry.

Definition at line 341 of file tensor.cpp.

## ◆ operator[]() [3/4]

 value_t & xerus::Tensor::operator[] ( const MultiIndex & _positions )

Parameters
 _positions the positions of the desired entry.
Returns
a reference to the selected entry.

Definition at line 355 of file tensor.cpp.

## ◆ operator[]() [4/4]

 value_t xerus::Tensor::operator[] ( const MultiIndex & _positions ) const

Parameters
 _positions the positions of the desired entry.
Returns
the value of the selected entry.

Definition at line 360 of file tensor.cpp.

## ◆ override_dense_data()

 value_t * xerus::Tensor::override_dense_data ( )

Returns a pointer to the internal dense data array for complete rewrite purpose ONLY.

This is equivalent to calling reset() with the current dimensions, dense representation and no initialisation and then calling get_unsanitized_dense_data().

Returns
pointer to the internal dense data array.

Definition at line 420 of file tensor.cpp.

## ◆ override_sparse_data()

 std::map< size_t, value_t > & xerus::Tensor::override_sparse_data ( )

Returns a pointer to the internal sparse data map for complete rewrite purpose ONLY.

This is equivalent to calling reset() with the current dimensions, sparse representation and no initialisation and then calling get_unsanitized_sparse_data().

Returns
reference to the internal sparse data map.

Definition at line 457 of file tensor.cpp.

## ◆ perform_trace()

 void xerus::Tensor::perform_trace ( size_t _firstMode, size_t _secondMode )

Performs the trace over the given modes.

Parameters
 _firstMode the first mode involved in the trace. _secondMode the second mode involved in the trace.

Definition at line 781 of file tensor.cpp.

## ◆ plus_minus_equal()

template<int sign>
 void xerus::Tensor::plus_minus_equal ( Tensor & _me, const Tensor & _other )
staticprotected

Definition at line 1087 of file tensor.cpp.

## ◆ position_to_multiIndex()

 Tensor::MultiIndex xerus::Tensor::position_to_multiIndex ( size_t _position, const DimensionTuple & _dimensions )
static

Definition at line 1144 of file tensor.cpp.

## ◆ random() [1/4]

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
 static Tensor XERUS_warn_unused xerus::Tensor::random ( DimensionTuple _dimensions, distribution & _dist = xerus::misc::defaultNormalDistribution, generator & _rnd = xerus::misc::randomEngine )
inlinestatic

Constructs a dense Tensor with the given dimensions and uses the given random generator and distribution to assign the values to the entries.

The entries are assigned in the order they are stored (i.e. row-major order). Each assigned is a seperate call to the random distribution.

Parameters
 _dimensions the future dimensions of the Tensor. _rnd the random generator to be used. _dist the random distribution to be used.

Definition at line 213 of file tensor.h.

## ◆ random() [2/4]

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
 static XERUS_force_inline Tensor XERUS_warn_unused xerus::Tensor::random ( std::initializer_list< size_t > && _dimensions, distribution & _dist = xerus::misc::defaultNormalDistribution, generator & _rnd = xerus::misc::randomEngine )
inlinestatic

Constructs a dense Tensor with the given dimensions and uses the given random generator and distribution to assign the values to the entries.

See the std::vector variant for details.

Definition at line 228 of file tensor.h.

## ◆ random() [3/4]

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
 static Tensor XERUS_warn_unused xerus::Tensor::random ( DimensionTuple _dimensions, const size_t _N, distribution & _dist = xerus::misc::defaultNormalDistribution, generator & _rnd = xerus::misc::randomEngine )
inlinestatic

Constructs a random sparse Tensor with the given dimensions.

The given random generator _rnd and distribution _dist are used to assign the values to _n randomly choosen entries.

Parameters
 _dimensions the future dimensions of the Tensor. _N the number of non-zero entries to be created. _rnd the random generator to be used. _dist the random distribution to be used.

Definition at line 294 of file tensor.h.

## ◆ random() [4/4]

template<class distribution = std::normal_distribution<value_t>, class generator = std::mt19937_64>
 static XERUS_force_inline Tensor XERUS_warn_unused xerus::Tensor::random ( std::initializer_list< size_t > && _dimensions, const size_t _N, distribution & _dist, generator & _rnd )
inlinestatic

Constructs a random sparse Tensor with the given dimensions.

See the std::vector variant for details.

Definition at line 311 of file tensor.h.

## ◆ random_orthogonal()

template<class generator = std::mt19937_64>
 static Tensor XERUS_warn_unused xerus::Tensor::random_orthogonal ( DimensionTuple _dimensions1, DimensionTuple _dimensions2, generator & _rnd = xerus::misc::randomEngine )
inlinestatic

Constructs a dense Tensor with the given dimensions and uses the given random generator and distribution to assign the values to the entries.

The entries are assigned in the order they are stored (i.e. row-major order). Each assigned is a seperate call to the random distribution.

Parameters
 _dimensions the future dimensions of the Tensor. _rnd the random generator to be used. _dist the random distribution to be used.

Definition at line 241 of file tensor.h.

## ◆ reinterpret_dimensions()

 void xerus::Tensor::reinterpret_dimensions ( DimensionTuple _newDimensions )

Reinterprets the dimensions of the tensor.

For this simple reinterpretation it is nessecary that the size implied by the new dimensions is the same as to old size (a vector with 16 entries cannot be interpreted as a 10x10 matrix, but it can be interpreted as a 4x4 matrix). If a real change in size is required use resize_mode() instead.

Parameters
 _newDimensions the dimensions the tensor shall be interpreted to have.

Definition at line 620 of file tensor.cpp.

## ◆ remove_slate()

 void xerus::Tensor::remove_slate ( const size_t _mode, const size_t _pos )

Removes a single slate from the Tensor, reducing dimension[_mode] by one.

Parameters
 _mode the mode that will be reduced. _pos the index within the selected mode for which the slate shall be removed.

Definition at line 772 of file tensor.cpp.

## ◆ reorder_cost()

 size_t xerus::Tensor::reorder_cost ( ) const

Approximates the cost to reorder the tensor.

Returns
the approximated costs.

Definition at line 270 of file tensor.cpp.

## ◆ reset() [1/6]

 void xerus::Tensor::reset ( DimensionTuple _newDim, const Representation _representation, const Initialisation _init = Initialisation::Zero )

Resets the tensor to the given dimensions and representation.

Leaves the Tensor in the same state as if newly constructed with the the same arguments.

Parameters
 _newDim the dimensions of the new tensor. _representation the new representation of the tensor. _init (optional) data treatment, i.e. whether the tensor shall be zero initialized.

Definition at line 500 of file tensor.cpp.

## ◆ reset() [2/6]

 void xerus::Tensor::reset ( DimensionTuple _newDim, const Initialisation _init = Initialisation::Zero )

Resets the tensor to the given dimensions, preserving the current representation.

Parameters
 _newDim the dimensions of the new tensor. _init (optional) data treatment, i.e. whether the tensor shall be zero initialized.

Definition at line 536 of file tensor.cpp.

## ◆ reset() [3/6]

 void xerus::Tensor::reset ( )

Resets the tensor as if default initialized.

Definition at line 559 of file tensor.cpp.

## ◆ reset() [4/6]

 void xerus::Tensor::reset ( DimensionTuple _newDim, const std::shared_ptr< value_t > & _newData )

Resets the tensor to the given dimensions and uses the given data.

Parameters
 _newDim the dimensions of the new tensor. _newData new dense data in row-major order.

Definition at line 579 of file tensor.cpp.

## ◆ reset() [5/6]

 void xerus::Tensor::reset ( DimensionTuple _newDim, std::unique_ptr< value_t[]> && _newData )

Resets the tensor to the given dimensions with data _newData.

Parameters
 _newDim the dimensions of the new tensor. _newData new dense data in row-major order.

Definition at line 593 of file tensor.cpp.

## ◆ reset() [6/6]

 void xerus::Tensor::reset ( DimensionTuple _newDim, std::map< size_t, value_t > && _newData )

Resets the tensor to a given dimensionstuple with sparse data _newData.

Definition at line 606 of file tensor.cpp.

## ◆ resize_mode()

 void xerus::Tensor::resize_mode ( const size_t _mode, const size_t _newDim, size_t _cutPos = ~0ul )

Resizes a specific mode of the Tensor.

Use this function only if the content of the tensor shall stay, otherwise use reset().

Parameters
 _mode the mode to resize. _newDim the new dimension that mode shall have. _cutPos the position within the selected mode in front of which slates are inserted or removed. By default the current dimension, i.e new slates are added after the last current one and removed starting from the last one.

Definition at line 626 of file tensor.cpp.

## ◆ sparse_copy()

 Tensor xerus::Tensor::sparse_copy ( ) const

Returns a copy of this Tensor that uses a sparse representation.

Definition at line 194 of file tensor.cpp.

## ◆ sparsity()

 size_t xerus::Tensor::sparsity ( ) const

Returns the number currently saved entries.

Note that this is not nessecarily the number of non-zero entries as the saved entries may contain zeros. Even more if a dense representation is used size is returned.

Definition at line 232 of file tensor.cpp.

## ◆ to_string()

 std::string xerus::Tensor::to_string ( ) const

Creates a string representation of the Tensor.

Note
the mapping is not unique and can thus not be used to recreate the original tensor
Returns
the string representation.

Definition at line 1067 of file tensor.cpp.

## ◆ use_dense_representation()

 void xerus::Tensor::use_dense_representation ( )

Converts the Tensor to a dense representation.

Definition at line 1028 of file tensor.cpp.

## ◆ use_dense_representation_if_desirable()

 void xerus::Tensor::use_dense_representation_if_desirable ( )

Converts the Tensor to a dense representation if sparsity * sparsityFactor >= size.

Definition at line 1043 of file tensor.cpp.

## ◆ use_sparse_representation()

 void xerus::Tensor::use_sparse_representation ( const value_t _eps = std::numeric_limits::epsilon() )

Converts the Tensor to a sparse representation.

Definition at line 1050 of file tensor.cpp.

## ◆ dimensions

 DimensionTuple xerus::Tensor::dimensions

Vector containing the individual dimensions of the tensor.

Definition at line 99 of file tensor.h.

## ◆ factor

 value_t xerus::Tensor::factor = 1.0

Single value representing a constant scaling factor.

Definition at line 105 of file tensor.h.

## ◆ representation

 Representation xerus::Tensor::representation = Representation::Sparse

The current representation of the Tensor (i.e Dense or Sparse)

Definition at line 108 of file tensor.h.

## ◆ size

 size_t xerus::Tensor::size = 1

Size of the Tensor – always equal to the product of the dimensions.

Definition at line 102 of file tensor.h.

## ◆ sparsityFactor

 size_t xerus::Tensor::sparsityFactor = 4
static

Definition at line 72 of file tensor.h.

The documentation for this class was generated from the following files:
• /home/gitlab-runner/builds/9071116c/0/xerus/xerus/include/xerus/tensor.h
• /home/gitlab-runner/builds/9071116c/0/xerus/xerus/src/xerus/tensor.cpp