.. _flag:
**************************************
Flagging cells for adaptive refinement
**************************************
**Describe flagging and clustering algorithms in more detail.**
See :ref:`setrun_amrclaw` for a description of the input parameters that define how
Richardson extrapolation and/or the `flag2refine` subroutine work.
.. _flag_regions:
Refinement regions
------------------
In AMRClaw and GeoClaw it is possible to specify space-time regions in which
refinement to a certain level is forced or a level beyond which refinement if
forbidden. These are specified through the parameter `rundata.regiondata.regions` in
`setrun.py`.
This is a list of lists, each of which specifies a region in the form
`[minlevel,maxlevel,t1,t2,x1,x2,y1,y2]`.
For example, suppose that `amr_levels_max = 6` has been specified along
with these two regions::
rundata.regiondata.regions = []
rundata.regiondata.regions.append([2, 5, 10.0, 30.0, 0.0, 0.5, 0.0, 0.5])
rundata.regiondata.regions.append([3, 4, 20.0, 40.0, 0.2, 1.0, 0.2, 1.0])
The first region specifies that from time 10 to 30 there should be at least 2
levels and at most 5 levels of refinement for points in the spatial domain
`0 < x < 0.5` and `0 < y < 0.5`.
The second region specifies that from time 20 to 40 there should be at least 3
level and at most 4 levels of refinement for points in the spatial domain
`0.2 < x < 1.0` and `0.2 < y < 1.0`.
Note that these regions overlap in both space and time, and in regions of
overlap the *maximum* of the `minlevel` and also the *maximum* of the
`maxlevel` parameters applies. So in the above example, from time 20 to 30
there will be at least 3 levels and at most 5 levels in the region of
overlap, `0.2 < x < 0.5` and `0.2 < y < 0.5`.
Within these regions, how many levels are chosen at each point will be
determined by the *error flagging criteria*, i.e. as
specified by Richardson extrapolation and/or the default or user-supplied
routine `flag2refine`. The parameters for these are described in
:ref:`setrun`.
Points that are not covered by either region are not constrained by the
regions. They might
be refined to any level from 1 to 6 depending on the error flagging criteria.
It is easiest to explain how this works by summarizing the implementation:
The regridding algorithm from level L to L+1 loops over all grid cells
at Level L and flags them or not based on the following criteria, where
`(xc,yc)` represents the cell center and `t` is the current regridding time:
* Initialize the flag by applying the error flagging criteria
specified by Richardson extrapolation and/or the default or user-supplied
routine `flag2refine` to determine whether this cell should be flagged.
* Loop over all regions (if any) for which `(xc,yc,t)` lies in the region
specified.
* If `L >= maxlevel` for *any* such region, set `flag = False` for this
cell and go on to the next cell.
* If `L < minlevel` for *every* such region, set `flag = True` and
go on to the next grid cell.