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 in monotonic grid.W order 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 in monotonic sol.W order. When spectra were not saved, reconstructs them from the time-domain fields.

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.