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

{tensor_network_visualization-1.4.0/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.0
+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
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://github.com/DOKOS-TAYOS/Tensor-Network-Visual
 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,tensorkrowch,tensornetwork,quimb,tenpy,matplotlib
+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
@@ -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)
@@ -361,7 +388,8 @@ 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. |
-| Huge graphs are slow | `PlotConfig(refine_tensor_labels=False)`; optionally set `layout_iterations` explicitly. |
+| 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).