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

tnfr/metrics/coherence.py

@@ -3,22 +3,28 @@
 from __future__ import annotations
 
 import math
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from concurrent.futures import ProcessPoolExecutor
 from dataclasses import dataclass
-from typing import Any, Sequence
+from types import ModuleType
+from typing import Any, MutableMapping, cast
 
-
-from ..constants import (
-    get_aliases,
-    get_param,
-)
+from .._compat import TypeAlias
+from ..alias import collect_attr, collect_theta_attr, get_attr, set_attr
 from ..callback_utils import CallbackEvent, callback_manager
-from ..glyph_history import ensure_history, append_metric
-from ..alias import collect_attr, get_attr, set_attr
-from ..collections_utils import normalize_weights
-from ..helpers.numeric import clamp01
-from ..cache import ensure_node_index_map
-from .common import compute_coherence, min_max_range
-from .trig_cache import compute_theta_trig, get_trig_cache
+from ..constants import get_param
+from ..constants.aliases import (
+    ALIAS_D2VF,
+    ALIAS_DNFR,
+    ALIAS_DSI,
+    ALIAS_DVF,
+    ALIAS_DEPI,
+    ALIAS_EPI,
+    ALIAS_SI,
+    ALIAS_VF,
+)
+from ..glyph_history import append_metric, ensure_history
+from ..utils import clamp01
 from ..observers import (
     DEFAULT_GLYPH_LOAD_SPAN,
     DEFAULT_WBAR_SPAN,
@@ -27,20 +33,30 @@ from ..observers import (
     phase_sync,
 )
 from ..sense import sigma_vector
-from ..import_utils import get_numpy
-from ..logging_utils import get_logger
+from ..types import (
+    CoherenceMetric,
+    FloatArray,
+    FloatMatrix,
+    GlyphLoadDistribution,
+    HistoryState,
+    NodeId,
+    ParallelWijPayload,
+    SigmaVector,
+    TNFRGraph,
+)
+from ..utils import (
+    ensure_node_index_map,
+    get_logger,
+    get_numpy,
+    normalize_weights,
+    resolve_chunk_size,
+)
+from .common import compute_coherence, min_max_range
+from .trig_cache import compute_theta_trig, get_trig_cache
 
 logger = get_logger(__name__)
 
-ALIAS_THETA = get_aliases("THETA")
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_VF = get_aliases("VF")
-ALIAS_SI = get_aliases("SI")
-ALIAS_DNFR = get_aliases("DNFR")
-ALIAS_DEPI = get_aliases("DEPI")
-ALIAS_DSI = get_aliases("DSI")
-ALIAS_DVF = get_aliases("DVF")
-ALIAS_D2VF = get_aliases("D2VF")
+GLYPH_LOAD_STABILIZERS_KEY = "glyph_load_stabilizers"
 
 
 @dataclass
@@ -55,16 +71,53 @@ class SimilarityInputs:
     sin_vals: Sequence[float] | None = None
 
 
+CoherenceMatrixDense = list[list[float]]
+CoherenceMatrixSparse = list[tuple[int, int, float]]
+CoherenceMatrixPayload = CoherenceMatrixDense | CoherenceMatrixSparse
+PhaseSyncWeights: TypeAlias = (
+    Sequence[float] | CoherenceMatrixSparse | CoherenceMatrixDense
+)
+
+SimilarityComponents = tuple[float, float, float, float]
+VectorizedComponents: TypeAlias = tuple[
+    FloatMatrix, FloatMatrix, FloatMatrix, FloatMatrix
+]
+ScalarOrArray: TypeAlias = float | FloatArray
+StabilityChunkArgs = tuple[
+    Sequence[float],
+    Sequence[float],
+    Sequence[float],
+    Sequence[float | None],
+    Sequence[float],
+    Sequence[float | None],
+    Sequence[float | None],
+    float,
+    float,
+    float,
+]
+StabilityChunkResult = tuple[
+    int,
+    int,
+    float,
+    float,
+    list[float],
+    list[float],
+    list[float],
+]
+
+MetricValue: TypeAlias = CoherenceMetric
+MetricProvider = Callable[[], MetricValue]
+MetricRecord: TypeAlias = tuple[MetricValue | MetricProvider, str]
 def _compute_wij_phase_epi_vf_si_vectorized(
-    epi,
-    vf,
-    si,
-    cos_th,
-    sin_th,
-    epi_range,
-    vf_range,
-    np,
-):
+    epi: FloatArray,
+    vf: FloatArray,
+    si: FloatArray,
+    cos_th: FloatArray,
+    sin_th: FloatArray,
+    epi_range: float,
+    vf_range: float,
+    np: ModuleType,
+) -> VectorizedComponents:
     """Vectorized computation of similarity components.
 
     All parameters are expected to be NumPy arrays already cast to ``float``
@@ -75,9 +128,7 @@ def _compute_wij_phase_epi_vf_si_vectorized(
     epi_range = epi_range if epi_range > 0 else 1.0
     vf_range = vf_range if vf_range > 0 else 1.0
     s_phase = 0.5 * (
-        1.0
-        + cos_th[:, None] * cos_th[None, :]
-        + sin_th[:, None] * sin_th[None, :]
+        1.0 + cos_th[:, None] * cos_th[None, :] + sin_th[:, None] * sin_th[None, :]
     )
     s_epi = 1.0 - np.abs(epi[:, None] - epi[None, :]) / epi_range
     s_vf = 1.0 - np.abs(vf[:, None] - vf[None, :]) / vf_range
@@ -90,13 +141,13 @@ def compute_wij_phase_epi_vf_si(
     i: int | None = None,
     j: int | None = None,
     *,
-    trig=None,
-    G: Any | None = None,
-    nodes: Sequence[Any] | None = None,
+    trig: Any | None = None,
+    G: TNFRGraph | None = None,
+    nodes: Sequence[NodeId] | None = None,
     epi_range: float = 1.0,
     vf_range: float = 1.0,
-    np=None,
-):
+    np: ModuleType | None = None,
+) -> SimilarityComponents | VectorizedComponents:
     """Return similarity components for nodes ``i`` and ``j``.
 
     When ``np`` is provided and ``i`` and ``j`` are ``None`` the computation is
@@ -126,11 +177,11 @@ def compute_wij_phase_epi_vf_si(
     si_vals = inputs.si_vals
 
     if np is not None and i is None and j is None:
-        epi = np.asarray(epi_vals)
-        vf = np.asarray(vf_vals)
-        si = np.asarray(si_vals)
-        cos_th = np.asarray(cos_vals, dtype=float)
-        sin_th = np.asarray(sin_vals, dtype=float)
+        epi = cast(FloatArray, np.asarray(epi_vals, dtype=float))
+        vf = cast(FloatArray, np.asarray(vf_vals, dtype=float))
+        si = cast(FloatArray, np.asarray(si_vals, dtype=float))
+        cos_th = cast(FloatArray, np.asarray(cos_vals, dtype=float))
+        sin_th = cast(FloatArray, np.asarray(sin_vals, dtype=float))
         return _compute_wij_phase_epi_vf_si_vectorized(
             epi,
             vf,
@@ -158,33 +209,42 @@ def compute_wij_phase_epi_vf_si(
 
 
 def _combine_similarity(
-    s_phase,
-    s_epi,
-    s_vf,
-    s_si,
-    phase_w,
-    epi_w,
-    vf_w,
-    si_w,
-    np=None,
-):
+    s_phase: ScalarOrArray,
+    s_epi: ScalarOrArray,
+    s_vf: ScalarOrArray,
+    s_si: ScalarOrArray,
+    phase_w: float,
+    epi_w: float,
+    vf_w: float,
+    si_w: float,
+    np: ModuleType | None = None,
+) -> ScalarOrArray:
     wij = phase_w * s_phase + epi_w * s_epi + vf_w * s_vf + si_w * s_si
     if np is not None:
-        return np.clip(wij, 0.0, 1.0)
+        return cast(FloatArray, np.clip(wij, 0.0, 1.0))
     return clamp01(wij)
 
 
 def _wij_components_weights(
-    G,
-    nodes,
+    G: TNFRGraph,
+    nodes: Sequence[NodeId] | None,
     inputs: SimilarityInputs,
-    wnorm,
+    wnorm: Mapping[str, float],
     i: int | None = None,
     j: int | None = None,
     epi_range: float = 1.0,
     vf_range: float = 1.0,
-    np=None,
-):
+    np: ModuleType | None = None,
+) -> tuple[
+    ScalarOrArray,
+    ScalarOrArray,
+    ScalarOrArray,
+    ScalarOrArray,
+    float,
+    float,
+    float,
+    float,
+]:
     """Return similarity components together with their weights.
 
     This consolidates repeated computations ensuring that both the
@@ -210,17 +270,17 @@ def _wij_components_weights(
 
 
 def _wij_vectorized(
-    G,
-    nodes,
+    G: TNFRGraph,
+    nodes: Sequence[NodeId],
     inputs: SimilarityInputs,
-    wnorm,
-    epi_min,
-    epi_max,
-    vf_min,
-    vf_max,
-    self_diag,
-    np,
-):
+    wnorm: Mapping[str, float],
+    epi_min: float,
+    epi_max: float,
+    vf_min: float,
+    vf_max: float,
+    self_diag: bool,
+    np: ModuleType,
+) -> FloatMatrix:
     epi_range = epi_max - epi_min if epi_max > epi_min else 1.0
     vf_range = vf_max - vf_min if vf_max > vf_min else 1.0
     (
@@ -241,65 +301,110 @@ def _wij_vectorized(
         vf_range=vf_range,
         np=np,
     )
-    wij = _combine_similarity(
-        s_phase, s_epi, s_vf, s_si, phase_w, epi_w, vf_w, si_w, np=np
+    wij_matrix = cast(
+        FloatMatrix,
+        _combine_similarity(
+            s_phase, s_epi, s_vf, s_si, phase_w, epi_w, vf_w, si_w, np=np
+        ),
     )
     if self_diag:
-        np.fill_diagonal(wij, 1.0)
+        np.fill_diagonal(wij_matrix, 1.0)
     else:
-        np.fill_diagonal(wij, 0.0)
-    return wij
+        np.fill_diagonal(wij_matrix, 0.0)
+    return wij_matrix
 
 
-def _assign_wij(
-    wij: list[list[float]],
+def _compute_wij_value_raw(
     i: int,
     j: int,
-    G: Any,
-    nodes: Sequence[Any],
-    inputs: SimilarityInputs,
+    epi_vals: Sequence[float],
+    vf_vals: Sequence[float],
+    si_vals: Sequence[float],
+    cos_vals: Sequence[float],
+    sin_vals: Sequence[float],
+    weights: tuple[float, float, float, float],
     epi_range: float,
     vf_range: float,
-    wnorm: dict[str, float],
-) -> None:
-    (
-        s_phase,
-        s_epi,
-        s_vf,
-        s_si,
-        phase_w,
-        epi_w,
-        vf_w,
-        si_w,
-    ) = _wij_components_weights(
-        G,
-        nodes,
-        inputs,
-        wnorm,
-        i,
-        j,
-        epi_range,
-        vf_range,
-    )
-    wij_ij = _combine_similarity(
-        s_phase, s_epi, s_vf, s_si, phase_w, epi_w, vf_w, si_w
-    )
-    wij[i][j] = wij[j][i] = wij_ij
+) -> float:
+    epi_range = epi_range if epi_range > 0 else 1.0
+    vf_range = vf_range if vf_range > 0 else 1.0
+    phase_w, epi_w, vf_w, si_w = weights
+    cos_i = cos_vals[i]
+    sin_i = sin_vals[i]
+    cos_j = cos_vals[j]
+    sin_j = sin_vals[j]
+    s_phase = 0.5 * (1.0 + (cos_i * cos_j + sin_i * sin_j))
+    s_epi = 1.0 - abs(epi_vals[i] - epi_vals[j]) / epi_range
+    s_vf = 1.0 - abs(vf_vals[i] - vf_vals[j]) / vf_range
+    s_si = 1.0 - abs(si_vals[i] - si_vals[j])
+    wij = phase_w * s_phase + epi_w * s_epi + vf_w * s_vf + si_w * s_si
+    return clamp01(wij)
+
+
+_PARALLEL_WIJ_DATA: ParallelWijPayload | None = None
+
+
+def _init_parallel_wij(data: ParallelWijPayload) -> None:
+    """Store immutable state for parallel ``wij`` computation."""
+
+    global _PARALLEL_WIJ_DATA
+    _PARALLEL_WIJ_DATA = data
+
+
+def _parallel_wij_worker(
+    pairs: Sequence[tuple[int, int]],
+) -> list[tuple[int, int, float]]:
+    """Compute coherence weights for ``pairs`` using shared state."""
+
+    if _PARALLEL_WIJ_DATA is None:
+        raise RuntimeError("Parallel coherence data not initialized")
+
+    data = _PARALLEL_WIJ_DATA
+    epi_vals: Sequence[float] = data["epi_vals"]
+    vf_vals: Sequence[float] = data["vf_vals"]
+    si_vals: Sequence[float] = data["si_vals"]
+    cos_vals: Sequence[float] = data["cos_vals"]
+    sin_vals: Sequence[float] = data["sin_vals"]
+    weights: tuple[float, float, float, float] = data["weights"]
+    epi_range: float = data["epi_range"]
+    vf_range: float = data["vf_range"]
+
+    compute = _compute_wij_value_raw
+    return [
+        (
+            i,
+            j,
+            compute(
+                i,
+                j,
+                epi_vals,
+                vf_vals,
+                si_vals,
+                cos_vals,
+                sin_vals,
+                weights,
+                epi_range,
+                vf_range,
+            ),
+        )
+        for i, j in pairs
+    ]
 
 
 def _wij_loops(
-    G,
-    nodes: Sequence[Any],
-    node_to_index: dict[Any, int],
+    G: TNFRGraph,
+    nodes: Sequence[NodeId],
+    node_to_index: Mapping[NodeId, int],
     inputs: SimilarityInputs,
-    wnorm: dict[str, float],
+    wnorm: Mapping[str, float],
     epi_min: float,
     epi_max: float,
     vf_min: float,
     vf_max: float,
     neighbors_only: bool,
     self_diag: bool,
-) -> list[list[float]]:
+    n_jobs: int | None = 1,
+) -> CoherenceMatrixDense:
     n = len(nodes)
     cos_vals = inputs.cos_vals
     sin_vals = inputs.sin_vals
@@ -310,47 +415,107 @@ def _wij_loops(
         sin_vals = [trig_local.sin[n] for n in nodes]
         inputs.cos_vals = cos_vals
         inputs.sin_vals = sin_vals
-    wij = [
-        [1.0 if (self_diag and i == j) else 0.0 for j in range(n)]
-        for i in range(n)
-    ]
+    assert cos_vals is not None
+    assert sin_vals is not None
+    epi_vals = list(inputs.epi_vals)
+    vf_vals = list(inputs.vf_vals)
+    si_vals = list(inputs.si_vals)
+    cos_vals_list = list(cos_vals)
+    sin_vals_list = list(sin_vals)
+    inputs.epi_vals = epi_vals
+    inputs.vf_vals = vf_vals
+    inputs.si_vals = si_vals
+    inputs.cos_vals = cos_vals_list
+    inputs.sin_vals = sin_vals_list
+    wij = [[1.0 if (self_diag and i == j) else 0.0 for j in range(n)] for i in range(n)]
     epi_range = epi_max - epi_min if epi_max > epi_min else 1.0
     vf_range = vf_max - vf_min if vf_max > vf_min else 1.0
+    weights = (
+        float(wnorm["phase"]),
+        float(wnorm["epi"]),
+        float(wnorm["vf"]),
+        float(wnorm["si"]),
+    )
+    pair_list: list[tuple[int, int]] = []
     if neighbors_only:
+        seen: set[tuple[int, int]] = set()
         for u, v in G.edges():
             i = node_to_index[u]
             j = node_to_index[v]
             if i == j:
                 continue
-            _assign_wij(
-                wij,
+            pair = (i, j) if i < j else (j, i)
+            if pair in seen:
+                continue
+            seen.add(pair)
+            pair_list.append(pair)
+    else:
+        for i in range(n):
+            for j in range(i + 1, n):
+                pair_list.append((i, j))
+
+    total_pairs = len(pair_list)
+    max_workers = 1
+    if n_jobs is not None:
+        try:
+            max_workers = int(n_jobs)
+        except (TypeError, ValueError):
+            max_workers = 1
+    if max_workers <= 1 or total_pairs == 0:
+        for i, j in pair_list:
+            wij_ij = _compute_wij_value_raw(
                 i,
                 j,
-                G,
-                nodes,
-                inputs,
+                epi_vals,
+                vf_vals,
+                si_vals,
+                cos_vals,
+                sin_vals,
+                weights,
                 epi_range,
                 vf_range,
-                wnorm,
             )
-    else:
-        for i in range(n):
-            for j in range(i + 1, n):
-                _assign_wij(
-                    wij,
-                    i,
-                    j,
-                    G,
-                    nodes,
-                    inputs,
-                    epi_range,
-                    vf_range,
-                    wnorm,
-                )
+            wij[i][j] = wij[j][i] = wij_ij
+        return wij
+
+    approx_chunk = math.ceil(total_pairs / max_workers) if max_workers else None
+    chunk_size = resolve_chunk_size(
+        approx_chunk,
+        total_pairs,
+        minimum=1,
+    )
+    payload: ParallelWijPayload = {
+        "epi_vals": tuple(epi_vals),
+        "vf_vals": tuple(vf_vals),
+        "si_vals": tuple(si_vals),
+        "cos_vals": tuple(cos_vals),
+        "sin_vals": tuple(sin_vals),
+        "weights": weights,
+        "epi_range": float(epi_range),
+        "vf_range": float(vf_range),
+    }
+
+    def _init() -> None:
+        _init_parallel_wij(payload)
+
+    with ProcessPoolExecutor(max_workers=max_workers, initializer=_init) as executor:
+        futures = []
+        for start in range(0, total_pairs, chunk_size):
+            chunk = pair_list[start : start + chunk_size]
+            futures.append(executor.submit(_parallel_wij_worker, chunk))
+        for future in futures:
+            for i, j, value in future.result():
+                wij[i][j] = wij[j][i] = value
     return wij
 
 
-def _compute_stats(values, row_sum, n, self_diag, np=None):
+def _compute_stats(
+    values: Iterable[float] | Any,
+    row_sum: Iterable[float] | Any,
+    n: int,
+    self_diag: bool,
+    np: ModuleType | None = None,
+) -> tuple[float, float, float, list[float], int]:
     """Return aggregate statistics for ``values`` and normalized row sums.
 
     ``values`` and ``row_sum`` can be any iterables. They are normalized to
@@ -360,62 +525,41 @@ def _compute_stats(values, row_sum, n, self_diag, np=None):
     """
 
     if np is not None:
-        # Normalize inputs to NumPy arrays
         if not isinstance(values, np.ndarray):
-            values = np.asarray(list(values), dtype=float)
+            values_arr = np.asarray(list(values), dtype=float)
         else:
-            values = values.astype(float)
+            values_arr = cast(Any, values.astype(float))
         if not isinstance(row_sum, np.ndarray):
-            row_sum = np.asarray(list(row_sum), dtype=float)
+            row_arr = np.asarray(list(row_sum), dtype=float)
         else:
-            row_sum = row_sum.astype(float)
-
-        def size_fn(v):
-            return int(v.size)
-
-        def min_fn(v):
-            return float(v.min()) if v.size else 0.0
-
-        def max_fn(v):
-            return float(v.max()) if v.size else 0.0
-
-        def mean_fn(v):
-            return float(v.mean()) if v.size else 0.0
-
-        def wi_fn(r, d):
-            return (r / d).astype(float).tolist()
-
+            row_arr = cast(Any, row_sum.astype(float))
+        count_val = int(values_arr.size)
+        min_val = float(values_arr.min()) if values_arr.size else 0.0
+        max_val = float(values_arr.max()) if values_arr.size else 0.0
+        mean_val = float(values_arr.mean()) if values_arr.size else 0.0
     else:
-        # Fall back to pure Python lists
-        values = list(values)
-        row_sum = list(row_sum)
-
-        def size_fn(v):
-            return len(v)
-
-        def min_fn(v):
-            return min(v) if v else 0.0
-
-        def max_fn(v):
-            return max(v) if v else 0.0
+        values_list = list(values)
+        row_arr = list(row_sum)
+        count_val = len(values_list)
+        min_val = min(values_list) if values_list else 0.0
+        max_val = max(values_list) if values_list else 0.0
+        mean_val = sum(values_list) / len(values_list) if values_list else 0.0
 
-        def mean_fn(v):
-            return sum(v) / len(v) if v else 0.0
-
-        def wi_fn(r, d):
-            return [float(r[i]) / d for i in range(n)]
-
-    count_val = size_fn(values)
-    min_val = min_fn(values)
-    max_val = max_fn(values)
-    mean_val = mean_fn(values)
     row_count = n if self_diag else n - 1
     denom = max(1, row_count)
-    Wi = wi_fn(row_sum, denom)
+    if np is not None:
+        Wi = (row_arr / denom).astype(float).tolist()  # type: ignore[operator]
+    else:
+        Wi = [float(row_arr[i]) / denom for i in range(n)]
     return min_val, max_val, mean_val, Wi, count_val
 
 
-def _coherence_numpy(wij, mode, thr, np):
+def _coherence_numpy(
+    wij: Any,
+    mode: str,
+    thr: float,
+    np: ModuleType,
+) -> tuple[int, Any, Any, CoherenceMatrixPayload]:
     """Aggregate coherence weights using vectorized operations.
 
     Produces the structural weight matrix ``W`` along with the list of off
@@ -430,42 +574,125 @@ def _coherence_numpy(wij, mode, thr, np):
         W = wij.tolist()
     else:
         idx = np.where((wij >= thr) & mask)
-        W = [
-            (int(i), int(j), float(wij[i, j]))
-            for i, j in zip(idx[0], idx[1])
-        ]
+        W = [(int(i), int(j), float(wij[i, j])) for i, j in zip(idx[0], idx[1])]
     return n, values, row_sum, W
 
 
-def _coherence_python(wij, mode, thr):
+def _coherence_python_worker(
+    args: tuple[Sequence[Sequence[float]], int, str, float],
+) -> tuple[int, list[float], list[float], CoherenceMatrixSparse]:
+    rows, start, mode, thr = args
+    values: list[float] = []
+    row_sum: list[float] = []
+    sparse: list[tuple[int, int, float]] = []
+    dense_mode = mode == "dense"
+
+    for offset, row in enumerate(rows):
+        i = start + offset
+        total = 0.0
+        for j, w in enumerate(row):
+            total += w
+            if i != j:
+                values.append(w)
+                if not dense_mode and w >= thr:
+                    sparse.append((i, j, w))
+        row_sum.append(total)
+
+    return start, values, row_sum, sparse
+
+
+def _coherence_python(
+    wij: Sequence[Sequence[float]],
+    mode: str,
+    thr: float,
+    n_jobs: int | None = 1,
+) -> tuple[int, list[float], list[float], CoherenceMatrixPayload]:
     """Aggregate coherence weights using pure Python loops."""
 
     n = len(wij)
     values: list[float] = []
     row_sum = [0.0] * n
-    if mode == "dense":
-        W = [row[:] for row in wij]
-        for i in range(n):
-            for j in range(n):
-                w = W[i][j]
-                if i != j:
-                    values.append(w)
-                row_sum[i] += w
+
+    if n_jobs is not None:
+        try:
+            max_workers = int(n_jobs)
+        except (TypeError, ValueError):
+            max_workers = 1
     else:
-        W: list[tuple[int, int, float]] = []
-        for i in range(n):
-            row_i = wij[i]
-            for j in range(n):
-                w = row_i[j]
-                if i != j:
-                    values.append(w)
-                    if w >= thr:
-                        W.append((i, j, w))
-                row_sum[i] += w
-    return n, values, row_sum, W
+        max_workers = 1
+
+    if max_workers <= 1:
+        if mode == "dense":
+            W: CoherenceMatrixDense = [list(row) for row in wij]
+            for i in range(n):
+                for j in range(n):
+                    w = W[i][j]
+                    if i != j:
+                        values.append(w)
+                    row_sum[i] += w
+        else:
+            W_sparse: CoherenceMatrixSparse = []
+            for i in range(n):
+                row_i = wij[i]
+                for j in range(n):
+                    w = row_i[j]
+                    if i != j:
+                        values.append(w)
+                        if w >= thr:
+                            W_sparse.append((i, j, w))
+                    row_sum[i] += w
+        return n, values, row_sum, W if mode == "dense" else W_sparse
+
+    approx_chunk = math.ceil(n / max_workers) if max_workers else None
+    chunk_size = resolve_chunk_size(
+        approx_chunk,
+        n,
+        minimum=1,
+    )
+    tasks = []
+    with ProcessPoolExecutor(max_workers=max_workers) as executor:
+        for start in range(0, n, chunk_size):
+            rows = wij[start : start + chunk_size]
+            tasks.append(
+                executor.submit(
+                    _coherence_python_worker,
+                    (tuple(tuple(row) for row in rows), start, mode, thr),
+                )
+            )
+        results = [task.result() for task in tasks]
 
+    results.sort(key=lambda item: item[0])
+    sparse_entries: list[tuple[int, int, float]] | None = (
+        [] if mode != "dense" else None
+    )
+    for start, chunk_values, chunk_row_sum, chunk_sparse in results:
+        values.extend(chunk_values)
+        for offset, total in enumerate(chunk_row_sum):
+            row_sum[start + offset] = total
+        if sparse_entries is not None:
+            sparse_entries.extend(chunk_sparse)
 
-def _finalize_wij(G, nodes, wij, mode, thr, scope, self_diag, np=None):
+    if mode == "dense":
+        W_dense: CoherenceMatrixDense = [list(row) for row in wij]
+        return n, values, row_sum, W_dense
+    sparse_result: CoherenceMatrixSparse = (
+        sparse_entries if sparse_entries is not None else []
+    )
+    return n, values, row_sum, sparse_result
+
+
+def _finalize_wij(
+    G: TNFRGraph,
+    nodes: Sequence[NodeId],
+    wij: FloatMatrix | Sequence[Sequence[float]],
+    mode: str,
+    thr: float,
+    scope: str,
+    self_diag: bool,
+    np: ModuleType | None = None,
+    *,
+    n_jobs: int = 1,
+) -> tuple[list[NodeId], CoherenceMatrixPayload]:
     """Finalize the coherence matrix ``wij`` and store results in history.
 
     When ``np`` is provided and ``wij`` is a NumPy array, the computation is
@@ -474,11 +701,11 @@ def _finalize_wij(G, nodes, wij, mode, thr, scope, self_diag, np=None):
     """
 
     use_np = np is not None and isinstance(wij, np.ndarray)
-    n, values, row_sum, W = (
-        _coherence_numpy(wij, mode, thr, np)
-        if use_np
-        else _coherence_python(wij, mode, thr)
-    )
+    if use_np:
+        assert np is not None
+        n, values, row_sum, W = _coherence_numpy(wij, mode, thr, np)
+    else:
+        n, values, row_sum, W = _coherence_python(wij, mode, thr, n_jobs=n_jobs)
 
     min_val, max_val, mean_val, Wi, count_val = _compute_stats(
         values, row_sum, n, self_diag, np if use_np else None
@@ -497,37 +724,58 @@ def _finalize_wij(G, nodes, wij, mode, thr, scope, self_diag, np=None):
     append_metric(hist, cfg.get("history_key", "W_sparse"), W)
     append_metric(hist, cfg.get("Wi_history_key", "W_i"), Wi)
     append_metric(hist, cfg.get("stats_history_key", "W_stats"), stats)
-    return nodes, W
+    return list(nodes), W
+
 
+def coherence_matrix(
+    G: TNFRGraph,
+    use_numpy: bool | None = None,
+    *,
+    n_jobs: int | None = None,
+) -> tuple[list[NodeId] | None, CoherenceMatrixPayload | None]:
+    """Compute the coherence weight matrix for ``G``.
+
+    Parameters
+    ----------
+    G:
+        Graph whose nodes encode the structural attributes.
+    use_numpy:
+        When ``True`` the vectorised NumPy implementation is forced. When
+        ``False`` the pure Python fallback is used. ``None`` selects NumPy
+        automatically when available.
+    n_jobs:
+        Maximum worker processes to use for the Python fallback. ``None`` or
+        values less than or equal to one preserve the serial behaviour.
+    """
 
-def coherence_matrix(G, use_numpy: bool | None = None):
     cfg = get_param(G, "COHERENCE")
     if not cfg.get("enabled", True):
         return None, None
 
-    node_to_index = ensure_node_index_map(G)
-    nodes = list(node_to_index.keys())
+    node_to_index: Mapping[NodeId, int] = ensure_node_index_map(G)
+    nodes: list[NodeId] = list(node_to_index.keys())
     n = len(nodes)
     if n == 0:
         return nodes, []
 
     # NumPy handling for optional vectorized operations
     np = get_numpy()
-    use_np = (
-        np is not None if use_numpy is None else (use_numpy and np is not None)
-    )
+    use_np = np is not None if use_numpy is None else (use_numpy and np is not None)
+
+    cfg_jobs = cfg.get("n_jobs")
+    parallel_jobs = n_jobs if n_jobs is not None else cfg_jobs
 
     # Precompute indices to avoid repeated list.index calls within loops
 
-    th_vals = collect_attr(G, nodes, ALIAS_THETA, 0.0, np=np if use_np else None)
+    th_vals = collect_theta_attr(G, nodes, 0.0, np=np if use_np else None)
     epi_vals = collect_attr(G, nodes, ALIAS_EPI, 0.0, np=np if use_np else None)
     vf_vals = collect_attr(G, nodes, ALIAS_VF, 0.0, np=np if use_np else None)
     si_vals = collect_attr(G, nodes, ALIAS_SI, 0.0, np=np if use_np else None)
-    si_vals = (
-        np.clip(si_vals, 0.0, 1.0)
-        if use_np
-        else [clamp01(v) for v in si_vals]
-    )
+    if use_np:
+        assert np is not None
+        si_vals = np.clip(si_vals, 0.0, 1.0)
+    else:
+        si_vals = [clamp01(v) for v in si_vals]
     epi_min, epi_max = min_max_range(epi_vals)
     vf_min, vf_max = min_max_range(vf_vals)
 
@@ -557,7 +805,8 @@ def coherence_matrix(G, use_numpy: bool | None = None):
         sin_vals=sin_vals,
     )
     if use_np:
-        wij = _wij_vectorized(
+        assert np is not None
+        wij_matrix = _wij_vectorized(
             G,
             nodes,
             inputs,
@@ -576,7 +825,8 @@ def coherence_matrix(G, use_numpy: bool | None = None):
                 j = node_to_index[v]
                 adj[i, j] = True
                 adj[j, i] = True
-            wij = np.where(adj, wij, 0.0)
+            wij_matrix = cast(FloatMatrix, np.where(adj, wij_matrix, 0.0))
+        wij: FloatMatrix | CoherenceMatrixDense = wij_matrix
     else:
         wij = _wij_loops(
             G,
@@ -590,14 +840,29 @@ def coherence_matrix(G, use_numpy: bool | None = None):
             vf_max,
             neighbors_only,
             self_diag,
+            n_jobs=parallel_jobs,
         )
 
-    return _finalize_wij(G, nodes, wij, mode, thr, scope, self_diag, np)
+    return _finalize_wij(
+        G,
+        nodes,
+        wij,
+        mode,
+        thr,
+        scope,
+        self_diag,
+        np,
+        n_jobs=parallel_jobs if not use_np else 1,
+    )
 
 
 def local_phase_sync_weighted(
-    G, n, nodes_order=None, W_row=None, node_to_index=None
-):
+    G: TNFRGraph,
+    n: NodeId,
+    nodes_order: Sequence[NodeId] | None = None,
+    W_row: PhaseSyncWeights | None = None,
+    node_to_index: Mapping[NodeId, int] | None = None,
+) -> float:
     """Compute local phase synchrony using explicit weights.
 
     ``nodes_order`` is the node ordering used to build the coherence matrix
@@ -621,27 +886,52 @@ def local_phase_sync_weighted(
     trig = get_trig_cache(G)
     cos_map, sin_map = trig.cos, trig.sin
 
-    if (
-        isinstance(W_row, list)
-        and W_row
-        and isinstance(W_row[0], (int, float))
-    ):
-        for w, nj in zip(W_row, nodes_order):
-            if nj == n:
-                continue
-            den += w
-            cos_j = cos_map.get(nj)
-            sin_j = sin_map.get(nj)
-            if cos_j is None or sin_j is None:
-                trig_j = compute_theta_trig(((nj, G.nodes[nj]),))
-                cos_j = trig_j.cos[nj]
-                sin_j = trig_j.sin[nj]
-            num += w * complex(cos_j, sin_j)
-    else:
-        for ii, jj, w in W_row:
-            if ii != i:
-                continue
-            nj = nodes_order[jj]
+    if isinstance(W_row, Sequence) and W_row:
+        first = W_row[0]
+        if isinstance(first, (int, float)):
+            row_vals = cast(Sequence[float], W_row)
+            for w, nj in zip(row_vals, nodes_order):
+                if nj == n:
+                    continue
+                den += w
+                cos_j = cos_map.get(nj)
+                sin_j = sin_map.get(nj)
+                if cos_j is None or sin_j is None:
+                    trig_j = compute_theta_trig(((nj, G.nodes[nj]),))
+                    cos_j = trig_j.cos[nj]
+                    sin_j = trig_j.sin[nj]
+                num += w * complex(cos_j, sin_j)
+            return abs(num / den) if den else 0.0
+
+        if (
+            isinstance(first, Sequence)
+            and len(first) == 3
+            and isinstance(first[0], int)
+            and isinstance(first[1], int)
+            and isinstance(first[2], (int, float))
+        ):
+            sparse_entries = cast(CoherenceMatrixSparse, W_row)
+            for ii, jj, w in sparse_entries:
+                if ii != i:
+                    continue
+                nj = nodes_order[jj]
+                if nj == n:
+                    continue
+                den += w
+                cos_j = cos_map.get(nj)
+                sin_j = sin_map.get(nj)
+                if cos_j is None or sin_j is None:
+                    trig_j = compute_theta_trig(((nj, G.nodes[nj]),))
+                    cos_j = trig_j.cos[nj]
+                    sin_j = trig_j.sin[nj]
+                num += w * complex(cos_j, sin_j)
+            return abs(num / den) if den else 0.0
+
+        dense_matrix = cast(CoherenceMatrixDense, W_row)
+        if i is None:
+            raise ValueError("node index resolution failed for dense weights")
+        row_vals = cast(Sequence[float], dense_matrix[i])
+        for w, nj in zip(row_vals, nodes_order):
             if nj == n:
                 continue
             den += w
@@ -652,11 +942,28 @@ def local_phase_sync_weighted(
                 cos_j = trig_j.cos[nj]
                 sin_j = trig_j.sin[nj]
             num += w * complex(cos_j, sin_j)
+        return abs(num / den) if den else 0.0
+
+    sparse_entries = cast(CoherenceMatrixSparse, W_row)
+    for ii, jj, w in sparse_entries:
+        if ii != i:
+            continue
+        nj = nodes_order[jj]
+        if nj == n:
+            continue
+        den += w
+        cos_j = cos_map.get(nj)
+        sin_j = sin_map.get(nj)
+        if cos_j is None or sin_j is None:
+            trig_j = compute_theta_trig(((nj, G.nodes[nj]),))
+            cos_j = trig_j.cos[nj]
+            sin_j = trig_j.sin[nj]
+        num += w * complex(cos_j, sin_j)
 
     return abs(num / den) if den else 0.0
 
 
-def local_phase_sync(G, n):
+def local_phase_sync(G: TNFRGraph, n: NodeId) -> float:
     """Compute unweighted local phase synchronization for node ``n``."""
     nodes, W = coherence_matrix(G)
     if nodes is None:
@@ -664,7 +971,7 @@ def local_phase_sync(G, n):
     return local_phase_sync_weighted(G, n, nodes_order=nodes, W_row=W)
 
 
-def _coherence_step(G, ctx: dict[str, Any] | None = None):
+def _coherence_step(G: TNFRGraph, ctx: dict[str, Any] | None = None) -> None:
     del ctx
 
     if not get_param(G, "COHERENCE").get("enabled", True):
@@ -672,7 +979,9 @@ def _coherence_step(G, ctx: dict[str, Any] | None = None):
     coherence_matrix(G)
 
 
-def register_coherence_callbacks(G) -> None:
+def register_coherence_callbacks(G: TNFRGraph) -> None:
+    """Attach coherence matrix maintenance to the ``AFTER_STEP`` event."""
+
     callback_manager.register_callback(
         G,
         event=CallbackEvent.AFTER_STEP.value,
@@ -687,18 +996,29 @@ def register_coherence_callbacks(G) -> None:
 
 
 def _record_metrics(
-    hist: dict[str, Any], *pairs: tuple[Any, str], evaluate: bool = False
+    hist: HistoryState,
+    *pairs: MetricRecord,
+    evaluate: bool = False,
 ) -> None:
-    """Generic recorder for metric values."""
+    """Record metric values for the trace history."""
 
-    for value, key in pairs:
-        append_metric(hist, key, value() if evaluate else value)
+    metrics = cast(MutableMapping[str, list[Any]], hist)
+    for payload, key in pairs:
+        if evaluate:
+            provider = cast(MetricProvider, payload)
+            append_metric(metrics, key, provider())
+        else:
+            append_metric(metrics, key, payload)
 
 
-def _update_coherence(G, hist) -> None:
+def _update_coherence(G: TNFRGraph, hist: HistoryState) -> None:
     """Update network coherence and related means."""
 
-    C, dnfr_mean, depi_mean = compute_coherence(G, return_means=True)
+    coherence_payload = cast(
+        tuple[CoherenceMetric, float, float],
+        compute_coherence(G, return_means=True),
+    )
+    C, dnfr_mean, depi_mean = coherence_payload
     _record_metrics(
         hist,
         (C, "C_steps"),
@@ -714,7 +1034,7 @@ def _update_coherence(G, hist) -> None:
         _record_metrics(hist, (wbar, "W_bar"))
 
 
-def _update_phase_sync(G, hist) -> None:
+def _update_phase_sync(G: TNFRGraph, hist: HistoryState) -> None:
     """Capture phase synchrony and Kuramoto order."""
 
     ps = phase_sync(G)
@@ -726,18 +1046,35 @@ def _update_phase_sync(G, hist) -> None:
     )
 
 
-def _update_sigma(G, hist) -> None:
+def _update_sigma(G: TNFRGraph, hist: HistoryState) -> None:
     """Record glyph load and associated Σ⃗ vector."""
 
-    gl = glyph_load(G, window=DEFAULT_GLYPH_LOAD_SPAN)
+    metrics = cast(MutableMapping[str, list[Any]], hist)
+    if "glyph_load_estab" in metrics:
+        raise ValueError(
+            "History payloads using 'glyph_load_estab' are no longer supported. "
+            "Rename the series to 'glyph_load_stabilizers' before loading the graph."
+        )
+    stabilizer_series = metrics.get(GLYPH_LOAD_STABILIZERS_KEY)
+
+    if stabilizer_series is None:
+        stabilizer_series = cast(
+            list[Any], metrics.setdefault(GLYPH_LOAD_STABILIZERS_KEY, [])
+        )
+    else:
+        stabilizer_series = cast(list[Any], stabilizer_series)
+
+    gl: GlyphLoadDistribution = glyph_load(G, window=DEFAULT_GLYPH_LOAD_SPAN)
+    stabilizers = float(gl.get("_stabilizers", 0.0))
+    disruptors = float(gl.get("_disruptors", 0.0))
     _record_metrics(
         hist,
-        (gl.get("_estabilizadores", 0.0), "glyph_load_estab"),
-        (gl.get("_disruptivos", 0.0), "glyph_load_disr"),
+        (stabilizers, GLYPH_LOAD_STABILIZERS_KEY),
+        (disruptors, "glyph_load_disr"),
     )
 
-    dist = {k: v for k, v in gl.items() if not k.startswith("_")}
-    sig = sigma_vector(dist)
+    dist: GlyphLoadDistribution = {k: v for k, v in gl.items() if not k.startswith("_")}
+    sig: SigmaVector = sigma_vector(dist)
     _record_metrics(
         hist,
         (sig.get("x", 0.0), "sense_sigma_x"),
@@ -747,51 +1084,341 @@ def _update_sigma(G, hist) -> None:
     )
 
 
-def _track_stability(G, hist, dt, eps_dnfr, eps_depi):
-    """Track per-node stability and derivative metrics."""
+def _stability_chunk_worker(args: StabilityChunkArgs) -> StabilityChunkResult:
+    """Compute stability aggregates for a chunk of nodes."""
 
-    stables = 0
-    total = max(1, G.number_of_nodes())
-    delta_si_sum = 0.0
-    delta_si_count = 0
+    (
+        dnfr_vals,
+        depi_vals,
+        si_curr_vals,
+        si_prev_vals,
+        vf_curr_vals,
+        vf_prev_vals,
+        dvf_prev_vals,
+        dt,
+        eps_dnfr,
+        eps_depi,
+    ) = args
+
+    inv_dt = (1.0 / dt) if dt else 0.0
+    stable = 0
+    delta_sum = 0.0
     B_sum = 0.0
-    B_count = 0
+    delta_vals: list[float] = []
+    dvf_dt_vals: list[float] = []
+    B_vals: list[float] = []
+
+    for idx in range(len(si_curr_vals)):
+        curr_si = float(si_curr_vals[idx])
+        prev_si_raw = si_prev_vals[idx]
+        prev_si = float(prev_si_raw) if prev_si_raw is not None else curr_si
+        delta = curr_si - prev_si
+        delta_vals.append(delta)
+        delta_sum += delta
+
+        curr_vf = float(vf_curr_vals[idx])
+        prev_vf_raw = vf_prev_vals[idx]
+        prev_vf = float(prev_vf_raw) if prev_vf_raw is not None else curr_vf
+        dvf_dt = (curr_vf - prev_vf) * inv_dt if dt else 0.0
+        prev_dvf_raw = dvf_prev_vals[idx]
+        prev_dvf = float(prev_dvf_raw) if prev_dvf_raw is not None else dvf_dt
+        B = (dvf_dt - prev_dvf) * inv_dt if dt else 0.0
+        dvf_dt_vals.append(dvf_dt)
+        B_vals.append(B)
+        B_sum += B
 
-    for _, nd in G.nodes(data=True):
         if (
-            abs(get_attr(nd, ALIAS_DNFR, 0.0)) <= eps_dnfr
-            and abs(get_attr(nd, ALIAS_DEPI, 0.0)) <= eps_depi
+            abs(float(dnfr_vals[idx])) <= eps_dnfr
+            and abs(float(depi_vals[idx])) <= eps_depi
         ):
-            stables += 1
-
-        Si_curr = get_attr(nd, ALIAS_SI, 0.0)
-        Si_prev = nd.get("_prev_Si", Si_curr)
-        dSi = Si_curr - Si_prev
-        nd["_prev_Si"] = Si_curr
-        set_attr(nd, ALIAS_DSI, dSi)
-        delta_si_sum += dSi
-        delta_si_count += 1
-
-        vf_curr = get_attr(nd, ALIAS_VF, 0.0)
-        vf_prev = nd.get("_prev_vf", vf_curr)
-        dvf_dt = (vf_curr - vf_prev) / dt
-        dvf_prev = nd.get("_prev_dvf", dvf_dt)
-        B = (dvf_dt - dvf_prev) / dt
-        nd["_prev_vf"] = vf_curr
-        nd["_prev_dvf"] = dvf_dt
-        set_attr(nd, ALIAS_DVF, dvf_dt)
-        set_attr(nd, ALIAS_D2VF, B)
-        B_sum += B
-        B_count += 1
-
-    hist["stable_frac"].append(stables / total)
-    hist["delta_Si"].append(
-        delta_si_sum / delta_si_count if delta_si_count else 0.0
+            stable += 1
+
+    chunk_len = len(si_curr_vals)
+    return (
+        stable,
+        chunk_len,
+        delta_sum,
+        B_sum,
+        delta_vals,
+        dvf_dt_vals,
+        B_vals,
     )
-    hist["B"].append(B_sum / B_count if B_count else 0.0)
 
 
-def _aggregate_si(G, hist):
+def _track_stability(
+    G: TNFRGraph,
+    hist: MutableMapping[str, Any],
+    dt: float,
+    eps_dnfr: float,
+    eps_depi: float,
+    *,
+    n_jobs: int | None = None,
+) -> None:
+    """Track per-node stability and derivative metrics."""
+
+    nodes: tuple[NodeId, ...] = tuple(G.nodes)
+    total_nodes = len(nodes)
+    if not total_nodes:
+        hist.setdefault("stable_frac", []).append(0.0)
+        hist.setdefault("delta_Si", []).append(0.0)
+        hist.setdefault("B", []).append(0.0)
+        return
+
+    np_mod = get_numpy()
+
+    dnfr_vals = collect_attr(G, nodes, ALIAS_DNFR, 0.0, np=np_mod)
+    depi_vals = collect_attr(G, nodes, ALIAS_DEPI, 0.0, np=np_mod)
+    si_curr_vals = collect_attr(G, nodes, ALIAS_SI, 0.0, np=np_mod)
+    vf_curr_vals = collect_attr(G, nodes, ALIAS_VF, 0.0, np=np_mod)
+
+    prev_si_data = [G.nodes[n].get("_prev_Si") for n in nodes]
+    prev_vf_data = [G.nodes[n].get("_prev_vf") for n in nodes]
+    prev_dvf_data = [G.nodes[n].get("_prev_dvf") for n in nodes]
+
+    inv_dt = (1.0 / dt) if dt else 0.0
+
+    if np_mod is not None:
+        np = np_mod
+        dnfr_arr = dnfr_vals
+        depi_arr = depi_vals
+        si_curr_arr = si_curr_vals
+        vf_curr_arr = vf_curr_vals
+
+        si_prev_arr = np.asarray(
+            [
+                (
+                    float(prev_si_data[idx])
+                    if prev_si_data[idx] is not None
+                    else float(si_curr_arr[idx])
+                )
+                for idx in range(total_nodes)
+            ],
+            dtype=float,
+        )
+        vf_prev_arr = np.asarray(
+            [
+                (
+                    float(prev_vf_data[idx])
+                    if prev_vf_data[idx] is not None
+                    else float(vf_curr_arr[idx])
+                )
+                for idx in range(total_nodes)
+            ],
+            dtype=float,
+        )
+
+        if dt:
+            dvf_dt_arr = (vf_curr_arr - vf_prev_arr) * inv_dt
+        else:
+            dvf_dt_arr = np.zeros_like(vf_curr_arr, dtype=float)
+
+        dvf_prev_arr = np.asarray(
+            [
+                (
+                    float(prev_dvf_data[idx])
+                    if prev_dvf_data[idx] is not None
+                    else float(dvf_dt_arr[idx])
+                )
+                for idx in range(total_nodes)
+            ],
+            dtype=float,
+        )
+
+        if dt:
+            B_arr = (dvf_dt_arr - dvf_prev_arr) * inv_dt
+        else:
+            B_arr = np.zeros_like(dvf_dt_arr, dtype=float)
+
+        stable_mask = (np.abs(dnfr_arr) <= eps_dnfr) & (np.abs(depi_arr) <= eps_depi)
+        stable_frac = float(stable_mask.mean()) if total_nodes else 0.0
+
+        delta_si_arr = si_curr_arr - si_prev_arr
+        delta_si_mean = float(delta_si_arr.mean()) if total_nodes else 0.0
+        B_mean = float(B_arr.mean()) if total_nodes else 0.0
+
+        hist.setdefault("stable_frac", []).append(stable_frac)
+        hist.setdefault("delta_Si", []).append(delta_si_mean)
+        hist.setdefault("B", []).append(B_mean)
+
+        for idx, node in enumerate(nodes):
+            nd = G.nodes[node]
+            curr_si = float(si_curr_arr[idx])
+            delta_val = float(delta_si_arr[idx])
+            nd["_prev_Si"] = curr_si
+            set_attr(nd, ALIAS_DSI, delta_val)
+
+            curr_vf = float(vf_curr_arr[idx])
+            nd["_prev_vf"] = curr_vf
+
+            dvf_dt_val = float(dvf_dt_arr[idx])
+            nd["_prev_dvf"] = dvf_dt_val
+            set_attr(nd, ALIAS_DVF, dvf_dt_val)
+            set_attr(nd, ALIAS_D2VF, float(B_arr[idx]))
+
+        return
+
+    # NumPy not available: optionally parallel fallback or sequential computation.
+    dnfr_list = list(dnfr_vals)
+    depi_list = list(depi_vals)
+    si_curr_list = list(si_curr_vals)
+    vf_curr_list = list(vf_curr_vals)
+
+    if n_jobs and n_jobs > 1:
+        approx_chunk = math.ceil(total_nodes / n_jobs) if n_jobs else None
+        chunk_size = resolve_chunk_size(
+            approx_chunk,
+            total_nodes,
+            minimum=1,
+        )
+        chunk_results: list[
+            tuple[
+                int,
+                tuple[int, int, float, float, list[float], list[float], list[float]],
+            ]
+        ] = []
+        with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+            futures: list[tuple[int, Any]] = []
+            for start in range(0, total_nodes, chunk_size):
+                end = min(start + chunk_size, total_nodes)
+                chunk_args = (
+                    dnfr_list[start:end],
+                    depi_list[start:end],
+                    si_curr_list[start:end],
+                    prev_si_data[start:end],
+                    vf_curr_list[start:end],
+                    prev_vf_data[start:end],
+                    prev_dvf_data[start:end],
+                    dt,
+                    eps_dnfr,
+                    eps_depi,
+                )
+                futures.append(
+                    (start, executor.submit(_stability_chunk_worker, chunk_args))
+                )
+
+            for start, fut in futures:
+                chunk_results.append((start, fut.result()))
+
+        chunk_results.sort(key=lambda item: item[0])
+
+        stable_total = 0
+        delta_sum = 0.0
+        B_sum = 0.0
+        delta_vals_all: list[float] = []
+        dvf_dt_all: list[float] = []
+        B_vals_all: list[float] = []
+
+        for _, result in chunk_results:
+            (
+                stable_count,
+                chunk_len,
+                chunk_delta_sum,
+                chunk_B_sum,
+                delta_vals,
+                dvf_vals,
+                B_vals,
+            ) = result
+            stable_total += stable_count
+            delta_sum += chunk_delta_sum
+            B_sum += chunk_B_sum
+            delta_vals_all.extend(delta_vals)
+            dvf_dt_all.extend(dvf_vals)
+            B_vals_all.extend(B_vals)
+
+        total = len(delta_vals_all)
+        stable_frac = stable_total / total if total else 0.0
+        delta_si_mean = delta_sum / total if total else 0.0
+        B_mean = B_sum / total if total else 0.0
+
+    else:
+        stable_total = 0
+        delta_sum = 0.0
+        B_sum = 0.0
+        delta_vals_all = []
+        dvf_dt_all = []
+        B_vals_all = []
+
+        for idx in range(total_nodes):
+            curr_si = float(si_curr_list[idx])
+            prev_si_raw = prev_si_data[idx]
+            prev_si = float(prev_si_raw) if prev_si_raw is not None else curr_si
+            delta = curr_si - prev_si
+            delta_vals_all.append(delta)
+            delta_sum += delta
+
+            curr_vf = float(vf_curr_list[idx])
+            prev_vf_raw = prev_vf_data[idx]
+            prev_vf = float(prev_vf_raw) if prev_vf_raw is not None else curr_vf
+            dvf_dt_val = (curr_vf - prev_vf) * inv_dt if dt else 0.0
+            prev_dvf_raw = prev_dvf_data[idx]
+            prev_dvf = float(prev_dvf_raw) if prev_dvf_raw is not None else dvf_dt_val
+            B_val = (dvf_dt_val - prev_dvf) * inv_dt if dt else 0.0
+            dvf_dt_all.append(dvf_dt_val)
+            B_vals_all.append(B_val)
+            B_sum += B_val
+
+            if (
+                abs(float(dnfr_list[idx])) <= eps_dnfr
+                and abs(float(depi_list[idx])) <= eps_depi
+            ):
+                stable_total += 1
+
+        total = len(delta_vals_all)
+        stable_frac = stable_total / total if total else 0.0
+        delta_si_mean = delta_sum / total if total else 0.0
+        B_mean = B_sum / total if total else 0.0
+
+    hist.setdefault("stable_frac", []).append(stable_frac)
+    hist.setdefault("delta_Si", []).append(delta_si_mean)
+    hist.setdefault("B", []).append(B_mean)
+
+    for idx, node in enumerate(nodes):
+        nd = G.nodes[node]
+        curr_si = float(si_curr_list[idx])
+        delta_val = float(delta_vals_all[idx])
+        nd["_prev_Si"] = curr_si
+        set_attr(nd, ALIAS_DSI, delta_val)
+
+        curr_vf = float(vf_curr_list[idx])
+        nd["_prev_vf"] = curr_vf
+
+        dvf_dt_val = float(dvf_dt_all[idx])
+        nd["_prev_dvf"] = dvf_dt_val
+        set_attr(nd, ALIAS_DVF, dvf_dt_val)
+        set_attr(nd, ALIAS_D2VF, float(B_vals_all[idx]))
+
+
+def _si_chunk_stats(
+    values: Sequence[float], si_hi: float, si_lo: float
+) -> tuple[float, int, int, int]:
+    """Compute partial Si aggregates for ``values``.
+
+    The helper keeps the logic shared between the sequential and parallel
+    fallbacks when NumPy is unavailable.
+    """
+
+    total = 0.0
+    count = 0
+    hi_count = 0
+    lo_count = 0
+    for s in values:
+        if math.isnan(s):
+            continue
+        total += s
+        count += 1
+        if s >= si_hi:
+            hi_count += 1
+        if s <= si_lo:
+            lo_count += 1
+    return total, count, hi_count, lo_count
+
+
+def _aggregate_si(
+    G: TNFRGraph,
+    hist: MutableMapping[str, list[float]],
+    *,
+    n_jobs: int | None = None,
+) -> None:
     """Aggregate Si statistics across nodes."""
 
     try:
@@ -800,27 +1427,69 @@ def _aggregate_si(G, hist):
         si_hi = float(thr_sel.get("si_hi", thr_def.get("hi", 0.66)))
         si_lo = float(thr_sel.get("si_lo", thr_def.get("lo", 0.33)))
 
-        sis = [
-            s
-            for _, nd in G.nodes(data=True)
-            if not math.isnan(s := get_attr(nd, ALIAS_SI, float("nan")))
-        ]
+        node_ids = list(G.nodes)
+        if not node_ids:
+            hist["Si_mean"].append(0.0)
+            hist["Si_hi_frac"].append(0.0)
+            hist["Si_lo_frac"].append(0.0)
+            return
+
+        sis = []
+        for node in node_ids:
+            raw = get_attr(
+                G.nodes[node],
+                ALIAS_SI,
+                None,
+                conv=lambda value: value,  # Preserve NaN sentinels
+            )
+            try:
+                sis.append(float(raw) if raw is not None else math.nan)
+            except (TypeError, ValueError):
+                sis.append(math.nan)
+
+        np_mod = get_numpy()
+        if np_mod is not None:
+            sis_array = np_mod.asarray(sis, dtype=float)
+            valid = sis_array[~np_mod.isnan(sis_array)]
+            n = int(valid.size)
+            if n:
+                hist["Si_mean"].append(float(valid.mean()))
+                hi_frac = np_mod.count_nonzero(valid >= si_hi) / n
+                lo_frac = np_mod.count_nonzero(valid <= si_lo) / n
+                hist["Si_hi_frac"].append(float(hi_frac))
+                hist["Si_lo_frac"].append(float(lo_frac))
+            else:
+                hist["Si_mean"].append(0.0)
+                hist["Si_hi_frac"].append(0.0)
+                hist["Si_lo_frac"].append(0.0)
+            return
+
+        if n_jobs is not None and n_jobs > 1:
+            approx_chunk = math.ceil(len(sis) / n_jobs) if n_jobs else None
+            chunk_size = resolve_chunk_size(
+                approx_chunk,
+                len(sis),
+                minimum=1,
+            )
+            futures = []
+            with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+                for idx in range(0, len(sis), chunk_size):
+                    chunk = sis[idx : idx + chunk_size]
+                    futures.append(
+                        executor.submit(_si_chunk_stats, chunk, si_hi, si_lo)
+                    )
+            totals = [future.result() for future in futures]
+            total = sum(part[0] for part in totals)
+            count = sum(part[1] for part in totals)
+            hi_count = sum(part[2] for part in totals)
+            lo_count = sum(part[3] for part in totals)
+        else:
+            total, count, hi_count, lo_count = _si_chunk_stats(sis, si_hi, si_lo)
 
-        total = 0.0
-        hi_count = 0
-        lo_count = 0
-        for s in sis:
-            total += s
-            if s >= si_hi:
-                hi_count += 1
-            if s <= si_lo:
-                lo_count += 1
-
-        n = len(sis)
-        if n:
-            hist["Si_mean"].append(total / n)
-            hist["Si_hi_frac"].append(hi_count / n)
-            hist["Si_lo_frac"].append(lo_count / n)
+        if count:
+            hist["Si_mean"].append(total / count)
+            hist["Si_hi_frac"].append(hi_count / count)
+            hist["Si_lo_frac"].append(lo_count / count)
         else:
             hist["Si_mean"].append(0.0)
             hist["Si_hi_frac"].append(0.0)