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

tnfr/types.pyi

@@ -0,0 +1,331 @@
+from collections.abc import (
+    Hashable,
+    Mapping,
+    MutableMapping,
+    MutableSequence,
+    Sequence,
+)
+from enum import Enum
+from typing import Any, Callable, ContextManager, Iterable, Protocol, TypedDict, cast
+
+from ._compat import TypeAlias
+
+try:
+    import networkx as nx  # type: ignore[import-not-found]
+except Exception:
+    class _FallbackGraph: ...
+
+    class _FallbackNetworkX:
+        Graph = _FallbackGraph
+
+    nx = cast(Any, _FallbackNetworkX())
+
+try:
+    import numpy as np  # type: ignore[import-not-found]
+except Exception:
+    class _FallbackNdArray: ...
+
+    class _FallbackNumpy:
+        ndarray = _FallbackNdArray
+
+    np = cast(Any, _FallbackNumpy())
+
+from .glyph_history import HistoryDict as _HistoryDict
+from .tokens import Token
+__all__: tuple[str, ...] = (
+    "TNFRGraph",
+    "Graph",
+    "ValidatorFunc",
+    "NodeId",
+    "Node",
+    "GammaSpec",
+    "EPIValue",
+    "BEPIProtocol",
+    "ensure_bepi",
+    "serialize_bepi",
+    "ZERO_BEPI_STORAGE",
+    "DeltaNFR",
+    "SecondDerivativeEPI",
+    "Phase",
+    "StructuralFrequency",
+    "SenseIndex",
+    "CouplingWeight",
+    "CoherenceMetric",
+    "DeltaNFRHook",
+    "GraphLike",
+    "IntegratorProtocol",
+    "Glyph",
+    "GlyphCode",
+    "GlyphLoadDistribution",
+    "GlyphSelector",
+    "SelectorPreselectionMetrics",
+    "SelectorPreselectionChoices",
+    "SelectorPreselectionPayload",
+    "SelectorMetrics",
+    "SelectorNorms",
+    "SelectorThresholds",
+    "SelectorWeights",
+    "TraceCallback",
+    "CallbackError",
+    "TraceFieldFn",
+    "TraceFieldMap",
+    "TraceFieldRegistry",
+    "TraceMetadata",
+    "TraceSnapshot",
+    "HistoryState",
+    "DiagnosisNodeData",
+    "DiagnosisSharedState",
+    "DiagnosisPayload",
+    "DiagnosisResult",
+    "DiagnosisPayloadChunk",
+    "DiagnosisResultList",
+    "DnfrCacheVectors",
+    "DnfrVectorMap",
+    "NeighborStats",
+    "TimingContext",
+    "PresetTokens",
+    "ProgramTokens",
+    "ArgSpec",
+    "TNFRConfigValue",
+    "SigmaVector",
+    "SigmaTrace",
+    "FloatArray",
+    "FloatMatrix",
+    "NodeInitAttrMap",
+    "NodeAttrMap",
+    "GlyphogramRow",
+    "GlyphTimingTotals",
+    "GlyphTimingByNode",
+    "GlyphCounts",
+    "GlyphMetricsHistoryValue",
+    "GlyphMetricsHistory",
+    "MetricsListHistory",
+    "ParallelWijPayload",
+    "RemeshMeta",
+)
+
+def __getattr__(name: str) -> Any: ...
+
+TNFRGraph: TypeAlias = nx.Graph
+Graph: TypeAlias = TNFRGraph
+ValidatorFunc: TypeAlias = Callable[[TNFRGraph], None]
+NodeId: TypeAlias = Hashable
+Node: TypeAlias = NodeId
+NodeInitAttrMap: TypeAlias = MutableMapping[str, float]
+NodeAttrMap: TypeAlias = Mapping[str, Any]
+GammaSpec: TypeAlias = Mapping[str, Any]
+class BEPIProtocol(Protocol): ...
+
+EPIValue: TypeAlias = BEPIProtocol
+ZERO_BEPI_STORAGE: dict[str, tuple[complex, ...] | tuple[float, ...]]
+def ensure_bepi(value: Any) -> "BEPIElement": ...
+def serialize_bepi(value: Any) -> dict[str, tuple[complex, ...] | tuple[float, ...]]: ...
+DeltaNFR: TypeAlias = float
+SecondDerivativeEPI: TypeAlias = float
+Phase: TypeAlias = float
+StructuralFrequency: TypeAlias = float
+SenseIndex: TypeAlias = float
+CouplingWeight: TypeAlias = float
+CoherenceMetric: TypeAlias = float
+TimingContext: TypeAlias = ContextManager[None]
+PresetTokens: TypeAlias = Sequence[Token]
+ProgramTokens: TypeAlias = Sequence[Token]
+ArgSpec: TypeAlias = tuple[str, Mapping[str, Any]]
+
+TNFRConfigScalar: TypeAlias = bool | int | float | str | None
+TNFRConfigSequence: TypeAlias = Sequence[TNFRConfigScalar]
+TNFRConfigValue: TypeAlias = (
+    TNFRConfigScalar | TNFRConfigSequence | Mapping[str, "TNFRConfigValue"]
+)
+
+class _SigmaVectorRequired(TypedDict):
+    x: float
+    y: float
+    mag: float
+    angle: float
+    n: int
+
+
+class _SigmaVectorOptional(TypedDict, total=False):
+    glyph: str
+    w: float
+    t: float
+
+
+class SigmaVector(_SigmaVectorRequired, _SigmaVectorOptional): ...
+
+
+class SigmaTrace(TypedDict):
+    t: list[float]
+    sigma_x: list[float]
+    sigma_y: list[float]
+    mag: list[float]
+    angle: list[float]
+
+
+FloatArray: TypeAlias = np.ndarray
+FloatMatrix: TypeAlias = np.ndarray
+
+class SelectorThresholds(TypedDict):
+    si_hi: float
+    si_lo: float
+    dnfr_hi: float
+    dnfr_lo: float
+    accel_hi: float
+    accel_lo: float
+
+class SelectorWeights(TypedDict):
+    w_si: float
+    w_dnfr: float
+    w_accel: float
+
+SelectorMetrics: TypeAlias = tuple[float, float, float]
+SelectorNorms: TypeAlias = Mapping[str, float]
+
+class _DeltaNFRHookProtocol(Protocol):
+    def __call__(self, graph: TNFRGraph, /, *args: Any, **kwargs: Any) -> None: ...
+
+DeltaNFRHook: TypeAlias = _DeltaNFRHookProtocol
+
+class GraphLike(Protocol):
+    graph: dict[str, Any]
+
+    def nodes(self, data: bool = ...) -> Iterable[Any]: ...
+    def number_of_nodes(self) -> int: ...
+    def neighbors(self, n: Any) -> Iterable[Any]: ...
+    def __iter__(self) -> Iterable[Any]: ...
+
+class IntegratorProtocol(Protocol):
+    def integrate(
+        self,
+        graph: TNFRGraph,
+        *,
+        dt: float | None = ...,
+        t: float | None = ...,
+        method: str | None = ...,
+        n_jobs: int | None = ...,
+    ) -> None: ...
+
+class Glyph(str, Enum):
+    AL = "AL"
+    EN = "EN"
+    IL = "IL"
+    OZ = "OZ"
+    UM = "UM"
+    RA = "RA"
+    SHA = "SHA"
+    VAL = "VAL"
+    NUL = "NUL"
+    THOL = "THOL"
+    ZHIR = "ZHIR"
+    NAV = "NAV"
+    REMESH = "REMESH"
+
+GlyphCode: TypeAlias = Glyph | str
+GlyphLoadDistribution: TypeAlias = dict[Glyph | str, float]
+
+
+class _SelectorLifecycle(Protocol):
+    def __call__(self, graph: TNFRGraph, node: NodeId) -> GlyphCode: ...
+    def prepare(self, graph: TNFRGraph, nodes: Sequence[NodeId]) -> None: ...
+    def select(self, graph: TNFRGraph, node: NodeId) -> GlyphCode: ...
+
+
+GlyphSelector: TypeAlias = Callable[[TNFRGraph, NodeId], GlyphCode] | _SelectorLifecycle
+SelectorPreselectionMetrics: TypeAlias = Mapping[Any, SelectorMetrics]
+SelectorPreselectionChoices: TypeAlias = Mapping[Any, Glyph | str]
+SelectorPreselectionPayload: TypeAlias = tuple[
+    SelectorPreselectionMetrics,
+    SelectorPreselectionChoices,
+]
+TraceFieldFn: TypeAlias = Callable[[TNFRGraph], "TraceMetadata"]
+TraceFieldMap: TypeAlias = Mapping[str, "TraceFieldFn"]
+TraceFieldRegistry: TypeAlias = dict[str, dict[str, "TraceFieldFn"]]
+
+class TraceMetadata(TypedDict, total=False):
+    gamma: Mapping[str, Any]
+    grammar: Mapping[str, Any]
+    selector: str | None
+    dnfr_weights: Mapping[str, Any]
+    si_weights: Mapping[str, Any]
+    si_sensitivity: Mapping[str, Any]
+    callbacks: Mapping[str, list[str] | None]
+    thol_open_nodes: int
+    kuramoto: Mapping[str, float]
+    sigma: Mapping[str, float]
+    glyphs: Mapping[str, int]
+
+class TraceSnapshot(TraceMetadata, total=False):
+    t: float
+    phase: str
+HistoryState: TypeAlias = _HistoryDict | dict[str, Any]
+TraceCallback: TypeAlias = Callable[[TNFRGraph, dict[str, Any]], None]
+
+
+class CallbackError(TypedDict):
+    event: str
+    step: int | None
+    error: str
+    traceback: str
+    fn: str
+    name: str | None
+
+
+DiagnosisNodeData: TypeAlias = Mapping[str, Any]
+DiagnosisSharedState: TypeAlias = Mapping[str, Any]
+DiagnosisPayload: TypeAlias = dict[str, Any]
+DiagnosisResult: TypeAlias = tuple[NodeId, DiagnosisPayload]
+DiagnosisPayloadChunk: TypeAlias = list[DiagnosisNodeData]
+DiagnosisResultList: TypeAlias = list[DiagnosisResult]
+DnfrCacheVectors: TypeAlias = tuple[
+    np.ndarray | None,
+    np.ndarray | None,
+    np.ndarray | None,
+    np.ndarray | None,
+    np.ndarray | None,
+]
+DnfrVectorMap: TypeAlias = dict[str, np.ndarray | None]
+NeighborStats: TypeAlias = tuple[
+    Sequence[float],
+    Sequence[float],
+    Sequence[float],
+    Sequence[float],
+    Sequence[float] | None,
+    Sequence[float] | None,
+    Sequence[float] | None,
+]
+
+GlyphogramRow: TypeAlias = MutableMapping[str, float]
+GlyphTimingTotals: TypeAlias = MutableMapping[str, float]
+GlyphTimingByNode: TypeAlias = MutableMapping[
+    Any, MutableMapping[str, MutableSequence[float]]
+]
+GlyphCounts: TypeAlias = Mapping[str, int]
+GlyphMetricsHistoryValue: TypeAlias = MutableMapping[Any, Any] | MutableSequence[Any]
+GlyphMetricsHistory: TypeAlias = MutableMapping[str, GlyphMetricsHistoryValue]
+MetricsListHistory: TypeAlias = MutableMapping[str, list[Any]]
+
+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
+
+class ParallelWijPayload(TypedDict):
+    epi_vals: Sequence[float]
+    vf_vals: Sequence[float]
+    si_vals: Sequence[float]
+    cos_vals: Sequence[float]
+    sin_vals: Sequence[float]
+    weights: tuple[float, float, float, float]
+    epi_range: float
+    vf_range: float

tnfr/units.py

@@ -0,0 +1,69 @@
+"""Structural unit conversion helpers.
+
+The TNFR engine tracks structural dynamics using the ``Hz_str`` unit.  A
+single configurable scale factor ``k`` bridges this canonical structural
+frequency with the conventional ``Hz`` base unit.  The factor is resolved
+according to the following invariants:
+
+* ``k`` is always read from the graph configuration via :func:`get_param` so
+  per-graph overrides take precedence over the package defaults.
+* The fallback value comes from :data:`tnfr.constants.DEFAULTS`, ensuring the
+  canonical 1 Hz_str↔Hz relationship is preserved when callers do not provide
+  explicit overrides.
+* ``k`` must remain strictly positive.  Invalid overrides raise
+  :class:`ValueError` to prevent incoherent conversions.
+
+All helpers defined here operate purely on ``GraphLike`` instances and only
+depend on :mod:`tnfr.constants` for configuration access, keeping the
+conversion logic transparent and side-effect free.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .constants import get_param
+from .types import GraphLike
+
+__all__ = ("get_hz_bridge", "hz_str_to_hz", "hz_to_hz_str")
+
+HZ_STR_BRIDGE_KEY: Final[str] = "HZ_STR_BRIDGE"
+
+
+def _coerce_bridge_factor(raw: object) -> float:
+    """Return ``raw`` coerced to a strictly positive floating point factor."""
+
+    try:
+        factor = float(raw)
+    except (TypeError, ValueError) as exc:  # pragma: no cover - defensive guard
+        raise TypeError(
+            "HZ_STR_BRIDGE must be a real number convertible to float"
+        ) from exc
+
+    if factor <= 0.0:
+        raise ValueError("HZ_STR_BRIDGE must be strictly positive")
+
+    return factor
+
+
+def get_hz_bridge(G: GraphLike) -> float:
+    """Return the ``Hz_str``→``Hz`` bridge factor for ``G``.
+
+    The helper always consults ``G.graph`` via :func:`get_param` so per-graph
+    overrides remain authoritative.
+    """
+
+    return _coerce_bridge_factor(get_param(G, HZ_STR_BRIDGE_KEY))
+
+
+def hz_str_to_hz(value: float, G: GraphLike) -> float:
+    """Convert ``value`` expressed in ``Hz_str`` into ``Hz`` using ``G``."""
+
+    return float(value) * get_hz_bridge(G)
+
+
+def hz_to_hz_str(value: float, G: GraphLike) -> float:
+    """Convert ``value`` expressed in ``Hz`` into ``Hz_str`` using ``G``."""
+
+    return float(value) / get_hz_bridge(G)
+

tnfr/units.pyi

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Final
+
+from .types import GraphLike
+
+__all__ = ("get_hz_bridge", "hz_str_to_hz", "hz_to_hz_str")
+
+HZ_STR_BRIDGE_KEY: Final[str]
+
+def get_hz_bridge(G: GraphLike) -> float: ...
+
+def hz_str_to_hz(value: float, G: GraphLike) -> float: ...
+
+def hz_to_hz_str(value: float, G: GraphLike) -> float: ...
+

tnfr/utils/__init__.py

@@ -0,0 +1,217 @@
+"""Shared utility helpers exposed under :mod:`tnfr.utils`."""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from . import init as _init
+from ..locking import get_lock
+
+WarnOnce = _init.WarnOnce
+cached_import = _init.cached_import
+warm_cached_import = _init.warm_cached_import
+LazyImportProxy = _init.LazyImportProxy
+get_logger = _init.get_logger
+get_nodenx = _init.get_nodenx
+get_numpy = _init.get_numpy
+prune_failed_imports = _init.prune_failed_imports
+warn_once = _init.warn_once
+_configure_root = _init._configure_root
+_reset_logging_state = _init._reset_logging_state
+_reset_import_state = _init._reset_import_state
+_warn_failure = _init._warn_failure
+_FAILED_IMPORT_LIMIT = _init._FAILED_IMPORT_LIMIT
+_DEFAULT_CACHE_SIZE = _init._DEFAULT_CACHE_SIZE
+EMIT_MAP = _init.EMIT_MAP
+
+from .cache import (
+    CacheCapacityConfig,
+    CacheLayer,
+    CacheManager,
+    CacheStatistics,
+    InstrumentedLRUCache,
+    ManagedLRUCache,
+    MappingCacheLayer,
+    RedisCacheLayer,
+    ShelveCacheLayer,
+    prune_lock_mapping,
+    DNFR_PREP_STATE_KEY,
+    DnfrPrepState,
+    DnfrCache,
+    NODE_SET_CHECKSUM_KEY,
+    ScopedCounterCache,
+    EdgeCacheManager,
+    cached_node_list,
+    cached_nodes_and_A,
+    clear_node_repr_cache,
+    configure_graph_cache_limits,
+    configure_global_cache_layers,
+    edge_version_cache,
+    edge_version_update,
+    ensure_node_index_map,
+    ensure_node_offset_map,
+    new_dnfr_cache,
+    _SeedHashCache,
+    _GRAPH_CACHE_MANAGER_KEY,
+    _graph_cache_manager,
+    build_cache_manager,
+    get_graph_version,
+    increment_edge_version,
+    increment_graph_version,
+    node_set_checksum,
+    reset_global_cache_manager,
+    stable_json,
+    _GRAPH_CACHE_LAYERS_KEY,
+)
+from .data import (
+    MAX_MATERIALIZE_DEFAULT,
+    STRING_TYPES,
+    convert_value,
+    normalize_optional_int,
+    ensure_collection,
+    flatten_structure,
+    is_non_string_sequence,
+    mix_groups,
+    negative_weights_warn_once,
+    normalize_counter,
+    normalize_materialize_limit,
+    normalize_weights,
+)
+from .chunks import auto_chunk_size, resolve_chunk_size
+from .graph import (
+    get_graph,
+    get_graph_mapping,
+    mark_dnfr_prep_dirty,
+    supports_add_edge,
+)
+from .numeric import (
+    angle_diff,
+    angle_diff_array,
+    clamp,
+    clamp01,
+    kahan_sum_nd,
+    similarity_abs,
+    within_range,
+)
+from .io import (
+    DEFAULT_PARAMS,
+    JsonDumpsParams,
+    StructuredFileError,
+    clear_orjson_param_warnings,
+    json_dumps,
+    read_structured_file,
+    safe_write,
+)
+
+__all__ = (
+    "IMPORT_LOG",
+    "WarnOnce",
+    "cached_import",
+    "warm_cached_import",
+    "LazyImportProxy",
+    "get_logger",
+    "get_lock",
+    "get_nodenx",
+    "get_numpy",
+    "prune_failed_imports",
+    "warn_once",
+    "convert_value",
+    "normalize_optional_int",
+    "normalize_weights",
+    "normalize_counter",
+    "normalize_materialize_limit",
+    "ensure_collection",
+    "flatten_structure",
+    "is_non_string_sequence",
+    "STRING_TYPES",
+    "MAX_MATERIALIZE_DEFAULT",
+    "negative_weights_warn_once",
+    "mix_groups",
+    "angle_diff",
+    "angle_diff_array",
+    "clamp",
+    "clamp01",
+    "auto_chunk_size",
+    "resolve_chunk_size",
+    "CacheCapacityConfig",
+    "CacheLayer",
+    "CacheManager",
+    "CacheStatistics",
+    "InstrumentedLRUCache",
+    "ManagedLRUCache",
+    "MappingCacheLayer",
+    "RedisCacheLayer",
+    "ShelveCacheLayer",
+    "prune_lock_mapping",
+    "EdgeCacheManager",
+    "DNFR_PREP_STATE_KEY",
+    "DnfrPrepState",
+    "DnfrCache",
+    "NODE_SET_CHECKSUM_KEY",
+    "ScopedCounterCache",
+    "cached_node_list",
+    "cached_nodes_and_A",
+    "clear_node_repr_cache",
+    "edge_version_cache",
+    "edge_version_update",
+    "configure_global_cache_layers",
+    "ensure_node_index_map",
+    "ensure_node_offset_map",
+    "new_dnfr_cache",
+    "get_graph_version",
+    "increment_edge_version",
+    "increment_graph_version",
+    "configure_graph_cache_limits",
+    "build_cache_manager",
+    "_graph_cache_manager",
+    "_GRAPH_CACHE_MANAGER_KEY",
+    "node_set_checksum",
+    "stable_json",
+    "reset_global_cache_manager",
+    "_SeedHashCache",
+    "_GRAPH_CACHE_LAYERS_KEY",
+    "get_graph",
+    "get_graph_mapping",
+    "mark_dnfr_prep_dirty",
+    "supports_add_edge",
+    "JsonDumpsParams",
+    "DEFAULT_PARAMS",
+    "json_dumps",
+    "clear_orjson_param_warnings",
+    "read_structured_file",
+    "safe_write",
+    "StructuredFileError",
+    "kahan_sum_nd",
+    "similarity_abs",
+    "within_range",
+    "_configure_root",
+    "_LOGGING_CONFIGURED",
+    "_reset_logging_state",
+    "_reset_import_state",
+    "_IMPORT_STATE",
+    "_warn_failure",
+    "_FAILED_IMPORT_LIMIT",
+    "_DEFAULT_CACHE_SIZE",
+    "EMIT_MAP",
+)
+
+#: Mapping of dynamically proxied names to the runtime types they expose.
+#:
+#: ``IMPORT_LOG`` and ``_IMPORT_STATE`` refer to the
+#: :class:`~tnfr.utils.init.ImportRegistry` instance that tracks cached import
+#: metadata, while ``_LOGGING_CONFIGURED`` is the module-level flag guarding the
+#: lazy logging bootstrap performed in :mod:`tnfr.utils.init`.
+_DYNAMIC_EXPORT_TYPES: Final[dict[str, type[object]]] = {
+    "IMPORT_LOG": _init.ImportRegistry,
+    "_IMPORT_STATE": _init.ImportRegistry,
+    "_LOGGING_CONFIGURED": bool,
+}
+_DYNAMIC_EXPORTS: Final[frozenset[str]] = frozenset(_DYNAMIC_EXPORT_TYPES)
+def __getattr__(name: str) -> Any:  # pragma: no cover - trivial delegation
+    if name in _DYNAMIC_EXPORTS:
+        return getattr(_init, name)
+    raise AttributeError(name)
+
+
+def __dir__() -> list[str]:  # pragma: no cover - trivial delegation
+    return sorted(set(globals()) | set(_DYNAMIC_EXPORTS))