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

tnfr/mathematics/projection.pyi

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import numpy as np
+from dataclasses import dataclass
+from typing import Protocol
+import numpy.typing as npt
+
+__all__ = ["StateProjector", "BasicStateProjector"]
+
+ComplexVector = npt.NDArray[np.complexfloating[np.float64, np.float64]]
+
+class StateProjector(Protocol):
+    def __call__(
+        self,
+        epi: float,
+        nu_f: float,
+        theta: float,
+        dim: int,
+        rng: np.random.Generator | None = None,
+    ) -> ComplexVector: ...
+
+@dataclass
+class BasicStateProjector:
+    dtype: np.dtype[np.complexfloating[np.float64, np.float64]] = ...
+    atol: float = ...
+    def __call__(
+        self,
+        epi: float,
+        nu_f: float,
+        theta: float,
+        dim: int,
+        rng: np.random.Generator | None = None,
+    ) -> ComplexVector: ...

tnfr/mathematics/runtime.py

@@ -0,0 +1,182 @@
+"""Runtime helpers capturing TNFR spectral performance metrics."""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+import numpy as np
+
+from ..config import get_flags
+from ..utils import get_logger
+from .backend import ensure_array, ensure_numpy, get_backend
+from .operators import CoherenceOperator, FrequencyOperator
+from .spaces import HilbertSpace
+
+__all__ = [
+    "normalized",
+    "coherence",
+    "frequency_positive",
+    "stable_unitary",
+    "coherence_expectation",
+    "frequency_expectation",
+]
+
+LOGGER = get_logger(__name__)
+
+
+def _as_vector(
+    state: Sequence[complex] | np.ndarray,
+    *,
+    dimension: int,
+    backend=None,
+) -> Any:
+    resolved_backend = backend or get_backend()
+    vector = ensure_array(state, dtype=np.complex128, backend=resolved_backend)
+    if (
+        getattr(vector, "ndim", len(getattr(vector, "shape", ()))) != 1
+        or vector.shape[0] != dimension
+    ):
+        raise ValueError(
+            "State vector dimension mismatch: "
+            f"expected ({dimension},), received {vector.shape!r}."
+        )
+    return vector
+
+
+def _resolve_operator_backend(operator: CoherenceOperator) -> tuple[Any, Any]:
+    backend = getattr(operator, "backend", None) or get_backend()
+    matrix_backend = getattr(operator, "_matrix_backend", None)
+    if matrix_backend is None:
+        matrix_backend = ensure_array(
+            operator.matrix, dtype=np.complex128, backend=backend
+        )
+    return backend, matrix_backend
+
+
+def _maybe_log(metric: str, payload: dict[str, object]) -> None:
+    if not get_flags().log_performance:
+        return
+    LOGGER.debug("%s: %s", metric, payload)
+
+
+def normalized(
+    state: Sequence[complex] | np.ndarray,
+    hilbert_space: HilbertSpace,
+    *,
+    atol: float = 1e-9,
+    label: str = "state",
+) -> tuple[bool, float]:
+    """Return normalization status and norm for ``state``."""
+
+    backend = get_backend()
+    vector = _as_vector(state, dimension=hilbert_space.dimension, backend=backend)
+    norm_backend = backend.norm(vector)
+    norm = float(np.asarray(ensure_numpy(norm_backend, backend=backend)))
+    passed = bool(np.isclose(norm, 1.0, atol=atol))
+    _maybe_log("normalized", {"label": label, "norm": norm, "passed": passed})
+    return passed, float(norm)
+
+
+def coherence_expectation(
+    state: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-9,
+) -> float:
+    """Return the coherence expectation value for ``state``."""
+
+    return float(operator.expectation(state, normalise=normalise, atol=atol))
+
+
+def coherence(
+    state: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    threshold: float,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-9,
+    label: str = "state",
+) -> tuple[bool, float]:
+    """Evaluate coherence expectation against ``threshold``."""
+
+    value = coherence_expectation(state, operator, normalise=normalise, atol=atol)
+    passed = bool(value + atol >= threshold)
+    _maybe_log(
+        "coherence",
+        {"label": label, "value": value, "threshold": threshold, "passed": passed},
+    )
+    return passed, value
+
+
+def frequency_expectation(
+    state: Sequence[complex] | np.ndarray,
+    operator: FrequencyOperator,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-9,
+) -> float:
+    """Return the structural frequency projection for ``state``."""
+
+    return float(operator.project_frequency(state, normalise=normalise, atol=atol))
+
+
+def frequency_positive(
+    state: Sequence[complex] | np.ndarray,
+    operator: FrequencyOperator,
+    *,
+    normalise: bool = True,
+    enforce: bool = True,
+    atol: float = 1e-9,
+    label: str = "state",
+) -> dict[str, float | bool]:
+    """Return summary ensuring structural frequency remains non-negative."""
+
+    spectrum = operator.spectrum()
+    spectrum_psd = bool(operator.is_positive_semidefinite(atol=atol))
+    value = frequency_expectation(state, operator, normalise=normalise, atol=atol)
+    projection_ok = bool(value + atol >= 0.0)
+    passed = bool(spectrum_psd and (projection_ok or not enforce))
+    summary = {
+        "passed": passed,
+        "value": value,
+        "enforce": enforce,
+        "spectrum_psd": spectrum_psd,
+        "spectrum_min": float(np.min(spectrum)) if spectrum.size else float("inf"),
+        "projection_passed": projection_ok,
+    }
+    _maybe_log("frequency_positive", {"label": label, **summary})
+    return summary
+
+
+def stable_unitary(
+    state: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    hilbert_space: HilbertSpace,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-9,
+    label: str = "state",
+) -> tuple[bool, float]:
+    """Return whether a one-step unitary preserves the Hilbert norm."""
+
+    backend, matrix_backend = _resolve_operator_backend(operator)
+    vector = _as_vector(state, dimension=hilbert_space.dimension, backend=backend)
+    if normalise:
+        norm_backend = backend.norm(vector)
+        norm = float(np.asarray(ensure_numpy(norm_backend, backend=backend)))
+        if np.isclose(norm, 0.0, atol=atol):
+            raise ValueError("Cannot normalise a null state vector.")
+        vector = vector / norm
+    generator = -1j * matrix_backend
+    unitary = backend.matrix_exp(generator)
+    evolved_backend = backend.matmul(unitary, vector[..., None]).reshape(
+        (hilbert_space.dimension,)
+    )
+    evolved = np.asarray(ensure_numpy(evolved_backend, backend=backend))
+    norm_after = hilbert_space.norm(evolved)
+    passed = bool(np.isclose(norm_after, 1.0, atol=atol))
+    _maybe_log(
+        "stable_unitary", {"label": label, "norm_after": norm_after, "passed": passed}
+    )
+    return passed, float(norm_after)

tnfr/mathematics/runtime.pyi

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import numpy as np
+from .operators import CoherenceOperator, FrequencyOperator
+from .spaces import HilbertSpace
+from typing import Sequence
+
+__all__ = [
+    "normalized",
+    "coherence",
+    "frequency_positive",
+    "stable_unitary",
+    "coherence_expectation",
+    "frequency_expectation",
+]
+
+def normalized(
+    state: Sequence[complex] | np.ndarray,
+    hilbert_space: HilbertSpace,
+    *,
+    atol: float = 1e-09,
+    label: str = "state",
+) -> tuple[bool, float]: ...
+def coherence_expectation(
+    state: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-09,
+) -> float: ...
+def coherence(
+    state: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    threshold: float,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-09,
+    label: str = "state",
+) -> tuple[bool, float]: ...
+def frequency_expectation(
+    state: Sequence[complex] | np.ndarray,
+    operator: FrequencyOperator,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-09,
+) -> float: ...
+def frequency_positive(
+    state: Sequence[complex] | np.ndarray,
+    operator: FrequencyOperator,
+    *,
+    normalise: bool = True,
+    enforce: bool = True,
+    atol: float = 1e-09,
+    label: str = "state",
+) -> dict[str, float | bool]: ...
+def stable_unitary(
+    state: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    hilbert_space: HilbertSpace,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-09,
+    label: str = "state",
+) -> tuple[bool, float]: ...

tnfr/mathematics/spaces.py

@@ -0,0 +1,256 @@
+"""Mathematical spaces supporting the TNFR canonical paradigm."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+import numpy as np
+
+from .epi import BEPIElement, _EPIValidators
+
+
+@dataclass(frozen=True)
+class HilbertSpace:
+    r"""Finite section of :math:`\ell^2(\mathbb{N}) \otimes L^2(\mathbb{R})`.
+
+    The space models the discrete spectral component of the TNFR paradigm.  The
+    canonical orthonormal basis corresponds to the standard coordinate vectors
+    and the inner product is sesquilinear, implemented through
+    :func:`numpy.vdot`.  Projection returns expansion coefficients for any
+    supplied orthonormal basis.
+    """
+
+    dimension: int
+    dtype: np.dtype = np.complex128
+
+    def __post_init__(self) -> None:
+        if self.dimension <= 0:
+            raise ValueError("Hilbert spaces require a positive dimension.")
+
+    @property
+    def basis(self) -> np.ndarray:
+        """Return the canonical orthonormal basis as identity vectors."""
+
+        return np.eye(self.dimension, dtype=self.dtype)
+
+    def _as_vector(self, value: Sequence[complex] | np.ndarray) -> np.ndarray:
+        vector = np.asarray(value, dtype=self.dtype)
+        if vector.shape != (self.dimension,):
+            raise ValueError(
+                f"Vector must have shape ({self.dimension},), got {vector.shape!r}."
+            )
+        return vector
+
+    def inner_product(
+        self,
+        vector_a: Sequence[complex] | np.ndarray,
+        vector_b: Sequence[complex] | np.ndarray,
+    ) -> complex:
+        """Compute the sesquilinear inner product ``⟨a, b⟩``."""
+
+        vec_a = self._as_vector(vector_a)
+        vec_b = self._as_vector(vector_b)
+        return np.vdot(vec_a, vec_b)
+
+    def norm(self, vector: Sequence[complex] | np.ndarray) -> float:
+        """Return the Hilbert norm induced by the inner product."""
+
+        value = self.inner_product(vector, vector)
+        magnitude = max(value.real, 0.0)
+        return float(np.sqrt(magnitude))
+
+    def is_normalized(
+        self, vector: Sequence[complex] | np.ndarray, *, atol: float = 1e-9
+    ) -> bool:
+        """Check whether a vector has unit norm within a tolerance."""
+
+        return np.isclose(self.norm(vector), 1.0, atol=atol)
+
+    def _validate_basis(
+        self, basis: Sequence[Sequence[complex] | np.ndarray]
+    ) -> np.ndarray:
+        basis_list = list(basis)
+        if len(basis_list) == 0:
+            raise ValueError("An orthonormal basis must contain at least one vector.")
+
+        basis_vectors = [self._as_vector(vector) for vector in basis_list]
+        matrix = np.vstack(basis_vectors)
+        gram = matrix @ matrix.conj().T
+        identity = np.eye(matrix.shape[0], dtype=self.dtype)
+        if not np.allclose(gram, identity, atol=1e-10):
+            raise ValueError("Provided basis is not orthonormal within tolerance.")
+        return matrix
+
+    def project(
+        self,
+        vector: Sequence[complex] | np.ndarray,
+        basis: Sequence[Sequence[complex] | np.ndarray] | None = None,
+    ) -> np.ndarray:
+        """Return coefficients ``⟨b_k|ψ⟩`` for the chosen orthonormal basis."""
+
+        vec = self._as_vector(vector)
+        if basis is None:
+            return vec.astype(self.dtype, copy=True)
+
+        basis_matrix = self._validate_basis(basis)
+        coefficients = basis_matrix.conj() @ vec
+        return coefficients.astype(self.dtype, copy=False)
+
+
+class BanachSpaceEPI(_EPIValidators):
+    r"""Banach space for :math:`C^0([0, 1],\mathbb{C}) \oplus \ell^2(\mathbb{N})`.
+
+    Elements are represented by a pair ``(f, a)`` where ``f`` samples the
+    continuous field over a uniform grid ``x_grid`` and ``a`` is the discrete
+    spectral tail.  The coherence norm combines the supremum of ``f``, the
+    :math:`\ell^2` norm of ``a`` and a derivative-based functional capturing
+    the local stability of ``f``.
+    """
+
+    def element(
+        self,
+        f_continuous: Sequence[complex] | np.ndarray,
+        a_discrete: Sequence[complex] | np.ndarray,
+        *,
+        x_grid: Sequence[float] | np.ndarray,
+    ) -> BEPIElement:
+        """Create a :class:`~tnfr.mathematics.epi.BEPIElement` with validated data."""
+
+        self.validate_domain(f_continuous, a_discrete, x_grid)
+        return BEPIElement(f_continuous, a_discrete, x_grid)
+
+    def zero_element(
+        self,
+        *,
+        continuous_size: int,
+        discrete_size: int,
+        x_grid: Sequence[float] | np.ndarray | None = None,
+    ) -> BEPIElement:
+        """Return the neutral element for the direct sum."""
+
+        if continuous_size < 2:
+            raise ValueError("continuous_size must be at least two samples.")
+        grid = (
+            np.asarray(x_grid, dtype=float)
+            if x_grid is not None
+            else np.linspace(0.0, 1.0, continuous_size, dtype=float)
+        )
+        zeros_f = np.zeros(continuous_size, dtype=np.complex128)
+        zeros_a = np.zeros(discrete_size, dtype=np.complex128)
+        return self.element(zeros_f, zeros_a, x_grid=grid)
+
+    def canonical_basis(
+        self,
+        *,
+        continuous_size: int,
+        discrete_size: int,
+        continuous_index: int = 0,
+        discrete_index: int = 0,
+        x_grid: Sequence[float] | np.ndarray | None = None,
+    ) -> BEPIElement:
+        """Generate a canonical basis element for the Banach space."""
+
+        if continuous_size < 2:
+            raise ValueError("continuous_size must be at least two samples.")
+        if not (0 <= continuous_index < continuous_size):
+            raise ValueError("continuous_index out of range.")
+        if not (0 <= discrete_index < discrete_size):
+            raise ValueError("discrete_index out of range.")
+
+        grid = (
+            np.asarray(x_grid, dtype=float)
+            if x_grid is not None
+            else np.linspace(0.0, 1.0, continuous_size, dtype=float)
+        )
+
+        f_vector = np.zeros(continuous_size, dtype=np.complex128)
+        a_vector = np.zeros(discrete_size, dtype=np.complex128)
+        f_vector[continuous_index] = 1.0 + 0.0j
+        a_vector[discrete_index] = 1.0 + 0.0j
+        return self.element(f_vector, a_vector, x_grid=grid)
+
+    def direct_sum(self, left: BEPIElement, right: BEPIElement) -> BEPIElement:
+        """Delegate direct sums to the underlying EPI element."""
+
+        return left.direct_sum(right)
+
+    def adjoint(self, element: BEPIElement) -> BEPIElement:
+        """Return the adjoint element of the supplied operand."""
+
+        return element.adjoint()
+
+    def compose(
+        self,
+        element: BEPIElement,
+        transform: Callable[[np.ndarray], np.ndarray],
+        *,
+        spectral_transform: Callable[[np.ndarray], np.ndarray] | None = None,
+    ) -> BEPIElement:
+        """Compose an element with the provided transforms."""
+
+        return element.compose(transform, spectral_transform=spectral_transform)
+
+    def tensor_with_hilbert(
+        self,
+        element: BEPIElement,
+        hilbert_space: HilbertSpace,
+        vector: Sequence[complex] | np.ndarray | None = None,
+    ) -> np.ndarray:
+        """Compute the tensor product against a :class:`HilbertSpace` vector."""
+
+        raw_vector = hilbert_space.basis[0] if vector is None else vector
+        hilbert_vector = hilbert_space._as_vector(
+            raw_vector
+        )  # pylint: disable=protected-access
+        return element.tensor(hilbert_vector)
+
+    def compute_coherence_functional(
+        self,
+        f_continuous: Sequence[complex] | np.ndarray,
+        x_grid: Sequence[float] | np.ndarray,
+    ) -> float:
+        r"""Approximate :math:`\int |f'|^2 dx / (1 + \int |f|^2 dx)`."""
+
+        f_array, _, grid = self.validate_domain(
+            f_continuous, np.array([0.0], dtype=np.complex128), x_grid
+        )
+        if grid is None:
+            raise ValueError("x_grid must be provided for coherence evaluations.")
+
+        derivative = np.gradient(
+            f_array,
+            grid,
+            edge_order=2 if f_array.size > 2 else 1,
+        )
+        numerator = np.trapz(np.abs(derivative) ** 2, grid)
+        denominator = 1.0 + np.trapz(np.abs(f_array) ** 2, grid)
+        if denominator <= 0:
+            raise ValueError("Denominator of coherence functional must be positive.")
+        return float(np.real_if_close(numerator / denominator))
+
+    def coherence_norm(
+        self,
+        f_continuous: Sequence[complex] | np.ndarray,
+        a_discrete: Sequence[complex] | np.ndarray,
+        *,
+        x_grid: Sequence[float] | np.ndarray,
+        alpha: float = 1.0,
+        beta: float = 1.0,
+        gamma: float = 1.0,
+    ) -> float:
+        """Return ``α‖f‖_∞ + β‖a‖_2 + γ CF(f)`` for positive weights."""
+
+        if alpha <= 0 or beta <= 0 or gamma <= 0:
+            raise ValueError("alpha, beta and gamma must be strictly positive.")
+
+        f_array, a_array, grid = self.validate_domain(f_continuous, a_discrete, x_grid)
+        if grid is None:
+            raise ValueError("x_grid must be supplied when evaluating the norm.")
+
+        sup_norm = float(np.max(np.abs(f_array))) if f_array.size else 0.0
+        l2_norm = float(np.linalg.norm(a_array))
+        coherence_functional = self.compute_coherence_functional(f_array, grid)
+
+        value = alpha * sup_norm + beta * l2_norm + gamma * coherence_functional
+        return float(np.real_if_close(value))

tnfr/mathematics/spaces.pyi

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import numpy as np
+from .epi import BEPIElement as BEPIElement, _EPIValidators
+from dataclasses import dataclass
+from typing import Callable, Sequence
+
+@dataclass(frozen=True)
+class HilbertSpace:
+    dimension: int
+    dtype: np.dtype = ...
+    def __post_init__(self) -> None: ...
+    @property
+    def basis(self) -> np.ndarray: ...
+    def inner_product(
+        self,
+        vector_a: Sequence[complex] | np.ndarray,
+        vector_b: Sequence[complex] | np.ndarray,
+    ) -> complex: ...
+    def norm(self, vector: Sequence[complex] | np.ndarray) -> float: ...
+    def is_normalized(
+        self, vector: Sequence[complex] | np.ndarray, *, atol: float = 1e-09
+    ) -> bool: ...
+    def project(
+        self,
+        vector: Sequence[complex] | np.ndarray,
+        basis: Sequence[Sequence[complex] | np.ndarray] | None = None,
+    ) -> np.ndarray: ...
+
+class BanachSpaceEPI(_EPIValidators):
+    def element(
+        self,
+        f_continuous: Sequence[complex] | np.ndarray,
+        a_discrete: Sequence[complex] | np.ndarray,
+        *,
+        x_grid: Sequence[float] | np.ndarray,
+    ) -> BEPIElement: ...
+    def zero_element(
+        self,
+        *,
+        continuous_size: int,
+        discrete_size: int,
+        x_grid: Sequence[float] | np.ndarray | None = None,
+    ) -> BEPIElement: ...
+    def canonical_basis(
+        self,
+        *,
+        continuous_size: int,
+        discrete_size: int,
+        continuous_index: int = 0,
+        discrete_index: int = 0,
+        x_grid: Sequence[float] | np.ndarray | None = None,
+    ) -> BEPIElement: ...
+    def direct_sum(self, left: BEPIElement, right: BEPIElement) -> BEPIElement: ...
+    def adjoint(self, element: BEPIElement) -> BEPIElement: ...
+    def compose(
+        self,
+        element: BEPIElement,
+        transform: Callable[[np.ndarray], np.ndarray],
+        *,
+        spectral_transform: Callable[[np.ndarray], np.ndarray] | None = None,
+    ) -> BEPIElement: ...
+    def tensor_with_hilbert(
+        self,
+        element: BEPIElement,
+        hilbert_space: HilbertSpace,
+        vector: Sequence[complex] | np.ndarray | None = None,
+    ) -> np.ndarray: ...
+    def compute_coherence_functional(
+        self,
+        f_continuous: Sequence[complex] | np.ndarray,
+        x_grid: Sequence[float] | np.ndarray,
+    ) -> float: ...
+    def coherence_norm(
+        self,
+        f_continuous: Sequence[complex] | np.ndarray,
+        a_discrete: Sequence[complex] | np.ndarray,
+        *,
+        x_grid: Sequence[float] | np.ndarray,
+        alpha: float = 1.0,
+        beta: float = 1.0,
+        gamma: float = 1.0,
+    ) -> float: ...