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

tnfr/dynamics/dnfr.pyi

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tnfr.types import DeltaNFRHook, TNFRGraph
+from tnfr.utils.cache import DnfrCache as DnfrCache
+
+__all__: tuple[str, ...]
+
+def default_compute_delta_nfr(
+    G: TNFRGraph,
+    *,
+    cache_size: int | None = ...,
+    n_jobs: int | None = ...,
+) -> None: ...
+def dnfr_epi_vf_mixed(G: TNFRGraph, *, n_jobs: int | None = ...) -> None: ...
+def dnfr_laplacian(G: TNFRGraph, *, n_jobs: int | None = ...) -> None: ...
+def dnfr_phase_only(G: TNFRGraph, *, n_jobs: int | None = ...) -> None: ...
+def set_delta_nfr_hook(
+    G: TNFRGraph,
+    func: DeltaNFRHook,
+    *,
+    name: str | None = ...,
+    note: str | None = ...,
+) -> None: ...
+def __getattr__(name: str) -> Any: ...

tnfr/dynamics/dynamic_limits.py

@@ -0,0 +1,225 @@
+"""Dynamic canonical limits based on network coherence.
+
+This module implements dynamic canonical limits for EPI and νf that adapt
+based on network coherence metrics. This addresses the theoretical question
+of whether fixed limits contradict TNFR's self-organizing principles.
+
+Theoretical Foundation
+----------------------
+TNFR paradigm principles:
+1. **Operational fractality**: Patterns should scale without artificial bounds
+2. **Self-organization**: System should find its own natural limits
+3. **Coherence emergence**: Stability arises from resonance, not external constraints
+
+Fixed limits may contradict these principles by imposing external constraints
+that don't emerge from the system's own dynamics. Dynamic limits address this
+by making bounds proportional to network coherence metrics.
+
+Dynamic Limit Formulas
+----------------------
+EPI effective maximum:
+    EPI_effective_max(t) = EPI_base_max × (1 + α × C(t) × Si_avg)
+
+νf effective maximum:
+    νf_effective_max(t) = νf_base_max × (1 + β × R_kuramoto)
+
+Where:
+- C(t): Global coherence at time t (0 to 1)
+- Si_avg: Average sense index across network (0 to 1+)
+- R_kuramoto: Kuramoto order parameter (0 to 1)
+- α, β: Expansion coefficients (default: 0.5, 0.3)
+
+Theoretical Justification
+--------------------------
+1. **Coherent networks** (high C(t), Si) can sustain higher EPI values
+2. **Synchronized networks** (high R_kuramoto) can sustain higher νf
+3. **Self-regulation** through coupling to system state
+4. **Fractality preservation** via proportional scaling
+5. **Safety bounds** via maximum expansion factors
+
+References
+----------
+- AGENTS.md: Section 3 (Canonical invariants)
+- Issue fermga/TNFR-Python-Engine#2624: Theoretical review of limits
+- TNFR.pdf: Nodal equation and coherence theory
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ..alias import collect_attr
+from ..constants.aliases import ALIAS_SI
+from ..metrics.common import compute_coherence
+from ..observers import kuramoto_order
+from ..utils import get_numpy
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph
+
+__all__ = (
+    "DynamicLimits",
+    "DynamicLimitsConfig",
+    "compute_dynamic_limits",
+    "DEFAULT_SI_FALLBACK",
+)
+
+# Default fallback value for sense index when nodes have no Si attribute
+# This represents a "neutral" sense index - neither high stability nor instability
+DEFAULT_SI_FALLBACK = 0.5
+
+
+@dataclass(frozen=True)
+class DynamicLimitsConfig:
+    """Configuration for dynamic canonical limits.
+
+    Attributes:
+        base_epi_max: Base maximum for EPI (static fallback)
+        base_vf_max: Base maximum for νf (static fallback)
+        alpha: Expansion coefficient for EPI (via C(t) × Si)
+        beta: Expansion coefficient for νf (via R_kuramoto)
+        max_expansion_factor: Maximum allowed expansion multiplier
+        enabled: Whether dynamic limits are active
+    """
+
+    base_epi_max: float = 1.0
+    base_vf_max: float = 10.0
+    alpha: float = 0.5
+    beta: float = 0.3
+    max_expansion_factor: float = 3.0
+    enabled: bool = True
+
+
+@dataclass(frozen=True)
+class DynamicLimits:
+    """Result of dynamic limits computation.
+
+    Attributes:
+        epi_max_effective: Computed effective maximum for EPI
+        vf_max_effective: Computed effective maximum for νf
+        coherence: C(t) value used in computation
+        si_avg: Average Si value used in computation
+        kuramoto_r: Kuramoto order parameter used in computation
+        coherence_factor: Combined coherence metric (C(t) × Si_avg)
+        config: Configuration used for computation
+    """
+
+    epi_max_effective: float
+    vf_max_effective: float
+    coherence: float
+    si_avg: float
+    kuramoto_r: float
+    coherence_factor: float
+    config: DynamicLimitsConfig
+
+
+def compute_dynamic_limits(
+    G: TNFRGraph,
+    config: DynamicLimitsConfig | None = None,
+) -> DynamicLimits:
+    """Compute dynamic canonical limits based on network state.
+
+    This function computes effective maximum values for EPI and νf that
+    adapt based on the network's coherence metrics. More coherent networks
+    are allowed higher values, reflecting their greater structural stability.
+
+    The computation respects TNFR invariants:
+    - Operator closure: bounds scale but remain finite
+    - Structural semantics: expansion proportional to coherence
+    - Self-organization: limits emerge from system state
+    - Fractality: proportional scaling preserves structure
+
+    Args:
+        G: TNFR graph with node attributes
+        config: Configuration for dynamic limits (uses defaults if None)
+
+    Returns:
+        DynamicLimits containing effective bounds and metrics
+
+    Examples:
+        >>> import networkx as nx
+        >>> G = nx.Graph()
+        >>> G.add_node(0, **{"νf": 1.0, "theta": 0.0, "EPI": 0.5, "Si": 0.7})
+        >>> limits = compute_dynamic_limits(G)
+        >>> limits.epi_max_effective >= 1.0  # May be expanded
+        True
+
+        >>> # With custom configuration
+        >>> config = DynamicLimitsConfig(alpha=0.8, beta=0.5)
+        >>> limits = compute_dynamic_limits(G, config)
+        >>> limits.config.alpha
+        0.8
+
+    Notes:
+        - Returns base limits if graph is empty
+        - Clamps expansion to max_expansion_factor for safety
+        - If config.enabled is False, returns base limits only
+        - All metrics computed using existing TNFR functions
+    """
+    if config is None:
+        config = DynamicLimitsConfig()
+
+    # Handle empty graph
+    n_nodes = G.number_of_nodes()
+    if n_nodes == 0:
+        return DynamicLimits(
+            epi_max_effective=config.base_epi_max,
+            vf_max_effective=config.base_vf_max,
+            coherence=0.0,
+            si_avg=0.0,
+            kuramoto_r=0.0,
+            coherence_factor=0.0,
+            config=config,
+        )
+
+    # If dynamic limits disabled, return base values
+    if not config.enabled:
+        return DynamicLimits(
+            epi_max_effective=config.base_epi_max,
+            vf_max_effective=config.base_vf_max,
+            coherence=1.0,
+            si_avg=1.0,
+            kuramoto_r=1.0,
+            coherence_factor=1.0,
+            config=config,
+        )
+
+    # Compute coherence metrics
+    C_t = compute_coherence(G)
+
+    # Compute average sense index
+    np_module = get_numpy()
+    si_values = collect_attr(G, G.nodes, ALIAS_SI, DEFAULT_SI_FALLBACK, np=np_module)
+    if np_module is not None:
+        Si_avg = float(np_module.mean(si_values))
+    else:
+        Si_avg = sum(si_values) / len(si_values) if si_values else DEFAULT_SI_FALLBACK
+
+    # Compute Kuramoto order parameter
+    R_kuramoto = kuramoto_order(G)
+
+    # Compute coherence factor
+    coherence_factor = C_t * Si_avg
+
+    # Compute dynamic limits
+    epi_expansion = 1.0 + config.alpha * coherence_factor
+    vf_expansion = 1.0 + config.beta * R_kuramoto
+
+    # Apply maximum expansion factor as safety bound
+    epi_expansion = min(epi_expansion, config.max_expansion_factor)
+    vf_expansion = min(vf_expansion, config.max_expansion_factor)
+
+    # Compute effective limits
+    epi_max_effective = config.base_epi_max * epi_expansion
+    vf_max_effective = config.base_vf_max * vf_expansion
+
+    return DynamicLimits(
+        epi_max_effective=epi_max_effective,
+        vf_max_effective=vf_max_effective,
+        coherence=C_t,
+        si_avg=Si_avg,
+        kuramoto_r=R_kuramoto,
+        coherence_factor=coherence_factor,
+        config=config,
+    )

tnfr/dynamics/feedback.py

@@ -0,0 +1,252 @@
+"""Structural feedback loops for TNFR adaptive dynamics.
+
+This module implements feedback loops that automatically adjust nodal parameters
+based on current structural state. Feedback loops enable autonomous regulation
+and homeostatic cycles as specified in TNFR dynamics theory.
+
+The core principle: ΔNFR → operator selection → application → measure effect →
+adjust thresholds, creating closed-loop structural regulation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import TNFRGraph, NodeId
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_DNFR, ALIAS_EPI, ALIAS_VF
+from ..operators.registry import get_operator_class
+from ..config.operator_names import (
+    COHERENCE,
+    DISSONANCE,
+    EMISSION,
+    SELF_ORGANIZATION,
+    SILENCE,
+)
+
+__all__ = ["StructuralFeedbackLoop"]
+
+
+class StructuralFeedbackLoop:
+    """Feedback loop that adapts nodal dynamics based on structural state.
+
+    This class implements closed-loop regulation where the system measures its
+    current coherence state and selects appropriate operators to maintain
+    target coherence levels. The feedback loop adjusts thresholds adaptively
+    based on performance.
+
+    **Feedback Cycle:**
+
+    1. **Measure**: Compute current coherence from ΔNFR and local state
+    2. **Decide**: Select operator based on deviation from target
+    3. **Act**: Apply selected operator
+    4. **Learn**: Adjust thresholds based on achieved coherence
+
+    Parameters
+    ----------
+    graph : TNFRGraph
+        Graph containing the regulated node
+    node : NodeId
+        Identifier of the node to regulate
+    target_coherence : float, default=0.7
+        Target coherence level (C_target)
+    tau_adaptive : float, default=0.1
+        Initial bifurcation threshold (adaptive)
+    learning_rate : float, default=0.05
+        Rate of threshold adaptation
+    coherence_tolerance_low : float, default=0.2
+        Deviation below target that triggers stabilization
+    coherence_tolerance_high : float, default=0.1
+        Deviation above target that triggers exploration
+    dnfr_threshold : float, default=0.15
+        ΔNFR threshold for self-organization
+    epi_threshold : float, default=0.3
+        EPI threshold for emission
+
+    Attributes
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node identifier
+    target_coherence : float
+        Target C(t) for homeostasis
+    tau_adaptive : float
+        Adaptive bifurcation threshold
+    learning_rate : float
+        Threshold adjustment rate
+    COHERENCE_TOL_LOW : float
+        Lower tolerance for coherence regulation
+    COHERENCE_TOL_HIGH : float
+        Upper tolerance for coherence regulation
+    DNFR_THRESHOLD : float
+        Threshold for self-organization activation
+    EPI_THRESHOLD : float
+        Threshold for emission activation
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> from tnfr.dynamics.feedback import StructuralFeedbackLoop
+    >>> G, node = create_nfr("test_node")
+    >>> loop = StructuralFeedbackLoop(G, node, target_coherence=0.7)
+    >>> operator_name = loop.regulate()
+    >>> loop.homeostatic_cycle(num_steps=5)
+    """
+
+    # Regulation thresholds
+    COHERENCE_TOL_LOW = 0.2  # Deviation below target triggers stabilization
+    COHERENCE_TOL_HIGH = 0.1  # Deviation above target triggers exploration
+    DNFR_THRESHOLD = 0.15  # ΔNFR threshold for self-organization
+    EPI_THRESHOLD = 0.3  # EPI threshold for emission
+
+    def __init__(
+        self,
+        graph: TNFRGraph,
+        node: NodeId,
+        target_coherence: float = 0.7,
+        tau_adaptive: float = 0.1,
+        learning_rate: float = 0.05,
+        coherence_tolerance_low: float = COHERENCE_TOL_LOW,
+        coherence_tolerance_high: float = COHERENCE_TOL_HIGH,
+        dnfr_threshold: float = DNFR_THRESHOLD,
+        epi_threshold: float = EPI_THRESHOLD,
+    ) -> None:
+        self.G = graph
+        self.node = node
+        self.target_coherence = float(target_coherence)
+        self.tau_adaptive = float(tau_adaptive)
+        self.learning_rate = float(learning_rate)
+        self.COHERENCE_TOL_LOW = float(coherence_tolerance_low)
+        self.COHERENCE_TOL_HIGH = float(coherence_tolerance_high)
+        self.DNFR_THRESHOLD = float(dnfr_threshold)
+        self.EPI_THRESHOLD = float(epi_threshold)
+
+    def regulate(self) -> str:
+        """Select appropriate operator based on current structural state.
+
+        Decision logic follows TNFR canonical regulation principles:
+
+        - **Low coherence**: Stabilize with IL (Coherence)
+        - **High coherence**: Explore with OZ (Dissonance)
+        - **High ΔNFR**: Self-organize with THOL
+        - **Low EPI**: Activate with AL (Emission)
+        - **Stable**: Consolidate with SHA (Silence)
+
+        Returns
+        -------
+        str
+            Operator name to apply
+
+        Notes
+        -----
+        The regulation logic implements structural decision-making based on
+        current node state. It avoids arbitrary choices by following TNFR
+        coherence principles.
+        """
+        dnfr = get_attr(self.G.nodes[self.node], ALIAS_DNFR, 0.0)
+        epi = get_attr(self.G.nodes[self.node], ALIAS_EPI, 0.0)
+
+        # Compute local coherence estimate
+        coherence = self._compute_local_coherence()
+
+        # Structural decision tree
+        if coherence < self.target_coherence - self.COHERENCE_TOL_LOW:
+            # Very low coherence → stabilize
+            return COHERENCE
+        elif coherence > self.target_coherence + self.COHERENCE_TOL_HIGH:
+            # High coherence → explore
+            return DISSONANCE
+        elif dnfr > self.DNFR_THRESHOLD:
+            # High reorganization pressure → self-organize
+            return SELF_ORGANIZATION
+        elif epi < self.EPI_THRESHOLD:
+            # Low activation → emit
+            return EMISSION
+        else:
+            # Stable state → consolidate
+            return SILENCE
+
+    def _compute_local_coherence(self) -> float:
+        """Estimate local coherence from ΔNFR.
+
+        Coherence is inversely proportional to reorganization pressure.
+        When ΔNFR is low, coherence is high (structure is stable).
+
+        Returns
+        -------
+        float
+            Estimated coherence in [0, 1]
+        """
+        dnfr = get_attr(self.G.nodes[self.node], ALIAS_DNFR, 0.0)
+        # Coherence inversely proportional to |ΔNFR|
+        return max(0.0, min(1.0, 1.0 - abs(dnfr)))
+
+    def adapt_thresholds(self, performance_metric: float) -> None:
+        """Adapt thresholds based on achieved performance.
+
+        Uses proportional feedback control to adjust tau_adaptive toward
+        target coherence. This implements learning in the feedback loop.
+
+        Parameters
+        ----------
+        performance_metric : float
+            Achieved coherence or other performance measure
+
+        Notes
+        -----
+        Threshold adaptation follows:
+
+        .. math::
+
+            \\tau_{t+1} = \\tau_t + \\alpha (C_{target} - C_{achieved})
+
+        where α is the learning rate.
+        """
+        error = self.target_coherence - performance_metric
+
+        # Proportional adjustment
+        self.tau_adaptive += self.learning_rate * error
+
+        # Clamp to valid range
+        self.tau_adaptive = max(0.05, min(0.25, self.tau_adaptive))
+
+    def homeostatic_cycle(self, num_steps: int = 10) -> None:
+        """Execute homeostatic regulation cycle.
+
+        Maintains target coherence through repeated sense-decide-act-learn cycles.
+
+        Parameters
+        ----------
+        num_steps : int, default=10
+            Number of regulation steps
+
+        Notes
+        -----
+        Each step:
+
+        1. Measures current coherence
+        2. Selects operator via regulate()
+        3. Applies operator
+        4. Measures new coherence
+        5. Adapts thresholds
+
+        This implements autonomous structural homeostasis.
+        """
+        for step in range(num_steps):
+            # Measure state before
+            coherence_before = self._compute_local_coherence()
+
+            # Select and apply operator
+            operator_name = self.regulate()
+            operator_class = get_operator_class(operator_name)
+            operator = operator_class()
+            operator(self.G, self.node, tau=self.tau_adaptive)
+
+            # Measure state after
+            coherence_after = self._compute_local_coherence()
+
+            # Adapt thresholds based on performance
+            self.adapt_thresholds(coherence_after)

tnfr/dynamics/feedback.pyi

@@ -0,0 +1,24 @@
+"""Type stubs for tnfr.dynamics.feedback module."""
+
+from typing import Any
+from ..types import TNFRGraph, NodeId
+
+class StructuralFeedbackLoop:
+    G: TNFRGraph
+    node: NodeId
+    target_coherence: float
+    tau_adaptive: float
+    learning_rate: float
+
+    def __init__(
+        self,
+        graph: TNFRGraph,
+        node: NodeId,
+        target_coherence: float = ...,
+        tau_adaptive: float = ...,
+        learning_rate: float = ...,
+    ) -> None: ...
+    def regulate(self) -> str: ...
+    def _compute_local_coherence(self) -> float: ...
+    def adapt_thresholds(self, performance_metric: float) -> None: ...
+    def homeostatic_cycle(self, num_steps: int = ...) -> None: ...