Source code for solprop.plotting.style

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""Colours, grids, units and annotations shared by the standard figures.

The display units every figure uses -- z in centimetres (:data:`Z_TO_CM`), time in
femtoseconds (:data:`T_TO_FS`), wavelength in nanometres, frequency in petahertz,
angular frequency in radians per femtosecond, energy in microjoules
(:data:`ENERGY_TO_UJ`) and power auto-scaled (:func:`power_unit`) -- are conventions
of the *figure*: everything :mod:`solprop.processing` returns is SI (``conventions.md``
§1), and the conversion happens here, once.

- Units and axes: :func:`power_unit`, :func:`spectral_display`,
  :func:`wavelength_to_axis` and :func:`per_width` (the label suffix of a run uniform
  in y, which reports per metre of y).
- Figures and colours: :func:`subplot_grid`, :func:`cmap_white` and
  :func:`cmap_colours`.
- Annotations: :func:`corner_text`, :func:`fwhm_arrows`, :func:`field_modes` and
  :func:`mode_labels`.
"""

import math
from typing import Any, Literal

import numpy as np
from jaxtyping import Float
from matplotlib.axes import Axes
from matplotlib.colors import Colormap, LinearSegmentedColormap
from matplotlib.figure import Figure

from solprop._validation import choice
from solprop.constants import C
from solprop.exceptions import ProcessingError
from solprop.output.store import Output, PlaneStore
from solprop.processing.axes import (
    SPECTRAL_AXES,
    SpectralAxis,
    transverse_units,
)
from solprop.processing.time import half_max_range

__all__ = [
    "CORNERS",
    "ENERGY_TO_UJ",
    "POWER_UNITS",
    "T_TO_FS",
    "Z_TO_CM",
    "Corner",
    "cmap_colours",
    "cmap_white",
    "corner_text",
    "field_modes",
    "fwhm_arrows",
    "mode_labels",
    "per_width",
    "power_unit",
    "spectral_display",
    "subplot_grid",
    "wavelength_to_axis",
]

Z_TO_CM = 1e2
"""Metres to centimetres, the distance unit of every propagation axis."""

T_TO_FS = 1e15
"""Seconds to femtoseconds, the unit of every time axis."""

ENERGY_TO_UJ = 1e6
"""Joules to microjoules, the unit of every energy axis."""

POWER_UNITS = ("kW", "MW", "GW", "TW", "PW")
"""The power units :func:`power_unit` chooses between."""

Corner = Literal["ul", "ur", "ll", "lr"]
"""Upper or lower, left or right."""

CORNERS: tuple[Corner, ...] = ("ul", "ur", "ll", "lr")
"""The four corners of an axis."""


[docs] def cmap_white( name: str = "viridis", *, stops: int = 8, levels: int = 4096 ) -> Colormap: """Return a colour map whose lowest colour has been replaced by white. A propagation map is mostly empty, and a colour map that starts at white puts that emptiness where the eye expects it. The stops are interpolated linearly, which is what :meth:`~matplotlib.colors.LinearSegmentedColormap.from_list` does and is indistinguishable at the number of levels used here. Parameters ---------- name : str Name of the matplotlib colour map to start from. stops : int How many colours to sample from it before replacing the first. levels : int How many levels the returned map holds. Returns ------- matplotlib.colors.Colormap The modified colour map. Examples -------- >>> from solprop.plotting.style import cmap_white >>> [float(channel) for channel in cmap_white()(0.0)] [1.0, 1.0, 1.0, 1.0] """ import matplotlib.pyplot as plt # noqa: PLC0415 - pyplot loads on first plot sampled = plt.get_cmap(name)(np.linspace(0.0, 1.0, stops)) sampled[0] = (1.0, 1.0, 1.0, 1.0) return LinearSegmentedColormap.from_list(f"{name}_white", sampled, N=levels)
[docs] def cmap_colours( count: int, name: str = "viridis", *, low: float = 0.0, high: float = 0.8 ) -> list[tuple[float, float, float, float]]: """Return evenly spaced colours from a colour map, for a family of lines. The default stops at 0.8 because the top of ``viridis`` is a pale yellow that disappears against a white page. Parameters ---------- count : int How many colours to return, at least one. name : str Name of the matplotlib colour map. low : float Where in the map to start, in ``[0, 1]``. high : float Where to stop, in ``[0, 1]``. Returns ------- list of tuple ``count`` RGBA tuples. Raises ------ solprop.exceptions.ProcessingError If fewer than one colour is asked for. Examples -------- >>> from solprop.plotting.style import cmap_colours >>> len(cmap_colours(3)) 3 """ if count < 1: msg = f"at least one colour is needed, got {count}" raise ProcessingError(msg) positions = np.linspace(low, high, count) import matplotlib.pyplot as plt # noqa: PLC0415 - pyplot loads on first plot return [tuple(colour) for colour in plt.get_cmap(name)(positions)]
[docs] def subplot_grid( count: int, *, portrait: bool = True, width: float = 4.0, height: float = 2.5 ) -> tuple[Figure, list[Axes]]: """Return a figure with a near-square grid of axes and the axes in row order. Surplus axes are removed rather than left blank, so a grid of seven panels is a figure of seven panels. The grid is filled in reading order, which is what :func:`matplotlib.pyplot.subplots` returns. Parameters ---------- count : int How many axes are wanted, at least one. portrait : bool Whether to make the grid taller than it is wide. width : float Width of each column, inches. height : float Height of each row, inches. Returns ------- figure : matplotlib.figure.Figure The figure. axes : list of matplotlib.axes.Axes Exactly ``count`` axes, in reading order. Raises ------ solprop.exceptions.ProcessingError If fewer than one axis is asked for. Examples -------- >>> import matplotlib.pyplot as plt >>> from solprop.plotting.style import subplot_grid >>> figure, axes = subplot_grid(5) >>> len(axes), figure.get_size_inches().tolist() (5, [8.0, 7.5]) >>> plt.close(figure) """ if count < 1: msg = f"at least one axis is needed, got {count}" raise ProcessingError(msg) columns = math.ceil(math.sqrt(count)) rows = math.ceil(count / columns) if portrait: rows, columns = columns, rows import matplotlib.pyplot as plt # noqa: PLC0415 - pyplot loads on first plot figure, grid = plt.subplots( rows, columns, figsize=(columns * width, rows * height), squeeze=False ) axes = list(grid.ravel()) for surplus in axes[count:]: surplus.remove() return figure, axes[:count]
[docs] def per_width(output: Output) -> str: """Return the suffix a power or energy label takes on a run uniform in y. Parameters ---------- output : solprop.output.store.Output An opened output handler. Returns ------- str ``"/m"`` when the run's powers and energies are per metre of y (:func:`solprop.processing.axes.transverse_units`), and ``""`` otherwise. Examples -------- >>> from solprop.plotting.style import per_width >>> from solprop.processing._examples import example_output >>> per_width(example_output()) '' """ return "/m" if transverse_units(output).measure == "per_unit_width" else ""
[docs] def power_unit(power: Float[np.ndarray, "*shape"]) -> tuple[float, str]: """Return the factor and label that put a power in a readable unit. The unit is chosen from the largest value, in steps of a thousand from kilowatts to petawatts, so that a trace reads between one and a thousand of whatever it says on the axis. Parameters ---------- power : numpy.ndarray Powers, W; only the maximum matters. Returns ------- factor : float What to multiply a power in watts by. label : str The unit, one of :data:`POWER_UNITS`. Raises ------ solprop.exceptions.ProcessingError If the array is empty. Examples -------- >>> import numpy as np >>> from solprop.plotting.style import power_unit >>> power_unit(np.array([2.5e9])) (1e-09, 'GW') """ if power.size == 0: msg = "an empty array has no power scale" raise ProcessingError(msg) peak = float(np.max(power)) # A plane with no light has no scale of its own; kilowatts is as good as any, and # taking the logarithm of zero would raise here rather than pick one. order = 1 if peak <= 0.0 else int(np.clip(math.floor(math.log10(peak) / 3), 1, 5)) return 10.0 ** (-3 * order), POWER_UNITS[order - 1]
[docs] def spectral_display(axis: SpectralAxis) -> tuple[float, str]: """Return the display factor and axis label of a spectral abscissa. Parameters ---------- axis : {'wavelength', 'f', 'omega'} The abscissa, in SI units as :mod:`solprop.processing` returns it. Returns ------- factor : float What to multiply the SI abscissa by: nm, PHz or rad/fs. label : str The axis label, unit included. Examples -------- >>> from solprop.plotting.style import spectral_display >>> spectral_display("wavelength") (1000000000.0, 'Wavelength (nm)') """ choice(axis, "axis", SPECTRAL_AXES, ProcessingError) if axis == "wavelength": return 1e9, "Wavelength (nm)" if axis == "f": return 1e-15, "Frequency (PHz)" return 1e-15, "Angular frequency (rad/fs)"
[docs] def wavelength_to_axis( axis: SpectralAxis, wavelength_limits: tuple[float, float] ) -> tuple[float, float]: """Return a wavelength range on a spectral abscissa, in SI units. For a plot asked for on a frequency axis by someone who thinks in wavelength: the result is what the plots' ``spec_range`` takes. Parameters ---------- axis : {'wavelength', 'f', 'omega'} The abscissa. wavelength_limits : tuple of float The range, m, in either order. Returns ------- tuple of float The lower and upper limits in m, Hz or rad/s. Raises ------ solprop.exceptions.ProcessingError If ``axis`` is unknown, or if a wavelength limit is not positive on a frequency axis. Examples -------- >>> from solprop.plotting.style import wavelength_to_axis >>> low, high = wavelength_to_axis("f", (400e-9, 2e-6)) >>> f"{low:.4g} Hz, {high:.4g} Hz" '1.499e+14 Hz, 7.495e+14 Hz' """ choice(axis, "axis", SPECTRAL_AXES, ProcessingError) low, high = min(wavelength_limits), max(wavelength_limits) if axis == "wavelength": return low, high if low <= 0.0: msg = f"wavelength_limits must be positive, in m, got {wavelength_limits!r}" raise ProcessingError(msg) turn = 2.0 * np.pi * C if axis == "omega" else C # Wavelength and frequency run in opposite directions, so the limits swap. return float(turn / high), float(turn / low)
def _spec_range( axis: SpectralAxis, spec_range: tuple[float, float] | None, default: tuple[float, float], ) -> tuple[float, float]: """Return the spectral range of a plot, in SI units of its abscissa, ascending. - ``spec_range``: the range asked for, in m, Hz or rad/s as ``axis`` says, in either order. - ``default``: the wavelength range, m, to show when none was asked for. - Returns: the lower and upper limits in the units of ``axis``. """ if spec_range is None: return wavelength_to_axis(axis, default) return float(min(spec_range)), float(max(spec_range)) def _display_limits( axis: SpectralAxis, spec_range: tuple[float, float] ) -> tuple[float, float]: """Return SI limits on a spectral abscissa in the display units of the figure. - ``spec_range``: the ascending limits, in m, Hz or rad/s. """ factor, _ = spectral_display(axis) return float(factor * spec_range[0]), float(factor * spec_range[1])
[docs] def corner_text( ax: Axes, text: str, corner: Corner = "ul", *, pad: float = 0.02, **kwargs: Any ) -> None: """Place a label in one corner of an axis, in axis coordinates. Parameters ---------- ax : matplotlib.axes.Axes The axis to write on. text : str The label. corner : {'ul', 'ur', 'll', 'lr'} Which corner: upper or lower, left or right. pad : float Distance from the corner, as a fraction of the axis. **kwargs : Any Passed to :meth:`matplotlib.axes.Axes.text`. Examples -------- >>> import matplotlib.pyplot as plt >>> from solprop.plotting.style import corner_text >>> figure, ax = plt.subplots() >>> corner_text(ax, "a)") >>> plt.close(figure) """ choice(corner, "corner", CORNERS, ProcessingError) upper, left = corner[0] == "u", corner[1] == "l" ax.text( pad if left else 1.0 - pad, 1.0 - pad if upper else pad, text, transform=ax.transAxes, ha="left" if left else "right", va="top" if upper else "bottom", **kwargs, )
[docs] def fwhm_arrows( ax: Axes, x: Float[np.ndarray, " n"], y: Float[np.ndarray, " n"], *, unit: str = "fs", outer: bool = False, colour: str = "k", ) -> float: """Mark the full width at half maximum of a trace with two arrows and a label. The abscissa is used as it stands, so pass it in the unit the label says: this draws on the axis, it does not convert. Nothing is drawn when the width is undefined. Parameters ---------- ax : matplotlib.axes.Axes The axis to draw on. x : numpy.ndarray Abscissa, shape ``(n,)``, in the unit of ``unit``. y : numpy.ndarray The trace, shape ``(n,)``. unit : str Unit of ``x``, for the label. outer : bool Whether to mark the outermost crossings rather than the central feature. colour : str Colour of the arrows and the label. Returns ------- float The width, in the unit of ``x``, or ``nan`` when there is none. Examples -------- >>> import matplotlib.pyplot as plt >>> import numpy as np >>> from solprop.plotting.style import fwhm_arrows >>> figure, ax = plt.subplots() >>> t = np.linspace(-50.0, 50.0, 401) >>> round(fwhm_arrows(ax, t, np.exp(-((t / 10) ** 2))), 2) 16.65 >>> plt.close(figure) """ low, high = half_max_range(x, y, outer=outer) width = high - low if not math.isfinite(width): return width level = 0.5 * float(np.max(y)) arrow = {"arrowstyle": "->", "color": colour} for tip, tail in ((low, low - width), (high, high + width)): ax.annotate("", xy=(tip, level), xytext=(tail, level), arrowprops=arrow) ax.text( 0.5 * (low + high), 1.05 * level, f"{width:.2f} {unit}", ha="center", va="bottom", color=colour, ) return width
[docs] def field_modes(output: Output) -> int: """Return how many modes, or transverse columns, a run's field carries. Read from the shape the run recorded, so that a run that kept no field (SEP 22) still labels its statistics' columns. Parameters ---------- output : solprop.output.store.Output An opened output handler holding at least one plane. Returns ------- int The field's leading axis, ``n_modes``. Examples -------- >>> from solprop.plotting.style import field_modes >>> from solprop.processing._examples import example_output >>> field_modes(example_output(n_modes=2)) 2 """ if isinstance(output, PlaneStore) and output.field_shape: return int(output.field_shape[0]) return int(output["field"].shape[1])
[docs] def mode_labels(output: Output, n_modes: int) -> list[str]: """Return a display name for each propagated mode, from the run's own metadata. A mode records the class it is and the arguments it was built from, so a capillary mode gives ``HE11``; anything else, and a mode-averaged run, gives ``mode 1``. When the set contains modes at more than one polarisation angle the name carries it, as ``(x)`` and ``(y)`` for the two axes and as a fraction of pi otherwise, read from the recorded mode arguments rather than from the printed form of the transform. Parameters ---------- output : solprop.output.store.Output An opened output handler. n_modes : int How many modes the saved field carries. Returns ------- list of str One label per mode. Examples -------- >>> from solprop.plotting.style import mode_labels >>> from solprop.processing._examples import example_output >>> mode_labels(example_output(n_modes=2), 2) ['mode 1', 'mode 2'] """ metadata = output.metadata records = () if metadata is None else metadata.modes angles = [record.configuration.get("phi") for record in records[:n_modes]] show_angle = any(isinstance(one, float) and one != 0.0 for one in angles) labels = [] for index in range(n_modes): name = f"mode {index + 1}" if index < len(records): configuration = records[index].configuration kind, radial, azimuthal = ( configuration.get("kind"), configuration.get("n"), configuration.get("m"), ) if ( isinstance(kind, str) and isinstance(radial, int) and isinstance(azimuthal, int) ): name = f"{kind}{radial}{azimuthal}" if show_angle: name = f"{name} {_angle_label(angles[index])}" labels.append(name) return labels
def _angle_label(phi: object) -> str: """Return the polarisation suffix of a mode at a given angle. - ``phi``: the angle as the metadata records it, rad, or anything else. """ if not isinstance(phi, float): return "(?)" if phi == 0.0: return "(x)" if phi == 0.5 * math.pi: return "(y)" return f"({phi / math.pi:.2f}pi)" def _figure_of(ax: Axes) -> Figure: """Return the figure an axis belongs to, narrowed to a root figure.""" figure = ax.get_figure(root=True) if figure is None: # pragma: no cover - an axis always belongs to a figure msg = "the axis to draw on does not belong to a figure" raise ProcessingError(msg) return figure