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

tnfr/operators/jitter.py

@@ -1,24 +1,31 @@
+"""Jitter operators for reproducible phase perturbations."""
+
 from __future__ import annotations
-from typing import Any, TYPE_CHECKING
 
-from cachetools import LRUCache
+import threading
+from typing import TYPE_CHECKING, Any, cast
 
-from ..cache import ensure_node_offset_map
+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 ..import_utils import get_nodonx
+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 NodoProtocol
+    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
 
@@ -26,18 +33,53 @@ _JITTER_MAX_ENTRIES = 1024
 class JitterCache:
     """Container for jitter-related caches."""
 
-    def __init__(self, max_entries: int = _JITTER_MAX_ENTRIES) -> None:
-        self._sequence = ScopedCounterCache("jitter", max_entries)
-        self.settings: dict[str, Any] = {"max_entries": self._sequence.max_entries}
+    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) -> 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
 
     @property
-    def lock(self):
+    def lock(self) -> threading.Lock | threading.RLock:
         """Return the lock protecting the sequence cache."""
 
         return self._sequence.lock
@@ -53,21 +95,26 @@ class JitterCache:
         """Set the maximum number of cached jitter sequences."""
 
         self._sequence.configure(max_entries=int(value))
-        self.settings["max_entries"] = self._sequence.max_entries
+        self._refresh_settings()
 
-    def setup(
-        self, force: bool = False, max_entries: int | None = None
-    ) -> None:
+    @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.settings["max_entries"] = self._sequence.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."""
@@ -78,40 +125,57 @@ class JitterCache:
 class JitterCacheManager:
     """Manager exposing the jitter cache without global reassignment."""
 
-    def __init__(self, cache: JitterCache | None = None) -> None:
-        self.cache = cache or JitterCache()
+    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) -> 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):
+    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:
+    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:
@@ -119,6 +183,7 @@ class JitterCacheManager:
 
     def clear(self) -> None:
         """Clear cached RNGs and jitter state."""
+
         self.cache.clear()
 
     def bump(self, key: tuple[int, int]) -> int:
@@ -148,27 +213,31 @@ def reset_jitter_manager() -> None:
     _JITTER_MANAGER = None
 
 
-def _node_offset(G, n) -> int:
+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: NodoProtocol) -> tuple[int, int]:
-    NodoNX = get_nodonx()
-    if NodoNX is None:
-        raise ImportError("NodoNX is unavailable")
-    if isinstance(node, NodoNX):
-        return _node_offset(node.G, node.n), id(node.G)
+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)
-    return int(uid), id(node)
+    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: NodoProtocol,
+    node: NodeProtocol,
     amplitude: float,
 ) -> float:
     """Return deterministic noise in ``[-amplitude, amplitude]`` for ``node``.
@@ -184,7 +253,7 @@ def random_jitter(
     seed_root = base_seed(node.G)
     seed_key, scope_id = _resolve_jitter_seed(node)
 
-    cache_key = (seed_root, scope_id)
+    cache_key = (seed_root, scope_id, seed_key)
     seq = 0
     if cache_enabled(node.G):
         manager = get_jitter_manager()

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/registry.py

@@ -0,0 +1,75 @@
+"""Registry mapping operator names to their classes."""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import TYPE_CHECKING
+
+from ..config.operator_names import canonical_operator_name
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from .definitions import Operator
+
+
+OPERATORS: dict[str, type["Operator"]] = {}
+
+
+def register_operator(cls: type["Operator"]) -> type["Operator"]:
+    """Register ``cls`` under its declared ``name`` in :data:`OPERATORS`."""
+
+    name = getattr(cls, "name", None)
+    if not isinstance(name, str) or not name:
+        raise ValueError(
+            f"Operator {cls.__name__} must declare a non-empty 'name' attribute"
+        )
+
+    existing = OPERATORS.get(name)
+    if existing is not None and existing is not cls:
+        raise ValueError(f"Operator '{name}' is already registered")
+
+    OPERATORS[name] = cls
+    return cls
+
+
+def get_operator_class(name: str) -> type["Operator"]:
+    """Return the operator class registered for ``name`` or its canonical alias."""
+
+    try:
+        return OPERATORS[name]
+    except KeyError:
+        canonical = canonical_operator_name(name)
+        if canonical == name:
+            raise
+        try:
+            return OPERATORS[canonical]
+        except KeyError as exc:  # pragma: no cover - defensive branch
+            raise KeyError(name) from exc
+
+
+def discover_operators() -> None:
+    """Import all operator submodules so their decorators run."""
+
+    package = importlib.import_module("tnfr.operators")
+    package_path = getattr(package, "__path__", None)
+    if not package_path:
+        return
+
+    if getattr(package, "_operators_discovered", False):  # pragma: no cover - cache
+        return
+
+    prefix = f"{package.__name__}."
+    for module_info in pkgutil.walk_packages(package_path, prefix):
+        if module_info.name == f"{prefix}registry":
+            continue
+        importlib.import_module(module_info.name)
+
+    setattr(package, "_operators_discovered", True)
+
+
+__all__ = (
+    "OPERATORS",
+    "register_operator",
+    "discover_operators",
+    "get_operator_class",
+)

tnfr/operators/registry.pyi

@@ -0,0 +1,13 @@
+from typing import Any
+
+from .definitions import Operator
+
+__all__: Any
+
+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]: ...