tensor-network-visualization 1.4.1__tar.gz → 1.4.2__tar.gz

{tensor_network_visualization-1.4.1/src/tensor_network_visualization.egg-info → tensor_network_visualization-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensor-network-visualization
-Version: 1.4.1
+Version: 1.4.2
 Summary: Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks.
 Author: Alejandro Mata Ali
 License: MIT
@@ -19,11 +19,13 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: matplotlib>=3.7
 Requires-Dist: networkx>=3.0
+Requires-Dist: numpy
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pyright; extra == "dev"
 Requires-Dist: ipython; extra == "dev"
+Requires-Dist: tomli>=2.0.1; extra == "dev"
 Requires-Dist: tensorkrowch; extra == "dev"
 Requires-Dist: tensornetwork; extra == "dev"
 Requires-Dist: quimb; extra == "dev"
@@ -78,8 +80,11 @@ PyPI package name: `tensor-network-visualization`. Import module: `tensor_networ
 python -m pip install tensor-network-visualization
 ```
 
-Depends on `matplotlib` and `networkx` only. You can render **`einsum`** traces built from ordered
-`pair_tensor` entries without installing PyTorch.
+Base runtime dependencies are `numpy`, `matplotlib`, and `networkx` only. You can **build and
+render** rich **`einsum`** graphs from ordered **`pair_tensor`** / **`einsum_trace_step`** entries
+(ellipsis and repeated indices need shapes in metadata); **`tensor-network-visualization[einsum]`**
+(PyTorch) is only needed to **execute** `tensor_network_viz.einsum(..., trace=...)` and record
+those rows automatically.
 
 ### Optional backends (extras)
 
@@ -89,7 +94,7 @@ Depends on `matplotlib` and `networkx` only. You can render **`einsum`** traces
 | TensorNetwork  | `tensornetwork`               | `pip install "tensor-network-visualization[tensornetwork]"` |
 | Quimb          | `quimb`                       | `pip install "tensor-network-visualization[quimb]"` |
 | TeNPy          | `tenpy`                       | Resolves to PyPI package **`physics-tenpy`**. |
-| Einsum tracing | `einsum`                      | Adds **PyTorch** for the traced `einsum` helper. |
+| Einsum tracing | `einsum`                      | Adds **PyTorch** for auto-traced `einsum(..., trace=...)` (layout from `pair_tensor` / `einsum_trace_step` lists with metadata as needed). |
 | Jupyter widgets| `jupyter`                    | `ipympl`, widgets, JupyterLab / Notebook 7+ for interactive figures. |
 
 Combine extras, for example:
@@ -148,7 +153,8 @@ Everything below maps to real parameters—there are no hidden mode switches.
 | **Display mode** | `show=True` / `False` | If `True`: Jupyter **kernel** uses `IPython.display.display(fig)`; otherwise `plt.show()`. If `False`: neither runs—use for `savefig` / batch. |
 | **Label policy** | `PlotConfig` + overrides | Defaults: `show_tensor_labels`, `show_index_labels`. Per-call: `show_tensor_network(..., show_tensor_labels=..., show_index_labels=...)`. |
 | **Hover labels** | `PlotConfig(hover_labels=True)` | Tensor names and bond labels appear on pointer hover (2D axes hit-test; 3D screen-space distance). Needs an **interactive** Matplotlib window. |
-| **Einsum workflow** | `engine="einsum"` | **Auto:** `EinsumTrace` + `tensor_network_viz.einsum`. **Manual:** ordered list of `pair_tensor(...)`. |
+| **Contraction scheme** | `PlotConfig(show_contraction_scheme=True)` | **Einsum:** cumulative per-step highlights from the trace. **Other engines:** set **`contraction_scheme_by_name`**. **2D:** rounded boxes (AABB + pad); colored borders (no fill by default). **3D:** wireframe box. See **`docs/guide.md`**. |
+| **Einsum workflow** | `engine="einsum"` | **Auto:** `EinsumTrace` + `einsum` (binary `pair_tensor`, unary/ternary+ `einsum_trace_step`; implicit `->`, `out=`). **Manual:** `pair_tensor` / `einsum_trace_step` (ellipsis needs `metadata` shapes). See **`examples/einsum_general.py`**. |
 
 ## Minimal examples
 
@@ -255,14 +261,14 @@ Numeric fields with **`None`** use the corresponding `DEFAULT_*` on the class (s
 
 | Field | Default | Role |
 |-------|---------|------|
-| `node_color` | `"#E8E8E8"` | Tensor node fill. |
-| `node_edge_color` | `"#2D3748"` | Tensor node outline. |
-| `node_color_degree_one` | `"#E8D6D6"` | Fill for tensors with total graph degree 1. |
-| `node_edge_color_degree_one` | `"#4A3436"` | Outline for degree-1 tensors. |
-| `tensor_label_color` | `"#1A202C"` | Tensor name text. |
-| `label_color` | `"#0C1319"` | Index / bond label text. |
-| `bond_edge_color` | `"#00008B"` | Contraction edges. |
-| `dangling_edge_color` | `"#8B0000"` | Dangling (open) legs. |
+| `node_color` | `"#E8EEF5"` | Tensor node fill. |
+| `node_edge_color` | `"#1E293B"` | Tensor node outline. |
+| `node_color_degree_one` | `"#FEE2E2"` | Fill for tensors with total graph degree 1. |
+| `node_edge_color_degree_one` | `"#7F1D1D"` | Outline for degree-1 tensors. |
+| `tensor_label_color` | `"#0F172A"` | Tensor name text. |
+| `label_color` | `"#334155"` | Index / bond label text. |
+| `bond_edge_color` | `"#0369A1"` | Contraction edges. |
+| `dangling_edge_color` | `"#BE123C"` | Dangling (open) legs. |
 | `figsize` | `(8, 6)` | `inches`; `None` uses Matplotlib fallback `(14, 10)` when the renderer creates a new figure. |
 | `show_tensor_labels` | `True` | Draw tensor names on nodes. |
 | `show_index_labels` | `True` | Draw axis names on bonds / stubs. |
@@ -290,6 +296,7 @@ from tensor_network_viz import (
     PlotConfig,
     ViewName,
     einsum,
+    einsum_trace_step,
     pair_tensor,
     show_tensor_network,
 )
@@ -301,10 +308,21 @@ Per-backend plotters (optional; same as `show_tensor_network` internals):
 from tensor_network_viz.tensorkrowch import plot_tensorkrowch_network_2d, plot_tensorkrowch_network_3d
 from tensor_network_viz.tensornetwork import plot_tensornetwork_network_2d, plot_tensornetwork_network_3d
 from tensor_network_viz.quimb import plot_quimb_network_2d, plot_quimb_network_3d
-from tensor_network_viz.tenpy import plot_tenpy_network_2d, plot_tenpy_network_3d
-from tensor_network_viz.einsum_module import plot_einsum_network_2d, plot_einsum_network_3d
+from tensor_network_viz.tenpy import (
+    make_tenpy_tensor_network,
+    plot_tenpy_network_2d,
+    plot_tenpy_network_3d,
+)
+from tensor_network_viz.einsum_module import (
+    parse_einsum_equation,
+    parse_equation_for_shapes,
+    plot_einsum_network_2d,
+    plot_einsum_network_3d,
+)
 ```
 
+(`parse_equation_for_shapes` — binary only; `parse_einsum_equation` — any arity, NumPy-validated.)
+
 ## Accepted inputs (summary)
 
 | Backend | Input |
@@ -312,8 +330,8 @@ from tensor_network_viz.einsum_module import plot_einsum_network_2d, plot_einsum
 | tensorkrowch | Network with `nodes` / `leaf_nodes`, or iterable of nodes |
 | tensornetwork | Iterable of `tensornetwork.Node` |
 | quimb | `TensorNetwork` or iterable of `Tensor` |
-| tenpy | Finite/segment/infinite `MPS`, finite/infinite `MPO` |
-| einsum | `EinsumTrace` or ordered iterable of `pair_tensor` |
+| tenpy | `TenPyTensorNetwork` / `make_tenpy_tensor_network` (`npc.Array` + bonds); `MPS`, `MPO`, `MomentumMPS`-like; no stable TeNPy PEPS class (hand-built TN ok) |
+| einsum | `EinsumTrace` or ordered iterable of `pair_tensor` / `einsum_trace_step` (ellipsis / hyperedges in the normalized graph) |
 
 Details, subgraph behavior, and Quimb hyperindex hubs are in **[docs/guide.md](docs/guide.md)**.
 
@@ -329,8 +347,10 @@ Runnable demos live under **`examples/`**. From the repo root with the right ext
 | `mera_tree_demo.py` | Large MERA + binary TTN stress test. |
 | `cubic_peps_demo.py` | 3D cubic PEPS lattice. |
 | `quimb_demo.py` | Includes hyper-index example; `--from-list`. |
-| `tenpy_demo.py` | Finite and infinite MPS/MPO. |
+| `tenpy_demo.py` | MPS/MPO, purification, uniform, excitation chain (duck-typed like `MomentumMPS`). |
+| `tenpy_explicit_tn_demo.py` | Explicit `TenPyTensorNetwork`: open chain or 3-way hub ([examples/README](examples/README.md)). |
 | `einsum_demo.py` | Auto trace vs manual `pair_tensor`. |
+| `einsum_general.py` | Ellipsis, batch hubs, multi-step fusion, traces, short MPS, implicit/`out=`, unary, ternary (auto-trace). |
 | `tn_tsp.py` | Larger TensorKrowch TSP construction. |
 
 Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
@@ -340,7 +360,14 @@ Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
 - Quimb **hyper-indices** (three or more tensors) are drawn via internal virtual hubs.
 - Infinite TeNPy **MPS/MPO** use one periodic unit cell.
 - The **einsum** backend visualizes the **fundamental** tensor network, not each intermediate
-  contraction tensor.
+  contraction tensor. Pairwise summed indices are drawn as ordinary bonds; repeated or
+  output-carrying indices use **virtual hubs** (layout separates colocated hubs, nudges **2D**
+  hubs that attach to **one** tensor only—e.g. **`ii->i`**—off that tensor, and offsets hubs on a
+  tensor–tensor chord when a **direct** bond also links that pair).
+- Optional **`contraction_steps`** from **einsum**: **running union** of operand physical lineages
+  (each step is a superset of the previous); **`PlotConfig`** draws per-step **AABB** highlights
+  (**2D:** rounded rectangles; **3D:** wireframe), colored borders (no fill by default), extra
+  padding as steps advance, and later steps underneath.
 - Passing a **subset** of nodes/tensors shows connections outside the subset as **dangling** legs.
 
 ## Quick verification (reviewers)
@@ -362,6 +389,7 @@ Expect `quimb_mps.png` and all tests passing.
 | Blank or double figure in Jupyter | Assign `fig, ax = show_tensor_network(...)`; avoid bare tuple as last line; try `%matplotlib widget` or inline. |
 | Hover labels do nothing | Requires interactive backend and `show` path that runs a GUI or widget event loop; not for `--no-show` PNG only. |
 | Huge graphs are slow | `PlotConfig(refine_tensor_labels=False)`; lower `layout_iterations` or pass `positions`. Force layout samples repulsion when node count is large (about 72+; see [guide](docs/guide.md#layout-and-draw-scale)). |
+| Einsum unary trace (`ii->i`) looks odd in 2D | Layout offsets the virtual hub off the tensor in 2D; try `view="3d"` or read [Einsum unary / same-tensor trace in 2D](docs/guide.md#toc-einsum-unary-2d-layout) in the guide. |
 
 **Full troubleshooting:** [docs/guide.md — Troubleshooting](docs/guide.md#troubleshooting).
 

{tensor_network_visualization-1.4.1 → tensor_network_visualization-1.4.2}/README.md

@@ -31,8 +31,11 @@ PyPI package name: `tensor-network-visualization`. Import module: `tensor_networ
 python -m pip install tensor-network-visualization
 ```
 
-Depends on `matplotlib` and `networkx` only. You can render **`einsum`** traces built from ordered
-`pair_tensor` entries without installing PyTorch.
+Base runtime dependencies are `numpy`, `matplotlib`, and `networkx` only. You can **build and
+render** rich **`einsum`** graphs from ordered **`pair_tensor`** / **`einsum_trace_step`** entries
+(ellipsis and repeated indices need shapes in metadata); **`tensor-network-visualization[einsum]`**
+(PyTorch) is only needed to **execute** `tensor_network_viz.einsum(..., trace=...)` and record
+those rows automatically.
 
 ### Optional backends (extras)
 
@@ -42,7 +45,7 @@ Depends on `matplotlib` and `networkx` only. You can render **`einsum`** traces
 | TensorNetwork  | `tensornetwork`               | `pip install "tensor-network-visualization[tensornetwork]"` |
 | Quimb          | `quimb`                       | `pip install "tensor-network-visualization[quimb]"` |
 | TeNPy          | `tenpy`                       | Resolves to PyPI package **`physics-tenpy`**. |
-| Einsum tracing | `einsum`                      | Adds **PyTorch** for the traced `einsum` helper. |
+| Einsum tracing | `einsum`                      | Adds **PyTorch** for auto-traced `einsum(..., trace=...)` (layout from `pair_tensor` / `einsum_trace_step` lists with metadata as needed). |
 | Jupyter widgets| `jupyter`                    | `ipympl`, widgets, JupyterLab / Notebook 7+ for interactive figures. |
 
 Combine extras, for example:
@@ -101,7 +104,8 @@ Everything below maps to real parameters—there are no hidden mode switches.
 | **Display mode** | `show=True` / `False` | If `True`: Jupyter **kernel** uses `IPython.display.display(fig)`; otherwise `plt.show()`. If `False`: neither runs—use for `savefig` / batch. |
 | **Label policy** | `PlotConfig` + overrides | Defaults: `show_tensor_labels`, `show_index_labels`. Per-call: `show_tensor_network(..., show_tensor_labels=..., show_index_labels=...)`. |
 | **Hover labels** | `PlotConfig(hover_labels=True)` | Tensor names and bond labels appear on pointer hover (2D axes hit-test; 3D screen-space distance). Needs an **interactive** Matplotlib window. |
-| **Einsum workflow** | `engine="einsum"` | **Auto:** `EinsumTrace` + `tensor_network_viz.einsum`. **Manual:** ordered list of `pair_tensor(...)`. |
+| **Contraction scheme** | `PlotConfig(show_contraction_scheme=True)` | **Einsum:** cumulative per-step highlights from the trace. **Other engines:** set **`contraction_scheme_by_name`**. **2D:** rounded boxes (AABB + pad); colored borders (no fill by default). **3D:** wireframe box. See **`docs/guide.md`**. |
+| **Einsum workflow** | `engine="einsum"` | **Auto:** `EinsumTrace` + `einsum` (binary `pair_tensor`, unary/ternary+ `einsum_trace_step`; implicit `->`, `out=`). **Manual:** `pair_tensor` / `einsum_trace_step` (ellipsis needs `metadata` shapes). See **`examples/einsum_general.py`**. |
 
 ## Minimal examples
 
@@ -208,14 +212,14 @@ Numeric fields with **`None`** use the corresponding `DEFAULT_*` on the class (s
 
 | Field | Default | Role |
 |-------|---------|------|
-| `node_color` | `"#E8E8E8"` | Tensor node fill. |
-| `node_edge_color` | `"#2D3748"` | Tensor node outline. |
-| `node_color_degree_one` | `"#E8D6D6"` | Fill for tensors with total graph degree 1. |
-| `node_edge_color_degree_one` | `"#4A3436"` | Outline for degree-1 tensors. |
-| `tensor_label_color` | `"#1A202C"` | Tensor name text. |
-| `label_color` | `"#0C1319"` | Index / bond label text. |
-| `bond_edge_color` | `"#00008B"` | Contraction edges. |
-| `dangling_edge_color` | `"#8B0000"` | Dangling (open) legs. |
+| `node_color` | `"#E8EEF5"` | Tensor node fill. |
+| `node_edge_color` | `"#1E293B"` | Tensor node outline. |
+| `node_color_degree_one` | `"#FEE2E2"` | Fill for tensors with total graph degree 1. |
+| `node_edge_color_degree_one` | `"#7F1D1D"` | Outline for degree-1 tensors. |
+| `tensor_label_color` | `"#0F172A"` | Tensor name text. |
+| `label_color` | `"#334155"` | Index / bond label text. |
+| `bond_edge_color` | `"#0369A1"` | Contraction edges. |
+| `dangling_edge_color` | `"#BE123C"` | Dangling (open) legs. |
 | `figsize` | `(8, 6)` | `inches`; `None` uses Matplotlib fallback `(14, 10)` when the renderer creates a new figure. |
 | `show_tensor_labels` | `True` | Draw tensor names on nodes. |
 | `show_index_labels` | `True` | Draw axis names on bonds / stubs. |
@@ -243,6 +247,7 @@ from tensor_network_viz import (
     PlotConfig,
     ViewName,
     einsum,
+    einsum_trace_step,
     pair_tensor,
     show_tensor_network,
 )
@@ -254,10 +259,21 @@ Per-backend plotters (optional; same as `show_tensor_network` internals):
 from tensor_network_viz.tensorkrowch import plot_tensorkrowch_network_2d, plot_tensorkrowch_network_3d
 from tensor_network_viz.tensornetwork import plot_tensornetwork_network_2d, plot_tensornetwork_network_3d
 from tensor_network_viz.quimb import plot_quimb_network_2d, plot_quimb_network_3d
-from tensor_network_viz.tenpy import plot_tenpy_network_2d, plot_tenpy_network_3d
-from tensor_network_viz.einsum_module import plot_einsum_network_2d, plot_einsum_network_3d
+from tensor_network_viz.tenpy import (
+    make_tenpy_tensor_network,
+    plot_tenpy_network_2d,
+    plot_tenpy_network_3d,
+)
+from tensor_network_viz.einsum_module import (
+    parse_einsum_equation,
+    parse_equation_for_shapes,
+    plot_einsum_network_2d,
+    plot_einsum_network_3d,
+)
 ```
 
+(`parse_equation_for_shapes` — binary only; `parse_einsum_equation` — any arity, NumPy-validated.)
+
 ## Accepted inputs (summary)
 
 | Backend | Input |
@@ -265,8 +281,8 @@ from tensor_network_viz.einsum_module import plot_einsum_network_2d, plot_einsum
 | tensorkrowch | Network with `nodes` / `leaf_nodes`, or iterable of nodes |
 | tensornetwork | Iterable of `tensornetwork.Node` |
 | quimb | `TensorNetwork` or iterable of `Tensor` |
-| tenpy | Finite/segment/infinite `MPS`, finite/infinite `MPO` |
-| einsum | `EinsumTrace` or ordered iterable of `pair_tensor` |
+| tenpy | `TenPyTensorNetwork` / `make_tenpy_tensor_network` (`npc.Array` + bonds); `MPS`, `MPO`, `MomentumMPS`-like; no stable TeNPy PEPS class (hand-built TN ok) |
+| einsum | `EinsumTrace` or ordered iterable of `pair_tensor` / `einsum_trace_step` (ellipsis / hyperedges in the normalized graph) |
 
 Details, subgraph behavior, and Quimb hyperindex hubs are in **[docs/guide.md](docs/guide.md)**.
 
@@ -282,8 +298,10 @@ Runnable demos live under **`examples/`**. From the repo root with the right ext
 | `mera_tree_demo.py` | Large MERA + binary TTN stress test. |
 | `cubic_peps_demo.py` | 3D cubic PEPS lattice. |
 | `quimb_demo.py` | Includes hyper-index example; `--from-list`. |
-| `tenpy_demo.py` | Finite and infinite MPS/MPO. |
+| `tenpy_demo.py` | MPS/MPO, purification, uniform, excitation chain (duck-typed like `MomentumMPS`). |
+| `tenpy_explicit_tn_demo.py` | Explicit `TenPyTensorNetwork`: open chain or 3-way hub ([examples/README](examples/README.md)). |
 | `einsum_demo.py` | Auto trace vs manual `pair_tensor`. |
+| `einsum_general.py` | Ellipsis, batch hubs, multi-step fusion, traces, short MPS, implicit/`out=`, unary, ternary (auto-trace). |
 | `tn_tsp.py` | Larger TensorKrowch TSP construction. |
 
 Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
@@ -293,7 +311,14 @@ Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
 - Quimb **hyper-indices** (three or more tensors) are drawn via internal virtual hubs.
 - Infinite TeNPy **MPS/MPO** use one periodic unit cell.
 - The **einsum** backend visualizes the **fundamental** tensor network, not each intermediate
-  contraction tensor.
+  contraction tensor. Pairwise summed indices are drawn as ordinary bonds; repeated or
+  output-carrying indices use **virtual hubs** (layout separates colocated hubs, nudges **2D**
+  hubs that attach to **one** tensor only—e.g. **`ii->i`**—off that tensor, and offsets hubs on a
+  tensor–tensor chord when a **direct** bond also links that pair).
+- Optional **`contraction_steps`** from **einsum**: **running union** of operand physical lineages
+  (each step is a superset of the previous); **`PlotConfig`** draws per-step **AABB** highlights
+  (**2D:** rounded rectangles; **3D:** wireframe), colored borders (no fill by default), extra
+  padding as steps advance, and later steps underneath.
 - Passing a **subset** of nodes/tensors shows connections outside the subset as **dangling** legs.
 
 ## Quick verification (reviewers)
@@ -315,6 +340,7 @@ Expect `quimb_mps.png` and all tests passing.
 | Blank or double figure in Jupyter | Assign `fig, ax = show_tensor_network(...)`; avoid bare tuple as last line; try `%matplotlib widget` or inline. |
 | Hover labels do nothing | Requires interactive backend and `show` path that runs a GUI or widget event loop; not for `--no-show` PNG only. |
 | Huge graphs are slow | `PlotConfig(refine_tensor_labels=False)`; lower `layout_iterations` or pass `positions`. Force layout samples repulsion when node count is large (about 72+; see [guide](docs/guide.md#layout-and-draw-scale)). |
+| Einsum unary trace (`ii->i`) looks odd in 2D | Layout offsets the virtual hub off the tensor in 2D; try `view="3d"` or read [Einsum unary / same-tensor trace in 2D](docs/guide.md#toc-einsum-unary-2d-layout) in the guide. |
 
 **Full troubleshooting:** [docs/guide.md — Troubleshooting](docs/guide.md#troubleshooting).
 

{tensor_network_visualization-1.4.1 → tensor_network_visualization-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tensor-network-visualization"
-version = "1.4.1"
+version = "1.4.2"
 description = "Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks."
 authors = [{ name = "Alejandro Mata Ali" }]
 readme = "README.md"
@@ -14,6 +14,7 @@ keywords = ["tensor-network", "visualization", "pytorch", "numpy", "tensorkrowch
 dependencies = [
     "matplotlib>=3.7",
     "networkx>=3.0",
+    "numpy",
 ]
 classifiers = [
     "License :: OSI Approved :: MIT License",
@@ -30,7 +31,7 @@ Repository = "https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization"
 Issues = "https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization/issues"
 
 [project.optional-dependencies]
-dev = ["pytest", "ruff", "pyright", "ipython", "tensorkrowch", "tensornetwork", "quimb", "physics-tenpy"]
+dev = ["pytest", "ruff", "pyright", "ipython", "tomli>=2.0.1", "tensorkrowch", "tensornetwork", "quimb", "physics-tenpy"]
 jupyter = ["ipympl>=0.9.0", "ipywidgets>=8.0", "jupyterlab>=4.0", "notebook>=7.0"]
 tensorkrowch = ["tensorkrowch"]
 tensornetwork = ["tensornetwork"]

{tensor_network_visualization-1.4.1 → tensor_network_visualization-1.4.2/src/tensor_network_visualization.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensor-network-visualization
-Version: 1.4.1
+Version: 1.4.2
 Summary: Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks.
 Author: Alejandro Mata Ali
 License: MIT
@@ -19,11 +19,13 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: matplotlib>=3.7
 Requires-Dist: networkx>=3.0
+Requires-Dist: numpy
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pyright; extra == "dev"
 Requires-Dist: ipython; extra == "dev"
+Requires-Dist: tomli>=2.0.1; extra == "dev"
 Requires-Dist: tensorkrowch; extra == "dev"
 Requires-Dist: tensornetwork; extra == "dev"
 Requires-Dist: quimb; extra == "dev"
@@ -78,8 +80,11 @@ PyPI package name: `tensor-network-visualization`. Import module: `tensor_networ
 python -m pip install tensor-network-visualization
 ```
 
-Depends on `matplotlib` and `networkx` only. You can render **`einsum`** traces built from ordered
-`pair_tensor` entries without installing PyTorch.
+Base runtime dependencies are `numpy`, `matplotlib`, and `networkx` only. You can **build and
+render** rich **`einsum`** graphs from ordered **`pair_tensor`** / **`einsum_trace_step`** entries
+(ellipsis and repeated indices need shapes in metadata); **`tensor-network-visualization[einsum]`**
+(PyTorch) is only needed to **execute** `tensor_network_viz.einsum(..., trace=...)` and record
+those rows automatically.
 
 ### Optional backends (extras)
 
@@ -89,7 +94,7 @@ Depends on `matplotlib` and `networkx` only. You can render **`einsum`** traces
 | TensorNetwork  | `tensornetwork`               | `pip install "tensor-network-visualization[tensornetwork]"` |
 | Quimb          | `quimb`                       | `pip install "tensor-network-visualization[quimb]"` |
 | TeNPy          | `tenpy`                       | Resolves to PyPI package **`physics-tenpy`**. |
-| Einsum tracing | `einsum`                      | Adds **PyTorch** for the traced `einsum` helper. |
+| Einsum tracing | `einsum`                      | Adds **PyTorch** for auto-traced `einsum(..., trace=...)` (layout from `pair_tensor` / `einsum_trace_step` lists with metadata as needed). |
 | Jupyter widgets| `jupyter`                    | `ipympl`, widgets, JupyterLab / Notebook 7+ for interactive figures. |
 
 Combine extras, for example:
@@ -148,7 +153,8 @@ Everything below maps to real parameters—there are no hidden mode switches.
 | **Display mode** | `show=True` / `False` | If `True`: Jupyter **kernel** uses `IPython.display.display(fig)`; otherwise `plt.show()`. If `False`: neither runs—use for `savefig` / batch. |
 | **Label policy** | `PlotConfig` + overrides | Defaults: `show_tensor_labels`, `show_index_labels`. Per-call: `show_tensor_network(..., show_tensor_labels=..., show_index_labels=...)`. |
 | **Hover labels** | `PlotConfig(hover_labels=True)` | Tensor names and bond labels appear on pointer hover (2D axes hit-test; 3D screen-space distance). Needs an **interactive** Matplotlib window. |
-| **Einsum workflow** | `engine="einsum"` | **Auto:** `EinsumTrace` + `tensor_network_viz.einsum`. **Manual:** ordered list of `pair_tensor(...)`. |
+| **Contraction scheme** | `PlotConfig(show_contraction_scheme=True)` | **Einsum:** cumulative per-step highlights from the trace. **Other engines:** set **`contraction_scheme_by_name`**. **2D:** rounded boxes (AABB + pad); colored borders (no fill by default). **3D:** wireframe box. See **`docs/guide.md`**. |
+| **Einsum workflow** | `engine="einsum"` | **Auto:** `EinsumTrace` + `einsum` (binary `pair_tensor`, unary/ternary+ `einsum_trace_step`; implicit `->`, `out=`). **Manual:** `pair_tensor` / `einsum_trace_step` (ellipsis needs `metadata` shapes). See **`examples/einsum_general.py`**. |
 
 ## Minimal examples
 
@@ -255,14 +261,14 @@ Numeric fields with **`None`** use the corresponding `DEFAULT_*` on the class (s
 
 | Field | Default | Role |
 |-------|---------|------|
-| `node_color` | `"#E8E8E8"` | Tensor node fill. |
-| `node_edge_color` | `"#2D3748"` | Tensor node outline. |
-| `node_color_degree_one` | `"#E8D6D6"` | Fill for tensors with total graph degree 1. |
-| `node_edge_color_degree_one` | `"#4A3436"` | Outline for degree-1 tensors. |
-| `tensor_label_color` | `"#1A202C"` | Tensor name text. |
-| `label_color` | `"#0C1319"` | Index / bond label text. |
-| `bond_edge_color` | `"#00008B"` | Contraction edges. |
-| `dangling_edge_color` | `"#8B0000"` | Dangling (open) legs. |
+| `node_color` | `"#E8EEF5"` | Tensor node fill. |
+| `node_edge_color` | `"#1E293B"` | Tensor node outline. |
+| `node_color_degree_one` | `"#FEE2E2"` | Fill for tensors with total graph degree 1. |
+| `node_edge_color_degree_one` | `"#7F1D1D"` | Outline for degree-1 tensors. |
+| `tensor_label_color` | `"#0F172A"` | Tensor name text. |
+| `label_color` | `"#334155"` | Index / bond label text. |
+| `bond_edge_color` | `"#0369A1"` | Contraction edges. |
+| `dangling_edge_color` | `"#BE123C"` | Dangling (open) legs. |
 | `figsize` | `(8, 6)` | `inches`; `None` uses Matplotlib fallback `(14, 10)` when the renderer creates a new figure. |
 | `show_tensor_labels` | `True` | Draw tensor names on nodes. |
 | `show_index_labels` | `True` | Draw axis names on bonds / stubs. |
@@ -290,6 +296,7 @@ from tensor_network_viz import (
     PlotConfig,
     ViewName,
     einsum,
+    einsum_trace_step,
     pair_tensor,
     show_tensor_network,
 )
@@ -301,10 +308,21 @@ Per-backend plotters (optional; same as `show_tensor_network` internals):
 from tensor_network_viz.tensorkrowch import plot_tensorkrowch_network_2d, plot_tensorkrowch_network_3d
 from tensor_network_viz.tensornetwork import plot_tensornetwork_network_2d, plot_tensornetwork_network_3d
 from tensor_network_viz.quimb import plot_quimb_network_2d, plot_quimb_network_3d
-from tensor_network_viz.tenpy import plot_tenpy_network_2d, plot_tenpy_network_3d
-from tensor_network_viz.einsum_module import plot_einsum_network_2d, plot_einsum_network_3d
+from tensor_network_viz.tenpy import (
+    make_tenpy_tensor_network,
+    plot_tenpy_network_2d,
+    plot_tenpy_network_3d,
+)
+from tensor_network_viz.einsum_module import (
+    parse_einsum_equation,
+    parse_equation_for_shapes,
+    plot_einsum_network_2d,
+    plot_einsum_network_3d,
+)
 ```
 
+(`parse_equation_for_shapes` — binary only; `parse_einsum_equation` — any arity, NumPy-validated.)
+
 ## Accepted inputs (summary)
 
 | Backend | Input |
@@ -312,8 +330,8 @@ from tensor_network_viz.einsum_module import plot_einsum_network_2d, plot_einsum
 | tensorkrowch | Network with `nodes` / `leaf_nodes`, or iterable of nodes |
 | tensornetwork | Iterable of `tensornetwork.Node` |
 | quimb | `TensorNetwork` or iterable of `Tensor` |
-| tenpy | Finite/segment/infinite `MPS`, finite/infinite `MPO` |
-| einsum | `EinsumTrace` or ordered iterable of `pair_tensor` |
+| tenpy | `TenPyTensorNetwork` / `make_tenpy_tensor_network` (`npc.Array` + bonds); `MPS`, `MPO`, `MomentumMPS`-like; no stable TeNPy PEPS class (hand-built TN ok) |
+| einsum | `EinsumTrace` or ordered iterable of `pair_tensor` / `einsum_trace_step` (ellipsis / hyperedges in the normalized graph) |
 
 Details, subgraph behavior, and Quimb hyperindex hubs are in **[docs/guide.md](docs/guide.md)**.
 
@@ -329,8 +347,10 @@ Runnable demos live under **`examples/`**. From the repo root with the right ext
 | `mera_tree_demo.py` | Large MERA + binary TTN stress test. |
 | `cubic_peps_demo.py` | 3D cubic PEPS lattice. |
 | `quimb_demo.py` | Includes hyper-index example; `--from-list`. |
-| `tenpy_demo.py` | Finite and infinite MPS/MPO. |
+| `tenpy_demo.py` | MPS/MPO, purification, uniform, excitation chain (duck-typed like `MomentumMPS`). |
+| `tenpy_explicit_tn_demo.py` | Explicit `TenPyTensorNetwork`: open chain or 3-way hub ([examples/README](examples/README.md)). |
 | `einsum_demo.py` | Auto trace vs manual `pair_tensor`. |
+| `einsum_general.py` | Ellipsis, batch hubs, multi-step fusion, traces, short MPS, implicit/`out=`, unary, ternary (auto-trace). |
 | `tn_tsp.py` | Larger TensorKrowch TSP construction. |
 
 Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
@@ -340,7 +360,14 @@ Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
 - Quimb **hyper-indices** (three or more tensors) are drawn via internal virtual hubs.
 - Infinite TeNPy **MPS/MPO** use one periodic unit cell.
 - The **einsum** backend visualizes the **fundamental** tensor network, not each intermediate
-  contraction tensor.
+  contraction tensor. Pairwise summed indices are drawn as ordinary bonds; repeated or
+  output-carrying indices use **virtual hubs** (layout separates colocated hubs, nudges **2D**
+  hubs that attach to **one** tensor only—e.g. **`ii->i`**—off that tensor, and offsets hubs on a
+  tensor–tensor chord when a **direct** bond also links that pair).
+- Optional **`contraction_steps`** from **einsum**: **running union** of operand physical lineages
+  (each step is a superset of the previous); **`PlotConfig`** draws per-step **AABB** highlights
+  (**2D:** rounded rectangles; **3D:** wireframe), colored borders (no fill by default), extra
+  padding as steps advance, and later steps underneath.
 - Passing a **subset** of nodes/tensors shows connections outside the subset as **dangling** legs.
 
 ## Quick verification (reviewers)
@@ -362,6 +389,7 @@ Expect `quimb_mps.png` and all tests passing.
 | Blank or double figure in Jupyter | Assign `fig, ax = show_tensor_network(...)`; avoid bare tuple as last line; try `%matplotlib widget` or inline. |
 | Hover labels do nothing | Requires interactive backend and `show` path that runs a GUI or widget event loop; not for `--no-show` PNG only. |
 | Huge graphs are slow | `PlotConfig(refine_tensor_labels=False)`; lower `layout_iterations` or pass `positions`. Force layout samples repulsion when node count is large (about 72+; see [guide](docs/guide.md#layout-and-draw-scale)). |
+| Einsum unary trace (`ii->i`) looks odd in 2D | Layout offsets the virtual hub off the tensor in 2D; try `view="3d"` or read [Einsum unary / same-tensor trace in 2D](docs/guide.md#toc-einsum-unary-2d-layout) in the guide. |
 
 **Full troubleshooting:** [docs/guide.md — Troubleshooting](docs/guide.md#troubleshooting).
 

{tensor_network_visualization-1.4.1 → tensor_network_visualization-1.4.2}/src/tensor_network_visualization.egg-info/SOURCES.txt

@@ -26,6 +26,7 @@ src/tensor_network_viz/_core/layout_structure.py
 src/tensor_network_viz/_core/renderer.py
 src/tensor_network_viz/_core/draw/__init__.py
 src/tensor_network_viz/_core/draw/constants.py
+src/tensor_network_viz/_core/draw/contraction_scheme.py
 src/tensor_network_viz/_core/draw/disk_metrics.py
 src/tensor_network_viz/_core/draw/edges.py
 src/tensor_network_viz/_core/draw/fonts_and_scale.py
@@ -54,6 +55,7 @@ src/tensor_network_viz/quimb/__init__.py
 src/tensor_network_viz/quimb/graph.py
 src/tensor_network_viz/quimb/renderer.py
 src/tensor_network_viz/tenpy/__init__.py
+src/tensor_network_viz/tenpy/explicit.py
 src/tensor_network_viz/tenpy/graph.py
 src/tensor_network_viz/tenpy/renderer.py
 src/tensor_network_viz/tensorkrowch/__init__.py
@@ -63,22 +65,24 @@ src/tensor_network_viz/tensornetwork/__init__.py
 src/tensor_network_viz/tensornetwork/graph.py
 src/tensor_network_viz/tensornetwork/renderer.py
 tests/test_contraction_groups_once.py
+tests/test_contraction_scheme.py
+tests/test_demo_cli_scheme.py
 tests/test_draw_performance.py
 tests/test_edge_index_label_2d.py
 tests/test_edge_index_label_3d.py
 tests/test_einsum_autotrace.py
 tests/test_einsum_backend.py
 tests/test_examples.py
+tests/test_examples_structure.py
 tests/test_graph_cache.py
 tests/test_integration_einsum.py
-tests/test_integration_quimb.py
-tests/test_integration_tenpy.py
 tests/test_integration_tensorkrowch.py
 tests/test_integration_tensornetwork.py
 tests/test_label_draw_metrics_perf.py
 tests/test_label_format.py
 tests/test_layout_core.py
 tests/test_node_degrees_perf.py
+tests/test_packaging_metadata.py
 tests/test_plotting.py
 tests/test_public_api.py
 tests/test_quimb_backend.py

{tensor_network_visualization-1.4.1 → tensor_network_visualization-1.4.2}/src/tensor_network_visualization.egg-info/requires.txt

@@ -1,11 +1,13 @@
 matplotlib>=3.7
 networkx>=3.0
+numpy
 
 [dev]
 pytest
 ruff
 pyright
 ipython
+tomli>=2.0.1
 tensorkrowch
 tensornetwork
 quimb

{tensor_network_visualization-1.4.1 → tensor_network_visualization-1.4.2}/src/tensor_network_viz/__init__.py

@@ -2,7 +2,8 @@ from typing import TYPE_CHECKING, Any
 
 from ._core.graph_cache import clear_tensor_network_graph_cache
 from .config import EngineName, PlotConfig, ViewName
-from .einsum_module.trace import EinsumTrace, einsum, pair_tensor
+from .einsum_module.trace import EinsumTrace, einsum, einsum_trace_step, pair_tensor
+from .tenpy.explicit import TenPyTensorNetwork, make_tenpy_tensor_network
 
 if TYPE_CHECKING:
     from .viewer import show_tensor_network
@@ -18,9 +19,12 @@ __all__ = [
     "EngineName",
     "EinsumTrace",
     "PlotConfig",
+    "TenPyTensorNetwork",
     "ViewName",
     "clear_tensor_network_graph_cache",
     "einsum",
+    "einsum_trace_step",
+    "make_tenpy_tensor_network",
     "pair_tensor",
     "show_tensor_network",
 ]