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

For additional code samples, see the following example tests; they are designed to highlight the differences between hydro solvers and demonstrate a number of plots and movies. The setups are described in detail in Hydro problem setups.

advectionTest()

Test of different solvers in 2D advection problem

shocktubeTest()

1D test of hydro solver with shock tube

kelvinHelmholtzTest()

The Kelvin-Helmholtz instability

kelvinHelmholtzMovie()

Movie of the Kelvin-Helmholtz instability

sedovTest([nx, plot1d])

Test of Sedov-Taylor explosion against analytic solution

Runtime function

ulula.run.run(setup, hydro_scheme=None, nx=200, tmax=1.0, max_steps=None, print_step=100, restart_file=None, output_step=None, output_time=None, output_suffix='', plot_step=None, plot_time=None, plot_ics=True, plot1d=False, save_plots=True, plot_suffix='', plot_file_ext='png', plot_dpi=300, movie=False, movie_length=4.0, 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 Hydro 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.

print_step: int

Print a line to the console every print_step timesteps.

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.

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)

plot1d: bool

If True, the 1D plotting routine is called instead of the usual 2D routine. This is useful only for test setups that are intrinsically 1D such as a shocktube.

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

movie: bool

If True, a movie is created by outputting a frame at equally spaced times and running the ffmpeg tool to combine them (this tool must be installed on the system). See also movie_length, movie_fps, and movie_dpi.

movie_length: float

Length of the movie in seconds (not code units!)

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 arguments that are passed to the Ulula plotting function (either 1D or 2D, depending on the plot1d parameter).

Returns
sim: Simulation

Object of type Simulation

Example problems

Please see the Hydro problem setups page for images of some of the results produced by these example functions.

ulula.examples.examples.advectionTest()

Test of different solvers in 2D advection problem

This function produces four runs of the same top-hat advection problem. An initial overdense disk is moving with the fluid towards the top right of the domain. The edges of the disk diffuse into the surrounding fluid at a rate that depends on the hydro solver. When using the MC limiter with an Euler (first-order) time integration, the test fails entirely.

The large plot_step and plot_ics = False ensure that only the final snapshots are plotted.

ulula.examples.examples.shocktubeTest()

1D test of hydro solver with shock tube

This function executes a shocktube test in pseudo-1D (by creating a domain that is much longer in x than in y, and by making it symmetric in y). The function creates outputs for piecewise- constant states and piecewise-linear reconstruction.

ulula.examples.examples.kelvinHelmholtzTest()

The Kelvin-Helmholtz instability

This function creates an interactive plot of the Kelvin-Helmholtz instability. It should take less than a minute to run on a modern laptop.

ulula.examples.examples.kelvinHelmholtzMovie()

Movie of the Kelvin-Helmholtz instability

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.

ulula.examples.examples.sedovTest(nx=200, plot1d=True)

Test of Sedov-Taylor explosion against analytic solution

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