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

tnfr/dynamics/integrators.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any, Literal
+
+import networkx as nx  # type: ignore[import-untyped]
+
+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
+
+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")
+
+__all__ = (
+    "prepare_integration_params",
+    "update_epi_via_nodal_equation",
+)
+
+
+def prepare_integration_params(
+    G,
+    dt: float | None = None,
+    t: float | None = None,
+    method: Literal["euler", "rk4"] | None = None,
+):
+    """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.
+    """
+    if dt is None:
+        dt = float(G.graph.get("DT", DEFAULTS["DT"]))
+    else:
+        if not isinstance(dt, (int, float)):
+            raise TypeError("dt must be a number")
+        if dt < 0:
+            raise ValueError("dt must be non-negative")
+        dt = float(dt)
+
+    if t is None:
+        t = float(G.graph.get("_t", 0.0))
+    else:
+        t = float(t)
+
+    method = (
+        method
+        or G.graph.get(
+            "INTEGRATOR_METHOD", DEFAULTS.get("INTEGRATOR_METHOD", "euler")
+        )
+    ).lower()
+    if method 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)))
+    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
+
+    return dt_step, steps, t, method
+
+
+def _apply_increments(
+    G: Any,
+    dt_step: float,
+    increments: dict[Any, tuple[float, ...]],
+    *,
+    method: str,
+) -> dict[Any, tuple[float, float, float]]:
+    """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]
+        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)
+            dEPI_dt = k4
+        else:
+            (k1,) = ks
+            # Euler: EPIₙ₊₁ = EPIᵢ + Δt·k1 where k1 = νf·ΔNFR + Γ
+            epi = epi_i + 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
+
+
+def _collect_nodal_increments(
+    G: Any,
+    gamma_maps: tuple[dict[Any, float], ...],
+    *,
+    method: str,
+) -> dict[Any, tuple[float, ...]]:
+    """Combine node base state with staged Γ contributions.
+
+    ``gamma_maps`` must contain one entry for Euler integration and four for
+    RK4. The helper merges the structural frequency/ΔNFR base contribution
+    with the supplied Γ evaluations.
+    """
+
+    increments: dict[Any, tuple[float, ...]] = {}
+    for n, nd in G.nodes(data=True):
+        vf, dnfr, *_ = _node_state(nd)
+        base = vf * dnfr
+        gammas = [gm.get(n, 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] = (
+                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,)
+
+    return increments
+
+
+def _build_gamma_increments(
+    G: Any,
+    dt_step: float,
+    t_local: float,
+    *,
+    method: str,
+) -> dict[Any, tuple[float, ...]]:
+    """Evaluate Γ contributions and merge them with ``νf·ΔNFR`` base terms."""
+
+    if method == "rk4":
+        gamma_count = 4
+    elif method == "euler":
+        gamma_count = 1
+    else:
+        raise ValueError("method must be 'euler' or 'rk4'")
+
+    gamma_spec = G.graph.get("_gamma_spec")
+    if gamma_spec is None:
+        gamma_spec = _get_gamma_spec(G)
+
+    gamma_type = ""
+    if isinstance(gamma_spec, Mapping):
+        gamma_type = str(gamma_spec.get("type", "")).lower()
+
+    if gamma_type == "none":
+        gamma_maps = tuple({} 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}
+        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},)
+
+    return _collect_nodal_increments(G, gamma_maps, method=method)
+
+
+def _integrate_euler(G, dt_step: float, t_local: float):
+    """One explicit Euler integration step."""
+    increments = _build_gamma_increments(
+        G,
+        dt_step,
+        t_local,
+        method="euler",
+    )
+    return _apply_increments(G, dt_step, increments, method="euler")
+
+
+def _integrate_rk4(G, dt_step: float, t_local: float):
+    """One Runge–Kutta order-4 integration step."""
+    increments = _build_gamma_increments(
+        G,
+        dt_step,
+        t_local,
+        method="rk4",
+    )
+    return _apply_increments(G, dt_step, increments, method="rk4")
+
+
+def update_epi_via_nodal_equation(
+    G,
+    *,
+    dt: float | None = None,
+    t: float | None = None,
+    method: Literal["euler", "rk4"] | None = None,
+) -> None:
+    """TNFR nodal equation.
+
+    Implements the extended nodal equation:
+        ∂EPI/∂t = νf · ΔNFR(t) + Γi(R)
+
+    Where:
+      - EPI is the node's Primary Information Structure.
+      - νf is the node's structural frequency (Hz_str).
+      - ΔNFR(t) is the nodal gradient (reorganisation need), typically a mix
+        of components (e.g. phase θ, EPI, νf).
+      - Γi(R) is the optional network coupling as a function of Kuramoto order
+        ``R`` (see :mod:`gamma`), used to modulate network integration.
+
+    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
+
+
+def _node_state(nd: dict[str, Any]) -> tuple[float, float, float, float]:
+    """Return common node state attributes.
+
+    Extracts ``νf``, ``ΔNFR``, previous ``dEPI/dt`` and current ``EPI``
+    using alias helpers, providing ``0.0`` defaults when attributes are
+    missing.
+    """
+
+    vf = get_attr(nd, ALIAS_VF, 0.0)
+    dnfr = get_attr(nd, ALIAS_DNFR, 0.0)
+    dEPI_dt_prev = get_attr(nd, ALIAS_DEPI, 0.0)
+    epi_i = get_attr(nd, ALIAS_EPI, 0.0)
+    return vf, dnfr, dEPI_dt_prev, epi_i

tnfr/dynamics/sampling.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from ..cache import cached_node_list
+from ..rng import _rng_for_step, base_seed
+
+__all__ = ("update_node_sample",)
+
+
+def update_node_sample(G, *, 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 a
+    :class:`~tnfr.cache.NodeCache` instance 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 = 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/execution.py

@@ -0,0 +1,201 @@
+"""Execution helpers for canonical TNFR programs."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any, Optional
+
+import networkx as nx  # networkx is used at runtime
+
+from .collections_utils import (
+    MAX_MATERIALIZE_DEFAULT,
+    ensure_collection,
+    is_non_string_sequence,
+)
+from .constants import get_param
+from .dynamics import step
+from .flatten import _flatten
+from .glyph_history import ensure_history
+from .grammar import apply_glyph_with_grammar
+from .tokens import OpTag, TARGET, THOL, WAIT, Token
+from .types import Glyph
+
+Node = Any
+AdvanceFn = Callable[[Any], None]
+HandlerFn = Callable[
+    [nx.Graph, Any, Optional[list[Node]], deque, AdvanceFn],
+    Optional[list[Node]],
+]
+
+__all__ = [
+    "AdvanceFn",
+    "CANONICAL_PRESET_NAME",
+    "CANONICAL_PROGRAM_TOKENS",
+    "HANDLERS",
+    "_apply_glyph_to_targets",
+    "_record_trace",
+    "compile_sequence",
+    "basic_canonical_example",
+    "block",
+    "play",
+    "seq",
+    "target",
+    "wait",
+]
+
+
+CANONICAL_PRESET_NAME = "ejemplo_canonico"
+CANONICAL_PROGRAM_TOKENS: tuple[Token, ...] = (
+    Glyph.SHA,
+    Glyph.AL,
+    Glyph.RA,
+    Glyph.ZHIR,
+    Glyph.NUL,
+    Glyph.THOL,
+)
+
+
+def _window(G) -> int:
+    return int(get_param(G, "GLYPH_HYSTERESIS_WINDOW"))
+
+
+def _apply_glyph_to_targets(
+    G, g: Glyph | str, nodes: Optional[Iterable[Node]] = None
+):
+    """Apply ``g`` to ``nodes`` (or all nodes) respecting the grammar."""
+
+    nodes_iter = G.nodes() if nodes is None else nodes
+    w = _window(G)
+    apply_glyph_with_grammar(G, nodes_iter, g, w)
+
+
+def _advance(G, step_fn: AdvanceFn):
+    step_fn(G)
+
+
+def _record_trace(trace: deque, G, op: OpTag, **data) -> None:
+    trace.append({"t": float(G.graph.get("_t", 0.0)), "op": op.name, **data})
+
+
+def _advance_and_record(
+    G,
+    trace: deque,
+    label: OpTag,
+    step_fn: AdvanceFn,
+    *,
+    times: int = 1,
+    **data,
+) -> None:
+    for _ in range(times):
+        _advance(G, step_fn)
+    _record_trace(trace, G, label, **data)
+
+
+def _handle_target(
+    G, payload: TARGET, _curr_target, trace: deque, _step_fn: AdvanceFn
+):
+    """Handle a ``TARGET`` token and return the active node set."""
+
+    nodes_src = G.nodes() if payload.nodes is None else payload.nodes
+    nodes = ensure_collection(nodes_src, max_materialize=None)
+    curr_target = nodes if is_non_string_sequence(nodes) else tuple(nodes)
+    _record_trace(trace, G, OpTag.TARGET, n=len(curr_target))
+    return curr_target
+
+
+def _handle_wait(
+    G, steps: int, curr_target, trace: deque, step_fn: AdvanceFn
+):
+    _advance_and_record(G, trace, OpTag.WAIT, step_fn, times=steps, k=steps)
+    return curr_target
+
+
+def _handle_glyph(
+    G,
+    g: str,
+    curr_target,
+    trace: deque,
+    step_fn: AdvanceFn,
+    label: OpTag = OpTag.GLYPH,
+):
+    _apply_glyph_to_targets(G, g, curr_target)
+    _advance_and_record(G, trace, label, step_fn, g=g)
+    return curr_target
+
+
+def _handle_thol(
+    G, g, curr_target, trace: deque, step_fn: AdvanceFn
+):
+    return _handle_glyph(
+        G, g or Glyph.THOL.value, curr_target, trace, step_fn, label=OpTag.THOL
+    )
+
+
+HANDLERS: dict[OpTag, HandlerFn] = {
+    OpTag.TARGET: _handle_target,
+    OpTag.WAIT: _handle_wait,
+    OpTag.GLYPH: _handle_glyph,
+    OpTag.THOL: _handle_thol,
+}
+
+
+def play(
+    G, sequence: Sequence[Token], step_fn: Optional[AdvanceFn] = None
+) -> None:
+    """Execute a canonical sequence on graph ``G``."""
+
+    step_fn = step_fn or step
+
+    curr_target: Optional[list[Node]] = None
+
+    history = ensure_history(G)
+    maxlen = int(get_param(G, "PROGRAM_TRACE_MAXLEN"))
+    trace = history.get("program_trace")
+    if not isinstance(trace, deque) or trace.maxlen != maxlen:
+        trace = deque(trace or [], maxlen=maxlen)
+        history["program_trace"] = trace
+
+    for op, payload in _flatten(sequence):
+        handler: HandlerFn | None = HANDLERS.get(op)
+        if handler is None:
+            raise ValueError(f"Unknown operation: {op}")
+        curr_target = handler(G, payload, curr_target, trace, step_fn)
+
+
+def compile_sequence(
+    sequence: Iterable[Token] | Sequence[Token] | Any,
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+) -> list[tuple[OpTag, Any]]:
+    """Return the operations executed by :func:`play` for ``sequence``."""
+
+    return _flatten(sequence, max_materialize=max_materialize)
+
+
+def seq(*tokens: Token) -> list[Token]:
+    return list(tokens)
+
+
+def block(
+    *tokens: Token, repeat: int = 1, close: Optional[Glyph] = None
+) -> THOL:
+    return THOL(body=list(tokens), repeat=repeat, force_close=close)
+
+
+def target(nodes: Optional[Iterable[Node]] = None) -> TARGET:
+    return TARGET(nodes=nodes)
+
+
+def wait(steps: int = 1) -> WAIT:
+    return WAIT(steps=max(1, int(steps)))
+
+
+def basic_canonical_example() -> list[Token]:
+    """Reference canonical sequence.
+
+    Returns a copy of the canonical preset tokens to keep CLI defaults aligned
+    with :func:`tnfr.presets.get_preset`.
+    """
+
+    return list(CANONICAL_PROGRAM_TOKENS)