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

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))

tnfr/dynamics/canonical.py

@@ -0,0 +1,229 @@
+"""Canonical TNFR nodal equation implementation.
+
+This module provides the explicit, canonical implementation of the fundamental
+TNFR nodal equation as specified in the theory:
+
+    ∂EPI/∂t = νf · ΔNFR(t)
+
+Where:
+  - EPI: Primary Information Structure (coherent form)
+  - νf: Structural frequency in Hz_str (structural hertz)
+  - ΔNFR: Nodal gradient (reorganization operator)
+  - t: Structural time (not chronological time)
+
+This implementation ensures theoretical fidelity to the TNFR paradigm by:
+  1. Making the canonical equation explicit in code
+  2. Validating dimensional consistency (Hz_str units)
+  3. Providing clear mapping between theory and implementation
+  4. Maintaining reproducibility and traceability
+
+TNFR Invariants (from AGENTS.md):
+  - EPI as coherent form: changes only via structural operators
+  - Structural units: νf expressed in Hz_str (structural hertz)
+  - ΔNFR semantics: sign and magnitude modulate reorganization rate
+  - Operator closure: composition yields valid TNFR states
+
+References:
+  - TNFR.pdf: Canonical nodal equation specification
+  - AGENTS.md: Section 3 (Canonical invariants)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+    from ..types import GraphLike
+
+__all__ = (
+    "NodalEquationResult",
+    "compute_canonical_nodal_derivative",
+    "validate_structural_frequency",
+    "validate_nodal_gradient",
+)
+
+
+class NodalEquationResult(NamedTuple):
+    """Result of canonical nodal equation evaluation.
+
+    Attributes:
+        derivative: ∂EPI/∂t computed from νf · ΔNFR(t)
+        nu_f: Structural frequency (Hz_str) used in computation
+        delta_nfr: Nodal gradient (ΔNFR) used in computation
+        validated: Whether units and bounds were validated
+    """
+
+    derivative: float
+    nu_f: float
+    delta_nfr: float
+    validated: bool
+
+
+def compute_canonical_nodal_derivative(
+    nu_f: float,
+    delta_nfr: float,
+    *,
+    validate_units: bool = True,
+    graph: GraphLike | None = None,
+) -> NodalEquationResult:
+    """Compute ∂EPI/∂t using the canonical TNFR nodal equation.
+
+    This is the explicit implementation of the fundamental equation:
+        ∂EPI/∂t = νf · ΔNFR(t)
+
+    The function computes the time derivative of the Primary Information
+    Structure (EPI) as the product of:
+      - νf: structural frequency (reorganization rate in Hz_str)
+      - ΔNFR: nodal gradient (reorganization need/operator)
+
+    Args:
+        nu_f: Structural frequency in Hz_str (must be non-negative)
+        delta_nfr: Nodal gradient (reorganization operator)
+        validate_units: If True, validates that inputs are in valid ranges
+        graph: Optional graph for context-aware validation
+
+    Returns:
+        NodalEquationResult containing the computed derivative and metadata
+
+    Raises:
+        ValueError: If validation is enabled and inputs are invalid
+
+    Notes:
+        - This function is the canonical reference implementation
+        - The result represents the instantaneous rate of EPI evolution
+        - Units: [∂EPI/∂t] = Hz_str (structural reorganization rate)
+        - The product νf·ΔNFR must preserve TNFR operator closure
+
+    Examples:
+        >>> # Basic computation
+        >>> result = compute_canonical_nodal_derivative(1.0, 0.5)
+        >>> result.derivative
+        0.5
+
+        >>> # With explicit validation
+        >>> result = compute_canonical_nodal_derivative(
+        ...     nu_f=1.2,
+        ...     delta_nfr=-0.3,
+        ...     validate_units=True
+        ... )
+        >>> result.validated
+        True
+    """
+    validated = False
+
+    if validate_units:
+        nu_f = validate_structural_frequency(nu_f, graph=graph)
+        delta_nfr = validate_nodal_gradient(delta_nfr, graph=graph)
+        validated = True
+
+    # Canonical TNFR nodal equation: ∂EPI/∂t = νf · ΔNFR(t)
+    derivative = float(nu_f) * float(delta_nfr)
+
+    return NodalEquationResult(
+        derivative=derivative,
+        nu_f=nu_f,
+        delta_nfr=delta_nfr,
+        validated=validated,
+    )
+
+
+def validate_structural_frequency(
+    nu_f: float,
+    *,
+    graph: GraphLike | None = None,
+) -> float:
+    """Validate that structural frequency is in valid range.
+
+    Structural frequency (νf) must satisfy TNFR constraints:
+      - Non-negative (νf ≥ 0)
+      - Expressed in Hz_str (structural hertz)
+      - Finite and well-defined
+
+    Args:
+        nu_f: Structural frequency to validate
+        graph: Optional graph for context-aware bounds checking
+
+    Returns:
+        Validated structural frequency value
+
+    Raises:
+        ValueError: If nu_f is negative, infinite, or NaN
+        TypeError: If nu_f cannot be converted to float
+
+    Notes:
+        - νf = 0 is valid and represents structural silence
+        - Units must be Hz_str (not classical Hz)
+        - For Hz↔Hz_str conversion, use tnfr.units module
+    """
+    try:
+        value = float(nu_f)
+    except TypeError as exc:
+        # Non-convertible type (e.g., None, object())
+        raise TypeError(
+            f"Structural frequency must be numeric, got {type(nu_f).__name__}"
+        ) from exc
+    except ValueError as exc:
+        # Invalid string value (e.g., "invalid")
+        raise ValueError(
+            f"Structural frequency must be a valid number, got {nu_f!r}"
+        ) from exc
+
+    # Check for NaN or infinity using math.isfinite
+    if not math.isfinite(value):
+        raise ValueError(f"Structural frequency must be finite, got νf={value}")
+
+    if value < 0:
+        raise ValueError(f"Structural frequency must be non-negative, got νf={value}")
+
+    return value
+
+
+def validate_nodal_gradient(
+    delta_nfr: float,
+    *,
+    graph: GraphLike | None = None,
+) -> float:
+    """Validate that nodal gradient is well-defined.
+
+    The nodal gradient (ΔNFR) represents the internal reorganization
+    operator and must be:
+      - Finite and well-defined
+      - Sign indicates reorganization direction
+      - Magnitude indicates reorganization intensity
+
+    Args:
+        delta_nfr: Nodal gradient to validate
+        graph: Optional graph for context-aware validation
+
+    Returns:
+        Validated nodal gradient value
+
+    Raises:
+        ValueError: If delta_nfr is infinite or NaN
+        TypeError: If delta_nfr cannot be converted to float
+
+    Notes:
+        - ΔNFR can be positive (expansion) or negative (contraction)
+        - ΔNFR = 0 indicates equilibrium (no reorganization)
+        - Do NOT reinterpret as classical "error gradient"
+        - Semantics: operator over EPI, not optimization target
+    """
+    try:
+        value = float(delta_nfr)
+    except TypeError as exc:
+        # Non-convertible type (e.g., None, object())
+        raise TypeError(
+            f"Nodal gradient must be numeric, got {type(delta_nfr).__name__}"
+        ) from exc
+    except ValueError as exc:
+        # Invalid string value (e.g., "invalid")
+        raise ValueError(
+            f"Nodal gradient must be a valid number, got {delta_nfr!r}"
+        ) from exc
+
+    # Check for NaN or infinity using math.isfinite
+    if not math.isfinite(value):
+        raise ValueError(f"Nodal gradient must be finite, got ΔNFR={value}")
+
+    return value

tnfr/dynamics/canonical.pyi

@@ -0,0 +1,48 @@
+"""Type stubs for canonical TNFR nodal equation implementation."""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from ..types import GraphLike
+
+__all__ = (
+    "NodalEquationResult",
+    "compute_canonical_nodal_derivative",
+    "validate_structural_frequency",
+    "validate_nodal_gradient",
+)
+
+class NodalEquationResult(NamedTuple):
+    """Result of canonical nodal equation evaluation."""
+
+    derivative: float
+    nu_f: float
+    delta_nfr: float
+    validated: bool
+
+def compute_canonical_nodal_derivative(
+    nu_f: float,
+    delta_nfr: float,
+    *,
+    validate_units: bool = True,
+    graph: GraphLike | None = None,
+) -> NodalEquationResult:
+    """Compute ∂EPI/∂t using the canonical TNFR nodal equation."""
+    ...
+
+def validate_structural_frequency(
+    nu_f: float,
+    *,
+    graph: GraphLike | None = None,
+) -> float:
+    """Validate that structural frequency is in valid range."""
+    ...
+
+def validate_nodal_gradient(
+    delta_nfr: float,
+    *,
+    graph: GraphLike | None = None,
+) -> float:
+    """Validate that nodal gradient is well-defined."""
+    ...