Plotting

This page documents Ulula’s plotting capabilities.

Overview

Ulula comes with two plotting routines for 1D and 2D data, plot1d() and plot2d(). Both plot multiple panels for multiple fluid quantities that are given as a list of strings. Valid identifiers are listed in the fields dictionary. A simulation object must be passed to the plotting functions.

Plottable quantities

All plotting functions take a q_plot parameter that contains a list of the fluid variables to be plotted. The fields and their properties are defined in the following dictionary:

ulula.core.plots.fields: List of fields that can be plotted. Most fields occur in the primitive or conserved variable arrays, but some fields are derived (e.g., total velocity).

Possible values include the primitive and conserved variables that the simulation keeps track of (see Simulation framework), as well as some derived quantities:

Abbreviation	Quantity
`DN`	Density
`VX`	X-velocity
`VY`	Y-velocity
`VT`	Total velocity
`MX`	X-momentum
`MY`	Y-momentum
`PR`	Pressure
`ET`	Total energy (internal + kinetic + potentials)
`EI`	Internal energy
`TK`	Temperature in Kelvin
`GP`	Gravitational potential
`GX`	Gravitational potential gradient in x
`GY`	Gravitational potential gradient in y

Units

The user can plot in code units or choose a unit system for plotting, which may or may not correspond to the system of code units set in the simulation itself. For example, if the unit system of the underlying simulation is cgs (the default), then plotting with unit length, time, and mass of 1 centimeter, 1 second, and 1 gram leads to exactly the same plot as plotting in code units (albeit with slightly different labels). However, instead choosing 1 meter as the plotted unit will change the spatial axes as well as fluid properties that depend on length, such as density. In the plotting functions documented below, the plotted units are chosen via the following string codes:

Abbreviation	Symbol	CGS value
Length (in cm)
`nm`	\({\rm nm}\)	\(10^{-7}\)
`mum`	\({\rm \mu m}\)	\(10^{-4}\)
`mm`	\({\rm mm}\)	\(10^{-1}\)
`cm`	\({\rm cm}\)	\(1\)
`m`	\({\rm m}\)	\(10^{2}\)
`km`	\({\rm km}\)	\(10^{5}\)
`au`	\({\rm AU}\)	\(1.496\times10^{13}\)
`pc`	\({\rm pc}\)	\(3.086\times10^{18}\)
`kpc`	\({\rm kpc}\)	\(3.086\times10^{21}\)
`Mpc`	\({\rm Mpc}\)	\(3.086\times10^{24}\)
`Gpc`	\({\rm Gpc}\)	\(3.086\times10^{27}\)
Time (in s)
`ns`	\({\rm ns}\)	\(10^{-9}\)
`mus`	\({\rm \mu s}\)	\(10^{-6}\)
`ms`	\({\rm ms}\)	\(10^{-3}\)
`s`	\({\rm s}\)	\(1\)
`min`	\({\rm min}\)	\(6.000\times10^{1}\)
`hr`	\({\rm hr}\)	\(3.600\times10^{3}\)
`yr`	\({\rm yr}\)	\(3.156\times10^{7}\)
`kyr`	\({\rm kyr}\)	\(3.156\times10^{10}\)
`Myr`	\({\rm Myr}\)	\(3.156\times10^{13}\)
`Gyr`	\({\rm Gyr}\)	\(3.156\times10^{16}\)
Mass (in g)
`u`	\({\rm u}\)	\(1.661\times10^{-24}\)
`mp`	\(m_{\rm p}\)	\(1.673\times10^{-24}\)
`ng`	\({\rm ng}\)	\(10^{-9}\)
`mug`	\({\rm \mu g}\)	\(10^{-6}\)
`mg`	\({\rm mg}\)	\(10^{-3}\)
`g`	\({\rm g}\)	\(1\)
`kg`	\({\rm kg}\)	\(10^{3}\)
`t`	\({\rm t}\)	\(10^{6}\)
`Mear`	\(M_{\oplus}\)	\(5.972\times10^{27}\)
`Msun`	\(M_{\odot}\)	\(1.988\times10^{33}\)

Plotting functions

ulula.core.plots.plot1d(sim, q_plot=['DN', 'VX', 'VY', 'PR'], plot_unit_l='code', plot_unit_t='code', plot_unit_m='code', plot_ghost_cells=False, range_func=None, true_solution_func=None, plot_geometry='line', invert_direction=False, radial_bins_per_cell=4.0)

Plot fluid state along a 1D line

Create a multi-panel plot of the fluid variables along a line through the domain. This plotting routine is intended for pseudo-1D simulations, where the fluid state is uniform in the second dimension. The line is taken at the center of the domain in that dimension. The plot is created but not shown or saved to a file; these operations can be completed using the current matplotlib figure.

Parameters:

q_plot: array_like: List of quantities to plot. Quantities are identified via the short strings given in the fields dictionary.
plot_unit_l: str: Length unit to be plotted (see units for valid units). If other than code, plot_unit_t and plot_unit_m must also be changed from code units.
plot_unit_t: str: Time unit to be plotted (see units for valid units). If other than code, plot_unit_l and plot_unit_m must also be changed from code units.
plot_unit_m: str: Mass unit to be plotted (see units for valid units). If other than code, plot_unit_l and plot_unit_t must also be changed from code units.
plot_ghost_cells: bool: If True, ghost cells are plotted and separated from the physical domain by a gray vertical line. This option is useful for debugging. Ignored if plot_geometry == 'radius'.
range_func: function: If None, the plotting ranges are chosen automatically. Otherwise this parameter must be a function that can be called with the signature range_func(sim, q_plot, plot_geometry) and that returns three lists with the same lengths as the number of plot quantities. The lists give the minimum and maximum plot extents for each fluid variable, as well as whether to use a log scale (True). Elements in the lists can be None in which case ranges are chosen automatically.
true_solution_func: function: If None, no true solution is plotted. Otherwise must be a function that can be called with the signature true_solution_func(sim, x_plot, q_plot, plot_geometry), where x_plot is an array of x-bins. The function must return a list with one element for each of the quantities in q_plot. If an element is None, no solution is plotted. Otherwise the element must be an array with the same dimensions as x_plot. The true solution must be in code units, which are automatically converted if the user has chosen different units for plotting. The true solution function is typically implemented within a problem setup (see Problem setups).
plot_geometry: str: The type of cut through the domain that is plotted. Can be line (in which case the idir parameter specifies the dimension along which the plot is made), or radius (which creates a radially averaged plot from the center).
invert_direction: bool: By default, the plotted line is along the dimension (x or y) that has more cells, and along x if they have the same number of cells. If True, this parameter inverts the direction.
radial_bins_per_cell: float: If plot_geometry == radius, this parameter chooses how many radial bins per cell are plotted. The bins are averaged onto the radial annuli, so this number can be greater than one.

Returns:

fig: matplotlib figure: The figure object.
panels: array_like: List of axes objects.

ulula.core.plots.plot2d(sim, q_plot=['DN', 'VX', 'VY', 'PR'], plot_unit_l='code', plot_unit_t='code', plot_unit_m='code', plot_ghost_cells=False, range_func=None, cmap_func=None, panel_size=3.0)

Plot fluid state in 2D

Create a multi-panel plot of the fluid variables in 2D. The plot is created but not shown or saved to a file; these operations can be completed using the current matplotlib figure.

Parameters:

q_plot: array_like: List of quantities to plot. Quantities are identified via the short strings given in the fields dictionary.
plot_unit_l: str: Length unit to be plotted (see units for valid units). If other than code, plot_unit_t and plot_unit_m must also be changed from code units.
plot_unit_t: str: Time unit to be plotted (see units for valid units). If other than code, plot_unit_l and plot_unit_m must also be changed from code units.
plot_unit_m: str: Mass unit to be plotted (see units for valid units). If other than code, plot_unit_l and plot_unit_t must also be changed from code units.
plot_ghost_cells: bool: If True, ghost cells are plotted and separated from the physical domain by a gray frame. This option is useful for debugging.
range_func: function: If None, the plotting ranges are chosen automatically. Otherwise this parameter must be a function that can be called with the signature range_func(sim, q_plot, plot_geometry) and that returns three lists with the same lengths as the number of plot quantities. The lists give the minimum and maximum plot extents for each fluid variable, as well as whether to use a log scale (True). Elements in the lists can be None in which case ranges are chosen automatically.
cmap_func: function: A function that returns a list of size nq with colormap objects to be used when plotting the fluid variables. If None, the default colormap is used for all fluid variables.
panel_size: float: Size of each plotted panel in inches

Returns:

fig: matplotlib figure: The figure object.
panels: array_like: List of axes objects.

Helper functions

If you wish to create an entirely different plot without using the functions above, the following helper function might be helpful.

ulula.core.plots.getPlotQuantities(sim, q_plot, unit_l='code', unit_t='code', unit_m='code')

Compile an array of fluid properties

Fluid properties are stored in separate arrays as primitive and conserved variables, or even in other arrays. Some quantities, such as total velocity, need to be calculated after the simulation has finished. This function takes care of all related operations and returns a single array that has the same dimensions as the domain.

Moreover, the function computes unit conversion factors if necessary and creates the corresponding labels. One quantity that demands special treatment is temperature, since it cannot sensibly be plotted in code units, or any other units than Kelvin. So we always convert to Kelvin, even if code units are used.

Parameters:

sim: Simulation: Object of type Simulation
q_plot: array_like: List of quantities to plot. Quantities are identified via the short strings given in the fields dictionary.
unit_l: str: Length unit to be plotted (see units for valid units). If other than code, unit_t and unit_m must also be changed from code units.
unit_t: str: Time unit to be plotted (see units for valid units). If other than code, unit_l and unit_m must also be changed from code units.
unit_m: str: Mass unit to be plotted (see units for valid units). If other than code, unit_l and unit_t must also be changed from code units.

Returns:

q_array: array_like: Array of fluid properties
conv_factors: array_like: Unit conversion factors. The return q_array has already been multiplied by these factors in order to bring it into the desired unit system, but some other parts of the plot routines (e.g., color map limits) may also depend on these factors. If the plotting happens in code units, all factors are unity.
q_labels: array_like: List of labels for the fluid quantities
conv_l: float: Unit conversion factor for length, which must be applied to the dimensions of any plot.
label_l: float: Unit label for lengths.