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

tnfr/dynamics/__init__.pyi

@@ -0,0 +1,83 @@
+from typing import Any, Literal, Sequence
+
+from tnfr.types import TNFRGraph
+
+__all__: tuple[str, ...]
+
+dnfr: Any
+integrators: Any
+
+ALIAS_D2EPI: Sequence[str]
+ALIAS_DNFR: Sequence[str]
+ALIAS_DSI: Sequence[str]
+ALIAS_EPI: Sequence[str]
+ALIAS_SI: Sequence[str]
+ALIAS_VF: Sequence[str]
+
+AbstractSelector: Any
+DefaultGlyphSelector: Any
+GlyphCode: Any
+ParametricGlyphSelector: Any
+_SelectorPreselection: Any
+_apply_glyphs: Any
+_apply_selector: Any
+_choose_glyph: Any
+_configure_selector_weights: Any
+ProcessPoolExecutor: Any
+_maybe_remesh: Any
+_normalize_job_overrides: Any
+_prepare_dnfr: Any
+_prepare_dnfr_data: Any
+_prepare_selector_preselection: Any
+_resolve_jobs_override: Any
+_resolve_preselected_glyph: Any
+_run_after_callbacks: Any
+_run_before_callbacks: Any
+_run_validators: Any
+_selector_parallel_jobs: Any
+_update_epi_hist: Any
+_update_node_sample: Any
+_update_nodes: Any
+_compute_dnfr: Any
+_compute_neighbor_means: Any
+_init_dnfr_cache: Any
+_refresh_dnfr_vectors: Any
+adapt_vf_by_coherence: Any
+apply_canonical_clamps: Any
+coordinate_global_local_phase: Any
+default_compute_delta_nfr: Any
+default_glyph_selector: Any
+dnfr_epi_vf_mixed: Any
+dnfr_laplacian: Any
+dnfr_phase_only: Any
+enforce_canonical_grammar: Any
+get_numpy: Any
+on_applied_glyph: Any
+apply_glyph: Any
+parametric_glyph_selector: Any
+
+AbstractIntegrator: Any
+DefaultIntegrator: Any
+
+def prepare_integration_params(
+    G: TNFRGraph,
+    dt: float | None = ...,
+    t: float | None = ...,
+    method: Literal["euler", "rk4"] | None = ...,
+) -> tuple[float, int, float, Literal["euler", "rk4"]]: ...
+
+run: Any
+set_delta_nfr_hook: Any
+step: Any
+
+def update_epi_via_nodal_equation(
+    G: TNFRGraph,
+    *,
+    dt: float | None = ...,
+    t: float | None = ...,
+    method: Literal["euler", "rk4"] | None = ...,
+    n_jobs: int | None = ...,
+) -> None: ...
+
+validate_canon: Any
+

tnfr/dynamics/adaptation.py

@@ -0,0 +1,201 @@
+"""νf adaptation routines for TNFR dynamics."""
+
+from __future__ import annotations
+
+import math
+from concurrent.futures import ProcessPoolExecutor
+from typing import Any, cast
+
+from ..alias import collect_attr, set_vf
+from ..constants import get_graph_param
+from ..helpers.numeric import clamp
+from ..metrics.common import ensure_neighbors_map
+from ..types import CoherenceMetric, DeltaNFR, NodeId, TNFRGraph
+from ..utils import get_numpy
+from .aliases import ALIAS_DNFR, ALIAS_SI, ALIAS_VF
+
+__all__ = ("adapt_vf_by_coherence",)
+
+
+def _vf_adapt_chunk(
+    args: tuple[list[tuple[Any, int, tuple[int, ...]]], tuple[float, ...], float]
+) -> list[tuple[Any, float]]:
+    """Return proposed νf updates for ``chunk`` of stable nodes."""
+
+    chunk, vf_values, mu = args
+    updates: list[tuple[Any, float]] = []
+    for node, idx, neighbor_idx in chunk:
+        vf = vf_values[idx]
+        if neighbor_idx:
+            mean = math.fsum(vf_values[j] for j in neighbor_idx) / len(neighbor_idx)
+        else:
+            mean = vf
+        updates.append((node, vf + mu * (mean - vf)))
+    return updates
+
+
+def adapt_vf_by_coherence(G: TNFRGraph, n_jobs: int | None = None) -> None:
+    """Adjust νf toward neighbour mean in nodes with sustained stability."""
+
+    tau = get_graph_param(G, "VF_ADAPT_TAU", int)
+    mu = float(get_graph_param(G, "VF_ADAPT_MU"))
+    eps_dnfr = cast(DeltaNFR, get_graph_param(G, "EPS_DNFR_STABLE"))
+    thr_sel = get_graph_param(G, "SELECTOR_THRESHOLDS", dict)
+    thr_def = get_graph_param(G, "GLYPH_THRESHOLDS", dict)
+    si_hi = cast(
+        CoherenceMetric,
+        float(thr_sel.get("si_hi", thr_def.get("hi", 0.66))),
+    )
+    vf_min = float(get_graph_param(G, "VF_MIN"))
+    vf_max = float(get_graph_param(G, "VF_MAX"))
+
+    nodes = list(G.nodes)
+    if not nodes:
+        return
+
+    neighbors_map = ensure_neighbors_map(G)
+    node_count = len(nodes)
+    node_index = {node: idx for idx, node in enumerate(nodes)}
+
+    jobs: int | None
+    if n_jobs is None:
+        jobs = None
+    else:
+        try:
+            jobs = int(n_jobs)
+        except (TypeError, ValueError):
+            jobs = None
+        else:
+            if jobs <= 1:
+                jobs = None
+
+    np_mod = get_numpy()
+    use_np = np_mod is not None
+
+    si_values = collect_attr(G, nodes, ALIAS_SI, 0.0, np=np_mod if use_np else None)
+    dnfr_values = collect_attr(G, nodes, ALIAS_DNFR, 0.0, np=np_mod if use_np else None)
+    vf_values = collect_attr(G, nodes, ALIAS_VF, 0.0, np=np_mod if use_np else None)
+
+    if use_np:
+        np = np_mod  # type: ignore[assignment]
+        assert np is not None
+        si_arr = si_values.astype(float, copy=False)
+        dnfr_arr = np.abs(dnfr_values.astype(float, copy=False))
+        vf_arr = vf_values.astype(float, copy=False)
+
+        prev_counts = np.fromiter(
+            (int(G.nodes[node].get("stable_count", 0)) for node in nodes),
+            dtype=int,
+            count=node_count,
+        )
+        stable_mask = (si_arr >= si_hi) & (dnfr_arr <= eps_dnfr)
+        new_counts = np.where(stable_mask, prev_counts + 1, 0)
+
+        for node, count in zip(nodes, new_counts.tolist()):
+            G.nodes[node]["stable_count"] = int(count)
+
+        eligible_mask = new_counts >= tau
+        if not bool(eligible_mask.any()):
+            return
+
+        max_degree = 0
+        if node_count:
+            degree_counts = np.fromiter(
+                (len(neighbors_map.get(node, ())) for node in nodes),
+                dtype=int,
+                count=node_count,
+            )
+            if degree_counts.size:
+                max_degree = int(degree_counts.max())
+
+        if max_degree > 0:
+            neighbor_indices = np.zeros((node_count, max_degree), dtype=int)
+            mask = np.zeros((node_count, max_degree), dtype=bool)
+            for idx, node in enumerate(nodes):
+                neigh = neighbors_map.get(node, ())
+                if not neigh:
+                    continue
+                idxs = [node_index[nbr] for nbr in neigh if nbr in node_index]
+                if not idxs:
+                    continue
+                length = len(idxs)
+                neighbor_indices[idx, :length] = idxs
+                mask[idx, :length] = True
+            neighbor_values = vf_arr[neighbor_indices]
+            sums = (neighbor_values * mask).sum(axis=1)
+            counts = mask.sum(axis=1)
+            neighbor_means = np.where(counts > 0, sums / counts, vf_arr)
+        else:
+            neighbor_means = vf_arr
+
+        vf_updates = vf_arr + mu * (neighbor_means - vf_arr)
+        for idx in np.nonzero(eligible_mask)[0]:
+            node = nodes[int(idx)]
+            vf_new = clamp(float(vf_updates[int(idx)]), vf_min, vf_max)
+            set_vf(G, node, vf_new)
+        return
+
+    si_list = [float(val) for val in si_values]
+    dnfr_list = [abs(float(val)) for val in dnfr_values]
+    vf_list = [float(val) for val in vf_values]
+
+    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)
+    ]
+    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)
+
+    eligible_nodes = [node for node, count in zip(nodes, new_counts) if count >= tau]
+    if not eligible_nodes:
+        return
+
+    if jobs is None:
+        for node in eligible_nodes:
+            idx = node_index[node]
+            neigh_indices = [
+                node_index[nbr]
+                for nbr in neighbors_map.get(node, ())
+                if nbr in node_index
+            ]
+            if neigh_indices:
+                total = math.fsum(vf_list[i] for i in neigh_indices)
+                mean = total / len(neigh_indices)
+            else:
+                mean = vf_list[idx]
+            vf_new = vf_list[idx] + mu * (mean - vf_list[idx])
+            set_vf(G, node, clamp(float(vf_new), vf_min, vf_max))
+        return
+
+    work_items: list[tuple[Any, int, tuple[int, ...]]] = []
+    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
+        )
+        work_items.append((node, idx, neigh_indices))
+
+    chunk_size = max(1, math.ceil(len(work_items) / jobs))
+    chunks = [
+        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] = {}
+    with ProcessPoolExecutor(max_workers=jobs) as executor:
+        args = ((chunk, vf_tuple, mu) for chunk in chunks)
+        for chunk_updates in executor.map(_vf_adapt_chunk, args):
+            for node, value in chunk_updates:
+                updates[node] = float(value)
+
+    for node in eligible_nodes:
+        vf_new = updates.get(node)
+        if vf_new is None:
+            continue
+        set_vf(G, node, clamp(float(vf_new), vf_min, vf_max))
+

tnfr/dynamics/aliases.py

@@ -0,0 +1,22 @@
+"""Shared alias tokens used across TNFR dynamics submodules."""
+
+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")
+
+__all__ = (
+    "ALIAS_VF",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_SI",
+    "ALIAS_D2EPI",
+    "ALIAS_DSI",
+)
+

tnfr/dynamics/coordination.py

@@ -0,0 +1,343 @@
+"""Phase coordination helpers for TNFR dynamics."""
+
+from __future__ import annotations
+
+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 ..alias import get_theta_attr, set_theta
+from ..constants import (
+    DEFAULTS,
+    METRIC_DEFAULTS,
+    STATE_DISSONANT,
+    STATE_STABLE,
+    STATE_TRANSITION,
+    normalise_state_token,
+)
+from ..glyph_history import append_metric
+from ..helpers.numeric import angle_diff
+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 ..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")
+
+ChunkArgs = tuple[
+    Sequence[NodeId],
+    Mapping[NodeId, Phase],
+    Mapping[NodeId, float],
+    Mapping[NodeId, float],
+    Mapping[NodeId, Sequence[NodeId]],
+    float,
+    float,
+    float,
+]
+
+__all__ = ("coordinate_global_local_phase",)
+
+
+def _ensure_hist_deque(
+    hist: MutableMapping[str, Any], key: str, maxlen: int
+) -> deque[_DequeT]:
+    """Ensure history entry ``key`` is a deque with ``maxlen``."""
+
+    dq = hist.setdefault(key, deque(maxlen=maxlen))
+    if not isinstance(dq, deque):
+        dq = deque(dq, maxlen=maxlen)
+        hist[key] = dq
+    return cast("deque[_DequeT]", dq)
+
+
+def _read_adaptive_params(
+    g: Mapping[str, Any],
+) -> tuple[Mapping[str, Any], float, float]:
+    """Obtain configuration and current values for phase adaptation."""
+
+    cfg = g.get("PHASE_ADAPT", DEFAULTS.get("PHASE_ADAPT", {}))
+    kG = float(g.get("PHASE_K_GLOBAL", DEFAULTS["PHASE_K_GLOBAL"]))
+    kL = float(g.get("PHASE_K_LOCAL", DEFAULTS["PHASE_K_LOCAL"]))
+    return cast(Mapping[str, Any], cfg), kG, kL
+
+
+def _compute_state(G: TNFRGraph, cfg: Mapping[str, Any]) -> tuple[str, float, float]:
+    """Return the canonical network state and supporting metrics."""
+
+    R = kuramoto_order(G)
+    dist = glyph_load(G, window=DEFAULT_GLYPH_LOAD_SPAN)
+    disr = float(dist.get("_disruptors", 0.0)) if dist else 0.0
+
+    R_hi = float(cfg.get("R_hi", 0.90))
+    R_lo = float(cfg.get("R_lo", 0.60))
+    disr_hi = float(cfg.get("disr_hi", 0.50))
+    disr_lo = float(cfg.get("disr_lo", 0.25))
+    if (R >= R_hi) and (disr <= disr_lo):
+        state = STATE_STABLE
+    elif (R <= R_lo) or (disr >= disr_hi):
+        state = STATE_DISSONANT
+    else:
+        state = STATE_TRANSITION
+    return state, float(R), disr
+
+
+def _smooth_adjust_k(
+    kG: float, kL: float, state: str, cfg: Mapping[str, Any]
+) -> tuple[float, float]:
+    """Smoothly update kG/kL toward targets according to state."""
+
+    kG_min = float(cfg.get("kG_min", 0.01))
+    kG_max = float(cfg.get("kG_max", 0.20))
+    kL_min = float(cfg.get("kL_min", 0.05))
+    kL_max = float(cfg.get("kL_max", 0.25))
+
+    state = normalise_state_token(state)
+
+    if state == STATE_DISSONANT:
+        kG_t = kG_max
+        kL_t = 0.5 * (
+            kL_min + kL_max
+        )  # local medio para no perder plasticidad
+    elif state == STATE_STABLE:
+        kG_t = kG_min
+        kL_t = kL_min
+    else:
+        kG_t = 0.5 * (kG_min + kG_max)
+        kL_t = 0.5 * (kL_min + kL_max)
+
+    up = float(cfg.get("up", 0.10))
+    down = float(cfg.get("down", 0.07))
+
+    def _step(curr: float, target: float, mn: float, mx: float) -> float:
+        gain = up if target > curr else down
+        nxt = curr + gain * (target - curr)
+        return max(mn, min(mx, nxt))
+
+    return _step(kG, kG_t, kG_min, kG_max), _step(kL, kL_t, kL_min, kL_max)
+
+
+def _phase_adjust_chunk(args: ChunkArgs) -> list[tuple[NodeId, Phase]]:
+    """Return coordinated phase updates for the provided chunk."""
+
+    (
+        nodes,
+        theta_map,
+        cos_map,
+        sin_map,
+        neighbors_map,
+        thG,
+        kG,
+        kL,
+    ) = args
+    updates: list[tuple[NodeId, Phase]] = []
+    for node in nodes:
+        th = float(theta_map.get(node, 0.0))
+        neigh = neighbors_map.get(node, ())
+        if neigh:
+            thL = neighbor_phase_mean_list(
+                neigh,
+                cos_map,
+                sin_map,
+                np=None,
+                fallback=th,
+            )
+        else:
+            thL = th
+        dG = angle_diff(thG, th)
+        dL = angle_diff(thL, th)
+        updates.append((node, cast(Phase, th + kG * dG + kL * dL)))
+    return updates
+
+
+def coordinate_global_local_phase(
+    G: TNFRGraph,
+    global_force: float | None = None,
+    local_force: float | None = None,
+    *,
+    n_jobs: int | None = None,
+) -> None:
+    """Coordinate phase using a blend of global and neighbour coupling."""
+
+    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"])
+    )
+    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]
+        if normalised_states != list(hist_state):
+            hist_state.clear()
+            hist_state.extend(normalised_states)
+    hist_R = cast(deque[float], _ensure_hist_deque(hist, "phase_R", maxlen))
+    hist_disr = cast(deque[float], _ensure_hist_deque(hist, "phase_disr", maxlen))
+
+    if (global_force is not None) or (local_force is not None):
+        kG = float(
+            global_force
+            if global_force is not None
+            else g.get("PHASE_K_GLOBAL", DEFAULTS["PHASE_K_GLOBAL"])
+        )
+        kL = float(
+            local_force
+            if local_force is not None
+            else g.get("PHASE_K_LOCAL", DEFAULTS["PHASE_K_LOCAL"])
+        )
+    else:
+        cfg, kG, kL = _read_adaptive_params(g)
+
+        if bool(cfg.get("enabled", False)):
+            state, R, disr = _compute_state(G, cfg)
+            kG, kL = _smooth_adjust_k(kG, kL, state, cfg)
+
+            hist_state.append(state)
+            hist_R.append(float(R))
+            hist_disr.append(float(disr))
+
+    g["PHASE_K_GLOBAL"] = kG
+    g["PHASE_K_LOCAL"] = kL
+    append_metric(hist, "phase_kG", float(kG))
+    append_metric(hist, "phase_kL", float(kL))
+
+    jobs: int | None
+    try:
+        jobs = None if n_jobs is None else int(n_jobs)
+    except (TypeError, ValueError):
+        jobs = None
+    if jobs is not None and jobs <= 1:
+        jobs = None
+
+    np = get_numpy()
+    if np is not None:
+        jobs = None
+
+    nodes: list[NodeId] = [cast(NodeId, node) for node in G.nodes()]
+    num_nodes = len(nodes)
+    if not num_nodes:
+        return
+
+    trig = get_trig_cache(G, np=np)
+    theta_map = cast(dict[NodeId, Phase], trig.theta)
+    cos_map = cast(dict[NodeId, float], trig.cos)
+    sin_map = cast(dict[NodeId, float], trig.sin)
+
+    neighbors_proxy = ensure_neighbors_map(G)
+    neighbors_map: dict[NodeId, tuple[NodeId, ...]] = {}
+    for n in nodes:
+        try:
+            neighbors_map[n] = tuple(cast(Sequence[NodeId], neighbors_proxy[n]))
+        except KeyError:
+            neighbors_map[n] = ()
+
+    def _theta_value(node: NodeId) -> float:
+        cached = theta_map.get(node)
+        if cached is not None:
+            return float(cached)
+        attr_val = get_theta_attr(G.nodes[node], 0.0)
+        return float(attr_val if attr_val is not None else 0.0)
+
+    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)
+    ]
+    sin_vals = [
+        float(sin_map.get(n, math.sin(theta_vals[idx])))
+        for idx, n in enumerate(nodes)
+    ]
+
+    if np is not None:
+        theta_arr = cast(FloatArray, np.fromiter(theta_vals, dtype=float))
+        cos_arr = cast(FloatArray, np.fromiter(cos_vals, dtype=float))
+        sin_arr = cast(FloatArray, np.fromiter(sin_vals, dtype=float))
+        if cos_arr.size:
+            mean_cos = float(np.mean(cos_arr))
+            mean_sin = float(np.mean(sin_arr))
+            thG = float(np.arctan2(mean_sin, mean_cos))
+        else:
+            thG = 0.0
+        neighbor_means = [
+            neighbor_phase_mean_list(
+                neighbors_map.get(n, ()),
+                cos_map,
+                sin_map,
+                np=np,
+                fallback=theta_vals[idx],
+            )
+            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
+        )
+        for idx, node in enumerate(nodes):
+            set_theta(G, node, float(theta_updates[int(idx)]))
+        return
+
+    mean_cos = math.fsum(cos_vals) / num_nodes
+    mean_sin = math.fsum(sin_vals) / num_nodes
+    thG = math.atan2(mean_sin, mean_cos)
+
+    if jobs is None:
+        for node in nodes:
+            th = float(theta_map.get(node, 0.0))
+            neigh = neighbors_map.get(node, ())
+            if neigh:
+                thL = neighbor_phase_mean_list(
+                    neigh,
+                    cos_map,
+                    sin_map,
+                    np=None,
+                    fallback=th,
+                )
+            else:
+                thL = th
+            dG = angle_diff(thG, th)
+            dL = angle_diff(thL, th)
+            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)
+    ]
+    args: list[ChunkArgs] = [
+        (
+            chunk,
+            theta_map,
+            cos_map,
+            sin_map,
+            neighbors_map,
+            thG,
+            kG,
+            kL,
+        )
+        for chunk in chunks
+    ]
+    results: dict[NodeId, Phase] = {}
+    with ProcessPoolExecutor(max_workers=jobs) as executor:
+        for res in executor.map(_phase_adjust_chunk, args):
+            for node, value in res:
+                results[node] = value
+    for node in nodes:
+        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))
+