pytreenet.ttno package

This submodule implements the tree tensor network operators (TTNO).

Apart from the class itself, it contains everything required to build them automatically from a symbolic Hamiltonian.

Submodules

pytreenet.ttno.collections module

This module provides collections/sets of hyperedges and vertices.

class pytreenet.ttno.collections.HyperEdgeColl(corr_node_id: str, contained_hyperedges: None | List[HyperEdge] = None)

Bases: object

Holds multiple hyperedges that correspond to the same node.

corr_node_id

The identifier of the node corresponding to this collection.

Type:

str

contained_hyperedges

A list of all hyperedges contained in this collection.

Type:

List[Hyperedge]

get_all_labels() → List[str]

Obtain all lables of all hyperedges in this collection.

Returns:

A list of all labels.

Return type:

List[str]

get_completely_contained_hyperedges() → List[HyperEdge]

Returns all hyperedges connected only to vertices marked as contained.

get_hyperedges_by_label(label: str) → List[HyperEdge]

Returns all hyperedges in this collection with a given label.

Parameters:

label (str) – The label to be looked for.

Returns:

A list of all hyperedges with the label given.

Return type:

List[HyperEdge]

class pytreenet.ttno.collections.VertexColl(corr_edge: Tuple[str, str], contained_vertices: None | List[Vertex])

Bases: object

Holds multiple vertices that correspond to the same edge.

corr_edge

The identifiers of the two nodes that are connected by the edge corresponding to this collectino of vertices.

Type:

Tuple[str,str]

contained_vertices

A list of all vertices in this collection.

Type:

List[Vertex]

contains_contained() → bool

Returns, if any of the vertices in this collection are marked as contained.

get_all_marked_vertices() → List[Vertex]

Returns all vertices in this collection marked as contained or new.

index_vertices()

Indexes all vertices contained in this collection.

This index is the index value to which this vertex corresponds in the bond dimension.

pytreenet.ttno.hyperedge module

This module provides a hyperedge to be used in state diagrams.

class pytreenet.ttno.hyperedge.HyperEdge(corr_node_id: str, label: str, vertices: List[Vertex])

Bases: object

A hyperedge, i.e. an edge connecting any number of vertices.

corr_node_id

The node to which this hyperedge corresponds.

Type:

str

label

The label associated to this hyperedge.

Type:

str

vertices

A list of vertices connected to this hyperedge.

Type:

List[Vertex]

hash

A hash value corresponding to this hyperedge’s label.

Type:

str

identifier

A unique identifier of this hyperedge.

Type:

str

add_vertex(vertex: Vertex)

Adds a vertex to this hyperedge.

In turn this hyperedge is also added to the vertex.

add_vertices(vertices: list)

Add multiple vertices to this hyperedge.

In turn this hyperedge is added to all vertices.

all_but_one_vertex_contained() → bool

Returns if all but one vertex of this hyperedge are marked as contained.

all_vertices_contained() → bool

Returns if all vertices of this hyperedge are marked as contained.

calculate_hash(children_hash: str | None = None) → str

Calculate the hash of the hyperedge.

Parameters:

children_hash (Union[str,None], optional) – The hash of vertices connected to the hyperedge. Defaults to None.

find_tensor_position(reference_tree: TreeStructure) → Tuple

Finds the position of the operator in the total TTNO tensor.

The position is of the operator represented by this hyperedge.

Parameters:

reference_tree (TreeStructure) – A tree to provide the topology.

Returns:

The position of the operator. The last two entries are

slices “:” corresponding to the physical dimensions.

Return type:

Tuple

find_vertex(other_node_id: str) → Vertex

Finds the vertex connected to this hyperedge corresponding to the edge (corr_node_id, other_node_id).

Parameters:

other_node_id (str) – The vertex corresponds to an edge in the underlying tree structure. One node the edge is connected to is the node this hyperedge corresponds to, while the other node identifier is provided by this string.

Raises:

ValueError – The hyperedge is not connected to a fitting vertex.

Returns:

The vertex corresponding to the edge connecting this

hyperedge and a hyperedge corresponding to the other specified node.

Return type:

Vertex

get_contained_vertices() → List[Vertex]

Returns all vertices marked as contained connected to this hyperedge.

get_hash() → str

Return the hash of the hyperedge

get_single_uncontained_vertex() → Vertex

Returns a single uncontained vertex.

Raises:

AssertionError – If there are more or less than one uncontained vertex.

get_uncontained_vertices() → List[Vertex]

Returns all vertices not marked as contained connected to this hyperedge.

num_of_vertices_contained() → int

The number of vertices connected to this hyperedge marked as contained.

Returns:

The number of connected contained vertices.

Return type:

int

set_hash(hash_val: str)

Set the hash of the hyperedge

vertex_single_he(other_node_id: str) → bool

Checks if a specified vertex is connected to only a single hyperedge.

The vertex checked, is the vertex connected to this hyperedge and a hypergraph corresponding to the other specified node. This method checks, if the current hypergraph is the only hypergraph connected to that vertex corresponding to this node

Parameters:

other_node_id (str) – The vertex corresponds to an edge in the underlying tree structure. One node the edge is connected to is the node this hyperedge corresponds to, while the other node identifier is provided by this string.

Returns:

Whether the specified vertex is connected to only a single

hyperedge.

Return type:

bool

pytreenet.ttno.single_term_diagram module

A state diagram representing a single term Hamiltonian

class pytreenet.ttno.single_term_diagram.SingleTermDiagram(reference_tree: TreeStructure)

Bases: object

A state diagram representing a single term.

This single term is a single term of an operator, usually a Hamiltonian, that can be represented as a sum of tensor products. As this class only represents a single term, all hyperedges and vertices are uniquely associated to an object in a reference tree.

hyperedges

All hyperedges, of which each is uniquely associated to a node.

Type:

Dict[str,HyperEdge]

vertices

All verties, of which each is uniquely associated to an edge.

Type:

Dict[str,Vertex]

reference_tree

A tree structure on which the state diagram is based, i.e. both have the same structure.

Type:

TreeStructure

classmethod from_single_term(term: Dict[str, str], reference_tree: TreeStructure)

Creates a state diagram corresponding to a single Hamiltonian term.

Parameters:

• term (Dict[str,str]) – The term the new state diagram should represent. The leys are identifiers of nodes to which the value, a symbolic operator, is to be applied.

• reference_tree (TreeStructure) – Provides the underlying tree structure and the identifiers of all nodes.

Returns:

The state diagram associated to this single

term.

Return type:

SingleTermDiagram

get_all_hyperedges() → List[HyperEdge]

Returns all hyperedges of this state diagram.

get_all_vertices() → List[Vertex]

Returns all vertices of this state diagram.

get_hyperedge_label(node_id: str) → str

Returns the label of a hyperedge.

Parameters:

node_id (str) – Specifies which hyperedge to return the label from.

pytreenet.ttno.state_diagram module

class pytreenet.ttno.state_diagram.StateDiagram(reference_tree: TreeStructure)

Bases: object

A state diagram represents a Hamiltonian (or other operator)

In principle it can represent any tree tensor network. It contains vertices and hyperedges, that can be sorted into an underlying tree structure.

vertex_colls

A collection of all vertices in the state diagram. They are grouped by the edge that corresponds to them.

Type:

VertexColl

hyperedge_colls

A collection of all hyperedges in the state diagram. They are grouped by the node that corresponds to them.

Type:

HyperEdgeColl

reference_tree

Provides the underlying tree structure with connectivity and identifiers.

Type:

TreeStructure

add_hyperedge(hyperedge: HyperEdge)

Adds a hyperedge to the correct collection and to the state diagram.

Parameters:

hyperedge (HyperEdge) – The hyperedge to be added.

add_single_term(term: Dict[str, str])

Modifies the state diagram to add a term.

Adds a term to the state diagram. This means the diagram is modified in a way such that it represents Hamiltonian + term instead of only the Hamiltonian.

Parameters:

term (Dict[str,str]) – A dictionary containing the node_ids as keys and the operator applied to that node as a value.

calculate_hashes(node, ref_tree)

Calculates and returns the hash of all of the hyperedges in the state diagram recursively. Hash is formed by the label of the hyperedge and concatenation of the hashes of its children.

combine_u(local_hyperedges, parent)

Checks if the hyperedges in the local_hyperedges list can be combined and when it is possible, combines them.

Combining two hyperedge is basically removing one of the subtree of the hyperedge and connecting deleted subtree’s vertex to the remaining hyperedge.

combine_v(local_vs, current_node, parent)

Checks if the hyperedges in the local_vs list can be combined as v nodes and when it is possible, combines them. Combining v nodes also means combining vertices in the cut site.

There are 4 cases to consider when combining v nodes with respect to the their vertices in the cut site:

1. Both vertices have more than one hyperedge to the parent node. (d1 and d2)

2. Both vertices have only one hyperedge to the parent node. (not d1 and not d2)

3. One vertex has more than one hyperedge to the parent node, the other has only one. (not d1 and d2)

4. One vertex has only one hyperedge to the parent node, the other has more than one. (d1 and not d2)

Case 1: In this case, we only check if there are a fully matching set of hyperedges between the vertices. If we can form a fully connected vertex, we combine the vertices and remove the hyperedges and call the function again. If not, keep both hyperedges as they are.

Case 2: In this case, we basically remove the second hyperedge and its connections and combine the vertices (as connecting second one to the first one).

Case 3: In this case, we handle the vertex with more than one hyperedge to the parent node specially. We create a new vertex and duplicate hyperedges and seperate connections to the new vertex. Then, we combine the vertices.

Case 4: Same as case 3, so we just switch element1 and element2.

After iterating each pair of hyperedges, we check if there are any combined hyperedges. If there are, we call the function recursively to check the hyperedges again.

erase_subtree(start_edge, erased=None)

Erases the subtree of a hyperedge from the state diagram recursively.

classmethod from_hamiltonian(hamiltonian: Hamiltonian, ref_tree: TreeStructure, method: TTNOFinder = TTNOFinder.TREE) → StateDiagram

Creates a state diagram equivalent to a given Hamiltonian.

Parameters:

• hamiltonian (Hamiltonian) – Hamiltonian for which the state diagram is to be found

• ref_tree (TreeTensorNetwork) – Supplies the tree topology which is to be incorporated into the state diagram.

• method (TTNOFinder) – The construction method to be used.

Returns:

The final state diagram

Return type:

StateDiagram

classmethod from_hamiltonian_combine_match(hamiltonian: Hamiltonian, ref_tree: TreeStructure) → StateDiagram

Creates optimal state diagram equivalent to a given Hamiltonian.

Parameters:

• hamiltonian (Hamiltonian) – Hamiltonian for which the state diagram is to be found

• ref_tree (TreeTensorNetwork) – Supplies the tree topology which is to be incorporated into the state diagram.

Returns:

The final state diagram

Return type:

StateDiagram

classmethod from_hamiltonian_tree_comparison(hamiltonian: Hamiltonian, ref_tree: TreeStructure)

Constructs a Hamiltonian using the leaf to root comparison method.

Parameters:

• hamiltonian (Hamiltonian) – Hamiltonian for which the state diagram is to be found

• ref_tree (TreeTensorNetwork) – Supplies the tree topology which is to be incorporated into the state diagram.

Returns:

The final state diagram.

Return type:

StateDiagram

classmethod from_single_state_diagram(single_term_diag: SingleTermDiagram) → StateDiagram

Transforms a single state diagram to a general one.

Parameters:

single_term_diag (SingleTermDiagram) – Represents a single term using a simpler structure than the general state diagrams.

Returns:

The equivalent general state diagram.

Return type:

state_diagram (StateDiagram)

classmethod from_single_term(term: Dict[str, str], reference_tree: TreeStructure)

Basically a wrap of SingleTermDiagram.from_single_term.

get_all_hyperedges() → List[HyperEdge]

Returns all hyperedges from all collections in a list

get_all_vertices() → List[Vertex]

Returns all vertices from all collections in a list.

classmethod get_state_diagram_compound(state_diagrams)

Forms a compound state diagram from a list of state diagrams.

classmethod get_state_diagrams(hamiltonian, ref_tree)

Creates single term diagrams for each term in the Hamiltonian. Calculates hash values for each state diagram.

get_vertex_coll_two_ids(id1: str, id2: str) → VertexColl

Obtain the vertex collection corresponding to a specified edge.

The edge is specified by the two node identifiers given and is the edge connecting the two. Since the order of the identifiers in the edge is irrelevant, the same is true for the supplied identifiers.

Parameters:

• id1 (str) – One identifier corresponding a node connected by the edge.

• id2 (str) – One identifier corresponding a node connected by the edge.

Returns:

The vertex collection corresponding to the specified

edge.

Return type:

VertexColl

obtain_tensor_shape(node_id: str, conversion_dict: Dict[str, ndarray]) → Tuple[int, ...]

Find the shape of the tensor corresponding to a node in the equivalent TTNO.

Parameters:

• node_id (str) – The identifier of a node.

• conversion_dict (Dict[str, np.ndarray]) – A dictionary to convert the labels into arrays, to determine the required physical dimension.

Returns:

The shape of the tensor in the equivalent TTNO in

the format (parent_shape, children_shape, phys_dim, phys_dim). The children are in the same order as in the node.

Return type:

Tuple[int, …]

reset_markers()

Resets the contained and new markers of every vertex in the diagram.

set_all_vertex_indices()

Indexes all vertices contained in this state diagram.

This index is the index value to which this vertex corresponds in the bond dimension.

classmethod sum_states(s1, s2, ref_tree)

Combines two state diagrams into a single one and returns it.

class pytreenet.ttno.state_diagram.TTNOFinder(value)

Bases: Enum

An Enum to switch between different construction modes of a state diagram.

CM = 'Combine and Match'

TREE = 'Tree'

pytreenet.ttno.ttno_class module

Provides the class to represent a Tree Tensor Network Operator (TTNO).

class pytreenet.ttno.ttno_class.Decomposition(value)

Bases: Enum

An enumeration to choosing decomposition method used for TTNO construction.

SVD

Singular Value Decomposition

QR

QR-Decomposition

tSVD

Truncated Singular Value Decomposition

QR = 'QR'

SVD = 'SVD'

tSVD = 'tSVD'

pytreenet.ttno.ttno_class.TTNO

alias of TreeTensorNetworkOperator

class pytreenet.ttno.ttno_class.TreeTensorNetworkOperator

Bases: TreeTensorNetwork

Represents a tree tensor network operator (TTNO).

A TTNO is a tree tensor network equivalent to an operator. This means every node has two open legs (input and output). The legs can be trivial, i.e., of dimension 1, but have the same dimension.

classmethod from_hamiltonian(hamiltonian: Hamiltonian, reference_tree: TreeStructure, method: TTNOFinder = TTNOFinder.CM) → TreeTensorNetworkOperator

Generates a TTNO from a Hamiltonian.

Parameters:

• hamiltonian (Hamiltonian) – The Hamiltonian, to which the TTNO should be equivalent.

• reference_tree (TreeStructure) – The tree structure which the TTNO should respect.

Returns:

The resulting TTNO.

Return type:

TreeTensorNetworkOperator

classmethod from_state_diagram(state_diagram: StateDiagram, conversion_dict: Dict[str, ndarray]) → TreeTensorNetworkOperator

Generates a TTNO from a state diagram.

Parameters:

• state_diagram (StateDiagram) – The state diagram, which the TTNO should represent.

• conversion_dict (Dict[str, np.ndarray]) – A conversion dictionary to determine the physical dimensions required.

classmethod from_tensor(reference_tree: TreeStructure, tensor: np.nadarray, leg_dict: dict[str, int], mode: Decomposition = Decomposition.QR)

Generate a TTNO from a big tensor.

The TTNO is generated by recursively splitting the tensor into the desired tree shape using tensor decompositions.

Args: reference_tree (TreeStructure): A tree used as a reference. The TTNO

will have the same underlying tree structure and the same node_ids.

tensor (np.ndarray): A big numpy array that represents an operator on a

lattice of quantum systems. Therefore it has to have an even number of legs. Assumed to be a reshape of operator, such that input and output legs are clustered as [out_1, out_2, ..., out_n, in_1, in_2, ..., in_n] and dim(out_i) == dim(in_i) for all legs.

leg_dict (dict): A dictionary containing node_identifiers as keys and

leg indices as values. It is used to match the legs of tensor to the different nodes. Only the lower (smaller) half of the legs is to be put in this dict, the others are inferred by ordering.

mode (Decomposition): Determines the decomposition to use for splitting

the tensor.

Returns:

The resulting TTNO.

Return type:

TreeTensorNetworkOperator

pytreenet.ttno.vertex module

Provides the vertex class to be used with state diagrams.

class pytreenet.ttno.vertex.Vertex(corr_edge: Tuple[str, str], hyperedges: List[HyperEdge])

Bases: object

A vertex in a state diagram.

A vertex is a point in the state diagram, which corresponds to an edge in the underlying tree structure. It is connected to hyperedges, which are correspond to the nodes of the tree structure.

corr_edge

The two node identifiers of the edge corresponding to this vertex.

Type:

Tuple[str, str]

hyperedges

The hyperedges connected to this vertex.

Type:

List[HyperEdge]

identifier

A unique identifier for this vertex.

Type:

str

contained

Whether this vertex is contained in the state diagram.

Type:

bool

new

Whether this vertex is new in the state diagram.

Type:

bool

index

The index of the vertex in the TTNO bond.

Type:

int

add_hyperedge(hyperedge: HyperEdge)

Adds a hyperedge to this vertex and this vertex to the hyperedge’s vertices.

add_hyperedges(hyperedges: List[HyperEdge])

Adds hyperedges to this vertex and adds this vertex to the hyperedges’

vertices.

check_hyperedge_uniqueness(node_id: str) → bool

Check if the hyperedge connected to this vertex and corresponding to the given node is unique.

Parameters:

node_id (str) – The identifier of the node for which we are to check the uniqueness of the hyperedge connected to this vertex.

Returns:

True if the hyperedge is unique, False otherwise.

Return type:

bool

check_validity_of_node(node_id: str)

Cecks if the current vertex corresponds to an edge of the given node.

get_hyperedges_for_one_node_id(node_id: str) → List[HyperEdge]

Find all hyperdeges of this vertex which correspond a given node.

Parameters:

node_id (str) – The identifier of the node for which we are to find the hyperedges connected to this vertex.

Returns:

A list containing all hyperedges connected to this vertex

and corresponding to the node with identifier node_id.

Return type:

List[HyperEdge]

get_second_node_id(node_id)

Given a node_id returns the other node_id of the corresponding edge.

Parameters:

node_id (string) – One of the two node identifiers of the edge to which this vertex corresponds.

Returns:

The other node identifier.

Return type:

string

num_hyperedges_to_node(node_id: str) → int

Finds the number of hyperedges corresponding to a given node and are connected to this vertex.

Parameters:

node_id (str) – The identifier of the node for which we are to find the number of hyperedges connected to this vertex.

Returns:

The number of hyperedges of this vertex corresponding to the

specified node.

Return type:

int

runtime_reset()

Allows for reset immediately during running while building state diagramms.

This works, since we check every marked vertex exactly twice.