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

tnfr/operators/jitter.py

@@ -0,0 +1,272 @@
+"""Jitter operators for reproducible phase perturbations."""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, Any, cast
+
+from ..rng import base_seed, cache_enabled
+from ..rng import clear_rng_cache as _clear_rng_cache
+from ..rng import (
+    make_rng,
+    seed_hash,
+)
+from ..types import NodeId, TNFRGraph
+from ..utils import (
+    CacheManager,
+    InstrumentedLRUCache,
+    ScopedCounterCache,
+    build_cache_manager,
+    ensure_node_offset_map,
+    get_nodenx,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from ..node import NodeProtocol
+
+# Guarded by the cache lock to ensure thread-safe access. ``seq`` stores
+# per-scope jitter sequence counters in an instrumented LRU cache bounded to avoid
+# unbounded memory usage.
+_JITTER_MAX_ENTRIES = 1024
+
+
+class JitterCache:
+    """Container for jitter-related caches."""
+
+    def __init__(
+        self,
+        max_entries: int = _JITTER_MAX_ENTRIES,
+        *,
+        manager: CacheManager | None = None,
+    ) -> None:
+        self._manager = manager or build_cache_manager()
+        if not self._manager.has_override("scoped_counter:jitter"):
+            self._manager.configure(
+                overrides={"scoped_counter:jitter": int(max_entries)}
+            )
+        self._sequence = ScopedCounterCache(
+            "jitter",
+            max_entries=None,
+            manager=self._manager,
+            default_max_entries=int(max_entries),
+        )
+        self._settings_key = "jitter_settings"
+        self._manager.register(
+            self._settings_key,
+            lambda: {"max_entries": self._sequence.max_entries},
+            reset=self._reset_settings,
+        )
+
+    def _reset_settings(self, settings: dict[str, Any] | None) -> dict[str, Any]:
+        return {"max_entries": self._sequence.max_entries}
+
+    def _refresh_settings(self) -> None:
+        self._manager.update(
+            self._settings_key,
+            lambda _: {"max_entries": self._sequence.max_entries},
+        )
+
+    @property
+    def manager(self) -> CacheManager:
+        """Expose the cache manager backing this cache."""
+
+        return self._manager
+
+    @property
+    def seq(self) -> InstrumentedLRUCache[tuple[int, int], int]:
+        """Expose the instrumented sequence cache for tests and diagnostics."""
+
+        return self._sequence.cache
+
+    @property
+    def lock(self) -> threading.Lock | threading.RLock:
+        """Return the lock protecting the sequence cache."""
+
+        return self._sequence.lock
+
+    @property
+    def max_entries(self) -> int:
+        """Return the maximum number of cached jitter sequences."""
+
+        return self._sequence.max_entries
+
+    @max_entries.setter
+    def max_entries(self, value: int) -> None:
+        """Set the maximum number of cached jitter sequences."""
+
+        self._sequence.configure(max_entries=int(value))
+        self._refresh_settings()
+
+    @property
+    def settings(self) -> dict[str, Any]:
+        """Return jitter cache settings stored on the manager."""
+
+        return cast(dict[str, Any], self._manager.get(self._settings_key))
+
+    def setup(self, force: bool = False, max_entries: int | None = None) -> None:
+        """Ensure jitter cache matches the configured size."""
+
+        self._sequence.configure(force=force, max_entries=max_entries)
+        self._refresh_settings()
+
+    def clear(self) -> None:
+        """Clear cached RNGs and jitter state."""
+
+        _clear_rng_cache()
+        self._sequence.clear()
+        self._manager.clear(self._settings_key)
+
+    def bump(self, key: tuple[int, int]) -> int:
+        """Return current jitter sequence counter for ``key`` and increment it."""
+
+        return self._sequence.bump(key)
+
+
+class JitterCacheManager:
+    """Manager exposing the jitter cache without global reassignment."""
+
+    def __init__(
+        self,
+        cache: JitterCache | None = None,
+        *,
+        manager: CacheManager | None = None,
+    ) -> None:
+        if cache is not None:
+            self.cache = cache
+            self._manager = cache.manager
+        else:
+            self._manager = manager or build_cache_manager()
+            self.cache = JitterCache(manager=self._manager)
+
+    # Convenience passthrough properties
+    @property
+    def seq(self) -> InstrumentedLRUCache[tuple[int, int], int]:
+        """Expose the underlying instrumented jitter sequence cache."""
+
+        return self.cache.seq
+
+    @property
+    def settings(self) -> dict[str, Any]:
+        """Return persisted jitter cache configuration."""
+
+        return self.cache.settings
+
+    @property
+    def lock(self) -> threading.Lock | threading.RLock:
+        """Return the lock associated with the jitter cache."""
+
+        return self.cache.lock
+
+    @property
+    def max_entries(self) -> int:
+        """Return the maximum number of cached jitter entries."""
+
+        return self.cache.max_entries
+
+    @max_entries.setter
+    def max_entries(self, value: int) -> None:
+        """Set the maximum number of cached jitter entries."""
+
+        self.cache.max_entries = value
+
+    def setup(self, force: bool = False, max_entries: int | None = None) -> None:
+        """Ensure jitter cache matches the configured size.
+
+        ``max_entries`` may be provided to explicitly resize the cache.
+        When omitted the existing ``cache.max_entries`` is preserved.
+        """
+
+        if max_entries is not None:
+            self.cache.setup(force=True, max_entries=max_entries)
+        else:
+            self.cache.setup(force=force)
+
+    def clear(self) -> None:
+        """Clear cached RNGs and jitter state."""
+
+        self.cache.clear()
+
+    def bump(self, key: tuple[int, int]) -> int:
+        """Return and increment the jitter sequence counter for ``key``."""
+
+        return self.cache.bump(key)
+
+
+# Lazy manager instance
+_JITTER_MANAGER: JitterCacheManager | None = None
+
+
+def get_jitter_manager() -> JitterCacheManager:
+    """Return the singleton jitter manager, initializing on first use."""
+    global _JITTER_MANAGER
+    if _JITTER_MANAGER is None:
+        _JITTER_MANAGER = JitterCacheManager()
+        _JITTER_MANAGER.setup(force=True)
+    return _JITTER_MANAGER
+
+
+def reset_jitter_manager() -> None:
+    """Reset the global jitter manager (useful for tests)."""
+    global _JITTER_MANAGER
+    if _JITTER_MANAGER is not None:
+        _JITTER_MANAGER.clear()
+    _JITTER_MANAGER = None
+
+
+def _node_offset(G: TNFRGraph, n: NodeId) -> int:
+    """Deterministic node index used for jitter seeds."""
+    mapping = ensure_node_offset_map(G)
+    return int(mapping.get(n, 0))
+
+
+def _resolve_jitter_seed(node: NodeProtocol) -> tuple[int, int]:
+    node_nx_type = get_nodenx()
+    if node_nx_type is None:
+        raise ImportError("NodeNX is unavailable")
+    if isinstance(node, node_nx_type):
+        graph = cast(TNFRGraph, getattr(node, "G"))
+        node_id = cast(NodeId, getattr(node, "n"))
+        return _node_offset(graph, node_id), id(graph)
+    uid = getattr(node, "_noise_uid", None)
+    if uid is None:
+        uid = id(node)
+        setattr(node, "_noise_uid", uid)
+    graph = cast(TNFRGraph | None, getattr(node, "G", None))
+    scope = graph if graph is not None else node
+    return int(uid), id(scope)
+
+
+def random_jitter(
+    node: NodeProtocol,
+    amplitude: float,
+) -> float:
+    """Return deterministic noise in ``[-amplitude, amplitude]`` for ``node``.
+
+    The per-node jitter sequences are tracked using the global manager
+    returned by :func:`get_jitter_manager`.
+    """
+    if amplitude < 0:
+        raise ValueError("amplitude must be positive")
+    if amplitude == 0:
+        return 0.0
+
+    seed_root = base_seed(node.G)
+    seed_key, scope_id = _resolve_jitter_seed(node)
+
+    cache_key = (seed_root, scope_id, seed_key)
+    seq = 0
+    if cache_enabled(node.G):
+        manager = get_jitter_manager()
+        seq = manager.bump(cache_key)
+    seed = seed_hash(seed_root, scope_id)
+    rng = make_rng(seed, seed_key + seq, node.G)
+    return rng.uniform(-amplitude, amplitude)
+
+
+__all__ = [
+    "JitterCache",
+    "JitterCacheManager",
+    "get_jitter_manager",
+    "reset_jitter_manager",
+    "random_jitter",
+]

tnfr/operators/jitter.pyi

@@ -0,0 +1,11 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+JitterCache: Any
+JitterCacheManager: Any
+get_jitter_manager: Any
+random_jitter: Any
+reset_jitter_manager: Any

tnfr/operators/lifecycle.py

@@ -0,0 +1,314 @@
+"""Node lifecycle management for TNFR canonical theory.
+
+According to TNFR theory (El pulso que nos atraviesa, p.44), nodes follow
+a canonical lifecycle:
+
+1. Activation - Node emerges through sufficient reorganization
+2. Stabilization - Finds coherent phase and form
+3. Propagation - Reorganizes its network environment
+4. Mutation - Transforms through dissonance
+5. Collapse - Loses phase/frequency and dissolves
+
+This module provides lifecycle state tracking and transition validation.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..types import NodeId, TNFRGraph
+
+from ..alias import get_attr
+from ..constants.aliases import ALIAS_EPI, ALIAS_VF, ALIAS_DNFR, ALIAS_THETA
+
+__all__ = [
+    "LifecycleState",
+    "CollapseReason",
+    "get_lifecycle_state",
+    "check_collapse_conditions",
+    "should_collapse",
+]
+
+# Default thresholds for lifecycle state determination
+DEFAULT_MIN_PHASE_COUPLING = 0.1  # Minimum phase coupling before decoupling collapse
+
+
+class LifecycleState(Enum):
+    """Canonical TNFR node lifecycle states.
+
+    These states correspond to the fundamental phases of node existence
+    in the Resonant Fractal Nature paradigm.
+    """
+
+    DORMANT = "dormant"
+    """Node exists but has minimal structural frequency (νf < activation_threshold)."""
+
+    ACTIVATION = "activation"
+    """Node is emerging with increasing νf and ΔNFR."""
+
+    STABILIZATION = "stabilization"
+    """Node is finding coherent form (high C(t), decreasing |ΔNFR|)."""
+
+    PROPAGATION = "propagation"
+    """Node is reorganizing its environment (high phase coupling)."""
+
+    MUTATION = "mutation"
+    """Node is undergoing phase transformation (high |ΔNFR|, phase shifts)."""
+
+    COLLAPSING = "collapsing"
+    """Node is losing coherence and approaching dissolution."""
+
+    COLLAPSED = "collapsed"
+    """Node has dissolved (νf → 0 or extreme dissonance)."""
+
+
+class CollapseReason(Enum):
+    """Canonical reasons for node collapse in TNFR.
+
+    These correspond to the fundamental ways structural coherence can fail.
+    """
+
+    FREQUENCY_FAILURE = "frequency_failure"
+    """Structural frequency dropped below collapse threshold (νf → 0)."""
+
+    EXTREME_DISSONANCE = "extreme_dissonance"
+    """ΔNFR magnitude exceeded bifurcation threshold."""
+
+    NETWORK_DECOUPLING = "network_decoupling"
+    """Phase coherence with network dropped below coupling threshold."""
+
+    EPI_DISSOLUTION = "epi_dissolution"
+    """Primary Information Structure lost coherence (EPI → 0)."""
+
+
+def _get_node_attr(
+    G: TNFRGraph, node: NodeId, aliases: tuple[str, ...], default: float = 0.0
+) -> float:
+    """Get node attribute using alias fallback."""
+    return float(get_attr(G.nodes[node], aliases, default))
+
+
+def get_lifecycle_state(
+    G: TNFRGraph,
+    node: NodeId,
+    *,
+    config: dict[str, Any] | None = None,
+) -> LifecycleState:
+    """Determine current lifecycle state of a node.
+
+    Analyzes node's structural parameters (νf, ΔNFR, EPI, θ) to determine
+    its position in the canonical TNFR lifecycle.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node to analyze
+    config : dict, optional
+        Configuration overrides for thresholds:
+        - activation_threshold: Min νf for activation (default: 0.1)
+        - collapse_threshold: Min νf to avoid collapse (default: 0.01)
+        - bifurcation_threshold: Max |ΔNFR| before bifurcation (default: 10.0)
+        - stabilization_dnfr: Max |ΔNFR| for stabilization (default: 1.0)
+        - stabilization_coherence: Min coherence for stabilization (default: 0.8)
+        - propagation_coupling: Min phase coupling for propagation (default: 0.7)
+        - mutation_dnfr: Min |ΔNFR| for mutation state (default: 5.0)
+
+    Returns
+    -------
+    LifecycleState
+        Current lifecycle state
+
+    Notes
+    -----
+    Collapse conditions are checked first. Among active states, the state
+    with the strongest indicators is returned (e.g., high |ΔNFR| → mutation
+    takes precedence over stabilization).
+
+    Examples
+    --------
+    >>> from tnfr.structural import create_nfr
+    >>> G, node = create_nfr("test", epi=0.5, vf=1.0)
+    >>> G.nodes[node]["ΔNFR"] = 0.5
+    >>> state = get_lifecycle_state(G, node)
+    >>> state.value
+    'activation'
+    """
+    if config is None:
+        config = {}
+
+    # Get thresholds from config or graph or defaults
+    def _get_threshold(key: str, default: float) -> float:
+        return float(config.get(key, G.graph.get(key.upper(), default)))
+
+    activation_threshold = _get_threshold("activation_threshold", 0.1)
+    collapse_threshold = _get_threshold("collapse_threshold", 0.01)
+    bifurcation_threshold = _get_threshold("bifurcation_threshold", 10.0)
+    stabilization_dnfr = _get_threshold("stabilization_dnfr", 1.0)
+    stabilization_coherence = _get_threshold("stabilization_coherence", 0.8)
+    propagation_coupling = _get_threshold("propagation_coupling", 0.7)
+    mutation_dnfr = _get_threshold("mutation_dnfr", 5.0)
+
+    # Get node structural parameters
+    vf = _get_node_attr(G, node, ALIAS_VF)
+    dnfr = _get_node_attr(G, node, ALIAS_DNFR)
+    epi = _get_node_attr(G, node, ALIAS_EPI)
+    theta = _get_node_attr(G, node, ALIAS_THETA)
+
+    # Check for collapse conditions first
+    if vf < collapse_threshold:
+        return LifecycleState.COLLAPSING
+
+    if abs(dnfr) > bifurcation_threshold:
+        return LifecycleState.COLLAPSING
+
+    # Compute phase coupling (simplified - could use full network coupling)
+    neighbors = list(G.neighbors(node))
+    if neighbors:
+        import math
+
+        neighbor_phases = [_get_node_attr(G, n, ALIAS_THETA) for n in neighbors]
+        mean_neighbor_phase = sum(neighbor_phases) / len(neighbor_phases)
+        phase_diff = abs(theta - mean_neighbor_phase)
+        # Normalize to [0, 1] where 1 is perfect alignment
+        phase_coupling = 1.0 - min(phase_diff, math.pi) / math.pi
+    else:
+        phase_coupling = 0.0
+
+    # Check for decoupling collapse
+    if neighbors and phase_coupling < DEFAULT_MIN_PHASE_COUPLING:
+        return LifecycleState.COLLAPSING
+
+    # Check active states (priority: mutation > propagation > stabilization > activation)
+
+    # Mutation: High dissonance with sufficient frequency
+    if abs(dnfr) > mutation_dnfr and vf > activation_threshold:
+        return LifecycleState.MUTATION
+
+    # Propagation: Strong network coupling
+    if phase_coupling > propagation_coupling and vf > activation_threshold:
+        return LifecycleState.PROPAGATION
+
+    # Stabilization: High coherence, low dissonance
+    # Note: C(t) computation would require full graph state, using EPI as proxy
+    if abs(dnfr) < stabilization_dnfr and epi > stabilization_coherence:
+        return LifecycleState.STABILIZATION
+
+    # Activation: Above activation threshold but not yet stabilized
+    if vf >= activation_threshold:
+        return LifecycleState.ACTIVATION
+
+    # Dormant: Below activation threshold but above collapse
+    return LifecycleState.DORMANT
+
+
+def check_collapse_conditions(
+    G: TNFRGraph,
+    node: NodeId,
+    *,
+    config: dict[str, Any] | None = None,
+) -> tuple[bool, CollapseReason | None]:
+    """Check if node meets any collapse conditions.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node to check
+    config : dict, optional
+        Configuration overrides for collapse thresholds
+
+    Returns
+    -------
+    should_collapse : bool
+        True if node should collapse
+    reason : CollapseReason | None
+        Reason for collapse, or None if not collapsing
+
+    Notes
+    -----
+    Multiple collapse conditions may be met simultaneously. This function
+    returns the first detected condition in priority order:
+    1. Frequency failure (most fundamental)
+    2. Extreme dissonance (structural instability)
+    3. Network decoupling (loss of resonance)
+    4. EPI dissolution (form loss)
+    """
+    if config is None:
+        config = {}
+
+    def _get_threshold(key: str, default: float) -> float:
+        return float(config.get(key, G.graph.get(key.upper(), default)))
+
+    collapse_threshold = _get_threshold("collapse_threshold", 0.01)
+    bifurcation_threshold = _get_threshold("bifurcation_threshold", 10.0)
+    min_coupling = _get_threshold("min_phase_coupling", 0.1)
+    min_epi = _get_threshold("min_epi", 0.01)
+
+    # Get node parameters
+    vf = _get_node_attr(G, node, ALIAS_VF)
+    dnfr = _get_node_attr(G, node, ALIAS_DNFR)
+    epi = _get_node_attr(G, node, ALIAS_EPI)
+    theta = _get_node_attr(G, node, ALIAS_THETA)
+
+    # Check frequency failure (most fundamental)
+    if vf < collapse_threshold:
+        return (True, CollapseReason.FREQUENCY_FAILURE)
+
+    # Check extreme dissonance
+    if abs(dnfr) > bifurcation_threshold:
+        return (True, CollapseReason.EXTREME_DISSONANCE)
+
+    # Check network decoupling
+    neighbors = list(G.neighbors(node))
+    if neighbors:
+        import math
+
+        neighbor_phases = [_get_node_attr(G, n, ALIAS_THETA) for n in neighbors]
+        mean_neighbor_phase = sum(neighbor_phases) / len(neighbor_phases)
+        phase_diff = abs(theta - mean_neighbor_phase)
+        phase_coupling = 1.0 - min(phase_diff, math.pi) / math.pi
+
+        if phase_coupling < min_coupling:
+            return (True, CollapseReason.NETWORK_DECOUPLING)
+
+    # Check EPI dissolution
+    if epi < min_epi:
+        return (True, CollapseReason.EPI_DISSOLUTION)
+
+    return (False, None)
+
+
+def should_collapse(
+    G: TNFRGraph,
+    node: NodeId,
+    *,
+    config: dict[str, Any] | None = None,
+) -> bool:
+    """Check if node should collapse (simplified interface).
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph containing the node
+    node : NodeId
+        Node to check
+    config : dict, optional
+        Configuration overrides
+
+    Returns
+    -------
+    bool
+        True if node meets collapse conditions
+
+    See Also
+    --------
+    check_collapse_conditions : Full collapse check with reason
+    get_lifecycle_state : Complete lifecycle state determination
+    """
+    should_collapse_flag, _ = check_collapse_conditions(G, node, config=config)
+    return should_collapse_flag