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

tnfr/mathematics/generators.py

@@ -0,0 +1,222 @@
+"""ΔNFR generator construction utilities."""
+from __future__ import annotations
+
+from typing import Final, Sequence
+
+import numpy as np
+from numpy.random import Generator
+
+from .backend import ensure_array, ensure_numpy, get_backend
+
+__all__ = ["build_delta_nfr", "build_lindblad_delta_nfr"]
+
+_TOPOLOGIES: Final[set[str]] = {"laplacian", "adjacency"}
+
+
+def _ring_adjacency(dim: int) -> np.ndarray:
+    """Return the adjacency matrix for a coherent ring topology."""
+
+    adjacency = np.zeros((dim, dim), dtype=float)
+    if dim == 1:
+        return adjacency
+
+    indices = np.arange(dim)
+    adjacency[indices, (indices + 1) % dim] = 1.0
+    adjacency[(indices + 1) % dim, indices] = 1.0
+    return adjacency
+
+
+def _laplacian_from_adjacency(adjacency: np.ndarray) -> np.ndarray:
+    """Construct a Laplacian operator from an adjacency matrix."""
+
+    degrees = adjacency.sum(axis=1)
+    laplacian = np.diag(degrees) - adjacency
+    return laplacian
+
+
+def _hermitian_noise(dim: int, rng: Generator) -> np.ndarray:
+    """Generate a Hermitian noise matrix with reproducible statistics."""
+
+    real = rng.standard_normal((dim, dim))
+    imag = rng.standard_normal((dim, dim))
+    noise = real + 1j * imag
+    return 0.5 * (noise + noise.conj().T)
+
+
+def _as_square_matrix(
+    matrix: Sequence[Sequence[complex]] | np.ndarray,
+    *,
+    expected_dim: int | None = None,
+    label: str = "matrix",
+) -> np.ndarray:
+    """Return ``matrix`` as a square :class:`numpy.ndarray` with validation."""
+
+    array = np.asarray(matrix, dtype=np.complex128)
+    if array.ndim != 2 or array.shape[0] != array.shape[1]:
+        raise ValueError(f"{label} must be a square matrix.")
+    if expected_dim is not None and array.shape[0] != expected_dim:
+        raise ValueError(
+            f"{label} dimension mismatch: expected {expected_dim}, received {array.shape[0]}."
+        )
+    return array
+
+
+def build_delta_nfr(
+    dim: int,
+    *,
+    topology: str = "laplacian",
+    nu_f: float = 1.0,
+    scale: float = 1.0,
+    rng: Generator | None = None,
+) -> np.ndarray:
+    """Construct a Hermitian ΔNFR generator using canonical TNFR topologies.
+
+    Parameters
+    ----------
+    dim:
+        Dimensionality of the Hilbert space supporting the ΔNFR operator.
+    topology:
+        Requested canonical topology. Supported values are ``"laplacian"``
+        and ``"adjacency"``.
+    nu_f:
+        Structural frequency scaling applied to the resulting operator.
+    scale:
+        Additional scaling applied uniformly to the operator amplitude.
+    rng:
+        Optional NumPy :class:`~numpy.random.Generator` used to inject
+        reproducible Hermitian noise.
+    """
+
+    if dim <= 0:
+        raise ValueError("ΔNFR generators require a positive dimensionality.")
+
+    if topology not in _TOPOLOGIES:
+        allowed = ", ".join(sorted(_TOPOLOGIES))
+        raise ValueError(f"Unknown ΔNFR topology: {topology}. Expected one of: {allowed}.")
+
+    adjacency = _ring_adjacency(dim)
+    if topology == "laplacian":
+        base = _laplacian_from_adjacency(adjacency)
+    else:
+        base = adjacency
+
+    matrix = base.astype(np.complex128, copy=False)
+
+    if rng is not None:
+        noise = _hermitian_noise(dim, rng)
+        matrix = matrix + (1.0 / np.sqrt(dim)) * noise
+
+    matrix *= (nu_f * scale)
+    hermitian = 0.5 * (matrix + matrix.conj().T)
+    backend = get_backend()
+    return np.asarray(ensure_numpy(ensure_array(hermitian, backend=backend), backend=backend), dtype=np.complex128)
+
+
+def build_lindblad_delta_nfr(
+    *,
+    hamiltonian: Sequence[Sequence[complex]] | np.ndarray | None = None,
+    collapse_operators: Sequence[Sequence[Sequence[complex]] | np.ndarray] | None = None,
+    dim: int | None = None,
+    nu_f: float = 1.0,
+    scale: float = 1.0,
+    ensure_trace_preserving: bool = True,
+    ensure_contractive: bool = True,
+    atol: float = 1e-9,
+) -> np.ndarray:
+    """Construct a Lindblad ΔNFR generator in Liouville space.
+
+    The resulting matrix acts on vectorised density operators using the
+    canonical column-major flattening.  The construction follows the standard
+    Gorini–Kossakowski–Sudarshan–Lindblad prescription while exposing TNFR
+    semantics through ``ν_f`` and ``scale``.
+
+    Parameters
+    ----------
+    hamiltonian:
+        Optional coherent component.  When ``None`` a null Hamiltonian is
+        assumed.
+    collapse_operators:
+        Iterable with the dissipative operators driving the contractive
+        semigroup.  Each entry must be square with the same dimension as the
+        Hamiltonian.  When ``None`` the generator reduces to the coherent part.
+    dim:
+        Explicit Hilbert-space dimension.  Only required if neither
+        ``hamiltonian`` nor ``collapse_operators`` are provided.  When supplied,
+        it must match the dimension inferred from the Hamiltonian and collapse
+        operators.
+    nu_f, scale:
+        Structural frequency scaling applied uniformly to the final generator.
+    ensure_trace_preserving:
+        When ``True`` (default) the resulting superoperator is validated to
+        leave the identity invariant.
+    ensure_contractive:
+        When ``True`` (default) the spectrum is required to have non-positive
+        real parts within ``atol``.
+    atol:
+        Absolute tolerance used for Hermiticity, trace and spectral checks.
+    """
+
+    operators = list(collapse_operators or [])
+
+    inferred_dim: int | None = dim
+    if hamiltonian is not None:
+        hermitian = _as_square_matrix(hamiltonian, label="hamiltonian")
+        inferred_dim = hermitian.shape[0]
+    elif operators:
+        inferred_dim = _as_square_matrix(operators[0], label="collapse operator[0]").shape[0]
+
+    if inferred_dim is None:
+        raise ValueError("dim must be supplied when no operators are provided.")
+
+    if inferred_dim <= 0:
+        raise ValueError("ΔNFR generators require a positive dimension.")
+
+    dimension = inferred_dim
+
+    if dim is not None and dim != dimension:
+        raise ValueError(
+            "Provided dim is inconsistent with the supplied operators: "
+            f"expected {dimension}, received {dim}."
+        )
+
+    if hamiltonian is None:
+        hermitian = np.zeros((dimension, dimension), dtype=np.complex128)
+    else:
+        hermitian = _as_square_matrix(hamiltonian, expected_dim=dimension, label="hamiltonian")
+        if not np.allclose(hermitian, hermitian.conj().T, atol=atol):
+            raise ValueError("Hamiltonian component must be Hermitian within tolerance.")
+
+    dissipators = [
+        _as_square_matrix(operator, expected_dim=dimension, label=f"collapse operator[{index}]")
+        for index, operator in enumerate(operators)
+    ]
+
+    identity = np.eye(dimension, dtype=np.complex128)
+    liouvillian = -1j * (np.kron(identity, hermitian) - np.kron(hermitian.T, identity))
+
+    for operator in dissipators:
+        adjoint_product = operator.conj().T @ operator
+        liouvillian += np.kron(operator.conj(), operator)
+        liouvillian -= 0.5 * np.kron(identity, adjoint_product)
+        liouvillian -= 0.5 * np.kron(adjoint_product.T, identity)
+
+    liouvillian *= (nu_f * scale)
+
+    if ensure_trace_preserving:
+        identity_vec = identity.reshape(dimension * dimension, order="F")
+        left_residual = identity_vec.conj().T @ liouvillian
+        if not np.allclose(left_residual, np.zeros_like(left_residual), atol=10 * atol):
+            raise ValueError("Lindblad generator must preserve the trace of density operators.")
+
+    backend = get_backend()
+    liouvillian_backend = ensure_array(liouvillian, backend=backend)
+
+    if ensure_contractive:
+        eigenvalues_backend, _ = backend.eig(liouvillian_backend)
+        eigenvalues = ensure_numpy(eigenvalues_backend, backend=backend)
+        if np.max(eigenvalues.real) > atol:
+            raise ValueError(
+                "Lindblad generator is not contractive: spectrum has positive real components."
+            )
+
+    return np.asarray(ensure_numpy(liouvillian_backend, backend=backend), dtype=np.complex128)

tnfr/mathematics/metrics.py

@@ -0,0 +1,119 @@
+"""Structural metrics preserving TNFR coherence invariants."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import numpy as np
+
+from .operators import CoherenceOperator
+
+__all__ = ["dcoh"]
+
+
+def _as_coherent_vector(
+    state: Sequence[complex] | np.ndarray,
+    *,
+    dimension: int,
+) -> np.ndarray:
+    """Return a complex vector compatible with ``CoherenceOperator`` matrices."""
+
+    vector = np.asarray(state, dtype=np.complex128)
+    if vector.ndim != 1 or vector.shape[0] != dimension:
+        raise ValueError(
+            "State vector dimension mismatch: "
+            f"expected ({dimension},), received {vector.shape!r}."
+        )
+    return vector
+
+
+def _normalise_vector(
+    vector: np.ndarray,
+    *,
+    atol: float,
+    label: str,
+) -> np.ndarray:
+    norm = np.linalg.norm(vector)
+    if np.isclose(norm, 0.0, atol=atol):
+        raise ValueError(f"Cannot normalise null coherence state {label}.")
+    return vector / norm
+
+
+def dcoh(
+    psi1: Sequence[complex] | np.ndarray,
+    psi2: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-9,
+) -> float:
+    """Return the TNFR dissimilarity of coherence between ``psi1`` and ``psi2``.
+
+    The metric follows the canonical TNFR expectation contracts:
+
+    * States are converted to Hilbert-compatible complex vectors respecting the
+      ``CoherenceOperator`` dimension, preserving the spectral phase space.
+    * Optional normalisation keeps overlap and expectations coherent with
+      unit-phase contracts, preventing coherence inflation.
+    * Expectation values ``⟨ψ|Ĉ|ψ⟩`` must remain strictly positive; null or
+      negative projections signal a collapse and therefore raise ``ValueError``.
+
+    Parameters mirror the runtime helpers so callers can rely on the same
+    tolerances.  Numerical overflow is contained by bounding intermediate ratios
+    within ``[0, 1]`` up to ``atol`` before applying the Bures-style angle
+    ``arccos(√ratio)``, ensuring the returned dissimilarity remains within the
+    TNFR coherence interval.
+    """
+
+    dimension = operator.matrix.shape[0]
+    vector1 = _as_coherent_vector(psi1, dimension=dimension)
+    vector2 = _as_coherent_vector(psi2, dimension=dimension)
+
+    if normalise:
+        vector1_norm = _normalise_vector(vector1, atol=atol, label="ψ₁")
+        vector2_norm = _normalise_vector(vector2, atol=atol, label="ψ₂")
+    else:
+        vector1_norm = vector1
+        vector2_norm = vector2
+
+    weighted_vector2 = operator.matrix @ vector2_norm
+    if weighted_vector2.shape != vector2_norm.shape:
+        raise ValueError("Operator application distorted coherence dimensionality.")
+
+    cross = np.vdot(vector1_norm, weighted_vector2)
+    if not np.isfinite(cross):
+        raise ValueError("State overlap produced a non-finite value.")
+
+    expect1 = float(operator.expectation(vector1, normalise=normalise, atol=atol))
+    expect2 = float(operator.expectation(vector2, normalise=normalise, atol=atol))
+
+    for idx, value in enumerate((expect1, expect2), start=1):
+        if not np.isfinite(value):
+            raise ValueError(f"Coherence expectation diverged for state ψ{idx}.")
+        if value <= 0.0 or np.isclose(value, 0.0, atol=atol):
+            raise ValueError(
+                "Coherence expectation must remain strictly positive to"
+                f" preserve TNFR invariants (state ψ{idx})."
+            )
+
+    denominator = expect1 * expect2
+    if not np.isfinite(denominator):
+        raise ValueError("Coherence expectations produced a non-finite product.")
+    if denominator <= 0.0 or np.isclose(denominator, 0.0, atol=atol):
+        raise ValueError(
+            "Product of coherence expectations must be strictly positive to"
+            " evaluate dissimilarity."
+        )
+
+    ratio = (np.abs(cross) ** 2) / denominator
+    eps = max(np.finfo(float).eps * 10.0, atol)
+    if ratio < -eps:
+        raise ValueError("Overlap produced a negative coherence ratio.")
+    if ratio < 0.0:
+        ratio = 0.0
+    if ratio > 1.0 + eps:
+        raise ValueError("Coherence ratio exceeded unity beyond tolerance.")
+    if ratio > 1.0:
+        ratio = 1.0
+
+    return float(np.arccos(np.sqrt(ratio)))

tnfr/mathematics/operators.py

@@ -0,0 +1,233 @@
+"""Spectral operators modelling coherence and frequency dynamics."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Sequence
+
+import numpy as np
+
+from .backend import MathematicsBackend, ensure_array, ensure_numpy, get_backend
+
+if TYPE_CHECKING:  # pragma: no cover - typing imports only
+    import numpy.typing as npt
+
+    ComplexVector = npt.NDArray[np.complexfloating[np.float64, np.float64]]
+    ComplexMatrix = npt.NDArray[np.complexfloating[np.float64, np.float64]]
+else:  # pragma: no cover - runtime alias
+    ComplexVector = np.ndarray
+    ComplexMatrix = np.ndarray
+
+__all__ = ["CoherenceOperator", "FrequencyOperator"]
+
+DEFAULT_C_MIN: float = 0.1
+_C_MIN_UNSET = object()
+
+
+def _as_complex_vector(
+    vector: Sequence[complex] | np.ndarray | Any,
+    *,
+    backend: MathematicsBackend,
+) -> Any:
+    arr = ensure_array(vector, dtype=np.complex128, backend=backend)
+    if getattr(arr, "ndim", len(getattr(arr, "shape", ()))) != 1:
+        raise ValueError("Vector input must be one-dimensional.")
+    return arr
+
+
+def _as_complex_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("Operator matrix must be square.")
+    return arr
+
+
+def _make_diagonal(values: Any, *, backend: MathematicsBackend) -> Any:
+    dim = int(getattr(values, "shape")[0])
+    identity = ensure_array(np.eye(dim, dtype=np.complex128), backend=backend)
+    return backend.einsum("i,ij->ij", values, identity)
+
+
+@dataclass(slots=True)
+class CoherenceOperator:
+    """Hermitian operator capturing coherence redistribution.
+
+    The operator encapsulates how a TNFR EPI redistributes coherence across
+    its spectral components.  It supports construction either from an explicit
+    matrix expressed on the canonical basis or from a pre-computed list of
+    eigenvalues (interpreted as already diagonalised).  The minimal eigenvalue
+    ``c_min`` is tracked explicitly so structural stability thresholds are easy
+    to evaluate during simulations.  The precedence for determining the stored
+    threshold is: an explicit ``c_min`` wins, otherwise the spectral floor
+    (minimum real eigenvalue) is used, with ``0.1`` acting as the canonical
+    fallback for callers that still wish to supply a fixed number.
+
+    When instantiated under an automatic differentiation backend (JAX, PyTorch)
+    the spectral decomposition remains differentiable provided the supplied
+    operator is non-defective.  NumPy callers receive ``numpy.ndarray`` outputs
+    and all tolerance checks match the historical semantics.
+    """
+
+    matrix: ComplexMatrix
+    eigenvalues: ComplexVector
+    c_min: float
+    backend: MathematicsBackend = field(init=False, repr=False)
+    _matrix_backend: Any = field(init=False, repr=False)
+    _eigenvalues_backend: Any = field(init=False, repr=False)
+
+    def __init__(
+        self,
+        operator: Sequence[Sequence[complex]] | Sequence[complex] | np.ndarray | Any,
+        *,
+        c_min: float | object = _C_MIN_UNSET,
+        ensure_hermitian: bool = True,
+        atol: float = 1e-9,
+        backend: MathematicsBackend | None = None,
+    ) -> None:
+        resolved_backend = backend or get_backend()
+        operand = ensure_array(operator, dtype=np.complex128, backend=resolved_backend)
+        if getattr(operand, "ndim", len(getattr(operand, "shape", ()))) == 1:
+            eigvals_backend = _as_complex_vector(operand, backend=resolved_backend)
+            if ensure_hermitian:
+                imag = ensure_numpy(eigvals_backend.imag, backend=resolved_backend)
+                if not np.allclose(imag, 0.0, atol=atol):
+                    raise ValueError("Hermitian operators require real eigenvalues.")
+            matrix_backend = _make_diagonal(eigvals_backend, backend=resolved_backend)
+            eigenvalues_backend = eigvals_backend
+        else:
+            matrix_backend = _as_complex_matrix(operand, backend=resolved_backend)
+            if ensure_hermitian and not self._check_hermitian(matrix_backend, atol=atol, backend=resolved_backend):
+                raise ValueError("Coherence operator must be Hermitian.")
+            if ensure_hermitian:
+                eigenvalues_backend, _ = resolved_backend.eigh(matrix_backend)
+            else:
+                eigenvalues_backend, _ = resolved_backend.eig(matrix_backend)
+
+        self.backend = resolved_backend
+        self._matrix_backend = matrix_backend
+        self._eigenvalues_backend = eigenvalues_backend
+        self.matrix = ensure_numpy(matrix_backend, backend=resolved_backend)
+        self.eigenvalues = ensure_numpy(eigenvalues_backend, backend=resolved_backend)
+        derived_c_min = float(np.min(self.eigenvalues.real))
+        if c_min is _C_MIN_UNSET:
+            self.c_min = derived_c_min
+        else:
+            self.c_min = float(c_min)
+
+    @staticmethod
+    def _check_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 is_hermitian(self, *, atol: float = 1e-9) -> bool:
+        """Return ``True`` when the operator matches its adjoint."""
+
+        return self._check_hermitian(self._matrix_backend, atol=atol, backend=self.backend)
+
+    def is_positive_semidefinite(self, *, atol: float = 1e-9) -> bool:
+        """Check that all eigenvalues are non-negative within ``atol``."""
+
+        return bool(np.all(self.eigenvalues.real >= -atol))
+
+    def spectrum(self) -> ComplexVector:
+        """Return the complex eigenvalue spectrum."""
+
+        return np.asarray(self.eigenvalues, dtype=np.complex128)
+
+    def spectral_radius(self) -> float:
+        """Return the largest magnitude eigenvalue (spectral radius)."""
+
+        return float(np.max(np.abs(self.eigenvalues)))
+
+    def spectral_bandwidth(self) -> float:
+        """Return the real bandwidth ``max(λ) - min(λ)``."""
+
+        eigvals = self.eigenvalues.real
+        return float(np.max(eigvals) - np.min(eigvals))
+
+    def expectation(
+        self,
+        state: Sequence[complex] | np.ndarray,
+        *,
+        normalise: bool = True,
+        atol: float = 1e-9,
+    ) -> float:
+        vector_backend = _as_complex_vector(state, backend=self.backend)
+        if vector_backend.shape != (self.matrix.shape[0],):
+            raise ValueError("State vector dimension mismatch with operator.")
+        working = vector_backend
+        if normalise:
+            norm_value = ensure_numpy(self.backend.norm(working), backend=self.backend)
+            norm = float(norm_value)
+            if np.isclose(norm, 0.0):
+                raise ValueError("Cannot normalise a null state vector.")
+            working = working / norm
+        column = working[..., None]
+        bra = self.backend.conjugate_transpose(column)
+        evolved = self.backend.matmul(self._matrix_backend, column)
+        expectation_backend = self.backend.matmul(bra, evolved)
+        expectation = ensure_numpy(expectation_backend, backend=self.backend)
+        expectation_scalar = complex(np.asarray(expectation).reshape(()))
+        if abs(expectation_scalar.imag) > atol:
+            raise ValueError(
+                "Expectation value carries an imaginary component beyond tolerance."
+            )
+        eps = np.finfo(float).eps
+        tol = max(1000.0, float(atol / eps)) if atol > 0 else 1000.0
+        real_expectation = np.real_if_close(expectation_scalar, tol=tol)
+        if np.iscomplexobj(real_expectation):
+            raise ValueError("Expectation remained complex after coercion.")
+        return float(real_expectation)
+
+
+class FrequencyOperator(CoherenceOperator):
+    """Operator encoding the structural frequency distribution.
+
+    The frequency operator reuses the coherence machinery but enforces a real
+    spectrum representing the structural hertz (νf) each mode contributes.  Its
+    helpers therefore constrain outputs to the real axis and expose projections
+    suited for telemetry collection.
+    """
+
+    def __init__(
+        self,
+        operator: Sequence[Sequence[complex]] | Sequence[complex] | np.ndarray | Any,
+        *,
+        ensure_hermitian: bool = True,
+        atol: float = 1e-9,
+        backend: MathematicsBackend | None = None,
+    ) -> None:
+        super().__init__(
+            operator,
+            ensure_hermitian=ensure_hermitian,
+            atol=atol,
+            backend=backend,
+        )
+
+    def spectrum(self) -> np.ndarray:
+        """Return the real-valued structural frequency spectrum."""
+
+        return np.asarray(self.eigenvalues.real, dtype=float)
+
+    def is_positive_semidefinite(self, *, atol: float = 1e-9) -> bool:
+        """Frequency spectra must be non-negative to preserve νf semantics."""
+
+        return bool(np.all(self.spectrum() >= -atol))
+
+    def project_frequency(
+        self,
+        state: Sequence[complex] | np.ndarray,
+        *,
+        normalise: bool = True,
+        atol: float = 1e-9,
+    ) -> float:
+        return self.expectation(state, normalise=normalise, atol=atol)

tnfr/mathematics/operators_factory.py

@@ -0,0 +1,71 @@
+"""Factory helpers to assemble TNFR coherence and frequency operators."""
+from __future__ import annotations
+
+import numpy as np
+
+from .backend import ensure_array, ensure_numpy, get_backend
+from .operators import CoherenceOperator, FrequencyOperator
+
+__all__ = ["make_coherence_operator", "make_frequency_operator"]
+
+_ATOL = 1e-9
+
+
+def _validate_dimension(dim: int) -> int:
+    if int(dim) != dim:
+        raise ValueError("Operator dimension must be an integer.")
+    if dim <= 0:
+        raise ValueError("Operator dimension must be strictly positive.")
+    return int(dim)
+
+
+def make_coherence_operator(
+    dim: int,
+    *,
+    spectrum: np.ndarray | None = None,
+    c_min: float = 0.1,
+) -> CoherenceOperator:
+    """Return a Hermitian positive semidefinite :class:`CoherenceOperator`."""
+
+    dimension = _validate_dimension(dim)
+    if not np.isfinite(c_min):
+        raise ValueError("Coherence threshold ``c_min`` must be finite.")
+
+    backend = get_backend()
+
+    if spectrum is None:
+        eigenvalues_backend = ensure_array(np.full(dimension, float(c_min), dtype=float), backend=backend)
+    else:
+        eigenvalues_backend = ensure_array(spectrum, dtype=np.complex128, backend=backend)
+        eigenvalues_np = ensure_numpy(eigenvalues_backend, backend=backend)
+        if eigenvalues_np.ndim != 1:
+            raise ValueError("Coherence spectrum must be one-dimensional.")
+        if eigenvalues_np.shape[0] != dimension:
+            raise ValueError("Coherence spectrum size must match operator dimension.")
+        if np.any(np.abs(eigenvalues_np.imag) > _ATOL):
+            raise ValueError("Coherence spectrum must be real-valued within tolerance.")
+        eigenvalues_backend = ensure_array(eigenvalues_np.real.astype(float, copy=False), backend=backend)
+
+    operator = CoherenceOperator(eigenvalues_backend, c_min=c_min, backend=backend)
+    if not operator.is_hermitian(atol=_ATOL):
+        raise ValueError("Coherence operator must be Hermitian.")
+    if not operator.is_positive_semidefinite(atol=_ATOL):
+        raise ValueError("Coherence operator must be positive semidefinite.")
+    return operator
+
+
+def make_frequency_operator(matrix: np.ndarray) -> FrequencyOperator:
+    """Return a Hermitian PSD :class:`FrequencyOperator` from ``matrix``."""
+
+    backend = get_backend()
+    array_backend = ensure_array(matrix, dtype=np.complex128, backend=backend)
+    array_np = ensure_numpy(array_backend, backend=backend)
+    if array_np.ndim != 2 or array_np.shape[0] != array_np.shape[1]:
+        raise ValueError("Frequency operator matrix must be square.")
+    if not np.allclose(array_np, array_np.conj().T, atol=_ATOL):
+        raise ValueError("Frequency operator must be Hermitian within tolerance.")
+
+    operator = FrequencyOperator(array_backend, backend=backend)
+    if not operator.is_positive_semidefinite(atol=_ATOL):
+        raise ValueError("Frequency operator must be positive semidefinite.")
+    return operator