solprop.plotting.propagation#

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

Drawn with matplotlib from whatever solprop.processing returns. Every function takes an Output, returns figures and never calls show(); the slice plots accept an ax to draw into, so a figure of several panels is assembled by the caller rather than by a keyword here.

The display units are solprop.plotting.style’s: z in centimetres, time in femtoseconds, wavelength in nanometres, frequency in petahertz, energy in microjoules and power auto-scaled.

Module Attributes

`DEFAULT_WAVELENGTH_RANGE`	Wavelength range of a propagation map, m.
`DEFAULT_TRANGE`	Time range of a propagation map, s.
`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

`energy`(output, *[, modes, bandpass, ax])	Return the energy along the propagation, with a conversion-efficiency axis.
`prop_2d`(output[, axis, wavelength_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.DEFAULT_TRANGE = (-5e-14, 5e-14)#: Time range of a propagation map, s.

solprop.plotting.propagation.DEFAULT_WAVELENGTH_RANGE = (1.5e-07, 2e-06)#: Wavelength range of a propagation map, m.

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.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.schema.Output: An opened output handler.
modesint, sequence of int, ‘sum’ or None: Which modes to draw.
bandpasstuple of float, numpy.ndarray or None: Wavelength limits, m, 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.

Examples

>>> import matplotlib.pyplot as plt
>>> from solprop.plotting.propagation import energy
>>> from solprop.processing._examples import example_output
>>> figure = energy(example_output())
>>> figure.axes[1].get_ylabel()
'Conversion efficiency (%)'
>>> plt.close(figure)

solprop.plotting.propagation.prop_2d(output, axis='f', *, wavelength_range=(1.5e-07, 2e-06), trange=(-5e-14, 5e-14), db_min=-60.0, resolution=None, modes=None, oversampling=4, bandpass=None, cmap=None)[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.schema.Output: An opened output handler.
axis{‘f’, ‘wavelength’, ‘omega’}: Spectral abscissa of the left panel.
wavelength_rangetuple of float: Spectral limits, m.
trangetuple of float: Time limits, s.
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, numpy.ndarray or None: Wavelength limits, m, of a window applied to the temporal panel.
cmapstr, matplotlib.colors.Colormap or None: Colour map of both panels.

Returns:

list of matplotlib.figure.Figure: One figure per drawn mode, and one for the modal sum when there is more than one.

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)
>>> plt.close("all")

solprop.plotting.propagation.spec_1d(output, z=None, axis='wavelength', *, modes=None, wavelength_range=(1.5e-07, 1.2e-06), log=True, log_min=1e-06, resolution=None, ax=None)[source]#

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

Parameters:

outputsolprop.output.schema.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.
wavelength_rangetuple of float: Spectral limits, m.
logbool: Whether to use a logarithmic ordinate.
log_minfloat: Bottom of a logarithmic ordinate, as a fraction of 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.

Returns:

matplotlib.figure.Figure: The figure the traces were drawn on.

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, trange=(-5e-14, 5e-14), 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.schema.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.
trangetuple of float: Time limits, s.
bandpasstuple of float, numpy.ndarray or None: Wavelength limits, m, 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.

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)