Tensor Network Visualization

Updated 4 July 2026

Tensor-Network-Visualization is a framework that integrates a software package with diagrammatic methods to represent tensor networks as graphs based on connectivity, indices, and contraction order.
It maps tensor contractions, decompositions, and rank annotations into clear visual diagrams using layouts like force-directed and hierarchical arrangements.
The package converts diverse tensor objects into a unified intermediate representation, enabling effective debugging and structural inspection of complex tensor computations.

Tensor-Network-Visualization denotes both a concrete software package and a broader diagrammatic practice for representing tensor networks as graphs whose meaning depends on connectivity, indices, contraction order, and related design choices. In the package introduced alongside Tensor-Network-Editor and Quantum Circuit Drawer, tensor-network or traced einsum objects are converted into a common intermediate representation, laid out in two or three dimensions, and rendered for visual debugging and structural inspection; more broadly, the literature treats tensor-network diagrams as a graphical language for contractions, decompositions, rank annotations, and entanglement structure (Ali, 7 Jun 2026, Biamonte et al., 2017, Zhou et al., 14 Jul 2025).

1. Graph-based representation and basic semantics

A tensor network can be represented by a graph

$G=(V,E),$

where $V=\{v_1,\dots,v_N\}$ is the set of tensor-nodes and $E=\{e_1,\dots,e_M\}$ is the set of edges connecting tensor-nodes. In the 2026 package, each node $v_i$ carries an order- $k$ tensor

$T^{(i)}\in\mathbb{R}^{d_{i1}\times d_{i2}\times\cdots\times d_{ik}},$

and a contraction edge corresponds to summation over a shared index. A simple two-tensor contraction is written as

$(T^{(i)}\star T^{(j)})_{\dots} = \sum_{\alpha=1}^{d_e} T^{(i)}_{\dots \alpha \dots}\;T^{(j)}_{\dots \alpha \dots}.$

For a full network, the contracted indices are summed over all edges in $E$ (Ali, 7 Jun 2026).

This graph-based view matches the standard graphical notation used across the tensor-network literature. A tensor is drawn as a shape with one leg per mode; an open leg represents a free index, a connected leg represents contraction, and a loop indicates self-contraction such as a trace. Biamonte and Bergholm describe contraction as the diagrammatic counterpart of Einstein summation, with disconnected shapes denoting tensor products and special wire-only tensors such as the identity, cup, and cap used to encode basic categorical operations (Biamonte et al., 2017). A parallel presentation in the lecture note on graphical notations emphasizes that most matrix and tensor products, including inner product, outer product, Hadamard product, Kronecker product, and Khatri-Rao product, can be written in this notation, and that mode- $n$ unfolding is represented by attaching a small “unfold” semicircle that merges all modes except $n$ into one leg (Yokota, 2024).

The same semantics underlie tensor-rank visualization. Closed edges correspond to contracted modes, and the dimension of a closed edge is the tensor-network rank. Open edges correspond to the external modes of the overall tensor. If a rank equals $V=\{v_1,\dots,v_N\}$ 0, the edge may be omitted. This convention is central in graphical explanations of CP, Tucker, Tensor-Train, and tree-structured decompositions (Zhou et al., 14 Jul 2025).

2. Visual grammars for decompositions, ranks, and publication-quality diagrams

The graphical grammar used in tensor-network visualization is not merely decorative; it encodes decomposition structure, unfolding bounds, and rank constraints. In the lecture note on tensor-network ranks, a tensor-core node is drawn as a filled circle, a factor node as a square or rectangle, and a leaf vector as a short line or small square on an open edge. For a third-order CP decomposition of $V=\{v_1,\dots,v_N\}$ 1, three factor matrices $V=\{v_1,\dots,v_N\}$ 2, $V=\{v_1,\dots,v_N\}$ 3, and $V=\{v_1,\dots,v_N\}$ 4 are connected to a super-diagonal core $V=\{v_1,\dots,v_N\}$ 5, and the three closed edges are all labeled $V=\{v_1,\dots,v_N\}$ 6. The algebraic definition is

$V=\{v_1,\dots,v_N\}$ 7

For Tucker decomposition,

$V=\{v_1,\dots,v_N\}$ 8

with $V=\{v_1,\dots,v_N\}$ 9 (Zhou et al., 14 Jul 2025).

For more complex topologies such as Tensor-Train, visualization proceeds by choosing a topology, placing one node per core factor, drawing closed edges between adjacent cores, and labeling those edges by ranks $E=\{e_1,\dots,e_M\}$ 0. A dashed cut across the network provides an upper bound on the rank of a tensor unfolding: if the cut crosses edges with ranks $E=\{e_1,\dots,e_M\}$ 1, then the product $E=\{e_1,\dots,e_M\}$ 2 upper-bounds the corresponding matricized rank. In a TT of order $E=\{e_1,\dots,e_M\}$ 3, cutting between cores $E=\{e_1,\dots,e_M\}$ 4 and $E=\{e_1,\dots,e_M\}$ 5 yields $E=\{e_1,\dots,e_M\}$ 6 (Zhou et al., 14 Jul 2025).

Several sources formulate explicit stylistic conventions for readable diagrams. The “Tensor Cookbook” prescribes clockwise leg ordering around a node, gray dimension labels above legs, blue index labels in element-wise drawings, curved edges to avoid overlaps, and consistent color-coding of tensor types (Rakhshan et al., 15 May 2026). Related best practices include using circles for cores and squares for factor matrices, labeling every rank-bearing edge, including legends or captions that define node shapes and edge styles, and aligning nodes on a grid while avoiding crossings (Zhou et al., 14 Jul 2025). Such conventions matter because, in tensor-network diagrams, only connectivity is structurally essential; nodes may be moved freely in the plane as long as connectivity and leg ordering remain unambiguous (Rakhshan et al., 15 May 2026).

3. Package architecture, layouts, and rendering pipeline

Tensor-Network-Visualization, imported as tensor_network_viz, is organized into three main layers: input dispatch and graph building, layout, and rendering. The input layer includes detect_engine.py, which routes Python objects such as NumPy arrays, PyTorch tensors, TensorNetwork, Quimb, TeNPy-style objects, or traced einsum traces into a common intermediate form. Backend-specific adapter classes in builders/, such as QuimbGraphBuilder and EinsumTraceBuilder, extract node identities and shapes, edge connectivity, and optional contraction history. The result is a NormalizedTensorGraph containing nodes, edges, and optional contraction hints such as ordering or cost metadata (Ali, 7 Jun 2026).

The layout layer exposes force_directed_layout, hierarchical_layout, and custom contraction-oriented layouts such as linear chains for MPS and circular layouts for MERA. The force-directed layout is based on NetworkX spring_layout and minimizes an energy of the form

$E=\{e_1,\dots,e_M\}$ 7

where $E=\{e_1,\dots,e_M\}$ 8 is the position of node $E=\{e_1,\dots,e_M\}$ 9, $v_i$ 0 is a rest length, and $v_i$ 1 control attraction and repulsion. The hierarchical layout uses Graphviz “dot” rank assignments to place nodes in layers and minimizes edge crossings via heuristic ordering. Tree-structured networks can also use radial or tubular 3D layouts (Ali, 7 Jun 2026).

Rendering is handled by renderer.py, which converts the positioned graph into a Matplotlib figure. Nodes are drawn as circles or polygons, edges as Bézier or straight lines, and text labels denote tensor names and index labels. Hover callbacks in Jupyter are supported via mpld3 or ipywidgets for showing values or dimension information. The central interface is show_tensor_network(graph, config=PlotConfig(), show=True), where PlotConfig includes toggles such as show_tensor_labels, edge_labels, hover_labels, 3D versus 2D, and color maps for tensor-element inspection (Ali, 7 Jun 2026).

The package is explicitly described as a visual authoring and inspection layer around existing tensor-network libraries, array-based scientific Python workflows, and quantum SDKs. It is not a simulator: it does not implement new contraction algorithms, execute quantum circuits, or guarantee full semantic equivalence across arbitrary backends (Ali, 7 Jun 2026).

4. Workflow integration and inspection use cases

A typical workflow couples traced tensor computation with immediate graphical inspection. In the documented einsum-tracing example, an EinsumTrace object is created, concrete arrays are bound by name, and a traced expression such as "ab,b->a" is executed through einsum(...). The visualization step then calls show_tensor_network(trace, config=PlotConfig(...)), and the resulting Matplotlib figure may be saved with fig.savefig("einsum-network.png", bbox_inches="tight"). Internally, einsum(...) records each tensor-node and each contraction edge, and show_tensor_network dispatches to the EinsumTraceBuilder, constructs the NormalizedTensorGraph, selects a layout, and renders the figure (Ali, 7 Jun 2026).

The package documentation includes a toy vector-matrix contraction and a three-tensor MPS-style chain. In the toy example, einsum("ij,j->i", A, v, ...) yields a two-node graph with one edge labeled j, showing the contracted index. In the MPS example, three random tensors $v_i$ 2, $v_i$ 3, and $v_i$ 4 are contracted in one expression, and the resulting figure arranges $v_i$ 5 horizontally, each with open legs and one contracted leg between neighbors. This is consistent with the standard MPS diagrammatic form

$v_i$ 6

in which successive SVDs produce an open-boundary chain with explicit bond indices $v_i$ 7 (Ali, 7 Jun 2026, Biamonte et al., 2017).

Supported inputs, via documented adapters, include einsum traces on NumPy or PyTorch, native TensorNetwork objects, Quimb tensor-network objects, TeNPy-style explicit tensor lists, and a limited subset of TensorKrowch. Known limitations include preservation only of graph topology, index sizes, labels, and available contraction metadata, while custom tensor metadata may not be extracted unless an adapter explicitly supports it. Translation through translate_tensor_network is described as best-effort, not a universal converter (Ali, 7 Jun 2026).

Tensor-network visualization has also developed through graphical authoring systems that translate diagrams into executable code. The relationship among three such systems is summarized below.

System	Visual model	Stated code-generation role
Tensor-Network-Visualization	Graph-based inspection of supported tensor-network and traced einsum workflows	Part of a visual authoring and inspection layer; not a simulator (Ali, 7 Jun 2026)
GuiTeNet	Nodes with ordered legs and zero-based red leg labels	Instantly generates Python/NumPy source code for the sequence of user actions (Sahlmann et al., 2018)
TensorTrace	Anchor-based tensor diagram canvas with blue and green plaques	Automatically generates code for optimal contraction in MATLAB, Python, or Julia (Evenbly, 2019)

GuiTeNet represents every tensor $v_i$ 8 of order $v_i$ 9 as a filled circle with exactly $k$ 0 legs, each carrying a small red zero-based label that fixes dimension ordering. User actions are decomposed into four atomic primitives—tensor contraction, transposition, QR splitting, and SVD splitting—and mapped directly to NumPy calls such as np.einsum, np.transpose, np.linalg.qr, and SVD routines. The software runs directly in web browsers, uses JavaScript and D3.js to manage an SVG scene graph, and may optionally invoke a simple force-directed layout with repulsive charges and spring attraction on edges (Sahlmann et al., 2018).

TensorTrace, by contrast, is centered on a free-form drawing canvas with configurable tensor shapes, anchor plaques, index types, and Bézier control points. Internal anchors use blue numbered plaques to fix local index ordering; free output anchors use green plaques to define final index positions. When code export is invoked, the network is validated, index dimensions are passed to a contraction-order finder based on a modified brute-force search using NCON2 and pruning heuristics from NCON3, and the system emits a function in MATLAB, Python, or Julia. The rendering engine is written in C++/Qt and is GPU-accelerated; placement remains under user control, with only lightweight on-drag collision detection and edge-routing hints rather than full global energy minimization (Evenbly, 2019).

A plausible implication is that Tensor-Network-Visualization occupies a different point in this ecosystem: it emphasizes backend-agnostic structural inspection of already existing workflows, whereas GuiTeNet and TensorTrace center the graphical construction of networks and direct code emission.

6. Interpretive applications, limitations, and open directions

Tensor-network visualization is also used as a scientific instrument for interpreting structure. In the structural optimization of tree tensor networks, the objective is to choose a TTN whose auxiliary bonds carry as little entanglement as possible. The cost function is written as

$k$ 1

where $k$ 2 is the entanglement entropy associated with the bipartition induced by cutting auxiliary bond $k$ 3. Repeated local reconnection steps evaluate the three inequivalent local TTN topologies on four legs, choose the one minimizing the local cost, and thereby update both tensor entries and graph structure (Hikihara et al., 2024).

In the Rainbow-chain application, the optimized TTN arranges its leaves so that each singlet pair sits under a single parent tensor. For $k$ 4, visualization of the final TTN uses thick red edges for physical bonds with $k$ 5, thin gray internal bonds with $k$ 6, and a tree structure in which every singlet pair shares a single tensor immediately above it. The result is a direct graphical map from entanglement data $k$ 7 to spatial arrangement (Hikihara et al., 2024).

This interpretive use clarifies a common misconception. Visibility of structure does not mean execution of structure. Tensor-Network-Visualization is expressly not a numerical backend, and it does not implement new contraction algorithms or guarantee full semantic equivalence across arbitrary backends. Likewise, the TTN structural-optimization method explores only loop-free networks; “one cannot see toroidal or plaquette-like entanglement without extending to higher-dimensional PEPS or MERA” (Ali, 7 Jun 2026, Hikihara et al., 2024).

Open directions are stated explicitly. For Tensor-Network-Visualization these include richer interactive debugging, such as step-through contraction playback with cost metrics; automatic detection of canonical forms such as MPS gauge fixing and on-the-fly re-layout; improved support for hyperedges; integration with quantum-circuit-drawer for combined tensor-circuit workflows; and scalability enhancements for very large networks with thousands of nodes (Ali, 7 Jun 2026). These directions suggest continued convergence between formal graphical notation, software-assisted inspection, and domain-specific visual analysis.