Merge commit 'be0410ece28f2b5b9c089f8ca09ce0c80c79fe6c' into feature/…

…hafs.v2.0.1

.github/workflows/gcc.yml

@@ -9,7 +9,7 @@ defaults:
     shell: bash -leo pipefail {0}
 
 env:
-  cache_key: gcc2  # The number (#) following the cache_key "gcc" is to flush Action cache.
+  cache_key: gcc3  # The number (#) following the cache_key "gcc" is to flush Action cache.
   CC: gcc-10
   FC: gfortran-10
   CXX: g++-10
@@ -60,6 +60,7 @@ jobs:
           sudo apt install cmake
           spack external find
           spack add [email protected]
+          spack add doxygen
           spack concretize
           spack install -v --fail-fast --dirty
           spack clean --all
@@ -91,6 +92,6 @@ jobs:
           export FC=mpif90
           cd UPP
           mkdir -p build && cd build
-          cmake -DCMAKE_INSTALL_PREFIX=../install ..
+          cmake -DENABLE_DOCS=ON -DCMAKE_INSTALL_PREFIX=../install ..
           make -j2 VERBOSE=1
           make install

.gitignore

@@ -9,7 +9,7 @@
 # USE CAUTION WHEN ADDING WILDCARDS, as some builds use different filename   #
 # conventions than others                                                    #
 ##############################################################################
-build*/
+build/*/
 install*/
 
 *.[aox]

.readthedocs.yml

@@ -11,7 +11,7 @@ build:
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-  configuration: docs/conf.py
+  configuration: doc/UserGuide/conf.py
 
 # Build documentation with MkDocs
 #mkdocs:
@@ -22,6 +22,5 @@ formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-#  version: 3.7
   install:
-    - requirements: docs/requirements.txt
+    - requirements: doc/UserGuide/requirements.txt

CMakeLists.txt

@@ -14,6 +14,7 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 # Handle user options.
 option(OPENMP "use OpenMP threading" ON)
 option(BUILD_POSTEXEC "Build NCEPpost executable" ON)
+option(BUILD_WITH_NEMSIO "Build NCEPpost with nemsio library" ON)
 option(BUILD_WITH_WRFIO "Build NCEPpost with WRF-IO library" OFF)
 option(BUILD_WITH_IFI "Build NCEPpost with In-Flight Icing (IFI) library if present" OFF)
 option(REQUIRE_IFI "Abort if libIFI is not found ; enables BUILD_WITH_IFI=ON" OFF)
@@ -84,9 +85,10 @@ else()
 endif()
 
 if(BUILD_POSTEXEC)
-  find_package(nemsio REQUIRED)
-  find_package(sfcio REQUIRED)
-  find_package(sigio REQUIRED)
+  if(BUILD_WITH_NEMSIO)
+    find_package(nemsio REQUIRED)
+    find_package(sigio REQUIRED)
+  endif()
   find_package(sp REQUIRED)
   find_package(w3emc REQUIRED)
   if(BUILD_WITH_WRFIO)
@@ -116,7 +118,7 @@ add_subdirectory(parm)
 # If desired, build the doxygen docs.
 if(ENABLE_DOCS)
   find_package(Doxygen REQUIRED)
-  add_subdirectory(docs)
+  add_subdirectory(doc)
 endif()
 
 ### Package config

README.md

@@ -1,33 +1,32 @@
 
-# Unified Post-Processing (UPP)
+# Unified Post Processor (UPP)
 
 The Unified Post Processor (UPP) software package is a software
 package designed to generate useful products from raw model
 output.
 
 The UPP is currently used in operations with the Global Forecast
 System (GFS), GFS Ensemble Forecast System (GEFS), North American
-Mesoscale (NAM), Rapid Refresh (RAP), High Resolution Rapid Refresh
+Mesoscale (NAM), Rapid Refresh (RAP), High-Resolution Rapid Refresh
 (HRRR), Short Range Ensemble Forecast (SREF), and Hurricane WRF (HWRF)
-applications. It is also used in the Unified Forecasting System (UFS),
-including the Rapid Refresh Forecast System (RRFS), Hurricane Application
-Forecasting System (HAFS), and the Medium Range Weather (MRW) and Short 
+applications. It is also used in the Unified Forecast System (UFS),
+including the Rapid Refresh Forecast System (RRFS), Hurricane Analysis and
+Forecast System (HAFS), and the Medium-Range Weather (MRW) and Short-
 Range Weather (SRW) Applications.
 
 The UPP provides the capability to compute a variety of diagnostic
 fields and interpolate to pressure levels or other vertical
 coordinates.
 
 UPP also incorporates the Joint Center for Satellite Data Assimilation
-(JCSDA) Community Radiative Transfer Model (CRTM) to compute model
-derived brightness temperature (TB) for various instruments and
+(JCSDA) Community Radiative Transfer Model (CRTM) to compute model-derived brightness temperature (TB) for various instruments and
 channels. This additional feature enables the generation of a number
 of simulated satellite products including GOES products.
 
 Output from the UPP is in National Weather Service (NWS) and World
 Meteorological Organization (WMO) GRIB2 format and can be used
-directly by visualization, plotting, or verification packages, or for
-further downstream post-processing, e.g. statistical post-processing
+directly by visualization, plotting, or verification packages or for
+further downstream post-processing, e.g., statistical post-processing
 techniques.
 
 Examples of UPP products include:
@@ -48,26 +47,24 @@ Examples of UPP products include:
 Support for the UFS UPP is provided through [GitHub Discussions](https://github.com/NOAA-EMC/UPP/discussions).
 
 ## Documentation 
-User Guide for latest public release: https://upp.readthedocs.io/en/latest/.
+User Guide for latest standalone public release: https://upp.readthedocs.io/en/latest/.
 
 Technical code-level documentation: https://noaa-emc.github.io/UPP/.
 
 ## Developer Information
-Please see review the [wiki](https://github.com/NOAA-EMC/UPP/wiki)
+Please review the [wiki](https://github.com/NOAA-EMC/UPP/wiki)
 
 ## Authors
 
 NCEP/EMC Developers
 
-Code Managers: Wen Meng, Huiya Chuang, Kate Fossell
+Code Managers: Wen Meng, Huiya Chuang, Fernando Andrade-Maldonado
 
 ## Prerequisites
 
 The UPP requires certain NCEPLIBS packages to be installed via the 
-HPC-Stack project. For instructions on installing these packages as a 
-bundle via HPC-Stack, see: https://hpc-stack.readthedocs.io/en/latest/.
-Users may instead install packages via spack-stack. For instructions,
-see: https://spack-stack.readthedocs.io/en/latest/.
+spack-stack project. For instructions on installing these packages as a 
+bundle via spack-stack, see: https://spack-stack.readthedocs.io/en/latest/.
 The `UPP/modulefiles` directory indicates which package versions are 
 used and supported on Level 1 systems. 
 
@@ -87,7 +84,6 @@ BUILD_POSTEXEC):
 - [NCEPLIBS-sigio](https://github.com/NOAA-EMC/NCEPLIBS-sigio)
 - [NCEPLIBS-sfcio](https://github.com/NOAA-EMC/NCEPLIBS-sfcio)
 - [NCEPLIBS-nemsio](https://github.com/NOAA-EMC/NCEPLIBS-nemsio)
-- [NCEPLIBS-gfsio](https://github.com/NOAA-EMC/NCEPLIBS-gfsio)
 
 The [NCEPLIBS-wrf_io](https://github.com/NOAA-EMC/NCEPLIBS-wrf_io)
 library is required to build with NCEPpost with WRF-IO library (cmake
@@ -110,7 +106,7 @@ Builds include:
 - Inline post (UPP library): Currently only supported for the GFS, RRFS,
   HAFS, and the UFS-MRW Application.
 
-- Offline post (UPP executable): Supported for Regional applications
+- Offline post (UPP executable): Supported for regional applications
   including SRW, RRFS, HAFS, and standalone applications of UPP.
 
 

ci/rt.sh

@@ -65,7 +65,7 @@ if [ $mac2 = hf ]; then # for HERA
  export machine=HERA
  export homedir=${homedir:-"/scratch2/NAGAPE/epic/UPP/test_suite"}
  export rundir=${rundir:-"/scratch1/NCEPDEV/stmp2/${USER}"}
- module use /scratch1/NCEPDEV/nems/role.epic/spack-stack/spack-stack-1.6.0/envs/unified-env/install/modulefiles/Core
+ module use /scratch1/NCEPDEV/nems/role.epic/spack-stack/spack-stack-1.6.0/envs/unified-env-rocky8/install/modulefiles/Core
  module load stack-intel/2021.5.0
  module load stack-intel-oneapi-mpi/2021.5.1
  module load prod_util/2.1.1
@@ -85,6 +85,7 @@ elif [ $mac3 = herc ] ; then
  module load stack-intel/2021.9.0
  module load stack-intel-oneapi-mpi/2021.9.0
  module load prod_util/2.1.1
+ module load stack-python/3.10.13
 fi
 
 #set working directory

docs/Doxyfile.in → doc/Doxyfile.in

@@ -846,8 +846,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @abs_top_srcdir@/docs/user_guide.md \
-                       = @abs_top_srcdir@/docs/2D-decomp.md \
+INPUT                  = @abs_top_srcdir@/doc/user_guide.md \
+                       = @abs_top_srcdir@/doc/2D-decomp.md \
                          @abs_top_srcdir@/sorc/ncep_post.fd \
                          @config_srcdir@
 
@@ -1007,7 +1007,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = @abs_top_srcdir@/docs/sp_user_guide.md
+USE_MDFILE_AS_MAINPAGE = @abs_top_srcdir@/doc/user_guide.md
 
 # By default, all characters from position 72 are to be considered as comment.
 # This prevents Doxygen from recognizing certain variables as undocumented

docs/Acknowledgments.rst → doc/UserGuide/BackgroundInfo/Acknowledgments.rst

@@ -2,20 +2,20 @@
 Acknowledgments
 ***************
 
-The adaptation of the original WRF Post Processor package and Users Guide (by Mike Baldwin of
+The adaptation of the original WRF Post Processor package and User's Guide (by Mike Baldwin of
 NSSL/CIMMS and Hui-Ya Chuang of NCEP/EMC) was done by Lígia Bernardet (NOAA/ESRL/DTC) in collaboration
 with Dusan Jovic (NCEP/EMC), Robert Rozumalski (COMET), Wesley Ebisuzaki (NWS/HQTR), and Louisa Nance
 (NCAR/RAL/DTC). Upgrades to WRF Post Processor versions 2.2 and higher were performed by Hui-Ya Chuang,
 Dusan Jovic, and Mathew Pyle (NCEP/EMC). Transitioning of the documentation from the WRF Post Processor
 to the Unified Post Processor was performed by Nicole McKee (NCEP/EMC), Hui-Ya Chuang (NCEP/EMC), and
 Jamie Wolff (NCAR/RAL/DTC). Implementation of the Community Unified Post Processor was performed by
-Tricia Slovacek, Kate Fossell, and Tracy Hertneky (NCAR/RAL/DTC).
+Tricia Slovacek, Kate Fossell, and Tracy Hertneky (NCAR/RAL/DTC). Currently, community user support is provided by the Earth Prediction Innovation Center (EPIC) UPP team.
 
 **Acknowledging the UPP Team:**
 
 If significant help was provided via the UPP helpdesk for work resulting in a publication, please
-acknowledge the Earth Prediction Innovation Center UPP Team.
+acknowledge the EPIC UPP team.
 
 For referencing this document please use:
 
-UPP Users Guide V11.0.0, 24 pp.
+UPP User's Guide V11.0.0, 24 pp.

docs/CodeOverview.rst → doc/UserGuide/BackgroundInfo/CodeOverview.rst

@@ -23,20 +23,20 @@ and generates output in :term:`GRIB2` format. It uses :term:`MPI` parallel code
 products like those used operationally on the same operational grids. Examples of UPP products include:
 
    - T, Z, humidity, wind, cloud water, cloud ice, rain, and snow on pressure levels
-   - SLP, shelter level T, humidity, and wind fields
+   - SLP, shelter-level T, humidity, and wind fields
    - Precipitation-related fields
    - PBL-related fields
    - Severe weather products (e.g. CAPE, Vorticity, Wind shear)
    - Radiative/Surface fluxes
-   - Cloud related fields
+   - Cloud-related fields
    - Aviation products
    - Radar reflectivity products
    - Satellite look-alike products
 
-A full list of fields that can be generated by the UPP is provided in :doc:`UPP_GRIB2_Table_byID`.
+A full list of fields that can be generated by the UPP is provided in :doc:`../tables/UPP_GRIB2_Table_byID`.
 
 As of v11.0.0, the UPP has 2D decomposition capabilities and is also backwards compatible for 1D decomposition.
-The functionality demonstrates run-time improvements, especially for larger domains. Support for this
+The functionality demonstrates runtime improvements, especially for larger domains. Support for this
 feature is available for standalone UPP applications.
 
 Support for the community UPP is provided through `GitHub Discussions <https://github.com/NOAA-EMC/UPP/discussions>`__.
@@ -48,7 +48,7 @@ Transfer Model (:term:`CRTM`) to compute model-derived brightness temperature (T
 channels. 
 This additional feature enables the generation of simulated satellite products such as:
 
-   * Geostationary Operational Environmental Satellite (GOES)
+   * Geostationary Operational Environmental Satellites (GOES)
    * Advanced Microwave Scanning Radiometer (AMSRE)
    * Special Sensor Microwave Imager/Sounder (SSMIS)
 
@@ -77,24 +77,22 @@ The main UPP repository is named ``UPP``; it is available on GitHub at https://g
 Under the main **UPP** directory reside the following relevant subdirectories 
 (the * indicates a directory that exists only after the build is complete):
 
-     | **exec***: Contains the :bolditalic:`upp.x` executable after successful compilation
+     | **exec***: Contains the ``upp.x`` executable after successful compilation
 
-     | **modulefiles**: Contains modulefiles for specific platforms and compilers for building on
-       pre-configured machines.
+     | **modulefiles**: Contains modulefiles for specific platforms and compilers for building on preconfigured machines.
 
-     | **parm**: Contains parameter files, which can be modified by the user to control how the post
-       processing is performed.
+     | **parm**: Contains parameter files, which can be modified by the user to control how the post processing is performed.
 
      | **scripts**: Contains a sample run script to process fv3 history files.
-     |   - **run_upp**: Script that runs the stand-alone UPP package (:bolditalic:`upp.x`)
+     |   - ``run_upp``: Script that runs the standalone UPP package (``upp.x``)
      
      | **sorc**: Contains source code for:
-     |   - **ncep_post.fd**: Source code for the UPP
+     |   - ``ncep_post.fd``: Source code for the UPP
 
      | **tests**: Contains the scripts used to install UPP
-     |   - **compile_upp.sh**: UPP build script
-     |   - **build***: Contains the UPP build
-     |   - **install***: Contains the installed executable (bin/upp.x), modules, and libraries
+     |   - ``compile_upp.sh``: UPP build script
+     |   - ``build*``: Contains the UPP build
+     |   - ``install*``: Contains the installed executable (``bin/upp.x``), modules and libraries
 
 When the ``develop`` branch of the UPP repository is cloned, the basic directory structure follows the example below. Some files and directories have been removed for brevity. 
 

docs/Introduction.rst → doc/UserGuide/BackgroundInfo/Introduction.rst

@@ -13,7 +13,7 @@ Analysis and Forecast System (HAFS), and the Medium-Range Weather (:term:`MRW`)
 Applications.
 
 This software package can be run inline---built as a library to be used by the model---and offline---built 
-stand-alone and run separately from the model. This documentation largely details the offline
+standalone and run separately from the model. This documentation primarily details the offline
 procedures.
 
 =====================

doc/UserGuide/BackgroundInfo/index.rst

@@ -0,0 +1,10 @@
+Background Information
+=========================
+
+.. toctree::
+   :maxdepth: 3
+
+
+   Introduction
+   CodeOverview
+   Acknowledgments