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

tnfr/glyph_history.pyi

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping, MutableMapping
+from typing import Any
+
+from .types import TNFRGraph
+
+__all__: tuple[str, ...]
+
+class HistoryDict(dict[str, Any]):
+    _maxlen: int
+    _counts: Counter[str]
+
+    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: ...
+    def __setitem__(self, key: str, value: Any) -> None: ...
+    def setdefault(self, key: str, default: Any | None = ...) -> 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 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 count_glyphs(
+    G: TNFRGraph, window: int | None = ..., *, last_only: bool = ...
+) -> Counter[str]: ...

tnfr/glyph_runtime.py

@@ -0,0 +1,19 @@
+"""Runtime helpers for structural operator glyphs decoupled from validation internals.
+
+This module provides utilities for working with glyphs (structural symbols like
+AL, EN, IL, etc.) that represent the application of structural operators to nodes.
+"""
+
+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,8 @@
+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,23 +7,46 @@ 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, singledispatch, wraps, partial
-from typing import Any, Callable
-from collections.abc import Mapping
+from functools import lru_cache, partial, singledispatch, wraps
 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
+"""Primitive immutable values handled directly by :func:`_freeze`."""
+
+FrozenCollectionItems: TypeAlias = tuple["FrozenSnapshot", ...]
+"""Frozen representation for generic iterables."""
+
+FrozenMappingItems: TypeAlias = tuple[tuple[Any, "FrozenSnapshot"], ...]
+"""Frozen representation for mapping ``items()`` snapshots."""
+
+FrozenTaggedCollection: TypeAlias = tuple[str, FrozenCollectionItems]
+"""Tagged iterable snapshot identifying the original container type."""
+
+FrozenTaggedMapping: TypeAlias = tuple[str, FrozenMappingItems]
+"""Tagged mapping snapshot identifying the original mapping flavour."""
+
+FrozenSnapshot: TypeAlias = (
+    FrozenPrimitive
+    | FrozenCollectionItems
+    | FrozenTaggedCollection
+    | FrozenTaggedMapping
 )
+"""Union describing the immutable snapshot returned by :func:`_freeze`."""
 
 
 @contextmanager
-def _cycle_guard(value: Any, seen: set[int] | None = None):
+def _cycle_guard(value: Any, seen: set[int] | None = None) -> Iterator[set[int]]:
     """Context manager that detects reference cycles during freezing."""
     if seen is None:
         seen = set()
@@ -37,18 +60,20 @@ def _cycle_guard(value: Any, seen: set[int] | None = None):
         seen.remove(obj_id)
 
 
-def _check_cycle(func: Callable[[Any, set[int] | None], Any]):
-    """Decorator applying :func:`_cycle_guard` to ``func``."""
+def _check_cycle(
+    func: Callable[[Any, set[int] | None], FrozenSnapshot],
+) -> Callable[[Any, set[int] | None], FrozenSnapshot]:
+    """Apply :func:`_cycle_guard` to ``func``."""
 
     @wraps(func)
-    def wrapper(value: Any, seen: set[int] | None = None):
-        with _cycle_guard(value, seen) as seen:
-            return func(value, seen)
+    def wrapper(value: Any, seen: set[int] | None = None) -> FrozenSnapshot:
+        with _cycle_guard(value, seen) as guard_seen:
+            return func(value, guard_seen)
 
     return wrapper
 
 
-def _freeze_dataclass(value: Any, seen: set[int]):
+def _freeze_dataclass(value: Any, seen: set[int]) -> FrozenTaggedMapping:
     params = getattr(type(value), "__dataclass_params__", None)
     frozen = bool(params and params.frozen)
     data = asdict(value)
@@ -58,9 +83,10 @@ def _freeze_dataclass(value: Any, seen: set[int]):
 
 @singledispatch
 @_check_cycle
-def _freeze(value: Any, seen: set[int] | None = None):
+def _freeze(value: Any, seen: set[int] | None = None) -> FrozenSnapshot:
     """Recursively convert ``value`` into an immutable representation."""
     if is_dataclass(value) and not isinstance(value, type):
+        assert seen is not None
         return _freeze_dataclass(value, seen)
     if type(value) in IMMUTABLE_SIMPLE:
         return value
@@ -69,22 +95,31 @@ def _freeze(value: Any, seen: set[int] | None = None):
 
 @_freeze.register(tuple)
 @_check_cycle
-def _freeze_tuple(value: tuple, seen: set[int] | None = None):  # 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)
 
 
-def _freeze_iterable(container: Any, tag: str, seen: set[int] | None) -> tuple[str, tuple]:
+def _freeze_iterable(
+    container: Iterable[Any], tag: str, seen: set[int]
+) -> FrozenTaggedCollection:
     return (tag, tuple(_freeze(v, seen) for v in container))
 
 
 def _freeze_iterable_with_tag(
-    value: Any, seen: set[int] | None = None, *, tag: str
-) -> tuple[str, tuple]:
+    value: Iterable[Any], seen: set[int] | None = None, *, tag: str
+) -> FrozenTaggedCollection:
+    assert seen is not None
     return _freeze_iterable(value, tag, seen)
 
 
 def _register_iterable(cls: type, tag: str) -> None:
-    _freeze.register(cls)(_check_cycle(partial(_freeze_iterable_with_tag, tag=tag)))
+    handler = _check_cycle(partial(_freeze_iterable_with_tag, tag=tag))
+    _freeze.register(cls)(
+        cast(Callable[[Any, set[int] | None], FrozenSnapshot], handler)
+    )
 
 
 for _cls, _tag in (
@@ -98,17 +133,22 @@ for _cls, _tag in (
 
 @_freeze.register(Mapping)
 @_check_cycle
-def _freeze_mapping(value: Mapping, seen: set[int] | None = None):  # noqa: F401
+def _freeze_mapping(
+    value: Mapping[Any, Any], seen: set[int] | None = None
+) -> FrozenTaggedMapping:  # noqa: F401
+    assert seen is not None
     tag = "dict" if hasattr(value, "__setitem__") else "mapping"
     return (tag, tuple((k, _freeze(v, seen)) for k, v in value.items()))
 
 
-def _all_immutable(iterable) -> bool:
+def _all_immutable(iterable: Iterable[Any]) -> bool:
     return all(_is_immutable_inner(v) for v in iterable)
 
 
 # Dispatch table kept immutable to avoid accidental mutation.
-_IMMUTABLE_TAG_DISPATCH: Mapping[str, Callable[[tuple], bool]] = MappingProxyType(
+ImmutableTagHandler: TypeAlias = Callable[[tuple[Any, ...]], bool]
+
+_IMMUTABLE_TAG_DISPATCH: Mapping[str, ImmutableTagHandler] = MappingProxyType(
     {
         "mapping": lambda v: _all_immutable(v[1]),
         "frozenset": lambda v: _all_immutable(v[1]),
@@ -123,11 +163,13 @@ _IMMUTABLE_TAG_DISPATCH: Mapping[str, Callable[[tuple], bool]] = MappingProxyTyp
 @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
 
 
 @_is_immutable_inner.register(tuple)
-def _is_immutable_inner_tuple(value: tuple) -> bool:  # noqa: F401
+def _is_immutable_inner_tuple(value: tuple[Any, ...]) -> bool:  # noqa: F401
     if value and isinstance(value[0], str):
         handler = _IMMUTABLE_TAG_DISPATCH.get(value[0])
         if handler is not None:
@@ -136,13 +178,11 @@ def _is_immutable_inner_tuple(value: tuple) -> bool:  # noqa: F401
 
 
 @_is_immutable_inner.register(frozenset)
-def _is_immutable_inner_frozenset(value: frozenset) -> bool:  # noqa: F401
+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()
 
 
@@ -152,7 +192,7 @@ def _is_immutable(value: Any) -> bool:
         try:
             return _IMMUTABLE_CACHE[value]
         except (KeyError, TypeError):
-            pass
+            pass  # Not in cache or value is unhashable
 
     try:
         frozen = _freeze(value)
@@ -165,7 +205,7 @@ def _is_immutable(value: Any) -> bool:
         try:
             _IMMUTABLE_CACHE[value] = result
         except TypeError:
-            pass
+            pass  # Value is unhashable, cannot cache
 
     return result
 

tnfr/immutable.pyi

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Iterator, Mapping, Union
+
+from ._compat import TypeAlias
+
+FrozenPrimitive: TypeAlias = Union[int, float, complex, str, bool, bytes, None]
+FrozenCollectionItems: TypeAlias = tuple["FrozenSnapshot", ...]
+FrozenMappingItems: TypeAlias = tuple[tuple[Any, "FrozenSnapshot"], ...]
+FrozenTaggedCollection: TypeAlias = tuple[str, FrozenCollectionItems]
+FrozenTaggedMapping: TypeAlias = tuple[str, FrozenMappingItems]
+FrozenSnapshot: TypeAlias = Union[
+    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
+_IMMUTABLE_TAG_DISPATCH: Mapping[str, ImmutableTagHandler]

tnfr/initialization.py

@@ -1,24 +1,25 @@
 """Node initialization."""
 
 from __future__ import annotations
-import random
-from typing import TYPE_CHECKING
 
+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
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx as nx  # type: ignore[import-untyped]
+    import networkx as nx
 
 __all__ = ("InitParams", "init_node_attrs")
 
 
 @dataclass
 class InitParams:
-    """Parametros de inicialización nodal."""
+    """Parameters governing node initialisation."""
 
     seed: int | None
     init_rand_phase: bool
@@ -38,7 +39,7 @@ class InitParams:
 
     @classmethod
     def from_graph(cls, G: "nx.Graph") -> "InitParams":
-        """Construir ``InitParams`` desde ``G.graph``."""
+        """Construct ``InitParams`` from ``G.graph`` configuration."""
 
         return cls(
             seed=get_graph_param(G, "RANDOM_SEED", int),
@@ -52,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"),
@@ -62,7 +61,7 @@ class InitParams:
 
 
 def _init_phase(
-    nd: dict,
+    nd: NodeInitAttrMap,
     rng: random.Random,
     *,
     override: bool,
@@ -82,7 +81,7 @@ def _init_phase(
 
 
 def _init_vf(
-    nd: dict,
+    nd: NodeInitAttrMap,
     rng: random.Random,
     *,
     override: bool,
@@ -118,7 +117,7 @@ def _init_vf(
 
 
 def _init_si_epi(
-    nd: dict,
+    nd: NodeInitAttrMap,
     rng: random.Random,
     *,
     override: bool,
@@ -145,6 +144,8 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
     Ranges for ``Si`` are added via ``INIT_SI_MIN`` and ``INIT_SI_MAX``, and
     for ``EPI`` via ``INIT_EPI_VALUE``. If ``INIT_VF_MIN`` is greater than
     ``INIT_VF_MAX``, values are swapped and clamped to ``VF_MIN``/``VF_MAX``.
+    When clamping results in an invalid range (min > max), both bounds
+    collapse to ``VF_MIN``, ensuring ``VF_MIN``/``VF_MAX`` are hard limits.
     """
     params = InitParams.from_graph(G)
 
@@ -160,12 +161,17 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
         vf_uniform_min, vf_uniform_max = vf_uniform_max, vf_uniform_min
     params.vf_uniform_min = max(vf_uniform_min, vf_min_lim)
     params.vf_uniform_max = min(vf_uniform_max, vf_max_lim)
+    # After clamping to VF_MIN/VF_MAX, ensure min <= max
+    if params.vf_uniform_min > params.vf_uniform_max:
+        # Collapse to VF_MIN when the requested range is entirely below the limit
+        params.vf_uniform_min = params.vf_uniform_max = vf_min_lim
 
     rng = make_rng(params.seed, -1, G)
     for _, nd in G.nodes(data=True):
+        node_attrs = cast(NodeInitAttrMap, nd)
 
         _init_phase(
-            nd,
+            node_attrs,
             rng,
             override=override,
             random_phase=params.init_rand_phase,
@@ -173,7 +179,7 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
             th_max=params.th_max,
         )
         _init_vf(
-            nd,
+            node_attrs,
             rng,
             override=override,
             mode=params.vf_mode,
@@ -186,7 +192,7 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
             clamp_to_limits=params.clamp_to_limits,
         )
         _init_si_epi(
-            nd,
+            node_attrs,
             rng,
             override=override,
             si_min=params.si_min,

tnfr/initialization.pyi

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+import networkx as nx
+
+from .types import NodeInitAttrMap
+
+__all__: tuple[str, str] = ("InitParams", "init_node_attrs")
+
+@dataclass
+class InitParams:
+    seed: int | None
+    init_rand_phase: bool
+    th_min: float
+    th_max: float
+    vf_mode: str
+    vf_min_lim: float
+    vf_max_lim: float
+    vf_uniform_min: float | None
+    vf_uniform_max: float | None
+    vf_mean: float
+    vf_std: float
+    clamp_to_limits: bool
+    si_min: float
+    si_max: float
+    epi_val: float
+
+    @classmethod
+    def from_graph(cls, G: nx.Graph) -> InitParams: ...
+
+def _init_phase(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    random_phase: bool,
+    th_min: float,
+    th_max: float,
+) -> None: ...
+def _init_vf(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    mode: str,
+    vf_uniform_min: float,
+    vf_uniform_max: float,
+    vf_mean: float,
+    vf_std: float,
+    vf_min_lim: float,
+    vf_max_lim: float,
+    clamp_to_limits: bool,
+) -> None: ...
+def _init_si_epi(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    si_min: float,
+    si_max: float,
+    epi_val: float,
+) -> None: ...
+def init_node_attrs(G: nx.Graph, *, override: bool = True) -> nx.Graph: ...