Class TensorNetworkV3

Nested Relationships

Nested Types

Class Documentation

class TensorNetworkV3

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.

Public Types

using Origin = SlotType
using NamedIndexSet = container::set<Index, Index::FullLabelCompare>

Public Functions

inline TensorNetworkV3(const Expr &expr)
inline TensorNetworkV3(const ExprPtr &expr)
template<typename ExprPtrRange, typename = std::enable_if_t<!std::is_base_of_v<ExprPtr, ExprPtrRange> && !std::is_base_of_v<Expr, ExprPtrRange>>>
inline TensorNetworkV3(const ExprPtrRange &exprptr_range)
TensorNetworkV3(TensorNetworkV3&&) noexcept
TensorNetworkV3 &operator=(TensorNetworkV3&&) noexcept
TensorNetworkV3(const TensorNetworkV3 &other)

copy constructor

Warning

does not copy edges

TensorNetworkV3 &operator=(const TensorNetworkV3 &other) noexcept

copy assignment

Warning

does not copy edges

inline const auto &tensors() const

Note

after invoking TensorNetworkV3::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 = {}, const CanonicalizeOptions &options = CanonicalizeOptions::default_options())
Parameters:
Returns:

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

SlotCanonicalizationMetadata canonicalize_slots(const container::vector<std::wstring> &cardinal_tensor_labels = {}, const NamedIndexSet *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.

Graph create_graph(const CreateGraphOptions &options = make_default_graph_options()) const

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

Consider Tensor as an example:

  • each index slot of a tensor is a vertex (b+k+a such vertices in an order-{b,k,a} tensor)

  • bra/ket slot vertices of an antisymmetric/symmetric tensor are bundled into bra/ket vertex (2 such vertices); they are subsequently bundleed into a braket vertex (1 such vertex)

  • if Tensor has asymmetric bras/kets each matching (corresponding to same particle ordinal) bra/ket slot vertex pair is bundleed into a braket vertex (max(b,k) such indices)

  • braket vertices bundleed into tensor core vertex

  • bra/ket slot vertices have same color for antisymmetric/symmetric tensors

  • for asymmetric bra/ket bra+ket+braket bundles must have same color if tensor is particle-symmetric, else

  • for tensors with bra<->ket symmetry matching bra and ket slot vertices have identical colors.

Note

Rules for constructing the graph:

  • symmetries are encoded by topology and color

  • vertex is introduced for an index slot or a bundle thereof, an index, and tensors core

    • bundles of slots include:

      • bra (bundle of 1 or more bra index slots)

      • ket

      • particle bundle (column of slots in covariant notation, e.g. a bundle of a bra index slot and ket index slot)

      • protoindex bundle (bundle of index slots attached to an Index)

    • N.B. lack of symmetry between slots and indices (can represent bundles of slots, but not bundles of indices) is due to the fact that index is already a plain index or an index with protoindices (i.e., a collection of plain indices)

    • to create a bundle of objects create the new “bundle” vertex and connect it to each object’s vertex

      • if set of n objects has symmetry with respect to permutation described by a particular irrep of S_n the colors of the objects’ vertices must be the same (else they are distinguishable)

      • for 2 objects it is not necessary to introduce a bundle vertex, but bundling is often done even for n=1 for the sake of consistency

    • vertices that can be swapped should have the same color

      • indices are colored by their space (not by label/ordinal) + the colors of their protoindices

      • slots and their bundles use custom colors (see below)

Parameters:

options – [in] the options for generating the graph

Returns:

The created Graph object

Public Static Functions

static inline constexpr int version()
Returns:

the implementation version of TN

static inline CreateGraphOptions make_default_graph_options()

Friends

friend class TensorNetworkV3Accessor
struct CreateGraphOptions

options for generating Graph from an object of this type

Public Members

const NamedIndexSet *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 = false

if false, will use same color for all named indices that have same Index::color(). This is needed to ignore labels of the external indices, which is the desired behavior for routine canonicalization that produces results independent of external slot renamings. In some circumstances where external slots are to be treated as topologically distinct (e.g. in WickTheorem) need to set this to true

bool make_labels = true

if false, will not generate the labels

bool label_prepend_ordinal = false

if true, will prepend label by vertex ordinal

bool make_xlabels = false

if false, will not generate the xlabels

std::function<std::wstring(std::size_t)> xlabel_maker = [](std::size_t vertex_ordinal) {return std::to_wstring(vertex_ordinal);}

callable that maps vertex index to xlabel

bool make_texlabels = true

if false, will not generate the TeX labels

bool texlabel_prepend_ordinal = false

if true, will prepend texlabel by vertex ordinal

bool make_idx_to_vertex = false

if false, will not generate the Index->vertex map

class Edge

a (hyper)edge in a tensor network

Edge in a TensorNetworkV3 = the Index annotating it + a list of vertices corresponding to the Tensor index slots it connects

Note

this is move-only since using pointers to refer to Index objects

Public Functions

Edge() = default
Edge(const Edge&) = delete
Edge(Edge&&) = default
Edge &operator=(const Edge&) = delete
Edge &operator=(Edge&&) = default
inline explicit Edge(const Vertex &vertex)
inline explicit Edge(std::initializer_list<Vertex> vertices)
inline Edge(const Vertex &vertex, const Index *index)
inline Edge(std::initializer_list<Vertex> vertices, const Index *index)
inline Edge &connect_to(const Vertex &vertex)
inline bool operator<(const Edge &other) const
inline bool operator==(const Edge &other) const
inline const Vertex &vertex(std::size_t i) const
Parameters:

i – vertex ordinal

Returns:

const reference to the ith Vertex object

Pre:

this->size() > i

inline std::size_t vertex_count() const
Returns:

the number of attached terminals (0 or more)

inline const Index &idx() const
struct Graph

Public Types

using VertexColor = std::uint32_t

The type used to encode the color of a vertex. The restriction of this being as 32-bit integer comes from how BLISS is trying to convert these into RGB values.

Public Functions

Graph() = default
std::size_t vertex_to_index_idx(std::size_t vertex) const
std::optional<std::size_t> vertex_to_tensor_idx(std::size_t vertex) const

maps vertex ordinal to tensor cluster ordinal

Note

usable as bliss::Graph::DotOptions::vertex_to_subgraph

Public Members

std::unique_ptr<bliss::Graph> bliss_graph
std::vector<std::wstring> vertex_labels
std::vector<std::optional<std::wstring>> vertex_xlabels
std::vector<std::optional<std::wstring>> vertex_texlabels
std::vector<VertexColor> vertex_colors
std::vector<VertexType> vertex_types
container::map<Index, std::size_t> idx_to_vertex
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

NamedIndexSet 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<NamedIndexSet::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

class Vertex

Public Functions

Vertex(Origin origin, std::size_t terminal_idx, std::size_t index_slot, Symmetry terminal_symm)
Origin getOrigin() const
std::size_t getTerminalIndex() const
std::size_t getIndexSlot() const
Symmetry getTerminalSymmetry() const
bool operator<(const Vertex &rhs) const
bool operator==(const Vertex &rhs) const