Soliton analysis¶
Soliton order, fission lengths, dispersive-wave prediction, trajectories and RSFS rates. Docstrings are the source of truth, rendered with mkdocstrings (numpydoc style).
photonics_helper.soliton ¶
Soliton dynamics analysis module.
Provides diagnostics for soliton propagation simulations: - Soliton order N - Dispersion/nonlinear/fission lengths - Dispersive wave wavelength - Soliton trajectory extraction - Soliton counting - Raman self-frequency shift rate
SolitonAnalyzer ¶
SolitonAnalyzer(pulse: Wave, fiber: FiberProfile, betas: NDArray, z_array: NDArray, spectra_vs_z: tuple)
Extract soliton dynamics metrics from GNLSE simulation results.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pulse
|
Wave
|
Input pulse (provides T0, peak power). |
required |
fiber
|
FiberProfile
|
Fiber/waveguide parameters (provides gamma via _gamma). |
required |
betas
|
array_like
|
Dispersion coefficients [beta2, beta3, ...] in ps^2/m. |
required |
z_array
|
array_like
|
Propagation distances (m) for each saved evolution step. |
required |
spectra_vs_z
|
tuple
|
(omega_array, spectra_matrix) from solver.spectra_vs_z. |
required |
Notes
The dispersive_wave_wavelength(dispersion=None) method accepts an
optional dispersion source for the full β(ω) root finder. When a
dispersion source is provided, it uses dispersive_wave_roots from
the phase_matching module. When dispersion=None (default), it falls
back to the β₂/β₃ analytic formula (Δω = −2β₂/β₃). This is backward
compatible with existing code that relied on the implicit
pulse._dispersion attribute.
gamma
instance-attribute
¶
gamma = _gamma(fiber.n2, pulse.central_frequency, fiber.A_eff, fiber.confinement_factor)
soliton_order ¶
soliton_order() -> float
Compute soliton order N = sqrt(gamma * P_peak * T0^2 / |beta2|).
Returns:
| Type | Description |
|---|---|
float
|
Soliton order (dimensionless). |
dispersion_length ¶
dispersion_length() -> Length
nonlinear_length ¶
nonlinear_length() -> Length
Compute nonlinear length L_NL = 1 / (gamma * P_peak).
Returns:
| Type | Description |
|---|---|
Length
|
Nonlinear length. |
fission_length ¶
fission_length(eta: float = 0.7) -> Length
Compute fission length L_fiss = L_D / (N * eta).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
eta
|
float
|
Raman correction factor (default 0.7). |
0.7
|
Returns:
| Type | Description |
|---|---|
Length
|
Fission length. |
dispersive_wave_wavelength ¶
dispersive_wave_wavelength(dispersion=None, wl_range: tuple[Wavelength, Wavelength] | None = None, n_brackets: int = 100) -> Wavelength
Compute dispersive wave (Cherenkov) wavelength from phase-matching.
Accepts an optional dispersion source for the full β(ω) root finder.
When no dispersion source is supplied, falls back to the β₂/β₃ formula
(Δω = −2β₂/β₃) for the common case.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dispersion
|
Dispersion or PropagationConstant or ZDependentDispersion
|
Dispersion source for full β(ω) root finding. When None, uses the β₂/β₃ analytic fallback. |
None
|
wl_range
|
tuple[Wavelength, Wavelength]
|
Search range as Wavelength objects. Defaults to 0.5× to 3× the pump wavelength. |
None
|
n_brackets
|
int
|
Number of bracket intervals for the root finder. Default 100. |
100
|
Returns:
| Type | Description |
|---|---|
Wavelength
|
DW wavelength. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no valid root is found and β₂/β₃ data unavailable. |
count_solitons ¶
count_solitons(spectrum: NDArray | None = None) -> int
Count solitons in output spectrum using peak detection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spectrum
|
NDArray
|
Spectrum to analyze. If None, uses last propagation step. |
None
|
Returns:
| Type | Description |
|---|---|
int
|
Number of soliton peaks detected. |
soliton_trajectories ¶
soliton_trajectories() -> list[tuple[float, float]]
Extract soliton trajectories (peak wavelength vs propagation distance).
Returns:
| Type | Description |
|---|---|
list of (z, lambda_peak_nm) tuples for each identified soliton peak.
|
|
raman_shift_rate ¶
raman_shift_rate() -> float
Compute Raman self-frequency shift rate (nm/mm).
Fits a line to the soliton trajectory in the linear (pre-fission) regime and returns the slope.
Returns:
| Type | Description |
|---|---|
float
|
RSFS rate in nm/mm. |
plot_soliton_trajectories ¶
plot_soliton_trajectories(solver: GNLSESolver, ax=None) -> plt.Figure
Plot individual soliton peak wavelengths vs propagation distance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solver
|
GNLSESolver
|
Solver with propagated results. |
required |
ax
|
matplotlib Axes
|
Axis to plot on. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
matplotlib Figure
|
|
plot_fission_dynamics ¶
plot_fission_dynamics(solver: GNLSESolver, N: float, L_D: Length, ax=None) -> plt.Figure
Plot soliton fission process: spectrum evolution with fission length marker.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solver
|
GNLSESolver
|
Solver with propagated results. |
required |
N
|
float
|
Soliton order. |
required |
L_D
|
Length
|
Dispersion length. |
required |
ax
|
matplotlib Axes
|
Axis to plot on. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
matplotlib Figure
|
|
plot_raman_shift ¶
plot_raman_shift(solver: GNLSESolver, ax=None) -> plt.Figure
Plot soliton peak wavelength drift due to Raman self-frequency shift.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solver
|
GNLSESolver
|
Solver with propagated results. |
required |
ax
|
matplotlib Axes
|
Axis to plot on. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
matplotlib Figure
|
|
plot_dispersion_wave ¶
plot_dispersion_wave(solver: GNLSESolver, ax=None) -> plt.Figure
Plot final spectrum with dispersive wave wavelength marked.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solver
|
GNLSESolver
|
Solver with propagated results. |
required |
ax
|
matplotlib Axes
|
Axis to plot on. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
fig |
matplotlib Figure
|
|