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

tnfr/operators/remesh.py

@@ -1,27 +1,61 @@
+"""Adaptive remeshing operators preserving TNFR structural coherence."""
+
 from __future__ import annotations
+
 import hashlib
 import heapq
-from operator import ge, le
+import random
+from collections import deque
+from collections.abc import Hashable, Iterable, Mapping, MutableMapping, Sequence
 from functools import cache
-from itertools import combinations
 from io import StringIO
-from collections import deque
-from statistics import fmean, StatisticsError
+from itertools import combinations
+from operator import ge, le
+from statistics import StatisticsError, fmean
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, cast
 
-from ..cache import edge_version_update
-from ..constants import DEFAULTS, REMESH_DEFAULTS, get_aliases, get_param
-from ..helpers.numeric import kahan_sum_nd
+from .._compat import TypeAlias
 from ..alias import get_attr, set_attr
+from ..constants import DEFAULTS, REMESH_DEFAULTS, get_param
+from ..constants.aliases import ALIAS_EPI
 from ..rng import make_rng
-from ..callback_utils import CallbackEvent, callback_manager
-from ..glyph_history import append_metric, ensure_history, current_step_idx
-from ..import_utils import cached_import
+from ..types import RemeshMeta
+from ..utils import cached_import, edge_version_update, kahan_sum_nd
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from ..callback_utils import CallbackEvent, CallbackManager
+
+CommunityGraph: TypeAlias = Any
+NetworkxModule: TypeAlias = ModuleType
+CommunityModule: TypeAlias = ModuleType
+RemeshEdge: TypeAlias = tuple[Hashable, Hashable]
+NetworkxModules: TypeAlias = tuple[NetworkxModule, CommunityModule]
+RemeshConfigValue: TypeAlias = bool | float | int
+
+
+def _as_float(value: Any, default: float = 0.0) -> float:
+    """Best-effort conversion to ``float`` returning ``default`` on failure."""
+
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _ordered_edge(u: Hashable, v: Hashable) -> RemeshEdge:
+    """Return a deterministic ordering for an undirected edge."""
 
-ALIAS_EPI = get_aliases("EPI")
+    return (u, v) if repr(u) <= repr(v) else (v, u)
+
+
+COOLDOWN_KEY = "REMESH_COOLDOWN_WINDOW"
 
 
 @cache
-def _get_networkx_modules():
+def _get_networkx_modules() -> NetworkxModules:
     nx = cached_import("networkx")
     if nx is None:
         raise ImportError(
@@ -34,30 +68,29 @@ def _get_networkx_modules():
             "networkx.algorithms.community is required for community-based "
             "operations; install 'networkx' to enable this feature"
         )
-    return nx, nx_comm
+    return cast(NetworkxModule, nx), cast(CommunityModule, nx_comm)
 
 
-def _remesh_alpha_info(G):
+def _remesh_alpha_info(G: CommunityGraph) -> tuple[float, str]:
     """Return ``(alpha, source)`` with explicit precedence."""
-    if bool(
-        G.graph.get("REMESH_ALPHA_HARD", REMESH_DEFAULTS["REMESH_ALPHA_HARD"])
-    ):
-        val = float(
-            G.graph.get("REMESH_ALPHA", REMESH_DEFAULTS["REMESH_ALPHA"])
+    if bool(G.graph.get("REMESH_ALPHA_HARD", REMESH_DEFAULTS["REMESH_ALPHA_HARD"])):
+        val = _as_float(
+            G.graph.get("REMESH_ALPHA", REMESH_DEFAULTS["REMESH_ALPHA"]),
+            float(REMESH_DEFAULTS["REMESH_ALPHA"]),
         )
         return val, "REMESH_ALPHA"
     gf = G.graph.get("GLYPH_FACTORS", DEFAULTS.get("GLYPH_FACTORS", {}))
     if "REMESH_alpha" in gf:
-        return float(gf["REMESH_alpha"]), "GLYPH_FACTORS.REMESH_alpha"
+        return _as_float(gf["REMESH_alpha"]), "GLYPH_FACTORS.REMESH_alpha"
     if "REMESH_ALPHA" in G.graph:
-        return float(G.graph["REMESH_ALPHA"]), "REMESH_ALPHA"
+        return _as_float(G.graph["REMESH_ALPHA"]), "REMESH_ALPHA"
     return (
         float(REMESH_DEFAULTS["REMESH_ALPHA"]),
         "REMESH_DEFAULTS.REMESH_ALPHA",
     )
 
 
-def _snapshot_topology(G, nx):
+def _snapshot_topology(G: CommunityGraph, nx: NetworkxModule) -> str | None:
     """Return a hash representing the current graph topology."""
     try:
         n_nodes = G.number_of_nodes()
@@ -69,12 +102,12 @@ def _snapshot_topology(G, nx):
         return None
 
 
-def _snapshot_epi(G):
+def _snapshot_epi(G: CommunityGraph) -> tuple[float, str]:
     """Return ``(mean, checksum)`` of the node EPI values."""
     buf = StringIO()
     values = []
     for n, data in G.nodes(data=True):
-        v = float(get_attr(data, ALIAS_EPI, 0.0))
+        v = _as_float(get_attr(data, ALIAS_EPI, 0.0))
         values.append(v)
         buf.write(f"{str(n)}:{round(v, 6)};")
     total = kahan_sum_nd(((v,) for v in values), dims=1)[0]
@@ -83,19 +116,21 @@ def _snapshot_epi(G):
     return float(mean_val), checksum
 
 
-def _log_remesh_event(G, meta):
+def _log_remesh_event(G: CommunityGraph, meta: RemeshMeta) -> None:
     """Store remesh metadata and optionally log and trigger callbacks."""
+    from ..callback_utils import CallbackEvent, callback_manager
+    from ..glyph_history import append_metric
+
     G.graph["_REMESH_META"] = meta
     if G.graph.get("REMESH_LOG_EVENTS", REMESH_DEFAULTS["REMESH_LOG_EVENTS"]):
         hist = G.graph.setdefault("history", {})
         append_metric(hist, "remesh_events", dict(meta))
-    callback_manager.invoke_callbacks(
-        G, CallbackEvent.ON_REMESH.value, dict(meta)
-    )
+    callback_manager.invoke_callbacks(G, CallbackEvent.ON_REMESH.value, dict(meta))
 
 
-def apply_network_remesh(G) -> None:
+def apply_network_remesh(G: CommunityGraph) -> None:
     """Network-scale REMESH using ``_epi_hist`` with multi-scale memory."""
+    from ..glyph_history import current_step_idx, ensure_history
     nx, _ = _get_networkx_modules()
     tau_g = int(get_param(G, "REMESH_TAU_GLOBAL"))
     tau_l = int(get_param(G, "REMESH_TAU_LOCAL"))
@@ -113,9 +148,13 @@ def apply_network_remesh(G) -> None:
     epi_mean_before, epi_checksum_before = _snapshot_epi(G)
 
     for n, nd in G.nodes(data=True):
-        epi_now = get_attr(nd, ALIAS_EPI, 0.0)
-        epi_old_l = float(past_l.get(n, epi_now))
-        epi_old_g = float(past_g.get(n, epi_now))
+        epi_now = _as_float(get_attr(nd, ALIAS_EPI, 0.0))
+        epi_old_l = _as_float(
+            past_l.get(n) if isinstance(past_l, Mapping) else None, epi_now
+        )
+        epi_old_g = _as_float(
+            past_g.get(n) if isinstance(past_g, Mapping) else None, epi_now
+        )
         mixed = (1 - alpha) * epi_now + alpha * epi_old_l
         mixed = (1 - alpha) * mixed + alpha * epi_old_g
         set_attr(nd, ALIAS_EPI, mixed)
@@ -123,7 +162,7 @@ def apply_network_remesh(G) -> None:
     epi_mean_after, epi_checksum_after = _snapshot_epi(G)
 
     step_idx = current_step_idx(G)
-    meta = {
+    meta: RemeshMeta = {
         "alpha": alpha,
         "alpha_source": alpha_src,
         "tau_global": tau_g,
@@ -148,20 +187,27 @@ def apply_network_remesh(G) -> None:
     _log_remesh_event(G, meta)
 
 
-def _mst_edges_from_epi(nx, nodes, epi):
+def _mst_edges_from_epi(
+    nx: NetworkxModule,
+    nodes: Sequence[Hashable],
+    epi: Mapping[Hashable, float],
+) -> set[RemeshEdge]:
     """Return MST edges based on absolute EPI distance."""
     H = nx.Graph()
     H.add_nodes_from(nodes)
     H.add_weighted_edges_from(
         (u, v, abs(epi[u] - epi[v])) for u, v in combinations(nodes, 2)
     )
-    return {
-        tuple(sorted((u, v)))
-        for u, v in nx.minimum_spanning_edges(H, data=False)
-    }
+    return {_ordered_edge(u, v) for u, v in nx.minimum_spanning_edges(H, data=False)}
 
 
-def _knn_edges(nodes, epi, k_val, p_rewire, rnd):
+def _knn_edges(
+    nodes: Sequence[Hashable],
+    epi: Mapping[Hashable, float],
+    k_val: int,
+    p_rewire: float,
+    rnd: random.Random,
+) -> set[RemeshEdge]:
     """Edges linking each node to its ``k`` nearest neighbours in EPI."""
     new_edges = set()
     node_set = set(nodes)
@@ -179,17 +225,21 @@ def _knn_edges(nodes, epi, k_val, p_rewire, rnd):
                 choices = list(node_set - {u, v})
                 if choices:
                     v = rnd.choice(choices)
-            new_edges.add(tuple(sorted((u, v))))
+            new_edges.add(_ordered_edge(u, v))
     return new_edges
 
 
-def _community_graph(comms, epi, nx):
+def _community_graph(
+    comms: Iterable[Iterable[Hashable]],
+    epi: Mapping[Hashable, float],
+    nx: NetworkxModule,
+) -> CommunityGraph:
     """Return community graph ``C`` with mean EPI per community."""
     C = nx.Graph()
     for idx, comm in enumerate(comms):
         members = list(comm)
         try:
-            epi_mean = fmean(epi[n] for n in members)
+            epi_mean = fmean(_as_float(epi.get(n)) for n in members)
         except StatisticsError:
             epi_mean = 0.0
         C.add_node(idx)
@@ -197,16 +247,21 @@ def _community_graph(comms, epi, nx):
         C.nodes[idx]["members"] = members
     for i, j in combinations(C.nodes(), 2):
         w = abs(
-            get_attr(C.nodes[i], ALIAS_EPI, 0.0)
-            - get_attr(C.nodes[j], ALIAS_EPI, 0.0)
+            _as_float(get_attr(C.nodes[i], ALIAS_EPI, 0.0))
+            - _as_float(get_attr(C.nodes[j], ALIAS_EPI, 0.0))
         )
         C.add_edge(i, j, weight=w)
-    return C
+    return cast(CommunityGraph, C)
 
 
-def _community_k_neighbor_edges(C, k_val, p_rewire, rnd):
+def _community_k_neighbor_edges(
+    C: CommunityGraph,
+    k_val: int,
+    p_rewire: float,
+    rnd: random.Random,
+) -> tuple[set[RemeshEdge], dict[int, int], list[tuple[int, int, int]]]:
     """Edges linking each community to its ``k`` nearest neighbours."""
-    epi_vals = {n: get_attr(C.nodes[n], ALIAS_EPI, 0.0) for n in C.nodes()}
+    epi_vals = {n: _as_float(get_attr(C.nodes[n], ALIAS_EPI, 0.0)) for n in C.nodes()}
     ordered = sorted(C.nodes(), key=lambda v: epi_vals[v])
     new_edges = set()
     attempts = {n: 0 for n in C.nodes()}
@@ -240,7 +295,7 @@ def _community_k_neighbor_edges(C, k_val, p_rewire, rnd):
                 if choices:
                     v = rnd.choice(choices)
                     rewired_now = True
-            new_edges.add(tuple(sorted((u, v))))
+            new_edges.add(_ordered_edge(u, v))
             attempts[u] += 1
             if rewired_now:
                 rewired.append((u, original_v, v))
@@ -249,17 +304,18 @@ def _community_k_neighbor_edges(C, k_val, p_rewire, rnd):
 
 
 def _community_remesh(
-    G,
-    epi,
-    k_val,
-    p_rewire,
-    rnd,
-    nx,
-    nx_comm,
-    mst_edges,
-    n_before,
-):
+    G: CommunityGraph,
+    epi: Mapping[Hashable, float],
+    k_val: int,
+    p_rewire: float,
+    rnd: random.Random,
+    nx: NetworkxModule,
+    nx_comm: CommunityModule,
+    mst_edges: Iterable[RemeshEdge],
+    n_before: int,
+) -> None:
     """Remesh ``G`` replacing nodes by modular communities."""
+    from ..glyph_history import append_metric
     comms = list(nx_comm.greedy_modularity_communities(G))
     if len(comms) <= 1:
         with edge_version_update(G):
@@ -268,7 +324,7 @@ def _community_remesh(
         return
     C = _community_graph(comms, epi, nx)
     mst_c = nx.minimum_spanning_tree(C, weight="weight")
-    new_edges = set(mst_c.edges())
+    new_edges: set[RemeshEdge] = {_ordered_edge(u, v) for u, v in mst_c.edges()}
     extra_edges, attempts, rewired_edges = _community_k_neighbor_edges(
         C, k_val, p_rewire, rnd
     )
@@ -312,7 +368,7 @@ def _community_remesh(
 
 
 def apply_topological_remesh(
-    G,
+    G: CommunityGraph,
     mode: str | None = None,
     *,
     k: int | None = None,
@@ -324,6 +380,7 @@ def apply_topological_remesh(
     When ``seed`` is ``None`` the RNG draws its base seed from
     ``G.graph['RANDOM_SEED']`` to keep runs reproducible.
     """
+    from ..glyph_history import append_metric
     nodes = list(G.nodes())
     n_before = len(nodes)
     if n_before <= 1:
@@ -336,18 +393,14 @@ def apply_topological_remesh(
 
     if mode is None:
         mode = str(
-            G.graph.get(
-                "REMESH_MODE", REMESH_DEFAULTS.get("REMESH_MODE", "knn")
-            )
+            G.graph.get("REMESH_MODE", REMESH_DEFAULTS.get("REMESH_MODE", "knn"))
         )
     mode = str(mode)
     nx, nx_comm = _get_networkx_modules()
-    epi = {n: get_attr(G.nodes[n], ALIAS_EPI, 0.0) for n in nodes}
+    epi = {n: _as_float(get_attr(G.nodes[n], ALIAS_EPI, 0.0)) for n in nodes}
     mst_edges = _mst_edges_from_epi(nx, nodes, epi)
     default_k = int(
-        G.graph.get(
-            "REMESH_COMMUNITY_K", REMESH_DEFAULTS.get("REMESH_COMMUNITY_K", 2)
-        )
+        G.graph.get("REMESH_COMMUNITY_K", REMESH_DEFAULTS.get("REMESH_COMMUNITY_K", 2))
     )
     k_val = max(1, int(k) if k is not None else default_k)
 
@@ -374,7 +427,11 @@ def apply_topological_remesh(
         G.add_edges_from(new_edges)
 
 
-def _extra_gating_ok(hist, cfg, w_estab):
+def _extra_gating_ok(
+    hist: MutableMapping[str, Sequence[float]],
+    cfg: Mapping[str, RemeshConfigValue],
+    w_estab: int,
+) -> bool:
     """Check additional stability gating conditions."""
     checks = [
         ("phase_sync", "REMESH_MIN_PHASE_SYNC", ge),
@@ -388,14 +445,27 @@ def _extra_gating_ok(hist, cfg, w_estab):
         if series is not None and len(series) >= w_estab:
             win = series[-w_estab:]
             avg = sum(win) / len(win)
-            if not op(avg, cfg[cfg_key]):
+            threshold = _as_float(cfg[cfg_key])
+            if not op(avg, threshold):
                 return False
     return True
 
 
 def apply_remesh_if_globally_stable(
-    G, pasos_estables_consecutivos: int | None = None
+    G: CommunityGraph,
+    stable_step_window: int | None = None,
+    **kwargs: Any,
 ) -> None:
+    """Trigger remeshing when global stability indicators satisfy thresholds."""
+
+    from ..glyph_history import ensure_history
+    if kwargs:
+        unexpected = ", ".join(sorted(kwargs))
+        raise TypeError(
+            "apply_remesh_if_globally_stable() got unexpected keyword argument(s): "
+            f"{unexpected}"
+        )
+
     params = [
         (
             "REMESH_STABILITY_WINDOW",
@@ -432,20 +502,16 @@ def apply_remesh_if_globally_stable(
             float,
             REMESH_DEFAULTS["REMESH_MIN_SI_HI_FRAC"],
         ),
-        (
-            "REMESH_COOLDOWN_VENTANA",
-            int,
-            REMESH_DEFAULTS["REMESH_COOLDOWN_VENTANA"],
-        ),
+        (COOLDOWN_KEY, int, REMESH_DEFAULTS[COOLDOWN_KEY]),
         ("REMESH_COOLDOWN_TS", float, REMESH_DEFAULTS["REMESH_COOLDOWN_TS"]),
     ]
     cfg = {}
     for key, conv, _default in params:
         cfg[key] = conv(get_param(G, key))
-    frac_req = float(get_param(G, "FRACTION_STABLE_REMESH"))
+    frac_req = _as_float(get_param(G, "FRACTION_STABLE_REMESH"))
     w_estab = (
-        pasos_estables_consecutivos
-        if pasos_estables_consecutivos is not None
+        stable_step_window
+        if stable_step_window is not None
         else cfg["REMESH_STABILITY_WINDOW"]
     )
 
@@ -456,21 +522,16 @@ def apply_remesh_if_globally_stable(
     win_sf = sf[-w_estab:]
     if not all(v >= frac_req for v in win_sf):
         return
-    if cfg["REMESH_REQUIRE_STABILITY"] and not _extra_gating_ok(
-        hist, cfg, w_estab
-    ):
+    if cfg["REMESH_REQUIRE_STABILITY"] and not _extra_gating_ok(hist, cfg, w_estab):
         return
 
     last = G.graph.get("_last_remesh_step", -(10**9))
     step_idx = len(sf)
-    if step_idx - last < cfg["REMESH_COOLDOWN_VENTANA"]:
+    if step_idx - last < cfg[COOLDOWN_KEY]:
         return
-    t_now = float(G.graph.get("_t", 0.0))
-    last_ts = float(G.graph.get("_last_remesh_ts", -1e12))
-    if (
-        cfg["REMESH_COOLDOWN_TS"] > 0
-        and (t_now - last_ts) < cfg["REMESH_COOLDOWN_TS"]
-    ):
+    t_now = _as_float(G.graph.get("_t", 0.0))
+    last_ts = _as_float(G.graph.get("_last_remesh_ts", -1e12))
+    if cfg["REMESH_COOLDOWN_TS"] > 0 and (t_now - last_ts) < cfg["REMESH_COOLDOWN_TS"]:
         return
 
     apply_network_remesh(G)