Specifying classic runtime parameters in setrun.py¶
It may be useful to look at a specific example, e.g. Sample setrun.py module for classic Clawpack.
Note: Many parameters have changed name since Version 4.X and some new ones have been added. See Changes to input parameters in setrun.py from 4.x to 5.0 for a summary.
To convert a Version 4.x setrun.py file to Version 5.0, see Converting from Clawpack 4.6 to 5.0.
Input¶
setrun takes a single argument claw_pkg that should be set to classic.
Output¶
rundata, an object of class ClawRunData, created in the setrun file with the commands:
from clawpack.clawutil import clawdata
rundata = clawdata.ClawRunData(claw_pkg, num_dim)
The rundata object has an attribute rundata.clawdata whose attributes are described below.
This section explains the parameters needed for the classic singlegrid Clawpack code. Additional parameters are needed by extensions of the code. For these, see:
AMRClaw (adaptive mesh refinement): Specifying AMRClaw runtime parameters in setrun.py
GeoClaw (geophysical flows): Specifying GeoClaw parameters in setrun.py
Runtime parameters¶
The parameters needed in 1 space dimension (ndim=1) are described. In 2d and 3d there are analogous parameters in y and z required, as mentioned below.

num_dim : integer from [1,2,3]
number of space dimensions.

lower : list of floats
lower limits in the x, [y,z] directions.

upper : list of floats
upper limits in the x, [y ,z] directions.

num_cells : list of integers
The number of grid cells in the x, [y, ,z] directions.
Note that when AMR is used, num_cells determines the number of cells in each dimension on the coarsest Level 1 grid. Additional parameters described below determine refinement ratios to finer levels.

num_eqn : integer
Number of equations in the system (e.g. num_eqn=1 for a scalar problem).

num_aux : integer
Number of auxiliary variables in the aux array (initialized in setaux.f)

capa_index : integer
Index of aux array corresponding to capacity function, if there is one.

t0 : float
Initial time, often t0 = 0.

restart : boolean
Currently only available in amrclaw and geoclaw.
Set True to restart a previous computation. To use this option, see Checkpointing and restarting. Note that a change in the Makefile is also required.

restart_file : str
If restart == True then this should be the name of the checkpoint file containing all the information needed to do a restart. This will generally be of the form fort.chkNNNNN where NNNNN is the (coarse grid) timestep from the previous computation to restart from. This file is assumed to be in the directory specified for output from this run. See Checkpointing and restarting for more details.

output_style: integer
There are three possible ways to specify the output times. This parameter selects the desired manner to specify the times, and affects what other attributes are required.
output_style = 1 : Output at fixed time intervals.
Requires additional parameters:
num_output_times : integer, number of output times
tfinal : float, final time
output_t0 : boolean, whether to also output at initial time t0.
The time steps will be adjusted to hit these times exactly. (Provided dt_variable = True. Otherwise dt_initial must divide tfinal/num_output_times an integer number of times.)
output_style = 2 : Output at specified times.
Requires the additional parameter:
output_times : list of floats, times to output (include t0 explicitly if desired)
output_style = 3 : Output every so many steps. Most often used for debugging, e.g to output every time step.
Requires additional parameters:
output_step_interval : integer, number of steps between outputs
total_steps : integer, total number of steps to take
output_t0 : boolean, whether to also output at initial time t0.

output_format: str
Format of output. Currently the following are supported in amrclaw and geoclaw (only ‘ascii’ in classic):
‘ascii’ : the files fort.q0000 etc. are ASCII files,
‘binary64’ : Raw binary dump of full float64 (kind=8) values,
‘binary32’ : Raw binary dump of float32 (kind=4) truncated values. This is almost always sufficient precision for plotting or postprocessing purposes, and results in files that are half as large as ‘binary64’.

output_q_components: list of booleans or str
A list such as [1,0,1] would indicate to output q[0] and q[2] only. This might not be working yet.
The string ‘all’ indicates that all components should be output
The string ‘none’ indicates that no components should be output

output_aux_components: list of booleans or str
A list such as [1,0,1] would indicate to output aux[0] and aux[2] only. This might not be working yet.
The string ‘all’ indicates that all components should be output
The string ‘none’ indicates that no components should be output

output_aux_onlyonce: boolean
If output_aux_components is not ‘none’ or an empty list, this indicates whether aux arrays should be only output at time t0 or at every output time. The latter is generally necessary for AMR applications unless the grids never change (and the component of aux are never modified except in setaux).

verbosity: integer >= 0
A line of output (reporting t, dt and CFL number) is written to the terminal every time step, but only at Level verbosity or coarser.
Set to 0 to suppress all such output.

dt_initial: float >= 0.
Initial time step to try in first step. If using dt_variable == True and are unsure of an appropriate timestep, set to a very small value (e.g. 1.e10). After the first step the wave speeds observed in all Riemann solutions will be used to set the time step appropriately for the next step.

dt_variable: boolean
If True, time steps are adjusted automatically based on the desired Courant number cfl_desired.
If False, fixed time steps of lenght dt_initial are used.

dt_max: float >= 0.
If dt_variable = True then this is an upper bound on the allowable time step regardless of the Courant number. Useful if there are other reasons to limit the time step (e.g. stiff source terms).

cfl_desired: float >= 0.
If dt_variable = True then this is the desired Courant number. Time steps will be adjusted based on the maximum wave speed seen in the last time step taken. For a nonlinear problem this may not result in the Courant number being exactly the desired value in the next step.
Usually cfl_desired = 0.9 or less.

cfl_max: float
If dt_variable = True then this is the maximum Courant number that can be allowed. If a time step results in a Courant number that is greater than cfl_desired but less than or equal to cfl_max, the step is accepted. If the Courant number is greater than cfl_max then the step is rejected and a smaller step is taken. (At this point the maximum wave speed from Riemann solutions is known, so the step can be adjusted to exactly hit the desired value cfl_desired.)
Note: With AMRClaw it is impossible to retake a step and so if cfl > cfl_max then a warning message is printed and the computation continues. Note that results may be contaminated if the Courant number is much above 1. This means that with AMR it is important to choose an appropriate time step dt_initial for the first time step, or use a very small value.
Usually cfl_max = 1.0 is fine, e.g. 500000.

steps_max: int
Maximum number of time steps allowed between output times. This is just to avoid infinite loops and generally a large value is fine.

order : int
order == 1 : Use Godunov’s method
order == 2 : Use second order corrections with limiters in normal direction.

dimensional_split : str
dimensional_split == ‘unsplit’ is the only option currently allowed for AMRClaw.

transverse_waves : int or str
transverse_waves == 0 or ‘none’ : No transverse correction terms (Donor cell upwind if also order == 1).
transverse_waves == 1 or ‘increment’ : Only the increment waves are transmitted transversely. (Corner transport upwind if also order == 1, should be second order accurate if order == 2).
transverse_waves == 2 or ‘all’ : Corner tranpsort of second order corrections as well. (Somewhat improved stability.)

num_waves : int
Number of waves the Riemann solver returns.

limiter : list of int or str, of length num_waves
Each element of the list can take the values:
0 or ‘none’ : no limiter (LaxWendroff)
1 or ‘minmod’ : minmod
2 or ‘superbee’ : superbee
3 or ‘mc’ : monotonized central (MC) limiter
4 or ‘vanleer’ : van Leer
See Chapter 6 of [LeVequeFVMHP] for details.

use_fwaves : boolean
If True, the Riemann solvers should return fwaves (a decomposition of the the flux difference) rather than the usual waves (which give a decomposition of the jump in Q between adjacent states). See fwave formulation, fwave Riemann solvers and Section 16.4 of [LeVequeFVMHP] or [BaleLevMitRoss02] for details.

source_split : list of int or str, of length num_waves
Determines form of fractional step algorithm used to apply source terms (if any). Source terms must be implemented by providing a subroutine srcN.f (in N space dimensions) that is called each time step and should advance the solution by solving the source term equations (the PDE after dropping the hyperolic terms). See Using src for source terms.
src_split == 0 or ‘none’ : no source term (srcN routine never called)
src_split == 1 or ‘godunov’ : Godunov (1st order) splitting used,
src_split == 2 or ‘strang’ : Strang (2nd order) splitting used.
The Strang splitting requires calling the source term routine twice each time step (before and after the hyperbolic step, with half the time step) and is generally not recommended. It is often no more accurate thn the Godunov splitting, requires more work, and can make it harder to properly set ghost cells for boundary conditions.

num_ghost : int
number of ghost cells at each boundary. Should be at least 1 if order == 1 and at least 2 if order == 2.

bc_lower : list of int or str, of length num_ghost
Choice of boundary conditions at the lower boundary in each dimension. Each element can take the following values:
0 or ‘user’ : user specified (must modify bcNamr.f to use this option)
1 or ‘extrap’ : extrapolation (nonreflecting outflow)
2 or ‘periodic’ : periodic (must specify this at both boundaries)
3 or ‘wall’ : solid wall for systems where q(2) is normal velocity
If the value is 0 or ‘user’, then the user must modify the boundary condition routine bcNamr.f to fill ghost cells in the desired manner. See Boundary conditions for more details.

bc_upper : list of int or str, of length num_ghost
Choice of boundary conditions at the upper boundary in each dimension. The same choices are available as for bc_lower.
Note that if periodic boundary conditions are specified at the lower boundary in some dimension then the same should be specified at the upper.

checkpt_style :: int
Currently only available in amrclaw and geoclaw.
Specify how often checkpoint files should be created that can be used to restart a computation. See Checkpointing and restarting for more details.
checkpt_style = 0 : Do not checkpoint at all
checkpt_style = 1 : Checkpoint only at the final time.
checkpt_style = 2 : Specify a list of checkpoint times.
This is generally not recommended because time steps will be adjusted to hit the checkpoint times, but may be useful in order to create a checkpoint file just before some event of interest (e.g. when debugging a code that is known to crash at a certain time).
Requires additional parameter:
checkpt_times : list of floats
checkpt_style = 3 : Specify an interval for checkpointing.
Requires additional parameter:
checkpt_interval : int
Checkpoint every checkpt_interval time steps on Level 1 (coarsest level).