Tensor Network

Graph-based tensor network container with label-based contraction.

TensorNetwork represents a collection of tensors connected by their shared leg labels. The graph structure (networkx.MultiGraph) tracks which legs are connected, and the contraction engine (contractor.py) handles the actual computation.

Key design choices: - Edges are identified by (node_a, label_a, node_b, label_b) — no positional indexing - connect_by_shared_label() auto-connects nodes that share a label name - Contraction cache keyed by tuple[NodeId] for O(1) lookup (order-sensitive) - Cache invalidated on any graph structure change (add/remove/replace/connect)

class tenax.network.network.TensorNetwork(name='')

Bases: object

Graph-based container for a tensor network.

The internal representation is an nx.MultiGraph where: - Nodes store the Tensor and its node_id. - Edges store which leg labels are connected: (label_a, label_b). - “Open” edges (no counterpart) represent physical/free indices.

The contraction cache maps (tuple[NodeId], output_labels, optimize) -> Tensor, and is invalidated whenever the graph structure changes.

Parameters:

name (Text) – Optional human-readable name for this network.

Example

>>> tn = TensorNetwork()
>>> tn.add_node("A", tensor_A)
>>> tn.add_node("B", tensor_B)
>>> tn.connect_by_shared_label("A", "B")
>>> result = tn.contract()

add_node(node_id, tensor)

Add a tensor as a node in the network.

Parameters:

• node_id (Hashable) – Unique identifier for this node.

• tensor (Tensor) – The tensor to store at this node.

Raises:

• ValueError – If node_id already exists.

• ValueError – If tensor has duplicate labels.

Return type:

None

remove_node(node_id)

Remove a node and all edges connected to it.

Parameters:

node_id (Hashable) – The node to remove.

Return type:

Tensor

Returns:

The tensor that was stored at this node.

Raises:

KeyError – If node_id not found.

replace_tensor(node_id, tensor)

Replace the tensor at an existing node.

The new tensor must have the same set of labels as the old one, since labels define the connectivity in the graph.

Parameters:

• node_id (Hashable) – The node to update.

• tensor (Tensor) – The replacement tensor.

Raises:

• KeyError – If node_id not found.

• ValueError – If labels differ from the original tensor.

Return type:

None

get_tensor(node_id)

Return the tensor stored at a node.

Parameters:

node_id (Hashable) – Identifier of the node to look up.

Return type:

Tensor

Returns:

The Tensor (DenseTensor or SymmetricTensor) at that node.

Raises:

KeyError – If node_id is not in the network.

connect(node_a, label_a, node_b, label_b)

Connect a specific leg of node_a to a specific leg of node_b.

After connection, these two legs are treated as contracted when contract() is called on a subgraph containing both nodes.

The leg labels on the two tensors do NOT need to match — the graph records which labels are paired. However, the TensorIndex objects must be compatible (same symmetry type, same bond dimension, opposite flows).

Parameters:

• node_a (Hashable) – First node.

• label_a (Text | int) – Label of the leg on node_a to connect.

• node_b (Hashable) – Second node.

• label_b (Text | int) – Label of the leg on node_b to connect.

Raises:

• KeyError – If either node not found.

• KeyError – If label not found on the corresponding tensor.

• ValueError – If the two TensorIndex objects are incompatible.

Return type:

None

connect_by_shared_label(node_a, node_b)

Auto-connect all legs sharing the same label between two nodes.

Finds labels that appear on both node_a and node_b and connects them. This is the most natural API for networks where shared label names already encode the connectivity.

Parameters:

• node_a (Hashable) – First node.

• node_b (Hashable) – Second node.

Return type:

int

Returns:

Number of connections made.

Raises:

• KeyError – If either node not found.

• ValueError – If no shared labels exist.

• ValueError – If shared labels have incompatible index objects.

disconnect(node_a, label_a, node_b, label_b)

Remove the edge connecting these two labeled legs.

Parameters:

• node_a (Hashable) – First node.

• label_a (Text | int) – Label of the leg on node_a.

• node_b (Hashable) – Second node.

• label_b (Text | int) – Label of the leg on node_b.

Raises:

KeyError – If no such edge exists.

Return type:

None

relabel_bond(node_id, old_label, new_label)

Rename a leg’s label on a node and update all connected edges.

Parameters:

• node_id (Hashable) – The node whose leg label to rename.

• old_label (Text | int) – The current label.

• new_label (Text | int) – The new label.

Raises:

KeyError – If node not found or old_label not in tensor.

Return type:

None

open_legs(node_id)

Return labels of legs on node_id not connected to any other node.

Parameters:

node_id (Hashable) – The node to query.

Return type:

list[Text | int]

Returns:

List of free (open) leg labels.

contract(nodes=None, output_labels=None, optimize='auto', cache=True)

Contract a subset of nodes (or all nodes if nodes is None).

Internally the method checks the cache, builds an einsum subscript string from the graph edge connectivity (contracting shared legs, keeping free legs), calls contract_with_subscripts() via opt_einsum, and caches the result.

The output tensor’s leg labels are the free labels in output_labels order (or natural order if not specified).

Parameters:

• nodes (list[Hashable] | None) – List of node IDs to contract. None = all nodes.

• output_labels (Sequence[Text | int] | None) – Explicit output leg ordering by label.

• optimize (Text) – opt_einsum optimizer.

• cache (bool) – Whether to use/populate the cache.

Return type:

Tensor

Returns:

Contracted Tensor with all open/free legs remaining.

clear_cache()

Manually clear the contraction cache.

Return type:

None

node_ids()

Return list of all node IDs.

Return type:

list[Hashable]

neighbors(node_id)

Return list of nodes connected to node_id.

Return type:

list[Hashable]

Parameters:

node_id (Hashable)

is_connected()

Return True if the network graph is connected.

Return type:

bool

n_nodes()

Number of nodes in the network.

Return type:

int

n_edges()

Number of edges (connected leg pairs) in the network.

Return type:

int

tenax.network.network.build_mps(tensors, open_boundary=True)

Build a Matrix Product State as a TensorNetwork.

Tensors are expected to have legs labeled with a convention that allows adjacent tensors to share virtual bond labels. If the tensors already have matching virtual bond labels (e.g., right label of site i matches left label of site i+1), they will be auto-connected.

If virtual bond labels don’t match, default virtual bonds are created: - Site i: left=”v{i-1}_{i}”, phys=”p{i}”, right=”v{i}_{i+1}”

Physical legs are not connected (they remain open).

Parameters:

• tensors (list[Tensor]) – List of site tensors [A_0, A_1, …, A_{L-1}].

• open_boundary (bool) – If True, boundary virtual legs remain open.

Return type:

TensorNetwork

Returns:

TensorNetwork with virtual bonds connected.

tenax.network.network.build_peps(tensors, Lx, Ly, open_boundary=True)

Build a PEPS (2D tensor network) as a TensorNetwork.

Tensors are organized in a 2D grid tensors[i][j] for row i, column j. Adjacent tensors are connected by shared virtual bond labels.

Convention for virtual bond labels (if not already matching): - Horizontal bond (j, j+1) in row i: “h{i}_{j}_{j+1}” - Vertical bond row (i, i+1) in column j: “v{i}_{i+1}_{j}” - Physical leg at (i,j): “p{i}_{j}”

Parameters:

• tensors (list[list[Tensor]]) – 2D list [Lx][Ly] of site tensors.

• Lx (int) – Number of rows.

• Ly (int) – Number of columns.

• open_boundary (bool) – If True, boundary virtual legs remain open.

Return type:

TensorNetwork

Returns:

TensorNetwork with virtual bonds connected.