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

tnfr/dynamics/dnfr.pyi

@@ -0,0 +1,33 @@
+from typing import Any
+
+from tnfr.types import DeltaNFRHook, TNFRGraph
+
+__all__: tuple[str, ...]
+
+def default_compute_delta_nfr(
+    G: TNFRGraph,
+    *,
+    cache_size: int | None = ...,
+    n_jobs: int | None = ...,
+) -> None: ...
+
+
+def dnfr_epi_vf_mixed(G: TNFRGraph, *, n_jobs: int | None = ...) -> None: ...
+
+
+def dnfr_laplacian(G: TNFRGraph, *, n_jobs: int | None = ...) -> None: ...
+
+
+def dnfr_phase_only(G: TNFRGraph, *, n_jobs: int | None = ...) -> None: ...
+
+
+def set_delta_nfr_hook(
+    G: TNFRGraph,
+    func: DeltaNFRHook,
+    *,
+    name: str | None = ...,
+    note: str | None = ...,
+) -> None: ...
+
+
+def __getattr__(name: str) -> Any: ...

tnfr/dynamics/integrators.py

@@ -1,17 +1,23 @@
 from __future__ import annotations
 
 import math
-from collections.abc import Mapping
-from typing import Any, Literal
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Mapping
+from concurrent.futures import ProcessPoolExecutor
+from multiprocessing import get_context
+from typing import Any, Literal, cast
 
-import networkx as nx  # type: ignore[import-untyped]
+import networkx as nx
 
 from ..constants import (
     DEFAULTS,
     get_aliases,
 )
 from ..gamma import _get_gamma_spec, eval_gamma
-from ..alias import get_attr, get_attr_str, set_attr, set_attr_str
+from ..alias import collect_attr, get_attr, get_attr_str, set_attr, set_attr_str
+from ..utils import get_numpy
+from ..types import NodeId, TNFRGraph
+from .._compat import TypeAlias
 
 ALIAS_VF = get_aliases("VF")
 ALIAS_DNFR = get_aliases("DNFR")
@@ -21,17 +27,130 @@ ALIAS_EPI_KIND = get_aliases("EPI_KIND")
 ALIAS_D2EPI = get_aliases("D2EPI")
 
 __all__ = (
+    "AbstractIntegrator",
+    "DefaultIntegrator",
     "prepare_integration_params",
     "update_epi_via_nodal_equation",
 )
 
 
+GammaMap: TypeAlias = dict[NodeId, float]
+"""Γ evaluation cache keyed by node identifier."""
+
+NodeIncrements: TypeAlias = dict[NodeId, tuple[float, ...]]
+"""Mapping of nodes to staged integration increments."""
+
+NodalUpdate: TypeAlias = dict[NodeId, tuple[float, float, float]]
+"""Mapping of nodes to ``(EPI, dEPI/dt, ∂²EPI/∂t²)`` tuples."""
+
+IntegratorMethod: TypeAlias = Literal["euler", "rk4"]
+"""Supported explicit integration schemes for nodal updates."""
+
+
+_PARALLEL_GRAPH: TNFRGraph | None = None
+
+
+def _gamma_worker_init(graph: TNFRGraph) -> None:
+    """Initialise process-local graph reference for Γ evaluation."""
+
+    global _PARALLEL_GRAPH
+    _PARALLEL_GRAPH = graph
+
+
+def _gamma_worker(task: tuple[list[NodeId], float]) -> list[tuple[NodeId, float]]:
+    """Evaluate Γ for ``task`` chunk using process-local graph."""
+
+    chunk, t = task
+    if _PARALLEL_GRAPH is None:
+        raise RuntimeError("Parallel Γ worker initialised without graph reference")
+    return [
+        (node, float(eval_gamma(_PARALLEL_GRAPH, node, t))) for node in chunk
+    ]
+
+
+def _normalise_jobs(n_jobs: int | None, total: int) -> int | None:
+    """Return an effective worker count respecting serial fallbacks."""
+
+    if n_jobs is None:
+        return None
+    try:
+        workers = int(n_jobs)
+    except (TypeError, ValueError):
+        return None
+    if workers <= 1 or total <= 1:
+        return None
+    return max(1, min(workers, total))
+
+
+def _chunk_nodes(nodes: list[NodeId], chunk_size: int) -> Iterable[list[NodeId]]:
+    """Yield deterministic chunks from ``nodes`` respecting insertion order."""
+
+    for idx in range(0, len(nodes), chunk_size):
+        yield nodes[idx:idx + chunk_size]
+
+
+def _apply_increment_chunk(
+    chunk: list[tuple[NodeId, float, float, tuple[float, ...]]],
+    dt_step: float,
+    method: str,
+) -> list[tuple[NodeId, tuple[float, float, float]]]:
+    """Compute updated states for ``chunk`` using scalar arithmetic."""
+
+    results: list[tuple[NodeId, tuple[float, float, float]]] = []
+    dt_nonzero = dt_step != 0
+
+    for node, epi_i, dEPI_prev, ks in chunk:
+        if method == "rk4":
+            k1, k2, k3, k4 = ks
+            epi = epi_i + (dt_step / 6.0) * (k1 + 2 * k2 + 2 * k3 + k4)
+            dEPI_dt = k4
+        else:
+            (k1,) = ks
+            epi = epi_i + dt_step * k1
+            dEPI_dt = k1
+        d2epi = (dEPI_dt - dEPI_prev) / dt_step if dt_nonzero else 0.0
+        results.append((node, (float(epi), float(dEPI_dt), float(d2epi))))
+
+    return results
+
+
+def _evaluate_gamma_map(
+    G: TNFRGraph,
+    nodes: list[NodeId],
+    t: float,
+    *,
+    n_jobs: int | None = None,
+) -> GammaMap:
+    """Return Γ evaluations for ``nodes`` at time ``t`` respecting parallelism."""
+
+    workers = _normalise_jobs(n_jobs, len(nodes))
+    if workers is None:
+        return {n: float(eval_gamma(G, n, t)) for n in nodes}
+
+    chunk_size = max(1, math.ceil(len(nodes) / (workers * 4)))
+    mp_ctx = get_context("spawn")
+    tasks = ((chunk, t) for chunk in _chunk_nodes(nodes, chunk_size))
+
+    results: GammaMap = {}
+    with ProcessPoolExecutor(
+        max_workers=workers,
+        mp_context=mp_ctx,
+        initializer=_gamma_worker_init,
+        initargs=(G,),
+    ) as executor:
+        futures = [executor.submit(_gamma_worker, task) for task in tasks]
+        for fut in futures:
+            for node, value in fut.result():
+                results[node] = value
+    return results
+
+
 def prepare_integration_params(
-    G,
+    G: TNFRGraph,
     dt: float | None = None,
     t: float | None = None,
     method: Literal["euler", "rk4"] | None = None,
-):
+) -> tuple[float, int, float, Literal["euler", "rk4"]]:
     """Validate and normalise ``dt``, ``t`` and ``method`` for integration.
 
     Returns ``(dt_step, steps, t0, method)`` where ``dt_step`` is the
@@ -52,13 +171,13 @@ def prepare_integration_params(
     else:
         t = float(t)
 
-    method = (
+    method_value = (
         method
         or G.graph.get(
             "INTEGRATOR_METHOD", DEFAULTS.get("INTEGRATOR_METHOD", "euler")
         )
     ).lower()
-    if method not in ("euler", "rk4"):
+    if method_value not in ("euler", "rk4"):
         raise ValueError("method must be 'euler' or 'rk4'")
 
     dt_min = float(G.graph.get("DT_MIN", DEFAULTS.get("DT_MIN", 0.0)))
@@ -69,43 +188,108 @@ def prepare_integration_params(
     # ``steps`` is guaranteed to be ≥1 at this point
     dt_step = dt / steps
 
-    return dt_step, steps, t, method
+    return dt_step, steps, t, cast(Literal["euler", "rk4"], method_value)
 
 
 def _apply_increments(
-    G: Any,
+    G: TNFRGraph,
     dt_step: float,
-    increments: dict[Any, tuple[float, ...]],
+    increments: NodeIncrements,
     *,
     method: str,
-) -> dict[Any, tuple[float, float, float]]:
+    n_jobs: int | None = None,
+) -> NodalUpdate:
     """Combine precomputed increments to update node states."""
 
-    new_states: dict[Any, tuple[float, float, float]] = {}
-    for n, nd in G.nodes(data=True):
-        vf, dnfr, dEPI_dt_prev, epi_i = _node_state(nd)
-        ks = increments[n]
+    nodes: list[NodeId] = list(G.nodes)
+    if not nodes:
+        return {}
+
+    np = get_numpy()
+
+    epi_initial: list[float] = []
+    dEPI_prev: list[float] = []
+    ordered_increments: list[tuple[float, ...]] = []
+
+    for node in nodes:
+        nd = G.nodes[node]
+        _, _, dEPI_dt_prev, epi_i = _node_state(nd)
+        epi_initial.append(float(epi_i))
+        dEPI_prev.append(float(dEPI_dt_prev))
+        ordered_increments.append(increments[node])
+
+    if np is not None:
+        epi_arr = np.asarray(epi_initial, dtype=float)
+        dEPI_prev_arr = np.asarray(dEPI_prev, dtype=float)
+        k_arr = np.asarray(ordered_increments, dtype=float)
+
         if method == "rk4":
-            k1, k2, k3, k4 = ks
-            # RK4: EPIₙ₊₁ = EPIᵢ + Δt/6·(k1 + 2k2 + 2k3 + k4)
-            epi = epi_i + (dt_step / 6.0) * (k1 + 2 * k2 + 2 * k3 + k4)
+            if k_arr.ndim != 2 or k_arr.shape[1] != 4:
+                raise ValueError("rk4 increments require four staged values")
+            dt_factor = dt_step / 6.0
+            k1 = k_arr[:, 0]
+            k2 = k_arr[:, 1]
+            k3 = k_arr[:, 2]
+            k4 = k_arr[:, 3]
+            epi = epi_arr + dt_factor * (k1 + 2 * k2 + 2 * k3 + k4)
             dEPI_dt = k4
         else:
-            (k1,) = ks
-            # Euler: EPIₙ₊₁ = EPIᵢ + Δt·k1 where k1 = νf·ΔNFR + Γ
-            epi = epi_i + dt_step * k1
+            if k_arr.ndim == 1:
+                k1 = k_arr
+            else:
+                k1 = k_arr[:, 0]
+            epi = epi_arr + dt_step * k1
             dEPI_dt = k1
-        d2epi = (dEPI_dt - dEPI_dt_prev) / dt_step if dt_step != 0 else 0.0
-        new_states[n] = (epi, dEPI_dt, d2epi)
-    return new_states
+
+        if dt_step != 0:
+            d2epi = (dEPI_dt - dEPI_prev_arr) / dt_step
+        else:
+            d2epi = np.zeros_like(dEPI_dt)
+
+        results: NodalUpdate = {}
+        for idx, node in enumerate(nodes):
+            results[node] = (
+                float(epi[idx]),
+                float(dEPI_dt[idx]),
+                float(d2epi[idx]),
+            )
+        return results
+
+    payload: list[tuple[NodeId, float, float, tuple[float, ...]]] = list(
+        zip(nodes, epi_initial, dEPI_prev, ordered_increments)
+    )
+
+    workers = _normalise_jobs(n_jobs, len(nodes))
+    if workers is None:
+        return dict(_apply_increment_chunk(payload, dt_step, method))
+
+    chunk_size = max(1, math.ceil(len(nodes) / (workers * 4)))
+    mp_ctx = get_context("spawn")
+
+    results: NodalUpdate = {}
+    with ProcessPoolExecutor(max_workers=workers, mp_context=mp_ctx) as executor:
+        futures = [
+            executor.submit(
+                _apply_increment_chunk,
+                chunk,
+                dt_step,
+                method,
+            )
+            for chunk in _chunk_nodes(payload, chunk_size)
+        ]
+        for fut in futures:
+            for node, value in fut.result():
+                results[node] = value
+
+    return {node: results[node] for node in nodes}
 
 
 def _collect_nodal_increments(
-    G: Any,
-    gamma_maps: tuple[dict[Any, float], ...],
+    G: TNFRGraph,
+    gamma_maps: tuple[GammaMap, ...],
     *,
     method: str,
-) -> dict[Any, tuple[float, ...]]:
+) -> NodeIncrements:
     """Combine node base state with staged Γ contributions.
 
     ``gamma_maps`` must contain one entry for Euler integration and four for
@@ -113,38 +297,71 @@ def _collect_nodal_increments(
     with the supplied Γ evaluations.
     """
 
-    increments: dict[Any, tuple[float, ...]] = {}
-    for n, nd in G.nodes(data=True):
+    nodes: list[NodeId] = list(G.nodes())
+    if not nodes:
+        return {}
+
+    if method == "rk4":
+        expected_maps = 4
+    elif method == "euler":
+        expected_maps = 1
+    else:
+        raise ValueError("method must be 'euler' or 'rk4'")
+
+    if len(gamma_maps) != expected_maps:
+        raise ValueError(f"{method} integration requires {expected_maps} gamma maps")
+
+    np = get_numpy()
+    if np is not None:
+        vf = collect_attr(G, nodes, ALIAS_VF, 0.0, np=np)
+        dnfr = collect_attr(G, nodes, ALIAS_DNFR, 0.0, np=np)
+        base = vf * dnfr
+
+        gamma_arrays = [
+            np.fromiter((gm.get(n, 0.0) for n in nodes), float, count=len(nodes))
+            for gm in gamma_maps
+        ]
+        if gamma_arrays:
+            gamma_stack = np.stack(gamma_arrays, axis=1)
+            combined = base[:, None] + gamma_stack
+        else:
+            combined = base[:, None]
+
+        return {
+            node: tuple(float(value) for value in combined[idx])
+            for idx, node in enumerate(nodes)
+        }
+
+    increments: NodeIncrements = {}
+    for node in nodes:
+        nd = G.nodes[node]
         vf, dnfr, *_ = _node_state(nd)
         base = vf * dnfr
-        gammas = [gm.get(n, 0.0) for gm in gamma_maps]
+        gammas = [gm.get(node, 0.0) for gm in gamma_maps]
 
         if method == "rk4":
-            if len(gammas) != 4:
-                raise ValueError("rk4 integration requires four gamma maps")
             k1, k2, k3, k4 = gammas
-            increments[n] = (
+            increments[node] = (
                 base + k1,
                 base + k2,
                 base + k3,
                 base + k4,
             )
         else:
-            if len(gammas) != 1:
-                raise ValueError("euler integration requires one gamma map")
             (k1,) = gammas
-            increments[n] = (base + k1,)
+            increments[node] = (base + k1,)
 
     return increments
 
 
 def _build_gamma_increments(
-    G: Any,
+    G: TNFRGraph,
     dt_step: float,
     t_local: float,
     *,
     method: str,
-) -> dict[Any, tuple[float, ...]]:
+    n_jobs: int | None = None,
+) -> NodeIncrements:
     """Evaluate Γ contributions and merge them with ``νf·ΔNFR`` base terms."""
 
     if method == "rk4":
@@ -163,50 +380,146 @@ def _build_gamma_increments(
         gamma_type = str(gamma_spec.get("type", "")).lower()
 
     if gamma_type == "none":
-        gamma_maps = tuple({} for _ in range(gamma_count))
+        gamma_maps: tuple[GammaMap, ...] = tuple(
+            cast(GammaMap, {}) for _ in range(gamma_count)
+        )
+        return _collect_nodal_increments(G, gamma_maps, method=method)
+
+    nodes: list[NodeId] = list(G.nodes)
+    if not nodes:
+        gamma_maps = tuple(cast(GammaMap, {}) for _ in range(gamma_count))
         return _collect_nodal_increments(G, gamma_maps, method=method)
 
     if method == "rk4":
         t_mid = t_local + dt_step / 2.0
         t_end = t_local + dt_step
-        g1_map = {n: eval_gamma(G, n, t_local) for n in G.nodes}
-        g_mid_map = {n: eval_gamma(G, n, t_mid) for n in G.nodes}
-        g4_map = {n: eval_gamma(G, n, t_end) for n in G.nodes}
+        g1_map = _evaluate_gamma_map(G, nodes, t_local, n_jobs=n_jobs)
+        g_mid_map = _evaluate_gamma_map(G, nodes, t_mid, n_jobs=n_jobs)
+        g4_map = _evaluate_gamma_map(G, nodes, t_end, n_jobs=n_jobs)
         gamma_maps = (g1_map, g_mid_map, g_mid_map, g4_map)
     else:  # method == "euler"
-        gamma_maps = ({n: eval_gamma(G, n, t_local) for n in G.nodes},)
+        gamma_maps = (
+            _evaluate_gamma_map(G, nodes, t_local, n_jobs=n_jobs),
+        )
 
     return _collect_nodal_increments(G, gamma_maps, method=method)
 
 
-def _integrate_euler(G, dt_step: float, t_local: float):
+def _integrate_euler(
+    G: TNFRGraph,
+    dt_step: float,
+    t_local: float,
+    *,
+    n_jobs: int | None = None,
+) -> NodalUpdate:
     """One explicit Euler integration step."""
     increments = _build_gamma_increments(
         G,
         dt_step,
         t_local,
         method="euler",
+        n_jobs=n_jobs,
+    )
+    return _apply_increments(
+        G,
+        dt_step,
+        increments,
+        method="euler",
+        n_jobs=n_jobs,
     )
-    return _apply_increments(G, dt_step, increments, method="euler")
 
 
-def _integrate_rk4(G, dt_step: float, t_local: float):
+def _integrate_rk4(
+    G: TNFRGraph,
+    dt_step: float,
+    t_local: float,
+    *,
+    n_jobs: int | None = None,
+) -> NodalUpdate:
     """One Runge–Kutta order-4 integration step."""
     increments = _build_gamma_increments(
         G,
         dt_step,
         t_local,
         method="rk4",
+        n_jobs=n_jobs,
     )
-    return _apply_increments(G, dt_step, increments, method="rk4")
+    return _apply_increments(
+        G,
+        dt_step,
+        increments,
+        method="rk4",
+        n_jobs=n_jobs,
+    )
+
+
+class AbstractIntegrator(ABC):
+    """Abstract base class encapsulating nodal equation integration."""
+
+    @abstractmethod
+    def integrate(
+        self,
+        graph: TNFRGraph,
+        *,
+        dt: float | None,
+        t: float | None,
+        method: str | None,
+        n_jobs: int | None,
+    ) -> None:
+        """Advance ``graph`` coherence states according to the nodal equation."""
+
+
+class DefaultIntegrator(AbstractIntegrator):
+    """Explicit integrator combining Euler and RK4 step implementations."""
+
+    def integrate(
+        self,
+        graph: TNFRGraph,
+        *,
+        dt: float | None,
+        t: float | None,
+        method: str | None,
+        n_jobs: int | None,
+    ) -> None:
+        if not isinstance(
+            graph, (nx.Graph, nx.DiGraph, nx.MultiGraph, nx.MultiDiGraph)
+        ):
+            raise TypeError("G must be a networkx graph instance")
+
+        dt_step, steps, t0, resolved_method = prepare_integration_params(
+            graph, dt, t, cast(IntegratorMethod | None, method)
+        )
+
+        t_local = t0
+        for _ in range(steps):
+            if resolved_method == "rk4":
+                updates: NodalUpdate = _integrate_rk4(
+                    graph, dt_step, t_local, n_jobs=n_jobs
+                )
+            else:
+                updates = _integrate_euler(graph, dt_step, t_local, n_jobs=n_jobs)
+
+            for n, (epi, dEPI_dt, d2epi) in updates.items():
+                nd = graph.nodes[n]
+                epi_kind = get_attr_str(nd, ALIAS_EPI_KIND, "")
+                set_attr(nd, ALIAS_EPI, epi)
+                if epi_kind:
+                    set_attr_str(nd, ALIAS_EPI_KIND, epi_kind)
+                set_attr(nd, ALIAS_DEPI, dEPI_dt)
+                set_attr(nd, ALIAS_D2EPI, d2epi)
+
+            t_local += dt_step
+
+        graph.graph["_t"] = t_local
 
 
 def update_epi_via_nodal_equation(
-    G,
+    G: TNFRGraph,
     *,
     dt: float | None = None,
     t: float | None = None,
     method: Literal["euler", "rk4"] | None = None,
+    n_jobs: int | None = None,
 ) -> None:
     """TNFR nodal equation.
 
@@ -224,32 +537,13 @@ def update_epi_via_nodal_equation(
     TNFR references: nodal equation (manual), νf/ΔNFR/EPI glossary, Γ operator.
     Side effects: caches dEPI and updates EPI via explicit integration.
     """
-    if not isinstance(
-        G, (nx.Graph, nx.DiGraph, nx.MultiGraph, nx.MultiDiGraph)
-    ):
-        raise TypeError("G must be a networkx graph instance")
-
-    dt_step, steps, t0, method = prepare_integration_params(G, dt, t, method)
-
-    t_local = t0
-    for _ in range(steps):
-        if method == "rk4":
-            updates = _integrate_rk4(G, dt_step, t_local)
-        else:
-            updates = _integrate_euler(G, dt_step, t_local)
-
-        for n, (epi, dEPI_dt, d2epi) in updates.items():
-            nd = G.nodes[n]
-            epi_kind = get_attr_str(nd, ALIAS_EPI_KIND, "")
-            set_attr(nd, ALIAS_EPI, epi)
-            if epi_kind:
-                set_attr_str(nd, ALIAS_EPI_KIND, epi_kind)
-            set_attr(nd, ALIAS_DEPI, dEPI_dt)
-            set_attr(nd, ALIAS_D2EPI, d2epi)
-
-        t_local += dt_step
-
-    G.graph["_t"] = t_local
+    DefaultIntegrator().integrate(
+        G,
+        dt=dt,
+        t=t,
+        method=method,
+        n_jobs=n_jobs,
+    )
 
 
 def _node_state(nd: dict[str, Any]) -> tuple[float, float, float, float]:

tnfr/dynamics/integrators.pyi

@@ -0,0 +1,35 @@
+from typing import Literal
+
+from tnfr.types import TNFRGraph
+
+__all__: tuple[str, ...]
+
+class AbstractIntegrator:
+    def integrate(
+        self,
+        graph: TNFRGraph,
+        *,
+        dt: float | None = ...,
+        t: float | None = ...,
+        method: str | None = ...,
+        n_jobs: int | None = ...,
+    ) -> None: ...
+
+class DefaultIntegrator(AbstractIntegrator):
+    def __init__(self) -> None: ...
+
+def prepare_integration_params(
+    G: TNFRGraph,
+    dt: float | None = ...,
+    t: float | None = ...,
+    method: Literal["euler", "rk4"] | None = ...,
+) -> tuple[float, int, float, Literal["euler", "rk4"]]: ...
+
+def update_epi_via_nodal_equation(
+    G: TNFRGraph,
+    *,
+    dt: float | None = ...,
+    t: float | None = ...,
+    method: Literal["euler", "rk4"] | None = ...,
+    n_jobs: int | None = ...,
+) -> None: ...