Runtime Parameters: Refinement

Enabling AMR

It only takes three steps to enable AMR:

• Set MAX_LEVEL
• Turn on at least one of the refinement criteria OPT__FLAG_*
• Edit the corresponding input file(s) Input__Flag_* to specify the refinement thresholds

See the descriptions of various refinement criteria OPT__FLAG_* given on this page for details.

Compilation Options

Related options: NLEVEL,   MAX_PATCH  

Runtime Parameters

Parameters described on this page: REGRID_COUNT,   REFINE_NLEVEL,   FLAG_BUFFER_SIZE,   FLAG_BUFFER_SIZE_MAXM1_LV,   FLAG_BUFFER_SIZE_MAXM2_LV,   MAX_LEVEL,   OPT__FLAG_RHO,   OPT__FLAG_RHO_GRADIENT,   OPT__FLAG_PRES_GRADIENT,   OPT__FLAG_LRTZ_GRADIENT,   OPT__FLAG_VORTICITY,   OPT__FLAG_JEANS,   OPT__FLAG_CURRENT,   OPT__FLAG_CRAY,   OPT__FLAG_LOHNER_DENS,   OPT__FLAG_LOHNER_ENGY,   OPT__FLAG_LOHNER_PRES,   OPT__FLAG_LOHNER_TEMP,   OPT__FLAG_LOHNER_ENTR,   OPT__FLAG_LOHNER_CRAY,   OPT__FLAG_LOHNER_FORM,   OPT__FLAG_USER,   OPT__FLAG_USER_NUM,   OPT__FLAG_REGION,   OPT__FLAG_NPAR_PATCH,   OPT__FLAG_NPAR_CELL,   OPT__FLAG_PAR_MASS_CELL,   OPT__NO_FLAG_NEAR_BOUNDARY,   OPT__PATCH_COUNT,   OPT__PARTICLE_COUNT,   OPT__REUSE_MEMORY,   OPT__MEMORY_POOL  

Other related parameters: OPT__UM_IC_DOWNGRADE,   OPT__UM_IC_REFINE,   OPT__CK_REFINE,   Interpolation Schemes  

Parameters below are shown in the format:   Name   (Valid Values)   [Default Value]

• REGRID_COUNT   (≥1)   [4]

  • Description: Check refinement on level l to create and remove patches on level l+1 every REGRID_COUNT substeps on level l. Adopting a larger value can improve performance but may also increase the risk of allowing the phenomenon of interest to leave regions with adequate resolution. Setting this parameter to an extremely large value is essentially the same as conducting a static mesh refinement (SMR) simulation.
  • Restriction:

• REFINE_NLEVEL   (≥1)   [1]

  • Description: Number of new AMR levels to be created at once during refinement.
  • Restriction:

• FLAG_BUFFER_SIZE   (0 ≤ input ≤ PATCH_SIZE)   [ PATCH_SIZE ]

  • Description: Number of flag buffers (denoted as N_buf). When checking refinement, a patch is flagged for refinement if any of its cells satisfy the refinement criteria. In addition, we add (1+2N_buf)³-1 flag buffers around each flagged cell and refine the corresponding sibling patches as well if any of these flag buffers extend across the patch border. See Fig. 2 in Schive et al. 2010 for an illustration. Adopting a value smaller than PATCH_SIZE may increase the risk of allowing the phenomenon of interest leaving regions with adequate resolution.

    Note that to alleviate the issue of over-refinemenet resulting from a large N_buf (e.g., PATCH_SIZE), we only apply this parameter to levels below MAX_LEVEL-2. N_buf on levels MAX_LEVEL-1 and MAX_LEVEL-2 are set by FLAG_BUFFER_SIZE_MAXM1_LV and FLAG_BUFFER_SIZE_MAXM2_LV, respectively, which can be safely set to smaller values.

  • Restriction:

• FLAG_BUFFER_SIZE_MAXM1_LV   (0 ≤ input ≤ PATCH_SIZE; <0 → set to default)   [ REGRID_COUNT ]

  • Description: N_buf on level MAX_LEVEL-1. See FLAG_BUFFER_SIZE for details. It is recommended to set this parameter to 2 ~ 4 (in accordance with REGRID_COUNT) for better performance.
  • Restriction:

• FLAG_BUFFER_SIZE_MAXM2_LV   (0 ≤ input ≤ PATCH_SIZE; <0 → set to default)   [depend]

  • Description: N_buf on level MAX_LEVEL-2. See FLAG_BUFFER_SIZE for details. The default value depends on both PATCH_SIZE and FLAG_BUFFER_SIZE_MAXM1_LV.
  • Restriction:

• MAX_LEVEL   (0 ≤ input < NLEVEL)   [ NLEVEL-1 ]

  • Description: Maximum allowed AMR level. Do not confuse with the compilation option NLEVEL. One can regard MAX_LEVEL as a runtime refinement criterion that simply forbids creating any patch above that level, and NLEVEL-1 is the upper bound of MAX_LEVEL.
  • Restriction:

• OPT__FLAG_RHO   (0=off, 1=on)   [0]

  • Description: Refinement criterion: gas mass density. Specify the refinement thresholds on different levels in the input file Input__Flag_Rho with the specific format. An example file can be found at example/input/Input__Flag_Rho8 (must rename it as Input__Flag_Rho to actually use it). By setting the density threshold ratio between adjacent levels to 8, it leads to a roughly fixed mass resolution similar to a Lagrangian method.
  • Restriction:

• OPT__FLAG_RHO_GRADIENT   (0=off, 1=on)   [0]

  • Description: Refinement criterion: gas mass density gradient. Specifically, a cell on level l will be flagged for refinement if its normalized density slope along a spatial direction ξ (= x/y/z in Cartesian coordinates) satisfies ∂_ξρ⋅Δξ_l / ρ ≥ η_l, where ρ is gas mass density, Δξ_l is the cell width along ξ on level l, and η_l is the refinement threshold on level l. Specify the refinement thresholds on different levels in the input file Input__Flag_RhoGradient with the specific format. An example file can be found at example/input/Input__Flag_RhoGradient.
  • Restriction:

• OPT__FLAG_PRES_GRADIENT   (0=off, 1=on)   [0]

  • Description: Refinement criterion: gas pressure gradient. See OPT__FLAG_RHO_GRADIENT for the definition of normalized slope. Specify the refinement thresholds on different levels in the input file Input__Flag_PresGradient with the specific format. An example file can be found at example/input/Input__Flag_PresGradient.
  • Restriction:

• OPT__FLAG_LRTZ_GRADIENT   (0=off, 1=on)   [0]

  • Description: Refinement criterion: Lorentz factor gradient. See OPT__FLAG_RHO_GRADIENT for the definition of normalized slope. Specify the refinement thresholds on different levels in the input file Input__Flag_LrtzGradient with the specific format. An example file can be found at example/input/Input__Flag_LrtzGradient.
  • Restriction: Must compile with SRHD.

• OPT__FLAG_VORTICITY   (0=off, 1=on)   [0]

  • Description: Refinement criterion: gas vorticity. Specifically, a cell on level l will be flagged for refinement if its normalized vorticity satisfies |∇⨯v|⋅Δξ_l / |v| ≥ η_l, where v is gas velocity, Δξ_l is the cell width along ξ on level l, and η_l is the refinement threshold on level l. Specify the refinement thresholds on different levels in the input file Input__Flag_Vorticity with the specific format. An example file can be found at example/input/Input__Flag_Vorticity.
  • Restriction:

• OPT__FLAG_JEANS   (0=off, 1=on)   [0]

  • Description: Refinement criterion: gas Jeans length. It ensures that the Jeans length is resolved by at least N cells. Specifically, a cell on level l will be flagged for refinement if its estimated Jeans length λ_J satisfies λ_J ≡ (πγP/Gρ²)^1/2 < N_lΔξ_l, where γ is adiabatic index (GAMMA), P is gas pressure, ρ is gas mass density, G is gravitational constant, Δξ_l is the cell width along ξ on level l, and N_l is the refinement threshold on level l. Specify the refinement thresholds on different levels in the input file Input__Flag_Jeans with the specific format. An example file can be found at example/input/Input__Flag_Jeans. Recommended values: ≥4.
  • Restriction:

• OPT__FLAG_CURRENT   (0=off, 1=on)   [0]

  • Description: Refinement criterion: current density in MHD. Specifically, a cell on level l will be flagged for refinement if its currenty density satisfies |∇⨯B|⋅Δξ_l / |B| ≥ η_l, where B is the magnetic field, Δξ_l is the cell width along ξ on level l, and η_l is the refinement threshold on level l. Specify the refinement thresholds on different levels in the input file Input__Flag_Current with the specific format. An example file can be found at example/input/Input__Flag_Current.
  • Restriction: Must compile with MHD.

• OPT__FLAG_CRAY   (0=off, 1=on)   [0]

  • Description: Refinement criterion: cosmic-ray energy density. Specify the refinement thresholds on different levels in the input file Input__Flag_CRay with the specific format. An example file can be found at example/input/Input__Flag_CRay.
  • Restriction: Must compile with COSMIC_RAY.

• OPT__FLAG_LOHNER_DENS   (0=off, 1=on)   [0]

  • Description: Refinement criterion: Loehner's error estimator on gas mass density. See OPT__FLAG_LOHNER_FORM for details.
  • Restriction:

• OPT__FLAG_LOHNER_ENGY   (0=off, 1=on)   [0]

  • Description: Refinement criterion: Loehner's error estimator on gas energy density (excluding potential energy). See OPT__FLAG_LOHNER_FORM for details.
  • Restriction:

• OPT__FLAG_LOHNER_PRES   (0=off, 1=on)   [0]

  • Description: Refinement criterion: Loehner's error estimator on gas pressure. See OPT__FLAG_LOHNER_FORM for details.
  • Restriction:

• OPT__FLAG_LOHNER_TEMP   (0=off, 1=on)   [0]

  • Description: Refinement criterion: Loehner's error estimator on gas temperature. See OPT__FLAG_LOHNER_FORM for details.
  • Restriction:

• OPT__FLAG_LOHNER_ENTR   (0=off, 1=on)   [0]

  • Description: Refinement criterion: Loehner's error estimator on gas entropy. See OPT__FLAG_LOHNER_FORM for details.
  • Restriction:

• OPT__FLAG_LOHNER_CRAY   (0=off, 1=on)   [0]

  • Description: Refinement criterion: Loehner's error estimator on cosmic-ray energy density. See OPT__FLAG_LOHNER_FORM for details.
  • Restriction: Must compile with COSMIC_RAY.

• OPT__FLAG_LOHNER_FORM   (1=FLASH-ghost1, 2=FLASH-ghost2, 3=form-invariant-ghost1, 4=form-invariant-ghost2)   [2]

  • Description: Different forms of the Loehner's error estimator. This method calculates the second derivative normalized by the first derivative, with an additional filter term in the denominator to ignore small fluctuations. OPT__FLAG_LOHNER_FORM=2 corresponds to the form used by FLASH and Enzo (see Eq. 8.4 in the FLASH User Guide or Eq. 33 in the Enzo Code Paper). OPT__FLAG_LOHNER_FORM=1 is similar to OPT__FLAG_LOHNER_FORM=2 except using only 1 instead of 2 ghost zones on each side when estimating spatial derivatives. OPT__FLAG_LOHNER_FORM=3/4 slightly revises the original formula to become form-invariant and uses 1 and 2 ghost zones on each side when estimating spatial derivatives, respectively.

    Specify the refinement thresholds on different levels in the input file Input__Flag_Lohner with the specific format. An example file can be found at example/input/Input__Flag_Lohner__FLASH2 (must rename it as Input__Flag_Lohner to actually use it).

    # Level  Threshold_Refine  Threshold_Derefine    Filter    Soften    MinDensity
          0              0.80                0.80      0.01      0.00          0.00
          1              0.80                0.80      0.01      0.00          0.00
          2              0.80                0.80      0.01      0.00          0.00
    

    Note that this input table takes 6 columns, where the 1st column (Level) is useless and the 5th column (Soften) is deprecated.

    • Threshold: dimensionless refinement/derefinement thresholds (recommended values: 0.3 ~ 0.8).
    • Filter: dimensionless filter term in the denominator to ignore small fluctuations (recommended value: 0.01 ~ 0.1).
    • Soften: dimensional floor value of the denominator. Specifically, we calculate error = sqrt( N/max(D,Soften) ), where N and D are the numerator and denominator in the Lohner's formula, respectively. This parameter is deprecated.
    • MinDensity: minimum gas mass density threshold. All Loehner's refinement criteria (i.e., all OPT__FLAG_LOHNER_* options) are disabled for cells with gas density lower than this threshold.

    Caution: currently all OPT__FLAG_LOHNER_* options share the same input file Input__Flag_Lohner.

  • Restriction:

• OPT__FLAG_USER   (0=off, 1=on)   [0]

  • Description: Refinement criterion: user-defined. Edit src/Refine/Flag_User.cpp or a problem-specific function (for the latter, see Add Problem Specific Functionalities). Specify the refinement thresholds on different levels in the input file Input__Flag_User with the specific format. An example file can be found at example/input/Input__Flag_User. See also OPT__FLAG_USER_NUM.
  • Restriction:

• OPT__FLAG_USER_NUM   (≥1)   [1]

  • Description: Number of threshold values on each level in the file Input__Flag_User for OPT__FLAG_USER.
  • Restriction:

• OPT__FLAG_REGION   (0=off, 1=on)   [0]

  • Description: Edit src/Refine/Flag_Region.cpp to specify the regions that are allowed to be refined. Note that this option does not trigger any refinement. Instead, it simply forbids refinement outside the specified regions.
  • Restriction:

• OPT__FLAG_NPAR_PATCH   (0=off, 1=itself, 2=itself+siblings)   [0]

  • Description: Refinement criterion: number of particles in a patch. For OPT__FLAG_NPAR_PATCH=1, only patches with more particles than a given threshold are flagged for refinement. For OPT__FLAG_NPAR_PATCH=2, not only patches with excessive numbers of particles but also their 26 siblings are flagged for refinement. Specify the refinement thresholds on different levels in the input file Input__Flag_NParPatch with the specific format. An example file can be found at example/input/Input__Flag_NParPatch. Note that the flag buffers (i.e., FLAG_BUFFER_SIZE, FLAG_BUFFER_SIZE_MAXM1_LV, and FLAG_BUFFER_SIZE_MAXM2_LV) do not apply to this refinement criterion.
  • Restriction: Currently always includes tracer particles.

• OPT__FLAG_NPAR_CELL   (0=off, 1=on)   [0]

  • Description: Refinement criterion: number of particles in a cell. Specify the refinement thresholds on different levels in the input file Input__Flag_NParCell with the specific format. An example file can be found at example/input/Input__Flag_NParCell.
  • Restriction: Currently always excludes tracer particles.

• OPT__FLAG_PAR_MASS_CELL   (0=off, 1=on)   [0]

  • Description: Refinement criterion: total particle mass in a cell. Specify the refinement thresholds on different levels in the input file Input__Flag_ParMassCell with the specific format. An example file can be found at example/input/Input__Flag_ParMassCell.
  • Restriction:

• OPT__NO_FLAG_NEAR_BOUNDARY   (0=off, 1=on)   [0]

  • Description: Disallow refinement near the boundaries.
  • Restriction:

• OPT__PATCH_COUNT   (0=off, 1=every root-level step, 2=every substep)   [1]

  • Description: Record the number of patches on each level in the log file Record__PatchCount.
  • Restriction:

• OPT__PARTICLE_COUNT   (0=off, 1=every root-level step, 2=every substep)   [1]

  • Description: Record the number of particles on each level in the log file Record__ParticleCount.
  • Restriction:

• OPT__REUSE_MEMORY   (0=off, 1=on, 2=aggressive)   [2]

  • Description: Reuse allocated patch memory to reduce memory fragmentation. For OPT__REUSE_MEMORY=1, the code will still deallocate patch memory when redistributing all patches for load balancing (see LB_INPUT__WLI_MAX). In comparison, for OPT__REUSE_MEMORY=2, the code will not deallocate patch memory during the entire simulation. Note that this option will not preallocate any patches unless OPT__MEMORY_POOL is enabled.
  • Restriction:

• OPT__MEMORY_POOL   (0=off, 1=on)   [0]

  • Description: Preallocate patches as a memory pool to reduce memory fragmentation. One must specify the numbers of patches to be preallocated in the input file Input__MemoryPool (check the link for details).
  • Restriction: Only applicable when adopting OPT__REUSE_MEMORY=1/2.

Remarks

Potential outside the isolated boundaries

When adopting the isolated boundary conditions for gravity (i.e., OPT__BC_POT=2), the ghost zones of gravitational potential outside the simulation domain are currently filled out by extrapolation.

Links

• Main page of Runtime Parameters