tnfr 6.0.0__py3-none-any.whl → 7.0.0__py3-none-any.whl

tnfr/dynamics/adaptation.py

@@ -8,7 +8,7 @@ from typing import Any, cast
 
 from ..alias import collect_attr, set_vf
 from ..constants import get_graph_param
-from ..helpers.numeric import clamp
+from ..utils import clamp, resolve_chunk_size
 from ..metrics.common import ensure_neighbors_map
 from ..types import CoherenceMetric, DeltaNFR, NodeId, TNFRGraph
 from ..utils import get_numpy
@@ -18,7 +18,7 @@ __all__ = ("adapt_vf_by_coherence",)
 
 
 def _vf_adapt_chunk(
-    args: tuple[list[tuple[Any, int, tuple[int, ...]]], tuple[float, ...], float]
+    args: tuple[list[tuple[Any, int, tuple[int, ...]]], tuple[float, ...], float],
 ) -> list[tuple[Any, float]]:
     """Return proposed νf updates for ``chunk`` of stable nodes."""
 
@@ -35,7 +35,71 @@ def _vf_adapt_chunk(
 
 
 def adapt_vf_by_coherence(G: TNFRGraph, n_jobs: int | None = None) -> None:
-    """Adjust νf toward neighbour mean in nodes with sustained stability."""
+    """Synchronise νf to the neighbour mean once ΔNFR and Si stay coherent.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph that stores the TNFR nodes and configuration required for
+        adaptation. The routine reads ``VF_ADAPT_TAU`` (τ) to decide how many
+        consecutive stable steps a node must accumulate in ``stable_count``
+        before updating. The adaptation weight ``VF_ADAPT_MU`` (μ) controls how
+        quickly νf moves toward the neighbour mean. Stability is detected when
+        the absolute ΔNFR stays below ``EPS_DNFR_STABLE`` and the sense index Si
+        exceeds the selector threshold ``SELECTOR_THRESHOLDS['si_hi']`` (falling
+        back to ``GLYPH_THRESHOLDS['hi']``). Only nodes that satisfy both
+        thresholds for τ successive evaluations are eligible for μ-weighted
+        averaging.
+    n_jobs : int or None, optional
+        Number of worker processes used for eligible nodes. ``None`` (the
+        default) keeps the adaptation serial, ``1`` disables parallelism, and
+        any value greater than one dispatches chunks of nodes to a
+        :class:`~concurrent.futures.ProcessPoolExecutor` so large graphs can
+        adjust νf without blocking the main dynamic loop.
+
+    Returns
+    -------
+    None
+        The graph is updated in place; no value is returned.
+
+    Raises
+    ------
+    KeyError
+        Raised when ``G.graph`` lacks the canonical adaptation parameters and
+        defaults have not been injected.
+
+    Examples
+    --------
+    >>> from tnfr.constants import inject_defaults
+    >>> from tnfr.dynamics import adapt_vf_by_coherence
+    >>> from tnfr.structural import create_nfr
+    >>> G, seed = create_nfr("seed", vf=0.2)
+    >>> _, anchor = create_nfr("anchor", graph=G, vf=1.0)
+    >>> G.add_edge(seed, anchor)
+    >>> inject_defaults(G)
+    >>> G.graph["VF_ADAPT_TAU"] = 2      # τ: consecutive stable steps
+    >>> G.graph["VF_ADAPT_MU"] = 0.5      # μ: neighbour coupling strength
+    >>> G.graph["SELECTOR_THRESHOLDS"] = {"si_hi": 0.8}
+    >>> for node in G.nodes:
+    ...     G.nodes[node]["Si"] = 0.9      # above ΔSi threshold
+    ...     G.nodes[node]["ΔNFR"] = 0.0    # within |ΔNFR| ≤ eps guard
+    ...     G.nodes[node]["stable_count"] = 1
+    >>> adapt_vf_by_coherence(G)
+    >>> round(G.nodes[seed]["νf"], 2), round(G.nodes[anchor]["νf"], 2)
+    (0.6, 0.6)
+    >>> G.nodes[seed]["stable_count"], G.nodes[anchor]["stable_count"] >= 2
+    (2, True)
+    """
+
+    required_keys = ("VF_ADAPT_TAU", "VF_ADAPT_MU")
+    missing_keys = [key for key in required_keys if key not in G.graph]
+    if missing_keys:
+        missing_list = ", ".join(sorted(missing_keys))
+        raise KeyError(
+            "adapt_vf_by_coherence requires graph parameters "
+            f"{missing_list}; call tnfr.constants.inject_defaults(G) "
+            "before adaptation."
+        )
 
     tau = get_graph_param(G, "VF_ADAPT_TAU", int)
     mu = float(get_graph_param(G, "VF_ADAPT_MU"))
@@ -141,10 +205,11 @@ def adapt_vf_by_coherence(G: TNFRGraph, n_jobs: int | None = None) -> None:
 
     prev_counts = [int(G.nodes[node].get("stable_count", 0)) for node in nodes]
     stable_flags = [
-        si >= si_hi and dnfr <= eps_dnfr
-        for si, dnfr in zip(si_list, dnfr_list)
+        si >= si_hi and dnfr <= eps_dnfr for si, dnfr in zip(si_list, dnfr_list)
+    ]
+    new_counts = [
+        prev + 1 if flag else 0 for prev, flag in zip(prev_counts, stable_flags)
     ]
-    new_counts = [prev + 1 if flag else 0 for prev, flag in zip(prev_counts, stable_flags)]
 
     for node, count in zip(nodes, new_counts):
         G.nodes[node]["stable_count"] = int(count)
@@ -174,16 +239,18 @@ def adapt_vf_by_coherence(G: TNFRGraph, n_jobs: int | None = None) -> None:
     for node in eligible_nodes:
         idx = node_index[node]
         neigh_indices = tuple(
-            node_index[nbr]
-            for nbr in neighbors_map.get(node, ())
-            if nbr in node_index
+            node_index[nbr] for nbr in neighbors_map.get(node, ()) if nbr in node_index
         )
         work_items.append((node, idx, neigh_indices))
 
-    chunk_size = max(1, math.ceil(len(work_items) / jobs))
+    approx_chunk = math.ceil(len(work_items) / jobs) if jobs else None
+    chunk_size = resolve_chunk_size(
+        approx_chunk,
+        len(work_items),
+        minimum=1,
+    )
     chunks = [
-        work_items[i : i + chunk_size]
-        for i in range(0, len(work_items), chunk_size)
+        work_items[i : i + chunk_size] for i in range(0, len(work_items), chunk_size)
     ]
     vf_tuple = tuple(vf_list)
     updates: dict[Any, float] = {}
@@ -198,4 +265,3 @@ def adapt_vf_by_coherence(G: TNFRGraph, n_jobs: int | None = None) -> None:
         if vf_new is None:
             continue
         set_vf(G, node, clamp(float(vf_new), vf_min, vf_max))
-

tnfr/dynamics/aliases.py

@@ -2,21 +2,22 @@
 
 from __future__ import annotations
 
-from ..constants import get_aliases
-
-ALIAS_VF = get_aliases("VF")
-ALIAS_DNFR = get_aliases("DNFR")
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_SI = get_aliases("SI")
-ALIAS_D2EPI = get_aliases("D2EPI")
-ALIAS_DSI = get_aliases("DSI")
+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/coordination.py

@@ -6,8 +6,7 @@ import math
 from collections import deque
 from collections.abc import Mapping, MutableMapping, Sequence
 from concurrent.futures import ProcessPoolExecutor
-from typing import TYPE_CHECKING, Any, TypeVar, cast
-
+from typing import Any, TypeVar, cast
 from ..alias import get_theta_attr, set_theta
 from ..constants import (
     DEFAULTS,
@@ -18,25 +17,13 @@ from ..constants import (
     normalise_state_token,
 )
 from ..glyph_history import append_metric
-from ..helpers.numeric import angle_diff
+from ..utils import angle_diff, resolve_chunk_size
 from ..metrics.common import ensure_neighbors_map
 from ..metrics.trig import neighbor_phase_mean_list
 from ..metrics.trig_cache import get_trig_cache
 from ..observers import DEFAULT_GLYPH_LOAD_SPAN, glyph_load, kuramoto_order
-from ..types import NodeId, Phase, TNFRGraph
+from ..types import FloatArray, NodeId, Phase, TNFRGraph
 from ..utils import get_numpy
-from .._compat import TypeAlias
-
-if TYPE_CHECKING:  # pragma: no cover - typing imports only
-    try:
-        import numpy as np_typing
-        import numpy.typing as npt
-    except ImportError:  # pragma: no cover - optional typing dependency
-        FloatArray: TypeAlias = Any
-    else:
-        FloatArray: TypeAlias = npt.NDArray[np_typing.float_]
-else:  # pragma: no cover - runtime without numpy typing
-    FloatArray: TypeAlias = Any
 
 _DequeT = TypeVar("_DequeT")
 
@@ -111,9 +98,7 @@ def _smooth_adjust_k(
 
     if state == STATE_DISSONANT:
         kG_t = kG_max
-        kL_t = 0.5 * (
-            kL_min + kL_max
-        )  # local medio para no perder plasticidad
+        kL_t = 0.5 * (kL_min + kL_max)  # keep kL mid-range to preserve local plasticity
     elif state == STATE_STABLE:
         kG_t = kG_min
         kL_t = kL_min
@@ -172,13 +157,71 @@ def coordinate_global_local_phase(
     *,
     n_jobs: int | None = None,
 ) -> None:
-    """Coordinate phase using a blend of global and neighbour coupling."""
+    """Coordinate phase using a blend of global and neighbour coupling.
+
+    This operator harmonises a TNFR graph by iteratively nudging each node's
+    phase toward the global Kuramoto mean while respecting the local
+    neighbourhood attractor. The global (``kG``) and local (``kL``) coupling
+    gains reshape phase coherence by modulating how strongly nodes follow the
+    network-wide synchrony versus immediate neighbours. When explicit coupling
+    overrides are not supplied, the gains adapt based on current ΔNFR telemetry
+    and the structural state recorded in the graph history. Adaptive updates
+    mutate the ``history`` buffers for phase state, order parameter, disruptor
+    load, and the stored coupling gains.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Graph whose nodes expose TNFR phase attributes and ΔNFR telemetry. The
+        graph's ``history`` mapping is updated in-place when adaptive gain
+        smoothing is active.
+    global_force : float, optional
+        Override for the global coupling gain ``kG``. When provided, adaptive
+        gain estimation is skipped and the global history buffers are left
+        untouched.
+    local_force : float, optional
+        Override for the local coupling gain ``kL``. Analogous to
+        ``global_force``, the adaptive pathway is bypassed when supplied.
+    n_jobs : int, optional
+        Maximum number of worker processes for distributing local updates.
+        Values of ``None`` or ``<=1`` perform updates sequentially. NumPy
+        availability forces sequential execution because vectorised updates are
+        faster than multiprocess handoffs.
+
+    Returns
+    -------
+    None
+        This operator updates node phases in-place and does not allocate a new
+        graph structure.
+
+    Examples
+    --------
+    Coordinate phase on a minimal TNFR network while inspecting ΔNFR telemetry
+    and history traces::
+
+        >>> import networkx as nx
+        >>> from tnfr.dynamics.coordination import coordinate_global_local_phase
+        >>> G = nx.Graph()
+        >>> G.add_nodes_from(("a", {"theta": 0.0, "ΔNFR": 0.08}),
+        ...                   ("b", {"theta": 1.2, "ΔNFR": -0.05}))
+        >>> G.add_edge("a", "b")
+        >>> G.graph["history"] = {}
+        >>> coordinate_global_local_phase(G)
+        >>> list(round(G.nodes[n]["theta"], 3) for n in G)
+        [0.578, 0.622]
+        >>> history = G.graph["history"]
+        >>> sorted(history)
+        ['phase_R', 'phase_disr', 'phase_kG', 'phase_kL', 'phase_state']
+        >>> history["phase_kG"][-1] <= history["phase_kL"][-1]
+        True
+
+    The resulting history buffers allow downstream observers to correlate
+    ΔNFR adjustments with phase telemetry snapshots.
+    """
 
     g = cast(dict[str, Any], G.graph)
     hist = cast(dict[str, Any], g.setdefault("history", {}))
-    maxlen = int(
-        g.get("PHASE_HISTORY_MAXLEN", METRIC_DEFAULTS["PHASE_HISTORY_MAXLEN"])
-    )
+    maxlen = int(g.get("PHASE_HISTORY_MAXLEN", METRIC_DEFAULTS["PHASE_HISTORY_MAXLEN"]))
     hist_state = cast(deque[str], _ensure_hist_deque(hist, "phase_state", maxlen))
     if hist_state:
         normalised_states = [normalise_state_token(item) for item in hist_state]
@@ -254,12 +297,10 @@ def coordinate_global_local_phase(
 
     theta_vals = [_theta_value(n) for n in nodes]
     cos_vals = [
-        float(cos_map.get(n, math.cos(theta_vals[idx])))
-        for idx, n in enumerate(nodes)
+        float(cos_map.get(n, math.cos(theta_vals[idx]))) for idx, n in enumerate(nodes)
     ]
     sin_vals = [
-        float(sin_map.get(n, math.sin(theta_vals[idx])))
-        for idx, n in enumerate(nodes)
+        float(sin_map.get(n, math.sin(theta_vals[idx]))) for idx, n in enumerate(nodes)
     ]
 
     if np is not None:
@@ -283,8 +324,8 @@ def coordinate_global_local_phase(
             for idx, n in enumerate(nodes)
         ]
         neighbor_arr = cast(FloatArray, np.fromiter(neighbor_means, dtype=float))
-        theta_updates = theta_arr + kG * (thG - theta_arr) + kL * (
-            neighbor_arr - theta_arr
+        theta_updates = (
+            theta_arr + kG * (thG - theta_arr) + kL * (neighbor_arr - theta_arr)
         )
         for idx, node in enumerate(nodes):
             set_theta(G, node, float(theta_updates[int(idx)]))
@@ -313,11 +354,13 @@ def coordinate_global_local_phase(
             set_theta(G, node, float(th + kG * dG + kL * dL))
         return
 
-    chunk_size = max(1, math.ceil(len(nodes) / jobs))
-    chunks = [
-        nodes[idx : idx + chunk_size]
-        for idx in range(0, len(nodes), chunk_size)
-    ]
+    approx_chunk = math.ceil(len(nodes) / jobs) if jobs else None
+    chunk_size = resolve_chunk_size(
+        approx_chunk,
+        len(nodes),
+        minimum=1,
+    )
+    chunks = [nodes[idx : idx + chunk_size] for idx in range(0, len(nodes), chunk_size)]
     args: list[ChunkArgs] = [
         (
             chunk,
@@ -340,4 +383,3 @@ def coordinate_global_local_phase(
         new_theta = results.get(node)
         base_theta = theta_map.get(node, 0.0)
         set_theta(G, node, float(new_theta if new_theta is not None else base_theta))
-