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

tnfr/initialization.py

@@ -0,0 +1,203 @@
+"""Node initialization."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+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
+
+__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``.
+    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)
+
+    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)
+    # 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(
+            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,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: ...

tnfr/io.py

@@ -0,0 +1,10 @@
+"""Legacy JSON utilities module.
+
+The backwards-compatible re-export was removed; use :mod:`tnfr.utils.io`
+directly. Importing :mod:`tnfr.io` now raises an :class:`ImportError` with a
+clear migration hint.
+"""
+
+from __future__ import annotations
+
+raise ImportError("`tnfr.io` was removed. Import helpers from `tnfr.utils.io` instead.")

tnfr/io.pyi

@@ -0,0 +1,13 @@
+"""Compatibility stub removed; import from :mod:`tnfr.utils.io` instead."""
+
+from __future__ import annotations
+
+from typing import NoReturn
+
+__all__ = ()
+
+def __getattr__(name: str) -> NoReturn:
+    """Indicate that :mod:`tnfr.io` no longer exports IO helpers."""
+
+def __dir__() -> tuple[str, ...]:
+    """Return an empty set of exports to mirror the removed shim."""

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/mathematics/__init__.py

@@ -0,0 +1,79 @@
+"""Mathematics primitives aligned with TNFR coherence modeling.
+
+Backend selection
+-----------------
+Use :func:`get_backend` to retrieve a numerical backend compatible with TNFR's
+structural operators.  The selection order is ``name`` → ``TNFR_MATH_BACKEND``
+→ :func:`tnfr.config.get_flags`.  NumPy remains the canonical default so
+existing code continues to operate even when optional dependencies are absent.
+"""
+
+from .backend import (
+    MathematicsBackend,
+    available_backends,
+    ensure_array,
+    ensure_numpy,
+    get_backend,
+    register_backend,
+)
+from .dynamics import ContractiveDynamicsEngine, MathematicalDynamicsEngine
+from .epi import BEPIElement, CoherenceEvaluation, evaluate_coherence_transform
+from .generators import build_delta_nfr, build_lindblad_delta_nfr
+from .metrics import dcoh
+from .operators import CoherenceOperator, FrequencyOperator
+from .operators_factory import make_coherence_operator, make_frequency_operator
+from .projection import BasicStateProjector, StateProjector
+from .runtime import (
+    coherence,
+    coherence_expectation,
+    frequency_expectation,
+    frequency_positive,
+    normalized,
+    stable_unitary,
+)
+from .spaces import BanachSpaceEPI, HilbertSpace
+from .transforms import (
+    CoherenceMonotonicityReport,
+    CoherenceViolation,
+    IsometryFactory,
+    build_isometry_factory,
+    ensure_coherence_monotonicity,
+    validate_norm_preservation,
+)
+
+__all__ = [
+    "MathematicsBackend",
+    "ensure_array",
+    "ensure_numpy",
+    "HilbertSpace",
+    "BanachSpaceEPI",
+    "BEPIElement",
+    "CoherenceEvaluation",
+    "CoherenceOperator",
+    "ContractiveDynamicsEngine",
+    "CoherenceMonotonicityReport",
+    "CoherenceViolation",
+    "FrequencyOperator",
+    "MathematicalDynamicsEngine",
+    "build_delta_nfr",
+    "build_lindblad_delta_nfr",
+    "make_coherence_operator",
+    "make_frequency_operator",
+    "IsometryFactory",
+    "build_isometry_factory",
+    "validate_norm_preservation",
+    "ensure_coherence_monotonicity",
+    "evaluate_coherence_transform",
+    "StateProjector",
+    "BasicStateProjector",
+    "normalized",
+    "coherence",
+    "frequency_positive",
+    "stable_unitary",
+    "dcoh",
+    "coherence_expectation",
+    "frequency_expectation",
+    "available_backends",
+    "get_backend",
+    "register_backend",
+]