.. _flagregions:
Specifying flagregions for adaptive refinement
==============================================
**New in Version 5.7.0.**
AMRClaw and GeoClaw version 5.6.1 (and earlier) allow specifying
rectangular refinement regions (see :ref:`refinement_regions`)
in `setrun.py`, in the form of a list that is appended to
`rundata.regiondata.regions`::
rundata.regiondata.regions.append([minlevel,maxlevel,t1,t2,x1,x2,y1,y2])
This is a region that is active from time `t1` to `t2` over the
spatial extent `[x1,x2,y1,y2]`.
Starting in v5.7.0 of AMRClaw/GeoClaw we now support a new approach to
specifying regions that are now called `flagregions` for more clarity
regarding what they are used for. The new data structure
also supports simple rectangles and so should ultimately replace
`regions` in both AMRClaw and GeoClaw, but currently you can mix and match.
The new way of specifying a flag region in `setrun.py` is to first
define an object `flagregion` of class `clawpack.amrclaw.data.FlagRegion`,
set various
attributes of this object (including `minlevel`, `maxlevel`, `t1`,
`t2`, and a spatial extent), and then append this object to the list
`rundata.flagregiondata.flagregions`.
Here is how you would specify a simple rectangle as above in the new
style, chosen to cover the entire spatial domain and to allow only 1 level
everywhere (which might be supplemented by other regions where more levels
are allowed)::
x1,x2,y1,y2 = [rundatat.clawdata.lower[0], rundatat.clawdata.upper[0],
rundatat.clawdata.lower[1], rundatat.clawdata.upper[1]]
from clawpack.amrclaw.data import FlagRegion
flagregion = FlagRegion(num_dim=2) # so far only 2D supported
flagregion.name = 'Region_domain'
flagregion.minlevel = 1
flagregion.maxlevel = 1
flagregion.t1 = 0.
flagregion.t2 = 1e9
flagregion.spatial_region_type = 1 # Rectangle
flagregion.spatial_region = [x1,x2,y1,y2]
rundata.flagregiondata.flagregions.append(flagregion)
Note that `flagregion.spatial_region_type == 1` indicates that the
flagregion is a rectangle.
.. _flagregions-rr:
Using ruled rectangles as flagregions
-------------------------------------
In addition to simple rectangles, more general ruled rectangles can also be
used as flagregions. These are a restricted set of polygons for which it is
easy to test if a point is inside or outside, as described in more detail in
:ref:`ruled_rectangles`.
To specify a ruled rectangle, use `flagregion.spatial_region_type == 2`
and provide a path to a data file that describes the ruled rectangle.
For simple ruled rectangles the code to create the data file can also be
included in `setrun.py`.
Here is an example where a simple ruled rectangle is defined and used as a
flagregion. In this case the flagregion is a trapezoid with vertices
:math:`(1,3),~ (1,6),~ (2,4),~ (2,7)`::
from clawpack.amrclaw.data import FlagRegion
flagregion = FlagRegion(num_dim=2)
flagregion.name = 'Region_Trapezoid'
flagregion.minlevel = 2
flagregion.maxlevel = 3
flagregion.t1 = 0.
flagregion.t2 = 1e9
flagregion.spatial_region_type = 2 # Ruled Rectangle
flagregion.spatial_region_file = \
os.path.abspath('RuledRectangle_Trapezoid.data')
rundata.flagregiondata.flagregions.append(flagregion)
# code to make RuledRectangle_Trapezoid.data:
from clawpack.amrclaw import region_tools
rr = region_tools.RuledRectangle()
rr.method = 1 # piecewiselinear edges between s values
rr.ixy = 'x' # so s refers to x, lower & upper are limits in y
rr.s = np.array([1,2])
rr.lower = np.array([3,6])
rr.upper = np.array([4,7])
rr.write('RuledRectangle_Trapezoid.data') # creates data file
See the `setrun.py` file in
`$CLAW/amrclaw/examples/advection_2d_flagregions` for additional examples.
See :ref:`mf-amr-flag` for a more complex example where a ruled rectangle is
defined that covers a set of fgmax points (see :ref:`fgmax`) defined with the
:ref:`marching_front`.