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.

`plot1d`(sim[, q_plot, plot_unit_l, ...])	Plot fluid state along a 1D line
`plot2d`(sim[, q_plot, plot_unit_l, ...])	Plot fluid state in 2D
`getPlotQuantities`(sim, q_plot[, unit_l, ...])	Compile an array of fluid properties

Plottable quantities

All plotting functions take a q_plot parameter that contains a list of the fluid variables to be plotted. 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
`GP`	Gravitational potential
`GX`	Gravitational potential gradient in x
`GY`	Gravitational potential gradient in x

The fields and their properties are defined in the following dictionary:

ulula.plots.fields = {'DN': {'cmap': 'viridis', 'label': '\\rho', 'name': 'Density'}, 'EI': {'cmap': 'viridis', 'label': '\\epsilon', 'name': 'Internal energy'}, 'ET': {'cmap': 'viridis', 'label': 'E', 'name': 'Energy'}, 'GP': {'cmap': 'viridis', 'label': '\\Phi', 'name': 'Potential'}, 'GX': {'cmap': 'RdBu_r', 'label': '{\\rm d}\\Phi/{\\rm d}x', 'name': 'Pot. gradient'}, 'GY': {'cmap': 'RdBu_r', 'label': '{\\rm d}\\Phi/{\\rm d}y', 'name': 'Pot. gradient'}, 'MX': {'cmap': 'RdBu_r', 'label': 'm_{\\rm x}', 'name': 'X-momentum'}, 'MY': {'cmap': 'RdBu_r', 'label': 'm_{\\rm y}', 'name': 'Y-momentum'}, 'PR': {'cmap': 'viridis', 'label': 'P', 'name': 'Pressure'}, 'VT': {'cmap': 'viridis', 'label': 'v_{\\rm tot}', 'name': 'Total velocity'}, 'VX': {'cmap': 'RdBu_r', 'label': 'v_{\\rm x}', 'name': 'X-velocity'}, 'VY': {'cmap': 'RdBu_r', 'label': 'v_{\\rm y}', 'name': 'Y-velocity'}}: 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).

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 (which is cgs by 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.

Plotting functions

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

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_l 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_t 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_m for valid units). If other than code, plot_unit_l and plot_unit_t must also be changed from code units.
plot_type: 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).
true_solution_func: function: If not None, the given function must return a 2D array with the true solution for the default fluid quantities and for a given input array of coordinates. This function is typically implemented within the problem setup (see Hydro problem setups).
vminmax_func: function: A function that returns two lists of minimum and maximum plot extents for the nq fluid variables, as well as whether to use a log scale. If None, the limits are chosen automatically.
radial_bins_per_cell: float: If plot_type == 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.
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.

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

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_l 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_t 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_m for valid units). If other than code, plot_unit_l and plot_unit_t must also be changed from code units.
vminmax_func: function: A function that returns two lists of minimum and maximum plot extents for the nq fluid variables, as well as whether to use a log scale. If None, the limits 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
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.

Helper functions

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

ulula.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.

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_l 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_t 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_m 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.