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

tnfr/dynamics/adaptive_sequences.py

@@ -0,0 +1,189 @@
+"""Adaptive sequence selection for TNFR operator trajectories.
+
+This module implements learning-based selection of operator sequences.
+Rather than executing fixed sequences, the system learns which sequences
+work best for given contexts and adapts its selection over time.
+
+The approach combines predefined canonical sequences with epsilon-greedy
+exploration to balance exploitation (use known good sequences) with
+exploration (try new patterns).
+"""
+
+from __future__ import annotations
+
+import random
+from typing import TYPE_CHECKING, Any, Dict, List
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph, NodeId
+
+try:
+    import numpy as np
+except ImportError:
+    np = None  # type: ignore[assignment]
+
+from ..config.operator_names import (
+    COHERENCE,
+    DISSONANCE,
+    EMISSION,
+    MUTATION,
+    RECEPTION,
+    RECURSIVITY,
+    RESONANCE,
+    SELF_ORGANIZATION,
+    SILENCE,
+    TRANSITION,
+)
+
+__all__ = ["AdaptiveSequenceSelector"]
+
+
+class AdaptiveSequenceSelector:
+    """Learns and selects optimal operator sequences based on context.
+
+    This class maintains a pool of canonical operator sequences and tracks
+    their performance over time. It uses epsilon-greedy selection to balance
+    exploitation of known-good sequences with exploration of alternatives.
+
+    **Selection Strategy:**
+
+    - **Exploitation (80%)**: Choose sequence with best historical performance
+    - **Exploration (20%)**: Random selection to discover new patterns
+
+    Parameters
+    ----------
+    graph : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Identifier of the node
+
+    Attributes
+    ----------
+    G : TNFRGraph
+        Graph reference
+    node : NodeId
+        Node identifier
+    sequences : dict[str, list[str]]
+        Pool of canonical operator sequences
+    performance : dict[str, list[float]]
+        Historical performance for each sequence
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.dynamics.adaptive_sequences import AdaptiveSequenceSelector
+    >>> G, node = create_nfr("test_node")
+    >>> selector = AdaptiveSequenceSelector(G, node)
+    >>> context = {"goal": "stability", "urgency": 0.5}
+    >>> sequence = selector.select_sequence(context)
+    >>> selector.record_performance("basic_activation", 0.85)
+    """
+
+    def __init__(self, graph: TNFRGraph, node: NodeId) -> None:
+        self.G = graph
+        self.node = node
+
+        # Canonical operator sequences
+        # Note: Sequences are designed to comply with TNFR grammar rules
+        self.sequences: Dict[str, List[str]] = {
+            "basic_activation": [EMISSION, COHERENCE],
+            "deep_learning": [EMISSION, RECEPTION, COHERENCE],
+            "exploration": [EMISSION, DISSONANCE, COHERENCE],
+            "consolidation": [COHERENCE, SILENCE, RECURSIVITY],
+            "mutation": [COHERENCE, MUTATION, TRANSITION, COHERENCE],
+        }
+
+        # Performance history: sequence_name -> [coherence_gains]
+        self.performance: Dict[str, List[float]] = {
+            k: [] for k in self.sequences.keys()
+        }
+
+    def select_sequence(self, context: Dict[str, Any]) -> List[str]:
+        """Select optimal sequence based on context and historical performance.
+
+        Uses goal-based filtering and epsilon-greedy selection:
+
+        1. Filter sequences appropriate for goal
+        2. With probability 0.8: select best-performing sequence
+        3. With probability 0.2: select random sequence (exploration)
+
+        Parameters
+        ----------
+        context : dict
+            Context with keys:
+
+            - **goal** (str): "stability", "growth", or "adaptation"
+            - **urgency** (float): Urgency level (0-1), currently unused
+
+        Returns
+        -------
+        list[str]
+            Sequence of operator names to execute
+
+        Notes
+        -----
+        Goal-to-sequence mapping follows TNFR principles:
+
+        - **stability**: Sequences emphasizing IL (Coherence) and SHA (Silence)
+        - **growth**: Sequences with AL (Emission) and THOL (Self-organization)
+        - **adaptation**: Sequences with ZHIR (Mutation) and learning cycles
+        """
+        goal = context.get("goal", "stability")
+
+        # Map goals to appropriate sequence candidates
+        if goal == "stability":
+            candidates = ["basic_activation", "consolidation"]
+        elif goal == "growth":
+            candidates = ["deep_learning", "exploration"]
+        elif goal == "adaptation":
+            candidates = ["mutation", "deep_learning"]
+        else:
+            candidates = list(self.sequences.keys())
+
+        # Epsilon-greedy selection (20% exploration, 80% exploitation)
+        epsilon = 0.2
+
+        if np is not None:
+            random_val = np.random.random()
+        else:
+            random_val = random.random()
+
+        if random_val < epsilon:
+            # Exploration: random selection
+            if np is not None:
+                selected = str(np.random.choice(candidates))
+            else:
+                selected = random.choice(candidates)
+        else:
+            # Exploitation: select best-performing sequence
+            avg_perf = {
+                k: (
+                    sum(self.performance[k]) / len(self.performance[k])
+                    if self.performance[k]
+                    else 0.0
+                )
+                for k in candidates
+            }
+            selected = max(avg_perf, key=avg_perf.get)  # type: ignore[arg-type]
+
+        return self.sequences[selected]
+
+    def record_performance(self, sequence_name: str, coherence_gain: float) -> None:
+        """Record performance metric for a sequence to enable learning.
+
+        Parameters
+        ----------
+        sequence_name : str
+            Name of the sequence that was executed
+        coherence_gain : float
+            Achieved coherence improvement or other performance metric
+
+        Notes
+        -----
+        Maintains a sliding window of the last 20 executions to adapt to
+        changing dynamics. Older performance data is discarded.
+        """
+        if sequence_name in self.performance:
+            self.performance[sequence_name].append(float(coherence_gain))
+            # Keep only last 20 executions (sliding window)
+            self.performance[sequence_name] = self.performance[sequence_name][-20:]

tnfr/dynamics/adaptive_sequences.pyi

@@ -0,0 +1,14 @@
+"""Type stubs for tnfr.dynamics.adaptive_sequences module."""
+
+from typing import Any, Dict, List
+from ..types import TNFRGraph, NodeId
+
+class AdaptiveSequenceSelector:
+    G: TNFRGraph
+    node: NodeId
+    sequences: Dict[str, List[str]]
+    performance: Dict[str, List[float]]
+
+    def __init__(self, graph: TNFRGraph, node: NodeId) -> None: ...
+    def select_sequence(self, context: Dict[str, Any]) -> List[str]: ...
+    def record_performance(self, sequence_name: str, coherence_gain: float) -> None: ...

tnfr/dynamics/aliases.py

@@ -0,0 +1,23 @@
+"""Shared alias tokens used across TNFR dynamics submodules."""
+
+from __future__ import annotations
+
+from ..constants.aliases import (
+    ALIAS_D2EPI,
+    ALIAS_DNFR,
+    ALIAS_DSI,
+    ALIAS_EPI,
+    ALIAS_SI,
+    ALIAS_THETA,
+    ALIAS_VF,
+)
+
+__all__ = (
+    "ALIAS_VF",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_SI",
+    "ALIAS_THETA",
+    "ALIAS_D2EPI",
+    "ALIAS_DSI",
+)

tnfr/dynamics/aliases.pyi

@@ -0,0 +1,19 @@
+from ..constants.aliases import (
+    ALIAS_D2EPI as ALIAS_D2EPI,
+    ALIAS_DNFR as ALIAS_DNFR,
+    ALIAS_DSI as ALIAS_DSI,
+    ALIAS_EPI as ALIAS_EPI,
+    ALIAS_SI as ALIAS_SI,
+    ALIAS_THETA as ALIAS_THETA,
+    ALIAS_VF as ALIAS_VF,
+)
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_SI",
+    "ALIAS_THETA",
+    "ALIAS_D2EPI",
+    "ALIAS_DSI",
+]

tnfr/dynamics/bifurcation.py

@@ -0,0 +1,232 @@
+"""Bifurcation dynamics and structural path selection for TNFR operators.
+
+This module provides utilities for detecting bifurcation readiness and
+determining viable structural reorganization paths after OZ-induced dissonance.
+
+According to TNFR canonical theory (§2.3.3, R4), when ∂²EPI/∂t² > τ,
+the system enters a bifurcation state enabling multiple reorganization
+trajectories. This module implements path selection based on nodal state.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..types import Glyph, NodeId, TNFRGraph
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_DNFR, ALIAS_EPI, ALIAS_VF
+from ..types import Glyph
+
+__all__ = [
+    "get_bifurcation_paths",
+    "compute_bifurcation_score",
+]
+
+
+def get_bifurcation_paths(G: "TNFRGraph", node: "NodeId") -> list["Glyph"]:
+    """Return viable structural paths after OZ-induced bifurcation.
+
+    When OZ (Dissonance) creates bifurcation readiness (∂²EPI/∂t² > τ),
+    this function determines which operators can resolve the dissonance
+    based on current nodal state.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+
+    Returns
+    -------
+    list[Glyph]
+        List of viable operator glyphs for structural reorganization.
+        Empty list if node is not in bifurcation state.
+
+    Notes
+    -----
+    **Canonical bifurcation paths:**
+
+    - **ZHIR (Mutation)**: Viable if νf > 0.8 (sufficient for controlled transformation)
+    - **NUL (Contraction)**: Viable if EPI < 0.5 (safe collapse window)
+    - **IL (Coherence)**: Always viable (universal resolution path)
+    - **THOL (Self-organization)**: Viable if degree >= 2 (network support)
+
+    The node must have `_bifurcation_ready = True` flag, typically set by
+    OZ precondition validation when ∂²EPI/∂t² exceeds threshold τ.
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.operators.definitions import Dissonance
+    >>> from tnfr.dynamics.bifurcation import get_bifurcation_paths
+    >>> G, node = create_nfr("test", epi=0.4, vf=1.0)
+    >>> # Set up bifurcation conditions
+    >>> G.nodes[node]["epi_history"] = [0.2, 0.35, 0.55]
+    >>> Dissonance()(G, node, validate_preconditions=True)
+    >>> paths = get_bifurcation_paths(G, node)
+    >>> # Returns viable operators: [ZHIR, NUL, IL, THOL] or subset
+
+    See Also
+    --------
+    tnfr.operators.preconditions.validate_dissonance : Sets bifurcation_ready flag
+    tnfr.operators.definitions.SelfOrganization : Spawns sub-EPIs on bifurcation
+    """
+    # Check if bifurcation active
+    if not G.nodes[node].get("_bifurcation_ready", False):
+        return []  # No bifurcation active
+
+    # Get node state for path evaluation
+    dnfr = abs(float(get_attr(G.nodes[node], ALIAS_DNFR, 0.0)))
+    epi = float(get_attr(G.nodes[node], ALIAS_EPI, 0.0))
+    vf = float(get_attr(G.nodes[node], ALIAS_VF, 0.0))
+    degree = G.degree(node)
+
+    paths = []
+
+    # ZHIR (Mutation) viable if sufficient νf for controlled transformation
+    zhir_threshold = float(G.graph.get("ZHIR_BIFURCATION_VF_THRESHOLD", 0.8))
+    if vf > zhir_threshold:
+        paths.append(Glyph.ZHIR)
+
+    # NUL (Contraction) viable if EPI low enough for safe collapse
+    nul_threshold = float(G.graph.get("NUL_BIFURCATION_EPI_THRESHOLD", 0.5))
+    if epi < nul_threshold:
+        paths.append(Glyph.NUL)
+
+    # IL (Coherence) always viable as universal resolution path
+    paths.append(Glyph.IL)
+
+    # THOL (Self-organization) viable if network connectivity supports it
+    thol_min_degree = int(G.graph.get("THOL_BIFURCATION_MIN_DEGREE", 2))
+    if degree >= thol_min_degree:
+        paths.append(Glyph.THOL)
+
+    return paths
+
+
+def compute_bifurcation_score(
+    d2epi: float,
+    dnfr: float,
+    vf: float,
+    epi: float,
+    tau: float = 0.5,
+) -> float:
+    """Compute quantitative bifurcation potential [0,1].
+
+    Integrates multiple structural indicators to assess bifurcation readiness.
+    According to TNFR canonical theory (§2.3.3, R4), bifurcation occurs when
+    ∂²EPI/∂t² > τ (acceleration exceeds threshold). This function extends that
+    binary condition into a continuous score that accounts for multiple factors.
+
+    Parameters
+    ----------
+    d2epi : float
+        Structural acceleration (∂²EPI/∂t²). Primary indicator of bifurcation.
+        When |d2epi| > τ, the system enters a bifurcation state enabling
+        multiple reorganization trajectories.
+    dnfr : float
+        Internal reorganization operator (ΔNFR). Magnitude indicates instability
+        level. Higher |ΔNFR| means stronger reorganization pressure.
+    vf : float
+        Structural frequency (νf) in Hz_str units. Determines capacity to respond
+        to bifurcation. Higher νf enables faster reorganization along new paths.
+    epi : float
+        Primary Information Structure. Provides structural substrate for
+        bifurcation. Higher EPI indicates more material to reorganize.
+    tau : float, default 0.5
+        Bifurcation acceleration threshold. When |d2epi| > tau, bifurcation
+        becomes active. Default 0.5 is the canonical TNFR threshold.
+
+    Returns
+    -------
+    float
+        Bifurcation score in range [0.0, 1.0]:
+        - 0.0 = no bifurcation potential (stable)
+        - 0.5 = bifurcation threshold (critical)
+        - 1.0 = maximal bifurcation readiness (multiple paths viable)
+
+    Notes
+    -----
+    The bifurcation score is a weighted combination of four factors:
+
+    1. **Acceleration factor** (40%): |∂²EPI/∂t²| / τ
+       Primary indicator. Measures how close the system is to or beyond
+       the bifurcation threshold.
+
+    2. **Instability factor** (30%): |ΔNFR|
+       Secondary indicator. Measures reorganization pressure that drives
+       bifurcation exploration.
+
+    3. **Capacity factor** (20%): νf / 2.0
+       Measures structural reorganization capacity. Higher νf enables faster
+       response to bifurcation opportunities.
+
+    4. **Substrate factor** (10%): EPI / 0.8
+       Measures available structural material. Higher EPI provides more
+       degrees of freedom for bifurcation paths.
+
+    Formula:
+        score = 0.4 * accel + 0.3 * instability + 0.2 * capacity + 0.1 * substrate
+
+    All factors are normalized to [0, 1] and clipped before combination.
+
+    Examples
+    --------
+    >>> from tnfr.dynamics.bifurcation import compute_bifurcation_score
+    >>>
+    >>> # Low bifurcation potential (stable state)
+    >>> score = compute_bifurcation_score(
+    ...     d2epi=0.1,  # Low acceleration
+    ...     dnfr=0.05,  # Low instability
+    ...     vf=0.5,     # Moderate capacity
+    ...     epi=0.3,    # Low substrate
+    ... )
+    >>> assert score < 0.3  # Low score
+    >>>
+    >>> # High bifurcation potential (critical state)
+    >>> score = compute_bifurcation_score(
+    ...     d2epi=0.7,  # High acceleration (> tau)
+    ...     dnfr=0.6,   # High instability
+    ...     vf=1.8,     # High capacity
+    ...     epi=0.7,    # High substrate
+    ... )
+    >>> assert score > 0.7  # High score
+
+    See Also
+    --------
+    get_bifurcation_paths : Determine viable operators after bifurcation
+    tnfr.operators.metrics.dissonance_metrics : Uses score in OZ metrics
+    """
+    from ..utils import get_numpy
+
+    np = get_numpy()
+
+    # 1. Acceleration factor (primary indicator)
+    # Normalized by tau threshold
+    accel_factor = min(abs(d2epi) / tau, 1.0) if tau > 0 else 0.0
+
+    # 2. Instability factor (secondary indicator)
+    # Already dimensionless, clip to [0, 1]
+    instability_factor = min(abs(dnfr), 1.0)
+
+    # 3. Capacity factor (reorganization capability)
+    # Normalize by 2.0 (typical high νf value)
+    capacity_factor = min(vf / 2.0, 1.0) if vf >= 0 else 0.0
+
+    # 4. Substrate factor (structural material available)
+    # Normalize by 0.8 (typical high EPI value)
+    substrate_factor = min(epi / 0.8, 1.0) if epi >= 0 else 0.0
+
+    # Weighted combination (percentages sum to 100%)
+    score = (
+        0.4 * accel_factor  # 40% - primary
+        + 0.3 * instability_factor  # 30% - secondary
+        + 0.2 * capacity_factor  # 20% - capability
+        + 0.1 * substrate_factor  # 10% - material
+    )
+
+    # Ensure result is in [0, 1] range
+    return float(np.clip(score, 0.0, 1.0))