Restructure to improve GUI workflow

Jordan Musserrequested to merge
jmusser/exa-docs:reorg-layout-for-gui into main

Merge request reports

docs/source_docs/user_guide/inputs/output/checkpointing.rst

+18 −2
Changes for docs/source_docs/user_guide/inputs/output/checkpointing.rst: 18 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -8,8 +8,6 @@ The following inputs must be preceded by the prefix ``mfix`` and control checkpo 
+-------------------------+------------------------------------------------------------------------+-------------+------------------+

|                         | Description                                                            |   Type      | Default          |

+=========================+========================================================================+=============+==================+

| restart                 | If present, the name of file to restart from.                          |  String     | None             |

+-------------------------+------------------------------------------------------------------------+-------------+------------------+

| check_file              | Prefix to use for checkpoint output file name.                         |  String     | chk              |

+-------------------------+------------------------------------------------------------------------+-------------+------------------+

| check_int               | Checkpoint output interval in number of timesteps (0 to disable).      |  Int        | 0                |
@@ -31,3 +29,21 @@ The following inputs must be preceded by the prefix ``mfix`` and control checkpo 
|                         | the refined geometry, i.e. when levelset refinement is enabled.        |             |                  |

|                         |                                                                        |             |                  |

+-------------------------+------------------------------------------------------------------------+-------------+------------------+





Replication

-----------



Domain replication is a restart capability that takes the domain stored in a checkpoint file and duplicates it according to the user‑specified replication factors. This feature is available only for fully periodic domains. Its primary purpose is to support scaling studies where the amount of work per processor must remain constant.



The following inputs must be preceded by the prefix ``mfix``.



+----------------------+-----------------------------------------------------------------------+-------------+--------------+

|                      | Description                                                           |   Type      | Default      |

+======================+=======================================================================+=============+==============+

| repl_x               | Replicate initial data by this factor in the x-direction.             |   Int       |    1         |

+----------------------+-----------------------------------------------------------------------+-------------+--------------+

| repl_y               | Replicate initial data by this factor in the y-direction.             |   Int       |    1         |

+----------------------+-----------------------------------------------------------------------+-------------+--------------+

| repl_z               | Replicate initial data by this factor in the z-direction.             |   Int       |    1         |

+----------------------+-----------------------------------------------------------------------+-------------+--------------+

docs/source_docs/user_guide/inputs/advanced.rst

+3 −3
Changes for docs/source_docs/user_guide/inputs/advanced.rst: 3 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -18,6 +18,9 @@ The following inputs must be preceded by the prefix ``mfix``: 
| only_print_grid_report |  Do not time-march the simulation. Simply generate the grid report    |   Bool      | false        |

|                        |  and exit.                                                            |             |              |

+------------------------+-----------------------------------------------------------------------+-------------+--------------+

| stop_for_unused_inputs |  Do not time-march the simulation if any keyword in the inputs file   |   Bool      | false        |

|                        |  has not been used. This is useful in catching input errors.          |             |              |

+------------------------+-----------------------------------------------------------------------+-------------+--------------+



To assist in verifying the breakdown of fluid grids created before running a full simulation, an input option

``mfix.only_print_grid_report`` is supported. By default, it is ``false``. When set to ``true``, the run uses
@@ -93,9 +96,6 @@ The following inputs must be preceded by the prefix ``mfix`` and control load ba 
+----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+

| 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                                                       |             |                   |

+----------------------------------+-----------------------------------------------------------------------+-------------+-------------------+





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

docs/source_docs/user_guide/inputs/domain.rst

+61 −0
Changes for docs/source_docs/user_guide/inputs/domain.rst: 61 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -29,3 +29,64 @@ The following inputs are defined using the prefix ``geometry``: 


   * There is **no support** for 1D or 2D simulation domains.

   * Cartesian is the **only supported** coordinate system.





Mesh

----



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



.. _InputsTable_mesh:



+----------------------+-----------------------------------------------------------------------+-------------+-----------+

|                      | Description                                                           |   Type      | Default   |

|                      |                                                                       |             |           |

+======================+=======================================================================+=============+===========+

| n_cell               | Number of cells at level 0 in each coordinate direction.              |    Ints<3>  | 0 0 0     |

+----------------------+-----------------------------------------------------------------------+-------------+-----------+



The base 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

   # -------------------------------------------------------------

   amr.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.

docs/source_docs/user_guide/inputs/fluid_model.rst

+197 −100

File changed.

Preview size limit exceeded, changes collapsed.

docs/source_docs/user_guide/inputs/geometry.rst

+36 −6
Changes for docs/source_docs/user_guide/inputs/geometry.rst: 36 added lines, 6 removed lines.
Original line number Diff line number Diff line
@@ -19,9 +19,6 @@ The following inputs are defined using the prefix ``mfix``: 
|                        | * ``None`` - no embedded boundary -- all domain faces must be specified       |          |                     |

|                        |                                                                               |          |                     |

+------------------------+-------------------------------------------------------------------------------+----------+---------------------+

| levelset_refinement    | Refinement factor of levelset resolution relative to level 0                  |   Int    | 1                   |

|                        | resolution                                                                    |          |                     |

+------------------------+-------------------------------------------------------------------------------+----------+---------------------+



Most simulations require a user to specify some kind of geometry. For example, the geometry could be a basic cylinder used to

model flow inside a pipe, or it may be an irregularly shaped solid to study external flow around a bluff body, or the geometry
@@ -289,7 +286,7 @@ The ``generic`` geometry option is used to select the user-programed embedded bo 


.. _InputsGeometry_CSG:



Constructive solid geometry (CSG)

CSG (Constructive solid geometry)

---------------------------------



* A constructive solid geometry can be created using OpenSCAD.
@@ -317,8 +314,8 @@ The following inputs are defined using the prefix ``csg``: 


.. _InputsGeometry_STL:



STL (Standard Triangle Language)

--------------------------------

STL (Stereolithography file)

----------------------------



* An STL geometry can be created using numerous CAD programs.
@@ -339,3 +336,36 @@ The following inputs are defined using the prefix ``stl``: 
.. note::

   A full description of this feature is beyond the scope of this section. A future update to

   the documentation may include a tutorial to better demonstrate this feature.





Checkpoint geometry

-------------------



Read EB geometry data from a checkpoint file.



The following inputs are defined using the prefix ``mfix``.



+----------------------+-----------------------------------------------------------------------+-------------+--------------+

|                      | Description                                                           |   Type      | Default      |

+======================+=======================================================================+=============+==============+

| geom_chk_read        | Flag to read the EB geometry data from the ``geom_chk_file``          |  Bool       |  false       |

|                      | :ref:`checkpoint file<Chap:InputsCheckpoint>`. If levelset refinement |             |              |

|                      | is enabled, levelset data is read from ``geom_levelset_chk_file``.    |             |              |

+----------------------+-----------------------------------------------------------------------+-------------+--------------+



Levelset refinement

-------------------



For particle-wall interactions, the geometry is represented using a levelset function, and the grid storing this

levelset can be refined to capture geometric details more accurately. This refinement affects only particle-wall

interactions and does not alter the geometry representation used for solving the fluid equations.



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



+------------------------+-------------------------------------------------------------------------------+----------+---------------------+

|                        | Description                                                                   |   Type   | Default             |

+========================+===============================================================================+==========+=====================+

| levelset_refinement    | Refinement factor of levelset resolution relative to level 0                  |   Int    | 1                   |

|                        | resolution                                                                    |          |                     |

+------------------------+-------------------------------------------------------------------------------+----------+---------------------+