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

tnfr/metrics/coherence.py

@@ -7,19 +7,32 @@ from collections.abc import Callable, Iterable, Mapping, Sequence
 from concurrent.futures import ProcessPoolExecutor
 from dataclasses import dataclass
 from types import ModuleType
-from typing import Any, MutableMapping, TypedDict, cast
+from typing import Any, MutableMapping, cast
 
 from .._compat import TypeAlias
-
-
-from ..constants import (
-    get_aliases,
-    get_param,
-)
+from ..alias import collect_attr, collect_theta_attr, get_attr, set_attr
 from ..callback_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 ..glyph_history import append_metric, ensure_history
-from ..alias import collect_attr, collect_theta_attr, set_attr
-from ..helpers.numeric import clamp01
+from ..utils import clamp01
+from ..observers import (
+    DEFAULT_GLYPH_LOAD_SPAN,
+    DEFAULT_WBAR_SPAN,
+    glyph_load,
+    kuramoto_order,
+    phase_sync,
+)
+from ..sense import sigma_vector
 from ..types import (
     CoherenceMetric,
     FloatArray,
@@ -27,37 +40,22 @@ from ..types import (
     GlyphLoadDistribution,
     HistoryState,
     NodeId,
+    ParallelWijPayload,
     SigmaVector,
     TNFRGraph,
 )
-from .common import compute_coherence, min_max_range
-from .trig_cache import compute_theta_trig, get_trig_cache
-from ..observers import (
-    DEFAULT_GLYPH_LOAD_SPAN,
-    DEFAULT_WBAR_SPAN,
-    glyph_load,
-    kuramoto_order,
-    phase_sync,
-)
-from ..sense import sigma_vector
 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_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"
 
 
@@ -81,9 +79,9 @@ PhaseSyncWeights: TypeAlias = (
 )
 
 SimilarityComponents = tuple[float, float, float, float]
-VectorizedComponents: TypeAlias = (
-    tuple[FloatMatrix, FloatMatrix, FloatMatrix, FloatMatrix]
-)
+VectorizedComponents: TypeAlias = tuple[
+    FloatMatrix, FloatMatrix, FloatMatrix, FloatMatrix
+]
 ScalarOrArray: TypeAlias = float | FloatArray
 StabilityChunkArgs = tuple[
     Sequence[float],
@@ -110,19 +108,6 @@ StabilityChunkResult = tuple[
 MetricValue: TypeAlias = CoherenceMetric
 MetricProvider = Callable[[], MetricValue]
 MetricRecord: TypeAlias = tuple[MetricValue | MetricProvider, str]
-
-
-class ParallelWijPayload(TypedDict):
-    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
-
-
 def _compute_wij_phase_epi_vf_si_vectorized(
     epi: FloatArray,
     vf: FloatArray,
@@ -143,9 +128,7 @@ def _compute_wij_phase_epi_vf_si_vectorized(
     epi_range = epi_range if epi_range > 0 else 1.0
     vf_range = vf_range if vf_range > 0 else 1.0
     s_phase = 0.5 * (
-        1.0
-        + cos_th[:, None] * cos_th[None, :]
-        + sin_th[:, None] * sin_th[None, :]
+        1.0 + cos_th[:, None] * cos_th[None, :] + sin_th[:, None] * sin_th[None, :]
     )
     s_epi = 1.0 - np.abs(epi[:, None] - epi[None, :]) / epi_range
     s_vf = 1.0 - np.abs(vf[:, None] - vf[None, :]) / vf_range
@@ -369,7 +352,7 @@ def _init_parallel_wij(data: ParallelWijPayload) -> None:
 
 
 def _parallel_wij_worker(
-    pairs: Sequence[tuple[int, int]]
+    pairs: Sequence[tuple[int, int]],
 ) -> list[tuple[int, int, float]]:
     """Compute coherence weights for ``pairs`` using shared state."""
 
@@ -444,10 +427,7 @@ def _wij_loops(
     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)
-    ]
+    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 = (
@@ -498,7 +478,12 @@ def _wij_loops(
             wij[i][j] = wij[j][i] = wij_ij
         return wij
 
-    chunk_size = max(1, math.ceil(total_pairs / max_workers))
+    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),
@@ -516,7 +501,7 @@ def _wij_loops(
     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]
+            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():
@@ -589,15 +574,12 @@ def _coherence_numpy(
         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_worker(
-    args: tuple[Sequence[Sequence[float]], int, str, float]
+    args: tuple[Sequence[Sequence[float]], int, str, float],
 ) -> tuple[int, list[float], list[float], CoherenceMatrixSparse]:
     rows, start, mode, thr = args
     values: list[float] = []
@@ -661,11 +643,16 @@ def _coherence_python(
                     row_sum[i] += w
         return n, values, row_sum, W if mode == "dense" else W_sparse
 
-    chunk_size = max(1, math.ceil(n / max_workers))
+    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]
+            rows = wij[start : start + chunk_size]
             tasks.append(
                 executor.submit(
                     _coherence_python_worker,
@@ -675,7 +662,9 @@ def _coherence_python(
         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
+    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):
@@ -771,9 +760,7 @@ def coherence_matrix(
 
     # 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
@@ -993,6 +980,8 @@ def _coherence_step(G: TNFRGraph, ctx: dict[str, Any] | None = None) -> 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,
@@ -1011,7 +1000,7 @@ def _record_metrics(
     *pairs: MetricRecord,
     evaluate: bool = False,
 ) -> None:
-    """Generic recorder for metric values."""
+    """Record metric values for the trace history."""
 
     metrics = cast(MutableMapping[str, list[Any]], hist)
     for payload, key in pairs:
@@ -1084,9 +1073,7 @@ def _update_sigma(G: TNFRGraph, hist: HistoryState) -> None:
         (disruptors, "glyph_load_disr"),
     )
 
-    dist: GlyphLoadDistribution = {
-        k: v for k, v in gl.items() if not k.startswith("_")
-    }
+    dist: GlyphLoadDistribution = {k: v for k, v in gl.items() if not k.startswith("_")}
     sig: SigmaVector = sigma_vector(dist)
     _record_metrics(
         hist,
@@ -1140,7 +1127,10 @@ def _stability_chunk_worker(args: StabilityChunkArgs) -> StabilityChunkResult:
         B_vals.append(B)
         B_sum += B
 
-        if abs(float(dnfr_vals[idx])) <= eps_dnfr and abs(float(depi_vals[idx])) <= eps_depi:
+        if (
+            abs(float(dnfr_vals[idx])) <= eps_dnfr
+            and abs(float(depi_vals[idx])) <= eps_depi
+        ):
             stable += 1
 
     chunk_len = len(si_curr_vals)
@@ -1196,18 +1186,22 @@ def _track_stability(
 
         si_prev_arr = np.asarray(
             [
-                float(prev_si_data[idx])
-                if prev_si_data[idx] is not None
-                else float(si_curr_arr[idx])
+                (
+                    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])
+                (
+                    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,
@@ -1220,9 +1214,11 @@ def _track_stability(
 
         dvf_prev_arr = np.asarray(
             [
-                float(prev_dvf_data[idx])
-                if prev_dvf_data[idx] is not None
-                else float(dvf_dt_arr[idx])
+                (
+                    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,
@@ -1268,8 +1264,18 @@ def _track_stability(
     vf_curr_list = list(vf_curr_vals)
 
     if n_jobs and n_jobs > 1:
-        chunk_size = max(1, math.ceil(total_nodes / n_jobs))
-        chunk_results: list[tuple[int, tuple[int, int, float, float, list[float], list[float], list[float]]]] = []
+        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):
@@ -1286,7 +1292,9 @@ def _track_stability(
                     eps_dnfr,
                     eps_depi,
                 )
-                futures.append((start, executor.submit(_stability_chunk_worker, chunk_args)))
+                futures.append(
+                    (start, executor.submit(_stability_chunk_worker, chunk_args))
+                )
 
             for start, fut in futures:
                 chunk_results.append((start, fut.result()))
@@ -1349,7 +1357,10 @@ def _track_stability(
             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:
+            if (
+                abs(float(dnfr_list[idx])) <= eps_dnfr
+                and abs(float(depi_list[idx])) <= eps_depi
+            ):
                 stable_total += 1
 
         total = len(delta_vals_all)
@@ -1416,10 +1427,30 @@ def _aggregate_si(
         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)))
 
+        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 = collect_attr(G, G.nodes, ALIAS_SI, float("nan"), np=np_mod)
-            valid = sis[~np_mod.isnan(sis)]
+            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()))
@@ -1433,19 +1464,17 @@ def _aggregate_si(
                 hist["Si_lo_frac"].append(0.0)
             return
 
-        sis = collect_attr(G, G.nodes, ALIAS_SI, float("nan"))
-        if not sis:
-            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:
-            chunk_size = max(1, math.ceil(len(sis) / n_jobs))
+            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]
+                    chunk = sis[idx : idx + chunk_size]
                     futures.append(
                         executor.submit(_si_chunk_stats, chunk, si_hi, si_lo)
                     )

tnfr/metrics/common.py

@@ -6,16 +6,12 @@ from types import MappingProxyType
 from typing import Any, Iterable, Mapping, Sequence
 
 from ..alias import collect_attr, get_attr, multi_recompute_abs_max
-from ..constants import DEFAULTS, get_aliases
-from ..helpers.numeric import clamp01, kahan_sum_nd
-from ..types import GraphLike
+from ..constants import DEFAULTS
+from ..constants.aliases import ALIAS_D2EPI, ALIAS_DEPI, ALIAS_DNFR, ALIAS_VF
+from ..utils import clamp01, kahan_sum_nd, normalize_optional_int
+from ..types import GraphLike, NodeAttrMap
 from ..utils import edge_version_cache, get_numpy, normalize_weights
 
-ALIAS_DNFR = get_aliases("DNFR")
-ALIAS_D2EPI = get_aliases("D2EPI")
-ALIAS_DEPI = get_aliases("DEPI")
-ALIAS_VF = get_aliases("VF")
-
 __all__ = (
     "GraphLike",
     "compute_coherence",
@@ -25,6 +21,7 @@ __all__ = (
     "merge_graph_weights",
     "merge_and_normalize_weights",
     "min_max_range",
+    "_coerce_jobs",
     "_get_vf_dnfr_max",
 )
 
@@ -70,7 +67,10 @@ def ensure_neighbors_map(G: GraphLike) -> Mapping[Any, Sequence[Any]]:
 def merge_graph_weights(G: GraphLike, key: str) -> dict[str, float]:
     """Merge default weights for ``key`` with any graph overrides."""
 
-    return {**DEFAULTS[key], **G.graph.get(key, {})}
+    overrides = G.graph.get(key, {})
+    if overrides is None or not isinstance(overrides, Mapping):
+        overrides = {}
+    return {**DEFAULTS[key], **overrides}
 
 
 def merge_and_normalize_weights(
@@ -101,7 +101,7 @@ def compute_dnfr_accel_max(G: GraphLike) -> dict[str, float]:
     )
 
 
-def normalize_dnfr(nd: Mapping[str, Any], max_val: float) -> float:
+def normalize_dnfr(nd: NodeAttrMap, max_val: float) -> float:
     """Normalise ``|ΔNFR|`` using ``max_val``."""
 
     if max_val <= 0:
@@ -135,9 +135,7 @@ def _get_vf_dnfr_max(G: GraphLike) -> tuple[float, float]:
     vfmax = G.graph.get("_vfmax")
     dnfrmax = G.graph.get("_dnfrmax")
     if vfmax is None or dnfrmax is None:
-        maxes = multi_recompute_abs_max(
-            G, {"_vfmax": ALIAS_VF, "_dnfrmax": ALIAS_DNFR}
-        )
+        maxes = multi_recompute_abs_max(G, {"_vfmax": ALIAS_VF, "_dnfrmax": ALIAS_DNFR})
         if vfmax is None:
             vfmax = maxes["_vfmax"]
         if dnfrmax is None:
@@ -147,3 +145,14 @@ def _get_vf_dnfr_max(G: GraphLike) -> tuple[float, float]:
     vfmax = 1.0 if vfmax == 0 else vfmax
     dnfrmax = 1.0 if dnfrmax == 0 else dnfrmax
     return float(vfmax), float(dnfrmax)
+
+
+def _coerce_jobs(raw_jobs: Any | None) -> int | None:
+    """Normalise parallel job hints shared by metrics modules."""
+
+    return normalize_optional_int(
+        raw_jobs,
+        allow_non_positive=False,
+        strict=False,
+        sentinels=None,
+    )

tnfr/metrics/common.pyi

@@ -1,15 +1,46 @@
-from typing import Any
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any, Literal, overload
 
-__all__: Any
+from ..types import GraphLike, NodeAttrMap
+
+__all__: tuple[str, ...]
 
 def __getattr__(name: str) -> Any: ...
 
-GraphLike: Any
-_get_vf_dnfr_max: Any
-compute_coherence: Any
-compute_dnfr_accel_max: Any
-ensure_neighbors_map: Any
-merge_and_normalize_weights: Any
-merge_graph_weights: Any
-min_max_range: Any
-normalize_dnfr: Any
+@overload
+def compute_coherence(G: GraphLike, *, return_means: Literal[False] = ...) -> float: ...
+
+
+@overload
+def compute_coherence(
+    G: GraphLike, *, return_means: Literal[True]
+) -> tuple[float, float, float]: ...
+
+
+def compute_coherence(
+    G: GraphLike, *, return_means: bool = ...
+) -> float | tuple[float, float, float]: ...
+
+def ensure_neighbors_map(G: GraphLike) -> Mapping[Any, Sequence[Any]]: ...
+
+def merge_graph_weights(G: GraphLike, key: str) -> dict[str, float]: ...
+
+def merge_and_normalize_weights(
+    G: GraphLike,
+    key: str,
+    fields: Sequence[str],
+    *,
+    default: float = ...,
+) -> dict[str, float]: ...
+
+def compute_dnfr_accel_max(G: GraphLike) -> dict[str, float]: ...
+
+def normalize_dnfr(nd: NodeAttrMap, max_val: float) -> float: ...
+
+def min_max_range(
+    values: Iterable[float], *, default: tuple[float, float] = ...
+) -> tuple[float, float]: ...
+
+def _get_vf_dnfr_max(G: GraphLike) -> tuple[float, float]: ...
+
+def _coerce_jobs(raw_jobs: Any | None) -> int | None: ...