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

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

@@ -1,31 +1,33 @@
 Metadata-Version: 2.4
 Name: tensor-network-visualization
-Version: 1.4.2
+Version: 1.5.0
 Summary: Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks.
 Author: Alejandro Mata Ali
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization
 Project-URL: Documentation, https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization/blob/main/docs/guide.md
 Project-URL: Changelog, https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization/blob/main/CHANGELOG.md
 Project-URL: Repository, https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization
 Project-URL: Issues, https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization/issues
 Keywords: tensor-network,visualization,pytorch,numpy,tensorkrowch,tensornetwork,quimb,tenpy,einsum,quantum-inspired,matplotlib
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 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: build; 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"
@@ -64,8 +66,9 @@ PyTorch/NumPy `einsum` tensor networks.
 Tensor network libraries use different object models and rarely share a single visualization path.
 This package **normalizes** each backend into one graph description, **lays out** nodes (chains,
 grids, trees, planar embeddings, or force-directed fallback), and **draws** with Matplotlib in
-**2D** (filled disks) or **3D** (lightweight octahedra). There is no custom GUI: you get standard
-`Figure` and `Axes` objects for saving, composing subplots, and further styling.
+**2D** (filled disks) or **3D** (lightweight octahedra). The interactive layer stays inside
+standard Matplotlib figures: `show_tensor_network` can add a small control panel, while the return
+value is still a normal `Figure` plus `Axes` object that you can save, embed, or restyle.
 
 **Audience:** Researchers who work with tensor networks and want consistent, publication-friendly
 diagrams across Quimb, TeNPy, TensorNetwork, TensorKrowch, or traced `einsum` contraction graphs.
@@ -74,6 +77,8 @@ diagrams across Quimb, TeNPy, TensorNetwork, TensorKrowch, or traced `einsum` co
 
 PyPI package name: `tensor-network-visualization`. Import module: `tensor_network_viz`.
 
+**Requires Python 3.11 or newer.**
+
 ### Base install
 
 ```bash
@@ -148,13 +153,19 @@ Everything below maps to real parameters—there are no hidden mode switches.
 
 | Concept | Where | Meaning |
 |--------|--------|---------|
-| **View mode** | `show_tensor_network(..., view=...)` | `"2d"` — disk nodes; `"3d"` — octahedra. Same normalized graph. |
-| **Engine mode** | `engine=...` | Adapter: `"tensorkrowch"`, `"tensornetwork"`, `"quimb"`, `"tenpy"`, `"einsum"`. Invalid → `ValueError`. |
+| **View mode** | `show_tensor_network(..., view=...)` | Default is `"2d"`; `"3d"` is available from the same figure controls when widgets are enabled. |
+| **Engine mode** | `engine=...` | Optional override. When omitted, `show_tensor_network` auto-detects `"tensorkrowch"`, `"tensornetwork"`, `"quimb"`, `"tenpy"`, or `"einsum"` from the input. Invalid explicit values still raise `ValueError`. |
 | **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. |
-| **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`**. |
+| **Interactive controls** | `interactive_controls=True` | Figure-level Matplotlib widgets for view/hover/label toggles. Set `False` for clean static exports or headless batch rendering. |
+| **Label policy** | `PlotConfig` + overrides | Defaults: `show_tensor_labels=False`, `show_index_labels=False`. Per-call: `show_tensor_network(..., show_tensor_labels=..., show_index_labels=...)`. |
+| **Hover labels** | `PlotConfig(hover_labels=True)` | Default is `True`. Hover tooltips are independent from static labels, so both can stay enabled together in an interactive Matplotlib window. |
+| **Contraction scheme** | `PlotConfig(show_contraction_scheme=True)` | **Einsum:** cumulative per-step highlights from the trace. **Other engines:** set **`contraction_scheme_by_name`**. Compatible figures now add Matplotlib toggles for **Scheme**, **Playback**, and **Cost hover**; if you start with those flags off, the scheme bundle is computed lazily on first use. **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:** ordered `pair_tensor` / `einsum_trace_step` lists when you want a fully explicit trace. See **`examples/run_demo.py`** and **`examples/einsum_demo.py`**. |
+
+`show_tensor_network` now creates figure-level Matplotlib widgets by default: a `2d/3d` selector on
+figures it creates itself, plus `Hover`, `Tensor labels`, and `Edge labels` checkboxes. If you
+pass an external `ax`, the same-view checkboxes stay available but the `2d/3d` selector is hidden.
+The default widget state is `Hover=True`, `Tensor labels=False`, `Edge labels=False`.
 
 ## Minimal examples
 
@@ -177,13 +188,16 @@ network = qtn.TensorNetwork(tensors)
 fig, ax = show_tensor_network(
     network,
     engine="quimb",
-    view="2d",
     config=PlotConfig(figsize=(8, 6)),
+    interactive_controls=False,
     show=False,
 )
 fig.savefig("network.png", bbox_inches="tight")
 ```
 
+Use `interactive_controls=False` when you want the saved figure without the Matplotlib control
+panel.
+
 ### Quimb 3D, hide index labels on this call only
 
 ```python
@@ -203,12 +217,12 @@ fig, ax = show_tensor_network(
 fig, ax = show_tensor_network(
     network,
     engine="quimb",
-    view="2d",
     config=PlotConfig(figsize=(8, 6), hover_labels=True),
 )
 ```
 
-No effect for headless `show=False` without a GUI event loop; pair with an interactive backend
+Hover is independent from static labels, so you can also enable tensor or edge labels from the
+figure checkboxes without losing the hover tooltips. This still needs an interactive backend
 (e.g. `%matplotlib widget` in Jupyter).
 
 ### TeNPy finite MPS (sketch)
@@ -222,7 +236,6 @@ from tensor_network_viz import show_tensor_network, PlotConfig
 fig, ax = show_tensor_network(
     mps,
     engine="tenpy",
-    view="2d",
     config=PlotConfig(figsize=(8, 6)),
     show=False,
 )
@@ -234,25 +247,30 @@ fig, ax = show_tensor_network(
 show_tensor_network(
     network,
     *,
-    engine: EngineName,
-    view: ViewName,
+    engine: EngineName | None = None,
+    view: ViewName | None = None,
     config: PlotConfig | None = None,
+    ax: Axes | Axes3D | None = None,
     show_tensor_labels: bool | None = None,
     show_index_labels: bool | None = None,
+    interactive_controls: bool = True,
     show: bool = True,
 ) -> tuple[Figure, Axes | Axes3D]
 ```
 
 - **`network`:** Backend-native object or iterable (see [guide — supported inputs](docs/guide.md)).
-- **`engine`:** `"tensorkrowch"` \| `"tensornetwork"` \| `"quimb"` \| `"tenpy"` \| `"einsum"`.
-- **`view`:** `"2d"` \| `"3d"`.
+- **`engine`:** optional explicit override. If omitted, the backend is inferred from `network`.
+- **`view`:** `"2d"` \| `"3d"`; omitted means `"2d"` unless a 3D `ax` is passed.
 - **`config`:** Styling and layout; defaults to `PlotConfig()` if omitted.
+- **`ax`:** Optional Matplotlib axes. When present, rendering stays on that axes and the `2d/3d` selector is hidden.
 - **`show_tensor_labels` / `show_index_labels`:** If `None`, use values from `config`; else override for this call only.
+- **`interactive_controls`:** If `True`, attach the view/hover/label widgets when the figure supports them. Set `False` for a static render.
 - **`show`:** Whether to push the figure to the current UI (`display`/`show`).
 - **Returns:** `(fig, ax)` for titles, `savefig`, colorbars, or embedding in a subplot.
 
 Backend-specific shortcuts (same renderer core) accept **`ax=`** and **`seed=`** for subplots and
-reproducible layout; see the [guide](docs/guide.md).
+reproducible layout; they stay fixed-dimension helpers (`plot_*_network_2d` or `plot_*_network_3d`)
+and do not add the `2d/3d` selector. See the [guide](docs/guide.md).
 
 ### `PlotConfig` quick reference
 
@@ -270,8 +288,8 @@ Numeric fields with **`None`** use the corresponding `DEFAULT_*` on the class (s
 | `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. |
+| `show_tensor_labels` | `False` | Draw tensor names on nodes. |
+| `show_index_labels` | `False` | Draw axis names on bonds / stubs. |
 | `node_radius` | `None` | → `0.08` data units (scaled with layout; multiplies geometric radius). |
 | `stub_length` | `None` | → `0.16` (dangling stub length scale). |
 | `self_loop_radius` | `None` | → `0.2` (self-contraction loops). |
@@ -281,7 +299,7 @@ Numeric fields with **`None`** use the corresponding `DEFAULT_*` on the class (s
 | `positions` | `None` | `dict[int, tuple[float, ...]]` — custom positions keyed by **normalized node id** (`id` of adapter node); partial dicts get layout for missing ids. |
 | `validate_positions` | `False` | If `True`, warn on unknown keys or short coordinates vs `view`. |
 | `refine_tensor_labels` | `True` | Extra passes to fit tensor names inside the node marker (2D or 3D); set `False` for speed. |
-| `hover_labels` | `False` | Hide labels until hover (interactive only). |
+| `hover_labels` | `True` | Enable hover tooltips independently from static labels (interactive only). |
 
 Defaults `0.08`, `0.16`, `0.2`, `0.85`, `0.75`, `220` are also available as
 `PlotConfig.DEFAULT_NODE_RADIUS`, `DEFAULT_STUB_LENGTH`, `DEFAULT_SELF_LOOP_RADIUS`,
@@ -337,23 +355,35 @@ Details, subgraph behavior, and Quimb hyperindex hubs are in **[docs/guide.md](d
 
 ## Example scripts
 
-Runnable demos live under **`examples/`**. From the repo root with the right extra installed:
+Runnable demos live under **`examples/`** and now share one public launcher:
+
+```bash
+python examples/run_demo.py <engine> <example> [options]
+```
 
-| Script | Purpose |
+Main files:
+
+| File | Purpose |
 |--------|---------|
-| `demo_cli.py` | Shared helpers (`--hover-labels` → `PlotConfig(hover_labels=True)`); imported by demos. |
-| `tensorkrowch_demo.py` | MPS, MPO, PEPS, weird, disconnected; `--from-list` subset. |
-| `tensornetwork_demo.py` | Same topologies with `tensornetwork.Node`. |
-| `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` | 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)**.
+| `run_demo.py` | Public CLI entry point for every engine and example. |
+| `demo_cli.py` | Shared typed helpers for parsing, save paths, plot config, and topology builders. |
+| `tensorkrowch_demo.py` | TensorKrowch registry: MPS/TT, MPO, ladder, PEPS, cubic PEPS, MERA, MERA+TTN, weird, disconnected. |
+| `tensornetwork_demo.py` | TensorNetwork registry with the same structured graph examples. |
+| `quimb_demo.py` | Quimb registry with the same graph family plus a native hypergraph example. |
+| `tenpy_demo.py` | TeNPy registry: native MPS/MPO/iMPS/iMPO/purification/uniform/excitation plus explicit chain/hub/hyper examples. |
+| `einsum_demo.py` | Einsum registry: network-style traces plus `ellipsis`, `batch`, `trace`, `ternary`, `unary`, `nway`, `implicit_out`. |
+| `run_all_examples.py` | Headless batch runner that calls `run_demo.py` and saves PNGs. |
+
+Useful launcher examples:
+
+```bash
+python examples/run_demo.py quimb hyper --view 2d
+python examples/run_demo.py tenpy chain --view 2d --save tenpy_chain.png --no-show
+python examples/run_demo.py einsum ellipsis --view 3d --from-list
+python examples/run_demo.py tensornetwork mera_ttn --view 2d --scheme
+```
+
+Catalog and CLI details: **[examples/README.md](examples/README.md)**.
 
 ## Backend notes
 
@@ -374,7 +404,7 @@ Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
 
 ```bash
 python -m pip install -e ".[quimb]"
-python examples/quimb_demo.py mps 2d --save quimb_mps.png --no-show
+python examples/run_demo.py quimb mps --view 2d --save quimb_mps.png --no-show
 python -m pytest
 ```
 
@@ -388,6 +418,7 @@ Expect `quimb_mps.png` and all tests passing.
 | `ValueError: Unsupported tensor network engine` / `view` | Use only listed `engine` / `view` literals (see above). |
 | 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. |
+| Saved figure includes the control panel | Pass `interactive_controls=False` when exporting a static figure from `show_tensor_network`. |
 | 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. |
 
@@ -398,7 +429,7 @@ Expect `quimb_mps.png` and all tests passing.
 - **[docs/guide.md](docs/guide.md)** — Installation, backends, `PlotConfig` recipes, layout/draw
   behavior, architecture, **extended troubleshooting**.
 - **[CHANGELOG.md](CHANGELOG.md)** — Release notes by version.
-- **[examples/README.md](examples/README.md)** — CLI examples per script.
+- **[examples/README.md](examples/README.md)** — launcher usage, engine/example matrix, and batch examples.
 - **[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md)**
 
 ## Support and contributing
@@ -410,9 +441,18 @@ Expect `quimb_mps.png` and all tests passing.
 ## Development
 
 ```bash
-python -m pip install -e ".[dev]"
-ruff check .
-ruff format .
-pyright
-pytest
+python -m venv .venv
+python -m pip install -r requirements.dev.txt
+```
+
+Windows:
+
+```powershell
+.\.venv\Scripts\python scripts\verify.py
+```
+
+Linux/macOS (with the venv activated):
+
+```bash
+python scripts/verify.py
 ```

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

@@ -15,8 +15,9 @@ PyTorch/NumPy `einsum` tensor networks.
 Tensor network libraries use different object models and rarely share a single visualization path.
 This package **normalizes** each backend into one graph description, **lays out** nodes (chains,
 grids, trees, planar embeddings, or force-directed fallback), and **draws** with Matplotlib in
-**2D** (filled disks) or **3D** (lightweight octahedra). There is no custom GUI: you get standard
-`Figure` and `Axes` objects for saving, composing subplots, and further styling.
+**2D** (filled disks) or **3D** (lightweight octahedra). The interactive layer stays inside
+standard Matplotlib figures: `show_tensor_network` can add a small control panel, while the return
+value is still a normal `Figure` plus `Axes` object that you can save, embed, or restyle.
 
 **Audience:** Researchers who work with tensor networks and want consistent, publication-friendly
 diagrams across Quimb, TeNPy, TensorNetwork, TensorKrowch, or traced `einsum` contraction graphs.
@@ -25,6 +26,8 @@ diagrams across Quimb, TeNPy, TensorNetwork, TensorKrowch, or traced `einsum` co
 
 PyPI package name: `tensor-network-visualization`. Import module: `tensor_network_viz`.
 
+**Requires Python 3.11 or newer.**
+
 ### Base install
 
 ```bash
@@ -99,13 +102,19 @@ Everything below maps to real parameters—there are no hidden mode switches.
 
 | Concept | Where | Meaning |
 |--------|--------|---------|
-| **View mode** | `show_tensor_network(..., view=...)` | `"2d"` — disk nodes; `"3d"` — octahedra. Same normalized graph. |
-| **Engine mode** | `engine=...` | Adapter: `"tensorkrowch"`, `"tensornetwork"`, `"quimb"`, `"tenpy"`, `"einsum"`. Invalid → `ValueError`. |
+| **View mode** | `show_tensor_network(..., view=...)` | Default is `"2d"`; `"3d"` is available from the same figure controls when widgets are enabled. |
+| **Engine mode** | `engine=...` | Optional override. When omitted, `show_tensor_network` auto-detects `"tensorkrowch"`, `"tensornetwork"`, `"quimb"`, `"tenpy"`, or `"einsum"` from the input. Invalid explicit values still raise `ValueError`. |
 | **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. |
-| **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`**. |
+| **Interactive controls** | `interactive_controls=True` | Figure-level Matplotlib widgets for view/hover/label toggles. Set `False` for clean static exports or headless batch rendering. |
+| **Label policy** | `PlotConfig` + overrides | Defaults: `show_tensor_labels=False`, `show_index_labels=False`. Per-call: `show_tensor_network(..., show_tensor_labels=..., show_index_labels=...)`. |
+| **Hover labels** | `PlotConfig(hover_labels=True)` | Default is `True`. Hover tooltips are independent from static labels, so both can stay enabled together in an interactive Matplotlib window. |
+| **Contraction scheme** | `PlotConfig(show_contraction_scheme=True)` | **Einsum:** cumulative per-step highlights from the trace. **Other engines:** set **`contraction_scheme_by_name`**. Compatible figures now add Matplotlib toggles for **Scheme**, **Playback**, and **Cost hover**; if you start with those flags off, the scheme bundle is computed lazily on first use. **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:** ordered `pair_tensor` / `einsum_trace_step` lists when you want a fully explicit trace. See **`examples/run_demo.py`** and **`examples/einsum_demo.py`**. |
+
+`show_tensor_network` now creates figure-level Matplotlib widgets by default: a `2d/3d` selector on
+figures it creates itself, plus `Hover`, `Tensor labels`, and `Edge labels` checkboxes. If you
+pass an external `ax`, the same-view checkboxes stay available but the `2d/3d` selector is hidden.
+The default widget state is `Hover=True`, `Tensor labels=False`, `Edge labels=False`.
 
 ## Minimal examples
 
@@ -128,13 +137,16 @@ network = qtn.TensorNetwork(tensors)
 fig, ax = show_tensor_network(
     network,
     engine="quimb",
-    view="2d",
     config=PlotConfig(figsize=(8, 6)),
+    interactive_controls=False,
     show=False,
 )
 fig.savefig("network.png", bbox_inches="tight")
 ```
 
+Use `interactive_controls=False` when you want the saved figure without the Matplotlib control
+panel.
+
 ### Quimb 3D, hide index labels on this call only
 
 ```python
@@ -154,12 +166,12 @@ fig, ax = show_tensor_network(
 fig, ax = show_tensor_network(
     network,
     engine="quimb",
-    view="2d",
     config=PlotConfig(figsize=(8, 6), hover_labels=True),
 )
 ```
 
-No effect for headless `show=False` without a GUI event loop; pair with an interactive backend
+Hover is independent from static labels, so you can also enable tensor or edge labels from the
+figure checkboxes without losing the hover tooltips. This still needs an interactive backend
 (e.g. `%matplotlib widget` in Jupyter).
 
 ### TeNPy finite MPS (sketch)
@@ -173,7 +185,6 @@ from tensor_network_viz import show_tensor_network, PlotConfig
 fig, ax = show_tensor_network(
     mps,
     engine="tenpy",
-    view="2d",
     config=PlotConfig(figsize=(8, 6)),
     show=False,
 )
@@ -185,25 +196,30 @@ fig, ax = show_tensor_network(
 show_tensor_network(
     network,
     *,
-    engine: EngineName,
-    view: ViewName,
+    engine: EngineName | None = None,
+    view: ViewName | None = None,
     config: PlotConfig | None = None,
+    ax: Axes | Axes3D | None = None,
     show_tensor_labels: bool | None = None,
     show_index_labels: bool | None = None,
+    interactive_controls: bool = True,
     show: bool = True,
 ) -> tuple[Figure, Axes | Axes3D]
 ```
 
 - **`network`:** Backend-native object or iterable (see [guide — supported inputs](docs/guide.md)).
-- **`engine`:** `"tensorkrowch"` \| `"tensornetwork"` \| `"quimb"` \| `"tenpy"` \| `"einsum"`.
-- **`view`:** `"2d"` \| `"3d"`.
+- **`engine`:** optional explicit override. If omitted, the backend is inferred from `network`.
+- **`view`:** `"2d"` \| `"3d"`; omitted means `"2d"` unless a 3D `ax` is passed.
 - **`config`:** Styling and layout; defaults to `PlotConfig()` if omitted.
+- **`ax`:** Optional Matplotlib axes. When present, rendering stays on that axes and the `2d/3d` selector is hidden.
 - **`show_tensor_labels` / `show_index_labels`:** If `None`, use values from `config`; else override for this call only.
+- **`interactive_controls`:** If `True`, attach the view/hover/label widgets when the figure supports them. Set `False` for a static render.
 - **`show`:** Whether to push the figure to the current UI (`display`/`show`).
 - **Returns:** `(fig, ax)` for titles, `savefig`, colorbars, or embedding in a subplot.
 
 Backend-specific shortcuts (same renderer core) accept **`ax=`** and **`seed=`** for subplots and
-reproducible layout; see the [guide](docs/guide.md).
+reproducible layout; they stay fixed-dimension helpers (`plot_*_network_2d` or `plot_*_network_3d`)
+and do not add the `2d/3d` selector. See the [guide](docs/guide.md).
 
 ### `PlotConfig` quick reference
 
@@ -221,8 +237,8 @@ Numeric fields with **`None`** use the corresponding `DEFAULT_*` on the class (s
 | `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. |
+| `show_tensor_labels` | `False` | Draw tensor names on nodes. |
+| `show_index_labels` | `False` | Draw axis names on bonds / stubs. |
 | `node_radius` | `None` | → `0.08` data units (scaled with layout; multiplies geometric radius). |
 | `stub_length` | `None` | → `0.16` (dangling stub length scale). |
 | `self_loop_radius` | `None` | → `0.2` (self-contraction loops). |
@@ -232,7 +248,7 @@ Numeric fields with **`None`** use the corresponding `DEFAULT_*` on the class (s
 | `positions` | `None` | `dict[int, tuple[float, ...]]` — custom positions keyed by **normalized node id** (`id` of adapter node); partial dicts get layout for missing ids. |
 | `validate_positions` | `False` | If `True`, warn on unknown keys or short coordinates vs `view`. |
 | `refine_tensor_labels` | `True` | Extra passes to fit tensor names inside the node marker (2D or 3D); set `False` for speed. |
-| `hover_labels` | `False` | Hide labels until hover (interactive only). |
+| `hover_labels` | `True` | Enable hover tooltips independently from static labels (interactive only). |
 
 Defaults `0.08`, `0.16`, `0.2`, `0.85`, `0.75`, `220` are also available as
 `PlotConfig.DEFAULT_NODE_RADIUS`, `DEFAULT_STUB_LENGTH`, `DEFAULT_SELF_LOOP_RADIUS`,
@@ -288,23 +304,35 @@ Details, subgraph behavior, and Quimb hyperindex hubs are in **[docs/guide.md](d
 
 ## Example scripts
 
-Runnable demos live under **`examples/`**. From the repo root with the right extra installed:
+Runnable demos live under **`examples/`** and now share one public launcher:
+
+```bash
+python examples/run_demo.py <engine> <example> [options]
+```
 
-| Script | Purpose |
+Main files:
+
+| File | Purpose |
 |--------|---------|
-| `demo_cli.py` | Shared helpers (`--hover-labels` → `PlotConfig(hover_labels=True)`); imported by demos. |
-| `tensorkrowch_demo.py` | MPS, MPO, PEPS, weird, disconnected; `--from-list` subset. |
-| `tensornetwork_demo.py` | Same topologies with `tensornetwork.Node`. |
-| `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` | 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)**.
+| `run_demo.py` | Public CLI entry point for every engine and example. |
+| `demo_cli.py` | Shared typed helpers for parsing, save paths, plot config, and topology builders. |
+| `tensorkrowch_demo.py` | TensorKrowch registry: MPS/TT, MPO, ladder, PEPS, cubic PEPS, MERA, MERA+TTN, weird, disconnected. |
+| `tensornetwork_demo.py` | TensorNetwork registry with the same structured graph examples. |
+| `quimb_demo.py` | Quimb registry with the same graph family plus a native hypergraph example. |
+| `tenpy_demo.py` | TeNPy registry: native MPS/MPO/iMPS/iMPO/purification/uniform/excitation plus explicit chain/hub/hyper examples. |
+| `einsum_demo.py` | Einsum registry: network-style traces plus `ellipsis`, `batch`, `trace`, `ternary`, `unary`, `nway`, `implicit_out`. |
+| `run_all_examples.py` | Headless batch runner that calls `run_demo.py` and saves PNGs. |
+
+Useful launcher examples:
+
+```bash
+python examples/run_demo.py quimb hyper --view 2d
+python examples/run_demo.py tenpy chain --view 2d --save tenpy_chain.png --no-show
+python examples/run_demo.py einsum ellipsis --view 3d --from-list
+python examples/run_demo.py tensornetwork mera_ttn --view 2d --scheme
+```
+
+Catalog and CLI details: **[examples/README.md](examples/README.md)**.
 
 ## Backend notes
 
@@ -325,7 +353,7 @@ Catalog and one-liner commands: **[examples/README.md](examples/README.md)**.
 
 ```bash
 python -m pip install -e ".[quimb]"
-python examples/quimb_demo.py mps 2d --save quimb_mps.png --no-show
+python examples/run_demo.py quimb mps --view 2d --save quimb_mps.png --no-show
 python -m pytest
 ```
 
@@ -339,6 +367,7 @@ Expect `quimb_mps.png` and all tests passing.
 | `ValueError: Unsupported tensor network engine` / `view` | Use only listed `engine` / `view` literals (see above). |
 | 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. |
+| Saved figure includes the control panel | Pass `interactive_controls=False` when exporting a static figure from `show_tensor_network`. |
 | 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. |
 
@@ -349,7 +378,7 @@ Expect `quimb_mps.png` and all tests passing.
 - **[docs/guide.md](docs/guide.md)** — Installation, backends, `PlotConfig` recipes, layout/draw
   behavior, architecture, **extended troubleshooting**.
 - **[CHANGELOG.md](CHANGELOG.md)** — Release notes by version.
-- **[examples/README.md](examples/README.md)** — CLI examples per script.
+- **[examples/README.md](examples/README.md)** — launcher usage, engine/example matrix, and batch examples.
 - **[THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md)**
 
 ## Support and contributing
@@ -361,9 +390,18 @@ Expect `quimb_mps.png` and all tests passing.
 ## Development
 
 ```bash
-python -m pip install -e ".[dev]"
-ruff check .
-ruff format .
-pyright
-pytest
+python -m venv .venv
+python -m pip install -r requirements.dev.txt
+```
+
+Windows:
+
+```powershell
+.\.venv\Scripts\python scripts\verify.py
+```
+
+Linux/macOS (with the venv activated):
+
+```bash
+python scripts/verify.py
 ```

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

@@ -1,15 +1,16 @@
 [build-system]
-requires = ["setuptools>=68"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "tensor-network-visualization"
-version = "1.4.2"
+version = "1.5.0"
 description = "Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks."
 authors = [{ name = "Alejandro Mata Ali" }]
 readme = "README.md"
-license = { text = "MIT" }
-requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
 keywords = ["tensor-network", "visualization", "pytorch", "numpy", "tensorkrowch", "tensornetwork", "quimb", "tenpy", "einsum", "quantum-inspired", "matplotlib"]
 dependencies = [
     "matplotlib>=3.7",
@@ -17,9 +18,11 @@ dependencies = [
     "numpy",
 ]
 classifiers = [
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Visualization",
 ]
 
@@ -31,7 +34,17 @@ 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", "tomli>=2.0.1", "tensorkrowch", "tensornetwork", "quimb", "physics-tenpy"]
+dev = [
+    "build",
+    "pytest",
+    "ruff",
+    "pyright",
+    "ipython",
+    "tensorkrowch",
+    "tensornetwork",
+    "quimb",
+    "physics-tenpy",
+]
 jupyter = ["ipympl>=0.9.0", "ipywidgets>=8.0", "jupyterlab>=4.0", "notebook>=7.0"]
 tensorkrowch = ["tensorkrowch"]
 tensornetwork = ["tensornetwork"]
@@ -52,7 +65,7 @@ pythonpath = ["src"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py311"
 src = ["src", "tests"]
 exclude = [".venv", ".tmp", ".tmp_venv_*", ".pip_tmp", ".pytest_cache", ".ruff_cache", "pytest-cache-files-*", "tn_tsp.py"]