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

tnfr/metrics/sense_index.py

@@ -3,17 +3,21 @@
 from __future__ import annotations
 
 import math
+from concurrent.futures import ProcessPoolExecutor
 from functools import partial
-from typing import Any
+from typing import Any, Iterable, Mapping
 
 from ..alias import get_attr, set_attr
-from ..collections_utils import normalize_weights
 from ..constants import get_aliases
-from ..cache import edge_version_cache, stable_json
 from ..helpers.numeric import angle_diff, clamp01
-from .trig import neighbor_phase_mean_list
-from ..import_utils import get_numpy
 from ..types import GraphLike
+from ..utils import (
+    edge_version_cache,
+    get_numpy,
+    normalize_weights,
+    stable_json,
+)
+from .trig import neighbor_phase_mean_list
 
 from .common import (
     ensure_neighbors_map,
@@ -25,17 +29,44 @@ from .trig_cache import get_trig_cache
 ALIAS_VF = get_aliases("VF")
 ALIAS_DNFR = get_aliases("DNFR")
 ALIAS_SI = get_aliases("SI")
-ALIAS_THETA = get_aliases("THETA")
 
+PHASE_DISPERSION_KEY = "dSi_dphase_disp"
+_VALID_SENSITIVITY_KEYS = frozenset(
+    {"dSi_dvf_norm", PHASE_DISPERSION_KEY, "dSi_ddnfr_norm"}
+)
 __all__ = ("get_Si_weights", "compute_Si_node", "compute_Si")
 
 
+def _normalise_si_sensitivity_mapping(
+    mapping: Mapping[str, float], *, warn: bool
+) -> dict[str, float]:
+    """Return a mapping containing only supported Si sensitivity keys."""
+
+    normalised = dict(mapping)
+    _ = warn  # kept for API compatibility with trace helpers
+    unexpected = sorted(k for k in normalised if k not in _VALID_SENSITIVITY_KEYS)
+    if unexpected:
+        allowed = ", ".join(sorted(_VALID_SENSITIVITY_KEYS))
+        received = ", ".join(unexpected)
+        raise ValueError(
+            "Si sensitivity mappings accept only {%s}; unexpected key(s): %s"
+            % (allowed, received)
+        )
+    return normalised
+
+
 def _cache_weights(G: GraphLike) -> tuple[float, float, float]:
     """Normalise and cache Si weights, delegating persistence."""
 
     w = merge_graph_weights(G, "SI_WEIGHTS")
     cfg_key = stable_json(w)
 
+    existing = G.graph.get("_Si_sensitivity")
+    if isinstance(existing, Mapping):
+        migrated = _normalise_si_sensitivity_mapping(existing, warn=True)
+        if migrated != existing:
+            G.graph["_Si_sensitivity"] = migrated
+
     def builder() -> tuple[float, float, float]:
         weights = normalize_weights(w, ("alpha", "beta", "gamma"), default=0.0)
         alpha = weights["alpha"]
@@ -45,7 +76,7 @@ def _cache_weights(G: GraphLike) -> tuple[float, float, float]:
         G.graph["_Si_weights_key"] = cfg_key
         G.graph["_Si_sensitivity"] = {
             "dSi_dvf_norm": alpha,
-            "dSi_ddisp_fase": -beta,
+            PHASE_DISPERSION_KEY: -beta,
             "dSi_ddnfr_norm": -gamma,
         }
         return alpha, beta, gamma
@@ -68,25 +99,84 @@ def compute_Si_node(
     gamma: float,
     vfmax: float,
     dnfrmax: float,
-    disp_fase: float,
+    phase_dispersion: float | None = None,
     inplace: bool,
+    **kwargs: Any,
 ) -> float:
     """Compute ``Si`` for a single node."""
 
+    if kwargs:
+        unexpected = ", ".join(sorted(kwargs))
+        raise TypeError(f"Unexpected keyword argument(s): {unexpected}")
+
+    if phase_dispersion is None:
+        raise TypeError("Missing required keyword-only argument: 'phase_dispersion'")
+
     vf = get_attr(nd, ALIAS_VF, 0.0)
     vf_norm = clamp01(abs(vf) / vfmax)
 
     dnfr = get_attr(nd, ALIAS_DNFR, 0.0)
     dnfr_norm = clamp01(abs(dnfr) / dnfrmax)
 
-    Si = alpha * vf_norm + beta * (1.0 - disp_fase) + gamma * (1.0 - dnfr_norm)
+    Si = (
+        alpha * vf_norm
+        + beta * (1.0 - phase_dispersion)
+        + gamma * (1.0 - dnfr_norm)
+    )
     Si = clamp01(Si)
     if inplace:
         set_attr(nd, ALIAS_SI, Si)
     return Si
 
 
-def compute_Si(G: GraphLike, *, inplace: bool = True) -> dict[Any, float]:
+def _coerce_jobs(raw_jobs: Any | None) -> int | None:
+    """Normalise ``n_jobs`` values coming from user configuration."""
+
+    try:
+        jobs = None if raw_jobs is None else int(raw_jobs)
+    except (TypeError, ValueError):
+        return None
+    if jobs is not None and jobs <= 0:
+        return None
+    return jobs
+
+
+def _compute_si_python_chunk(
+    chunk: Iterable[tuple[Any, tuple[Any, ...], float, float, float]],
+    *,
+    cos_th: dict[Any, float],
+    sin_th: dict[Any, float],
+    alpha: float,
+    beta: float,
+    gamma: float,
+    vfmax: float,
+    dnfrmax: float,
+) -> dict[Any, float]:
+    """Compute Si values for a chunk of nodes using pure Python math."""
+
+    results: dict[Any, float] = {}
+    for n, neigh, theta, vf, dnfr in chunk:
+        th_bar = neighbor_phase_mean_list(
+            neigh, cos_th=cos_th, sin_th=sin_th, np=None, fallback=theta
+        )
+        phase_dispersion = abs(angle_diff(theta, th_bar)) / math.pi
+        vf_norm = clamp01(abs(vf) / vfmax)
+        dnfr_norm = clamp01(abs(dnfr) / dnfrmax)
+        Si = (
+            alpha * vf_norm
+            + beta * (1.0 - phase_dispersion)
+            + gamma * (1.0 - dnfr_norm)
+        )
+        results[n] = clamp01(Si)
+    return results
+
+
+def compute_Si(
+    G: GraphLike,
+    *,
+    inplace: bool = True,
+    n_jobs: int | None = None,
+) -> dict[Any, float]:
     """Compute ``Si`` per node and optionally store it on the graph."""
 
     neighbors = ensure_neighbors_map(G)
@@ -101,20 +191,104 @@ def compute_Si(G: GraphLike, *, inplace: bool = True) -> dict[Any, float]:
         neighbor_phase_mean_list, cos_th=cos_th, sin_th=sin_th, np=np
     )
 
-    out: dict[Any, float] = {}
-    for n, nd in G.nodes(data=True):
-        neigh = neighbors[n]
-        th_bar = pm_fn(neigh, fallback=thetas[n])
-        disp_fase = abs(angle_diff(thetas[n], th_bar)) / math.pi
-        out[n] = compute_Si_node(
-            n,
-            nd,
-            alpha=alpha,
-            beta=beta,
-            gamma=gamma,
-            vfmax=vfmax,
-            dnfrmax=dnfrmax,
-            disp_fase=disp_fase,
-            inplace=inplace,
+    if n_jobs is None:
+        n_jobs = _coerce_jobs(G.graph.get("SI_N_JOBS"))
+    else:
+        n_jobs = _coerce_jobs(n_jobs)
+
+    supports_vector = (
+        np is not None
+        and hasattr(np, "ndarray")
+        and all(hasattr(np, attr) for attr in ("fromiter", "abs", "clip", "remainder"))
+    )
+
+    nodes_data = list(G.nodes(data=True))
+    if not nodes_data:
+        return {}
+
+    if supports_vector:
+        node_ids: list[Any] = []
+        theta_vals: list[float] = []
+        mean_vals: list[float] = []
+        vf_vals: list[float] = []
+        dnfr_vals: list[float] = []
+        for n, nd in nodes_data:
+            theta = thetas.get(n, 0.0)
+            neigh = neighbors[n]
+            node_ids.append(n)
+            theta_vals.append(theta)
+            mean_vals.append(pm_fn(neigh, fallback=theta))
+            vf_vals.append(get_attr(nd, ALIAS_VF, 0.0))
+            dnfr_vals.append(get_attr(nd, ALIAS_DNFR, 0.0))
+
+        count = len(node_ids)
+        theta_arr = np.fromiter(theta_vals, dtype=float, count=count)
+        mean_arr = np.fromiter(mean_vals, dtype=float, count=count)
+        diff = np.remainder(theta_arr - mean_arr + math.pi, math.tau) - math.pi
+        phase_dispersion_arr = np.abs(diff) / math.pi
+
+        vf_arr = np.fromiter(vf_vals, dtype=float, count=count)
+        dnfr_arr = np.fromiter(dnfr_vals, dtype=float, count=count)
+        vf_norm = np.clip(np.abs(vf_arr) / vfmax, 0.0, 1.0)
+        dnfr_norm = np.clip(np.abs(dnfr_arr) / dnfrmax, 0.0, 1.0)
+
+        si_arr = np.clip(
+            alpha * vf_norm + beta * (1.0 - phase_dispersion_arr)
+            + gamma * (1.0 - dnfr_norm),
+            0.0,
+            1.0,
         )
+
+        out = {node_ids[i]: float(si_arr[i]) for i in range(count)}
+    else:
+        out: dict[Any, float] = {}
+        if n_jobs is not None and n_jobs > 1:
+            node_payload: list[tuple[Any, tuple[Any, ...], float, float, float]] = []
+            for n, nd in nodes_data:
+                theta = thetas.get(n, 0.0)
+                vf = float(get_attr(nd, ALIAS_VF, 0.0))
+                dnfr = float(get_attr(nd, ALIAS_DNFR, 0.0))
+                neigh = neighbors[n]
+                node_payload.append((n, tuple(neigh), theta, vf, dnfr))
+
+            if node_payload:
+                chunk_size = math.ceil(len(node_payload) / n_jobs)
+                with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+                    futures = [
+                        executor.submit(
+                            _compute_si_python_chunk,
+                            node_payload[idx:idx + chunk_size],
+                            cos_th=cos_th,
+                            sin_th=sin_th,
+                            alpha=alpha,
+                            beta=beta,
+                            gamma=gamma,
+                            vfmax=vfmax,
+                            dnfrmax=dnfrmax,
+                        )
+                        for idx in range(0, len(node_payload), chunk_size)
+                    ]
+                    for future in futures:
+                        out.update(future.result())
+        else:
+            for n, nd in nodes_data:
+                theta = thetas.get(n, 0.0)
+                neigh = neighbors[n]
+                th_bar = pm_fn(neigh, fallback=theta)
+                phase_dispersion = abs(angle_diff(theta, th_bar)) / math.pi
+                out[n] = compute_Si_node(
+                    n,
+                    nd,
+                    alpha=alpha,
+                    beta=beta,
+                    gamma=gamma,
+                    vfmax=vfmax,
+                    dnfrmax=dnfrmax,
+                    phase_dispersion=phase_dispersion,
+                    inplace=False,
+                )
+
+    if inplace:
+        for n, value in out.items():
+            set_attr(G.nodes[n], ALIAS_SI, value)
     return out

tnfr/metrics/sense_index.pyi

@@ -0,0 +1,9 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+compute_Si: Any
+compute_Si_node: Any
+get_Si_weights: Any

tnfr/metrics/trig.py

@@ -7,12 +7,16 @@ Caching of cosine/sine values lives in :mod:`tnfr.metrics.trig_cache`.
 from __future__ import annotations
 
 import math
-from collections.abc import Iterable, Sequence
+from collections.abc import Iterable, Iterator, Sequence
 from itertools import tee
-from typing import Any
+from typing import TYPE_CHECKING, Any, overload, cast
 
-from ..import_utils import cached_import, get_numpy
 from ..helpers.numeric import kahan_sum_nd
+from ..utils import cached_import, get_numpy
+from ..types import NodeId, Phase, TNFRGraph
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ..node import NodeProtocol
 
 __all__ = (
     "accumulate_cos_sin",
@@ -37,7 +41,7 @@ def accumulate_cos_sin(
 
     processed = False
 
-    def iter_real_pairs():
+    def iter_real_pairs() -> Iterator[tuple[float, float]]:
         nonlocal processed
         for cs in it:
             if cs is None:
@@ -82,12 +86,12 @@ def _neighbor_phase_mean_core(
     neigh: Sequence[Any],
     cos_map: dict[Any, float],
     sin_map: dict[Any, float],
-    np,
+    np: Any | None,
     fallback: float,
 ) -> float:
     """Return circular mean of neighbour phases given trig mappings."""
 
-    def _iter_pairs():
+    def _iter_pairs() -> Iterator[tuple[float, float]]:
         for v in neigh:
             c = cos_map.get(v)
             s = sin_map.get(v)
@@ -113,10 +117,10 @@ def _neighbor_phase_mean_core(
 
 
 def _neighbor_phase_mean_generic(
-    obj,
+    obj: "NodeProtocol" | Sequence[Any],
     cos_map: dict[Any, float] | None = None,
     sin_map: dict[Any, float] | None = None,
-    np=None,
+    np: Any | None = None,
     fallback: float = 0.0,
 ) -> float:
     """Internal helper delegating to :func:`_neighbor_phase_mean_core`.
@@ -132,7 +136,7 @@ def _neighbor_phase_mean_generic(
         np = get_numpy()
 
     if cos_map is None or sin_map is None:
-        node = obj
+        node = cast("NodeProtocol", obj)
         if getattr(node, "G", None) is None:
             raise TypeError(
                 "neighbor_phase_mean requires nodes bound to a graph"
@@ -145,7 +149,7 @@ def _neighbor_phase_mean_generic(
         sin_map = trig.sin
         neigh = node.G[node.n]
     else:
-        neigh = obj
+        neigh = cast(Sequence[Any], obj)
 
     return _neighbor_phase_mean_core(neigh, cos_map, sin_map, np, fallback)
 
@@ -154,7 +158,7 @@ def neighbor_phase_mean_list(
     neigh: Sequence[Any],
     cos_th: dict[Any, float],
     sin_th: dict[Any, float],
-    np=None,
+    np: Any | None = None,
     fallback: float = 0.0,
 ) -> float:
     """Return circular mean of neighbour phases from cosine/sine mappings.
@@ -168,14 +172,45 @@ def neighbor_phase_mean_list(
     )
 
 
-def neighbor_phase_mean(obj, n=None) -> float:
-    """Circular mean of neighbour phases.
+@overload
+def neighbor_phase_mean(obj: "NodeProtocol", n: None = ...) -> Phase:
+    ...
+
+
+@overload
+def neighbor_phase_mean(obj: TNFRGraph, n: NodeId) -> Phase:
+    ...
+
+
+def neighbor_phase_mean(
+    obj: "NodeProtocol" | TNFRGraph, n: NodeId | None = None
+) -> Phase:
+    """Circular mean of neighbour phases for ``obj``.
 
-    The :class:`NodoNX` import is cached after the first call.
+    Parameters
+    ----------
+    obj:
+        Either a :class:`~tnfr.node.NodeProtocol` instance bound to a graph or a
+        :class:`~tnfr.types.TNFRGraph` from which the node ``n`` will be wrapped.
+    n:
+        Optional node identifier. Required when ``obj`` is a graph. Providing a
+        node identifier for a node object raises :class:`TypeError`.
     """
 
-    NodoNX = cached_import("tnfr.node", "NodoNX")
-    if NodoNX is None:
-        raise ImportError("NodoNX is unavailable")
-    node = NodoNX(obj, n) if n is not None else obj
+    NodeNX = cached_import("tnfr.node", "NodeNX")
+    if NodeNX is None:
+        raise ImportError("NodeNX is unavailable")
+    if n is None:
+        if hasattr(obj, "nodes"):
+            raise TypeError(
+                "neighbor_phase_mean requires a node identifier when passing a graph"
+            )
+        node = obj
+    else:
+        if hasattr(obj, "nodes"):
+            node = NodeNX(obj, n)
+        else:
+            raise TypeError(
+                "neighbor_phase_mean received a node and an explicit identifier"
+            )
     return _neighbor_phase_mean_generic(node)

tnfr/metrics/trig.pyi

@@ -0,0 +1,12 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+_neighbor_phase_mean_core: Any
+_neighbor_phase_mean_generic: Any
+_phase_mean_from_iter: Any
+accumulate_cos_sin: Any
+neighbor_phase_mean: Any
+neighbor_phase_mean_list: Any

tnfr/metrics/trig_cache.py

@@ -10,13 +10,9 @@ import math
 from dataclasses import dataclass
 from typing import Any, Iterable, Mapping
 
-from ..alias import get_attr
-from ..constants import get_aliases
-from ..cache import edge_version_cache
-from ..import_utils import get_numpy
+from ..alias import get_theta_attr
 from ..types import GraphLike
-
-ALIAS_THETA = get_aliases("THETA")
+from ..utils import edge_version_cache, get_numpy
 
 __all__ = ("TrigCache", "compute_theta_trig", "get_trig_cache", "_compute_trig_python")
 
@@ -37,7 +33,7 @@ def _iter_theta_pairs(
 
     for n, data in nodes:
         if isinstance(data, Mapping):
-            yield n, get_attr(data, ALIAS_THETA, 0.0)
+            yield n, get_theta_attr(data, 0.0) or 0.0
         else:
             yield n, float(data)
 

tnfr/metrics/trig_cache.pyi

@@ -0,0 +1,10 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+TrigCache: Any
+_compute_trig_python: Any
+compute_theta_trig: Any
+get_trig_cache: Any