symop.modes.envelopes.base¶

Base envelope abstraction.

This module defines the abstract base class for mode envelopes. An envelope represents a complex time-domain field and provides:

Time-domain evaluation.
Frequency-domain evaluation.
Overlap computation.
Heuristic center/scale estimation.
Plotting utilities.

Concrete envelope types must implement time and/or frequency evaluation consistently with the package Fourier convention.

Classes

BaseEnvelope()

Abstract base class for time/frequency envelopes.

class BaseEnvelope → None¶

Bases: ABC

Abstract base class for time/frequency envelopes.

Subclasses must implement: - time_eval: evaluate the complex field on a time grid - freq_eval: evaluate the complex spectrum on a frequency grid - delayed: return a time-shifted copy - phased: return a phase-shifted copy - signature: stable identifier used for caching / comparisons - approx_signature: rounded or approximate identifier for grouping

This base class provides: - a generic overlap implementation based on numeric quadrature - plotting utilities (requires matplotlib)

Presentation: Objects may optionally implement symop.modes.protocols.HasLatex to provide a LaTeX (mathtext) string for display in plots. If unavailable, plotting uses a readable textual fallback.

_abc_impl = <_abc._abc_data object>¶

abstractmethod approx_signature(*, decimals: int = 12, ignore_global_phase: bool = False) → tuple[object, ...]¶

Return an approximate signature.

Implementations typically round floating parameters to a specified number of decimals and/or ignore non-essential parameters (e.g., global phase), depending on keyword arguments.

Parameters:

decimals (int)
ignore_global_phase (bool)

Return type:

tuple[object, …]

center_and_scale() → tuple[float, float]¶

Heuristic center and scale for choosing a plotting / overlap window.

Returns:

center – Center time.
scale – Characteristic scale

Return type:

tuple[float, float]

abstractmethod delayed(dt: float) → Self¶

Return a copy delayed by dt in time.

Parameters:: dt (float)
Return type:: Self

formalism: ClassVar[Literal['generic', 'gaussian_closed']] = 'generic'¶

abstractmethod freq_eval(w: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]] | ndarray[tuple[Any, ...], dtype[float64]]¶

Evaluate the envelope in the frequency domain on a grid of frequencies w.

Parameters:: w (ndarray[tuple[Any, ...], dtype[float64]])
Return type:: ndarray[tuple[Any, …], dtype[complex128]] | ndarray[tuple[Any, …], dtype[float64]]

norm2() → float¶

Return the squared norm <zeta, zeta> (real, non-negative up to numerical noise).

Return type:: float

overlap(other: TimeFrequencyEnvelope) → complex¶

Compute the overlap (inner product) with another envelope.

If either envelope implements SupportsOverlapWithGeneric, that hook is used. Otherwise, a numeric quadrature is performed over a window selected from center_and_scale().

Parameters:: other (TimeFrequencyEnvelope) – The envelope to overlap with.
Returns:: The overlap value.
Return type:: complex

abstractmethod phased(dphi: float) → Self¶

Return a copy with an added global phase dphi.

Parameters:: dphi (float)
Return type:: Self

abstract property signature: tuple[object, ...]¶: Return a stable signature for this envelope.

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

Evaluate the envelope in the time domain on a grid of times t.

Parameters:: t (ndarray[tuple[Any, ...], dtype[float64]])
Return type:: ndarray[tuple[Any, …], dtype[complex128]] | ndarray[tuple[Any, …], dtype[float64]]

_overlap_numeric(f1: Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[complex128]] | ndarray[tuple[Any, ...], dtype[float64]]], f2: Callable[[ndarray[tuple[Any, ...], dtype[float64]]], ndarray[tuple[Any, ...], dtype[complex128]] | ndarray[tuple[Any, ...], dtype[float64]]], *, tmin: float, tmax: float, n: int = 65536) → complex¶

Numerically approximate the overlap (inner product) between two time functions.

This approximates the integral

\[\langle f_1, f_2 \rangle \;=\; \int_{t_\mathrm{min}}^{t_\mathrm{max}} f_1(t)^*\,f_2(t)\,dt\]

on a uniform grid using the trapezoidal rule.

Parameters:

f1 (Callable[[ndarray[tuple[Any, ...], dtype[double]]], ndarray[tuple[Any, ...], dtype[cdouble]] | ndarray[tuple[Any, ...], dtype[double]]]) – Callables mapping a real-valued time grid to real-or-complex samples.
f2 (Callable[[ndarray[tuple[Any, ...], dtype[double]]], ndarray[tuple[Any, ...], dtype[cdouble]] | ndarray[tuple[Any, ...], dtype[double]]]) – Callables mapping a real-valued time grid to real-or-complex samples.
tmin (float) – Integration limits.
tmax (float) – Integration limits.
n (int) – Number of grid points used in the uniform grid (default: 2**16).

Returns:

Approximation to the overlap integral.

Return type:

complex

Raises:

ValueError – If either function returns non-finite values on the grid.