tensor-network-visualization 1.5.3__tar.gz → 1.5.4__tar.gz

{tensor_network_visualization-1.5.3 → tensor_network_visualization-1.5.4}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Alejandro Mata Ali
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Alejandro Mata Ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{tensor_network_visualization-1.5.3/src/tensor_network_visualization.egg-info → tensor_network_visualization-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensor-network-visualization
-Version: 1.5.3
+Version: 1.5.4
 Summary: Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks.
 Author: Alejandro Mata Ali
 License-Expression: MIT
@@ -63,12 +63,15 @@ PyTorch/NumPy `einsum` tensor networks.
 
 ## What This Library Does
 
-Tensor-network libraries expose very different Python objects, but this package gives them two
-aligned plotting entry points:
+Tensor-network libraries expose very different Python objects, but this package gives them aligned
+inspection and export entry points:
 
 ```python
 fig, ax = show_tensor_network(...)
 fig, ax = show_tensor_elements(...)
+fig, ax = show_tensor_comparison(...)
+graph = normalize_tensor_network(...)
+snapshot = export_tensor_network_snapshot(...)
 ```
 
 Internally, the library:
@@ -79,7 +82,7 @@ Internally, the library:
 4. optionally adds figure controls for view/label/scheme toggles.
 
 The goal is to keep the public API small while still being useful for notebooks, papers, debugging,
-and saved figures.
+saved figures, and external tooling that wants the backend-normalized graph model.
 
 ## Install
 
@@ -211,9 +214,10 @@ When several tensors are present, the figure keeps one tensor active at a time a
 to switch between them. The interactive controls are grouped: `basic` (`elements`, `magnitude`,
 `log_magnitude`, `distribution`, `data`), `complex` (`real`, `imag`, `phase`), and
 `diagnostic` (`sign`, `signed_value`, `sparsity`, `nan_inf`, `singular_values`, `eigen_real`,
-`eigen_imag`).
+`eigen_imag`), plus `analysis` (`slice`, `reduce`, `profiles`).
 
-- `data`: single tensor, iterable of tensors, supported backend-native tensor collections, or an
+- `data`: direct numeric tensor input (for example a NumPy array), direct iterables of tensors
+  preserving order and duplicates, supported backend-native tensor collections, or an
   `EinsumTrace` with live tensor values.
 - `engine`: optional backend override. If omitted, the library auto-detects it.
 - `config`: tensor-inspection behavior lives here.
@@ -228,12 +232,57 @@ to switch between them. The interactive controls are grouped: `basic` (`elements
   tensor slider.
 - `show`: if `False`, nothing is displayed automatically.
 
+### `show_tensor_comparison`
+
+Use `show_tensor_comparison` to compare one tensor against one reference tensor:
+
+```python
+show_tensor_comparison(
+    data,
+    reference,
+    *,
+    engine=None,
+    config=None,
+    comparison_config=None,
+    ax=None,
+    show_controls=True,
+    show=True,
+)
+```
+
+- `config`: still uses `TensorElementsConfig(...)` for matrixization and rendering style.
+- `comparison_config`: uses `TensorComparisonConfig(...)` for comparison-specific behavior.
+- comparison modes are `reference`, `abs_diff`, `relative_diff`, `ratio`, `sign_change`,
+  `phase_change`, and `topk_changes`.
+
+### Normalized snapshots
+
+Use the snapshot helpers when you want the backend-normalized graph and layout without touching any
+backend adapter internals:
+
+```python
+graph = normalize_tensor_network(network, engine=None)
+snapshot = export_tensor_network_snapshot(
+    network,
+    engine=None,
+    view="2d",
+    config=PlotConfig(),
+    seed=0,
+)
+```
+
+Both snapshot objects are immutable and expose `.to_dict()` for serialization.
+
 ### `PlotConfig`
 
 Use `PlotConfig` for visual behavior:
 
 ```python
-from tensor_network_viz import PlotConfig
+from tensor_network_viz import (
+    PlotConfig,
+    TensorNetworkDiagnosticsConfig,
+    TensorNetworkFocus,
+)
 
 config = PlotConfig(
     show_nodes=True,
@@ -243,6 +292,15 @@ config = PlotConfig(
     show_contraction_scheme=False,
     contraction_scheme_cost_hover=False,
     contraction_tensor_inspector=False,
+    diagnostics=TensorNetworkDiagnosticsConfig(
+        show_overlay=False,
+        include_hover=True,
+    ),
+    focus=TensorNetworkFocus(
+        kind="neighborhood",
+        center="A",
+        radius=1,
+    ),
     tensor_label_refinement="auto",
     tensor_label_fontsize=None,
     edge_label_fontsize=None,
@@ -253,6 +311,8 @@ This is where you configure:
 
 - labels,
 - hover tooltips,
+- diagnostics overlays and enriched hover payloads (`shape`, `dtype`, `bond dimension`, memory),
+- reproducible subnetwork focus (`neighborhood` radius 1/2 or shortest `path` by tensor name),
 - contraction-scheme overlays,
 - optional tensor/edge label font-size overrides,
 - styling,
@@ -266,12 +326,20 @@ This is where you configure:
 Use `TensorElementsConfig` for tensor inspection behavior:
 
 ```python
-from tensor_network_viz import TensorElementsConfig
+from tensor_network_viz import TensorAnalysisConfig, TensorElementsConfig
 
 config = TensorElementsConfig(
     mode="auto",
     row_axes=None,
     col_axes=None,
+    analysis=TensorAnalysisConfig(
+        slice_axis="phys",
+        slice_index=0,
+        reduce_axes=("bond",),
+        reduce_method="mean",
+        profile_axis="phys",
+        profile_method="norm",
+    ),
     figsize=(7.2, 6.4),
     max_matrix_shape=(256, 256),
     shared_color_scale=False,
@@ -290,6 +358,7 @@ This is where you configure:
 
 - the active inspection mode,
 - row/column axis grouping for rank > 2 tensors,
+- analysis selectors for `slice`, `reduce`, and `profiles`,
 - heatmap downsampling limits,
 - histogram sampling and bin count,
 - data-summary depth (`topk_count`),
@@ -299,15 +368,27 @@ This is where you configure:
 
 If you want to start in a specific grouped view, pass `mode="real"`, `mode="imag"`,
 `mode="phase"`, `mode="log_magnitude"`, `mode="sparsity"`, `mode="nan_inf"`, `mode="sign"`,
-`mode="signed_value"`, `mode="singular_values"`, `mode="eigen_real"`, or `mode="eigen_imag"` directly in
-`TensorElementsConfig(...)`.
+`mode="signed_value"`, `mode="singular_values"`, `mode="eigen_real"`, `mode="eigen_imag"`,
+`mode="slice"`, `mode="reduce"`, or `mode="profiles"` directly in `TensorElementsConfig(...)`.
+
+For the analytical views, keep this mental model:
+
+- `slice` fixes one axis at one index and removes that axis from the result.
+- `reduce` collapses the checked axes with `mean` or `norm`, so you see the axes that were not
+  checked.
+- `profiles` keeps one axis as a 1D curve and reduces the other surviving axes.
 
 ## Most Common Workflows
 
 ### Interactive figure with controls
 
 ```python
-from tensor_network_viz import PlotConfig, show_tensor_network
+from tensor_network_viz import (
+    PlotConfig,
+    TensorNetworkDiagnosticsConfig,
+    TensorNetworkFocus,
+    show_tensor_network,
+)
 
 fig, ax = show_tensor_network(
     network,
@@ -315,10 +396,17 @@ fig, ax = show_tensor_network(
         show_tensor_labels=False,
         show_index_labels=False,
         hover_labels=True,
+        diagnostics=TensorNetworkDiagnosticsConfig(show_overlay=True),
+        focus=TensorNetworkFocus(kind="neighborhood", center="A", radius=1),
     ),
 )
 ```
 
+When the network exposes inspectable tensor values, clicking a visible tensor node opens the shared
+auxiliary inspector directly. In playback-enabled traces, the same inspector can still follow the
+current contraction result or stay pinned to a manually selected node until you click empty space
+to clear the manual selection.
+
 ### Clean export with no embedded controls
 
 ```python
@@ -339,16 +427,71 @@ fig.savefig("network.png", bbox_inches="tight")
 ### Inspect tensor values
 
 ```python
-from tensor_network_viz import TensorElementsConfig, show_tensor_elements
+from tensor_network_viz import TensorAnalysisConfig, TensorElementsConfig, show_tensor_elements
 
 fig, ax = show_tensor_elements(
     trace,
-    config=TensorElementsConfig(mode="auto"),
+    config=TensorElementsConfig(
+        mode="profiles",
+        analysis=TensorAnalysisConfig(profile_axis="phys", profile_method="norm"),
+    ),
     show=False,
 )
 fig.savefig("tensor-elements.png", bbox_inches="tight")
 ```
 
+### Export a focused snapshot with diagnostics
+
+```python
+from tensor_network_viz import (
+    PlotConfig,
+    TensorNetworkDiagnosticsConfig,
+    TensorNetworkFocus,
+    export_tensor_network_snapshot,
+)
+
+snapshot = export_tensor_network_snapshot(
+    network,
+    config=PlotConfig(
+        diagnostics=TensorNetworkDiagnosticsConfig(include_hover=True),
+        focus=TensorNetworkFocus(kind="path", endpoints=("A", "C")),
+    ),
+)
+payload = snapshot.to_dict()
+```
+
+### Compare tensors
+
+```python
+from tensor_network_viz import (
+    TensorComparisonConfig,
+    TensorElementsConfig,
+    show_tensor_comparison,
+)
+
+fig, ax = show_tensor_comparison(
+    current_tensor,
+    reference_tensor,
+    config=TensorElementsConfig(mode="elements"),
+    comparison_config=TensorComparisonConfig(mode="abs_diff"),
+    show=False,
+)
+fig.savefig("tensor-comparison.png", bbox_inches="tight")
+```
+
+### Export a normalized snapshot
+
+```python
+from tensor_network_viz import PlotConfig, export_tensor_network_snapshot
+
+snapshot = export_tensor_network_snapshot(
+    network,
+    config=PlotConfig(),
+    view="2d",
+)
+payload = snapshot.to_dict()
+```
+
 ### Faster render for large graphs
 
 ```python
@@ -465,6 +608,7 @@ For fuller backend examples, see [docs/backends.md](docs/backends.md).
 | `hover_labels` | Enable hover tooltips in interactive sessions. |
 | `show_contraction_scheme` | Enable the dynamic contraction slider with real node shape/color changes. |
 | `contraction_scheme_cost_hover` | Show contraction details in the slider panel. |
+| `contraction_tensor_inspector` | Enable the auxiliary tensor inspector with direct node selection and comparison controls. |
 | `tensor_label_refinement` | `"auto"`, `"always"`, or `"never"` for the expensive label-fit pass. |
 | `layout_iterations` | Force-layout effort. |
 | `positions` | Supply custom node coordinates. |

{tensor_network_visualization-1.5.3 → tensor_network_visualization-1.5.4}/README.md

@@ -12,12 +12,15 @@ PyTorch/NumPy `einsum` tensor networks.
 
 ## What This Library Does
 
-Tensor-network libraries expose very different Python objects, but this package gives them two
-aligned plotting entry points:
+Tensor-network libraries expose very different Python objects, but this package gives them aligned
+inspection and export entry points:
 
 ```python
 fig, ax = show_tensor_network(...)
 fig, ax = show_tensor_elements(...)
+fig, ax = show_tensor_comparison(...)
+graph = normalize_tensor_network(...)
+snapshot = export_tensor_network_snapshot(...)
 ```
 
 Internally, the library:
@@ -28,7 +31,7 @@ Internally, the library:
 4. optionally adds figure controls for view/label/scheme toggles.
 
 The goal is to keep the public API small while still being useful for notebooks, papers, debugging,
-and saved figures.
+saved figures, and external tooling that wants the backend-normalized graph model.
 
 ## Install
 
@@ -160,9 +163,10 @@ When several tensors are present, the figure keeps one tensor active at a time a
 to switch between them. The interactive controls are grouped: `basic` (`elements`, `magnitude`,
 `log_magnitude`, `distribution`, `data`), `complex` (`real`, `imag`, `phase`), and
 `diagnostic` (`sign`, `signed_value`, `sparsity`, `nan_inf`, `singular_values`, `eigen_real`,
-`eigen_imag`).
+`eigen_imag`), plus `analysis` (`slice`, `reduce`, `profiles`).
 
-- `data`: single tensor, iterable of tensors, supported backend-native tensor collections, or an
+- `data`: direct numeric tensor input (for example a NumPy array), direct iterables of tensors
+  preserving order and duplicates, supported backend-native tensor collections, or an
   `EinsumTrace` with live tensor values.
 - `engine`: optional backend override. If omitted, the library auto-detects it.
 - `config`: tensor-inspection behavior lives here.
@@ -177,12 +181,57 @@ to switch between them. The interactive controls are grouped: `basic` (`elements
   tensor slider.
 - `show`: if `False`, nothing is displayed automatically.
 
+### `show_tensor_comparison`
+
+Use `show_tensor_comparison` to compare one tensor against one reference tensor:
+
+```python
+show_tensor_comparison(
+    data,
+    reference,
+    *,
+    engine=None,
+    config=None,
+    comparison_config=None,
+    ax=None,
+    show_controls=True,
+    show=True,
+)
+```
+
+- `config`: still uses `TensorElementsConfig(...)` for matrixization and rendering style.
+- `comparison_config`: uses `TensorComparisonConfig(...)` for comparison-specific behavior.
+- comparison modes are `reference`, `abs_diff`, `relative_diff`, `ratio`, `sign_change`,
+  `phase_change`, and `topk_changes`.
+
+### Normalized snapshots
+
+Use the snapshot helpers when you want the backend-normalized graph and layout without touching any
+backend adapter internals:
+
+```python
+graph = normalize_tensor_network(network, engine=None)
+snapshot = export_tensor_network_snapshot(
+    network,
+    engine=None,
+    view="2d",
+    config=PlotConfig(),
+    seed=0,
+)
+```
+
+Both snapshot objects are immutable and expose `.to_dict()` for serialization.
+
 ### `PlotConfig`
 
 Use `PlotConfig` for visual behavior:
 
 ```python
-from tensor_network_viz import PlotConfig
+from tensor_network_viz import (
+    PlotConfig,
+    TensorNetworkDiagnosticsConfig,
+    TensorNetworkFocus,
+)
 
 config = PlotConfig(
     show_nodes=True,
@@ -192,6 +241,15 @@ config = PlotConfig(
     show_contraction_scheme=False,
     contraction_scheme_cost_hover=False,
     contraction_tensor_inspector=False,
+    diagnostics=TensorNetworkDiagnosticsConfig(
+        show_overlay=False,
+        include_hover=True,
+    ),
+    focus=TensorNetworkFocus(
+        kind="neighborhood",
+        center="A",
+        radius=1,
+    ),
     tensor_label_refinement="auto",
     tensor_label_fontsize=None,
     edge_label_fontsize=None,
@@ -202,6 +260,8 @@ This is where you configure:
 
 - labels,
 - hover tooltips,
+- diagnostics overlays and enriched hover payloads (`shape`, `dtype`, `bond dimension`, memory),
+- reproducible subnetwork focus (`neighborhood` radius 1/2 or shortest `path` by tensor name),
 - contraction-scheme overlays,
 - optional tensor/edge label font-size overrides,
 - styling,
@@ -215,12 +275,20 @@ This is where you configure:
 Use `TensorElementsConfig` for tensor inspection behavior:
 
 ```python
-from tensor_network_viz import TensorElementsConfig
+from tensor_network_viz import TensorAnalysisConfig, TensorElementsConfig
 
 config = TensorElementsConfig(
     mode="auto",
     row_axes=None,
     col_axes=None,
+    analysis=TensorAnalysisConfig(
+        slice_axis="phys",
+        slice_index=0,
+        reduce_axes=("bond",),
+        reduce_method="mean",
+        profile_axis="phys",
+        profile_method="norm",
+    ),
     figsize=(7.2, 6.4),
     max_matrix_shape=(256, 256),
     shared_color_scale=False,
@@ -239,6 +307,7 @@ This is where you configure:
 
 - the active inspection mode,
 - row/column axis grouping for rank > 2 tensors,
+- analysis selectors for `slice`, `reduce`, and `profiles`,
 - heatmap downsampling limits,
 - histogram sampling and bin count,
 - data-summary depth (`topk_count`),
@@ -248,15 +317,27 @@ This is where you configure:
 
 If you want to start in a specific grouped view, pass `mode="real"`, `mode="imag"`,
 `mode="phase"`, `mode="log_magnitude"`, `mode="sparsity"`, `mode="nan_inf"`, `mode="sign"`,
-`mode="signed_value"`, `mode="singular_values"`, `mode="eigen_real"`, or `mode="eigen_imag"` directly in
-`TensorElementsConfig(...)`.
+`mode="signed_value"`, `mode="singular_values"`, `mode="eigen_real"`, `mode="eigen_imag"`,
+`mode="slice"`, `mode="reduce"`, or `mode="profiles"` directly in `TensorElementsConfig(...)`.
+
+For the analytical views, keep this mental model:
+
+- `slice` fixes one axis at one index and removes that axis from the result.
+- `reduce` collapses the checked axes with `mean` or `norm`, so you see the axes that were not
+  checked.
+- `profiles` keeps one axis as a 1D curve and reduces the other surviving axes.
 
 ## Most Common Workflows
 
 ### Interactive figure with controls
 
 ```python
-from tensor_network_viz import PlotConfig, show_tensor_network
+from tensor_network_viz import (
+    PlotConfig,
+    TensorNetworkDiagnosticsConfig,
+    TensorNetworkFocus,
+    show_tensor_network,
+)
 
 fig, ax = show_tensor_network(
     network,
@@ -264,10 +345,17 @@ fig, ax = show_tensor_network(
         show_tensor_labels=False,
         show_index_labels=False,
         hover_labels=True,
+        diagnostics=TensorNetworkDiagnosticsConfig(show_overlay=True),
+        focus=TensorNetworkFocus(kind="neighborhood", center="A", radius=1),
     ),
 )
 ```
 
+When the network exposes inspectable tensor values, clicking a visible tensor node opens the shared
+auxiliary inspector directly. In playback-enabled traces, the same inspector can still follow the
+current contraction result or stay pinned to a manually selected node until you click empty space
+to clear the manual selection.
+
 ### Clean export with no embedded controls
 
 ```python
@@ -288,16 +376,71 @@ fig.savefig("network.png", bbox_inches="tight")
 ### Inspect tensor values
 
 ```python
-from tensor_network_viz import TensorElementsConfig, show_tensor_elements
+from tensor_network_viz import TensorAnalysisConfig, TensorElementsConfig, show_tensor_elements
 
 fig, ax = show_tensor_elements(
     trace,
-    config=TensorElementsConfig(mode="auto"),
+    config=TensorElementsConfig(
+        mode="profiles",
+        analysis=TensorAnalysisConfig(profile_axis="phys", profile_method="norm"),
+    ),
     show=False,
 )
 fig.savefig("tensor-elements.png", bbox_inches="tight")
 ```
 
+### Export a focused snapshot with diagnostics
+
+```python
+from tensor_network_viz import (
+    PlotConfig,
+    TensorNetworkDiagnosticsConfig,
+    TensorNetworkFocus,
+    export_tensor_network_snapshot,
+)
+
+snapshot = export_tensor_network_snapshot(
+    network,
+    config=PlotConfig(
+        diagnostics=TensorNetworkDiagnosticsConfig(include_hover=True),
+        focus=TensorNetworkFocus(kind="path", endpoints=("A", "C")),
+    ),
+)
+payload = snapshot.to_dict()
+```
+
+### Compare tensors
+
+```python
+from tensor_network_viz import (
+    TensorComparisonConfig,
+    TensorElementsConfig,
+    show_tensor_comparison,
+)
+
+fig, ax = show_tensor_comparison(
+    current_tensor,
+    reference_tensor,
+    config=TensorElementsConfig(mode="elements"),
+    comparison_config=TensorComparisonConfig(mode="abs_diff"),
+    show=False,
+)
+fig.savefig("tensor-comparison.png", bbox_inches="tight")
+```
+
+### Export a normalized snapshot
+
+```python
+from tensor_network_viz import PlotConfig, export_tensor_network_snapshot
+
+snapshot = export_tensor_network_snapshot(
+    network,
+    config=PlotConfig(),
+    view="2d",
+)
+payload = snapshot.to_dict()
+```
+
 ### Faster render for large graphs
 
 ```python
@@ -414,6 +557,7 @@ For fuller backend examples, see [docs/backends.md](docs/backends.md).
 | `hover_labels` | Enable hover tooltips in interactive sessions. |
 | `show_contraction_scheme` | Enable the dynamic contraction slider with real node shape/color changes. |
 | `contraction_scheme_cost_hover` | Show contraction details in the slider panel. |
+| `contraction_tensor_inspector` | Enable the auxiliary tensor inspector with direct node selection and comparison controls. |
 | `tensor_label_refinement` | `"auto"`, `"always"`, or `"never"` for the expensive label-fit pass. |
 | `layout_iterations` | Force-layout effort. |
 | `positions` | Supply custom node coordinates. |

{tensor_network_visualization-1.5.3 → tensor_network_visualization-1.5.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tensor-network-visualization"
-version = "1.5.3"
+version = "1.5.4"
 description = "Minimal Matplotlib visualizations for TensorKrowch, TensorNetwork, Quimb, TeNPy, and traced PyTorch/NumPy einsum tensor networks."
 authors = [{ name = "Alejandro Mata Ali" }]
 readme = "README.md"