solprop.plotting.propagation#

The standard figures of a propagation: the maps, the slices and the energy.

  • prop_2d() draws the false-colour propagation maps, one figure per mode; time_1d() and spec_1d() the time-domain and spectral slices at one or more positions, into a caller’s ax when given one, so a figure of several panels is assembled by the caller; plot_energy() the energy along the propagation.

  • default_time_range() and default_spec_range() choose what a plot shows when it is given no range (where the light is; the run’s band).

Display units are solprop.plotting.style’s. These figures draw modes, so a radial, Cartesian, line or planar file is refused by the figure’s name, naming the spatial functionals to draw instead (solprop.output.capability.COLUMN_READINGS). The manual page is docs/guide/results/plotting.md.

Module Attributes

TIME_ENERGY_FRACTION

Fraction of a trace's energy a default time range may leave out on each side.

TIME_MARGIN

Fraction of the occupied time span added on each side of a default time range.

SliceQuantity

What a time-domain slice draws: the power, the real field, or its square.

SLICE_QUANTITIES

The three time-domain quantities: power, field and squared field.

Functions

default_spec_range(output, axis)

Return the spectral range a plot shows when it is given none: the run's band.

default_time_range(t, power)

Return the time range a plot shows when it is given none: where the light is.

plot_energy(output, *[, modes, bandpass, ax])

Return the energy along the propagation, with a conversion-efficiency axis.

prop_2d(output[, axis, spec_range, ...])

Return the false-colour propagation maps of a run, one figure per mode.

spec_1d(output[, z, axis, modes, ...])

Return spectral slices of a run at one or more positions.

time_1d(output[, z, quantity, modes, ...])

Return time-domain slices of a run at one or more positions.

solprop.plotting.propagation.SLICE_QUANTITIES: tuple[Literal['power', 'field', 'field_squared'], ...] = ('power', 'field', 'field_squared')#

The three time-domain quantities: power, field and squared field.

solprop.plotting.propagation.SliceQuantity#

What a time-domain slice draws: the power, the real field, or its square.

alias of Literal[‘power’, ‘field’, ‘field_squared’]

solprop.plotting.propagation.TIME_ENERGY_FRACTION = 0.0005#

Fraction of a trace’s energy a default time range may leave out on each side.

With no time_range, a plot shows the span between the instants where each drawn trace’s running energy passes this fraction and one less it, joined over the traces and widened by TIME_MARGIN of its width on each side, within the run’s time window (default_time_range()).

solprop.plotting.propagation.TIME_MARGIN = 0.25#

Fraction of the occupied time span added on each side of a default time range.

solprop.plotting.propagation.default_spec_range(output, axis)[source]#

Return the spectral range a plot shows when it is given none: the run’s band.

The band the run’s grid was declared over (its wavelength_limits), on the abscissa asked for, so a deep-ultraviolet, a near-infrared and a mid-infrared run each fill their figure.

Parameters:
outputsolprop.output.store.Output

An opened output handler.

axis{‘wavelength’, ‘f’, ‘omega’}

The spectral abscissa.

Returns:
tuple of float

The ascending limits in m, Hz or rad/s.

Examples

>>> from solprop.plotting.propagation import default_spec_range
>>> from solprop.processing._examples import example_output
>>> low, high = default_spec_range(example_output(), "wavelength")
>>> f"{low * 1e9:.0f} nm to {high * 1e9:.0f} nm"
'400 nm to 2000 nm'
solprop.plotting.propagation.default_time_range(t, power)[source]#

Return the time range a plot shows when it is given none: where the light is.

Each trace’s running energy is followed from the start of the window: the range runs from the earliest instant any trace passes TIME_ENERGY_FRACTION of its energy to the latest it passes one less that fraction, widened by TIME_MARGIN of its width on each side and kept within the window. A picosecond fibre pulse and a few-cycle one both fill their figure, and a pulse that walks off or spreads along a run is followed, without a fixed window clipping one or drowning the other.

Parameters:
tnumpy.ndarray

The time axis, s, ascending, shape (n_t,).

powernumpy.ndarray

The traces to show, W or any non-negative density in time, with t as their last axis.

Returns:
tuple of float

The lower and upper limits, s; the whole window when no trace carries energy.

Examples

>>> import numpy as np
>>> from solprop.plotting.propagation import default_time_range
>>> t = np.linspace(-1e-12, 1e-12, 2001)
>>> low, high = default_time_range(t, np.exp(-(t / 30e-15) ** 2))
>>> -0.2e-12 < low < -30e-15 and 30e-15 < high < 0.2e-12
True
solprop.plotting.propagation.plot_energy(output, *, modes=None, bandpass=None, ax=None)[source]#

Return the energy along the propagation, with a conversion-efficiency axis.

The right-hand axis is the same data as a percentage of the total energy of every mode at the first saved plane, before any bandpass, which is what a conversion efficiency means. Its limits are set from the left axis analytically rather than by drawing an invisible line for matplotlib to autoscale.

Parameters:
outputsolprop.output.store.Output

An opened output handler.

modesint, sequence of int, ‘sum’ or None

Which modes to draw.

bandpasstuple of float, Passband, numpy.ndarray or None

Wavelength limits, m, or a Passband on any axis, of a window applied before the measurement, which is how the energy in one spectral region is followed along z.

axmatplotlib.axes.Axes or None

Axis to draw into; a new figure is made when none is given.

Returns:
matplotlib.figure.Figure

The figure the traces were drawn on.

Raises:
solprop.exceptions.OutputError

If the stored run is a spatial one, whose columns are not modal amplitudes, or a general modal one, whose coordinate energies do not add.

Examples

>>> import matplotlib.pyplot as plt
>>> from solprop.plotting.propagation import plot_energy
>>> from solprop.processing._examples import example_output
>>> figure = plot_energy(example_output())
>>> figure.axes[1].get_ylabel()
'Conversion efficiency (%)'
>>> plt.close(figure)
solprop.plotting.propagation.prop_2d(output, axis='wavelength', *, spec_range=None, time_range=None, db_min=-60.0, resolution=None, modes=None, oversampling=4, bandpass=None, cmap=None, noise_floor='keep')[source]#

Return the false-colour propagation maps of a run, one figure per mode.

Each figure carries the spectral energy density in decibels beside the instantaneous power, both against distance. A multimode run gets one figure per mode and a last one for the modal sum; a single-mode run gets one figure.

The decibel scale is shared: every map is normalised by the peak of the modal sum, so the modes are comparable and none goes above 0 dB; normalising by the peak of the per-mode maps and then summing would take the summed map off the top of the scale. The bandpass reaches the temporal panel only: a window drawn on the spectrum it is displayed beside would be circular.

Parameters:
outputsolprop.output.store.Output

An opened output handler.

axis{‘wavelength’, ‘f’, ‘omega’}

Spectral abscissa of the left panel, as for every other plot.

spec_rangetuple of float or None

Spectral limits in the units of axis: m, Hz or rad/s. By default the run’s band (default_spec_range()); wavelength_to_axis() converts a wavelength range. A range that selects no sample of the axis is refused.

time_rangetuple of float or None

Time limits, s. By default where the light is at every plane (default_time_range()).

db_minfloat

Bottom of the colour scale, dB below the peak.

resolutionfloat or None

Instrument resolution of the spectral panel, in the units of axis.

modesint, sequence of int, ‘sum’ or None

Which modes to draw.

oversamplingint

Time-domain resampling factor of the temporal panel.

bandpasstuple of float, Passband, numpy.ndarray or None

Wavelength limits, m, or a Passband on any axis, of a window applied to the temporal panel.

cmapstr, matplotlib.colors.Colormap or None

Colour map of both panels.

noise_floor{‘keep’, ‘subtract’}

Whether the spectral panel keeps or removes the input noise’s seed (get_spectral_density()). A value at or below zero, which the subtraction can leave, is drawn at the bottom of the colour scale, as everything below db_min is.

Returns:
list of matplotlib.figure.Figure

One figure per drawn mode, and one for the modal sum when there is more than one.

Raises:
solprop.exceptions.OutputError

If the stored run is a spatial one, whose columns are not modal amplitudes.

Examples

>>> import matplotlib.pyplot as plt
>>> from solprop.plotting.propagation import prop_2d
>>> from solprop.processing._examples import example_output
>>> figures = prop_2d(example_output())
>>> len(figures), len(figures[0].axes)
(1, 4)
>>> figures = prop_2d(example_output(), "f", spec_range=(0.0, 2e15))
>>> figures[0].axes[0].get_xlim() == (0.0, 2.0)
True
>>> plt.close("all")
solprop.plotting.propagation.spec_1d(output, z=None, axis='wavelength', *, modes=None, spec_range=None, log=True, db_min=-60.0, resolution=None, ax=None, noise_floor='keep')[source]#

Return spectral slices of a run at one or more positions.

Parameters:
outputsolprop.output.store.Output

An opened output handler.

zfloat, sequence of float or None

Positions to draw, m; the end of the run by default.

axis{‘wavelength’, ‘f’, ‘omega’}

Spectral abscissa.

modesint, sequence of int, ‘sum’ or None

Which modes to draw.

spec_rangetuple of float or None

Spectral limits in the units of axis: m, Hz or rad/s. By default the run’s band (default_spec_range()); wavelength_to_axis() converts a wavelength range.

logbool

Whether to use a logarithmic ordinate.

db_minfloat

Bottom of a logarithmic ordinate, dB below the largest value drawn.

resolutionfloat or None

Instrument resolution, in the units of axis.

axmatplotlib.axes.Axes or None

Axis to draw into; a new figure is made when none is given.

noise_floor{‘keep’, ‘subtract’}

Whether the slices keep or remove the input noise’s seed (get_spectral_density()). On a logarithmic ordinate a value at or below zero, which the subtraction can leave, is masked rather than drawn.

Returns:
matplotlib.figure.Figure

The figure the traces were drawn on.

Raises:
solprop.exceptions.OutputError

If the stored run is a spatial one, whose columns are not modal amplitudes.

Examples

>>> import matplotlib.pyplot as plt
>>> from solprop.plotting.propagation import spec_1d
>>> from solprop.processing._examples import example_output
>>> figure = spec_1d(example_output(), 0.0)
>>> figure.axes[0].get_xlabel()
'Wavelength (nm)'
>>> plt.close(figure)
solprop.plotting.propagation.time_1d(output, z=None, *, quantity='power', modes=None, oversampling=4, time_range=None, bandpass=None, widths=True, ax=None, transfer=None, transform_limit=False)[source]#

Return time-domain slices of a run at one or more positions.

Parameters:
outputsolprop.output.store.Output

An opened output handler.

zfloat, sequence of float or None

Positions to draw, m; the end of the run by default.

quantity{‘power’, ‘field’, ‘field_squared’}

What to draw: the instantaneous power, the real field, or its square.

modesint, sequence of int, ‘sum’ or None

Which modes to draw; only a power may be summed over modes.

oversamplingint

Time-domain resampling factor.

time_rangetuple of float or None

Time limits, s. By default where the drawn traces’ light is (default_time_range()).

bandpasstuple of float, Passband, numpy.ndarray or None

Wavelength limits, m, or a Passband on any axis, of a window applied before the transform.

widthsbool

Whether to append each trace’s width at half maximum to its legend entry.

axmatplotlib.axes.Axes or None

Axis to draw into; a new figure is made when none is given.

transferTransferFunction or None

A linear optical element of solprop.optics applied before the transform: draw the pulse after a compressor.

transform_limitbool

Whether to draw the transform-limited pulse of each spectrum.

Returns:
matplotlib.figure.Figure

The figure the traces were drawn on.

Raises:
solprop.exceptions.OutputError

If the stored run is a spatial one, whose columns are not modal amplitudes.

Examples

>>> import matplotlib.pyplot as plt
>>> from solprop.plotting.propagation import time_1d
>>> from solprop.processing._examples import example_output
>>> figure = time_1d(example_output(), [0.0, 0.1])
>>> len(figure.axes[0].lines)
2
>>> plt.close(figure)