Analysis Functions

pulse_energy(pulse::Pulse)

Pulse energy E = ∫|A(t)|²dt [J].

peak_power(pulse::Pulse)

Peak power P_peak = max(|A(t)|²) [W].

fwhm(pulse::Pulse; domain::Symbol=:time)

Full width at half maximum of the pulse.

domain = :time returns the temporal width [s]; domain = :frequency returns the spectral width as an angular-frequency width [rad/s].

spectral_bandwidth(pulse::Pulse; level::Float64=0.5)

Spectral width at the given intensity level (0.5 = FWHM), returned as ordinary frequency ν [Hz] (i.e. divided by 2π; not angular frequency ω [rad/s]).

time_bandwidth_product(pulse::Pulse)

Time-bandwidth product Δt·Δν (dimensionless). Transform-limited references: ≈ 0.441 (Gaussian), ≈ 0.315 (sech²).

spectral_centroid(pulse::Pulse)

Intensity-weighted center frequency of the pulse spectrum relative to the carrier: ⟨ω - ω₀⟩ [rad/s]. Returns zero for a spectrum centered at the carrier; positive/negative for red/blue shifts. Useful for tracking spectral drift during nonlinear propagation.

photon_number(pulse::Pulse)
photon_number(solution::Solution)

Conserved quantity ∝ ∫|A(ω)|²/ω dω used to monitor numerical accuracy of the GNLSE integration. For a lossless fiber this quantity is conserved by the GNLSE (including self-steepening); a drift indicates the step-size tolerance is too loose. Note: the returned value is not an absolute photon count — it lacks the ℏ and dω normalization factors and should only be compared relative to itself along the propagation axis. For a Solution, returns one value per saved distance.

dispersion_length(beta2, T0)

Dispersion length LD = T₀² / |β₂| [m], the distance over which a pulse of characteristic width T₀ disperses significantly due to chromatic dispersion. Compares to nonlinear length to determine whether dispersion or nonlinearity dominates the pulse evolution. See [`solitonnumber`](@ref).

nonlinear_length(gamma, P0)

Nonlinear length LNL = 1 / (γ P₀) [m], the distance over which a pulse of peak power P₀ undergoes significant nonlinear phase modulation. Compares to dispersion length to determine the dominant physics. See [`solitonnumber`](@ref).

soliton_number(beta2, gamma, T0, P0)

Soliton number N = √(LD / LNL) = √(γ P₀ T₀² / |β₂|) (dimensionless). This parameter predicts the number of fundamental solitons that comprise the initial pulse and governs nonlinear-dispersive dynamics:

• N ≪ 1: weakly nonlinear, dispersion dominates
• N ≈ 1: fundamental soliton (stable in anomalous dispersion)
• N > 1: higher-order soliton exhibiting periodic breathing; also indicates soliton-fission regime where multiple solitons emerge

The higher-order soliton period is approximately Tfission ≈ π L_D / 2 ≈ π T₀² / (2|β₂|).

spectral_coherence(spectra) -> Vector{Float64}

Modulus of the complex degree of first-order coherence |g₁₂⁽¹⁾(ω)| at zero path delay, evaluated bin-by-bin across an ensemble of independent spectra:

g(ω) = |⟨Aᵢ*(ω) Aⱼ(ω)⟩_{i≠j}| / ⟨|A(ω)|²⟩

spectra may be a vector of complex frequency-domain fields (all equal length), a vector of Pulses, or a vector of Solutions (the spectrum at the final distance is used). Returns g ∈ [0, 1]: 1 = fully coherent (the supercontinuum is reproducible shot-to-shot), 0 = incoherent (noise-dominated).

The estimator uses the algebraic identity Σ_{i≠j} Aᵢ*Aⱼ = |ΣAᵢ|² - Σ|Aᵢ|², which averages over all M(M-1) ordered pairs without an explicit double loop.

Reference: J. M. Dudley & S. Coen, Opt. Lett. 27, 1180 (2002).

spectral_coherence(pulses::AbstractVector{<:Pulse})

Convenience overload: accepts a vector of Pulse objects and extracts their frequency-domain envelopes (AW fields) before computing coherence.

spectral_coherence(solutions::AbstractVector{<:Solution})

Convenience overload: accepts a vector of Solution objects and extracts the final spectrum (AW field at the last propagation distance) from each, then computes coherence across the ensemble.

spectrogram(pulse::Pulse; n_delay=200, gate_fwhm=nothing) -> (t_delays, V_grid, S_matrix)

Compute Short-Time Fourier Transform (STFT) spectrogram of pulse: S(t, ω) = |∫ A(t') exp(-(t' - t)² / (2 τ_g²)) exp(-i ω t') dt'|²

shg_frog_trace(pulse::Pulse; n_delay=200) -> (delays, V_shg, I_frog)

Compute Second-Harmonic Generation (SHG) FROG trace: I_FROG(ω, τ) = |∫ A(t) A(t - τ) exp(-i ω t) dt|²

track_solitons(sol::Solution) -> (z_fiss, peak_power_z, centroid_w_z)

Automated tracking of soliton fission and Soliton Self-Frequency Shift (SSFS) red-shift trajectory across propagation distances sol.Z.

Returns

• z_fiss: Estimated distance of peak compression / soliton fission [m]
• peak_power_z: Peak power P_max(z) [W] along propagation
• centroid_w_z: Spectral centroid ⟨ω - ω₀⟩(z) [rad/s] along propagation

dispersive_wave_wavelength(medium::Medium, pulse::Pulse; P0::Real=peak_power(pulse)) -> Float64

Calculate the predicted resonant Cherenkov dispersive wave emission wavelength λ_DW [m] emitted during soliton fission in medium.

Solves the phase-matching condition: Δβ(Δω) = β(ω₀ + Δω) - β(ω₀) - β₁(ω₀)·Δω - ½·γ·P₀ = 0 for Δω ≠ 0.