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

tnfr/dynamics/dnfr.py

@@ -12,21 +12,19 @@ from __future__ import annotations
 
 import math
 import sys
+from collections.abc import Callable, Iterator, Mapping, MutableMapping, Sequence
 from concurrent.futures import ProcessPoolExecutor
-from dataclasses import dataclass
 from types import ModuleType
-from collections.abc import Callable, Iterator, Mapping, MutableMapping, Sequence
 from typing import TYPE_CHECKING, Any, cast
 
+from time import perf_counter
+
 from ..alias import get_attr, get_theta_attr, set_dnfr
-from ..constants import DEFAULTS, get_aliases, get_param
-from ..helpers.numeric import angle_diff
-from ..cache import CacheManager
+from ..constants import DEFAULTS, get_param
+from ..constants.aliases import ALIAS_EPI, ALIAS_VF
 from ..metrics.common import merge_and_normalize_weights
 from ..metrics.trig import neighbor_phase_mean_list
 from ..metrics.trig_cache import compute_theta_trig
-from ..utils import cached_node_list, cached_nodes_and_A, get_numpy, normalize_weights
-from ..utils.cache import DNFR_PREP_STATE_KEY, DnfrPrepState, _graph_cache_manager
 from ..types import (
     DeltaNFRHook,
     DnfrCacheVectors,
@@ -35,15 +33,28 @@ from ..types import (
     NodeId,
     TNFRGraph,
 )
+from ..utils import (
+    DNFR_PREP_STATE_KEY,
+    DnfrPrepState,
+    DnfrCache,
+    CacheManager,
+    _graph_cache_manager,
+    angle_diff,
+    angle_diff_array,
+    cached_node_list,
+    cached_nodes_and_A,
+    get_numpy,
+    normalize_weights,
+    resolve_chunk_size,
+    new_dnfr_cache,
+)
 
 if TYPE_CHECKING:  # pragma: no cover - import-time typing hook
     import numpy as np
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_VF = get_aliases("VF")
-
 
 _MEAN_VECTOR_EPS = 1e-12
 _SPARSE_DENSITY_THRESHOLD = 0.25
+_DNFR_APPROX_BYTES_PER_EDGE = 48
 
 
 def _should_vectorize(G: TNFRGraph, np_module: ModuleType | None) -> bool:
@@ -57,64 +68,6 @@ def _should_vectorize(G: TNFRGraph, np_module: ModuleType | None) -> bool:
     return bool(flag)
 
 
-@dataclass
-class DnfrCache:
-    idx: dict[Any, int]
-    theta: list[float]
-    epi: list[float]
-    vf: list[float]
-    cos_theta: list[float]
-    sin_theta: list[float]
-    neighbor_x: list[float]
-    neighbor_y: list[float]
-    neighbor_epi_sum: list[float]
-    neighbor_vf_sum: list[float]
-    neighbor_count: list[float]
-    neighbor_deg_sum: list[float] | None
-    th_bar: list[float] | None = None
-    epi_bar: list[float] | None = None
-    vf_bar: list[float] | None = None
-    deg_bar: list[float] | None = None
-    degs: dict[Any, float] | None = None
-    deg_list: list[float] | None = None
-    theta_np: Any | None = None
-    epi_np: Any | None = None
-    vf_np: Any | None = None
-    cos_theta_np: Any | None = None
-    sin_theta_np: Any | None = None
-    deg_array: Any | None = None
-    edge_src: Any | None = None
-    edge_dst: Any | None = None
-    checksum: Any | None = None
-    neighbor_x_np: Any | None = None
-    neighbor_y_np: Any | None = None
-    neighbor_epi_sum_np: Any | None = None
-    neighbor_vf_sum_np: Any | None = None
-    neighbor_count_np: Any | None = None
-    neighbor_deg_sum_np: Any | None = None
-    th_bar_np: Any | None = None
-    epi_bar_np: Any | None = None
-    vf_bar_np: Any | None = None
-    deg_bar_np: Any | None = None
-    grad_phase_np: Any | None = None
-    grad_epi_np: Any | None = None
-    grad_vf_np: Any | None = None
-    grad_topo_np: Any | None = None
-    grad_total_np: Any | None = None
-    dense_components_np: Any | None = None
-    dense_accum_np: Any | None = None
-    dense_degree_np: Any | None = None
-    neighbor_accum_np: Any | None = None
-    neighbor_inv_count_np: Any | None = None
-    neighbor_cos_avg_np: Any | None = None
-    neighbor_sin_avg_np: Any | None = None
-    neighbor_mean_tmp_np: Any | None = None
-    neighbor_mean_length_np: Any | None = None
-    edge_signature: Any | None = None
-    neighbor_accum_signature: Any | None = None
-    neighbor_edge_values_np: Any | None = None
-
-
 _NUMPY_CACHE_ATTRS = (
     "theta_np",
     "epi_np",
@@ -141,6 +94,34 @@ _NUMPY_CACHE_ATTRS = (
 )
 
 
+def _profile_start_stop(
+    profile: MutableMapping[str, float] | None,
+    *,
+    keys: Sequence[str] = (),
+) -> tuple[Callable[[], float], Callable[[str, float], None]]:
+    """Return helpers to measure wall-clock durations for ``profile`` keys."""
+
+    if profile is not None:
+        for key in keys:
+            profile.setdefault(key, 0.0)
+
+        def _start() -> float:
+            return perf_counter()
+
+        def _stop(metric: str, start: float) -> None:
+            profile[metric] = float(profile.get(metric, 0.0)) + (perf_counter() - start)
+
+    else:
+
+        def _start() -> float:
+            return 0.0
+
+        def _stop(metric: str, start: float) -> None:  # noqa: ARG001 - uniform signature
+            return None
+
+    return _start, _stop
+
+
 def _iter_chunk_offsets(total: int, jobs: int) -> Iterator[tuple[int, int]]:
     """Yield ``(start, end)`` offsets splitting ``total`` items across ``jobs``."""
 
@@ -175,7 +156,15 @@ def _neighbor_sums_worker(
     deg_base: Sequence[float] | None,
     deg_list: Sequence[float] | None,
     degs_list: Sequence[float] | None,
-) -> tuple[int, list[float], list[float], list[float], list[float], list[float], list[float] | None]:
+) -> tuple[
+    int,
+    list[float],
+    list[float],
+    list[float],
+    list[float],
+    list[float],
+    list[float] | None,
+]:
     """Return partial neighbour sums for the ``[start, end)`` range."""
 
     chunk_x: list[float] = []
@@ -281,7 +270,10 @@ def _resolve_parallel_jobs(n_jobs: int | None, total: int) -> int | None:
 
 
 def _is_numpy_like(obj) -> bool:
-    return getattr(obj, "dtype", None) is not None and getattr(obj, "shape", None) is not None
+    return (
+        getattr(obj, "dtype", None) is not None
+        and getattr(obj, "shape", None) is not None
+    )
 
 
 def _has_cached_numpy_buffers(data: dict, cache: DnfrCache | None) -> bool:
@@ -416,43 +408,28 @@ def _init_dnfr_cache(
         idx_local = {n: i for i, n in enumerate(nodes)}
         size = len(nodes)
         zeros = [0.0] * size
-        if prev_cache is None:
-            cache_new = DnfrCache(
-                idx=idx_local,
-                theta=zeros.copy(),
-                epi=zeros.copy(),
-                vf=zeros.copy(),
-                cos_theta=[1.0] * size,
-                sin_theta=[0.0] * size,
-                neighbor_x=zeros.copy(),
-                neighbor_y=zeros.copy(),
-                neighbor_epi_sum=zeros.copy(),
-                neighbor_vf_sum=zeros.copy(),
-                neighbor_count=zeros.copy(),
-                neighbor_deg_sum=zeros.copy() if size else [],
-                degs=None,
-                edge_src=None,
-                edge_dst=None,
-                checksum=checksum,
-            )
-        else:
-            cache_new = prev_cache
-            cache_new.idx = idx_local
-            cache_new.theta = zeros.copy()
-            cache_new.epi = zeros.copy()
-            cache_new.vf = zeros.copy()
-            cache_new.cos_theta = [1.0] * size
-            cache_new.sin_theta = [0.0] * size
-            cache_new.neighbor_x = zeros.copy()
-            cache_new.neighbor_y = zeros.copy()
-            cache_new.neighbor_epi_sum = zeros.copy()
-            cache_new.neighbor_vf_sum = zeros.copy()
-            cache_new.neighbor_count = zeros.copy()
-            cache_new.neighbor_deg_sum = zeros.copy() if size else []
-
-            # Reset any numpy mirrors or aggregated buffers to avoid leaking
-            # state across refresh cycles (e.g. switching between vectorised
-            # and Python paths or reusing legacy caches).
+        cache_new = prev_cache if prev_cache is not None else new_dnfr_cache()
+        cache_new.idx = idx_local
+        cache_new.theta = zeros.copy()
+        cache_new.epi = zeros.copy()
+        cache_new.vf = zeros.copy()
+        cache_new.cos_theta = [1.0] * size
+        cache_new.sin_theta = [0.0] * size
+        cache_new.neighbor_x = zeros.copy()
+        cache_new.neighbor_y = zeros.copy()
+        cache_new.neighbor_epi_sum = zeros.copy()
+        cache_new.neighbor_vf_sum = zeros.copy()
+        cache_new.neighbor_count = zeros.copy()
+        cache_new.neighbor_deg_sum = zeros.copy() if size else []
+        cache_new.degs = None
+        cache_new.edge_src = None
+        cache_new.edge_dst = None
+        cache_new.checksum = checksum
+
+        # Reset any numpy mirrors or aggregated buffers to avoid leaking
+        # state across refresh cycles (e.g. switching between vectorised
+        # and Python paths or reusing legacy caches).
+        if prev_cache is not None:
             for attr in _NUMPY_CACHE_ATTRS:
                 setattr(cache_new, attr, None)
             for attr in (
@@ -501,7 +478,8 @@ def _ensure_numpy_vectors(cache: DnfrCache, np: ModuleType) -> DnfrCacheVectors:
     if cache is None:
         return (None, None, None, None, None)
 
-    arrays = []
+    arrays: list[Any | None] = []
+    size = len(cache.theta)
     for attr_np, source_attr in (
         ("theta_np", "theta"),
         ("epi_np", "epi"),
@@ -509,16 +487,18 @@ def _ensure_numpy_vectors(cache: DnfrCache, np: ModuleType) -> DnfrCacheVectors:
         ("cos_theta_np", "cos_theta"),
         ("sin_theta_np", "sin_theta"),
     ):
-        src = getattr(cache, source_attr)
         arr = getattr(cache, attr_np)
+        if arr is not None and getattr(arr, "shape", None) == (size,):
+            arrays.append(arr)
+            continue
+        src = getattr(cache, source_attr)
         if src is None:
             setattr(cache, attr_np, None)
             arrays.append(None)
             continue
-        if arr is None or len(arr) != len(src):
+        arr = np.asarray(src, dtype=float)
+        if getattr(arr, "shape", None) != (size,):
             arr = np.array(src, dtype=float)
-        else:
-            np.copyto(arr, src, casting="unsafe")
         setattr(cache, attr_np, arr)
         arrays.append(arr)
     return tuple(arrays)
@@ -588,52 +568,50 @@ def _ensure_cached_array(
     return arr
 
 
-def _ensure_numpy_state_vectors(data: MutableMapping[str, Any], np: ModuleType) -> DnfrVectorMap:
+def _ensure_numpy_state_vectors(
+    data: MutableMapping[str, Any], np: ModuleType
+) -> DnfrVectorMap:
     """Synchronise list-based state vectors with their NumPy counterparts."""
 
     nodes = data.get("nodes") or ()
     size = len(nodes)
     cache: DnfrCache | None = data.get("cache")
 
+    cache_arrays: DnfrCacheVectors = (None, None, None, None, None)
     if cache is not None:
-        theta_np, epi_np, vf_np, cos_np, sin_np = _ensure_numpy_vectors(cache, np)
-        for key, arr in (
-            ("theta_np", theta_np),
-            ("epi_np", epi_np),
-            ("vf_np", vf_np),
-            ("cos_theta_np", cos_np),
-            ("sin_theta_np", sin_np),
-        ):
-            if arr is not None and getattr(arr, "shape", None) == (size,):
-                data[key] = arr
-
-    mapping = (
-        ("theta_np", "theta"),
-        ("epi_np", "epi"),
-        ("vf_np", "vf"),
-        ("cos_theta_np", "cos_theta"),
-        ("sin_theta_np", "sin_theta"),
-    )
-    for np_key, src_key in mapping:
-        src = data.get(src_key)
-        if src is None:
-            continue
+        cache_arrays = _ensure_numpy_vectors(cache, np)
+
+    result: dict[str, Any | None] = {}
+    for (plain_key, np_key, cached_arr, result_key) in (
+        ("theta", "theta_np", cache_arrays[0], "theta"),
+        ("epi", "epi_np", cache_arrays[1], "epi"),
+        ("vf", "vf_np", cache_arrays[2], "vf"),
+        ("cos_theta", "cos_theta_np", cache_arrays[3], "cos"),
+        ("sin_theta", "sin_theta_np", cache_arrays[4], "sin"),
+    ):
         arr = data.get(np_key)
+        if arr is None:
+            arr = cached_arr
         if arr is None or getattr(arr, "shape", None) != (size,):
-            arr = np.array(src, dtype=float)
-        elif cache is None:
-            np.copyto(arr, src, casting="unsafe")
-        data[np_key] = arr
-        if cache is not None:
-            setattr(cache, np_key, arr)
+            src = data.get(plain_key)
+            if src is None and cache is not None:
+                src = getattr(cache, plain_key)
+            if src is None:
+                arr = None
+            else:
+                arr = np.asarray(src, dtype=float)
+                if getattr(arr, "shape", None) != (size,):
+                    arr = np.array(src, dtype=float)
+        if arr is not None:
+            data[np_key] = arr
+            data[plain_key] = arr
+            if cache is not None:
+                setattr(cache, np_key, arr)
+        else:
+            data[np_key] = None
+        result[result_key] = arr
 
-    return {
-        "theta": data.get("theta_np"),
-        "epi": data.get("epi_np"),
-        "vf": data.get("vf_np"),
-        "cos": data.get("cos_theta_np"),
-        "sin": data.get("sin_theta_np"),
-    }
+    return result
 
 
 def _build_edge_index_arrays(
@@ -679,26 +657,94 @@ def _refresh_dnfr_vectors(
     np_module = get_numpy()
     trig = compute_theta_trig(((n, G.nodes[n]) for n in nodes), np=np_module)
     use_numpy = _should_vectorize(G, np_module)
-    for index, node in enumerate(nodes):
-        i: int = int(index)
-        node_id: NodeId = node
-        nd = G.nodes[node_id]
-        cache.theta[i] = trig.theta[node_id]
-        cache.epi[i] = get_attr(nd, ALIAS_EPI, 0.0)
-        cache.vf[i] = get_attr(nd, ALIAS_VF, 0.0)
-        cache.cos_theta[i] = trig.cos[node_id]
-        cache.sin_theta[i] = trig.sin[node_id]
-    if use_numpy:
-        _ensure_numpy_vectors(cache, np_module)
+    node_count = len(nodes)
+    trig_theta = getattr(trig, "theta_values", None)
+    trig_cos = getattr(trig, "cos_values", None)
+    trig_sin = getattr(trig, "sin_values", None)
+    np_ready = (
+        use_numpy
+        and np_module is not None
+        and isinstance(trig_theta, getattr(np_module, "ndarray", tuple()))
+        and isinstance(trig_cos, getattr(np_module, "ndarray", tuple()))
+        and isinstance(trig_sin, getattr(np_module, "ndarray", tuple()))
+        and getattr(trig_theta, "shape", None) == getattr(trig_cos, "shape", None)
+        and getattr(trig_theta, "shape", None) == getattr(trig_sin, "shape", None)
+        and (trig_theta.shape[0] if getattr(trig_theta, "ndim", 0) else 0) == node_count
+    )
+
+    if np_ready:
+        if node_count:
+            epi_arr = np_module.fromiter(
+                (get_attr(G.nodes[node], ALIAS_EPI, 0.0) for node in nodes),
+                dtype=float,
+                count=node_count,
+            )
+            vf_arr = np_module.fromiter(
+                (get_attr(G.nodes[node], ALIAS_VF, 0.0) for node in nodes),
+                dtype=float,
+                count=node_count,
+            )
+        else:
+            epi_arr = np_module.empty(0, dtype=float)
+            vf_arr = np_module.empty(0, dtype=float)
+
+        theta_arr = np_module.asarray(trig_theta, dtype=float)
+        cos_arr = np_module.asarray(trig_cos, dtype=float)
+        sin_arr = np_module.asarray(trig_sin, dtype=float)
+
+        def _sync_numpy(attr: str, source: Any) -> Any:
+            dest = getattr(cache, attr)
+            if dest is None or getattr(dest, "shape", None) != source.shape:
+                dest = np_module.array(source, dtype=float)
+            else:
+                np_module.copyto(dest, source, casting="unsafe")
+            setattr(cache, attr, dest)
+            return dest
+
+        _sync_numpy("theta_np", theta_arr)
+        _sync_numpy("epi_np", epi_arr)
+        _sync_numpy("vf_np", vf_arr)
+        _sync_numpy("cos_theta_np", cos_arr)
+        _sync_numpy("sin_theta_np", sin_arr)
+
+        # Python mirrors remain untouched while the vectorised path is active.
+        # They will be rebuilt the next time the runtime falls back to lists.
+        if cache.theta is not None and len(cache.theta) != node_count:
+            cache.theta = [0.0] * node_count
+        if cache.epi is not None and len(cache.epi) != node_count:
+            cache.epi = [0.0] * node_count
+        if cache.vf is not None and len(cache.vf) != node_count:
+            cache.vf = [0.0] * node_count
+        if cache.cos_theta is not None and len(cache.cos_theta) != node_count:
+            cache.cos_theta = [1.0] * node_count
+        if cache.sin_theta is not None and len(cache.sin_theta) != node_count:
+            cache.sin_theta = [0.0] * node_count
     else:
-        cache.theta_np = None
-        cache.epi_np = None
-        cache.vf_np = None
-        cache.cos_theta_np = None
-        cache.sin_theta_np = None
+        for index, node in enumerate(nodes):
+            i: int = int(index)
+            node_id: NodeId = node
+            nd = G.nodes[node_id]
+            cache.theta[i] = trig.theta[node_id]
+            cache.epi[i] = get_attr(nd, ALIAS_EPI, 0.0)
+            cache.vf[i] = get_attr(nd, ALIAS_VF, 0.0)
+            cache.cos_theta[i] = trig.cos[node_id]
+            cache.sin_theta[i] = trig.sin[node_id]
+        if use_numpy and np_module is not None:
+            _ensure_numpy_vectors(cache, np_module)
+        else:
+            cache.theta_np = None
+            cache.epi_np = None
+            cache.vf_np = None
+            cache.cos_theta_np = None
+            cache.sin_theta_np = None
 
 
-def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[str, Any]:
+def _prepare_dnfr_data(
+    G: TNFRGraph,
+    *,
+    cache_size: int | None = 128,
+    profile: MutableMapping[str, float] | None = None,
+) -> dict[str, Any]:
     """Precompute common data for ΔNFR strategies.
 
     The helper decides between edge-wise and dense adjacency accumulation
@@ -706,7 +752,20 @@ def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[st
     ``_SPARSE_DENSITY_THRESHOLD`` receive a cached adjacency matrix so the
     dense path can be exercised; callers may also force the dense mode by
     setting ``G.graph['dnfr_force_dense']`` to a truthy value.
+
+    Parameters
+    ----------
+    profile : MutableMapping[str, float] or None, optional
+        Mutable mapping that accumulates wall-clock timings for ΔNFR
+        preparation. When provided the helper increases the
+        ``"dnfr_cache_rebuild"`` bucket with the time spent refreshing cached
+        node vectors and associated NumPy workspaces.
     """
+    start_timer, stop_timer = _profile_start_stop(
+        profile,
+        keys=("dnfr_cache_rebuild",),
+    )
+
     graph = G.graph
     weights = graph.get("_dnfr_weights")
     if weights is None:
@@ -743,6 +802,7 @@ def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[st
     checksum = G.graph.get("_dnfr_nodes_checksum")
     dirty_flag = bool(G.graph.pop("_dnfr_prep_dirty", False))
     existing_cache = cast(DnfrCache | None, graph.get("_dnfr_prep_cache"))
+    cache_timer = start_timer()
     cache, idx, theta, epi, vf, cos_theta, sin_theta, refreshed = _init_dnfr_cache(
         G,
         nodes,
@@ -751,7 +811,9 @@ def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[st
         force_refresh=dirty_flag,
         manager=manager,
     )
+    stop_timer("dnfr_cache_rebuild", cache_timer)
     dirty = dirty_flag or refreshed
+    caching_enabled = cache is not None and (cache_size is None or cache_size > 0)
     result["cache"] = cache
     result["idx"] = idx
     result["theta"] = theta
@@ -761,7 +823,7 @@ def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[st
     result["sin_theta"] = sin_theta
     if cache is not None:
         _refresh_dnfr_vectors(G, nodes, cache)
-        if np_module is None:
+        if np_module is None and not caching_enabled:
             for attr in (
                 "neighbor_x_np",
                 "neighbor_y_np",
@@ -812,41 +874,47 @@ def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[st
         cache.neighbor_accum_np = None
         cache.neighbor_edge_values_np = None
         degree_map = None
-    if degree_map is None or len(degree_map) != len(G):
-        degree_map = {cast(NodeId, node): float(deg) for node, deg in G.degree()}
-        if cache is not None:
-            cache.degs = degree_map
-
-    G.graph["_dnfr_prep_dirty"] = False
 
-    if (
-        cache is not None
-        and cache.deg_list is not None
-        and not dirty
-        and len(cache.deg_list) == len(nodes)
-    ):
-        deg_list = cache.deg_list
-    else:
-        deg_list = [float(degree_map.get(node, 0.0)) for node in nodes]
-        if cache is not None:
-            cache.deg_list = deg_list
+    deg_list: list[float] | None = None
+    degs: dict[NodeId, float] | None = None
+    deg_array: np.ndarray | None = None
 
-    if w_topo != 0.0:
-        degs: dict[NodeId, float] | None = degree_map
-    else:
-        degs = None
-    result["degs"] = degs
-    result["deg_list"] = deg_list
+    if w_topo != 0.0 or caching_enabled:
+        if degree_map is None or len(degree_map) != len(G):
+            degree_map = {cast(NodeId, node): float(deg) for node, deg in G.degree()}
+            if cache is not None:
+                cache.degs = degree_map
 
-    deg_array: np.ndarray | None = None
-    if np_module is not None and deg_list is not None:
-        if cache is not None:
-            deg_array = _ensure_numpy_degrees(cache, deg_list, np_module)
+        if (
+            cache is not None
+            and cache.deg_list is not None
+            and not dirty
+            and len(cache.deg_list) == len(nodes)
+        ):
+            deg_list = cache.deg_list
         else:
-            deg_array = np_module.array(deg_list, dtype=float)
-    elif cache is not None:
+            deg_list = [float(degree_map.get(node, 0.0)) for node in nodes]
+            if cache is not None:
+                cache.deg_list = deg_list
+
+        degs = degree_map
+
+        if np_module is not None and deg_list is not None:
+            if cache is not None:
+                deg_array = _ensure_numpy_degrees(cache, deg_list, np_module)
+            else:
+                deg_array = np_module.array(deg_list, dtype=float)
+        elif cache is not None:
+            cache.deg_array = None
+    elif cache is not None and dirty:
+        cache.deg_list = None
         cache.deg_array = None
 
+    G.graph["_dnfr_prep_dirty"] = False
+
+    result["degs"] = degs
+    result["deg_list"] = deg_list
+
     theta_np: np.ndarray | None
     epi_np: np.ndarray | None
     vf_np: np.ndarray | None
@@ -864,9 +932,7 @@ def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[st
             edge_src = cache.edge_src
             edge_dst = cache.edge_dst
             if edge_src is None or edge_dst is None or dirty:
-                edge_src, edge_dst = _build_edge_index_arrays(
-                    G, nodes, idx, np_module
-                )
+                edge_src, edge_dst = _build_edge_index_arrays(G, nodes, idx, np_module)
                 cache.edge_src = edge_src
                 cache.edge_dst = edge_dst
         else:
@@ -903,6 +969,16 @@ def _prepare_dnfr_data(G: TNFRGraph, *, cache_size: int | None = 128) -> dict[st
     result["vf_np"] = vf_np
     result["cos_theta_np"] = cos_theta_np
     result["sin_theta_np"] = sin_theta_np
+    if theta_np is not None and getattr(theta_np, "shape", None) == (len(nodes),):
+        result["theta"] = theta_np
+    if epi_np is not None and getattr(epi_np, "shape", None) == (len(nodes),):
+        result["epi"] = epi_np
+    if vf_np is not None and getattr(vf_np, "shape", None) == (len(nodes),):
+        result["vf"] = vf_np
+    if cos_theta_np is not None and getattr(cos_theta_np, "shape", None) == (len(nodes),):
+        result["cos_theta"] = cos_theta_np
+    if sin_theta_np is not None and getattr(sin_theta_np, "shape", None) == (len(nodes),):
+        result["sin_theta"] = sin_theta_np
     result["deg_array"] = deg_array
     result["edge_src"] = edge_src
     result["edge_dst"] = edge_dst
@@ -925,8 +1001,22 @@ def _apply_dnfr_gradients(
     degs: Mapping[Any, float] | Sequence[float] | np.ndarray | None = None,
     *,
     n_jobs: int | None = None,
+    profile: MutableMapping[str, float] | None = None,
 ) -> None:
-    """Combine precomputed gradients and write ΔNFR to each node."""
+    """Combine precomputed gradients and write ΔNFR to each node.
+
+    Parameters
+    ----------
+    profile : MutableMapping[str, float] or None, optional
+        Mutable mapping receiving aggregated timings for the gradient assembly
+        (``"dnfr_gradient_assembly"``) and in-place writes
+        (``"dnfr_inplace_write"``).
+    """
+    start_timer, stop_timer = _profile_start_stop(
+        profile,
+        keys=("dnfr_gradient_assembly", "dnfr_inplace_write"),
+    )
+
     np = get_numpy()
     nodes = data["nodes"]
     theta = data["theta"]
@@ -962,6 +1052,8 @@ def _apply_dnfr_gradients(
             and isinstance(deg_array, np.ndarray)
         )
 
+    grad_timer = start_timer()
+
     if use_vector:
         grad_phase = _ensure_cached_array(cache, "grad_phase_np", theta_np.shape, np)
         grad_epi = _ensure_cached_array(cache, "grad_epi_np", epi_np.shape, np)
@@ -969,16 +1061,10 @@ def _apply_dnfr_gradients(
         grad_total = _ensure_cached_array(cache, "grad_total_np", theta_np.shape, np)
         grad_topo = None
         if w_topo != 0.0:
-            grad_topo = _ensure_cached_array(
-                cache, "grad_topo_np", deg_array.shape, np
-            )
+            grad_topo = _ensure_cached_array(cache, "grad_topo_np", deg_array.shape, np)
 
-        np.copyto(grad_phase, theta_np, casting="unsafe")
-        grad_phase -= th_bar
-        grad_phase += math.pi
-        np.mod(grad_phase, math.tau, out=grad_phase)
-        grad_phase -= math.pi
-        grad_phase *= -1.0 / math.pi
+        angle_diff_array(theta_np, th_bar, np=np, out=grad_phase)
+        np.multiply(grad_phase, -1.0 / math.pi, out=grad_phase)
 
         np.copyto(grad_epi, epi_bar, casting="unsafe")
         grad_epi -= epi_np
@@ -1069,8 +1155,12 @@ def _apply_dnfr_gradients(
             cache.grad_topo_np = None
             cache.grad_total_np = None
 
+    stop_timer("dnfr_gradient_assembly", grad_timer)
+
+    write_timer = start_timer()
     for i, n in enumerate(nodes):
         set_dnfr(G, n, float(dnfr_values[i]))
+    stop_timer("dnfr_inplace_write", write_timer)
 
 
 def _init_bar_arrays(
@@ -1124,10 +1214,7 @@ def _init_bar_arrays(
                 else:
                     deg_size = len(degs)
                 deg_bar = cache.deg_bar_np
-                if (
-                    deg_bar is None
-                    or getattr(deg_bar, "shape", None) != (deg_size,)
-                ):
+                if deg_bar is None or getattr(deg_bar, "shape", None) != (deg_size,):
                     if isinstance(degs, dict):
                         deg_bar = np.array(
                             [float(degs.get(node, 0.0)) for node in nodes],
@@ -1198,9 +1285,7 @@ def _init_bar_arrays(
             th_bar = list(theta)
             epi_bar = list(epi)
             vf_bar = list(vf)
-            deg_bar = (
-                list(degs) if w_topo != 0.0 and degs is not None else None
-            )
+            deg_bar = list(degs) if w_topo != 0.0 and degs is not None else None
     return th_bar, epi_bar, vf_bar, deg_bar
 
 
@@ -1294,13 +1379,31 @@ def _compute_dnfr_common(
     deg_sum: Sequence[float] | None = None,
     degs: Sequence[float] | None = None,
     n_jobs: int | None = None,
+    profile: MutableMapping[str, float] | None = None,
 ) -> None:
-    """Compute neighbour means and apply ΔNFR gradients."""
+    """Compute neighbour means and apply ΔNFR gradients.
+
+    Parameters
+    ----------
+    profile : MutableMapping[str, float] or None, optional
+        Mutable mapping that records wall-clock durations for the neighbour
+        mean computation (``"dnfr_neighbor_means"``), the gradient assembly
+        (``"dnfr_gradient_assembly"``) and the final in-place writes to the
+        graph (``"dnfr_inplace_write"``).
+    """
+    start_timer, stop_timer = _profile_start_stop(
+        profile,
+        keys=("dnfr_neighbor_means", "dnfr_gradient_assembly", "dnfr_inplace_write"),
+    )
+
     np_module = get_numpy()
-    if np_module is not None and isinstance(count, getattr(np_module, "ndarray", tuple)):
+    if np_module is not None and isinstance(
+        count, getattr(np_module, "ndarray", tuple)
+    ):
         np_arg = np_module
     else:
         np_arg = None
+    neighbor_timer = start_timer()
     th_bar, epi_bar, vf_bar, deg_bar = _compute_neighbor_means(
         G,
         data,
@@ -1313,6 +1416,7 @@ def _compute_dnfr_common(
         degs=degs,
         np=np_arg,
     )
+    stop_timer("dnfr_neighbor_means", neighbor_timer)
     _apply_dnfr_gradients(
         G,
         data,
@@ -1322,6 +1426,7 @@ def _compute_dnfr_common(
         deg_bar,
         degs,
         n_jobs=n_jobs,
+        profile=profile,
     )
 
 
@@ -1330,7 +1435,11 @@ def _reset_numpy_buffer(
     size: int,
     np: ModuleType,
 ) -> np.ndarray:
-    if buffer is None or getattr(buffer, "shape", None) is None or buffer.shape[0] != size:
+    if (
+        buffer is None
+        or getattr(buffer, "shape", None) is None
+        or buffer.shape[0] != size
+    ):
         return np.zeros(size, dtype=float)
     buffer.fill(0.0)
     return buffer
@@ -1476,10 +1585,12 @@ def _accumulate_neighbors_dense(
     vectors = [state["cos"], state["sin"], state["epi"], state["vf"]]
 
     components = _ensure_cached_array(cache, "dense_components_np", (n, 4), np)
-    for col, src_vec in enumerate(vectors):
-        np.copyto(components[:, col], src_vec, casting="unsafe")
-
     accum = _ensure_cached_array(cache, "dense_accum_np", (n, 4), np)
+
+    # ``components`` retains the last source copies so callers relying on
+    # cached buffers (e.g. diagnostics) still observe meaningful values.
+    np.copyto(components, np.column_stack(vectors), casting="unsafe")
+
     np.matmul(A, components, out=accum)
 
     np.copyto(x, accum[:, 0], casting="unsafe")
@@ -1537,6 +1648,7 @@ def _accumulate_neighbors_broadcasted(
     deg_array: np.ndarray | None,
     cache: DnfrCache | None,
     np: ModuleType,
+    chunk_size: int | None = None,
 ) -> dict[str, np.ndarray]:
     """Accumulate neighbour contributions using direct indexed reductions."""
 
@@ -1548,6 +1660,23 @@ def _accumulate_neighbors_broadcasted(
 
     component_rows = 4 + (1 if include_count else 0) + (1 if use_topology else 0)
 
+    if edge_count:
+        if chunk_size is None:
+            resolved_chunk = edge_count
+        else:
+            try:
+                resolved_chunk = int(chunk_size)
+            except (TypeError, ValueError):
+                resolved_chunk = edge_count
+            else:
+                if resolved_chunk <= 0:
+                    resolved_chunk = edge_count
+        resolved_chunk = max(1, min(edge_count, resolved_chunk))
+    else:
+        resolved_chunk = 0
+
+    use_chunks = bool(edge_count and resolved_chunk < edge_count)
+
     if cache is not None:
         base_signature = (id(edge_src), id(edge_dst), n, edge_count)
         cache.edge_signature = base_signature
@@ -1565,52 +1694,144 @@ def _accumulate_neighbors_broadcasted(
         else:
             accum.fill(0.0)
 
-        edge_values = cache.neighbor_edge_values_np
-        if (
-            edge_values is None
-            or getattr(edge_values, "shape", None) != (edge_count,)
-        ):
-            edge_values = np.empty((edge_count,), dtype=float)
-            cache.neighbor_edge_values_np = edge_values
+        workspace = cache.neighbor_edge_values_np
+        if use_chunks:
+            workspace_length = resolved_chunk
+        else:
+            workspace_length = component_rows
+        if workspace_length:
+            expected_shape = (component_rows, workspace_length)
+            if workspace is None or getattr(workspace, "shape", None) != expected_shape:
+                workspace = np.empty(expected_shape, dtype=float)
+        else:
+            workspace = None
+        cache.neighbor_edge_values_np = workspace
 
         cache.neighbor_accum_signature = signature
     else:
         accum = np.zeros((component_rows, n), dtype=float)
-        edge_values = (
-            np.empty((edge_count,), dtype=float)
-            if edge_count
-            else np.empty((0,), dtype=float)
+        workspace_length = resolved_chunk if use_chunks else component_rows
+        workspace = (
+            np.empty((component_rows, workspace_length), dtype=float)
+            if workspace_length
+            else None
         )
 
     if edge_count:
         row = 0
-
-        np.take(cos, edge_dst, out=edge_values)
-        np.add.at(accum[row], edge_src, edge_values)
+        cos_row = row
         row += 1
-
-        np.take(sin, edge_dst, out=edge_values)
-        np.add.at(accum[row], edge_src, edge_values)
+        sin_row = row
         row += 1
-
-        np.take(epi, edge_dst, out=edge_values)
-        np.add.at(accum[row], edge_src, edge_values)
+        epi_row = row
         row += 1
-
-        np.take(vf, edge_dst, out=edge_values)
-        np.add.at(accum[row], edge_src, edge_values)
+        vf_row = row
         row += 1
-
-        if include_count and count is not None:
-            edge_values.fill(1.0)
-            np.add.at(accum[row], edge_src, edge_values)
+        count_row = row if include_count and count is not None else None
+        if count_row is not None:
             row += 1
+        deg_row = row if use_topology and deg_array is not None else None
+
+        edge_src_int = edge_src.astype(np.intp, copy=False)
+        edge_dst_int = edge_dst.astype(np.intp, copy=False)
+
+        if use_chunks:
+            chunk_step = resolved_chunk if resolved_chunk else edge_count
+            chunk_indices = range(0, edge_count, chunk_step)
+
+            for start in chunk_indices:
+                end = min(start + chunk_step, edge_count)
+                if start >= end:
+                    continue
+                src_slice = edge_src_int[start:end]
+                dst_slice = edge_dst_int[start:end]
+                slice_len = end - start
+                if slice_len <= 0:
+                    continue
+
+                if workspace is not None:
+                    chunk_matrix = workspace[:, :slice_len]
+                else:
+                    chunk_matrix = np.empty((component_rows, slice_len), dtype=float)
+
+                np.take(cos, dst_slice, out=chunk_matrix[cos_row, :slice_len])
+                np.take(sin, dst_slice, out=chunk_matrix[sin_row, :slice_len])
+                np.take(epi, dst_slice, out=chunk_matrix[epi_row, :slice_len])
+                np.take(vf, dst_slice, out=chunk_matrix[vf_row, :slice_len])
+
+                if count_row is not None:
+                    chunk_matrix[count_row, :slice_len].fill(1.0)
+                if deg_row is not None and deg_array is not None:
+                    np.take(deg_array, dst_slice, out=chunk_matrix[deg_row, :slice_len])
+
+                def _accumulate_into(
+                    target_row: int | None,
+                    values: np.ndarray | None = None,
+                    *,
+                    unit_weight: bool = False,
+                ) -> None:
+                    if target_row is None:
+                        return
+                    row_view = accum[target_row]
+                    if unit_weight:
+                        np.add.at(row_view, src_slice, 1.0)
+                    else:
+                        if values is None:
+                            return
+                        np.add.at(row_view, src_slice, values)
+
+                _accumulate_into(cos_row, chunk_matrix[cos_row, :slice_len])
+                _accumulate_into(sin_row, chunk_matrix[sin_row, :slice_len])
+                _accumulate_into(epi_row, chunk_matrix[epi_row, :slice_len])
+                _accumulate_into(vf_row, chunk_matrix[vf_row, :slice_len])
+
+                if count_row is not None:
+                    _accumulate_into(count_row, unit_weight=True)
 
-        if use_topology and deg_sum is not None and deg_array is not None:
-            np.take(deg_array, edge_dst, out=edge_values)
-            np.add.at(accum[row], edge_src, edge_values)
+                if deg_row is not None and deg_array is not None:
+                    _accumulate_into(deg_row, chunk_matrix[deg_row, :slice_len])
+        else:
+            def _apply_full_bincount(
+                target_row: int | None,
+                values: np.ndarray | None = None,
+                *,
+                unit_weight: bool = False,
+            ) -> None:
+                if target_row is None:
+                    return
+                if values is None and not unit_weight:
+                    return
+                if unit_weight:
+                    component_accum = np.bincount(
+                        edge_src_int,
+                        minlength=n,
+                    )
+                else:
+                    component_accum = np.bincount(
+                        edge_src_int,
+                        weights=values,
+                        minlength=n,
+                    )
+                np.copyto(
+                    accum[target_row, : n],
+                    component_accum[:n],
+                    casting="unsafe",
+                )
+
+            _apply_full_bincount(cos_row, np.take(cos, edge_dst_int))
+            _apply_full_bincount(sin_row, np.take(sin, edge_dst_int))
+            _apply_full_bincount(epi_row, np.take(epi, edge_dst_int))
+            _apply_full_bincount(vf_row, np.take(vf, edge_dst_int))
+
+            if count_row is not None:
+                _apply_full_bincount(count_row, unit_weight=True)
+
+            if deg_row is not None and deg_array is not None:
+                _apply_full_bincount(deg_row, np.take(deg_array, edge_dst_int))
     else:
         accum.fill(0.0)
+        if workspace is not None:
+            workspace.fill(0.0)
 
     row = 0
     np.copyto(x, accum[row], casting="unsafe")
@@ -1631,7 +1852,7 @@ def _accumulate_neighbors_broadcasted(
 
     return {
         "accumulator": accum,
-        "edge_values": edge_values,
+        "edge_values": workspace,
     }
 
 
@@ -1741,9 +1962,15 @@ def _build_neighbor_sums_common(
             for future in futures:
                 chunk_results.append(future.result())
 
-        for start, chunk_x, chunk_y, chunk_epi, chunk_vf, chunk_count, chunk_deg in sorted(
-            chunk_results, key=lambda item: item[0]
-        ):
+        for (
+            start,
+            chunk_x,
+            chunk_y,
+            chunk_epi,
+            chunk_vf,
+            chunk_count,
+            chunk_deg,
+        ) in sorted(chunk_results, key=lambda item: item[0]):
             end = start + len(chunk_x)
             x[start:end] = chunk_x
             y[start:end] = chunk_y
@@ -1824,11 +2051,14 @@ def _accumulate_neighbors_numpy(
         data["edge_count"] = int(edge_src.size)
 
     cached_deg_array = data.get("deg_array")
-    reuse_count_from_deg = False
+    reuse_count_from_deg = bool(count is not None and cached_deg_array is not None)
+    count_for_accum = count
     if count is not None:
-        if cached_deg_array is not None:
+        if reuse_count_from_deg:
+            # Reuse the cached degree vector as neighbour counts to avoid
+            # allocating an extra accumulator row in the broadcast routine.
             np.copyto(count, cached_deg_array, casting="unsafe")
-            reuse_count_from_deg = True
+            count_for_accum = None
         else:
             count.fill(0.0)
 
@@ -1841,6 +2071,24 @@ def _accumulate_neighbors_numpy(
     elif cached_deg_array is not None:
         deg_array = cached_deg_array
 
+    edge_count = int(edge_src.size) if edge_src is not None else 0
+    chunk_hint = data.get("neighbor_chunk_hint")
+    if chunk_hint is None:
+        chunk_hint = G.graph.get("DNFR_CHUNK_SIZE")
+    resolved_neighbor_chunk = (
+        resolve_chunk_size(
+            chunk_hint,
+            edge_count,
+            minimum=1,
+            approx_bytes_per_item=_DNFR_APPROX_BYTES_PER_EDGE,
+            clamp_to=None,
+        )
+        if edge_count
+        else 0
+    )
+    data["neighbor_chunk_hint"] = chunk_hint
+    data["neighbor_chunk_size"] = resolved_neighbor_chunk
+
     accum = _accumulate_neighbors_broadcasted(
         edge_src=edge_src,
         edge_dst=edge_dst,
@@ -1852,19 +2100,26 @@ def _accumulate_neighbors_numpy(
         y=y,
         epi_sum=epi_sum,
         vf_sum=vf_sum,
-        count=count,
+        count=count_for_accum,
         deg_sum=deg_sum,
         deg_array=deg_array,
         cache=cache,
         np=np,
+        chunk_size=resolved_neighbor_chunk,
     )
 
     data["neighbor_accum_np"] = accum.get("accumulator")
-    data["neighbor_edge_values_np"] = accum.get("edge_values")
+    edge_values = accum.get("edge_values")
+    data["neighbor_edge_values_np"] = edge_values
+    if edge_values is not None:
+        width = getattr(edge_values, "shape", (0, 0))[1]
+        data["neighbor_chunk_size"] = int(width)
+    else:
+        data["neighbor_chunk_size"] = resolved_neighbor_chunk
     if cache is not None:
         data["neighbor_accum_signature"] = cache.neighbor_accum_signature
-    if reuse_count_from_deg and count is not None and cached_deg_array is not None:
-        np.copyto(count, cached_deg_array, casting="unsafe")
+    if reuse_count_from_deg and cached_deg_array is not None:
+        count = cached_deg_array
     degs = deg_array if deg_sum is not None and deg_array is not None else None
     return x, y, epi_sum, vf_sum, count, deg_sum, degs
 
@@ -1875,6 +2130,7 @@ def _compute_dnfr(
     *,
     use_numpy: bool | None = None,
     n_jobs: int | None = None,
+    profile: MutableMapping[str, float] | None = None,
 ) -> None:
     """Compute ΔNFR using neighbour sums.
 
@@ -1889,7 +2145,19 @@ def _compute_dnfr(
         prepares NumPy buffers (if available). When ``False`` the engine still
         prefers the vectorised path whenever :func:`get_numpy` returns a module
         and the graph does not set ``vectorized_dnfr`` to ``False``.
+    profile : MutableMapping[str, float] or None, optional
+        Mutable mapping that aggregates wall-clock durations for neighbour
+        accumulation and records which execution branch was used. The
+        ``"dnfr_neighbor_accumulation"`` bucket gathers the time spent inside
+        :func:`_build_neighbor_sums_common`, while ``"dnfr_path"`` stores the
+        string ``"vectorized"`` or ``"fallback"`` describing the active
+        implementation.
     """
+    start_timer, stop_timer = _profile_start_stop(
+        profile,
+        keys=("dnfr_neighbor_accumulation",),
+    )
+
     np_module = get_numpy()
     data["dnfr_numpy_available"] = bool(np_module)
     vector_disabled = G.graph.get("vectorized_dnfr") is False
@@ -1899,23 +2167,29 @@ def _compute_dnfr(
     if use_numpy is False or vector_disabled:
         prefer_dense = False
     data["dnfr_used_numpy"] = bool(prefer_dense and np_module is not None)
+    if profile is not None:
+        profile["dnfr_path"] = "vectorized" if data["dnfr_used_numpy"] else "fallback"
 
     data["n_jobs"] = n_jobs
     try:
+        neighbor_timer = start_timer()
         res = _build_neighbor_sums_common(
             G,
             data,
             use_numpy=prefer_dense,
             n_jobs=n_jobs,
         )
+        stop_timer("dnfr_neighbor_accumulation", neighbor_timer)
     except TypeError as exc:
         if "n_jobs" not in str(exc):
             raise
+        neighbor_timer = start_timer()
         res = _build_neighbor_sums_common(
             G,
             data,
             use_numpy=prefer_dense,
         )
+        stop_timer("dnfr_neighbor_accumulation", neighbor_timer)
     if res is None:
         return
     x, y, epi_sum, vf_sum, count, deg_sum, degs = res
@@ -1930,6 +2204,7 @@ def _compute_dnfr(
         deg_sum=deg_sum,
         degs=degs,
         n_jobs=n_jobs,
+        profile=profile,
     )
 
 
@@ -1938,6 +2213,7 @@ def default_compute_delta_nfr(
     *,
     cache_size: int | None = 1,
     n_jobs: int | None = None,
+    profile: MutableMapping[str, float] | None = None,
 ) -> None:
     """Compute ΔNFR by mixing phase, EPI, νf and a topological term.
 
@@ -1953,17 +2229,40 @@ def default_compute_delta_nfr(
         Parallel worker count for the pure-Python accumulation path. ``None``
         or values <= 1 preserve the serial behaviour. The vectorised NumPy
         branch ignores this parameter as it already operates in bulk.
+    profile : MutableMapping[str, float] or None, optional
+        Mutable mapping that aggregates the wall-clock timings captured during
+        the ΔNFR computation. The mapping receives the buckets documented in
+        :func:`_prepare_dnfr_data` and :func:`_compute_dnfr`, plus
+        ``"dnfr_neighbor_means"``, ``"dnfr_gradient_assembly"`` and
+        ``"dnfr_inplace_write"`` describing the internal stages of
+        :func:`_compute_dnfr_common`. ``"dnfr_path"`` reflects whether the
+        vectorised or fallback implementation executed the call.
     """
-    data = _prepare_dnfr_data(G, cache_size=cache_size)
+    if profile is not None:
+        for key in (
+            "dnfr_cache_rebuild",
+            "dnfr_neighbor_accumulation",
+            "dnfr_neighbor_means",
+            "dnfr_gradient_assembly",
+            "dnfr_inplace_write",
+        ):
+            profile.setdefault(key, 0.0)
+
+    data = _prepare_dnfr_data(G, cache_size=cache_size, profile=profile)
     _write_dnfr_metadata(
         G,
         weights=data["weights"],
         hook_name="default_compute_delta_nfr",
     )
-    _compute_dnfr(G, data, n_jobs=n_jobs)
+    _compute_dnfr(G, data, n_jobs=n_jobs, profile=profile)
     if not data.get("dnfr_numpy_available"):
         cache = data.get("cache")
-        if isinstance(cache, DnfrCache):
+        cache_size = data.get("cache_size")
+        caching_enabled = (
+            isinstance(cache, DnfrCache)
+            and (cache_size is None or int(cache_size) > 0)
+        )
+        if isinstance(cache, DnfrCache) and not caching_enabled:
             for attr in (
                 "neighbor_x_np",
                 "neighbor_y_np",
@@ -2016,9 +2315,7 @@ def set_delta_nfr_hook(
     _wrapped.__doc__ = getattr(func, "__doc__", _wrapped.__doc__)
 
     G.graph["compute_delta_nfr"] = _wrapped
-    G.graph["_dnfr_hook_name"] = str(
-        name or getattr(func, "__name__", "custom_dnfr")
-    )
+    G.graph["_dnfr_hook_name"] = str(name or getattr(func, "__name__", "custom_dnfr"))
     if "_dnfr_weights" not in G.graph:
         _configure_dnfr_weights(G)
     if note:
@@ -2063,7 +2360,7 @@ def _apply_dnfr_hook(
     note: str | None = None,
     n_jobs: int | None = None,
 ) -> None:
-    """Generic helper to compute and store ΔNFR using ``grads``.
+    """Compute and store ΔNFR using ``grads``.
 
     Parameters
     ----------
@@ -2158,7 +2455,7 @@ def _apply_dnfr_hook(
     _write_dnfr_metadata(G, weights=weights, hook_name=hook_name, note=note)
 
 
-# --- Hooks de ejemplo (opcionales) ---
+# --- Example hooks (optional) ---
 
 
 class _PhaseGradient:
@@ -2232,7 +2529,7 @@ class _NeighborAverageGradient:
 
 
 def dnfr_phase_only(G: TNFRGraph, *, n_jobs: int | None = None) -> None:
-    """Example: ΔNFR from phase only (Kuramoto-like).
+    """Compute ΔNFR from phase only (Kuramoto-like).
 
     Parameters
     ----------
@@ -2256,7 +2553,7 @@ def dnfr_phase_only(G: TNFRGraph, *, n_jobs: int | None = None) -> None:
 
 
 def dnfr_epi_vf_mixed(G: TNFRGraph, *, n_jobs: int | None = None) -> None:
-    """Example: ΔNFR without phase, mixing EPI and νf.
+    """Compute ΔNFR without phase, mixing EPI and νf.
 
     Parameters
     ----------
@@ -2267,7 +2564,9 @@ def dnfr_epi_vf_mixed(G: TNFRGraph, *, n_jobs: int | None = None) -> None:
         serial execution.
     """
 
-    epi_values = {n: float(get_attr(nd, ALIAS_EPI, 0.0)) for n, nd in G.nodes(data=True)}
+    epi_values = {
+        n: float(get_attr(nd, ALIAS_EPI, 0.0)) for n, nd in G.nodes(data=True)
+    }
     vf_values = {n: float(get_attr(nd, ALIAS_VF, 0.0)) for n, nd in G.nodes(data=True)}
     grads = {
         "epi": _NeighborAverageGradient(ALIAS_EPI, epi_values),
@@ -2299,7 +2598,9 @@ def dnfr_laplacian(G: TNFRGraph, *, n_jobs: int | None = None) -> None:
     wE = float(weights_cfg.get("epi", DEFAULTS["DNFR_WEIGHTS"]["epi"]))
     wV = float(weights_cfg.get("vf", DEFAULTS["DNFR_WEIGHTS"]["vf"]))
 
-    epi_values = {n: float(get_attr(nd, ALIAS_EPI, 0.0)) for n, nd in G.nodes(data=True)}
+    epi_values = {
+        n: float(get_attr(nd, ALIAS_EPI, 0.0)) for n, nd in G.nodes(data=True)
+    }
     vf_values = {n: float(get_attr(nd, ALIAS_VF, 0.0)) for n, nd in G.nodes(data=True)}
     grads = {
         "epi": _NeighborAverageGradient(ALIAS_EPI, epi_values),