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()andspec_1d()the time-domain and spectral slices at one or more positions, into a caller’saxwhen given one, so a figure of several panels is assembled by the caller;plot_energy()the energy along the propagation.default_time_range()anddefault_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
Fraction of a trace's energy a default time range may leave out on each side. |
|
Fraction of the occupied time span added on each side of a default time range. |
|
What a time-domain slice draws: the power, the real field, or its square. |
|
The three time-domain quantities: power, field and squared field. |
Functions
|
Return the spectral range a plot shows when it is given none: the run's band. |
|
Return the time range a plot shows when it is given none: where the light is. |
|
Return the energy along the propagation, with a conversion-efficiency axis. |
|
Return the false-colour propagation maps of a run, one figure per mode. |
|
Return spectral slices of a run at one or more positions. |
|
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 byTIME_MARGINof 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_FRACTIONof its energy to the latest it passes one less that fraction, widened byTIME_MARGINof 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
tas 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
Passbandon 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
Passbandon 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 belowdb_minis.
- 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', *, plane=None, 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.
- planeint, sequence of int or None
Saved planes to draw, by index, negative from the end; refused beside z.
- 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.
- solprop.exceptions.ProcessingError
If both z and plane are given.
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, *, plane=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.
- planeint, sequence of int or None
Saved planes to draw, by index, negative from the end; refused beside z.
- 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
Passbandon 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.opticsapplied 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.
- solprop.exceptions.ProcessingError
If both z and plane are given.
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)