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

tnfr/dynamics/dnfr.pyi

@@ -1,6 +1,7 @@
 from typing import Any
 
 from tnfr.types import DeltaNFRHook, TNFRGraph
+from tnfr.utils.cache import DnfrCache as DnfrCache
 
 __all__: tuple[str, ...]
 
@@ -10,17 +11,9 @@ def default_compute_delta_nfr(
     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,
@@ -28,6 +21,4 @@ def set_delta_nfr_hook(
     name: str | None = ...,
     note: str | None = ...,
 ) -> None: ...
-
-
 def __getattr__(name: str) -> Any: ...

tnfr/dynamics/integrators.py

@@ -1,3 +1,5 @@
+"""Canonical ΔNFR integrators driving TNFR runtime evolution."""
+
 from __future__ import annotations
 
 import math
@@ -9,22 +11,20 @@ from typing import Any, Literal, cast
 
 import networkx as nx
 
-from ..constants import (
-    DEFAULTS,
-    get_aliases,
+from .._compat import TypeAlias
+from ..alias import collect_attr, get_attr, get_attr_str, set_attr, set_attr_str
+from ..constants import DEFAULTS
+from ..constants.aliases import (
+    ALIAS_D2EPI,
+    ALIAS_DEPI,
+    ALIAS_DNFR,
+    ALIAS_EPI,
+    ALIAS_EPI_KIND,
+    ALIAS_VF,
 )
 from ..gamma import _get_gamma_spec, eval_gamma
-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")
-ALIAS_DEPI = get_aliases("DEPI")
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_EPI_KIND = get_aliases("EPI_KIND")
-ALIAS_D2EPI = get_aliases("D2EPI")
+from ..utils import get_numpy, resolve_chunk_size
 
 __all__ = (
     "AbstractIntegrator",
@@ -63,9 +63,7 @@ def _gamma_worker(task: tuple[list[NodeId], float]) -> list[tuple[NodeId, float]
     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
-    ]
+    return [(node, float(eval_gamma(_PARALLEL_GRAPH, node, t))) for node in chunk]
 
 
 def _normalise_jobs(n_jobs: int | None, total: int) -> int | None:
@@ -86,7 +84,7 @@ 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]
+        yield nodes[idx : idx + chunk_size]
 
 
 def _apply_increment_chunk(
@@ -127,7 +125,12 @@ def _evaluate_gamma_map(
     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)))
+    approx_chunk = math.ceil(len(nodes) / (workers * 4)) if workers > 0 else None
+    chunk_size = resolve_chunk_size(
+        approx_chunk,
+        len(nodes),
+        minimum=1,
+    )
     mp_ctx = get_context("spawn")
     tasks = ((chunk, t) for chunk in _chunk_nodes(nodes, chunk_size))
 
@@ -153,9 +156,16 @@ def prepare_integration_params(
 ) -> 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
-    effective step, ``steps`` the number of substeps and ``t0`` the prepared
-    initial time.
+    The function raises :class:`TypeError` when ``dt`` cannot be coerced to a
+    number, :class:`ValueError` if ``dt`` is negative, and another
+    :class:`ValueError` when an unsupported method is requested.  When ``dt``
+    exceeds a positive ``DT_MIN`` stored on ``G`` the span is deterministically
+    subdivided into integer steps so that the resulting ``dt_step`` never falls
+    below that minimum threshold.
+
+    Returns ``(dt_step, steps, t0, method)`` where ``dt_step`` is the effective
+    step, ``steps`` the number of substeps and ``t0`` the prepared initial
+    time.
     """
     if dt is None:
         dt = float(G.graph.get("DT", DEFAULTS["DT"]))
@@ -173,20 +183,19 @@ def prepare_integration_params(
 
     method_value = (
         method
-        or G.graph.get(
-            "INTEGRATOR_METHOD", DEFAULTS.get("INTEGRATOR_METHOD", "euler")
-        )
+        or G.graph.get("INTEGRATOR_METHOD", DEFAULTS.get("INTEGRATOR_METHOD", "euler"))
     ).lower()
     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)))
+    steps = 1
     if dt_min > 0 and dt > dt_min:
-        steps = int(math.ceil(dt / dt_min))
-    else:
-        steps = 1
-    # ``steps`` is guaranteed to be ≥1 at this point
-    dt_step = dt / steps
+        ratio = dt / dt_min
+        steps = max(1, int(math.floor(ratio + 1e-12)))
+        if dt / steps < dt_min:
+            steps = int(math.ceil(ratio))
+    dt_step = dt / steps if steps else 0.0
 
     return dt_step, steps, t, cast(Literal["euler", "rk4"], method_value)
 
@@ -263,7 +272,12 @@ def _apply_increments(
     if workers is None:
         return dict(_apply_increment_chunk(payload, dt_step, method))
 
-    chunk_size = max(1, math.ceil(len(nodes) / (workers * 4)))
+    approx_chunk = math.ceil(len(nodes) / (workers * 4)) if workers > 0 else None
+    chunk_size = resolve_chunk_size(
+        approx_chunk,
+        len(nodes),
+        minimum=1,
+    )
     mp_ctx = get_context("spawn")
 
     results: NodalUpdate = {}
@@ -398,9 +412,7 @@ def _build_gamma_increments(
         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 = (
-            _evaluate_gamma_map(G, nodes, t_local, n_jobs=n_jobs),
-        )
+        gamma_maps = (_evaluate_gamma_map(G, nodes, t_local, n_jobs=n_jobs),)
 
     return _collect_nodal_increments(G, gamma_maps, method=method)
 
@@ -481,6 +493,8 @@ class DefaultIntegrator(AbstractIntegrator):
         method: str | None,
         n_jobs: int | None,
     ) -> None:
+        """Integrate the nodal equation updating EPI, ΔEPI and Δ²EPI."""
+
         if not isinstance(
             graph, (nx.Graph, nx.DiGraph, nx.MultiGraph, nx.MultiDiGraph)
         ):

tnfr/dynamics/integrators.pyi

@@ -24,7 +24,6 @@ def prepare_integration_params(
     t: float | None = ...,
     method: Literal["euler", "rk4"] | None = ...,
 ) -> tuple[float, int, float, Literal["euler", "rk4"]]: ...
-
 def update_epi_via_nodal_equation(
     G: TNFRGraph,
     *,