Allow different AMR flagging methods/tolerances for different regions

[rjleveque]

I suggest modifying the specification of regions so that for each region rather than the current set of parameters specified in setrun.py:

    [minlevel,maxlevel,t1,t2,x1,x2,y1,y2]

we expand this to:

    [minlevel,maxlevel,t1,t2,x1,x2,y1,y2,flag_method,tolerance]

where flag_method is an integer specifying which flagging method should be used in this region when on a level with minlevel <= level < maxlevel.

If minlevel == maxlevel then it wouldn't matter what flag_method is specified for this region but otherwise it could be one of the following, for example:

    flag_method == 1  means use Richardson extrapolation
    flag_method == 2  means use adjoint flagging
    flag_method >= 10  means use flag2refine

Note adjoint flagging isn't yet merged into master but is under development.

We could reserve method values 3 - 9 for possible other approaches to be implemented in the future, and any value flag_method >= 10 would be passed into flag2refine in case the user wants to implement multiple flagging approaches in their own version of this routine.

This enhancement would allow different regions of the domain to be flagged according to different criteria (or the same region to be tested with two different criteria, by specifying two regions with the same extents but different flag_methods).

The application I have in mind is in tsunami modeling with GeoClaw, where we might want to refine using the adjoint over the ocean, but on the finer levels that exist only around the coastal region instead use the wave_tolerance approach (implemented in GeoClaw's flag2refine) that refines where the surface elevation has abs(eta) > tolerance. This may be useful since adjoint flagging can be much more expensive at each regridding time, and near the coast regridding is done much more frequently on the finer levels where the adjoint is not giving useful information.

This would also allow much more flexibility in flagging in general, e.g. one could specify a different tolerance over some region (even for the full domain and for all levels) at early times and a different tolerance later.

We could then get rid of some parameters in setrun.py, in this section:

    amrdata.flag_richardson = False    # use Richardson?
    amrdata.flag_richardson_tol = 0.01  # Richardson tolerance

    # Flag for refinement using routine flag2refine:
    amrdata.flag2refine = True      # use this?
    amrdata.flag2refine_tol  = 0.1 # tolerance used in this routine

and instead require that the user always set at least one region covering the whole domain, e.g. add this default to a generic setrun.py:

flag_method = 10  # to use flag2refine
tolerance = 0.1
full_domain_region = [1, amrdata.amr_levels_max, 
                      clawdata.t0, 1e99,
                      clawdata.lower[0], clawdata.upper[0], 
                      clawdata.lower[1], clawdata.upper[1], 
                      flag_method, tolerance]
rundata.regiondata.regions.append(full_domain_region)

[mandli]

I am all for this. One thing that immediately comes to mind though is how we would manage these regions and data that might be specific to the flagging routine requiring more than a simple derived type. Also how would this interact with what now serves the allow_flag capability?

Some other comments:

• We should check to make sure that the union of all regions covers the entire domain. I could imagine that someone might want to have two regions that the union of do cover the entire domain but no region covers the entire domain.
• Allowing for the capability of Level specific wave tolerance geoclaw#241 would be nice. I think we could do this by simply passing any values past flag_method to the appropriate routine.
• Would suggest to change 1e99 to clawdata.tfinal although I am not sure this would work with output_style = 3

[rjleveque]

See also clawpack/geoclaw#297.