updating docs

docs/source/GettingStarted_Chapter.rst

@@ -10,14 +10,16 @@ can be cloned by using git:
 .. code-block:: shell
 
    > git clone https://mfix.netl.doe.gov/gitlab/exa/mfix.git
-   > cd mfix
-
 
 .. note::
 
    Access to the repository is currently restricted to project members. As the
    code matures, a distribution mechanism will be developed.
 
+MFiX-Exa is also dependent on the AMReX and AMReX-Hydro git repositories.
+For cmake builds these repositories may be cloned as part of the configuration.
+Details are included in the sections below.
+
 Once you have obtained the source code, the following sections describe the
 source code contents, compiling, running a simple simulation, and visualizing
 the simulations results.
@@ -26,7 +28,7 @@ the simulations results.
    :maxdepth: 1
 
    Source directory overview <getting_started/Structure>
-   Compiling with CMake <getting_started/BuildingCMake>
-   Compiling with GMake <getting_started/BuildingGMake>
+   Compiling with gmake <getting_started/BuildingGMake>
+   Compiling with cmake <getting_started/BuildingCMake>
    Running your first simulation <getting_started/FirstSimulation>
    Visualizing simulation results <getting_started/Visualization>

docs/source/getting_started/BuildingCMake.rst

-Building MFiX-Exa with CMake
+Building MFiX-Exa with cmake
 ============================
 
 CMake build is a two-step process. First ``cmake`` is invoked to create

docs/source/getting_started/BuildingGMake.rst

 Building MFiX-Exa with gmake
 ============================
 
-Building MFiX-Exa with gmake 
-
-If you want to use gmake to build MFiX_Exa, you will need to have already
-cloned amrex and AMReX-Hydro into a local directories:
+If you want to use gmake to build MFiX_Exa, you will need to
+clone amrex and AMReX-Hydro into a local directories, and also
+clone mfix:
 
 .. code:: shell
 
     > git clone https://github.com/AMReX-Codes/amrex.git
     > git clone https://github.com/AMReX-Codes/AMReX-Hydro.git
-
-Then
-
-.. code:: shell
-
     > git clone http://mfix.netl.doe.gov/gitlab/exa/mfix.git
     > cd mfix/exec
 
-Edit the GNUmakefile (or use an environment variable)
-to set AMREX_HOME and AMREX_HYDRO_HOME
+Then, edit the GNUmakefile (or set an environment variable)
+to define AMREX_HOME and AMREX_HYDRO_HOME
 to be the path to the directories where you have put amrex
-and AMReX-Hydro.  Other options that you can set include
-
-+-----------------+------------------------------+------------------+-------------+
-| Option name     | Description                  | Possible values  | Default     |
-|                 |                              |                  | value       |
-+=================+==============================+==================+=============+
-| COMP            | Compiler (gnu or intel)      | gnu / intel      | None        |
-+-----------------+------------------------------+------------------+-------------+
-| USE_MPI         | Whether to enable MPI        | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
-| USE_OMP         | Whether to enable OpenMP     | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
-| USE_CUDA        | Whether to enable CUDA       | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
-| DEBUG           | Whether to use DEBUG mode    | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
-| PROFILE         | Include profiling info       | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
-| TINY_PROFILE    | Include tiny profiling info  | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
-| COMM_PROFILE    | Include comm profiling info  | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
-| TRACE_PROFILE   | Include trace profiling info | TRUE / FALSE     | FALSE       |
-+-----------------+------------------------------+------------------+-------------+
+and AMReX-Hydro.  Note that the default locations of
+AMREX_HOME and AMREX_HYDRO_HOME are in the subprojects directory,
+which is where a cmake configuration may clone these repositories.
+Other options that you can set include
 
++-----------------+----------------------------------+------------------+-------------+
+| Option name     | Description                      | Possible values  | Default     |
+|                 |                                  |                  | value       |
++=================+==================================+==================+=============+
+| COMP            | Compiler (gnu or intel)          | gnu / intel      | gnu         |
++-----------------+----------------------------------+------------------+-------------+
+| USE_MPI         | Enable MPI                       | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| USE_OMP         | Enable OpenMP                    | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| USE_CSG         | Enable CSG geometry file support | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| USE_CUDA        | Enable CUDA GPU support          | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| USE_HIP         | Enable HIP GPU support           | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| USE_DPCPP       | Enable DPCPP GPU support         | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| USE_HYPRE       | Enable HYPRE support             | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| DEBUG           | Create a DEBUG executable        | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| PROFILE         | Include profiling info           | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| TRACE_PROFILE   | Include trace profiling info     | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| COMM_PROFILE    | Include comm profiling info      | TRUE / FALSE     | FALSE       |
++-----------------+----------------------------------+------------------+-------------+
+| 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 to true.**
+   **Do not set both USE_OMP and USE_CUDA/HIP/DPCPP to true.**
 
 Then type
 
 .. code:: shell
 
-    > make
+    > make -j
+
+An executable will appear; the executable name will reflect
+some of the build options above.

docs/source/getting_started/Structure.rst

@@ -8,16 +8,15 @@ Directory overview
 +===============+==================================================+
 | benchmarks    | UC Benchmark cases (see benchmark/README.md)     |
 +---------------+--------------------------------------------------+
-| doc           |  Source code for building the documentation      |
-+---------------+--------------------------------------------------+
-| exec          | Directory for building with gmake (optional)     |
+| exec          | Directory for building with gmake                |
 +---------------+--------------------------------------------------+
 | src           | Source files                                     |
 +---------------+--------------------------------------------------+
+| subprojects   | Location of dependent git repos for cmake builds |
++---------------+--------------------------------------------------+
 | tests         | Regression tests (see tests/README.md)           |
 +---------------+--------------------------------------------------+
-| tools         | CMake configuration files                        |
+| tools         | cmake configuration files                        |
 +---------------+--------------------------------------------------+
-| tutorials     | Set-ups for different EB geometries              |
+| tutorials     | Additional test cases                            |
 +---------------+--------------------------------------------------+
-