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

tnfr/metrics/diagnosis.py

@@ -2,47 +2,305 @@
 
 from __future__ import annotations
 
-from statistics import fmean, StatisticsError
+import math
+from collections import deque
+from collections.abc import Mapping, MutableMapping, Sequence
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+from functools import partial
 from operator import ge, le
-from typing import Any
+from statistics import StatisticsError, fmean
+from typing import Any, Callable, Iterable, cast
 
+from ..alias import get_attr
+from ..callback_utils import CallbackEvent, callback_manager
 from ..constants import (
+    STATE_DISSONANT,
+    STATE_STABLE,
+    STATE_TRANSITION,
     VF_KEY,
-    get_aliases,
     get_param,
+    normalise_state_token,
 )
-from ..callback_utils import CallbackEvent, callback_manager
-from ..glyph_history import ensure_history, append_metric
-from ..alias import get_attr
-from ..helpers.numeric import clamp01, similarity_abs
-from .common import compute_dnfr_accel_max, min_max_range, normalize_dnfr
-from .coherence import (
-    local_phase_sync,
-    local_phase_sync_weighted,
+from ..constants.aliases import ALIAS_DNFR, ALIAS_EPI, ALIAS_SI, ALIAS_VF
+from ..glyph_history import append_metric, ensure_history
+from ..utils import clamp01, resolve_chunk_size, similarity_abs
+from ..types import (
+    DiagnosisNodeData,
+    DiagnosisPayload,
+    DiagnosisPayloadChunk,
+    DiagnosisResult,
+    DiagnosisResultList,
+    DiagnosisSharedState,
+    NodeId,
+    TNFRGraph,
 )
-
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_VF = get_aliases("VF")
-ALIAS_SI = get_aliases("SI")
-
-def _symmetry_index(
-    G, n, epi_min: float | None = None, epi_max: float | None = None
-):
-    """Compute the symmetry index for node ``n`` based on EPI values."""
-    nd = G.nodes[n]
-    epi_i = get_attr(nd, ALIAS_EPI, 0.0)
-    vec = G.neighbors(n)
-    try:
-        epi_bar = fmean(get_attr(G.nodes[v], ALIAS_EPI, epi_i) for v in vec)
-    except StatisticsError:
-        return 1.0
-    if epi_min is None or epi_max is None:
-        epi_iter = (get_attr(G.nodes[v], ALIAS_EPI, 0.0) for v in G.nodes())
-        epi_min, epi_max = min_max_range(epi_iter, default=(0.0, 1.0))
-    return similarity_abs(epi_i, epi_bar, epi_min, epi_max)
-
-
-def _state_from_thresholds(Rloc, dnfr_n, cfg):
+from ..utils import get_numpy
+from .coherence import CoherenceMatrixPayload, coherence_matrix, local_phase_sync
+from .common import (
+    _coerce_jobs,
+    compute_dnfr_accel_max,
+    min_max_range,
+    normalize_dnfr,
+)
+from .trig_cache import compute_theta_trig, get_trig_cache
+
+CoherenceSeries = Sequence[CoherenceMatrixPayload | None]
+CoherenceHistory = Mapping[str, CoherenceSeries]
+def _coherence_matrix_to_numpy(
+    weight_matrix: Any,
+    size: int,
+    np_mod: Any,
+) -> Any:
+    """Convert stored coherence weights into a dense NumPy array."""
+
+    if weight_matrix is None or np_mod is None or size <= 0:
+        return None
+
+    ndarray_type: Any = getattr(np_mod, "ndarray", tuple())
+    if ndarray_type and isinstance(weight_matrix, ndarray_type):
+        matrix = weight_matrix.astype(float, copy=True)
+    elif isinstance(weight_matrix, (list, tuple)):
+        weight_seq = list(weight_matrix)
+        if not weight_seq:
+            matrix = np_mod.zeros((size, size), dtype=float)
+        else:
+            first = weight_seq[0]
+            if isinstance(first, (list, tuple)) and len(first) == size:
+                matrix = np_mod.array(weight_seq, dtype=float)
+            elif (
+                isinstance(first, (list, tuple))
+                and len(first) == 3
+                and not isinstance(first[0], (list, tuple))
+            ):
+                matrix = np_mod.zeros((size, size), dtype=float)
+                for i, j, weight in weight_seq:
+                    matrix[int(i), int(j)] = float(weight)
+            else:
+                return None
+    else:
+        return None
+
+    if matrix.shape != (size, size):
+        return None
+    np_mod.fill_diagonal(matrix, 0.0)
+    return matrix
+
+
+def _weighted_phase_sync_vectorized(
+    matrix: Any,
+    cos_vals: Any,
+    sin_vals: Any,
+    np_mod: Any,
+) -> Any:
+    """Vectorised computation of weighted local phase synchrony."""
+
+    denom = np_mod.sum(matrix, axis=1)
+    if np_mod.all(denom == 0.0):
+        return np_mod.zeros_like(denom, dtype=float)
+    real = matrix @ cos_vals
+    imag = matrix @ sin_vals
+    magnitude = np_mod.hypot(real, imag)
+    safe_denom = np_mod.where(denom == 0.0, 1.0, denom)
+    return magnitude / safe_denom
+
+
+def _unweighted_phase_sync_vectorized(
+    nodes: Sequence[Any],
+    neighbors_map: Mapping[Any, tuple[Any, ...]],
+    cos_arr: Any,
+    sin_arr: Any,
+    index_map: Mapping[Any, int],
+    np_mod: Any,
+) -> list[float]:
+    """Compute unweighted phase synchrony using NumPy helpers."""
+
+    results: list[float] = []
+    for node in nodes:
+        neighbors = neighbors_map.get(node, ())
+        if not neighbors:
+            results.append(0.0)
+            continue
+        indices = [index_map[nb] for nb in neighbors if nb in index_map]
+        if not indices:
+            results.append(0.0)
+            continue
+        cos_vals = np_mod.take(cos_arr, indices)
+        sin_vals = np_mod.take(sin_arr, indices)
+        real = np_mod.sum(cos_vals)
+        imag = np_mod.sum(sin_vals)
+        denom = float(len(indices))
+        if denom == 0.0:
+            results.append(0.0)
+        else:
+            results.append(float(np_mod.hypot(real, imag) / denom))
+    return results
+
+
+def _neighbor_means_vectorized(
+    nodes: Sequence[Any],
+    neighbors_map: Mapping[Any, tuple[Any, ...]],
+    epi_arr: Any,
+    index_map: Mapping[Any, int],
+    np_mod: Any,
+) -> list[float | None]:
+    """Vectorized helper to compute neighbour EPI means."""
+
+    results: list[float | None] = []
+    for node in nodes:
+        neighbors = neighbors_map.get(node, ())
+        if not neighbors:
+            results.append(None)
+            continue
+        indices = [index_map[nb] for nb in neighbors if nb in index_map]
+        if not indices:
+            results.append(None)
+            continue
+        values = np_mod.take(epi_arr, indices)
+        results.append(float(np_mod.mean(values)))
+    return results
+
+
+@dataclass(frozen=True)
+class RLocalWorkerArgs:
+    """Typed payload passed to :func:`_rlocal_worker`."""
+
+    chunk: Sequence[Any]
+    coherence_nodes: Sequence[Any]
+    weight_matrix: Any
+    weight_index: Mapping[Any, int]
+    neighbors_map: Mapping[Any, tuple[Any, ...]]
+    cos_map: Mapping[Any, float]
+    sin_map: Mapping[Any, float]
+
+
+@dataclass(frozen=True)
+class NeighborMeanWorkerArgs:
+    """Typed payload passed to :func:`_neighbor_mean_worker`."""
+
+    chunk: Sequence[Any]
+    neighbors_map: Mapping[Any, tuple[Any, ...]]
+    epi_map: Mapping[Any, float]
+
+
+def _rlocal_worker(args: RLocalWorkerArgs) -> list[float]:
+    """Worker used to compute ``R_local`` in Python fallbacks."""
+
+    results: list[float] = []
+    for node in args.chunk:
+        if args.coherence_nodes and args.weight_matrix is not None:
+            idx = args.weight_index.get(node)
+            if idx is None:
+                rloc = 0.0
+            else:
+                rloc = _weighted_phase_sync_from_matrix(
+                    idx,
+                    node,
+                    args.coherence_nodes,
+                    args.weight_matrix,
+                    args.cos_map,
+                    args.sin_map,
+                )
+        else:
+            rloc = _local_phase_sync_unweighted(
+                args.neighbors_map.get(node, ()),
+                args.cos_map,
+                args.sin_map,
+            )
+        results.append(float(rloc))
+    return results
+
+
+def _neighbor_mean_worker(args: NeighborMeanWorkerArgs) -> list[float | None]:
+    """Worker used to compute neighbour EPI means in Python mode."""
+
+    results: list[float | None] = []
+    for node in args.chunk:
+        neighbors = args.neighbors_map.get(node, ())
+        if not neighbors:
+            results.append(None)
+            continue
+        try:
+            results.append(fmean(args.epi_map[nb] for nb in neighbors))
+        except StatisticsError:
+            results.append(None)
+    return results
+
+
+def _weighted_phase_sync_from_matrix(
+    node_index: int,
+    node: Any,
+    nodes_order: Sequence[Any],
+    matrix: Any,
+    cos_map: Mapping[Any, float],
+    sin_map: Mapping[Any, float],
+) -> float:
+    """Compute weighted phase synchrony using a cached matrix."""
+
+    if matrix is None or not nodes_order:
+        return 0.0
+
+    num = 0.0 + 0.0j
+    den = 0.0
+
+    if isinstance(matrix, list) and matrix and isinstance(matrix[0], list):
+        row = matrix[node_index]
+        for weight, neighbor in zip(row, nodes_order):
+            if neighbor == node:
+                continue
+            w = float(weight)
+            if w == 0.0:
+                continue
+            cos_j = cos_map.get(neighbor)
+            sin_j = sin_map.get(neighbor)
+            if cos_j is None or sin_j is None:
+                continue
+            den += w
+            num += w * complex(cos_j, sin_j)
+    else:
+        for ii, jj, weight in matrix:
+            if ii != node_index:
+                continue
+            neighbor = nodes_order[jj]
+            if neighbor == node:
+                continue
+            w = float(weight)
+            if w == 0.0:
+                continue
+            cos_j = cos_map.get(neighbor)
+            sin_j = sin_map.get(neighbor)
+            if cos_j is None or sin_j is None:
+                continue
+            den += w
+            num += w * complex(cos_j, sin_j)
+
+    return abs(num / den) if den else 0.0
+
+
+def _local_phase_sync_unweighted(
+    neighbors: Iterable[Any],
+    cos_map: Mapping[Any, float],
+    sin_map: Mapping[Any, float],
+) -> float:
+    """Fallback unweighted phase synchrony based on neighbours."""
+
+    num = 0.0 + 0.0j
+    den = 0.0
+    for neighbor in neighbors:
+        cos_j = cos_map.get(neighbor)
+        sin_j = sin_map.get(neighbor)
+        if cos_j is None or sin_j is None:
+            continue
+        num += complex(cos_j, sin_j)
+        den += 1.0
+    return abs(num / den) if den else 0.0
+
+
+def _state_from_thresholds(
+    Rloc: float,
+    dnfr_n: float,
+    cfg: Mapping[str, Any],
+) -> str:
     stb = cfg.get("stable", {"Rloc_hi": 0.8, "dnfr_lo": 0.2, "persist": 3})
     dsr = cfg.get("dissonance", {"Rloc_lo": 0.4, "dnfr_hi": 0.5, "persist": 3})
 
@@ -51,29 +309,28 @@ def _state_from_thresholds(Rloc, dnfr_n, cfg):
         "dnfr": (dnfr_n, float(stb["dnfr_lo"]), le),
     }
     if all(comp(val, thr) for val, thr, comp in stable_checks.values()):
-        return "estable"
+        return STATE_STABLE
 
     dissonant_checks = {
         "Rloc": (Rloc, float(dsr["Rloc_lo"]), le),
         "dnfr": (dnfr_n, float(dsr["dnfr_hi"]), ge),
     }
     if all(comp(val, thr) for val, thr, comp in dissonant_checks.values()):
-        return "disonante"
+        return STATE_DISSONANT
 
-    return "transicion"
+    return STATE_TRANSITION
 
 
-def _recommendation(state, cfg):
+def _recommendation(state: str, cfg: Mapping[str, Any]) -> list[Any]:
     adv = cfg.get("advice", {})
-    key = {
-        "estable": "stable",
-        "transicion": "transition",
-        "disonante": "dissonant",
-    }[state]
-    return list(adv.get(key, []))
+    canonical_state = normalise_state_token(state)
+    return list(adv.get(canonical_state, []))
 
 
-def _get_last_weights(G, hist):
+def _get_last_weights(
+    G: TNFRGraph,
+    hist: CoherenceHistory,
+) -> tuple[CoherenceMatrixPayload | None, CoherenceMatrixPayload | None]:
     """Return last Wi and Wm matrices from history."""
     CfgW = get_param(G, "COHERENCE")
     Wkey = CfgW.get("Wi_history_key", "W_i")
@@ -86,105 +343,440 @@ def _get_last_weights(G, hist):
 
 
 def _node_diagnostics(
-    G,
-    n,
-    i,
-    nodes,
-    node_to_index,
-    Wi_last,
-    Wm_last,
-    epi_min,
-    epi_max,
-    dnfr_max,
-    dcfg,
-):
-    nd = G.nodes[n]
-    Si = clamp01(get_attr(nd, ALIAS_SI, 0.0))
-    EPI = get_attr(nd, ALIAS_EPI, 0.0)
-    vf = get_attr(nd, ALIAS_VF, 0.0)
-    dnfr_n = normalize_dnfr(nd, dnfr_max)
-
-    if Wm_last is not None:
-        if Wm_last and isinstance(Wm_last[0], list):
-            row = Wm_last[i]
-        else:
-            row = Wm_last
-        Rloc = local_phase_sync_weighted(
-            G, n, nodes_order=nodes, W_row=row, node_to_index=node_to_index
+    node_data: DiagnosisNodeData,
+    shared: DiagnosisSharedState,
+) -> DiagnosisResult:
+    """Compute diagnostic payload for a single node."""
+
+    dcfg = shared["dcfg"]
+    compute_symmetry = shared["compute_symmetry"]
+    epi_min = shared["epi_min"]
+    epi_max = shared["epi_max"]
+
+    node = node_data["node"]
+    Si = clamp01(float(node_data["Si"]))
+    EPI = float(node_data["EPI"])
+    vf = float(node_data["VF"])
+    dnfr_n = clamp01(float(node_data["dnfr_norm"]))
+    Rloc = float(node_data["R_local"])
+
+    if compute_symmetry:
+        epi_bar = node_data.get("neighbor_epi_mean")
+        symm = (
+            1.0 if epi_bar is None else similarity_abs(EPI, epi_bar, epi_min, epi_max)
         )
     else:
-        Rloc = local_phase_sync(G, n)
+        symm = None
 
-    symm = (
-        _symmetry_index(G, n, epi_min=epi_min, epi_max=epi_max)
-        if dcfg.get("compute_symmetry", True)
-        else None
-    )
     state = _state_from_thresholds(Rloc, dnfr_n, dcfg)
+    canonical_state = normalise_state_token(state)
 
     alerts = []
-    if state == "disonante" and dnfr_n >= float(
-        dcfg.get("dissonance", {}).get("dnfr_hi", 0.5)
-    ):
+    if canonical_state == STATE_DISSONANT and dnfr_n >= shared["dissonance_hi"]:
         alerts.append("high structural tension")
 
-    advice = _recommendation(state, dcfg)
+    advice = _recommendation(canonical_state, dcfg)
 
-    return {
-        "node": n,
+    payload: DiagnosisPayload = {
+        "node": node,
         "Si": Si,
         "EPI": EPI,
         VF_KEY: vf,
         "dnfr_norm": dnfr_n,
-        "W_i": (Wi_last[i] if (Wi_last and i < len(Wi_last)) else None),
+        "W_i": node_data.get("W_i"),
         "R_local": Rloc,
         "symmetry": symm,
-        "state": state,
+        "state": canonical_state,
         "advice": advice,
         "alerts": alerts,
     }
 
+    return node, payload
+
+
+def _diagnosis_worker_chunk(
+    chunk: DiagnosisPayloadChunk,
+    shared: DiagnosisSharedState,
+) -> DiagnosisResultList:
+    """Evaluate diagnostics for a chunk of nodes."""
+
+    return [_node_diagnostics(item, shared) for item in chunk]
 
-def _diagnosis_step(G, ctx: dict[str, Any] | None = None):
+
+def _diagnosis_step(
+    G: TNFRGraph,
+    ctx: DiagnosisSharedState | None = None,
+    *,
+    n_jobs: int | None = None,
+) -> None:
     del ctx
 
+    if n_jobs is None:
+        n_jobs = _coerce_jobs(G.graph.get("DIAGNOSIS_N_JOBS"))
+    else:
+        n_jobs = _coerce_jobs(n_jobs)
+
     dcfg = get_param(G, "DIAGNOSIS")
     if not dcfg.get("enabled", True):
         return
 
     hist = ensure_history(G)
+    coherence_hist = cast(CoherenceHistory, hist)
     key = dcfg.get("history_key", "nodal_diag")
 
+    existing_diag_history = hist.get(key, [])
+    if isinstance(existing_diag_history, deque):
+        snapshots = list(existing_diag_history)
+    elif isinstance(existing_diag_history, list):
+        snapshots = existing_diag_history
+    else:
+        snapshots = []
+
+    for snapshot in snapshots:
+        if not isinstance(snapshot, Mapping):
+            continue
+        for node, payload in snapshot.items():
+            if not isinstance(payload, Mapping):
+                continue
+            state_value = payload.get("state")
+            if not isinstance(state_value, str):
+                continue
+            canonical = normalise_state_token(state_value)
+            if canonical == state_value:
+                continue
+            if isinstance(payload, MutableMapping):
+                payload["state"] = canonical
+            elif isinstance(snapshot, MutableMapping):
+                new_payload = dict(payload)
+                new_payload["state"] = canonical
+                snapshot[node] = new_payload
+
     norms = compute_dnfr_accel_max(G)
     G.graph["_sel_norms"] = norms
     dnfr_max = float(norms.get("dnfr_max", 1.0)) or 1.0
-    epi_iter = (get_attr(nd, ALIAS_EPI, 0.0) for _, nd in G.nodes(data=True))
-    epi_min, epi_max = min_max_range(epi_iter, default=(0.0, 1.0))
-
-    Wi_last, Wm_last = _get_last_weights(G, hist)
-
-    nodes = list(G.nodes())
-    node_to_index = {v: i for i, v in enumerate(nodes)}
-    diag = {}
-    for i, n in enumerate(nodes):
-        diag[n] = _node_diagnostics(
-            G,
-            n,
-            i,
-            nodes,
-            node_to_index,
-            Wi_last,
-            Wm_last,
-            epi_min,
-            epi_max,
-            dnfr_max,
-            dcfg,
+
+    nodes_data: list[tuple[NodeId, dict[str, Any]]] = list(G.nodes(data=True))
+    nodes: list[NodeId] = [n for n, _ in nodes_data]
+
+    Wi_last, Wm_last = _get_last_weights(G, coherence_hist)
+
+    np_mod = get_numpy()
+    supports_vector = bool(
+        np_mod is not None
+        and all(
+            hasattr(np_mod, attr)
+            for attr in (
+                "fromiter",
+                "clip",
+                "abs",
+                "maximum",
+                "minimum",
+                "array",
+                "zeros",
+                "zeros_like",
+                "sum",
+                "hypot",
+                "where",
+                "take",
+                "mean",
+                "fill_diagonal",
+                "all",
+            )
+        )
+    )
+
+    if not nodes:
+        append_metric(hist, key, {})
+        return
+
+    rloc_values: list[float]
+
+    if supports_vector:
+        epi_arr = np_mod.fromiter(
+            (cast(float, get_attr(nd, ALIAS_EPI, 0.0)) for _, nd in nodes_data),
+            dtype=float,
+            count=len(nodes_data),
+        )
+        epi_min = float(np_mod.min(epi_arr))
+        epi_max = float(np_mod.max(epi_arr))
+        epi_vals = epi_arr.tolist()
+
+        si_arr = np_mod.clip(
+            np_mod.fromiter(
+                (cast(float, get_attr(nd, ALIAS_SI, 0.0)) for _, nd in nodes_data),
+                dtype=float,
+                count=len(nodes_data),
+            ),
+            0.0,
+            1.0,
         )
+        si_vals = si_arr.tolist()
+
+        vf_arr = np_mod.fromiter(
+            (cast(float, get_attr(nd, ALIAS_VF, 0.0)) for _, nd in nodes_data),
+            dtype=float,
+            count=len(nodes_data),
+        )
+        vf_vals = vf_arr.tolist()
+
+        if dnfr_max > 0:
+            dnfr_arr = np_mod.clip(
+                np_mod.fromiter(
+                    (
+                        abs(cast(float, get_attr(nd, ALIAS_DNFR, 0.0)))
+                        for _, nd in nodes_data
+                    ),
+                    dtype=float,
+                    count=len(nodes_data),
+                )
+                / dnfr_max,
+                0.0,
+                1.0,
+            )
+            dnfr_norms = dnfr_arr.tolist()
+        else:
+            dnfr_norms = [0.0] * len(nodes)
+    else:
+        epi_vals = [cast(float, get_attr(nd, ALIAS_EPI, 0.0)) for _, nd in nodes_data]
+        epi_min, epi_max = min_max_range(epi_vals, default=(0.0, 1.0))
+        si_vals = [clamp01(get_attr(nd, ALIAS_SI, 0.0)) for _, nd in nodes_data]
+        vf_vals = [cast(float, get_attr(nd, ALIAS_VF, 0.0)) for _, nd in nodes_data]
+        dnfr_norms = [
+            normalize_dnfr(nd, dnfr_max) if dnfr_max > 0 else 0.0
+            for _, nd in nodes_data
+        ]
+
+    epi_map = {node: epi_vals[idx] for idx, node in enumerate(nodes)}
+
+    trig_cache = get_trig_cache(G, np=np_mod)
+    trig_local = compute_theta_trig(nodes_data, np=np_mod)
+    cos_map = dict(trig_cache.cos)
+    sin_map = dict(trig_cache.sin)
+    cos_map.update(trig_local.cos)
+    sin_map.update(trig_local.sin)
+
+    neighbors_map = {n: tuple(G.neighbors(n)) for n in nodes}
+
+    if Wm_last is None:
+        coherence_nodes, weight_matrix = coherence_matrix(G)
+        if coherence_nodes is None:
+            coherence_nodes = []
+            weight_matrix = None
+    else:
+        coherence_nodes = list(nodes)
+        weight_matrix = Wm_last
+
+    coherence_nodes = list(coherence_nodes)
+    weight_index = {node: idx for idx, node in enumerate(coherence_nodes)}
+
+    node_index_map: dict[Any, int] | None = None
+
+    if supports_vector:
+        size = len(coherence_nodes)
+        matrix_np = (
+            _coherence_matrix_to_numpy(weight_matrix, size, np_mod) if size else None
+        )
+        if matrix_np is not None and size:
+            cos_weight = np_mod.fromiter(
+                (float(cos_map.get(node, 0.0)) for node in coherence_nodes),
+                dtype=float,
+                count=size,
+            )
+            sin_weight = np_mod.fromiter(
+                (float(sin_map.get(node, 0.0)) for node in coherence_nodes),
+                dtype=float,
+                count=size,
+            )
+            weighted_sync = _weighted_phase_sync_vectorized(
+                matrix_np,
+                cos_weight,
+                sin_weight,
+                np_mod,
+            )
+            rloc_map = {
+                coherence_nodes[idx]: float(weighted_sync[idx]) for idx in range(size)
+            }
+        else:
+            rloc_map = {}
+
+        node_index_map = {node: idx for idx, node in enumerate(nodes)}
+        if not rloc_map:
+            cos_arr = np_mod.fromiter(
+                (float(cos_map.get(node, 0.0)) for node in nodes),
+                dtype=float,
+                count=len(nodes),
+            )
+            sin_arr = np_mod.fromiter(
+                (float(sin_map.get(node, 0.0)) for node in nodes),
+                dtype=float,
+                count=len(nodes),
+            )
+            rloc_values = _unweighted_phase_sync_vectorized(
+                nodes,
+                neighbors_map,
+                cos_arr,
+                sin_arr,
+                node_index_map,
+                np_mod,
+            )
+        else:
+            rloc_values = [rloc_map.get(node, 0.0) for node in nodes]
+    else:
+        if n_jobs and n_jobs > 1 and len(nodes) > 1:
+            approx_chunk = math.ceil(len(nodes) / n_jobs) if n_jobs else None
+            chunk_size = resolve_chunk_size(
+                approx_chunk,
+                len(nodes),
+                minimum=1,
+            )
+            rloc_values = []
+            with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+                futures = [
+                    executor.submit(
+                        _rlocal_worker,
+                        RLocalWorkerArgs(
+                            chunk=nodes[idx : idx + chunk_size],
+                            coherence_nodes=coherence_nodes,
+                            weight_matrix=weight_matrix,
+                            weight_index=weight_index,
+                            neighbors_map=neighbors_map,
+                            cos_map=cos_map,
+                            sin_map=sin_map,
+                        ),
+                    )
+                    for idx in range(0, len(nodes), chunk_size)
+                ]
+                for fut in futures:
+                    rloc_values.extend(fut.result())
+        else:
+            rloc_values = _rlocal_worker(
+                RLocalWorkerArgs(
+                    chunk=nodes,
+                    coherence_nodes=coherence_nodes,
+                    weight_matrix=weight_matrix,
+                    weight_index=weight_index,
+                    neighbors_map=neighbors_map,
+                    cos_map=cos_map,
+                    sin_map=sin_map,
+                )
+            )
+
+    if isinstance(Wi_last, (list, tuple)) and Wi_last:
+        wi_values = [
+            Wi_last[i] if i < len(Wi_last) else None for i in range(len(nodes))
+        ]
+    else:
+        wi_values = [None] * len(nodes)
+
+    compute_symmetry = bool(dcfg.get("compute_symmetry", True))
+    neighbor_means: list[float | None]
+    if compute_symmetry:
+        if supports_vector and node_index_map is not None and len(nodes):
+            neighbor_means = _neighbor_means_vectorized(
+                nodes,
+                neighbors_map,
+                epi_arr,
+                node_index_map,
+                np_mod,
+            )
+        elif n_jobs and n_jobs > 1 and len(nodes) > 1:
+            approx_chunk = math.ceil(len(nodes) / n_jobs) if n_jobs else None
+            chunk_size = resolve_chunk_size(
+                approx_chunk,
+                len(nodes),
+                minimum=1,
+            )
+            neighbor_means = cast(list[float | None], [])
+            with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+                submit = cast(Callable[..., Any], executor.submit)
+                futures = [
+                    submit(
+                        cast(
+                            Callable[[NeighborMeanWorkerArgs], list[float | None]],
+                            _neighbor_mean_worker,
+                        ),
+                        NeighborMeanWorkerArgs(
+                            chunk=nodes[idx : idx + chunk_size],
+                            neighbors_map=neighbors_map,
+                            epi_map=epi_map,
+                        ),
+                    )
+                    for idx in range(0, len(nodes), chunk_size)
+                ]
+                for fut in futures:
+                    neighbor_means.extend(cast(list[float | None], fut.result()))
+        else:
+            neighbor_means = _neighbor_mean_worker(
+                NeighborMeanWorkerArgs(
+                    chunk=nodes,
+                    neighbors_map=neighbors_map,
+                    epi_map=epi_map,
+                )
+            )
+    else:
+        neighbor_means = [None] * len(nodes)
+
+    node_payload: DiagnosisPayloadChunk = []
+    for idx, node in enumerate(nodes):
+        node_payload.append(
+            {
+                "node": node,
+                "Si": si_vals[idx],
+                "EPI": epi_vals[idx],
+                "VF": vf_vals[idx],
+                "dnfr_norm": dnfr_norms[idx],
+                "R_local": rloc_values[idx],
+                "W_i": wi_values[idx],
+                "neighbor_epi_mean": neighbor_means[idx],
+            }
+        )
+
+    shared = {
+        "dcfg": dcfg,
+        "compute_symmetry": compute_symmetry,
+        "epi_min": float(epi_min),
+        "epi_max": float(epi_max),
+        "dissonance_hi": float(dcfg.get("dissonance", {}).get("dnfr_hi", 0.5)),
+    }
+
+    if n_jobs and n_jobs > 1 and len(node_payload) > 1:
+        approx_chunk = math.ceil(len(node_payload) / n_jobs) if n_jobs else None
+        chunk_size = resolve_chunk_size(
+            approx_chunk,
+            len(node_payload),
+            minimum=1,
+        )
+        diag_pairs: DiagnosisResultList = []
+        with ProcessPoolExecutor(max_workers=n_jobs) as executor:
+            submit = cast(Callable[..., Any], executor.submit)
+            futures = [
+                submit(
+                    cast(
+                        Callable[
+                            [list[dict[str, Any]], dict[str, Any]],
+                            list[tuple[Any, dict[str, Any]]],
+                        ],
+                        _diagnosis_worker_chunk,
+                    ),
+                    node_payload[idx : idx + chunk_size],
+                    shared,
+                )
+                for idx in range(0, len(node_payload), chunk_size)
+            ]
+            for fut in futures:
+                diag_pairs.extend(cast(DiagnosisResultList, fut.result()))
+    else:
+        diag_pairs = [_node_diagnostics(item, shared) for item in node_payload]
+
+    diag_map = dict(diag_pairs)
+    diag: dict[NodeId, DiagnosisPayload] = {
+        node: diag_map.get(node, {}) for node in nodes
+    }
 
     append_metric(hist, key, diag)
 
 
-def dissonance_events(G, ctx: dict[str, Any] | None = None):
+def dissonance_events(G: TNFRGraph, ctx: DiagnosisSharedState | None = None) -> None:
     """Emit per-node structural dissonance start/end events.
 
     Events are recorded as ``"dissonance_start"`` and ``"dissonance_end"``.
@@ -193,11 +785,11 @@ def dissonance_events(G, ctx: dict[str, Any] | None = None):
     del ctx
 
     hist = ensure_history(G)
-    # eventos de disonancia se registran en ``history['events']``
+    # Dissonance events are recorded in ``history['events']``
     norms = G.graph.get("_sel_norms", {})
     dnfr_max = float(norms.get("dnfr_max", 1.0)) or 1.0
     step_idx = len(hist.get("C_steps", []))
-    nodes = list(G.nodes())
+    nodes: list[NodeId] = list(G.nodes())
     for n in nodes:
         nd = G.nodes[n]
         dn = normalize_dnfr(nd, dnfr_max)
@@ -219,11 +811,16 @@ def dissonance_events(G, ctx: dict[str, Any] | None = None):
             )
 
 
-def register_diagnosis_callbacks(G) -> None:
+def register_diagnosis_callbacks(G: TNFRGraph) -> None:
+    """Attach diagnosis observers (Si/dissonance tracking) to ``G``."""
+
+    raw_jobs = G.graph.get("DIAGNOSIS_N_JOBS")
+    n_jobs = _coerce_jobs(raw_jobs)
+
     callback_manager.register_callback(
         G,
         event=CallbackEvent.AFTER_STEP.value,
-        func=_diagnosis_step,
+        func=partial(_diagnosis_step, n_jobs=n_jobs),
         name="diagnosis_step",
     )
     callback_manager.register_callback(