Specifying classic run-time 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 single-grid Clawpack code. Additional parameters are needed by extensions of the code. For these, see:

Run-time 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:

  • ‘ascii’ : the files fort.q0000 etc. are ASCII files.
  • ‘binary’ : Raw binary dump. Working??
  • ‘netcdf’ : NetCDF format. Working??
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.e-10). 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 (Lax-Wendroff)
  • 1 or ‘minmod’ : minmod
  • 2 or ‘superbee’ : superbee
  • 3 or ‘mc’ : monotonized central (MC) limiter
  • 4 or ‘vanleer’ : van Leer

See Chapter 6 of [LeVeque-FVMHP] for details.

use_fwaves : boolean

If True, the Riemann solvers should return f-waves (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 f-wave formulation, f-wave Riemann solvers and Section 16.4 of [LeVeque-FVMHP] 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 (non-reflecting 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).