Running Ulula

This page shows how Ulula can be run with a few lines of code and describes a number of pre-implemented example problems.

Quick start

The easiest way to execute Ulula is via the runtime function run(), which is documented below. The main input to this function is a Setup, a class that contains all data and routines that describe a particular physical problem. The following example runs a simulation of the Kelvin-Helmholtz instability:

import ulula.setups.kelvin_helmholtz as setup_kh
import ulula.core.run as ulula_run

setup = setup_kh.SetupKelvinHelmholtz()
ulula_run.run(setup, tmax = 4.0, nx = 200)

This code will set up a domain with 200x200 cells and run the Kelvin-Helmholtz problem until time 4.0 using the default hydro solver. If you want control over the algorithms used, the HydroScheme class contains all relevant settings, e.g.:

import ulula.core.simulation as ulula_sim

hs = ulula_sim.HydroScheme(reconstruction = 'linear', limiter = 'mc', cfl = 0.9)
ulula_run.run(setup, hydro_scheme = hs, tmax = 4.0, nx = 200)

The run() function takes a number of additional parameters, many of which govern various possible output products such as figures and movies. For example, these code snippets would produce a series of density and pressure plots at time intervals of 0.5 or a movie of the evolution of density:

ulula_run.run(setup, tmax = 4.0, nx = 200, plot_time = 0.5, q_plot = ['DN', 'PR'])
ulula_run.run(setup, tmax = 4.0, nx = 200, movie = True, q_plot = ['DN'])

Internally, the run() function creates and handles an Ulula Simulation object (see the Simulation framework page for more details). This simulation object can be saved to hdf5 files, either after regular time intervals or numbers of snapshots:

ulula_run.run(setup, tmax = 4.0, nx = 200, output_time = 0.5)
ulula_run.run(setup, tmax = 4.0, nx = 200, output_step = 100)

Note that the various outputs (plot_time, plot_step, output_time, output_step, and movie) can be used concurrently. Alternatively, the runtime function returns a simulation object, which can be saved manually:

sim = ulula_run.run(setup, tmax = 2.0, nx = 200)
sim.save(filename = 'my_file.hdf5')

Ulula files are both snapshots and restart files. For example, we can recreate a simulation object from a file and run it to a later time:

ulula_run.run(setup, restart_file = 'my_file.hdf5', tmax = 4.0)

In this case, the data from the restart file overwrite all other input to the runtime function. While the run() function has plenty of options to create plots during a simulation run, we can also load a file and plot it. Note that the plot functions create a plot but do not save or show it:

import matplotlib.pyplot as plt
import ulula.core.plots as ulula_plots

sim = ulula_sim.load('my_file.hdf5')
ulula_plots.plot2d(sim, q_plot = ['DN', 'PR'])
plt.show()

For more information on the plotting routines and plottable fluid quantities, see Plotting & Analysis.

Runtime function

ulula.core.run.run(setup, hydro_scheme=None, nx=200, tmax=1.0, max_steps=None, restart_file=None, print_step=100, check_conservation=True, output_step=None, output_time=None, output_suffix='', plot_step=None, plot_time=None, plot_ics=True, plot_1d=False, plot_2d=True, save_plots=True, plot_suffix='', plot_file_ext='pdf', plot_dpi=300, plot_callback_func=None, movie=False, movie_1d=False, movie_length=4.0, movie_file_ext='mp4', movie_fps=25, movie_dpi=200, **kwargs)

Runtime environment for Ulula.

This function executes the hydro solver for a given problem setup and user-defined parameters. Depending on user choices, it produces output files, plots, and movies. Customizations that are implemented in the setup class (e.g., which variables to plot with which colormaps) are automatically routed to the respective plotting routines.

Parameters:

setup: Setup: Setup object. See Problem setups for how to create this object.
hydro_scheme: HydroScheme: HydroScheme object that contains choices for the hydro solver, the CFL number, and so on. If None, the standard scheme is used. See Simulation framework for details.
nx: int: Number of cells in the x-direction. The ratio of x and y is determined by the problem setup.
tmax: float: Time when the simulation should be stopped (in code units).
max_steps: int: Maximum number of steps to take. If None, no limit is imposed and the code is run to a time tmax.
restart_file: str: If not None, the simulation is loaded from this filename and restarted at the step where it was saved.
print_step: int: Print a line to the console every print_step timesteps.
check_conservation: bool: If True, we compute the total mass, energy and so on each print_step timesteps and compare it to the initial energy. Note that the conserved quantities depend on the boundary conditions of the simulation setup: mass, energy and momentum are conserved in periodic BCs, only mass and energy in wall BCs, and nothing is conserved in outflow BCs. Similarly, gravity can break the conservation laws.
output_step: int: Output a snapshot/restart file every output_step timesteps. Note that this spacing probably does not correspond to fixed times. If the latter is desired, use output_time. Both output_step and output_time can be used at the same time to produce two sets of files.
output_time: float: Produce output files in time intervals of size output_time (given in code units). This parameter should not change the progression of the simulation because the timesteps taken to arrive at the desired times are not used for the actual simulation.
output_suffix: string: String to add to all output filenames.
plot_step: int: Produce a plot every plot_step timesteps. Note that this spacing probably does not correspond to fixed times. If the latter is desired, use plot_time. Both plot_step and plot_time can be used at the same time to produce two sets of plots.
plot_time: float: Produce plots in time intervals of size plot_time (given in code units). This parameter should not change the progression of the simulation because the timesteps taken to arrive at the desired times are not used for the actual simulation.
plot_ics: bool: Produce a plot of the initial conditions (if plot_step and/or plot_time are set).
plot_1d: bool: If True, the 1D plotting routine is called at the specified time or step intervals. This parameter is ignored for 1D simulations.
plot_2d: bool: If True, the 2D plotting routine is called at the specified time or step intervals. This parameter is ignored for 1D simulations.
save_plots: bool: If True, plots are saved to a file (see also plot_suffix, plot_file_ext, and plot_dpi). If False, plots are shown in an interactive matplotlib window. Note that this can happen many times during a simulation depending on the values of plot_step and/or plot_time.
plot_suffix: string: String to add to all plot filenames (only active if save_plots == True).
plot_file_ext: string: File extension for plots. Can be png, pdf, or any other extension supported by the matplotlib library (only active if save_plots == True).
plot_dpi: Dots per inch for png figures or other bitmap-like image formats (only active if save_plots == True and plot_file_ext == 'png').
plot_callback_func: function: If not None, this must be a function that can be called with the signature plot_callback_func(sim, fig, panels, plot_type), meaning that it accepts as parameters a simulation object, a matplotlib figure, a list of matplotlib axes objects, and a string that may be '1d', '2d', or 'movie' to identify what kind of plot has been created. The function is called after every time a plot is created and before it is saved or shown.
movie: bool: If True, a movie is created by outputting frames at equally spaced times and running a tool to combine them (see movie_file_ext).
movie_1d: bool: If True, the 1D plotting routine is called instead of the 2D plotting routine for a 2D simulation. This parameter is ignored for 1D simulations.
movie_length: float: Length of the movie in seconds (not code units!).
movie_file_ext: str: Movie format, which can be 'mp4' or 'gif'. If 'mp4', the ffmpeg software must be installed to compile image files into a movie. If 'gif', the python package pillow is used. The mp4 format offers much better compression (and thus smaller file size) at fixed quality.
movie_fps: int: Framerate of the movie (25 is typical). The code can output at most one frame per simulation timestep, which should not normally be an issue. A movie with a finer time resolution could be produced by lowering the CFL number to force smaller timesteps and increasing the framerate.
movie_dpi: int: Resolution of the png files used to create the movie.
kwargs: kwargs: Additional keyword arguments that are passed to the Ulula plotting functions plot1d() and/or plot2d(). Keyword arguments must appear in either function signature.

Returns:

sim: Simulation: Object of type Simulation

Examples

The following code samples showcase how to run different problem setups, change hydro solvers, and produce plots and movies. The physical setups are described in detail in Problem setups.

`runAdvection1D`()	Run the 1D advection test setup
`runSoundwave`()	Run the sound wave setup
`runShocktube`()	Run the shock tube setup
`runFreefall`()	Run the freefall setup
`runAtmosphere`()	Run the atmosphere setup
`runJeansInstability`()	Run the Jeans instability setup
`runAdvection2D`()	Run the 2D advection test setup
`runKelvinHelmholtz`([movie])	Run the Kelvin-Helmholtz setup
`runCloudCrushing`()	Run the cloud crushing setup
`runSedovTaylor`()	Run the Sedov-Taylor explosion setup
`runGreshoVortex`()	Run the Gresho vortex setup
`runRayleighTaylor`()	Run the Rayleigh-Taylor setup
`runTidalDisruption`()	Run the tidal disruption setup
`runKeplerianDisk`()	Run the Keplerian disk setup
`runMerger`([movie])	Run the merger disk setup

ulula.examples.examples.runAdvection1D()

Run the 1D advection test setup

We run the advection test with different numerical algorithms. When using Euler (first-order) time integration, the test may be unstable. We use a callback function to add labels to the plots before they are saved.

ulula.examples.examples.runSoundwave(): Run the sound wave setup

ulula.examples.examples.runShocktube()

Run the shock tube setup

The function creates outputs for piecewise-constant states and piecewise-linear reconstruction.

ulula.examples.examples.runFreefall(): Run the freefall setup

ulula.examples.examples.runAtmosphere()

Run the atmosphere setup

In its default mode, this setup uses an isothermal equation of state, which means we cannot use the default HLLC Riemann solver.

ulula.examples.examples.runJeansInstability()

Run the Jeans instability setup

This setup uses an isothermal equation of state, which means we cannot use the default HLLC Riemann solver.

ulula.examples.examples.runAdvection2D()

Run the 2D advection test setup

We run the advection test with different numerical algorithms. When using the MC limiter with an Euler (first-order) time integration, the test fails spectacularly. We use a callback function to add labels to the plots before they are saved.

ulula.examples.examples.runKelvinHelmholtz(movie=False)

Run the Kelvin-Helmholtz setup

This function demonstrates how to make movies with Ulula. By passing the movie parameter, the function outputs frames at a user-defined rate and combines them into a movie at the end of the simulation.

Parameters:

movie: bool: Whether to produce plots or a movie.

ulula.examples.examples.runCloudCrushing(): Run the cloud crushing setup

ulula.examples.examples.runSedovTaylor()

Run the Sedov-Taylor explosion setup

This function demonstrates a style of 1D plotting where the solution is averaged in radial bins.

ulula.examples.examples.runGreshoVortex(): Run the Gresho vortex setup

ulula.examples.examples.runRayleighTaylor(): Run the Rayleigh-Taylor setup

ulula.examples.examples.runTidalDisruption(): Run the tidal disruption setup

ulula.examples.examples.runKeplerianDisk(): Run the Keplerian disk setup

ulula.examples.examples.runMerger(movie=False)

Run the merger disk setup

Parameters:

movie: bool: Whether to produce plots or a movie.