Class TensorNetwork

Nested Relationships

Nested Types

Class Documentation

class TensorNetwork

A (non-directed) graph view of a sequence of AbstractTensor objects.

Note

The main role of this is to canonize itself. Since Tensor objects can be connected by multiple Index’es (thus edges are colored), what is canonized is actually the graph of indices (roughly the dual of the tensor graph), with Tensor objects represented by one or more vertices.

Warning

the terminology is a mix at best, e.g. terminal vs. slot, etc.

Public Types

using named_indices_t = container::set<Index, Index::FullLabelCompare>

Public Functions

template<typename ExprPtrRange>
inline TensorNetwork(ExprPtrRange &exprptr_range)

Note

uses RTTI

Throws:

std::logic_error – if exprptr_range contains a non-tensor

inline const auto &tensors() const

Note

after invoking TensorNetwork::canonicalize() the order of tensors may be different from that provided as input; use tensor_input_ordinals() to obtain the input ordinals of the tensors in the result

Returns:

const reference to the sequence of tensors

inline const auto &tensor_input_ordinals() const
ExprPtr canonicalize(const container::vector<std::wstring> &cardinal_tensor_labels = {}, bool fast = true, const named_indices_t *named_indices = nullptr)
Parameters:

  • cardinal_tensor_labels – move all tensors with these labels to the front before canonicalizing indices

  • fast – if true (default), does fast canonicalization that is only optimal if all tensors are distinct; set to false to perform complete canonicalization

  • named_indices – specifies the indices that cannot be renamed, i.e. their labels are meaningful; default is nullptr, which results in external indices treated as named indices

Returns:

byproduct of canonicalization (e.g. phase); if none, returns nullptr

SlotCanonicalizationMetadata canonicalize_slots(const container::vector<std::wstring> &cardinal_tensor_labels = {}, const named_indices_t *named_indices = nullptr, SlotCanonicalizationMetadata::named_index_compare_t named_index_compare = default_idxptr_slottype_lesscompare{})

Like canonicalize(), but only use graph-based canonicalization to produce canonical list of slots occupied by named indices. This is sufficient to be able to match 2 tensor networks that differ in anonymous and named indices.

Parameters:

  • cardinal_tensor_labels – move all tensors with these labels to the front before canonicalizing indices

  • named_indices – specifies the indices that cannot be renamed, i.e. their labels are meaningful; default is nullptr, which results in external indices treated as named indices

  • named_index_compare – less-than comparison function for named indices, used for coarse-grained sorting of named indices, before sorting to canonical order; the default is to sort by Index::space()

Returns:

the computed canonicalization metadata

container::svector<std::pair<long, long>> factorize()

Factorizes tensor network

Returns:

sequence of binary products; each element encodes the tensors to be multiplied (values >0 refer to the tensors in tensors(), values <0 refer to the elements of this sequence. E.g. sequences {{0,1},{-1,2},{-2,3}} , {{0,2},{1,3},{-1,-2}} , {{3,1},{2,-1},{0,-2}} encode the following respective factorizations (((T0*T1)*T2)*T3) , ((T0*T2)*(T1*T3)) , and (((T3*T1)*T2)*T0) .

inline const auto &edges() const

accessor for the Edge object sequence

See also

Edge

Returns:

const reference to the sequence container of Edge objects, sorted by their Index’s full label

inline const auto &ext_indices() const

Returns a range of external indices, i.e. those indices that do not connect tensors.

Note

The external indices are sorted by label (not full label) of the corresponding value (Index)

inline const auto &idxrepl() const

accessor for the list of anonymous index replacements performed by the last call to canonicalize()

Returns:

replacements of anonymous indices performed by the last call to canonicalize()

GraphData make_bliss_graph (const BlissGraphOptions &options={ .named_indices=nullptr,.distinct_named_indices=true,.make_labels=true,.make_texlabels=true}) const

converts the network into a Bliss graph whose vertices are indices and tensor vertex representations

Note

Rules for constructing the graph:

  • Indices with protoindices are connected to their protoindices, either directly or (if protoindices are symmetric) via a protoindex vertex.

  • Indices are colored by their space, which in general encodes also the space of the protoindices.

  • An anti/symmetric n-body tensor has 2 terminals, each connected to each other + to n index vertices.

  • A nonsymmetric n-body tensor has n terminals, each connected to 2 indices and 1 tensor vertex which is connected to all n terminal indices.

  • tensor vertices are colored by the label+rank+symmetry of the tensor; terminal vertices are colored by the color of its tensor, with the color of symm/antisymm terminals augmented by the terminal’s type (bra/ket).

Parameters:

options – [in] the options for generating the graph

Returns:

{shared_ptr to Graph, vector of vertex labels, vector of optional vertex TeX labels, vector of vertex colors, vector of vertex types, vector of cluster ordinals for each vertex}

Public Static Attributes

static constexpr size_t max_rank = 256
struct BlissGraphOptions

options for generating bliss Graph

Public Members

const named_indices_t *named_indices = nullptr

pointer to the set of named indices (ordinarily, this includes all external indices); default is nullptr, which means use all external indices for named indices

bool distinct_named_indices = true

if false, will use same color for all named indices that have same Index::color(), else will use distinct color for each

bool make_labels = true

if false, will not generate the labels

bool make_texlabels = true

if false, will not generate the TeX labels

class Edge

Edge in a TensorNetwork = the Index annotating it + a pair of indices to identify which Tensor terminals it’s connected to.

Note

tensor terminals in a sequence of tensors are indexed as follows:

  • >0 for bra terminals (i.e. “+7” indicated connection to a bra terminal of 7th tensor object in the sequence)

  • <0 for ket terminals

  • 0 if free (not attached to any tensor objects)

  • position records the terminal’s location in the sequence of bra/ket/aux terminals (always 0 for symmetric/antisymmetric tensors) Terminal indices are sorted by the tensor index (i.e. by the absolute value of the terminal index), followed by position

Public Functions

Edge() = default
inline explicit Edge(const Terminal &t)
inline Edge(const Terminal &t, const Index *idxptr)
inline Edge &connect_to(const Terminal &t)
inline bool operator<(const Edge &other) const
inline const auto &first() const
inline const auto &second() const
inline const auto &operator[](std::size_t i) const

access terminals by index, nonnull terminals first

Parameters:

i – the ordinal index, i must be 0 or 1

Returns:

if i==0 return first(), if nonnull, else second(), if nonnull, else null; if i==1 return second(), if nonnull, else else null;

inline auto size() const
Returns:

the number of attached terminals (0, 1, or 2)

inline const Index &idx() const

Friends

inline friend bool operator==(const Edge &a, const Edge &b)
struct Terminal

Public Functions

inline Terminal() noexcept
inline Terminal(int tensor_ord, TensorIndexSlotType slot_type, int slot_group_ord) noexcept
inline explicit operator bool() const
inline bool null() const
inline bool nonnull() const

Public Members

int tensor_ord = -1
TensorIndexSlotType slot_type = TensorIndexSlotType::Invalid
int slot_group_ord = -1

Friends

inline friend bool operator==(const Terminal &a, const Terminal &b)
inline friend bool operator<(const Terminal &a, const Terminal &b)
struct GraphData

contains bliss::Graph representation of TN + metadata

Note

it works with structured bindings

Public Types

using VertexColor = unsigned int

this is the type used as color by bliss::Graph

Public Functions

std::optional<std::size_t> vertex_to_tensor_cluster(std::size_t vertex) const

maps vertex ordinal to tensor cluster ordinal

Note

usable as blis::Graph::DotOptions::vertex_to_subgraph

template<std::size_t Index>
inline auto &&get() &
template<std::size_t Index>
inline auto &&get() &&
template<std::size_t Index>
inline auto &&get() const &
template<std::size_t Index>
inline auto &&get() const &&

Public Members

std::shared_ptr<bliss::Graph> graph

bliss::Graph

std::vector<std::wstring> vertex_labels

vertex labels

std::vector<std::optional<std::wstring>> vertex_texlabels

optional vertex TeX labels usable for dot2tex

std::vector<VertexColor> vertex_colors

vertex colors

std::vector<VertexType> vertex_types

vertex types

struct SlotCanonicalizationMetadata

metadata produced by canonicalize_slots()

Public Types

using named_index_compare_t = std::function<bool(const std::pair<const Index*, IndexSlotType>&, const std::pair<const Index*, IndexSlotType>&)>

type of less-than comparison function for named indices, receives {Index ptr, its slot type}

Public Functions

size_t hash_value() const
inline auto get_index_view() const
template<typename Cont>
inline auto get_indices() const

Public Members

named_indices_t named_indices

list of named indices

named_index_compare_t named_index_compare

less-than comparison function for named indices, used for coarse-grained sorting of named indices, before sorting to canonical order

container::svector<named_indices_t::const_iterator> named_indices_canonical

list of named indices, sorted first by named_index_compare, then by canonical order; iterators point to named_indices

std::shared_ptr<bliss::Graph> graph

canonicalized colored graph, use graph->cmp to compare against another to detect equivalence

std::int8_t phase = +1

if tensor network contains tensors with antisymmetric bra/ket this reports the phase change due to permutation of slots relative to their input order