.. _setrun:
*****************************************************************
Specifying classic run-time parameters in `setrun.py`
*****************************************************************
It may be useful to look at a specific example, e.g.
:ref:`setrun_sample`.
**Note:** Many parameters have changed name since Version 4.X and some new
ones have been added. See :ref:`setrun_changes` for a summary.
To convert a Version 4.x `setrun.py` file to Version 5.0, see :ref:`claw46to50`.
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:
* AMRClaw (adaptive mesh refinement): :ref:`setrun_amrclaw`
* GeoClaw (geophysical flows): :ref:`setrun_geoclaw`
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.
.. attribute:: num_dim : integer from [1,2,3]
number of space dimensions.
.. attribute:: lower : list of floats
lower limits in the x, [y,z] directions.
.. attribute:: upper : list of floats
upper limits in the x, [y ,z] directions.
.. attribute:: 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.
.. attribute:: num_eqn : integer
Number of equations in the system (e.g. *num_eqn=1* for a scalar problem).
.. attribute:: num_aux : integer
Number of auxiliary variables in the aux array (initialized in `setaux.f`)
.. attribute:: capa_index : integer
Index of aux array corresponding to capacity function, if there is one.
.. attribute:: t0 : float
Initial time, often *t0 = 0.*
.. attribute:: restart : boolean
**Currently only available in amrclaw and geoclaw.**
Set True to restart a previous computation. To use this option,
see :ref:`restart`. Note that a change in the `Makefile` is also
required.
.. attribute:: 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 :ref:`restart` for more details.
.. attribute:: 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`.
.. attribute:: 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??
.. attribute:: 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
.. attribute:: 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
.. attribute:: 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`).
.. attribute:: 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.
.. attribute:: 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.
.. attribute:: 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.
.. attribute:: 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).
.. attribute:: 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.
.. attribute:: 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.
.. attribute:: 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.
.. attribute:: order : int
`order == 1` : Use Godunov's method
`order == 2` : Use second order corrections with limiters in normal
direction.
.. attribute:: dimensional_split : str
`dimensional_split == 'unsplit'` is the only option currently allowed
for AMRClaw.
.. attribute:: 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.)
.. attribute:: num_waves : int
Number of waves the Riemann solver returns.
.. attribute:: 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.
.. attribute:: 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 :ref:`wp_fwave`, :ref:`riemann_fwave` and
Section 16.4 of [LeVeque-FVMHP]_ or [BaleLevMitRoss02]_ for details.
.. attribute:: 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 :ref:`user_src`.
* 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.
.. attribute:: 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`.
.. attribute:: 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 :ref:`bc` for more details.
.. attribute:: 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.
.. attribute:: 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 :ref:`restart` 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).