best-linear-approximation 0.1.0__py3-none-any.whl

best_linear_approximation/__init__.py

@@ -0,0 +1,43 @@
+"""Tools for best linear approximation."""
+
+from __future__ import annotations
+
+from best_linear_approximation import _dataloader as dataloader
+from best_linear_approximation import robust
+from best_linear_approximation._bla import (
+    EstimationMethod,
+    ExperimentInfo,
+    FrequencyInfo,
+    FrequencyResponse,
+    NonparametricBLA,
+)
+from best_linear_approximation._dataloader import (
+    load_f16,
+    load_fine_steering_mirror,
+    load_parallel_wiener_hammerstein,
+    load_silverbox,
+)
+from best_linear_approximation._spectra import (
+    InputSpectrum,
+    OutputSpectrum,
+    Spectra,
+)
+from best_linear_approximation._uncertainty import Uncertainty
+
+__all__ = [
+    "EstimationMethod",
+    "ExperimentInfo",
+    "FrequencyInfo",
+    "FrequencyResponse",
+    "InputSpectrum",
+    "NonparametricBLA",
+    "OutputSpectrum",
+    "Spectra",
+    "Uncertainty",
+    "dataloader",
+    "load_f16",
+    "load_fine_steering_mirror",
+    "load_parallel_wiener_hammerstein",
+    "load_silverbox",
+    "robust",
+]

best_linear_approximation/_argument_preparation.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING, cast, overload
+
+import numpy as np
+
+from best_linear_approximation._array_shapes import add_period_axis, to_experiment_layout
+from best_linear_approximation._exceptions import (
+    NoiseCovarianceUnavailableWarning,
+    PossibleExcitationAmplitudeMismatchWarning,
+    PossiblePeriodMismatchWarning,
+    TotalCovarianceUnavailableWarning,
+)
+from best_linear_approximation._misc import rms, standardize_channels
+from best_linear_approximation._signal_validation import (
+    ContractType,
+    SignalContract,
+    validate_signal_contract,
+)
+from best_linear_approximation._spectral_validation import (
+    resolve_excited_bins,
+    validate_sampling_frequency,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from numpy.typing import NDArray
+
+    from best_linear_approximation._typing import (
+        ExcitedBins,
+        RealArray,
+        SamplingFrequencyHz,
+        TimeDomainSignal,
+    )
+
+# Tuned to pass all tests in "tests/test_argument_preparation.py"
+MINIMUM_RELATIVE_PERIOD_MISMATCH = 0.025  # keep in sync with docstring
+MINIMUM_RELATIVE_REALIZATION_MISMATCH = 0.025  # keep in sync with docstring
+
+
+@overload
+def prepare_arguments(
+    r: None,
+    u: RealArray,
+    y: RealArray,
+    fs: float,
+    excited_bins: NDArray[np.int_] | float,
+    contracts: Mapping[ContractType, SignalContract],
+) -> tuple[
+    None,
+    TimeDomainSignal,
+    TimeDomainSignal,
+    SamplingFrequencyHz,
+    ExcitedBins,
+]: ...
+
+
+@overload
+def prepare_arguments(
+    r: RealArray,
+    u: RealArray,
+    y: RealArray,
+    fs: float,
+    excited_bins: NDArray[np.int_] | float,
+    contracts: Mapping[ContractType, SignalContract],
+) -> tuple[
+    TimeDomainSignal,
+    TimeDomainSignal,
+    TimeDomainSignal,
+    SamplingFrequencyHz,
+    ExcitedBins,
+]: ...
+
+
+def prepare_arguments(  # noqa: PLR0913, PLR0917
+    r: RealArray | None,
+    u: RealArray,
+    y: RealArray,
+    fs: float,
+    excited_bins: NDArray[np.int_] | float,
+    contracts: Mapping[ContractType, SignalContract],
+) -> tuple[
+    TimeDomainSignal | None,
+    TimeDomainSignal,
+    TimeDomainSignal,
+    SamplingFrequencyHz,
+    ExcitedBins,
+]:
+    """Validate and resolve all arguments.
+
+    Ensures the signals conform to a supported contract and transforms them into the
+    canonical five-dimensional experiment layout, verifies the sampling frequency,
+    and resolves the excited bins. Warns when the data is insufficient to estimate the
+    noise or total covariance, and when adjacent output periods differ substantially
+    or excitation amplitudes change between realizations.
+
+    If ``excited_bins`` is an array, it is validated directly. If it is a float, it is
+    interpreted as a threshold for detecting the excited bins, using ``r`` if available
+    and ``u`` otherwise.
+    """
+    contract_type = validate_signal_contract(r, u, y, contracts)
+
+    nu = u.shape[1]
+    if contract_type is ContractType.REALIZATION:
+        r = to_experiment_layout(r, nu) if r is not None else None
+        u = to_experiment_layout(u, nu)
+        y = to_experiment_layout(y, nu)
+    else:
+        r = add_period_axis(r) if r is not None else None
+        u = add_period_axis(u)
+
+    r = cast("TimeDomainSignal", r) if r is not None else None
+    u = cast("TimeDomainSignal", u)
+    y = cast("TimeDomainSignal", y)
+
+    fs = validate_sampling_frequency(fs)
+    excited_bins = resolve_excited_bins(excited_bins, r if r is not None else u, fs)
+
+    n_experiments, n_periods = y.shape[-2:]
+
+    if n_experiments == 1:
+        _warn_total_covariance_unavailable()
+    if n_periods == 1:
+        _warn_noise_covariance_unavailable()
+
+    max_bin = excited_bins[-1]
+    if n_experiments > 1:
+        _warn_if_excitation_amplitude_mismatch(r if r is not None else u, max_bin)
+    if n_periods > 1:
+        _warn_if_output_spectra_mismatch(y, max_bin)
+
+    return r, u, y, fs, excited_bins
+
+
+def _warn_if_output_spectra_mismatch(y: RealArray, max_bin: int) -> None:
+    """Warn when the aggregate spectral mismatch between adjacent periods exceeds 2.5%.
+
+    Requires ``n_periods > 1``.
+
+    Only ``rfft`` bins from DC through ``max_bin`` are used. An appropriate choice of
+    ``max_bin`` reduces the influence of higher-frequency measurement noise and
+    emphasizes mismatches arising from drift and initial-condition effects.
+    """
+    n_periods = y.shape[-1]
+    if n_periods <= 1:
+        msg = f"y must have more than one period, got n_periods={n_periods}."
+        raise ValueError(msg)
+
+    y = standardize_channels(y)
+
+    stop_bin = max_bin + 1
+    spectrum = np.fft.rfft(y, axis=0)[:stop_bin]
+    later_spectrum = spectrum[..., 1:]
+    spectral_difference = later_spectrum - spectrum[..., :-1]
+
+    reduction_axis = tuple(range(y.ndim - 1))  # all axes except the last (period) axis
+    difference_rms = rms(spectral_difference, axis=reduction_axis)
+    reference_rms = rms(later_spectrum, axis=reduction_axis)
+
+    relative_difference = np.divide(
+        difference_rms,
+        reference_rms,
+        out=np.where(difference_rms == 0, 0.0, np.inf),
+        where=reference_rms != 0,
+    )
+
+    exceeds_threshold = relative_difference > MINIMUM_RELATIVE_PERIOD_MISMATCH
+    if np.any(exceeds_threshold):
+        values = ", ".join(f"{value:.2%}" for value in relative_difference)
+        affected_pairs = np.flatnonzero(exceeds_threshold)
+        n_period_pairs = n_periods - 1
+        n_affected_pairs = affected_pairs.size
+        if n_period_pairs == 1:
+            scope = "the"
+            period_pair_label = "period pair"
+            difference_label = "difference"
+        else:
+            scope = (
+                f"all {n_period_pairs}"
+                if n_affected_pairs == n_period_pairs
+                else f"{n_affected_pairs} of {n_period_pairs}"
+            )
+            period_pair_label = "period pairs"
+            difference_label = "differences"
+        msg = (
+            f"The relative spectral mismatch between {scope} adjacent {period_pair_label} "
+            f"exceeds the threshold of {MINIMUM_RELATIVE_PERIOD_MISMATCH:.2%}. This may "
+            f"indicate transients, drift, changing excitation, or period-alignment "
+            f"issues. Aggregated relative {difference_label}: "
+            f"[{values}]."
+        )
+        warnings.warn(msg, PossiblePeriodMismatchWarning, stacklevel=2)
+
+
+def _warn_if_excitation_amplitude_mismatch(
+    signal: RealArray,
+    max_bin: int,
+) -> None:
+    """Warn when excitation magnitude changes between adjacent realizations.
+
+    Requires ``n_experiments > 1``.
+
+    Only ``rfft`` bins from DC through ``max_bin`` are used. The input and experiment
+    axes are merged into realization layout using column-major ordering. Adjacent
+    realizations are compared separately for every physical input channel. Each
+    channel is standardized before comparison, so fixed amplitude differences between
+    channels do not trigger a warning.
+    """
+    n_experiments = signal.shape[-2]
+    if n_experiments <= 1:
+        msg = (
+            "signal must contain more than one experiment, "
+            f"got n_experiments={n_experiments}."
+        )
+        raise ValueError(msg)
+
+    signal = standardize_channels(signal)
+
+    stop_bin = max_bin + 1
+    spectrum = np.fft.rfft(signal, axis=0)[:stop_bin]
+    n_bins, n_channels, nu, _, n_periods = spectrum.shape
+    n_realizations = nu * n_experiments
+    realization_spectrum = spectrum.reshape(
+        n_bins,
+        n_channels,
+        n_realizations,
+        n_periods,
+        order="F",
+    )
+    realization_magnitude_spectrum = np.abs(realization_spectrum)
+
+    later_magnitude_spectrum = realization_magnitude_spectrum[..., 1:, :]
+    spectral_difference = later_magnitude_spectrum - realization_magnitude_spectrum[..., :-1, :]
+
+    reduction_axes = (0, 3)
+    difference_rms = rms(spectral_difference, axis=reduction_axes)
+    reference_rms = rms(later_magnitude_spectrum, axis=reduction_axes)
+    relative_difference = np.divide(
+        difference_rms,
+        reference_rms,
+        out=np.where(difference_rms == 0, 0.0, np.inf),
+        where=reference_rms != 0,
+    )
+
+    exceeds_threshold = relative_difference > MINIMUM_RELATIVE_REALIZATION_MISMATCH
+    if np.any(exceeds_threshold):
+        values = ", ".join(f"{value:.2%}" for value in relative_difference.ravel())
+        affected_pairs = np.flatnonzero(exceeds_threshold)
+        n_realization_pairs = n_realizations - 1
+        n_affected_pairs = affected_pairs.size
+        n_channel_realization_pairs = n_channels * n_realization_pairs
+        if n_channel_realization_pairs == 1:
+            scope = "the"
+            channel_realization_pair_label = "channel-realization pair"
+            difference_label = "difference"
+        else:
+            scope = (
+                f"all {n_channel_realization_pairs}"
+                if n_affected_pairs == n_channel_realization_pairs
+                else f"{n_affected_pairs} of {n_channel_realization_pairs}"
+            )
+            channel_realization_pair_label = "channel-realization pairs"
+            difference_label = "differences"
+        msg = (
+            f"The relative mismatch between {scope} adjacent {channel_realization_pair_label} "
+            f"exceeds the threshold of {MINIMUM_RELATIVE_REALIZATION_MISMATCH:.2%}. This "
+            "may indicate an excitation-amplitude change between realizations. Aggregated relative "
+            f"{difference_label}: [{values}]."
+        )
+        warnings.warn(msg, PossibleExcitationAmplitudeMismatchWarning, stacklevel=2)
+
+
+def _warn_noise_covariance_unavailable() -> None:
+    msg = "Only a single period is provided, so the noise covariance cannot be estimated."
+    warnings.warn(msg, NoiseCovarianceUnavailableWarning, stacklevel=2)
+
+
+def _warn_total_covariance_unavailable() -> None:
+    msg = (
+        "Only a single experiment is provided, so the total covariance "
+        "(noise plus nonlinear distortions) cannot be estimated."
+    )
+    warnings.warn(msg, TotalCovarianceUnavailableWarning, stacklevel=2)

best_linear_approximation/_array_shapes.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING, cast, overload
+
+import numpy as np
+
+from best_linear_approximation._exceptions import (
+    InsufficientExperimentsError,
+    RealizationsTruncatedWarning,
+)
+
+if TYPE_CHECKING:
+    from best_linear_approximation._typing import (
+        FrequencyDomainSignal,
+        RealArray,
+        TimeDomainSignal,
+    )
+
+CANONICAL_SIGNAL_NDIM = 5
+MINIMUM_SIGNAL_NDIM = 3
+EXPERIMENT_LAYOUT_WITHOUT_PERIOD_NDIM = 4
+
+
+def to_experiment_layout(
+    signal: RealArray,
+    nu: int,
+) -> TimeDomainSignal:
+    """Convert a signal from realization layout to five-dimensional experiment layout.
+
+    Splits the realization axis of a signal with shape
+    ``(n_samples, n_channels, n_realizations[, n_periods])`` into input and experiment
+    axes using column-major ordering. Adds a singleton period axis if none is present.
+    The resulting shape is ``(n_samples, n_channels, nu, n_experiments, n_periods)``.
+
+    Raises an ``InsufficientExperimentsError`` if ``n_realizations < nu``. Warns if
+    ``n_realizations`` is not divisible by ``nu`` and discards the remaining realizations.
+    """
+    n_realizations = signal.shape[2]
+    n_experiments = n_realizations // nu
+    if n_experiments == 0:
+        msg = (
+            f"The number of realizations ({n_realizations}) is less than the number of "
+            f"input channels ({nu}). No frequency response can be estimated."
+        )
+        raise InsufficientExperimentsError(msg)
+
+    n_effective_realizations = n_experiments * nu
+    if n_effective_realizations < n_realizations:
+        msg = (
+            f"The number of realizations ({n_realizations}) is not a multiple of "
+            f"the number of input channels ({nu}). Only the first "
+            f"{n_effective_realizations} realizations will be used for estimation."
+        )
+        warnings.warn(msg, RealizationsTruncatedWarning, stacklevel=2)
+
+    signal = signal[:, :, :n_effective_realizations, ...]
+    signal = signal.reshape(*signal.shape[:2], nu, n_experiments, *signal.shape[3:], order="F")
+
+    return cast(
+        "TimeDomainSignal",
+        signal
+        if signal.ndim == CANONICAL_SIGNAL_NDIM
+        else add_period_axis(signal),
+    )
+
+
+def add_period_axis(signal: RealArray) -> RealArray:
+    """Add a singleton period axis to a four-dimensional experiment signal.
+
+    Five-dimensional signals are returned unchanged.
+    """
+    return signal[..., None] if signal.ndim == EXPERIMENT_LAYOUT_WITHOUT_PERIOD_NDIM else signal
+
+
+@overload
+def as_batched_matrices(signal: TimeDomainSignal) -> TimeDomainSignal: ...
+
+
+@overload
+def as_batched_matrices(signal: FrequencyDomainSignal) -> FrequencyDomainSignal: ...
+
+
+def as_batched_matrices(
+    signal: TimeDomainSignal | FrequencyDomainSignal,
+) -> TimeDomainSignal | FrequencyDomainSignal:
+    """Arrange a signal as matrices for batched linear algebra.
+
+    Transforms an array with shape ``(n_leading, n_rows, n_cols, ...)`` into
+    one with shape ``(n_leading, ..., n_rows, n_cols)``.
+    """
+    if signal.ndim < MINIMUM_SIGNAL_NDIM:
+        msg = (
+            f"Expected a signal with at least {MINIMUM_SIGNAL_NDIM} dimensions, got {signal.ndim}."
+        )
+        raise ValueError(msg)
+
+    return np.moveaxis(signal, (1, 2), (-2, -1))

best_linear_approximation/_bla.py

@@ -0,0 +1,241 @@
+"""Result types for best linear approximation estimates."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Self
+
+import numpy as np
+
+from best_linear_approximation._covariance import project_onto_positive_semidefinite
+from best_linear_approximation._uncertainty import Uncertainty
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from best_linear_approximation._spectra import Spectra
+    from best_linear_approximation._typing import (
+        ComplexArray,
+        ExcitedBins,
+        RealArray,
+        SamplingFrequencyHz,
+        TimeDomainSignal,
+    )
+
+
+@dataclass(frozen=True)
+class FrequencyResponse:
+    """Frequency response estimate and its uncertainty estimates."""
+
+    value: ComplexArray
+    noise: Uncertainty
+    nonlinear: Uncertainty
+    total: Uncertainty
+
+
+class EstimationMethod(Enum):
+    """Method used to estimate a best linear approximation."""
+
+    ROBUST_DIRECT_KNOWN_INPUT = "robust_direct_known_input"
+    ROBUST_DIRECT_NOISY_INPUT = "robust_direct_noisy_input"
+    ROBUST_INDIRECT = "robust_indirect"
+
+
+@dataclass(frozen=True)
+class ExperimentInfo:
+    """Metadata describing the recordings used to estimate a BLA.
+
+    Attributes
+    ----------
+    estimation_method : EstimationMethod
+        Method used to estimate the BLA.
+    n_samples : int
+        Number of time-domain samples in each period.
+    nu : int
+        Number of input channels.
+    ny : int
+        Number of output channels.
+    n_experiments : int
+        Number of experiments.
+    n_periods : int
+        Number of output periods per experiment.
+    u_shape : tuple of int
+        Canonical time-domain shape of the input signal.
+    y_shape : tuple of int
+        Canonical time-domain shape of the output signal.
+    r_shape : tuple of int or None
+        Canonical time-domain shape of the reference signal, when available.
+
+    """
+
+    estimation_method: EstimationMethod
+    n_samples: int
+    nu: int
+    ny: int
+    n_experiments: int
+    n_periods: int
+    u_shape: tuple[int, ...]
+    y_shape: tuple[int, ...]
+    r_shape: tuple[int, ...] | None = None
+
+    @property
+    def n_realizations(self) -> int:
+        """Number of effective realizations after arranging data by input direction."""
+        return self.nu * self.n_experiments
+
+    @classmethod
+    def from_signals(
+        cls,
+        estimation_method: EstimationMethod,
+        u: TimeDomainSignal,
+        y: TimeDomainSignal,
+        r: TimeDomainSignal | None = None,
+    ) -> Self:
+        """Create recording metadata from canonical time-domain signals."""
+        n_samples, ny, nu, n_experiments, n_periods = y.shape
+        return cls(
+            estimation_method=estimation_method,
+            n_samples=n_samples,
+            nu=nu,
+            ny=ny,
+            n_experiments=n_experiments,
+            n_periods=n_periods,
+            u_shape=u.shape,
+            y_shape=y.shape,
+            r_shape=r.shape if r is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class FrequencyInfo:
+    """Metadata for the frequency content of a best linear approximation.
+
+    Attributes
+    ----------
+    fs : float
+        Sampling frequency in Hz.
+    f_res : float
+        Frequency resolution in Hz.
+    f_min : float
+        Lowest excited frequency in Hz.
+    f_max : float
+        Highest excited frequency in Hz.
+    freqs : RealArray
+        Non-negative DFT frequencies in Hz.
+    excited_bins : NDArray[np.int_]
+        Indices of the excited DFT frequencies.
+    non_excited_bins : NDArray[np.int_]
+        Indices of the non-excited DFT frequencies.
+
+    """
+
+    fs: float
+    f_res: float
+    f_min: float
+    f_max: float
+    freqs: RealArray
+    excited_bins: NDArray[np.int_]
+    non_excited_bins: NDArray[np.int_]
+
+
+@dataclass(frozen=True)
+class NonparametricBLA:
+    """Nonparametric best linear approximation estimate.
+
+    Attributes
+    ----------
+    G : FrequencyResponse
+        Frequency response estimate and its uncertainty estimates.
+    spectra : Spectra
+        Input, output, and optional reference spectra with their uncertainty estimates.
+    freq : FrequencyInfo
+        Frequency metadata for the estimate.
+    experiment : ExperimentInfo
+        Recording metadata and estimation method.
+
+    """
+
+    G: FrequencyResponse
+    spectra: Spectra
+    freq: FrequencyInfo
+    experiment: ExperimentInfo
+
+
+def create_frequency_info(
+    n_samples: int,
+    fs: SamplingFrequencyHz,
+    excited_bins: ExcitedBins,
+) -> FrequencyInfo:
+    """Create frequency metadata from validated sampling and excitation data."""
+    n_bins = n_samples // 2 + 1
+    f_res = fs / n_samples
+    freqs = np.arange(n_bins) * f_res
+    non_excited_bins = np.setdiff1d(np.arange(n_bins), excited_bins)
+    f_min = float(freqs[excited_bins[0]])
+    f_max = float(freqs[excited_bins[-1]])
+    return FrequencyInfo(
+        fs=fs,
+        f_res=f_res,
+        f_min=f_min,
+        f_max=f_max,
+        freqs=freqs,
+        excited_bins=excited_bins,
+        non_excited_bins=non_excited_bins,
+    )
+
+
+def create_bla_frequency_response(
+    G_bla: ComplexArray,
+    G_total_cov: ComplexArray | None,
+    G_noise_cov: ComplexArray | None,
+    n_samples: int,
+    excited_bins: ExcitedBins,
+) -> FrequencyResponse:
+    """Create a frequency response estimate from its value and covariances."""
+    nonlinear_cov = None
+    if G_total_cov is not None and G_noise_cov is not None:
+        nonlinear_cov = project_onto_positive_semidefinite(G_total_cov - G_noise_cov)
+
+    marginal_var_shape = G_bla.shape[1:]
+    noise = _create_frequency_domain_uncertainty(
+        G_noise_cov,
+        marginal_var_shape,
+        G_bla,
+        n_samples,
+        excited_bins,
+    )
+    nonlinear = _create_frequency_domain_uncertainty(
+        nonlinear_cov,
+        marginal_var_shape,
+        G_bla,
+        n_samples,
+        excited_bins,
+    )
+    total = _create_frequency_domain_uncertainty(
+        G_total_cov,
+        marginal_var_shape,
+        G_bla,
+        n_samples,
+        excited_bins,
+    )
+    return FrequencyResponse(G_bla, noise, nonlinear, total)
+
+
+def _create_frequency_domain_uncertainty(
+    covariance: ComplexArray | None,
+    marginal_var_shape: tuple[int, ...],
+    spectrum: ComplexArray,
+    n_samples: int,
+    frequency_bins: ExcitedBins,
+) -> Uncertainty:
+    if covariance is None:
+        return Uncertainty.unavailable()
+
+    return Uncertainty.from_cov(
+        covariance,
+        marginal_var_shape,
+        spectrum=spectrum,
+        n_samples=n_samples,
+        frequency_bins=frequency_bins,
+    )

best_linear_approximation/_config.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+# Tuned to pass all tests in "tests/test_spectral_validation.py", which use
+# flat excitation spectra. This value may be too high for non-flat spectra.
+DEFAULT_RELATIVE_THRESHOLD_EXCITED_BINS = 0.5  # keep in sync with docstrings