feat: add tensor element viewer

Author: DOKOS-TAYOS

README.md

@@ -12,11 +12,12 @@ PyTorch/NumPy `einsum` tensor networks.
 
 ## What This Library Does
 
-Tensor-network libraries expose very different Python objects, but this package gives them one
-common plotting entry point:
+Tensor-network libraries expose very different Python objects, but this package gives them two
+aligned plotting entry points:
 
 ```python
 fig, ax = show_tensor_network(...)
+fig, ax = show_tensor_elements(...)
 ```
 
 Internally, the library:
@@ -101,6 +102,35 @@ show_tensor_network(
 - `show_controls`: if `False`, the figure is saved/rendered without the embedded control panel.
 - `show`: if `False`, nothing is displayed automatically.
 
+### `show_tensor_elements`
+
+Use `show_tensor_elements` to inspect tensor values:
+
+```python
+show_tensor_elements(
+    data,
+    *,
+    engine=None,
+    config=None,
+    ax=None,
+    show_controls=True,
+    show=True,
+)
+```
+
+When several tensors are present, the figure keeps one tensor active at a time and uses a slider
+to switch between them. The interactive controls are grouped: `basic` (`elements`, `magnitude`,
+`distribution`, `data`), `complex` (`real`, `imag`, `phase`), and `diagnostic` (`sign`,
+`signed_value`).
+
+- `data`: single tensor, iterable of tensors, 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.
+- `ax`: render a single tensor into an existing Matplotlib axis.
+- `show_controls`: if `True`, add compact Matplotlib `group + mode` controls and, when needed, a tensor slider.
+- `show`: if `False`, nothing is displayed automatically.
+
 ### `PlotConfig`
 
 Use `PlotConfig` for visual behavior:
@@ -128,6 +158,31 @@ This is where you configure:
 - label-refinement policy,
 - static/export-oriented rendering choices.
 
+### `TensorElementsConfig`
+
+Use `TensorElementsConfig` for tensor inspection behavior:
+
+```python
+from tensor_network_viz import TensorElementsConfig
+
+config = TensorElementsConfig(
+    mode="auto",
+    max_matrix_shape=(256, 256),
+    histogram_bins=40,
+)
+```
+
+This is where you configure:
+
+- the active inspection mode,
+- row/column axis grouping for rank > 2 tensors,
+- heatmap downsampling limits,
+- histogram sampling and bin count.
+
+If you want to start in a specific grouped view, pass `mode="real"`, `mode="imag"`,
+`mode="phase"`, `mode="sign"`, or `mode="signed_value"` directly in
+`TensorElementsConfig(...)`.
+
 ## Most Common Workflows
 
 ### Interactive figure with controls
@@ -162,6 +217,19 @@ fig, ax = show_tensor_network(
 fig.savefig("network.png", bbox_inches="tight")
 ```
 
+### Inspect tensor values
+
+```python
+from tensor_network_viz import TensorElementsConfig, show_tensor_elements
+
+fig, ax = show_tensor_elements(
+    trace,
+    config=TensorElementsConfig(mode="auto"),
+    show=False,
+)
+fig.savefig("tensor-elements.png", bbox_inches="tight")
+```
+
 ### Faster render for large graphs
 
 ```python
@@ -302,6 +370,12 @@ python examples/run_demo.py einsum ellipsis --view 3d --scheme
 
 More details: [examples/README.md](examples/README.md)
 
+There is also a minimal inspection example that only uses base dependencies:
+
+```bash
+python examples/tensor_elements_demo.py
+```
+
 ## Troubleshooting
 
 | Symptom | What to try |
@@ -310,13 +384,17 @@ More details: [examples/README.md](examples/README.md)
 | Hover tooltips do nothing | Use an interactive Matplotlib backend; hover is not useful for PNG-only runs. |
 | Big graphs are slow | Set `tensor_label_refinement="never"`, reduce `layout_iterations`, or pass `positions`. |
 | `Unsupported tensor network engine` | Install the matching extra or pass the correct backend object. |
+| `show_tensor_elements(...)` fails on TensorKrowch nodes | Materialize the node tensors first; shape-only nodes do not expose element values. |
+| `show_tensor_elements(...)` fails on manual `pair_tensor(...)` lists | Use an `EinsumTrace` with live tensors instead; manual trace steps only describe contractions. |
 | Blank / duplicate Jupyter figure | Assign `fig, ax = show_tensor_network(...)` instead of leaving the tuple as the last line. |
 
 ## Documentation Map
 
 - [docs/guide.md](docs/guide.md): workflow-oriented guide to the public API.
 - [docs/backends.md](docs/backends.md): copy-paste backend-specific examples.
 - [examples/README.md](examples/README.md): demo launcher and batch-render usage.
+- [examples/tensor_elements_demo.py](examples/tensor_elements_demo.py): minimal tensor inspection
+  example.
 - [CHANGELOG.md](CHANGELOG.md): release notes.
 
 ## Development

docs/backends.md

@@ -2,6 +2,29 @@
 
 This page collects copy-paste examples for each supported backend.
 
+## Tensor Inspection
+
+### Base-dependency example with `EinsumTrace`
+
+```python
+import numpy as np
+from tensor_network_viz import EinsumTrace, TensorElementsConfig, einsum, show_tensor_elements
+
+trace = EinsumTrace()
+a = np.arange(6, dtype=float).reshape(2, 3)
+x = np.array([1.0, -0.5, 0.25], dtype=float)
+trace.bind("A", a)
+trace.bind("x", x)
+r0 = einsum("ab,b->a", a, x, trace=trace, backend="numpy")
+
+fig, ax = show_tensor_elements(
+    trace,
+    config=TensorElementsConfig(mode="auto"),
+    show=False,
+)
+fig.savefig("tensor-elements.png", bbox_inches="tight")
+```
+
 ## TensorKrowch
 
 ```python
@@ -144,6 +167,13 @@ fig, ax = show_tensor_network(
 ## Notes
 
 - You can often omit `engine=...` because `show_tensor_network` auto-detects the backend.
+- `show_tensor_elements(...)` auto-detects the same backends, but it needs real tensor values.
 - Use `show_controls=False` when you want a clean saved figure with no embedded buttons/sliders.
 - Use `PlotConfig(...)` for labels, hover behavior, contraction schemes, and performance-related
   rendering choices.
+- Use `TensorElementsConfig(...)` for tensor-view mode, matrix grouping, and downsampling choices.
+- When multiple tensors are present, `show_tensor_elements(...)` shows one tensor at a time and
+  adds a slider to move between them. Interactive views are grouped into `basic`, `complex`, and
+  `diagnostic`, with diagnostic modes `sign` and `signed_value`.
+- TensorKrowch shape-only nodes and manual `pair_tensor(...)` lists are intentionally unsupported
+  for `show_tensor_elements(...)` because they do not expose inspectable tensor values.

docs/guide.md

@@ -4,15 +4,18 @@ This guide is organized around user workflows instead of internal implementation
 
 ## Core Idea
 
-The public API is intentionally split into two responsibilities:
+The public API is intentionally split into four responsibilities:
 
 - `show_tensor_network(...)` manages the figure lifecycle.
-- `PlotConfig(...)` manages how the network should look and behave.
+- `show_tensor_elements(...)` manages tensor element inspection figures.
+- `PlotConfig(...)` manages how tensor networks should look and behave.
+- `TensorElementsConfig(...)` manages how tensor inspection should look and behave.
 
 If you remember only one thing, remember this:
 
 ```python
 fig, ax = show_tensor_network(network, config=PlotConfig(...))
+fig, ax = show_tensor_elements(data, config=TensorElementsConfig(...))
 ```
 
 ## Public API
@@ -30,6 +33,18 @@ show_tensor_network(
 )
 ```
 
+```python
+show_tensor_elements(
+    data,
+    *,
+    engine=None,
+    config=None,
+    ax=None,
+    show_controls=True,
+    show=True,
+)
+```
+
 ### Parameters
 
 | Parameter | Meaning |
@@ -42,6 +57,15 @@ show_tensor_network(
 | `show_controls` | If `True`, add the figure control panel. If `False`, render only the network. |
 | `show` | If `True`, display the figure immediately. If `False`, just return `(fig, ax)`. |
 
+| Parameter | Meaning |
+| --- | --- |
+| `data` | Supported tensor object, tensor collection, backend-native tensor container, or `EinsumTrace` with live tensors. |
+| `engine` | Optional explicit backend: `"tensorkrowch"`, `"tensornetwork"`, `"quimb"`, `"tenpy"`, or `"einsum"`. |
+| `config` | A `TensorElementsConfig` instance. If omitted, `TensorElementsConfig()` is used. |
+| `ax` | Existing Matplotlib axis for single-tensor rendering only. |
+| `show_controls` | If `True`, add compact `group + mode` controls and, when several tensors are present, a tensor slider. |
+| `show` | If `True`, display the figure immediately. If `False`, just return `(fig, ax)`. |
+
 ## `PlotConfig` in Practice
 
 `PlotConfig` is where visual behavior lives.
@@ -98,6 +122,39 @@ config = PlotConfig(
 )
 ```
 
+## `TensorElementsConfig` in Practice
+
+`TensorElementsConfig` is where tensor inspection behavior lives.
+
+### Useful defaults
+
+```python
+config = TensorElementsConfig(
+    mode="auto",
+    max_matrix_shape=(256, 256),
+    histogram_bins=40,
+)
+```
+
+When multiple tensors are present, `show_tensor_elements(...)` keeps one tensor visible at a time.
+The slider changes the active tensor. The controls are grouped so you first choose a family of
+views and then the concrete mode inside that family:
+
+- `basic`: `elements`, `magnitude`, `distribution`, `data`
+- `complex`: `real`, `imag`, `phase`
+- `diagnostic`: `sign`, `signed_value`
+
+### Rank > 2 tensors
+
+```python
+config = TensorElementsConfig(
+    row_axes=("left", "phys"),
+    col_axes=("right",),
+)
+```
+
+If you omit `row_axes` / `col_axes`, the library chooses a deterministic balanced partition.
+
 ## Common Workflows
 
 ### 1. Explore interactively
@@ -148,31 +205,50 @@ show_tensor_network(
 
 If you pass `ax`, the plot is rendered into that axis and the figure is not recreated.
 
+### 4. Inspect tensor values
+
+```python
+fig, ax = show_tensor_elements(
+    trace,
+    config=TensorElementsConfig(mode="auto"),
+    show=False,
+)
+fig.savefig("tensor-elements.png", bbox_inches="tight")
+```
+
+Use this when you want one tensor at a time, quick switches between grouped views, and a `data`
+summary without leaving the same figure.
+
 ## Supported Inputs
 
 ### TensorKrowch
 
 - `TensorNetwork`
 - iterable of TensorKrowch nodes
+- single TensorKrowch node with a materialized `tensor`
 
 ### TensorNetwork
 
 - iterable of `tensornetwork.Node`
+- single `tensornetwork.Node`
 
 ### Quimb
 
 - `quimb.tensor.TensorNetwork`
 - iterable of `quimb.tensor.Tensor`
+- single `quimb.tensor.Tensor`
 
 ### TeNPy
 
 - common native MPS/MPO-style objects
 - explicit `TenPyTensorNetwork`
+- single TeNPy tensor exposing `to_ndarray()` and `get_leg_labels()`
 
 ### `einsum`
 
 - `EinsumTrace`
-- ordered iterable of `pair_tensor(...)` / `einsum_trace_step(...)`
+- manual `pair_tensor(...)` / `einsum_trace_step(...)` lists are only valid for
+  `show_tensor_network(...)`, not for `show_tensor_elements(...)`
 
 More detailed copy-paste examples: [backends.md](backends.md)
 
@@ -186,6 +262,11 @@ ax.set_title("My tensor network")
 fig.savefig("out.png", bbox_inches="tight")
 ```
 
+```python
+fig, ax = show_tensor_elements(data, show=False)
+fig.savefig("tensor-elements.png", bbox_inches="tight")
+```
+
 That means you can:
 
 - add titles,
@@ -220,6 +301,16 @@ config = PlotConfig(
 
 Then consider passing `positions` if you already know the layout you want.
 
+### Tensor inspection fails for TensorKrowch shape-only nodes
+
+`show_tensor_elements(...)` needs real tensor values. Nodes with only `shape` metadata are not
+enough.
+
+### Tensor inspection fails for manual `pair_tensor(...)` lists
+
+Manual trace steps describe contractions, not tensor values. Use `EinsumTrace` and keep the traced
+tensors alive until you render them.
+
 ### Jupyter shows duplicate output
 
 Prefer:

docs/tensor_elements_ideas.md

@@ -0,0 +1,28 @@
+# Tensor Elements Ideas
+
+This file collects ideas that are intentionally out of scope for the current implementation round.
+
+## Potential Future Views
+
+- `log_magnitude`
+- `sparsity`
+- `nan_inf`
+- `topk`
+- `slice`
+- `reduce`
+- `profiles`
+- `spectrum`
+
+## Potential Future Controls
+
+- shared color scale across tensors
+- robust scaling by percentiles
+- symmetric color scaling around zero
+- reference tensor comparison
+- outlier highlighting
+
+## Notes
+
+- Prefer additions that fit the current Matplotlib control style.
+- Avoid turning `TensorElementsConfig` into a catch-all config object.
+- Keep `show_tensor_elements(...)` aligned with the current package API style.