xerus
a general purpose tensor library

Very general class used to represent arbitary tensor networks. More...
#include <tensorNetwork.h>
Classes  
class  Link 
Class representing a link from a TensorNode to another node or an external index. More...  
class  TensorNode 
The TensorNode class is used by the class TensorNetwork to store the componentent tensors defining the network. More...  
Public Types  
using  RankTuple = std::vector< size_t > 
: Represention of the ranks of a TensorNetwork. More...  
Public Member Functions  
TensorNetwork ()  
Constructs an order zero TensorNetwork. More...  
TensorNetwork (const TensorNetwork &_cpy)=default  
Copy Constructor. More...  
TensorNetwork (TensorNetwork &&_mv) noexcept=default  
Move Constructor. More...  
TensorNetwork (Tensor _other)  
Constructs the trivial TensorNetwork containing the given Tensor as single node. More...  
TensorNetwork (std::unique_ptr< Tensor > &&_tensor)  
Constructs the trivial TensorNetwork containing the given Tensor as single node. The TN takes the ownership of the pointer. More...  
TensorNetwork (size_t _degree)  
Constructs the trivial TensorNetwork containing a Tensor with the given degree. More...  
TensorNetwork (const ZeroNode _nodeStatus)  
(Internal) Constructs an order zero TensorNetwork. More...  
virtual  ~TensorNetwork ()=default 
Destructor. More...  
void  contract (const size_t _nodeId1, const size_t _nodeId2) 
Contracts the nodes with indices _nodeId1 and _nodeId2. More...  
size_t  contract (const std::set< size_t > &_ids) 
Contracts the nodes with with indices included in the given set _ids. More...  
double  contraction_cost (const size_t _nodeId1, const size_t _nodeId2) const 
Approximates the cost of contraction two given nodes. More...  
size_t  datasize () const 
Calculates the storage requirement of the current representation. More...  
size_t  degree () const 
Gets the degree of the TensorNetwork. More...  
void  draw (const std::string &_filename) const 
Draws a graph representation of the TensorNetwork. More...  
std::pair< size_t, size_t >  find_common_edge (const size_t _nodeA, const size_t _nodeB) const 
Finds the position of a single common edge between two nodes. More...  
virtual 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...  
virtual value_t  frob_norm () const 
Calculates the frobenious norm of the TensorNetwork. More...  
virtual TensorNetwork *  get_copy () const 
Returns a new copy of the network. More...  
operator Tensor () const  
Explicit cast to Tensor. More...  
template<typename... args>  
internal::IndexedTensor< TensorNetwork >  operator() (args... _args) 
Indexes the TensorNetwork for read/write use. More...  
template<typename... args>  
internal::IndexedTensorReadOnly< TensorNetwork >  operator() (args... _args) const 
Indexes the TensorNetwork for read only use. More...  
internal::IndexedTensor< TensorNetwork >  operator() (const std::vector< Index > &_indices) 
Indexes the TensorNetwork for read/write use. More...  
internal::IndexedTensor< TensorNetwork >  operator() (std::vector< Index > &&_indices) 
Indexes the TensorNetwork for read/write use. More...  
internal::IndexedTensorReadOnly< TensorNetwork >  operator() (const std::vector< Index > &_indices) const 
Indexes the TensorNetwork for read only use. More...  
internal::IndexedTensorReadOnly< TensorNetwork >  operator() (std::vector< Index > &&_indices) const 
Indexes the TensorNetwork for read only use. More...  
virtual void  operator*= (const value_t _factor) 
Performs the entrywise multiplication with a constant _factor. More...  
virtual void  operator/= (const value_t _divisor) 
Performs the entrywise divison by a constant _divisor. More...  
TensorNetwork &  operator= (const TensorNetwork &_cpy)=default 
TensorNetworks are copy assignable. More...  
TensorNetwork &  operator= (TensorNetwork &&_mv)=default 
TensorNetworks are move assignable. More...  
value_t  operator[] (const size_t _position) const 
Read the value at a specific position. More...  
value_t  operator[] (const std::vector< size_t > &_positions) const 
Read the value at a specific position. More...  
void  reduce_representation () 
Contracts all nodes that are joined by a fullrank edge. More...  
virtual void  remove_slate (const size_t _mode, const size_t _slatePosition) 
removes the given _slatePosition from the _mode. this reduces the given dimension by one More...  
virtual void  require_correct_format () const 
Sanity check for the TensorNetwork and if applicable for the specific format. More...  
void  require_valid_network (const bool _check_erased=true) const 
Sanity checks the network. More...  
void  reshuffle_nodes (const std::function< size_t(size_t)> &_f) 
reshuffled the nodes according to the given function More...  
virtual void  resize_mode (const size_t _mode, const size_t _newDim, const size_t _cutPos=~0ul) 
Resizes a specific mode of the TensorNetwork. More...  
virtual void  round_edge (const size_t _nodeA, const size_t _nodeB, const size_t _maxRank, const double _eps, const double _softThreshold) 
Thresholds the rank between two given nodes. More...  
void  sanitize () 
Removes all erased nodes from the TensorNetwork. More...  
virtual bool  specialized_contraction (std::unique_ptr< internal::IndexedTensorMoveable< TensorNetwork >> &_out, internal::IndexedTensorReadOnly< TensorNetwork > &&_me, internal::IndexedTensorReadOnly< TensorNetwork > &&_other) const 
(Internal) Calculates the contraction between _me and _other and stores the result in _out. Requires that *this is the tensorObjectReadOnly of _me. More...  
virtual void  specialized_evaluation (internal::IndexedTensorWritable< TensorNetwork > &&_me, internal::IndexedTensorReadOnly< TensorNetwork > &&_other) 
(Internal) Evaluates _other into _me. Requires that *this is the tensorObjectReadOnly of _me. More...  
virtual bool  specialized_sum (std::unique_ptr< internal::IndexedTensorMoveable< TensorNetwork >> &_out, internal::IndexedTensorReadOnly< TensorNetwork > &&_me, internal::IndexedTensorReadOnly< TensorNetwork > &&_other) const 
(Internal) Calculates the sum between _me and _other and stores the result in _out. Requires that *this is the tensorObjectReadOnly of _me. More...  
void  swap_external_links (const size_t _i, const size_t _j) 
Swaps the external indices _i and _j, effectively changing those indices for the represented Tensor (e.g. a transposition for matrices). More...  
virtual void  transfer_core (const size_t _from, const size_t _to, const bool _allowRankReduction=true) 
Transfers the core from one given node to another. More...  
Static Public Member Functions  
static void  add_network_to_network (internal::IndexedTensorWritable< TensorNetwork > &&_base, internal::IndexedTensorReadOnly< TensorNetwork > &&_toInsert) 
Inserts all nodes from _toInsert into _base, creating links where demanded by the indices. More...  
static void  link_traces_and_fix (internal::IndexedTensorWritable< TensorNetwork > &&_base) 
Finds traces defined by the indices and internally links the corresponding indices. Also applys all fixed indices. More...  
Public Attributes  
std::vector< size_t >  dimensions 
Dimensions of the external indices, i.e. the dimensions of the tensor represented by the network. More...  
std::vector< Link >  externalLinks 
The open links of the network in order. More...  
std::vector< TensorNode >  nodes 
The nodes constituting the network. The order determines the ids of the nodes. More...  
Protected Types  
enum  ZeroNode : bool { ZeroNode::None, ZeroNode::Add } 
Internal indicator to prevent the creation of an degree zero node in TensorNetwork constructor. More...  
Protected Member Functions  
virtual void  contract_unconnected_subnetworks () 
Contracts all nodes that are not connected to any external links. More...  
std::vector< Link >  init_from_dimension_array () 
: Sets the externalLinks and returns an Link vector for a node, assuming that this node is the only node there is and all given dimensions are open. More...  
void  perform_traces (const size_t _nodeId) 
Performs all traces in the given node. More...  
TensorNetwork  stripped_subnet (const std::function< bool(size_t)> &_idF=[](size_t){ return true;}) const 
Creates a dataless copy of a subnet. More...  
Very general class used to represent arbitary tensor networks.
Used as a basis for tensor decompositions like the TTNetwork but also used for the lazy evaluation of Tensor contractions.
Definition at line 42 of file tensorNetwork.h.
using xerus::TensorNetwork::RankTuple = std::vector<size_t> 
: Represention of the ranks of a TensorNetwork.
Definition at line 45 of file tensorNetwork.h.

strongprotected 
Internal indicator to prevent the creation of an degree zero node in TensorNetwork constructor.
Enumerator  

None  
Add 
Definition at line 126 of file tensorNetwork.h.

explicit 
Constructs an order zero TensorNetwork.
The order of an empty TN is zero.
Definition at line 46 of file tensorNetwork.cpp.

default 
Copy Constructor.

defaultnoexcept 
Move Constructor.
xerus::TensorNetwork::TensorNetwork  (  Tensor  _other  ) 
Constructs the trivial TensorNetwork containing the given Tensor as single node.
Definition at line 51 of file tensorNetwork.cpp.
xerus::TensorNetwork::TensorNetwork  (  std::unique_ptr< Tensor > &&  _tensor  ) 
Constructs the trivial TensorNetwork containing the given Tensor as single node. The TN takes the ownership of the pointer.
Definition at line 56 of file tensorNetwork.cpp.
xerus::TensorNetwork::TensorNetwork  (  size_t  _degree  ) 
Constructs the trivial TensorNetwork containing a Tensor with the given degree.
All dimensions are set equals one and the only entry of the tensor is zero.
Definition at line 61 of file tensorNetwork.cpp.

explicit 
(Internal) Constructs an order zero TensorNetwork.
The order of an empty TN is zero.
_nodeStatus  defines whether the network will contain one degree zero node with the single entry zero. 
Definition at line 66 of file tensorNetwork.cpp.

virtualdefault 
Destructor.

static 
Inserts all nodes from _toInsert into _base, creating links where demanded by the indices.
Definition at line 553 of file tensorNetwork.cpp.
void xerus::TensorNetwork::contract  (  const size_t  _nodeId1, 
const size_t  _nodeId2  
) 
Contracts the nodes with indices _nodeId1 and _nodeId2.
Replaces _nodeId1 with the contraction and erases _nodeId2.
_nodeId1  The first node, that will contain the result afterwards. 
_nodeId2  The second node, that will be erased afterwards. 
Definition at line 1037 of file tensorNetwork.cpp.
size_t xerus::TensorNetwork::contract  (  const std::set< size_t > &  _ids  ) 
Contracts the nodes with with indices included in the given set _ids.
Erases all nodes but one, which id is returned.
_ids  set with all ids to be erased. 
Definition at line 1253 of file tensorNetwork.cpp.

protectedvirtual 
Contracts all nodes that are not connected to any external links.
Reimplemented in xerus::TTNetwork< isOperator >, and xerus::TTNetwork< false >.
Definition at line 134 of file tensorNetwork.cpp.
double xerus::TensorNetwork::contraction_cost  (  const size_t  _nodeId1, 
const size_t  _nodeId2  
)  const 
Approximates the cost of contraction two given nodes.
_nodeId1  id of the first node. 
_nodeId2  id of the second node. 
Definition at line 1232 of file tensorNetwork.cpp.
size_t xerus::TensorNetwork::datasize  (  )  const 
Calculates the storage requirement of the current representation.
Definition at line 455 of file tensorNetwork.cpp.
size_t xerus::TensorNetwork::degree  (  )  const 
Gets the degree of the TensorNetwork.
The degree is defined as the number of dimensions (i.e. dimensions.size()) and is always equal to the number of externalLinks (i.e. externalLinks.size()).
Definition at line 451 of file tensorNetwork.cpp.
void xerus::TensorNetwork::draw  (  const std::string &  _filename  )  const 
Draws a graph representation of the TensorNetwork.
The drawing is realized by a system call to "dot" which plots the graph structure.
_filename  path and name of the file where to save the image. 
Definition at line 1344 of file tensorNetwork.cpp.
std::pair< size_t, size_t > xerus::TensorNetwork::find_common_edge  (  const size_t  _nodeA, 
const size_t  _nodeB  
)  const 
Finds the position of a single common edge between two nodes.
_nodeA  The first node. 
_nodeB  The second node. 
Definition at line 201 of file tensorNetwork.cpp.

virtual 
Fixes a specific mode to a specific value, effectively reducing the order by one.
_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. 
Reimplemented in xerus::TTNetwork< isOperator >, and xerus::TTNetwork< false >.
Definition at line 912 of file tensorNetwork.cpp.

virtual 
Calculates the frobenious norm of the TensorNetwork.
Reimplemented in xerus::TTNetwork< isOperator >, xerus::TTNetwork< false >, and xerus::internal::TTStack< isOperator >.
Definition at line 1336 of file tensorNetwork.cpp.

virtual 
Returns a new copy of the network.
Reimplemented in xerus::TTNetwork< isOperator >, xerus::TTNetwork< false >, and xerus::internal::TTStack< isOperator >.
Definition at line 72 of file tensorNetwork.cpp.

protected 
: Sets the externalLinks and returns an Link vector for a node, assuming that this node is the only node there is and all given dimensions are open.
Definition at line 79 of file tensorNetwork.cpp.

static 
Finds traces defined by the indices and internally links the corresponding indices. Also applys all fixed indices.
For each trace this reduces the degree of the TN by two and removes two indices from the IndexedTensor.
Definition at line 598 of file tensorNetwork.cpp.

explicit 
Explicit cast to Tensor.
Contracts the complete network into a single Tensor
Definition at line 287 of file tensorNetwork.cpp.

inline 
Indexes the TensorNetwork for read/write use.
_args  several indices determining the desired index order. 
Definition at line 306 of file tensorNetwork.h.

inline 
Indexes the TensorNetwork for read only use.
_args  several indices determining the desired index order. 
Definition at line 317 of file tensorNetwork.h.
internal::IndexedTensor< TensorNetwork > xerus::TensorNetwork::operator()  (  const std::vector< Index > &  _indices  ) 
Indexes the TensorNetwork for read/write use.
_args  several indices determining the desired index order. 
Definition at line 383 of file tensorNetwork.cpp.
internal::IndexedTensor< TensorNetwork > xerus::TensorNetwork::operator()  (  std::vector< Index > &&  _indices  ) 
Indexes the TensorNetwork for read/write use.
_args  several indices determining the desired index order. 
Definition at line 388 of file tensorNetwork.cpp.
internal::IndexedTensorReadOnly< TensorNetwork > xerus::TensorNetwork::operator()  (  const std::vector< Index > &  _indices  )  const 
Indexes the TensorNetwork for read only use.
_args  several indices determining the desired index order. 
Definition at line 393 of file tensorNetwork.cpp.
internal::IndexedTensorReadOnly< TensorNetwork > xerus::TensorNetwork::operator()  (  std::vector< Index > &&  _indices  )  const 
Indexes the TensorNetwork for read only use.
_args  several indices determining the desired index order. 
Definition at line 398 of file tensorNetwork.cpp.

virtual 
Performs the entrywise multiplication with a constant _factor.
Internally this only results in a change in the global factor.
_factor  the factor, 
Reimplemented in xerus::TTNetwork< isOperator >, xerus::TTNetwork< false >, and xerus::internal::TTStack< isOperator >.
Definition at line 368 of file tensorNetwork.cpp.

virtual 
Performs the entrywise divison by a constant _divisor.
Internally this only results in a change in the global factor.
_divisor  the divisor, 
Reimplemented in xerus::TTNetwork< isOperator >, xerus::TTNetwork< false >, and xerus::internal::TTStack< isOperator >.
Definition at line 375 of file tensorNetwork.cpp.

default 
TensorNetworks are copy assignable.

default 
TensorNetworks are move assignable.
value_t xerus::TensorNetwork::operator[]  (  const size_t  _position  )  const 
Read the value at a specific position.
This allows the efficent calculation of a single entry of the TensorNetwork, by first fixing the external dimensions and then completly contracting the network. Do NOT use this as a manual cast to Tensor (there is an explicit cast for that).
_position  the position of the entry to be read assuming rowmajor ordering and a single node. 
Definition at line 310 of file tensorNetwork.cpp.
value_t xerus::TensorNetwork::operator[]  (  const std::vector< size_t > &  _positions  )  const 
Read the value at a specific position.
This allows the efficent calculation of a single entry of the TensorNetwork, by first fixing the external dimensions and then completly contracting the network. Do NOT use this as a manual cast to Tensor (there is an explicit cast for that).
_positions  the position of the entry to be read assuming a single node. 
Definition at line 331 of file tensorNetwork.cpp.

protected 
Performs all traces in the given node.
_nodeId  id of the node for which the traces shall be performed. 
Definition at line 222 of file tensorNetwork.cpp.
void xerus::TensorNetwork::reduce_representation  (  ) 
Contracts all nodes that are joined by a fullrank edge.
This reduces the overall storage requirements and can be useful to store intermediate results e.g. after fixing one of several indices.
Definition at line 990 of file tensorNetwork.cpp.

virtual 
removes the given _slatePosition from the _mode. this reduces the given dimension by one
Definition at line 954 of file tensorNetwork.cpp.

virtual 
Sanity check for the TensorNetwork and if applicable for the specific format.
Checks whether all links in the network are set consistently and matching the underlying tensor objects. This also checks whether the additional constrains of the specific format (if any) are fullfilled.
Reimplemented in xerus::TTNetwork< isOperator >, and xerus::TTNetwork< false >.
Definition at line 538 of file tensorNetwork.cpp.
void xerus::TensorNetwork::require_valid_network  (  const bool  _check_erased = true  )  const 
Sanity checks the network.
Checks whether all links in the network are set consistently and matching the underlying tensor objects. If not an exception is throws and the function does not return. Note that this only checks whether the TensorNetwork is valid not whether the additional constrains of a specific format are fullfilled. For this purpose use is_in_expected_format().
Definition at line 485 of file tensorNetwork.cpp.
void xerus::TensorNetwork::reshuffle_nodes  (  const std::function< size_t(size_t)> &  _f  ) 
reshuffled the nodes according to the given function
Definition at line 463 of file tensorNetwork.cpp.

virtual 
Resizes a specific mode of the TensorNetwork.
_mode  the mode to resize. 
_newDim  the new value that resized 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. 
Reimplemented in xerus::TTNetwork< isOperator >, and xerus::TTNetwork< false >.
Definition at line 974 of file tensorNetwork.cpp.

virtual 
Thresholds the rank between two given nodes.
The given nodes must be joined by a single edge. Both nodes are contracted and an SVD is calculated to perform the thresholding. The obtained core is contracted to nodeB, i.e. nodeA remains orthogonal in the used matrification.
_nodeA  First node that takes part in the rank thresholding. This node remains orthogonalized. 
_nodeB  Second node that takes part in the rank thresholding. This nodes carries the core afterwards. 
_maxRank  Maximal allowed rank. 
_eps  Epsilion to be used in the SVD to determine zero singular values. 
_softThreshold  Softthreshold that is to be applied. 
Definition at line 678 of file tensorNetwork.cpp.
void xerus::TensorNetwork::sanitize  (  ) 
Removes all erased nodes from the TensorNetwork.
The order of the node ids is retained, but the ids might decrease due to removed nodes.
Definition at line 258 of file tensorNetwork.cpp.

virtual 
(Internal) Calculates the contraction between _me and _other and stores the result in _out. Requires that *this is the tensorObjectReadOnly of _me.
Reimplemented in xerus::TTNetwork< isOperator >, xerus::TTNetwork< false >, and xerus::internal::TTStack< isOperator >.
Definition at line 404 of file tensorNetwork.cpp.

virtual 
(Internal) Evaluates _other into _me. Requires that *this is the tensorObjectReadOnly of _me.
Reimplemented in xerus::TTNetwork< isOperator >, xerus::TTNetwork< false >, and xerus::internal::TTStack< isOperator >.
Definition at line 414 of file tensorNetwork.cpp.

virtual 
(Internal) Calculates the sum between _me and _other and stores the result in _out. Requires that *this is the tensorObjectReadOnly of _me.
Reimplemented in xerus::TTNetwork< isOperator >, xerus::TTNetwork< false >, and xerus::internal::TTStack< isOperator >.
Definition at line 409 of file tensorNetwork.cpp.

protected 
Creates a dataless copy of a subnet.
Creates a copy of this TensorNetwork containing the specified nodes, but does not propagate the data. Instead it uses the nullptr as data for all nodes.
_idF  a function returning true if its argument should be part of the stripped subnet. defaults to selecting all nodes. 
Definition at line 89 of file tensorNetwork.cpp.
void xerus::TensorNetwork::swap_external_links  (  const size_t  _i, 
const size_t  _j  
) 
Swaps the external indices _i and _j, effectively changing those indices for the represented Tensor (e.g. a transposition for matrices).
Definition at line 543 of file tensorNetwork.cpp.

virtual 
Transfers the core from one given node to another.
The given nodes must be joined by a single edge. A QR decomposition of the first node is calculated and the core contracted to the second one.
_from  First node, which remains orthogonalized. 
_to  Second node, which carries the core afterwards. 
_allowRankReduction  Flag indicating whether a rank revealing decomposition is to be used which allows the reduction of the rank. 
Definition at line 821 of file tensorNetwork.cpp.
std::vector<size_t> xerus::TensorNetwork::dimensions 
Dimensions of the external indices, i.e. the dimensions of the tensor represented by the network.
Definition at line 133 of file tensorNetwork.h.
std::vector<Link> xerus::TensorNetwork::externalLinks 
The open links of the network in order.
Definition at line 139 of file tensorNetwork.h.
std::vector<TensorNode> xerus::TensorNetwork::nodes 
The nodes constituting the network. The order determines the ids of the nodes.
Definition at line 136 of file tensorNetwork.h.