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

tnfr/node.py

@@ -1,31 +1,63 @@
 """Node utilities and structures for TNFR graphs."""
 
 from __future__ import annotations
+
+import copy
+import math
+from collections.abc import Hashable
+from dataclasses import dataclass
 from typing import (
     Any,
     Callable,
     Iterable,
+    Mapping,
     MutableMapping,
     Optional,
     Protocol,
+    Sequence,
     SupportsFloat,
     TypeVar,
 )
-from collections.abc import Hashable
-import math
-from dataclasses import dataclass
 
-from .constants import get_aliases
+import numpy as np
+
 from .alias import (
     get_attr,
-    get_theta_attr,
     get_attr_str,
+    get_theta_attr,
     set_attr,
     set_attr_str,
-    set_vf,
+    set_attr_generic,
     set_dnfr,
     set_theta,
+    set_vf,
 )
+from .config import context_flags, get_flags
+from .constants.aliases import (
+    ALIAS_D2EPI,
+    ALIAS_DNFR,
+    ALIAS_EPI,
+    ALIAS_EPI_KIND,
+    ALIAS_SI,
+    ALIAS_THETA,
+    ALIAS_VF,
+)
+from .mathematics import (
+    BasicStateProjector,
+    CoherenceOperator,
+    FrequencyOperator,
+    HilbertSpace,
+    NFRValidator,
+    StateProjector,
+)
+from .mathematics.operators_factory import make_coherence_operator, make_frequency_operator
+from .mathematics.runtime import (
+    coherence as runtime_coherence,
+    frequency_positive as runtime_frequency_positive,
+    normalized as runtime_normalized,
+    stable_unitary as runtime_stable_unitary,
+)
+from .locking import get_lock
 from .types import (
     CouplingWeight,
     DeltaNFR,
@@ -36,28 +68,26 @@ from .types import (
     SenseIndex,
     StructuralFrequency,
     TNFRGraph,
+    ZERO_BEPI_STORAGE,
+    ensure_bepi,
+    serialize_bepi,
 )
 from .utils import (
     cached_node_list,
     ensure_node_offset_map,
+    get_logger,
     increment_edge_version,
     supports_add_edge,
 )
-from .locking import get_lock
-
-ALIAS_EPI = get_aliases("EPI")
-ALIAS_VF = get_aliases("VF")
-ALIAS_THETA = get_aliases("THETA")
-ALIAS_SI = get_aliases("SI")
-ALIAS_EPI_KIND = get_aliases("EPI_KIND")
-ALIAS_DNFR = get_aliases("DNFR")
-ALIAS_D2EPI = get_aliases("D2EPI")
 
 T = TypeVar("T")
 
 __all__ = ("NodeNX", "NodeProtocol", "add_edge")
 
 
+LOGGER = get_logger(__name__)
+
+
 @dataclass(frozen=True)
 class AttrSpec:
     """Configuration required to expose a ``networkx`` node attribute.
@@ -93,11 +123,43 @@ class AttrSpec:
         return property(fget, fset)
 
 
+# Canonical adapters for BEPI storage ------------------------------------
+
+
+def _epi_to_python(value: Any) -> EPIValue:
+    if value is None:
+        raise ValueError("EPI attribute is required for BEPI nodes")
+    return ensure_bepi(value)
+
+
+def _epi_to_storage(value: Any) -> Mapping[str, tuple[complex, ...] | tuple[float, ...]]:
+    return serialize_bepi(value)
+
+
+def _get_bepi_attr(
+    mapping: Mapping[str, Any], aliases: tuple[str, ...], default: Any
+) -> Any:
+    return get_attr(mapping, aliases, default, conv=lambda obj: obj)
+
+
+def _set_bepi_attr(
+    mapping: MutableMapping[str, Any], aliases: tuple[str, ...], value: Any
+) -> Mapping[str, tuple[complex, ...] | tuple[float, ...]]:
+    return set_attr_generic(mapping, aliases, value, conv=lambda obj: obj)
+
+
 # Mapping of NodeNX attribute specifications used to generate property
 # descriptors. Each entry defines the keyword arguments passed to
 # ``AttrSpec.build_property`` for a given attribute name.
 ATTR_SPECS: dict[str, AttrSpec] = {
-    "EPI": AttrSpec(aliases=ALIAS_EPI),
+    "EPI": AttrSpec(
+        aliases=ALIAS_EPI,
+        default=ZERO_BEPI_STORAGE,
+        getter=_get_bepi_attr,
+        to_python=_epi_to_python,
+        to_storage=_epi_to_storage,
+        setter=_set_bepi_attr,
+    ),
     "vf": AttrSpec(aliases=ALIAS_VF, setter=set_vf, use_graph_setter=True),
     "theta": AttrSpec(
         aliases=ALIAS_THETA,
@@ -178,12 +240,18 @@ class NodeProtocol(Protocol):
     graph: MutableMapping[str, Any]
 
     def neighbors(self) -> Iterable[NodeProtocol | Hashable]:
+        """Iterate structural neighbours coupled to this node."""
+
         ...
 
     def _glyph_storage(self) -> MutableMapping[str, object]:
+        """Return the mutable mapping storing glyph metadata."""
+
         ...
 
     def has_edge(self, other: "NodeProtocol") -> bool:
+        """Return ``True`` when an edge connects this node to ``other``."""
+
         ...
 
     def add_edge(
@@ -193,12 +261,18 @@ class NodeProtocol(Protocol):
         *,
         overwrite: bool = False,
     ) -> None:
+        """Couple ``other`` using ``weight`` optionally replacing existing links."""
+
         ...
 
     def offset(self) -> int:
+        """Return the node offset index within the canonical ordering."""
+
         ...
 
     def all_nodes(self) -> Iterable[NodeProtocol]:
+        """Iterate all nodes of the attached graph as :class:`NodeProtocol` objects."""
+
         ...
 
 
@@ -216,10 +290,116 @@ class NodeNX(NodeProtocol):
     dnfr: DeltaNFR = ATTR_SPECS["dnfr"].build_property()
     d2EPI: SecondDerivativeEPI = ATTR_SPECS["d2EPI"].build_property()
 
-    def __init__(self, G: TNFRGraph, n: NodeId) -> None:
+    @staticmethod
+    def _prepare_coherence_operator(
+        operator: CoherenceOperator | None,
+        *,
+        dim: int | None = None,
+        spectrum: Sequence[float] | np.ndarray | None = None,
+        c_min: float | None = None,
+    ) -> CoherenceOperator | None:
+        if operator is not None:
+            return operator
+
+        spectrum_array: np.ndarray | None
+        if spectrum is None:
+            spectrum_array = None
+        else:
+            spectrum_array = np.asarray(spectrum, dtype=np.complex128)
+            if spectrum_array.ndim != 1:
+                raise ValueError("Coherence spectrum must be one-dimensional.")
+
+        effective_dim = dim
+        if spectrum_array is not None:
+            spectrum_length = spectrum_array.shape[0]
+            if effective_dim is None:
+                effective_dim = int(spectrum_length)
+            elif spectrum_length != int(effective_dim):
+                raise ValueError("Coherence spectrum size mismatch with requested dimension.")
+
+        if effective_dim is None:
+            return None
+
+        kwargs: dict[str, Any] = {}
+        if spectrum_array is not None:
+            kwargs["spectrum"] = spectrum_array
+        if c_min is not None:
+            kwargs["c_min"] = float(c_min)
+        return make_coherence_operator(int(effective_dim), **kwargs)
+
+    @staticmethod
+    def _prepare_frequency_operator(
+        operator: FrequencyOperator | None,
+        *,
+        matrix: Sequence[Sequence[complex]] | np.ndarray | None = None,
+    ) -> FrequencyOperator | None:
+        if operator is not None:
+            return operator
+        if matrix is None:
+            return None
+        return make_frequency_operator(np.asarray(matrix, dtype=np.complex128))
+
+    def __init__(
+        self,
+        G: TNFRGraph,
+        n: NodeId,
+        *,
+        state_projector: StateProjector | None = None,
+        enable_math_validation: Optional[bool] = None,
+        hilbert_space: HilbertSpace | None = None,
+        coherence_operator: CoherenceOperator | None = None,
+        coherence_dim: int | None = None,
+        coherence_spectrum: Sequence[float] | np.ndarray | None = None,
+        coherence_c_min: float | None = None,
+        frequency_operator: FrequencyOperator | None = None,
+        frequency_matrix: Sequence[Sequence[complex]] | np.ndarray | None = None,
+        coherence_threshold: float | None = None,
+        validator: NFRValidator | None = None,
+        rng: np.random.Generator | None = None,
+    ) -> None:
         self.G: TNFRGraph = G
         self.n: NodeId = n
         self.graph: MutableMapping[str, Any] = G.graph
+        self.state_projector: StateProjector = state_projector or BasicStateProjector()
+        self._math_validation_override: Optional[bool] = enable_math_validation
+        if enable_math_validation is None:
+            effective_validation = get_flags().enable_math_validation
+        else:
+            effective_validation = bool(enable_math_validation)
+        self.enable_math_validation: bool = effective_validation
+        default_dimension = (
+            G.number_of_nodes() if hasattr(G, "number_of_nodes") else len(tuple(G.nodes))
+        )
+        default_dimension = max(1, int(default_dimension))
+        self.hilbert_space: HilbertSpace = hilbert_space or HilbertSpace(default_dimension)
+        if coherence_operator is not None and (
+            coherence_dim is not None
+            or coherence_spectrum is not None
+            or coherence_c_min is not None
+        ):
+            raise ValueError(
+                "Provide either a coherence operator or factory parameters, not both."
+            )
+        if frequency_operator is not None and frequency_matrix is not None:
+            raise ValueError(
+                "Provide either a frequency operator or frequency matrix, not both."
+            )
+
+        self.coherence_operator: CoherenceOperator | None = self._prepare_coherence_operator(
+            coherence_operator,
+            dim=coherence_dim,
+            spectrum=coherence_spectrum,
+            c_min=coherence_c_min,
+        )
+        self.frequency_operator: FrequencyOperator | None = self._prepare_frequency_operator(
+            frequency_operator,
+            matrix=frequency_matrix,
+        )
+        self.coherence_threshold: float | None = (
+            float(coherence_threshold) if coherence_threshold is not None else None
+        )
+        self.validator: NFRValidator | None = validator
+        self.rng: np.random.Generator | None = rng
         G.graph.setdefault("_node_cache", {})[n] = self
 
     def _glyph_storage(self) -> MutableMapping[str, Any]:
@@ -245,6 +425,8 @@ class NodeNX(NodeProtocol):
         return self.G.neighbors(self.n)
 
     def has_edge(self, other: NodeProtocol) -> bool:
+        """Return ``True`` when an edge connects this node to ``other``."""
+
         if isinstance(other, NodeNX):
             return self.G.has_edge(self.n, other.n)
         raise NotImplementedError
@@ -256,6 +438,8 @@ class NodeNX(NodeProtocol):
         *,
         overwrite: bool = False,
     ) -> None:
+        """Couple ``other`` using ``weight`` optionally replacing existing links."""
+
         if isinstance(other, NodeNX):
             add_edge(
                 self.G,
@@ -268,13 +452,212 @@ class NodeNX(NodeProtocol):
             raise NotImplementedError
 
     def offset(self) -> int:
+        """Return the cached node offset within the canonical ordering."""
+
         mapping = ensure_node_offset_map(self.G)
         return mapping.get(self.n, 0)
 
     def all_nodes(self) -> Iterable[NodeProtocol]:
+        """Iterate all nodes of ``self.G`` as ``NodeNX`` adapters."""
+
         override = self.graph.get("_all_nodes")
         if override is not None:
             return override
 
         nodes = cached_node_list(self.G)
         return tuple(NodeNX.from_graph(self.G, v) for v in nodes)
+
+    def run_sequence_with_validation(
+        self,
+        ops: Iterable[Callable[[TNFRGraph, NodeId], None]],
+        *,
+        projector: StateProjector | None = None,
+        hilbert_space: HilbertSpace | None = None,
+        coherence_operator: CoherenceOperator | None = None,
+        coherence_dim: int | None = None,
+        coherence_spectrum: Sequence[float] | np.ndarray | None = None,
+        coherence_c_min: float | None = None,
+        coherence_threshold: float | None = None,
+        frequency_operator: FrequencyOperator | None = None,
+        frequency_matrix: Sequence[Sequence[complex]] | np.ndarray | None = None,
+        validator: NFRValidator | None = None,
+        enforce_frequency_positivity: bool | None = None,
+        enable_validation: bool | None = None,
+        rng: np.random.Generator | None = None,
+        log_metrics: bool = False,
+    ) -> dict[str, Any]:
+        """Run ``ops`` then return pre/post metrics with optional validation."""
+
+        from .structural import run_sequence as structural_run_sequence
+
+        projector = projector or self.state_projector
+        hilbert = hilbert_space or self.hilbert_space
+
+        effective_coherence = (
+            self._prepare_coherence_operator(
+                coherence_operator,
+                dim=coherence_dim,
+                spectrum=coherence_spectrum,
+                c_min=(
+                    coherence_c_min
+                    if coherence_c_min is not None
+                    else (
+                        self.coherence_operator.c_min
+                        if self.coherence_operator is not None
+                        else None
+                    )
+                ),
+            )
+            if any(
+                parameter is not None
+                for parameter in (
+                    coherence_operator,
+                    coherence_dim,
+                    coherence_spectrum,
+                    coherence_c_min,
+                )
+            )
+            else self.coherence_operator
+        )
+        effective_freq = (
+            self._prepare_frequency_operator(
+                frequency_operator,
+                matrix=frequency_matrix,
+            )
+            if frequency_operator is not None or frequency_matrix is not None
+            else self.frequency_operator
+        )
+        threshold = (
+            float(coherence_threshold)
+            if coherence_threshold is not None
+            else self.coherence_threshold
+        )
+        validator = validator or self.validator
+        rng = rng or self.rng
+
+        if enable_validation is None:
+            if self._math_validation_override is not None:
+                should_validate = bool(self._math_validation_override)
+            else:
+                should_validate = bool(get_flags().enable_math_validation)
+        else:
+            should_validate = bool(enable_validation)
+        self.enable_math_validation = should_validate
+
+        enforce_frequency = (
+            bool(enforce_frequency_positivity)
+            if enforce_frequency_positivity is not None
+            else bool(effective_freq is not None)
+        )
+
+        def _project(epi: float, vf: float, theta: float) -> np.ndarray:
+            local_rng = None
+            if rng is not None:
+                bit_generator = rng.bit_generator
+                cloned_state = copy.deepcopy(bit_generator.state)
+                local_bit_generator = type(bit_generator)()
+                local_bit_generator.state = cloned_state
+                local_rng = np.random.Generator(local_bit_generator)
+            vector = projector(
+                epi=epi,
+                nu_f=vf,
+                theta=theta,
+                dim=hilbert.dimension,
+                rng=local_rng,
+            )
+            return np.asarray(vector, dtype=np.complex128)
+
+        active_flags = get_flags()
+        should_log_metrics = bool(log_metrics and active_flags.log_performance)
+
+        def _metrics(state: np.ndarray, label: str) -> dict[str, Any]:
+            metrics: dict[str, Any] = {}
+            with context_flags(log_performance=False):
+                norm_passed, norm_value = runtime_normalized(state, hilbert, label=label)
+                metrics["normalized"] = bool(norm_passed)
+                metrics["norm"] = float(norm_value)
+                if effective_coherence is not None and threshold is not None:
+                    coh_passed, coh_value = runtime_coherence(
+                        state, effective_coherence, threshold, label=label
+                    )
+                    metrics["coherence"] = bool(coh_passed)
+                    metrics["coherence_expectation"] = float(coh_value)
+                    metrics["coherence_threshold"] = float(threshold)
+                if effective_freq is not None:
+                    freq_summary = runtime_frequency_positive(
+                        state,
+                        effective_freq,
+                        enforce=enforce_frequency,
+                        label=label,
+                    )
+                    metrics["frequency_positive"] = bool(freq_summary["passed"])
+                    metrics["frequency_expectation"] = float(freq_summary["value"])
+                    metrics["frequency_projection_passed"] = bool(
+                        freq_summary["projection_passed"]
+                    )
+                    metrics["frequency_spectrum_psd"] = bool(freq_summary["spectrum_psd"])
+                    metrics["frequency_spectrum_min"] = float(freq_summary["spectrum_min"])
+                    metrics["frequency_enforced"] = bool(freq_summary["enforce"])
+                if effective_coherence is not None:
+                    unitary_passed, unitary_norm = runtime_stable_unitary(
+                        state,
+                        effective_coherence,
+                        hilbert,
+                        label=label,
+                    )
+                    metrics["stable_unitary"] = bool(unitary_passed)
+                    metrics["stable_unitary_norm_after"] = float(unitary_norm)
+            if should_log_metrics:
+                LOGGER.debug(
+                    "node_metrics.%s normalized=%s coherence=%s frequency_positive=%s stable_unitary=%s coherence_expectation=%s frequency_expectation=%s",
+                    label,
+                    metrics.get("normalized"),
+                    metrics.get("coherence"),
+                    metrics.get("frequency_positive"),
+                    metrics.get("stable_unitary"),
+                    metrics.get("coherence_expectation"),
+                    metrics.get("frequency_expectation"),
+                )
+            return metrics
+
+        pre_state = _project(self.EPI, self.vf, self.theta)
+        pre_metrics = _metrics(pre_state, "pre")
+
+        structural_run_sequence(self.G, self.n, ops)
+
+        post_state = _project(self.EPI, self.vf, self.theta)
+        post_metrics = _metrics(post_state, "post")
+
+        validation_summary: dict[str, Any] | None = None
+        if should_validate:
+            validator_instance = validator
+            if validator_instance is None:
+                if effective_coherence is None:
+                    raise ValueError("Validation requires a coherence operator.")
+                validator_instance = NFRValidator(
+                    hilbert,
+                    effective_coherence,
+                    threshold if threshold is not None else 0.0,
+                    frequency_operator=effective_freq,
+                )
+            outcome = validator_instance.validate(
+                post_state,
+                enforce_frequency_positivity=enforce_frequency,
+            )
+            validation_summary = {
+                "passed": bool(outcome.passed),
+                "summary": outcome.summary,
+                "report": validator_instance.report(outcome),
+            }
+
+        result = {
+            "pre_state": pre_state,
+            "post_state": post_state,
+            "pre_metrics": pre_metrics,
+            "post_metrics": post_metrics,
+            "validation": validation_summary,
+        }
+        # Preserve legacy structure for downstream compatibility.
+        result["pre"] = {"state": pre_state, "metrics": pre_metrics}
+        result["post"] = {"state": post_state, "metrics": post_metrics}
+        return result