symop.modes.transfer.gaussian.formalism

Closed-form Gaussian transfer expansions for gaussian_closed envelopes.

This module provides a small algebra for staying inside the "gaussian_closed" envelope formalism when applying certain frequency-domain transfer functions.

Core idea

Let \(\zeta(t)\) be a normalized mode descriptor and \(Z(\omega)\) its spectrum under the package convention

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

so that the mode inner product can be evaluated in the frequency domain as

\[\langle \zeta_1, \zeta_2 \rangle = \frac{1}{2\pi}\int_{-\infty}^{\infty} \overline{Z_1(\omega)}\,Z_2(\omega)\,d\omega.\]

Filtering a mode by an amplitude transfer \(H(\omega)\) produces an unnormalized spectrum

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

Because envelopes are treated as mode descriptors, we keep the envelope normalized and return the power transmission separately:

\[\eta = \langle \zeta_{\mathrm{raw}}, \zeta_{\mathrm{raw}} \rangle = \frac{1}{2\pi}\int |H(\omega)|^2\,|Z_{\mathrm{in}}(\omega)|^2\,d\omega, \qquad \zeta_{\mathrm{out}} = \frac{\zeta_{\mathrm{raw}}}{\sqrt{\eta}}.\]

The quantum state is then damped by a loss channel with transmissivity \(\eta\), while the envelope remains normalized.

Supported closed-form family

This module targets transfers representable as a constant plus a finite sum of Gaussian low-pass “atoms”:

\[H(\omega) = c_0 + \sum_{k=1}^{K} c_k \exp\left[-\frac{1}{2}\left(\frac{\omega-\omega_k}{\sigma_k}\right)^2\right].\]

Applying such a transfer to a single GaussianEnvelope produces a GaussianMixtureEnvelope in closed form (a finite linear combination of normalized Gaussian components).

Pruning

Expansions can create mixtures with many components (especially when applying to an already-mixture input). We optionally prune components whose raw contribution is negligible using a conservative proxy:

\[p_i \approx |w_i|^2,\]

since each component is individually normalized. Pruning is applied to the returned envelope representation only. The returned \(\eta\) is computed from the full unpruned raw mixture by default.

Functions

prune_mixture_terms(comps, weights, *[, ...])

Prune mixture terms by a conservative diagonal power proxy.

Classes

GaussianAtom(coeff, w0, sigma_w)

One Gaussian low-pass atom term in an expansion.

GaussianTransferExpansion(c0, atoms)

Transfer function as a constant plus a sum of Gaussian low-pass atoms.
class GaussianAtom(coeff: complex, w0: float, sigma_w: float) → None

Bases: object

One Gaussian low-pass atom term in an expansion.

The atom is

\[T(\omega) = c\, \exp\left[-\frac{1}{2}\left(\frac{\omega-w_0}{\sigma_\omega}\right)^2\right].\]
Parameters:
coeff

Complex coefficient \(c\).

w0

Atom center frequency \(w_0\).

sigma_w

Atom width \(\sigma_\omega\).

coeff: complex
sigma_w: float
w0: float
class GaussianTransferExpansion(c0: complex, atoms: tuple[GaussianAtom, ...]) → None

Bases: object

Transfer function as a constant plus a sum of Gaussian low-pass atoms.

We represent a transfer function as

\[H(\omega) = c_0 + \sum_{k=1}^{K} c_k \exp\left[-\frac{1}{2}\left(\frac{\omega-\omega_k}{\sigma_k}\right)^2\right].\]

Applying \(H\) to a Gaussian envelope spectrum remains within a finite span of Gaussian spectra, so the output envelope can be represented as a GaussianMixtureEnvelope.

The returned scalar \(\eta\) is the squared norm of the raw output mode before renormalization, suitable for applying loss to the quantum state.

Parameters:
c0

Constant term \(c_0\).

atoms

Gaussian atom terms \((c_k,\omega_k,\sigma_k)\).

Pruning controls
---------------
This class supports optional pruning when building output mixtures
- `rel_weight2_min` and `abs_weight2_min` define pruning thresholds.
- `max_terms` caps the mixture size.
- `keep_at_least` enforces a minimum number of terms.
Pruning affects only the **returned envelope representation** by default.
The transmissivity :math:`\eta` is computed from the full unpruned raw mixture
unless you set `eta_from_pruned=True` in the apply methods.
apply_to_gaussian(env: GaussianClosedEnvelope, *, rel_weight2_min: float = 1e-12, abs_weight2_min: float = 0.0, max_terms: int | None = 128, keep_at_least: int = 1, eta_from_pruned: bool = False) → tuple[GaussianClosedEnvelope, float]

Apply this expansion to a gaussian_closed envelope.

Parameters:

  • env (GaussianClosedEnvelope) – Input envelope in the gaussian_closed family (single Gaussian or mixture).

  • rel_weight2_min (float) – Pruning controls.

  • abs_weight2_min (float) – Pruning controls.

  • max_terms (int | None) – Pruning controls.

  • keep_at_least (int) – Pruning controls.

  • eta_from_pruned (bool) – If True, compute \(\eta\) using the pruned mixture only.

Returns:

Output gaussian_closed envelope (typically a mixture) and transmissivity.

Return type:

(env_out, eta)

apply_to_gaussian_env(env: GaussianEnvelope, *, rel_weight2_min: float = 1e-12, abs_weight2_min: float = 0.0, max_terms: int | None = 128, keep_at_least: int = 1, eta_from_pruned: bool = False) → tuple[GaussianMixtureEnvelope, float]

Apply this expansion to a single GaussianEnvelope (closed form).

Parameters:
Returns:

  • env_out: normalized Gaussian mixture envelope representing the filtered mode.

  • eta: transmissivity (raw mode squared norm).

Return type:

(env_out, eta)

Notes

The raw (unnormalized) output is

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

We then return a normalized envelope representing

\[Z_{\mathrm{out}}(\omega) = \frac{1}{\sqrt{\eta}} Z_{\mathrm{raw}}(\omega),\]

and the scalar

\[\eta = \langle \zeta_{\mathrm{raw}}, \zeta_{\mathrm{raw}} \rangle.\]
atoms: tuple[GaussianAtom, ...]
c0: complex
_apply_expansion_to_mixture(env: GaussianMixtureEnvelope, exp: GaussianTransferExpansion, *, rel_weight2_min: float = 1e-12, abs_weight2_min: float = 0.0, max_terms: int | None = 128, keep_at_least: int = 1, eta_from_pruned: bool = False) → tuple[GaussianMixtureEnvelope, float]

Apply an expansion \(H(\omega)\) to a Gaussian mixture input.

If the input mode is

\[\zeta_{\mathrm{in}}(t) = \sum_i c_i g_i(t),\]

then the raw output is

\[\zeta_{\mathrm{raw}}(t) = \sum_i c_i \,(H g_i)(t),\]

and each \(H g_i\) is represented in closed form as a (small) Gaussian mixture. The final output is therefore a Gaussian mixture whose number of components scales with the input mixture size and the number of atoms.

Parameters:

  • env (GaussianMixtureEnvelope) – Input Gaussian mixture envelope (normalized).

  • exp (GaussianTransferExpansion) – Transfer expansion to apply.

  • rel_weight2_min (float) – Pruning controls.

  • abs_weight2_min (float) – Pruning controls.

  • max_terms (int | None) – Pruning controls.

  • keep_at_least (int) – Pruning controls.

  • eta_from_pruned (bool) – If True, compute \(\eta\) using the pruned mixture only.

Returns:

Output Gaussian mixture envelope and transmissivity \(\eta\).

Return type:

(env_out, eta)

_canonicalize_closed_env(env: GaussianClosedEnvelope) → GaussianClosedEnvelope

Canonicalize a gaussian_closed envelope representation.

This helper simplifies the returned representation after closed-form transfer application.

If the input is a GaussianMixtureEnvelope with exactly one component, the mixture is collapsed back to a single GaussianEnvelope by absorbing the unit-modulus mixture weight into the component global phase \(\phi_0\).

Parameters:

env (GaussianClosedEnvelope) – Envelope in the gaussian_closed family.

Returns:

Canonicalized envelope representation.

  • If env is not a single-term mixture, it is returned unchanged.

  • If env is a one-term mixture, a single GaussianEnvelope is returned.

Return type:

SupportsGaussianClosedOverlap

Notes

Let a normalized one-term mixture be

\[\zeta(t) = w\,g(t),\]

where \(|w| = 1\) after normalization. Since this factor is a pure global phase, it can be absorbed into the Gaussian phase parameter:

\[w = e^{i\Delta\phi}, \qquad g(t) \mapsto g'(t) \text{ with } \phi_0' = \phi_0 + \Delta\phi.\]

This preserves the represented mode while yielding a simpler canonical form.

_clip_eta(x: float) → float

Clip a scalar to \([0,1]\) with non-finite mapped to 0.

Parameters:

x (float) – Candidate transmissivity.

Returns:

Value clipped to \([0, 1]\).

Return type:

float

Notes

In exact arithmetic, the transmissivity

\[\eta = \frac{1}{2\pi}\int |H(\omega)|^2 |Z(\omega)|^2 d\omega\]

should lie in \([0,1]\) for passive amplitude transfers with \(|H|\le 1\). In floating-point arithmetic and for “semantic” filters (e.g. complements), tiny violations can occur; clipping keeps the higher-level semantics stable.

_gauss_atom_times_gauss_env(env: GaussianEnvelope, *, w0: float, sigma_w: float) → tuple[GaussianEnvelope, float]

Apply a Gaussian low-pass atom to a single Gaussian envelope (closed form).

The atom transfer is

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

For the GaussianEnvelope spectral shape used in this package

\[Z(\omega)\propto \exp\left[-\sigma_t^2(\omega-\omega_0)^2\right]e^{-i\omega\tau}e^{i\phi_0},\]

the product \(H(\omega)Z(\omega)\) remains Gaussian in \(\omega\). Therefore there exists a normalized output Gaussian envelope \(g_{\mathrm{out}}\) and a scalar \(\eta\in[0,1]\) such that

\[H(\omega)Z(\omega) = \sqrt{\eta}\,Z_{\mathrm{out}}(\omega),\]

where \(Z_{\mathrm{out}}\) is the spectrum of \(g_{\mathrm{out}}\) and \(\langle g_{\mathrm{out}}, g_{\mathrm{out}}\rangle=1\).

Parameters:

  • env (GaussianEnvelope) – Input normalized Gaussian envelope.

  • w0 (float) – Atom center frequency.

  • sigma_w (float) – Atom width parameter.

Returns:

  • env_out: normalized output Gaussian envelope shape.

  • eta: power transmissivity (squared norm of the raw filtered mode).

Return type:

(env_out, eta)

Notes

  • The returned \(\eta\) matches the definition

    \[\eta = \frac{1}{2\pi}\int |H(\omega)|^2 |Z(\omega)|^2 d\omega.\]

  • This function assumes the transfer is real amplitude (no phase). If you later support dispersive Gaussian transfers (quadratic phase), you will want a chirped-Gaussian envelope class.

prune_mixture_terms(comps: list[GaussianEnvelope], weights: list[complex], *, rel_weight2_min: float = 1e-12, abs_weight2_min: float = 0.0, max_terms: int | None = 128, keep_at_least: int = 1) → tuple[tuple[GaussianEnvelope, ...], ndarray]

Prune mixture terms by a conservative diagonal power proxy.

Given a raw mixture

\[\zeta_{\mathrm{raw}}(t) = \sum_{i=1}^{N} w_i\,g_i(t),\]

with normalized components \(\langle g_i, g_i\rangle = 1\), the diagonal contribution to \(\|\zeta_{\mathrm{raw}}\|^2\) is approximately

\[p_i \approx |w_i|^2.\]

This function discards terms whose \(p_i\) is far below the maximum.

Parameters:

  • comps (list[GaussianEnvelope]) – List of Gaussian components \(g_i\).

  • weights (list[complex]) – List of complex weights \(w_i\) (raw, unnormalized).

  • rel_weight2_min (float) – Relative threshold on \(|w_i|^2\) compared to \(\max_j |w_j|^2\).

  • abs_weight2_min (float) – Absolute threshold on \(|w_i|^2\).

  • max_terms (int | None) – If not None, cap the number of kept terms by keeping the largest \(|w_i|^2\) terms after thresholding.

  • keep_at_least (int) – Ensure at least this many terms remain (keeps the largest terms if needed).

Returns:

Pruned components (tuple) and corresponding weights (1D complex array).

Return type:

(components, weights)

Notes

  • This is a heuristic: it ignores cross terms \(\overline{w_i}w_j\langle g_i, g_j\rangle\). Use conservative thresholds.

  • Pruning should be viewed as a representation-compression step. For safety, compute \(\eta\) from the full unpruned raw mixture first, then prune the returned envelope representation.