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...

template<XERUS_ADD_MOVE(Vec, DimensionTuple) , XERUS_ADD_MOVE(SPtr, std::shared_ptr< value_t >) >
	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_t &	at (const size_t _position)
	Unsanitized access to a single entry. More...

value_t	cat (const size_t _position) const
	Unsanitized read access to a single entry. More...

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_t *	get_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_t *	get_unsanitized_dense_data ()
	Gives access to the internal data pointer, without any checks. More...

const value_t *	get_unsanitized_dense_data () const
	Gives access to the internal data pointer, without any checks. More...

std::map< size_t, value_t > &	get_unsanitized_sparse_data ()
	Gives access to the internal sparse map, without any checks. More...

const std::map< size_t, value_t > &	get_unsanitized_sparse_data () const
	Gives access to the internal sparse map, without any checks. More...

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< Tensor >	operator() (args... _args)
	Indexes the Tensor for read/write use. More...

template<typename... args>
internal::IndexedTensorReadOnly< Tensor >	operator() (args... _args) const
	Indexes the Tensor for read only use. More...

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

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

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

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

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

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

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

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

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

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

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

value_t &	operator[] (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_t &	operator[] (const MultiIndex &_positions)
	Read/Write access a single entry. More...

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

value_t *	override_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.

Member Typedef Documentation

◆ DimensionTuple

typedef std::vector<size_t> xerus::Tensor::DimensionTuple

: Represention of the dimensions of a Tensor.

Definition at line 92 of file tensor.h.

◆ MultiIndex

typedef std::vector<size_t> 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.

Member Enumeration Documentation

◆ 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.

Constructor & Destructor Documentation

◆ 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]

template<XERUS_ADD_MOVE(Vec, DimensionTuple) , XERUS_ADD_MOVE(SPtr, std::shared_ptr< value_t >) >

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

◆ add_sparse_to_full()

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.

◆ add_sparse_to_sparse()

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 )

Unsanitized access to a single entry.

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

Unsanitized read access to a single entry.

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<value_t>::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 ( )

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

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 ( )

Returns a reference for direct access to the sparse data map.

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 ( )

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

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

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

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 ( )

Gives access to the internal sparse map, 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: 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

Gives access to the internal sparse map, 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: 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.

◆ offset_add()

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<Tensor> 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<Tensor> 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 )

Read/Write access a single entry.

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

Read access a single entry.

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 )

Read/Write access a single entry.

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

Read access a single entry.

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<value_t>::epsilon() )

Converts the Tensor to a sparse representation.

Definition at line 1050 of file tensor.cpp.

Member Data Documentation

◆ 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

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ DimensionTuple

◆ MultiIndex

Member Enumeration Documentation

◆ Initialisation

◆ Representation

Constructor & Destructor Documentation

◆ Tensor() [1/10]

◆ Tensor() [2/10]

◆ Tensor() [3/10]

◆ Tensor() [4/10]

◆ Tensor() [5/10]

◆ Tensor() [6/10]

◆ Tensor() [7/10]

◆ Tensor() [8/10]

◆ Tensor() [9/10]

◆ Tensor() [10/10]

Member Function Documentation

◆ add_sparse_to_full()

◆ add_sparse_to_sparse()

◆ all_entries_valid()

◆ apply_factor()

◆ at()

◆ cat()

◆ count_non_zero_entries()

◆ degree()

◆ dense_copy()

◆ dirac() [1/2]

◆ dirac() [2/2]

◆ ensure_own_data()

◆ ensure_own_data_and_apply_factor()

◆ ensure_own_data_no_copy()

◆ fix_mode()

◆ frob_norm()

◆ get_dense_data()

◆ get_internal_dense_data()

◆ get_internal_sparse_data()

◆ get_sparse_data()

◆ get_unsanitized_dense_data() [1/2]

◆ get_unsanitized_dense_data() [2/2]

◆ get_unsanitized_sparse_data() [1/2]

◆ get_unsanitized_sparse_data() [2/2]

◆ has_factor()

◆ identity()

◆ is_dense()

◆ is_sparse()

◆ kronecker()

◆ modify_diagonal_entries() [1/2]

◆ modify_diagonal_entries() [2/2]

◆ modify_entries() [1/3]

◆ modify_entries() [2/3]

◆ modify_entries() [3/3]

◆ multiIndex_to_position()

◆ offset_add()

◆ one_norm()

◆ ones()

◆ operator()() [1/6]

◆ operator()() [2/6]

◆ operator()() [3/6]

◆ operator()() [4/6]

◆ operator()() [5/6]

◆ operator()() [6/6]

◆ operator*=()

◆ operator+=()

◆ operator-=()

◆ operator/=()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator[]() [1/4]

◆ operator[]() [2/4]

◆ operator[]() [3/4]

◆ operator[]() [4/4]