Updates to Getting-Started and User-Guide sections

Signed-off-by: Lizzie Lundgren <elundgren@seas.harvard.edu>

docs/source/bibtex.json

@@ -6,7 +6,8 @@
             "Long_et_al._2015",
             "Eastham_et_al._2018",
             "Zhuang_et_al._2020",
-            "Bindle_et_al._2021"
+            "Bindle_et_al._2021",
+            "Lin_et_al._2021",
         ],
         "stretched-grid": [
             "Bindle_et_al._2021"

docs/source/conf.py

@@ -19,11 +19,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'GCHP'
-copyright = '2021, GEOS-Chem Support Team'
+copyright = '2022, GEOS-Chem Support Team'
 author = 'GEOS-Chem Support Team'
 
 # The full version, including alpha/beta/rc tags
-release = '13.0.2'
+release = '14.0.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/getting-started/key-references.rst

@@ -2,7 +2,7 @@ Key References
 ==============
 
 * GEOS-Chem was first described in :cite:`Bey_et_al._2001`. 
-* HEMCO is described in :cite:`Keller_et_al._2014`.
+* HEMCO is described in :cite:`Keller_et_al._2014` and :cite:`Lin_et_al._2021`.
 * Columnar operators are described in :cite:`Long_et_al._2015`.
 * GEOS-Chem High Performance (GCHP) is described in :cite:`Eastham_et_al._2018`.
 * GCHP execution on the cloud and MPI considerations are described in :cite:`Zhuang_et_al._2020`.

docs/source/getting-started/quick-start.rst

@@ -118,27 +118,27 @@ Now, navigate to your run directory:
 
    $ cd path/to/your/run/directory
 
-Commonly changed simulation settings, such as grid resolution, run duration, and number of cores, are set in :file:`./setCommonRunSettings.sh`. 
+Commonly changed simulation settings, such as grid resolution, run duration, and number of cores, are set in :file:`setCommonRunSettings.sh`. 
 You should review this file as it explains most settings.
-Note that :file:`./setCommonRunSettings.sh` is actually a helper script that updates other configuration files. 
+Note that :file:`setCommonRunSettings.sh` is actually a helper script that updates other configuration files. 
 You therefore need to run it to actually apply the settings:
 
 .. code-block:: console
 
    $ vim setCommonRunSettings.sh           # edit simulation settings here
    $ ./setCommonRunSettings.sh             # applies the updated settings
 
-Simulation start date is set in :file:`./cap_restart`. 
-Run directories come with this file filled in based on date of the initial restart file in subdirectory :literal:`./Restarts`. 
-You can change the start date only if you have a restart file for the new date in :literal:`./Restarts`. 
-A symbolic link called :file:`gchp_restart.nc4` points to the restart file for the date in :file:`./cap_restart` and the grid resolution in :file:`./setCommonRunSettings.sh`.  
+Simulation start date is set in :file:`cap_restart`. 
+Run directories come with this file filled in based on date of the initial restart file in subdirectory :file:`Restarts`. 
+You can change the start date only if you have a restart file for the new date in :file:`Restarts`. 
+A symbolic link called :file:`gchp_restart.nc4` points to the restart file for the date in :file:`cap_restart` and the grid resolution in :file:`setCommonRunSettings.sh`.  
 You need to set this symbolic link before running:
 
 .. code-block:: console
 
    $ ./setRestartLink.sh                   # sets symbolic link to target file in Restarts
 
-If you used an environment file to load libraries prior to building GCHP then you should load that file prior to running. A simple way to make sure you always use the correct combination of libraries is to set the GCHP environment symbolic link :literal:`./gchp.env` in the run directory:
+If you used an environment file to load libraries prior to building GCHP then you should load that file prior to running. A simple way to make sure you always use the correct combination of libraries is to set the GCHP environment symbolic link :file:`gchp.env` in the run directory:
 
 .. code-block:: console
 
@@ -165,7 +165,7 @@ This means that you write a script (usually bash) that configures and runs your
 Example job scripts are provided in subdirectory :literal:`./runScriptSamples` in the run directory. 
 That folder also includes an example script for running GCHP from the command line.
 
-Several steps beyond running GCHP are included in the example run scripts. These include loading the environment, updating commonly changed run settings, and setting the restart file based on start time and grid resolution.  In addition, the output restart file is moved and renamed to the :literal:`./Restarts` subdirectory upon successful completion of the run.
+Several steps beyond running GCHP are included in the example run scripts. These include loading the environment, updating commonly changed run settings, and setting the restart file based on start time and grid resolution.  In addition, the output restart file is moved to the :file:`Restarts` subdirectory and renamed to include start date and grid resolution upon successful completion of the run.
 
 .. note::
    File :file:`cap_restart` is over-written to contain the run end date upon successful completion of a GCHP run. This is done within GCHP and not by the run script. You can then easily submit a new GCHP run starting off where your last run left off. In addition, GCHP outputs a restart file to your run directory called :file:`gcchem_internal_checkpoint`. This file is moved to subdirectory :literal:`Restarts` and renamed to include the date and grid resolution. This is done by the run script and technically is optional. We recommend doing this since it is is good for archiving (restart files will contain date and grid res) and enables use of the :file:`./setRestartLink.sh` script to set the :file:`gchp_restart.nc4` symbolic link.

docs/source/getting-started/requirements.rst

@@ -6,7 +6,7 @@ System Requirements
 Software Requirements
 ---------------------
 
-To build and run GCHP you compute :term:`environment` needs the following software:
+To build and run GCHP your compute :term:`environment` needs the following software:
 
 * Git
 * Make (or GNUMake)
@@ -57,7 +57,7 @@ Bare Minimum Requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 These bare minimum requirements are sufficient for running GCHP at C24. The are adequate 
-for try GCHP out, and for learning purposes.
+for trying GCHP out, and for learning purposes.
 
 * 6 cores
 * 32 GB of memory
@@ -77,11 +77,21 @@ computational problems:
 
 * Lots of storage. Several TB is sufficient, but tens or hundreds of TB is better.
 
-Other Recommendations
-^^^^^^^^^^^^^^^^^^^^^
+General Hardware and Software Recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Hyper-threading may improve simulation throughput, particularly at low core counts
+
 * MPI process should be bound sequentially across cores and nodes (e.g., a simulation with 48-processes with 24 processes per node 
   should bind rank 0 to CPU L#0, rank 1 to CPU L#1, etc. on the first node, and rank 24 to CPU L#0, rank 1 to CPU L#1, etc. on the 
   second node). This should be the default, but it's worth checking if your performance is lower than expected. With OpenMPI the
   `--report-bindings` argument will show you how processes are ranked and binded.
+
+* If using IntelMPI include the following your environment setup to avoid a run-time error:
+
+.. code-block:: bash
+
+    export I_MPI_ADJUST_GATHERV=3
+    export I_MPI_ADJUST_ALLREDUCE=12
+
+* If using OpenMPI and a large number of cores (>1000) we recommend setting :literal:`WRITE_RESTART_BY_OSERVER: YES` in config file :file:`GCHP.rc`. This enables the MAPL o-server functionality for writing restart files, thereby speeding up the mdoel. This is set automatically when executing :file:`setCommonRunSettings.sh`.

docs/source/user-guide/compiling.rst

@@ -1,11 +1,10 @@
 .. note::
    Compiling GCHP and creating a run directory are independent steps, and their order doesn't matter. A small exception
-   is the :ref:`RUNDIR <build_setting_rundir>` build option, which controls the behaviour of :command:`make install`;
+   is the :ref:`RUNDIR <build_setting_rundir>` build option, which controls the behaviour of :command:`make install` which copies the GCHP executable to the run directory;
    however, this setting can be reconfigured at any time (e.g., after compiling and creating a run directory). 
 
-   Here in the User Guide, we describe compiling GCHP before we describe creating a run directory. This is
-   so that conceptually the instructions have a linear flow. The Quickstart Guide uses the opposite ordering
-   to minimize the number of commands.
+   Here in the User Guide we describe compiling GCHP before we describe creating a run directory. This is
+   so that conceptually the instructions have a linear flow. The Quickstart Guide, on the other hand, shows how to make a run directory prior to compiling.
 
 .. note::
    Another resource for GCHP build instructions is our `YouTube tutorial <https://www.youtube.com/watch?v=G_DMCv-mJ2k>`_.
@@ -15,13 +14,13 @@
 Compiling GCHP
 ==============
 
-There are two steps to building GCHP. The first is configuring your build, which is done with :program:`cmake`; 
-the second step is compiling, which is done with :program:`make`.
+There are three steps to building GCHP. The first is configuring your build, which is done with :program:`cmake`; 
+the second step is compiling, which is done with :program:`make`. The third step is install, which is also done with :program:`make`.
 
 In the first step (build configuration), :program:`cmake` finds GCHP's :ref:`software dependencies <software_requirements>`
 on your system, and you can set :ref:`build options <gchp_build_options>` like
-enabling/disabling components, setting paths to run directories, picking between debug or speed-optimizing compiler
-flags, etc. The second step (running :program:`make`) compiles GCHP according your build configuration.
+enabling/disabling components (such as RRTMG), setting paths to run directories, picking between debug or speed-optimizing compiler
+flags, etc. The second step (running :program:`make`) compiles GCHP according your build configuration. The third step copies GCHP executable to an appropriate location, such as one or more run directories if you specify them.
 
 .. important::
    These instructions assume you have loaded a computing environment that satisfies

docs/source/user-guide/downloading.rst

@@ -8,7 +8,7 @@ the repository:
 
 .. code-block:: console
 
-   gcuser:~$ git clone https://github.com/geoschem/GCHP.git Code.GCHP
+   gcuser:~$ git clone https://github.com/geoschem/GCHP.git GCHP
 
 The GCHP repository has submodules (other repositories that are 
 nested inside the GCHP repository) that aren't automatically retrieved when
@@ -17,20 +17,20 @@ initialize and update the submodules:
 
 .. code-block:: console
 
-   gcuser:~$ cd Code.GCHP
-   gcuser:~/Code.GCHP$ git submodule update --init --recursive
+   gcuser:~$ cd GCHP
+   gcuser:~/GCHP$ git submodule update --init --recursive
 
 
-By default, the source code will be on the :literal:`main` branch. Checking out
-an official release is recommended because they are scientifically-validated versions of the
-code, and it records the version for your future reference. You can find the list
-of GCHP releases `here <https://github.com/geoschem/GCHP/releases>`_.
-Checkout the version that you want to work with, and update the submodules:
+By default, the source code will be on the :literal:`main` branch which is always the last offocial release of GCHP. 
+Checking out the official release is recommended because it is a scientifically-validated version of the
+code and is easily citable. You can find the list
+of past and present GCHP releases `here <https://github.com/geoschem/GCHP/releases>`_.
+Checkout the release that you want to work with, and update the submodules:
 
 .. code-block:: console
 
-   gcuser:~/Code.GCHP$ git checkout 13.3.4
-   gcuser:~/Code.GCHP$ git submodule update --init --recursive
+   gcuser:~/GCHP$ git checkout 13.3.4
+   gcuser:~/GCHP$ git submodule update --init --recursive
 
 --------------------------------------------------------------------------------------
 
@@ -39,10 +39,10 @@ Run :command:`git status` to check that there are no differences:
 
 .. code-block:: console
 
-   gcuser:~/Code.GCHP$ git status
+   gcuser:~/GCHP$ git status
    HEAD detached at 13.3.4
    nothing to commit, working tree clean
-   gcuser:~/Code.GCHP$
+   gcuser:~/GCHP$
 
-The output of :command:`git status` should say that you are at the right version and
-that there are no modifications (nothing to commit, and a clean working tree).
+The output of :command:`git status` should confirm your GCHP version and
+that there are no modifications (nothing to commit, and a clean working tree). It also says that you are are in detached HEAD state, meaning you are not in a GCHP git software branch. This is true for all submodules in the model as well. If you wish to use version control to track your changes you must checkout a new branch to work on in the directory you will be developing.

docs/source/user-guide/rundir-init.rst

@@ -10,15 +10,15 @@ and answer the prompts:
 
 .. code-block:: console
 
-   gcuser:~$ cd Code.GCHP/run
-   gcuser:~/Code.GCHP/run$ ./createRunDir.sh
+   gcuser:~$ cd GCHP/run
+   gcuser:~/GCHP/run$ ./createRunDir.sh
    ... <answer the prompts> ...
    
 .. important::
    Use :term:`absolute paths <absolute path>` when responding to prompts.
 
-Create a run directory. If you are unsure what a prompt is asking, see their explanations below, or ask a question 
-on GitHub. After creating a run directory, you can move on to the next section.
+If you are unsure what a prompt is asking, see their explanations below, or ask a question 
+on GitHub. After following all prompts a run directory should be created for you with a confirmation message, and, you can move on to the next section.
 
 -------------------------------------------------------------------------------------------