Running Ulula

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

Quick start

The easiest way to execute Ulula is via the runtime function run() (see documentation 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 test:

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 test 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 interactive and saved figures as well as 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.

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 takes a given problem setup and other user-defined parameters and executes the hydro solver. Depending on user choices, it can also 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 sets the algorithm and CFL number for the simulation. 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. The setup is ignored.

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.

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, step 0 (only active if plot_step == True)

plot_1d: bool

If True, the 1D plotting routine is called at the specific time or step intervals. This parameter is ignored for 1D simulations.

plot_2d: bool

If True, the 2D plotting routine is called at the specific 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 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 (only active if save_plots == True and plot_file_ext == png or other bitmap-like image formats).

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 it accepts as parameters a simulation object, a matplotlib figure, a list of matplotlib axes objects, and a string that can 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 a frame 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

File extension for movie, 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)

movie_dpi: int

Resolution of the png files used to create the movie (see plot_dpi)

kwargs: kwargs

Additional keyword arguments that are passed to the Ulula plotting functions plot1d() or plot2d(). Keyword arguments must appear in either function signature.

Returns:

sim: Simulation

Object of type Simulation

Examples

The following code samples are 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
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

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

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