anafibre.fields

Module Functions

Defines the GuidedMode class, which represents a single eigenmode \((\ell, m, \lambda)\) of a step-index fiber. Now includes a lightweight grid cache to avoid recomputing radial functions and phases when sampling E/H on the same spatial grid repeatedly (e.g., for plotting, power integration, animations along z, etc.).

Cache design (small & safe): - Keyed by coordinate system ("xy" or "cyl") and a compact fingerprint of the grid (shape, extents, mean step, z if scalar/broadcastable). This avoids storing gigantic array hashes and keeps comparisons fast. - Stored items: flattened rho/phi/z, shape, precomputed radial functions \(R_0\), \(R_+\), \(R_-\), and the longitudinal/azimuthal phase \(\exp(i(k_z z + \ell \phi))\). - Invalidation: automatic whenever A/B, \(k_z\), \(\ell\), wavelength, fibre, or \(V/b\) change, i.e., on new GuidedMode instance. You can also call clear_grid_cache().

Notes: - The cache is per-mode (per GuidedMode instance). It never grows beyond a handful of grids you touch in a session. Use clear_grid_cache() if you need to free memory. - If you pass a different grid (different shape or spacing), the cache just recomputes and stores it.

ModeNotFoundError

Bases: RuntimeError

Raised when the requested guided mode does not exist.

spin_to_cartesian

Convert spin-basis field components to Cartesian components.

Parameters:

Name	Type	Description	Default
F0	array - like	Longitudinal and circular transverse spin components.	required
Fp	array - like	Longitudinal and circular transverse spin components.	required
Fm	array - like	Longitudinal and circular transverse spin components.	required

Returns:

Type	Description
ndarray	Array with last axis (Fx, Fy, Fz).

cartesian_to_cylindrical

Convert Cartesian vectors to cylindrical components.

Parameters:

Name	Type	Description	Default
F_cart	array - like	Vector field with last axis (Fx, Fy, Fz).	required
phi	array - like	Azimuth angle in radians.	required

Returns:

Type	Description
ndarray	Vector field with last axis (F_rho, F_phi, F_z).

cylindrical_to_cartesian

Convert cylindrical vectors to Cartesian components.

Parameters:

Name	Type	Description	Default
F_cyl	array - like	Vector field with last axis (F_rho, F_phi, F_z).	required
phi	array - like	Azimuth angle in radians.	required

Returns:

Type	Description
ndarray	Vector field with last axis (Fx, Fy, Fz).

format_complex_auto

Format a complex scalar (or quantity) with compact zero suppression.

Parameters:

Name	Type	Description	Default
z	complex | Quantity	Value to format.	required
tol	float	Threshold below which real/imaginary parts are treated as zero.	1e-14

Returns:

Type	Description
str	Human-readable complex number string, including unit suffix if present.

GuidedMode

Parameters:

Name	Type	Description	Default
fibre	StepIndexFibre	Parent fibre object used for material/profile and dispersion queries.	required
ell	int	Azimuthal mode index.	required
m	int	Internal radial mode index (1-based).	required
wl	float | Quantity[m]	Wavelength in meters.	required
mode_type	(HE, EH, TE, TM, None)	Mode-family selector. For ell=0, use "TE" or "TM". For ell>0, typically "HE" or "EH".	"HE"
N_b	int	Number of samples used for root bracketing when solving for b.	2000
a	complex	Default superposition coefficient used as a_plus when a_plus/a_minus are not explicitly provided.	1.0
a_plus	complex	Coefficient of the +|ell| degenerate partner.	None
a_minus	complex	Coefficient of the -|ell| degenerate partner. Ignored for non-degenerate ell=0 modes.	None

Raises:

Type	Description
ModeNotFoundError	If no guided root exists for the requested (ell, m, wl).

Notes

If neither a_plus nor a_minus is provided, the default is a_plus=a and a_minus=0.

Construction And Cache

Analytical representation of one guided mode at fixed wavelength.

A GuidedMode stores the solved modal constants and exposes methods to evaluate electric/magnetic phasors and their derivatives on arbitrary grids.

clear_grid_cache

Clear cached grid-dependent intermediate arrays.

Returns:

Type	Description
None	Empties the per-instance grid cache.

Material Accessors

Analytical representation of one guided mode at fixed wavelength.

A GuidedMode stores the solved modal constants and exposes methods to evaluate electric/magnetic phasors and their derivatives on arbitrary grids.

eps

Evaluate relative permittivity at radial coordinate(s).

Parameters:

Name	Type	Description	Default
rho	float | array - like	Radial coordinate in meters.	required

Returns:

Type	Description
float | complex | ndarray	Relative permittivity.

mu

Evaluate relative permeability at radial coordinate(s).

Parameters:

Name	Type	Description	Default
rho	float | array - like	Radial coordinate in meters.	required

Returns:

Type	Description
float | complex | ndarray	Relative permeability.

n

Evaluate refractive index at radial coordinate(s).

Parameters:

Name	Type	Description	Default
rho	float | array - like	Radial coordinate in meters.	required

Returns:

Type	Description
float | complex | ndarray	Refractive index.

k

Evaluate local wave number k = k0 * n(rho).

Parameters:

Name	Type	Description	Default
rho	float | array - like	Radial coordinate in meters.	required

Returns:

Type	Description
float | complex | ndarray	Local wave number in rad/m.

kap

Evaluate local transverse wave number.

Parameters:

Name	Type	Description	Default
rho	float | array - like	Radial coordinate in meters.	required

Returns:

Type	Description
complex | ndarray	sqrt(k(rho)^2 - kz^2) with complex branch support.

sigma

Compute power-normalization coefficient for modal amplitudes.

Parameters:

Name	Type	Description	Default
A	complex	Longitudinal-field coefficients. Defaults to the instance values.	None
B	complex	Longitudinal-field coefficients. Defaults to the instance values.	None

Returns:

Type	Description
complex | float	Modal normalization coefficient used in amplitude normalization.

Field Evaluation

Analytical representation of one guided mode at fixed wavelength.

A GuidedMode stores the solved modal constants and exposes methods to evaluate electric/magnetic phasors and their derivatives on arbitrary grids.

E

Evaluate electric field phasor on a transverse grid.

Parameters:

Name	Type	Description	Default
rho	array - like	Cylindrical coordinates in meters/radians.	None
phi	array - like	Cylindrical coordinates in meters/radians.	None
z	float | array - like	Longitudinal position in meters.	0
x	array - like	Cartesian coordinates in meters.	None
y	array - like	Cartesian coordinates in meters.	None
coord	(cartesian, cylindrical)	Output vector basis. Also accepts "cart"/"cyl" prefixes.	"cartesian"

Returns:

Type	Description
ndarray	Complex electric field with last axis (Ex, Ey, Ez) for Cartesian, or (E_rho, E_phi, E_z) for cylindrical output.

Notes

The returned phasor is built from the cylindrical-mode expansion \(\sum_s E^{(s)}(\rho)\,\mathbf{e}_s\,e^{i(\ell-s)\phi}e^{ik_z z}\), with optional superposition of degenerate +/-ell partners via a_plus and a_minus.

H

Evaluate magnetic field phasor on a transverse grid.

Parameters:

Name	Type	Description	Default
rho	array - like	Cylindrical coordinates in meters/radians.	None
phi	array - like	Cylindrical coordinates in meters/radians.	None
z	float | array - like	Longitudinal position in meters.	0
x	array - like	Cartesian coordinates in meters.	None
y	array - like	Cartesian coordinates in meters.	None
coord	(cartesian, cylindrical)	Output vector basis. Also accepts "cart"/"cyl" prefixes.	"cartesian"

Returns:

Type	Description
ndarray	Complex magnetic field with last axis (Hx, Hy, Hz) for Cartesian, or (H_rho, H_phi, H_z) for cylindrical output.

Notes

Uses the same modal ansatz and phase convention as :meth:E, with magnetic spin components linked to electric ones through Maxwell-coupled amplitudes.

gradE

Evaluate spatial Jacobian of the electric field.

Parameters:

Name	Type	Description	Default
rho	array - like	Cylindrical coordinates in meters/radians.	None
phi	array - like	Cylindrical coordinates in meters/radians.	None
z	float | array - like	Longitudinal position in meters.	0
x	array - like	Cartesian coordinates in meters.	None
y	array - like	Cartesian coordinates in meters.	None
coord	(cartesian, cylindrical)	Coordinate basis for derivative columns.	"cartesian"

Returns:

Type	Description
ndarray	Array J[..., i, j] = dE_i / dx_j.

Notes

Implements the analytical Jacobian derived from the mode ansatz. For coord='cylindrical', derivative columns are ordered as \((\partial/\partial\rho,\,(1/\rho)\partial/\partial\phi,\,\partial/\partial z)\).

gradH

Evaluate spatial Jacobian of the magnetic field.

Parameters:

Name	Type	Description	Default
rho	array - like	Cylindrical coordinates in meters/radians.	None
phi	array - like	Cylindrical coordinates in meters/radians.	None
z	float | array - like	Longitudinal position in meters.	0
x	array - like	Cartesian coordinates in meters.	None
y	array - like	Cartesian coordinates in meters.	None
coord	(cartesian, cylindrical)	Coordinate basis for derivative columns.	"cartesian"

Returns:

Type	Description
ndarray	Array J[..., i, j] = dH_i / dx_j.

Notes

Magnetic-field Jacobian counterpart of :meth:gradE, using the same analytical derivative pathway (no finite differences).

Power

Compute guided power by integrating the time-averaged Poynting flux.

Parameters:

Name	Type	Description	Default
rho	array - like	Polar integration grid in meters/radians.	None
phi	array - like	Polar integration grid in meters/radians.	None
z	float	Longitudinal position in meters.	0
x	array - like	Cartesian integration grid in meters.	None
y	array - like	Cartesian integration grid in meters.	None
auto	bool | None	If True (or None with no grid given), run adaptive square-grid integration. If False, explicit grid input is required.	None
extent_factor	float	Initial half-width in units of core radius for adaptive integration.	8.0
N	int	Grid resolution per axis for adaptive integration.	1000
tol	float	Relative convergence threshold for adaptive integration.	1e-3
max_iter	int	Maximum number of domain expansions in adaptive mode.	8
expand_factor	float	Domain growth multiplier between adaptive iterations.	1.5
cache	bool	Cache the latest adaptive-integration result.	True
geometry	square	Adaptive integration geometry.	"square"

Returns:

Type	Description
float	Estimated guided power crossing the transverse plane.

Notes

Computes the time-averaged power \(P=\frac{1}{2}\int \mathrm{Re}(\mathbf{E}\times\mathbf{H}^*)\cdot\hat{\mathbf{z}}\,dA\) over the transverse plane. This is the numerical counterpart of the analytical normalization relation used for \(\sigma\) in the paper.

Labelling

Analytical representation of one guided mode at fixed wavelength.

A GuidedMode stores the solved modal constants and exposes methods to evaluate electric/magnetic phasors and their derivatives on arbitrary grids.

mode_label property

Return HTML-formatted mode family label.

Returns:

Type	Description
str	Label such as HE<sub>11</sub> or TE<sub>01</sub>.

Polarisation And Stokes

Analytical representation of one guided mode at fixed wavelength.

A GuidedMode stores the solved modal constants and exposes methods to evaluate electric/magnetic phasors and their derivatives on arbitrary grids.

S0 property

Unnormalised Stokes-like intensity parameter.

S1 property

Unnormalised Stokes-like parameter S0 * s1.

S2 property

Unnormalised Stokes-like parameter S0 * s2.

S3 property

Unnormalised Stokes-like parameter S0 * s3.

stokes

Return Stokes-like parameters derived from a_plus/a_minus.