From e6f4fb3bed0209c2da590462fb4c89501222ad1c Mon Sep 17 00:00:00 2001 From: Weiqun Zhang Date: Mon, 22 Jul 2024 18:41:40 -0700 Subject: [PATCH] Documentation: Runtime Parameters * Update the chapter on runtime parameters. * Add amrex prefix to a number of obscure parameters. This should not cause any backward compatibility issues. * For uncommon parameters, use query instread of queryAdd. So the user will not see them when print out all parameters. * Remove fab.init_snan because there is now amrex.init_snan. * Change some boolean parameters' type from int to bool. --- Docs/sphinx_documentation/source/Basics.rst | 8 +- .../source/InputsCheckpoint.rst | 18 - .../source/InputsComputeBackends.rst | 21 - .../source/InputsLoadBalancing.rst | 56 - .../source/InputsPlotFiles.rst | 18 - .../source/InputsProblemDefinition.rst | 41 - .../source/InputsTimeStepping.rst | 18 - .../source/Inputs_Chapter.rst | 15 - .../source/RuntimeParameters.rst | 1200 +++++++++++++++++ Docs/sphinx_documentation/source/index.rst | 9 +- Src/Amr/AMReX_Amr.H | 6 +- Src/Amr/AMReX_Amr.cpp | 72 +- Src/AmrCore/AMReX_AmrMesh.cpp | 41 +- Src/Base/AMReX.H | 20 +- Src/Base/AMReX.cpp | 63 +- Src/Base/AMReX_AsyncOut.cpp | 2 +- Src/Base/AMReX_DistributionMapping.cpp | 17 +- Src/Base/AMReX_FArrayBox.cpp | 24 +- Src/Base/AMReX_FabArrayBase.cpp | 24 +- Src/Base/AMReX_ForkJoin.cpp | 4 +- Src/Base/AMReX_Geometry.cpp | 6 +- Src/Base/AMReX_GpuDevice.cpp | 22 +- Src/Base/AMReX_IArrayBox.H | 1 - Src/Base/AMReX_IArrayBox.cpp | 2 - Src/Base/AMReX_Machine.cpp | 6 +- Src/Base/AMReX_MemPool.cpp | 10 +- Src/Base/AMReX_OpenMP.cpp | 2 +- Src/Base/AMReX_ParallelDescriptor.H | 2 +- Src/Base/AMReX_ParallelDescriptor.cpp | 10 +- Src/Base/AMReX_ParmParse.H | 32 + Src/Base/AMReX_ParmParse.cpp | 13 +- Src/Base/AMReX_TinyProfiler.H | 2 +- Src/Base/AMReX_TinyProfiler.cpp | 7 +- Src/Base/AMReX_VisMF.cpp | 24 +- Src/Base/AMReX_iMultiFab.cpp | 1 - Src/EB/AMReX_EB2.cpp | 4 +- Src/EB/AMReX_EB2_MultiGFab.cpp | 1 - Src/EB/AMReX_WriteEBSurface.cpp | 1 - .../HDF5/AMReX_WriteBinaryParticleDataHDF5.H | 2 +- Src/Extern/HYPRE/AMReX_HypreABecLap.H | 1 - Src/Particle/AMReX_ParticleContainerBase.cpp | 8 +- Src/Particle/AMReX_ParticleContainerI.H | 4 +- Src/Particle/AMReX_ParticleIO.H | 2 +- Src/Particle/AMReX_TracerParticles.cpp | 2 +- 44 files changed, 1427 insertions(+), 415 deletions(-) delete mode 100644 Docs/sphinx_documentation/source/InputsCheckpoint.rst delete mode 100644 Docs/sphinx_documentation/source/InputsComputeBackends.rst delete mode 100644 Docs/sphinx_documentation/source/InputsLoadBalancing.rst delete mode 100644 Docs/sphinx_documentation/source/InputsPlotFiles.rst delete mode 100644 Docs/sphinx_documentation/source/InputsProblemDefinition.rst delete mode 100644 Docs/sphinx_documentation/source/InputsTimeStepping.rst delete mode 100644 Docs/sphinx_documentation/source/Inputs_Chapter.rst create mode 100644 Docs/sphinx_documentation/source/RuntimeParameters.rst diff --git a/Docs/sphinx_documentation/source/Basics.rst b/Docs/sphinx_documentation/source/Basics.rst index da14577f26e..5b9b137e30c 100644 --- a/Docs/sphinx_documentation/source/Basics.rst +++ b/Docs/sphinx_documentation/source/Basics.rst @@ -278,6 +278,9 @@ runtime error that will abort the run. Math Expressions ---------------- +.. versionadded:: 24.08 + Math expression support in :cpp:`ParmParse`. + :cpp:`ParmParse` supports math expressions for integers and floating point numbers. For example, @@ -600,6 +603,9 @@ literals. Additionally, a floating point like number with a positive exponent may be accepted as an integer if it is reasonable to do so. For example, it's okay to have ``1.234e3``, but ``1.234e2`` is an error. + .. versionadded:: 24.08 + Support for ``'`` and ``e`` in :cpp:`IParser` integers. + .. _sec:basics:initialize: Initialize and Finalize @@ -1057,7 +1063,7 @@ an :cpp:`int` pointer or array specifying periodicity. If a :cpp:`RealBox` is no given in the first constructor, AMReX will construct one based on :cpp:`ParmParse` parameters, ``geometry.prob_lo`` / ``geometry.prob_hi`` / ``geometry.prob_extent``, where each of the parameter is an array of ``AMREX_SPACEDIM`` real numbers. -See the section on :ref:`sec:inputs:pd` for more details about how to specify these. +See the section on :ref:`sec:inputs:geom` for more details about how to specify these. The argument for coordinate system is an integer type with valid values being 0 (Cartesian), or 1 (cylindrical), or 2 (spherical). If it diff --git a/Docs/sphinx_documentation/source/InputsCheckpoint.rst b/Docs/sphinx_documentation/source/InputsCheckpoint.rst deleted file mode 100644 index 13bae0e467f..00000000000 --- a/Docs/sphinx_documentation/source/InputsCheckpoint.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _Chap:InputsCheckpoint: - -Checkpoint/Restart -================== - -The following inputs must be preceded by "amr" and control checkpoint/restart. - -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+==================+=======================================================================+=============+===========+ -| restart | If present, then the name of file to restart from | String | None | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| check_int | Frequency of checkpoint output; | Int | -1 | -| | if -1 then no checkpoints will be written | | | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| check_file | Prefix to use for checkpoint output | String | chk | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ - diff --git a/Docs/sphinx_documentation/source/InputsComputeBackends.rst b/Docs/sphinx_documentation/source/InputsComputeBackends.rst deleted file mode 100644 index 26e5d527508..00000000000 --- a/Docs/sphinx_documentation/source/InputsComputeBackends.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _Chap:InputsComputeBackends: - -Compute Backends -================ - -The following inputs must be preceded by ``amrex.`` and determine runtime options of CPU or GPU compute implementations. - -+------------------------+-----------------------------------------------------------------------+-------------+------------+ -| Parameter | Description | Type | Default | -+========================+=======================================================================+=============+============+ -| ``omp_threads`` | If OpenMP is enabled, this can be used to set the default number of | String | ``system`` | -| | threads. The special value ``nosmt`` can be used to avoid using | or Int | | -| | 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. For Integer values, | | | -| | ``OMP_NUM_THREADS`` is ignored. | | | -+------------------------+-----------------------------------------------------------------------+-------------+------------+ - -For GPU-specific parameters, see also the :ref:`GPU chapter `. diff --git a/Docs/sphinx_documentation/source/InputsLoadBalancing.rst b/Docs/sphinx_documentation/source/InputsLoadBalancing.rst deleted file mode 100644 index ea7ff2ebaae..00000000000 --- a/Docs/sphinx_documentation/source/InputsLoadBalancing.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _Chap:InputsLoadBalancing: - -Gridding and Load Balancing -=========================== - -The following inputs must be preceded by "amr" and determine how we create the grids and how often we regrid. - -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| Parameter | Description | Type | Default | -+========================+=======================================================================+=============+===========+ -| regrid_int | How often to regrid (in number of steps at level 0) | Int | -1 | -| | if regrid_int = -1 then no regridding will occur | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| max_grid_size_x | Maximum number of cells at level 0 in each grid in x-direction | Int | 32 | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| max_grid_size_y | Maximum number of cells at level 0 in each grid in y-direction | Int | 32 | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| max_grid_size_z | Maximum number of cells at level 0 in each grid in z-direction | Int | 32 | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| blocking_factor_x | Each grid must be divisible by blocking_factor_x in x-direction | Int | 8 | -| | (must be 1 or power of 2) | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| blocking_factor_y | Each grid must be divisible by blocking_factor_y in y-direction | Int | 8 | -| | (must be 1 or power of 2) | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| blocking_factor_z | Each grid must be divisible by blocking_factor_z in z-direction | Int | 8 | -| | (must be 1 or power of 2) | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| refine_grid_layout | Split grids in half until the number of grids is no less than the | Bool | true | -| | number of procs. (Will be overridden if refine_grid_layout_[x,y,z] | | | -| | is specified) | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| refine_grid_layout_x | Allow grids to be split in the x-dimension when refining the layout. | Int | 1 | -| | (1 to allow or 0 to disallow) | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| refine_grid_layout_y | Allow grids to be split in the y-dimension when refining the layout. | Int | 1 | -| | (1 to allow or 0 to disallow) | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| refine_grid_layout_z | Allow grids to be split in the z-dimension when refining the layout. | Int | 1 | -| | (1 to allow or 0 to disallow) | | | -+------------------------+-----------------------------------------------------------------------+-------------+-----------+ - -The following inputs must be preceded by "particles". - -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ -| Parameter | Description | Type | Default | -+===================+=======================================================================+=============+===========+ -| max_grid_size_x | Maximum number of cells at level 0 in each grid in x-direction | Int | 32 | -| | for grids in the ParticleBoxArray if dual_grid is true | | | -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ -| max_grid_size_y | Maximum number of cells at level 0 in each grid in y-direction | Int | 32 | -| | for grids in the ParticleBoxArray if dual_grid is true | | | -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ -| max_grid_size_z | Maximum number of cells at level 0 in each grid in z-direction | Int | 32 | -| | for grids in the ParticleBoxArray if dual_grid is true. | | | -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ diff --git a/Docs/sphinx_documentation/source/InputsPlotFiles.rst b/Docs/sphinx_documentation/source/InputsPlotFiles.rst deleted file mode 100644 index 9e8789a90ac..00000000000 --- a/Docs/sphinx_documentation/source/InputsPlotFiles.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _Chap:InputsPlotfiles: - -Plotfiles and Other Output -========================== - -The following inputs must be preceded by "amr" and control the frequency and naming of plotfile generation, as well -as whether a plotfile should be written out immediately after restarting a simulation. - -+---------------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+=====================+=======================================================================+=============+===========+ -| plot_int | Frequency of plotfile output; | Int | -1 | -| | if -1 then no plotfiles will be written | | | -+---------------------+-----------------------------------------------------------------------+-------------+-----------+ -| plotfile_on_restart | Should we write a plotfile when we restart (only used if plot_int>0) | Bool | 0 (false) | -+---------------------+-----------------------------------------------------------------------+-------------+-----------+ -| plot_file | Prefix to use for plotfile output | String | plt | -+---------------------+-----------------------------------------------------------------------+-------------+-----------+ diff --git a/Docs/sphinx_documentation/source/InputsProblemDefinition.rst b/Docs/sphinx_documentation/source/InputsProblemDefinition.rst deleted file mode 100644 index 3e67ffdb38e..00000000000 --- a/Docs/sphinx_documentation/source/InputsProblemDefinition.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _sec:inputs:pd: - -Problem Definition -================== - -The following inputs must be preceded by "amr." - -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+===================+=======================================================================+=============+===========+ -| n_cell | Number of cells at level 0 in each coordinate direction | Int Int Int | None | -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ -| max_level | Maximum level of refinement allowed (0 when single-level) | Int | None | -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ - -The following inputs must be preceded by "geometry." - -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+=================+=======================================================================+=============+===========+ -| coord_sys | 0 for Cartesian | Int | 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| is_periodic | 1 for true, 0 for false (one value for each coordinate direction) | Ints | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| prob_lo | Low corner of physical domain (physical not index space) | Reals | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| prob_hi | High corner of physical domain (physical not index space) | Reals | None | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| prob_extent | Extent of physical domain (physical not index space) | Reals | None | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ - -Note that internally ``prob_lo`` and ``prob_hi`` are the variables carried by the ``Geometry`` class. -In the inputs file (or command line), one can specify -1) ``geometry.prob_hi`` only or -2) ``geometry.prob_extent`` only or -3) ``geometry.prob_lo`` and ``geometry.prob_hi`` or -4) ``geometry.prob_lo`` and ``geometry.prob_extent``. -If ``geometry.prob_lo`` is not specified then it will be 0 in each coordinate direction. -If ``geometry.prob_extent`` is specified (and ``geometry.prob_hi`` is not) then internally -"prob_hi" will be set to "prob_lo" + "prob_extent". - diff --git a/Docs/sphinx_documentation/source/InputsTimeStepping.rst b/Docs/sphinx_documentation/source/InputsTimeStepping.rst deleted file mode 100644 index 144ef0fe6dd..00000000000 --- a/Docs/sphinx_documentation/source/InputsTimeStepping.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. sec:InputsTimeStepping: - -Time Stepping -============= - -The following inputs must be preceded by "amr." Note that if both are specified, both criteria -are used and the simulation still stop when the first criterion is hit. In the case of unsteady flow, -the simulation will stop when either the number of steps reaches max_step or time reaches stop_time. -In the case of unsteady flow, the simulation will stop when either the tolerance (difference between -subsequent steps) is reached or the number of iterations reaches the maximum number specified. - -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+==================+=======================================================================+=============+===========+ -| max_step | Maximum number of time steps to take | Int | -1 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| stop_time | Maximum time to reach | Real | -1.0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ diff --git a/Docs/sphinx_documentation/source/Inputs_Chapter.rst b/Docs/sphinx_documentation/source/Inputs_Chapter.rst deleted file mode 100644 index 43ead40b3c6..00000000000 --- a/Docs/sphinx_documentation/source/Inputs_Chapter.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _Chap:Inputs: - -Run-time Inputs -=============== - -.. toctree:: - :maxdepth: 1 - - InputsProblemDefinition - InputsTimeStepping - InputsLoadBalancing - InputsComputeBackends - InputsPlotFiles - InputsCheckpoint - diff --git a/Docs/sphinx_documentation/source/RuntimeParameters.rst b/Docs/sphinx_documentation/source/RuntimeParameters.rst new file mode 100644 index 00000000000..460a68e837b --- /dev/null +++ b/Docs/sphinx_documentation/source/RuntimeParameters.rst @@ -0,0 +1,1200 @@ + +.. _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-1`` and values after the first + ``max_level-1`` 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] + +.. 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 plotfile. 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`, :cpp:`PODVectors`, + :cpp:`Gpu::DeviceVector`, 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, 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. + +.. 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 ` +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 be 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 `. 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. + diff --git a/Docs/sphinx_documentation/source/index.rst b/Docs/sphinx_documentation/source/index.rst index d302af07468..203545cf40a 100644 --- a/Docs/sphinx_documentation/source/index.rst +++ b/Docs/sphinx_documentation/source/index.rst @@ -57,7 +57,7 @@ Documentation on migration from BoxLib is available in the AMReX repository at D Visualization_Chapter Post_Processing_Chapter Debugging - Inputs_Chapter + RuntimeParameters AMReX_Profiling_Tools_Chapter External_Profiling_Tools_Chapter External_Frameworks_Chapter @@ -69,13 +69,6 @@ Documentation on migration from BoxLib is available in the AMReX repository at D :maxdepth: 1 :caption: API -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - The copyright notice of AMReX is included in the AMReX home directory as README.txt. Your use of this software is under the 3-clause BSD license -- the license agreement is included in the diff --git a/Src/Amr/AMReX_Amr.H b/Src/Amr/AMReX_Amr.H index 3d9df9484ec..627285f9d9a 100644 --- a/Src/Amr/AMReX_Amr.H +++ b/Src/Amr/AMReX_Amr.H @@ -181,7 +181,7 @@ public: static void fillDerivePlotVarList (); static void fillDeriveSmallPlotVarList (); - static void setComputeNewDtOnRegrid (int flag) { compute_new_dt_on_regrid = flag; } + static void setComputeNewDtOnRegrid (bool flag) { compute_new_dt_on_regrid = flag; } static void Initialize (); static void Finalize (); @@ -430,7 +430,7 @@ protected: int small_plot_int; //!< How often small plotfile (# of time steps) Real small_plot_per; //!< How often small plotfile (in units of time) Real small_plot_log_per; //!< How often small plotfile (in units of log10(time)) - int write_plotfile_with_checkpoint; //!< Write out a plotfile whenever we checkpoint + bool write_plotfile_with_checkpoint; //!< Write out a plotfile whenever we checkpoint int file_name_digits; //!< How many digits to use in the plotfile and checkpoint names int message_int; //!< How often checking messages touched by user, such as "stop_run" std::string plot_file_root; //!< Root name of plotfile. @@ -473,7 +473,7 @@ protected: static Vector initial_ba; //! Array of BoxArrays read in to externally define grid hierarchy at each regrid static Vector regrid_ba; - static int compute_new_dt_on_regrid; + static bool compute_new_dt_on_regrid; #if defined(AMREX_USE_SENSEI_INSITU) && !defined(AMREX_NO_SENSEI_AMR_INST) static AmrInSituBridge *insitu_bridge; diff --git a/Src/Amr/AMReX_Amr.cpp b/Src/Amr/AMReX_Amr.cpp index 8df6f5cd423..2f8c110359b 100644 --- a/Src/Amr/AMReX_Amr.cpp +++ b/Src/Amr/AMReX_Amr.cpp @@ -59,7 +59,7 @@ bool Amr::first_plotfile; bool Amr::first_smallplotfile; Vector Amr::initial_ba; Vector Amr::regrid_ba; -int Amr::compute_new_dt_on_regrid; +bool Amr::compute_new_dt_on_regrid; #if defined(AMREX_USE_SENSEI_INSITU) && !defined(AMREX_NO_SENSEI_AMR_INST) AmrInSituBridge* Amr::insitu_bridge; #endif @@ -80,12 +80,12 @@ namespace #endif bool plot_files_output; int checkpoint_nfiles; - int regrid_on_restart; - int force_regrid_level_zero; - int use_efficient_regrid; - int plotfile_on_restart; - int insitu_on_restart; - int checkpoint_on_restart; + bool regrid_on_restart; + bool force_regrid_level_zero; + bool use_efficient_regrid; + bool plotfile_on_restart; + bool insitu_on_restart; + bool checkpoint_on_restart; bool checkpoint_files_output; bool precreateDirectories; bool prereadFAHeaders; @@ -117,14 +117,14 @@ Amr::Initialize () #endif plot_files_output = true; checkpoint_nfiles = 64; - regrid_on_restart = 0; - force_regrid_level_zero = 0; - use_efficient_regrid = 0; - plotfile_on_restart = 0; - insitu_on_restart = 0; - checkpoint_on_restart = 0; + regrid_on_restart = false; + force_regrid_level_zero = false; + use_efficient_regrid = false; + plotfile_on_restart = false; + insitu_on_restart = false; + checkpoint_on_restart = false; checkpoint_files_output = true; - compute_new_dt_on_regrid = 0; + compute_new_dt_on_regrid = false; precreateDirectories = true; prereadFAHeaders = true; plot_headerversion = VisMF::Header::Version_v1; @@ -257,17 +257,17 @@ Amr::InitAmr () // pp.queryAdd("regrid_on_restart",regrid_on_restart); pp.queryAdd("force_regrid_level_zero",force_regrid_level_zero); - pp.queryAdd("use_efficient_regrid",use_efficient_regrid); + pp.query("use_efficient_regrid",use_efficient_regrid); pp.queryAdd("plotfile_on_restart",plotfile_on_restart); - pp.queryAdd("insitu_on_restart",insitu_on_restart); + pp.query("insitu_on_restart",insitu_on_restart); pp.queryAdd("checkpoint_on_restart",checkpoint_on_restart); pp.queryAdd("compute_new_dt_on_regrid",compute_new_dt_on_regrid); - pp.queryAdd("mffile_nstreams", mffile_nstreams); + pp.query("mffile_nstreams", mffile_nstreams); #ifndef AMREX_NO_PROBINIT - pp.queryAdd("probinit_natonce", probinit_natonce); + pp.query("probinit_natonce", probinit_natonce); probinit_natonce = std::max(1, std::min(ParallelDescriptor::NProcs(), probinit_natonce)); #endif @@ -502,13 +502,13 @@ Amr::InitAmr () } loadbalance_with_workestimates = 0; - pp.queryAdd("loadbalance_with_workestimates", loadbalance_with_workestimates); + pp.query("loadbalance_with_workestimates", loadbalance_with_workestimates); loadbalance_level0_int = 2; - pp.queryAdd("loadbalance_level0_int", loadbalance_level0_int); + pp.query("loadbalance_level0_int", loadbalance_level0_int); loadbalance_max_fac = 1.5; - pp.queryAdd("loadbalance_max_fac", loadbalance_max_fac); + pp.query("loadbalance_max_fac", loadbalance_max_fac); } int @@ -2008,7 +2008,7 @@ Amr::timeStep (int level, // if (plotfile_on_restart && ! (restart_chkfile.empty()) ) { - plotfile_on_restart = 0; + plotfile_on_restart = false; writePlotFile(); } // @@ -2610,7 +2610,7 @@ Amr::regrid (int lbase, // // If use_efficient_regrid flag is set and grids are unchanged, then don't do anything more here. // - if (use_efficient_regrid == 1 && grids_unchanged ) + if (use_efficient_regrid == true && grids_unchanged ) { if (verbose > 0) { amrex::Print() << "Regridding at level lbase = " << lbase @@ -2673,7 +2673,7 @@ Amr::regrid (int lbase, { // // Init with data from old structure then remove old structure. - // NOTE: The init function may use a filPatch from the old level, + // NOTE: The init function may use a fillPatch from the old level, // which therefore needs remain in the hierarchy during the call. // a->init(*amr_level[lev]); @@ -2820,7 +2820,7 @@ Amr::InstallNewDistributionMap (int lev, const DistributionMapping& newdm) void Amr::regrid_level_0_on_restart() { - regrid_on_restart = 0; + regrid_on_restart = false; // // Coarsening before we split the grids ensures that each resulting // grid will have an even number of cells in each direction. @@ -3121,6 +3121,7 @@ Amr::initSubcycle () BL_PROFILE("Amr::initSubcycle()"); ParmParse pp("amr"); sub_cycle = true; + subcycling_mode = "Auto"; if (pp.contains("nosub")) { if (verbose) { @@ -3136,11 +3137,8 @@ Amr::initSubcycle () } subcycling_mode = "None"; } - else - { - subcycling_mode = "Auto"; - pp.queryAdd("subcycling_mode",subcycling_mode); - } + + pp.queryAdd("subcycling_mode",subcycling_mode); if (subcycling_mode == "None") { @@ -3292,25 +3290,25 @@ Amr::initPltAndChk () } } - write_plotfile_with_checkpoint = 1; + write_plotfile_with_checkpoint = true; pp.queryAdd("write_plotfile_with_checkpoint",write_plotfile_with_checkpoint); stream_max_tries = 4; - pp.queryAdd("stream_max_tries",stream_max_tries); + pp.query("stream_max_tries",stream_max_tries); stream_max_tries = std::max(stream_max_tries, 1); abort_on_stream_retry_failure = false; - pp.queryAdd("abort_on_stream_retry_failure",abort_on_stream_retry_failure); + pp.query("abort_on_stream_retry_failure",abort_on_stream_retry_failure); - pp.queryAdd("precreateDirectories", precreateDirectories); - pp.queryAdd("prereadFAHeaders", prereadFAHeaders); + pp.query("precreateDirectories", precreateDirectories); + pp.query("prereadFAHeaders", prereadFAHeaders); int phvInt(plot_headerversion), chvInt(checkpoint_headerversion); - pp.queryAdd("plot_headerversion", phvInt); + pp.query("plot_headerversion", phvInt); if(phvInt != plot_headerversion) { plot_headerversion = static_cast (phvInt); } - pp.queryAdd("checkpoint_headerversion", chvInt); + pp.query("checkpoint_headerversion", chvInt); if(chvInt != checkpoint_headerversion) { checkpoint_headerversion = static_cast (chvInt); } diff --git a/Src/AmrCore/AMReX_AmrMesh.cpp b/Src/AmrCore/AMReX_AmrMesh.cpp index 57b46ca686f..9dd03d51e45 100644 --- a/Src/AmrCore/AMReX_AmrMesh.cpp +++ b/Src/AmrCore/AMReX_AmrMesh.cpp @@ -78,7 +78,9 @@ AmrMesh::InitAmrMesh (int max_level_in, const Vector& n_cell_in, { ParmParse pp("amr"); - pp.queryAdd("v",verbose); + if (! pp.query("verbose", "v", verbose)) { + pp.add("verbose", verbose); + } if (max_level_in == -1) { pp.get("max_level", max_level); @@ -89,28 +91,17 @@ AmrMesh::InitAmrMesh (int max_level_in, const Vector& n_cell_in, int nlev = max_level + 1; - blocking_factor.resize(nlev); - max_grid_size.resize(nlev); - n_error_buf.resize(nlev); + AmrInfo def_amr_info; + + blocking_factor.resize(nlev, def_amr_info.blocking_factor.back()); + max_grid_size.resize (nlev, def_amr_info.max_grid_size.back()); + n_error_buf.resize (nlev, def_amr_info.n_error_buf.back()); + ref_ratio.resize (nlev, def_amr_info.ref_ratio.back()); geom.resize(nlev); dmap.resize(nlev); grids.resize(nlev); - for (int i = 0; i < nlev; ++i) { - n_error_buf[i] = IntVect{AMREX_D_DECL(1,1,1)}; - blocking_factor[i] = IntVect{AMREX_D_DECL(8,8,8)}; - max_grid_size[i] = (AMREX_SPACEDIM == 2) ? IntVect{AMREX_D_DECL(128,128,128)} - : IntVect{AMREX_D_DECL(32,32,32)}; - } - - // Make the default ref_ratio = 2 for all levels. - ref_ratio.resize(max_level); - for (int i = 0; i < max_level; ++i) - { - ref_ratio[i] = 2 * IntVect::TheUnitVector(); - } - pp.queryAdd("n_proper",n_proper); pp.queryAdd("grid_eff",grid_eff); int cnt = pp.countval("n_error_buf"); @@ -371,11 +362,15 @@ AmrMesh::InitAmrMesh (int max_level_in, const Vector& n_cell_in, { pp.queryAdd("refine_grid_layout", refine_grid_layout); - refine_grid_layout_dims = IntVect(refine_grid_layout); - AMREX_D_TERM(pp.queryAdd("refine_grid_layout_x", refine_grid_layout_dims[0]);, - pp.queryAdd("refine_grid_layout_y", refine_grid_layout_dims[1]);, - pp.queryAdd("refine_grid_layout_z", refine_grid_layout_dims[2])); - + std::array tmp{AMREX_D_DECL(refine_grid_layout, + refine_grid_layout, + refine_grid_layout)}; + AMREX_D_TERM(pp.query("refine_grid_layout_x", tmp[0]);, + pp.query("refine_grid_layout_y", tmp[1]);, + pp.query("refine_grid_layout_z", tmp[2])); + for (int idim = 0; idim < AMREX_SPACEDIM; ++idim) { + refine_grid_layout_dims[idim] = tmp[idim]; + } refine_grid_layout = refine_grid_layout_dims != 0; } diff --git a/Src/Base/AMReX.H b/Src/Base/AMReX.H index ba131a9d94e..4094d4f2ff2 100644 --- a/Src/Base/AMReX.H +++ b/Src/Base/AMReX.H @@ -49,23 +49,23 @@ namespace amrex extern AMREX_EXPORT int verbose; - extern AMREX_EXPORT int signal_handling; - extern AMREX_EXPORT int handle_sigsegv; - extern AMREX_EXPORT int handle_sigterm; - extern AMREX_EXPORT int handle_sigint; - extern AMREX_EXPORT int handle_sigabrt; - extern AMREX_EXPORT int handle_sigfpe; + extern AMREX_EXPORT bool signal_handling; + extern AMREX_EXPORT bool handle_sigsegv; + extern AMREX_EXPORT bool handle_sigterm; + extern AMREX_EXPORT bool handle_sigint; + extern AMREX_EXPORT bool handle_sigabrt; + extern AMREX_EXPORT bool handle_sigfpe; - extern AMREX_EXPORT int call_addr2line; - extern AMREX_EXPORT int throw_exception; + extern AMREX_EXPORT bool call_addr2line; + extern AMREX_EXPORT bool throw_exception; - extern AMREX_EXPORT int regtest_reduction; + extern AMREX_EXPORT bool regtest_reduction; extern AMREX_EXPORT std::ostream* osout; extern AMREX_EXPORT std::ostream* oserr; extern AMREX_EXPORT ErrorHandler error_handler; - extern AMREX_EXPORT int abort_on_unused_inputs; + extern AMREX_EXPORT bool abort_on_unused_inputs; extern AMREX_EXPORT bool init_snan; } diff --git a/Src/Base/AMReX.cpp b/Src/Base/AMReX.cpp index 67a3e39aa58..b4aa8f44909 100644 --- a/Src/Base/AMReX.cpp +++ b/Src/Base/AMReX.cpp @@ -99,17 +99,17 @@ namespace system { std::string exename; int verbose = 1; - int signal_handling; - int handle_sigsegv; - int handle_sigterm; - int handle_sigint; - int handle_sigabrt; - int handle_sigfpe; - int handle_sigill; - int call_addr2line; - int throw_exception; - int regtest_reduction; - int abort_on_unused_inputs = 0; + bool signal_handling; + bool handle_sigsegv; + bool handle_sigterm; + bool handle_sigint; + bool handle_sigabrt; + bool handle_sigfpe; + bool handle_sigill; + bool call_addr2line; + bool throw_exception; + bool regtest_reduction; + bool abort_on_unused_inputs = false; std::ostream* osout = &std::cout; std::ostream* oserr = &std::cerr; ErrorHandler error_handler = nullptr; @@ -148,11 +148,11 @@ namespace { #ifdef AMREX_USE_HYPRE namespace { - int init_hypre = 1; + bool init_hypre = true; #if defined(HYPRE_USING_CUDA) || defined(HYPRE_USING_HIP) - int hypre_spgemm_use_vendor = 0; - int hypre_spmv_use_vendor = 0; - int hypre_sptrans_use_vendor = 0; + bool hypre_spgemm_use_vendor = false; + bool hypre_spmv_use_vendor = false; + bool hypre_sptrans_use_vendor = false; #endif } #endif @@ -336,16 +336,16 @@ amrex::Initialize (int& argc, char**& argv, bool build_parm_parse, { system::exename.clear(); // system::verbose = 0; - system::regtest_reduction = 0; - system::signal_handling = 1; - system::handle_sigsegv = 1; - system::handle_sigterm = 0; - system::handle_sigint = 1; - system::handle_sigabrt = 1; - system::handle_sigfpe = 1; - system::handle_sigill = 1; - system::call_addr2line = 1; - system::throw_exception = 0; + system::regtest_reduction = false; + system::signal_handling = true; + system::handle_sigsegv = true; + system::handle_sigterm = false; + system::handle_sigint = true; + system::handle_sigabrt = true; + system::handle_sigfpe = true; + system::handle_sigill = true; + system::call_addr2line = true; + system::throw_exception = false; system::osout = &a_osout; system::oserr = &a_oserr; system::error_handler = a_errhandler; @@ -451,8 +451,9 @@ amrex::Initialize (int& argc, char**& argv, bool build_parm_parse, { ParmParse pp("amrex"); - pp.queryAdd("v", system::verbose); - pp.queryAdd("verbose", system::verbose); + if (! pp.query("verbose", "v", system::verbose)) { + pp.add("verbose", system::verbose); + } pp.queryAdd("init_snan", system::init_snan); } @@ -511,10 +512,10 @@ amrex::Initialize (int& argc, char**& argv, bool build_parm_parse, { ParmParse pp("amrex"); - pp.queryAdd("regtest_reduction", system::regtest_reduction); + pp.query("regtest_reduction", system::regtest_reduction); pp.queryAdd("signal_handling", system::signal_handling); pp.queryAdd("throw_exception", system::throw_exception); - pp.queryAdd("call_addr2line", system::call_addr2line); + pp.query("call_addr2line", system::call_addr2line); pp.queryAdd("abort_on_unused_inputs", system::abort_on_unused_inputs); #ifdef AMREX_USE_SYCL @@ -574,7 +575,7 @@ amrex::Initialize (int& argc, char**& argv, bool build_parm_parse, if (system::handle_sigfpe) { - int invalid = 0, divbyzero=0, overflow=0; + bool invalid = false, divbyzero=false, overflow=false; pp.queryAdd("fpe_trap_invalid", invalid); pp.queryAdd("fpe_trap_zero", divbyzero); pp.queryAdd("fpe_trap_overflow", overflow); @@ -604,7 +605,7 @@ amrex::Initialize (int& argc, char**& argv, bool build_parm_parse, #if defined(__APPLE__) && defined(__aarch64__) if (system::handle_sigill) { - int invalid = 0, divbyzero=0, overflow=0; + bool invalid = false, divbyzero=false, overflow=false; pp.queryAdd("fpe_trap_invalid", invalid); pp.queryAdd("fpe_trap_zero", divbyzero); pp.queryAdd("fpe_trap_overflow", overflow); diff --git a/Src/Base/AMReX_AsyncOut.cpp b/Src/Base/AMReX_AsyncOut.cpp index b235baa6580..3835c0b137e 100644 --- a/Src/Base/AMReX_AsyncOut.cpp +++ b/Src/Base/AMReX_AsyncOut.cpp @@ -10,7 +10,7 @@ namespace amrex::AsyncOut { namespace { -int s_asyncout = false; +bool s_asyncout = false; int s_noutfiles = 64; MPI_Comm s_comm = MPI_COMM_NULL; diff --git a/Src/Base/AMReX_DistributionMapping.cpp b/Src/Base/AMReX_DistributionMapping.cpp index 958f7ef9ec6..cfe16b346a1 100644 --- a/Src/Base/AMReX_DistributionMapping.cpp +++ b/Src/Base/AMReX_DistributionMapping.cpp @@ -118,14 +118,15 @@ DistributionMapping::Initialize () ParmParse pp("DistributionMapping"); - pp.queryAdd("v" , verbose); - pp.queryAdd("verbose", verbose); - pp.queryAdd("efficiency", max_efficiency); - pp.queryAdd("sfc_threshold", sfc_threshold); - pp.queryAdd("node_size", node_size); - pp.queryAdd("verbose_mapper", flag_verbose_mapper); - - std::string theStrategy; + if (! pp.query("verbose", "v", verbose)) { + pp.add("verbose", verbose); + } + pp.query("efficiency", max_efficiency); + pp.query("sfc_threshold", sfc_threshold); + pp.query("node_size", node_size); + pp.query("verbose_mapper", flag_verbose_mapper); + + std::string theStrategy("SFC"); if (pp.query("strategy", theStrategy)) { diff --git a/Src/Base/AMReX_FArrayBox.cpp b/Src/Base/AMReX_FArrayBox.cpp index 023cfff2738..3341c3da5dd 100644 --- a/Src/Base/AMReX_FArrayBox.cpp +++ b/Src/Base/AMReX_FArrayBox.cpp @@ -24,10 +24,8 @@ bool FArrayBox::initialized = false; #if defined(AMREX_DEBUG) || defined(AMREX_TESTING) bool FArrayBox::do_initval = true; -bool FArrayBox::init_snan = true; #else bool FArrayBox::do_initval = false; -bool FArrayBox::init_snan = false; #endif Real FArrayBox::initval; @@ -161,22 +159,7 @@ FArrayBox::initVal () noexcept runon = RunOn::Cpu; #endif - if (init_snan) { -#if defined(AMREX_USE_GPU) - if (runon == RunOn::Gpu) - { - amrex::ParallelFor(s, [=] AMREX_GPU_DEVICE (Long i) noexcept - { - p[i] = std::numeric_limits::signaling_NaN(); - }); - Gpu::streamSynchronize(); - } - else -#endif - { - amrex_array_init_snan(p, s); - } - } else if (do_initval) { + if (do_initval) { const Real x = initval; AMREX_HOST_DEVICE_PARALLEL_FOR_1D_FLAG (runon, s, i, { @@ -438,9 +421,8 @@ FArrayBox::Initialize () ? std::numeric_limits::quiet_NaN() : std::numeric_limits::max(); - pp.queryAdd("initval", initval); - pp.queryAdd("do_initval", do_initval); - pp.queryAdd("init_snan", init_snan); + pp.query("initval", initval); + pp.query("do_initval", do_initval); amrex::ExecOnFinalize(FArrayBox::Finalize); } diff --git a/Src/Base/AMReX_FabArrayBase.cpp b/Src/Base/AMReX_FabArrayBase.cpp index d8820e97e6f..00a0778cd43 100644 --- a/Src/Base/AMReX_FabArrayBase.cpp +++ b/Src/Base/AMReX_FabArrayBase.cpp @@ -27,10 +27,7 @@ namespace amrex { -// -// Set default values in Initialize()!!! -// -int FabArrayBase::MaxComp; +int FabArrayBase::MaxComp = 25; #if defined(AMREX_USE_GPU) @@ -99,11 +96,6 @@ FabArrayBase::Initialize () if (initialized) { return; } initialized = true; - // - // Set default values here!!! - // - FabArrayBase::MaxComp = 25; - ParmParse pp("fabarray"); Vector tilesize(AMREX_SPACEDIM); @@ -112,13 +104,25 @@ FabArrayBase::Initialize () { for (int i=0; i{AMREX_D_DECL(FabArrayBase::mfiter_tile_size[0], + FabArrayBase::mfiter_tile_size[1], + FabArrayBase::mfiter_tile_size[2])}); + } if (pp.queryarr("comm_tile_size", tilesize, 0, AMREX_SPACEDIM)) { for (int i=0; i{AMREX_D_DECL(FabArrayBase::comm_tile_size[0], + FabArrayBase::comm_tile_size[1], + FabArrayBase::comm_tile_size[2])}); + } - pp.queryAdd("maxcomp", FabArrayBase::MaxComp); + pp.query("maxcomp", FabArrayBase::MaxComp); if (MaxComp < 1) { MaxComp = 1; diff --git a/Src/Base/AMReX_ForkJoin.cpp b/Src/Base/AMReX_ForkJoin.cpp index f0cc03ae04b..ce51203ab35 100644 --- a/Src/Base/AMReX_ForkJoin.cpp +++ b/Src/Base/AMReX_ForkJoin.cpp @@ -68,8 +68,8 @@ ForkJoin::ForkJoin (const Vector &task_rank_pct) void ForkJoin::init(const Vector &task_rank_n) { - ParmParse pp("forkjoin"); - pp.queryAdd("verbose", flag_verbose); + ParmParse pp("amrex.forkjoin"); + pp.query("verbose", flag_verbose); const auto task_n = task_rank_n.size(); AMREX_ALWAYS_ASSERT_WITH_MESSAGE(task_n > 0, diff --git a/Src/Base/AMReX_Geometry.cpp b/Src/Base/AMReX_Geometry.cpp index 4cc374d9c3d..4b63f29fdd8 100644 --- a/Src/Base/AMReX_Geometry.cpp +++ b/Src/Base/AMReX_Geometry.cpp @@ -15,16 +15,14 @@ namespace amrex { std::ostream& -operator<< (std::ostream& os, - const Geometry& g) +operator<< (std::ostream& os, const Geometry& g) { os << (CoordSys&) g << g.ProbDomain() << g.Domain() << 'P' << IntVect(g.isPeriodic()); return os; } std::istream& -operator>> (std::istream& is, - Geometry& g) +operator>> (std::istream& is, Geometry& g) { is >> (CoordSys&) g >> g.prob_domain >> g.domain; diff --git a/Src/Base/AMReX_GpuDevice.cpp b/Src/Base/AMReX_GpuDevice.cpp index fa190a22c1c..5e63646121d 100644 --- a/Src/Base/AMReX_GpuDevice.cpp +++ b/Src/Base/AMReX_GpuDevice.cpp @@ -155,9 +155,9 @@ Device::Initialize () max_gpu_streams = std::max(max_gpu_streams, 1); ParmParse pp("device"); - - pp.queryAdd("v", verbose); - pp.queryAdd("verbose", verbose); + if (! pp.query("verbose", "v", verbose)) { + pp.add("verbose", verbose); + } if (amrex::Verbose()) { AMREX_HIP_OR_CUDA_OR_SYCL @@ -519,9 +519,9 @@ Device::initialize_gpu () int ny = 0; int nz = 0; - pp.queryAdd("numThreads.x", nx); - pp.queryAdd("numThreads.y", ny); - pp.queryAdd("numThreads.z", nz); + pp.query("numThreads.x", nx); + pp.query("numThreads.y", ny); + pp.query("numThreads.z", nz); numThreadsOverride.x = (int) nx; numThreadsOverride.y = (int) ny; @@ -531,9 +531,9 @@ Device::initialize_gpu () ny = 0; nz = 0; - pp.queryAdd("numBlocks.x", nx); - pp.queryAdd("numBlocks.y", ny); - pp.queryAdd("numBlocks.z", nz); + pp.query("numBlocks.x", nx); + pp.query("numBlocks.y", ny); + pp.query("numBlocks.z", nz); numBlocksOverride.x = (int) nx; numBlocksOverride.y = (int) ny; @@ -542,8 +542,8 @@ Device::initialize_gpu () // Graph initialization int graph_init = 0; int graph_size = 10000; - pp.queryAdd("graph_init", graph_init); - pp.queryAdd("graph_init_nodes", graph_size); + pp.query("graph_init", graph_init); + pp.query("graph_init_nodes", graph_size); if (graph_init) { diff --git a/Src/Base/AMReX_IArrayBox.H b/Src/Base/AMReX_IArrayBox.H index db0f26d5080..b070f5c1f96 100644 --- a/Src/Base/AMReX_IArrayBox.H +++ b/Src/Base/AMReX_IArrayBox.H @@ -94,7 +94,6 @@ public: void readFrom (std::istream& is); - //! Initialize from ParmParse with "fab" prefix. static void Initialize (); static void Finalize (); diff --git a/Src/Base/AMReX_IArrayBox.cpp b/Src/Base/AMReX_IArrayBox.cpp index 40b2762729d..1b9eea50658 100644 --- a/Src/Base/AMReX_IArrayBox.cpp +++ b/Src/Base/AMReX_IArrayBox.cpp @@ -2,7 +2,6 @@ #include #include #include -#include #include #include @@ -32,7 +31,6 @@ void IArrayBox::Initialize () { if (initialized) { return; } -// ParmParse pp("iab"); ifabio = std::make_unique(); diff --git a/Src/Base/AMReX_Machine.cpp b/Src/Base/AMReX_Machine.cpp index 97de84f30c8..a7cc0d3993e 100644 --- a/Src/Base/AMReX_Machine.cpp +++ b/Src/Base/AMReX_Machine.cpp @@ -327,9 +327,9 @@ class Machine void get_params () { - ParmParse pp("machine"); - pp.queryAdd("verbose", flag_verbose); - pp.queryAdd("very_verbose", flag_very_verbose); + ParmParse pp("amrex.machine"); + pp.query("verbose", flag_verbose); + pp.query("very_verbose", flag_very_verbose); } static std::string get_env_str (const std::string& env_key) diff --git a/Src/Base/AMReX_MemPool.cpp b/Src/Base/AMReX_MemPool.cpp index 9b03e6eca4a..3d4bfde5247 100644 --- a/Src/Base/AMReX_MemPool.cpp +++ b/Src/Base/AMReX_MemPool.cpp @@ -23,11 +23,6 @@ using namespace amrex; namespace { Vector > the_memory_pool; -#if defined(AMREX_TESTING) || defined(AMREX_DEBUG) - int init_snan = 1; -#else - int init_snan = 0; -#endif bool initialized = false; } @@ -41,9 +36,6 @@ void amrex_mempool_init () initialized = true; - ParmParse pp("fab"); - pp.queryAdd("init_snan", init_snan); - int nthreads = OpenMP::get_max_threads(); the_memory_pool.resize(nthreads); @@ -109,7 +101,7 @@ void amrex_mempool_get_stats (int& mp_min, int& mp_max, int& mp_tot) // min, max void amrex_real_array_init (Real* p, size_t nelems) { - if (init_snan) { amrex_array_init_snan(p, nelems); } + if (amrex::InitSNaN()) { amrex_array_init_snan(p, nelems); } } void amrex_array_init_snan (Real* p, size_t nelems) diff --git a/Src/Base/AMReX_OpenMP.cpp b/Src/Base/AMReX_OpenMP.cpp index 53782c8c347..56225253fa7 100644 --- a/Src/Base/AMReX_OpenMP.cpp +++ b/Src/Base/AMReX_OpenMP.cpp @@ -175,7 +175,7 @@ namespace amrex::OpenMP } } else { std::optional num_omp_threads = to_int(omp_threads); - if (num_omp_threads.has_value()) { + if (num_omp_threads.has_value() && num_omp_threads.value() > 0) { omp_set_num_threads(num_omp_threads.value()); } else { diff --git a/Src/Base/AMReX_ParallelDescriptor.H b/Src/Base/AMReX_ParallelDescriptor.H index f949ae6f45c..a41d393833d 100644 --- a/Src/Base/AMReX_ParallelDescriptor.H +++ b/Src/Base/AMReX_ParallelDescriptor.H @@ -107,7 +107,7 @@ while ( false ) void Initialize (); void Finalize (); - extern AMREX_EXPORT int use_gpu_aware_mpi; + extern AMREX_EXPORT bool use_gpu_aware_mpi; inline bool UseGpuAwareMpi () { return use_gpu_aware_mpi; } //! Split the process pool into teams diff --git a/Src/Base/AMReX_ParallelDescriptor.cpp b/Src/Base/AMReX_ParallelDescriptor.cpp index 60f08d4ca35..f6ac26e7984 100644 --- a/Src/Base/AMReX_ParallelDescriptor.cpp +++ b/Src/Base/AMReX_ParallelDescriptor.cpp @@ -57,9 +57,9 @@ namespace amrex::ParallelDescriptor { #endif #ifdef AMREX_USE_GPU - int use_gpu_aware_mpi = false; + bool use_gpu_aware_mpi = false; #else - int use_gpu_aware_mpi = false; + bool use_gpu_aware_mpi = false; #endif ProcessTeam m_Team; @@ -1537,9 +1537,9 @@ StartTeams () int do_team_reduce = 0; #if defined(BL_USE_MPI3) - ParmParse pp("team"); - pp.queryAdd("size", team_size); - pp.queryAdd("reduce", do_team_reduce); + ParmParse pp("amrex.team"); + pp.query("size", team_size); + pp.query("reduce", do_team_reduce); if (nprocs % team_size != 0) { amrex::Abort("Number of processes not divisible by team size"); } diff --git a/Src/Base/AMReX_ParmParse.H b/Src/Base/AMReX_ParmParse.H index d39a60d0bba..286bed71660 100644 --- a/Src/Base/AMReX_ParmParse.H +++ b/Src/Base/AMReX_ParmParse.H @@ -1084,6 +1084,38 @@ public: } } + /* + * \brief Query two names. + * + * This function queries with `new_name` first. If it's not found, it + * will try again with `old_name`. + */ + template + int query (const char* new_name, const char* old_name, T& ref) + { + return (this->query(new_name, ref) || + this->query(old_name, ref)); + } + + /** + * \brief Get using two names. + * + * This function queries with `new_name` first, If it's not found, it + * will try again with `old_name`. It's an error if neither name is + * found. + */ + template + void get (const char* new_name, const char* old_name, T& ref) + { + auto exist = this->query(new_name, old_name, ref); + if (!exist) { + amrex::ErrorStream() << "ParmParse::get failed to find " + << new_name << " and " << old_name << '\n'; + ParmParse::dumpTable(amrex::ErrorStream()); + amrex::Abort(); + } + } + //! Remove given name from the table. int remove (const char* name); diff --git a/Src/Base/AMReX_ParmParse.cpp b/Src/Base/AMReX_ParmParse.cpp index 7a1eae245d4..a56b1d14cdf 100644 --- a/Src/Base/AMReX_ParmParse.cpp +++ b/Src/Base/AMReX_ParmParse.cpp @@ -5,6 +5,7 @@ #include #include #include +#include #include #include @@ -139,12 +140,13 @@ template <> bool is (const std::string& str, bool& val) { - if ( str == "true" || str == "t" ) + auto const lo_str = amrex::toLower(str); + if ( lo_str == "true" || lo_str == "t" ) { val = true; return true; } - if ( str == "false" || str == "f" ) + if ( lo_str == "false" || lo_str == "f" ) { val = false; return true; @@ -1117,9 +1119,10 @@ ParmParse::Verbose () { if (pp_detail::verbose < 0) { pp_detail::verbose = std::max(amrex::Verbose(),0); - ParmParse pp("parmparse"); - pp.queryAdd("v", pp_detail::verbose); - pp.queryAdd("verbose", pp_detail::verbose); + ParmParse pp("amrex.parmparse"); + if (! pp.query("verbose", "v", pp_detail::verbose)) { + pp.add("verbose", pp_detail::verbose); + } } return pp_detail::verbose; } diff --git a/Src/Base/AMReX_TinyProfiler.H b/Src/Base/AMReX_TinyProfiler.H index 4ddbb05ea7e..4ffc5bdef22 100644 --- a/Src/Base/AMReX_TinyProfiler.H +++ b/Src/Base/AMReX_TinyProfiler.H @@ -143,7 +143,7 @@ private: static std::deque > ttstack; static std::map > statsmap; static double t_init; - static int device_synchronize_around_region; + static bool device_synchronize_around_region; static int n_print_tabs; static int verbose; static double print_threshold; diff --git a/Src/Base/AMReX_TinyProfiler.cpp b/Src/Base/AMReX_TinyProfiler.cpp index 1cffe78e75a..7e84b457e75 100644 --- a/Src/Base/AMReX_TinyProfiler.cpp +++ b/Src/Base/AMReX_TinyProfiler.cpp @@ -34,7 +34,7 @@ std::vector TinyProfiler::regionstack; std::deque > TinyProfiler::ttstack; std::map > TinyProfiler::statsmap; double TinyProfiler::t_init = std::numeric_limits::max(); -int TinyProfiler::device_synchronize_around_region = 0; +bool TinyProfiler::device_synchronize_around_region = false; int TinyProfiler::n_print_tabs = 0; int TinyProfiler::verbose = 0; double TinyProfiler::print_threshold = 1.; @@ -277,8 +277,9 @@ TinyProfiler::Initialize () noexcept { amrex::ParmParse pp("tiny_profiler"); pp.queryAdd("device_synchronize_around_region", device_synchronize_around_region); - pp.queryAdd("verbose", verbose); - pp.queryAdd("v", verbose); + if (! pp.query("verbose", "v", verbose)) { + pp.add("verbose", verbose); + } // Specify the maximum percentage of inclusive time // that the "Other" section in the output can have (default 1%) pp.queryAdd("print_threshold", print_threshold); diff --git a/Src/Base/AMReX_VisMF.cpp b/Src/Base/AMReX_VisMF.cpp index 4c8b4b43fb2..2b0ac6716d0 100644 --- a/Src/Base/AMReX_VisMF.cpp +++ b/Src/Base/AMReX_VisMF.cpp @@ -77,24 +77,24 @@ VisMF::Initialize () amrex::ExecOnFinalize(VisMF::Finalize); ParmParse pp("vismf"); - pp.queryAdd("v",verbose); + pp.query("verbose", "v",verbose); int headerVersion(currentVersion); - pp.queryAdd("headerversion", headerVersion); + pp.query("headerversion", headerVersion); if(headerVersion != currentVersion) { currentVersion = static_cast (headerVersion); } - pp.queryAdd("groupsets", groupSets); - pp.queryAdd("setbuf", setBuf); - pp.queryAdd("usesingleread", useSingleRead); - pp.queryAdd("usesinglewrite", useSingleWrite); - pp.queryAdd("checkfilepositions", checkFilePositions); - pp.queryAdd("usepersistentifstreams", usePersistentIFStreams); - pp.queryAdd("usesynchronousreads", useSynchronousReads); - pp.queryAdd("usedynamicsetselection", useDynamicSetSelection); - pp.queryAdd("iobuffersize", ioBufferSize); - pp.queryAdd("allowsparsewrites", allowSparseWrites); + pp.query("groupsets", groupSets); + pp.query("setbuf", setBuf); + pp.query("usesingleread", useSingleRead); + pp.query("usesinglewrite", useSingleWrite); + pp.query("checkfilepositions", checkFilePositions); + pp.query("usepersistentifstreams", usePersistentIFStreams); + pp.query("usesynchronousreads", useSynchronousReads); + pp.query("usedynamicsetselection", useDynamicSetSelection); + pp.query("iobuffersize", ioBufferSize); + pp.query("allowsparsewrites", allowSparseWrites); initialized = true; } diff --git a/Src/Base/AMReX_iMultiFab.cpp b/Src/Base/AMReX_iMultiFab.cpp index d79e1d71444..090f1ca96d6 100644 --- a/Src/Base/AMReX_iMultiFab.cpp +++ b/Src/Base/AMReX_iMultiFab.cpp @@ -4,7 +4,6 @@ #include #include #include -#include #include #include diff --git a/Src/EB/AMReX_EB2.cpp b/Src/EB/AMReX_EB2.cpp index 87ecb9c4392..f99eb504d2f 100644 --- a/Src/EB/AMReX_EB2.cpp +++ b/Src/EB/AMReX_EB2.cpp @@ -214,11 +214,11 @@ Build (const Geometry& geom, int required_coarsening_level, pp.queryAdd("stl_scale", stl_scale); std::vector stl_center{0.0_rt, 0.0_rt, 0.0_rt}; pp.queryAdd("stl_center", stl_center); - int stl_reverse_normal = 0; + bool stl_reverse_normal = false; pp.queryAdd("stl_reverse_normal", stl_reverse_normal); IndexSpace::push(new IndexSpaceSTL(stl_file, stl_scale, // NOLINT(clang-analyzer-cplusplus.NewDeleteLeaks) {stl_center[0], stl_center[1], stl_center[2]}, - stl_reverse_normal, + int(stl_reverse_normal), geom, required_coarsening_level, max_coarsening_level, ngrow, build_coarse_level_by_coarsening, diff --git a/Src/EB/AMReX_EB2_MultiGFab.cpp b/Src/EB/AMReX_EB2_MultiGFab.cpp index 8d09ca7c069..8461b5618d4 100644 --- a/Src/EB/AMReX_EB2_MultiGFab.cpp +++ b/Src/EB/AMReX_EB2_MultiGFab.cpp @@ -1,7 +1,6 @@ #include #include -#include namespace amrex::EB2 { diff --git a/Src/EB/AMReX_WriteEBSurface.cpp b/Src/EB/AMReX_WriteEBSurface.cpp index f26420cdcc7..2e94ccb7ffb 100644 --- a/Src/EB/AMReX_WriteEBSurface.cpp +++ b/Src/EB/AMReX_WriteEBSurface.cpp @@ -1,5 +1,4 @@ #include -#include #include #include #include diff --git a/Src/Extern/HDF5/AMReX_WriteBinaryParticleDataHDF5.H b/Src/Extern/HDF5/AMReX_WriteBinaryParticleDataHDF5.H index 271f2e0e4cd..462716ae2a3 100644 --- a/Src/Extern/HDF5/AMReX_WriteBinaryParticleDataHDF5.H +++ b/Src/Extern/HDF5/AMReX_WriteBinaryParticleDataHDF5.H @@ -385,7 +385,7 @@ void WriteHDF5ParticleDataSync (PC const& pc, int nOutFiles(-1); ParmParse pp("particles"); - pp.queryAdd("particles_nfiles",nOutFiles); + pp.query("particles_nfiles",nOutFiles); if(nOutFiles == -1) nOutFiles = NProcs; /* nOutFiles = std::max(1, std::min(nOutFiles,NProcs)); */ pc.nOutFilesPrePost = nOutFiles; diff --git a/Src/Extern/HYPRE/AMReX_HypreABecLap.H b/Src/Extern/HYPRE/AMReX_HypreABecLap.H index 1d57d942a14..9b0685de434 100644 --- a/Src/Extern/HYPRE/AMReX_HypreABecLap.H +++ b/Src/Extern/HYPRE/AMReX_HypreABecLap.H @@ -7,7 +7,6 @@ #include #include #include -#include #include #include diff --git a/Src/Particle/AMReX_ParticleContainerBase.cpp b/Src/Particle/AMReX_ParticleContainerBase.cpp index 7b405681e4d..4f0ec83f4cb 100644 --- a/Src/Particle/AMReX_ParticleContainerBase.cpp +++ b/Src/Particle/AMReX_ParticleContainerBase.cpp @@ -198,7 +198,7 @@ int ParticleContainerBase::MaxReaders () first = false; ParmParse pp("particles"); Max_Readers = Max_Readers_def; - pp.queryAdd("nreaders", Max_Readers); + pp.query("nreaders", Max_Readers); Max_Readers = std::min(ParallelDescriptor::NProcs(),Max_Readers); if (Max_Readers <= 0) { @@ -224,7 +224,7 @@ Long ParticleContainerBase::MaxParticlesPerRead () first = false; ParmParse pp("particles"); Max_Particles_Per_Read = Max_Particles_Per_Read_def; - pp.queryAdd("nparts_per_read", Max_Particles_Per_Read); + pp.query("nparts_per_read", Max_Particles_Per_Read); if (Max_Particles_Per_Read <= 0) { amrex::Abort("particles.nparts_per_read must be positive"); @@ -244,7 +244,7 @@ const std::string& ParticleContainerBase::AggregationType () first = false; aggregation_type = "None"; ParmParse pp("particles"); - pp.queryAdd("aggregation_type", aggregation_type); + pp.query("aggregation_type", aggregation_type); if (!(aggregation_type == "None" || aggregation_type == "Cell")) { amrex::Abort("particles.aggregation_type not implemented."); @@ -264,7 +264,7 @@ int ParticleContainerBase::AggregationBuffer () first = false; aggregation_buffer = 2; ParmParse pp("particles"); - pp.queryAdd("aggregation_buffer", aggregation_buffer); + pp.query("aggregation_buffer", aggregation_buffer); if (aggregation_buffer <= 0) { amrex::Abort("particles.aggregation_buffer must be positive"); diff --git a/Src/Particle/AMReX_ParticleContainerI.H b/Src/Particle/AMReX_ParticleContainerI.H index de76a104b53..74e65b792f0 100644 --- a/Src/Particle/AMReX_ParticleContainerI.H +++ b/Src/Particle/AMReX_ParticleContainerI.H @@ -56,8 +56,8 @@ ParticleContainer_impl::value, // "Particle type must be standard layout and trivial."); - pp.queryAdd("use_prepost", usePrePost); - pp.queryAdd("do_unlink", doUnlink); + pp.query("use_prepost", usePrePost); + pp.query("do_unlink", doUnlink); pp.queryAdd("do_mem_efficient_sort", memEfficientSort); initialized = true; diff --git a/Src/Particle/AMReX_ParticleIO.H b/Src/Particle/AMReX_ParticleIO.H index ca40256620e..01ab0ded869 100644 --- a/Src/Particle/AMReX_ParticleIO.H +++ b/Src/Particle/AMReX_ParticleIO.H @@ -651,7 +651,7 @@ ParticleContainer_impl