From 06a359a14bb5a2b730723e8e5cef0bc1122f3c03 Mon Sep 17 00:00:00 2001
From: Andy Nonaka <AJNonaka@lbl.gov>
Date: Wed, 19 Oct 2022 13:57:12 -0700
Subject: [PATCH] updating docs
---
docs/source/GettingStarted_Chapter.rst | 10 ++-
docs/source/getting_started/BuildingCMake.rst | 2 +-
docs/source/getting_started/BuildingGMake.rst | 83 ++++++++++---------
docs/source/getting_started/Structure.rst | 11 ++-
4 files changed, 58 insertions(+), 48 deletions(-)
diff --git a/docs/source/GettingStarted_Chapter.rst b/docs/source/GettingStarted_Chapter.rst
index 7033b61..dc74b72 100644
--- a/docs/source/GettingStarted_Chapter.rst
+++ b/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>
diff --git a/docs/source/getting_started/BuildingCMake.rst b/docs/source/getting_started/BuildingCMake.rst
index 4c7abdb..b19c19a 100644
--- a/docs/source/getting_started/BuildingCMake.rst
+++ b/docs/source/getting_started/BuildingCMake.rst
@@ -1,4 +1,4 @@
-Building MFiX-Exa with CMake
+Building MFiX-Exa with cmake
============================
CMake build is a two-step process. First ``cmake`` is invoked to create
diff --git a/docs/source/getting_started/BuildingGMake.rst b/docs/source/getting_started/BuildingGMake.rst
index 80513c8..308535b 100644
--- a/docs/source/getting_started/BuildingGMake.rst
+++ b/docs/source/getting_started/BuildingGMake.rst
@@ -1,57 +1,66 @@
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.
diff --git a/docs/source/getting_started/Structure.rst b/docs/source/getting_started/Structure.rst
index 98195a6..0980fdf 100644
--- a/docs/source/getting_started/Structure.rst
+++ b/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 |
+---------------+--------------------------------------------------+
-
--
GitLab