diff --git a/docs/source_docs/user_guide/inputs/advanced.rst b/docs/source_docs/user_guide/inputs/advanced.rst index ee1ef6b55ae503f3a503881c6afb52798051c772..a1d2f7fda81022d0618f54d849f880d2cdf310e7 100644 --- a/docs/source_docs/user_guide/inputs/advanced.rst +++ b/docs/source_docs/user_guide/inputs/advanced.rst @@ -53,54 +53,38 @@ The following inputs must be preceded by "amrex." Load balancing -------------- -Note that when running a granular simulation, i.e., no fluid phase, :cpp:`mfix.dual_grid` must be 0. Hence, -the :cpp:`particles.max_grid_size` (in each direction) have no meaning. Therefore the fluid grid and tile +Note that when running a granular simulation, i.e., no fluid phase, ``mfix.load_balance`` defaults to ``SingleGrid``. Hence, +the ``particles.max_grid_size`` (in each direction) have no meaning. Therefore the fluid grid and tile sizes should be set for particle load balancing. It may also be necessary to set the blocking factors to 1. -The following inputs must be preceded by "mfix." and determine how we load balance: - -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| | Description | Type | Default | -+======================+=======================================================================+=============+==============+ -| dual_grid | If true then use the "dual_grid" approach for load balancing | Bool | False | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| regrid_int | How often to regrid (in number of steps at level 0) | Int | -1 | -| | if regrid_int = -1 then no regridding will occur | | | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| load_balance_fluid | Only relevant if (dual_grid); if so do we also regrid mesh data | Int | 0 | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| load_balance_type | What strategy to use for load balancing | String | KnapSack | -| | Options are "KnapSack", "SFC", or "Greedy" | | | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| knapsack_weight_type | What weighting function to use if using Knapsack load balancing | String | RunTimeCosts | -| | Options are "RunTimeCosts" or "NumParticles"" | | | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| knapsack_nmax | Maximum number of grids per MPI process if using knapsack algorithm | Int | 128 | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| greedy_dir | The direction in which the greedy algorithm cuts overloaded boxes | Int | 0 | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| greedy_min_grid_size | The minimum particle grid size in the greedy load balance algorithm | Int | 2 | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| greedy_3d | Partition particle grids in 3D with the greedy algorithhm | Bool | False | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| overload_tolerance* | The ratio between the maximum workload and the average workload | Real | 1.2 | -| | in the greedy algorithm | | | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| underload_tolerance* | The ratio between the minimum workload and the average workload | Real | 0.8 | -| | in the greedy algorithm | | | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| grid_pruning | Remove all covered grids from the base mesh; this may result in | Bool | False | -| | disjoined grids | | | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ - -\* The greedy partitioning algorithm uses the tolerances to set the expected -workload range for each rank but doesn't strictly enforce them. The algorithm -creates a partition as balance as possible even if the partition doesn't -meet the tolerances. +The following inputs must be preceded by ``mfix`` and determine how we load balance: + ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ +| | Description | Type | Default | ++==================================+=======================================================================+=============+===================+ +| regrid_int | How often to regrid (in number of steps at level 0) | int | 0 | +| | if regrid_int <= 0 then no regridding will occur | | | ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ +| load_balance | * ``SingleGrid`` fluid and particles are co-located on the same grids | string | SingleGrid | +| | * ``DualGrid`` fluid and particles live on different grids | | | ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ +| load_balance.DualGrid.fluid | Regrid mesh (fluid) in addition to particles when using `DualGrid` | int | 0 | ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ +| load_balance.strategy | What strategy to use for load balancing | string | KnapSack | +| | Options are ``KnapSack`` and ``SFC`` | | | ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ +| load_balance.weighting | What weighting function to use if using Knapsack load balancing | string | ParticleRunTime | +| | Options are ``ParticleRunTime``, ``ParticleCount`` and ``CellCount`` | | | ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ +| knapsack_nmax | Maximum number of grids per MPI process if using knapsack algorithm | int | 128 | ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ +| grid_pruning | Remove all covered grids from the base mesh; this may result in | bool | False | +| | disjoined grids | | | ++----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+ To allow a user to verify the breakdown of fluid grids created before running a full simulation, an input option, -:cpp:`mfix.only_print_grid_report` is supported. By default, it is :cpp:`False`. When set to :cpp:`True`, the run uses +``mfix.only_print_grid_report`` is supported. By default, it is ``False``. When set to ``True``, the run uses minimal memory to print the grid coverage report and exits immediately after that. @@ -118,16 +102,3 @@ The following inputs are defined using the ``particles`` prefix. | 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. | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ - - -.. todo:: Is this needed anymore? - - The following inputs must be preceded by "particles." - - +----------------------+-----------------------------------------------------------------------+-------------+--------------+ - | | Description | Type | Default | - +======================+=======================================================================+=============+==============+ - | reduceGhostParticles | Remove unused ghost particles from communication, | Bool | True | - | | only supported by GPU build | | | - +----------------------+-----------------------------------------------------------------------+-------------+--------------+ - diff --git a/docs/source_docs/user_guide/quick_start/BuildingMFIX.rst b/docs/source_docs/user_guide/quick_start/BuildingMFIX.rst index 362342337a8cf9bf0f48a8bc60f41417317d25a3..778587b91d347a1317f844e60a674b11e950dd48 100644 --- a/docs/source_docs/user_guide/quick_start/BuildingMFIX.rst +++ b/docs/source_docs/user_guide/quick_start/BuildingMFIX.rst @@ -2,8 +2,8 @@ Building MFIX-Exa ================== This page gives the generic instructions for building MFIX-Exa using gmake and cmake. -The instructions assume you have already downloaded and unpacked the MFIX-Exa code -into a local ``mfix`` directory. If not, please visit the +The instructions assume you have already downloaded and unpacked the MFIX-Exa code +into a local ``mfix`` directory. If not, please visit the `download page <https://mfix.netl.doe.gov/products/mfix-exa/download/>`_ first. For HPC cluster specific instructions, please refer to :ref:`GettingStarted:HPC`. @@ -44,7 +44,7 @@ Other options that you can set include +-----------------+----------------------------------+------------------+-------------+ | USE_HIP | Enable HIP GPU support | TRUE / FALSE | FALSE | +-----------------+----------------------------------+------------------+-------------+ -| USE_DPCPP | Enable DPCPP GPU support | TRUE / FALSE | FALSE | +| USE_SYCL | Enable dpc++ GPU support | TRUE / FALSE | FALSE | +-----------------+----------------------------------+------------------+-------------+ | USE_HYPRE | Enable HYPRE support | TRUE / FALSE | FALSE | +-----------------+----------------------------------+------------------+-------------+ @@ -58,11 +58,9 @@ Other options that you can set include +-----------------+----------------------------------+------------------+-------------+ | TINY_PROFILE | Include tiny profiling info | TRUE / FALSE | FALSE | +-----------------+----------------------------------+------------------+-------------+ -| DIM | Dimensionality of problem | 2 / 3 | 3 | -+-----------------+----------------------------------+------------------+-------------+ .. note:: - **Do not set both USE_OMP and USE_CUDA/HIP/DPCPP to true.** + **Do not set both USE_OMP and USE_CUDA/HIP/SYCL to true.** Then type