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

tnfr/mathematics/transforms.py

@@ -0,0 +1,305 @@
+"""Canonical transform contracts for TNFR coherence tooling.
+
+This module intentionally provides *contracts* rather than concrete
+implementations.  Phase 2 of the mathematics roadmap will plug the actual
+algorithms into these helpers.  Until then, the functions below raise
+``NotImplementedError`` with descriptive guidance so downstream modules know
+which structural guarantees each helper must provide.
+
+The three exposed contracts cover:
+
+``build_isometry_factory``
+    Expected to output callables that embed or project states while preserving
+    the TNFR structural metric.  Implementations must return operators whose
+    adjoint composes to identity inside the target Hilbert or Banach space so
+    no coherence is lost during modal changes.
+
+``validate_norm_preservation``
+    Should perform diagnostic checks that a provided transform keeps the
+    νf-aligned norm invariant (within tolerance) across representative states.
+    Validation must surface informative errors so simulation pipelines can
+    gate potentially destructive transforms before they act on an EPI.
+
+``ensure_coherence_monotonicity``
+    Designed to assert that a transform (or sequence thereof) does not break
+    the monotonic coherence requirements captured in the repo-wide invariants.
+    Implementations should report any drop in ``C(t)`` outside authorised
+    dissonance windows and annotate the offending timestep to ease triage.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Iterable,
+    Mapping,
+    Protocol,
+    Sequence,
+    Union,
+    runtime_checkable,
+)
+
+import numpy as np
+
+from .epi import BEPIElement
+
+if TYPE_CHECKING:
+    from .spaces import BanachSpaceEPI
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "CoherenceMonotonicityReport",
+    "CoherenceViolation",
+    "IsometryFactory",
+    "build_isometry_factory",
+    "validate_norm_preservation",
+    "ensure_coherence_monotonicity",
+]
+
+
+@runtime_checkable
+class IsometryFactory(Protocol):
+    """Callable creating isometric transforms aligned with TNFR semantics.
+
+    Implementations produced by :func:`build_isometry_factory` must accept a
+    structural basis (modal decomposition, eigenvectors, or similar spectral
+    anchors) and return a transform that preserves both the vector norm and the
+    encoded coherence structure.  The returned callable should accept the raw
+    state data and emit the mapped state in the target representation while
+    guaranteeing ``T* · T == I`` on the relevant space.
+    """
+
+    def __call__(
+        self,
+        *,
+        basis: Sequence[Sequence[complex]] | None = None,
+        enforce_phase: bool = True,
+    ) -> Callable[[Sequence[complex]], Sequence[complex]]:
+        """Return an isometric transform for the provided basis."""
+
+
+def build_isometry_factory(
+    *,
+    source_dimension: int,
+    target_dimension: int,
+    allow_expansion: bool = False,
+) -> IsometryFactory:
+    """Create a factory for constructing TNFR-aligned isometries.
+
+    Parameters
+    ----------
+    source_dimension:
+        Dimensionality of the input structural space.
+    target_dimension:
+        Dimensionality of the destination structural space.  When the target
+        dimension is larger than the source, implementations must specify how
+        coherence is embedded without dilution.
+    allow_expansion:
+        Flag indicating whether the isometry may expand into a higher
+        dimensional space (still norm-preserving via padding and phase guards).
+
+    Returns
+    -------
+    IsometryFactory
+        A callable that can produce concrete isometries on demand once a basis
+        or spectral frame is available.
+    """
+
+    raise NotImplementedError(
+        "Phase 2 will provide the canonical TNFR isometry factory; "
+        "current stage only documents the expected contract."
+    )
+
+
+def validate_norm_preservation(
+    transform: Callable[[Sequence[complex]], Sequence[complex]],
+    *,
+    probes: Iterable[Sequence[complex]],
+    metric: Callable[[Sequence[complex]], float],
+    atol: float = 1e-9,
+) -> None:
+    """Assert that a transform preserves the TNFR structural norm.
+
+    The validator should iterate through ``probes`` (representative EPI states)
+    and confirm that applying ``transform`` leaves the provided ``metric``
+    unchanged within ``atol``.  Any detected drift must be reported via
+    exceptions that include the offending probe and the measured deviation so
+    callers can attribute potential coherence loss to specific conditions.
+    """
+
+    raise NotImplementedError(
+        "Norm preservation checks will be introduced in Phase 2; implementers "
+        "should ensure transform(metric(state)) == metric(state) within atol."
+    )
+
+
+@dataclass(frozen=True)
+class CoherenceViolation:
+    """Details about a monotonicity violation detected in a coherence trace."""
+
+    index: int
+    previous_value: float
+    current_value: float
+    tolerated_drop: float
+    drop: float
+    kind: str
+
+
+@dataclass(frozen=True)
+class CoherenceMonotonicityReport:
+    """Structured report generated by :func:`ensure_coherence_monotonicity`."""
+
+    coherence_values: tuple[float, ...]
+    violations: tuple[CoherenceViolation, ...]
+    allow_plateaus: bool
+    tolerated_drop: float
+    atol: float
+
+    @property
+    def is_monotonic(self) -> bool:
+        """Return ``True`` when no violations were recorded."""
+
+        return not self.violations
+
+
+def _as_coherence_values(
+    coherence_series: Sequence[Union[float, BEPIElement]],
+    *,
+    space: "BanachSpaceEPI" | None,
+    norm_kwargs: Mapping[str, float],
+) -> tuple[float, ...]:
+    if not coherence_series:
+        raise ValueError("coherence_series must contain at least one entry.")
+
+    first = coherence_series[0]
+    if isinstance(first, BEPIElement):
+        from .spaces import BanachSpaceEPI  # Local import to avoid circular dependency
+
+        working_space = space if space is not None else BanachSpaceEPI()
+        values = []
+        for element in coherence_series:
+            if not isinstance(element, BEPIElement):
+                raise TypeError(
+                    "All entries must be BEPIElement instances when the series contains BEPI data.",
+                )
+            value = working_space.coherence_norm(
+                element.f_continuous,
+                element.a_discrete,
+                x_grid=element.x_grid,
+                **norm_kwargs,
+            )
+            values.append(float(value))
+        return tuple(values)
+
+    values = []
+    for value in coherence_series:
+        if isinstance(value, BEPIElement):
+            raise TypeError(
+                "All entries must be numeric when the series is treated as coherence values.",
+            )
+        numeric = float(value)
+        if not np.isfinite(numeric):
+            raise ValueError("Coherence values must be finite numbers.")
+        values.append(numeric)
+    return tuple(values)
+
+
+def ensure_coherence_monotonicity(
+    coherence_series: Sequence[Union[float, BEPIElement]],
+    *,
+    allow_plateaus: bool = True,
+    tolerated_drop: float = 0.0,
+    atol: float = 1e-9,
+    space: "BanachSpaceEPI" | None = None,
+    norm_kwargs: Mapping[str, float] | None = None,
+) -> CoherenceMonotonicityReport:
+    """Validate monotonic behaviour of coherence measurements ``C(t)``.
+
+    Parameters
+    ----------
+    coherence_series:
+        Ordered sequence of coherence measurements (as floats) or
+        :class:`BEPIElement` instances recorded after each transform
+        application.
+    allow_plateaus:
+        When ``True`` the contract tolerates flat segments, otherwise every
+        subsequent value must strictly increase.
+    tolerated_drop:
+        Maximum allowed temporary decrease in coherence, representing approved
+        dissonance windows.  Values greater than zero should only appear when a
+        higher-level scenario explicitly references controlled dissonance tests.
+
+    Returns
+    -------
+    CoherenceMonotonicityReport
+        Structured report describing the evaluated coherence trajectory and any
+        detected violations.  Callers can inspect ``report.is_monotonic`` to
+        determine whether the constraint holds.
+    """
+
+    if tolerated_drop < 0:
+        raise ValueError("tolerated_drop must be non-negative.")
+    if atol < 0:
+        raise ValueError("atol must be non-negative.")
+
+    if norm_kwargs is None:
+        norm_kwargs = {}
+
+    values = _as_coherence_values(
+        coherence_series, space=space, norm_kwargs=norm_kwargs
+    )
+
+    violations: list[CoherenceViolation] = []
+
+    for index in range(1, len(values)):
+        previous_value = values[index - 1]
+        current_value = values[index]
+        drop = previous_value - current_value
+
+        if current_value + tolerated_drop + atol < previous_value:
+            violation = CoherenceViolation(
+                index=index,
+                previous_value=previous_value,
+                current_value=current_value,
+                tolerated_drop=tolerated_drop,
+                drop=drop,
+                kind="drop",
+            )
+            violations.append(violation)
+            logger.warning(
+                "Coherence drop detected at step %s: previous=%s current=%s tolerated_drop=%s",
+                index,
+                previous_value,
+                current_value,
+                tolerated_drop,
+            )
+            continue
+
+        if not allow_plateaus and current_value <= previous_value + atol:
+            violation = CoherenceViolation(
+                index=index,
+                previous_value=previous_value,
+                current_value=current_value,
+                tolerated_drop=tolerated_drop,
+                drop=max(0.0, drop),
+                kind="plateau",
+            )
+            violations.append(violation)
+            logger.warning(
+                "Coherence plateau detected at step %s: previous=%s current=%s",
+                index,
+                previous_value,
+                current_value,
+            )
+
+    return CoherenceMonotonicityReport(
+        coherence_values=values,
+        violations=tuple(violations),
+        allow_plateaus=allow_plateaus,
+        tolerated_drop=tolerated_drop,
+        atol=atol,
+    )

tnfr/mathematics/transforms.pyi

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from .epi import BEPIElement
+from .spaces import BanachSpaceEPI
+from dataclasses import dataclass
+from typing import Callable, Iterable, Mapping, Protocol, Sequence
+
+__all__ = [
+    "CoherenceMonotonicityReport",
+    "CoherenceViolation",
+    "IsometryFactory",
+    "build_isometry_factory",
+    "validate_norm_preservation",
+    "ensure_coherence_monotonicity",
+]
+
+class IsometryFactory(Protocol):
+    def __call__(
+        self,
+        *,
+        basis: Sequence[Sequence[complex]] | None = None,
+        enforce_phase: bool = True,
+    ) -> Callable[[Sequence[complex]], Sequence[complex]]: ...
+
+def build_isometry_factory(
+    *, source_dimension: int, target_dimension: int, allow_expansion: bool = False
+) -> IsometryFactory: ...
+def validate_norm_preservation(
+    transform: Callable[[Sequence[complex]], Sequence[complex]],
+    *,
+    probes: Iterable[Sequence[complex]],
+    metric: Callable[[Sequence[complex]], float],
+    atol: float = 1e-09,
+) -> None: ...
+@dataclass(frozen=True)
+class CoherenceViolation:
+    index: int
+    previous_value: float
+    current_value: float
+    tolerated_drop: float
+    drop: float
+    kind: str
+
+@dataclass(frozen=True)
+class CoherenceMonotonicityReport:
+    coherence_values: tuple[float, ...]
+    violations: tuple[CoherenceViolation, ...]
+    allow_plateaus: bool
+    tolerated_drop: float
+    atol: float
+    @property
+    def is_monotonic(self) -> bool: ...
+
+def ensure_coherence_monotonicity(
+    coherence_series: Sequence[float | BEPIElement],
+    *,
+    allow_plateaus: bool = True,
+    tolerated_drop: float = 0.0,
+    atol: float = 1e-09,
+    space: BanachSpaceEPI | None = None,
+    norm_kwargs: Mapping[str, float] | None = None,
+) -> CoherenceMonotonicityReport: ...

tnfr/metrics/__init__.py

@@ -0,0 +1,79 @@
+"""Registerable metrics."""
+
+from __future__ import annotations
+
+from .cache_utils import (
+    CacheStats,
+    configure_hot_path_caches,
+    get_cache_config,
+    log_cache_metrics,
+)
+from .coherence import (
+    coherence_matrix,
+    local_phase_sync,
+    local_phase_sync_weighted,
+    register_coherence_callbacks,
+)
+from .core import register_metrics_callbacks
+from .diagnosis import (
+    dissonance_events,
+    register_diagnosis_callbacks,
+)
+from .emergence import (
+    compute_bifurcation_rate,
+    compute_emergence_index,
+    compute_metabolic_efficiency,
+    compute_structural_complexity,
+)
+from .export import export_metrics
+from .learning_metrics import (
+    compute_consolidation_index,
+    compute_learning_efficiency,
+    compute_learning_plasticity,
+    glyph_history_to_operator_names,
+)
+from .phase_compatibility import (
+    compute_network_phase_alignment,
+    compute_phase_coupling_strength,
+    is_phase_compatible,
+)
+from .reporting import (
+    Tg_by_node,
+    Tg_global,
+    build_metrics_summary,
+    glyph_top,
+    glyphogram_series,
+    latency_series,
+)
+
+__all__ = (
+    "register_metrics_callbacks",
+    "Tg_global",
+    "Tg_by_node",
+    "latency_series",
+    "glyphogram_series",
+    "glyph_top",
+    "build_metrics_summary",
+    "coherence_matrix",
+    "local_phase_sync",
+    "local_phase_sync_weighted",
+    "register_coherence_callbacks",
+    "register_diagnosis_callbacks",
+    "dissonance_events",
+    "export_metrics",
+    "CacheStats",
+    "configure_hot_path_caches",
+    "get_cache_config",
+    "log_cache_metrics",
+    "compute_learning_plasticity",
+    "compute_consolidation_index",
+    "compute_learning_efficiency",
+    "glyph_history_to_operator_names",
+    "compute_structural_complexity",
+    "compute_bifurcation_rate",
+    "compute_metabolic_efficiency",
+    "compute_emergence_index",
+    "compute_phase_coupling_strength",
+    "is_phase_compatible",
+    "compute_network_phase_alignment",
+)

tnfr/metrics/__init__.pyi

@@ -0,0 +1,20 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+Tg_by_node: Any
+Tg_global: Any
+build_metrics_summary: Any
+coherence_matrix: Any
+dissonance_events: Any
+export_metrics: Any
+glyph_top: Any
+glyphogram_series: Any
+latency_series: Any
+local_phase_sync: Any
+local_phase_sync_weighted: Any
+register_coherence_callbacks: Any
+register_diagnosis_callbacks: Any
+register_metrics_callbacks: Any

tnfr/metrics/buffer_cache.py

@@ -0,0 +1,163 @@
+"""Unified buffer cache for TNFR metrics hot paths.
+
+This module consolidates buffer management across hot path computations
+(Sense index, coherence, ΔNFR) to eliminate duplication and ensure consistent
+cache key patterns and invalidation strategies.
+
+Cache Key Structure
+-------------------
+All buffer caches use a tuple key: ``(key_prefix, count, buffer_count)``
+
+This ensures:
+- Collision avoidance between different computations (via unique key_prefix)
+- Automatic invalidation on graph topology changes (via edge_version_cache)
+- Efficient cache lookups without hash collisions
+
+Common Key Prefixes
+-------------------
+- ``_si_buffers``: Sense index main computation buffers
+- ``_si_chunk_workspace``: Si chunked processing scratch space
+- ``_si_neighbor_buffers``: Si neighbor phase aggregation buffers
+- ``_coherence_temp``: Coherence matrix temporary buffers
+- ``_dnfr_prep_buffers``: ΔNFR preparation workspace
+
+See docs/CACHING_STRATEGY.md for complete cache documentation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import GraphLike
+from ..utils import edge_version_cache, get_graph
+
+__all__ = ("ensure_numpy_buffers",)
+
+
+def ensure_numpy_buffers(
+    G: GraphLike,
+    *,
+    key_prefix: str,
+    count: int,
+    buffer_count: int,
+    np: Any,
+    dtype: Any = None,
+    max_cache_entries: int | None = 128,
+) -> tuple[Any, ...]:
+    """Return reusable NumPy buffers with unified caching strategy.
+
+    This function centralizes buffer allocation for vectorized computations,
+    ensuring consistent cache key structure and automatic invalidation on
+    topology changes. Buffers are tied to the graph's edge version and
+    automatically cleared when edges are added or removed.
+
+    Cache Behavior
+    --------------
+    - **Key**: ``(key_prefix, count, buffer_count)`` ensures uniqueness
+    - **Invalidation**: Automatic on edge version changes
+    - **Capacity**: Controlled by ``max_cache_entries`` parameter
+    - **Override**: Graph-level config via ``_cache_config['buffer_max_entries']``
+
+    Parameters
+    ----------
+    G : GraphLike
+        Graph whose edge version controls cache invalidation.
+    key_prefix : str
+        Prefix for the cache key, e.g. ``"_si_buffers"`` or ``"_coherence_temp"``.
+        Must be unique per computation to avoid key collisions. See module
+        docstring for standard prefixes.
+    count : int
+        Number of elements per buffer. Typically set to node count for
+        node-level computations or edge count for edge-level operations.
+    buffer_count : int
+        Number of buffers to allocate. Each buffer is independent and can be
+        used for different intermediate values in the computation.
+    np : Any
+        NumPy module or compatible array backend. Must support ``np.empty``.
+    dtype : Any, optional
+        Data type for the buffers. Default: ``float``.
+    max_cache_entries : int or None, optional
+        Maximum number of cached buffer sets for this key prefix. Default: ``128``.
+        Set to ``None`` for unlimited cache size (use with caution on large graphs).
+        Can be overridden globally via graph-level configuration.
+
+    Returns
+    -------
+    tuple[Any, ...]
+        Tuple of ``buffer_count`` NumPy arrays each sized to ``count`` elements.
+        Arrays are reused from cache when available, avoiding repeated allocation.
+
+    Notes
+    -----
+    This function consolidates buffer allocation patterns across Si computation,
+    coherence matrix computation, and ΔNFR preparation. By centralizing buffer
+    management, we ensure consistent cache key naming, avoid duplication, and
+    maintain coherent cache invalidation when the graph edge structure changes.
+
+    The buffer allocation pattern follows TNFR caching principles:
+    1. **Determinism**: Same graph topology → same cached buffers
+    2. **Coherence**: Edge changes → automatic cache invalidation
+    3. **Efficiency**: Reuse eliminates allocation overhead in hot loops
+
+    Performance Considerations
+    --------------------------
+    - Cache hits avoid O(n) allocation overhead
+    - Memory cost: O(buffer_count * count * sizeof(dtype)) per cache entry
+    - Recommended for buffers reused across multiple computation steps
+    - Consider chunked processing for very large graphs (n > 100k nodes)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import networkx as nx
+    >>> G = nx.Graph([(0, 1)])
+    >>> buffers = ensure_numpy_buffers(
+    ...     G, key_prefix="_test", count=10, buffer_count=3, np=np
+    ... )
+    >>> len(buffers)
+    3
+    >>> buffers[0].shape
+    (10,)
+    >>> all(isinstance(buf, np.ndarray) for buf in buffers)
+    True
+
+    Allocate workspace for a computation with 100 nodes:
+
+    >>> G_large = nx.complete_graph(100)
+    >>> workspace = ensure_numpy_buffers(
+    ...     G_large,
+    ...     key_prefix="_my_computation",
+    ...     count=100,
+    ...     buffer_count=2,
+    ...     np=np
+    ... )
+    >>> workspace[0].size == 100
+    True
+
+    See Also
+    --------
+    edge_version_cache : Underlying cache mechanism
+    configure_hot_path_caches : Global cache configuration
+    """
+    # Allow graph-level override of max_cache_entries
+    graph = get_graph(G)
+    cache_config = graph.get("_cache_config")
+    if isinstance(cache_config, dict) and max_cache_entries is not None:
+        override = cache_config.get("buffer_max_entries")
+        if override is not None:
+            max_cache_entries = int(override)
+
+    if dtype is None:
+        dtype = float
+    if count <= 0:
+        count = 1
+
+    def builder() -> tuple[Any, ...]:
+        return tuple(np.empty(count, dtype=dtype) for _ in range(buffer_count))
+
+    return edge_version_cache(
+        G,
+        (key_prefix, count, buffer_count),
+        builder,
+        max_entries=max_cache_entries,
+    )

tnfr/metrics/buffer_cache.pyi

@@ -0,0 +1,24 @@
+"""Unified buffer cache for TNFR metrics hot paths.
+
+This module consolidates buffer management across hot path computations
+(Sense index, coherence, ΔNFR) to eliminate duplication and ensure consistent
+cache key patterns and invalidation strategies.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import GraphLike
+
+__all__ = ("ensure_numpy_buffers",)
+
+def ensure_numpy_buffers(
+    G: GraphLike,
+    *,
+    key_prefix: str,
+    count: int,
+    buffer_count: int,
+    np: Any,
+    dtype: Any = None,
+) -> tuple[Any, ...]: ...