tensor-network-visualization 1.0.0__tar.gz

tensor_network_visualization-1.0.0/LICENSE

@@ -0,0 +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.

tensor_network_visualization-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: tensor-network-visualization
+Version: 1.0.0
+Summary: Minimal Matplotlib visualizations for TensorKrowch tensor networks.
+Author: Alejandro Mata Ali
+License: MIT
+Project-URL: Repository, https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization
+Keywords: tensor-network,visualization,tensorkrowch,matplotlib
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: networkx>=3.0
+Requires-Dist: tensorkrowch
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Dynamic: license-file
+
+# Tensor-Network-Visualization
+
+Minimal Matplotlib visualizations for TensorKrowch tensor networks.
+
+**Repository:** [https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization](https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization)
+
+## Features
+
+- 2D and 3D plotting for TensorKrowch tensor networks
+- Tensors rendered as nodes
+- Contractions rendered as edges between tensors
+- Dangling indices rendered as labeled stubs
+- Self-contractions rendered as loops
+- No UI; uses Matplotlib for rendering and NetworkX for graph layouts
+
+## Installation
+
+### As a dependency
+
+Add to your project's `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["tensor-network-visualization>=0.1.0"]
+```
+
+Or install with pip:
+
+```bash
+pip install tensor-network-visualization
+```
+
+### Local development
+
+Inside the project virtual environment:
+
+```powershell
+.\.venv\Scripts\python -m pip install -e ".[dev]"
+```
+
+For runtime-only (editable install without dev tools):
+
+```powershell
+.\.venv\Scripts\python -m pip install -e .
+```
+
+## Usage
+
+Networks must expose `nodes` or `leaf_nodes` (iterable or dict). Each node must have `edges`, `axes_names`, and `name`. Each edge must have `node1`, `node2`, and `name`.
+
+```python
+from tensor_network_viz import PlotConfig, show_tensor_network
+
+config = PlotConfig(figsize=(8, 6))
+fig, ax = show_tensor_network(
+    network,
+    engine="tensorkrowch",
+    view="2d",
+    config=config,
+)
+```
+
+You can also use the TensorKrowch-specific helpers directly:
+
+```python
+from tensor_network_viz.tensorkrowch import plot_tensorkrowch_network_2d, plot_tensorkrowch_network_3d
+```
+
+## Project layout
+
+- `examples/` — Demo scripts. Run `python examples/tensor_network_demo.py mps 2d` from the project root.
+- `scripts/` — Utility scripts (e.g. `clean.py` to remove caches and build artifacts).
+
+## Development
+
+```powershell
+.\.venv\Scripts\python -m ruff check .
+.\.venv\Scripts\python -m pyright
+.\.venv\Scripts\python -m pytest
+```

tensor_network_visualization-1.0.0/README.md

@@ -0,0 +1,80 @@
+# Tensor-Network-Visualization
+
+Minimal Matplotlib visualizations for TensorKrowch tensor networks.
+
+**Repository:** [https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization](https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization)
+
+## Features
+
+- 2D and 3D plotting for TensorKrowch tensor networks
+- Tensors rendered as nodes
+- Contractions rendered as edges between tensors
+- Dangling indices rendered as labeled stubs
+- Self-contractions rendered as loops
+- No UI; uses Matplotlib for rendering and NetworkX for graph layouts
+
+## Installation
+
+### As a dependency
+
+Add to your project's `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["tensor-network-visualization>=0.1.0"]
+```
+
+Or install with pip:
+
+```bash
+pip install tensor-network-visualization
+```
+
+### Local development
+
+Inside the project virtual environment:
+
+```powershell
+.\.venv\Scripts\python -m pip install -e ".[dev]"
+```
+
+For runtime-only (editable install without dev tools):
+
+```powershell
+.\.venv\Scripts\python -m pip install -e .
+```
+
+## Usage
+
+Networks must expose `nodes` or `leaf_nodes` (iterable or dict). Each node must have `edges`, `axes_names`, and `name`. Each edge must have `node1`, `node2`, and `name`.
+
+```python
+from tensor_network_viz import PlotConfig, show_tensor_network
+
+config = PlotConfig(figsize=(8, 6))
+fig, ax = show_tensor_network(
+    network,
+    engine="tensorkrowch",
+    view="2d",
+    config=config,
+)
+```
+
+You can also use the TensorKrowch-specific helpers directly:
+
+```python
+from tensor_network_viz.tensorkrowch import plot_tensorkrowch_network_2d, plot_tensorkrowch_network_3d
+```
+
+## Project layout
+
+- `examples/` — Demo scripts. Run `python examples/tensor_network_demo.py mps 2d` from the project root.
+- `scripts/` — Utility scripts (e.g. `clean.py` to remove caches and build artifacts).
+
+## Development
+
+```powershell
+.\.venv\Scripts\python -m ruff check .
+.\.venv\Scripts\python -m pyright
+.\.venv\Scripts\python -m pytest
+```

tensor_network_visualization-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tensor-network-visualization"
+version = "1.0.0"
+description = "Minimal Matplotlib visualizations for TensorKrowch tensor networks."
+authors = [{ name = "Alejandro Mata Ali" }]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["tensor-network", "visualization", "tensorkrowch", "matplotlib"]
+dependencies = [
+    "matplotlib>=3.7",
+    "networkx>=3.0",
+    "tensorkrowch",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.urls]
+Repository = "https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "pyright"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tensor_network_viz = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-p no:cacheprovider"
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+exclude = [".venv", ".tmp", ".pip_tmp", ".pytest_cache", ".ruff_cache", "pytest-cache-files-*", "tn_tsp.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "C4", "SIM"]

tensor_network_visualization-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tensor_network_visualization-1.0.0/src/tensor_network_visualization.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: tensor-network-visualization
+Version: 1.0.0
+Summary: Minimal Matplotlib visualizations for TensorKrowch tensor networks.
+Author: Alejandro Mata Ali
+License: MIT
+Project-URL: Repository, https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization
+Keywords: tensor-network,visualization,tensorkrowch,matplotlib
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: networkx>=3.0
+Requires-Dist: tensorkrowch
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Dynamic: license-file
+
+# Tensor-Network-Visualization
+
+Minimal Matplotlib visualizations for TensorKrowch tensor networks.
+
+**Repository:** [https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization](https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization)
+
+## Features
+
+- 2D and 3D plotting for TensorKrowch tensor networks
+- Tensors rendered as nodes
+- Contractions rendered as edges between tensors
+- Dangling indices rendered as labeled stubs
+- Self-contractions rendered as loops
+- No UI; uses Matplotlib for rendering and NetworkX for graph layouts
+
+## Installation
+
+### As a dependency
+
+Add to your project's `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["tensor-network-visualization>=0.1.0"]
+```
+
+Or install with pip:
+
+```bash
+pip install tensor-network-visualization
+```
+
+### Local development
+
+Inside the project virtual environment:
+
+```powershell
+.\.venv\Scripts\python -m pip install -e ".[dev]"
+```
+
+For runtime-only (editable install without dev tools):
+
+```powershell
+.\.venv\Scripts\python -m pip install -e .
+```
+
+## Usage
+
+Networks must expose `nodes` or `leaf_nodes` (iterable or dict). Each node must have `edges`, `axes_names`, and `name`. Each edge must have `node1`, `node2`, and `name`.
+
+```python
+from tensor_network_viz import PlotConfig, show_tensor_network
+
+config = PlotConfig(figsize=(8, 6))
+fig, ax = show_tensor_network(
+    network,
+    engine="tensorkrowch",
+    view="2d",
+    config=config,
+)
+```
+
+You can also use the TensorKrowch-specific helpers directly:
+
+```python
+from tensor_network_viz.tensorkrowch import plot_tensorkrowch_network_2d, plot_tensorkrowch_network_3d
+```
+
+## Project layout
+
+- `examples/` — Demo scripts. Run `python examples/tensor_network_demo.py mps 2d` from the project root.
+- `scripts/` — Utility scripts (e.g. `clean.py` to remove caches and build artifacts).
+
+## Development
+
+```powershell
+.\.venv\Scripts\python -m ruff check .
+.\.venv\Scripts\python -m pyright
+.\.venv\Scripts\python -m pytest
+```

tensor_network_visualization-1.0.0/src/tensor_network_visualization.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+src/tensor_network_visualization.egg-info/PKG-INFO
+src/tensor_network_visualization.egg-info/SOURCES.txt
+src/tensor_network_visualization.egg-info/dependency_links.txt
+src/tensor_network_visualization.egg-info/requires.txt
+src/tensor_network_visualization.egg-info/top_level.txt
+src/tensor_network_viz/__init__.py
+src/tensor_network_viz/config.py
+src/tensor_network_viz/py.typed
+src/tensor_network_viz/viewer.py
+src/tensor_network_viz/tensorkrowch/__init__.py
+src/tensor_network_viz/tensorkrowch/_draw_common.py
+src/tensor_network_viz/tensorkrowch/curves.py
+src/tensor_network_viz/tensorkrowch/draw_2d.py
+src/tensor_network_viz/tensorkrowch/draw_3d.py
+src/tensor_network_viz/tensorkrowch/graph.py
+src/tensor_network_viz/tensorkrowch/layout.py
+src/tensor_network_viz/tensorkrowch/renderer.py
+tests/test_integration_tensorkrowch.py
+tests/test_plotting.py

tensor_network_visualization-1.0.0/src/tensor_network_visualization.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tensor_network_visualization-1.0.0/src/tensor_network_visualization.egg-info/requires.txt

@@ -0,0 +1,8 @@
+matplotlib>=3.7
+networkx>=3.0
+tensorkrowch
+
+[dev]
+pytest
+ruff
+pyright

tensor_network_visualization-1.0.0/src/tensor_network_visualization.egg-info/top_level.txt

@@ -0,0 +1 @@
+tensor_network_viz

tensor_network_visualization-1.0.0/src/tensor_network_viz/__init__.py

@@ -0,0 +1,10 @@
+from .config import EngineName, PlotConfig, ViewName
+
+
+def show_tensor_network(*args, **kwargs):
+    from .viewer import show_tensor_network as _show_tensor_network
+
+    return _show_tensor_network(*args, **kwargs)
+
+
+__all__ = ["EngineName", "PlotConfig", "ViewName", "show_tensor_network"]

tensor_network_visualization-1.0.0/src/tensor_network_viz/config.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+EngineName: TypeAlias = Literal["tensorkrowch"]
+ViewName: TypeAlias = Literal["2d", "3d"]
+
+
+_DEFAULT_NODE_RADIUS = 0.08
+_DEFAULT_STUB_LENGTH = 0.34
+_DEFAULT_SELF_LOOP_RADIUS = 0.2
+_DEFAULT_LINE_WIDTH_2D = 1.8
+_DEFAULT_LINE_WIDTH_3D = 1.6
+
+
+@dataclass(frozen=True)
+class PlotConfig:
+    """Configuration for tensor network plot styling.
+
+    Compatible networks must expose `nodes` or `leaf_nodes` (iterable or dict).
+    Each node must have `edges`, `axes_names`, and `name`. Each edge must have
+    `node1`, `node2`, and `name`.
+
+    Attributes:
+        node_color: Fill color for tensor nodes (hex or named color).
+        edge_color: Color for generic edges (currently unused; bond/dangling take precedence).
+        label_color: Color for axis and edge labels.
+        bond_edge_color: Color for contraction edges between tensors.
+        dangling_edge_color: Color for dangling index stubs.
+        figsize: Figure size as (width, height) in inches; None uses Matplotlib default.
+        show_tensor_labels: Whether to display tensor names on nodes.
+        show_index_labels: Whether to display axis names on edges.
+        node_radius: Radius of tensor nodes; None uses default (0.08).
+        stub_length: Length of dangling index stubs; None uses default (0.34).
+        self_loop_radius: Radius for self-contraction loops; None uses default (0.2).
+        line_width_2d: Line width for 2D plots; None uses default (1.8).
+        line_width_3d: Line width for 3D plots; None uses default (1.6).
+        positions: Custom node positions for grid/PEPS layout; dict mapping node id to
+            (x, y) for 2D or (x, y, z) for 3D. None uses automatic layout.
+        node_edge_color: Border color for tensor nodes; use dark for contrast on light nodes.
+        tensor_label_color: Color for tensor names on nodes; use dark for readability.
+    """
+
+    node_color: str = "#E8E8E8"
+    node_edge_color: str = "#2D3748"
+    tensor_label_color: str = "#1A202C"
+    edge_color: str = "#202B33"
+    label_color: str = "#0C1319"
+    bond_edge_color: str = "#00008B"
+    dangling_edge_color: str = "#8B0000"
+    figsize: tuple[float, float] | None = (8, 6)
+    show_tensor_labels: bool = True
+    show_index_labels: bool = True
+    node_radius: float | None = None
+    stub_length: float | None = None
+    self_loop_radius: float | None = None
+    line_width_2d: float | None = None
+    line_width_3d: float | None = None
+    positions: dict[int, tuple[float, ...]] | None = None

tensor_network_visualization-1.0.0/src/tensor_network_viz/tensorkrowch/__init__.py

@@ -0,0 +1,9 @@
+from .renderer import (
+    plot_tensorkrowch_network_2d,
+    plot_tensorkrowch_network_3d,
+)
+
+__all__ = [
+    "plot_tensorkrowch_network_2d",
+    "plot_tensorkrowch_network_3d",
+]

tensor_network_visualization-1.0.0/src/tensor_network_viz/tensorkrowch/_draw_common.py

@@ -0,0 +1,62 @@
+"""Shared scale and style parameters for 2D and 3D drawing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..config import (
+    _DEFAULT_LINE_WIDTH_2D,
+    _DEFAULT_LINE_WIDTH_3D,
+    _DEFAULT_NODE_RADIUS,
+    _DEFAULT_SELF_LOOP_RADIUS,
+    _DEFAULT_STUB_LENGTH,
+    PlotConfig,
+)
+
+
+@dataclass(frozen=True)
+class _DrawScaleParams:
+    """Resolved scale-dependent parameters for drawing."""
+
+    r: float
+    stub: float
+    loop_r: float
+    lw: float
+    font_dangling: int
+    font_bond: int
+    font_node: int
+    label_offset: float
+    ellipse_w: float
+    ellipse_h: float
+    scatter_s: float
+
+
+def _draw_scale_params(config: PlotConfig, scale: float, *, is_3d: bool) -> _DrawScaleParams:
+    """Compute scale-dependent drawing parameters from config."""
+    r = (config.node_radius if config.node_radius is not None else _DEFAULT_NODE_RADIUS) * scale
+    stub = (
+        config.stub_length if config.stub_length is not None else _DEFAULT_STUB_LENGTH
+    ) * scale
+    loop_r = (
+        config.self_loop_radius
+        if config.self_loop_radius is not None
+        else _DEFAULT_SELF_LOOP_RADIUS
+    ) * scale
+    lw_default = _DEFAULT_LINE_WIDTH_3D if is_3d else _DEFAULT_LINE_WIDTH_2D
+    lw_attr = config.line_width_3d if is_3d else config.line_width_2d
+    lw = (lw_attr if lw_attr is not None else lw_default) * scale
+    scatter_s = (120 if is_3d else 900) * (scale**2)
+
+    return _DrawScaleParams(
+        r=r,
+        stub=stub,
+        loop_r=loop_r,
+        lw=lw,
+        font_dangling=max(7, round(9 * scale)),
+        font_bond=max(5, round(5 * scale)),
+        font_node=max(8, round(10 * scale)),
+        label_offset=0.08 * scale,
+        ellipse_w=0.16 * scale,
+        ellipse_h=0.12 * scale,
+        scatter_s=scatter_s,
+    )

tensor_network_visualization-1.0.0/src/tensor_network_viz/tensorkrowch/curves.py

@@ -0,0 +1,98 @@
+"""Curve geometry and edge grouping utilities."""
+
+from __future__ import annotations
+
+import math
+from typing import TypeAlias
+
+import numpy as np
+
+from .graph import _EdgeData, _EdgeEndpoint, _GraphData
+
+Vector: TypeAlias = np.ndarray
+
+# For curve offset: positive = curve "above"/"right", negative = "below"/"left"
+_AXIS_OFFSET_SIGN: dict[str, int] = {
+    "up": 1,
+    "right": 1,
+    "north": 1,
+    "east": 1,
+    "down": -1,
+    "left": -1,
+    "south": -1,
+    "west": -1,
+}
+
+
+def _offset_sign_from_axis_name(axis_name: str | None) -> int:
+    if not axis_name:
+        return 0
+    return _AXIS_OFFSET_SIGN.get(axis_name.lower().strip(), 0)
+
+
+def _group_contractions(graph: _GraphData) -> dict[tuple[int, int], list[_EdgeData]]:
+    groups: dict[tuple[int, int], list[_EdgeData]] = {}
+    for edge in graph.edges:
+        if edge.kind != "contraction":
+            continue
+        key = tuple(sorted(edge.node_ids))
+        groups.setdefault(key, []).append(edge)
+    for group in groups.values():
+        group.sort(key=lambda e: _offset_sign_from_axis_name(
+            e.endpoints[0].axis_name if e.endpoints else None
+        ))
+    return groups
+
+
+def _quadratic_curve(
+    start: Vector,
+    control: Vector,
+    end: Vector,
+    samples: int = 40,
+) -> Vector:
+    t = np.linspace(0.0, 1.0, samples)
+    return (
+        ((1.0 - t) ** 2)[:, None] * start
+        + (2.0 * (1.0 - t) * t)[:, None] * control
+        + (t**2)[:, None] * end
+    )
+
+
+def _ellipse_points(
+    center: Vector,
+    direction: Vector,
+    normal: Vector,
+    *,
+    width: float,
+    height: float,
+    samples: int = 60,
+) -> Vector:
+    theta = np.linspace(0.0, 2.0 * math.pi, samples)
+    return (
+        center
+        + np.outer(np.cos(theta), direction) * width
+        + np.outer(np.sin(theta), normal) * height
+    )
+
+
+def _ellipse_points_3d(
+    center: Vector,
+    axis_a: Vector,
+    axis_b: Vector,
+    *,
+    width: float,
+    height: float,
+    samples: int = 60,
+) -> Vector:
+    theta = np.linspace(0.0, 2.0 * math.pi, samples)
+    return (
+        center
+        + np.outer(np.cos(theta), axis_a) * width
+        + np.outer(np.sin(theta), axis_b) * height
+    )
+
+
+def _require_self_endpoints(edge: _EdgeData) -> tuple[_EdgeEndpoint, _EdgeEndpoint]:
+    if len(edge.endpoints) < 2:
+        raise TypeError("Self-edges must expose two endpoints.")
+    return edge.endpoints[0], edge.endpoints[1]