Update GCHP documentation and changelog for 14.1.0 and 14.1.1

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

CHANGELOG.md

@@ -14,9 +14,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 ### Changed
 - Changed "carboncycle" to "carbon" in `src/GCHP_GridComp/GEOSChem_GridComp/CMakeLists.txt`
 - Simplified Github issue and pull request templates
+- Updated ReadTheDocs to specify 8.1 is minimum version of ESMF
+- Updated version numbers in `CMakeLists.txt` and `docs/source/conf.py` to 14.1.1
 
 ### Fixed
 - Fixed global attributes written to stretched grid checkpoint files to enable restart
+- Fixed day-of-week scale factor handling in MAPL ExtData
+- Fixed stretched grid checkpoint file issue in MAPL that prevented restarting stretched grid simulations
 
 ## [14.1.0] - 2023-02-01
 ### Changed

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required (VERSION 3.13)
 project (gchp_ctm
-  VERSION 14.1.0
+  VERSION 14.1.1
   LANGUAGES Fortran CXX C
 )
 

docs/source/conf.py

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

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

@@ -19,18 +19,32 @@ Download the source code:
    gcuser:~$ git clone https://github.com/geoschem/GCHP.git ~/GCHP
    gcuser:~$ cd ~/GCHP
 
-Checkout the GEOS-Chem version that you want to use:
+Upon download you will have the most recently released version. You can check what this is by printing the last commit in the git log and scanning the output for tag.
 
 .. code-block:: console
 
-   gcuser:~/GCHP$ git checkout 14.0.0
+   gcuser:~/GCHP$ git log -n 1
 
-Initialize and update all the submodules:
+You can stay with this version or checkout an earlier version by its tag name:
+
+.. code-block:: console
+
+   gcuser:~/GCHP$ git checkout tags/13.3.4
+
+You can see a list of all possible tables using the git tag command:
+
+.. code-block:: console
+
+   gcuser:~/GCHP$ git tag
+
+When you have the version you wish to use you must initialize and update all the submodules:
 
 .. code-block:: console
 
    gcuser:~/GCHP$ git submodule update --init --recursive
 
+Repeat this last step every time you switch to a new version of GCHP.
+
 2. Create a run directory
 -------------------------
 
@@ -45,10 +59,7 @@ To create a run directory, run :file:`./createRunDir.sh` and answer the prompts:
 3. Configure your build
 -----------------------
 
-Create a build directory and :command:`cd` into it. 
-A good name for this directory is :file:`build/`, and you may put this directory anywhere on your system, such as in the top-level of the source code or in your run directory. 
-The GCHP build directory will require 1.4G of storage space. 
-In this guide we put it in the source code:
+Building GCHP will require 1.4G of storage space. You may build GCHP from within the run directory or from anywhere else on your system. Building from within the run directory is convenient because it keeps all build files in close proximity to where you will run GCHP. For this purpose the GCHP run directory includes a build directory called :file:`build/`. However, you can create a build directory elsewhere, such as within the GCHP source code. In this guide we will do both, starting with building from the source code.
 
 .. code-block:: console
 
@@ -64,9 +75,9 @@ Make sure you have loaded all libraries required for GCHP prior to this step.
 
 Now you can configure :ref:`build options <gchp_build_options>`. 
 These are persistent settings that are saved to your build directory.
-A common build option is :literal:`-DRUNDIR`. 
+A useful build option is :literal:`-DRUNDIR`. 
 This option lets you specify one or more run directories that GCHP is "installed" to, meaning where the executable is copied, when you do :command:`make install`. 
-Configure your build so it installs GCHP to the run directory you created in Step 2:
+Configure your build so it installs GCHP to the run directory you created in Step 2.
 
 .. code-block:: console
 
@@ -75,18 +86,27 @@ Configure your build so it installs GCHP to the run directory you created in Ste
 .. note::
    The :literal:`.` in the :program:`cmake` command above is important. It tells CMake that your current working directory (i.e., :literal:`.`) is your build directory.
 
-If you decide instead to build GCHP in your run directory you can do all of the above in one step making use of the :literal:`CodeDir` symbolic link in the run directory:
+If you decide instead to build GCHP in your run directory you can do all of the above in one step. This makes use of the :literal:`CodeDir` symbolic link in the run directory:
 
 .. code-block:: console
 
+   gcuser:/path/to/your/run/directory/$ cd build
    gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=..
 
+GEOS-Chem has a number of optional compiler flags you can add here. For example, to compile with RRTMG:
+
+   gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. -DRRTMG=y
+
+A useful compiler option is to build in debug mode. Doing this is a good idea if you encountered a segmentation fault in a previous run and need more information about where the error happened and why.
+
+   gcuser:/path/to/your/run/directory/build$ cmake ../CodeDir -DRUNDIR=.. -DCMAKE_BUILD_TYPE=Debug
+
+See the GEOS-Chem documentation for more information on compiler flags.
 
 4. Compile and install
 ----------------------
 
-Compiling GCHP takes about 20 minutes, but it can vary depending on your system. 
-Next, compile GCHP in parallel using as many cores as are available:
+Compiling GCHP takes about 20 minutes, but it can vary depending on your system, your compiler, and your compiler flags. To maximize build speed you should compile GCHP in parallel using as many cores as are available. Do this with the -j flag:
 
 .. code-block:: console
 
@@ -104,10 +124,12 @@ This copies :file:`bin/gchp` and supplemental files to your run directory.
    You can update build settings at any time:
 
    1. Navigate to your build directory.
-   2. Update your build settings with :program:`cmake`.
+   2. Update your build settings with :program:`cmake` (only if they differ since your last execution of cmake)
    3. Recompile with :command:`make -j`. Note that the build system automatically figures out what (if any) files need to be recompiled.
    4. Install the rebuilt executable with :command:`make install`.
 
+If you do not install the executable to your run directory you can always get the executable from the directory :command:`build/bin`.
+
 
 5. Configure your run directory
 -------------------------------

docs/source/getting-started/requirements.rst

@@ -13,8 +13,8 @@ To build and run GCHP your compute :term:`environment` needs the following softw
 * CMake version ≥ 3.13
 * Compilers (C, C++, and Fortran):
 
-   * Intel compilers version ≥ 18.0.5, or
-   * GNU compilers version ≥ 8.3
+   * Intel compilers version ≥ 19, or
+   * GNU compilers version ≥ 10
 
 * MPI (Message Passing Interface)
 
@@ -26,7 +26,7 @@ To build and run GCHP your compute :term:`environment` needs the following softw
 
 * HDF5
 * NetCDF (with C, C++, and Fortran support)
-* ESMF version ≥ 8.0.0
+* ESMF version ≥ 8.1.0
 
 Your system administrator should be able to tell you if this software is already available on your cluster, and if so, how to activate it.
 If it is not already available, they might be able to build it for you.
@@ -51,13 +51,12 @@ applications:
 * 2 nodes, preferably ≥24 cores per node
 * Gigabit Ethernet (GbE) interconnect or better
 * 100 GB memory per node
-* 1 TB of storage
+* 1 TB of storage, depending on your input and output needs
 
 Bare Minimum Requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-These bare minimum requirements are sufficient for running GCHP at C24. The are adequate 
-for trying GCHP out, and for learning purposes.
+These bare minimum requirements are sufficient for running GCHP at C24. They are adequate for trying GCHP out, and for learning purposes. Please note that we recommend running at C90 or greater for scientific applications.
 
 * 6 cores
 * 32 GB of memory
@@ -66,8 +65,7 @@ for trying GCHP out, and for learning purposes.
 Big Compute Recommendations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-These hardware recommendations are for users that are interested in tackling large bleeding-edge
-computational problems:
+These hardware recommendations are for users that are interested in tackling large bleeding-edge computational problems:
 
 * A high-performance-computing cluster (or a cloud-HPC service like AWS)
 

docs/source/index.rst

@@ -12,15 +12,15 @@ GEOS-Chem High Performance
    <a href="https://github.com/geoschem/GCHP/releases"><img src="https://img.shields.io/github/v/release/geoschem/GCHP?include_prereleases&label=Latest%20Pre-Release"></a>
    </p>
 
-The `GEOS--Chem model <http://acmg.seas.harvard.edu/geos/>`_ is a global 3-D model of atmospheric
+The `GEOS--Chem model <http://geos-chem.org/>`_ is a global 3-D model of atmospheric
 composition driven by assimilated meteorological observations from the Goddard Earth Observing
 System (GEOS) of the `NASA Global Modeling and Assimilation Office <http://gmao.gsfc.nasa.gov/>`_.
 It is applied by `research groups around the world
 <http://acmg.seas.harvard.edu/geos/geos_people.html>`_ to a wide range of atmospheric composition
 problems.
 
-* `GEOS-Chem Overview <http://acmg.seas.harvard.edu/geos/geos_overview.html>`_
-* `Narrative description of GEOS-Chem <http://acmg.seas.harvard.edu/geos/geos_chem_narrative.html>`_
+* `GEOS-Chem Overview <http://geos-chem.org/geos-overview>`_
+* `Narrative description of GEOS-Chem <http://geos-chem.org/geos-chem-narrative>`_
 
 This site provides instructions for GEOS-Chem High Performance, GEOS-Chem's multi-node variant. We provide two different
 instruction sets for downloading and compiling GCHP: from a clone of the source code, or using the Spack package manager. 

docs/source/user-guide/config-files/CAP_rc.rst

@@ -46,3 +46,6 @@ USE_SHMEM
 
 REVERSE_TIME	
    Enables running time backwards in CAP. Default is 0 (off).
+
+USE_EXTDATA2G
+   Enables using the next generation of MAPL ExtData (input component) which uses a yaml-format configuration file. Default is .FALSE. (off).

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

@@ -32,7 +32,9 @@ Below are detailed explanations of the prompts in :file:`./createRunDir.sh`.
 Enter ExtData path
 ^^^^^^^^^^^^^^^^^^
 
-The first time you create a GCHP run directory on your system you will be prompted for a path to GEOS-Chem shared data directories. 
+The first time you create a GCHP run directory on your system you will be prompted to register as a GEOS-Chem user. Please provide this information so that we can track GEOS-Chem user groups around the world and get to know what GEOS-Chem is used for.
+
+Following registration you will be prompted for a path to GEOS-Chem shared data directories.
 The path should include the name of your :file:`ExtData/` directory and should not contain symbolic links. 
 The path you enter will be stored in file :file:`.geoschem/config` in your home directory as environment variable :envvar:`GC_DATA_ROOT`. 
 If that file does not already exist it will be created for you. 
@@ -51,11 +53,15 @@ Enter the integer number that is next to the simulation type you want to use.
 
 .. code-block:: none
 
-   -----------------------------------------------------------
-   Choose simulation type:
-   -----------------------------------------------------------
-     1. Full chemistry
-     2. TransportTracers
+     -----------------------------------------------------------
+     Choose simulation type:
+     -----------------------------------------------------------
+       1. Full chemistry
+       2. TransportTracers
+       3. CO2 w/ CMS-Flux emissions
+       4. Tagged O3
+       5. Carbon
+     >>>
 
 If creating a full chemistry run directory you will be given additional options. Enter the integer number that is next to the simulation option you want to run.
 
@@ -72,11 +78,12 @@ If creating a full chemistry run directory you will be given additional options.
      6. TOMAS
      7. APM
      8. RRTMG
+   >>>
 
 Choose meteorology source
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Enter the integer number that is next to the input meteorology source you would like to use.
+Enter the integer number that is next to the input meteorology source you would like to use. The primary difference between GEOS-FP and GEOS-FP native data is that the GEOS-FP native data includes the option to use C720 mass fluxes or derived winds. 
 
 .. code-block:: none
 
@@ -85,6 +92,8 @@ Enter the integer number that is next to the input meteorology source you would
    -----------------------------------------------------------
      1. MERRA2 (Recommended)
      2. GEOS-FP
+     3. GEOS-FP native data
+   >>>
 
 Enter run directory path
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -96,6 +105,7 @@ Enter the target path where the run directory will be stored. You will be prompt
    -----------------------------------------------------------
    Enter path where the run directory will be created:
    -----------------------------------------------------------
+   >>>
 
 Enter run directory name
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -106,7 +116,10 @@ Enter the run directory name, or accept the default. You will be prompted for a
 
    -----------------------------------------------------------
    Enter run directory name, or press return to use default:
+
+   NOTE: This will be a subfolder of the path you entered above.
    -----------------------------------------------------------
+   >>>
 
 Enable version control (optional)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^