.. sec:InputsMeshAndGridding:

Mesh, grids, and tiles
======================

Mesh
----

.. rubric:: Level-0 mesh

The following inputs are defined using the prefix ``amr``:

.. _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 prefix ``amr``. 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 untagged 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.

The following inputs are defined using the prefix ``mfix.tag``. They control how cells are tagged
for the mesh refinement algorithm and are only applicable when ``amr.max_level > 0``.

Cells intersected by the embedded boundary are always tagged for refinement, regardless of these settings.

+----------------------+-----------------------------------------------------------------------+-------------+-----------+
|                      | Description                                                           |   Type      | Default   |
+======================+=======================================================================+=============+===========+
| rho                  | Tag cells for refinement when the fluid density is **greater than**   |    Reals    |  None     |
|                      | the specified value.                                                  |             |           |
|                      |                                                                       |             |           |
|                      | * To tag cells when density is **less than** the specified value,     |             |           |
|                      |   set ``mfix.rho.less_than = true``.                                  |             |           |
|                      | * Values may be specified per level. If fewer than ``amr.max_level``  |             |           |
|                      |   values are provided, the last value is used for all higher levels.  |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| rho.less_than        | Tag cells for refinement when the fluid density is **less than** the  |    Bool     |  false    |
|                      | specified value.                                                      |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| grad_rho             | Tag cells for refinement when the difference in fluid density between |    Reals    |  None     |
|                      | two adjacent cells is greater than the specified value.               |             |           |
|                      |                                                                       |             |           |
|                      | * To tag cells when the difference is less than the specified value,  |             |           |
|                      |   set ``mfix.grad_rho.less_than = true``.                             |             |           |
|                      | * Values may be specified per level. If fewer than ``amr.max_level``  |             |           |
|                      |   values are provided, the last value is used for all higher levels.  |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| grad_rho.less_than   | Tag cells for refinement when the difference in fluid density between |    Bool     |  false    |
|                      | two adjacent cells is **less than** the specified value.              |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| vel                  | Tag cells for refinement when the difference in any fluid velocity    |    Reals    |  None     |
|                      | component between two adjacent cells is **greater than** the          |             |           |
|                      | specified value.                                                      |             |           |
|                      |                                                                       |             |           |
|                      | * To tag cells when the difference is less than the specified value,  |             |           |
|                      |   set ``mfix.grad_vel.less_than = true``.                             |             |           |
|                      | * Values may be specified per level. If fewer than ``amr.max_level``  |             |           |
|                      |   values are provided, the last value is used for all higher levels.  |             |           |
|                      |                                                                       |             |           |
|                      | Tag cells for refinement when the fluid velocity magnitude is         |             |           |
|                      | *greater than* the specified value.                                   |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| vel.less_than        | Tag cells for refinement when fluid velocity magnitude is             |    Bool     |  false    |
|                      | **less than** the specified value.                                    |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| grad_vel             | Tag cells for refinement when the difference in any fluid velocity    |    Reals    |  None     |
|                      | component between two adjacent cells is **greater than** the          |             |           |
|                      | specified value.                                                      |             |           |
|                      |                                                                       |             |           |
|                      | * To tag cells when the difference is less than the specified value,  |             |           |
|                      |   set ``mfix.grad_vel.less_than = true``.                             |             |           |
|                      | * Values may be specified per level. If fewer than ``amr.max_level``  |             |           |
|                      |   values are provided, the last value is used for all higher levels.  |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| grad_vel.less_than   | Tag cells for refinement when the difference in any fluid velocity    |    Bool     |  false    |
|                      | component between two adjacent cells is **less than** the specified   |             |           |
|                      | value.                                                                |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| regions              | A list of predefined regions used to identify sections of the domain  |   Strings   | None      |
|                      | for mesh refinement.                                                  |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+


-----

Grids
-----

The following inputs are defined using the prefix ``amr``:

+----------------------+-----------------------------------------------------------------------+-------------+-----------+
|                      | 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 prefix ``fabarray``:

+----------------------+-----------------------------------------------------------------------+----------+-------------+
|                      | Description                                                           | Type     | Default     |
+======================+=======================================================================+==========+=============+
| mfiter_tile_size     | Maximum number of cells in each direction for (logical) tiles.        | Ints     | 1024000 8 8 |
+----------------------+-----------------------------------------------------------------------+----------+-------------+

The following inputs are defined using the prefix ``particles``:

+----------------------+-----------------------------------------------------------------------+-------------+--------------+
|                      | Description                                                           |   Type      | Default      |
+======================+=======================================================================+=============+==============+
| tile_size            | Maximum number of cells in each direction for (logical) tiles         |  Ints       | 1024000 8 8  |
|                      | in the ParticleBoxArray if ``load_balance`` is ``DualGrid``           |             |              |
+----------------------+-----------------------------------------------------------------------+-------------+--------------+

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.
