symop.modes.transfer.apply

Transfer application utilities for mode envelopes.

This module provides helper routines for applying spectral transfer functions to mode envelopes.

The main entry point is apply_transfer(), which applies a TransferFunction to a BaseEnvelope and returns the resulting envelope together with the transmission efficiency.

Two execution paths are supported:

  1. Closed Gaussian formalism

    If both the envelope and the transfer function support the Gaussian closed-form formalism, the transformation is performed analytically. This avoids numerical sampling and preserves the analytic Gaussian representation.

  2. Numerical spectral filtering

    For general envelopes or transfer functions, the operation is implemented via FilteredEnvelope, which evaluates the spectral product

    \[\zeta_{\mathrm{out}}(\omega) = H(\omega)\,\zeta_{\mathrm{in}}(\omega)\]

    using FFT-based reconstruction.

In both cases the returned efficiency

\[\eta = \langle \zeta_{\mathrm{out}} \mid \zeta_{\mathrm{out}} \rangle\]

represents the transmitted power of the mode after filtering.

Functions

apply_transfer(transfer, env, *[, n_fft, ...])

Apply a spectral transfer function to a mode envelope.
apply_transfer(transfer: TransferFunction, env: TimeFrequencyEnvelope, *, n_fft: int = 32768, w_span_sigma: float = 12.0) → tuple[TimeFrequencyEnvelope, float]

Apply a spectral transfer function to a mode envelope.

This function multiplies the envelope spectrum with a transfer function

\[\zeta_{\mathrm{out}}(\omega) = H(\omega)\,\zeta_{\mathrm{in}}(\omega),\]

and returns the resulting envelope together with the transmitted power.

Two evaluation strategies are used depending on the available representations:

  • Closed Gaussian path

    If the envelope is a GaussianClosedEnvelope and the transfer function implements SupportsGaussianClosedTransfer, the operation is performed analytically.

  • Numerical filtering path

    Otherwise the operation is performed using FilteredEnvelope, which evaluates the spectral product on a discrete frequency grid.

Parameters:

  • transfer (TransferFunction) – Spectral transfer function \(H(\omega)\).

  • env (TimeFrequencyEnvelope) – Input mode envelope.

  • n_fft (int) – Number of FFT points used for numerical filtering. Ignored if the analytic Gaussian path is used.

  • w_span_sigma (float) – Frequency span of the numerical grid expressed in multiples of the envelope bandwidth.

Returns:

Pair (env_out, eta) where

  • env_out is the filtered envelope

  • eta is the transmission efficiency

\[\eta = \langle \zeta_{\mathrm{out}} \mid \zeta_{\mathrm{out}} \rangle.\]

Return type:

tuple[TimeFrequencyEnvelope, float]

Notes

The returned envelope always implements the TimeFrequencyEnvelope interface so it can be evaluated in both time and frequency domains.