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

tnfr/metrics/coherence.py

@@ -1,24 +1,161 @@
-"""Coherence metrics."""
+r"""Coherence metrics for TNFR networks.
+
+This module implements the coherence operator :math:`\hat{C}` and related
+metrics for measuring structural stability in resonant fractal networks.
+
+Mathematical Foundation
+-----------------------
+
+The **coherence operator** :math:`\hat{C}` is a Hermitian operator on the Hilbert
+space :math:`H_{\text{NFR}}` with spectral decomposition:
+
+.. math::
+    \hat{C} = \sum_i \lambda_i |\phi_i\rangle\langle\phi_i|
+
+where :math:`\lambda_i \geq 0` are coherence eigenvalues and :math:`|\phi_i\rangle`
+are coherence eigenstates (maximally stable configurations).
+
+**Properties**:
+
+1. **Hermiticity**: :math:`\hat{C}^\dagger = \hat{C}` (ensures real eigenvalues)
+2. **Positivity**: :math:`\langle\psi|\hat{C}|\psi\rangle \geq 0` (coherence is non-negative)
+3. **Boundedness**: :math:`\|\hat{C}\| \leq M` (prevents runaway growth)
+
+In the discrete node basis :math:`\{|i\rangle\}`, matrix elements are approximated:
+
+.. math::
+    w_{ij} \approx \langle i | \hat{C} | j \rangle
+
+The **total coherence** is computed as the trace:
+
+.. math::
+    C(t) = \text{Tr}(\hat{C}\rho) = \sum_i w_{ii} \rho_i
+
+where :math:`\rho_i` is the density of node :math:`i` (typically uniform: :math:`\rho_i = 1/N`).
+
+Similarity Components
+---------------------
+
+Matrix elements :math:`w_{ij}` are computed from four structural similarity components:
+
+.. math::
+    w_{ij} = w_{\text{phase}} \cdot s_{\text{phase}}(i,j)
+           + w_{\text{EPI}} \cdot s_{\text{EPI}}(i,j)
+           + w_{\nu_f} \cdot s_{\nu_f}(i,j)
+           + w_{\text{Si}} \cdot s_{\text{Si}}(i,j)
+
+where:
+
+- :math:`s_{\text{phase}}(i,j) = \frac{1}{2}\left(1 + \cos(\theta_i - \theta_j)\right)` : Phase similarity
+- :math:`s_{\text{EPI}}(i,j) = 1 - \frac{|\text{EPI}_i - \text{EPI}_j|}{\Delta_{\text{EPI}}}` : Structural form similarity
+- :math:`s_{\nu_f}(i,j) = 1 - \frac{|\nu_{f,i} - \nu_{f,j}|}{\Delta_{\nu_f}}` : Frequency similarity
+- :math:`s_{\text{Si}}(i,j) = 1 - |\text{Si}_i - \text{Si}_j|` : Stability similarity
+
+and :math:`w_{\text{phase}}, w_{\text{EPI}}, w_{\nu_f}, w_{\text{Si}}` are structural weights
+(default: 0.25 each).
+
+Implementation Map
+------------------
+
+**Core Functions**:
+
+- :func:`coherence_matrix` : Constructs :math:`W \approx \hat{C}` matrix representation
+- :func:`compute_coherence` : Computes :math:`C(t) = \text{Tr}(\hat{C}\rho)` from graph (imported from `.common`)
+- :func:`compute_wij_phase_epi_vf_si` : Computes similarity components :math:`(s_{\text{phase}}, s_{\text{EPI}}, s_{\nu_f}, s_{\text{Si}})`
+
+**Helper Functions**:
+
+- :func:`_combine_similarity` : Weighted combination: :math:`w_{ij} = \sum_k w_k s_k`
+- :func:`_compute_wij_phase_epi_vf_si_vectorized` : Vectorized computation for all pairs
+- :func:`_wij_vectorized` : Builds full matrix with NumPy acceleration
+- :func:`_wij_sparse` : Builds sparse matrix for large networks
+
+**Parallel Computation**:
+
+- :func:`_coherence_matrix_parallel` : Multi-process matrix construction
+- :func:`_parallel_wij_worker` : Worker function for parallel chunks
+
+Theoretical References
+----------------------
+
+See the following for complete mathematical derivation:
+
+- **Mathematical Foundations**: `docs/source/theory/mathematical_foundations.md` §3.1
+- **Coherence Operator Theory**: Sections 3.1 (operator definition), 3.1.1 (implementation bridge)
+- **Spectral Properties**: Section 3.1 on eigenvalue decomposition
+- **Style Guide**: `docs/source/style_guide.md` for notation conventions
+
+Examples
+--------
+
+**Basic coherence computation**:
+
+>>> import networkx as nx
+>>> from tnfr.metrics.coherence import coherence_matrix
+>>> from tnfr.metrics.common import compute_coherence
+>>> G = nx.Graph()
+>>> G.add_edge("a", "b")
+>>> G.nodes["a"].update({"EPI": 0.5, "nu_f": 0.8, "phase": 0.0, "Si": 0.7})
+>>> G.nodes["b"].update({"EPI": 0.6, "nu_f": 0.7, "phase": 0.1, "Si": 0.8})
+>>> C = compute_coherence(G)
+>>> 0 <= C <= 1
+True
+
+**Matrix representation**:
+
+>>> nodes, W = coherence_matrix(G)
+>>> len(nodes) == 2
+True
+>>> W.shape == (2, 2)  # Assuming numpy backend
+True
+
+**Worked examples** with step-by-step calculations:
+
+See `docs/source/examples/worked_examples.md` Example 2 for detailed coherence
+matrix element computation walkthrough.
+
+Notes
+-----
+
+- Matrix element computation can use different backends (NumPy, JAX, PyTorch)
+- Sparse matrix format is automatically selected for large networks (>1000 nodes)
+- Parallel computation is enabled for networks with >500 nodes by default
+- Trigonometric values are cached to avoid redundant cos/sin evaluations
+
+See Also
+--------
+
+compute_coherence : Total coherence :math:`C(t)` computation
+sense_index.compute_Si : Sense Index :math:`\text{Si}` computation
+observers.kuramoto_order : Kuramoto order parameter :math:`r`
+observers.phase_sync : Phase synchronization metrics
+"""
 
 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 ..constants import (
-    get_aliases,
-    get_param,
+from types import ModuleType
+from typing import Any, MutableMapping, cast
+
+from .._compat import TypeAlias
+from ..alias import collect_attr, collect_theta_attr, get_attr, set_attr
+from ..utils import CallbackEvent, callback_manager
+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 ..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 ..glyph_history import append_metric, ensure_history
+from ..utils import clamp01
 from ..observers import (
     DEFAULT_GLYPH_LOAD_SPAN,
     DEFAULT_WBAR_SPAN,
@@ -27,20 +164,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 +202,55 @@ 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 +261,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,17 +274,176 @@ 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,
-):
-    """Return similarity components for nodes ``i`` and ``j``.
+    np: ModuleType | None = None,
+) -> SimilarityComponents | VectorizedComponents:
+    r"""Compute structural similarity components for coherence matrix elements.
+
+    Returns four similarity components :math:`(s_{\text{phase}}, s_{\text{EPI}}, s_{\nu_f}, s_{\text{Si}})`
+    that approximate coherence operator matrix elements :math:`w_{ij} \approx \langle i | \hat{C} | j \rangle`.
 
-    When ``np`` is provided and ``i`` and ``j`` are ``None`` the computation is
-    vectorized returning full matrices for all node pairs.
+    Mathematical Foundation
+    -----------------------
+
+    Each similarity component measures structural resemblance between nodes :math:`i` and :math:`j`
+    in a specific dimension:
+
+    **Phase similarity** (synchronization):
+
+    .. math::
+        s_{\text{phase}}(i,j) = \frac{1}{2}\left(1 + \cos(\theta_i - \theta_j)\right)
+
+    Range: [0, 1] where 1 = perfect synchrony, 0 = anti-phase.
+
+    **EPI similarity** (structural form):
+
+    .. math::
+        s_{\text{EPI}}(i,j) = 1 - \frac{|\text{EPI}_i - \text{EPI}_j|}{\Delta_{\text{EPI}}}
+
+    Range: [0, 1] where 1 = identical structure, 0 = maximally different.
+
+    **Frequency similarity** (reorganization rate):
+
+    .. math::
+        s_{\nu_f}(i,j) = 1 - \frac{|\nu_{f,i} - \nu_{f,j}|}{\Delta_{\nu_f}}
+
+    Range: [0, 1] where 1 = matching frequencies.
+
+    **Si similarity** (stability):
+
+    .. math::
+        s_{\text{Si}}(i,j) = 1 - |\text{Si}_i - \text{Si}_j|
+
+    Range: [0, 1] where 1 = equal reorganization stability.
+
+    These components are combined via weighted sum to obtain :math:`w_{ij}`:
+
+    .. math::
+        w_{ij} = w_{\text{phase}} \cdot s_{\text{phase}} + w_{\text{EPI}} \cdot s_{\text{EPI}}
+               + w_{\nu_f} \cdot s_{\nu_f} + w_{\text{Si}} \cdot s_{\text{Si}}
+
+    where :math:`w_{ij} \approx \langle i | \hat{C} | j \rangle` (coherence operator matrix element).
+
+    Parameters
+    ----------
+    inputs : SimilarityInputs
+        Container with structural data:
+
+        - `th_vals` : Sequence[float] - Phase values :math:`\theta` in radians
+        - `epi_vals` : Sequence[float] - EPI values
+        - `vf_vals` : Sequence[float] - Structural frequencies :math:`\nu_f` in Hz_str
+        - `si_vals` : Sequence[float] - Sense Index values
+        - `cos_vals` : Sequence[float] | None - Precomputed :math:`\cos\theta` (optional cache)
+        - `sin_vals` : Sequence[float] | None - Precomputed :math:`\sin\theta` (optional cache)
+
+    i : int | None, optional
+        Index of first node for pairwise computation. If None, vectorized mode is used.
+    j : int | None, optional
+        Index of second node for pairwise computation. If None, vectorized mode is used.
+    trig : Any | None, optional
+        Trigonometric cache object with `cos` and `sin` dictionaries. If None, computed on demand.
+    G : TNFRGraph | None, optional
+        Source graph (used to retrieve cached trigonometric values if available).
+    nodes : Sequence[NodeId] | None, optional
+        Node identifiers corresponding to indices in `inputs` arrays.
+    epi_range : float, default=1.0
+        Normalization range :math:`\Delta_{\text{EPI}}` for EPI similarity.
+        Should be :math:`\text{EPI}_{\max} - \text{EPI}_{\min}`.
+    vf_range : float, default=1.0
+        Normalization range :math:`\Delta_{\nu_f}` for frequency similarity.
+        Should be :math:`\nu_{f,\max} - \nu_{f,\min}`.
+    np : ModuleType | None, optional
+        NumPy-like module (numpy, jax.numpy, torch) for vectorized computation.
+        If provided with `i=None, j=None`, returns vectorized arrays for all pairs.
+
+    Returns
+    -------
+    SimilarityComponents or VectorizedComponents
+        **Pairwise mode** (i and j provided):
+            tuple of (s_phase, s_epi, s_vf, s_si) : tuple[float, float, float, float]
+            Normalized similarity scores :math:`\in [0,1]` for the pair (i, j).
+
+        **Vectorized mode** (i=None, j=None, np provided):
+            tuple of (S_phase, S_epi, S_vf, S_si) : tuple[FloatMatrix, FloatMatrix, FloatMatrix, FloatMatrix]
+            Matrices of shape (N, N) containing all pairwise similarities.
+
+    Raises
+    ------
+    ValueError
+        If pairwise mode is requested (i or j provided) but both are not specified.
+
+    See Also
+    --------
+    coherence_matrix : Constructs full :math:`W \approx \hat{C}` matrix
+    compute_coherence : Computes :math:`C(t) = \text{Tr}(\hat{C}\rho)`
+    _combine_similarity : Weighted combination of similarity components
+
+    Notes
+    -----
+
+    **Performance**:
+
+    - Vectorized mode (with `np`) is ~10-100x faster for large networks
+    - Trigonometric caching avoids redundant cos/sin evaluations
+    - Use `get_trig_cache(G)` to populate cache before repeated calls
+
+    **Normalization**:
+
+    - `epi_range` and `vf_range` should reflect actual network ranges for proper scaling
+    - If ranges are 0, defaults to 1.0 to avoid division by zero
+    - Si similarity uses absolute difference (already bounded to [0,1])
+
+    References
+    ----------
+    .. [1] Mathematical Foundations, §3.1.1 - Implementation Bridge
+    .. [2] docs/source/theory/mathematical_foundations.md#311-implementation-bridge-theory-to-code
+    .. [3] docs/source/examples/worked_examples.md - Example 2: Coherence Matrix Elements
+
+    Examples
+    --------
+
+    **Pairwise computation**:
+
+    >>> from tnfr.metrics.coherence import compute_wij_phase_epi_vf_si, SimilarityInputs
+    >>> inputs = SimilarityInputs(
+    ...     th_vals=[0.0, 0.1],
+    ...     epi_vals=[0.5, 0.6],
+    ...     vf_vals=[0.8, 0.7],
+    ...     si_vals=[0.7, 0.8]
+    ... )
+    >>> s_phase, s_epi, s_vf, s_si = compute_wij_phase_epi_vf_si(
+    ...     inputs, i=0, j=1, epi_range=1.0, vf_range=1.0
+    ... )
+    >>> 0.9 < s_phase < 1.0  # Nearly synchronized (theta_diff = 0.1 rad)
+    True
+    >>> 0.8 < s_epi < 1.0    # Similar EPI values
+    True
+
+    **Vectorized computation**:
+
+    >>> import numpy as np
+    >>> S_phase, S_epi, S_vf, S_si = compute_wij_phase_epi_vf_si(
+    ...     inputs, epi_range=1.0, vf_range=1.0, np=np
+    ... )
+    >>> S_phase.shape  # All pairwise similarities
+    (2, 2)
+    >>> np.allclose(S_phase[0, 1], S_phase[1, 0])  # Symmetric
+    True
+
+    **With graph and caching**:
+
+    >>> import networkx as nx
+    >>> from tnfr.metrics.trig_cache import get_trig_cache
+    >>> G = nx.Graph()
+    >>> G.add_edge(0, 1)
+    >>> G.nodes[0].update({"phase": 0.0, "EPI": 0.5, "nu_f": 0.8, "Si": 0.7})
+    >>> G.nodes[1].update({"phase": 0.1, "EPI": 0.6, "nu_f": 0.7, "Si": 0.8})
+    >>> trig = get_trig_cache(G, np=np)  # Precompute cos/sin
+    >>> # ... use trig in repeated calls for efficiency
     """
 
     trig = trig or (get_trig_cache(G, np=np) if G is not None else None)
@@ -120,17 +463,16 @@ def compute_wij_phase_epi_vf_si(
         inputs.cos_vals = cos_vals
         inputs.sin_vals = sin_vals
 
-    th_vals = inputs.th_vals
     epi_vals = inputs.epi_vals
     vf_vals = inputs.vf_vals
     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 +500,48 @@ 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:
+    """Combine similarity components into coherence weight wᵢⱼ ≈ ⟨i|Ĉ|j⟩.
+
+    Returns wᵢⱼ ∈ [0, 1] clamped to maintain operator boundedness.
+
+    See: Mathematical Foundations §3.1.1 for spectral projection details.
+    """
     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 +567,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 +598,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 +712,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 +822,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 +871,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 +998,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 +1021,81 @@ 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, use_numpy: bool | None = None):
+def coherence_matrix(
+    G: TNFRGraph,
+    use_numpy: bool | None = None,
+    *,
+    n_jobs: int | None = None,
+) -> tuple[list[NodeId] | None, CoherenceMatrixPayload | None]:
+    """Compute coherence matrix W approximating operator Ĉ.
+
+    Returns matrix W where wᵢⱼ ≈ ⟨i|Ĉ|j⟩ computed from structural
+    similarities: phase, EPI, frequency, and sense index.
+
+    Mathematical Foundation:
+        Ĉ ≈ Σᵢⱼ wᵢⱼ |i⟩⟨j|
+
+    Matrix W satisfies Hermiticity (W=W^T), element bounds (wᵢⱼ ∈ [0,1]),
+    and provides spectrum σ(Ĉ) via eigenvalues.
+
+    Parameters
+    ----------
+    G:
+        Graph with node attributes: theta, EPI, vf, Si
+    use_numpy:
+        Force NumPy (True), pure Python (False), or auto-detect (None)
+    n_jobs:
+        Worker processes for Python fallback (None or ≤1 = serial)
+
+    Returns
+    -------
+    nodes:
+        Ordered node list matching matrix indexing
+    W:
+        Coherence matrix (dense or sparse per configuration)
+
+    See Also
+    --------
+    compute_coherence : Computes C(t) = Tr(Ĉρ)
+    Mathematical Foundations §3.1: Theory + Implementation Bridge
+
+    Examples
+    --------
+    >>> nodes, W = coherence_matrix(G)
+    >>> # W[i][j] ≈ ⟨i|Ĉ|j⟩ for computational basis
+    """
+
     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 +1125,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 +1145,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 +1160,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 +1206,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 +1262,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 +1291,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 +1299,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 +1316,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 +1354,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 +1366,29 @@ 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."
+        )
+    if metrics.get(GLYPH_LOAD_STABILIZERS_KEY) is None:
+        metrics.setdefault(GLYPH_LOAD_STABILIZERS_KEY, [])
+
+    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 +1398,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,30 +1741,269 @@ 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)
             hist["Si_lo_frac"].append(0.0)
     except (KeyError, AttributeError, TypeError) as exc:
         logger.debug("Si aggregation failed: %s", exc)
+
+
+def compute_global_coherence(G: TNFRGraph) -> float:
+    """Compute global coherence C(t) for entire network.
+
+    C(t) = 1 - (σ_ΔNFR / ΔNFR_max)
+
+    This is the canonical TNFR coherence metric that measures global structural
+    stability through the dispersion of reorganization pressure (ΔNFR) across
+    the network.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Network graph with nodes containing ΔNFR attributes
+
+    Returns
+    -------
+    float
+        Global coherence value in [0, 1] where:
+        - 1.0 = perfect coherence (no reorganization pressure variance)
+        - 0.0 = maximum incoherence (extreme ΔNFR dispersion)
+
+    Notes
+    -----
+    **Mathematical Foundation:**
+
+    Global coherence quantifies the network's structural stability by measuring
+    how uniformly reorganization pressure is distributed across nodes:
+
+    - **σ_ΔNFR**: Standard deviation of ΔNFR values measures dispersion
+    - **ΔNFR_max**: Maximum ΔNFR provides normalization scale
+    - **C(t)**: Higher values indicate more uniform structural state
+
+    **Special Cases:**
+
+    - Empty network: Returns 1.0 (perfect coherence by definition)
+    - All ΔNFR = 0: Returns 1.0 (no reorganization pressure)
+    - ΔNFR_max = 0: Returns 1.0 (degenerate case, no pressure)
+
+    **TNFR Context:**
+
+    C(t) is the primary metric for measuring IL (Coherence) operator
+    effectiveness. When IL is applied, C(t) should increase as ΔNFR
+    becomes more uniformly distributed (ideally all approaching zero).
+
+    See Also
+    --------
+    compute_local_coherence : Local coherence for node neighborhoods
+    compute_coherence : Alternative coherence metric (legacy)
+
+    Examples
+    --------
+    >>> import networkx as nx
+    >>> from tnfr.metrics.coherence import compute_global_coherence
+    >>> from tnfr.constants import DNFR_PRIMARY
+    >>> G = nx.Graph()
+    >>> G.add_nodes_from([1, 2, 3])
+    >>> G.nodes[1][DNFR_PRIMARY] = 0.1
+    >>> G.nodes[2][DNFR_PRIMARY] = 0.2
+    >>> G.nodes[3][DNFR_PRIMARY] = 0.15
+    >>> C_global = compute_global_coherence(G)
+    >>> 0.0 <= C_global <= 1.0
+    True
+    """
+    # Collect all ΔNFR values
+    dnfr_values = [float(get_attr(G.nodes[n], ALIAS_DNFR, 0.0)) for n in G.nodes()]
+
+    if not dnfr_values or all(v == 0 for v in dnfr_values):
+        return 1.0  # Perfect coherence when no reorganization pressure
+
+    np = get_numpy()
+    if np is not None:
+        dnfr_array = np.array(dnfr_values)
+        sigma_dnfr = float(np.std(dnfr_array))
+        dnfr_max = float(np.max(dnfr_array))
+    else:
+        # Pure Python fallback
+        mean_dnfr = sum(dnfr_values) / len(dnfr_values)
+        variance = sum((v - mean_dnfr) ** 2 for v in dnfr_values) / len(dnfr_values)
+        sigma_dnfr = variance**0.5
+        dnfr_max = max(dnfr_values)
+
+    if dnfr_max == 0:
+        return 1.0
+
+    C_t = 1.0 - (sigma_dnfr / dnfr_max)
+
+    # Clamp to [0, 1] to handle numerical edge cases
+    if np is not None:
+        return float(np.clip(C_t, 0.0, 1.0))
+    return max(0.0, min(1.0, C_t))
+
+
+def compute_local_coherence(G: TNFRGraph, node: Any, radius: int = 1) -> float:
+    """Compute local coherence for node and its neighborhood.
+
+    Local coherence applies the same C(t) formula to a neighborhood subgraph:
+    C_local(t) = 1 - (σ_ΔNFR_local / ΔNFR_max_local)
+
+    This measures structural stability within a node's local vicinity, useful
+    for identifying coherence gradients and structural weak points in networks.
+
+    Parameters
+    ----------
+    G : TNFRGraph
+        Network graph
+    node : Any
+        Central node for local coherence computation
+    radius : int, default=1
+        Neighborhood radius:
+        - 1 = immediate neighbors (default)
+        - 2 = neighbors + neighbors-of-neighbors
+        - etc.
+
+    Returns
+    -------
+    float
+        Local coherence value in [0, 1] where:
+        - 1.0 = perfect local coherence
+        - 0.0 = maximum local incoherence
+
+    Notes
+    -----
+    **Use Cases:**
+
+    - **Hotspot Detection**: Identify regions of structural instability
+    - **IL Targeting**: Prioritize nodes needing coherence stabilization
+    - **Network Health**: Monitor local vs. global coherence balance
+    - **Bifurcation Risk**: Low local C(t) may predict structural splits
+
+    **Radius Selection:**
+
+    - **radius=1**: Fast, captures immediate structural environment
+    - **radius=2**: Better for mesoscale patterns, slower
+    - **radius>2**: Approaches global coherence, expensive
+
+    **Special Cases:**
+
+    - Isolated node (no neighbors): Returns 1.0
+    - All neighborhood ΔNFR = 0: Returns 1.0
+    - Single-node neighborhood: Returns 1.0 (no variance)
+
+    See Also
+    --------
+    compute_global_coherence : Global network coherence
+
+    Examples
+    --------
+    >>> import networkx as nx
+    >>> from tnfr.metrics.coherence import compute_local_coherence
+    >>> from tnfr.constants import DNFR_PRIMARY
+    >>> G = nx.Graph()
+    >>> G.add_edges_from([(1, 2), (2, 3), (3, 4)])
+    >>> for n in [1, 2, 3, 4]:
+    ...     G.nodes[n][DNFR_PRIMARY] = 0.1 * n
+    >>> C_local = compute_local_coherence(G, node=2, radius=1)
+    >>> 0.0 <= C_local <= 1.0
+    True
+    """
+    import networkx as nx
+
+    # Get neighborhood
+    if radius == 1:
+        neighbors = set(G.neighbors(node)) | {node}
+    else:
+        neighbors = set(
+            nx.single_source_shortest_path_length(G, node, cutoff=radius).keys()
+        )
+
+    # Collect ΔNFR for neighborhood
+    dnfr_values = [float(get_attr(G.nodes[n], ALIAS_DNFR, 0.0)) for n in neighbors]
+
+    if not dnfr_values or all(v == 0 for v in dnfr_values):
+        return 1.0
+
+    np = get_numpy()
+    if np is not None:
+        dnfr_array = np.array(dnfr_values)
+        sigma_dnfr = float(np.std(dnfr_array))
+        dnfr_max = float(np.max(dnfr_array))
+    else:
+        # Pure Python fallback
+        mean_dnfr = sum(dnfr_values) / len(dnfr_values)
+        variance = sum((v - mean_dnfr) ** 2 for v in dnfr_values) / len(dnfr_values)
+        sigma_dnfr = variance**0.5
+        dnfr_max = max(dnfr_values)
+
+    if dnfr_max == 0:
+        return 1.0
+
+    C_local = 1.0 - (sigma_dnfr / dnfr_max)
+
+    # Clamp to [0, 1]
+    if np is not None:
+        return float(np.clip(C_local, 0.0, 1.0))
+    return max(0.0, min(1.0, C_local))