Plotting & Analysis

Overview

Ulula comes with two plotting routines for 1D and 2D data, plot1d() and plot2d(). Both functions take as parameters a simulation object and a list of quantities to be plotted in the form of a list of strings. Valid identifiers are listed in the fields dictionary below. The functions then create multiple panels, one per fluid quantity. The data are extracted from the simulation object with the helper function getQuantities(), which can also be used separately from the plotting routines to extract derived quantities for analysis (see listing below).

Plottable quantities

The plotting functions take a q_plot parameter that contains a list of the desired quantities to be plotted. Valid fields and their properties are defined in the following dictionary, which includes the primitive and conserved variables (see Simulation framework) as well as some derived quantities:

ulula.core.plots.fields: List of fields that can be extracted from the simulation and/or plotted.

Symbol	Abbr.	Quantity
\(\rho\)	`DN`	Density
\(v_{\rm x}\)	`VX`	X-velocity
\(v_{\rm y}\)	`VY`	Y-velocity
\(v_{\rm tot}\)	`VT`	Total velocity
\(v_{\rm r}\)	`VR`	Radial velocity
\(v_{\rm \phi}\)	`VA`	Azimuthal velocity
\(P\)	`PR`	Pressure
\(m_{\rm x}\)	`MX`	X-momentum density
\(m_{\rm y}\)	`MY`	Y-momentum density
\(E\)	`ET`	Total energy density (internal + kinetic + potentials)
\(\epsilon\)	`EI`	Internal energy per unit mass
\(T\)	`TK`	Temperature (in Kelvin)
\(\Phi\)	`GP`	Gravitational potential
\(\partial \Phi / \partial x\)	`GX`	Gravitational potential gradient in x
\(\partial \Phi / \partial y\)	`GY`	Gravitational potential gradient in y
\(\Phi_{\rm user}\)	`GU`	User-defined fixed potential

The symbols listed above are those used in the plots. The labels can be changed by updating the global fields dictionary before plotting. For example, we use the symbol \(v\) for velocities, but some users might prefer \(u\).

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
`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
`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
`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, vertical=False)

Plot fluid state along a 1D line

This function creates a multi-panel plot of the fluid variables along a 1D domain. For 2D simulations, the plots can show fluid quantities along a line through the center of the domain or a radial average. The plot is created but not shown or saved to a file. These operations can be completed using the returned matplotlib objects. Plots can also be edited before saving via a callback function passed to the run() function.

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.
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 (if True is returned for a given quantity). Elements in the lists can be None in which case ranges are chosen automatically. The range function is typically implemented within a problem setup (see Problem setups).
true_solution_func: function: If None, no true solution is plotted. Otherwise it 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: For 2D simulations, the type of cut through the domain that is plotted. Can be line or radius (which creates a radially averaged plot from the center).
invert_direction: bool: If plot_geometry == 'line', the default is to for the plotted line to be 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 unity.
vertical: bool: If True, panels are stacked vertically instead of being placed next to each other horizontally.

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 returned matplotlib objects. Plots can also be edited before saving via a callback function passed to the run() function.

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.
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, '2d') 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 (if True is returned for a given quantity). Elements in the lists can be None in which case ranges are chosen automatically. The range function is typically implemented within a problem setup (see Problem setups).
cmap_func: function: If None, the default colormaps are used. Otherwise this parameter must be a function that can be called with the signature``cmap_func(q_plot)`` and returns a list of color maps of the same length as the list of plotted quantities. The cmap function is typically implemented within a problem setup (see Problem setups).
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

The plottable fields listed in fields above are extracted from a simulation object using the following generalized function. This function can be used separately from the plotting routines, e.g. to create a different kind of figure or to analyze the data otherwise.

ulula.core.plots.getQuantities(sim, q_list, unit_l='code', unit_t='code', unit_m='code')

Extract fluid properties

The fluid properties in an Ulula simulation are stored in separate arrays as primitive and conserved variables. 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 for plotting. One quantity that demands special treatment is temperature, which cannot sensibly be plotted in code units. Instead we always convert to Kelvin, even if code units are used.

Parameters:

sim: Simulation: Object of type Simulation.
q_list: array_like: List of quantities to extract. Quantities are identified via the short strings given in the fields dictionary.
unit_l: str: Length unit for returned arrays (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 for returned arrays (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 for returned arrays (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. Has dimensions of the number of quantities extracted times the domain.
conv_factors: array_like: Unit conversion factors. The returned q_array has already been multiplied by these factors in order to bring it into the desired unit system, but they may be useful for other parts of the analysis or plotting. If code units are chosen, all factors are unity.
q_labels: array_like: List of latex-formatted 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.