Pulses

Pulse{T<:Complex}

Optical pulse envelope in time and frequency domains.

Fields

• At::Vector{T}: Time domain envelope A(t) [√W]
• AW::Vector{T}: Frequency domain envelope A(ω) [√W·s]
• grid::Grid: Associated time-frequency grid

Notes

Following gnlse-python convention:

• AW = N * ifft(At) (note: inverted FFT convention)
• At = fft(AW)
• Power: P(t) = |A(t)|²
• Energy: E = ∫|A(t)|²dt

VectorialPulse(At, grid)
VectorialPulse(At_x, At_y, grid)

Two-component (orthogonal polarization) optical pulse envelope in time and frequency domains.

Fields

• At::Matrix{ComplexF64}: Time domain envelope matrix of size N × 2 [√W]
• AW::Matrix{ComplexF64}: Frequency domain envelope matrix of size N × 2 [√W·s]
• grid::Grid: Associated time-frequency grid

sech_pulse(grid::Grid, Pmax::Real, FWHM::Real)

Generate hyperbolic secant pulse in natural SI units.

Arguments

• grid::Grid: Time-frequency grid
• Pmax::Real: Peak power [W]
• FWHM::Real: Pulse duration Full-Width Half-Maximum [s]

Returns

• Pulse: Pulse structure with At and AW

Physics

Following gnlse-python SechEnvelope:

m = 2 * log(1 + sqrt(2))
A(T) = sqrt(Pmax) * 2 / (exp(m*T/FWHM) + exp(-m*T/FWHM))
     = sqrt(Pmax) * sech(m*T/FWHM)

Where m = 2*arcsinh(1) ≈ 1.763 is the factor relating FWHM to 1/e half-width.

gaussian_pulse(grid::Grid, Pmax::Real, FWHM::Real)

Generate Gaussian pulse following gnlse-python GaussianEnvelope.

Arguments

• grid::Grid: Time-frequency grid
• Pmax::Real: Peak power [W]
• FWHM::Real: Pulse duration Full-Width Half-Maximum [s]

Returns

• Pulse: Pulse structure with At and AW

Physics

Following gnlse-python GaussianEnvelope, where m = 4*log(2) relates the 1/e² half-width to the FWHM:

A(T) = sqrt(Pmax) * exp(-m * 0.5 * T² / FWHM²)

This defines a pulse whose intensity drops to half-maximum at ±FWHM/2.

lorentzian_pulse(grid::Grid, Pmax::Real, FWHM::Real)

Generate Lorentzian pulse following gnlse-python LorentzianEnvelope.

Arguments

• grid::Grid: Time-frequency grid
• Pmax::Real: Peak power [W]
• FWHM::Real: Pulse duration Full-Width Half-Maximum [s]

Returns

• Pulse: Pulse structure with At and AW

Physics

Following gnlse-python LorentzianEnvelope:

m = 2 * sqrt(sqrt(2) - 1)
A(T) = sqrt(Pmax) / (1 + (m*T/FWHM)^2)

cw_pulse(grid::Grid, Pmax::Real; Pn::Real=0.0, rng=Random.default_rng())

Generate a continuous-wave (CW) field with optional broadband temporal noise.

Arguments

• grid::Grid: Time-frequency grid
• Pmax::Real: CW power [W]
• Pn::Real: Power of the additive temporal noise floor [W] (default: 0.0)
• rng: random source for the noise realization

Returns

• Pulse: Pulse structure with At and AW

Physics

A constant-amplitude field √Pmax with, if Pn > 0, an additive seed of amplitude √Pn and an independent uniformly random phase in every time bin:

A(t) = √Pmax + √Pn · exp(i·2π·U(t)),   U(t) ~ Uniform[0, 1)

For a physically grounded quantum (one-photon-per-mode) or RIN seed on top of a clean field, use add_noise instead.

add_noise(pulse::Pulse; kwargs...) -> Pulse

Return a copy of pulse with a physically motivated realization of input noise added. Four independent contributions can be enabled and tuned separately:

1. Quantum noise — vacuum fluctuations of the optical field, modelled as photons_per_mode photons per spectral mode. This is the fundamental seed for noise-driven dynamics (modulation instability, supercontinuum decoherence) and is the only term enabled by default.
2. Relative intensity noise (RIN) — classical shot-to-shot fluctuation of the laser output power, applied as a multiplicative amplitude scaling.
3. Phase noise (shot-to-shot) — common-mode optical phase jitter drawn from a single Gaussian deviate (white phase noise).
4. Laser linewidth — frequency-domain colored phase noise with a Lorentzian power spectrum corresponding to a laser of linewidth linewidth_hz. Modeled as a Wiener (random-walk) phase process: the phase evolves as Brownian motion in time, giving a Lorentzian electric-field spectrum with FWHM = linewidth_hz.

Independent rng draws give statistically independent realizations, so calling add_noise repeatedly on the same clean pulse builds the ensemble needed for a spectral_coherence study.

Keyword arguments

• rng::AbstractRNG = default_rng(): random source.
• photons_per_mode::Real = 1.0: quantum-noise level. 1.0 is the standard one-photon-per-mode seed (Dudley & Coen); 0.5 corresponds to the vacuum zero-point energy ħω/2; 0.0 disables quantum noise.
• quantum_model::Symbol = :gaussian: :gaussian draws each field quadrature from an independent normal distribution (Rayleigh-distributed amplitude, uniform phase) — the physically faithful model of a vacuum/coherent state. :phase_only uses a fixed per-mode amplitude with a uniformly random phase, i.e. the classic Dudley & Coen seed.
• rin::Real = 0.0: RMS relative intensity noise σP/P (fractional, e.g. 0.01 = 1 % RMS power fluctuation). Convert a dBc/Hz spec with [`rinrms`](@ref).
• phase_rms::Real = 0.0: RMS common-mode optical phase jitter [rad] (shot-to-shot; white phase noise).
• linewidth_hz::Real = 0.0: Laser linewidth [Hz] (half-maximum of the Lorentzian power spectrum). Generates a time-domain Wiener phase process with diffusion coefficient D = 2π · linewidth_hz. Typical values: < 1 kHz (narrow-linewidth CW), 1–100 MHz (standard DFB), > 10 GHz (free-running).

Physics

In the package FFT convention the energy of spectral mode m is N·dt·|AW[m]|², so a mode carrying nₚ photons of energy ħω satisfies N·dt·⟨|δAW|²⟩ = nₚ·ħω. RIN scales the field by √(1 + δ) with δ ~ 𝒩(0, rin²); the shot-to-shot phase noise multiplies it by exp(iφ) with φ ~ 𝒩(0, phase_rms²).

The Wiener phase process satisfies φ(t+dt) = φ(t) + 𝒩(0, 2π·Δν·dt), giving a Lorentzian electric-field autocorrelation ⟨E*(0)E(τ)⟩ ∝ exp(−π|Δν||τ|) and power spectrum FWHM = Δν (Schawlow–Townes white-frequency-noise limit).

Reference: J. M. Dudley & S. Coen, Opt. Lett. 27, 1180 (2002); J. M. Dudley, G. Genty & S. Coen, Rev. Mod. Phys. 78, 1135 (2006); A. L. Schawlow & C. H. Townes, Phys. Rev. 112, 1940 (1958).

rin_rms(psd_dbc_hz, bandwidth) -> Float64

RMS relative intensity fluctuation σP/P obtained by integrating a (flat) relative-intensity-noise power spectral density `psddbc_hz[dBc/Hz] over a one-sided detectionbandwidth` [Hz]:

σ² = ∫₀^B S(f) df = 10^(RIN/10) · B

Use the result as the rin argument of add_noise. Example: a laser with −150 dBc/Hz RIN observed over a 1 GHz bandwidth gives rin_rms(-150, 1e9) ≈ 3.2e-4 (0.03 % RMS power fluctuation).