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

tnfr/mathematics/generators.pyi

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import numpy as np
+from numpy.random import Generator
+from typing import Sequence
+
+__all__ = ["build_delta_nfr", "build_lindblad_delta_nfr"]
+
+def build_delta_nfr(
+    dim: int,
+    *,
+    topology: str = "laplacian",
+    nu_f: float = 1.0,
+    scale: float = 1.0,
+    rng: Generator | None = None,
+) -> np.ndarray: ...
+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-09,
+) -> np.ndarray: ...

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/metrics.pyi

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import numpy as np
+from .operators import CoherenceOperator
+from typing import Sequence
+
+__all__ = ["dcoh"]
+
+def dcoh(
+    psi1: Sequence[complex] | np.ndarray,
+    psi2: Sequence[complex] | np.ndarray,
+    operator: CoherenceOperator,
+    *,
+    normalise: bool = True,
+    atol: float = 1e-09,
+) -> float: ...

tnfr/mathematics/operators.py

@@ -0,0 +1,239 @@
+"""Spectral operators modelling coherence and frequency dynamics."""
+
+from __future__ import annotations
+
+from dataclasses import field
+from typing import TYPE_CHECKING, Any, Sequence
+
+import numpy as np
+
+from ..compat.dataclass import dataclass
+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.pyi

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import numpy as np
+from .backend import MathematicsBackend
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+import numpy.typing as npt
+
+__all__ = ["CoherenceOperator", "FrequencyOperator"]
+
+ComplexMatrix = npt.NDArray[np.complexfloating[np.float64, np.float64]]
+ComplexVector = npt.NDArray[np.complexfloating[np.float64, np.float64]]
+
+@dataclass
+class CoherenceOperator:
+    matrix: ComplexMatrix
+    eigenvalues: ComplexVector
+    c_min: float
+    backend: MathematicsBackend = field(init=False, repr=False)
+    def __init__(
+        self,
+        operator: Sequence[Sequence[complex]] | Sequence[complex] | np.ndarray | Any,
+        *,
+        c_min: float | object = ...,
+        ensure_hermitian: bool = True,
+        atol: float = 1e-09,
+        backend: MathematicsBackend | None = None,
+    ) -> None: ...
+    def is_hermitian(self, *, atol: float = 1e-09) -> bool: ...
+    def is_positive_semidefinite(self, *, atol: float = 1e-09) -> bool: ...
+    def spectrum(self) -> ComplexVector: ...
+    def spectral_radius(self) -> float: ...
+    def spectral_bandwidth(self) -> float: ...
+    def expectation(
+        self,
+        state: Sequence[complex] | np.ndarray,
+        *,
+        normalise: bool = True,
+        atol: float = 1e-09,
+    ) -> float: ...
+
+class FrequencyOperator(CoherenceOperator):
+    def __init__(
+        self,
+        operator: Sequence[Sequence[complex]] | Sequence[complex] | np.ndarray | Any,
+        *,
+        ensure_hermitian: bool = True,
+        atol: float = 1e-09,
+        backend: MathematicsBackend | None = None,
+    ) -> None: ...
+    def spectrum(self) -> np.ndarray: ...
+    def is_positive_semidefinite(self, *, atol: float = 1e-09) -> bool: ...
+    def project_frequency(
+        self,
+        state: Sequence[complex] | np.ndarray,
+        *,
+        normalise: bool = True,
+        atol: float = 1e-09,
+    ) -> float: ...

tnfr/mathematics/operators_factory.py

@@ -0,0 +1,124 @@
+"""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`.
+
+    This factory validates inputs, ensures structural invariants (Hermiticity
+    and positive semi-definiteness), and integrates with the TNFR backend
+    abstraction layer.
+
+    Parameters
+    ----------
+    dim : int
+        Dimensionality of the operator's Hilbert space. Must be positive.
+    spectrum : np.ndarray | None, optional
+        Custom eigenvalue spectrum. If None, uses uniform c_min values.
+        Must be real-valued and match dimension.
+    c_min : float, optional
+        Minimum coherence threshold for default spectrum (default: 0.1).
+
+    Returns
+    -------
+    CoherenceOperator
+        Validated coherence operator with backend-native arrays.
+
+    Raises
+    ------
+    ValueError
+        If dimension is invalid, spectrum has wrong shape, or operator
+        violates Hermiticity/PSD constraints.
+    """
+
+    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``.
+
+    This factory validates the input matrix for Hermiticity and constructs
+    a frequency operator that enforces positive semi-definiteness.
+
+    Parameters
+    ----------
+    matrix : np.ndarray
+        Square Hermitian matrix representing the frequency operator.
+        Must be complex128 compatible.
+
+    Returns
+    -------
+    FrequencyOperator
+        Validated frequency operator with backend-native arrays.
+
+    Raises
+    ------
+    ValueError
+        If matrix is not square, not Hermitian, or not positive semidefinite.
+    """
+
+    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

tnfr/mathematics/operators_factory.pyi

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import numpy as np
+from .operators import CoherenceOperator, FrequencyOperator
+
+__all__ = ["make_coherence_operator", "make_frequency_operator"]
+
+def make_coherence_operator(
+    dim: int, *, spectrum: np.ndarray | None = None, c_min: float = 0.1
+) -> CoherenceOperator: ...
+def make_frequency_operator(matrix: np.ndarray) -> FrequencyOperator: ...

tnfr/mathematics/projection.py

@@ -0,0 +1,87 @@
+"""Projection helpers constructing TNFR state vectors."""
+
+from __future__ import annotations
+
+from ..compat.dataclass import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+import numpy as np
+
+if TYPE_CHECKING:  # pragma: no cover - typing hook when numpy.typing is available
+    import numpy.typing as npt
+
+    ComplexVector = npt.NDArray[np.complexfloating[np.float64, np.float64]]
+else:  # pragma: no cover - runtime fallback without numpy.typing
+    ComplexVector = np.ndarray  # type: ignore[assignment]
+
+__all__ = ["StateProjector", "BasicStateProjector"]
+
+
+@runtime_checkable
+class StateProjector(Protocol):
+    """Protocol describing state projection callables.
+
+    Notes
+    -----
+    Marked with @runtime_checkable to enable isinstance() checks for validating
+    state projector implementations conform to the expected callable interface.
+    """
+
+    def __call__(
+        self,
+        epi: float,
+        nu_f: float,
+        theta: float,
+        dim: int,
+        rng: np.random.Generator | None = None,
+    ) -> ComplexVector:
+        """Return a normalised TNFR state vector for the provided parameters."""
+
+
+@dataclass(slots=True)
+class BasicStateProjector:
+    """Canonical projector building deterministic TNFR state vectors.
+
+    The projector maps the structural scalars of a node—its EPI magnitude,
+    structural frequency ``νf`` and phase ``θ``—onto the canonical Hilbert
+    basis.  The resulting vector encodes a coherent amplitude envelope derived
+    from the structural intensity while the complex exponential captures the
+    phase progression across the local modes.  Optional stochastic excitation is
+    injected via a :class:`numpy.random.Generator` to model controlled
+    dissonance while preserving determinism when a seed is provided.
+    """
+
+    dtype: np.dtype[np.complexfloating[np.float64, np.float64]] = np.dtype(
+        np.complex128
+    )
+    atol: float = 1e-12
+
+    def __call__(
+        self,
+        epi: float,
+        nu_f: float,
+        theta: float,
+        dim: int,
+        rng: np.random.Generator | None = None,
+    ) -> ComplexVector:
+        if dim <= 0:
+            raise ValueError("State dimension must be a positive integer.")
+
+        indices = np.arange(1, dim + 1, dtype=float)
+        phase_progression = theta + (nu_f + 1.0) * indices / max(dim, 1)
+        envelope = np.abs(epi) + 0.5 * indices / dim + 1.0
+        base_vector = envelope * np.exp(1j * phase_progression)
+
+        if rng is not None:
+            noise_scale = (np.abs(epi) + np.abs(nu_f) + 1.0) * 0.05
+            real_noise = rng.standard_normal(dim)
+            imag_noise = rng.standard_normal(dim)
+            stochastic = noise_scale * (real_noise + 1j * imag_noise)
+            base_vector = base_vector + stochastic
+
+        norm = np.linalg.norm(base_vector)
+        if np.isclose(norm, 0.0, atol=self.atol):
+            raise ValueError("Cannot normalise a null state vector.")
+
+        normalised = base_vector / norm
+        return np.asarray(normalised, dtype=self.dtype)