anafibre.utils

Utility functions and optional dependency management for Anafibre. Includes unit handling and color conversion for wavelength visualisation.

GuidedModeList

Bases: list

List subclass that preserves rich HTML display for mode collections.

Slicing returns another :class:GuidedModeList so notebook rendering via _repr_html_ is retained for subsets.

wavelength_to_rgb

Map visible wavelength to an approximate sRGB color.

Parameters:

Name	Type	Description	Default
wl	float	Wavelength in nanometers.	required

Returns:

Type	Description
tuple[float, float, float]	Normalised (R, G, B) values in the range [0, 1]. Values outside the visible range (380-780 nm) return black (0, 0, 0).

Notes

Uses a standard piecewise approximation for visible-spectrum mapping rather than a colorimetrically exact CIE conversion.

wavelength_band_label_nm

Classify non-visible wavelengths into coarse EM-band labels.

Parameters:

Name	Type	Description	Default
wl_nm	float | None	Wavelength in nanometers.	required

Returns:

Type	Description
tuple[str | None, str | None]	A tuple (label, color_hex). Visible wavelengths return (None, None) because they are rendered with :func:wavelength_to_rgb.

Notes

The THz window (30 um to 3 mm) takes precedence over overlapping broader infrared/microwave naming ranges.

pretty_length

Format a length quantity as a compact LaTeX fragment.

Parameters:

Name	Type	Description	Default
qty	Quantity	Length quantity.	required
digits	int	Significant digits in the formatted value.	3

Returns:

Type	Description
str	A LaTeX snippet without surrounding $ delimiters.

Raises:

Type	Description
AttributeError	If qty is not an astropy quantity-like object with to_value.

Notes

Chooses the first unit in (m, cm, mm, um, nm) whose absolute numeric value lies in [1, 1000); otherwise falls back to meters.

repr_html_modes

Build a single HTML table summarizing a sequence of guided modes.

Parameters:

Name	Type	Description	Default
modes	iterable	Iterable of guided-mode-like objects with at least mode_label, wl, V, neff, a_plus and a_minus attributes. Optional attributes ell and mode_type are used to select polarization conventions for Stokes parameters.	required

Returns:

Type	Description
str	HTML markup for a styled table. Returns an empty string if no valid modes are provided.

Notes

For ell != 0, normalized Stokes parameters are computed from a_plus and a_minus. For ell == 0, TE is rendered as linear S1=-1 and all other ell == 0 modes as S1=+1.

display_modes

Render one or more guided modes as an HTML table in notebooks.

Parameters:

Name	Type	Description	Default
*modes		One or more :class:anafibre.fields.GuidedMode objects.	()

Returns:

Type	Description
None	Displays HTML output via IPython.

Notes

Intended for notebook environments where IPython.display is available.

display_anim

Render a Matplotlib animation inline in notebooks.

Parameters:

Name	Type	Description	Default
anim	Animation	Animation instance with a to_jshtml method.	required

Returns:

Type	Description
None	Displays the animation via IPython HTML output.

Notes

Uses anim.to_jshtml() for inline playback in Jupyter-style frontends.