RTD updates for 14.4.0

- Move rundir-ch4.rst to rundir-carbon.rst - Update rundir creation & code compilation examples for 14.4.0 - Update geoschem-config.rst to 14.4.0 - Now point to the HISTORY.rc example in the geos-chem-shared-docs - Fix incorrect link in known-bugs.rst; Also add link to bug fixes Signed-off-by: Bob Yantosca <[email protected]>
geoschem · May 15, 2024 · ef7af4d · ef7af4d
1 parent 0939e6e
commit ef7af4d
Show file tree

Hide file tree

Showing 13 changed files with 532 additions and 494 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -33,7 +33,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Updated HEMCO submodule to 3.8.1
 - Now use short submodule names (i.e. without the full path) in `.gitmodules`
 - Remove obsolete CH4 menu options from config file documentation
->>>>>>> dev/14.4.0
 
 ## [14.3.0] - 2024-02-07
 ### Changed

diff --git a/docs/source/gcclassic-user-guide/compile-cmake.rst b/docs/source/gcclassic-user-guide/compile-cmake.rst
@@ -38,12 +38,11 @@ directory listing as shown below:
 
    $ cd /path/to/gc_4x5_merra2_fullchem
    $ ls
-   archiveRun.sh*      GEOSChem.Restart.20190701_0000z.nc4   metrics.py
-   build/              getrunInfo*                           OutputDir/
-   cleanRunDir.sh*     HEMCO_Config.rc                       README
-   CodeDir@            HEMCO_Diagn.rc                        rundir.version
-   download_data.py*   HISTORY.rc                            runScriptSamples
-   download_data.yml   input.geos                            species_database.yml
+   archiveRun.sh*     download_data.py*    HEMCO_Config.rc.gmao_metfields  README.md
+   build/             download_data.yml    HEMCO_Diagn.rc                  Restarts/
+   cleanRunDir.sh*    geoschem_config.yml  HISTORY.rc                      runScriptSamples@
+   CodeDir@           getRunInfo*          metrics.py*                     species_database.yml
+   CreateRunDirLogs/  HEMCO_Config.rc      OutputDir/
 
 Note that each GEOS-Chem run directory that you generate has a folder
 named :file:`build/`. This is where we will run CMake.
@@ -87,61 +86,68 @@ generate output similar to this:
 
 .. code-block:: text
 
-   -- The Fortran compiler identification is GNU 11.2.0
-   -- Detecting Fortran compiler ABI info
-   -- Detecting Fortran compiler ABI info - done
-   -- Check for working Fortran compiler: /n/home09/ryantosca/spack/var/spack/environments/gc-classic/.spack-env/view/bin/gfortran - skipped
-   -- Checking whether /n/home09/ryantosca/spack/var/spack/environments/gc-classic/.spack-env/view/bin/gfortran supports Fortran 90
-   -- Checking whether /n/home09/ryantosca/spack/var/spack/environments/gc-classic/.spack-env/view/bin/gfortran supports Fortran 90 - yes
    =================================================================
    GCClassic X.Y.Z (superproject wrapper)
    Current status: X.Y.Z
    =================================================================
-   -- Found NetCDF: /n/home09/ryantosca/spack/opt/spack/linux-centos7-x86_64/gcc-8.3.0/netcdf-fortran-4.5.3-tb3oqspkitgcbkcyp623tdq2al6gxmom/lib/libnetcdff.so
+   -- Found NetCDF: /path/to/netcdf-fortran/lib/libnetcdff.so
    -- Useful CMake variables:
-     + CMAKE_PREFIX_PATH:    /path/to/netcdf-c /path/to/netcdf-fortran
+     + CMAKE_PREFIX_PATH:    /path/to/netcdf-c/
+     ...             /path/to/netcdf-fortran/
      + CMAKE_BUILD_TYPE:     Release
    -- Run directory setup:
-     + RUNDIR:       /n/holyscratch01/jacob_lab/ryantosca/tests/test/test_cc
+     + RUNDIR:       /path/to/run/directory
    -- Threading:
-     * OMP:          **ON**  OFF
+     * OMP:          *ON*  OFF
    -- Found OpenMP_Fortran: -fopenmp (found version "4.5")
    -- Found OpenMP: TRUE (found version "4.5")
    -- General settings:
      * MECH:         **fullchem**  carbon  Hg  custom
-     * USE_REAL8:    **ON**  OFF
-     * SANITIZE:     ON  **OFF**
+     * USE_REAL8:    *ON*  OFF
+     * SANITIZE:      ON  *OFF*
    -- Components:
-     * TOMAS:        ON  **OFF**
-     * TOMAS_BINS:   **NA**  15  40
-     * APM:          ON  **OFF**
-     * RRTMG:        ON  **OFF**
-     * GTMM:         ON  **OFF**
-     * HCOSA:        ON  **OFF**
-     * LUO_WETDEP:   ON  **OFF**
-     * FASTJX:       ON  **OFF**
+     * TOMAS:         ON  *OFF*
+     * TOMAS_BINS:   *NA*  15  40
+     * APM:           ON  *OFF*
+     * RRTMG:         ON  *OFF*
+     * GTMM:          ON  *OFF*
+     * HCOSA:         ON  *OFF*
+     * LUO_WETDEP:    ON  *OFF*
+     * FASTJX:        ON  *OFF*
    =================================================================
    HEMCO A.B.C
    Current status: A.B.C
    =================================================================
    =================================================================
-   GEOS-Chem T.U.V (science codebase)
-   Current status: T.U.V
+   HETP D.E.F
    =================================================================
-   Creating /n/holyscratch01/jacob_lab/ryantosca/tests/test/test_cc/CodeDir/src/GEOS-Chem/Interfaces/GCClassic/gc_classic_version.H
+   =================================================================
+   Cloud-J G
+   Current status: G
+   =================================================================
+   =================================================================
+   GEOS-Chem X.Y.Z (science codebase)
+   Current status: X.Y.Z
+   =================================================================
+   Creating /path/to/run/directory/CodeDir/src/GEOS-Chem/Interfaces/GCClassic/gc_classic_version.H
    -- Configuring done
    -- Generating done
-   -- Build files have been written to: /n/holyscratch01/jacob_lab/ryantosca/tests/test/test_cc/build
+   -- Build files have been written to: /path/to/run/directory
 
 Your CMake command's output contains important information about your
 build's configuration.
 
 .. note::
 
-   The text :literal:`X.Y.Z`, :literal:`A.B.C`, and :literal:`T.U.V`
+   The text :literal:`X.Y.Z`, :literal:`A.B.C`, :literal:`D.E.F.`,
+   and :literal:`G`
    refer to the version numbers (in `semantic versioning
-   <https://semver.org>`_ style) of the GCClassic, HEMCO, and
-   GEOS-Chem "science codebase" repositories.
+   <https://semver.org>`_ style) of the GCClassic, HEMCO, HETP,
+   and Cloud-J repositories.
+
+   The GEOS-Chem "science codebase" repository and GCClassic
+   repository wrapper share the same version number :literal:`X.Y.Z`.
+
 
 .. _compile-cmake-step4:
 
@@ -303,6 +309,11 @@ options, unless you explicitly specify otherwise.
 
       Deactivates the RRTMG radiative transfer model. **(Default option)**
 
+
+.. option:: HCOSA
+
+   Compiles the HEMCO standalone executable.
+
 .. option:: LUO_WETDEP
 
    Configures GEOS-Chem to use the `Luo et al., 2020

diff --git a/docs/source/gcclassic-user-guide/compile-info.rst b/docs/source/gcclassic-user-guide/compile-info.rst
@@ -13,7 +13,7 @@ directory listing:
    $ cd build_info
    $ ls -CF
    CMakeCache.txt  summarize_build*
-   
+
 :file:`CMakeCache.txt` contains the **CMake cache**, which is a complete
 listing of all compilation settings.  :file:`summarize_build` is a
 script that will print the most important of these CMake cache
@@ -29,23 +29,24 @@ You will get output similar to this:
 
 .. code-block:: bash
 
+   $ ./summarize_build
    ## Compiler Info
    #  Family:   GNU
-   #  Version:  11.2.0
-   #  Which:    /path/to/gfortran
-   
+   #  Version:  10.2.0
+   #  Which:    /n/sw/helmod-rocky8/apps/Core/gcc/10.2.0-fasrc01/bin/gfortran
+
    ## Compiler Options (global)
    -DCMAKE_Fortran_FLAGS=""
-   -DCMAKE_Fortran_FLAGS_DEBUG="-g"
-   
+   -DCMAKE_Fortran_FLAGS_RELEASE="-O3"
+
    ## Compiler Options (GEOS-Chem)
-   -DGEOSChem_Fortran_FLAGS_GNU="-g;-cpp;-w;-std=legacy;-fautomatic;-fno-align-commons;-fconvert=big-endian;-fno-range-check;-mcmodel=medium;-fbacktrace;-g;-DLINUX_GFORTRAN;-ffree-line-length-none"
-   -DGEOSChem_Fortran_FLAGS_DEBUG_GNU="-O0;-Wall;-Wextra;-Wconversion;-Warray-temporaries;-fcheck=array-temps;-ffpe-trap=invalid,zero,overflow;-finit-real=snan;-fcheck=bounds;-fcheck=pointer"
-   
+   -DGEOSChem_Fortran_FLAGS_GNU="-cpp;-w;-std=legacy;-fautomatic;-fno-align-commons;-fconvert=big-endian;-fno-range-check;-mcmodel=medium;-fbacktrace;-g;-DLINUX_GFORTRAN;-ffree-line-length-none"
+   -DGEOSChem_Fortran_FLAGS_RELEASE_GNU="-O3;-funroll-loops"
+
    ## Compiler Options (HEMCO)
    -DHEMCO_Fortran_FLAGS_GNU="-cpp;-w;-std=legacy;-fautomatic;-fno-align-commons;-fconvert=big-endian;-fno-range-check;-mcmodel=medium;-fbacktrace;-g;-DLINUX_GFORTRAN;-ffree-line-length-none"
-   -DHEMCO_Fortran_FLAGS_DEBUG_GNU="-g;-gdwarf-2;-gstrict-dwarf;-O0;-Wall;-Wextra;-Wconversion;-Warray-temporaries;-fcheck=array-temps;-ffpe-trap=invalid,zero,overflow;-finit-real=snan;-fcheck=bounds;-fcheck=pointer;-fcheck=no-recursion"
-   
+   -DHEMCO_Fortran_FLAGS_RELEASE_GNU="-O3;-funroll-loops"
+
    ## GEOS-Chem Components Settings
    -DTOMAS="OFF"
    -DTOMAS_BINS="NA"

diff --git a/docs/source/gcclassic-user-guide/compile-make.rst b/docs/source/gcclassic-user-guide/compile-make.rst
@@ -15,31 +15,25 @@ Use the :command:`make` command to build the GEOS-Chem executable.  Type:
 
 .. code-block:: console
 
-    $ make -j
-
-You will see output similar to this:
-
-.. code-block:: text
-
-   Scanning dependencies of target HeadersHco
-   Scanning dependencies of target Isorropia
-   Scanning dependencies of target KPP_FirstPass
-   [  1%] Building Fortran object src/HEMCO/src/Shared/Headers/CMakeFiles/HeadersHco.dir/hco_inquireMod.F90.o
-   [  1%] Building Fortran object src/HEMCO/src/Shared/Headers/CMakeFiles/HeadersHco.dir/hco_precision_mod.F90.o
-   [  1%] Building Fortran object src/HEMCO/src/Shared/Headers/CMakeFiles/HeadersHco.dir/hco_charpak_mod.F90.o
-   [  3%] Building Fortran object src/GEOS-Chem/KPP/fullchem/CMakeFiles/KPP_FirstPass.dir/gckpp_Monitor.F90.o
-   [  3%] Building Fortran object src/GEOS-Chem/KPP/fullchem/CMakeFiles/KPP_FirstPass.dir/gckpp_Precision.F90.o
-   [  3%] Building Fortran object src/GEOS-Chem/KPP/fullchem/CMakeFiles/KPP_FirstPass.dir/gckpp_Parameters.F90.o
-   [  3%] Linking Fortran static library libKPP_FirstPass.a
-   [  3%] Built target KPP_FirstPass
-   Scanning dependencies of target Headers
-   [  3%] Building Fortran object src/GEOS-Chem/ISORROPIA/CMakeFiles/Isorropia.dir/isorropiaII_main_mod.F.o
-   [  3%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/charpak_mod.F90.o
-   [  3%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/dictionary_m.F90.o
-   [  3%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/CMN_SIZE_mod.F90.o
-   [  3%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/qfyaml_mod.F90.o
-   [  4%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/CMN_O3_mod.F90.o
-   [  6%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/inquireMod.F90.o
+   $ make -j
+   [  1%] Built target KPP_FirstPass
+   [  1%] Building Fortran object src/Cloud-J/src/Core/CMakeFiles/CloudJ_Core.dir/cldj_fjx_sub_mod.F90.o
+   [  1%] Building Fortran object src/Cloud-J/src/Core/CMakeFiles/CloudJ_Core.dir/cldj_init_mod.F90.o
+   [  1%] Building Fortran object src/Cloud-J/src/Core/CMakeFiles/CloudJ_Core.dir/cldj_osa_sub_mod.F90.o
+   [  3%] Building Fortran object src/Cloud-J/src/Core/CMakeFiles/CloudJ_Core.dir/cldj_sub_mod.F90.o
+   [  4%] Linking Fortran static library libCloudJ_Core.a
+   [  4%] Built target CloudJ_Core
+   [  6%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/charpak_mod.F90.o
+   [  6%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/errcode_mod.F90.o
+   [  7%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/precision_mod.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/input_opt_mod.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/state_grid_mod.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/CMN_FJX_MOD.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/CMN_SIZE_mod.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/aermass_container_mod.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/inquireMod.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/qfyaml_mod.F90.o
+   [  9%] Building Fortran object src/GEOS-Chem/Headers/CMakeFiles/Headers.dir/diaglist_mod.F90.o
 
    ... etc ...
 
@@ -58,6 +52,7 @@ You will see output similar to this:
    [100%] Linking Fortran executable ../bin/gcclassic
    [100%] Built target gcclassic
 
+
 .. tip::
 
    The :command:`-j` argument tells :command:`make` that it can
@@ -84,55 +79,48 @@ described above <compile-cmake>`.  Type:
 
 .. code-block:: console
 
-    $ make install
-
-and you will see output similar to this:
-
-.. code-block:: console
-
-   [  1%] Built target HeadersHco
-   [  3%] Built target KPP_FirstPass
-   [  3%] Built target Isorropia
-   [  4%] Built target JulDayHco
+   $ make install
+   [  1%] Built target KPP_FirstPass
+   [  4%] Built target CloudJ_Core
    [ 13%] Built target Headers
-   [ 18%] Built target NcdfUtilHco
-   [ 19%] Built target JulDay
-   [ 19%] Built target GeosUtilHco
-   [ 25%] Built target NcdfUtil
-   [ 40%] Built target HCO
-   [ 46%] Built target GeosUtil
+   [ 13%] Built target JulDay
+   [ 18%] Built target NcdfUtil
+   [ 24%] Built target GeosUtil
+   [ 26%] Built target ObsPack
+   [ 27%] Built target HeadersHco
+   [ 29%] Built target JulDayHco
+   [ 33%] Built target NcdfUtilHco
+   [ 33%] Built target GeosUtilHco
+   [ 47%] Built target HCO
    [ 56%] Built target HCOX
-   [ 59%] Built target Transport
-   [ 62%] Built target History
-   [ 63%] Built target ObsPack
-   [ 71%] Built target KPP
-   [ 71%] Built target HCOI_Shared
+   [ 58%] Built target HCOI_Shared
+   [ 60%] Built target HETP_core
+   [ 69%] Built target KPP
+   [ 72%] Built target History
    [ 98%] Built target GeosCore
    [100%] Built target gcclassic
    Install the project...
    -- Install configuration: "Release"
-   -- Up-to-date: /home/ubuntu/gc_merra2_fullchem/build_info/CMakeCache.txt
-   -- Up-to-date: /home/ubuntu/gc_merra2_fullchem/build_info/summarize_build
-   -- Up-to-date: /home/ubuntu/gc_merra2_fullchem/gcclassic
+   -- Installing: /path/to/run/directory/build_info/CMakeCache.txt
+   -- Installing: /path/to/run/directory/build_info/summarize_build
+   -- Installing: /path/to/run/directory/gcclassic
+   -- Set runtime path of "/path/to/run/directory/gcclassic" to ""
+
+
 
 Let's now navigate back to the run directory and get a directory
 listing:
 
 .. code-block:: console
 
    $ cd ..
-   $ ls
-   CodeDir@                             cleanRunDir.sh*
-   GEOSChem.Restart.20190701_0000z.nc4  download_data.py*
-   HEMCO_Config.rc                      download_data.yml
-   HEMCO_Config.rc.gmao_metfields       gcclassic*
-   HEMCO_Diagn.rc                       geoschem_config.yml
-   HISTORY.rc                           getRunInfo*
-   OutputDir/                           metrics.py*
-   README                               runScriptSamples@
-   archiveRun.sh*                       rundirConfig/
-   build/                               species_database.yml
-   build_info/
+   $ ls -CF
+   archiveRun.sh*     download_data.py*    HEMCO_Config.rc.gmao_metfields  Restarts/
+   build/             download_data.yml    HEMCO_Diagn.rc                  runScriptSamples@
+   build_info/        gcclassic*           HISTORY.rc                      species_database.yml
+   cleanRunDir.sh*    geoschem_config.yml  metrics.py*
+   CodeDir@           getRunInfo*          OutputDir/
+   CreateRunDirLogs/  HEMCO_Config.rc      README.md
 
 You should now see the :program:`gcclassic` executable and a :file:`build_info`
 directory there. GEOS-Chem has now been configured, compiled, and

diff --git a/docs/source/gcclassic-user-guide/create-rundir.rst b/docs/source/gcclassic-user-guide/create-rundir.rst
@@ -8,12 +8,6 @@
 Create a run directory
 ######################
 
-We have greatly simplified run directory creation in `GEOS-Chem
-Classic 13.0.0 <GEOS-Chem_13.0.0>`__ and later versions. You no longer
-need to download the separate GEOS-Chem Unit Tester repository, but
-can create run directories from a script in the GEOS-Chem source code
-itself.
-
 Please see the following sections for more information on how to
 create run directories for GEOS-Chem Classic simulations:
 
@@ -22,5 +16,5 @@ create run directories for GEOS-Chem Classic simulations:
 
    rundir-registration.rst
    rundir-fullchem.rst
-   rundir-ch4.rst
+   rundir-carbon.rst
    rundir-files.rst
diff --git a/docs/source/gcclassic-user-guide/geoschem-config.rst b/docs/source/gcclassic-user-guide/geoschem-config.rst
@@ -736,16 +736,16 @@ Photolysis
      photolysis:
        activate: true
        input_directories:
-         fastjx_input_dir: /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2021-10/
-	 cloudj_input_dir: /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2023-05/
+         fastjx_input_dir: /path/to/ExtData/CHEM_INPUTS/FAST_JX/v2024-05/
+         cloudj_input_dir: /path/to/ExtData/CHEM_INPUTS/CLOUD_J/v2023-05/
        overhead_O3:
          use_online_O3_from_model: true
          use_column_O3_from_met: true
          use_TOMS_SBUV_O3: false
        photolyze_nitrate_aerosol:
          activate: true
-         NITs_Jscale_JHNO3: 0.0
-         NIT_Jscale_JHNO2: 0.0
+         NITs_Jscale: 100.0
+         NIT_Jscale: 100.0
          percent_channel_A_HONO: 66.667
          percent_channel_B_NO2: 33.333