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

tnfr/node.pyi

@@ -1,8 +1,17 @@
 from __future__ import annotations
 
-from collections.abc import Hashable, Iterable, MutableMapping
+from collections.abc import Hashable, Iterable, MutableMapping, Sequence
 from typing import Any, Callable, Optional, Protocol, SupportsFloat, TypeVar
 
+import numpy as np
+
+from .mathematics import (
+    CoherenceOperator,
+    FrequencyOperator,
+    HilbertSpace,
+    NFRValidator,
+    StateProjector,
+)
 from .types import (
     CouplingWeight,
     DeltaNFR,
@@ -19,7 +28,6 @@ T = TypeVar("T")
 
 __all__ = ("NodeNX", "NodeProtocol", "add_edge")
 
-
 class AttrSpec:
     aliases: tuple[str, ...]
     default: Any
@@ -31,7 +39,6 @@ class AttrSpec:
 
     def build_property(self) -> property: ...
 
-
 ALIAS_EPI: tuple[str, ...]
 ALIAS_VF: tuple[str, ...]
 ALIAS_THETA: tuple[str, ...]
@@ -42,14 +49,11 @@ ALIAS_D2EPI: tuple[str, ...]
 
 ATTR_SPECS: dict[str, AttrSpec]
 
-
 def _add_edge_common(
     n1: NodeId,
     n2: NodeId,
     weight: CouplingWeight | SupportsFloat | str,
 ) -> Optional[CouplingWeight]: ...
-
-
 def add_edge(
     graph: TNFRGraph,
     n1: NodeId,
@@ -58,7 +62,6 @@ def add_edge(
     overwrite: bool = ...,
 ) -> None: ...
 
-
 class NodeProtocol(Protocol):
     EPI: EPIValue
     vf: StructuralFrequency
@@ -70,11 +73,8 @@ class NodeProtocol(Protocol):
     graph: MutableMapping[str, Any]
 
     def neighbors(self) -> Iterable[NodeProtocol | Hashable]: ...
-
     def _glyph_storage(self) -> MutableMapping[str, object]: ...
-
     def has_edge(self, other: NodeProtocol) -> bool: ...
-
     def add_edge(
         self,
         other: NodeProtocol,
@@ -82,70 +82,72 @@ class NodeProtocol(Protocol):
         *,
         overwrite: bool = ...,
     ) -> None: ...
-
     def offset(self) -> int: ...
-
     def all_nodes(self) -> Iterable[NodeProtocol]: ...
 
-
 class NodeNX(NodeProtocol):
     G: TNFRGraph
     n: NodeId
     graph: MutableMapping[str, Any]
-
-    def __init__(self, G: TNFRGraph, n: NodeId) -> None: ...
-
+    state_projector: StateProjector
+    hilbert_space: HilbertSpace
+    coherence_operator: CoherenceOperator | None
+    frequency_operator: FrequencyOperator | None
+    coherence_threshold: float | None
+    validator: NFRValidator | None
+    rng: np.random.Generator | None
+
+    def __init__(
+        self,
+        G: TNFRGraph,
+        n: NodeId,
+        *,
+        state_projector: StateProjector | None = ...,
+        enable_math_validation: Optional[bool] = ...,
+        hilbert_space: HilbertSpace | None = ...,
+        coherence_operator: CoherenceOperator | None = ...,
+        coherence_dim: int | None = ...,
+        coherence_spectrum: Sequence[float] | np.ndarray | None = ...,
+        coherence_c_min: float | None = ...,
+        frequency_operator: FrequencyOperator | None = ...,
+        frequency_matrix: Sequence[Sequence[complex]] | np.ndarray | None = ...,
+        coherence_threshold: float | None = ...,
+        validator: NFRValidator | None = ...,
+        rng: np.random.Generator | None = ...,
+    ) -> None: ...
     @classmethod
     def from_graph(cls, G: TNFRGraph, n: NodeId) -> "NodeNX": ...
-
     def _glyph_storage(self) -> MutableMapping[str, Any]: ...
-
     @property
     def EPI(self) -> EPIValue: ...
-
     @EPI.setter
     def EPI(self, value: EPIValue) -> None: ...
-
     @property
     def vf(self) -> StructuralFrequency: ...
-
     @vf.setter
     def vf(self, value: StructuralFrequency) -> None: ...
-
     @property
     def theta(self) -> Phase: ...
-
     @theta.setter
     def theta(self, value: Phase) -> None: ...
-
     @property
     def Si(self) -> SenseIndex: ...
-
     @Si.setter
     def Si(self, value: SenseIndex) -> None: ...
-
     @property
     def epi_kind(self) -> str: ...
-
     @epi_kind.setter
     def epi_kind(self, value: str) -> None: ...
-
     @property
     def dnfr(self) -> DeltaNFR: ...
-
     @dnfr.setter
     def dnfr(self, value: DeltaNFR) -> None: ...
-
     @property
     def d2EPI(self) -> SecondDerivativeEPI: ...
-
     @d2EPI.setter
     def d2EPI(self, value: SecondDerivativeEPI) -> None: ...
-
     def neighbors(self) -> Iterable[NodeId]: ...
-
     def has_edge(self, other: NodeProtocol) -> bool: ...
-
     def add_edge(
         self,
         other: NodeProtocol,
@@ -153,9 +155,24 @@ class NodeNX(NodeProtocol):
         *,
         overwrite: bool = ...,
     ) -> None: ...
-
     def offset(self) -> int: ...
-
     def all_nodes(self) -> Iterable[NodeProtocol]: ...
-
-
+    def run_sequence_with_validation(
+        self,
+        ops: Iterable[Callable[[TNFRGraph, NodeId], None]],
+        *,
+        projector: StateProjector | None = ...,
+        hilbert_space: HilbertSpace | None = ...,
+        coherence_operator: CoherenceOperator | None = ...,
+        coherence_dim: int | None = ...,
+        coherence_spectrum: Sequence[float] | np.ndarray | None = ...,
+        coherence_c_min: float | None = ...,
+        coherence_threshold: float | None = ...,
+        frequency_operator: FrequencyOperator | None = ...,
+        frequency_matrix: Sequence[Sequence[complex]] | np.ndarray | None = ...,
+        validator: NFRValidator | None = ...,
+        enforce_frequency_positivity: bool | None = ...,
+        enable_validation: bool | None = ...,
+        rng: np.random.Generator | None = ...,
+        log_metrics: bool = ...,
+    ) -> dict[str, Any]: ...

tnfr/observers.py

@@ -2,30 +2,31 @@
 
 from __future__ import annotations
 
+import statistics
 from collections.abc import Mapping
 from functools import partial
-import statistics
 from statistics import StatisticsError, pvariance
 
 from .alias import get_theta_attr
-from .helpers.numeric import angle_diff
 from .callback_utils import CallbackEvent, callback_manager
+from .config.constants import GLYPH_GROUPS
+from .gamma import kuramoto_R_psi
 from .glyph_history import (
-    ensure_history,
-    count_glyphs,
     append_metric,
+    count_glyphs,
+    ensure_history,
 )
+from .utils import angle_diff
+from .metrics.common import compute_coherence
 from .types import Glyph, GlyphLoadDistribution, TNFRGraph
 from .utils import (
     get_logger,
     get_numpy,
     mix_groups,
     normalize_counter,
-    validate_window,
 )
-from .config.constants import GLYPH_GROUPS
-from .gamma import kuramoto_R_psi
-from .metrics.common import compute_coherence
+from .validation import validate_window
+from .telemetry import ensure_nu_f_telemetry, record_nu_f_window
 
 __all__ = (
     "attach_standard_observer",
@@ -58,15 +59,114 @@ _STD_CALLBACKS = {
     CallbackEvent.BEFORE_STEP.value: partial(_std_log, "before"),
     CallbackEvent.AFTER_STEP.value: partial(_std_log, "after"),
     CallbackEvent.ON_REMESH.value: partial(_std_log, "remesh"),
+    CallbackEvent.CACHE_METRICS.value: partial(_std_log, "cache"),
 }
 
 
+_REORG_STATE_KEY = "_std_observer_reorg"
+
+
+def _resolve_reorg_state(G: TNFRGraph) -> dict[str, object]:
+    state = G.graph.get(_REORG_STATE_KEY)
+    if not isinstance(state, dict):
+        state = {}
+        G.graph[_REORG_STATE_KEY] = state
+    return state
+
+
+def _before_step_reorg(G: TNFRGraph, ctx: Mapping[str, object] | None) -> None:
+    """Capture structural time metadata before the step starts."""
+
+    ensure_nu_f_telemetry(G, confidence_level=None)
+    state = _resolve_reorg_state(G)
+    step_idx = ctx.get("step") if ctx else None
+    try:
+        state["step"] = int(step_idx) if step_idx is not None else None
+    except (TypeError, ValueError):
+        state["step"] = None
+    start_t = float(G.graph.get("_t", 0.0))
+    state["start_t"] = start_t
+    dt_raw = ctx.get("dt") if ctx else None
+    try:
+        state["dt"] = float(dt_raw) if dt_raw is not None else None
+    except (TypeError, ValueError):
+        state["dt"] = None
+
+
+def _after_step_reorg(G: TNFRGraph, ctx: Mapping[str, object] | None) -> None:
+    """Record the reorganisation window for νf telemetry."""
+
+    state = _resolve_reorg_state(G)
+    pending_step = state.get("step")
+    ctx_step = ctx.get("step") if ctx else None
+    if pending_step is not None and ctx_step is not None and pending_step != ctx_step:
+        # Ignore mismatched callbacks to avoid double counting.
+        return
+
+    try:
+        start_t = float(state.get("start_t", float(G.graph.get("_t", 0.0))))
+    except (TypeError, ValueError):
+        start_t = float(G.graph.get("_t", 0.0))
+    end_t = float(G.graph.get("_t", start_t))
+    dt_raw = state.get("dt")
+    try:
+        duration = float(dt_raw) if dt_raw is not None else end_t - start_t
+    except (TypeError, ValueError):
+        duration = end_t - start_t
+    if duration <= 0.0:
+        duration = end_t - start_t
+    if duration <= 0.0:
+        return
+
+    stable_frac = ctx.get("stable_frac") if ctx else None
+    if stable_frac is None:
+        hist = ensure_history(G)
+        series = hist.get("stable_frac", [])
+        stable_frac = series[-1] if series else None
+    try:
+        stable_frac_f = float(stable_frac) if stable_frac is not None else None
+    except (TypeError, ValueError):
+        stable_frac_f = None
+    total_nodes = G.number_of_nodes()
+    if stable_frac_f is None:
+        reorganisations = total_nodes
+    else:
+        frac = min(max(stable_frac_f, 0.0), 1.0)
+        stable_nodes = int(round(frac * total_nodes))
+        reorganisations = max(total_nodes - stable_nodes, 0)
+
+    record_nu_f_window(
+        G,
+        reorganisations,
+        duration,
+        start=start_t,
+        end=end_t,
+    )
+    state["last_duration"] = duration
+    state["last_reorganisations"] = reorganisations
+    state["last_end_t"] = end_t
+    state["step"] = None
+
+
 def attach_standard_observer(G: TNFRGraph) -> TNFRGraph:
     """Register standard callbacks: before_step, after_step, on_remesh."""
     if G.graph.get("_STD_OBSERVER"):
         return G
     for event, fn in _STD_CALLBACKS.items():
         callback_manager.register_callback(G, event, fn)
+    callback_manager.register_callback(
+        G,
+        CallbackEvent.BEFORE_STEP.value,
+        _before_step_reorg,
+        name="std_reorg_before",
+    )
+    callback_manager.register_callback(
+        G,
+        CallbackEvent.AFTER_STEP.value,
+        _after_step_reorg,
+        name="std_reorg_after",
+    )
+    ensure_nu_f_telemetry(G, confidence_level=None)
     G.graph["_STD_OBSERVER"] = "attached"
     return G
 
@@ -90,6 +190,8 @@ def phase_sync(
     R: float | None = None,
     psi: float | None = None,
 ) -> float:
+    """Return a [0, 1] synchrony index derived from phase dispersion."""
+
     if not _ensure_nodes(G):
         return 1.0
     if R is None or psi is None:
@@ -98,6 +200,7 @@ def phase_sync(
             R = R_calc
         if psi is None:
             psi = psi_calc
+
     def _theta(nd: Mapping[str, object]) -> float:
         value = get_theta_attr(nd, 0.0)
         return float(value) if value is not None else 0.0

tnfr/observers.pyi

@@ -10,37 +10,22 @@ __all__: tuple[str, ...]
 DEFAULT_GLYPH_LOAD_SPAN: Final[int]
 DEFAULT_WBAR_SPAN: Final[int]
 
-
 def _std_log(kind: str, G: TNFRGraph, ctx: Mapping[str, object]) -> None: ...
-
-
 def attach_standard_observer(G: TNFRGraph) -> TNFRGraph: ...
-
-
 def _ensure_nodes(G: TNFRGraph) -> bool: ...
-
-
 def kuramoto_metrics(G: TNFRGraph) -> tuple[float, float]: ...
-
-
 def phase_sync(
     G: TNFRGraph,
     R: float | None = ...,
     psi: float | None = ...,
 ) -> float: ...
-
-
 def kuramoto_order(
     G: TNFRGraph,
     R: float | None = ...,
     psi: float | None = ...,
 ) -> float: ...
-
-
 def glyph_load(
     G: TNFRGraph,
     window: int | None = ...,
 ) -> GlyphLoadDistribution: ...
-
-
 def wbar(G: TNFRGraph, window: int | None = ...) -> float: ...

tnfr/ontosim.py

@@ -6,11 +6,12 @@ from collections import deque
 from typing import TYPE_CHECKING
 
 from .callback_utils import CallbackEvent
-from .constants import METRIC_DEFAULTS, inject_defaults, get_param
-from .dynamics import step as _step, run as _run
+from .constants import METRIC_DEFAULTS, get_param, inject_defaults
 from .dynamics import default_compute_delta_nfr
-from .initialization import init_node_attrs
+from .dynamics import run as _run
+from .dynamics import step as _step
 from .glyph_history import append_metric
+from .initialization import init_node_attrs
 from .utils import cached_import
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -46,9 +47,7 @@ def prepare_network(
         merge_overrides(G, **overrides)
     # Initialize history buffers
     ph_len = int(
-        G.graph.get(
-            "PHASE_HISTORY_MAXLEN", METRIC_DEFAULTS["PHASE_HISTORY_MAXLEN"]
-        )
+        G.graph.get("PHASE_HISTORY_MAXLEN", METRIC_DEFAULTS["PHASE_HISTORY_MAXLEN"])
     )
     hist_keys = [
         "C_steps",
@@ -127,6 +126,8 @@ def step(
     use_Si: bool = True,
     apply_glyphs: bool = True,
 ) -> None:
+    """Advance the ontosim runtime by a single step."""
+
     _step(G, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)
 
 
@@ -138,4 +139,6 @@ def run(
     use_Si: bool = True,
     apply_glyphs: bool = True,
 ) -> None:
+    """Advance the ontosim runtime ``steps`` times with optional overrides."""
+
     _run(G, steps=steps, dt=dt, use_Si=use_Si, apply_glyphs=apply_glyphs)

tnfr/ontosim.pyi

@@ -4,7 +4,6 @@ from .types import TNFRConfigValue, TNFRGraph
 
 __all__: tuple[str, ...]
 
-
 def prepare_network(
     G: TNFRGraph,
     *,
@@ -12,8 +11,6 @@ def prepare_network(
     override_defaults: bool = False,
     **overrides: TNFRConfigValue,
 ) -> TNFRGraph: ...
-
-
 def step(
     G: TNFRGraph,
     *,
@@ -21,8 +18,6 @@ def step(
     use_Si: bool = True,
     apply_glyphs: bool = True,
 ) -> None: ...
-
-
 def run(
     G: TNFRGraph,
     steps: int,