Skip to content

Fiber dispersion and propagation constants

Dispersion/PropagationConstant objects, spline dispersion fitting, waveguide support. Docstrings are the source of truth, rendered with mkdocstrings (numpydoc style).

photonics_helper.fiber

Fiber dispersion and propagation constant calculations.

Dispersion

Wavelength-dependent dispersion D(λ) with spline interpolation.

Values are stored internally in s/m² and can be queried in ps/(nm·km).

Attributes:

Name Type Description
wavelengths wavelength array.
values dispersion values in s/m².
central_wavelength design central wavelength.

values instance-attribute 

values: NDArray

unit instance-attribute 

unit: Literal['ps/nm.km', 's/m^2']

wavelengths instance-attribute 

wavelengths: WavelengthArray

central_wavelength instance-attribute 

central_wavelength: Wavelength

as_ps_nm_km cached property 

as_ps_nm_km: NDArray

Dispersion values in ps/(nm·km).

as_s_m_m cached property 

as_s_m_m: NDArray

Dispersion values in s/m² (internal units).

get_wls 

get_wls() -> WavelengthArray

Return the wavelength array.

fn 

fn(wavelength: Wavelength) -> float

Interpolated dispersion at wavelength (m)

from_neff classmethod 

from_neff(neff: NDArray, wavelengths: WavelengthArray, central_wavelength: Wavelength, ignore_fit_error: bool = False) -> Self

Compute dispersion D(λ) from effective index neff(λ).

D = -λ/c × d²neff/dλ²

from_propagation_constant classmethod 

from_propagation_constant(beta: NDArray, wavelengths: WavelengthArray, central_wavelength: Wavelength, ignore_fit_error: bool = False) -> Self

Compute dispersion D(λ) from propagation constant β(ω).

D = -(2πc)/λ² × d²β/dω²

get_beta2 

get_beta2(wavelength_nm: float)

Return β₂ at wavelength_nm (s²/m) via spline interpolation.

get_beta2_at 

get_beta2_at(wavelength: Wavelength) -> float

Return β₂ (s²/m) at a :class:Wavelength (unit-safe wrapper).

This is the preferred entry point for callers that work with unit objects; it forwards the wavelength in nm to :meth:get_beta2 so the unit convention cannot be mixed up.

get_betas 

get_betas(polyOrder, wavelength: Wavelength | None = None, make_plot=False, return_diagnostics=False)

Fit dispersion data to a polynomial in ω and return beta coefficients.

Returns betas in array [beta2, beta3, ...] in ps^k/m (with Ω in rad/ps) — the native form expected by :class:~photonics_helper.gnlse.GNLSESolver. If you instead have SI coefficients (s^k/m), pass them with GNLSESolver(..., betas_unit="s^k/m") and they will be converted. If return_diagnostics is True, returns (betas, fit_x_axis, data, fit).

PropagationConstant

Propagation constant β as a function of wavelength or angular frequency.

Attributes:

Name Type Description
values β values.
x_values wavelength or angular frequency array.

values instance-attribute 

values: NDArray

x_values instance-attribute 

x_values: WavelengthArray | AngularFrequencyArray

beta 

beta(omega: NDArray | float) -> float | NDArray

Callable β(ω) via spline interpolation of the stored values.

Scalar input returns a Python float; array input returns an NDArray of the same shape. Raises ValueError when omega lies outside the stored n_eff(λ)/ω table window.

Bridges DispersionModel-style usage (beta_fn in :mod:photonics_helper.phase_matching and the χ⁽²⁾ solvers) without the :class:~photonics_helper.phase_matching.PropagationConstantAdaptor indirection.

beta2 

beta2(wavelength: Wavelength) -> float

Return the group-velocity dispersion d²β/dω² (s²/m).

Differentiates a cubic spline through the tabulated β(ω). Requires at least four points (cubic-spline minimum).

beta_from_neff classmethod 

beta_from_neff(neff: NDArray, x_values: WavelengthArray | AngularFrequencyArray) -> Self

Compute β = neff × ω / c and return a PropagationConstant.

from_neff_omega classmethod 

from_neff_omega(neff: NDArray, omega: AngularFrequencyArray) -> Self

Construct from effective index neff and angular frequency array.

WaveguideMode

Imported waveguide mode: effective index n_eff(λ) from an FEM solver.

Tabulated effective indices are converted into the library's dispersion objects. This is the documented bridge from an external eigenmode solver (Lumerical MODE, COMSOL Wave Optics, …) into :class:PropagationConstant / :class:Dispersion.

File conventions

CSV — comma separated, optional header, two or three columns::

wavelength_um, neff
1.50, 2.4310
1.55, 2.4205
...

or wavelength_um, neff, ng with the optional group index ng. A header line is detected automatically (any non-numeric first row).

NPZ — np.savez archive with keys:

  • wavelength_um (required) — 1-D vacuum wavelengths in micrometres.
  • neff (required) — 1-D effective indices, same length.
  • ng (optional) — group index.
  • central_wavelength_nm or central_wavelength_um (optional) — design wavelength; defaults to the mid-point of the grid.

Validation mirrors :class:~photonics_helper.materials.RefractiveIndex: a finite, positive, strictly increasing wavelength grid with at least four points (cubic-spline requirement).

Attributes:

Name Type Description
neff 1-D effective index array.
wavelengths :class:`WavelengthArray` of the tabulated grid.
central_wavelength design wavelength.
ng optional 1-D group-index array.

neff instance-attribute 

neff: NDArray

wavelengths instance-attribute 

wavelengths: WavelengthArray

central_wavelength class-attribute instance-attribute 

central_wavelength: Wavelength | None = None

ng class-attribute instance-attribute 

ng: NDArray | None = None

neff_at 

neff_at(wavelength: Wavelength) -> float

Interpolated n_eff at wavelength within the tabulated range.

to_propagation_constant 

to_propagation_constant() -> PropagationConstant

Build a :class:PropagationConstant with β = n_eff·ω/c.

to_dispersion 

to_dispersion(ignore_fit_error: bool = True) -> Dispersion

Build a :class:Dispersion D(λ) from n_eff(λ).

ignore_fit_error defaults to True because FEM exports are often coarse and the smoothness guard in :meth:Dispersion.from_neff can otherwise reject a perfectly usable table.

from_csv classmethod 

from_csv(path: str | Path, *, central_wavelength: Wavelength | None = None, delimiter: str = ',', skiprows: int = 0) -> WaveguideMode

Load wavelength_um, neff[, ng] from a CSV/text file.

from_npz classmethod 

from_npz(path: str | Path, *, central_wavelength: Wavelength | None = None) -> WaveguideMode

Load an n_eff(λ) table from an np.savez archive.

Required keys: wavelength_um (µm) and neff. Optional: ng, central_wavelength_nm/central_wavelength_um.

ZDependentDispersion

Z-dependent dispersion profile β(ω, z) for tapered/dispersion-managed waveguides.

Holds a 2-D table of propagation constants β[ω_idx, z_idx] with axis arrays, plus a fn(omega, z) interpolant built via RegularGridInterpolator.

Attributes:

Name Type Description
omegas 1-D array of angular frequencies (rad/s).
z_positions 1-D array of propagation positions (m).
beta 2-D array of shape (n_omega, n_z) with β values.
central_wavelength design central wavelength (m).
Notes

The interpolant uses linear interpolation with bounds_error=False and fill_value=None so out-of-range queries return NaN (caller decides what to do).

omegas instance-attribute 

omegas: NDArray

z_positions instance-attribute 

z_positions: NDArray

beta instance-attribute 

beta: NDArray

central_wavelength instance-attribute 

central_wavelength: float

betas_taylor class-attribute instance-attribute 

betas_taylor: NDArray | None = None

beta_orders class-attribute instance-attribute 

beta_orders: NDArray | None = None

omega0_fit class-attribute instance-attribute 

omega0_fit: float | None = None

n_omega property 

n_omega: int

Effective index n(Ω) at each angular-frequency sample.

n_z property 

n_z: int

Longitudinal coordinate array (sample positions per step).

fn 

fn(omega: float | NDArray, z: float) -> float | NDArray

Interpolate β(ω, z) via the 2-D table.

Parameters:

Name Type Description Default
omega float or 1-D array — absolute angular frequency(ies) in rad/s.
required
z float — propagation position in m.
required

Returns:

Type Description
β interpolated at (omega, z). Scalar if omega is scalar, array otherwise.
Out-of-range values return NaN (not an error).

get_betas_at_z 

get_betas_at_z(z: float, order: int = 7, omega0: float | None = None, halfwidth: float | None = None) -> NDArray

Fit Taylor coefficients β₂…β_order near omega0 at position z.

Returns [β₂, β₃, …, β_order] in SI units (s^k/m). ω is in rad/s.

get_betas_vs_z 

get_betas_vs_z(order: int = 7, omega0: float | None = None, halfwidth: float | None = None) -> NDArray

Taylor coefficients β₂…β_order at every z position.

Returns array of shape (n_z, order - 1) in SI units (s^k/m).

from_arrays classmethod 

from_arrays(omegas: NDArray, z_positions: NDArray, beta: NDArray, central_wavelength: float) -> ZDependentDispersion

Construct from raw arrays.

Parameters:

Name Type Description Default
omegas 1-D array — angular frequencies (rad/s).
required
z_positions 1-D array — propagation positions (m).
required
beta 2-D array — shape (n_omega, n_z).
required
central_wavelength float — design central wavelength (m).
required

from_npz classmethod 

from_npz(path: str, central_wavelength: float | None = None) -> ZDependentDispersion

Load β(ω, z) from an NPZ file.

Expected keys: - "omegas": 1-D array of angular frequencies (rad/s). - "z_positions": 1-D array of propagation positions (m). - "beta": 2-D array of shape (n_omega, n_z). - "central_wavelength" (optional): if present, used; otherwise central_wavelength arg required.

Parameters:

Name Type Description Default
path str — path to the .npz file.
required
central_wavelength float — required if not stored in the NPZ file.
None