General setup class

class ulula.core.setup_base.Setup(unit_l=1.0, unit_t=1.0, unit_m=1.0)

General setup class

This abstract container class serves as the basis for any problem setup in Ulula. Only two routines must be overwritten, namely those setting a short name and that set the initial conditions (shortName() and setInitialConditions()). However, default implementations for numerous other routines are provided and can be overwritten if desired. For example, some routines determine the style of plots and are automatically passed to the plotting module when using the run() function.

Parameters:

unit_l: float

Code unit for length in units of centimeters.

unit_t: float

Code unit for time in units of seconds.

unit_m: float

Code unit for mass in units of gram.

Methods

hasUserBoundaryConditions()	Check whether setup provides BCs
hasUserUpdateFunction()	Check whether setup provides update function
initialConditions(sim, nx)	Wrapper function for setting initial data
internalEnergyFromTemperature(T, mu, gamma)	Conversion for isothermal EOS
plotColorMaps(q_plot)	Return colormaps for plotted quantities
plotLimits(q_plot, plot_geometry)	Return min/max limits for plotted quantities
setBoundaryConditions(sim)	Set boundary conditions at run-time
setInitialConditions(sim, nx)	Set the initial conditions (must be overwritten)
shortName()	Short identifier for filenames (must be overwritten)
trueSolution(sim, x, q_plot, plot_geometry)	Return a true solution for this setup
updateFunction(sim)	Interact with the simulation at run-time

abstractmethod shortName()

Short identifier for filenames (must be overwritten)

initialConditions(sim, nx)

Wrapper function for setting initial data

This function provides a framework to make setting the initial conditions easier. It calls the user-defined routine to set the ICs in primitive variables, but it also sets code units, checks for erroneous input such as negative densities, initializes gravitational potentials, and converts primitive to conserved variables.

Parameters:

sim: Simulation

Object of type Simulation.

nx: int

Number of cells in the x-direction.

abstractmethod setInitialConditions(sim, nx)

Set the initial conditions (must be overwritten)

In this function, the user sets the initial conditions for the simulation in primitive variables and choose the settings for the simulation such the equation of state, gravity mode, and so on (see Simulation framework). The wrapper function initialConditions() takes care of any other necessary steps.

Parameters:

sim: Simulation

Object of type Simulation.

nx: int

Number of cells in the x-direction.

trueSolution(sim, x, q_plot, plot_geometry)

Return a true solution for this setup

If overwritten, this function is passed to the Ulula 1D plotting routine plot1d(). 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.

Parameters:

sim: Simulation

Object of type Simulation.

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.

plot_geometry: str

If the setup is 2D, the type of cut through the domain that the solution is desired for. Can be 'line' or 'radius' (a radially averaged plot from the center). See the documentation of plot1d() for details.

Returns:

solution: array_like

A list of length len(q_plot), with elements that are either None or an array with the same length as x.

plotLimits(q_plot, plot_geometry)

Return min/max limits for plotted quantities

If overwritten, this function is passed to the Ulula plotting routines. By default, no limits are returned, which means the plotting functions automatically select limits. The limits must be in code units.

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.

plot_geometry: str

For 2D plots, this parameter is '2d'. For 1D plots in a 1D simulation, it is 'line'. If the setup is 2D but a 1D plot is created, this parameter gives the cut through the domain, which can be 'line' or 'radius' (a radially averaged plot from the center). See the documentation of plot1d() for details.

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.

log: array_like

List of True/False values that determine whether to plot the given quantities in log space. If None, all quantities are plotted in linear space. If log is chosen, the limits must be positive.

plotColorMaps(q_plot)

Return colormaps for plotted quantities

If overwritten, this function is passed to the Ulula plotting routines. By default, quantities that can be negative (such as velocities) are displayed with divergent colormaps whereas positive-only quantities such as density are displayed with perceptually uniform colormaps.

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.

updateFunction(sim)

Interact with the simulation at run-time

If this function is overwritten by a child class, it will be executed by the Ulula simulation before boundary conditions are enforced. During that time, the setup can change the fluid variables in the domain.

Note that the simulation does not check whether what this function does makes any sense! If the function implements unphysical behavior, an unphysical simulation will result. The overwriting function can manipulate either primitive or conserved variables and thus must ensure that primitive and conserved variables are consistent after the function call.

Derived classes should not return any values (and must not return False like this base class implementation, because that value is used to determine whether a user function is provided in a given setup).

Parameters:

sim: Simulation

Object of type Simulation.

setBoundaryConditions(sim)

Set boundary conditions at run-time

If this function is overwritten by a child class, it will be executed by the Ulula simulation after the boundary conditions are enforced. During that time, the setup can overwrite the boundary conditions.

Note that the simulation does not check whether what this function does makes any sense! If the function implements unphysical behavior, an unphysical simulation will result. The overwriting function can manipulate either primitive or conserved variables and thus must ensure that primitive and conserved variables are consistent after the function call.

Derived classes should not return any values (and must not return False like this base class implementation, because that value is used to determine whether user BCs are provided in a given setup).

Parameters:

sim: Simulation

Object of type Simulation.

hasUserUpdateFunction()

Check whether setup provides update function

An internal function that determines whether a child class has overwritten updateFunction().

Parameters:

has_user_updates: bool

True if an setup implementation is providing a user-defined update function, False otherwise.

hasUserBoundaryConditions()

Check whether setup provides BCs

An internal function that determines whether a child class has overwritten setBoundaryConditions().

Parameters:

has_user_bcs: bool

True if an setup implementation is providing user-defined BCs, False otherwise.

internalEnergyFromTemperature(T, mu, gamma)

Conversion for isothermal EOS

If you are choosing an isothermal EOS, you need to pass the temperature in the form of an equivalent internal energy in code units, which can be a little tedious to compute. This function takes care of the calculation. The result can be passed as the eint_fixed parameter to the setEquationOfState() function.

Parameters:

T: float

Temperature in Kelvin.

mu: float

Mean particle weight in proton masses.

Returns:

eint: float

Internal energy in code units corresponding to the given temperature.