tensor-network-visualization 1.6.0

Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks.

Tensor-Network-Visualization

Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks.

Why This Exists

Tensor-network libraries expose different Python objects. This package gives them a small shared visualization API so you can inspect structure, tensor values, contraction playback, and normalized graph exports without rewriting plotting code for every backend.

The common entry points are:

show_tensor_network(...)
show_tensor_elements(...)
show_tensor_comparison(...)
normalize_tensor_network(...)
export_tensor_network_snapshot(...)

Install

• PyPI package name: tensor-network-visualization
• Import package: tensor_network_viz
• Requires Python 3.11 or newer.

python -m pip install tensor-network-visualization

The base install only depends on numpy, matplotlib, and networkx.

For interactive Jupyter figures:

python -m pip install "tensor-network-visualization[jupyter]"

For backend-specific packages, install the matching extra, for example:

python -m pip install "tensor-network-visualization[quimb]"

See docs/installation.md for virtual environments, all optional extras, and local development installs.

Basic Usage

NumPy einsum trace (base install)

This example uses only base dependencies and a NumPy-backed EinsumTrace.

import numpy as np
from tensor_network_viz import EinsumTrace, PlotConfig, einsum, show_tensor_network

trace = EinsumTrace()
a = np.ones((2, 3), dtype=float)
x = np.array([1.0, -0.5, 0.25], dtype=float)

trace.bind("A", a)
trace.bind("x", x)
einsum("ab,b->a", a, x, trace=trace, backend="numpy")

fig, ax = show_tensor_network(
    trace,
    config=PlotConfig(show_tensor_labels=True, hover_labels=True),
    show=False,
)
fig.savefig("einsum-network.png", bbox_inches="tight")

TensorKrowch

Install the TensorKrowch extra (see Installation for details):

python -m pip install "tensor-network-visualization[tensorkrowch]"

import tensorkrowch as tk
from tensor_network_viz import PlotConfig, show_tensor_network

network = tk.TensorNetwork(name="demo")
left = tk.Node(shape=(2, 2), axes_names=("a", "b"), name="L", network=network)
right = tk.Node(shape=(2, 2), axes_names=("b", "c"), name="R", network=network)
left["b"] ^ right["b"]

fig, ax = show_tensor_network(
    network,
    config=PlotConfig(show_tensor_labels=True, show_index_labels=False),
    show=False,
)
fig.savefig("tensorkrowch-network.png", bbox_inches="tight")

Use show=False when you want to save or customize the figure yourself. Use show_controls=False when you want a clean static figure with no embedded Matplotlib controls.

In Jupyter, install "tensor-network-visualization[jupyter]", run %matplotlib widget before plotting, then call show_tensor_network as usual (default show_controls=True) for interactive figures with embedded controls. See Installation and User Guide for details.

Documentation

• Installation: virtual environments, optional extras, Jupyter, and local editable installs.
• API Reference: public functions, configuration objects, snapshots, exceptions, and logging.
• User Guide: workflows, notebooks, exports, layouts, tensor inspection, comparisons, snapshots, and performance tips.
• Backend Examples: copy-paste examples for TensorKrowch, TensorNetwork, Quimb, TeNPy, and einsum.
• Troubleshooting: common install, Jupyter, Matplotlib, backend, and data issues.
• Repository Examples: command-line demo launcher and example catalog.

Project Links

• Changelog
• Contributing
• Code of Conduct
• Issues
• Repository