symop.modes.envelopes.gaussian

Closed-form Gaussian time-domain envelopes.

This module defines GaussianEnvelope, a canonical Gaussian mode envelope with analytic (closed-form) expressions in both the time and frequency domains.

The time-domain field is a Gaussian-modulated carrier with parameters (omega0, sigma, tau, phi0). Under the Fourier convention used in this package, its spectrum is also Gaussian and can be evaluated in closed form. This allows overlaps and transformations to be computed without numerical FFT-based reconstruction.

The implementation is intended to provide a consistent reference envelope for analytic calculations and as a well-behaved building block for filtering and mode construction.

Classes

GaussianEnvelope(omega0, sigma, tau[, phi0])

Canonical Gaussian time-domain envelope.
class GaussianEnvelope(omega0: float, sigma: float, tau: float, phi0: float = 0.0) → None

Bases: BaseEnvelope

Canonical Gaussian time-domain envelope.

Parameters:

  • omega0 (float) – Carrier (angular) frequency \(\omega_0\).

  • sigma (float) – Temporal width \(\sigma_t\) (standard deviation in time).

  • tau (float) – Time shift (center) \(\tau\).

  • phi0 (float) – Global phase \(\phi_0\).

Definition

We define the complex field (not a rotating-frame envelope) as

\[\zeta(t) = \left(\frac{1}{2\pi\sigma_t^{2}}\right)^{1/4} \exp\!\left[-\frac{(t-\tau)^2}{4\sigma_t^{2}}\right] \exp\!\bigl(i(\omega_0(t-\tau)+\phi_0)\bigr).\]

Frequency domain

With the Fourier convention used in this package:

\[Z(\omega) = \int_{-\infty}^{\infty} \zeta(t)\,e^{+i\omega t}\,dt,\]

so that

\[\zeta(t)=\frac{1}{2\pi}\int_{-\infty}^{\infty} Z(\omega)\,e^{-i\omega t}\,d\omega.\]

Under this convention, the spectrum is also Gaussian:

\[Z(\omega) = \mathcal{A}\, \exp\!\left[-\sigma_t^2(\omega-\omega_0)^2\right]\, \exp\!\bigl(-i\omega\tau + i\phi_0\bigr),\]

where \(\mathcal{A}\) is a real constant (depends on normalization and Fourier convention). For overlaps and CCR-consistent mode construction, the absolute constant does not matter as long as it is used consistently.

Notes

This implementation chooses a consistent normalization constant for freq_eval, but the exact overall scale is not intended to be relied on unless you have explicitly standardized a Fourier convention across the codebase.

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

Approximate signature with rounded floating parameters.

Parameters:

  • decimals (int) – Number of decimals to round to.

  • ignore_global_phase (bool) – If True, treat \(\phi_0\) as zero for grouping.

Returns:

Rounded/approximate signature tuple.

Return type:

Signature

center_and_scale() → tuple[float, float]

Return plotting/overlap heuristics.

Returns:

  • center – Center time (\(\tau\)).

  • scale – Characteristic scale (\(\sigma_t\)).

Return type:

tuple[float, float]

delayed(dt: float) → GaussianEnvelope

Return a copy delayed by dt.

Parameters:

dt (float) – Time shift to add to \(\tau\).

Returns:

Delayed envelope.

Return type:

GaussianEnvelope

formalism: ClassVar[Literal['generic', 'gaussian_closed']] = 'gaussian_closed'
freq_eval(w: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]] | ndarray[tuple[Any, ...], dtype[float64]]

Evaluate the frequency-domain spectrum \(Z(\omega)\).

This returns a Gaussian spectrum consistent with the time-domain definition used in time_eval(), up to an overall real scale factor.

Parameters:

w (ndarray[tuple[Any, ...], dtype[double]]) – Frequency grid (angular frequency \(\omega\)).

Returns:

Complex samples of the spectrum.

Return type:

RCArray

omega0: float
property omega_sigma: float

Heuristic spectral width hint (rad/s).

For the envelope definition used here, a reasonable scaling for the intensity spectral standard deviation is approximately \(1/\sigma_t\).

overlap_gaussian_closed(other: SupportsGaussianClosedOverlap) → complex

Closed-form overlap with another closed-form Gaussian envelope.

This computes the inner product

\[\langle \zeta_1, \zeta_2 \rangle = \int_{-\infty}^{\infty} \overline{\zeta_1(t)}\,\zeta_2(t)\,dt,\]

specialized to the normalized Gaussian family defined by time_eval().

Let \(\sigma_1,\tau_1,\omega_1,\phi_1\) be the parameters of self and \(\sigma_2,\tau_2,\omega_2,\phi_2\) those of other. Define

\[\begin{split}S &= \sigma_1^2 + \sigma_2^2, \\ \Delta\tau &= \tau_2 - \tau_1, \\ \Delta\omega &= \omega_2 - \omega_1, \\ \omega_w &= \frac{\omega_1\sigma_1^2 + \omega_2\sigma_2^2}{S}.\end{split}\]

Then the overlap is

\[\langle \zeta_1, \zeta_2 \rangle = \sqrt{\frac{2\sigma_1\sigma_2}{S}} \exp\!\left(-\frac{\Delta\tau^2}{4S}\right) \exp\!\left(-\frac{\sigma_1^2\sigma_2^2}{S}\,\Delta\omega^2\right) \exp\!\left(i(\phi_2-\phi_1-\omega_w\Delta\tau)\right).\]

Notes

  • This formula assumes both envelopes are normalized such that

\(\langle \zeta, \zeta \rangle = 1\). The normalization used in time_eval() satisfies this. - The result is consistent with conjugate symmetry: \(\langle \zeta_1,\zeta_2\rangle = \overline{\langle \zeta_2,\zeta_1\rangle}\).

Parameters:

other (SupportsGaussianClosedOverlap) – Another envelope in the same closed-form Gaussian family.

Returns:

The overlap \(\langle \zeta_1, \zeta_2 \rangle\).

Return type:

complex

Raises:
phased(dphi: float) → GaussianEnvelope

Return a copy with an added global phase.

Parameters:

dphi (float) – Phase increment to add to \(\phi_0\).

Returns:

Phased envelope.

Return type:

GaussianEnvelope

phi0: float = 0.0
sigma: float
property signature: tuple[object, ...]

Stable signature for caching/comparison.

tau: float
time_eval(t: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]] | ndarray[tuple[Any, ...], dtype[float64]]

Evaluate the time-domain complex field \(\zeta(t)\).

Parameters:

t (ndarray[tuple[Any, ...], dtype[double]]) – Time grid.

Returns:

Complex samples of the field.

Return type:

RCArray

_env_check: EnvelopeProtocol
_gaussian_closed_check: GaussianClosedEnvelope
_spectral_hints_check: HasSpectralHints
_tf_env_check: TimeFrequencyEnvelope