Sphinx Documentation: Minor wording fixes (#5217)

Minor editing pass by Codex.

Author: WeiqunZhang

Docs/sphinx_documentation/source/AMReX_Profiling_Tools.rst

@@ -20,15 +20,15 @@ Currently, AMReX has two options for built-in profiling:
 Tiny Profiling
 ----------------------
 
-To enable "Tiny Profiling" with GNU Make edit the options in the file ``GNUMakefile``
-to show,
+To enable "Tiny Profiling" with GNU Make, edit the options in the file ``GNUMakefile``
+as follows:
 
 ::
 
   TINY_PROFILE = TRUE
   PROFILE      = FALSE
 
-If building with CMake, set the following CMake flags,
+If building with CMake, set the following CMake flags:
 
 ::
 
@@ -82,21 +82,21 @@ be written at user-defined points in the code by inserting the line:
   BL_PROFILE_TINY_FLUSH();
 
 Any timers that have not reached their ``BL_PROFILE_VAR_STOP`` call or exited
-their scope and been destructed will not be included in these partial outputs.
+their scope and been destroyed will not be included in these partial outputs.
 (e.g., a properly instrumented ``main()`` should show a time of zero in all
 partial outputs.) Therefore, it is recommended to place these flush calls in
 easily identifiable regions of your code and outside of as many profiling
 timers as possible, such as immediately before or after writing a checkpoint.
 
-Also, since flush calls will print multiple, similar looking outputs to ``stdout``,
+Also, since flush calls will print multiple, similar-looking outputs to ``stdout``,
 it is also recommended to wrap any ``BL_PROFILE_TINY_FLUSH();`` calls in
 informative ``amrex::Print()`` lines to ensure accurate identification of each
 set of timers.
 
 Hot Spots and Load Balance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The output of TinyProfiler can help us to identify hot spots. For example,
+The output of TinyProfiler can help identify hot spots. For example,
 the following output shows the top three hot spots of a linear solver test
 running on 4 MPI processes.
 
@@ -176,7 +176,7 @@ AMReX profiler objects are created and managed through :cpp:`BL_PROF` macros.
 
 .. highlight:: c++
 
-To start, you must at least instrument main(), i.e.:
+To start, you must at least instrument ``main()``, i.e.:
 
 ::
 
@@ -209,7 +209,7 @@ Or:
         amrex::Finalize();
     }
 
-You can then instrument any of your functions, or code blocks. There are four general
+You can then instrument any of your functions or code blocks. There are four general
 profiler macro types available:
 
 1) A scoped timer, :cpp:`BL_PROFILE`:
@@ -246,7 +246,7 @@ In some cases, using scopes to control a timer is not ideal. In such cases, you
             FORT_FLATENX(arg1, arg2);
           BL_PROFILE_VAR_STOP(anyname);   // Stop the "anyname" timer object.
 
-This can also be used to selectively time with the same scope. For example, to include :cpp:`Func_0`
+This can also be used to selectively time within the same scope. For example, to include :cpp:`Func_0`
 and :cpp:`Func_2`, but not :cpp:`Func_1`:
 
 ::
@@ -279,7 +279,7 @@ timers by just using the :cpp:`_VAR` macro:
 3) A named, scoped timer that doesn't auto-start, :cpp:`BL_PROFILE_VAR_NS`:
 ----------------------------------------------------------------------------------------
 
-Sometimes, a complicated scoping may mean the profiling object needs to be defined before it's
+Sometimes, a complicated scope may mean the profiling object needs to be defined before it's
 started. To create a named AMReX timer that doesn't start automatically, use the ``_NS_`` macros.
 ("NS" stands for "no start"). For example, this implementation times :cpp:`MyFunc0`
 and :cpp:`MyFunc1` but not any of the
@@ -288,7 +288,7 @@ and :cpp:`MyFunc1` but not any of the
 ::
 
           {
-              BL_PROFILE_VAR_NS("MyFuncs()", myfuncs);  // dont start the timer
+              BL_PROFILE_VAR_NS("MyFuncs()", myfuncs);  // don't start the timer
 
               <Additional Code A>
 
@@ -309,7 +309,7 @@ and :cpp:`MyFunc1` but not any of the
               }
           }
 
-.. Note::
+.. note::
    The ``_NS_`` macro must, by necessity, also be a ``_VAR_`` macro. Otherwise, you would never be
    able to turn the timer on!
 
@@ -355,7 +355,7 @@ macros in the following way:
           }
 
 The ``MyFuncs`` region appears in the Tiny Profiler output as an additional table.
-The following output example, mimics the above code. In it, the region is
+The following output example mimics the above code. In it, the region is
 indicated by ``REG::MyFuncs``.
 
 .. code-block:: console
@@ -448,7 +448,7 @@ and at the point in the function where you want to stop profiling. The profiling
 output will only warn of any :fortran:`bl_proffortfuncstart` calls that were not stopped with
 :fortran:`bl_proffortfuncstop` calls when in debug mode.
 
-For functions with a high number of calls, there is a lighter-weight interface,
+For functions with a high number of calls, there is a lighter-weight interface:
 
 ::
 
@@ -474,10 +474,10 @@ in the ``bl_proffortfuncstart_int/bl_proffortfuncstop_int`` calls.
 Profiling Options
 =================
 
-AMReX's communication algorithms are often regions of code that increase in wall clock time
+AMReX's communication algorithms are often regions of code that increase in wall-clock time
 when the application is load imbalanced, due to the MPI_Wait calls in these functions.
 To better understand if this is occurring and by how much, you can turn on an AMReX timed
-synchronization with the runtime variable: ``amrex.use_profiler_syncs=1`` This adds named timers
+synchronization with the runtime variable ``amrex.use_profiler_syncs=1``. This adds named timers
 beginning with ``SyncBeforeComms`` immediately prior to the start of the FillBoundary,
 ParallelCopy and particle Redistribute functions, isolating any prior load imbalance to that timer
 before beginning the comm operation.
@@ -486,7 +486,7 @@ This is a diagnostic tool and may slow your code down, so it is not recommended
 on for production runs.
 
 .. note::
-  Note: the ``SyncBeforeComms`` timer is not equal to your load imbalance. It only captures imbalance
+  The ``SyncBeforeComms`` timer is not equal to your load imbalance. It only captures imbalance
   between the comm functions and the previous sync point; there may be other load imbalances
   captured elsewhere. Also, the timer reports in terms of MPI rank, so if the most imbalanced
   rank changes throughout the simulation, the timer will be an underestimation.
@@ -508,6 +508,6 @@ data products. The parser's data services functionality can be called from an
 interactive environment such as :ref:`sec:amrvis`, from a sidecar for dynamic performance
 optimization, and from other utilities such as the command line version of the
 parser itself. It has been integrated into Amrvis for visual interpretation of
-the data allowing Amrvis to open the ``bl_prof`` database like a plotfile but with
+the data, allowing Amrvis to open the ``bl_prof`` database like a plotfile but with
 interfaces appropriate to profiling data. AMRProfParser and Amrvis can be run
 in parallel both interactively and in batch mode.

Docs/sphinx_documentation/source/AMReX_Profiling_Tools_Chapter.rst

@@ -13,7 +13,7 @@ More details can be found in the documentation below.
 
 Lecture 1: `Introduction and TINYPROFILER <http://ccse.lbl.gov/AMReX/AMReX_Profiling_Lecture1.pdf>`_
 
-Lecture 2: `Introduction to  Full Profiling <http://ccse.lbl.gov/AMReX/AMReX_Profiling_Lecture2.pdf>`_
+Lecture 2: `Introduction to Full Profiling <http://ccse.lbl.gov/AMReX/AMReX_Profiling_Lecture2.pdf>`_
 
 Lecture 3: `Using ProfVis -- GUI Features <http://ccse.lbl.gov/AMReX/AMReX_Profiling_Lecture3.pdf>`_
 

Docs/sphinx_documentation/source/AmrCore.rst

@@ -25,7 +25,7 @@
 
 .. _fig:Adv:
 
-.. table:: Time sequence (:math:`t=0,0.5,1,1.5,2` s) of advection of a Gaussian profile using the SingleVortex tutorial. The analytic velocity field distorts the profile, and then restores the profile to the original configuration.  The red, green, and blue boxes indicate grids at AMR levels :math:`\ell=0,1`, and :math:`2`.
+.. table:: Time sequence (:math:`t=0, 0.5, 1, 1.5, 2` s) of advection of a Gaussian profile using the SingleVortex tutorial. The analytic velocity field distorts the profile, and then restores the profile to its original configuration. The red, green, and blue boxes indicate grids at AMR levels :math:`\ell=0,1`, and :math:`2`.
    :align: center
 
    +-----+-----+-----+-----+-----+
@@ -85,7 +85,7 @@ The protected data members are:
         Vector<BoxArray>            grids;
 
 The following parameters are frequently set via the inputs file or the command line.
-Their usage is described in the section on :ref:`sec:grid_creation`
+Their usage is described in the section on :ref:`sec:grid_creation`.
 
 .. raw:: latex
 
@@ -127,9 +127,9 @@ have any data members, just additional member functions, some of which override
 the base class AmrMesh.
 
 There are no pure virtual functions in :cpp:`AmrMesh`, but
-there are 5 pure virtual functions in the :cpp:`AmrCore` class. Any applications
+there are five pure virtual functions in the :cpp:`AmrCore` class. Any applications
 you create must implement these functions. The tutorial code
-Amr/Advection_AmrCore provides sample implementation in the derived
+Amr/Advection_AmrCore provides a sample implementation in the derived
 class :cpp:`AmrCoreAdv`.
 
 .. highlight:: c++
@@ -162,8 +162,8 @@ Refer to the :cpp:`AmrCoreAdv` class in the
 ``amrex-tutorials/ExampleCodes/Amr/AmrCore_Advection/Source``
 code for a sample implementation.
 
-TagBox, and Cluster
--------------------
+TagBox and Cluster
+------------------
 
 These classes are used in the grid generation process.
 The :cpp:`TagBox` class is essentially a data structure that marks which
@@ -193,15 +193,15 @@ FillPatchUtil and Interpolater
    :cpp:`operator()` that fills domain boundaries for a :cpp:`MultiFab`.
 
 Many codes, including the Advection_AmrCore example, contain an array of MultiFabs
-(one for each level of refinement), and then use "fillpatch" operations to fill temporary
-MultiFabs that may include a different number of ghost cells. Fillpatch operations fill
-all cells, valid and ghost, from actual valid data at that level, space-time interpolated data
+(one for each level of refinement), and then use FillPatch operations to fill temporary
+MultiFabs that may include a different number of ghost cells. FillPatch operations fill
+all cells, valid and ghost, using actual valid data at that level, space-time interpolated data
 from the next-coarser level, neighboring grids at the same level, and domain
 boundary conditions (for examples that have non-periodic boundary conditions).
 Note that at the coarsest level,
-the interior and domain boundary (which can be periodic or prescribed based on physical considerations)
-need to be filled. At the non-coarsest level, the ghost cells can also be interior or domain,
-but can also be at coarse-fine interfaces away from the domain boundary.
+interior cells and domain boundaries (which can be periodic or prescribed based on physical considerations)
+need to be filled. At non-coarsest levels, the ghost cells can also be interior or on the domain boundary,
+but they can also be at coarse-fine interfaces away from the domain boundary.
 :cpp:`AMReX_FillPatchUtil.cpp/H` contains two primary functions of interest.
 
 #. :cpp:`FillPatchSingleLevel()` fills a :cpp:`MultiFab` and its ghost region at a single level of
@@ -218,11 +218,11 @@ to fill interior, periodic, and physical boundary ghost cells.  In principle, yo
 write a single-level application that calls :cpp:`FillPatchSingleLevel()` instead
 of using :cpp:`MultiFab::FillBoundary` and :cpp:`FillDomainBoundary()`.
 
-A :cpp:`FillPatchUtil` uses an :cpp:`Interpolator`. This is largely hidden from application codes.
+The :cpp:`FillPatchUtil` routines use an :cpp:`Interpolator`. This is largely hidden from application codes.
 AMReX_Interpolater.cpp/H contains the virtual base class :cpp:`Interpolater`, which provides
 an interface for coarse-to-fine spatial interpolation operators. The fillpatch routines described
-above require an Interpolater for FillPatchTwoLevels().
-Within AMReX_Interpolater.cpp/H are the derived classes:
+above require an :cpp:`Interpolater` for :cpp:`FillPatchTwoLevels()`.
+Within AMReX_Interpolater.cpp/H, the derived classes are:
 
 -  :cpp:`NodeBilinear`
 
@@ -240,7 +240,7 @@ Within AMReX_Interpolater.cpp/H are the derived classes:
 
 -  :cpp:`FaceLinear`
 
--  :cpp:`FaceDivFree`: This is more accurately a divergence-preserving interpolation on face centered data, i.e., it ensures the divergence of the fine ghost cells match the value of the divergence of the underlying coarse cell. All fine cells overlying a given coarse cell will have the same divergence, even when the coarse grid divergence is spatially varying. Note that when using this with :cpp:`FillPatch` for time sub-cycling, the coarse grid times may not match the fine grid time, in which case :cpp:`FillPatch` will create coarse values at the fine time before calling this interpolation and the result of the :cpp:`FillPatch` is *not* guaranteed to preserve the original divergence.
+-  :cpp:`FaceDivFree`: This is more accurately a divergence-preserving interpolation on face-centered data, i.e., it ensures the divergence of the fine ghost cells matches the value of the divergence of the underlying coarse cell. All fine cells overlying a given coarse cell will have the same divergence, even when the coarse grid divergence is spatially varying. Note that when using this with :cpp:`FillPatch` for time sub-cycling, the coarse grid times may not match the fine grid time, in which case :cpp:`FillPatch` will create coarse values at the fine time before calling this interpolation and the result of the :cpp:`FillPatch` is *not* guaranteed to preserve the original divergence.
 
 These Interpolaters can be executed on CPU or GPU, with certain limitations:
 
@@ -283,12 +283,12 @@ the coarse grid flux must be compared to the area *and* time-weighted fine grid
 fluxes. A :cpp:`FluxRegister` accumulates and ultimately stores the net
 difference in fluxes between the coarse grid and fine grid advance over each
 face over a given coarse time step. The simplest possible synchronization step
-is to modify the coarse grid solution in coarse cells immediately adjacent to
-the coarse-fine interface are updated to account for the mismatch stored in the
+is to modify the coarse grid solution in the coarse cells immediately adjacent to
+the coarse-fine interface to account for the mismatch stored in the
 FluxRegister. This can be done "simply" by taking the coarse-level divergence of
 the data in the FluxRegister using the :cpp:`reflux` function.
 
-The Fortran routines that perform the actual floating point work associated with
+The Fortran routines that perform the actual floating-point work associated with
 incrementing data in a :cpp:`FluxRegister` are contained in the files
 AMReX_FLUXREG_F.H and AMReX_FLUXREG_xD.F.
 
@@ -358,8 +358,7 @@ easily be thought of as a recursive algorithm in which, to advance level :math:`
 
    \end{center}
 
-Specifically, for a 3-level simulation, depicted graphically in the figure
-showing the :ref:`fig:subcycling` above:
+Specifically, for a 3-level simulation, as depicted in :ref:`fig:subcycling`:
 
 #. Integrate :math:`\ell=0` over :math:`\Delta t`.
 
@@ -415,28 +414,28 @@ Code Structure
    Source code tree for the AmrAdvection_AmrCore example.
 
 
-The figure shows the :ref:`fig:AmrAdvection_AmrCore_flowchart`
+The figure above shows the source tree for the example.
 
 
--  amrex/Src/
+-  ``amrex/Src/``
 
-   -  Base/ Base amrex library.
+   -  ``Base/`` Base AMReX library.
 
-   -  Boundary/ An assortment of classes for handling boundary data.
+   -  ``Boundary/`` An assortment of classes for handling boundary data.
 
-   -  AmrCore/ AMR data management classes, described in more detail above.
+   -  ``AmrCore/`` AMR data management classes, described in more detail above.
 
 
--  ``Advection_AmrCore/Src`` Source code specific to this example. Most notably
-   is the :cpp:`AmrCoreAdv` class, which is derived from :cpp:`AmrCore`. The subdirectories ``Src_2d``
-   and ``Src_3d`` contain dimension specific routines. ``Src_nd`` contains dimension-independent routines.
+-  ``Advection_AmrCore/Src`` contains source code specific to this example. Most notably,
+   it includes the :cpp:`AmrCoreAdv` class, which is derived from :cpp:`AmrCore`. The subdirectories ``Src_2d``
+   and ``Src_3d`` contain dimension-specific routines. ``Src_nd`` contains dimension-independent routines.
 
 
--  Exec Contains a makefile so a user can write other examples besides SingleVortex.
+-  ``Exec`` contains a makefile so that users can write other examples besides ``SingleVortex``.
 
 
--  SingleVortex Build the code here by editing the GNUmakefile and running make. There
-   is also problem-specific source code here used for initialization or specifying the velocity field used in this
+-  ``SingleVortex`` builds the code by editing the ``GNUmakefile`` and running ``make``. There
+   is also problem-specific source code here for initialization and for specifying the velocity field used in this
    simulation.
 
 Here is a high-level pseudo-code of the flow of the program:
@@ -448,7 +447,7 @@ Here is a high-level pseudo-code of the flow of the program:
     /* Advection_AmrCore Pseudocode */
     main()
       AmrCoreAdv amr_core_adv; // build an AmrCoreAdv object
-      amr_core_adv.InitData()  // initialize data all all levels
+      amr_core_adv.InitData()  // initialize data on all levels
         AmrCore::InitFromScratch()
         AmrMesh::MakeNewGrids()
         AmrMesh::MakeBaseGrids() // define level 0 grids
@@ -547,12 +546,12 @@ Regridding
 ----------
 
 The regrid function belongs to the :cpp:`AmrCore` class (it is virtual -- in this
-tutorial we use the instance in :cpp:`AmrCore`).
+tutorial we use the implementation in :cpp:`AmrCore`).
 
 At the beginning of each time step, we check whether we need to regrid.
-In this example, we use a :cpp:`regrid_int` and keep track of how many times each level
-has been advanced. When any given particular level :math:`\ell<\ell_{\rm max}` has been
-advanced a multiple of :cpp:`regrid_int`, we call the :cpp:`regrid` function.
+In this example, we use :cpp:`regrid_int` and keep track of how many times each level
+has been advanced. When any given level :math:`\ell<\ell_{\rm max}` has been
+advanced a number of times equal to a multiple of :cpp:`regrid_int`, we call the :cpp:`regrid` function.
 
 .. highlight:: c++
 
@@ -568,7 +567,7 @@ advanced a multiple of :cpp:`regrid_int`, we call the :cpp:`regrid` function.
             {
                 if (istep[lev] % regrid_int == 0)
                 {
-                    // regrid could add newly refine levels
+                    // regrid could add newly refined levels
                     // (if finest_level < max_level)
                     // so we save the previous finest level index
             int old_finest = finest_level;
@@ -582,7 +581,7 @@ advanced a multiple of :cpp:`regrid_int`, we call the :cpp:`regrid` function.
         }
         }
 
-Central to the regridding process is the concept of "tagging" which cells need refinement.
+Central to the regridding process is the concept of "tagging" cells that need refinement.
 :cpp:`ErrorEst` is a pure virtual function of :cpp:`AmrCore`, so each application code must
 contain an implementation. In AmrCoreAdv.cpp the ErrorEst function is essentially an
 interface to a Fortran routine that tags cells (in this case, :fortran:`state_error` in