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

tnfr/mathematics/dynamics.py

@@ -0,0 +1,398 @@
+"""Spectral dynamics helpers driven by ΔNFR generators."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, NamedTuple, Sequence
+
+import numpy as np
+
+from .backend import MathematicsBackend, ensure_array, ensure_numpy, get_backend
+from .spaces import HilbertSpace
+
+try:  # pragma: no cover - optional SciPy dependency
+    from scipy.linalg import expm as _scipy_expm  # type: ignore
+except Exception:  # pragma: no cover - SciPy not installed
+    _scipy_expm = None
+
+__all__ = ["MathematicalDynamicsEngine", "ContractiveDynamicsEngine"]
+
+
+def _has_backend_matrix_exp(backend: MathematicsBackend) -> bool:
+    """Return ``True`` when ``backend`` exposes a usable ``matrix_exp``."""
+
+    matrix_exp = getattr(backend, "matrix_exp", None)
+    if not callable(matrix_exp):
+        return False
+
+    try:
+        probe = ensure_array([[0.0]], dtype=np.complex128, backend=backend)
+        matrix_exp(probe)
+    except (AttributeError, NotImplementedError):
+        return False
+    except Exception:
+        # Older backends may surface missing implementations as runtime errors;
+        # treat them as signals to fall back to SciPy when available.
+        return False
+    return True
+
+
+def _as_matrix(
+    matrix: Sequence[Sequence[complex]] | np.ndarray | Any,
+    *,
+    backend: MathematicsBackend,
+) -> Any:
+    arr = ensure_array(matrix, dtype=np.complex128, backend=backend)
+    shape = getattr(arr, "shape", None)
+    if shape is None or len(shape) != 2 or shape[0] != shape[1]:
+        raise ValueError("Generator matrix must be square.")
+    return arr
+
+
+def _is_hermitian(matrix: Any, *, atol: float = 1e-9, backend: MathematicsBackend) -> bool:
+    matrix_np = ensure_numpy(matrix, backend=backend)
+    return bool(np.allclose(matrix_np, matrix_np.conj().T, atol=atol))
+
+
+def _vectorize_density(matrix: Any, *, backend: MathematicsBackend) -> Any:
+    arr = ensure_array(matrix, dtype=np.complex128, backend=backend)
+    return arr.transpose(1, 0).reshape((-1,))
+
+
+def _devectorize_density(vector: Any, dim: int, *, backend: MathematicsBackend) -> Any:
+    arr = ensure_array(vector, dtype=np.complex128, backend=backend)
+    return arr.reshape((dim, dim)).transpose(1, 0)
+
+
+class TraceValue(NamedTuple):
+    """Container for trace evaluations in both backend and NumPy space."""
+
+    backend: Any
+    numpy: complex
+
+
+def _trace(matrix: Any, *, backend: MathematicsBackend) -> TraceValue:
+    traced_backend = backend.einsum("ii->", matrix)
+    traced_numpy = complex(np.asarray(ensure_numpy(traced_backend, backend=backend)))
+    return TraceValue(traced_backend, traced_numpy)
+
+
+@dataclass(slots=True)
+class MathematicalDynamicsEngine:
+    """Unitary evolution generated by Hermitian ΔNFR operators.
+
+    The engine accepts inputs expressed as backend-native tensors (NumPy,
+    :mod:`jax`, :mod:`torch`).  When the configured backend supports automatic
+    differentiation the evolution map ``exp(-i·Δ·dt)`` remains differentiable
+    because native propagators are now preferred.  Passing ``use_scipy=True``
+    explicitly opts into SciPy's exponential; we only fall back automatically
+    when the backend lacks a ``matrix_exp`` implementation.
+    """
+
+    generator: np.ndarray
+    hilbert_space: HilbertSpace
+    atol: float = 1e-9
+    _use_scipy: bool = False
+    backend: MathematicsBackend = field(init=False, repr=False)
+    _generator_backend: Any = field(init=False, repr=False)
+    _numpy_generator: np.ndarray = field(init=False, repr=False)
+
+    def __init__(
+        self,
+        generator: Sequence[Sequence[complex]] | np.ndarray | Any,
+        hilbert_space: HilbertSpace,
+        *,
+        atol: float = 1e-9,
+        use_scipy: bool | None = None,
+        backend: MathematicsBackend | None = None,
+    ) -> None:
+        resolved_backend = backend or get_backend()
+        matrix = _as_matrix(generator, backend=resolved_backend)
+        matrix_np = ensure_numpy(matrix, backend=resolved_backend)
+        if matrix_np.shape != (hilbert_space.dimension, hilbert_space.dimension):
+            raise ValueError("Generator dimension must match the Hilbert space.")
+        if not _is_hermitian(matrix, atol=atol, backend=resolved_backend):
+            raise ValueError("Dynamics generator must be Hermitian.")
+        self.backend = resolved_backend
+        self._generator_backend = matrix
+        self._numpy_generator = matrix_np
+        self.generator = matrix_np
+        self.hilbert_space = hilbert_space
+        self.atol = float(atol)
+        if use_scipy is None:
+            has_matrix_exp = _has_backend_matrix_exp(self.backend)
+            if has_matrix_exp:
+                self._use_scipy = False
+            elif _scipy_expm is not None:
+                self._use_scipy = True
+            else:
+                raise RuntimeError(
+                    "Backend lacks matrix_exp and SciPy is unavailable for fallback."
+                )
+        else:
+            if use_scipy and _scipy_expm is None:
+                raise RuntimeError("SciPy expm requested but SciPy is not available.")
+            self._use_scipy = bool(use_scipy and _scipy_expm is not None)
+
+    def _unitary_backend(self, dt: float) -> Any:
+        if self._use_scipy and _scipy_expm is not None:
+            return ensure_array(
+                _scipy_expm(-1j * dt * self._numpy_generator),
+                backend=self.backend,
+            )
+        return self.backend.matrix_exp(-1j * dt * self._generator_backend)
+
+    def step(
+        self,
+        state: Sequence[complex] | np.ndarray | Any,
+        *,
+        dt: float = 1.0,
+        normalize: bool = True,
+    ) -> Any:
+        """Evolve ``state`` by ``dt`` using the unitary ``exp(-i·Δ·dt)``."""
+
+        vector = ensure_array(state, dtype=np.complex128, backend=self.backend)
+        if vector.shape != (self.hilbert_space.dimension,):
+            raise ValueError(
+                "State dimension mismatch: "
+                f"expected ({self.hilbert_space.dimension},), received {vector.shape!r}."
+            )
+        unitary = self._unitary_backend(dt)
+        evolved = self.backend.matmul(unitary, vector)
+        if normalize:
+            norm_backend = self.backend.norm(evolved)
+            norm_numpy = float(np.asarray(ensure_numpy(norm_backend, backend=self.backend)))
+            if np.isclose(norm_numpy, 0.0, atol=self.atol):
+                raise ValueError("Cannot normalise a null state vector.")
+            evolved = evolved / norm_backend
+        return evolved
+
+    def evolve(
+        self,
+        state: Sequence[complex] | np.ndarray | Any,
+        *,
+        steps: int,
+        dt: float = 1.0,
+        normalize: bool = True,
+    ) -> Any:
+        """Return trajectory of length ``steps + 1`` starting from ``state``."""
+
+        if steps < 0:
+            raise ValueError("steps must be non-negative.")
+        current = ensure_array(state, dtype=np.complex128, backend=self.backend)
+        if current.shape != (self.hilbert_space.dimension,):
+            raise ValueError(
+                "State dimension mismatch: "
+                f"expected ({self.hilbert_space.dimension},), received {current.shape!r}."
+            )
+        trajectory: list[Any] = [current]
+        for _ in range(steps):
+            current = self.step(current, dt=dt, normalize=normalize)
+            trajectory.append(current)
+        return self.backend.stack(trajectory, axis=0)
+
+
+@dataclass(slots=True)
+class ContractiveDynamicsEngine:
+    """Contractive semigroup evolution driven by Lindblad ΔNFR generators.
+
+    Backend-native tensors are accepted for all density operators.  When the
+    chosen backend supports automatic differentiation we keep gradients intact
+    by default because native semigroup propagators are preferred.  Requesting
+    ``use_scipy=True`` still falls back to SciPy's :func:`scipy.linalg.expm`,
+    primarily for generators missing backend support.
+    """
+
+    generator: np.ndarray
+    hilbert_space: HilbertSpace
+    atol: float = 1e-9
+    _use_scipy: bool = False
+    backend: MathematicsBackend = field(init=False, repr=False)
+    _generator_backend: Any = field(init=False, repr=False)
+    _numpy_generator: np.ndarray = field(init=False, repr=False)
+    _identity_backend: Any = field(init=False, repr=False)
+    _last_contractivity_gap: float = field(init=False, repr=False)
+
+    def __init__(
+        self,
+        generator: Sequence[Sequence[complex]] | np.ndarray | Any,
+        hilbert_space: HilbertSpace,
+        *,
+        atol: float = 1e-9,
+        ensure_contractive: bool = True,
+        use_scipy: bool | None = None,
+        backend: MathematicsBackend | None = None,
+    ) -> None:
+        resolved_backend = backend or get_backend()
+        matrix = _as_matrix(generator, backend=resolved_backend)
+        matrix_np = ensure_numpy(matrix, backend=resolved_backend)
+        expected = hilbert_space.dimension * hilbert_space.dimension
+        if matrix_np.shape != (expected, expected):
+            raise ValueError(
+                "Generator must act on vectorised density operators with dimension "
+                f"{expected} × {expected}."
+            )
+        self.backend = resolved_backend
+        self._generator_backend = matrix
+        self._numpy_generator = matrix_np.astype(np.complex128, copy=False)
+        self.generator = self._numpy_generator
+        self.hilbert_space = hilbert_space
+        self.atol = float(atol)
+        if use_scipy is None:
+            has_matrix_exp = _has_backend_matrix_exp(self.backend)
+            if has_matrix_exp:
+                self._use_scipy = False
+            elif _scipy_expm is not None:
+                self._use_scipy = True
+            else:
+                raise RuntimeError(
+                    "Backend lacks matrix_exp and SciPy is unavailable for fallback."
+                )
+        else:
+            if use_scipy and _scipy_expm is None:
+                raise RuntimeError("SciPy expm requested but SciPy is not available.")
+            self._use_scipy = bool(use_scipy and _scipy_expm is not None)
+
+        self._identity_backend = ensure_array(
+            np.eye(hilbert_space.dimension, dtype=np.complex128),
+            backend=self.backend,
+        )
+        self._last_contractivity_gap = float("nan")
+        if ensure_contractive:
+            eigenvalues_backend, _ = self.backend.eig(self._generator_backend)
+            eigenvalues = ensure_numpy(eigenvalues_backend, backend=self.backend)
+            if np.max(eigenvalues.real) > self.atol:
+                raise ValueError(
+                    "ΔNFR generator is not contractive: positive real eigenvalues detected."
+                )
+
+    def _propagator_backend(self, dt: float) -> Any:
+        if self._use_scipy and _scipy_expm is not None:
+            return ensure_array(
+                _scipy_expm(dt * self._numpy_generator),
+                backend=self.backend,
+            )
+        return self.backend.matrix_exp(dt * self._generator_backend)
+
+    def frobenius_norm(
+        self,
+        density: Sequence[Sequence[complex]] | np.ndarray | Any,
+        *,
+        center: bool = False,
+    ) -> float:
+        """Return the Frobenius norm associated with the Hilbert space."""
+
+        matrix = ensure_array(density, dtype=np.complex128, backend=self.backend)
+        if matrix.shape != (self.hilbert_space.dimension, self.hilbert_space.dimension):
+            raise ValueError(
+                "Density operator dimension mismatch: "
+                f"expected {(self.hilbert_space.dimension, self.hilbert_space.dimension)}, "
+                f"received {matrix.shape!r}."
+            )
+        if center:
+            trace_value = _trace(matrix, backend=self.backend)
+            trace_backend = trace_value.backend / self.hilbert_space.dimension
+            matrix = matrix - trace_backend * self._identity_backend
+        norm_backend = self.backend.norm(matrix, ord="fro")
+        return float(np.asarray(ensure_numpy(norm_backend, backend=self.backend)))
+
+    @property
+    def last_contractivity_gap(self) -> float:
+        """Return the latest monitored contractivity gap (NaN if unavailable)."""
+
+        return float(self._last_contractivity_gap)
+
+    def step(
+        self,
+        density: Sequence[Sequence[complex]] | np.ndarray | Any,
+        *,
+        dt: float = 1.0,
+        normalize_trace: bool = True,
+        enforce_contractivity: bool = True,
+        raise_on_violation: bool = False,
+        symmetrize: bool = True,
+    ) -> Any:
+        """Advance ``density`` by ``dt`` enforcing trace and contractivity control."""
+
+        matrix = ensure_array(density, dtype=np.complex128, backend=self.backend)
+        dim = self.hilbert_space.dimension
+        if matrix.shape != (dim, dim):
+            raise ValueError(
+                "Density operator dimension mismatch: "
+                f"expected {(dim, dim)}, received {matrix.shape!r}."
+            )
+
+        initial_norm = None
+        if enforce_contractivity:
+            trace_value = _trace(matrix, backend=self.backend)
+            trace_backend = trace_value.backend / dim
+            centered = matrix - trace_backend * self._identity_backend
+            initial_norm_backend = self.backend.norm(centered, ord="fro")
+            initial_norm = float(np.asarray(ensure_numpy(initial_norm_backend, backend=self.backend)))
+
+        vector = _vectorize_density(matrix, backend=self.backend)
+        propagator = self._propagator_backend(dt)
+        evolved_vec = self.backend.matmul(propagator, vector)
+        evolved = _devectorize_density(evolved_vec, dim, backend=self.backend)
+
+        if symmetrize:
+            evolved = 0.5 * (evolved + self.backend.conjugate_transpose(evolved))
+
+        if normalize_trace:
+            trace_value = _trace(evolved, backend=self.backend)
+            if np.isclose(trace_value.numpy, 0.0, atol=self.atol):
+                raise ValueError("Trace collapsed below tolerance during evolution.")
+            if not np.isclose(trace_value.numpy, 1.0, atol=10 * self.atol):
+                evolved = evolved / trace_value.backend
+
+        if enforce_contractivity and initial_norm is not None:
+            trace_value = _trace(evolved, backend=self.backend)
+            trace_backend = trace_value.backend / dim
+            centered = evolved - trace_backend * self._identity_backend
+            evolved_norm_backend = self.backend.norm(centered, ord="fro")
+            evolved_norm = float(np.asarray(ensure_numpy(evolved_norm_backend, backend=self.backend)))
+            self._last_contractivity_gap = initial_norm - evolved_norm
+            if raise_on_violation and self._last_contractivity_gap < -5 * self.atol:
+                raise ValueError(
+                    "Contractivity violated: Frobenius norm increased beyond tolerance."
+                )
+        else:
+            self._last_contractivity_gap = float("nan")
+
+        return evolved
+
+    def evolve(
+        self,
+        density: Sequence[Sequence[complex]] | np.ndarray | Any,
+        *,
+        steps: int,
+        dt: float = 1.0,
+        normalize_trace: bool = True,
+        enforce_contractivity: bool = True,
+        raise_on_violation: bool = False,
+        symmetrize: bool = True,
+    ) -> Any:
+        """Return trajectory of density operators for the contractive semigroup."""
+
+        if steps < 0:
+            raise ValueError("steps must be non-negative.")
+
+        current = ensure_array(density, dtype=np.complex128, backend=self.backend)
+        dim = self.hilbert_space.dimension
+        if current.shape != (dim, dim):
+            raise ValueError(
+                "Density operator dimension mismatch: "
+                f"expected {(dim, dim)}, received {current.shape!r}."
+            )
+
+        trajectory: list[Any] = [current]
+        for _ in range(steps):
+            current = self.step(
+                current,
+                dt=dt,
+                normalize_trace=normalize_trace,
+                enforce_contractivity=enforce_contractivity,
+                raise_on_violation=raise_on_violation,
+                symmetrize=symmetrize,
+            )
+            trajectory.append(current)
+        return self.backend.stack(trajectory, axis=0)

tnfr/mathematics/epi.py

@@ -0,0 +1,254 @@
+"""EPI elements and algebraic helpers for the TNFR Banach space."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Mapping, Sequence
+
+import numpy as np
+
+__all__ = [
+    "BEPIElement",
+    "CoherenceEvaluation",
+    "evaluate_coherence_transform",
+]
+
+
+class _EPIValidators:
+    """Shared validation helpers for EPI Banach constructions."""
+
+    _complex_dtype = np.complex128
+
+    @staticmethod
+    def _as_array(values: Sequence[complex] | np.ndarray, *, dtype: np.dtype) -> np.ndarray:
+        array = np.asarray(values, dtype=dtype)
+        if array.ndim != 1:
+            raise ValueError("Inputs must be one-dimensional arrays.")
+        if not np.all(np.isfinite(array)):
+            raise ValueError("Inputs must not contain NaNs or infinities.")
+        return array
+
+    @classmethod
+    def _validate_grid(cls, grid: Sequence[float] | np.ndarray, expected_size: int) -> np.ndarray:
+        array = np.asarray(grid, dtype=float)
+        if array.ndim != 1:
+            raise ValueError("x_grid must be one-dimensional.")
+        if array.size != expected_size:
+            raise ValueError("x_grid length must match continuous component.")
+        if array.size < 2:
+            raise ValueError("x_grid must contain at least two points.")
+        if not np.all(np.isfinite(array)):
+            raise ValueError("x_grid must not contain NaNs or infinities.")
+
+        spacings = np.diff(array)
+        if np.any(spacings <= 0):
+            raise ValueError("x_grid must be strictly increasing.")
+        if not np.allclose(spacings, spacings[0], rtol=1e-9, atol=1e-12):
+            raise ValueError("x_grid must be uniform for finite-difference stability.")
+        return array
+
+    @classmethod
+    def validate_domain(
+        cls,
+        f_continuous: Sequence[complex] | np.ndarray,
+        a_discrete: Sequence[complex] | np.ndarray,
+        x_grid: Sequence[float] | np.ndarray | None = None,
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray | None]:
+        """Validate dimensionality and sampling grid compatibility."""
+
+        f_array = cls._as_array(f_continuous, dtype=cls._complex_dtype)
+        a_array = cls._as_array(a_discrete, dtype=cls._complex_dtype)
+
+        if x_grid is None:
+            return f_array, a_array, None
+
+        grid_array = cls._validate_grid(x_grid, f_array.size)
+        return f_array, a_array, grid_array
+
+
+@dataclass(frozen=True)
+class BEPIElement(_EPIValidators):
+    """Concrete :math:`C^0([0,1]) \oplus \ell^2` element with TNFR operations."""
+
+    f_continuous: Sequence[complex] | np.ndarray
+    a_discrete: Sequence[complex] | np.ndarray
+    x_grid: Sequence[float] | np.ndarray
+
+    def __post_init__(self) -> None:
+        f_array, a_array, grid = self.validate_domain(self.f_continuous, self.a_discrete, self.x_grid)
+        if grid is None:
+            raise ValueError("x_grid is mandatory for BEPIElement instances.")
+        object.__setattr__(self, "f_continuous", f_array)
+        object.__setattr__(self, "a_discrete", a_array)
+        object.__setattr__(self, "x_grid", grid)
+
+    def _assert_compatible(self, other: BEPIElement) -> None:
+        if self.f_continuous.shape != other.f_continuous.shape:
+            raise ValueError("Continuous components must share shape for direct sums.")
+        if self.a_discrete.shape != other.a_discrete.shape:
+            raise ValueError("Discrete tails must share shape for direct sums.")
+        if not np.allclose(self.x_grid, other.x_grid, rtol=1e-12, atol=1e-12):
+            raise ValueError("x_grid must match to combine EPI elements.")
+
+    def direct_sum(self, other: BEPIElement) -> BEPIElement:
+        """Return the algebraic direct sum ``self ⊕ other``."""
+
+        self._assert_compatible(other)
+        return BEPIElement(self.f_continuous + other.f_continuous, self.a_discrete + other.a_discrete, self.x_grid)
+
+    def tensor(self, vector: Sequence[complex] | np.ndarray) -> np.ndarray:
+        """Return the tensor product between the discrete tail and a Hilbert vector."""
+
+        hilbert_vector = self._as_array(vector, dtype=self._complex_dtype)
+        return np.outer(self.a_discrete, hilbert_vector)
+
+    def adjoint(self) -> BEPIElement:
+        """Return the conjugate element representing the ``*`` operation."""
+
+        return BEPIElement(np.conjugate(self.f_continuous), np.conjugate(self.a_discrete), self.x_grid)
+
+    @staticmethod
+    def _apply_transform(transform: Callable[[np.ndarray], np.ndarray], values: np.ndarray) -> np.ndarray:
+        result = np.asarray(transform(values), dtype=np.complex128)
+        if result.shape != values.shape:
+            raise ValueError("Transforms must preserve the element shape.")
+        if not np.all(np.isfinite(result)):
+            raise ValueError("Transforms must return finite values.")
+        return result
+
+    def compose(
+        self,
+        transform: Callable[[np.ndarray], np.ndarray],
+        *,
+        spectral_transform: Callable[[np.ndarray], np.ndarray] | None = None,
+    ) -> BEPIElement:
+        """Compose the element with linear transforms on both components."""
+
+        new_f = self._apply_transform(transform, self.f_continuous)
+        spectral_fn = spectral_transform or transform
+        new_a = self._apply_transform(spectral_fn, self.a_discrete)
+        return BEPIElement(new_f, new_a, self.x_grid)
+
+    def _max_magnitude(self) -> float:
+        mags = []
+        if self.f_continuous.size:
+            mags.append(float(np.max(np.abs(self.f_continuous))))
+        if self.a_discrete.size:
+            mags.append(float(np.max(np.abs(self.a_discrete))))
+        return float(max(mags)) if mags else 0.0
+
+    def __float__(self) -> float:
+        return self._max_magnitude()
+
+    def __abs__(self) -> float:
+        return self._max_magnitude()
+
+
+@dataclass(frozen=True)
+class CoherenceEvaluation:
+    """Container describing the outcome of a coherence transform evaluation."""
+
+    element: BEPIElement
+    transformed: BEPIElement
+    coherence_before: float
+    coherence_after: float
+    kappa: float
+    tolerance: float
+    satisfied: bool
+    required: float
+    deficit: float
+    ratio: float
+
+
+def evaluate_coherence_transform(
+    element: BEPIElement,
+    transform: Callable[[BEPIElement], BEPIElement],
+    *,
+    kappa: float = 1.0,
+    tolerance: float = 1e-9,
+    space: "BanachSpaceEPI" | None = None,
+    norm_kwargs: Mapping[str, float] | None = None,
+) -> CoherenceEvaluation:
+    """Apply ``transform`` to ``element`` and verify a coherence inequality.
+
+    Parameters
+    ----------
+    element:
+        The :class:`BEPIElement` subject to the transformation.
+    transform:
+        Callable receiving ``element`` and returning the transformed
+        :class:`BEPIElement`.  The callable is expected to preserve the
+        structural sampling grid and dimensionality of the element.
+    kappa:
+        Factor on the right-hand side of the inequality ``C(T(EPI)) ≥ κ·C(EPI)``.
+    tolerance:
+        Non-negative slack applied to the inequality.  When
+        ``C(T(EPI)) + tolerance`` exceeds ``κ·C(EPI)`` the check succeeds.
+    space:
+        Optional :class:`~tnfr.mathematics.spaces.BanachSpaceEPI` instance used
+        to compute the coherence norm.  When omitted, a local instance is
+        constructed to avoid circular imports at module import time.
+    norm_kwargs:
+        Optional keyword arguments forwarded to
+        :meth:`BanachSpaceEPI.coherence_norm`.
+
+    Returns
+    -------
+    CoherenceEvaluation
+        Dataclass capturing the before/after coherence values together with the
+        inequality verdict.
+    """
+
+    if kappa < 0:
+        raise ValueError("kappa must be non-negative.")
+    if tolerance < 0:
+        raise ValueError("tolerance must be non-negative.")
+
+    if norm_kwargs is None:
+        norm_kwargs = {}
+
+    from .spaces import BanachSpaceEPI  # Local import to avoid circular dependency
+
+    working_space = space if space is not None else BanachSpaceEPI()
+
+    coherence_before = working_space.coherence_norm(
+        element.f_continuous,
+        element.a_discrete,
+        x_grid=element.x_grid,
+        **norm_kwargs,
+    )
+
+    transformed = transform(element)
+    if not isinstance(transformed, BEPIElement):
+        raise TypeError("transform must return a BEPIElement instance.")
+
+    coherence_after = working_space.coherence_norm(
+        transformed.f_continuous,
+        transformed.a_discrete,
+        x_grid=transformed.x_grid,
+        **norm_kwargs,
+    )
+
+    required = kappa * coherence_before
+    satisfied = coherence_after + tolerance >= required
+    deficit = max(0.0, required - coherence_after)
+
+    if coherence_before > 0:
+        ratio = coherence_after / coherence_before
+    elif coherence_after > tolerance:
+        ratio = float("inf")
+    else:
+        ratio = 1.0
+
+    return CoherenceEvaluation(
+        element=element,
+        transformed=transformed,
+        coherence_before=coherence_before,
+        coherence_after=coherence_after,
+        kappa=kappa,
+        tolerance=tolerance,
+        satisfied=satisfied,
+        required=required,
+        deficit=deficit,
+        ratio=ratio,
+    )
+