Hydro problem setups

This page describes Ulula’s general system for setting up hydro problems, as well as some specific setups that describe classical hydro problems.

Overview

The Setup class contains two methods that must be implemented by each subclass: providing a name for the problem and setting initial conditions. All other routines can optionally be overwritten. Some of those routines are passed to the Ulula plotting functions when using the run() function. In addition to the general superclass, the following specific setups are implemented:

SetupAdvect()

Tophat advection test

SetupKelvinHelmholtz([sharp_ics, n_waves])

Kelvin-Helmholtz instability

SetupSedov([E, rho0, gamma])

Sedov-Taylor explosion

SetupSod()

Superclass for a shocktube problem in one dimension

SetupSodX()

Sod shocktube problem along the x-direction

SetupSodY()

Sod shocktube problem along the y-direction.

General setup class

class ulula.setup_base.Setup

General setup class

This abstract container must be partially overwritten by child classes, but also contains defaults for many standard routines.

Methods

direction(self)

Return the direction of the problem (1D only)

initialConditions(self, sim, nx)

Wrapper function to set initial data

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup
abstract shortName(self)

Short name for the problem (to be used in output filenames)

initialConditions(self, sim, nx)

Wrapper function to set initial data

This function calls the problem-specific setup, which is assumed to set the primitive variables. Those are also converted to conserved variables.

Parameters
sim: Simulation

Simulation object in which the ICs are to be set

nx: int

Number of cells in the x-direction

abstract setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

Parameters
sim: Simulation

Simulation object in which the ICs are to be set

nx: int

Number of cells in the x-direction

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup

This function can be passed to the Ulula 1D plotting routine plot1d(). It must return a 2D array, with the solution in primitive variables for a given input vector of coordinates.

Parameters
sim: Simulation

Simulation object

x: array_like

The coordinates where the true solution is to be computed.

q_plot: array_like

List of quantities for which to return the true solution. Quantities are identified via the short strings given in the fields dictionary.

Returns
solution: array_like

A 2D array with dimensions (len(q_plot), len(x))

direction(self)

Return the direction of the problem (1D only)

1D problems can be set up along the x or y direction. If the former, this function should return 0, and 1 if the latter.

Returns
idir: int

Either 0 or 1, indicating x or y

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

This function can be passed to the Ulula plotting routines. By default, no limits are returned, which means the plotting functions automatically select limits.

Parameters
q_plot: array_like

List of quantities for which to return the plot limits. Quantities are identified via the short strings given in the fields dictionary.

Returns
limits_lower: array_like

List of lower limits for the given plot quantities. If None, a limit is chosen automatically. Individual items can also be None.

limits_upper: array_like

List of upper limits for the given plot quantities. If None, a limit is chosen automatically. Individual items can also be None.

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

This function can be passed to the Ulula plotting routines. By default, velocities are plotted with a divergent colormap, whereas density and pressure are plotted with a perceptually uniform colormap.

Parameters
q_plot: array_like

List of quantities for which to return the colormaps. Quantities are identified via the short strings given in the fields dictionary.

Returns
cmaps: array_like

List of colormaps for the given quantities. If None, a colormap is chosen automatically. Individual items can also be None.

Setup: Advection tests

The following image shows the results of the advection test for four combinations of hydro solvers. This test can be run with the function given in the runtime examples (see Running Ulula).

_images/setup_advect.png

The initially spherical and perfectly sharp circle with higher density is advected through the box on a diagonal trajectory. When using no spatial reconstruction (top left), the scheme is extremely diffusive (and 1st order in space and time). When using linear reconstruction with the MinMod limiter but still a 1st-order in time Euler integrator (top right), the results are better but still pretty diffusive. When using a less diffusive slope limiter (MC, bottom left), the scheme is unstable and explodes. Using the MUSCL-Hancock 2nd-order scheme (bottom right) leads to a stable and much less diffusive solution.

class ulula.setups.advection.SetupAdvect

Tophat advection test

In this test, an initially overdense tophat is placed at the center of the domain. The entire fluid moves towards the northeast direction. This test is the 2D equivalent of tophat advection in 1D and mostly tests how diffusive a hydro solver is.

Methods

direction(self)

Return the direction of the problem (1D only)

initialConditions(self, sim, nx)

Wrapper function to set initial data

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup
shortName(self)

Short name for the problem (to be used in output filenames)

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

Parameters
sim: Simulation

Simulation object in which the ICs are to be set

nx: int

Number of cells in the x-direction

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

This function can be passed to the Ulula plotting routines. By default, no limits are returned, which means the plotting functions automatically select limits.

Parameters
q_plot: array_like

List of quantities for which to return the plot limits. Quantities are identified via the short strings given in the fields dictionary.

Returns
limits_lower: array_like

List of lower limits for the given plot quantities. If None, a limit is chosen automatically. Individual items can also be None.

limits_upper: array_like

List of upper limits for the given plot quantities. If None, a limit is chosen automatically. Individual items can also be None.

Setup: Kelvin-Helmholtz instability

The following images show the evolution of the standard Kelvin-Helmholtz setup implemented in the class below.

_images/setup_kh.png

This test can be run in less than a minute (see, e.g., the example function in Running Ulula).

class ulula.setups.kelvin_helmholtz.SetupKelvinHelmholtz(sharp_ics=False, n_waves=1)

Kelvin-Helmholtz instability

The KH instability forms at the interface between two fluids that are moving past each other. The user can choose between a setup where the interface is infinitely sharp and the smooth ICs of Robertson et al. 2010. In the sharp case, the instability is seeded by grid noise, but we still add a small velocity perturbation to obtain more well-defined behavior. The smooth version is recommended as it leads to a more physical test case.

Parameters
sharp_ics: bool

Use sharp boundary between fluids instead of smoothed ICs.

n_waves: int

Number of wave periods in the domain. The number of periods that can be resolved depends on the resolution.

Methods

direction(self)

Return the direction of the problem (1D only)

initialConditions(self, sim, nx)

Wrapper function to set initial data

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup
shortName(self)

Short name for the problem (to be used in output filenames)

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

Parameters
sim: Simulation

Simulation object in which the ICs are to be set

nx: int

Number of cells in the x-direction

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

This function can be passed to the Ulula plotting routines. By default, no limits are returned, which means the plotting functions automatically select limits.

Parameters
q_plot: array_like

List of quantities for which to return the plot limits. Quantities are identified via the short strings given in the fields dictionary.

Returns
limits_lower: array_like

List of lower limits for the given plot quantities. If None, a limit is chosen automatically. Individual items can also be None.

limits_upper: array_like

List of upper limits for the given plot quantities. If None, a limit is chosen automatically. Individual items can also be None.

Setup: Sedov-Taylor explosion

The following image shows the Sedov-Taylor test when the blastwave is about to reach the edge of the box:

_images/setup_sedov.png

Ulula can also plot the results binned in radial annuli:

_images/setup_sedov_1d.png

The analytical solution is part of the setup class below.

class ulula.setups.sedov_taylor.SetupSedov(E=50.0, rho0=1.0, gamma=1.6666666666666667)

Sedov-Taylor explosion

The Sedov-Taylor solution represents a blastwave created by a large amount of energy that is injected at the center of the domain. If the energy is much larger than the thermal energy of the surrounding gas, the solution is self-similar, i.e., does not depend on any physical scale and evolves in time as a power-law.

In this setup, the energy is distributed in a Gaussian with a radius of ~1 cell. This avoids grid artifacts that can arise to the square nature of the grid cells. The exact solution code is adapted from the Gandalf code by Hubber et al.

Parameters
E: float

Explosion energy in code units; the thermal energy in the domain is about unity in these units, so E should be significantly larger than unity

rho0: float

The density of the surrounding medium in code units

gamma: float

The adiabatic index of the gas

Methods

direction(self)

Return the direction of the problem (1D only)

initialConditions(self, sim, nx)

Wrapper function to set initial data

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup
shortName(self)

Short name for the problem (to be used in output filenames)

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

Parameters
sim: Simulation

Simulation object in which the ICs are to be set

nx: int

Number of cells in the x-direction

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup

This function can be passed to the Ulula 1D plotting routine plot1d(). It must return a 2D array, with the solution in primitive variables for a given input vector of coordinates.

Parameters
sim: Simulation

Simulation object

x: array_like

The coordinates where the true solution is to be computed.

q_plot: array_like

List of quantities for which to return the true solution. Quantities are identified via the short strings given in the fields dictionary.

Returns
solution: array_like

A 2D array with dimensions (len(q_plot), len(x))

Setup: Shocktube tests

The image below shows the result of the shocktube test for a domain with 100 cells:

_images/setup_sod.png

The shocktube setup is implemented as a general class and child versions that elongate the 2D domain in the x and y directions. Both must give the same result, which tests that the solver does not unphysically prefer one direction.

class ulula.setups.shocktube.SetupSod

Superclass for a shocktube problem in one dimension

The Sod (1978) shocktube problem is a class test for Riemann solvers. A sharp break in fluid properties at the center of a 1D domain causes a shock, contact discontinuity, and rarefaction wave. The problem can be solved analytically. The solution used here was taken from Frank van den Bosch’s and Susanne Hoefner’s lecture notes.

This class is meant as a superclass because it does not decide which direction (x or y) to use. This is done in subclasses, which can be used to test whether the code behaves the same in both directions.

Methods

direction(self)

Return the direction of the problem (1D only)

initialConditions(self, sim, nx)

Wrapper function to set initial data

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, idir, x, q_plot)

Return a true solution for this setup
shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, idir, x, q_plot)

Return a true solution for this setup

This function can be passed to the Ulula 1D plotting routine plot1d(). It must return a 2D array, with the solution in primitive variables for a given input vector of coordinates.

Parameters
sim: Simulation

Simulation object

x: array_like

The coordinates where the true solution is to be computed.

q_plot: array_like

List of quantities for which to return the true solution. Quantities are identified via the short strings given in the fields dictionary.

Returns
solution: array_like

A 2D array with dimensions (len(q_plot), len(x))

class ulula.setups.shocktube.SetupSodX

Sod shocktube problem along the x-direction

See the SetupSod class for documentation of this test.

Methods

direction(self)

Return the direction of the problem (1D only)

initialConditions(self, sim, nx)

Wrapper function to set initial data

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup
shortName(self)

Short name for the problem (to be used in output filenames)

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

Parameters
sim: Simulation

Simulation object in which the ICs are to be set

nx: int

Number of cells in the x-direction

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup

This function can be passed to the Ulula 1D plotting routine plot1d(). It must return a 2D array, with the solution in primitive variables for a given input vector of coordinates.

Parameters
sim: Simulation

Simulation object

x: array_like

The coordinates where the true solution is to be computed.

q_plot: array_like

List of quantities for which to return the true solution. Quantities are identified via the short strings given in the fields dictionary.

Returns
solution: array_like

A 2D array with dimensions (len(q_plot), len(x))

direction(self)

Return the direction of the problem (1D only)

1D problems can be set up along the x or y direction. If the former, this function should return 0, and 1 if the latter.

Returns
idir: int

Either 0 or 1, indicating x or y

class ulula.setups.shocktube.SetupSodY

Sod shocktube problem along the y-direction.

See the SetupSod class for documentation of this test.

Methods

direction(self)

Return the direction of the problem (1D only)

initialConditions(self, sim, nx)

Wrapper function to set initial data

plotColorMaps(self, q_plot)

Return colormaps for plotted quantities

plotLimits(self, q_plot)

Return min/max limits for plotted quantities

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

shortName(self)

Short name for the problem (to be used in output filenames)

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup
shortName(self)

Short name for the problem (to be used in output filenames)

setInitialData(self, sim, nx)

Set the initial conditions (must be overwritten)

Parameters
sim: Simulation

Simulation object in which the ICs are to be set

nx: int

Number of cells in the x-direction

trueSolution(self, sim, x, q_plot)

Return a true solution for this setup

This function can be passed to the Ulula 1D plotting routine plot1d(). It must return a 2D array, with the solution in primitive variables for a given input vector of coordinates.

Parameters
sim: Simulation

Simulation object

x: array_like

The coordinates where the true solution is to be computed.

q_plot: array_like

List of quantities for which to return the true solution. Quantities are identified via the short strings given in the fields dictionary.

Returns
solution: array_like

A 2D array with dimensions (len(q_plot), len(x))

direction(self)

Return the direction of the problem (1D only)

1D problems can be set up along the x or y direction. If the former, this function should return 0, and 1 if the latter.

Returns
idir: int

Either 0 or 1, indicating x or y