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

tnfr/gamma.py

@@ -1,127 +1,358 @@
-"""gamma.py — TNFR canónica
+"""Gamma registry."""
 
-Γi(R): acoplamientos de red para la ecuación nodal extendida
-    ∂EPI/∂t = νf · ΔNFR(t) + Γi(R)
+from __future__ import annotations
+from typing import Any, Callable, NamedTuple
+import math
+import logging
+import hashlib
+from collections.abc import Mapping
+from functools import lru_cache
+from types import MappingProxyType
 
-`Γ` suma un término de acoplamiento dependiente del orden global de fase
-`R`. La especificación se toma de ``G.graph['GAMMA']`` (ver
-``DEFAULTS['GAMMA']``) con parámetros como:
+from .constants import DEFAULTS
+from .alias import get_theta_attr
+from .types import GammaSpec, NodeId, TNFRGraph
+from .utils import (
+    edge_version_cache,
+    get_graph_mapping,
+    get_logger,
+    json_dumps,
+    node_set_checksum,
+)
+from .metrics.trig_cache import get_trig_cache
 
-* ``type`` – modo de acoplamiento (``none``, ``kuramoto_linear``,
-  ``kuramoto_bandpass``)
-* ``beta`` – ganancia del acoplamiento
-* ``R0`` – umbral de activación (solo lineal)
 
-Provee:
-- kuramoto_R_psi(G): (R, ψ) orden de Kuramoto en la red
-- GAMMA_REGISTRY: registro de acoplamientos canónicos
-- eval_gamma(G, node, t): evalúa Γ para cada nodo según la config
-"""
-from __future__ import annotations
-from typing import Dict, Any, Tuple
-import math
-import cmath
+logger = get_logger(__name__)
+
+DEFAULT_GAMMA: Mapping[str, Any] = MappingProxyType(dict(DEFAULTS["GAMMA"]))
+
+__all__ = (
+    "kuramoto_R_psi",
+    "gamma_none",
+    "gamma_kuramoto_linear",
+    "gamma_kuramoto_bandpass",
+    "gamma_kuramoto_tanh",
+    "gamma_harmonic",
+    "GammaEntry",
+    "GAMMA_REGISTRY",
+    "eval_gamma",
+)
+
+
+@lru_cache(maxsize=1)
+def _default_gamma_spec() -> tuple[bytes, str]:
+    dumped = json_dumps(dict(DEFAULT_GAMMA), sort_keys=True, to_bytes=True)
+    hash_ = hashlib.blake2b(dumped, digest_size=16).hexdigest()
+    return dumped, hash_
+
 
-from .constants import ALIAS_THETA
-from .helpers import _get_attr
+def _ensure_kuramoto_cache(G: TNFRGraph, t: float | int) -> None:
+    """Cache ``(R, ψ)`` for the current step ``t`` using
+    ``edge_version_cache``."""
+    checksum = G.graph.get("_dnfr_nodes_checksum")
+    if checksum is None:
+        # reuse checksum from cached_nodes_and_A when available
+        checksum = node_set_checksum(G)
+    nodes_sig = (len(G), checksum)
+    max_steps = int(G.graph.get("KURAMOTO_CACHE_STEPS", 1))
 
+    def builder() -> dict[str, float]:
+        R, psi = kuramoto_R_psi(G)
+        return {"R": R, "psi": psi}
 
-def kuramoto_R_psi(G) -> Tuple[float, float]:
-    """Devuelve (R, ψ) del orden de Kuramoto usando θ de todos los nodos."""
-    acc = 0 + 0j
-    n = 0
-    for node in G.nodes():
-        nd = G.nodes[node]
-        th = _get_attr(nd, ALIAS_THETA, 0.0)
-        acc += cmath.exp(1j * th)
-        n += 1
+    key = (t, nodes_sig)
+    entry = edge_version_cache(G, key, builder, max_entries=max_steps)
+    G.graph["_kuramoto_cache"] = entry
+
+
+def kuramoto_R_psi(G: TNFRGraph) -> tuple[float, float]:
+    """Return ``(R, ψ)`` for Kuramoto order using θ from all nodes."""
+    max_steps = int(G.graph.get("KURAMOTO_CACHE_STEPS", 1))
+    trig = get_trig_cache(G, cache_size=max_steps)
+    n = len(trig.theta)
     if n == 0:
         return 0.0, 0.0
-    z = acc / n
-    return abs(z), math.atan2(z.imag, z.real)
+
+    cos_sum = sum(trig.cos.values())
+    sin_sum = sum(trig.sin.values())
+    R = math.hypot(cos_sum, sin_sum) / n
+    psi = math.atan2(sin_sum, cos_sum)
+    return R, psi
+
+
+def _kuramoto_common(
+    G: TNFRGraph, node: NodeId, _cfg: GammaSpec
+) -> tuple[float, float, float]:
+    """Return ``(θ_i, R, ψ)`` for Kuramoto-based Γ functions.
+
+    Reads cached global order ``R`` and mean phase ``ψ`` and obtains node
+    phase ``θ_i``. ``_cfg`` is accepted only to keep a homogeneous signature
+    with Γ evaluators.
+    """
+    cache = G.graph.get("_kuramoto_cache", {})
+    R = float(cache.get("R", 0.0))
+    psi = float(cache.get("psi", 0.0))
+    th_val = get_theta_attr(G.nodes[node], 0.0)
+    th_i = float(th_val if th_val is not None else 0.0)
+    return th_i, R, psi
+
+
+def _read_gamma_raw(G: TNFRGraph) -> GammaSpec | None:
+    """Return raw Γ specification from ``G.graph['GAMMA']``.
+
+    The returned value is the direct contents of ``G.graph['GAMMA']`` when
+    it is a mapping or the result of :func:`get_graph_mapping` if a path is
+    provided.  Final validation and caching are handled elsewhere.
+    """
+
+    raw = G.graph.get("GAMMA")
+    if raw is None or isinstance(raw, Mapping):
+        return raw
+    return get_graph_mapping(
+        G,
+        "GAMMA",
+        "G.graph['GAMMA'] is not a mapping; using {'type': 'none'}",
+    )
+
+
+def _get_gamma_spec(G: TNFRGraph) -> GammaSpec:
+    """Return validated Γ specification caching results.
+
+    The raw value from ``G.graph['GAMMA']`` is cached together with the
+    normalized specification and its hash. When the raw value is unchanged,
+    the cached spec is returned without re-reading or re-validating,
+    preventing repeated warnings or costly hashing.
+    """
+
+    raw = G.graph.get("GAMMA")
+    cached_raw = G.graph.get("_gamma_raw")
+    cached_spec = G.graph.get("_gamma_spec")
+    cached_hash = G.graph.get("_gamma_spec_hash")
+
+    def _hash_mapping(mapping: GammaSpec) -> str:
+        dumped = json_dumps(mapping, sort_keys=True, to_bytes=True)
+        return hashlib.blake2b(dumped, digest_size=16).hexdigest()
+
+    mapping_hash: str | None = None
+    if isinstance(raw, Mapping):
+        mapping_hash = _hash_mapping(raw)
+        if (
+            raw is cached_raw
+            and cached_spec is not None
+            and cached_hash == mapping_hash
+        ):
+            return cached_spec
+    elif raw is cached_raw and cached_spec is not None and cached_hash is not None:
+        return cached_spec
+
+    if raw is None:
+        spec = DEFAULT_GAMMA
+        _, cur_hash = _default_gamma_spec()
+    elif isinstance(raw, Mapping):
+        spec = raw
+        cur_hash = mapping_hash if mapping_hash is not None else _hash_mapping(spec)
+    else:
+        spec_raw = _read_gamma_raw(G)
+        if isinstance(spec_raw, Mapping) and spec_raw is not None:
+            spec = spec_raw
+            cur_hash = _hash_mapping(spec)
+        else:
+            spec = DEFAULT_GAMMA
+            _, cur_hash = _default_gamma_spec()
+
+    # Store raw input, validated spec and its hash for future calls
+    G.graph["_gamma_raw"] = raw
+    G.graph["_gamma_spec"] = spec
+    G.graph["_gamma_spec_hash"] = cur_hash
+    return spec
 
 
 # -----------------
-# Γi(R) canónicos
+# Helpers
 # -----------------
 
 
-def gamma_none(G, node, t, cfg: Dict[str, Any]) -> float:
-    return 0.0
+def _gamma_params(
+    cfg: GammaSpec, **defaults: float
+) -> tuple[float, ...]:
+    """Return normalized Γ parameters from ``cfg``.
+
+    Parameters are retrieved from ``cfg`` using the keys in ``defaults`` and
+    converted to ``float``. If a key is missing, its value from ``defaults`` is
+    used. Values convertible to ``float`` (e.g. strings) are accepted.
 
+    Example
+    -------
+    >>> beta, R0 = _gamma_params(cfg, beta=0.0, R0=0.0)
+    """
 
-def gamma_kuramoto_linear(G, node, t, cfg: Dict[str, Any]) -> float:
-    """Acoplamiento lineal de Kuramoto para Γi(R).
+    return tuple(
+        float(cfg.get(name, default)) for name, default in defaults.items()
+    )
 
-    Fórmula: Γ = β · (R - R0) · cos(θ_i - ψ)
-      - R ∈ [0,1] es el orden global de fase.
-      - ψ es la fase media (dirección de coordinación).
-      - β, R0 son parámetros (ganancia/umbral).
 
-    Uso: refuerza integración cuando la red ya exhibe coherencia de fase (R>R0).
+# -----------------
+# Canonical Γi(R)
+# -----------------
+
+
+def gamma_none(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
+    return 0.0
+
+
+def _gamma_kuramoto(
+    G: TNFRGraph,
+    node: NodeId,
+    cfg: GammaSpec,
+    builder: Callable[..., float],
+    **defaults: float,
+) -> float:
+    """Helper for Kuramoto-based Γ functions.
+
+    ``builder`` receives ``(θ_i, R, ψ, *params)`` where ``params`` are
+    extracted from ``cfg`` according to ``defaults``.
     """
-    beta = float(cfg.get("beta", 0.0))
-    R0 = float(cfg.get("R0", 0.0))
-    R, psi = kuramoto_R_psi(G)
-    th_i = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+
+    params = _gamma_params(cfg, **defaults)
+    th_i, R, psi = _kuramoto_common(G, node, cfg)
+    return builder(th_i, R, psi, *params)
+
+
+def _builder_linear(th_i: float, R: float, psi: float, beta: float, R0: float) -> float:
     return beta * (R - R0) * math.cos(th_i - psi)
 
 
-def gamma_kuramoto_bandpass(G, node, t, cfg: Dict[str, Any]) -> float:
-    """Γ = β · R(1-R) · sign(cos(θ_i - ψ))"""
-    beta = float(cfg.get("beta", 0.0))
-    R, psi = kuramoto_R_psi(G)
-    th_i = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
+def _builder_bandpass(th_i: float, R: float, psi: float, beta: float) -> float:
     sgn = 1.0 if math.cos(th_i - psi) >= 0.0 else -1.0
     return beta * R * (1.0 - R) * sgn
 
 
-def gamma_kuramoto_tanh(G, node, t, cfg: Dict[str, Any]) -> float:
-    """Acoplamiento saturante tipo tanh para Γi(R).
+def _builder_tanh(th_i: float, R: float, psi: float, beta: float, k: float, R0: float) -> float:
+    return beta * math.tanh(k * (R - R0)) * math.cos(th_i - psi)
+
+
+def gamma_kuramoto_linear(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
+    """Linear Kuramoto coupling for Γi(R).
+
+    Formula: Γ = β · (R - R0) · cos(θ_i - ψ)
+      - R ∈ [0,1] is the global phase order.
+      - ψ is the mean phase (coordination direction).
+      - β, R0 are parameters (gain/threshold).
 
-    Fórmula: Γ = β · tanh(k·(R - R0)) · cos(θ_i - ψ)
-      - β: ganancia del acoplamiento
-      - k: pendiente de la tanh (cuán rápido satura)
-      - R0: umbral de activación
+    Use: reinforces integration when the network already shows phase
+    coherence (R>R0).
     """
-    beta = float(cfg.get("beta", 0.0))
-    k = float(cfg.get("k", 1.0))
-    R0 = float(cfg.get("R0", 0.0))
-    R, psi = kuramoto_R_psi(G)
-    th_i = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
-    return beta * math.tanh(k * (R - R0)) * math.cos(th_i - psi)
 
+    return _gamma_kuramoto(G, node, cfg, _builder_linear, beta=0.0, R0=0.0)
 
-def gamma_harmonic(G, node, t, cfg: Dict[str, Any]) -> float:
-    """Forzamiento armónico coherente con el campo global de fase.
 
-    Fórmula: Γ = β · sin(ω·t + φ) · cos(θ_i - ψ)
-      - β: ganancia del acoplamiento
-      - ω: frecuencia angular del forzante
-      - φ: fase inicial del forzante
+def gamma_kuramoto_bandpass(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
+    """Γ = β · R(1-R) · sign(cos(θ_i - ψ))"""
+
+    return _gamma_kuramoto(G, node, cfg, _builder_bandpass, beta=0.0)
+
+
+def gamma_kuramoto_tanh(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
+    """Saturating tanh coupling for Γi(R).
+
+    Formula: Γ = β · tanh(k·(R - R0)) · cos(θ_i - ψ)
+      - β: coupling gain
+      - k: tanh slope (how fast it saturates)
+      - R0: activation threshold
+    """
+
+    return _gamma_kuramoto(G, node, cfg, _builder_tanh, beta=0.0, k=1.0, R0=0.0)
+
+
+def gamma_harmonic(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float:
+    """Harmonic forcing aligned with the global phase field.
+
+    Formula: Γ = β · sin(ω·t + φ) · cos(θ_i - ψ)
+      - β: coupling gain
+      - ω: angular frequency of the forcing
+      - φ: initial phase of the forcing
     """
-    beta = float(cfg.get("beta", 0.0))
-    omega = float(cfg.get("omega", 1.0))
-    phi = float(cfg.get("phi", 0.0))
-    R, psi = kuramoto_R_psi(G)
-    th = _get_attr(G.nodes[node], ALIAS_THETA, 0.0)
-    return beta * math.sin(omega * t + phi) * math.cos(th - psi)
-
-
-GAMMA_REGISTRY = {
-    "none": gamma_none,
-    "kuramoto_linear": gamma_kuramoto_linear,
-    "kuramoto_bandpass": gamma_kuramoto_bandpass,
-    "kuramoto_tanh": gamma_kuramoto_tanh,
-    "harmonic": gamma_harmonic,
+    beta, omega, phi = _gamma_params(cfg, beta=0.0, omega=1.0, phi=0.0)
+    th_i, _, psi = _kuramoto_common(G, node, cfg)
+    return beta * math.sin(omega * t + phi) * math.cos(th_i - psi)
+
+
+class GammaEntry(NamedTuple):
+    fn: Callable[[TNFRGraph, NodeId, float | int, GammaSpec], float]
+    needs_kuramoto: bool
+
+
+# ``GAMMA_REGISTRY`` associates each coupling name with a ``GammaEntry`` where
+# ``fn`` is the evaluation function and ``needs_kuramoto`` indicates whether
+# the global phase order must be precomputed.
+GAMMA_REGISTRY: dict[str, GammaEntry] = {
+    "none": GammaEntry(gamma_none, False),
+    "kuramoto_linear": GammaEntry(gamma_kuramoto_linear, True),
+    "kuramoto_bandpass": GammaEntry(gamma_kuramoto_bandpass, True),
+    "kuramoto_tanh": GammaEntry(gamma_kuramoto_tanh, True),
+    "harmonic": GammaEntry(gamma_harmonic, True),
 }
 
 
-def eval_gamma(G, node, t) -> float:
-    """Evalúa Γi para `node` según la especificación en G.graph['GAMMA']."""
-    spec = G.graph.get("GAMMA", {"type": "none"})
-    fn = GAMMA_REGISTRY.get(spec.get("type", "none"), gamma_none)
+def eval_gamma(
+    G: TNFRGraph,
+    node: NodeId,
+    t: float | int,
+    *,
+    strict: bool = False,
+    log_level: int | None = None,
+) -> float:
+    """Evaluate Γi for ``node`` according to ``G.graph['GAMMA']``
+    specification.
+
+    If ``strict`` is ``True`` exceptions raised during evaluation are
+    propagated instead of returning ``0.0``. Likewise, if the specified
+    Γ type is not registered a warning is emitted (or ``ValueError`` in
+    strict mode) and ``gamma_none`` is used.
+
+    ``log_level`` controls the logging level for captured errors when
+    ``strict`` is ``False``. If omitted, ``logging.ERROR`` is used in
+    strict mode and ``logging.DEBUG`` otherwise.
+    """
+    spec = _get_gamma_spec(G)
+    spec_type = spec.get("type", "none")
+    reg_entry = GAMMA_REGISTRY.get(spec_type)
+    if reg_entry is None:
+        msg = f"Unknown GAMMA type: {spec_type}"
+        if strict:
+            raise ValueError(msg)
+        logger.warning(msg)
+        entry = GammaEntry(gamma_none, False)
+    else:
+        entry = reg_entry
+    if entry.needs_kuramoto:
+        _ensure_kuramoto_cache(G, t)
     try:
-        return float(fn(G, node, t, spec))
-    except Exception:
+        return float(entry.fn(G, node, t, spec))
+    except (ValueError, TypeError, ArithmeticError) as exc:
+        level = (
+            log_level
+            if log_level is not None
+            else (logging.ERROR if strict else logging.DEBUG)
+        )
+        logger.log(
+            level,
+            "Failed to evaluate Γi for node %s at t=%s: %s: %s",
+            node,
+            t,
+            exc.__class__.__name__,
+            exc,
+        )
+        if strict:
+            raise
         return 0.0

tnfr/gamma.pyi

@@ -0,0 +1,40 @@
+from typing import Callable, NamedTuple
+
+from .types import GammaSpec, NodeId, TNFRGraph
+
+__all__: tuple[str, ...]
+
+class GammaEntry(NamedTuple):
+    fn: Callable[[TNFRGraph, NodeId, float | int, GammaSpec], float]
+    needs_kuramoto: bool
+
+GAMMA_REGISTRY: dict[str, GammaEntry]
+
+def kuramoto_R_psi(G: TNFRGraph) -> tuple[float, float]: ...
+
+def gamma_none(G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec) -> float: ...
+
+def gamma_kuramoto_linear(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def gamma_kuramoto_bandpass(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def gamma_kuramoto_tanh(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def gamma_harmonic(
+    G: TNFRGraph, node: NodeId, t: float | int, cfg: GammaSpec
+) -> float: ...
+
+def eval_gamma(
+    G: TNFRGraph,
+    node: NodeId,
+    t: float | int,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+) -> float: ...