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

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,18 +7,23 @@ 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, cast, overload
 
-from ..import_utils import cached_import, get_numpy
-from ..helpers.numeric import kahan_sum_nd
+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
 
 __all__ = (
     "accumulate_cos_sin",
     "_phase_mean_from_iter",
     "_neighbor_phase_mean_core",
     "_neighbor_phase_mean_generic",
+    "neighbor_phase_mean_bulk",
     "neighbor_phase_mean_list",
     "neighbor_phase_mean",
 )
@@ -37,7 +42,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 +87,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,13 +118,13 @@ 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`.
+    """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
@@ -132,11 +137,9 @@ 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"
-            )
+            raise TypeError("neighbor_phase_mean requires nodes bound to a graph")
         from .trig_cache import get_trig_cache
 
         trig = get_trig_cache(node.G)
@@ -145,7 +148,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 +157,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 +171,203 @@ def neighbor_phase_mean_list(
     )
 
 
-def neighbor_phase_mean(obj, n=None) -> float:
-    """Circular mean of neighbour phases.
+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")
 
-    The :class:`NodoNX` import is cached after the first call.
+    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: ...
+
+
+@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``.
+
+    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,13 @@
+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_bulk: Any
+neighbor_phase_mean_list: Any

tnfr/metrics/trig_cache.py

@@ -6,17 +6,15 @@ focused on pure mathematical utilities (phase means, compensated sums, etc.).
 
 from __future__ import annotations
 
+from ..compat.dataclass import dataclass
+import hashlib
 import math
-from dataclasses import dataclass
+import struct
 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 ..types import GraphLike
-
-ALIAS_THETA = get_aliases("THETA")
+from ..alias import get_theta_attr
+from ..types import GraphLike, NodeAttrMap
+from ..utils import edge_version_cache, get_numpy
 
 __all__ = ("TrigCache", "compute_theta_trig", "get_trig_cache", "_compute_trig_python")
 
@@ -28,37 +26,71 @@ 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``."""
 
     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)
 
 
 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."""
@@ -70,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)
@@ -80,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,15 +154,80 @@ def get_trig_cache(
     np: Any | None = None,
     cache_size: int | None = 128,
 ) -> TrigCache:
-    """Return cached cosines and sines of ``θ`` per node."""
+    """Return cached cosines and sines of ``θ`` per node.
+
+    This function maintains a cache of trigonometric values to avoid repeated
+    cos(θ) and sin(θ) computations across Si, coherence, and ΔNFR calculations.
+    The cache uses version-based invalidation triggered by theta attribute changes.
+
+    Cache Strategy
+    --------------
+    - **Key**: ``("_trig", version)`` where version increments on theta changes
+    - **Invalidation**: Checksum-based detection of theta attribute updates
+    - **Capacity**: Controlled by ``cache_size`` parameter (default: 128)
+    - **Scope**: Graph-wide, shared across all metrics computations
+
+    The cache maintains both dict (for sparse access) and array (for vectorized
+    operations) representations of the trigonometric values.
+
+    Parameters
+    ----------
+    G : GraphLike
+        Graph whose node theta attributes are cached.
+    np : Any or None, optional
+        NumPy module for array-based storage. Falls back to dict if None.
+    cache_size : int or None, optional
+        Maximum cache entries. Default: 128. None for unlimited.
+
+    Returns
+    -------
+    TrigCache
+        Container with cos/sin mappings and optional array representations.
+        See TrigCache dataclass for field documentation.
+    """
 
     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 = {}
+
+    # Checksum-based invalidation: detect theta attribute changes
+    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

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

tnfr/multiscale/__init__.py

@@ -0,0 +1,32 @@
+"""Multi-scale hierarchical TNFR network support.
+
+This module implements operational fractality (§3.7) by enabling TNFR networks
+to operate recursively at multiple scales simultaneously, preserving structural
+coherence across scale transitions.
+
+Canonical Invariants Preserved
+------------------------------
+1. EPI operational fractality - nested EPIs maintain functional identity
+2. Cross-scale ΔNFR - coherence propagates between scales
+3. Phase synchrony - maintained within and across scales
+4. Deterministic evolution - reproducible multi-scale dynamics
+
+Examples
+--------
+Create a hierarchical network spanning quantum to organism scales:
+
+>>> from tnfr.multiscale import HierarchicalTNFRNetwork, ScaleDefinition
+>>> scales = [
+...     ScaleDefinition("quantum", node_count=1000, coupling_strength=0.8),
+...     ScaleDefinition("molecular", node_count=500, coupling_strength=0.6),
+...     ScaleDefinition("cellular", node_count=100, coupling_strength=0.4),
+... ]
+>>> network = HierarchicalTNFRNetwork(scales)
+>>> # Network supports simultaneous evolution at all scales
+"""
+
+from __future__ import annotations
+
+from .hierarchical import HierarchicalTNFRNetwork, ScaleDefinition
+
+__all__ = ["HierarchicalTNFRNetwork", "ScaleDefinition"]