.. _chap:inputs:

Runtime Parameters
==================

.. role:: cpp(code)
   :language: c++

This chapter contains a list of AMReX :cpp:`ParmParse` runtime parameters
and their **default** values. They can be set by either including them in an
inputs file, or specifying them at the command line, or passing a function
to :cpp:`amrex::Initialize` and the function adds parameters to AMReX's
:cpp:`ParmParse`'s parameter database. For more information on
:cpp:`ParmParse`, see :ref:`sec:basics:parmparse`.

.. important:: AMReX reserves the following prefixes in :cpp:`ParmParse`
               parameters: ``amr``, ``amrex``, ``blprofiler``, ``device``,
               ``DistributionMapping``, ``eb2``, ``fab``, ``fabarray``,
               ``geometry``, ``particles``, ``tiny_profiler``, and
               ``vismf``.

AMR
---

AMReX applications with AMR use either :cpp:`class AmrCore` or the more
specialized :cpp:`class Amr`. Since :cpp:`class Amr` is derived from
:cpp:`class AmrCore`, the parameters for the :cpp:`AmrCore` class also apply
to the :cpp:`Amr` class. Additionally, :cpp:`class AmrCore` is derived from
:cpp:`class AmrMesh`, so :cpp:`AmrMesh` member functions are also available
to :cpp:`AmrCore` and :cpp:`Amr`.

AmrCore Class
^^^^^^^^^^^^^

Below are a list of important :cpp:`ParmParse` parameters. However, AMReX
applications can choose to avoid them entirely by use this :cpp:`AMRCore`
constructor :cpp:`AmrCore(Geometry const& level_0_geom, AmrInfo const&
amr_info)`, where :cpp:`struct AmrInfo` contains all the information that
can be set via :cpp:`ParmParse`.

.. py:data:: amr.verbose
   :type: int
   :value: 0

   This controls the verbosity level of :cpp:`AmrCore` functions.

.. py:data:: amr.n_cell
   :type: int array
   :value: [none]

   This parameter is used only when ``n_cell`` is not provided as an
   argument to :cpp:`AmrCore` constructors. It specifies the number of cells
   in each dimension on Level 0.

.. py:data:: amr.max_level
   :type: int
   :value: [none]

   This parameter is used only when ``max_level`` is not provided as an
   argument to :cpp:`AmrCore` constructors. It specifies the maximum level
   of refinement allowed. Note that the total number of levels, including
   the base level 0, is ``max_level+1``.

.. py:data:: amr.ref_ratio
   :type: int array
   :value: 2 2 2 ... 2

   If the refinement ratio is not provided as an argument to :cpp:`AmrCore`
   constructors and :py:data:`amr.ref_ratio_vect` is not found in the
   :cpp:`ParmParse` database, this parameter will be used to set the
   refinement ratios between AMR levels. If there are more AMR levels than
   the size of the integer parameter array, the last integer will be used as
   the refinement ratio for the unspecified levels. For example, if
   ``max_level`` is 4 and the provided ``amr.ref_ratio`` parameter is ``2
   4``, the refinement ratios are 2, 4, 4 and 4, for levels 0/1, 1/2, 2/3
   and 3/4, respectively.

.. py:data:: amr.ref_ratio_vect
   :type: int array
   :value: [none]

   If the refinement ratio is not provided as an argument to :cpp:`AmrCore`
   constructors and :py:data:`amr.ref_ratio_vect` is found in the
   :cpp:`ParmParse` database, it will be used to set the refinement ratios
   between AMR levels. It's an error if the size of the integer array, if
   found, is less than ``max_level*AMREX_SPACEDIM``. The first
   ``AMREX_SPACEDIM`` numbers specify the refinement ratios in the
   ``AMREX_SPACEDIM`` dimensions between levels 0 and 1, the next
   ``AMREX_SPACEDIM`` numbers specify the ratios for levels 1 and 2, and so
   on.

.. py:data:: amr.max_grid_size
   :type: int array
   :value: [build dependent]

   This controls the maximum grid size on AMR levels, one value for each
   level. If the size of the integer array is less than the total number of
   levels, the last integer will be used for the unspecified levels. The
   default value is 128 for 1D and 2D runs. For 3D runs, the default value
   is 64 and 32, for GPU and CPU runs, respectively. Note that the user can
   also call :cpp:`AmrMesh::SetMaxGridSize` to set the maximum grid
   sizes. Additionally, the values set by this parameter can be overridden
   by :py:data:`amr.max_grid_size_x`, :py:data:`amr.max_grid_size_y` and
   :py:data:`amr.max_grid_size_z`.

.. py:data:: amr.max_grid_size_x
   :type: int array
   :value: [none]

   If provided, this will override the maximum grid size in the x-direction
   set by :py:data:`amr.max_grid_size`. If the size of the integer array is
   less than the total number of levels, the last integer will be used for
   the unspecified levels.

.. py:data:: amr.max_grid_size_y
   :type: int array
   :value: [none]

   If provided, this will override the maximum grid size in the y-direction
   set by :py:data:`amr.max_grid_size`. If the size of the integer array is
   less than the total number of levels, the last integer will be used for
   the unspecified levels.

.. py:data:: amr.max_grid_size_z
   :type: int array
   :value: [none]

   If provided, this will override the maximum grid size in the z-direction
   set by :py:data:`amr.max_grid_size`. If the size of the integer array is
   less than the total number of levels, the last integer will be used for
   the unspecified levels.

.. py:data:: amr.blocking_factor
   :type: int array
   :value: [build dependent]

   This controls the blocking factor on AMR levels, one value for each
   level. If the size of the integer array is less than the total number of
   levels, the last integer will be used for the unspecified levels. The
   default value is 8. Note that the user can also call
   :cpp:`AmrMesh::SetBlockingFactor` to set the blocking
   factors. Additionally, the values set by this parameter can be overridden
   by :py:data:`amr.blocking_factor_x`, :py:data:`amr.blocking_factor_y` and
   :py:data:`amr.blocking_factor_z`.

.. py:data:: amr.blocking_factor_x
   :type: int array
   :value: [none]

   If provided, this will override the blocking factor in the x-direction
   set by :py:data:`amr.blocking_factor`. If the size of the integer array
   is less than the total number of levels, the last integer will be used
   for the unspecified levels.

.. py:data:: amr.blocking_factor_y
   :type: int array
   :value: [none]

   If provided, this will override the blocking factor in the y-direction
   set by :py:data:`amr.blocking_factor`. If the size of the integer array
   is less than the total number of levels, the last integer will be used
   for the unspecified levels.

.. py:data:: amr.blocking_factor_z
   :type: int array
   :value: [none]

   If provided, this will override the blocking factor in the z-direction
   set by :py:data:`amr.blocking_factor`. If the size of the integer array
   is less than the total number of levels, the last integer will be used
   for the unspecified levels.

.. py:data:: amr.n_proper
   :type: int
   :value: 1

   This parameter controls the proper nesting of grids on AMR levels. For
   example, if we have ``blocking_factor = 8``, ``ref_ratio = 2`` and
   ``n_proper = 1``, there will be at least ``8/2*1 = 4`` coarse level cells
   outside the fine level grids except at the physical boundaries. Note that
   the user can also call :cpp:`AmrMesh::SetNProper(int)` to set the proper
   nesting parameter.

.. py:data:: amr.grid_eff
   :type: amrex::Real
   :value: 0.7

   This parameter controls the grid efficiency threshold during grid
   creation. While a higher value can enhance efficiency, it may negatively
   impact overall performance, especially for GPU runs, because it tends to
   create smaller grids. Note that the user can also call
   :cpp:`AmrMesh::SetGridEff(Real)` to set the grid efficiency threshold.

.. py:data:: amr.n_error_buf
   :type: int array
   :value: 1 1 1 ... 1

   This parameter controls how many extra cells will be tagged around every
   tagged cell. For example, if ``n_error_buf = 2``, tagging cell
   ``(i,j,k)`` will result in the tagging of the region of from lower corner
   ``(i-2,j-2,k-2)`` to upper corner ``(i+2,j+2,k+2)``. If the size of the
   integer array is less than the number of levels, the last integer will be
   used for the unspecified levels. Note that the values set by this
   parameter can be overridden by :py:data:`amr.n_error_buf_x`,
   :py:data:`amr.n_error_buf_y` and :py:data:`amr.n_error_buf_z`.


.. py:data:: amr.n_error_buf_x
   :type: int array
   :value: [none]

   This parameter controls the error buffer size in the x-direction. If the
   size of the integer array is less than the number of levels, the last
   integer will be used for the unspecified levels.

.. py:data:: amr.n_error_buf_y
   :type: int array
   :value: [none]

   This parameter controls the error buffer size in the y-direction. If the
   size of the integer array is less than the number of levels, the last
   integer will be used for the unspecified levels.

.. py:data:: amr.n_error_buf_z

   This parameter controls the error buffer size in the z-direction. If the
   size of the integer array is less than the number of levels, the last
   integer will be used for the unspecified levels.

.. py:data:: amr.refine_grid_layout
   :type: bool
   :value: true

   If it's true, AMReX will attempt to chop new grids into smaller chunks
   ensuring at least one grid per MPI process, provided this does not
   violate the blocking factor constraint.

.. py:data:: amr.refine_grid_layout_x
   :type: bool
   :value: [none]

   This parameter, if found, will override the
   :py:data:`amrex.refine_grid_layout` parameter in the x-direction.

.. py:data:: amr.refine_grid_layout_y
   :type: bool
   :value: [none]

   This parameter, if found, will override the
   :py:data:`amrex.refine_grid_layout` parameter in the y-direction.

.. py:data:: amr.refine_grid_layout_z
   :type: bool
   :value: [none]

   This parameter, if found, will override the
   :py:data:`amrex.refine_grid_layout` parameter in the z-direction.

.. py:data:: amr.check_input
   :type: bool
   :value: true

   If this is true, AMReX will check if the various parameters in
   :cpp:`AmrMesh` are reasonable.

Amr Class
^^^^^^^^^

.. warning:: These parameters are specific to :cpp:`class Amr` based
             applications. If your application use :cpp:`class AmrCore`
             directly, they do not apply unless you have provided
             implementations for them.

Subcycling
""""""""""

.. py:data:: amr.subcycling_mode
   :type: string
   :value: Auto

   This controls the subcycling mode of :cpp:`class Amr`. Possible value
   are ``None`` for no subcycling, or ``Auto`` for subcycling.

Regrid
""""""

.. py:data:: amr.regrid_int
   :type: int array
   :value: 1 1 1 ... 1

   This controls how often we perform the regrid operation on AMR levels 0
   to ``max_level-1``. If the parameter is a single value, it will be used
   on all levels. If the parameter is an array of more than one values, the
   size must be at least ``max_level`` and values after the first
   ``max_level`` elements are ignored.

.. py:data:: amr.regrid_on_restart
   :type: bool
   :value: false

   This controls whether we perform regrid immediately after restart.

.. py:data:: amr.force_regrid_level_zero
   :type: bool
   :value: false

   This controls whether we perform regrid on level 0.

.. py:data:: amr.compute_new_dt_on_regrid
   :type: bool
   :value: false

   This controls whether we re-compute ``dt`` after regrid.

.. py:data:: amr.initial_grid_file
   :type: string
   :value: [none]

   If this is set, the initial grids will be read from the specified file.

.. py:data:: amr.regrid_file
   :type: string
   :value: [none]

   If this is set, regrid will use the grids in the specified file.

I/O
"""

.. py:data:: amr.restart
   :type: string
   :value: [none]

   If this is set, the simulation will restart from the specified checkpoint
   file.

.. py:data:: amr.plotfile_on_restart
   :type: bool
   :value: false

   If this is set to true, a plotfile will be written after restart.

.. py:data:: amr.file_name_digits
   :type: int
   :value: 5

   This parameter specifies the minimum number of digits in checkpoint and
   plotfile names.

.. py:data:: amr.checkpoint_files_output
   :type: bool
   :value: true

   This controls whether we write checkpoint files.

.. py:data:: amr.check_file
   :type: string
   :value: chk

   This sets the "root" of checkpoint file names. For example, the
   checkpoint files are named ``chk00000``, ``chk001000``, etc. by default.

.. py:data:: amr.check_int
   :type: int
   :value: -1

   This controls the interval of writing checkpoint files, defined as the
   number of level 0 steps between each checkpoint. A value less than 1
   indicates no checkpoint files will be written.

.. py:data:: amr.check_per
   :type: amrex::Real
   :value: -1

   This controls the interval of writing checkpoint files, defined as the
   time (not the wall time) elapsed between each checkpoint. A value less
   or equal to 0 indicates no checkpoint files will be written.

.. py:data:: amr.checkpoint_nfiles
   :type: int
   :value: 64

   This is the maximum number of binary files per :cpp:`MultiFab` when
   writing checkpoint files.

.. py:data:: amr.plot_files_output
   :type: bool
   :value: true

   This controls whether we write plot files.

.. py:data:: amr.plot_file
   :type: string
   :value: plt

   This sets the "root" of plot file names. For example, the plot files are
   named ``plt00000``, ``plt001000``, etc. by default.

.. py:data:: amr.plot_int
   :type: int
   :value: -1

   This controls the interval of writing plot files, defined as the number
   of level 0 steps between each plot file. A value less than 1 indicates no
   plot files will be written.

.. py:data:: amr.plot_per
   :type: amrex::Real
   :value: -1

   This controls the interval of writing plot files, defined as the time
   (not the wall time) elapsed between each plot file. A value less or equal
   to 0 indicates no plot files will be written.

.. py:data:: amr.plot_log_per
   :type: amrex::Real
   :value: -1

   This controls the interval of writing plot files, defined as the
   ``log10`` time (not the wall time) elapsed between each plot file. A
   value less or equal to 0 indicates no plot files will be written.

.. py:data:: amr.plot_max_level
   :type: int
   :value: amr.max_level

   This controls the finest level in a plot file. For example, if the finest
   level in a run is 3, but this parameter is set to 1, only levels 0 and 1
   will be saved in a plot file.

.. py:data:: amr.plot_nfiles
   :type: int
   :value: 64

   This is the maximum number of binary files per :cpp:`MultiFab` when
   writing plot files.

.. py:data:: amr.plot_vars
   :type: string array
   :value: [none]

   If this parameter is set, the variables specified in the string array
   will be the state variables saved in the plot files. The special values
   ``ALL`` and ``NONE`` mean that all or none of the state variables will be
   saved. If this parameter is not set, all state variables will be saved.

.. py:data:: amr.derive_plot_vars
   :type: string array
   :value: [none]

   If this parameter is set, the variables specified in the string array
   will be the derive variables saved in the plot files. The special values
   ``ALL`` and ``NONE`` mean that all or none of the derive variables will
   be saved. If this parameter is not set, none of the derive variables will
   be saved.

.. py:data:: amr.small_plot_file
   :type: string
   :value: smallplt

   This sets the "root" of small plot file names. For example, the small
   plot files are named ``smallplt00000``, ``smallplt001000``, etc. by
   default.

.. py:data:: amr.small_plot_int
   :type: int
   :value: -1

   This controls the interval of writing small plot files, defined as the
   number of level 0 steps between each small plot file. A value less than 1
   indicates no small plot files will be written.

.. py:data:: amr.small_plot_per
   :type: amrex::Real
   :value: -1

   This controls the interval of writing small plot files, defined as the
   time (not the wall time) elapsed between each small plot file. A value
   less or equal to 0 indicates no small plot files will be written.

.. py:data:: amr.small_plot_log_per
   :type: amrex::Real
   :value: -1

   This controls the interval of writing small plot files, defined as the
   ``log10`` time (not the wall time) elapsed between each small plot
   file. A value less or equal to 0 indicates no small plot files will be
   written.

.. py:data:: amr.small_plot_vars
   :type: string array
   :value: [none]

   If this parameter is set, the variables specified in the string array
   will be the state variables saved in the small plot files. The special
   values ``ALL`` and ``NONE`` mean that all or none of the state variables
   will be saved. If this parameter is not set, none of the state variables
   will be saved.

.. py:data:: amr.derive_small_plot_vars
   :type: string array
   :value: [none]

   If this parameter is set, the variables specified in the string array
   will be the derive variables saved in the small plot files. The special
   values ``ALL`` and ``NONE`` mean that all or none of the derive variables
   will be saved. If this parameter is not set, none of the derive variables
   will be saved.

.. py:data:: amr.message_int
   :type: int
   :value: 10

   This controls the interval of checking messages during a run, defined as
   the number of level 0 steps between checks. A value less than 1 indicates
   no checking will be performed. A message refers to a file created by the
   user on the disk, where only the file name is checked, not its
   content. If the file name matches one of the following predefined names,
   appropriate actions will be taken.

   dump_and_continue
      Make a checkpoint file and continue running the simulation.

   stop_run
      Stop the simulation.

   dump_and_stop
      Make a checkpoint file and stop the simulation.

   plot_and_continue
      Make a plot file and continue running the simulation.

   small_plot_and_continue
      Make a small plot file and continue running the simulation.

.. py:data:: amr.write_plotfile_with_checkpoint
   :type: bool
   :value: true

   This parameter is for the message action discussed in
   :py:data:`amr.message_int`. It controls whether an action will make a
   plot file as well when asked to make a checkpoint file.

.. py:data:: amr.run_log
   :type: string
   :value: [none]

   If this parameter is set, the run log will be enabled and this is the log
   file name.

.. py:data:: amr.run_log_terse
   :type: string
   :value: [none]

   If this parameter is set, the terse run log will be enabled and this is
   the log file name.

.. py:data:: amr.grid_log
   :type: string
   :value: [none]

   If this parameter is set, the grid log will be enabled and this is the
   log file name.

.. py:data:: amr.data_log
   :type: string
   :value: [none]

   If this parameter is set, the data log will be enabled and this is the
   log file name.

Basic Controls
--------------

.. py:data:: amrex.verbose
   :type: int
   :value: 1

   This controls the verbosity level of AMReX. Besides using
   :cpp:`ParmParse`, you can also call :cpp:`amrex::SetVerbose(int)` to set
   it.

.. py:data:: amrex.init_snan
   :type: bool
   :value: [build dependent]

   This controls whether :cpp:`MultiFab`, :cpp:`FArrayBox`,
   :cpp:`BaseFab<double|float>`, :cpp:`PODVectors<double|float>`,
   :cpp:`Gpu::DeviceVector<double|float>`, etc. will be initialized to
   signaling NaNs at construction. The default value is true for debug
   builds. For non-debug builds, the default is false unless ``TEST=TRUE``
   for GNU Make or ``AMReX_TESTING`` is enabled for CMake.

.. py:data:: amrex.abort_on_unused_inputs
   :type: bool
   :value: false

   If this is true and there are unused :cpp:`ParmParse` parameters, AMReX
   will abort during :cpp:`amrex::Finalize`.

.. py:data:: amrex.parmparse.verbose
   :type: int
   :value: amrex.verbose

   If this is greater than zero, unused :cpp:`ParmParse` variables will be
   printed out during :cpp:`amrex::Finalize` or
   :cpp:`ParmParse::QueryUnusedInputs`. The parameter can also be set by
   calling :cpp:`amrex::ParmParse::SetVerbose(int)`.

.. py:data:: amrex.device.verbose
   :type: int
   :value: 0

   This controls whether AMReX prints out GPU device properties such name,
   vendor, total memory size, etc. This is only relevant for GPU runs.

.. py:data:: amrex.max_gpu_streams
   :type: int
   :value: 4

   This controls the number of GPU streams used by AMReX. It's only relevant
   for GPU runs.

.. py:data:: amrex.omp_threads
   :type: string
   :value: system

   If OpenMP is enabled, this can be used to set the default number of
   threads. Possible values are ``system``, ``nosmt``, or an integer
   string. The special value ``nosmt`` can be used to avoid using threads
   for virtual cores (aka Hyperthreading or SMT), as is default in OpenMP,
   and instead only spawns threads equal to the number of physical cores in
   the system.  For the values ``system`` and ``nosmt``, the environment
   variable ``OMP_NUM_THREADS`` takes precedence. If the string can be
   converted to an integer, ``OMP_NUM_THREADS`` is ignored.

.. py:data:: amrex.memory_log
   :type: string
   :value: memlog

   This is the name of the memory log file when memory profiling is enabled.

Communication
-------------

.. py:data:: amrex.use_gpu_aware_mpi
   :type: bool
   :value: false

   For GPU runs, this controls the memory type used for AMReX's
   communication buffers. When this is true, AMReX uses GPU device memory
   for communication data in MPI function calls. When this is false, the
   data are placed in pinned memory. Note that this flag does not enable
   GPU-aware MPI by itself. Enabling GPU-aware MPI is system
   dependent. Users should consult their system's documentation for
   instructions on setting up the environment and linking to GPU-aware MPI
   libraries.

Distribution Mapping
--------------------

.. py:data:: DistributionMapping.verbose
   :type: int
   :value: 0

   This controls the verbosity level of :cpp:`DistributionMapping`
   functions.

.. py:data:: DistributionMapping.strategy
   :type: string
   :value: SFC

   This is the default :cpp:`DistributionMapping` strategy. Possible values
   are ``SFC``, ``KNAPSACK``, ``ROUNDROBIN``, or ``RRSFC``. Note that the
   default strategy can also be set by calling
   :cpp:`DistributionMapping::strategy(DistributionMapping::Strategy)`.

Embedded Boundary
-----------------

.. py:data:: eb2.max_grid_size
   :type: int
   :value: 64

   This parameter specifies the maximum grid size in AMReX's internal EB
   database, not the user's data.

.. py:data:: eb2.extend_domain_face
   :type: bool
   :value: true

   This controls the behavior of the embedded boundary outside the
   domain. If this is true, the embedded boundary outside the domain is
   extended perpendicularly from the domain face. Otherwise, it's generated
   with the user provided implicit function. Note that this parameter can be
   overridden by the user when calling :cpp:`amrex::EB2::Build` with the
   optional parameter ``bool extend_domain_face``.

.. py:data:: eb2.num_coarsen_opt
   :type: int
   :value: 0

   If it is greater than 0, this parameter can speed up the EB
   generation. It indicates that the search for EB can be performed on grids
   coarsened by this factor and then the EB information details will be
   generated on the original grids. However, the user should be aware that
   setting this parameter too high could result in erroneous results. Also
   note that this parameter can be overridden by the user when calling
   :cpp:`amrex::EB2::Build` with the optional parameter ``int
   num_coarsen_opt``.

.. py:data:: eb2.geom_type
   :type: string
   :value: [none]

   There are two versions of the `amrex::EB2::Build` function that can be
   used to build EB. One version is a function template that takes a user
   provided :cpp:`GeometryShop`, while the other uses :cpp:`ParmParse`
   parameters to build EB. For the latter version, this parameter specifies
   the type of the EB. Possible values include the following.

   all_regular
      The entire domain is regular without any EB objects.

   parser
      The embedded boundary is describe by :py:data:`eb2.parser_function`.

   stl
      The embedded boundary will be built using an STL file specified by
      :py:data:`eb2.stl_file`.

.. py:data:: eb2.parser_function
   :type: string
   :value: [none]

   When ``eb2.geom_type = parser``, this parameter is a parser function
   string that contains a math expression describing the surface of the EB.

   .. seealso:: Section :ref:`sec:basics:parser`.

.. py:data:: eb2.stl_file
   :type: string
   :value: [none]

   When ``eb2.geom_type = stl``, this is a required string parameter
   specifying the STL file name.

.. py:data:: eb2.stl_scale
   :type: amrex:Real
   :value: 1

   When building EB using STL, the triangles in the STL file will be scaled
   by the given value of this optional parameter.

.. py:data:: eb2.stl_center
   :type: amrex::Real array
   :value: 0 0 0

   When building EB using STL, this optional parameter specifies the shifted
   center. The original coordinates in the STL file will be shifted by the
   provided values.

.. py:data:: eb2.stl_reverse_normal
   :type: bool
   :value: false

   When building EB using STL, the normal direction of the triangles in the
   STL file will be reversed if this optional parameter is set to true.

.. py:data:: eb2.small_volfrac
   :type: amrex::Real
   :value: [depend on the type of amrex::Real]

   This parameter specifies the threshold for small cells that will be
   converted to covered cells. The default value is ``1.e-14`` if
   :cpp:`amrex::Real` is ``double``, or ``1.e-5`` if :cpp:`amrex::Real` is
   ``float``.

.. py:data:: eb2.cover_multiple_cuts
   :type: bool
   :value: false

   If this parameter is set to true, multi-cut cells will be converted to
   covered cells.

   .. tip::  Because AMReX currently does not support multi-cut cells, it
             would be a runtime error if multi-cut cells are left unfixed.

.. py:data:: eb2.maxiter
   :type: int
   :value: 32

   Fixing small and multi-cut cells is an iterative process. This parameter
   specifies the maximum number of iterations for the fix-up process.

Error Handling
--------------

By default AMReX installs a signal handler that will be run when a signal
such as segfault is received. You can also enable floating point exception
trapping. The signal handler will print out backtraces that can be useful
for debugging.

.. note:: Floating point exception trapping is not enabled by default,
   because compilers might generate optimized SIMD code that raises the
   exceptions.

.. py:data:: amrex.signal_handling
   :type: bool
   :value: true

   This controls whether AMReX should handle signals.

.. py:data:: amrex.handle_sigsegv
   :type: bool
   :value: true

   If both this flag and ``amrex.signal_handling`` are true, ``SIGSEGV``
   will be handled by AMReX.

.. py:data:: amrex.handle_sigterm
   :type: bool
   :value: false

   If both this flag and ``amrex.signal_handling`` are true, ``SIGTERM``
   will be handled by AMReX. This flag is false by default because this
   could generate lots of backtrace files on some batch systems that issue
   ``SIGTERM`` for jobs running out of wall clock time.

.. py:data:: amrex.handle_sigint
   :type: bool
   :value: true

   If both this flag and ``amrex.signal_handling`` are true, ``SIGINT``
   will be handled by AMReX.

.. py:data:: amrex.handle_sigabrt
   :type: bool
   :value: true

   If both this flag and ``amrex.signal_handling`` are true, ``SIGABGT``
   will be handled by AMReX.

.. py:data:: amrex.handle_sigfpe
   :type: bool
   :value: true

   If both this flag and ``amrex.signal_handling`` are true, ``SIGFPE``
   will be handled by AMReX.

   .. seealso::
      Use :py:data:`amrex.fpe_trap_invalid`, :py:data:`amrex.fpe_trap_zero`
      and :py:data:`amrex.fpe_trap_overflow` to enable ``FE_INVALID``,
      ``FE_DIVBYZERO`` and ``FE_OVERFLOW`` trapping, respectively.

.. py:data:: amrex.handle_sigill
   :type: bool
   :value: true

   If both this flag and ``amrex.signal_handling`` are true, ``SIGILL``
   will be handled by AMReX.

.. py:data:: amrex.throw_exception
   :type: bool
   :value: false

   If this flag is true and ``amrex.signal_handling`` is false,
   :cpp:`amrex::Abort` and :cpp:`amrex::Error` will throw
   :cpp:`std::runtime_error` instead of aborting immediately. Note that
   according the C++ standard, if an exception is thrown and not caught,
   :cpp:`std::terminate` will be called.

.. py:data:: amrex.fpe_trap_invalid
   :type: bool
   :value: false

    If ``SIGFPE`` is handled by AMReX and this flag is true, ``FE_INVALID``
    (e.g., ``0/0``) trapping will be enabled. This flag has no effect on
    Windows.

.. py:data:: amrex.fpe_trap_zero
   :type: bool
   :value: false

    If ``SIGFPE`` is handled by AMReX and this flag is true,
    ``FE_DIVBYZERO`` (e.g., ``1/0``) trapping will be enabled. This flag has
    no effect on Windows.

.. py:data:: amrex.fpe_trap_overflow
   :type: bool
   :value: false

    If ``SIGFPE`` is handled by AMReX and this flag is true, ``FE_OVERFLOW``
    (i.e., the result is too large to be representable) trapping will be
    enabled. This flag has no effect on Windows.

Extern
------

Hypre
^^^^^

These parameters are relevant only when Hypre support is enabled.

.. py:data:: amrex.init_hypre
   :type: bool
   :value: true

   This controls whether AMReX should call ``HYPRE_Init()`` during
   :cpp:`amrex::Initialize`.

.. py:data:: amrex.hypre_spgemm_use_vendor
   :type: bool
   :value: false

   This controls whether HYPRE should use the vendor's ``SpGemm``
   functionality.

.. py:data:: amrex.hypre_spmv_use_vendor
   :type: bool
   :value: false

   This controls whether HYPRE should use the vendor's ``SpMV``
   functionality.

.. py:data:: amrex.hypre_sptrans_use_vendor
   :type: bool
   :value: false

   This controls whether HYPRE should use the vendor's ``SpTrans``
   functionality.

.. _sec:inputs:geom:

Geometry
--------

All these parameters are optional for constructing a :ref:`Geometry <sec:basics:geom>`
object. There are only used if the information is not provided via function
arguments.

.. py:data:: geometry.coord_sys
   :type: int
   :value: 0

   This specifies the coordinate system type with valid values being 0
   (Cartesian), or 1 (cylindrical), or 2 (spherical).

.. py:data:: geometry.prob_lo
   :type: amrex::Real array
   :value: 0 0 0

   This specifies the position of the lower corner of the physical domain.

.. py:data:: geometry.prob_hi
   :type: amrex::Real array
   :value: [none]

   This specifies the position of the upper corner of the physical
   domain. If this is provided, :py:data:`geometry.prob_extent` will be
   ignored.

.. py:data:: geometry.prob_extent
   :type: amrex::Real array
   :value: [none]

   This specifies the length of the physical domain. If
   :py:data:`geometry.prob_hi` is provided, this will be ignored.

.. py:data:: geometry.is_periodic
   :type: int array
   :value: 0 0 0

   These integer parameters are boolean flags to indicate whether the domain
   is periodic in each direction. It's considered true (i.e., periodic) if
   its value is non-zero, and false (i.e., non-periodic) if its value is
   zero.

I/O
---

.. py:data:: amrex.async_out
   :type: bool
   :value: false

   If this is true, AMReX's native mesh and particle plotfiles will be
   written asynchronously by a background thread.

.. py:data:: amrex.async_out_nfiles
   :type: into
   :value: 64

   This is the maximum number of binary files on each AMR level that will be
   used when AMReX writes a plotfile asynchronously.

.. py:data:: vismf.verbose
   :type: int
   :value: 0

   This controls the verbosity level of :cpp:`VisMF` functions.

Memory
------

.. py:data:: amrex.the_arena_init_size
   :type: long
   :value: [system dependent]

   This controls the main memory arena's initial size in bytes. For CPU
   runs, the default is 0, whereas for GPU runs, the default is set at run
   time to 3/4 of the system's device memory.

   .. tip:: Since ``amrex v24.08``, instead of
            ``amrex.the_arena_init_size=10000000000``, one can use
            ``amrex.the_arena_init_size=10'000'000'000`` or
            ``amrex.the_arena_init_size=1e10`` to set :cpp:`ParmParse`
            integer parameters like this one.

.. py:data:: amrex.the_device_arena_init_size
   :type: long
   :value: 8388608 [8 MB]

   This controls the GPU device arena's initial size in bytes. For CPU runs,
   this is ignored. If the main arena uses the device memory (as opposed to
   managed memory), this parameter is also ignored.

.. py:data:: amrex.the_managed_arena_init_size
   :type: long
   :value: 8388608 [8 MB]

   This controls the managed device arena's initial size in bytes. For CPU
   runs, this is ignored. If the main arena uses the managed memory (as
   opposed to device memory), this parameter is also ignored.

.. py:data:: amrex.the_pinned_arena_init_size
   :type: long
   :value: [system dependent]

   This controls the pinned host memory arena's initial size in bytes. The
   default is 8 MB for CPU runs. For GPU runs it's set to half of the GPU
   device memory by default.

.. py:data:: amrex.the_comms_arena_init_size
   :type: long
   :value: 8388608 [8 MB]

   This controls the MPI communication memory arena's initial size in bytes.

.. py:data:: amrex.the_arena_release_threshold
   :type: long
   :value: LONG_MAX

   This controls the release threshold of the main arena.

.. py:data:: amrex.the_device_arena_release_threshold
   :type: long
   :value: LONG_MAX

   This controls the release threshold of the device arena.

.. py:data:: amrex.the_managed_arena_release_threshold
   :type: long
   :value: LONG_MAX

   This controls the release threshold of the managed arena.

.. py:data:: amrex.the_pinned_arena_release_threshold
   :type: long
   :value: LONG_MAX

   This controls the release threshold of the pinned arena.

.. py:data:: amrex.the_comms_arena_release_threshold
   :type: long
   :value: LONG_MAX

   This controls the release threshold of the communication arena.

.. py:data:: amrex.the_async_arena_release_threshold
   :type: long
   :value: LONG_MAX

   This controls the release threshold of the asynchronous arena. Note that
   this is only relevant for the CUDA (>= 11.2) and HIP backends that
   support stream-ordered memory allocator.

.. py:data:: amrex.the_arena_is_managed
   :type: bool
   :value: false

   This controls if AMReX uses the managed memory for the main arena. This
   is only relevant for GPU runs.

.. py:data:: amrex.abort_on_out_of_gpu_memory
   :type: bool
   :value: false

   This controls if AMReX should simply abort when the reported free device
   memory is less than the amount an arena is asked to allocate. Note that
   for managed memory it's possible to allocate more than the amount of free
   device memory available. However, the code will be very slow. This
   parameter is only relevant for GPU runs.

.. py:data:: amrex.mf.alloc_single_chunk
   :type: bool
   :value: false

   This controls if all the data in a :cpp:`FabArray` (including
   :cpp:`MultiFab`) are in a contiguous chunk of memory.

.. py:data:: amrex.vector_growth_factor
   :type: amrex::Real
   :value: 1.5

   This controls the growth factor of :cpp:`amrex::PODVector` and its
   derived classes such as :cpp:`amrex::Gpu::DeviceVector`,
   :cpp:`amrex::Gpu::ManagedVector`, etc. A smaller value can avoid wasting
   memory, but it may result in a performance penalty during resizing.

Particles
---------

.. py:data:: particles.do_tiling
   :type: bool
   :value: false

   This controls whether tiling is enabled for particle containers.

.. py:data:: particles.tile_size
   :type: int array
   :value: 1024000 8 8

   When tiling is enabled, this is the default tile size. Note that a big
   number like 1024000 effectively turns tiling off in that direction.

.. py:data:: particles.do_mem_efficient_sort
   :type: bool
   :value: true

   This parameter controls whether the more memory efficient method will be
   used for sorting particles.

.. py:data:: particles.particles_nfiles
   :type: int
   :value: 256

   This is the maximum number of binary files per level for a particle
   container when writing checkpoint and plot files for particles. The
   special value of ``-1`` indicates one file per process.

Tiling
------

.. py:data:: fabarray.mfiter_tile_size
   :type: int array
   :value: [build dependent]

   This is the default size for :ref:`tiling <sec:basics:mfiter>`. For GPU
   runs, it is disabled by default. For CPU runs, it is disabled by default
   in 1D and 2D, but enabled in 3D with a tile size of 8 in the y and
   z-directions.

.. py:data:: fabarray.comm_tile_size
   :type: int array
   :value: [build dependent]

   This is the default tiling size used in moving data in and out of the MPI
   communication buffer . It is disabled by default for GPU runs, but
   enabled for CPU runs with a tile size of 8 in the y and z-directions (if
   they exist).

Tiny Profiler
-------------

These parameters are ignored unless profiling with :cpp:`TinyProfiler` is
enabled.

.. py:data:: tiny_profiler.verbose
   :type: int
   :value: 0

   If this value is greater than 0, messages about entering or leaving
   profiled regions will be printed on the I/O process.

.. py:data:: tiny_profiler.print_threshold
  :type: double
  :value: 1.0

  In the profiling report, regions with very small run times are not listed
  individually. Instead, they are included in a section named "Other". This
  parameter specifies the maximum inclusive run time that the "Other"
  section can take in percent relative to the total run time.

.. py:data:: tiny_profiler.device_synchronize_around_region
  :type: bool
  :value: false

  This parameter is only relevant for GPU runs. If it is set to true, the
  current GPU stream is synchronized when entering and leaving a profiling
  region. Because GPU kernels are asynchronous, time measurements without
  synchronization could be misleading. Enabling this parameter can provide
  more accurate measurements. However, the added synchronization points,
  which are unnecessary for correctness, could potentially degrade the
  performance.

.. py:data:: tiny_profiler.enabled
   :type: bool
   :value: true

   .. versionadded:: 24.09
      Runtime parameter `tiny_profiler.enabled``.

   This parameter can be used to disable tiny profiling including
   :cpp:`CArena` memory profiling at run time.

.. py:data:: tiny_profiler.memprof_enabled
   :type: bool
   :value: true

   .. versionadded:: 24.09
      Runtime parameter ``tiny_profiler.memprof_enabled``.

   This parameter can be used to disable :cpp:`CArena` memory profiling at
   run time. If ``tiny_profiler.enabled`` is false, this parameter has no
   effects.

.. py:data:: tiny_profiler.output_file
   :type: string
   :value: [empty]

   .. versionadded:: 24.09
      Runtime parameter ``tiny_profiler.output_file``.

   If this parameter is empty, the output of tiny profiling is dumped on the
   default out stream of AMReX. If it's not empty, it specifies the file
   name for the output. Note that ``/dev/null`` is a special name that means
   no output.