AmrMesh

AmrMesh handles virtually the entire AMR and cut-cell infrastructure in chombo-discharge, and has the following responsibility:

  1. Generate grids form a set of cell tags (potentially more than one set of grids).

  2. Load balance the grids if necessary.

  3. Instantiate the cut-cell information on grids.

  4. Provide a mask which tells the user if a cell is covered by a finer grid.

  5. Generate operators that are required for handling AMR data, e.g.,

    • Ghost cell interpolators.

    • Coarsening operators.

    • Stencils for interpolation and extrapolation near the embedded boundaries.

    • Fine-to-coarse grid interpolators.

    • Infrastructure for particle-mesh operators.

    • … and many others.

In addition to these, AmrMesh contains function for actually allocating data with user-defined centering (e.g., cell, face, EB) on a specified Realm. It also has responsibility for allocating particle containers.

One thing that AmrMesh is not, is a numerical discretization holder for PDEs, which is a responsibility that is generally deferred to solvers. In some cases AmrMesh certainly holds operators that have an underlying discretization, e.g., gradient operators which have a specific discretization based on least squares reconstruction around the embedded boundaries. But in virtually all cases one should simply think of these operators as AMR operators that handle specific types of common data operations on mesh and particle data.

AmrMesh is an integral part of chombo-discharge, and users will never have the need to modify it unless they are implementing something entirely new. The behavior of AmrMesh is modified through its available input parameters.

Tip

Here is the AmrMesh C++ API

Class options

Various class options are available for adjusting the behavior of the Driver class. Below, we include the current template options file for the Driver class.

Listing 21 Template input options for the AmrMesh class. Runtime adjustable options are highlighted.
# ====================================================================================================
# AmrMesh class options
# ====================================================================================================
AmrMesh.lo_corner            = -1 -1 -1       ## Low corner of problem domain
AmrMesh.hi_corner            = 1  1  1        ## High corner of problem domain
AmrMesh.verbosity            = -1             ## Controls verbosity.
AmrMesh.coarsest_domain      = 128 128 128    ## Number of cells on coarsest domain
AmrMesh.max_amr_depth        = 0              ## Maximum amr depth
AmrMesh.max_sim_depth        = -1             ## Maximum simulation depth
AmrMesh.fill_ratio           = 1.0            ## Fill ratio for grid generation
AmrMesh.buffer_size          = 2              ## Number of cells between grid levels
AmrMesh.grid_algorithm       = tiled          ## Berger-Rigoustous 'br' or 'tiled' for the tiled algorithm
AmrMesh.box_sorting          = morton         ## 'none', 'shuffle', 'morton'
AmrMesh.blocking_factor      = 16             ## Blocking factor.
AmrMesh.max_box_size         = 16             ## Maximum allowed box size
AmrMesh.max_ebis_box         = 16             ## Maximum allowed box size for EBIS generation.
AmrMesh.ref_rat              = 2 2 2 2 2 2    ## Refinement ratios (mixed ratios are allowed).
AmrMesh.num_ghost            = 2              ## Number of ghost cells.
AmrMesh.lsf_ghost            = 2              ## Number of ghost cells when writing level-set to grid
AmrMesh.eb_ghost             = 2              ## Set number of of ghost cells for EB stuff
AmrMesh.mg_interp_order      = 2              ## Multigrid interpolation order
AmrMesh.mg_interp_radius     = 2              ## Multigrid interpolation radius
AmrMesh.mg_interp_weight     = 1              ## Multigrid interpolation weight (for least squares)
AmrMesh.centroid_interp      = minmod         ## Centroid interp stencils. linear, lsq, minmod, etc
AmrMesh.eb_interp            = minmod         ## EB interp stencils. linear, taylor, minmod, etc
AmrMesh.redist_radius        = 1              ## Redistribution radius for hyperbolic conservation laws

For users, modifying the behavior of AmrMesh is comparatively easy. We have listed the most commonly adjusted grid parameters above, which include the specification of the physical domain, the maximum number of AMR levels that are permitted, as well as how grids are generated.

Coarse-grid decomposition

AmrMesh.lo_corner and AmrMesh.hi_corner are the physical corners of the simulation domain. AmrMesh.coarsest_domain is the number of grid cells on the coarsest grid level (i.e., without AMR). It is important that cell sizes are uniform, so one must always have \(\Delta x = \Delta y = \Delta z\). Usually, this means that AmrMesh.lo_corner, AmrMesh.hi_corner, and AmrMesh.coarsest_domain must all be consistently defined. Moreover, it is normally desirable to make AmrMesh.coarsest_domain a factor of 2 (e.g., 64, 128, 256, etc.), since this permits arbitrarily deep multigrid coarsening. This is not a requirement, however, although we do note that AmrMesh.coarsest_domain must be divisible by AmrMesh.blocking_factor.

Domain decomposition

With Cartesian AMR, each grid level is decomposed into grid blocks of constant size, or sizes that potentially vary between some min/max size along each dimension. In chombo-discharge this is encapsulated by AmrMesh.blocking_factor, which is the smallest grid box that can be generated when meshing the domain. Likewise, AmrMesh.max_box_size is the maximum box size that can be produced, but usage of a constant box size is common an increased requirement in chombo-discharge.

Tip

Use fixed box sizes where AmrMesh.blocking_factor and AmrMesh.max_box_size are the same.

The flag AmrMesh.max_ebis_box indicates essentially the blocking factor when generating the cut-cell information at the start of a simulation. It may happen for very large simulations that one has to increase the box size (e.g., to 32) in order to trim grid metadata.

AmrMesh.ref_rat determines the refinement ratio between grid levels, and factors of 2 and 4 are supported. We want to point out that mixed refinement factors are supported.

Tip

If AmrMesh.max_amr_depth is greater than the number of refinement ratios specified in AmrMesh.ref_rat, chombo-discharge will automatically fill in the remaining refinement ratios (padding with the last entry). I.e., one obtains factor 2 refinement every if AmrMesh.ref_rat = 2.

Two gridding algorithms are supported, called Tiled mesh refinement the classical Berger-Rigoutsos refinement algorithm. These are discussed in Mesh generation, and the user can specify which one to use by setting AmrMesh.grid_algorithm accordingly. In general, the tiled algorithm is exceedingly more performant at larger scales.

Ghost cells

It is normally not necessary to adjust the number of ghost cells in chombo-discharge simulations since most discretizations require at most 2 ghost cells. Substantial efforts have been made to avoid increasing the required number of ghost cells. Regardless, the number of ghost cells can be adjusted by setting AmrMesh.num_ghost to a specified value. A companion parameter is AmrMesh.eb_ghost, which specifies the maximum number of ghost cells that are used when computing the cut-cell discretization.

Warning

One must always have AmrMesh.eb_ghost > AmrMesh.num_ghost.

Finally, it is possible to evaluate implicit functions on the mesh (e.g., for figuring out how far a cell is from a boundary). It can be useful to include a larger ghost region in these data holders, which is adjusted by AmrMesh.lsf_ghost.

Multigrid interpolation

Multigrid interpolation is done using least squares reconstruction, as discussed in Multigrid ghost cell interpolation. The user can set the order, radius, and least squares weighting for this interpolation by setting AmrMesh.mg_interp_order, AmrMesh.mg_interp_radius, and AmrMesh.mg_interp_weight. Note that specifying AmrMesh.mg_interp_radius > AmrMesh.eb_ghost is sure to lead to a run-time error (possibly a segfault).

Interpolation near the EB

Most data in chombo-discharge is cell-centered, although data can be interpolated or extrapolated to cell centroids and EB centroids. The interpolation type is done by setting AmrMesh.centroid_interp and AmrMesh.eb_interp accordingly. Currently, we support the following options:

  1. constant i.e., use the cell centered value.

  2. linear, using bi/tri-linear interpolation.

  3. taylor, using the Taylor series evaluated at the cell center.

  4. lsq, using a first order unweighted least squares polynomial.

  5. pwl, using piecewise linear reconstruction.

  6. minmod, using a minmod slope limiter.

  7. superbee, using a superbee slope limiter.

  8. monotonized_central, using a van Leer slope limiter.

Typically, one can just leave this option at minmod.