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

tnfr/dynamics/runtime.pyi

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from ..types import HistoryState, TNFRGraph
+from .aliases import (
+    ALIAS_DNFR as ALIAS_DNFR,
+    ALIAS_EPI as ALIAS_EPI,
+    ALIAS_SI as ALIAS_SI,
+    ALIAS_VF as ALIAS_VF,
+)
+from collections.abc import Mapping
+from typing import Any
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_SI",
+    "_normalize_job_overrides",
+    "_resolve_jobs_override",
+    "_prepare_dnfr",
+    "_update_nodes",
+    "_update_epi_hist",
+    "_maybe_remesh",
+    "_run_validators",
+    "_run_before_callbacks",
+    "_run_after_callbacks",
+    "step",
+    "run",
+]
+
+def _normalize_job_overrides(
+    job_overrides: Mapping[str, Any] | None,
+) -> dict[str, Any]: ...
+def _resolve_jobs_override(
+    overrides: Mapping[str, Any],
+    key: str,
+    graph_value: Any,
+    *,
+    allow_non_positive: bool,
+) -> int | None: ...
+def _run_before_callbacks(
+    G: TNFRGraph, *, step_idx: int, dt: float | None, use_Si: bool, apply_glyphs: bool
+) -> None: ...
+def _prepare_dnfr(
+    G: TNFRGraph, *, use_Si: bool, job_overrides: Mapping[str, Any] | None = None
+) -> None: ...
+def _update_nodes(
+    G: TNFRGraph,
+    *,
+    dt: float | None,
+    use_Si: bool,
+    apply_glyphs: bool,
+    step_idx: int,
+    hist: HistoryState,
+    job_overrides: Mapping[str, Any] | None = None,
+) -> None: ...
+def _update_epi_hist(G: TNFRGraph) -> None: ...
+def _maybe_remesh(G: TNFRGraph) -> None: ...
+def _run_validators(G: TNFRGraph) -> None: ...
+def _run_after_callbacks(G, *, step_idx: int) -> None: ...
+def step(
+    G: TNFRGraph,
+    *,
+    dt: float | None = None,
+    use_Si: bool = True,
+    apply_glyphs: bool = True,
+    n_jobs: Mapping[str, Any] | None = None,
+) -> None: ...
+def run(
+    G: TNFRGraph,
+    steps: int,
+    *,
+    dt: float | None = None,
+    use_Si: bool = True,
+    apply_glyphs: bool = True,
+    n_jobs: Mapping[str, Any] | None = None,
+) -> None: ...

tnfr/dynamics/sampling.py

@@ -0,0 +1,36 @@
+"""Sampling helpers used by runtime selectors and glyph application."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from ..rng import _rng_for_step, base_seed
+from ..types import NodeId, TNFRGraph
+from ..utils import cached_node_list
+
+__all__ = ("update_node_sample",)
+
+
+def update_node_sample(G: TNFRGraph, *, step: int) -> None:
+    """Refresh ``G.graph['_node_sample']`` with a random subset of nodes.
+
+    The sample is limited by ``UM_CANDIDATE_COUNT`` and refreshed every
+    simulation step. When the network is small (``< 50`` nodes) or the limit
+    is non‑positive, the full node set is used and sampling is effectively
+    disabled. A snapshot of nodes is cached via the NodeCache helper from
+    ``tnfr.utils`` stored in
+    ``G.graph['_node_list_cache']`` and reused across steps; it is only refreshed
+    when the graph size changes. Sampling operates directly on the cached
+    tuple of nodes.
+    """
+    graph = G.graph
+    limit = int(graph.get("UM_CANDIDATE_COUNT", 0))
+    nodes = cast(tuple[NodeId, ...], cached_node_list(G))
+    current_n = len(nodes)
+    if limit <= 0 or current_n < 50 or limit >= current_n:
+        graph["_node_sample"] = nodes
+        return
+
+    seed = base_seed(G)
+    rng = _rng_for_step(seed, step)
+    graph["_node_sample"] = rng.sample(nodes, limit)

tnfr/dynamics/sampling.pyi

@@ -0,0 +1,7 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+update_node_sample: Any