symop.modes.transfer

Transfer functions and transfer-function algebra.

This package provides frequency-domain transfer functions and combinators used to transform mode envelopes.

Overview

A transfer function \(H(\omega)\) acts multiplicatively in the frequency domain:

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

The package supports two execution regimes:

  • Gaussian-closed (analytic) transfers Transfers that admit a closed-form action on Gaussian envelopes. These preserve an analytic representation and avoid numerical FFT evaluation.

  • General transfers Arbitrary transfer functions evaluated numerically via spectral sampling (FFT-based filtering).

Transfer algebra

Transfer functions can be combined to build more complex responses:

  • Cascade

    Sequential composition (product) of multiple transfer functions

    \[H(\omega) = H_n(\omega)\cdots H_2(\omega) H_1(\omega)\]

Available transfers

Gaussian-closed transfers (analytic):

General transfers (numerical fallback):

Notes

  • All transfers operate on mode descriptors (envelopes), not directly on quantum states.

  • Power loss (transmissivity \(\eta\)) is handled separately from the envelope representation.

  • When no analytic path is available, transfers are evaluated via FilteredEnvelope.

class Cascade(parts: tuple[TransferFunction, ...]) → None

Bases: TransferBase

Pointwise product of transfer functions.

A cascade represents sequential application of transfer functions in the frequency domain:

\[H(\omega) = H_n(\omega)\,\cdots\,H_2(\omega)\,H_1(\omega).\]
Parameters:

parts (tuple[TransferFunction, ...])

parts

Ordered transfer functions applied from right to left in the product expression.

_abc_impl = <_abc._abc_data object>
_signature_tag: ClassVar[str] = 'cascade'
approx_signature(*, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]

Return an approximate signature of the cascade.

Parameters:

  • decimals (int) – Number of decimal places used for rounding component signatures.

  • ignore_global_phase (bool) – Whether component signatures may suppress physically irrelevant global phase factors.

Returns:

Approximate signature containing ordered approximate component signatures.

Return type:

Signature

parts: tuple[TransferFunction, ...]
property signature: tuple[object, ...]

Return the exact stable signature of the cascade.

Returns:

Signature containing the ordered exact signatures of all component transfers.

Return type:

Signature

class ConstantPhase(phi0: float) → None

Bases: GaussianClosedTransferBase

Frequency-independent global phase transfer.

The transfer is

\[H(\omega) = e^{i\phi_0}.\]

Since the phase factor is independent of \(\omega\), this transfer does not modify the spectral intensity profile and therefore does not introduce attenuation. Its transmissivity is always

\[\eta = 1.\]
Parameters:

phi0 (float) – Global phase shift \(\phi_0\) in radians.

_abc_impl = <_abc._abc_data object>
_as_expansion() → GaussianTransferExpansion

Convert the transfer into a Gaussian expansion.

Returns:

Expansion consisting only of a constant term,

\[H(\omega) = c_0, \qquad c_0 = e^{i\phi_0}.\]

Return type:

GaussianTransferExpansion

Notes

Although apply_to_gaussian() is implemented directly for efficiency and clarity, providing this expansion keeps the class compatible with Gaussian-closed analytic machinery that may rely on _as_expansion().

_is_protocol = False
_signature_params(*, ignore_global_phase: bool = False) → tuple[float]

Return the parameter tuple used in signatures.

Parameters:

ignore_global_phase (bool) – If True, normalize the global phase to zero for approximate grouping and comparison.

Returns:

Signature parameter tuple.

Return type:

tuple[float]

_signature_tag: ClassVar[str] = 'const_phase'
apply_to_gaussian(env: GaussianClosedEnvelope) → tuple[GaussianClosedEnvelope, float]

Apply the transfer analytically to a Gaussian-closed envelope.

Parameters:

env (GaussianClosedEnvelope) – Input envelope in the Gaussian-closed family.

Returns:

Pair (env_out, eta) where env_out is the transformed Gaussian-closed envelope and eta = 1.0.

Return type:

tuple[GaussianClosedEnvelope, float]

Notes

For a single Gaussian envelope, the phase is absorbed into the Gaussian phase parameter \(\phi_0\).

For a Gaussian mixture, the mixture weights are multiplied by the common phase factor \(e^{i\phi_0}\). The represented mode is unchanged up to a global phase, and no loss is introduced.

phi0: float
class GaussianBandpass(w0: float, sigma_w: float) → None

Bases: GaussianClosedTransferBase

Gaussian band-pass amplitude transfer.

\[H(\omega) = \exp\left[ -\frac{1}{2} \left( \frac{\omega-\omega_0}{\sigma_\omega} \right)^2 \right].\]
Parameters:

  • w0 (float) – Center angular frequency \(\omega_0\).

  • sigma_w (float) – Bandwidth parameter \(\sigma_\omega\).

_abc_impl = <_abc._abc_data object>
_as_expansion() → GaussianTransferExpansion

Convert this transfer into a Gaussian expansion.

Returns:

Expansion consisting of a single Gaussian atom:

\[H(\omega) = \exp\left[ -\frac{1}{2} \left( \frac{\omega-\omega_0}{\sigma_\omega} \right)^2 \right].\]

Return type:

GaussianTransferExpansion

Notes

This representation enables closed-form propagation of Gaussian envelopes and Gaussian mixtures.

_is_protocol = False
_signature_tag: ClassVar[str] = 'gauss_bandpass'
sigma_w: float
w0: float
class GaussianHighpass(w0: float, sigma_w: float) → None

Bases: GaussianClosedTransferBase

Soft Gaussian high-pass amplitude transfer.

The transfer is defined by

\[H(\omega) = 1 - \exp\left[ -\frac{1}{2} \left( \frac{\omega-\omega_0}{\sigma_\omega} \right)^2 \right].\]
Parameters:

  • w0 (float) – Center angular frequency \(\omega_0\).

  • sigma_w (float) – Width parameter \(\sigma_\omega\) of the complementary Gaussian low-pass.

_abc_impl = <_abc._abc_data object>
_as_expansion() → GaussianTransferExpansion

Convert this transfer into a Gaussian expansion.

Returns:

Expansion of the form

\[H(\omega) = c_0 + c_1 \exp\left[ -\frac{1}{2} \left( \frac{\omega-\omega_0}{\sigma_\omega} \right)^2 \right],\]

with

\[c_0 = 1, \qquad c_1 = -1.\]

Return type:

GaussianTransferExpansion

Notes

This representation allows the transfer to be applied in closed form to Gaussian-closed envelopes.

_is_protocol = False
_signature_tag: ClassVar[str] = 'gauss_highpass'
sigma_w: float
w0: float
class GaussianLowpass(w0: float, sigma_w: float) → None

Bases: GaussianClosedTransferBase

Gaussian low-pass amplitude transfer.

\[H(\omega) = \exp\left[ -\frac{1}{2} \left( \frac{\omega-\omega_0}{\sigma_\omega} \right)^2 \right].\]
Parameters:

  • w0 (float) – Center angular frequency \(\omega_0\).

  • sigma_w (float) – Bandwidth parameter \(\sigma_\omega\).

_abc_impl = <_abc._abc_data object>
_as_expansion() → GaussianTransferExpansion

Convert this transfer into a Gaussian expansion.

Returns:

Expansion consisting of a single Gaussian atom:

\[H(\omega) = \exp\left[ -\frac{1}{2} \left( \frac{\omega-\omega_0}{\sigma_\omega} \right)^2 \right].\]

Return type:

GaussianTransferExpansion

Notes

This representation enables closed-form propagation of Gaussian envelopes and Gaussian mixtures.

_is_protocol = False
_signature_tag: ClassVar[str] = 'gauss_lowpass'
sigma_w: float
w0: float
class QuadraticDispersion(beta2: float, w_ref: float = 0.0) → None

Bases: TransferBase

Pure quadratic spectral phase around \(\omega_\mathrm{ref}\).

The transfer is

\[H(\omega) = \exp\left( -i\frac{\beta_2}{2}(\omega-\omega_\mathrm{ref})^2 \right).\]
Parameters:

  • beta2 (float) – Quadratic dispersion coefficient \(\beta_2\).

  • w_ref (float) – Reference angular frequency \(\omega_\mathrm{ref}\).

_abc_impl = <_abc._abc_data object>
_signature_tag: ClassVar[str] = 'quad_dispersion'
beta2: float
w_ref: float = 0.0
class RectBandpass(w0: float, width: float) → None

Bases: TransferBase

Ideal rectangular band-pass amplitude transfer.

Parameters:

  • w0 (float) – Center angular frequency \(\omega_0\).

  • width (float) – Full passband width \(\Delta\omega\).

_abc_impl = <_abc._abc_data object>
_signature_tag: ClassVar[str] = 'rect_bandpass'
w0: float
width: float
class SuperGaussianBandpass(w0: float, sigma_w: float, order: int = 2) → None

Bases: TransferBase

Super-Gaussian band-pass amplitude transfer.

Parameters:

  • w0 (float) – Center angular frequency \(\omega_0\).

  • sigma_w (float) – Width parameter \(\sigma_\omega\).

  • order (int) – Super-Gaussian order \(m \ge 1\).

_abc_impl = <_abc._abc_data object>
_signature_tag: ClassVar[str] = 'supergauss_bandpass'
order: int = 2
sigma_w: float
w0: float
class TimeDelay(tau: float) → None

Bases: GaussianClosedTransferBase

Time delay in the frequency domain.

\[H(\omega) = e^{-i\omega\tau}.\]
Parameters:

tau (float)

_abc_impl = <_abc._abc_data object>
_as_expansion() → GaussianTransferExpansion

Raise because time delay is not a finite Gaussian expansion.

Returns:

Never returned.

Return type:

GaussianTransferExpansion

Raises:

NotImplementedError – Always raised because time delay is not representable as a finite Gaussian expansion in the current formalism.

_is_protocol = False
_signature_tag: ClassVar[str] = 'time_delay'
apply_to_gaussian(env: GaussianClosedEnvelope) → tuple[GaussianClosedEnvelope, float]

Apply the time delay analytically to a Gaussian-closed envelope.

Parameters:

env (GaussianClosedEnvelope) – Input envelope in the Gaussian-closed family.

Returns:

Pair (env_out, eta) where env_out is the delayed envelope and eta = 1.0.

Return type:

tuple[GaussianClosedEnvelope, float]

Notes

A time delay shifts the Gaussian time parameter without changing the envelope norm.

tau: float

Modules

apply

Transfer application utilities for mode envelopes.

base

Base classes for spectral transfer functions.

cascade

Cascade transfer function.

gaussian

Gaussian-closed transfer functions.

quadratic_dispersion

Quadratic dispersion transfer function.

rect_bandpass

Rectangular band-pass transfer function.

supergaussian_bandpass

Super-Gaussian band-pass transfer function.