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

tnfr/initialization.py

@@ -0,0 +1,199 @@
+"""Node initialization."""
+
+from __future__ import annotations
+import random
+from typing import TYPE_CHECKING, cast
+
+from dataclasses import dataclass
+
+from .constants import VF_KEY, THETA_KEY, get_graph_param
+from .helpers.numeric import clamp
+from .rng import make_rng
+from .types import NodeInitAttrMap
+
+if TYPE_CHECKING:  # pragma: no cover
+    import networkx as nx
+
+__all__ = ("InitParams", "init_node_attrs")
+
+
+@dataclass
+class InitParams:
+    """Parameters governing node initialisation."""
+
+    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":
+        """Construct ``InitParams`` from ``G.graph`` configuration."""
+
+        return cls(
+            seed=get_graph_param(G, "RANDOM_SEED", int),
+            init_rand_phase=get_graph_param(G, "INIT_RANDOM_PHASE", bool),
+            th_min=get_graph_param(G, "INIT_THETA_MIN"),
+            th_max=get_graph_param(G, "INIT_THETA_MAX"),
+            vf_mode=str(get_graph_param(G, "INIT_VF_MODE", str)).lower(),
+            vf_min_lim=get_graph_param(G, "VF_MIN"),
+            vf_max_lim=get_graph_param(G, "VF_MAX"),
+            vf_uniform_min=get_graph_param(G, "INIT_VF_MIN"),
+            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
+            ),
+            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"),
+        )
+
+
+def _init_phase(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    random_phase: bool,
+    th_min: float,
+    th_max: float,
+) -> None:
+    """Initialise ``θ`` in ``nd``."""
+    if random_phase:
+        if override or THETA_KEY not in nd:
+            nd[THETA_KEY] = rng.uniform(th_min, th_max)
+    else:
+        if override:
+            nd[THETA_KEY] = 0.0
+        else:
+            nd.setdefault(THETA_KEY, 0.0)
+
+
+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:
+    """Initialise ``νf`` in ``nd``."""
+    if mode == "uniform":
+        vf = rng.uniform(vf_uniform_min, vf_uniform_max)
+    elif mode == "normal":
+        for _ in range(16):
+            cand = rng.normalvariate(vf_mean, vf_std)
+            if vf_min_lim <= cand <= vf_max_lim:
+                vf = cand
+                break
+        else:
+            vf = min(
+                max(rng.normalvariate(vf_mean, vf_std), vf_min_lim),
+                vf_max_lim,
+            )
+    else:
+        vf = float(nd.get(VF_KEY, 0.5))
+    if clamp_to_limits:
+        vf = clamp(vf, vf_min_lim, vf_max_lim)
+    if override or VF_KEY not in nd:
+        nd[VF_KEY] = vf
+
+
+def _init_si_epi(
+    nd: NodeInitAttrMap,
+    rng: random.Random,
+    *,
+    override: bool,
+    si_min: float,
+    si_max: float,
+    epi_val: float,
+) -> None:
+    """Initialise ``Si`` and ``EPI`` in ``nd``."""
+    if override or "EPI" not in nd:
+        nd["EPI"] = epi_val
+
+    si = rng.uniform(si_min, si_max)
+    if override or "Si" not in nd:
+        nd["Si"] = si
+
+
+def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
+    """Initialise EPI, θ, νf and Si on the nodes of ``G``.
+
+    Parameters can be customised via ``G.graph`` entries:
+    ``RANDOM_SEED``, ``INIT_RANDOM_PHASE``, ``INIT_THETA_MIN/MAX``,
+    ``INIT_VF_MODE``, ``VF_MIN``, ``VF_MAX``, ``INIT_VF_MIN/MAX``,
+    ``INIT_VF_MEAN``, ``INIT_VF_STD`` and ``INIT_VF_CLAMP_TO_LIMITS``.
+    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``.
+    """
+    params = InitParams.from_graph(G)
+
+    vf_uniform_min = params.vf_uniform_min
+    vf_uniform_max = params.vf_uniform_max
+    vf_min_lim = params.vf_min_lim
+    vf_max_lim = params.vf_max_lim
+    if vf_uniform_min is None:
+        vf_uniform_min = vf_min_lim
+    if vf_uniform_max is None:
+        vf_uniform_max = vf_max_lim
+    if vf_uniform_min > vf_uniform_max:
+        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)
+
+    rng = make_rng(params.seed, -1, G)
+    for _, nd in G.nodes(data=True):
+        node_attrs = cast(NodeInitAttrMap, nd)
+
+        _init_phase(
+            node_attrs,
+            rng,
+            override=override,
+            random_phase=params.init_rand_phase,
+            th_min=params.th_min,
+            th_max=params.th_max,
+        )
+        _init_vf(
+            node_attrs,
+            rng,
+            override=override,
+            mode=params.vf_mode,
+            vf_uniform_min=params.vf_uniform_min,
+            vf_uniform_max=params.vf_uniform_max,
+            vf_mean=params.vf_mean,
+            vf_std=params.vf_std,
+            vf_min_lim=params.vf_min_lim,
+            vf_max_lim=params.vf_max_lim,
+            clamp_to_limits=params.clamp_to_limits,
+        )
+        _init_si_epi(
+            node_attrs,
+            rng,
+            override=override,
+            si_min=params.si_min,
+            si_max=params.si_max,
+            epi_val=params.epi_val,
+        )
+
+    return G

tnfr/initialization.pyi

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import random
+
+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: ...

tnfr/io.py

@@ -0,0 +1,311 @@
+"""Structured file I/O utilities.
+
+Optional parsers such as ``tomllib``/``tomli`` and ``pyyaml`` are loaded via
+the :func:`tnfr.utils.cached_import` helper. Their import results and
+failure states are cached and can be cleared with
+``cached_import.cache_clear()`` and :func:`tnfr.utils.prune_failed_imports`
+when needed.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Callable
+from functools import partial
+
+from .utils import LazyImportProxy, cached_import, get_logger
+
+
+def _raise_import_error(name: str, *_: Any, **__: Any) -> Any:
+    raise ImportError(f"{name} is not installed")
+
+
+_MISSING_TOML_ERROR = type(
+    "MissingTOMLDependencyError",
+    (Exception,),
+    {"__doc__": "Fallback error used when tomllib/tomli is missing."},
+)
+
+_MISSING_YAML_ERROR = type(
+    "MissingPyYAMLDependencyError",
+    (Exception,),
+    {"__doc__": "Fallback error used when pyyaml is missing."},
+)
+
+
+def _resolve_lazy(value: Any) -> Any:
+    if isinstance(value, LazyImportProxy):
+        return value.resolve()
+    return value
+
+
+class _LazyBool:
+    __slots__ = ("_value",)
+
+    def __init__(self, value: Any) -> None:
+        self._value = value
+
+    def __bool__(self) -> bool:
+        return _resolve_lazy(self._value) is not None
+
+
+_TOMLI_MODULE = cached_import("tomli", emit="log", lazy=True)
+tomllib = cached_import(
+    "tomllib",
+    emit="log",
+    lazy=True,
+    fallback=_TOMLI_MODULE,
+)
+has_toml = _LazyBool(tomllib)
+
+
+_TOMLI_TOML_ERROR = cached_import(
+    "tomli",
+    "TOMLDecodeError",
+    emit="log",
+    lazy=True,
+    fallback=_MISSING_TOML_ERROR,
+)
+TOMLDecodeError = cached_import(
+    "tomllib",
+    "TOMLDecodeError",
+    emit="log",
+    lazy=True,
+    fallback=_TOMLI_TOML_ERROR,
+)
+
+
+_TOMLI_LOADS = cached_import(
+    "tomli",
+    "loads",
+    emit="log",
+    lazy=True,
+    fallback=partial(_raise_import_error, "tomllib/tomli"),
+)
+_TOML_LOADS: Callable[[str], Any] = cached_import(
+    "tomllib",
+    "loads",
+    emit="log",
+    lazy=True,
+    fallback=_TOMLI_LOADS,
+)
+
+
+yaml = cached_import("yaml", emit="log", lazy=True)
+
+
+YAMLError = cached_import(
+    "yaml",
+    "YAMLError",
+    emit="log",
+    lazy=True,
+    fallback=_MISSING_YAML_ERROR,
+)
+
+
+_YAML_SAFE_LOAD: Callable[[str], Any] = cached_import(
+    "yaml",
+    "safe_load",
+    emit="log",
+    lazy=True,
+    fallback=partial(_raise_import_error, "pyyaml"),
+)
+
+
+def _parse_yaml(text: str) -> Any:
+    """Parse YAML ``text`` using ``safe_load`` if available."""
+    return _YAML_SAFE_LOAD(text)
+
+
+def _parse_toml(text: str) -> Any:
+    """Parse TOML ``text`` using ``tomllib`` or ``tomli``."""
+    return _TOML_LOADS(text)
+
+
+PARSERS = {
+    ".json": json.loads,
+    ".yaml": _parse_yaml,
+    ".yml": _parse_yaml,
+    ".toml": _parse_toml,
+}
+
+
+def _get_parser(suffix: str) -> Callable[[str], Any]:
+    try:
+        return PARSERS[suffix]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported suffix: {suffix}") from exc
+
+
+_BASE_ERROR_MESSAGES: dict[type[BaseException], str] = {
+    OSError: "Could not read {path}: {e}",
+    UnicodeDecodeError: "Encoding error while reading {path}: {e}",
+    json.JSONDecodeError: "Error parsing JSON file at {path}: {e}",
+    ImportError: "Missing dependency parsing {path}: {e}",
+}
+
+
+def _resolve_exception_type(candidate: Any) -> type[BaseException] | None:
+    resolved = _resolve_lazy(candidate)
+    if isinstance(resolved, type) and issubclass(resolved, BaseException):
+        return resolved
+    return None
+
+
+_OPTIONAL_ERROR_MESSAGE_FACTORIES: tuple[
+    tuple[Callable[[], type[BaseException] | None], str],
+    ...,
+] = (
+    (lambda: _resolve_exception_type(YAMLError), "Error parsing YAML file at {path}: {e}"),
+    (lambda: _resolve_exception_type(TOMLDecodeError), "Error parsing TOML file at {path}: {e}"),
+)
+
+
+_BASE_STRUCTURED_EXCEPTIONS = (
+    OSError,
+    UnicodeDecodeError,
+    json.JSONDecodeError,
+    ImportError,
+)
+
+
+def _iter_optional_exceptions() -> list[type[BaseException]]:
+    errors: list[type[BaseException]] = []
+    for resolver, _ in _OPTIONAL_ERROR_MESSAGE_FACTORIES:
+        exc_type = resolver()
+        if exc_type is not None:
+            errors.append(exc_type)
+    return errors
+
+
+def _is_structured_error(exc: Exception) -> bool:
+    if isinstance(exc, _BASE_STRUCTURED_EXCEPTIONS):
+        return True
+    for optional_exc in _iter_optional_exceptions():
+        if isinstance(exc, optional_exc):
+            return True
+    return False
+
+
+def _format_structured_file_error(path: Path, e: Exception) -> str:
+    for exc, msg in _BASE_ERROR_MESSAGES.items():
+        if isinstance(e, exc):
+            return msg.format(path=path, e=e)
+
+    for resolver, msg in _OPTIONAL_ERROR_MESSAGE_FACTORIES:
+        exc_type = resolver()
+        if exc_type is not None and isinstance(e, exc_type):
+            return msg.format(path=path, e=e)
+
+    return f"Error parsing {path}: {e}"
+
+
+class StructuredFileError(Exception):
+    """Error while reading or parsing a structured file."""
+
+    def __init__(self, path: Path, original: Exception) -> None:
+        super().__init__(_format_structured_file_error(path, original))
+        self.path = path
+
+
+def read_structured_file(path: Path) -> Any:
+    """Read a JSON, YAML or TOML file and return parsed data."""
+    suffix = path.suffix.lower()
+    try:
+        parser = _get_parser(suffix)
+    except ValueError as e:
+        raise StructuredFileError(path, e) from e
+    try:
+        text = path.read_text(encoding="utf-8")
+        return parser(text)
+    except Exception as e:
+        if _is_structured_error(e):
+            raise StructuredFileError(path, e) from e
+        raise
+
+
+logger = get_logger(__name__)
+
+
+def safe_write(
+    path: str | Path,
+    write: Callable[[Any], Any],
+    *,
+    mode: str = "w",
+    encoding: str | None = "utf-8",
+    atomic: bool = True,
+    sync: bool | None = None,
+    **open_kwargs: Any,
+) -> None:
+    """Write to ``path`` ensuring parent directory exists and handle errors.
+
+    Parameters
+    ----------
+    path:
+        Destination file path.
+    write:
+        Callback receiving the opened file object and performing the actual
+        write.
+    mode:
+        File mode passed to :func:`open`. Text modes (default) use UTF-8
+        encoding unless ``encoding`` is ``None``. When a binary mode is used
+        (``'b'`` in ``mode``) no encoding parameter is supplied so
+        ``write`` may write bytes.
+    encoding:
+        Encoding for text modes. Ignored for binary modes.
+    atomic:
+        When ``True`` (default) writes to a temporary file and atomically
+        replaces the destination after flushing to disk. When ``False``
+        writes directly to ``path`` without any atomicity guarantee.
+    sync:
+        When ``True`` flushes and fsyncs the file descriptor after writing.
+        ``None`` uses ``atomic`` to determine syncing behaviour.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    open_params = dict(mode=mode, **open_kwargs)
+    if "b" not in mode and encoding is not None:
+        open_params["encoding"] = encoding
+    if sync is None:
+        sync = atomic
+    tmp_path: Path | None = None
+    try:
+        if atomic:
+            tmp_fd = tempfile.NamedTemporaryFile(dir=path.parent, delete=False)
+            tmp_path = Path(tmp_fd.name)
+            tmp_fd.close()
+            with open(tmp_path, **open_params) as fd:
+                write(fd)
+                if sync:
+                    fd.flush()
+                    os.fsync(fd.fileno())
+            try:
+                os.replace(tmp_path, path)
+            except OSError as e:
+                logger.error(
+                    "Atomic replace failed for %s -> %s: %s", tmp_path, path, e
+                )
+                raise
+        else:
+            with open(path, **open_params) as fd:
+                write(fd)
+                if sync:
+                    fd.flush()
+                    os.fsync(fd.fileno())
+    except (OSError, ValueError, TypeError) as e:
+        raise type(e)(f"Failed to write file {path}: {e}") from e
+    finally:
+        if tmp_path is not None:
+            tmp_path.unlink(missing_ok=True)
+
+
+__all__ = (
+    "read_structured_file",
+    "safe_write",
+    "StructuredFileError",
+    "TOMLDecodeError",
+    "YAMLError",
+)

tnfr/io.pyi

@@ -0,0 +1,11 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+StructuredFileError: Any
+TOMLDecodeError: Any
+YAMLError: Any
+read_structured_file: Any
+safe_write: Any

tnfr/locking.py

@@ -0,0 +1,37 @@
+"""Utilities for named locks.
+
+This module provides helpers to obtain process-wide ``threading.Lock``
+instances identified by name. Locks are created lazily and reused,
+allowing different modules to synchronise on shared resources without
+redefining locks repeatedly.
+"""
+
+from __future__ import annotations
+
+import threading
+from weakref import WeakValueDictionary
+
+# Registry of locks by name guarded by ``_REGISTRY_LOCK``.
+# Using ``WeakValueDictionary`` ensures that once a lock is no longer
+# referenced elsewhere, it is removed from the registry automatically,
+# keeping the catalogue aligned with active coherence nodes.
+_locks: WeakValueDictionary[str, threading.Lock] = WeakValueDictionary()
+_REGISTRY_LOCK = threading.Lock()
+
+
+def get_lock(name: str) -> threading.Lock:
+    """Return a re-usable lock identified by ``name``.
+
+    The same lock object is returned for identical names. Locks are
+    created on first use and stored in a process-wide registry.
+    """
+
+    with _REGISTRY_LOCK:
+        lock = _locks.get(name)
+        if lock is None:
+            lock = threading.Lock()
+            _locks[name] = lock
+    return lock
+
+
+__all__ = ["get_lock"]

tnfr/locking.pyi

@@ -0,0 +1,7 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+get_lock: Any

tnfr/metrics/__init__.py

@@ -0,0 +1,41 @@
+"""Registerable metrics."""
+
+from __future__ import annotations
+
+from .core import register_metrics_callbacks
+from .reporting import (
+    Tg_global,
+    Tg_by_node,
+    latency_series,
+    glyphogram_series,
+    glyph_top,
+    build_metrics_summary,
+)
+from .coherence import (
+    coherence_matrix,
+    local_phase_sync,
+    local_phase_sync_weighted,
+    register_coherence_callbacks,
+)
+from .diagnosis import (
+    register_diagnosis_callbacks,
+    dissonance_events,
+)
+from .export import export_metrics
+
+__all__ = (
+    "register_metrics_callbacks",
+    "Tg_global",
+    "Tg_by_node",
+    "latency_series",
+    "glyphogram_series",
+    "glyph_top",
+    "build_metrics_summary",
+    "coherence_matrix",
+    "local_phase_sync",
+    "local_phase_sync_weighted",
+    "register_coherence_callbacks",
+    "register_diagnosis_callbacks",
+    "dissonance_events",
+    "export_metrics",
+)

tnfr/metrics/__init__.pyi

@@ -0,0 +1,20 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+Tg_by_node: Any
+Tg_global: Any
+build_metrics_summary: Any
+coherence_matrix: Any
+dissonance_events: Any
+export_metrics: Any
+glyph_top: Any
+glyphogram_series: Any
+latency_series: Any
+local_phase_sync: Any
+local_phase_sync_weighted: Any
+register_coherence_callbacks: Any
+register_diagnosis_callbacks: Any
+register_metrics_callbacks: Any