update documentation

Docs/sphinx_documentation/source/BuildingAMReX.rst

@@ -71,7 +71,7 @@ alternatively, in tcsh one can set
 
 One must set the ``COMP`` variable to choose a compiler. Currently the list of
 supported compilers includes gnu, cray, ibm, intel, llvm, and pgi. One must
-also set the DIM variable to either 1, 2, or 3, depending on the dimensionality
+also set the ``DIM`` variable to either 1, 2, or 3, depending on the dimensionality
 of the problem.
 
 Variables ``DEBUG``, ``USE_MPI`` and ``USE_OMP`` are optional with default set
@@ -172,17 +172,25 @@ For example, macOS' Xcode ships with its own (woefully outdated) version of GCC
 (4.2.1). It is therefore commonplace to install GCC using the `homebrew
 <https://brew.sh>`_ package manager. This in turn installs compilers with names
 reflecting the version number. If GCC 7.3 is installed, homebrew installs it as
-``gcc-7``. AMReX can be built using ``gcc-7`` by using the following
+``gcc-7``. AMReX can be built using ``gcc-7`` without MPI by using the following
 ``amrex/Tools/GNUMake/Make.local``:
 
 :: 
 
-    CXX = g++-7
-    CC  = gcc-7
-    FC  = gfortran-7
-    F90 = gfortran-7
-
-
+    ifeq ($(USE_MPI),TRUE)
+      CXX = mpicxx
+      CC  = mpicc
+      FC  = mpif90
+      F90 = mpif90
+    else
+      CXX = g++-7
+      CC  = gcc-7
+      FC  = gfortran-7
+      F90 = gfortran-7
+    endif
+
+For building with MPI, we assume ``mpicxx``, ``mpif90``, etc. provide
+access to the correct underlying compilers.
 
 .. _sec:build:lib:
 

Docs/sphinx_documentation/source/Chapter3.rst

@@ -10,7 +10,7 @@ AMReX while compiling their own codes. This will be discussed in more detail in
 the section on :ref:`sec:build:make`.  The second approach is to build install
 AMReX as a library (cf. :ref:`sec:build:lib`).; an application code then uses
 its own build system and links to AMReX as an external library.  Finally, AMReX
-can also be built with Cmake, as detailed in the section on
+can also be built with CMake, as detailed in the section on
 :ref:`sec:build:cmake`.
 
 .. toctree::

Docs/sphinx_documentation/source/GettingStarted.rst

@@ -95,7 +95,7 @@ set ``USE_MPI=TRUE`` in the GNUmakefile). This should make an executable named
 
 ::
 
-      mpiexec -n 4 ./main3d.gnu.DEBUG.MPI.ex
+      mpiexec -n 4 ./main3d.gnu.DEBUG.MPI.ex amrex.v=1
 
 The result may look like,
 
@@ -107,7 +107,11 @@ The result may look like,
       Hello world from AMReX version 17.05-30-g5775aed933c4-dirty
 
 If the compilation fails, you are referred to :ref:`Chap:BuildingAMReX` for
-more details on how to configure the build system.
+more details on how to configure the build system.  The command line
+argument ``amrex.v=1`` increases the AMReX verbosity level from the
+default value of 0 to 1 to print the number of MPI processes used.
+More details on how runtime parameters are handled can be found in
+section :ref:`sec:basics:parmparse`.
 
 If you want to build with OpenMP, type make ``USE_OMP=TRUE``.  This should make
 an executable named ``main3d.gnu.DEBUG.OMP.ex``. Note OMP in the file name.
@@ -118,7 +122,7 @@ You can then run,
 
 ::
 
-      ./main3d.gnu.DEBUG.OMP.ex
+      OMP_NUM_THREADS=4 ./main3d.gnu.DEBUG.OMP.ex amrex.v=1
 
 The result may look like,
 
@@ -136,7 +140,7 @@ can then run,
 
 ::
 
-      mpiexec -n 2 ./main3d.gnu.DEBUG.MPI.OMP.ex
+      OMP_NUM_THREADS=4 mpiexec -n 2 ./main3d.gnu.DEBUG.MPI.OMP.ex
 
 The result may look like,
 
@@ -161,7 +165,7 @@ can be visualized. This example solves the heat equation,
 
 using forward Euler temporal integration on a periodic domain.  We could use a
 5-point (in 2D) or 7-point (in 3D) stencil, but for demonstration purposes we
-spatially discretize the PDE by first constructing fluxes on cell faces, e.g.,
+spatially discretize the PDE by first constructing (negative) fluxes on cell faces, e.g.,
 
 .. math:: F_{i+^1\!/_2,\,j} = \frac{\phi_{i+1,j}-\phi_{i,j}}{\Delta x},
 

Docs/sphinx_documentation/source/Introduction.rst

@@ -20,6 +20,8 @@ Key features of AMReX include:
 
 -  Support for particles
 
+-  Support for embedded boundary (cut cell) representations of complex geometries
+
 -  Parallelization via flat MPI, OpenMP, hybrid MPI/OpenMP, or MPI/MPI
 
 -  Parallel I/O