.. sec:InputsMeshAndGridding:
Mesh, grids, and tiles
======================
Mesh
----
.. rubric:: Level-0 mesh
The following inputs are defined using the ``amr`` prefix.
.. _InputsTable_mesh:
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| | Description | Type | Default |
| | | | |
+======================+=======================================================================+=============+===========+
| max_level | Maximum level of refinement. The default value, 0, means that there | int | 0 |
| | is one cell size covering the entire domain (i.e., single-level). | | |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| n_cell | Number of cells at level 0 in each coordinate direction | ints | 0 0 0 |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
The level 0 mesh spacing is computed for each direction by dividing the :ref:`domain length<InputsTable_domain>` by the
number of cells. The mesh spacing is **required** to be the same in all directions:
.. math::
\frac{\text{prob_hi[0] - prob_lo[0]}}{\text{n_cell[0]}}
= \frac{\text{prob_hi[1] - prob_lo[1]}}{\text{n_cell[1]}}
= \frac{\text{prob_hi[2] - prob_lo[2]}}{\text{n_cell[2]}}
The inputs for defining the mesh for a single-level simulation are demonstrated in the
:ref:`following example<inputs_mesh_ex>` and illustrated in :numref:`fig_basic_mesh_ex`.
In this example, the domain is a :math:`4 \times 1 \times 1` cuboid, and there are
:math:`32 \times 8 \times 8` cells in the *X*, *Y*, and *Z* directions, respectively.
The result is a uniform mesh spacing of :math:`0.125` *m* in all three directions.
.. _inputs_mesh_ex:
.. code-block:: bash
:caption: Snippet of intpus for mesh example. This is not a complete input file.
# Define periodicity and domain extents
# -------------------------------------------------------------
geometry.coord_sys = 0 # Cartesian coordinates
geometry.is_periodic = 0 0 0 # periodicity for each direction
geometry.prob_lo = 0. 0. 0 # lo corner of physical domain.
geometry.prob_hi = 4. 1. 1. # hi corner of physical domain
# Define the maximum level of refinement and number of cells
# -------------------------------------------------------------
arm.max_level = 0
arm.n_cell = 32 8 8
.. _fig_basic_mesh_ex:
.. figure:: ./images/geometry/mesh_lev0_ex.png
:width: 100%
:align: center
:alt: domain used with box embedded boundary
Example of a single-level mesh.
.. warning::
MFIX-Exa simulations with a non-uniform mesh will not run.
-----
.. rubric:: Mesh refinement
The following inputs are defined using the ``amr`` prefix. These inputs control the automatic
mesh refinement algorithm and are only applicable when ``amr.max_level > 0``.
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| | Description | Type | Default |
+======================+=======================================================================+=============+===========+
| grid_eff | Threshold value to ensure grids do not contain too large a fraction | Real | 0.7 |
| | of un-tagged cells. | | |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| n_error_buf | Controls the number of tagged cells before grids are defined. Used | int | 1 |
| | to ensure coarse/fine boundaries are not too close to tagged cells. | | |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
.. caution::
**Mesh refinement limitations:**
* MFIX-Exa simulations with particles currently do not support mesh refinement.
See the `AMReX documentation <https://amrex-codes.github.io/amrex/docs_html/index.html>`_
for details on the adaptive mesh refinement algorithms.
-----
Grids
-----
The following inputs are defined using the ``amr`` prefix.
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| | Description | Type | Default |
+======================+=======================================================================+=============+===========+
| max_grid_size_x | Maximum number of cells at level 0 in each grid in *X* | int | 32 |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| max_grid_size_y | Maximum number of cells at level 0 in each grid in *Y* | int | 32 |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| max_grid_size_z | Maximum number of cells at level 0 in each grid in *Z* | int | 32 |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| blocking_factor_x | Each grid in *X* must be divisible by ``blocking_factor_x`` | int | 8 |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| blocking_factor_y | Each grid in *Y* must be divisible by ``blocking_factor_y`` | int | 8 |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| blocking_factor_z | Each grid in *Z* must be divisible by ``blocking_factor_z`` | int | 8 |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
The domain is decomposed into *grids* by dividing the number of cells by the max grid size
for each direction (e.g., ``n_cells[0]/max_grid_size_x``). The blocking factor ensures that
the grids will be sufficiently coarsenable for good multigrid performance; therefore, the
``max_grid_size`` must be divisible by the corresponding ``blocking_factor``.
.. note::
The `AMReX documentation <https://amrex-codes.github.io/amrex/docs_html/index.html>`_ contains a significant
amount of information on grid creation and load balancing. Users are **strongly** encouraged to
read the relevant sections.
-----
Tiles
-----
The following inputs are defined using the ``fabarray`` prefix.
+----------------------+-----------------------------------------------------------------------+----------+-------------+
| | Description | Type | Default |
+======================+=======================================================================+==========+=============+
| mfiter_tile_size | Maximum number of cells in each direction for (logical) tiles | IntVect | 1024000,8,8 |
+----------------------+-----------------------------------------------------------------------+----------+-------------+
The following inputs are defined using the ``particles`` prefix.
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
| | Description | Type | Default |
+======================+=======================================================================+=============+==============+
| tile_size | Maximum number of cells in each direction for (logical) tiles | IntVect | 1024000,8,8 |
| | in the ParticleBoxArray if dual_grid is true. | | |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+
When running on shared memory machines using an OpenMP enabled executable, *grids* are subdivided into
*tiles* and iterated over to improve data locality by cache blocking.
.. note::
MFIX-Exa disables tiling when using GPU accelerators.