tnfr 4.5.2__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/validation/window.py

@@ -0,0 +1,39 @@
+"""Primitive window validation helpers without heavy dependencies."""
+
+from __future__ import annotations
+
+import numbers
+
+__all__ = ["validate_window"]
+
+
+def validate_window(window: int, *, positive: bool = False) -> int:
+    """Validate ``window`` as an integer and return it.
+
+    Parameters
+    ----------
+    window:
+        Value to coerce into an integer window size.
+    positive:
+        When ``True`` the window must be strictly greater than zero; otherwise
+        zero is accepted. Negative values are never permitted.
+
+    Returns
+    -------
+    int
+        The validated integer window size.
+
+    Raises
+    ------
+    TypeError
+        If ``window`` is not an integer value.
+    ValueError
+        If ``window`` violates the positivity constraint.
+    """
+
+    if isinstance(window, bool) or not isinstance(window, numbers.Integral):
+        raise TypeError("'window' must be an integer")
+    if window < 0 or (positive and window == 0):
+        kind = "positive" if positive else "non-negative"
+        raise ValueError(f"'window'={window} must be {kind}")
+    return int(window)

tnfr/validation/window.pyi

@@ -0,0 +1 @@
+def validate_window(window: int, *, positive: bool = ...) -> int: ...

tnfr/visualization/__init__.py

@@ -0,0 +1,98 @@
+"""Visualization tools for TNFR operator sequences and structural analysis.
+
+This module provides advanced visualization capabilities for:
+- Sequence flow diagrams with compatibility-colored transitions
+- Health metrics dashboards with radar charts and gauges
+- Pattern analysis with component highlighting
+- Frequency timelines showing structural evolution
+- Cascade propagation and temporal dynamics
+- Hierarchical bifurcation structures (NEW)
+
+Requires matplotlib for plotting (optional). Install with::
+
+    pip install tnfr[viz]
+
+Hierarchy visualization (ASCII) has no external dependencies.
+
+Examples
+--------
+>>> from tnfr.visualization import SequenceVisualizer
+>>> from tnfr.operators.grammar import validate_sequence_with_health
+>>>
+>>> sequence = ["emission", "reception", "coherence", "silence"]
+>>> result = validate_sequence_with_health(sequence)
+>>>
+>>> visualizer = SequenceVisualizer()
+>>> fig, ax = visualizer.plot_sequence_flow(sequence, result.health_metrics)
+>>> fig.savefig("sequence_flow.png")
+
+>>> # Cascade visualization
+>>> from tnfr.visualization import plot_cascade_propagation, plot_cascade_timeline
+>>> fig = plot_cascade_propagation(G)
+>>> fig.savefig("cascade_propagation.png")
+
+>>> # Hierarchy visualization (no matplotlib required)
+>>> from tnfr.visualization import print_bifurcation_hierarchy
+>>> print_bifurcation_hierarchy(G, node)
+"""
+
+# Always available (no dependencies)
+from .hierarchy import (
+    print_bifurcation_hierarchy,
+    get_hierarchy_info,
+)
+
+_import_error: ImportError | None = None
+
+try:
+    from .sequence_plotter import SequenceVisualizer
+    from .cascade_viz import (
+        plot_cascade_propagation,
+        plot_cascade_timeline,
+        plot_cascade_metrics_summary,
+    )
+
+    __all__ = [
+        "SequenceVisualizer",
+        "plot_cascade_propagation",
+        "plot_cascade_timeline",
+        "plot_cascade_metrics_summary",
+        "print_bifurcation_hierarchy",
+        "get_hierarchy_info",
+    ]
+except ImportError as _import_err:
+    _import_error = _import_err
+    from typing import Any as _Any
+
+    def _missing_viz_dependency(*args: _Any, **kwargs: _Any) -> None:
+        missing_deps = []
+        try:
+            import matplotlib  # noqa: F401
+        except ImportError:
+            missing_deps.append("matplotlib")
+
+        if missing_deps:
+            deps_str = " and ".join(missing_deps)
+            raise ImportError(
+                f"Visualization functions require {deps_str}. "
+                "Install with: pip install tnfr[viz]"
+            ) from _import_error
+        else:
+            raise ImportError(
+                "Visualization functions are not available. "
+                "Install with: pip install tnfr[viz]"
+            ) from _import_error
+
+    SequenceVisualizer = _missing_viz_dependency  # type: ignore[assignment]
+    plot_cascade_propagation = _missing_viz_dependency  # type: ignore[assignment]
+    plot_cascade_timeline = _missing_viz_dependency  # type: ignore[assignment]
+    plot_cascade_metrics_summary = _missing_viz_dependency  # type: ignore[assignment]
+
+    __all__ = [
+        "SequenceVisualizer",
+        "plot_cascade_propagation",
+        "plot_cascade_timeline",
+        "plot_cascade_metrics_summary",
+        "print_bifurcation_hierarchy",
+        "get_hierarchy_info",
+    ]

tnfr/visualization/cascade_viz.py

@@ -0,0 +1,256 @@
+"""Visualization tools for THOL cascade dynamics.
+
+Provides plotting functions to visualize cascade propagation across networks,
+temporal evolution of cascades, and collective emergence patterns.
+
+TNFR Canonical Principle
+-------------------------
+From "El pulso que nos atraviesa" (TNFR Manual, §2.2.10):
+
+    "THOL actúa como modulador central de plasticidad. Es el glifo que
+    permite a la red reorganizar su topología sin intervención externa."
+
+These visualizations make cascade dynamics observable and traceable,
+enabling scientific validation and debugging of self-organization.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph
+
+import matplotlib.pyplot as plt
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_EPI
+
+try:
+    import networkx as nx
+
+    HAS_NETWORKX = True
+except ImportError:
+    HAS_NETWORKX = False
+
+__all__ = [
+    "plot_cascade_propagation",
+    "plot_cascade_timeline",
+]
+
+
+def plot_cascade_propagation(G: TNFRGraph, figsize: tuple[int, int] = (12, 8)):
+    """Visualize THOL cascade propagation across network.
+
+    Creates network diagram with:
+    - Node size = EPI magnitude
+    - Node color = bifurcation occurred (red) or not (blue)
+    - Edge thickness = coupling strength
+    - Arrows = propagation direction
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph with THOL propagation history
+    figsize : tuple[int, int], default (12, 8)
+        Figure size in inches (width, height)
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        Figure object containing the cascade visualization
+
+    Notes
+    -----
+    TNFR Principle: Cascade propagation shows how self-organization
+    spreads through phase-aligned neighbors. Red nodes = bifurcation source,
+    blue nodes = unaffected. Arrow thickness = propagation strength.
+
+    Examples
+    --------
+    >>> # After running THOL sequence with cascades
+    >>> fig = plot_cascade_propagation(G)
+    >>> fig.savefig("cascade_propagation.png")
+    >>> plt.show()
+    """
+    if not HAS_NETWORKX:
+        raise ImportError("NetworkX required for cascade visualization")
+
+    propagations = G.graph.get("thol_propagations", [])
+
+    fig, ax = plt.subplots(figsize=figsize)
+
+    # Identify nodes that bifurcated (source nodes in propagations)
+    bifurcated_nodes = set()
+    for prop in propagations:
+        bifurcated_nodes.add(prop["source_node"])
+
+    # Node colors: red = bifurcated, lightblue = normal
+    node_colors = ["red" if n in bifurcated_nodes else "lightblue" for n in G.nodes]
+
+    # Node sizes based on EPI magnitude
+    node_sizes = []
+    for n in G.nodes:
+        epi = float(get_attr(G.nodes[n], ALIAS_EPI, 0.5))
+        node_sizes.append(1000 * epi)
+
+    # Compute layout
+    pos = nx.spring_layout(G, seed=42)
+
+    # Draw network structure
+    nx.draw_networkx_nodes(
+        G, pos, node_color=node_colors, node_size=node_sizes, ax=ax, alpha=0.8
+    )
+    nx.draw_networkx_edges(G, pos, alpha=0.3, ax=ax)
+    nx.draw_networkx_labels(G, pos, ax=ax, font_size=10)
+
+    # Draw propagation arrows
+    for prop in propagations:
+        source = prop["source_node"]
+        for target, strength in prop["propagations"]:
+            if source in pos and target in pos:
+                ax.annotate(
+                    "",
+                    xy=pos[target],
+                    xytext=pos[source],
+                    arrowprops=dict(
+                        arrowstyle="->",
+                        color="red",
+                        lw=2 * strength,
+                        alpha=0.7,
+                    ),
+                )
+
+    ax.set_title("THOL Cascade Propagation", fontsize=14, fontweight="bold")
+    ax.axis("off")
+    plt.tight_layout()
+    return fig
+
+
+def plot_cascade_timeline(G: TNFRGraph, figsize: tuple[int, int] = (10, 5)):
+    """Plot temporal evolution of cascade events.
+
+    Creates scatter plot showing:
+    - X-axis: Timestamp (operator sequence step)
+    - Y-axis: Number of propagation targets
+    - Size: Indicates cascade magnitude
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph with THOL propagation history
+    figsize : tuple[int, int], default (10, 5)
+        Figure size in inches (width, height)
+
+    Returns
+    -------
+    matplotlib.figure.Figure or None
+        Figure object containing the timeline, or None if no cascades
+
+    Notes
+    -----
+    TNFR Principle: Temporal evolution reveals cascade patterns.
+    Spikes indicate strong propagation events; clusters indicate
+    sustained collective reorganization.
+
+    Examples
+    --------
+    >>> # After running THOL sequence with cascades
+    >>> fig = plot_cascade_timeline(G)
+    >>> if fig:
+    ...     fig.savefig("cascade_timeline.png")
+    ...     plt.show()
+    """
+    propagations = G.graph.get("thol_propagations", [])
+
+    if not propagations:
+        print("No cascade events to plot")
+        return None
+
+    timestamps = [p["timestamp"] for p in propagations]
+    cascade_sizes = [len(p["propagations"]) for p in propagations]
+
+    fig, ax = plt.subplots(figsize=figsize)
+    ax.scatter(timestamps, cascade_sizes, s=100, alpha=0.7, color="darkred")
+    ax.plot(timestamps, cascade_sizes, linestyle="--", alpha=0.5, color="gray")
+
+    ax.set_xlabel("Timestamp (operator sequence step)", fontsize=12)
+    ax.set_ylabel("Propagation Targets", fontsize=12)
+    ax.set_title("THOL Cascade Evolution", fontsize=14, fontweight="bold")
+    ax.grid(alpha=0.3)
+
+    plt.tight_layout()
+    return fig
+
+
+def plot_cascade_metrics_summary(
+    G: TNFRGraph,
+    node_metrics: dict[Any, dict[str, Any]],
+    figsize: tuple[int, int] = (14, 6),
+):
+    """Create comprehensive cascade metrics dashboard.
+
+    Creates multi-panel visualization showing:
+    - Panel 1: Cascade depth distribution
+    - Panel 2: Sub-EPI coherence over time
+    - Panel 3: Metabolic activity index
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph with THOL history
+    node_metrics : dict
+        Dictionary mapping node IDs to their THOL metrics
+    figsize : tuple[int, int], default (14, 6)
+        Figure size in inches (width, height)
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        Figure object containing the dashboard
+
+    Notes
+    -----
+    TNFR Principle: Complete observability requires multiple metrics.
+    This dashboard provides holistic view of self-organization dynamics.
+
+    Examples
+    --------
+    >>> # Collect metrics during sequence
+    >>> metrics_by_node = {}
+    >>> for node in G.nodes:
+    ...     metrics_by_node[node] = self_organization_metrics(G, node, ...)
+    >>> fig = plot_cascade_metrics_summary(G, metrics_by_node)
+    >>> fig.savefig("cascade_metrics_dashboard.png")
+    """
+    fig, axes = plt.subplots(1, 3, figsize=figsize)
+
+    # Panel 1: Cascade depth distribution
+    depths = [m.get("cascade_depth", 0) for m in node_metrics.values()]
+    axes[0].hist(depths, bins=range(max(depths) + 2), alpha=0.7, color="steelblue")
+    axes[0].set_xlabel("Cascade Depth", fontsize=11)
+    axes[0].set_ylabel("Count", fontsize=11)
+    axes[0].set_title("Cascade Depth Distribution", fontsize=12, fontweight="bold")
+    axes[0].grid(alpha=0.3)
+
+    # Panel 2: Sub-EPI coherence
+    coherences = [m.get("subepi_coherence", 0) for m in node_metrics.values()]
+    node_ids = list(node_metrics.keys())
+    axes[1].bar(range(len(node_ids)), coherences, alpha=0.7, color="forestgreen")
+    axes[1].set_xlabel("Node Index", fontsize=11)
+    axes[1].set_ylabel("Coherence [0,1]", fontsize=11)
+    axes[1].set_title("Sub-EPI Collective Coherence", fontsize=12, fontweight="bold")
+    axes[1].axhline(0.5, color="red", linestyle="--", alpha=0.5, label="Threshold")
+    axes[1].legend()
+    axes[1].grid(alpha=0.3)
+
+    # Panel 3: Metabolic activity index
+    activities = [m.get("metabolic_activity_index", 0) for m in node_metrics.values()]
+    axes[2].bar(range(len(node_ids)), activities, alpha=0.7, color="darkorange")
+    axes[2].set_xlabel("Node Index", fontsize=11)
+    axes[2].set_ylabel("Activity [0,1]", fontsize=11)
+    axes[2].set_title("Metabolic Activity Index", fontsize=12, fontweight="bold")
+    axes[2].grid(alpha=0.3)
+
+    plt.tight_layout()
+    return fig

tnfr/visualization/hierarchy.py

@@ -0,0 +1,284 @@
+"""Hierarchical bifurcation visualization for THOL operator.
+
+Provides utilities to visualize and inspect nested THOL bifurcation structures,
+supporting operational fractality analysis and debugging of complex emergent
+hierarchies.
+
+TNFR Canonical Principle
+-------------------------
+From THOL_ENCAPSULATION_GUIDE.md:
+
+    "THOL windows can be nested to arbitrary depth, reflecting TNFR's 
+    fractal structure."
+
+This module implements ASCII tree visualization of bifurcation hierarchies,
+enabling rapid inspection of multi-level emergent structures without external
+visualization dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..types import NodeId, TNFRGraph
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_EPI
+
+__all__ = [
+    "print_bifurcation_hierarchy",
+    "get_hierarchy_info",
+]
+
+
+def print_bifurcation_hierarchy(
+    G: TNFRGraph, 
+    node: NodeId, 
+    indent: int = 0,
+    max_depth: int | None = None,
+) -> None:
+    """Print ASCII tree of bifurcation hierarchy.
+    
+    Recursively traverses THOL bifurcations and displays them as an ASCII
+    tree structure, showing EPI values and bifurcation levels at each node.
+    
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing bifurcation structure
+    node : NodeId
+        Root node to start visualization from
+    indent : int, optional
+        Current indentation level (used internally for recursion), by default 0
+    max_depth : int | None, optional
+        Maximum depth to display (None = unlimited), by default None
+        
+    Notes
+    -----
+    TNFR Principle: Operational fractality (Invariant #7) enables recursive
+    bifurcation. This visualization makes hierarchical structures visible for:
+    - Debugging nested THOL sequences
+    - Validating depth constraints
+    - Analyzing emergent patterns
+    - Educational demonstrations
+    
+    The format uses standard tree characters:
+    - ├─ for intermediate branches
+    - └─ for last branch at each level
+    - │  for vertical continuation
+    
+    Examples
+    --------
+    >>> # Simple single-level bifurcation
+    >>> print_bifurcation_hierarchy(G, node)
+    Node 0 (EPI=0.82, level=0)
+    ├─ Sub-EPI 1 (epi=0.21, level=1)
+    └─ Sub-EPI 2 (epi=0.18, level=1)
+    
+    >>> # Multi-level nested bifurcation
+    >>> print_bifurcation_hierarchy(G, node)
+    Node 0 (EPI=0.82, level=0)
+    ├─ Sub-EPI 1 (epi=0.21, level=1)
+    │  ├─ Sub-Sub-EPI 1.1 (epi=0.05, level=2)
+    │  └─ Sub-Sub-EPI 1.2 (epi=0.08, level=2)
+    └─ Sub-EPI 2 (epi=0.18, level=1)
+    
+    >>> # Limit depth display
+    >>> print_bifurcation_hierarchy(G, node, max_depth=1)
+    Node 0 (EPI=0.82, level=0)
+    ├─ Sub-EPI 1 (epi=0.21, level=1) [...]
+    └─ Sub-EPI 2 (epi=0.18, level=1) [...]
+    """
+    # Check depth limit
+    if max_depth is not None and indent >= max_depth:
+        return
+    
+    # Get node information
+    node_epi = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
+    node_level = G.nodes[node].get("_bifurcation_level", 0)
+    
+    # Print current node
+    prefix = "  " * indent
+    print(f"{prefix}Node {node} (EPI={node_epi:.2f}, level={node_level})")
+    
+    # Get sub-EPIs
+    sub_epis = G.nodes[node].get("sub_epis", [])
+    
+    if not sub_epis:
+        return
+    
+    # Print each sub-EPI
+    for i, sub_epi in enumerate(sub_epis):
+        is_last = (i == len(sub_epis) - 1)
+        branch = "└─" if is_last else "├─"
+        continuation = "  " if is_last else "│ "
+        
+        sub_level = sub_epi.get("bifurcation_level", 1)
+        sub_epi_value = sub_epi.get("epi", 0.0)
+        
+        # Check if we'll hit depth limit on next level
+        truncated = ""
+        if max_depth is not None and indent + 1 >= max_depth:
+            # Check if sub-EPI has further nesting
+            sub_node_id = sub_epi.get("node_id")
+            if sub_node_id and sub_node_id in G.nodes:
+                sub_has_children = bool(G.nodes[sub_node_id].get("sub_epis", []))
+                if sub_has_children:
+                    truncated = " [...]"
+        
+        print(f"{prefix}{branch} Sub-EPI {i+1} "
+              f"(epi={sub_epi_value:.2f}, level={sub_level}){truncated}")
+        
+        # Recurse into sub-node if it exists and we haven't hit depth limit
+        sub_node_id = sub_epi.get("node_id")
+        if sub_node_id and sub_node_id in G.nodes:
+            if max_depth is None or indent + 1 < max_depth:
+                # Print continuation line for all but last child
+                if not is_last:
+                    child_sub_epis = G.nodes[sub_node_id].get("sub_epis", [])
+                    if child_sub_epis:
+                        # Prepare indentation for child's children
+                        child_indent = indent + 1
+                        child_prefix = "  " * child_indent
+                        # Print vertical continuation
+                        print(f"{prefix}{continuation}")
+                        # Recurse with continuation context
+                        _print_sub_hierarchy(
+                            G, sub_node_id, child_indent, 
+                            parent_continuation=continuation,
+                            parent_prefix=prefix,
+                            max_depth=max_depth
+                        )
+                else:
+                    # Last child - no continuation line
+                    child_sub_epis = G.nodes[sub_node_id].get("sub_epis", [])
+                    if child_sub_epis:
+                        child_indent = indent + 1
+                        _print_sub_hierarchy(
+                            G, sub_node_id, child_indent,
+                            parent_continuation="  ",
+                            parent_prefix=prefix,
+                            max_depth=max_depth
+                        )
+
+
+def _print_sub_hierarchy(
+    G: TNFRGraph,
+    node: NodeId,
+    indent: int,
+    parent_continuation: str,
+    parent_prefix: str,
+    max_depth: int | None,
+) -> None:
+    """Helper to print sub-hierarchy with proper indentation.
+    
+    Internal function handling continuation lines for nested hierarchies.
+    """
+    sub_epis = G.nodes[node].get("sub_epis", [])
+    
+    if not sub_epis:
+        return
+    
+    if max_depth is not None and indent >= max_depth:
+        return
+    
+    for i, sub_epi in enumerate(sub_epis):
+        is_last = (i == len(sub_epis) - 1)
+        branch = "└─" if is_last else "├─"
+        continuation = "  " if is_last else "│ "
+        
+        sub_level = sub_epi.get("bifurcation_level", 1)
+        sub_epi_value = sub_epi.get("epi", 0.0)
+        
+        # Build prefix with parent continuation
+        full_prefix = parent_prefix + parent_continuation
+        
+        truncated = ""
+        if max_depth is not None and indent + 1 >= max_depth:
+            sub_node_id = sub_epi.get("node_id")
+            if sub_node_id and sub_node_id in G.nodes:
+                sub_has_children = bool(G.nodes[sub_node_id].get("sub_epis", []))
+                if sub_has_children:
+                    truncated = " [...]"
+        
+        print(f"{full_prefix}{branch} Sub-EPI {i+1} "
+              f"(epi={sub_epi_value:.2f}, level={sub_level}){truncated}")
+        
+        # Recurse if node exists
+        sub_node_id = sub_epi.get("node_id")
+        if sub_node_id and sub_node_id in G.nodes:
+            if max_depth is None or indent + 1 < max_depth:
+                child_sub_epis = G.nodes[sub_node_id].get("sub_epis", [])
+                if child_sub_epis:
+                    _print_sub_hierarchy(
+                        G, sub_node_id, indent + 1,
+                        parent_continuation=parent_continuation + continuation,
+                        parent_prefix=parent_prefix,
+                        max_depth=max_depth
+                    )
+
+
+def get_hierarchy_info(G: TNFRGraph, node: NodeId) -> dict:
+    """Get hierarchical bifurcation information for a node.
+    
+    Returns structured data about the bifurcation hierarchy, useful for
+    programmatic analysis and testing.
+    
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing bifurcation structure
+    node : NodeId
+        Node to analyze
+        
+    Returns
+    -------
+    dict
+        Hierarchy information containing:
+        - node: Node identifier
+        - epi: Current EPI value
+        - bifurcation_level: Current bifurcation level
+        - hierarchy_path: List of ancestor nodes
+        - sub_epi_count: Number of direct sub-EPIs
+        - max_depth: Maximum bifurcation depth from this node
+        - total_descendants: Total number of sub-EPIs at all levels
+        
+    Examples
+    --------
+    >>> info = get_hierarchy_info(G, node)
+    >>> info["bifurcation_level"]
+    0
+    >>> info["max_depth"]
+    2
+    >>> info["total_descendants"]
+    4
+    """
+    from ..operators.metabolism import compute_hierarchical_depth
+    
+    node_epi = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
+    node_level = G.nodes[node].get("_bifurcation_level", 0)
+    hierarchy_path = G.nodes[node].get("_hierarchy_path", [])
+    sub_epis = G.nodes[node].get("sub_epis", [])
+    
+    # Compute max depth
+    max_depth = compute_hierarchical_depth(G, node)
+    
+    # Count total descendants recursively
+    total_descendants = len(sub_epis)
+    for sub_epi in sub_epis:
+        sub_node_id = sub_epi.get("node_id")
+        if sub_node_id and sub_node_id in G.nodes:
+            # Recurse into sub-node
+            sub_info = get_hierarchy_info(G, sub_node_id)
+            total_descendants += sub_info["total_descendants"]
+    
+    return {
+        "node": node,
+        "epi": node_epi,
+        "bifurcation_level": node_level,
+        "hierarchy_path": hierarchy_path,
+        "sub_epi_count": len(sub_epis),
+        "max_depth": max_depth,
+        "total_descendants": total_descendants,
+    }