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

tnfr/gamma.py

@@ -1,26 +1,26 @@
 """Gamma registry."""
 
 from __future__ import annotations
-from typing import Any, Callable, NamedTuple
-import math
-import logging
+
 import hashlib
+import logging
+import math
 from collections.abc import Mapping
 from functools import lru_cache
 from types import MappingProxyType
+from typing import Any, Callable, NamedTuple
 
-from .constants import DEFAULTS
 from .alias import get_theta_attr
+from .constants import DEFAULTS
+from .utils import json_dumps
+from .metrics.trig_cache import get_trig_cache
 from .types import GammaSpec, NodeId, TNFRGraph
 from .utils import (
     edge_version_cache,
     get_graph_mapping,
     get_logger,
-    json_dumps,
     node_set_checksum,
 )
-from .metrics.trig_cache import get_trig_cache
-
 
 logger = get_logger(__name__)
 
@@ -47,8 +47,7 @@ def _default_gamma_spec() -> tuple[bytes, str]:
 
 
 def _ensure_kuramoto_cache(G: TNFRGraph, t: float | int) -> None:
-    """Cache ``(R, ψ)`` for the current step ``t`` using
-    ``edge_version_cache``."""
+    """Cache ``(R, ψ)`` for the current step ``t`` using ``edge_version_cache``."""
     checksum = G.graph.get("_dnfr_nodes_checksum")
     if checksum is None:
         # reuse checksum from cached_nodes_and_A when available
@@ -172,9 +171,7 @@ def _get_gamma_spec(G: TNFRGraph) -> GammaSpec:
 # -----------------
 
 
-def _gamma_params(
-    cfg: GammaSpec, **defaults: float
-) -> tuple[float, ...]:
+def _gamma_params(cfg: GammaSpec, **defaults: float) -> tuple[float, ...]:
     """Return normalized Γ parameters from ``cfg``.
 
     Parameters are retrieved from ``cfg`` using the keys in ``defaults`` and
@@ -186,9 +183,7 @@ def _gamma_params(
     >>> beta, R0 = _gamma_params(cfg, beta=0.0, R0=0.0)
     """
 
-    return tuple(
-        float(cfg.get(name, default)) for name, default in defaults.items()
-    )
+    return tuple(float(cfg.get(name, default)) for name, default in defaults.items())
 
 
 # -----------------
@@ -196,9 +191,9 @@ def _gamma_params(
 # -----------------
 
 
-def gamma_none(
-    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
-) -> float:
+def gamma_none(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float:
+    """Return ``0.0`` to disable Γ forcing for the given node."""
+
     return 0.0
 
 
@@ -209,7 +204,7 @@ def _gamma_kuramoto(
     builder: Callable[..., float],
     **defaults: float,
 ) -> float:
-    """Helper for Kuramoto-based Γ functions.
+    """Construct a Kuramoto-based Γ function.
 
     ``builder`` receives ``(θ_i, R, ψ, *params)`` where ``params`` are
     extracted from ``cfg`` according to ``defaults``.
@@ -229,7 +224,9 @@ def _builder_bandpass(th_i: float, R: float, psi: float, beta: float) -> float:
     return beta * R * (1.0 - R) * sgn
 
 
-def _builder_tanh(th_i: float, R: float, psi: float, beta: float, k: float, R0: float) -> float:
+def _builder_tanh(
+    th_i: float, R: float, psi: float, beta: float, k: float, R0: float
+) -> float:
     return beta * math.tanh(k * (R - R0)) * math.cos(th_i - psi)
 
 
@@ -253,7 +250,7 @@ def gamma_kuramoto_linear(
 def gamma_kuramoto_bandpass(
     G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
 ) -> float:
-    """Γ = β · R(1-R) · sign(cos(θ_i - ψ))"""
+    """Compute Γ = β · R(1-R) · sign(cos(θ_i - ψ))."""
 
     return _gamma_kuramoto(G, node, cfg, _builder_bandpass, beta=0.0)
 
@@ -272,9 +269,7 @@ def gamma_kuramoto_tanh(
     return _gamma_kuramoto(G, node, cfg, _builder_tanh, beta=0.0, k=1.0, R0=0.0)
 
 
-def gamma_harmonic(
-    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
-) -> float:
+def gamma_harmonic(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float:
     """Harmonic forcing aligned with the global phase field.
 
     Formula: Γ = β · sin(ω·t + φ) · cos(θ_i - ψ)
@@ -288,6 +283,8 @@ def gamma_harmonic(
 
 
 class GammaEntry(NamedTuple):
+    """Lookup entry linking Γ evaluators with their preconditions."""
+
     fn: Callable[[TNFRGraph, NodeId, float | int, GammaSpec], float]
     needs_kuramoto: bool
 
@@ -312,8 +309,7 @@ def eval_gamma(
     strict: bool = False,
     log_level: int | None = None,
 ) -> float:
-    """Evaluate Γi for ``node`` according to ``G.graph['GAMMA']``
-    specification.
+    """Evaluate Γi for ``node`` using ``G.graph['GAMMA']`` specification.
 
     If ``strict`` is ``True`` exceptions raised during evaluation are
     propagated instead of returning ``0.0``. Likewise, if the specified

tnfr/gamma.pyi

@@ -11,25 +11,19 @@ class GammaEntry(NamedTuple):
 GAMMA_REGISTRY: dict[str, GammaEntry]
 
 def kuramoto_R_psi(G: TNFRGraph) -> tuple[float, float]: ...
-
 def gamma_none(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float: ...
-
 def gamma_kuramoto_linear(
     G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
 ) -> float: ...
-
 def gamma_kuramoto_bandpass(
     G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
 ) -> float: ...
-
 def gamma_kuramoto_tanh(
     G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
 ) -> float: ...
-
 def gamma_harmonic(
     G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
 ) -> float: ...
-
 def eval_gamma(
     G: TNFRGraph,
     node: NodeId,

tnfr/glyph_history.py

@@ -2,14 +2,15 @@
 
 from __future__ import annotations
 
-from typing import Any, cast
-from collections import deque, Counter
-from itertools import islice
+from collections import Counter, deque
 from collections.abc import Iterable, Mapping, MutableMapping
+from itertools import islice
+from typing import Any, cast
 
 from .constants import get_param, normalise_state_token
-from .utils import ensure_collection, get_logger, validate_window
+from .glyph_runtime import last_glyph
 from .types import TNFRGraph
+from .utils import ensure_collection, get_logger
 
 logger = get_logger(__name__)
 
@@ -20,16 +21,27 @@ __all__ = (
     "ensure_history",
     "current_step_idx",
     "append_metric",
-    "last_glyph",
     "count_glyphs",
 )
 
 
+_NU_F_HISTORY_KEYS = (
+    "nu_f_rate_hz_str",
+    "nu_f_rate_hz",
+    "nu_f_ci_lower_hz_str",
+    "nu_f_ci_upper_hz_str",
+    "nu_f_ci_lower_hz",
+    "nu_f_ci_upper_hz",
+)
+
+
 def _ensure_history(
     nd: MutableMapping[str, Any], window: int, *, create_zero: bool = False
 ) -> tuple[int, deque[str] | None]:
     """Validate ``window`` and ensure ``nd['glyph_history']`` deque."""
 
+    from tnfr.validation.window import validate_window
+
     v_window = validate_window(window)
     if v_window == 0 and not create_zero:
         return v_window, None
@@ -42,9 +54,7 @@ def _ensure_history(
             try:
                 items = ensure_collection(hist, max_materialize=None)
             except TypeError:
-                logger.debug(
-                    "Discarding non-iterable glyph history value %r", hist
-                )
+                logger.debug("Discarding non-iterable glyph history value %r", hist)
                 items = ()
         hist = deque((str(item) for item in items), maxlen=v_window)
         nd["glyph_history"] = hist
@@ -62,9 +72,7 @@ def push_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> None:
     hist.append(str(glyph))
 
 
-def recent_glyph(
-    nd: MutableMapping[str, Any], glyph: str, window: int
-) -> bool:
+def recent_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> bool:
     """Return ``True`` if ``glyph`` appeared in last ``window`` emissions.
 
     ``window`` validation and deque creation are handled by
@@ -145,26 +153,36 @@ class HistoryDict(dict[str, Any]):
         return val
 
     def get_increment(self, key: str, default: Any = None) -> Any:
+        """Return value for ``key`` and increment its usage counter."""
+
         insert = key not in self
         val = self._resolve_value(key, default, insert=insert)
         self._increment(key)
         return val
 
     def __getitem__(self, key: str) -> Any:  # type: ignore[override]
+        """Return the tracked value for ``key`` ensuring deque normalisation."""
+
         return self._resolve_value(key, None, insert=False)
 
     def get(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        """Return ``key`` when present; otherwise fall back to ``default``."""
+
         try:
             return self._resolve_value(key, None, insert=False)
         except KeyError:
             return default
 
     def __setitem__(self, key: str, value: Any) -> None:  # type: ignore[override]
+        """Store ``value`` for ``key`` while initialising usage tracking."""
+
         super().__setitem__(key, value)
         if key not in self._counts:
             self._counts[key] = 0
 
     def setdefault(self, key: str, default: Any | None = None) -> Any:  # type: ignore[override]
+        """Return existing value for ``key`` or insert ``default`` when absent."""
+
         insert = key not in self
         val = self._resolve_value(key, default, insert=insert)
         if insert:
@@ -181,6 +199,8 @@ class HistoryDict(dict[str, Any]):
         raise KeyError("HistoryDict is empty; cannot pop least used")
 
     def pop_least_used_batch(self, k: int) -> None:
+        """Remove up to ``k`` least-used entries from the history."""
+
         for _ in range(max(0, int(k))):
             try:
                 self.pop_least_used()
@@ -213,10 +233,7 @@ def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]:
         if isinstance(hist, MutableMapping):
             _normalise_state_streams(hist)
         return hist
-    if (
-        not isinstance(hist, HistoryDict)
-        or hist._maxlen != maxlen
-    ):
+    if not isinstance(hist, HistoryDict) or hist._maxlen != maxlen:
         hist = HistoryDict(hist, maxlen=maxlen)
         G.graph["history"] = hist
         replaced = True
@@ -226,6 +243,8 @@ def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]:
     if replaced:
         G.graph.pop(sentinel_key, None)
     _normalise_state_streams(cast(MutableMapping[str, Any], hist))
+    for key in _NU_F_HISTORY_KEYS:
+        hist.setdefault(key, [])
     return hist
 
 
@@ -236,9 +255,7 @@ def current_step_idx(G: TNFRGraph | Mapping[str, Any]) -> int:
     return len(graph.get("history", {}).get("C_steps", []))
 
 
-def append_metric(
-    hist: MutableMapping[str, list[Any]], key: str, value: Any
-) -> None:
+def append_metric(hist: MutableMapping[str, list[Any]], key: str, value: Any) -> None:
     """Append ``value`` to ``hist[key]`` list, creating it if missing."""
     if key == "phase_state" and isinstance(value, str):
         value = normalise_state_token(value)
@@ -260,14 +277,6 @@ def append_metric(
         return
 
     hist.setdefault(key, []).append(value)
-
-
-def last_glyph(nd: Mapping[str, Any]) -> str | None:
-    """Return the most recent glyph for node or ``None``."""
-    hist = nd.get("glyph_history")
-    return hist[-1] if hist else None
-
-
 def count_glyphs(
     G: TNFRGraph, window: int | None = None, *, last_only: bool = False
 ) -> Counter[str]:
@@ -279,6 +288,8 @@ def count_glyphs(
     """
 
     if window is not None:
+        from tnfr.validation.window import validate_window
+
         window = validate_window(window)
         if window == 0:
             return Counter()

tnfr/glyph_history.pyi

@@ -8,7 +8,6 @@ from .types import TNFRGraph
 
 __all__: tuple[str, ...]
 
-
 class HistoryDict(dict[str, Any]):
     _maxlen: int
     _counts: Counter[str]
@@ -16,7 +15,6 @@ class HistoryDict(dict[str, Any]):
     def __init__(
         self, data: Mapping[str, Any] | None = ..., *, maxlen: int = ...
     ) -> None: ...
-
     def get_increment(self, key: str, default: Any = ...) -> Any: ...
     def __getitem__(self, key: str) -> Any: ...
     def get(self, key: str, default: Any | None = ...) -> Any: ...
@@ -25,29 +23,13 @@ class HistoryDict(dict[str, Any]):
     def pop_least_used(self) -> Any: ...
     def pop_least_used_batch(self, k: int) -> None: ...
 
-
 def push_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> None: ...
-
-
-def recent_glyph(
-    nd: MutableMapping[str, Any], glyph: str, window: int
-) -> bool: ...
-
-
+def recent_glyph(nd: MutableMapping[str, Any], glyph: str, window: int) -> bool: ...
 def ensure_history(G: TNFRGraph) -> HistoryDict | dict[str, Any]: ...
-
-
 def current_step_idx(G: TNFRGraph | Mapping[str, Any]) -> int: ...
-
-
 def append_metric(
     hist: MutableMapping[str, list[Any]], key: str, value: Any
 ) -> None: ...
-
-
-def last_glyph(nd: Mapping[str, Any]) -> str | None: ...
-
-
 def count_glyphs(
     G: TNFRGraph, window: int | None = ..., *, last_only: bool = ...
 ) -> Counter[str]: ...

tnfr/glyph_runtime.py

@@ -0,0 +1,16 @@
+"""Runtime glyph helpers decoupled from validation internals."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+__all__ = ("last_glyph",)
+
+
+def last_glyph(nd: Mapping[str, Any]) -> str | None:
+    """Return the most recent glyph for node or ``None``."""
+
+    hist = nd.get("glyph_history")
+    return hist[-1] if hist else None
+

tnfr/glyph_runtime.pyi

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+__all__: tuple[str, ...]
+
+def last_glyph(nd: Mapping[str, Any]) -> str | None: ...
+

tnfr/immutable.py

@@ -7,21 +7,19 @@ encountered.
 
 from __future__ import annotations
 
+import threading
+import weakref
+from collections.abc import Mapping
 from contextlib import contextmanager
 from dataclasses import asdict, is_dataclass
 from functools import lru_cache, partial, singledispatch, wraps
-from typing import Any, Callable, Iterable, Iterator, cast
-from collections.abc import Mapping
 from types import MappingProxyType
-import threading
-import weakref
+from typing import Any, Callable, Iterable, Iterator, cast
 
 from ._compat import TypeAlias
 
 # Types considered immutable without further inspection
-IMMUTABLE_SIMPLE = frozenset(
-    {int, float, complex, str, bool, bytes, type(None)}
-)
+IMMUTABLE_SIMPLE = frozenset({int, float, complex, str, bool, bytes, type(None)})
 
 
 FrozenPrimitive: TypeAlias = int | float | complex | str | bool | bytes | None
@@ -40,7 +38,10 @@ FrozenTaggedMapping: TypeAlias = tuple[str, FrozenMappingItems]
 """Tagged mapping snapshot identifying the original mapping flavour."""
 
 FrozenSnapshot: TypeAlias = (
-    FrozenPrimitive | FrozenCollectionItems | FrozenTaggedCollection | FrozenTaggedMapping
+    FrozenPrimitive
+    | FrozenCollectionItems
+    | FrozenTaggedCollection
+    | FrozenTaggedMapping
 )
 """Union describing the immutable snapshot returned by :func:`_freeze`."""
 
@@ -61,9 +62,9 @@ def _cycle_guard(value: Any, seen: set[int] | None = None) -> Iterator[set[int]]
 
 
 def _check_cycle(
-    func: Callable[[Any, set[int] | None], FrozenSnapshot]
+    func: Callable[[Any, set[int] | None], FrozenSnapshot],
 ) -> Callable[[Any, set[int] | None], FrozenSnapshot]:
-    """Decorator applying :func:`_cycle_guard` to ``func``."""
+    """Apply :func:`_cycle_guard` to ``func``."""
 
     @wraps(func)
     def wrapper(value: Any, seen: set[int] | None = None) -> FrozenSnapshot:
@@ -95,7 +96,9 @@ def _freeze(value: Any, seen: set[int] | None = None) -> FrozenSnapshot:
 
 @_freeze.register(tuple)
 @_check_cycle
-def _freeze_tuple(value: tuple[Any, ...], seen: set[int] | None = None) -> FrozenCollectionItems:  # noqa: F401
+def _freeze_tuple(
+    value: tuple[Any, ...], seen: set[int] | None = None
+) -> FrozenCollectionItems:  # noqa: F401
     assert seen is not None
     return tuple(_freeze(v, seen) for v in value)
 
@@ -115,7 +118,9 @@ def _freeze_iterable_with_tag(
 
 def _register_iterable(cls: type, tag: str) -> None:
     handler = _check_cycle(partial(_freeze_iterable_with_tag, tag=tag))
-    _freeze.register(cls)(cast(Callable[[Any, set[int] | None], FrozenSnapshot], handler))
+    _freeze.register(cls)(
+        cast(Callable[[Any, set[int] | None], FrozenSnapshot], handler)
+    )
 
 
 for _cls, _tag in (
@@ -159,6 +164,8 @@ _IMMUTABLE_TAG_DISPATCH: Mapping[str, ImmutableTagHandler] = MappingProxyType(
 @lru_cache(maxsize=1024)
 @singledispatch
 def _is_immutable_inner(value: Any) -> bool:
+    """Return ``True`` when ``value`` belongs to the canonical immutable set."""
+
     return type(value) in IMMUTABLE_SIMPLE
 
 
@@ -176,9 +183,7 @@ def _is_immutable_inner_frozenset(value: frozenset[Any]) -> bool:  # noqa: F401
     return _all_immutable(value)
 
 
-_IMMUTABLE_CACHE: weakref.WeakKeyDictionary[Any, bool] = (
-    weakref.WeakKeyDictionary()
-)
+_IMMUTABLE_CACHE: weakref.WeakKeyDictionary[Any, bool] = weakref.WeakKeyDictionary()
 _IMMUTABLE_CACHE_LOCK = threading.Lock()
 
 

tnfr/immutable.pyi

@@ -8,29 +8,26 @@ FrozenMappingItems: TypeAlias = tuple[tuple[Any, "FrozenSnapshot"], ...]
 FrozenTaggedCollection: TypeAlias = tuple[str, FrozenCollectionItems]
 FrozenTaggedMapping: TypeAlias = tuple[str, FrozenMappingItems]
 FrozenSnapshot: TypeAlias = (
-    FrozenPrimitive | FrozenCollectionItems | FrozenTaggedCollection | FrozenTaggedMapping
+    FrozenPrimitive
+    | FrozenCollectionItems
+    | FrozenTaggedCollection
+    | FrozenTaggedMapping
 )
 ImmutableTagHandler: TypeAlias = Callable[[tuple[Any, ...]], bool]
 
 __all__: tuple[str, ...]
 
 def __getattr__(name: str) -> Any: ...
-
 def _cycle_guard(value: Any, seen: set[int] | None = ...) -> Iterator[set[int]]: ...
-
 def _check_cycle(
     func: Callable[[Any, set[int] | None], FrozenSnapshot],
 ) -> Callable[[Any, set[int] | None], FrozenSnapshot]: ...
-
 def _freeze(value: Any, seen: set[int] | None = ...) -> FrozenSnapshot: ...
-
 def _freeze_mapping(
     value: Mapping[Any, Any],
     seen: set[int] | None = ...,
 ) -> FrozenTaggedMapping: ...
-
 def _is_immutable(value: Any) -> bool: ...
-
 def _is_immutable_inner(value: Any) -> bool: ...
 
 _IMMUTABLE_CACHE: Any

tnfr/initialization.py

@@ -1,13 +1,13 @@
 """Node initialization."""
 
 from __future__ import annotations
-import random
-from typing import TYPE_CHECKING, cast
 
+import random
 from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
 
-from .constants import VF_KEY, THETA_KEY, get_graph_param
-from .helpers.numeric import clamp
+from .constants import THETA_KEY, VF_KEY, get_graph_param
+from .utils import clamp
 from .rng import make_rng
 from .types import NodeInitAttrMap
 
@@ -53,9 +53,7 @@ class InitParams:
             vf_uniform_max=get_graph_param(G, "INIT_VF_MAX"),
             vf_mean=get_graph_param(G, "INIT_VF_MEAN"),
             vf_std=get_graph_param(G, "INIT_VF_STD"),
-            clamp_to_limits=get_graph_param(
-                G, "INIT_VF_CLAMP_TO_LIMITS", bool
-            ),
+            clamp_to_limits=get_graph_param(G, "INIT_VF_CLAMP_TO_LIMITS", bool),
             si_min=get_graph_param(G, "INIT_SI_MIN"),
             si_max=get_graph_param(G, "INIT_SI_MAX"),
             epi_val=get_graph_param(G, "INIT_EPI_VALUE"),

tnfr/initialization.pyi

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 import random
+from dataclasses import dataclass
 
 import networkx as nx
 
@@ -9,7 +9,6 @@ from .types import NodeInitAttrMap
 
 __all__: tuple[str, str] = ("InitParams", "init_node_attrs")
 
-
 @dataclass
 class InitParams:
     seed: int | None
@@ -31,7 +30,6 @@ class InitParams:
     @classmethod
     def from_graph(cls, G: nx.Graph) -> InitParams: ...
 
-
 def _init_phase(
     nd: NodeInitAttrMap,
     rng: random.Random,
@@ -41,8 +39,6 @@ def _init_phase(
     th_min: float,
     th_max: float,
 ) -> None: ...
-
-
 def _init_vf(
     nd: NodeInitAttrMap,
     rng: random.Random,
@@ -57,8 +53,6 @@ def _init_vf(
     vf_max_lim: float,
     clamp_to_limits: bool,
 ) -> None: ...
-
-
 def _init_si_epi(
     nd: NodeInitAttrMap,
     rng: random.Random,
@@ -68,6 +62,4 @@ def _init_si_epi(
     si_max: float,
     epi_val: float,
 ) -> None: ...
-
-
 def init_node_attrs(G: nx.Graph, *, override: bool = True) -> nx.Graph: ...