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

tnfr/operators/jitter.py

@@ -1,27 +1,31 @@
-from __future__ import annotations
-import threading
+"""Jitter operators for reproducible phase perturbations."""
 
-from typing import Any, TYPE_CHECKING, cast
+from __future__ import annotations
 
-from cachetools import LRUCache
+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 (
-    ScopedCounterCache,
     make_rng,
-    base_seed,
-    cache_enabled,
-    clear_rng_cache as _clear_rng_cache,
     seed_hash,
 )
-from ..cache import CacheManager
-from ..utils import ensure_node_offset_map, get_nodenx
 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 LRU cache bounded to avoid
+# per-scope jitter sequence counters in an instrumented LRU cache bounded to avoid
 # unbounded memory usage.
 _JITTER_MAX_ENTRIES = 1024
 
@@ -35,7 +39,7 @@ class JitterCache:
         *,
         manager: CacheManager | None = None,
     ) -> None:
-        self._manager = manager or CacheManager()
+        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)}
@@ -69,8 +73,8 @@ class JitterCache:
         return self._manager
 
     @property
-    def seq(self) -> LRUCache[tuple[int, int], int]:
-        """Expose the sequence cache for tests and diagnostics."""
+    def seq(self) -> InstrumentedLRUCache[tuple[int, int], int]:
+        """Expose the instrumented sequence cache for tests and diagnostics."""
 
         return self._sequence.cache
 
@@ -99,9 +103,7 @@ class JitterCache:
 
         return cast(dict[str, Any], self._manager.get(self._settings_key))
 
-    def setup(
-        self, force: bool = False, max_entries: int | None = None
-    ) -> None:
+    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)
@@ -133,20 +135,26 @@ class JitterCacheManager:
             self.cache = cache
             self._manager = cache.manager
         else:
-            self._manager = manager or CacheManager()
+            self._manager = manager or build_cache_manager()
             self.cache = JitterCache(manager=self._manager)
 
     # Convenience passthrough properties
     @property
-    def seq(self) -> LRUCache[tuple[int, int], int]:
+    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
@@ -161,9 +169,7 @@ class JitterCacheManager:
 
         self.cache.max_entries = value
 
-    def setup(
-        self, force: bool = False, max_entries: int | None = None
-    ) -> None:
+    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.

tnfr/operators/registry.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import importlib
 import pkgutil
-from typing import Any, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 from ..config.operator_names import canonical_operator_name
 
@@ -67,14 +67,9 @@ def discover_operators() -> None:
     setattr(package, "_operators_discovered", True)
 
 
-__all__ = ("OPERATORS", "register_operator", "discover_operators", "get_operator_class")
-
-
-def __getattr__(name: str) -> Any:
-    """Provide guidance for legacy registry aliases."""
-
-    if name == "OPERADORES":
-        raise AttributeError(
-            f"module '{__name__}' has no attribute '{name}'; use 'OPERATORS' instead."
-        )
-    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+__all__ = (
+    "OPERATORS",
+    "register_operator",
+    "discover_operators",
+    "get_operator_class",
+)

tnfr/operators/registry.pyi

@@ -9,7 +9,5 @@ def __getattr__(name: str) -> Any: ...
 OPERATORS: dict[str, type[Operator]]
 
 def discover_operators() -> None: ...
-
 def register_operator(cls: type[Operator]) -> type[Operator]: ...
-
 def get_operator_class(name: str) -> type[Operator]: ...

tnfr/operators/remesh.py

@@ -1,51 +1,36 @@
+"""Adaptive remeshing operators preserving TNFR structural coherence."""
+
 from __future__ import annotations
 
 import hashlib
 import heapq
 import random
-from operator import ge, le
-from functools import cache
-from itertools import combinations
-from io import StringIO
 from collections import deque
 from collections.abc import Hashable, Iterable, Mapping, MutableMapping, Sequence
-from statistics import fmean, StatisticsError
+from functools import cache
+from io import StringIO
+from itertools import combinations
+from operator import ge, le
+from statistics import StatisticsError, fmean
 from types import ModuleType
-from typing import Any, TypedDict, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from .._compat import TypeAlias
-
-from ..constants import DEFAULTS, REMESH_DEFAULTS, get_aliases, get_param
-from ..helpers.numeric import kahan_sum_nd
 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 ..utils import cached_import, edge_version_update
+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]
-
-
-class RemeshMeta(TypedDict, total=False):
-    alpha: float
-    alpha_source: str
-    tau_global: int
-    tau_local: int
-    step: int | None
-    topo_hash: str | None
-    epi_mean_before: float
-    epi_mean_after: float
-    epi_checksum_before: str
-    epi_checksum_after: str
-    stable_frac_last: float
-    phase_sync_last: float
-    glyph_disr_last: float
-
-
 RemeshConfigValue: TypeAlias = bool | float | int
 
 
@@ -66,9 +51,6 @@ def _ordered_edge(u: Hashable, v: Hashable) -> RemeshEdge:
     return (u, v) if repr(u) <= repr(v) else (v, u)
 
 
-ALIAS_EPI = get_aliases("EPI")
-
-
 COOLDOWN_KEY = "REMESH_COOLDOWN_WINDOW"
 
 
@@ -91,9 +73,7 @@ def _get_networkx_modules() -> NetworkxModules:
 
 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"])
-    ):
+    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"]),
@@ -138,17 +118,19 @@ def _snapshot_epi(G: CommunityGraph) -> tuple[float, str]:
 
 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: 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"))
@@ -167,8 +149,12 @@ def apply_network_remesh(G: CommunityGraph) -> None:
 
     for n, nd in G.nodes(data=True):
         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)
+        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)
@@ -212,10 +198,7 @@ def _mst_edges_from_epi(
     H.add_weighted_edges_from(
         (u, v, abs(epi[u] - epi[v])) for u, v in combinations(nodes, 2)
     )
-    return {
-        _ordered_edge(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(
@@ -332,6 +315,7 @@ def _community_remesh(
     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):
@@ -340,9 +324,7 @@ def _community_remesh(
         return
     C = _community_graph(comms, epi, nx)
     mst_c = nx.minimum_spanning_tree(C, weight="weight")
-    new_edges: set[RemeshEdge] = {
-        _ordered_edge(u, v) for u, v in 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
     )
@@ -398,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:
@@ -410,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: _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)
 
@@ -477,6 +456,9 @@ def apply_remesh_if_globally_stable(
     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(
@@ -540,9 +522,7 @@ 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))
@@ -551,10 +531,7 @@ def apply_remesh_if_globally_stable(
         return
     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"]
-    ):
+    if cfg["REMESH_COOLDOWN_TS"] > 0 and (t_now - last_ts) < cfg["REMESH_COOLDOWN_TS"]:
         return
 
     apply_network_remesh(G)