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

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,
@@ -163,9 +162,10 @@ def init_node_attrs(G: "nx.Graph", *, override: bool = True) -> "nx.Graph":
 
     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 +173,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 +186,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: ...

tnfr/io.py

@@ -1,246 +1,12 @@
-"""Structured file I/O utilities.
+"""Legacy JSON utilities module.
 
-Optional parsers such as ``tomllib``/``tomli`` and ``pyyaml`` are loaded via
-the :func:`tnfr.import_utils.cached_import` helper. Their import results and
-failure states are cached and can be cleared with
-``cached_import.cache_clear()`` and :func:`tnfr.import_utils.prune_failed_imports`
-when needed.
+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
 
-import json
-import os
-import tempfile
-from pathlib import Path
-from typing import Any, Callable
-from functools import partial
-
-from .import_utils import cached_import
-from .logging_utils 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."},
-)
-
-
-tomllib = cached_import(
-    "tomllib",
-    emit="log",
-    fallback=cached_import("tomli", emit="log"),
-)
-has_toml = tomllib is not None
-
-
-TOMLDecodeError = cached_import(
-    "tomllib",
-    "TOMLDecodeError",
-    emit="log",
-    fallback=cached_import(
-        "tomli",
-        "TOMLDecodeError",
-        emit="log",
-        fallback=_MISSING_TOML_ERROR,
-    ),
-)
-
-
-_TOML_LOADS: Callable[[str], Any] = cached_import(
-    "tomllib",
-    "loads",
-    emit="log",
-    fallback=cached_import(
-        "tomli",
-        "loads",
-        emit="log",
-        fallback=partial(_raise_import_error, "tomllib/tomli"),
-    ),
-)
-
-
-yaml = cached_import("yaml", emit="log")
-
-
-YAMLError = cached_import(
-    "yaml",
-    "YAMLError",
-    emit="log",
-    fallback=_MISSING_YAML_ERROR,
-)
-
-
-_YAML_SAFE_LOAD: Callable[[str], Any] = cached_import(
-    "yaml",
-    "safe_load",
-    emit="log",
-    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
-
-
-ERROR_MESSAGES = {
-    OSError: "Could not read {path}: {e}",
-    UnicodeDecodeError: "Encoding error while reading {path}: {e}",
-    json.JSONDecodeError: "Error parsing JSON file at {path}: {e}",
-    YAMLError: "Error parsing YAML file at {path}: {e}",
-    ImportError: "Missing dependency parsing {path}: {e}",
-}
-if has_toml:
-    ERROR_MESSAGES[TOMLDecodeError] = "Error parsing TOML file at {path}: {e}"
-
-
-def _format_structured_file_error(path: Path, e: Exception) -> str:
-    for exc, msg in ERROR_MESSAGES.items():
-        if isinstance(e, exc):
-            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):
-        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 (
-        OSError,
-        UnicodeDecodeError,
-        json.JSONDecodeError,
-        YAMLError,
-        TOMLDecodeError,
-        ImportError,
-    ) as e:
-        raise StructuredFileError(path, e) from e
-
-
-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",
+raise ImportError(
+    "`tnfr.io` was removed. Import helpers from `tnfr.utils.io` instead."
 )

tnfr/io.pyi

@@ -0,0 +1,16 @@
+"""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.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,81 @@
+"""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,
+)
+from ..validation import NFRValidator
+
+__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",
+    "NFRValidator",
+    "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",
+]