Feature/doc updates into release/public-v1 (#127)

* Update path to fix files and sample model data on AWS * Updated links to several model archives * Update links for final versions and make a few small edits * Update link to Chpt 10 * Final tweaks * Updated link for UFS_UTILS doc * Update DOI publish date in README * Update wording of citation in Introduction * First pass at addressing Dom's comments. More to come, especially related to platform environments. * More small edits. More to come. * A few more updates. Still more to come. * Getting closer to addressing all of Dom's concerns. * Another small edit * A few more edits to the graphics chapter to add an example command line for the diff plot * Updated some remaining concens raised by Dom. This will now be tested and the final issues will be added prior to a PR. * More updates to the graphics chapter * Added subsections for easier reading
ufs-community · Mar 2, 2021 · 0b0fbff · 0b0fbff
1 parent 0602eb0
commit 0b0fbff
Show file tree

Hide file tree

Showing 10 changed files with 220 additions and 124 deletions.
diff --git a/docs/UsersGuide/source/CodeReposAndDirs.rst b/docs/UsersGuide/source/CodeReposAndDirs.rst
@@ -157,7 +157,7 @@ workflow is run, is shown in :numref:`Table %s <ExptDirStructure>`.
    +---------------------------+-------------------------------------------------------------------------------------------------------+
    | data_table                | Cycle-independent input file (empty)                                                                  |
    +---------------------------+-------------------------------------------------------------------------------------------------------+
-   | field_table               | Scalar fields in the `forecast model                                                                  |
+   | field_table               | Tracers in the `forecast model                                                                        |
    |                           | <https://ufs-weather-model.readthedocs.io/en/ufs-v2.0.0/InputsOutputs.html#field-table-file>`_        |
    +---------------------------+-------------------------------------------------------------------------------------------------------+
    | FV3LAM_wflow.xml          | Rocoto XML file to run the workflow                                                                   |

diff --git a/docs/UsersGuide/source/ConfigNewPlatform.rst b/docs/UsersGuide/source/ConfigNewPlatform.rst
@@ -14,11 +14,11 @@ The first step to installing on a new machine is to install :term:`NCEPLIBS` (ht
 
 * C and C++ compilers compatible with the Fortran compiler
 
-   * gcc v9+, ifort v18+, and clang (MacOS) have been tested
+   * gcc v9+, ifort v18+, and clang v9+ (macOS, native Apple clang or LLVM clang) have been tested
 
 * Python v3.6+
 
-   * Prerequisite packages must be downloaded: jinja2, yaml and f90nml, as well as pygrib if the user would like to use the provided graphics scripts
+   * Prerequisite packages must be downloaded: jinja2, yaml and f90nml, as well as a number of additional Python modules (see :numref:`Section %s <SW-OS-Requirements>`) if the user would like to use the provided graphics scripts
 
 * Perl 5
 
@@ -28,16 +28,20 @@ The first step to installing on a new machine is to install :term:`NCEPLIBS` (ht
 
    * CMake v3.15+ is needed for building NCEPLIBS, but versions as old as 3.12 can be used to build NCEPLIBS-external, which contains a newer CMake that can be used for the rest of the build.
 
-For Linux systems, as long as the above software is available, you can move on to the next step: installing the :term:`NCEPLIBS-external` package.
-
-For MacOS systems, you will also need to set the stack size to “unlimited”. 
+For both Linux and macOS, you will need to set the stack size to "unlimited" (if allowed) or the largest possible value.
 
 .. code-block:: console
 
+   # Linux, if allowed
+   ulimit -s unlimited
+
+   # macOS, this corresponds to 65MB
    ulimit -S -s unlimited
 
-Additionally, some extra software is needed: ``wget``, ``coreutils``, ``pkg-config``, and ``gnu-sed``.
-It is recommended that you install this software using the Homebrew package manager for MacOS (https://brew.sh/):
+For Linux systems, as long as the above software is available, you can move on to the next step: installing the :term:`NCEPLIBS-external` package.
+
+For macOS systems, some extra software is needed: ``wget``, ``coreutils``, ``pkg-config``, and ``gnu-sed``.
+It is recommended that you install this software using the Homebrew package manager for macOS (https://brew.sh/):
 
 * brew install wget
 
@@ -160,7 +164,7 @@ At this point there are just a few more variables that need to be set prior to b
    export CMAKE_CXX_COMPILER=mpicxx
    export CMAKE_Fortran_COMPILER=mpifort
 
-If you are using your machine’s built-in MPI compilers, it is recommended you set the ``CMAKE_*_COMPILER`` flags to full paths to ensure that the correct MPI aliases are used. Finally, one last environment variable, ``CMAKE_Platform``, must be set. This will depend on your machine; for example, on a MacOS operating system with GNU compilers:
+If you are using your machine’s built-in MPI compilers, it is recommended you set the ``CMAKE_*_COMPILER`` flags to full paths to ensure that the correct MPI aliases are used. Finally, one last environment variable, ``CMAKE_Platform``, must be set. This will depend on your machine; for example, on a macOS operating system with GNU compilers:
 
 .. code-block:: console
 
@@ -198,7 +202,7 @@ Running the graphics scripts in ``${WORKDIR}/ufs-srweather-app/regional_workflow
 
 For the final step of creating and running an experiment, the exact methods will depend on if you are running with or without a workflow manager (Rocoto).
 
-Running Without a Workflow Manager: Generic Linux and MacOS Platforms
+Running Without a Workflow Manager: Generic Linux and macOS Platforms
 =====================================================================
 Now that the code has been built, you can stage your data as described in :numref:`Section %s <DownloadingStagingInput>`.
 
@@ -244,7 +248,7 @@ From here, you can run each individual task of the UFS SRW App using the provide
    cp ${WORKDIR}/ufs-srweather-app/regional_workflow/ush/wrappers/*sh .
    cp ${WORKDIR}/ufs-srweather-app/regional_workflow/ush/wrappers/README.md .
 
-The ``README.md`` file will contain instructions on the order that each script should be run in. An example of wallclock times for each task for an example run (2017 Macbook Pro, MacOS Catalina, 25km CONUS domain, 48hr forecast) is listed in :numref:`Table %s <WallClockTimes>`.
+The ``README.md`` file will contain instructions on the order that each script should be run in. An example of wallclock times for each task for an example run (2017 Macbook Pro, macOS Catalina, 25km CONUS domain, 48hr forecast) is listed in :numref:`Table %s <WallClockTimes>`.
 
 .. _WallClockTimes:
 
@@ -341,7 +345,7 @@ Those requirements highlighted in **bold** are included in the NCEPLIBS-external
 
 * 4GB memory (CONUS 25km domain)
 
-* Fortran compiler with full Fortran 2003 standard support
+* Fortran compiler with full Fortran 2008 standard support
 
 * C and C++ compiler
 
@@ -361,13 +365,13 @@ Those requirements highlighted in **bold** are included in the NCEPLIBS-external
 
    * **netCDF (C and Fortran libraries)**
    * **HDF5** 
-   * **ESMF**
+   * **ESMF** 8.0.0
    * **Jasper**
    * **libJPG**
    * **libPNG**
    * **zlib**
 
-MacOS-specific prerequisites:
+macOS-specific prerequisites:
 
 * brew install wget
 * brew install cmake
@@ -381,4 +385,4 @@ Optional but recommended prerequisites:
 * Bash v4+
 * Rocoto Workflow Management System (1.3.1)
 * **CMake v3.15+**
-* Python package pygrib for graphics
+* Python packages scipy, matplotlib, pygrib, cartopy, and pillow for graphics
diff --git a/docs/UsersGuide/source/ConfigParameters.inc b/docs/UsersGuide/source/ConfigParameters.inc
@@ -5,7 +5,9 @@
 Grid Generation Parameters
 ==========================
 ``GRID_GEN_METHOD``: (Default: “”)
-   This variable specifies the method to use to generate a regional grid in the horizontal.  The only supported value of this parameter is “ESGgrid”, in which case the Extended Schmidt Gnomonic grid generation method developed by Jim Purser of EMC will be used. 
+   This variable specifies the method to use to generate a regional grid in the horizontal.  The only supported value of this parameter is “ESGgrid”, in which case the Extended Schmidt Gnomonic grid generation method developed by Jim Purser(1) of EMC will be used. 
+
+(1)Purser, R. J., D. Jovic, G. Ketefian, T. Black, J. Beck, J. Dong, and J. Carley, 2020: The Extended Schmidt Gnomonic Grid for Regional Applications. Unified Forecast System (UFS) Users’ Workshop. July 27-29, 2020.
 
 .. note::
 
@@ -49,11 +51,11 @@ Computational Forecast Parameters
 ``BLOCKSIZE``: (Default: “”)
    The amount of data that is passed into the cache at a time.
 
-Here, we set these parameters to null strings.  This is so that, for any one of these parameters:
+Here, we set these parameters to null strings. This is so that, for any one of these parameters:
 
-#. If the experiment is using a predefined grid, then if the user sets the parameter in the user-specified experiment configuration file (``EXPT_CONFIG_FN``), that value will be used in the forecast(s). Otherwise, the default value of the parameter for that predefined grid will be used.
+#. If the experiment is using a predefined grid and the user sets the parameter in the user-specified experiment configuration file (``EXPT_CONFIG_FN``), that value will be used in the forecast(s). Otherwise, the default value of the parameter for that predefined grid will be used.
 
-#. If the experiment is not using a predefined grid (i.e. it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file.  Otherwise, the parameter will remain set to a null string, and the experiment generation will fail because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory.
+#. If the experiment is not using a predefined grid (i.e. it is using a custom grid whose parameters are specified in the experiment configuration file), then the user must specify a value for the parameter in that configuration file.  Otherwise, the parameter will remain set to a null string, and the experiment generation will fail, because the generation scripts check to ensure that all the parameters defined in this section are set to non-empty strings before creating the experiment directory.
 
 Write-Component (Quilting) Parameters
 =====================================
@@ -91,7 +93,7 @@ Currently supported ``PREDEF_GRID_NAME`` options are "RRFS_CONUS_25km," "RRFS_CO
 Pre-existing Directory Parameter
 ================================
 ``PREEXISTING_DIR_METHOD``: (Default: “delete”)
-   This variable determines the method to use to deal with pre-existing directories [e.g ones generated by previous calls to the experiment generation script using the same experiment name (``EXPT_SUBDIR``) as the current experiment].  This variable must be set to one of "delete", "rename", and "quit".  The resulting behavior for each of these values is as follows:
+   This variable determines the method to deal with pre-existing directories [e.g ones generated by previous calls to the experiment generation script using the same experiment name (``EXPT_SUBDIR``) as the current experiment].  This variable must be set to one of "delete", "rename", and "quit".  The resulting behavior for each of these values is as follows:
 
    * "delete": The preexisting directory is deleted and a new directory (having the same name as the original preexisting directory) is created.
 
@@ -128,12 +130,12 @@ These parameters set flags (and related directories) that determine whether the
 
 Surface Climatology Parameter
 =============================
-``SFC_CLIMO_FIELDS``: (Default: “("facsf" "maximum_snow_albedo" "slope_type" "snowfree_albedo" "soil_type" "substrate_temperature" "vegetation_greenness" "vegetation_type")”
+``SFC_CLIMO_FIELDS``: (Default: “("facsf" "maximum_snow_albedo" "slope_type" "snowfree_albedo" "soil_type" "substrate_temperature" "vegetation_greenness" "vegetation_type")”)
    Array containing the names of all the fields for which the ``MAKE_SFC_CLIMO_TN`` task generates files on the native FV3-LAM grid.
 
 Fixed File Parameters
 =====================
-Set parameters associated with the fixed (i.e. static) files.  For the main NOAA HPC platforms, as well as Cheyenne, Odin, and Stampede, fixed files are prestaged in locations on each machine with paths defined in the ``setup.sh`` script.
+Set parameters associated with the fixed (i.e. static) files.  For the main NOAA HPC platforms, as well as Cheyenne, Odin, and Stampede, fixed files are prestaged with paths defined in the ``setup.sh`` script.
 
 ``FIXgsm``: (Default: “”)
    System directory in which the majority of fixed (i.e. time-independent) files that are needed to run the FV3-LAM model are located.
@@ -221,7 +223,7 @@ Set parameters associated with the fixed (i.e. static) files.  For the main NOAA
 ``CYCLEDIR_LINKS_TO_FIXam_FILES_MAPPING``: (Default: see below)
    .. code-block:: console
 
-      ("aerosol.dat            	| global_climaeropac_global.txt" \
+      ("aerosol.dat            	   | global_climaeropac_global.txt" \
        "co2historicaldata_2010.txt | fix_co2_proj/global_co2historicaldata_2010.txt" \
        "co2historicaldata_2011.txt | fix_co2_proj/global_co2historicaldata_2011.txt" \
        "co2historicaldata_2012.txt | fix_co2_proj/global_co2historicaldata_2012.txt" \