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

tnfr/metrics/trig.py

@@ -9,11 +9,11 @@ from __future__ import annotations
 import math
 from collections.abc import Iterable, Iterator, Sequence
 from itertools import tee
-from typing import TYPE_CHECKING, Any, overload, cast
+from typing import TYPE_CHECKING, Any, cast, overload
 
-from ..helpers.numeric import kahan_sum_nd
-from ..utils import cached_import, get_numpy
+from ..utils import kahan_sum_nd
 from ..types import NodeId, Phase, TNFRGraph
+from ..utils import cached_import, get_numpy
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from ..node import NodeProtocol
@@ -23,6 +23,7 @@ __all__ = (
     "_phase_mean_from_iter",
     "_neighbor_phase_mean_core",
     "_neighbor_phase_mean_generic",
+    "neighbor_phase_mean_bulk",
     "neighbor_phase_mean_list",
     "neighbor_phase_mean",
 )
@@ -123,7 +124,7 @@ def _neighbor_phase_mean_generic(
     np: Any | None = None,
     fallback: float = 0.0,
 ) -> float:
-    """Internal helper delegating to :func:`_neighbor_phase_mean_core`.
+    """Compute the neighbour phase mean via :func:`_neighbor_phase_mean_core`.
 
     ``obj`` may be either a node bound to a graph or a sequence of neighbours.
     When ``cos_map`` and ``sin_map`` are ``None`` the function assumes ``obj`` is
@@ -138,9 +139,7 @@ def _neighbor_phase_mean_generic(
     if cos_map is None or sin_map is None:
         node = cast("NodeProtocol", obj)
         if getattr(node, "G", None) is None:
-            raise TypeError(
-                "neighbor_phase_mean requires nodes bound to a graph"
-            )
+            raise TypeError("neighbor_phase_mean requires nodes bound to a graph")
         from .trig_cache import get_trig_cache
 
         trig = get_trig_cache(node.G)
@@ -172,14 +171,171 @@ def neighbor_phase_mean_list(
     )
 
 
+def neighbor_phase_mean_bulk(
+    edge_src: Any,
+    edge_dst: Any,
+    *,
+    cos_values: Any,
+    sin_values: Any,
+    theta_values: Any,
+    node_count: int,
+    np: Any,
+    neighbor_cos_sum: Any | None = None,
+    neighbor_sin_sum: Any | None = None,
+    neighbor_counts: Any | None = None,
+    mean_cos: Any | None = None,
+    mean_sin: Any | None = None,
+) -> tuple[Any, Any]:
+    """Vectorised neighbour phase means for all nodes in a graph.
+
+    Parameters
+    ----------
+    edge_src, edge_dst:
+        Arrays describing the source (neighbour) and destination (node) indices
+        for each edge contribution. They must have matching shapes.
+    cos_values, sin_values:
+        Arrays containing the cosine and sine values of each node's phase. The
+        arrays must be indexed using the same positional indices referenced by
+        ``edge_src``.
+    theta_values:
+        Array with the baseline phase for each node. Positions that do not have
+        neighbours reuse this baseline as their mean phase.
+    node_count:
+        Total number of nodes represented in ``theta_values``.
+    np:
+        Numpy module used to materialise the vectorised operations.
+
+    Optional buffers
+    -----------------
+    neighbor_cos_sum, neighbor_sin_sum, neighbor_counts, mean_cos, mean_sin:
+        Preallocated arrays sized ``node_count`` reused to accumulate the
+        neighbour cosine/sine sums, neighbour sample counts, and the averaged
+        cosine/sine vectors. When omitted, the helper materialises fresh
+        buffers that match the previous semantics.
+
+    Returns
+    -------
+    tuple[Any, Any]
+        Tuple ``(mean_theta, has_neighbors)`` where ``mean_theta`` contains the
+        circular mean of neighbour phases for every node and ``has_neighbors``
+        is a boolean mask identifying which nodes contributed at least one
+        neighbour sample.
+    """
+
+    if node_count <= 0:
+        empty_mean = np.zeros(0, dtype=float)
+        return empty_mean, empty_mean.astype(bool)
+
+    edge_src_arr = np.asarray(edge_src, dtype=np.intp)
+    edge_dst_arr = np.asarray(edge_dst, dtype=np.intp)
+
+    if edge_src_arr.shape != edge_dst_arr.shape:
+        raise ValueError("edge_src and edge_dst must share the same shape")
+
+    theta_arr = np.asarray(theta_values, dtype=float)
+    if theta_arr.ndim != 1 or theta_arr.size != node_count:
+        raise ValueError("theta_values must be a 1-D array matching node_count")
+
+    cos_arr = np.asarray(cos_values, dtype=float)
+    sin_arr = np.asarray(sin_values, dtype=float)
+    if cos_arr.ndim != 1 or cos_arr.size != node_count:
+        raise ValueError("cos_values must be a 1-D array matching node_count")
+    if sin_arr.ndim != 1 or sin_arr.size != node_count:
+        raise ValueError("sin_values must be a 1-D array matching node_count")
+
+    edge_count = edge_dst_arr.size
+    def _coerce_buffer(buffer: Any | None, *, name: str) -> tuple[Any, bool]:
+        if buffer is None:
+            return None, False
+        arr = np.array(buffer, dtype=float, copy=False)
+        if arr.ndim != 1 or arr.size != node_count:
+            raise ValueError(f"{name} must be a 1-D array sized node_count")
+        arr.fill(0.0)
+        return arr, True
+
+    neighbor_cos_sum, has_cos_buffer = _coerce_buffer(
+        neighbor_cos_sum, name="neighbor_cos_sum"
+    )
+    neighbor_sin_sum, has_sin_buffer = _coerce_buffer(
+        neighbor_sin_sum, name="neighbor_sin_sum"
+    )
+    neighbor_counts, has_count_buffer = _coerce_buffer(
+        neighbor_counts, name="neighbor_counts"
+    )
+
+    if edge_count:
+        cos_bincount = np.bincount(
+            edge_dst_arr,
+            weights=cos_arr[edge_src_arr],
+            minlength=node_count,
+        )
+        sin_bincount = np.bincount(
+            edge_dst_arr,
+            weights=sin_arr[edge_src_arr],
+            minlength=node_count,
+        )
+        count_bincount = np.bincount(
+            edge_dst_arr,
+            minlength=node_count,
+        ).astype(float, copy=False)
+
+        if not has_cos_buffer:
+            neighbor_cos_sum = cos_bincount
+        else:
+            np.copyto(neighbor_cos_sum, cos_bincount)
+
+        if not has_sin_buffer:
+            neighbor_sin_sum = sin_bincount
+        else:
+            np.copyto(neighbor_sin_sum, sin_bincount)
+
+        if not has_count_buffer:
+            neighbor_counts = count_bincount
+        else:
+            np.copyto(neighbor_counts, count_bincount)
+    else:
+        if neighbor_cos_sum is None:
+            neighbor_cos_sum = np.zeros(node_count, dtype=float)
+        if neighbor_sin_sum is None:
+            neighbor_sin_sum = np.zeros(node_count, dtype=float)
+        if neighbor_counts is None:
+            neighbor_counts = np.zeros(node_count, dtype=float)
+
+    has_neighbors = neighbor_counts > 0.0
+
+    mean_cos, _ = _coerce_buffer(mean_cos, name="mean_cos")
+    mean_sin, _ = _coerce_buffer(mean_sin, name="mean_sin")
+
+    if mean_cos is None:
+        mean_cos = np.zeros(node_count, dtype=float)
+    if mean_sin is None:
+        mean_sin = np.zeros(node_count, dtype=float)
+
+    if edge_count:
+        with np.errstate(divide="ignore", invalid="ignore"):
+            np.divide(
+                neighbor_cos_sum,
+                neighbor_counts,
+                out=mean_cos,
+                where=has_neighbors,
+            )
+            np.divide(
+                neighbor_sin_sum,
+                neighbor_counts,
+                out=mean_sin,
+                where=has_neighbors,
+            )
+
+    mean_theta = np.where(has_neighbors, np.arctan2(mean_sin, mean_cos), theta_arr)
+    return mean_theta, has_neighbors
+
+
 @overload
-def neighbor_phase_mean(obj: "NodeProtocol", n: None = ...) -> Phase:
-    ...
+def neighbor_phase_mean(obj: "NodeProtocol", n: None = ...) -> Phase: ...
 
 
 @overload
-def neighbor_phase_mean(obj: TNFRGraph, n: NodeId) -> Phase:
-    ...
+def neighbor_phase_mean(obj: TNFRGraph, n: NodeId) -> Phase: ...
 
 
 def neighbor_phase_mean(

tnfr/metrics/trig.pyi

@@ -9,4 +9,5 @@ _neighbor_phase_mean_generic: Any
 _phase_mean_from_iter: Any
 accumulate_cos_sin: Any
 neighbor_phase_mean: Any
+neighbor_phase_mean_bulk: Any
 neighbor_phase_mean_list: Any

tnfr/metrics/trig_cache.py

@@ -6,12 +6,14 @@ focused on pure mathematical utilities (phase means, compensated sums, etc.).
 
 from __future__ import annotations
 
+import hashlib
 import math
+import struct
 from dataclasses import dataclass
 from typing import Any, Iterable, Mapping
 
 from ..alias import get_theta_attr
-from ..types import GraphLike
+from ..types import GraphLike, NodeAttrMap
 from ..utils import edge_version_cache, get_numpy
 
 __all__ = ("TrigCache", "compute_theta_trig", "get_trig_cache", "_compute_trig_python")
@@ -24,10 +26,18 @@ class TrigCache:
     cos: dict[Any, float]
     sin: dict[Any, float]
     theta: dict[Any, float]
+    theta_checksums: dict[Any, bytes]
+    order: tuple[Any, ...]
+    cos_values: Any
+    sin_values: Any
+    theta_values: Any
+    index: dict[Any, int]
+    edge_src: Any | None = None
+    edge_dst: Any | None = None
 
 
 def _iter_theta_pairs(
-    nodes: Iterable[tuple[Any, Mapping[str, Any] | float]],
+    nodes: Iterable[tuple[Any, NodeAttrMap | float]],
 ) -> Iterable[tuple[Any, float]]:
     """Yield ``(node, θ)`` pairs from ``nodes``."""
 
@@ -39,22 +49,48 @@ def _iter_theta_pairs(
 
 
 def _compute_trig_python(
-    nodes: Iterable[tuple[Any, Mapping[str, Any] | float]],
+    nodes: Iterable[tuple[Any, NodeAttrMap | float]],
 ) -> TrigCache:
     """Compute trigonometric mappings using pure Python."""
 
+    pairs = list(_iter_theta_pairs(nodes))
+
     cos_th: dict[Any, float] = {}
     sin_th: dict[Any, float] = {}
     thetas: dict[Any, float] = {}
-    for n, th in _iter_theta_pairs(nodes):
+    theta_checksums: dict[Any, bytes] = {}
+    order_list: list[Any] = []
+
+    for n, th in pairs:
+        order_list.append(n)
         thetas[n] = th
         cos_th[n] = math.cos(th)
         sin_th[n] = math.sin(th)
-    return TrigCache(cos=cos_th, sin=sin_th, theta=thetas)
+        theta_checksums[n] = _theta_checksum(th)
+
+    order = tuple(order_list)
+    cos_values = tuple(cos_th[n] for n in order)
+    sin_values = tuple(sin_th[n] for n in order)
+    theta_values = tuple(thetas[n] for n in order)
+    index = {n: i for i, n in enumerate(order)}
+
+    return TrigCache(
+        cos=cos_th,
+        sin=sin_th,
+        theta=thetas,
+        theta_checksums=theta_checksums,
+        order=order,
+        cos_values=cos_values,
+        sin_values=sin_values,
+        theta_values=theta_values,
+        index=index,
+        edge_src=None,
+        edge_dst=None,
+    )
 
 
 def compute_theta_trig(
-    nodes: Iterable[tuple[Any, Mapping[str, Any] | float]],
+    nodes: Iterable[tuple[Any, NodeAttrMap | float]],
     np: Any | None = None,
 ) -> TrigCache:
     """Return trigonometric mappings of ``θ`` per node."""
@@ -66,9 +102,22 @@ def compute_theta_trig(
 
     pairs = list(_iter_theta_pairs(nodes))
     if not pairs:
-        return TrigCache(cos={}, sin={}, theta={})
+        return TrigCache(
+            cos={},
+            sin={},
+            theta={},
+            theta_checksums={},
+            order=(),
+            cos_values=(),
+            sin_values=(),
+            theta_values=(),
+            index={},
+            edge_src=None,
+            edge_dst=None,
+        )
 
     node_list, theta_vals = zip(*pairs)
+    node_list = tuple(node_list)
     theta_arr = np.fromiter(theta_vals, dtype=float)
     cos_arr = np.cos(theta_arr)
     sin_arr = np.sin(theta_arr)
@@ -76,7 +125,21 @@ def compute_theta_trig(
     cos_th = dict(zip(node_list, map(float, cos_arr)))
     sin_th = dict(zip(node_list, map(float, sin_arr)))
     thetas = dict(zip(node_list, map(float, theta_arr)))
-    return TrigCache(cos=cos_th, sin=sin_th, theta=thetas)
+    theta_checksums = {node: _theta_checksum(float(theta)) for node, theta in pairs}
+    index = {n: i for i, n in enumerate(node_list)}
+    return TrigCache(
+        cos=cos_th,
+        sin=sin_th,
+        theta=thetas,
+        theta_checksums=theta_checksums,
+        order=node_list,
+        cos_values=cos_arr,
+        sin_values=sin_arr,
+        theta_values=theta_arr,
+        index=index,
+        edge_src=None,
+        edge_dst=None,
+    )
 
 
 def _build_trig_cache(G: GraphLike, np: Any | None = None) -> TrigCache:
@@ -95,11 +158,45 @@ def get_trig_cache(
 
     if np is None:
         np = get_numpy()
-    version = G.graph.setdefault("_trig_version", 0)
+    graph = G.graph
+    version = graph.setdefault("_trig_version", 0)
     key = ("_trig", version)
-    return edge_version_cache(
-        G,
-        key,
-        lambda: _build_trig_cache(G, np=np),
-        max_entries=cache_size,
-    )
+
+    def builder() -> TrigCache:
+        return _build_trig_cache(G, np=np)
+
+    trig = edge_version_cache(G, key, builder, max_entries=cache_size)
+    current_checksums = _graph_theta_checksums(G)
+    trig_checksums = getattr(trig, "theta_checksums", None)
+    if trig_checksums is None:
+        trig_checksums = {}
+
+    if trig_checksums != current_checksums:
+        version = version + 1
+        graph["_trig_version"] = version
+        key = ("_trig", version)
+        trig = edge_version_cache(G, key, builder, max_entries=cache_size)
+        trig_checksums = getattr(trig, "theta_checksums", None)
+        if trig_checksums is None:
+            trig_checksums = {}
+        if trig_checksums != current_checksums:
+            current_checksums = _graph_theta_checksums(G)
+            if trig_checksums != current_checksums:
+                return trig
+    return trig
+
+
+def _theta_checksum(theta: float) -> bytes:
+    """Return a deterministic checksum for ``theta``."""
+
+    packed = struct.pack("!d", float(theta))
+    return hashlib.blake2b(packed, digest_size=8).digest()
+
+
+def _graph_theta_checksums(G: GraphLike) -> dict[Any, bytes]:
+    """Return checksum snapshot of the graph's current ``θ`` values."""
+
+    checksums: dict[Any, bytes] = {}
+    for node, theta in _iter_theta_pairs(G.nodes(data=True)):
+        checksums[node] = _theta_checksum(theta)
+    return checksums