solprop.plotting.style#

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

The small plotting helpers, and the display units every figure in this package uses: z in centimetres, time in femtoseconds, wavelength in nanometres, frequency in petahertz, angular frequency in radians per femtosecond, energy in microjoules and power auto-scaled between kilowatts and petawatts. Those are conventions of the figure, not of the package: everything solprop.processing returns is SI (conventions.md section 1), and the conversion happens here, once. A run uniform in y (a hollow planar guide) reports its powers and energies per metre of y, and per_width() is the suffix its labels carry.

Module Attributes

`Z_TO_CM`	Metres to centimetres, the distance unit of every propagation axis.
`T_TO_FS`	Seconds to femtoseconds, the unit of every time axis.
`ENERGY_TO_UJ`	Joules to microjoules, the unit of every energy axis.
`POWER_UNITS`	The power units `power_unit()` chooses between.
`Corner`	Upper or lower, left or right.
`CORNERS`	The four corners of an axis.

Functions

`cmap_colours`(count[, name, low, high])	Return evenly spaced colours from a colour map, for a family of lines.
`cmap_white`([name, stops, levels])	Return a colour map whose lowest colour has been replaced by white.
`corner_text`(ax, text[, corner, pad])	Place a label in one corner of an axis, in axis coordinates.
`field_modes`(output)	Return how many modes, or transverse columns, a run's field carries.
`fwhm_arrows`(ax, x, y, *[, unit, outer, colour])	Mark the full width at half maximum of a trace with two arrows and a label.
`mode_labels`(output, n_modes)	Return a display name for each propagated mode, from the run's own metadata.
`per_width`(output)	Return the suffix a power or energy label takes on a run uniform in y.
`power_unit`(power)	Return the factor and label that put a power in a readable unit.
`spectral_display`(axis)	Return the display factor and axis label of a spectral abscissa.
`subplot_grid`(count, *[, portrait, width, height])	Return a figure with a near-square grid of axes and the axes in row order.
`wavelength_to_axis`(axis, wavelength_range)	Return a wavelength range on a spectral abscissa, in SI units.

solprop.plotting.style.CORNERS: tuple[Literal['ul', 'ur', 'll', 'lr'], ...] = ('ul', 'ur', 'll', 'lr')#: The four corners of an axis.

solprop.plotting.style.Corner#

Upper or lower, left or right.

alias of Literal[‘ul’, ‘ur’, ‘ll’, ‘lr’]

solprop.plotting.style.ENERGY_TO_UJ = 1000000.0#: Joules to microjoules, the unit of every energy axis.

solprop.plotting.style.POWER_UNITS = ('kW', 'MW', 'GW', 'TW', 'PW')#: The power units power_unit() chooses between.

solprop.plotting.style.T_TO_FS = 1000000000000000.0#: Seconds to femtoseconds, the unit of every time axis.

solprop.plotting.style.Z_TO_CM = 100.0#: Metres to centimetres, the distance unit of every propagation axis.

solprop.plotting.style.cmap_colours(count, name='viridis', *, low=0.0, high=0.8)[source]#

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:

countint: How many colours to return, at least one.
namestr: Name of the matplotlib colour map.
lowfloat: Where in the map to start, in [0, 1].
highfloat: 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

solprop.plotting.style.cmap_white(name='viridis', *, stops=8, levels=4096)[source]#

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 from_list() does and is indistinguishable at the number of levels used here.

Parameters:

namestr: Name of the matplotlib colour map to start from.
stopsint: How many colours to sample from it before replacing the first.
levelsint: 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]

solprop.plotting.style.corner_text(ax, text, corner='ul', *, pad=0.02, **kwargs)[source]#

Place a label in one corner of an axis, in axis coordinates.

Parameters:

axmatplotlib.axes.Axes: The axis to write on.
textstr: The label.
corner{‘ul’, ‘ur’, ‘ll’, ‘lr’}: Which corner: upper or lower, left or right.
padfloat: Distance from the corner, as a fraction of the axis.
**kwargsAny: Passed to 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)

solprop.plotting.style.field_modes(output)[source]#

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:

outputsolprop.output.schema.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

solprop.plotting.style.fwhm_arrows(ax, x, y, *, unit='fs', outer=False, colour='k')[source]#

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:

axmatplotlib.axes.Axes: The axis to draw on.
xnumpy.ndarray: Abscissa, shape (n,), in the unit of unit.
ynumpy.ndarray: The trace, shape (n,).
unitstr: Unit of x, for the label.
outerbool: Whether to mark the outermost crossings rather than the central feature.
colourstr: 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)

solprop.plotting.style.mode_labels(output, n_modes)[source]#

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:

outputsolprop.output.schema.Output: An opened output handler.
n_modesint: 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']

solprop.plotting.style.per_width(output)[source]#

Return the suffix a power or energy label takes on a run uniform in y.

Parameters:

outputsolprop.output.schema.Output: An opened output handler.

Returns:

str: "/m" when the run’s powers and energies are per metre of y (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())
''

solprop.plotting.style.power_unit(power)[source]#

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:

powernumpy.ndarray: Powers, W; only the maximum matters.

Returns:

factorfloat: What to multiply a power in watts by.
labelstr: The unit, one of 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')

solprop.plotting.style.spectral_display(axis)[source]#

Return the display factor and axis label of a spectral abscissa.

Parameters:

axis{‘wavelength’, ‘f’, ‘omega’}: The abscissa, in SI units as solprop.processing returns it.

Returns:

factorfloat: What to multiply the SI abscissa by: nm, PHz or rad/fs.
labelstr: The axis label, unit included.

Examples

>>> from solprop.plotting.style import spectral_display
>>> spectral_display("wavelength")
(1000000000.0, 'Wavelength (nm)')

solprop.plotting.style.subplot_grid(count, *, portrait=True, width=4.0, height=2.5)[source]#

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 matplotlib.pyplot.subplots() returns.

Parameters:

countint: How many axes are wanted, at least one.
portraitbool: Whether to make the grid taller than it is wide.
widthfloat: Width of each column, inches.
heightfloat: Height of each row, inches.

Returns:

figurematplotlib.figure.Figure: The figure.
axeslist 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)

solprop.plotting.style.wavelength_to_axis(axis, wavelength_range)[source]#

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_rangetuple of float: The range, m, in either order.

Returns:

tuple of float: The lower and upper limits in m, Hz or rad/s.

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'